ステータス: 合意済み（2026-09-24、Issue #14、工程2: 設計）。実装範囲は工程3（runtime-management-implementation-plan.md）で決める
改訂: 2026-09-25 停止シーケンス（§7.7）を追加した（#15 #issuecomment-6615。2026-09-26に運用者が合意）
改訂: 2026-09-26 ダッシュボードをBrainから切り離し、Brainの起動・停止とUIへの終了の要求を行えるようにした（§1.3、§2、§3.1、§4.1、§4.3、§4.4、§7.8、§8、§9、§11〜§13。Issue #25、#6674、#6675）
改訂: 2026-09-26 §3.1.1の世代について、世代の作成に失敗した場合の縮退を許す表現に改めた（Issue #24、#6703。詳細設計runtime-management-detail-registration.mdの合意時に運用者が合意）
改訂: 2026-10-05 ダッシュボードに、Brainが使うOllamaのモデルをGPUから下ろす操作を加えた（§1.3、FR-24、NFR-03、§4.4、§9.3、§11。UC-D08。Issue #17、#17 #6942。運用者が合意）。§12.2に、ダッシュボードの詳細設計で決めた項目を注記した
更新するときは、設計文書の更新ルールに従うこと。
本書は、ランタイム管理 ユースケースの全件を満たす管理モデルと、UI–Brain間のランタイム管理プロトコルを定義する。会話要求と会話の継続に関する契約はUI層-Brain層間 インタフェース仕様書が扱い、本書はそれと混同しない。
本書は設計を定義する。どのユースケースをどこまで実装・実機検証するかは本書に持ち込まず、実装計画書（runtime-management-implementation-plan.md）で決める。
Issue #13の工程2（設計）の成果物である。
| 工程 | 成果物 |
|---|---|
| 1. ユースケース | runtime-management-use-cases.md（合意済み） |
| 2. 設計 | 本書 |
| 3. 実装範囲の決定 | runtime-management-implementation-plan.md |
| 4. 詳細設計 | runtime-management-detail-<領域>.md |
| 5. 実装 | コード、テスト、runtime-management-runbook.md |
ui-brain-protocol.md）ユースケースから、機能要件・非機能要件を抽出する。要件は「何を満たすか」だけを書き、実現方式は後続の節で決める。
| ID | 要件 | ユースケース | 主な対応先 |
|---|---|---|---|
| FR-01 | 運用者が、常駐が期待されるUIを「どの実行ホストで、どの種類が、どの枠で動いているべきか」として、常駐監視対象に1件ずつ登録できる。登録は、観測一覧に現れたUIを選んで行う。変更、解除もできる。登録はBrainが永続的に保持する | UC-D06、UC-R01、UC-R07、UC-D02 | §3.1 |
| FR-02 | 実行ホストの起動条件（ログイン後かホスト起動時か）に応じて、Brainと常駐UIが自動的に利用可能になる。起動条件は実行ホストごとに宣言できる | UC-B01、UC-R01 | §4 |
| FR-03 | 自動起動に失敗した場合、正式な回復方法を確認できる。常駐監視対象として登録されたUIの失敗は、ダッシュボードで未稼働として確認できる。Brainの失敗は、ダッシュボード（Brainとは別に動く）で確認できる。ダッシュボード自体の失敗は、実行環境の管理手段で確認できる | UC-B01、UC-R01、UC-B05 | §4.3、§4.4 |
| FR-04 | Brainと、実行ホストごとに1つのUIは、二重起動を拒否する。Brainが停止中でも拒否でき、既存プロセスが終了していれば再起動できる。拒否理由が分かる。実行環境が拒否できなかった二重起動は、Brainが重複として検出・表示する（target_id が異なる場合を含む） |
UC-B02、UC-M02 | §4.2、§5 |
| FR-05 | Brainは正常終了時に、新規受付を終え、実行中の処理と保持資源を適切に扱う | UC-B03 | §4.2 |
| FR-06 | Brainの生存と、会話サービスとしての利用可能性を区別して確認できる | UC-B04 | §6、§8 |
| FR-07 | 稼働状態を伝えるUIを、会話の有無にかかわらずプロセスとして観測でき、実行ホスト・起動時刻・版（commit）を確認できる | UC-R02、UC-D03 | §7 |
| FR-08 | 終了通知が届かなくても、正常終了・クラッシュ・通信断のいずれでも、UIを稼働中と誤認し続けない。最後に確認できた時刻と、現在利用できないことが分かる | UC-R03 | §6 |
| FR-09 | UIの新旧プロセスを取り違えない。更新後の切替と、古いプロセスの残存を判別できる | UC-R04、UC-D03 | §5、§6 |
| FR-10 | Brainの再起動後、動作中のUIを再び認識し、利用者から見た状態が正常へ戻る | UC-R05 | §6 |
| FR-11 | 稼働状態を伝えないUIは会話としてのみ扱い、未稼働・応答なしと判定しない | UC-R06 | §3.2、§3.4 |
| FR-12 | 常駐が期待されないUIは、動いている間だけ一覧に現れ、停止しても異常としない | UC-R07 | §3.1、§6 |
| FR-13 | UIごとの起動数制約（多重起動可／実行ホストごとに1つ）を表せる。多重起動可のUIは意図した複数起動として表示し、異なる実行ホストでの起動は互いに拒否しない | UC-M01、UC-M03 | §3.1、§5、§6 |
| FR-14 | 常駐監視対象として登録されたUIが確認できない場合は、一覧から消えず「未稼働」または「応答なし」として表示する。Brain自身の停止・起動失敗は、ダッシュボード（Brainとは別に動く）で確認する。ダッシュボード自体が動いていない場合は、実行環境の管理手段で確認する | UC-D02 | §4.3、§4.4、§6 |
| FR-15 | BrainとUIの状態（未稼働を含む）、実行ホスト、利用可能性、最終確認時刻を、機械可読な読み取り専用の状態取得と、一画面で確認できるダッシュボードで提供する | UC-D01 | §8 |
| FR-16 | UIプロセスとは別に、会話のセッション数と処理中件数だけを確認できる | UC-D04 | §3.3、§8 |
| FR-17 | Brainとは別の実行ホストから、同じ状態を閲覧できる。閲覧できるのは許可された利用者だけである | UC-D05 | §9 |
| FR-18 | 常駐監視対象の登録・変更・解除は、閲覧とは別の権限で認可される。権限のない利用者の変更は拒否される | UC-D06、UC-D05（閲覧認可との分離） | §9 |
| FR-19 | 管理プロトコルにプロトコル版を含め、UIは対応する版を申告する。非対応の版のUIは「非対応版」として扱える | 設計判断（Issue #14） | §7 |
| FR-20 | 常駐監視対象の登録情報を保全する。起動時に登録情報が壊れている・失われている場合も、Brainは起動を続け、正常だった直近の状態へ自動で戻す。戻したことを、発生日時とともに運用者が確認済みにするまで示す | UC-D07 | §3.1.1 |
| FR-21 | 運用者が、ダッシュボードからBrainを起動・停止できる。Brainが止まっていても、停止中・起動失敗・停止処理中であることがダッシュボードで分かる。操作できるのは許可された運用者だけである | UC-B05、UC-D02 | §4.4、§9 |
| FR-22 | 運用者が、ダッシュボードから、動いているUIに終了を求められる。UIは求めに応じて正常に終了する。求めに応じないUIは、稼働中のままであることが分かる。ダッシュボードからUIを起動することはできない | UC-R08 | §7.8、§9 |
| FR-23 | UIは、UIごとに自分の実行ホストで起動・停止の手段を持つ。停止は正常終了（終了通知あり）として扱う | UC-R09 | §4.1 |
| FR-24 | 運用者が、ダッシュボードで、Brainが使うOllamaのモデルがGPUに載っているか（自動で下りる予定の時刻を含む）を確認し、WSL・Ollama・Brainを止めずに、モデルをGPUから下ろせる。処理中の回答は最後まで返る。Brainが止まっていても使える。操作できるのは許可された運用者だけである | UC-D08 | §4.4、§9 |
| ID | 要件 | 根拠 |
|---|---|---|
| NFR-01 | 異常終了を前提とし、正常終了時の処理が行われなくても、いずれ正しい状態へ収束する | ユースケース原則3 |
| NFR-02 | 起動数制約はBrainの稼働に依存しない | ユースケース原則4 |
| NFR-03 | 状態取得は読み取り専用とする。ダッシュボードのプロセス操作は、Brainの起動・停止とUIへの終了の要求に限り、状態表示から他の操作（UIの起動、再起動、自動復旧等）を生やさない。Ollamaのモデルを下ろす操作（FR-24）は、プロセスを止めない操作として明示して加える。操作と監視設定の変更は、閲覧と分けて認可する | ユースケース原則5 |
| NFR-04 | 単一の実行ホスト・単一のUI種類を前提にしない | ユースケース原則7 |
| NFR-05 | 会話とプロセスの稼働を混同しない | ユースケース原則1 |
| NFR-06 | 応答途絶は数分以内（目安2〜3分）にダッシュボードへ反映される。ブラウザのタブ等、終了通知が確実に届かないUIも含めて判断できる | ユースケース §9-4 |
| NFR-07 | 会話内容と認証情報を、状態取得・ダッシュボードに含めない | UC-D01、UC-D05 |
| NFR-08 | commitを取得できない場合は推測せず「不明」と扱う。人向けversionは必須にしない | ユースケース §9-5 |
| NFR-09 | 自動起動失敗の能動的な通知は行わない。確認できることで足りる | ユースケース §9-2 |
常駐監視対象、実際のプロセス、会話の3層の責務と関係を定義する。
運用者が登録した、「動いているべき論理UI」の一覧である。Brainが永続的に保持する。
登録の意味: 「この論理UIは動いているべき」という監視上の期待を記録する操作である。プロセスの自動起動や常駐化は行わない
登録の単位: 監視対象キー (host_id, ui_kind, target_id)（§5）。特定のUIに限定しない
登録されないUI: 動いていれば観測されるが、停止していても異常とはみなさない（UC-R07）
所有者と変更手段: 所有者は運用者、変更手段は管理画面とする。変更は監視設定の変更であり、閲覧とは別の権限で認可する（§9）
登録の方法: 観測一覧に現れたUI（未登録のUI）を選んで登録する方法に限る。まだ一度も観測されていないUIの事前登録は行わない。host_idはOS由来のIDのハッシュ値（§5.2）であり人には分からないため、事前登録にはhost_idを確認する手段が別に必要になるが、事前登録で拾えるのは「新規導入したUIが最初から一度も起動に成功せず、運用者も導入後に確認していない」場合に限られ、その複雑さに見合わない。新規導入したUIは、一度起動し、一覧に現れたことを確認してから登録する（運用手順（runbook）で定める。§4.3）。この方法では、登録する値を人が手入力しないため、監視対象キーの打ち間違いも生じない
Brain自身: 登録の対象にしない。Brainの状態（稼働中・停止中・起動失敗・停止処理中）は、ダッシュボードが実行環境とBrainの状態取得から得て表示する（§4.4）。常駐監視対象の仕組み（heartbeatによる観測）は、Brainには適用しない
登録の管理: 同じ監視対象キーの重複登録は拒否する。登録・変更・解除の要求を拒否した場合は、拒否した理由（既に同じキーが登録済みである、解除しようとしたキーが登録されていない、権限がない等）を要求元へ返し、運用者が理由を確認できるようにする（UC-D06）。理由の具体的な表現（エラーコード、応答形式等）は、書き込み契約の詳細として詳細設計で決める。登録キーの変更は、旧キーの解除と新キーの登録として扱い、稼働中のプロセスが新キーに一致しなければ、§5.3の不一致として表示される。一時無効化の機能は持たない。計画的に長期間止める対象（修理・電源断等）は、登録を解除し、再開後に観測一覧から登録し直す（登録内容は監視対象キーの3要素だけであり、再登録の手間は小さい。止めている間に未稼働と表示されるのを避けるための専用状態を設けるより、状態の規則を単純に保つことを優先する）。権限のない利用者の変更は拒否する（§9）。UC-D06で規定する
版: 期待する版は管理しない。版の更新漏れは、実際の起動時刻と版を見て判断する
解除: 管理画面で対象を選んで解除すると、登録情報からその1件を削除する。解除前の内容は下記の世代に残るため、誤って解除しても戻せる。解除した対象に一致していたプロセスは「未登録のUI」になる（§6.2）
正常終了通知を受けた対象は削除せず「未稼働」として扱う（§6.2で確定）。
現在または直近に動作していたBrain・UIのプロセスである。稼働状態を伝えるUIだけが、この単位で把握される。
process_instance_id（UUID等）で区別する。再起動のたびに変わる（§5.1、§5.2）UIプロセスが持つ情報: 毎回のheartbeat（§7.1）でUIが申告する値と、Brainが受信・設定・時刻から導出する値を分けて保持する。両者を混同すると、実装者が互換性判定や最終確認時刻をUIの自己申告として扱う誤りにつながるため、明確に分ける。
host_id・ui_kind・target_id）process_instance_idBrain自身が持つ情報: BrainはUIのようにheartbeatを送らないため、自身の起動時刻・commit（取得できなければ「不明」）・人向けversion（任意）を、自身の起動時点で直接把握し保持する。UC-D03（BrainまたはUIの起動時刻・実行中commitを確認し、更新結果を判別する）をBrain自身についても満たすために必要であり、状態取得（§8.1）に含める。監視対象キー・process_instance_idはBrainには適用しない（Brainは常駐監視対象の登録対象ではない、§3.1）。
登録済みの監視対象ごとの最終観測: プロセスの記録は破棄される（下記「保持場所」）が、UC-R03は、終了したUIについても「最後に確認できた時刻と、現在利用できないこと」が分かることを求める。そこでBrainは、登録済みの監視対象に一致するプロセスの記録を破棄するとき、その監視対象ごとに次の要約を残す（既に要約があれば、最終確認時刻がより新しい方で置き換える）。
process_instance_id要約は、登録を解除するか、Brainが再起動するまで保持する。Brain再起動後に一度も一致するプロセスを観測していない監視対象の最終確認時刻は「不明」とする。すなわち、ダッシュボード（状態取得）で最終確認時刻を示せるのは、同じBrainプロセスが動いている間に限る（永続化はしない。登録情報と同様の破損時の扱いを増やさないため）。
観測の出来事のログ: Brainの再起動をまたいでも「いつ止まったか」を後から追えるよう、Brainは、UIプロセスの観測の開始、期限切れ、終了通知の受信、記録の破棄を、監視対象キー・process_instance_id・時刻とともに自身のログへ出力する。ログはBrainの再起動をまたいで残るため、再起動前に止まった登録済みUIの最終確認時刻は、ログで確認できる（§4.3と同じく、詳細はログで確認する経路）。ログの出力形式は、ロギング・観測可能性の方針（Issue #12）に合わせ、詳細設計で決める（§12.2）。未登録のUIには要約を残さない（UC-R07のとおり、記録の破棄とともに一覧から消えるため。一覧に残っている間は、プロセスの記録が最終確認時刻を持つ）。
保持場所: いずれもBrainのメモリ上にのみ保持し、永続化しない。UIプロセスの記録は、終了通知を受けた時点で直ちに、終了通知なしに「期限切れ」になった場合は応答なし保持時間（§6.3）が経過した時点で破棄する。UIプロセスの情報は、Brainが再起動すれば失われるが、次のheartbeatを受信した時点で、そのheartbeat単体から再構築できる（UC-R05、§6.4）。Brain自身の情報は、Brainの起動のたびに新しく記録し直す。これは、Brainが永続的に保持する常駐監視対象の登録情報（§3.1）とは対照的である。
現行の session_id（ui-brain-protocol.md§5）が表す会話履歴・TTL・処理状態である。プロセス（§3.2）とは別の単位として扱う。
session_id は、UIプロセスが起動時に1つ生成し、プロセスの生存期間中使い回す（既存のui-brain-protocol.md§5の規定。本書は変更しない）session_id と process_instance_id は、UIがそれぞれ別々に生成する、意味・値が独立した識別子である（§10）。同じ値である必然性はないprocess_instance_id を持たず、session_id だけを持つ（§3.2、UC-R06）ui-brain-protocol.md§5の規定にそのまま従うsession_idの数）と処理中件数（処理中のリクエスト数）の集計のみとする。個々のsession_id・会話内容は含めない（NFR-07、UC-D04）Brain・UI・実行環境（各コンポーネントを動かすホスト側の管理手段）が、それぞれ何を保証するかを抽象的な契約として定義する。Supervisor、named mutex等の具体的な方式は決めない（詳細設計の対象）。UC-B01〜B03、UC-R01、UC-M02はここで満たす。
実行環境、Brain、UIそれぞれが保証する範囲を分ける。具体的な実現手段（Supervisor、systemdのunit設定、named mutex等）は詳細設計の対象とし、ここでは何を保証するかだけを定める。
実行環境（各コンポーネントを動かすホスト側の管理手段）
host:1、§5.1）の二重起動を、Brainの稼働に依存せず拒否する（原則4、NFR-02）。既存プロセスが終了していれば、次の起動を妨げないBrain
/health/live・/health/ready、§8）ダッシュボード（§4.4）
UI
実装方式ではなく、外部から観測できる結果として定義する。
自動起動の契約（UC-B01、UC-R01）
/health/liveが応答すること、UIは最初のheartbeatをBrainが受信すること）二重起動拒否の契約（UC-B02、UC-M02）
target_idでの起動等）は、Brainが§6.1の起動数判定で重複として検出・表示する（FR-04）。これは実行環境による一次的な拒否を補う二次的な検出であり、二重起動そのものの防止手段ではない正常終了の契約（UC-B03）
ダッシュボードはBrainとは別に動くため、Brainの起動失敗もダッシュボードで確認できる。ダッシュボード自体が動いていない場合は、ダッシュボードでは確認できないため、対象ごとに確認経路を分ける。
| 対象 | 確認経路 | 根拠 |
|---|---|---|
| Brain自身の起動失敗（自動起動・ダッシュボードからの起動） | ダッシュボードで「起動失敗」として確認できる（§4.4）。詳細なログは実行環境の管理手段で確認する | UC-B01、UC-B05 |
| ダッシュボード自身の起動失敗 | 実行環境の正式な管理手段（サービスマネージャの状態・ログ等）。ダッシュボードは使えないため対象外 | UC-B01、確定事項2 |
| 常駐監視対象として登録されたUIの自動起動失敗 | ダッシュボード上で「未稼働」として確認できる（§6.2）。詳細なログは、そのUIを動かす実行環境側で確認する | UC-R01、FR-03 |
| 常駐監視対象として登録されていないUIの自動起動失敗 | ダッシュボードの対象外。一度も観測されないため、Brainは失敗の発生自体を知り得ない | 確定事項2、§3.1 |
| 新規導入したUIの初回起動の失敗（登録前） | 導入時に、運用者が一覧に「未登録のUI」として現れることを確認する（runbookの手順）。現れなければ、そのUIを動かす実行環境側で失敗状態・ログを確認する。登録は現れた後に行うため（§3.1）、登録前の失敗はダッシュボードでは「未稼働」にならない | UC-R01、§3.1 |
| 二重起動の拒否（実行環境が拒否できた場合） | 拒否されたプロセス自身の終了ログ・終了コード等、実行環境側で確認する | UC-B02、UC-M02 |
| 二重起動の検出（実行環境が拒否できず、Brainが検出した場合） | ダッシュボード上で「重複起動」として確認できる（§6.1） | FR-04 |
回復手順そのもの（再起動の具体的操作）は、実行環境ごとの運用手順（runbook）で定める（§13、対象外）。本書が定義するのは、失敗・重複をどこで確認できるかという経路までである。
ダッシュボードは、Brainとは別のプロセスとして、Brainと同じ実行ホストで動く（UC-B05、UC-D02）。Brainの中にあると、Brainが止まっているときに使えず、Brainを起動する操作も置けないためである。
次の方針を出発点とし、設計で検証する（経緯はIssue #14 の検討結果）。
識別を2階層にする。
process_instance_id: 現在動いているプロセスを区別する。起動のたびに変わる。process_instance_id は、UIが起動時に生成する（UUID等）。Brainとの事前のやり取りを必要とせず、最初のheartbeatを受信した時点でBrainがそのプロセスの観測を開始する。これは、運用者が管理画面から行う常駐監視対象の登録（§3.1）とは別の操作であり、heartbeatの送信によって常駐監視対象が自動的に作られることはない。
監視対象キーは (host_id, ui_kind, target_id) とする。
host_id: 実行ホスト（OSインスタンス。WindowsとWSL2は別のホスト）を指す、OS由来の安定した識別子。Linux/WSL2の /etc/machine-id、Windowsの MachineGuid、macOSの IOPlatformUUID 等から取得し、AiChatWlsの全コンポーネントで共通の方式・名前空間でハッシュ化して用いる。同じOSインスタンスからは、UIの種類や版によらず同じ値になる。方式や名前空間を変更する場合は、登録情報の移行が必要になる。設定値としては書かず、設定ファイルを別ホストへコピーしても値が変わらないようにする。表示用ホスト名とは別の属性とする。ui_kind: UIアプリの種類。target_id: 同一ホスト・同一UI種類の中の論理的な枠。単一なら default とする。マイクごとに別プロセスで多重起動する場合に、それぞれを別の監視対象として区別する。永続化されるキーに後から要素を足すと移行が必要になるため、最初からキーに含める。UIは3要素を申告し、Brainは登録と完全一致で突き合わせる。一致すれば登録された対象のプロセスとし、一致しなければ「未登録のUI」として観測する。
起動数ポリシーは、UIアプリ自身の性質として、UIが申告する。監視対象キーとは別の属性で、登録には持たせない（未登録のUIにも同じ判定を適用するため）。表現は、文字列と数値の組み合わせとする。
multi: 起動数の制限なし（多重起動可）host:N: 実行ホストごとにN個まで（host_id + ui_kind の単位で数える）。実行ホストごとに1つのUIは host:1limit:N: すべての実行ホストの合計でN個まで（ui_kind の単位で数える）稼働中のプロセス数が上限を超えれば、重複起動と判定する。target_id が違っても、同じ数え方の単位に入る。ポリシーにかかわらず、同じ host_id + ui_kind + target_id の稼働中プロセスが2つ以上なら、重複起動とする。同じ ui_kind で異なるポリシーを申告するプロセスが混在する場合は、いずれかの申告に違反していれば重複起動とする（厳しい方で判定する）。二重起動の拒否はUI側の実行環境が行うため、誤申告の実害は重複を検出しにくくなることにとどまる。記法の細部（区切り文字、省略形等）は詳細設計で決める。
「実行ホストごとに1つ」の強制はUI側の実行環境が行い、Brainは検出と表示を担当する。
表示用ホスト名は判定に使わない。
host_id の取得手段
/etc/machine-idHKLM\SOFTWARE\Microsoft\Cryptography\MachineGuidIOPlatformUUID（ioreg -rd1 -c IOPlatformExpertDevice 等で取得）/etc/machine-id を読む）。ホストの /etc/machine-id をコンテナへbind mountして共有することを、AiChatWls固有の運用方針とする。理由は、コンテナの再作成をまたいでhost_idを安定させたいためである。なお、machine-id(5)自体は、イメージ内の/etc/machine-idを空または欠落させておき、起動時にコンテナごとの個別IDを確立する運用を基本としており、ホストIDの共有を標準として推奨しているわけではない。ここでは、AiChatWlsの識別モデル(同じ物理・VMホストは同じhost_idを持つ)を優先し、あえてホストIDを共有する方針を採る。これにより、同じ物理・VMホスト上のコンテナは、そのホストと同じ host_id を持つ。bind mountしない場合、コンテナを再作成するたびに新しい host_id になり得るが、これは設定ファイルのコピーと同種の運用ミスとして扱う（§5.3）target_id の決め方: 単一枠なら default。複数枠（マイクごとの多重起動等）を使う場合は、運用者が任意の文字列を決め、UI側の設定ファイルに書く（自由記述、Brainからの自動配布はしない）。常駐監視対象への登録は、そのUIが観測一覧に現れてから選んで行うため（§3.1）、登録側へtarget_idを手で書き写す必要はないprocess_instance_id の形式: UUID v4文字列。生成主体はUI（§5.1で決定済み）。UC-R04（新旧プロセスの取り違え）は、process_instance_id の一致・不一致で判定でき、起動時刻の申告だけに頼る必要はない登録とキーがずれる誤設定は、登録側が「未稼働」、実プロセスが「未登録のUI」として両方に残るため、気づける。同じキーで2つのプロセスが動けば、重複起動として検出できる。
| 誤設定 | 表示 | 検出 |
|---|---|---|
target_id・ui_kind の打ち間違い、登録ミス |
登録側は未稼働、実プロセスは未登録のUI | できる |
| 同じキーで2プロセスが動く | 重複起動 | できる |
実行ホストごとに1つのUIが、異なる target_id で2つ動く |
重複起動（host_id + ui_kind の単位で判定） |
できる |
| 旧版のUIで管理プロトコルを送れない | 未稼働（管理プロトコルの版管理を導入した後の版であれば、「非対応版」と表示できる） | 原因は分からない |
| キーが登録と完全に一致するが、別のホスト・インストールである | 正常稼働に見える | できない |
コンテナが /etc/machine-id をホストと共有せず、再作成のたびに新しい host_id になる |
登録側は未稼働のまま。実プロセス側には新しい host_id のUIが増え続ける |
できない |
最後の2行は、host_id を設定値ではなくOS由来の値にすることで、設定ファイルのコピーによる発生を防ぐ。コンテナの場合はbind mountの徹底が同じ役割を果たす。それでも防げない申告の誤りは、自己申告を信頼する制約として受け入れ、検出対象外とする（自作のUIを信頼する運用）。
稼働、応答途絶、未稼働、重複起動等は性質が異なる（例: 重複した2プロセスの一方だけが応答途絶になり得る）ため、単一の状態一覧ではなく、次の直交する軸を別々に導出する。
| 軸 | 値 | 対象 |
|---|---|---|
| プロセス観測状態 | 稼働中／終了通知済み／期限切れ | プロセスごと |
| サービス利用可能性 | ready／not ready／不明 | Brainの会話サービス（UC-B04） |
| 監視対象充足状態 | 充足／未充足／不明（Brain再起動直後の猶予期間中。§6.4） | 登録済みの監視対象ごと |
| 登録対応状態 | 登録一致／未登録 | 観測プロセスごと |
| 起動数判定 | 正常／重複 | ポリシーに応じた単位（実行ホストごとに1つのUIは host_id + ui_kind、それ以外は監視対象キー）。「稼働中」のプロセス数で判定（「終了通知済み」「期限切れ」は数えない） |
| プロトコル互換性 | 対応／非対応 | 観測プロセスごと（§7.3で申告された版をBrainが判定） |
キーの打ち間違いでは、「登録済みの監視対象は未充足」と「実プロセスは未登録」が同時に成立するため、両者は別の軸として扱う。各軸の導出規則は6.1、軸の組み合わせから表示上の状態（稼働中・未稼働・応答なし・不明等）を導く規則は6.2に定める。
/health/live相当）と、依存先を含めて利用可能か（現行の/health/ready相当）を区別する（UC-B04）。host:Nはhost_id + ui_kind、limit:Nはui_kind、いずれのポリシーでも同じhost_id + ui_kind + target_idは別枠で常に対象）ごとに、「稼働中」のプロセス数を数え、上限を超えれば「重複」、超えなければ「正常」とする。「終了通知済み」「期限切れ」のプロセスは数えない（正常終了・途絶したプロセスが、新規プロセスとの重複起動に数えられないようにするため）。process_instance_id・heartbeat間隔・期限切れ時間・起動数ポリシー）は通常どおり解釈できることを前提にする。共通部分に含まれない情報（起動時刻・commit等）の信頼性は問わない。版管理の仕組み自体を持たない（版を申告しない）旧版のUIは、この軸の対象外とし、§7.3のとおり無言のまま未稼働として扱われる。matching_processes（§8.1）の内訳で確認できる。対応版のプロセスが1つでも「稼働中」であれば、非対応版のプロセスが同時に稼働していても対象全体の表示は「稼働中」に戻る（更新時の新旧混在を、いたずらに異常表示しないため。§6.5）。当該監視対象の充足状態が「未充足」へ遷移すれば、以降は通常の規則（未稼働・応答なし）に従う（途絶の判断は、プロトコルの解釈可否に影響されない）。UIが、heartbeat間隔と期限切れ時間を申告する。Brainは、応答途絶を数分以内（目安2〜3分）に反映できるよう、それぞれに申告値の上限と下限を持つ（暫定値を持ち、Brainの設定で変更できる。暫定値は詳細設計で決める。ユースケース文書 §9-4）。申告値が範囲外なら、それぞれの範囲内に丸める。
丸めた後の値には、次の不変条件を満たす。
期限切れ時間 ≥ heartbeat間隔 + 許容幅
許容幅は、通信遅延・スケジューリングの揺らぎを吸収するための、Brainが持つ別の設定値（暫定値を持ち、設定で変更できる）。個別の上限・下限で丸めた後にこの不変条件を満たさない場合、期限切れ時間を「heartbeat間隔＋許容幅」まで引き上げる（期限切れ時間の上限は超えない）。これにより、UIが申告どおり正常にheartbeatを送り続けている間は、その合間に一時的に「期限切れ」へ遷移することがない。
Brainの設定（heartbeat間隔・期限切れ時間それぞれの上限・下限、および許容幅）は、次を満たすように用意する。
期限切れ時間の上限 ≥ heartbeat間隔の上限 + 許容幅
これにより、どのUIの申告値であっても、丸め後に上の不変条件を必ず満たせる（期限切れ時間側の上限に阻まれて不変条件を満たせない、という矛盾が起きない）。この関係を保つことは、Brainの設定値を決める・変更する側の責任とする。
期限は、最後に確認した時刻に期限切れ時間を足して求める。
応答なし保持時間: 終了通知なしに「期限切れ」となったプロセスの記録を、破棄するまで保持する時間である。登録済みの監視対象はこの間「応答なし」と表示され、破棄後に「未稼働」へ移る。未登録のUIはこの間「応答なし」として残り、破棄後に一覧から消える（§6.2）。
Brainはプロセスの観測状態をメモリ上に保持する。再起動直後は、常駐監視対象の登録情報（永続化済み、§3.1）は復元できるが、稼働中プロセスの観測状態は失われる。§7で、heartbeat間隔・期限切れ時間・起動数ポリシーを含む全情報を毎回のheartbeatに載せる設計にしているため、各UIからの次のheartbeatを受信した時点で、そのheartbeat単体から観測状態を再構築できる。
ただし、Brainは再起動前にどのUIがどの間隔・期限切れ時間で送っていたかを覚えていないため、「次のheartbeatが来るまでの時間」を個別には見積もれない。そこで、Brain再起動時点から、Brainの設定が持つ期限切れ時間の上限（§6.3）に相当する猶予期間が経過するまでの間、登録済みの監視対象は実際の充足状態によらず一律「不明」として扱う（§6.1の監視対象充足状態、§6.2の表示）。猶予期間中にheartbeatを受信した対象は、そこで「充足」へ確定する。猶予期間を過ぎてもheartbeatが無い対象は、通常の判定（§6.1・§6.2）に従い「未充足」（表示は「未稼働」）へ移る。これにより、実際は稼働中のプロセスを、Brain再起動直後に誤って「未稼働」と表示することを避ける（UC-R05）。
猶予期間を「期限切れ時間の上限」とすることが安全なのは、§6.3の設定制約（期限切れ時間の上限 ≥ heartbeat間隔の上限＋許容幅）が保たれている場合に限る。この制約により、どのUIも、正常に稼働していれば期限切れ時間の上限が経過するまでに少なくとも1回はheartbeatを送っているはずであり、猶予期間内に「充足」へ確定できることが保証される。
同じ監視対象キーで複数のprocess_instance_idが観測された場合、それぞれを別のプロセスとして扱い、起動時刻とcommitで区別する（同一視しない、という意味で「取り違えない」）。「実行ホストごとに1つ」等のポリシーを持つUIで2つ目が観測された場合は、6.1の起動数判定により重複起動として検出される。更新時に旧プロセスをいつ・どう終了させるかの手順は、本書の対象外とし、運用手順（runbook）で定める（§13）。
commitを取得できない、またはUIが申告しない場合は「不明」として扱う。他の軸の判定には影響しない（NFR-08）。
UIが稼働状態をBrainへ伝える契約を定義する。§10の決定により、会話プロトコル（ui-brain-protocol.mdの/ask・keepalive）とは独立した契約とする。
host_id・ui_kind・target_id）process_instance_id版間で意味を変えない共通部分（エンベロープ）: 次のフィールドは、どのプロトコル版でも同じ形式・同じ意味を持つことを、プロトコル自体の制約とする。将来の版が追加できるのはこれ以外のフィールドだけであり、この共通部分の名前・形式・意味は変更しない。
host_id・ui_kind・target_id）process_instance_idこれらは、Brainの状態機械（§6）が監視対象への対応付け・途絶判定・重複判定を続けるために不可欠であり、Brainが対応していない版（非対応版）のheartbeatであっても、この共通部分だけは通常どおり解釈できることを前提にする。
共通部分に含まれない情報（起動時刻・commit・応答なし保持時間・表示用ホスト名・人向けversion等）は、非対応版のheartbeatではBrainが正しさを保証しない（将来の版で形式が変わっている可能性があるため）。状態取得（§8）の表示には、取得・解釈できた範囲でそのまま使ってよいが、解釈できない場合は「不明」として扱う（§6.6と同じ扱い）。これらは状態判定（稼働中・期限切れ・重複起動等）には使わない。応答なし保持時間は記録の破棄時期（§6.3）に使うが、非対応版の申告値は使わず、Brainのデフォルト値を適用する（共通部分に加えなくても、状態機械が止まらないようにするため）。
ui-brain-protocol.md §9と同じ切り分け）。heartbeat・終了通知は、送信元の認証を必須とする。認証なしで受理すると、認証されていない送信者が正当なUIになりすまして「稼働中」を偽装し未稼働を隠したり、任意の監視対象キー・process_instance_idを送って実在しない重複起動を作り出したりできてしまう。仮に通信路を暗号化しても（§9.2）、盗聴は防げるが、送信者が正当なUIであることまでは保証しないため、認証は通信路の保護とは別に必要である。
使用するトークンは、会話用トークンBRAIN_AUTH_TOKEN（ui-brain-protocol.md§3）とする（§9.1）。heartbeat・終了通知を送るのは会話するUI自身であり、会話用トークンを持つ主体とheartbeatを送る主体はほぼ一致するため、専用のトークンを設けても防げる相手がほとんどいない一方、UIが保持・配布する秘密が増えるためである。会話用トークンを持つが稼働状態を伝えないクライアント（リクエスト単位で完結するスクリプト等）もheartbeatを送れてしまうが、これは運用者自身が配布した自作のクライアントであり、自己申告を信頼する前提（§5.3、§7.4）の範囲内として受け入れる。
Brainが正常終了するとき（§4.2）に、観測中のUIへ停止を伝え、UIが対応する時間を取る。
運用者は、ダッシュボードから、動いているUIに終了を求められる（UC-R08、FR-22）。
process_instance_id）を指定して、Brainに要求する（書き込み契約。管理トークンで認可する。§9）機械可読な読み取り専用の状態取得を定義する。ダッシュボード（UC-D01）は、この取得結果を表示するだけの薄い画面であり、状態そのものを別途保持しない。
/health/live・/health/ready（ui-brain-protocol.md）と同じロジックを用い、その結果を本節のエンドポイントの応答にも含める（UC-B04、FR-06）。/health/live・/health/ready自体は、監視ツール等からの単純な生存確認用として別に残す（8.3）。あわせて、Brain自身の起動時刻・commit（取得できなければ「不明」）・人向けversion（任意）を含める（§3.2「Brain自身が持つ情報」。UC-D03がBrainについても更新結果の判別を求めるため）。監視対象キー・process_instance_idはBrainには適用しない（§3.1）matching_processes（重複起動時や、更新後に新旧プロセスが同時に残っている間は複数になり得る。UC-D03）、最終観測の要約（最終確認時刻・process_instance_id・終わり方。一致するプロセスの記録がすべて破棄された後も残る。§3.2、UC-R03）。各要素はprocess_instance_id・プロセス観測状態（§6.1）・起動時刻・commit・プロトコル版・プロトコル互換性（対応／非対応、§6.1）・最終確認時刻・表示用ホスト名（任意）を持つ。重複起動の注記（§6.1）process_instance_id、起動時刻、commit、プロトコル版、プロトコル互換性（対応／非対応）、最終確認時刻、表示用ホスト名（任意）、重複起動の注記（§3.4、UC-D02）matching_processesの各要素にも含める会話プロトコル（/ask・keepalive）とは別の、新しい読み取り専用エンドポイントとして提供する（§10で管理heartbeatを独立エンドポイントとした方針を踏襲する）。既存の/health/live・/health/readyは、監視ツール等からの単純な生存確認用として維持し、廃止・置き換えはしない。新エンドポイントは、1回の呼び出しで8.1の情報（Brain自身のliveness・readinessを含む）をまとめて返し、ダッシュボードが複数回の呼び出しを組み合わせなくても一画面を構成できるようにする（UC-D01）。エンドポイントの名称・具体的なJSON構造は詳細設計で決める。
本節の取得（閲覧）は、§9の閲覧トークンで認可する。常駐監視対象の登録・変更・解除（§3.1、FR-18）、復帰警告を確認済みにする操作（§3.1.1）、UIへの終了の要求（§7.8）は、本節とは別の書き込み契約とし、閲覧とは別の権限（§9の管理トークン）で認可する。状態取得と書き込み契約は、Brainが提供し、ダッシュボード（§4.4）が使う。
別の実行ホストからのBrainへの接続と、管理画面の閲覧に必要な認証・通信経路・権限の方針を定義する。実装は本書の範囲外である。
現行の会話プロトコル（ui-brain-protocol.md§3）は、単一の共有トークン（BRAIN_AUTH_TOKEN）による認証を、loopback運用を前提に採用している。本書が前提とする「別の実行ホストからの接続」（§1.3）と、「常駐監視対象の登録・変更・解除は閲覧と別の権限で認可する」（原則5、FR-18）を満たすため、現行方式を踏襲しつつ、トークンを次の2種類に拡張する。
いずれも、現行方式と同じ共有シークレット・Bearer認証（Authorization: Bearer <token>）とする。ユーザーアカウント・ロールベースの認証基盤は導入しない。
理由:
会話用トークン（BRAIN_AUTH_TOKEN）と、閲覧トークン・管理トークンは別のシークレットとする。閲覧・管理は利用者（人）に与える権限であり、UIが会話のために持つ秘密とは、保持する主体も漏れたときの影響も異なるためである。一方、管理heartbeat・終了通知（§7.6）は会話するUI自身が送るものであり、保持する主体が会話用トークンと同じであるため、会話用トークンで認証する（専用のトークンは設けない）。
現行の会話プロトコルは、loopback運用を前提とし、通信路自体の暗号化を行っていない（ui-brain-protocol.md§3）。別の実行ホストからBrainへ接続する場合、共有トークンは暗号化されずにネットワークを流れる。
本書では、通信路の暗号化（TLS、VPN・SSHトンネル等）を行わない。想定する運用では、通信は同じPCの中（WindowsとWSL2の間。§5.1では別の実行ホストとして扱うが、通信はPCの外に出ない）か、運用者が信頼するLANの中に限られ、盗聴者が経路上にいる状況を想定しにくいためである。暗号化を前提にすると、同じPCの中の通信にまでTLS等を求めることになり、運用に見合わない。
インターネット、公衆Wi-Fi等、運用者が信頼できないネットワークを通して接続することになった時点で、通信保護をあらためて検討する（本書の対象外。§13）。
| 操作 | 必要な権限 | 対応する契約 |
|---|---|---|
| §8の状態取得（閲覧） | 閲覧トークン以上 | §8 |
| 常駐監視対象の登録・変更・解除（UC-D06） | 管理トークン | §3.1 |
| 登録情報の復帰警告を確認済みにする（UC-D07） | 管理トークン | §3.1.1 |
会話（/ask等） |
会話用トークン（BRAIN_AUTH_TOKEN、既存） |
ui-brain-protocol.md |
| 管理heartbeat・終了通知の送信（§7） | 会話用トークン（BRAIN_AUTH_TOKEN） |
§7.6 |
| Brainの起動・停止（ダッシュボード。UC-B05） | 管理トークン | §4.4 |
| UIへの終了の要求（UC-R08） | 管理トークン | §7.8 |
| Ollamaのモデルを GPU から下ろす（ダッシュボード。UC-D08） | 管理トークン | §4.4 |
認可の境目は2つある。(1) ダッシュボードは、ブラウザ（利用者）からの閲覧・操作の要求を、閲覧トークン・管理トークンで自ら認可する。Brainの起動・停止はBrainが止まっていても行うため、この認可はダッシュボードが担う（§4.4）。(2) Brainは、状態取得・書き込み契約の要求を、ダッシュボードから来たものも含めて、自らトークンで認可する。ダッシュボードは、同じ権限の範囲でBrainの状態取得・書き込み契約を使う（具体的な受け渡しは詳細設計）。権限のないトークンによる登録変更・操作は拒否し、拒否の理由が分かる（UC-D06、FR-18）。認証されていない送信元からのheartbeat・終了通知は受理しない（§7.6）。
本節では方針までを決め、次は詳細設計で決める（§12.2）。
管理画面（ダッシュボード）は認証情報自体を画面に表示しない（NFR-07、ユースケース文書§9の末尾）。
現行の ui-brain-protocol.md との境界を明示し、本書の内容を統合するか、別文書として参照させるかを決める。
現行仕様には、会話セッションのTTL維持を目的とする POST /session/{session_id}/keepalive があり、session_id はUIプロセスの起動時に生成される。ただし、送信ループは必須ではなく、TTLはUIが指定する値（既定値86400秒・範囲60〜604800秒）である。これを管理heartbeatへ流用できるかを、次の3点で検討した。
/ask は管理heartbeatを兼ねない。 /ask は会話が発生したときしか呼ばれず、ウェイクワード待ちの音声UIのように正当に長時間会話が発生しないUIがある（FR-11で明示的に許容）。/ask の頻度を生存確認に使うと、これらを「応答なし」と誤検出する。session_id とプロセス識別子（process_instance_id、§5）は別の値にする。 契約自体は1・2で分離済みのため実害は小さいが、将来1プロセスが複数会話を扱う構成（現状スコープ外、§2.3）になっても影響を受けないよう、意味の異なる識別子として独立させる。ui-brain-protocol.md の会話エンドポイント群（/ask・keepalive）とは独立した新しいエンドポイントとして§7で定義する。session_id と process_instance_id は別々にUIが生成する（いずれもUUID）。ui-brain-protocol.md 側には、管理heartbeatは別文書（本書）で定義する旨のポインタを追記する（確定文書の改訂のため、運用者に別途確認する）。各ユースケースが、設計のどこで満たされるかを対応付ける。設計（本書）で決める事項は、すべてのユースケースについて決着している（§12.1）。「詳細設計・runbookへ送った事項」列は、方針を本書で決めたうえで、具体化を詳細設計（§12.2）または運用手順（runbook。§13）へ送った事項を示す。該当が無ければ「なし」とする（2026-09-24に全件を見直した）。
| ユースケース | 内容 | 設計の対応先 | 詳細設計・runbookへ送った事項 |
|---|---|---|---|
| UC-B01 | Brainの自動起動と失敗時の回復（正式な回復方法が分かる） | §4.1（実行環境の責務）、§4.2（自動起動の契約）、§4.3・§4.4（Brain自身の失敗はダッシュボードで確認し、詳細なログとダッシュボード自体の失敗は実行環境の管理手段で確認） | runbook: 回復手順（§13） |
| UC-B02 | Brainの二重起動の拒否 | §4.1（Brain自身が拒否）、§4.2（二重起動拒否の契約）、§4.3 | なし |
| UC-B03 | Brainの正常終了 | §4.1、§4.2（正常終了の契約）、§7.7（停止シーケンス） | 詳細設計: 停止シーケンスの通知・応答の形式、応答待ち時間の扱い（§12.2） |
| UC-B05 | ダッシュボードからのBrainの起動・停止（Brainが止まっていても状態が分かる） | §4.4（ダッシュボード）、§4.3、§9.3（管理トークン） | 詳細設計: ダッシュボードの実現方式、実行環境との連携、トークンの受け渡し（§12.2） |
| UC-B04 | Brainの生存と会話サービスとしての利用可能性の区別 | §6.1（サービス利用可能性の軸）、§8.1（Brain自身の状態）、§8.3（/health/live・/health/readyの維持） |
なし |
| UC-R01 | 常駐UIの自動起動と失敗時の回復（正式な回復方法が分かる） | §4.1、§4.2（自動起動の契約）、§4.3（登録済みUIの失敗はダッシュボードで「未稼働」、登録前の新規導入UIはrunbookの確認手順）、§3.1（登録の方法）、§6.2 | runbook: 新規導入UIの確認手順、回復手順（§13） |
| UC-R02 | 会話していない間のUIの稼働の確認 | §7.1（会話と独立したheartbeat）、§3.2（プロセスが持つ情報）、§8.1（表示用ホスト名・起動時刻・commit）、§10（/askを生存確認に使わない） |
なし |
| UC-R03 | 正常終了・クラッシュ・通信断のいずれでも、終了通知が届かないUIの途絶を判断 | §6.1（期限切れへの遷移、記録の破棄）、§6.3（期限切れの判断、応答なし保持時間）、§6.2（応答なし・未稼働）、§7.2（終了通知は任意）、§3.2・§8.1（最終確認時刻、記録破棄後は最終観測の要約。Brain再起動をまたぐ分は観測の出来事のログ） | 詳細設計: 応答なし保持時間の暫定値、観測の出来事のログの形式（§12.2） |
| UC-R04 | UI再起動時の新旧プロセスの区別 | §5.2（process_instance_id）、§6.5 |
runbook: 更新時の旧プロセスの終了手順（§13） |
| UC-R05 | Brain再起動後のUIの再認識 | §6.4（猶予期間と「不明」）、§7.1（毎回全情報を載せる）、§3.2（保持場所） | なし |
| UC-R06 | 稼働状態を伝えるUIと伝えないUIの混在 | §3.2、§3.3、§3.4 | なし |
| UC-R07 | 常駐が期待されないUIの起動・終了 | §3.1、§6.2（未登録のUI）、§6.3（応答なし保持時間） | 詳細設計: 応答なし保持時間の暫定値（§12.2） |
| UC-R08 | ダッシュボードからUIへの終了の要求 | §7.8、§8.1（終了の要求の表示）、§9.3 | 詳細設計: 要求の形式、プロトコル版2の差分（§12.2） |
| UC-R09 | UIを自分の実行ホストで起動・停止する | §4.1（UIの責務） | UIごとの詳細設計（音声UIはAiChat側） |
| UC-M01 | 多重起動を許可されたUIの複数起動 | §5.1（multi）、§6.1（起動数判定）、§8.1（各プロセスを個別に表示） |
なし |
| UC-M02 | 実行ホストごとに1つのUIの二重起動拒否 | §4.1（実行環境が拒否）、§4.2（二重起動拒否の契約）、§5.1（host:1）、§6.1（拒否できなかった場合の検出） |
詳細設計: 排他の具体方式（§13） |
| UC-M03 | 実行ホストごとに1つのUIを別の実行ホストで起動 | §5.1（host_id + ui_kindの単位で数える）、§6.1 |
なし |
| UC-D01 | 管理ダッシュボードでの状態確認（実行ホスト・利用可能性・最終確認時刻を表示、機密情報は非表示） | §6（状態の算出）、§8.1・§8.3（一回で取得できる取得契約）、§8.2・§9.5（会話内容・認証情報を含めない） | 詳細設計: 状態取得エンドポイントの名称・JSON構造（§12.2） |
| UC-D02 | 起動想定のコンポーネントが確認できない場合の表示 | §6.2（登録済みUIは「未稼働」「応答なし」として残る）、§8.1、§4.4（Brainの停止・起動失敗はダッシュボードで確認）、§4.3（ダッシュボード自体は実行環境の管理手段） | なし |
| UC-D03 | 更新後の切替と古いプロセスの残存の判別（BrainまたはUI） | UIは§6.5、§8.1（matching_processes）。Brainは§3.2「Brain自身が持つ情報」、§8.1（Brain自身の状態） |
なし |
| UC-D04 | 会話の利用状況の確認 | §3.3、§8.1（会話の集計） | なし |
| UC-D05 | 別の実行ホストからのダッシュボード閲覧（閲覧認可を含む） | §8（同じ取得契約）、§9.1（閲覧トークン）、§9.2（通信保護。信頼するネットワーク内に限り暗号化しない）、§9.3、§9.5 | 詳細設計: トークンの配布手順（§12.2） |
| UC-D06 | 運用者による常駐監視対象の管理（登録・変更・解除） | §3.1（観測一覧からの登録、登録の管理、重複登録の拒否と拒否理由の提示、計画停止は解除・再登録で扱う）、§6.2（解除後に一致していたプロセスは未登録のUI）、§9.1・§9.3（管理トークン、権限のない変更の拒否） | 詳細設計: 拒否理由の具体的な表現（§12.2） |
| UC-D08 | Brainが使うOllamaのモデルをGPUから下ろす（WSL・Ollama・Brainを止めない） | §4.4（ダッシュボードの役割）、§9.3（管理トークン） | 詳細設計: 表示と操作の形式（runtime-management-detail-dashboard.md§4.3・§5.2） |
| UC-D07 | 登録情報の破損・消失からの復帰（Brainは起動を続け、正常だった状態へ自動で戻し、運用者が確認できる。UIは影響を受けない） | §3.1.1（保存・世代・起動時の自動復帰・復帰警告）、§8.1（復帰警告の提供）、§9.3（確認済みにする操作の認可）、ユースケース文書4.5（3者から見た結果） | 詳細設計: ファイルの置き場所・形式、世代の保持期間の暫定値、確認操作の形式（§12.2）。runbook: バックアップの別保管（§13） |
なし（2026-09-24にすべて決着した。経緯は§14）。
本書で方針まで決め、具体化を詳細設計（runtime-management-detail-<領域>.md）へ送ったもの。本書では決めない。
process_instance_idへの要求、同じ要求の再送、要求時刻の更新の規則、版1のUIへ要求したときの結果を、エラーの契約として含める常駐監視対象の登録・永続化・復帰警告の確認・UIへの終了の要求に関する項目（拒否の理由の表現、登録情報ファイル・警告ファイルの置き場所・形式・暫定値、復帰警告の確認の形式、終了の要求の形式とプロトコル版2の差分）は、runtime-management-detail-registration.md（2026-09-26合意）で決めた。
ダッシュボードの実現方式（プロセスの形、待ち受けのアドレス、実行環境との連携、トークンの受け渡し）と、Brainの起動・停止を続けて押した場合・起動中・停止処理中に押した場合の扱い（既に目的の状態なら何もせず成功とし、途中なら今の状態を添えて拒否する）は、runtime-management-detail-dashboard.md（2026-10-05合意）で決めた。
解決済みとして削除した項目: 重複起動の導出規則（Brainが§6.1の起動数判定として一元的に導出する。登録側・表示側で別々に判定しない）。更新時の旧プロセス置き換え手順の位置づけ（設計の対象外とし、運用手順（runbook）で定めると§6.5で確定した）。
runtime-management-implementation-plan.md で決めるruntime-management-detail-<領域>.md で定義するruntime-management-runbook.mdで定める。本書から送った手順は、失敗時の回復手順（§4.3）、更新時の旧プロセスの終了手順（§6.5）、新規導入UIを一覧で確認してから登録する手順（§3.1）、登録情報のバックアップの別保管（§3.1.1）である主要な決定を、時系列でまとめる。詳細な議論は、根拠のIssueコメントを参照する。記入の仕方は設計文書の更新ルールに従う。
| 日付 | 決めたこと | 理由 | 却下・置き換えた案 | 根拠 |
|---|---|---|---|---|
| 2026-09-21 | 実行環境との責務境界の節（§4）を追加した | UC-B01〜B03、UC-R01、UC-M02について、実行環境・Brain・UIのどれが何を保証するかを書く場所がなかった | （なし。骨組みに節がなかった） | #6462 |
| 2026-09-21 | 認証・通信保護は接続経路に応じて定める（§1.3） | 現行の会話プロトコルはloopback運用を前提としており、「認証は場所に依存しない」は強すぎた | 「認証・応答はUIの場所に依存しない」 | #6462 |
| 2026-09-21 | 状態を直交する軸に分けて導出する（§6） | 稼働・応答途絶・未稼働・重複は性質が異なり、単一の一覧にすると状態が爆発する | 単一の状態一覧 | #6462、#6467 |
| 2026-09-21 | セッションkeepaliveと管理heartbeatの境界を論点とする（§10） | 会話とプロセスを分ける原則が、keepaliveの流用で崩れる恐れがある | （論点として明示。未決） | #6462 |
| 2026-09-21 | 期待構成を、運用者が登録しBrainが永続保持する「常駐監視対象」へ置き換える（§3.1） | 無人で動くUIの起動失敗を検出したい（シナリオA）。常駐区分をUIの自己申告に頼ると、誤申告で監視から外れる（シナリオD） | 案X（観測のみ、常駐は自己申告、期待の一覧なし）。「権威的な期待構成」（事前の静的な全体一覧。#6463） | #6463、#6464、#6465、#6466 |
| 2026-09-21 | 原則5を「プロセス操作をしない」に絞る。監視設定の変更は許可し、閲覧とは別の権限で認可する | 原則5の目的は、起動・停止・再起動の混入を防ぐことで、設定変更の禁止ではない。運用者が管理画面から登録する方が管理しやすい | 「ダッシュボードは読み取り専用」 | #6465、#6466 |
| 2026-09-21 | 監視対象キーを(host_id, ui_kind, target_id)とする。host_idはOS由来のIDのハッシュ。target_idは最初からキーに含める（§5.1） |
設定値のhost_idは、設定ファイルのコピーで別ホストと同じ値になる。永続化するキーに後から要素を足すと移行が必要になる。マイクごとの多重起動を想定 |
host_idを設定値にする案。表示用ホスト名を判定に使う案 |
#6465 |
| 2026-09-21 | 管理プロトコルにプロトコル版の管理を含める（§7） | 旧版のUIが無言で未稼働になるのを避け、非対応版を明示できるようにする | （なし） | #6465 |
| 2026-09-21 | Brainを常駐監視対象の登録対象から外す | Brain自身の未稼働は、Brain内ダッシュボードでは判定できない。実行環境の管理手段で確認する | 確定事項3の「Brainと常駐音声UI」を登録する案 | #6466 |
| 2026-09-21 | 起動数判定をポリシー別にする。UC-D06（常駐監視対象の管理）を追加する。UC-R07を改訂する。状態の軸を2軸に分ける。「1プロセス＝1監視対象」の表現を直す | target_idが違うと二重起動を検出できない。中心操作（登録）に対応するユースケースがなかった。UC-R03とUC-R07が衝突していた |
キー単位だけの重複判定。「1プロセスは1つの常駐監視対象に対応」 | #6467 |
| 2026-09-21 | 起動数ポリシーはUIが申告する。heartbeat間隔と期限切れ時間もUIが申告し、Brainが上限・下限で制限する | ポリシーはUIアプリの性質で、未登録のUIにも同じ判定が要る。UIの特性はUI自身が最もよく知っている。応答途絶を数分以内に反映する要件を守るため、Brainが範囲を制限する | 登録にポリシーを持たせる案。Brainだけが期限を決める案 | #6468 |
| 2026-09-21 | 上限・下限は暫定値を持ち、設定で変更できる。起動数ポリシーの表現をmulti／host:N／limit:Nとする（§5.1、§6） |
具体値は運用で調整する。2値だけでなく、ホストごと・全体のN個までも同じ形式で表せる | 2値（多重起動可／実行ホストごとに1つ） | #6469 |
| 2026-09-21 | 設計文書の更新ルール（doc-update-rules.md）を新設し、文書冒頭・STARTUP_CONTEXT.md・AGENTS.mdから参照させる。設計書に「決定の経緯」節を設け、Issue本文を現在の設計に書き直した |
更新するたびにIssueへ理由を書いても、セッションが変わる、または別の担当者（CODEX等）が更新するとルールが失われ、理由が追えなくなる。ルールをリポジトリ内に置き、更新する人が必ず目にする形にする | ルールを会話（セッション内）だけで運用する案。自動チェック（quality.shで設計書の変更コミットにIssue番号を要求する案）は、コメントの中身まで検査できず負担が増えるため見送り |
#6470 |
| 2026-09-22 | host_idの取得手段（OSごと）とハッシュ方式、target_idの決め方、process_instance_idの形式を確定した（§5.2）。コンテナは取得手段を分けず、ホストの/etc/machine-idをbind mountして共有する運用要件とした |
OS別の標準的な取得手段（/etc/machine-id・MachineGuid・IOPlatformUUID）を採用。コンテナは取得手段自体を分けず、ホストの/etc/machine-idをbind mountして共有するAiChatWls固有の運用方針とすることで、追加の取得手段を作らずに済む（machine-id(5)自体はコンテナごとの個別ID生成を基本としており、これはAiChatWlsが識別モデルの安定性を優先してあえて採る方針である。CODEXレビュー#6482で指摘、修正済み）。bind mountを怠った場合は、設定ファイルのコピーと同種の「検出できない誤設定」として§5.3に整理した |
「取得不能な環境（コンテナ等）は対象外」として、取得手段を決めずにエラーで済ませる案（コンテナが一般的な実行環境である以上、それでは使えないと同義になるため不採用） | #6478 |
| 2026-09-22 | セッションkeepaliveと管理heartbeatを別契約（別エンドポイント）にする。/askは管理heartbeatを兼ねない。session_idとprocess_instance_idは別の値にする（§10） |
会話TTL（最大7日）と応答途絶検出（数分以内）は時間スケールが両立せず、単一の仕組みに統合すると一方の要求を必ず破る。/askは会話が発生したときしか呼ばれず、頻度を生存確認に使うと正当に無会話が続くUI（ウェイクワード待ち等）を誤検出する |
keepaliveまたは/askを管理heartbeatに流用する案（時間スケールの衝突・誤検出という実害があるため不採用）。session_idをそのままprocess_instance_idとして使う案（現状の実害は小さいが、契約分離後も識別子を独立させる方を採った） |
#6479 |
| 2026-09-22 | 状態遷移（§6）とUI–Brain管理プロトコル（§7）の本文を書いた。5軸の導出規則、軸の組み合わせから「未稼働」「応答なし」等を導く規則、Brain再起動後の再認識（heartbeat単体から状態を復元）、新旧プロセスの区別規則、heartbeatでプロセス観測を開始する契約、終了通知は任意、プロトコル版の非対応時の扱いを確定した | §5・§10までの決定を、実際に判定・通信できる形に具体化する必要があった。終了通知を任意にしたのはNFR-01（正常終了処理が無くても収束する）と整合させるため。heartbeat単体からの状態復元は、Brainが記憶を持たずに再起動できる設計（UC-R05）を実現するため | （なし。骨組みの未着手部分を埋めた） | #6480 |
| 2026-09-22 | CODEXレビュー（#6482）の指摘7件をすべて反映した。反映しなかった指摘はない。(1)プロセス観測状態が「稼働中」に留まり「期限切れ」へ遷移できない不備を修正（期限切れ時間以内かどうかで判定）。(2)起動数判定が「終了通知済み」を重複起動に数えていた不備を修正（「稼働中」のみを数える）。(3)正常終了後の表示状態が未定義だった点を修正（終了通知を受けたら直ちに「未稼働」。未登録UIも同様）。(4)Brain再起動直後の「不明」を状態軸・表示規則に追加（猶予期間の導入）。(5)heartbeatと常駐監視対象の「登録」の混同を解消（heartbeatは「観測の開始」であり、常駐監視対象の登録は運用者のみが行う）。(6)決定の経緯の根拠欄を実際のIssueコメントリンクに置き換えた。(7)machine-id(5)の説明を訂正（コンテナへのホストID共有は標準推奨ではなく、AiChatWls固有の運用方針であると明記） |
push前のレビューで、状態遷移の2箇所（期限切れ・重複起動）に、設計として成立しない誤りが見つかったため。用語の混同（heartbeat/登録）は将来の実装者を誤誘導する恐れがあったため | （なし。既存の誤りの修正） | #6482 |
| 2026-09-22 | heartbeat間隔と期限切れ時間の丸め後の値に、不変条件（期限切れ時間 ≥ heartbeat間隔＋許容幅）を追加した。Brainの設定制約（期限切れ時間の上限 ≥ heartbeat間隔の上限＋許容幅）も明記した（§6.3、§6.4） | CODEX再レビュー（#6483）で、両者を独立に上限・下限でクランプするだけでは、丸め後に期限切れ時間がheartbeat間隔以下になり得ることが指摘された。正常にheartbeatを送っていても、その合間に周期的に「期限切れ」「応答なし」へ遷移してしまう。§6.4のBrain再起動後の猶予期間（期限切れ時間の上限）も、この制約が成り立たなければ、heartbeat間隔の上限の方が長い場合に正しく機能しない | （なし。既存の不備の修正） | #6484 |
| 2026-09-22 | 実行環境・Brain・UIの責務分担、自動起動・二重起動拒否・正常終了の結果契約、失敗状態・ログ・回復手順の確認経路を確定した（§4） | UC-B01〜B03、UC-R01、UC-M02について、実現方式ではなく外部から観測できる結果と、Brain自身／登録済みUI／未登録UIで異なる確認経路を明文化する必要があった | （なし。骨組みの未着手部分を埋めた） | #6490 |
| 2026-09-22 | 機械可読な状態取得の契約（取得できる情報、含めないもの、独立エンドポイントとして提供、閲覧トークンによる認可）を確定した（§8） | UC-D01が求める一画面表示と、NFR-03（状態取得は読み取り専用）・NFR-07（会話内容・認証情報を含めない）を、具体的な取得契約として定義する必要があった | （なし。骨組みの未着手部分を埋めた） | #6490 |
| 2026-09-22 | 認証を、現行の共有トークン方式を踏襲した閲覧用・管理用の2トークンとする。別の実行ホストからの接続は通信路の暗号化を前提とする（§9） | 個人・小規模運用の現状ではアカウント基盤の複雑さに見合う利点がなく、既存の会話プロトコルと認証方式を揃える方が学習・運用コストが小さい。FR-18（登録変更を閲覧と別権限にする）は2トークンで満たせる | アカウント・ロールベース認証の新規導入。単一トークンのまま権限分離をしない案（FR-18と矛盾するため不採用） | #6490 |
| 2026-09-22 | 登録済み監視対象の一致プロセスをmatching_processesの一覧で表現し、表示用ホスト名（任意）を追加した（§8.1）。新しい状態取得エンドポイントが/health/*と同じロジックの結果を含める一方、/health/live・/health/ready自体は監視ツール向けに維持する整理にした（§8.1、§8.3） |
CODEXレビュー（push前）で、単一値のような記述では重複起動・新旧プロセス残存時にUC-D03を判別できないこと、host_idがハッシュ値のため表示用ホスト名がないと人が実行ホストを確認しにくいこと、/health/*の扱いが二通りに読めることを指摘された |
一致するプロセスを単一の起動時刻・commitだけで表す記述（複数プロセスを表現できないため不採用） | #6492 |
| 2026-09-22 | 管理heartbeat・終了通知の認証を必須と決定した（§7.6）。使用するトークンの種類だけを詳細設計へ送る | CODEXレビューで、heartbeatが自己申告だけで受理されると、認証されていない送信者が「稼働中」を偽装して未稼働を隠したり、偽の重複起動を作り出せることを指摘された。TLS（§9.2）は盗聴を防ぐが送信者の正当性は保証しないため、認証の要否自体を本書で決める必要があった | heartbeat認証の要否も含めて詳細設計に委ねる案（実装時に無認証のまま実装される恐れがあるため不採用） | #6492 |
| 2026-09-22 | 「非対応版」を、プロトコル互換性という独立した軸（対応／非対応）から導く、独立した表示状態として追加した（§6の軸表、§6.1、§6.2、§8.1） | CODEX再レビューで、§7.3の「非対応版として区別して表示する」が、§6・§8のどこにも反映されておらず、実装者が独自解釈する余地が残っていた。非対応版は「解釈の前提が崩れている」状態であり、「解釈はできるが数が多い」重複起動（既存状態に重ねる注記）とは性質が異なるため、独立状態として扱う方を選んだ | 重複起動と同様に、通常の表示状態へ重ねる注記として扱う案（性質の違いを踏まえ不採用） | #6494 |
| 2026-09-22 | プロトコル版間で意味を変えない共通部分（エンベロープ: プロトコル版・監視対象キー・process_instance_id・heartbeat間隔と期限切れ時間の申告値・起動数ポリシー）を定義した（§7.3）。複数プロセスの互換性が混在する場合は、対応版が1つでも稼働中なら監視対象全体を「稼働中」とする集約規則を定めた（§6.2）。未登録のUIには「非対応版」の表示区分を適用しないことを明記した |
CODEX再レビューで、非対応版でも監視対象キー等の他フィールドを解釈できる前提になっている点（Brainの状態機械に必要な範囲の線引きがない）と、新旧プロセス混在時の集約規則の曖昧さを指摘された。全フィールド固定（版の拡張性を過度に縛る）でも版番号のみ固定（状態機械が非対応版で機能しなくなる）でもなく、状態機械に不可欠な範囲だけをエンベロープとして固定する中間案を採った。集約規則は、更新時の新旧混在（§6.5）を異常表示にしないことを優先した | 全フィールドを版間で固定する案（拡張性を縛りすぎるため不採用）。版番号のみを共通部分とする案（監視対象への対応付け・途絶判定が非対応版で成立しなくなるため不採用）。稼働中プロセスが1件でも非対応なら全体を非対応版とする集約規則（更新のたびに一時的な異常表示が発生するため不採用） | #6496 |
| 2026-09-24 | §3.2（実際のプロセス）・§3.3（会話）の残る本文を書いた。プロセスが持つ情報を§7.1・§6.1と突き合わせて列挙し、保持場所（メモリ上のみ）を明記した。session_idがui-brain-protocol.mdの既存規定どおりプロセス起動時に1つ生成され生存期間中使い回されること、process_instance_idとは独立した識別子であることを整理した |
骨組みに残っていた未着手部分を埋める必要があった。新しい設計判断ではなく、§5〜§7・§10で既に決めた内容の集約である | （なし。骨組みの未着手部分を埋めた） | #6503 |
| 2026-09-24 | §3.2に「Brain自身が持つ情報」（起動時刻・commit・人向けversion。自身の起動時点で直接把握し、heartbeatは介さない）を追加し、§8.1のBrain自身の状態にも含めた。UIプロセスが持つ情報を「UIが申告する値」と「Brainが導出する値」に分けて列挙し直した | CODEXレビューで、Brain自身の起動時刻・commitがどこにも定義されておらず、UC-D03（BrainまたはUIの更新結果判別）がBrainについて未充足だったこと、プロトコル互換性・丸め後の値・最終確認時刻というBrain導出値がUI申告値と混在していたことを指摘された | Brain自身にも監視対象キー・process_instance_idを適用する案（Brainは常駐監視対象の登録対象外という§3.1の決定と矛盾するため不採用） |
#6505 |
| 2026-09-24 | 常駐監視対象の「一時無効化」を廃止し、計画的な長期停止は登録の解除・再登録で扱う（§3.1、FR-01、§9.1、§9.3。ユースケース文書UC-D06・§6も改訂） | §11の見直しで、一時無効化が§6の状態規則に反映されていないことが分かった。反映するには表示状態・一致プロセスの扱い・重複起動の扱いを追加で決める必要がある一方、無効化の利点は登録内容（監視対象キーの3要素のみ）を覚えておくことだけで、解除・再登録で代えられる。能動通知はしない（NFR-09）ため、計画停止中の「未稼働」表示の実害も小さい。状態規則を単純に保つことを優先した（運用者の判断） | 一時無効化を残し、表示状態「無効」を追加する案（Claudeの当初案。コミット前に取り下げ）。一時無効化を廃止し、計画停止中の「未稼働」表示をそのまま受け入れる案。置き換えた記述: UC-D06・FR-01・§3.1・§9.1・§9.3の「一時無効化」（2026-09-21、#6467で追加） | #6508 |
| 2026-09-24 | §11（ユースケース対応表）を全件見直した。対応先を項単位にし、「残る未決」列を追加した。§12の「応答なし」として残す時間を、登録済みの監視対象（未稼働へ切り替わるまで）と未登録のUI（一覧から消えるまで）の両方を含む形に直した | 受け入れ条件（全ユースケースの対応付け）の最終確認のため。§6.2が§12へ送っていた項目の一方が、§12に記載されていなかった | （なし。対応表の精緻化と記述の整合） | #6509 |
| 2026-09-24 | 常駐監視対象の登録・変更・解除を拒否した場合は、拒否理由を要求元へ返す契約を§3.1に追加した（理由の具体的な表現は詳細設計）。「登録・変更」とだけ書いていた箇所（§1.3、§8.4、§9.1、ユースケース文書§1.1・アクター表）を「登録・変更・解除」に揃えた | CODEXレビューで、UC-D06が求める「重複登録を拒否した理由が分かる」ことが設計されていないのに、§11で満たしているものとして扱われていたことを指摘された。また、一時無効化の廃止で解除が計画停止の中心操作になったのに、一部の認可の記述から解除が漏れており、契約が曖昧だった | 拒否理由の提示を§12の未決事項として残す案（拒否理由を返すこと自体は運用者の判断を要さず、表現の詳細だけを詳細設計へ送れば足りるため不採用） | #6510 |
| 2026-09-24 | §12を「§12.1 設計で決めるもの」と「§12.2 詳細設計へ送ったもの」に分けた。§6.3・§7.3で詳細設計へ送っていた暫定値・採番規則も§12.2に載せた。§11「残る未決」の参照先を合わせた | 未決事項と、本文で既に詳細設計へ送った事項が混在し、設計がどこまで済んだか読み取れなかった（運用者と合意） | （なし。既存の扱いの整理） | #6511 |
| 2026-09-24 | 終了通知なしに期限切れとなったプロセスの記録を残す「応答なし保持時間」を、UIが任意で申告し、申告が無い場合・非対応版の場合はBrainのデフォルト値を使い、Brainが上限・下限で丸める値とした。記録の寿命として一元化し、破棄後に登録済みの監視対象は「未稼働」、未登録のUIは一覧から消える（§3.2、§6.1、§6.2、§6.3、§7.1、§7.3） | 適切な保持時間はUIの性質で決まる（常駐音声UIは長く、頻繁に開閉するブラウザのタブ等は短く）。heartbeat間隔・期限切れ時間と同じ「UIが申告し、Brainが制限する」型に揃えた。上限は記録がメモリに溜まり続けるのを防ぐためにも要る。デフォルト値があるため、エンベロープに加えなくても非対応版で状態機械が止まらない（運用者の提案） | Brainの設定値1つを全UIに適用する案（Claudeの当初案。UIの性質の違いを表せない）。登録済みは「応答なし」を保持し続ける案（期限切れ記録の破棄規則が別に要る）。登録済み・未登録で別の値を持つ案。置き換えた記述: §6.2の「一定時間（残す時間は§12の未決事項）」 | #6512 |
| 2026-09-24 | 管理heartbeat・終了通知を、会話用トークンBRAIN_AUTH_TOKENで認証する。専用のトークンは設けない（§7.6、§9.1、§9.3） |
トークンを分けて意味があるのは保持する主体が異なる場合だけであり、会話用トークンを持つUIとheartbeatを送るUIはほぼ一致する。専用トークンにすると、常駐UIが持つ秘密と配布の手間が倍になる。会話のみのクライアントがheartbeatを偽装できる点は、自作クライアントを信頼する既存の前提（§5.3、§7.4）の範囲内として受け入れた。閲覧・管理トークンは利用者（人）の権限であり主体が異なるため、従来どおり会話用と分ける（運用者の判断） | heartbeat専用のトークンを設ける案。閲覧トークン・管理トークンを使う案（権限の原則に反するため不可）。置き換えた記述: §7.6「トークンの種類は詳細設計で決める」、§9.1「別契約であるため、トークンも共有しない」、§9.3「トークンの種類は9.4で未決」 | #6513 |
| 2026-09-24 | 常駐監視対象の「事前登録」を廃止し、登録は観測一覧に現れたUIを選ぶ方法に限る。新規導入したUIは、一度起動して一覧に現れたことを確認してから登録する（runbookで定める前提）（FR-01、§3.1、§4.3、§5.2、§11。ユースケース文書UC-D06も改訂） | host_idはハッシュ値で人には分からず、事前登録にはhost_idの確認手段（表示コマンド・候補表示等）が必要になる。一方、事前登録で拾えるのは「新規導入したUIが最初から一度も起動に成功せず、運用者も導入後に確認していない」場合に限られ、導入時の確認手順で代えられる。廃止すれば、人がhost_idを扱う場面と、登録値の手入力（打ち間違い）がなくなる（運用者の判断） |
host_idを表示するコマンドを用意し、観測済みホストを候補に出す案（Claudeの当初案）。表示用ホスト名で仮登録し後から結び付ける案（表示用ホスト名を判定に使わない決定に反する）。対象ホスト上から登録APIを呼ぶ案（管理トークンがUIホストに散らばる）。置き換えた記述: UC-D06・FR-01・§3.1・§5.2・§11・§12.1の事前登録（2026-09-21、#6467で追加） |
#6514 |
| 2026-09-24 | ユースケース文書にUC-D07（登録情報の破損・消失からの復帰）と、Brain・UI・運用者の3者から見た想定シナリオ（4.5）を追加した。§11にUC-D07の行を追加した（設計の対応は§12.1で検討中） | 登録情報の永続化とバックアップを検討する中で、破損時にBrain・UI・運用者がそれぞれどう認識し、どう動くかを明らかにする必要があった。仕組み（ファイル・世代）ではなく、利用者から見た期待結果としてユースケースに残す（運用者の依頼） | （なし。ユースケースの追加） | #6515 |
| 2026-09-24 | 常駐監視対象の登録情報を、Brainのホスト上の1つのファイルに保存する。正常な書き込みのたびに世代を作り、一定期間（最新の数世代は期間によらず）残す。起動時に読めなければ、壊れた本体を退避し、最新の読める世代から自動で戻す（無ければ登録0件）。Brainは起動を続ける。復帰警告は発生日時つきで状態取得に含め、運用者が確認済みにする（管理トークン）まで、ファイルに保存して再起動をまたいで残す。解除は登録情報から1件を削除する（§3.1、§3.1.1、FR-20、§8.1、§8.4、§9.1、§9.3） | 数件〜数十件の登録にはファイルで足りる。世代は壊れたときではなく正常なときに作っておく（運用者の指摘）。書いた内容そのものを世代にすると、最新の世代が本体と同じになり、破損時に何も失わない。警告を再起動で消すと、再起動を繰り返したときに経緯が分からなくなる（運用者の指摘）。監視設定の破損で会話サービスを止めない | データベース（過剰）。エクスポート／インポート機能（書き込み契約が増え、ファイルのコピーで足りる）。直前の内容を世代にする案（最新の変更を失う）。読めない間は登録変更を拒否し続ける案（運用が重い）。警告を次の再起動まで表示する案（Claudeの推奨。再起動を繰り返すと分からなくなるため不採用） | #6515、#6516 |
| 2026-09-24 | CODEXレビュー（#6517）の指摘7件をすべて反映した。(1)登録済みの監視対象ごとに「最終観測の要約」（最終確認時刻・process_instance_id・終わり方）を残し、プロセスの記録を破棄した後もUC-R03の「最後に確認できた時刻」を示せるようにした（§3.2、§6.2、§8.1）。(2)復帰警告を、登録情報とは別で世代の対象にしない「警告ファイル」に保存し、「警告の保存を本体の書き直しより先に行う」という不変条件を設けた（§3.1.1）。(3)警告に種別（破損／消失）を加え、消失時は退避ファイル名を「該当なし」とした。(4)§11の列を「詳細設計・runbookへ送った事項」に改め、書き方を統一した。(5)ユースケース文書4.5を、観測できる結果の記述に改めた。(6)§11の括弧を修正した。(7)§6.5の参照先を§13にし、§13にrunbookへ送った手順の一覧を追加した |
(1)記録の破棄を導入したことで、UC-R03の要求を満たせなくなっていた。(2)警告の保存に失敗すると、次回起動時は本体が正常なので自動復帰が再発せず、未確認の警告が黙って消えてFR-20に反していた。また、世代に警告を含めると古い世代への復帰で確認済みの警告が復活し、含めなければ失われるという未定義があった | (2)警告を登録情報と同じファイルに保存する案（#6516の記述。世代との関係が破綻するため置き換えた）。置き換えた記述: §3.1.1「登録情報と同じファイルに保存する」「警告をファイルへ書き込めない場合も、メモリ上の警告は状態取得に含める」、§11「残る未決」列 | #6518 |
| 2026-09-24 | CODEX最終横断レビュー（#6528）のうち、Issue #14の範囲の4件を反映した。(#1)本体と世代が保存場所ごと失われた場合は初回導入と区別できないことを、既知の制約として明記した（§3.1.1）。(#3)通信路の暗号化の方針を取り下げ、本書では暗号化を行わず、信頼できないネットワークを通すことになった時点で検討することにした（§7.6、§9.2、§9.4、§11、§12.2、§13）。(#4)ダッシュボードで最終確認時刻を示せるのは同じBrainプロセスが動いている間に限ると明記し、再起動をまたいで追えるよう、観測の出来事をBrainのログに出すことにした（§3.2、§11、§12.2）。(#8)ユースケース文書§10を実施状況に改めた。範囲外の5件（会話プロトコル・セッションブリッジ）は反映しない | (#1)発生するのは保存場所ごと消した場合等に限られ、本人が知っており、ダッシュボードでも気づける。検出の仕組みはかえって利用者を混乱させる（運用者の判断）。(#3)WindowsとWSL2を別の実行ホストとして扱うため、従来の方針では同じPCの中の通信にまで暗号化が必要になり過剰。想定する運用は同じPCの中と信頼するLANの中（運用者の判断）。(#4)要約の永続化は破損時の扱いを増やす。ログなら既存の経路で再起動をまたいで追える（運用者の判断） | (#1)初期化済みマーカーで初回導入と区別する案。(#3)別の実行ホストからの接続は暗号化を前提とする方針（2026-09-22、#6490。置き換えた）。(#4)最終観測の要約を永続化する案。制約の明記だけにする案 | #6528、#6529 |
| 2026-09-24 | 本書（baafedf時点）の設計に、運用者が合意した | CODEXレビュー（#6517、#6528）への対応を終え、設計で決める事項（§12.1）がすべて決着したため | （なし） | #6536 |
| 2026-09-25 | Brainの停止シーケンス（§7.7）を追加した。Brainは停止処理中に入ると新しい会話要求を理由を示して断り、heartbeatの応答で観測中のUIに停止を伝える。UIの対応はUI層ごとに決め、BrainはUIごとの応答待ち時間（UIが任意で申告、デフォルト1秒、Brainが上限で丸める）まで待つ。§4.2の正常終了の契約、§8.1のBrain自身の状態、§11のUC-B03、§12.2に反映した | 運用者の判断（#15の方式検討）。Brainの停止をUIが知らないまま会話が失敗するのではなく、UIが停止に合わせて利用者への案内等を行えるようにする | 処理中の要求の完了を上限まで待つだけで、UIには何も伝えない案（C1）。完了まで数分待つ案（C2） | #15 #issuecomment-6615 |
| 2026-09-26 | ダッシュボードをBrainから切り離し、Brainと同じ実行ホストで動く別のプロセスにした（§4.4）。ダッシュボードのプロセス操作は、実行環境を通したBrainの起動・停止と、UIへの終了の要求に限る。UIへの終了の要求は、Brainを経由してheartbeatの応答で伝え、プロトコル版を上げる（§7.8）。UIは、UIごとに自分の実行ホストで起動・停止の手段を持つ。管理トークンで認可する操作に、Brainの起動・停止と終了の要求を加えた（§9）。FR-21〜FR-23を追加した | Brainの中のダッシュボードでは、Brainが止まっているときに使えず、Brainを起動する操作も置けない。起動・停止の手段は、プロセスが常駐する実行ホストに置く（運用者の方針）。UIは別の実行ホストにあり得るため、ダッシュボードからは起動せず、終了を求めるだけにする。UIへ能動的に送る経路は持たない（§7.7と同じ） | ダッシュボードはプロセス操作をしない（2026-09-21の原則5。本行で置き換えた）。Brain内のダッシュボード（§3.1、§4.3、FR-03、FR-14、NFR-03、§13の記述。本行で置き換えた）。ダッシュボードからUIを起動する案、Windows側に常駐の起動役を置く案（運用者の方針により不採用）。Brainの再起動の操作（運用者の判断で設けない） | #6659、#6674、#6675、#6677 |
| 2026-09-26 | CODEXレビュー（#6679）の3件をすべて反映した。(1)認可の境目を2つに分けた。ダッシュボード自身が閲覧・管理トークンで利用者の要求を認可し、確かめた後に限り、決められたBrainのサービスだけを実行環境に起動・停止させる。Brainは状態取得・書き込み契約を自ら認可する（§4.4、§9.3）。(2)Brainが動いているかは実行環境を正とし、Brainの状態取得は到達できる間だけ詳細を補う。Brainに到達できない間は、登録一覧とUIの状態を「取得できない」と表示し、古い内容を今の状態として見せない。到達できない間と停止処理中は、終了の要求を受け付けず、溜めない（§4.4、§7.8）。(3)置き換え漏れ（FR-14、§11のUC-B01、ユースケース文書§9の2・3）を直した。補足の指摘（終了の要求のエラーの契約、起動・停止の連打）は§12.2へ送った | (1)Brainの起動はBrainが止まっていても行うため、Brainに認可を任せられない。任意のサービス名・コマンドを受け取ると、ダッシュボードが何でも起動できてしまう。(2)ダッシュボードは状態を持たないため、Brainに届かないときの見せ方を決めないと、古い状態を今の状態として表示してしまう | 本改訂の草案の§9.3「ダッシュボードは同じ権限の範囲でBrainを使う」だけの記述（本行で具体化した） | #6679 |
| 2026-09-26 | §3.1.1の「最新の世代は常に本体と同じ内容になる」を、世代の作成だけに失敗した場合の縮退（本体を正として続け、状態取得で警告し、次の書き込みで再試行する）を許す表現に改めた | 世代は本体の写しであり、本体が正である。ログだけでは運用者が気づけない。二重の障害で直近の変更を失う危険は、復帰警告と観測一覧からの再登録で補える（運用者の判断） | 「最新の世代は常に本体と同じ内容になる」（本行で置き換えた）。pendingの世代とrevision_idによる小さなトランザクション（この規模には過剰） |
#24 #6701、#6703 |
| 2026-10-05 | ダッシュボードに、Brainが使うOllamaのモデルの表示と、管理トークンでモデルをGPUから下ろす操作を加えた（§1.3、FR-24、NFR-03、§4.4、§9.3、§11）。プロセスを止めない操作として、原則5の範囲に明示して加えた。§12.2の、ダッシュボードの実現方式とBrainの起動・停止を続けて押した場合の扱いは、詳細設計（runtime-management-detail-dashboard.md）で決めたと注記した |
OLLAMA_KEEP_ALIVE=24hのため、モデルが最後の質問から24時間GPUに残る。WSLを止めずにGPUを空ける手段を、画面から使えるようにする（運用者の判断） |
必要なときに手でcurlを送る案。OLLAMA_KEEP_ALIVEを短くする案。別のIssueに分ける案 |
#17 #6942 |