aiterm-mcp 0.19.3 → 0.20.0

package/README.md

@@ -326,6 +326,8 @@ As of v0.16 a parent agent **never blocks** on aiterm — there is no wait param
 3. **The parent never runs the waiter in its own foreground.** Waiting is correct — but the waiter is a separate process, not the parent's turn. 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. So that this is not left to interpretation, aiterm reads `clientInfo.name` from the MCP `initialize` handshake and its receipts name the concrete invocation for the detected host — for Claude Code, literally `Bash(command: "aiterm-wait …", run_in_background: true)`. Unknown or undeclared hosts get the generic "start it as a process that does not block the parent's turn" wording; nothing else about the contract changes. Every receipt leads with the same rule: dispatch and let go, then go do something else or end the turn.
 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.
 
+**If your host has no completion push** (no mechanism that re-invokes the agent when a background process exits), `--timeout 0` is a one-shot check instead of a wait: it scans the event file once and returns `running` (exit `5`) when the turn is still in flight, `done` (exit `0`) when it finished, `closed` (exit `4`) when the session is gone. It is deliberately absent from the receipts and tool descriptions — a host that *does* get pushed should be woken, not poll. An unknown session name is an error, never `running`, so a typo cannot masquerade as a child that is still working.
+
 `aiterm-wait` takes no locks, never writes session state, and never dispatches — any number can run beside the MCP server and each other, and `pty_close`/concurrent sends are unaffected.
 
 ### Token reduction

package/dist/aiterm-wait-cli.js

@@ -2,14 +2,16 @@
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
 // 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
-// exit≠完了: exit code は outcome を映す（0=done / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 1=エラー）。
+// --timeout 0 は待たずに一度だけ観測する照会で、未完了は running（timeout と混同させない）。
 // 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";
 const SESSION_RE = /^[A-Za-z0-9_-]{1,64}$/;
 const OPERATION_RE = /^sha256:[0-9a-f]{64}$/;
-const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]";
+const USAGE = "usage: aiterm-wait --session <name> [--cursor <event_cursor>] [--operation sha256:<64hex>] [--timeout <sec>]" +
+    "（--timeout 0 は待たずに一度だけ観測する照会で、未完了は outcome=running / exit 5）";
 export function parseArgs(argv) {
     let session = null;
     let operationId = null;
@@ -65,7 +67,14 @@ 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 };
+// Record で全 outcome を型に強制する: 語を足して対応表を直し忘れると undefined→exit 0 になり、
+// 「まだ終わっていない」が「完了」として親へ届く。その取りこぼしを compile error で止める。
+const OUTCOME_EXIT_CODES = {
+    done: 0,
+    running: 5,
+    timeout: 3,
+    closed: 4,
+};
 export async function main(argv) {
     const cmd = parseArgs(argv);
     const result = await observeAgentDone(cmd.session, {

package/dist/core.js

@@ -2938,8 +2938,10 @@ export async function observeAgentDone(name, o = {}) {
             if (scanned.event)
                 return observation("done", scanned.event);
         }
+        // timeout=0 は「待たずに一度だけ見る」照会＝未完了は失敗ではなく running。
+        // 1秒以上を指定した待機の未完了は従来どおり timeout で、待ち方の意味は変えない。
         if (performance.now() >= deadline)
-            return observation("timeout");
+            return observation(timeout === 0 ? "running" : "timeout");
         await sleep(AGENT_DONE_POLL_MS);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.19.3",
+  "version": "0.20.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": [