docs: refine pod visibility and tui restore flow

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)

tickets/pod-discovery-restore-tools.md

@@ -6,12 +6,20 @@ Pod state の永続化と `--pod <name>` 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 <name>` 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 <name>` resume が入ったことで、名前
 
 ## 範囲外
 
-- 過去 Pod 一覧の本格 UI / picker
+- 過去 Pod 一覧の本格 UI / picker（TUI 側の Pod picker は `tickets/tui-pod-restore-picker.md` で扱う）
 - fork tree の可視化
 - transcript 全文検索 / semantic search
 - Pod の自動再起動

tickets/tui-pod-restore-picker.md

@@ -0,0 +1,73 @@
+# TUI: Session 直接 resume を廃止し Pod 単位の attach / restore に寄せる
+
+## 背景
+
+Pod state 永続化と `--pod <name>` resume が入ったことで、TUI が `SessionId` / `SegmentId` を直接選んで復元する必要は薄くなった。現行の `tui -r` は session picker を開き、選択した `SegmentId` から `pod --session <UUID>` 相当の resume を行うが、これは Pod 単位の運用とズレる。
+
+今後の TUI は、通常操作では Session を直接触らず、Pod 名 / Pod state を入口にする。
+
+## 方針
+
+- `tui <podname>` を 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 <UUID>` は互換用に残すか、非推奨扱いにする。
+  - 少なくとも TUI の通常導線からは外す。
+  - 完全削除する場合は別途明示判断する。
+
+## Pod picker の表示要件
+
+各 row には最低限以下を表示する。
+
+- Pod name
+- live / stopped / corrupt などの状態
+- 最終アクティブ時刻
+- active `SessionId` / `SegmentId` の短縮表示（debug 用。主表示は Pod 名）
+- preview text（取得できる場合のみ）
+
+最終アクティブ時刻は、Pod state に持つか、active segment log の最新 timestamp から算出する。実装時に既存 metadata との整合を確認して決める。
+
+## 要件
+
+- `tui <podname>` が以下を満たす。
+  - live socket reachable なら attach。
+  - socket が無い / 到達不能で Pod state があるなら `pod --pod <name>` 経路で restore。
+  - Pod state が無ければ同名の新規 Pod を spawn。
+- `tui -r` が Pod picker を表示し、選択した Pod に attach / restore できる。
+- `tui -r` は Session 一覧ではなく Pod 一覧を表示する。
+- `tui` 引数なしは新規 Pod 名入力 dialog のままにする。
+- TUI の通常導線では Session / Segment を直接選ばせない。
+- 既存 `--pod <name>` / `--session <UUID>` の CLI 互換を壊さない。
+
+## 完了条件
+
+- live Pod を `tui <podname>` で attach できる。
+- stopped Pod state を `tui <podname>` で restore できる。
+- unknown Pod name を `tui <podname>` で新規作成できる。
+- `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