From a4f03e7688d6679c1c9a55a85b68dc26eb1b8b81 Mon Sep 17 00:00:00 2001 From: Hare Date: Sat, 23 May 2026 08:33:00 +0900 Subject: [PATCH] docs: refine pod visibility and tui restore flow --- TODO.md | 1 + tickets/pod-discovery-restore-tools.md | 19 +++++-- tickets/tui-pod-restore-picker.md | 73 ++++++++++++++++++++++++++ 3 files changed, 88 insertions(+), 5 deletions(-) create mode 100644 tickets/tui-pod-restore-picker.md diff --git a/TODO.md b/TODO.md index 3c7fc966..b3007e6d 100644 --- a/TODO.md +++ b/TODO.md @@ -16,6 +16,7 @@ - E2E テストハーネス（`tests/e2e/`、opt-in） → [tickets/e2e-harness.md](tickets/e2e-harness.md) - TUI 拡充 - TUI から任意タイミングで Compact を発火する system command → [tickets/tui-system-command-compact.md](tickets/tui-system-command-compact.md) + - Session 直接 resume を廃止し Pod 単位の attach / restore に寄せる → [tickets/tui-pod-restore-picker.md](tickets/tui-pod-restore-picker.md) - user manifest env override 時の spawn scope overlay 前提ズレ → [tickets/tui-user-manifest-env-overlay.md](tickets/tui-user-manifest-env-overlay.md) - Run 中の入力キューイング → [tickets/tui-input-queue.md](tickets/tui-input-queue.md) - ユーザーマニフェストのモデル設定 wizard → [tickets/tui-user-model-setup.md](tickets/tui-user-model-setup.md) diff --git a/tickets/pod-discovery-restore-tools.md b/tickets/pod-discovery-restore-tools.md index 92c5d077..de09b9dc 100644 --- a/tickets/pod-discovery-restore-tools.md +++ b/tickets/pod-discovery-restore-tools.md @@ -6,12 +6,20 @@ Pod state の永続化と `--pod ` resume が入ったことで、名前 現在の `ListPods` は主に spawner が知っている spawned child の live/runtime registry を見るためのツールであり、永続化された全 Pod の探索や、過去 Pod の restore 導線としては不十分。今後 Pod 単位で作業を再開する運用を成立させるには、Pod state を正本として過去 Pod を列挙・確認・復元できる tool surface が必要。 +ただし、ホスト上の全 Pod state がどの Pod / LLM からも見える設計にはしない。Pod 管理 tool は capability / visibility scope を持ち、呼び出し元が見る権限を持つ Pod だけを列挙・操作できる必要がある。 + ## 要件 -- 永続化された Pod state から、既知の Pod 一覧を取得する tool / protocol API を追加する。 +- 永続化された Pod state から、可視性 scope 内の既知 Pod 一覧を取得する tool / protocol API を追加する。 - 実際の Method / tool 名は実装時に確定する。 - `session-store` の Pod state backend/FsStore を正本にし、runtime dir の `spawned_pods.json` を正本にしない。 - state が壊れている Pod や active segment 未確定の Pod は、全体失敗ではなく item 単位の状態として返せるようにする。 + - 呼び出し元に可視性がない Pod は列挙結果に含めない。 +- Pod 可視性の制御を設計する。 + - 少なくとも「現在の parent が spawn した child」と「明示的に指定された Pod 名」は扱えるようにする。 + - ホスト上の全 Pod を無条件に返す admin/global tool にはしない。 + - visibility の根拠は Pod state / parent-child registry / manifest capability / explicit user selection のいずれかに寄せ、実装時に確定する。 + - 可視でない Pod に対する detail / restore / attach は not visible / forbidden として、state missing とは区別する。 - 一覧 item には最低限以下を含める。 - `pod_name` - active `SessionId` / `SegmentId`（未確定ならその状態） @@ -36,13 +44,14 @@ Pod state の永続化と `--pod ` resume が入ったことで、名前 ## 完了条件 -- 永続化済み Pod を Pod state から列挙できる。 -- runtime dir の `spawned_pods.json` が存在しない状態でも、Pod state から過去 Pod を探索できる。 +- 永続化済み Pod のうち、呼び出し元の可視性 scope 内にあるものだけを Pod state から列挙できる。 +- runtime dir の `spawned_pods.json` が存在しない状態でも、Pod state から可視 Pod を探索できる。 - Pod 名指定で詳細を取得し、live attach 可能 / restore 可能 / state 不在 / state 破損 / lock 衝突を区別できる。 - Pod 名指定の restore / attach tool が、到達可能 live Pod には attach し、到達不能だが state がある Pod には既存 restore 経路で復元できる。 - 既存の `ListPods` / `SendToPod` / `StopPod` / `--pod` / `--session` の挙動を壊さない。 - unit / integration test で以下を確認する。 - - 複数 Pod metadata の列挙 + - 複数 Pod metadata の列挙（可視 Pod のみ） + - 可視でない Pod が列挙されず、detail / restore / attach でも state missing と区別されること - active segment 未確定 Pod の表示 - runtime file が消えても Pod state から探索できる - socket 到達可否の反映 @@ -54,7 +63,7 @@ Pod state の永続化と `--pod ` resume が入ったことで、名前 ## 範囲外 -- 過去 Pod 一覧の本格 UI / picker +- 過去 Pod 一覧の本格 UI / picker（TUI 側の Pod picker は `tickets/tui-pod-restore-picker.md` で扱う） - fork tree の可視化 - transcript 全文検索 / semantic search - Pod の自動再起動 diff --git a/tickets/tui-pod-restore-picker.md b/tickets/tui-pod-restore-picker.md new file mode 100644 index 00000000..e70e6bb8 --- /dev/null +++ b/tickets/tui-pod-restore-picker.md @@ -0,0 +1,73 @@ +# TUI: Session 直接 resume を廃止し Pod 単位の attach / restore に寄せる + +## 背景 + +Pod state 永続化と `--pod ` resume が入ったことで、TUI が `SessionId` / `SegmentId` を直接選んで復元する必要は薄くなった。現行の `tui -r` は session picker を開き、選択した `SegmentId` から `pod --session ` 相当の resume を行うが、これは Pod 単位の運用とズレる。 + +今後の TUI は、通常操作では Session を直接触らず、Pod 名 / Pod state を入口にする。 + +## 方針 + +- `tui ` を Pod 名指定の主導線にする。 + - 既に同名 Pod が live なら attach する。 + - live でなければ、Pod state があれば restore する。 + - Pod state がなければ、新規 Pod として作成する。 +- `tui -r` / `tui --resume` は Session picker ではなく Pod picker にする。 + - 稼働中 Pod と停止済み Pod state を一覧表示する。 + - live Pod は attach、停止済み Pod は restore する。 + - 最終アクティブ時刻の降順で sort する。 +- `tui` 引数なしの場合のみ、現行の「Pod 名を入力して新規 spawn」導線を残す。 + - 既存 name dialog は新規作成用として維持する。 +- `--session ` は互換用に残すか、非推奨扱いにする。 + - 少なくとも TUI の通常導線からは外す。 + - 完全削除する場合は別途明示判断する。 + +## Pod picker の表示要件 + +各 row には最低限以下を表示する。 + +- Pod name +- live / stopped / corrupt などの状態 +- 最終アクティブ時刻 +- active `SessionId` / `SegmentId` の短縮表示（debug 用。主表示は Pod 名） +- preview text（取得できる場合のみ） + +最終アクティブ時刻は、Pod state に持つか、active segment log の最新 timestamp から算出する。実装時に既存 metadata との整合を確認して決める。 + +## 要件 + +- `tui ` が以下を満たす。 + - live socket reachable なら attach。 + - socket が無い / 到達不能で Pod state があるなら `pod --pod ` 経路で restore。 + - Pod state が無ければ同名の新規 Pod を spawn。 +- `tui -r` が Pod picker を表示し、選択した Pod に attach / restore できる。 +- `tui -r` は Session 一覧ではなく Pod 一覧を表示する。 +- `tui` 引数なしは新規 Pod 名入力 dialog のままにする。 +- TUI の通常導線では Session / Segment を直接選ばせない。 +- 既存 `--pod ` / `--session ` の CLI 互換を壊さない。 + +## 完了条件 + +- live Pod を `tui ` で attach できる。 +- stopped Pod state を `tui ` で restore できる。 +- unknown Pod name を `tui ` で新規作成できる。 +- `tui -r` で live / stopped Pod が最終アクティブ時刻順に出る。 +- `tui -r` で選択した live Pod に attach できる。 +- `tui -r` で選択した stopped Pod を restore できる。 +- TUI の picker / spawn tests を更新する。 +- `cargo fmt --check` +- `cargo check --workspace` +- `cargo test -p tui -p pod -p session-store` + +## 範囲外 + +- LLM tool としての任意 Pod 管理 API。 +- Pod state の可視性 / capability 制御。 +- fork tree 可視化。 +- session / segment 単位の新しい TUI UX。 +- transcript 全文検索。 + +## 関連 + +- `tickets/pod-discovery-restore-tools.md` +- Pod state backend / lifecycle write-through / Pod 名 resume