aiterm-mcp 0.16.0 → 0.18.0

package/README.ja.md

@@ -24,10 +24,19 @@
 
 12 ツール: 6 つの **PTY ツール**（`pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list`）で 1 本の永続端末を開き・操作し・読む。加えて 4 つの **エージェント起動ツール**（`claude_agent` / `codex_agent` / `grok_agent` / `composer_agent`）が別のコーディングエージェントの TUI を新しい端末の中に起動し、`claude_turn`がdurable caller向けの構造化issue／recoveryを、`diagnostics`が安全なfactory readinessを返す。バックエンドは **tmux** なので、MCP サーバや AI クライアントが再起動してもセッションは生き残る。
 
-**v0.12.2 は release candidate（公開待ち）です。** factory diagnostics と local
+**v0.18.0 を 2026-07-18 に公開。** 実運用障害の還流による agent dispatch の hardening:
+全 dispatch／launch receipt に **submit 座礁観測** `submit_residue` を追加
+（送信 prompt が vendor TUI の composer に未 submit のまま残存していないかを有界に観測して報告する。
+陽性証拠のみ・auto-retry なし）。agent への prompt paste は tmux **bracketed paste**（pane ごとの
+negotiation）で包み、語中の文字化けと Enter 取り落としを抑制。初回 prompt 前の ready gate は
+busy 表示中（esc to interrupt）の Codex/Claude を ready と数えない。
+v0.16/0.17 以来、親エージェントは aiterm 上で一切ブロックしない:
+agent session への send は常に非ブロック dispatch になり、完了待ちは `aiterm-wait` 一本
+（exit code が receipt の outcome を映す: 0=done / 3=timeout=未完了 / 4=closed）、初回 prompt 付き
+launch は structured receipt にコピペ可能な `wait_command` を含む。factory diagnostics と local
 runtime-error store は canonical dotagents config の `collection.enabled: true` が明示された
-場合だけ収集し、既定OFF、network送信は行いません。npm公開、tag、CI、registry登録、registry由来install
-の確認は未実施です。
+場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
+Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
 **状態:** 開発継続中 · この分野では新参で、別の形に賭けている（[既存手段との比較](#既存手段との比較)参照）· 動作対象は Linux · WSL2 · macOS · Windows ネイティブ（core PTY ツール。`agent_done` は現時点では POSIX/WSL/macOS のみ）· MIT · [変更履歴](CHANGELOG.md)。
 
@@ -52,7 +61,7 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 ### 2. その端末の中に他のコーディングエージェントを起動する — オーケストレーションの旗艦
 
-同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**（aiterm 所有の Stop hook 付き）で、agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、その exit で受ける（親はブロックもポーリングもしない）。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
+同じ primitive が別エージェントの TUI を宿す。4 つの起動ツールが、Claude/Codex/Grok/Composer の対話 TUI を新しい永続端末の中に起動し、`session_id` を返す。既存の人間向けtextに加えて`aiterm.agent-launch-result.v1` structured receiptも返すため、durable callerは表示文字列を解析せずsession handleを取得できる。以後は同じ `pty_read` / `pty_send` で継続操作する。**起動は常に managed**（aiterm 所有の Stop hook 付き）で、agent session への `pty_send` は非ブロックの **dispatch** になり `event_cursor` 入り receipt を即返す。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` をホストのバックグラウンドタスクとして実行し、exit 時に receipt の `outcome` で判定する（exit 0=done / 3=timeout=未完了・既定600秒 / 4=closed。親はブロックもポーリングもしない）。起動時 `prompt` を渡した launch は structured receipt にコピペ可能な `wait_command` と `event_cursor`、そして `submit_residue` 観測を含む（true=prompt が composer に未 submit で残存している疑い＝案内に従い画面確認から復旧 / false=残存観測せず・成立の保証ではない / null=対象外）。dispatch receipt にも同じ観測が付く。durable machine callerは`claude_turn({ action:"issue"|"recover", session_id, operation_id, ... })`を使い、人間向けerror文字列を解析せず`accepted`／`pending`／`completed`／`unknown`を判定できる。recoveryは再送せず、検証済み完了だけがexact `raw_output`を持つ。通常の`pty_send`／`pty_read`は対話callerと人間向けに維持する。`C-c`後もmarkerを保持し、Stopが来なければsessionをcloseする。`claude_agent` と `codex_agent` の初回 `prompt` は ready gate 経由で送信して待たずに返る（Grok/Composer は argv 渡し）。手動でキー操作したい場合は `pty_open` で素の端末を開き vendor CLI を自分で起動する。
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
@@ -60,7 +69,7 @@ codex_agent({ session_name: "codex1", cwd: "/repo",
                                     → { session_id: "codex1", … }   # Codex が永続端末で稼働開始
 pty_read("codex1", { screen: true })   → 何をしているか読む（トークン削減）
 pty_send("codex1", "also fix the imports it broke")   # 非ブロックdispatch＝event_cursor入りreceipt
-$ aiterm-wait --session codex1 --cursor <event_cursor>   # exitが完了push。回収は pty_read(agent_transcript:true)
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeout(未完了) / 4=closed。回収は pty_read(agent_transcript:true)
                                     → 操舵し、Codex の次の入力境界で返る
 ```
 
@@ -298,7 +307,7 @@ consumer は `aiterm-runtime-errors snapshot` を読み、durable ingestion 後
 
 `pty_send` は送信前に破壊的コマンド（`rm -rf /`, `mkfs`, `dd of=/dev/…`, `DROP TABLE` 等）を遮断し（`force: true` で越える）、ESC・ブラケットペースト終端などをサニタイズする。`pty_read` は既定で制御文字を無害化して返す（`raw: true` はバイトをそのまま返す）。これは**サンドボックスではなく tripwire**（[既知の制約](#既知の制約バグではなく仕様)参照）。
 
-1回の `pty_send` が受理する本文はUTF-8で最大64KiB。同一sessionへの送信はaiterm processをまたいで直列化し、chunk同士の混線を防ぐ。macOSでは長いPTY入力の欠落を避けるためUTF-8境界を壊さない256-byte単位でtmux pasteし、Linux/WSLでは上限内を1回でpasteする。途中chunkが失敗した場合は部分送信済みであることを明示し、自動でEnterを押さない。送信processの異常終了でlockが残った場合は送信前にfail-closedする。そのsessionを `pty_close` して作り直すか、全sessionを破棄できる場合だけ `pty_kill_all` で安全に掃除する。
+1回の `pty_send` が受理する本文はUTF-8で最大64KiB。同一sessionへの送信はaiterm processをまたいで直列化し、chunk同士の混線を防ぐ。macOSでは長いPTY入力の欠落を避けるためUTF-8境界を壊さない256-byte単位でtmux pasteし、Linux/WSLでは上限内を1回でpasteする。agent dispatch の paste はさらに tmux bracketed paste（`paste-buffer -p`）を使う: bracketed paste mode を要求している pane（vendor TUI）へは各 chunk を `ESC[200~/201~` で包んで届け、チャンク投入中のキー解釈による語中文字化け・submit 取り落としを抑える。通常の shell 送信は不変。途中chunkが失敗した場合は部分送信済みであることを明示し、自動でEnterを押さない。送信processの異常終了でlockが残った場合は送信前にfail-closedする。そのsessionを `pty_close` して作り直すか、全sessionを破棄できる場合だけ `pty_kill_all` で安全に掃除する。
 
 ## 人が覗く
 

package/README.md

@@ -24,14 +24,24 @@
 
 Twelve tools: six **PTY tools** — `pty_open` / `pty_send` / `pty_read` / `pty_key` / `pty_close` / `pty_list` — to open, drive, and read one persistent terminal, four **agent launchers** — `claude_agent` / `codex_agent` / `grok_agent` / `composer_agent` — that each start another coding agent's TUI inside a fresh one, `claude_turn` for durable structured issue/recovery, and `diagnostics` for safe factory readiness. The backend is **tmux**, so sessions survive even if the MCP server or the AI client restarts.
 
-**v0.15.0 was published on 2026-07-18.** It brings the interactive agent
-launchers, durable `claude_turn` issue/recovery, machine-readable launch and
-idempotent close receipts, the hardened TUI readiness gate, and the new
-`aiterm-wait` completion-push binary to npm. Factory diagnostics and the local
-runtime-error store collect only when canonical dotagents config explicitly sets
-`collection.enabled: true`; collection is off by default and performs no network
-I/O. It ships via tag-triggered CI with npm provenance (OIDC Trusted Publishing);
-the GitHub Release re-registers the Official MCP Registry entry.
+**v0.18.0 was published on 2026-07-18.** Field-failure hardening for agent
+dispatch: every dispatch/launch receipt now carries a **submit-strand
+observation** `submit_residue` (a bounded screen poll that reports when the
+sent prompt is still sitting unsubmitted in the vendor TUI's composer —
+positive evidence only, no auto-retry), agent prompt pastes are wrapped in
+tmux **bracketed paste** (negotiated per pane) against mid-word corruption and
+dropped submits, and the pre-prompt ready gate no longer counts a busy
+Codex/Claude screen ("esc to interrupt") as ready. As of v0.16/0.17 a parent
+agent never blocks on aiterm: every send to an agent session is a non-blocking
+dispatch, completion is one universal `aiterm-wait` waiter whose exit codes
+mirror the receipt outcome (`0`=done / `3`=timeout, not finished /
+`4`=closed), and a launch with an initial prompt returns a ready-made
+`wait_command` in its structured receipt.
+Factory diagnostics and the local runtime-error store collect only when
+canonical dotagents config explicitly sets `collection.enabled: true`;
+collection is off by default and performs no network I/O. It ships via
+tag-triggered CI with npm provenance (OIDC Trusted Publishing); the GitHub
+Release re-registers the Official MCP Registry entry.
 
 **Status:** actively maintained · the newcomer here, betting on a different shape (see [vs. the alternatives](#vs-the-alternatives)) · runs on Linux · WSL2 · macOS · native Windows for the core PTY tools (managed completion is POSIX/WSL/macOS only for now) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
@@ -62,7 +72,7 @@ pty_read(id, { wait: true })       → read the token-reduced output, completion
 
 ### 2. Launch other coding agents into that terminal — the orchestration flagship
 
-The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle. From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Every launch is **managed**: aiterm installs its own Stop hook, so turn completion is a first-class event. Sending to an agent session is a non-blocking **dispatch** — the call returns immediately with an `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Stop; if no Stop arrives, close the session. An initial `prompt` on `claude_agent`/`codex_agent` is submitted through the same ready gate and the launcher returns without waiting; on Grok/Composer it is passed on the CLI's argv. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
+The same primitive hosts another agent's TUI. Four launchers each start one vendor's interactive coding-agent TUI inside a fresh persistent terminal and return a `session_id`. Their existing human-readable text is accompanied by an `aiterm.agent-launch-result.v1` structured receipt, so durable callers never parse display text for the session handle; when the launch carries an initial `prompt`, the receipt also includes the `event_cursor`, a ready-made `wait_command` for the completion waiter, and a `submit_residue` observation (`true` = the prompt is likely still sitting unsubmitted in the composer — the hint explains recovery; `false` = no residue observed, not a proof of submission; `null` = not applicable). From there you drive it with the same `pty_read` / `pty_send` you'd use on any shell: read its output token-reduced, send it the next step. (The TUIs are full-screen apps, so `pty_read({ screen: true })` gives you the rendered view.) Every launch is **managed**: aiterm installs its own Stop hook, so turn completion is a first-class event. Sending to an agent session is a non-blocking **dispatch** — the call returns immediately with an `event_cursor`, and completion arrives via [`aiterm-wait`](#completion-push-for-parent-agents-aiterm-wait). Durable machine callers use `claude_turn({ action: "issue" | "recover", session_id, operation_id, ... })`: it returns fixed `accepted` / `pending` / `completed` / `unknown` states without parsing human-facing errors, never resends during recovery, and includes exact `raw_output` only for a verified completion. The same operation ID is carried through the dispatch receipt, active marker, Stop event, and result. The ordinary `pty_send` / `pty_read` surface remains available for interactive callers and humans. `C-c` keeps the marker for a delayed Stop; if no Stop arrives, close the session. An initial `prompt` on `claude_agent`/`codex_agent` is submitted through the same ready gate and the launcher returns without waiting; on Grok/Composer it is passed on the CLI's argv. This needs the vendor's own CLI installed and authenticated — see [Requirements](#requirements).
 
 ```text
 codex_agent({ session_name: "codex1", cwd: "/repo",
@@ -71,7 +81,7 @@ codex_agent({ session_name: "codex1", cwd: "/repo",
 pty_read("codex1", { screen: true })   → read what it's doing (token-reduced)
 pty_send("codex1", "also fix the imports it broke")
                                     → non-blocking dispatch; receipt carries event_cursor
-$ aiterm-wait --session codex1 --cursor <event_cursor>   # host background task; its exit = completion push
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # host background task; exit code 0=done, 3=timeout (not done), 4=closed
 pty_read("codex1", { agent_transcript: true })           → collect the full answer
 ```
 
@@ -303,10 +313,10 @@ When an agent's answer is longer than the on-screen tail (pane height ≈ 24 lin
 
 ### Completion push for parent agents (`aiterm-wait`)
 
-As of v0.16.0 a parent agent **never blocks** on aiterm — there is no wait parameter anywhere. The whole flow is dispatch + one universal waiter:
+As of v0.16 a parent agent **never blocks** on aiterm — there is no wait parameter anywhere (v0.17 makes the waiter's exit codes mirror its outcome). The whole flow is dispatch + one universal waiter:
 
-1. Launch the child (`claude_agent` / `codex_agent` / ...; every launch is managed). Send a turn with plain `pty_send` (or `claude_turn issue` for durable Claude operations). The call passes the TUI ready gate, submits, and returns immediately with an `event_cursor` in its structured receipt.
-2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]`. It observes the vendor Stop-hook completion event as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt (`done` / `timeout` / `closed`). The `--cursor` boundary makes it start-order independent: no completion can slip past even if the waiter starts late.
+1. Launch the child (`claude_agent` / `codex_agent` / ...; every launch is managed). Send a turn with plain `pty_send` (or `claude_turn issue` for durable Claude operations). The call passes the TUI ready gate, submits, and returns immediately with an `event_cursor` in its structured receipt — plus a `submit_residue` observation: `true` means the sent text still lingered in the composer after submit (likely stranded; inspect the screen before re-pressing Enter), `false` means no residue was observed (not a proof of submission), `null` means not applicable.
+2. Run `aiterm-wait --session <id> --cursor <event_cursor> [--operation sha256:<64hex>] [--timeout <sec>]` (a launch with an initial `prompt` returns this command ready-made as `wait_command` in its structured receipt). It observes the vendor Stop-hook completion event as a **pure reader** and exits with a one-line `aiterm.agent-wait-result.v1` receipt. **Exit ≠ done**: the receipt's `outcome` is authoritative, and the exit code mirrors it — `0` = `done`, `3` = `timeout` (the turn is **not** finished; default `--timeout` is 600 s), `4` = `closed`, `1` = error. On `timeout` just re-run the waiter with the same cursor. The `--cursor` boundary makes it start-order independent: no completion can slip past even if the waiter starts late.
 3. Host integration picks the invocation style: a harness that re-invokes its agent when a background task exits (Claude Code) runs the waiter **in the background** and gets woken with zero polling; a host without that mechanism runs it as a foreground shell command. Either way the aiterm MCP call itself never blocks.
 4. Collect the result exactly as before: `pty_read(agent_transcript: true)`, or `claude_turn recover` for durable Claude operations. The waiter carries the signal, never the payload.
 
@@ -322,7 +332,7 @@ As of v0.16.0 a parent agent **never blocks** on aiterm — there is no wait par
 
 Before sending, `pty_send` blocks destructive commands (`rm -rf /`, `mkfs`, `dd of=/dev/…`, `DROP TABLE`, …) — pass `force: true` to override — and sanitizes ESC / bracketed-paste terminators. `pty_read` neutralizes control characters in what it returns by default (`raw: true` returns the bytes verbatim). This is a **tripwire, not a sandbox** (see [Known constraints](#known-constraints-by-design-not-bugs)).
 
-Each `pty_send` accepts at most 64 KiB of UTF-8 text. Sends to the same session are serialized across aiterm processes so chunks cannot interleave. On macOS, text is pasted through tmux in UTF-8-safe 256-byte chunks to avoid the platform PTY truncation observed with long input; Linux and WSL use one bounded paste. If a later chunk fails, aiterm reports the partial-send state and does not press Enter automatically. A lock left by a terminated sender fails closed before sending; close and recreate that session (or use `pty_kill_all` when every session is disposable) to clean it up safely.
+Each `pty_send` accepts at most 64 KiB of UTF-8 text. Sends to the same session are serialized across aiterm processes so chunks cannot interleave. On macOS, text is pasted through tmux in UTF-8-safe 256-byte chunks to avoid the platform PTY truncation observed with long input; Linux and WSL use one bounded paste. Agent dispatches additionally paste with tmux bracketed paste (`paste-buffer -p`): panes that requested bracketed-paste mode (the vendor TUIs) receive each chunk wrapped in `ESC[200~/201~`, hardening prompt injection against mid-word key-interpretation corruption and dropped submits; ordinary shell sends are unchanged. If a later chunk fails, aiterm reports the partial-send state and does not press Enter automatically. A lock left by a terminated sender fails closed before sending; close and recreate that session (or use `pty_kill_all` when every session is disposable) to clean it up safely.
 
 ## A human can watch
 

package/dist/aiterm-wait-cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
-// 親AIホストのバックグラウンドタスクとして起動し、exitを「完了通知」として使う。
+// 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
+// exit≠完了: exit code は outcome を映す（0=done / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// receipt の outcome が正で、done 以外は未完了。timeout の既定は core の DEFAULT_AGENT_DONE_TIMEOUT（600秒）。
 import { fileURLToPath } from "node:url";
 import * as fs from "node:fs";
 import { AitermError, observeAgentDone } from "./core.js";
@@ -62,6 +64,8 @@ export function parseArgs(argv) {
 function emit(value) {
     process.stdout.write(JSON.stringify(value) + "\n");
 }
+// outcome → exit code。exit status しか見えないホストでも done とそれ以外を誤読できないようにする。
+const OUTCOME_EXIT_CODES = { done: 0, timeout: 3, closed: 4 };
 export async function main(argv) {
     const cmd = parseArgs(argv);
     const result = await observeAgentDone(cmd.session, {
@@ -70,6 +74,7 @@ export async function main(argv) {
         cursor: cmd.cursor,
     });
     emit(result);
+    process.exitCode = OUTCOME_EXIT_CODES[result.outcome];
 }
 function isDirectExecution() {
     const entry = process.argv[1];

package/dist/core.js

@@ -56,6 +56,12 @@ const AGENT_TUI_READY_TIMEOUT_MS = 30_000;
 const AGENT_TUI_READY_POLL_MS = 500;
 const AGENT_TUI_READY_STABLE_SAMPLES = 11;
 const AGENT_TUI_READY_LINES = 45;
+// submit座礁観測（dispatch後にcomposerへ送信textが残存していないかの有界チェック）
+const AGENT_SUBMIT_RESIDUE_DELAY_MS = 250;
+const AGENT_SUBMIT_RESIDUE_POLL_MS = 300;
+const AGENT_SUBMIT_RESIDUE_MAX_SAMPLES = 5;
+const AGENT_SUBMIT_RESIDUE_TAIL_CHARS = 32;
+const AGENT_SUBMIT_RESIDUE_MIN_TAIL_CHARS = 8;
 const GROK_AUTH_MAX_BYTES = 64 * 1024;
 const CLAUDE_RESULT_MAX_BYTES = 4 * 1024 * 1024;
 // 出力削減（RTK の CAP 思想を移植）
@@ -936,7 +942,7 @@ export function send(name, text, o = {}) {
         // sentinelを待つため、公開上の拒否は副作用ゼロでなければならない。
         if (!o.preserveAgentOperation && managedClaudeOperation(name) !== undefined) {
             throw new AitermError("managed Claude agent sessionへの通常送信はturn境界を失うため拒否します。" +
-                'pty_send(wait:"agent_done")を使うか、通常対話へ切り替えるならsessionをcloseしてagent_done:falseで起動し直してください。', 2);
+                "pty_send（forceなし＝自動dispatch）を使うか、通常対話へ切り替えるならsessionをcloseしてpty_openから手動起動し直してください。", 2);
         }
         writeLastcmd(name, text); // read rtk の reducer 分類用（書換/mark 前の素のコマンド）
         if (o.rtk)
@@ -983,6 +989,8 @@ export function send(name, text, o = {}) {
             // -r: LF→CR 置換を無効化。-Sは対応新版だけでvis(3)制御文字変換を無効化する。
             // send 自身の raw/sanitize 契約だけを真実とし、tmux 側で黙って再変換させない。
             const pasteArgs = ["paste-buffer", "-d", "-r"];
+            if (o.bracketedPaste)
+                pasteArgs.push("-p");
             if (pasteSupportsNoSanitize)
                 pasteArgs.push("-S");
             pasteArgs.push("-b", bufferName, "-t", name);
@@ -1015,7 +1023,7 @@ export function sendKey(name, key, o = {}) {
     const k = KEYMAP[key.toLowerCase()] ?? key;
     if (!o.preserveAgentOperation && managedClaudeOperation(name) !== undefined && k !== "C-c") {
         throw new AitermError("managed Claude agent sessionではturn相関を壊さないC-cだけをpty_keyで送れます。" +
-            "他の対話操作はpty_send(wait:\"agent_done\")、終了はpty_closeを使ってください。", 2);
+            "他の対話操作はpty_send（自動dispatch）、終了はpty_closeを使ってください。", 2);
     }
     tmux("send-keys", "-t", name, k);
     return `sent key ${k} to ${name}`;
@@ -2284,6 +2292,9 @@ function bindAgentVendorSession(meta, ev) {
         meta.vendor_session_id = ev.vendor_session_id;
     }
 }
+// 復旧案内の aiterm-wait は --cursor 0 を明示する: cursor 省略時の既定は waiter 起動時 EOF のため、
+// 案内表示〜実行の間に done event が書かれていると読み飛ばして timeout まで座る。event file は
+// per-launch 新規作成＋launch_id フィルタ付き走査なので、0 起点は取りこぼしゼロかつ安全。
 function bindCompletedInitialPrompt(meta) {
     if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
         return;
@@ -2293,7 +2304,7 @@ function bindCompletedInitialPrompt(meta) {
     }
     const size = safeStatSize(meta.event_file);
     if (size === 0) {
-        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。初回応答完了後に再度 pty_send(wait:"agent_done") してください。`, 2);
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了待ちです。aiterm-wait --session ${meta.aiterm_session} --cursor 0 で完了（outcome=done）を確認してから再度操作してください。`, 2);
     }
     const text = readFileRange(meta.event_file, 0, size).toString("utf8");
     const lines = text.split("\n");
@@ -2305,7 +2316,7 @@ function bindCompletedInitialPrompt(meta) {
     if (!scanned.event) {
         const malformed = scanned.malformedEvents ? ` malformed_events=${scanned.malformedEvents}` : "";
         const partial = tail.trim() ? " partial_event=true" : "";
-        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。初回応答完了後に再度 pty_send(wait:"agent_done") してください。${malformed}${partial}`, 2);
+        throw new AitermError(`agent session '${meta.aiterm_session}' は起動時 prompt の完了 event をまだ確認できません。aiterm-wait --session ${meta.aiterm_session} --cursor 0 で完了（outcome=done）を確認してから再度操作してください。${malformed}${partial}`, 2);
     }
     bindAgentVendorSession(meta, scanned.event);
     setInitialPromptState(meta, "done");
@@ -2426,8 +2437,11 @@ function findLatestCodexTranscript(codexHome, vendorSessionId) {
     visit(sessionsDir);
     return latestFile;
 }
+// 未完了系エラーの共通出口案内。pollingへ誘導せず、正規の完了待ち手段を必ず指す。
+const AGENT_WAIT_GUIDE = "完了待ちは aiterm-wait --session <session_id> のバックグラウンド実行で受ける（polling不要。" +
+    "receiptのoutcome=doneを確認してから再取得）。";
 function transcriptUnavailable() {
-    throw new AitermError("transcript がまだありません。ターン完了後に再取得してください。", 2);
+    throw new AitermError(`transcript がまだありません。ターン完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
 }
 function transcriptNotFound(vendor) {
     throw new AitermError(`最終 assistant メッセージを特定できませんでした（vendor=${vendor}）。screen で確認してください。`, 2);
@@ -2494,18 +2508,18 @@ export async function readAgentTranscript(name, o = {}) {
         const active = readClaudeOperationMarker(meta);
         if (active) {
             const label = active.operationId ? `operation ${active.operationId}` : "operation_idなしのClaude turn";
-            throw new AitermError(`${label} はまだ完了していません。Stop完了後に同じsessionから再取得してください。`, 2);
+            throw new AitermError(`${label} はまだ完了していません。Stop完了後に同じsessionから再取得してください。${AGENT_WAIT_GUIDE}`, 2);
         }
     }
     // wait timeout は「失敗」ではなく状態不明。後着した同一launchの完了eventから
     // vendor session をbindし、promptを再送せず結果だけ回収できるようにする。
     recoverAgentVendorSession(meta);
     if (!meta.vendor_session_id) {
-        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。`, 2);
+        throw new AitermError(`agent session '${name}' はまだターンが完了していません。agent_done 完了後に再取得してください。${AGENT_WAIT_GUIDE}`, 2);
     }
     const done = latestAgentDoneEvent(meta, operationId);
     if (operationId && !done) {
-        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。`, 2);
+        throw new AitermError(`operation ${operationId} はまだ完了していません。同じoperation_idで後から再取得してください。${AGENT_WAIT_GUIDE}`, 2);
     }
     const turnId = done?.turn_id ?? null;
     let text = "";
@@ -2646,8 +2660,10 @@ function assertInitialPromptNotPendingForSend(name, force) {
     if (meta.initial_prompt !== "pending" && meta.initial_prompt !== "sent")
         return;
     throw new AitermError(`agent session '${name}' は起動時 prompt の完了待ちです。通常 pty_send は混入防止のため送信しません。` +
-        `完了後に pty_send(wait:"agent_done") するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
+        `aiterm-wait --session ${name} --cursor 0 で完了（outcome=done）を確認してから再度 pty_send するか、手動介入が必要な場合だけ force:true を明示してください。`, 2);
 }
+// aiterm-wait の exit 契約（CLI と各所の案内文で共有する正）。exit≠完了: outcome が done の時だけ完了。
+export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed。receiptのoutcomeが正で、done以外は未完了`;
 // 外部waiterプロセス用の純リーダー観測。lock・PTY・metadata書込・dispatch状態には一切触れない。
 // event fileのtail規律（未終端行保持・増分上限）はwaitAgentDoneEventと同一だが、
 // vendor_session_idのbind永続化を行わない点だけ意図的に異なる（waiterは観測者であって所有者でない）。
@@ -2719,6 +2735,18 @@ function isAgentTuiReady(kind, screen) {
     }
     return screen.includes("Grok Build") && /(^|\n|\s)❯/.test(screen);
 }
+// Codex/Claude は実行中に「(esc to interrupt)」を表示する（実機採取）。startup 側の処理
+// （MCP initialize 等）が走ったまま composer だけ描画されている画面は入力受付とみなさない。
+// Grok/Composer は busy 表示文字列の実機根拠が未採取のため対象外（誤ブロックで起動不能にしない）。
+const AGENT_TUI_BUSY_KINDS = new Set(["codex", "claude"]);
+const AGENT_TUI_BUSY_RE = /esc to interrupt/i;
+// ready gate 用: 入力欄マーカーがあっても busy 表示中は ready と数えない。
+// frontend 推定（inferAgentFrontend）は「agent TUI が前面か」を見るだけなので isAgentTuiReady のまま。
+function isAgentTuiIdleReady(kind, screen) {
+    if (!isAgentTuiReady(kind, screen))
+        return false;
+    return !(AGENT_TUI_BUSY_KINDS.has(kind) && AGENT_TUI_BUSY_RE.test(screen));
+}
 async function waitAgentTuiReadyImpl(kind, sample, sleepFn, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? AGENT_TUI_READY_TIMEOUT_MS;
     const pollMs = opts.pollMs ?? AGENT_TUI_READY_POLL_MS;
@@ -2730,7 +2758,7 @@ async function waitAgentTuiReadyImpl(kind, sample, sleepFn, opts = {}) {
     for (;;) {
         lastScreen = sample();
         samples++;
-        if (isAgentTuiReady(kind, lastScreen)) {
+        if (isAgentTuiIdleReady(kind, lastScreen)) {
             readyStreak++;
             if (readyStreak >= stableSamples)
                 return { ready: true, samples, lastScreen };
@@ -2749,6 +2777,68 @@ async function waitAgentTuiReady(name, meta, timeoutMs = AGENT_TUI_READY_TIMEOUT
 async function waitAgentTuiReadyByKind(name, kind, timeoutMs = AGENT_TUI_READY_TIMEOUT_MS) {
     return waitAgentTuiReadyImpl(kind, () => captureScreen(name, AGENT_TUI_READY_LINES), sleep, { timeoutMs });
 }
+function normalizeResidueText(s) {
+    return s.replace(/\s+/g, "");
+}
+function agentSubmitResidueTail(text) {
+    // 行単位でなく text 全体の正規化末尾から取る: 最終行が短い prompt（「以上」等の締め行）でも
+    // 直前行の内容を含む末尾 32 codepoint で観測できる。composer は末尾（カーソル位置）を表示し、
+    // submit 済みの transcript echo は長文では先頭側を表示するため、末尾一致は座礁側に偏る。
+    const cps = [...normalizeResidueText(text)];
+    if (cps.length < AGENT_SUBMIT_RESIDUE_MIN_TAIL_CHARS)
+        return null;
+    return cps.slice(-AGENT_SUBMIT_RESIDUE_TAIL_CHARS).join("");
+}
+function agentSubmitResidueOnScreen(kind, screen, tail) {
+    const lines = screen.split("\n");
+    // 入力欄マーカーは ready 判定と同じ記号を行頭基準で探す。submit 済みの transcript echo は
+    // マーカー行より上に出るため、最後のマーカー行以降だけを composer 領域として見る。
+    const markerRe = kind === "codex" ? /^\s*[›>]/ : kind === "claude" ? /^\s*❯/ : /(^|\s)❯/;
+    let markerIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (markerRe.test(lines[i])) {
+            markerIdx = i;
+            break;
+        }
+    }
+    if (markerIdx < 0)
+        return null;
+    return normalizeResidueText(lines.slice(markerIdx).join("")).includes(tail);
+}
+async function detectAgentSubmitResidueImpl(kind, text, sample, sleepFn, opts = {}) {
+    const tail = agentSubmitResidueTail(text);
+    if (!tail)
+        return { residue: null, samples: 0 };
+    const delayMs = opts.delayMs ?? AGENT_SUBMIT_RESIDUE_DELAY_MS;
+    const pollMs = opts.pollMs ?? AGENT_SUBMIT_RESIDUE_POLL_MS;
+    const maxSamples = opts.maxSamples ?? AGENT_SUBMIT_RESIDUE_MAX_SAMPLES;
+    if (delayMs > 0)
+        await sleepFn(delayMs);
+    let samples = 0;
+    let last = null;
+    for (let i = 0; i < maxSamples; i++) {
+        last = agentSubmitResidueOnScreen(kind, sample(), tail);
+        samples++;
+        // 残存が消えた（または判定不能になった）時点で確定。true だけは描画遅延と区別するため
+        // 全サンプル持続した場合にのみ報告する。
+        if (last !== true)
+            return { residue: last, samples };
+        if (i < maxSamples - 1)
+            await sleepFn(pollMs);
+    }
+    return { residue: true, samples };
+}
+async function detectAgentSubmitResidue(name, kind, text) {
+    return detectAgentSubmitResidueImpl(kind, text, () => captureScreen(name, AGENT_TUI_READY_LINES), sleep);
+}
+export function agentSubmitResidueWarning(name, residue) {
+    if (residue !== true)
+        return "";
+    return (`\n警告: submit_residue=true＝送信 text が composer に残存しており submit 未成立の疑いがある` +
+        `（実行中 turn への queued message が表示されている可能性もある）。` +
+        `pty_read(${name}, screen:true) で状態を確認してから、座礁していれば pty_key(${name}, "Enter") で再 submit、` +
+        `破棄するなら pty_key(${name}, "Escape") を使う。盲目的に Enter を送らない（queued だった場合の二重 submit 防止）。`);
+}
 async function settleAgentDoneScreenImpl(sample, sleepFn, opts = {}) {
     const minDelayMs = opts.minDelayMs ?? AGENT_DONE_SETTLE_MIN_MS;
     const pollMs = opts.pollMs ?? AGENT_DONE_SCREEN_SETTLE_POLL_MS;
@@ -2799,6 +2889,17 @@ export async function __testWaitAgentTuiReady(kind, samples, opts = {}) {
     }, opts);
     return { ...result, sleeps };
 }
+export function __testIsAgentTuiIdleReady(kind, screen) {
+    return isAgentTuiIdleReady(kind, screen);
+}
+export async function __testDetectAgentSubmitResidue(kind, text, samples, opts = {}) {
+    let i = 0;
+    const sleeps = [];
+    const result = await detectAgentSubmitResidueImpl(kind, text, () => samples[Math.min(i++, samples.length - 1)], async (ms) => {
+        sleeps.push(ms);
+    }, opts);
+    return { ...result, sleeps };
+}
 export function __testSetAgentTuiReadyStableSamples(value) {
     if (value !== null && (!Number.isInteger(value) || value < 1 || value > 1000)) {
         throw new AitermError("test ready stable samplesが不正です", 2);
@@ -2813,6 +2914,7 @@ async function sendAgentPromptText(name, text) {
         mark: false,
         rtk: false,
         preserveAgentOperation: true,
+        bracketedPaste: true,
     });
     await sleep(AGENT_SUBMIT_DELAY_MS);
     sendKey(name, "Enter", { preserveAgentOperation: true });
@@ -2829,8 +2931,12 @@ export async function sendInitialAgentPrompt(name, text, o = {}) {
     setInitialPromptState(meta, "not_sent");
     const ready = await waitAgentTuiReady(name, meta, o.ready_timeout ?? AGENT_TUI_READY_TIMEOUT_MS);
     if (!ready.ready) {
-        return (`initial_prompt=not_sent vendor=${meta.kind} ready=false samples=${ready.samples}\n` +
-            `agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。prompt は送信していません。`);
+        return {
+            text: `initial_prompt=not_sent vendor=${meta.kind} ready=false samples=${ready.samples}\n` +
+                `agent session '${name}' の ${agentLabel(meta.kind)} TUI が入力受付状態になりません。prompt は送信していません。`,
+            event_cursor: null,
+            submit_residue: null,
+        };
     }
     const startOffset = safeStatSize(meta.event_file);
     try {
@@ -2845,9 +2951,15 @@ export async function sendInitialAgentPrompt(name, text, o = {}) {
         setInitialPromptState(meta, "failed");
         throw e;
     }
-    return (`initial_prompt=pending vendor=${meta.kind} event_cursor=${startOffset}\n` +
-        `起動時 prompt を送信した。完了通知は aiterm-wait --session ${name} --cursor ${startOffset}（ホストのバックグラウンドタスクとして実行し、exit を完了通知にする）、` +
-        `回収は pty_read(agent_transcript:true) を使う。`);
+    const residue = await detectAgentSubmitResidue(name, meta.kind, text);
+    return {
+        text: `initial_prompt=pending vendor=${meta.kind} event_cursor=${startOffset}\n` +
+            `起動時 prompt を送信した。完了通知は aiterm-wait --session ${name} --cursor ${startOffset} をホストのバックグラウンドタスクとして実行し、` +
+            `exit 時に receipt の outcome で判定する（${AITERM_WAIT_OUTCOME_NOTE}）。回収は pty_read(agent_transcript:true) を使う。` +
+            agentSubmitResidueWarning(name, residue.residue),
+        event_cursor: startOffset,
+        submit_residue: residue.residue,
+    };
 }
 export function isAgentSession(name) {
     assertSessionName(name);
@@ -2889,10 +3001,12 @@ export async function dispatchAgentTurn(name, text, o = {}) {
         mark: false,
         rtk: false,
         preserveAgentOperation: meta.kind === "claude",
+        bracketedPaste: true,
     });
     // Codex TUI は literal text 投入直後の Enter を取り落とすことがある。agent 経路だけ submit を分離する。
     await sleep(AGENT_SUBMIT_DELAY_MS);
     sendKey(name, "Enter", { preserveAgentOperation: meta.kind === "claude" });
+    const residue = await detectAgentSubmitResidue(name, meta.kind, text);
     return {
         schema: "aiterm.agent-dispatch.v1",
         session_id: meta.aiterm_session,
@@ -2900,6 +3014,7 @@ export async function dispatchAgentTurn(name, text, o = {}) {
         vendor: meta.kind,
         event_cursor: startOffset,
         operation_id: operationId,
+        submit_residue: residue.residue,
     };
 }
 export async function runClaudeOperation({ session_id: name, action, operation_id: operationIdInput, text, }) {
@@ -2911,22 +3026,25 @@ export async function runClaudeOperation({ session_id: name, action, operation_i
     const meta = loadAgentMetadata(name);
     if (meta.kind !== "claude")
         throw new AitermError("claude_turnはmanaged Claude agent sessionだけで使用できます", 2);
+    let dispatchReceipt = null;
     if (action === "issue") {
         if (typeof text !== "string" || text.length === 0) {
             throw new AitermError("claude_turn issueには空でないtextが必要です", 2);
         }
         // v0.16.0: issue は dispatch-only。完了通知は aiterm-wait --operation、回収は recover が担う。
-        await dispatchAgentTurn(name, text, { operation_id: operationId });
+        dispatchReceipt = await dispatchAgentTurn(name, text, { operation_id: operationId });
     }
     else {
         if (text != null)
             throw new AitermError("claude_turn recoverにtextは指定できません", 2);
     }
     const inspected = inspectClaudeOperation(meta, operationId, action);
-    if (action === "issue" && inspected.status === "pending") {
-        return { ...inspected, status: "accepted" };
+    // issue は dispatch の submit 座礁観測を捨てずに返す（観測を払ったのに信号を返さない契約矛盾を作らない）。
+    const result = dispatchReceipt ? { ...inspected, submit_residue: dispatchReceipt.submit_residue } : inspected;
+    if (action === "issue" && result.status === "pending") {
+        return { ...result, status: "accepted" };
     }
-    return inspected;
+    return result;
 }
 function inspectClaudeOperation(meta, operationId, action) {
     const base = {
@@ -2934,6 +3052,7 @@ function inspectClaudeOperation(meta, operationId, action) {
         action,
         session_id: meta.aiterm_session,
         operation_id: operationId,
+        submit_residue: null,
     };
     const active = readClaudeOperationMarker(meta);
     if (active) {
@@ -3310,7 +3429,7 @@ export function openAgent(kind, opts = {}) {
     }
     const driveHint = agentDone && kind === "claude"
         ? `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
-            `turnはpty_send(${sid}, "...", wait:"agent_done")で送る。中断はpty_key(${sid}, "C-c")、` +
+            `turnはpty_send(${sid}, "...")で送る（自動で非ブロックdispatch・完了通知はaiterm-wait）。中断はpty_key(${sid}, "C-c")、` +
             `Stopが来ない場合の解除はpty_close(${sid})を使う。`
         : `TUI の描画には数秒かかる。少し置いてから pty_read(${sid}, screen:true) で画面を読み、` +
             `pty_send(${sid}, "...") で入力・pty_key(${sid}, "Enter"/"Up"/"C-c" 等) で操作する（対話）。`;
@@ -3329,8 +3448,10 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
     }
     // v0.16.0: launcher は常に managed（Stop hook つき）で立つ。手動運転したい場合は
     // pty_open で素の PTY を開き、vendor CLI を自分で send する。
+    // 第3要素は「起動時点でturnが走っているか」の event_cursor: Grok/Composer の argv prompt は
+    // event file 新規作成直後の起動＝境界0、prompt なしの起動は turn なし＝null。
     if (!prompt || (kind !== "codex" && kind !== "claude")) {
-        return openAgent(kind, {
+        const [sid, hint] = openAgent(kind, {
             session_name: opts.session_name ?? null,
             model: opts.model ?? null,
             reasoning_effort: opts.reasoning_effort ?? null,
@@ -3339,6 +3460,8 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
             agent_done: true,
             launch_operation_id: opts.launch_operation_id ?? null,
         });
+        // argv prompt（grok/composer）は composer を経由しないため submit 座礁観測の対象外。
+        return [sid, hint, prompt ? 0 : null, null];
     }
     const [sid, hint] = openAgent(kind, {
         session_name: opts.session_name ?? null,
@@ -3353,7 +3476,7 @@ export async function openAgentWithInitialPrompt(kind, opts = {}) {
         const initial = await sendInitialAgentPrompt(sid, prompt, {
             ready_timeout: opts.ready_timeout ?? undefined,
         });
-        return [sid, `${hint}\n${initial}`];
+        return [sid, `${hint}\n${initial.text}`, initial.event_cursor, initial.submit_residue];
     }
     catch (e) {
         const code = e instanceof AitermError ? e.code : 1;

package/dist/index.js

@@ -89,7 +89,8 @@ server.registerTool("pty_send", {
     description: "セッションへテキストを送る。通常PTYへは送信のみ（出力は pty_read で取得）。" +
         "agent session（launcher起動）への send は自動で dispatch になる: TUI の ready gate と submit 分離を通して即返り、" +
         "receipt の event_cursor を返す＝親はブロックしない。完了通知は `aiterm-wait --session <id> --cursor <event_cursor>` を" +
-        "ホストのバックグラウンドタスクとして実行し、その exit で受ける（ポーリング不要）。" +
+        "ホストのバックグラウンドタスクとして実行し、exit時にreceiptのoutcomeで判定する" +
+        `（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
         "結果回収は pty_read(agent_transcript:true)、Claude の durable turn は claude_turn を使う。" +
         "force:true は agent session への手動介入用の素送信。",
     inputSchema: {
@@ -118,6 +119,9 @@ server.registerTool("pty_send", {
         event_cursor: z.number().int().nullable(),
         launch_id: z.string().nullable(),
         vendor: z.enum(["claude", "codex", "grok", "composer"]).nullable(),
+        // dispatch後のsubmit座礁観測（additive）。true=composerに送信textの残存を確認（submit未成立の疑い）/
+        // false=残存を観測せず（成立の保証ではない）/ null=通常送信・判定不能。
+        submit_residue: z.boolean().nullable(),
     },
 }, async ({ session_id, text, enter, mark, force, rtk, raw }) => {
     try {
@@ -134,7 +138,9 @@ server.registerTool("pty_send", {
                     {
                         type: "text",
                         text: `dispatchした（vendor=${receipt.vendor}）。完了通知: aiterm-wait --session ${receipt.session_id} --cursor ${receipt.event_cursor} を` +
-                            "ホストのバックグラウンドタスクとして実行し exit を待つ。回収: pty_read(agent_transcript:true)",
+                            `ホストのバックグラウンドタスクとして実行し、exit時にreceiptのoutcomeで判定（${core.AITERM_WAIT_OUTCOME_NOTE}）。` +
+                            "回収: pty_read(agent_transcript:true)" +
+                            core.agentSubmitResidueWarning(receipt.session_id, receipt.submit_residue),
                     },
                 ],
                 structuredContent: {
@@ -144,6 +150,7 @@ server.registerTool("pty_send", {
                     event_cursor: receipt.event_cursor,
                     launch_id: receipt.launch_id,
                     vendor: receipt.vendor,
+                    submit_residue: receipt.submit_residue,
                 },
             };
         }
@@ -157,6 +164,7 @@ server.registerTool("pty_send", {
                 event_cursor: null,
                 launch_id: null,
                 vendor: null,
+                submit_residue: null,
             },
         };
     }
@@ -309,6 +317,9 @@ server.registerTool("claude_turn", {
         operation_id: z.string().regex(/^sha256:[0-9a-f]{64}$/),
         raw_output: z.string().nullable(),
         reason: z.enum(["operation_not_found", "result_unknown"]).nullable(),
+        // issue時のみdispatch由来のsubmit座礁観測（additive）。true=composerに残存を確認（submit未成立の疑い）/
+        // false=残存を観測せず（成立の保証ではない）/ recover等はnull。
+        submit_residue: z.boolean().nullable(),
     },
 }, async ({ action, session_id, operation_id, text }) => {
     try {
@@ -342,6 +353,13 @@ const agentEffortDesc = (kind) => kind === "claude"
             "composer は effort 自体非対応）。指定すると起動前にエラーを返す"
         : "reasoning effort（思考レベル）。low/medium/high/xhigh/max/ultra（CLI 版依存）。" +
             "ultra は max 推論＋proactive 自動委譲 ON＝使用量急増注意（明示要求時のみ）。省略時は端末 config／CLI 既定。";
+// 全launcher共通の完了受信ガイド。launch応答のwait_command（起動時promptあり時）／pty_send dispatchの
+// event_cursorから組んだaiterm-waitをホストのバックグラウンドタスクとして1本実行し、exit時にreceiptの
+// outcomeで判定する。
+const agentCompletionDesc = `完了通知は起動応答の wait_command（初回prompt時）または pty_send dispatch 後の ` +
+    `aiterm-wait --session <id> --cursor <event_cursor> をホストのバックグラウンドタスクとして実行し、` +
+    `exit時にreceiptのoutcomeで判定する（${core.AITERM_WAIT_OUTCOME_NOTE}。ポーリング不要）。` +
+    `結果回収は pty_read(agent_transcript:true)。`;
 function registerAgentTool(toolName, kind, desc) {
     const correlatedLaunchSchema = {};
     if (kind === "claude") {
@@ -368,10 +386,17 @@ function registerAgentTool(toolName, kind, desc) {
             provider: z.literal(kind),
             session_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
             managed_completion: z.boolean(),
+            // 起動時 prompt でturnが走っている時だけ非null（additive拡張）。wait_command はそのままホストの
+            // バックグラウンドタスクとして実行できる完了待ちコマンド。
+            event_cursor: z.number().int().nullable(),
+            wait_command: z.string().nullable(),
+            // 初回prompt dispatch後のsubmit座礁観測（additive）。true=composerに残存を確認（submit未成立の疑い）/
+            // false=残存を観測せず（submit成立の保証ではない）/ null=promptなし・argv prompt・判定不能。
+            submit_residue: z.boolean().nullable(),
         },
     }, async ({ prompt, model, reasoning_effort, cwd, session_name, launch_operation_id }) => {
         try {
-            const [sid, hint] = await core.openAgentWithInitialPrompt(kind, {
+            const [sid, hint, eventCursor, submitResidue] = await core.openAgentWithInitialPrompt(kind, {
                 prompt: prompt ?? undefined,
                 model: model ?? undefined,
                 reasoning_effort: reasoning_effort ?? undefined,
@@ -384,6 +409,9 @@ function registerAgentTool(toolName, kind, desc) {
                 provider: kind,
                 session_id: sid,
                 managed_completion: true,
+                event_cursor: eventCursor,
+                wait_command: eventCursor === null ? null : `aiterm-wait --session ${sid} --cursor ${eventCursor}`,
+                submit_residue: submitResidue,
             };
             return {
                 content: [{ type: "text", text: `session_id: ${sid}\n${hint}` }],
@@ -396,14 +424,22 @@ function registerAgentTool(toolName, kind, desc) {
     });
 }
 registerAgentTool("claude_agent", "claude", "【Claude Code (Anthropic)】の対話エージェントTUIを永続端末に起動する。`claude -p`ではなく、" +
-    "同じ利用者可視sessionへpty_sendで継続入力する。常にmanaged（isolated settingsのStop hook）で起動し、完了通知はaiterm-wait、結果はpty_read(agent_transcript)/claude_turnで回収する。");
+    "同じ利用者可視sessionへpty_sendで継続入力する。常にmanaged（isolated settingsのStop hook）で起動する。" +
+    agentCompletionDesc +
+    "Claude の durable turn は claude_turn でも回収できる。");
 registerAgentTool("codex_agent", "codex", "【Codex (OpenAI)】の対話エージェント TUI を永続端末に起動する。実装・レビュー・調査を対話で回す。" +
-    "起動後は pty_read で画面を読み pty_send で操作する。model / reasoning_effort を引数で指定可" +
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model / reasoning_effort を引数で指定可" +
     "（省略時は端末 config／CLI 既定を継承。実効値は起動応答に明示）。");
 registerAgentTool("grok_agent", "grok", "【Grok Build の Grok モデル (既定 grok-4.5)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は対話 TUI 非対応（指定はエラー）。");
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model を引数で指定可。reasoning_effort は対話 TUI 非対応（指定はエラー）。");
 registerAgentTool("composer_agent", "composer", "【Grok Build の Composer モデル (既定 grok-composer-2.5-fast)】の対話エージェント TUI を永続端末に起動する。" +
-    "起動後は pty_read/pty_send で対話操作。model を引数で指定可。reasoning_effort は非対応（指定はエラー）。");
+    "turn は pty_send で送る（自動で非ブロック dispatch になる）。" +
+    agentCompletionDesc +
+    "model を引数で指定可。reasoning_effort は非対応（指定はエラー）。");
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "mcpName": "io.github.kitepon-rgb/aiterm-mcp",
   "description": "AI-driven persistent terminal as a local stdio MCP server (tmux-backed). Holds one local PTY; SSH and containers are just commands you send into it. Also launches interactive Claude/Codex/Grok/Composer agent TUIs in a persistent terminal. Token-reducing reads.",
   "keywords": [