From a4146553667d92681e7236d71e6f71edade6d1cf Mon Sep 17 00:00:00 2001 From: Hare Date: Mon, 25 May 2026 06:37:38 +0900 Subject: [PATCH] docs: add spawnpod run delivery ticket --- TODO.md | 1 + tickets/spawnpod-initial-run-confirmation.md | 51 ++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 tickets/spawnpod-initial-run-confirmation.md diff --git a/TODO.md b/TODO.md index 93b43453..487d5fd7 100644 --- a/TODO.md +++ b/TODO.md @@ -7,6 +7,7 @@ - Pod: 任意ターンからの Fork（複数ターン巻き戻しを汎用化） → [tickets/pod-session-fork.md](tickets/pod-session-fork.md) - Pod/TUI: 手動 rollback 導線 → [tickets/manual-turn-rollback.md](tickets/manual-turn-rollback.md) - Pod: Inbound PodEvent ハンドリングの重複を統合 → [tickets/pod-inbound-pod-event-dedup.md](tickets/pod-inbound-pod-event-dedup.md) +- SpawnPod 初回 task delivery の受理確認 → [tickets/spawnpod-initial-run-confirmation.md](tickets/spawnpod-initial-run-confirmation.md) - llm-worker のエラー耐性 - ストリーム途中失敗時の継続 → [tickets/llm-worker-stream-continuation.md](tickets/llm-worker-stream-continuation.md) - E2E テストハーネス（`tests/e2e/`、opt-in） → [tickets/e2e-harness.md](tickets/e2e-harness.md) diff --git a/tickets/spawnpod-initial-run-confirmation.md b/tickets/spawnpod-initial-run-confirmation.md new file mode 100644 index 00000000..ebfbff41 --- /dev/null +++ b/tickets/spawnpod-initial-run-confirmation.md @@ -0,0 +1,51 @@ +# SpawnPod: initial Run delivery confirmation + +## 背景 + +`SpawnPod` は child Pod を起動し、初回 task を `Method::Run` として送る。しかし、実例として `impl-llm-worker-stream-continuation` を再作成した際、runtime registry / socket / process は生きている一方で、初回 task の session log が materialize されず、Pod は `idle` のままだった。 + +確認された状態: + +- `/run/user/1000/insomnia/pods.json` に live allocation がある +- `/run/user/1000/insomnia//status.json` は `state: "idle"` と runtime `segment_id` を持つ +- `/home/hare/.insomnia/sessions/pods//metadata.json` は pending segment のまま +- 対応する session / segment `.jsonl` が存在しない +- `ReadPodOutput` は no new assistant text + +`SpawnPod` の送信側は `send_run` で `Method::Run` を write してすぐ切断し、`TurnStart` 等の ack を待っていない。一方 server 側は接続直後に `Snapshot` を書いてから method を読むため、client がすぐ close すると server が snapshot write で失敗し、method を読む前に connection handler が終了する race があり得る。 + +この場合 `SpawnPod` は成功を返すが、child Pod は初回 task を実行していない。 + +## 方針 + +`SpawnPod` は child process / socket の起動だけでなく、初回 task が controller に受理され、少なくとも `UserMessage` または `TurnStart` が観測できるまで確認してから成功を返す。 + +既存の `SendToPod` が使う `send_run_and_confirm` と同等の acknowledgement を `SpawnPod` の初回 task 送信にも適用する。 + +## 要件 + +- `SpawnPod` の初回 task 送信は fire-and-forget にしない。 + - `Method::Run` 送信後、`UserMessage` / `TurnStart` / `InvokeStart` など、run が受理されたことを示す event を待つ。 + - timeout 時は `SpawnPod` を失敗扱いにする。 +- 初回 task delivery に失敗した場合、process / registry / delegated scope の扱いを明確にする。 + - cleanup するか、attach 可能な idle Pod として残すかを実装で決める。 + - 少なくとも成功扱いで返さない。 +- Server が connection 開始時に `Snapshot` を書く設計と競合しない。 + - client 側が snapshot/event を読みながら `Method::Run` ack を待つ形にする。 +- `SpawnPod` 成功後は、child Pod の metadata が pending でも、初回 run が開始済みであることを確認できる。 + - session log materialization のタイミングそのものは別設計でもよい。 +- `SendToPod` と `SpawnPod` の run delivery confirmation ロジックを可能な範囲で共通化する。 + +## 完了条件 + +- `SpawnPod` が初回 task の受理確認を待つ。 +- 初回 task が実行されない race を再現する test または regression test がある。 +- `SpawnPod` が success を返した後、child Pod が idle pending のまま task 未実行になる状態が起きない。 +- delivery timeout / failure 時の error message が人間に分かる。 +- `cargo fmt --check` と関連 crate の test が通る。 + +## 範囲外 + +- `tui -r` picker に live pending Pod を表示する修正。 +- session log の SegmentStart materialization 方針変更。 +- spawned child Pod panel UI。