ステータス: 合意済み（2026-09-24、Issue #22、工程3: 実装範囲の決定）
改訂: 2026-09-26 Issue #25（ダッシュボードの切り離し、Brainの起動・停止、UIへの終了の要求）の設計改訂に合わせて、§2.2、§3、§4、§5を改めた（運用者が合意。#6682）
改訂: 2026-10-05 ダッシュボードの詳細設計（#17）の合意に合わせて、§4にUC-D08を加え、§5.1の#17・#21を改めた（運用者が合意。#17 #6942）
更新するときは、設計文書の更新ルールに従うこと。
本書は、ランタイム管理 設計（合意済み）のうち、どのユースケースをどこまで実装・実機検証するか、どの順で着手するかを決める。設計書とユースケース文書は全ユースケースを対象にしており、本書で範囲を決めても書き換えない（Issue #13の工程方針）。
| 工程 | 成果物 |
|---|---|
| 1. ユースケース | runtime-management-use-cases.md（合意済み） |
| 2. 設計 | runtime-management-design.md（合意済み） |
| 3. 実装範囲の決定 | 本書 |
| 4. 詳細設計 | runtime-management-detail-<領域>.md |
| 5. 実装 | コード、テスト、runtime-management-runbook.md |
実機検証に使える環境は、PC 1台（Windows＋WSL2）である。
設計では、WindowsとWSL2を別の実行ホストとして扱う（設計書§5.1）。したがって、日常の構成（WSL2上のBrain、Windows上の常駐音声UI、Windowsのブラウザで開くダッシュボード）は、1台のPCの中で「別の実行ホストからの接続・閲覧」になる。通信はPCの外に出ない（設計書§9.2）。
| 段階 | 内容 | 着手の条件 |
|---|---|---|
| 段階1 | PC 1台（Windows＋WSL2）でできることを、すべて実装・実機検証する | 本書の合意後 |
| 段階2 | 別のPCが必要な部分（LAN越しの接続・閲覧、別のPCでのUI起動） | 段階1の完了後、かつ別のPCを用意できた時点 |
段階2に回すのは、別のPCが無いと実機検証できない部分だけである。設計上、別のPCに依存しない部分（ホストに依存しない状態判定、閲覧トークンによる認可等）は段階1で実装する。ダッシュボードをLANから開ける形（待ち受けのアドレス、Windowsファイアウォールの規則）も段階1で作る。LAN上の端末からの確認は、同じLANにつながったスマートフォン等で段階1でも行える（2026-09-26、#25）
#13の「実装範囲の暫定案」は設計前に作ったものであり、次のとおり改める。
| #13の暫定案 | 本書 | 理由 |
|---|---|---|
| loopback通信に限定し、別の実行ホストからの管理画面閲覧・Brain接続は実装しない | Windows→WSL2の接続・閲覧は段階1で実装する。LAN越しの接続・閲覧は段階2 | WindowsとWSL2は設計上別の実行ホストであり、日常の構成がすでに「別ホストからの接続・閲覧」にあたる（2.1） |
| 期待構成の宣言と観測状態の比較 | 運用者が管理画面から登録する常駐監視対象（UC-D06）を実装する | 設計で置き換わった（設計書§3.1） |
| 読み取り専用ダッシュボード（書き込み系を設けない） | 閲覧に加え、常駐監視対象の登録・変更・解除と、復帰警告の確認操作（管理トークンで認可）を実装する | 設計で変わった（設計書§8.4、§9） |
| （なし） | 登録情報の永続化・世代・起動時の自動復帰（UC-D07）を実装する | 設計で追加された（設計書§3.1.1） |
| 着手順 #15 → #16 → #19 → #21 → #17 | 可視化を先にする（§3） | 運用者の判断 |
可視化（「今、何が、どこで、どの版で動いているか」が分かること）を先に整え、その上で起動数の強制と自動起動を整える。
| 順 | 担当Issue | 内容 | 主なユースケース |
|---|---|---|---|
| 1 | #15 | Brainの単一起動と正常終了（2026-09-26完了） | UC-B02、UC-B03（Brain側の土台） |
| 2 | #16 | 管理heartbeatの受信、状態判定、状態取得API、閲覧トークン。停止の通知と応答の受信。検証用のテストUI（2026-09-26完了） | UC-B03（停止の通知と応答）、UC-B04、UC-R02〜R07、UC-M01、UC-M03、UC-D01（API）、UC-D03、UC-D04 |
| 3 | #23 | Windows常駐音声UIのheartbeatクライアント、停止への対応と応答（AiChatリポジトリ。版1は実装・実機確認済み）。管理プロトコル版2（終了の要求）への対応 | UC-R02〜R05、UC-B03、UC-R08（UI側） |
| 4 | #24 | 管理トークン。Brainの書き込み契約（常駐監視対象の登録・解除、復帰警告の確認、UIへの終了の要求）。登録情報の永続化・世代・自動復帰。管理プロトコル版2（heartbeatの応答で終了を求める） | UC-D06、UC-D07、UC-D02、UC-R08（Brain側） |
| 5 | #17 | Brainとは別のWebサーバーとしてのダッシュボード（WSL側）。状態の表示、Brainの起動・停止、UIへの終了の要求、登録・解除、復帰警告の確認。LANから開ける形。ダッシュボード自身の認可 | UC-D01、UC-D02、UC-D05、UC-D06、UC-D07、UC-B05、UC-R08 |
| 6 | #19 | UIのローカル排他（AiChatリポジトリ）。音声UI自身の起動・停止のUI | UC-M02、UC-R09 |
| 7 | #21 | Windowsログイン後の自動起動（SearXNG→Ollama→Brain、ダッシュボード、音声UI）と、失敗時の確認・回復手順 | UC-B01、UC-R01 |
| 段階2 | 新Issue C（段階2の着手時に起票） | LAN越しの接続・閲覧、別のPCでのUI起動の実機検証 | UC-D05、UC-M03（別のPC） |
実現したい順（§3の着手順）に並べる。「実機検証」は、PC 1台（Windows＋WSL2）で行う段階1の範囲を示す。「単体テスト」は、実機では再現しにくいため単体テストで確認する範囲を示す。
| ユースケース | 担当Issue | 実装範囲（段階1） | 実機検証（段階1） | 単体テストで確認／段階2 |
|---|---|---|---|---|
| UC-B02 Brainの二重起動の拒否 | #15 | 全体 | WSL2でBrainを2個起動し、2個目が理由を示して終了する | — |
| UC-B03 Brainの正常終了 | #15、#16、#23 | 全体。#15はBrain側の土台（停止処理中の状態、新しい会話要求の拒否、処理中の要求の完了待ちと打ち切り、資源の解放）。#16・#23は観測中のUIへの停止の通知と応答（設計書§7.7）。#23の完了で全体を満たす | #15: 処理中の要求がある状態で、正式な手順で停止する。#23: 音声UIを動かしたままBrainを停止し、音声UIが停止を知って応答し、Brainが終了する | 打ち切りの判断基準（#15）。UIが応答しない場合の待ち時間の上限（#16） |
| UC-B05 ダッシュボードからのBrainの起動・停止 | #17 | 全体 | ダッシュボードでBrainを停止し、停止中と分かる。起動し、稼働中に戻る。Brainの起動に失敗させ、起動失敗と分かる。閲覧トークンでは起動・停止できない | 起動・停止の連打、起動中・停止処理中の操作 |
| UC-B04 生存と利用可能性の区別 | #16 | 状態取得APIにliveness・readinessを含める（/health/*は既存のまま） |
Ollamaを止めると、Brainは動いているが会話には使えないと分かる。Ollamaを戻すと、使える状態に戻る | SearXNG等、他の依存先の不調 |
| UC-R02 会話していない間のUIの稼働 | #16、#23 | 全体 | 待機中の音声UIが、ホスト・起動時刻・commitとともに見える | — |
| UC-R03 終了通知が届かないUIの途絶 | #16、#23 | 全体（観測の出来事のログを含む） | 音声UIを強制終了し、応答なし→未稼働と遷移する。正常終了では直ちに未稼働 | ブラウザのタブ（該当するUIが無い） |
| UC-R04 UI再起動時の新旧の区別 | #16、#23 | 全体 | 音声UIを再起動し、別のプロセスとして扱われる | — |
| UC-R05 Brain再起動後のUIの再認識 | #16、#23 | 全体 | 音声UIを動かしたままBrainを再起動し、不明→稼働中へ戻る | — |
| UC-R06 稼働状態を伝えるUIと伝えないUIの混在 | #16 | 全体 | heartbeatを送らないスクリプトで/askを呼び、会話の集計にだけ現れる |
— |
| UC-R07 常駐が期待されないUI | #16、#24 | 全体 | テストUIを起動・終了・強制終了し、一覧に現れて消える | — |
| UC-R08 ダッシュボードからUIへの終了の要求 | #24（Brain側）、#17（画面）、#23（UI側） | 全体 | ダッシュボードから音声UIに終了を求め、音声UIが正常に終了して一覧に反映される。版1のテストUIに求め、稼働中のまま要求中と分かる。Brainを止めた状態では要求が失敗し、理由が分かる | 未知・破棄済みのプロセスへの要求、同じ要求の再送 |
| UC-R09 UIを自分の実行ホストで起動・停止する | #19 | 音声UI | Windowsで、音声UIの起動・停止のUIから起動・停止し、停止は正常終了（一覧から直ちに消える）になる。二重起動は拒否される | — |
| UC-M01 多重起動可のUI | #16 | Brain側の判定・表示 | テストUIをmultiで複数起動する |
— |
| UC-M03 実行ホストごとに1つのUIを別ホストで起動 | #16 | Brain側の判定・表示 | テストUIをhost:1でWindowsとWSL2に1つずつ起動し、重複と判定されない |
段階2: 別のPCで起動する |
| UC-D01 ダッシュボードでの状態確認 | #16（API）、#17（画面） | 全体 | Windowsのブラウザで一画面に表示され、会話内容・トークンが出ない | — |
| UC-D03 更新後の切替と古いプロセスの残存 | #16、#17 | 全体（Brain自身の起動時刻・commitを含む） | 音声UI・Brainを更新して再起動し、起動時刻とcommitで切替を判別する。テストUIで、同じ監視対象キーの旧プロセス（旧commit）を残したまま新プロセスを起動し、両方が区別して表示され、古いプロセスの残存に気づける（cutover時に実際に起きた事故の再現） | — |
| UC-D04 会話の利用状況 | #16 | 全体 | セッション数・処理中件数だけが見える | — |
| UC-D06 常駐監視対象の管理 | #24（API）、#17（画面） | 全体。登録の変更は、設計どおり解除と登録で行う（登録内容は監視対象キーだけのため、変更専用の操作は設けない） | 観測一覧から音声UIを登録・解除する。変更として、テストUIのtarget_idを変えて起動し直し、旧キーの未稼働と新キーの未登録のUIが見えるところから、旧キーを解除し新キーを登録する。閲覧トークンでの登録・解除が拒否される。重複登録が理由とともに拒否される |
— |
| UC-D07 登録情報の破損・消失からの復帰 | #24、#17 | 全体 | ユースケース文書4.5のシナリオ1: 登録情報ファイルを壊して／消してBrainを再起動すると、自動で戻り、音声UIと会話は何もせずに使え続ける。警告はBrainを再起動しても残り、確認済みにすると消える | シナリオ2（最新の世代も壊れていて、より古い世代へ戻る）、シナリオ3（戻せる世代が無く、登録0件で起動して警告を出す）、警告ファイル自体の破損、書き込み失敗時の拒否 |
| UC-D08 OllamaのモデルをGPUから下ろす | #17 | 全体 | ダッシュボードで、GPUに載っているモデルと自動で下りる予定の時刻が見える。下ろすと区画から消え、VRAMの使用量が減る。次の質問は読み込み直して答える。閲覧トークンでは下ろせない | 回答の途中で下ろしても回答が最後まで返ること（2026-10-05にOllamaで確認済み）。Ollamaに到達できない場合 |
| UC-D02 登録済みUIが確認できない場合の表示 | #24、#17 | 全体 | 登録済みの音声UIを止め、一覧から消えずに未稼働と表示される。Brainを止めると、ダッシュボードでBrainの停止と、登録一覧・UIの状態が「取得できない」ことが分かる | — |
| UC-D05 別ホストからのダッシュボード閲覧 | #16（閲覧トークン）、#17 | Windows→WSL2の閲覧、LANから開ける形 | Windowsのブラウザと、同じLANのスマートフォン等で、閲覧トークンを持つ場合だけ見られる | 段階2: LAN上の別のPCから閲覧する |
| UC-M02 実行ホストごとに1つのUIの二重起動拒否 | #19（拒否）、#16（検出） | 全体 | Brainを止めた状態で音声UIを2個起動し、2個目が拒否される。異常終了後は再起動できる | — |
| UC-B01 Brainの自動起動と失敗時の回復 | #21 | Windowsログイン後の自動起動、runbookの回復手順 | Windowsを再起動し、Brainが使える。起動を意図的に失敗させ、実行環境の管理手段で失敗と原因を確認し、runbookの手順どおりに回復して使えるようになる | — |
| UC-R01 常駐UIの自動起動と失敗時の回復 | #21 | Windowsログイン後の自動起動、runbookの回復手順 | Windowsを再起動し、音声UIが使える。起動を意図的に失敗させ、ダッシュボードで未稼働と分かり、runbookの手順どおりに回復して稼働中に戻る | — |
| Issue | リポジトリ | 範囲 | 詳細設計の成果物 |
|---|---|---|---|
| #15 | AiChatWls | Brainの単一起動、正常終了（lifespan、セッション掃除スレッドの停止、処理中要求の扱い）、停止処理中の状態と新しい会話要求の拒否（設計書§7.7）、正式な起動・停止手順 | runtime-management-detail-brain-lifecycle.md |
| #16 | AiChatWls | 管理heartbeat・終了通知の受信（会話用トークンで認証）、状態の6軸の導出と表示上の状態、状態取得API（閲覧トークン）、Brain自身の起動時刻・commit、観測の出来事のログ、停止シーケンスの通知と応答の受信（Brain側。設計書§7.7。UIの応答待ちの上限を決めたら、BrainのunitのTimeoutStopSecを見直す）、検証用テストUI（スクリプト。WindowsとWSL2の両方で動き、それぞれのhost_idを取得する）、ui-brain-protocol.mdへの参照の追記 |
runtime-management-detail-observation.md（合意済み） |
| #23 | AiChat | Windows常駐音声UIのheartbeat・終了通知の送信、host_id（Windows）の取得、停止シーケンスへの対応と応答（UI側。設計書§7.7）。管理プロトコル版2で終了を求められたら正常に終了する（設計書§7.8） |
（#16・#24の契約に従う。必要ならAiChat側に置く） |
| #24 | AiChatWls | 常駐監視対象の登録・解除API（変更は解除と登録で行う）、管理トークン、登録情報ファイル・世代・警告ファイル、起動時の自動復帰、復帰警告の確認操作。UIへの終了の要求の書き込み契約と、管理プロトコル版2（heartbeatの応答で終了を求める。設計書§7.8）。登録APIは、観測一覧に現れたUIを選ぶ登録方法だけを提供する（設計書§3.1）。具体的な要求形式、観測済みであることの確認方法、拒否理由の表現は詳細設計で決める。runbook: バックアップの別保管 | runtime-management-detail-registration.md |
| #17 | AiChatWls | Brainとは別のWebサーバーとしてのダッシュボード（WSL側。systemd --user）。状態取得APIと実行環境からのBrainの状態の表示、Brainの起動・停止（決められたサービスだけ）、UIへの終了の要求、観測一覧からの登録と解除、復帰警告の確認。ダッシュボード自身の認可（閲覧・管理トークン）とBrainへのトークンの受け渡し。LANから開ける形（待ち受けのアドレス、Windowsファイアウォールの規則の手順）。Windowsのデスクトップのアイコン（ダッシュボード自身の起動・停止）。Brainが使うOllamaのモデルの表示と、GPUから下ろす操作（UC-D08）。runbook: 常駐の前提（.wslconfigのinstanceIdleTimeout=-1、loginctl enable-linger）、新規導入UIを一覧で確認してから登録する手順、ダッシュボードの起動・停止 |
runtime-management-detail-dashboard.md（合意済み） |
| #19 | AiChat | Windows常駐音声UIのローカル排他（Brainに依存しない）、拒否時の表示とログ。音声UI自身の起動・停止のUI（停止は正常終了。設計書§4.1、UC-R09） | runtime-management-detail-ui-exclusion.md |
| #21 | AiChatWls（WSL2側）、AiChat（Windows側） | Windowsログイン後のWSL2・SearXNG・Ollama・Brain・ダッシュボード・音声UIの自動起動、起動順序と準備待ち。runbook: 更新・自動起動・回復を通した手順（回復手順、更新時の旧プロセスの終了手順）。Brainの正式な停止方法は#15、UIの排他と終了の条件は#19が提供し、#21がそれらを使った手順としてまとめる。常駐の前提（.wslconfigのinstanceIdleTimeout=-1、loginctl enable-linger）は#17のrunbookの手順を使う |
runtime-management-detail-autostart.md |
#15 ─────────────────────────────────────────────────┐
#16 ──┬─→ #23（版1: 済み） │
└─→ #24（書き込み契約・終了の要求・版2）─┬─→ #17（ダッシュボード）──┼─→ #21
└─→ #23（版2への対応）─────┤
#19（ローカル排他・音声UIの起動・停止のUI）─────────────────────────────┘
#16 blocks #19は、heartbeatクライアントを#23へ分けたことで不要になる）必要になった時点で、別のIssueとして扱う。設計上の前提から外れるものではない。
| 項目 | 理由 |
|---|---|
macOSでのhost_idの取得 |
macOS上で動くUI・Brainが無い |
コンテナで動かす場合のhost_idの扱い（/etc/machine-idのbind mount） |
コンテナで動かす構成が無い |
| 新しい種類のUI（テキストUI、ブラウザのUI等） | ユースケースの検証のために新しいUIは作らず、検証用のテストUI（スクリプト）で代える |
| 非対応版のUIでの実機検証 | 版管理を持つ旧版のUIがまだ存在しない。判定は単体テストで確認する |
段階2（§2.2）の項目は「実装しない」ではなく、別のPCを用意できた時点で着手する。
ui-brain-protocol.md）について指摘があった（特に、ロックを保持したままのchat.close()）。#15の正常終了（保持資源の解放）に影響し得るため、#15の詳細設計で確認するui-brain-protocol.mdへの参照の追記: 設計書§10の反映方針のとおり、管理heartbeatは別文書で定義する旨を追記する。確定文書の改訂のため、#16で運用者に確認してから行う| 日付 | 決めたこと | 理由 | 却下・置き換えた案 | 根拠 |
|---|---|---|---|---|
| 2026-09-24 | 同一PC（Windows＋WSL2）でできることをすべて段階1で実装・検証し、別のPCが必要な部分は段階2とする。実機検証の環境はPC 1台 | 運用者の判断。WindowsとWSL2は設計上別の実行ホストであり、別ホストからの接続・閲覧の大部分は1台で実装・検証できる | #13の暫定案（loopbackに限定し、別ホストからの接続・閲覧は実装しない） | #22 #issuecomment-6553 |
| 2026-09-24 | 着手順を、可視化を先にする（#15 → #16 → 新A → 新B → #17 → #19 → #21） | 運用者の判断 | 手作業の排除を先にする案（#15 ∥ #19 → #21 → #16 → 新B → #17）。#13の暫定順（#15 → #16 → #19 → #21 → #17） | #22 #issuecomment-6553 |
| 2026-09-24 | #19を、ローカル排他（#19）とheartbeatクライアント（新A）に分ける。常駐監視対象の登録・永続化・復帰を新Bとして#16から分ける | ローカル排他はBrainに依存せず、heartbeatクライアントは#16の契約に依存するため、依存関係が異なる。登録・永続化・復帰は、状態判定と独立した領域であり、詳細設計を分けられる | 分割しない案、#19だけを分ける案 | #22 #issuecomment-6553 |
| 2026-09-24 | CODEXレビューを反映した。新A→#21の依存を追加。UC-D03に古いプロセスの残存の検証、UC-B01・R01にrunbookどおりの回復の検証を追加。UC-D06の変更は解除と登録で行うと明記し、その流れを検証に追加。UC-D07の実機検証をシナリオ1と警告の扱いに絞り、他の分岐は単体テストとした。新規導入UIの登録手順を新Bから#17へ移した | 運用者の指示により、運用者から見て意味があるかで判断した。変更専用の操作は、登録内容が監視対象キーだけのため運用者に必要な場面が無い。世代の分岐を実機で再現しても、単体テスト以上の確認にならない | 変更専用の画面操作を追加する案、UC-D07の分岐をすべて実機で検証する案 | #22 #issuecomment-6559 |
| 2026-09-24 | CODEX再レビューを反映した。新Bの登録APIは、観測一覧に現れたUIを選ぶ登録方法だけを提供すると明記した（要求形式、観測済みであることの確認方法、拒否理由の表現は詳細設計）。§3・§4の「変更」の表記を「登録・解除」に揃えた | 設計書§3.1で登録方法は確定しており、計画書で未決に戻すと合意済みの設計を開き直すことになる | 前回の記述「一度も観測されていないキーの登録をAPIで拒否するかは詳細設計で決める」（本行で置き換えた） | #22 #issuecomment-6561 |
| 2026-09-24 | 本書に運用者が合意した。合意に合わせ、新Issue Aを#23、新Issue Bを#24として起票し、本文の「新A」「新B」を番号に置き換えた（本節の過去の行は記録として残す） | CODEXの再レビュー（#6561の反映後）で「合意できる」と判定され、運用者が合意した | — | #22 #issuecomment-6562 |
| 2026-09-25 | 設計書に停止シーケンス（§7.7）が加わったことに合わせ、§5.1の範囲を改めた。#15は停止処理中の状態と新しい会話要求の拒否まで、#16は通知と応答の受信（Brain側）、#23は停止への対応と応答（UI側）を担当する | 運用者の判断。heartbeatが未実装のため、#15では土台だけを作り、通知・応答はheartbeatと一緒に実装する | #15で通知・応答まで実装する案（heartbeatが無いため実装できない） | #15 #issuecomment-6615 |
| 2026-09-26 | UC-B03を#15・#16・#23の共同担当とし、#15を「Brain側の土台」、#16・#23を「停止の通知と応答」とした（§3、§4、§5.2）。#16の範囲に、UIの応答待ちの上限を決めたらBrainのTimeoutStopSecを見直すことを加えた |
CODEXレビューで、停止シーケンスを設計に加えた後もUC-B03が#15単独の「全体」のままであり、#15の完了をUC-B03全体の完了と誤って判断できると指摘された。停止にかかる時間の上限は、UIの応答待ちの上限で変わる | 2026-09-25の本節の行で#15単独のままにしていた記述（本行で置き換えた） | #15 #issuecomment-6623 |
| 2026-09-26 | #16の詳細設計の成果物の名前をruntime-management-detail-observation.mdに改めた（§5.1） |
仮の名前registration-apiは、#24のruntime-management-detail-registration.md（登録）と紛らわしく、#16の内容（観測と状態取得）とも合わない。CODEXも賛成した |
runtime-management-detail-registration-api.md（本行で置き換えた） |
#6646 |
| 2026-09-26 | Issue #25の設計改訂に合わせて改めた。#24に、UIへの終了の要求の書き込み契約と管理プロトコル版2を加えた。#17を、Brainとは別のWebサーバーとしてのダッシュボード（Brainの起動・停止、UIへの終了の要求、LANから開ける形を含む）にした。#23に版2への対応、#19に音声UI自身の起動・停止のUI（UC-R09）、#21にダッシュボード・Ollama・SearXNGの起動を加えた。UC-B05・UC-R08・UC-R09を§4に加えた。着手順は#24→#17（#23の版2対応・#19と並行）→#21とした。LANから開ける形は段階1で作る | ダッシュボードが使うBrainの口を先に固めると、#17を作り直さずに済む。段階2は、別のPCが無いと確かめられない部分を分けたもので、作ること自体は段階1でできる（運用者の判断） | 着手順の旧記述（#24→#17→#19→#21、#17はBrain内の画面）。UC-D05のLANからの閲覧をすべて段階2にしていた記述（本行で置き換えた） | #25 #6675、#25 #6682 |
| 2026-10-05 | ダッシュボードの詳細設計（#17）の合意に合わせ、§5.1の#17に、デスクトップのアイコン、常駐の前提の手順、Ollamaのモデルの表示と下ろす操作を加えた。#21に、常駐の前提を#17の手順から使うことを加えた。§4にUC-D08を加えた | 詳細設計で決めた範囲を、実装計画の範囲に揃える（詳細設計§16）。UC-D08は運用者の判断で#17に加えた | UC-D08を別のIssueに分ける案 | #17 #6942 |