chore: E2Eの計画とgit運用の話

AGENTS.md

@@ -22,6 +22,7 @@ LLM に投げる context への割り込みは、大きく2種類に分かれる
 
 Gitはpush以外のすべての操作が許可されている。
 基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
+コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。
 
 外部の参考プロジェクトはghqでgetしており、必要に応じて`~/ghq`からReadすること。
 

TODO.md

@@ -15,6 +15,8 @@
   - ストリーム途中失敗時の継続 → [tickets/llm-worker-stream-continuation.md](tickets/llm-worker-stream-continuation.md)
 - llm-worker: Anthropic projection で assistant ターン内ブロックを 1 message に束ねる → [tickets/anthropic-assistant-burst-bundling.md](tickets/anthropic-assistant-burst-bundling.md)
 - ネイティブ GUI クライアント MVP → [tickets/native-gui-mvp.md](tickets/native-gui-mvp.md)
+- Client crate の切り出し（TUI/GUI/E2E 共通の protocol クライアント） → [tickets/client-crate.md](tickets/client-crate.md)
+- E2E テストハーネス（`tests/e2e/`、opt-in） → [tickets/e2e-harness.md](tickets/e2e-harness.md)
 - TUI 拡充
   - 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/client-crate.md

@@ -0,0 +1,51 @@
+# Client crate の切り出し
+
+## 背景
+
+protocol を喋る socket クライアントは現在 `crates/tui/src/client.rs` に閉じている。今後の二つの方向で、TUI 内に閉じていることが障害になる:
+
+- **GUI MVP** (`tickets/native-gui-mvp.md`): GUI バイナリも同じ protocol を喋る。チケット側の検討事項にも「socket client を別 crate に切り出して共有するか、GUI crate 内に閉じて持つか」が挙げられている (`native-gui-mvp.md:67`)。
+- **E2E ハーネス** (`tickets/e2e-harness.md`): TUI バイナリを PTY で叩くのは脆く、GUI バイナリは MVP 中。E2E から protocol を直接喋る入口として client crate が要る。
+
+TUI 内に置いたまま GUI と E2E から再利用しようとすると、TUI のレンダリング都合と client の責務が混ざる。先に切り出しておく。
+
+## 方針
+
+- `crates/client/` を新設し、socket への接続・`Method` 送信・`Event` 受信・graceful shutdown までの低レベル機能を移す。
+- TUI / GUI / E2E は当 crate を依存先として呼び出す。Pod の subprocess 起動も client crate 側で扱うのが自然か、別 crate / 上位呼び出し側に残すかは設計で詰める（GUI が subprocess を直接 spawn する流儀との整合）。
+- 移行は機能等価で、TUI に regression を起こさないこと。
+
+## 検討事項
+
+- crate 名: `client` で良いか、より具体的な名前にするか（`pod-client` 等。`feedback_crate_naming.md` の方針に従いプレフィックスは付けない）。
+- subprocess spawn 責務: client crate に含めるか、呼び出し側に残すか。GUI MVP では「GUI から直接 pod を spawn」する流儀なので、spawn と connect を分離して両方公開しておくのが妥当そう。
+- 公開 API の境界: 生 socket / `JsonLineReader` までを露出するか、もう一段抽象化したリクエスト/サブスクライブ API にするか。
+- 非同期ランタイム: tokio 前提で良いか（GUI の GPUI executor との統合は GUI 側で吸収する）。
+- error 型: TUI の `client.rs` 内で持っている error をそのまま move するか、再設計するか。
+
+## 要件
+
+- `crates/client/` が新設され、現 `crates/tui/src/client.rs` 相当の機能を提供する。
+- TUI は新 crate に依存して動作し、既存テスト・既存挙動が通る。
+- API は GUI / E2E から呼べる粒度で公開されている（最低限: 接続、`Method` 送信、`Event` ストリーム購読、shutdown）。
+- pod subprocess を spawn する経路をどこに置くかが決まり、必要なら本 crate からも呼べる。
+
+## 完了条件
+
+- 上記要件が満たされる。
+- TUI が新 crate を使って従来通り動く（`cargo test -p tui` / TUI 手動起動で regression 無し）。
+- E2E ハーネス（`tickets/e2e-harness.md`）が本 crate に依存して protocol を喋れる状態になる。
+
+## 範囲外
+
+- GUI バイナリ実装そのもの（`tickets/native-gui-mvp.md`）。
+- protocol の拡張・互換破壊。
+- TUI のリファクタリングを切り出し以上にやること（責務移動だけに留める）。
+- daemon 層の導入。
+
+## 依存 / 関連
+
+- `tickets/native-gui-mvp.md`
+- `tickets/e2e-harness.md`
+- `crates/tui/src/client.rs`
+- `crates/protocol/`

tickets/e2e-harness.md

@@ -0,0 +1,86 @@
+# E2E テストハーネス
+
+## 背景
+
+`CLAUDE.md:6` で明記している通り、現状「実プロセスをスポーンさせての E2E」は未設計である。crate 内 integration test は 121 ファイル / 969 ケースまで揃っているが、以下の領域は in-process では再現できず、複数チケットの完了条件が宙に浮いている。
+
+- `pod-cli-manifest-flags`: `--manifest` / `INSOMNIA_USER_MANIFEST` / 併用 conflict など実 CLI 挙動
+- `pod-persistent-state`: Pod プロセス**再起動後**の active session 復元、spawner 再起動後の `ListPods` 復元
+- `pod-session-fork`: `pod_cli` から fork → 新 session で run まで通せる
+- `pod-parent-turn-callback`: 実子 Pod を spawn した状態の親 history 反映
+- `pod-empty-turn-rollback`: 「TUI / pod_cli いずれの経路でも」明記
+- `permission-extension-point.review.md:21`: `[permissions]` を含む Pod 構築 → tool deny までの結合検証
+- `llm-worker-stream-continuation`: SSE 途中切断 + 継続/中断と課金重複が無いことの確認
+- `native-gui-mvp`: GUI から `pod` subprocess を起動 → socket 接続 → graceful shutdown
+
+`crates/pod/tests/spawn_pod_test.rs` のように subprocess を `/bin/true` ですり替える擬似手法は既にあるが、これは「子 Pod が即終了する状況下での registry 書き込み」を見るためのもので、実 pod を立ち上げての protocol 往復はしていない。
+
+## 方針
+
+- ワークスペース直下 **`tests/e2e/`** に E2E 専用の crate を切る。E2E は単一の crate / バイナリの責務ではないため、既存 `crates/<x>/tests/` には置かない。
+- 実 `pod` バイナリは `env!("CARGO_BIN_EXE_pod")` で取得。ファイルシステムは tmpdir に閉じ、`INSOMNIA_RUNTIME_DIR` / data dir / `INSOMNIA_USER_MANIFEST` 等を env で完全 sandbox 化する。
+- protocol を喋る側は **`tickets/client-crate.md` で切り出す `client` crate** を直接利用する。TUI バイナリを PTY で叩く方針は採らない（GUI MVP との整合と E2E 安定性の観点から）。
+- CI 既定実行から外す。`--features e2e` か独立ジョブで opt-in。ローカルでは `cargo test -p e2e --features e2e` 相当で叩ける形にする。
+
+## 詰めたい論点（実装前に決める）
+
+### 1. LLM provider のスタブ手段が fixture HTTP 再生だけで充足するか
+
+既存 `crates/llm-worker/tests/anthropic_fixtures.rs` 等は in-process loader として書かれており、HTTP サーバーとして再生する形にはなっていない。E2E では Pod プロセスが env で渡された URL に対して実 HTTP を叩く以上、**最低限「fixture を返す HTTP サーバー」** は必要。
+
+ただし、それだけで充足するかは不明:
+
+- **動的応答が要るシナリオ**: SSE を途中で能動的に切る (`llm-worker-stream-continuation`)、tool 呼び出しの結果に応じて分岐する応答、複数ターンに渡る会話の途中で挙動を変える、など。録画再生だけでは作りにくい。
+- **provider 差**: Anthropic / OpenAI Responses / Gemini / Ollama / Codex OAuth で endpoint / 認証 / スキーマが違う。E2E で全 provider を回す必要は無いが、最低 1〜2 provider はハーネスを持たせるべきで、選定が要る。
+- **OAuth 系**: Codex OAuth はトークン取得経路自体が外部依存。E2E では事前注入された token を読む形に倒すか、OAuth flow ごと canned server で模すか。
+
+このチケットでは「fixture HTTP 再生」を出発点としつつ、**動的応答のための最小 canned server インターフェース**（テストケース側からハンドラを差し替えられる形）も同時に検討範囲に含める。両方が無いと上のシナリオが書けない。
+
+### 2. provider URL の差し替え経路
+
+各 provider の base URL を env で上書きできる前提が、現コードに揃っているか確認・整備する必要がある。揃っていなければ別チケットに切り出すか、本チケット内で minimal に対応するか決める。
+
+### 3. fixture 形式
+
+既存の in-process fixture (`tests/*_fixtures.rs`) と HTTP 再生用 fixture を同じソースから作るか、別管理にするか。共通化できるなら record/replay 経路を整備する。
+
+### 4. 並列実行と env 干渉
+
+`spawn_pod_test.rs` は env mutex で直列化している。E2E でも env (`INSOMNIA_*`)・runtime dir・socket path に依存する以上、テスト並列度の方針を決める（`--test-threads=1`、test-per-process、または env を引数にハンドオフして mutex 不要にする）。
+
+### 5. 失敗時の診断
+
+実プロセスが絡むためスタックトレースだけでは原因特定しにくい。pod の stderr / stdout、session log、runtime dir の中身をテスト失敗時に dump する仕組みを最初に入れておく。
+
+## 要件
+
+- `tests/e2e/` 以下に E2E 用 crate（仮称 `e2e`）が存在し、`Cargo.toml` の `[features] e2e = []` で gate されている。
+- `cargo test -p e2e --features e2e` で実 `pod` バイナリを spawn し、protocol 経由で 1 シナリオ（最小: spawn → 1 turn 実行 → graceful shutdown）が通る。
+- LLM provider のスタブが少なくとも 1 provider 分動き、上の最小シナリオが本物の HTTP 越しに完結する。
+- env / tmpdir / socket path が tmpdir 内に閉じ、テスト間の干渉が無い。
+- テスト失敗時に pod プロセスの stderr / 関連ファイルが artefact として確認できる。
+- CI 既定パス (`cargo test --workspace`) では E2E が走らない。opt-in jobs でだけ走る。
+- 上の論点 1〜5 が文書化されている（チケット内 or `docs/` 配下のいずれか）。
+
+## 完了条件
+
+- 上記要件を満たすハーネスが入り、最小シナリオ 1 本が通る。
+- 後続シナリオ（permission deny / cli-manifest-flags / spawn 親子 / resume / fork / stream-continuation）を**書く側の手順書**が提示されている（fixture 追加方法、シナリオ crate の追加方法、env のお作法）。
+- 個別シナリオの実装は本チケットに含めない。後続チケットで切る。
+
+## 範囲外
+
+- 個別 E2E シナリオの実装（permission deny / cli flags / spawn / resume / fork / stream-continuation）。それぞれ後続チケット。
+- 全 provider 分の HTTP スタブ（最初は 1 provider に絞る）。
+- TUI バイナリを PTY で操作する経路。
+- GUI バイナリの E2E（`tickets/native-gui-mvp.md` 完了後に別途）。
+- E2E を CI 既定で走らせる切替。
+
+## 依存 / 関連
+
+- `tickets/client-crate.md`（protocol を喋る client crate を切り出す。E2E はここに依存して書く）
+- `tickets/llm-worker-stream-continuation.md`（動的応答 canned server を必要とする最初のシナリオ）
+- `tickets/permission-extension-point.review.md`（最初に書きたいシナリオ）
+- `crates/pod/tests/spawn_pod_test.rs`（env mutex 等の流儀を流用）
+- `crates/llm-worker/tests/*_fixtures.rs`（fixture 資産の出発点）
+- `CLAUDE.md:6`（E2E 未設計の宣言）