# ユーザ起点の Pause と Resume

## 背景

現状 `PodStatus::Paused` に到達する経路は interceptor フック（`PreToolAction::Pause` / `TurnEndAction::Pause`）のみで、**ユーザが TUI から Paused 状態に落とす手段がない**。結果として `Method::Resume` と TUI の `Ctrl-R` は実装されているのに発火機会がなく死に筋になっている。

`Method::Cancel`（現 TUI `Ctrl-X`）はハード中止で `PodStatus::Idle` に落ちる — turn を破棄したい時には使えるが、続きから再開する手段がない。

ユーザが「今の LLM リクエストを止めて、続きは後で再開したい」「止めて、別のことを先にやりたい」という操作が可能な primitive と UI を整える。

## 依存

- `Method::Resume` / `PodStatus::Paused`: 既に実装済み、変更不要
- `cancel_tx` による worker 割り込み: 既に実装済み
- `Method::PodEvent` / `Method::Notify` の既存プロトコル拡張パターンを踏襲

## 設計

### 新しい primitive

```rust
pub enum Method {
    Run { input: String },
    Notify { message: String },
    PodEvent(PodEvent),
    Resume,
    Cancel,
    Pause,              // 新: 実行中の turn を止めて Paused 状態に落とす
    Shutdown,
    GetHistory,
}
```

**Cancel / Pause / Shutdown のセマンティクス分離**:

| Method | 実行中に受けた時 | 結果状態 | 用途 |
|---|---|---|---|
| `Cancel` | cancel_tx 発火、turn を破棄 | `Idle` | 中止して捨てる |
| `Pause` | cancel_tx 発火、turn を中断 | `Paused` | 止めるけど続きは後で |
| `Shutdown` | cancel_tx 発火、controller loop 終了 | プロセス終了 | Pod を落とす |

### Controller 側の変更

`run_with_cancel_support` に `pause_requested` フラグを導入：

```rust
async fn run_with_cancel_support<F>(...) -> (PodStatus, bool) {
    let mut shutdown_requested = false;
    let mut pause_requested = false;

    loop {
        tokio::select! {
            result = &mut pod_future => {
                return match result {
                    Ok(r) => { ... }
                    Err(PodError::Worker(WorkerError::Cancelled)) if pause_requested => {
                        // Pause 時は upward PodEvent::Errored を抑止
                        (PodStatus::Paused, shutdown_requested)
                    }
                    Err(e) => { ... PodEvent::Errored 発火 → (PodStatus::Idle, ...) }
                };
            }
            method = method_rx.recv() => {
                match method {
                    Some(Method::Cancel) => { cancel_tx.try_send(()); }
                    Some(Method::Pause) => {
                        pause_requested = true;
                        cancel_tx.try_send(());
                    }
                    Some(Method::Shutdown) => { ... }
                    ...
                }
            }
        }
    }
}
```

worker の割り込みは `cancel_tx` 一本で共通、Cancel と Pause の区別は pause フラグの有無で controller 側が判定する。

**Pause 時の upward PodEvent 抑止**: `PodEvent::Errored` は worker エラー限定の報告なので、ユーザ起点 Pause では発火させない。親 Pod への「子が Paused になった」通知は本チケットでは実装しない（必要なら別チケットで `PodEvent::Paused` variant を追加）。

**自動 turn 中の Pause**: `Method::Notify` の IDLE 自動起動、`Method::PodEvent` の auto-kick も同じ `run_with_cancel_support` を通るので Pause は同じ挙動で効く。

### 割り込みタイミングと history の整合性

`cancel_tx` 発火時の history 状態：

- **LLM ストリーム中**: block collector の Stop が発火していないので partial text / tool_call は history に入らない → history は前ラウンド末で consistent
- **Tool 実行中**: tool 自体は cancellation を知らず完了を待つ。完了後の次チェックポイントで Cancelled → history には tool_result が書かれる、orphan なし
- **tool_call 確定後 ～ tool 実行前**: orphan `tool_use` が history に残りうる
- **ラウンド間待機**: consistent、orphan なし

Resume と Pause→Run で扱いが分かれる。

### Resume の挙動

`worker.resume()` は既存実装のままで全ケース対応：

- Partial text で止まっていた場合: history は前ラウンド末なので、同じリクエストを再送 → LLM が新しく生成
- Orphan `tool_use` が残っている場合: `run_turn_loop` が `get_pending_tool_calls()` で拾って tool を実行
- 綺麗な境界で止まっていた場合: そのまま次ラウンドへ

Resume の仕様は変更なし。

### Paused → Run（新しい turn として開始）

ユーザが Paused 中に新しい入力を投げたら、**「現 turn は終わった」として新しい turn を開始**する。orphan `tool_use` がある場合は history に下記を順に追加してから `worker.run(input)` を呼ぶ：

1. 各 orphan `tool_use` に対して synthetic `tool_result`（summary: `"[Interrupted by user]"`、content なし）を inject — wire 互換性のため
2. `Item::system_message`（内容: `"[The previous turn was interrupted by the user. The user's next request follows.]"`）を inject — LLM に文脈を伝える
3. 新しい user message（`Run` の input）を append
4. `run_turn_loop` に入る

実装する API の目安：`Pod::interrupt_and_run(input: String)` みたいな名前で上記 4 ステップを提供。Controller が Paused → Run 遷移時に呼ぶ。

注: 実機テストで Anthropic が orphan `tool_use`（次 user turn に `tool_result` が含まれない形）を許容するようなら step 1 は削除できる。まずは安全側に倒して両方入れる。

### Idle / Paused 時の Pause / Cancel

- `Pause` when `Idle`: `Event::Error { NotRunning }` を返す（`Cancel` と同じ）
- `Pause` when `Paused`: no-op（既に Paused）
- `Cancel` when `Idle` / `Paused`: `NotRunning` エラー（既存の Cancel 挙動と揃える）

### TUI のキー割り当て

現状：`Ctrl-X` = Cancel、`Ctrl-R` = Resume、`Ctrl-D` = Shutdown（running なら 2 連打確認）、`Esc` = TUI 終了、`Ctrl-C` = TUI 終了。

変更後：

| キー | Running 時 | Idle / Paused 時 |
|---|---|---|
| `Ctrl-X` | `Method::Cancel`（破棄 → Idle） | no-op（エラー表示） |
| `Ctrl-C` | `Method::Pause`（→ Paused） | 1 回目 warn / 3 秒以内の 2 回目で TUI 終了（Pod は残る） |
| `Ctrl-D` | 1 回目 warn / 3 秒以内の 2 回目で `Method::Shutdown` | `Method::Shutdown`（Pod を落とす） |
| `Enter` (入力あり) | —（入力は TUI 側でバッファ） | Idle なら `Method::Run`。Paused なら同じく `Method::Run`（Controller が前 turn を打ち切って新 turn 開始） |
| `Enter` (空) | — | Paused なら `Method::Resume`。Idle なら no-op |

`Ctrl-R` と `Esc` は廃止。

Ctrl-C の 2 段階 UX は Ctrl-D と対称：running 中の 1 回目は安全な中断（Pause）、非 running 時の 1 回目は確認 warn、どちらも連打で最終アクション。

### Paused 状態の TUI 表示

現状 `App` は `running: bool` のみで Paused を区別していない。`ui.rs:draw_status` も「running / idle」の 2 状態のみ。

追加：

- `App` に `paused: bool`（または `status: enum { Idle, Running, Paused }`）
- `Event::RunEnd { result: RunResult::Paused }` で `paused = true`、`running = false`
- `Event::TurnStart` または新しい Run / Resume 送信時に clear
- `draw_status` に paused 分岐を追加、hint は `Enter to resume, type to start new turn`

## 影響範囲

- `crates/protocol/src/lib.rs`: `Method::Pause` variant 追加、serde round-trip テスト
- `crates/pod/src/controller.rs`: `run_with_cancel_support` に `pause_requested` 追加、Paused → Run の interrupt 処理
- `crates/pod/src/pod.rs`: `interrupt_and_run(input)` 相当の API（orphan 閉じ + system note inject + run）
- `crates/tui/src/app.rs`: `paused` フラグ、`submit_input` の Paused 分岐（空なら Resume）
- `crates/tui/src/main.rs`: `handle_key` のキー割り当て変更（Ctrl-X / Ctrl-C / Ctrl-D）、Ctrl-C の 2 連打 Quit、`Ctrl-R` / `Esc` 削除
- `crates/tui/src/ui.rs`: `draw_status` の paused 分岐
- `docs/tui-keybindings.md`: 既存ファイルを更新
- 既存の interceptor-driven Pause（`PreToolAction::Pause` / `TurnEndAction::Pause`）は挙動不変

## 完了条件

- `Method::Pause` が protocol crate に追加され、serde round-trip テストが通る
- 実行中 Pod に `Method::Pause` を送ると `PodStatus::Paused` に落ち、`Method::Resume` で続きから再開できる
- TUI で `Ctrl-C` を押すと Pause される（LLM ストリーム中・tool 実行中どちらからでも、Notify / PodEvent 起点の自動 turn 中でも）
- Pause 時に親 Pod への `PodEvent::Errored` が飛ばない（upward 通知抑止）
- Paused 中に空 Enter → Resume、入力あり Enter → 新 turn として Run（orphan tool_use は synthetic tool_result + system note で閉じる）
- Paused → Run 後、LLM への送信が wire 上正しい（orphan tool_use が解消されている）ことを統合テストで確認
- Pause → Resume の history consistency を統合テストで確認
- `Ctrl-X` = Cancel（破棄 → Idle）、`Ctrl-C` = Pause / 2 連打で TUI 終了、`Ctrl-D` = Shutdown（running 中は 2 連打）
- `Ctrl-R` / `Esc` キーが無効化されている
- TUI status line に Paused 状態と Enter ヒントが表示される
- 既存の Cancel / Shutdown / interceptor-driven Pause の挙動が回帰しない

## 範囲外

- 複数クライアントが同時に Pod を触る時の race。最後の勝ち or 冪等挙動で十分
- Tool 実行の cancellation 対応（長時間 tool を interrupt する仕組み）
- 親 Pod への `PodEvent::Paused` 通知
- Anthropic が orphan `tool_use` を本当に 400 で弾くかの実機検証。まず synthetic tool_result を入れて安全側で実装、許容されるなら後で削る