aiterm-mcp 0.30.0 → 0.31.1

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.1] - 2026-09-06
+
+### Fixed
+
+- Grok／Composerがread-only sandboxの適用に失敗して終了した時、入力受付を待ち続けて再送を案内していた。初回promptと通常dispatchの入力受付確認で`GROK_SANDBOX_STARTUP_FAILED`を即時に返し、CLIの原因と未送信を明示する。設定とsandboxは変更しない。
+
+## [0.31.0] - 2026-09-04
+
+### Fixed
+
+- Claude Codeのturnが529 Overloaded等のAPIエラーで打ち切られるとStop hookが走らず、`aiterm-wait`が永久に未完了を返し続けていた（実被弾 2026-09-03: BellTeamのClaude席で70分の待機）。会話記録（`<config dir>/projects/<cwd slug>/<session-id>.jsonl`）に観測開始後に増えた`isApiErrorMessage:true`の行を読み、新しいoutcome `error`（exit 7、`error`にエラー本文）で返す。
+- Grokの`turn_ended outcome=error`を完了境界として扱わず待ち続けていた。同じくoutcome `error`で返す。Cursorは`turn_ended`のstatusを問わず既に終了を返していたため変更なし。Codexはエラー終了の記録形が実測できておらず未対応。
+
 ## [0.30.0] - 2026-09-04
 
 ### Added
@@ -1546,7 +1559,9 @@ prototype (preserved under `prototype/python/` as the porting source and referen
   `ubuntu-latest` for Node 18/20/22, publishing to npm on `v*` tags with
   provenance.
 
-[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...HEAD
+[Unreleased]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.1...HEAD
+[0.31.1]: https://github.com/kitepon/aiterm-mcp/compare/v0.31.0...v0.31.1
+[0.31.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.31...v0.30.0
 [0.29.31]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.30...v0.29.31
 [0.29.30]: https://github.com/kitepon/aiterm-mcp/compare/v0.29.29...v0.29.30

package/README.ja.md

@@ -153,7 +153,7 @@ runtime-error store は canonical dotagents config の `collection.enabled: true
 場合だけ収集し、既定OFF、network送信は行いません。tag起点CIのnpm provenance（OIDC Trusted
 Publishing）で公開し、GitHub Release が Official MCP Registry を再登録します。
 
-**状態:** 開発継続中 · 現行公開版 **v0.30.0** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
+**状態:** 開発継続中 · 現行公開版 **v0.31.1** · 動作対象は Linux · WSL2 · macOS · Windows ネイティブ · MIT · [変更履歴](CHANGELOG.md)。
 
 ### 更新と巻き戻し
 
@@ -193,6 +193,8 @@ pty_read(id, { wait: true })       → 削減済みの出力を読む（完了
 
 `agent_launch`は任意の`write_scope`も受ける。Codex／Grokのread-onlyは`--sandbox read-only`、Cursorは公式`--mode ask`で実効化する。path説明は同等CLI引数がないためdeclaration-only。
 
+Grok／Composerがread-only sandboxの適用を拒否した場合、prompt送信時に`GROK_SANDBOX_STARTUP_FAILED`とCLIの原因を返す。例えばhookのパスにシンボリックリンクがあるとGrok CLIは起動を拒否する。設定の管理元で原因を修正し、対象sessionを`pty_close`して起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。
+
 ```text
 agent_launch({ harness: "codex-cli", session_name: "codex1", cwd: "/repo",
               prompt: "port test/legacy.py to vitest",
@@ -201,7 +203,7 @@ agent_launch({ harness: "codex-cli", 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 0=done / 3=timeout(未完了) / 4=closed。回収は pty_read(agent_transcript:true)
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # exit 0=done / 3=timeout(未完了) / 4=closed / 7=error(APIエラー等でturn打ち切り)。回収は pty_read(agent_transcript:true)
                                     → 操舵し、Codex の次の入力境界で返る
 ```
 

package/README.md

@@ -169,7 +169,7 @@ 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 · current public release **v0.30.0** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
+**Status:** actively maintained · current public release **v0.31.1** · runs on Linux · WSL2 · macOS · native Windows (tmux on POSIX, the tmux-CLI-compatible [psmux](https://github.com/psmux/psmux) on native Windows — no WSL required) · MIT · see the [CHANGELOG](CHANGELOG.md).
 
 ### Update and rollback
 
@@ -215,6 +215,8 @@ The human-readable launch text is accompanied by an `aiterm.agent-launch-result.
 
 `agent_launch` accepts an optional `write_scope`: either `"read-only"` or a human-readable description of writable paths. Codex/Grok use `--sandbox read-only`; Cursor uses its official read-only `--mode ask`. A path description remains declaration-only because these CLI launch surfaces provide no equivalent path allowlist flag.
 
+Grok／Composerがread-only sandboxの適用を拒否した場合、prompt送信時に`GROK_SANDBOX_STARTUP_FAILED`とCLIの原因を返す。hookパスのシンボリックリンクなど、CLIが示した原因を設定の管理元で修正し、対象sessionを`pty_close`して起動し直す。Aitermはsandboxを解除したりhookをコピーしたりしない。
+
 For a correlated Claude turn stopped at `Do you want to proceed?`, use `claude_approval(action: "inspect", ...)` to capture the active operation and SHA-256 screen digest, review the displayed command, then call `respond` with that exact digest and either `approve_once` or `deny`. The relay rechecks the operation and screen under the send lock, never exposes arbitrary input or permanent approval, keeps the active marker intact, and records a prompt-free owner-only receipt. `pty_send(force: true)` does not bypass this boundary.
 
 ```text
@@ -226,7 +228,7 @@ agent_launch({ harness: "codex-cli", 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>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed
+$ aiterm-wait --session codex1 --cursor <event_cursor>   # never in the parent's foreground; exit 0=done, 3=timeout (not done), 4=closed, 7=error (turn aborted by an API error)
 pty_read("codex1", { agent_transcript: true })           → collect the full answer
 ```
 

package/dist/aiterm-wait-cli.js

@@ -2,7 +2,7 @@
 // aiterm-wait — agent turn 完了eventの純リーダー観測CLI。
 // 完了/timeout/close を1行のJSON receiptで返してexitする。lock・PTY・dispatch状態には一切触れない。
 // 親AIホストのバックグラウンドタスクとして起動し、exitを「観測終了の通知」として使う。
-// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 6=rate_limited=harness利用上限 / 1=エラー）。
+// exit≠完了: exit code は outcome を映す（0=done / 5=running=未完了 / 3=timeout=未完了 / 4=closed / 6=rate_limited=harness利用上限 / 7=error=turnがエラー終了 / 1=waiter自身のエラー）。
 // --timeout 0 は待たずに一度だけ観測する照会で、未完了は running（timeout と混同させない）。
 // receipt の outcome が正で、done 以外は未完了。timeout の既定は core の DEFAULT_AGENT_DONE_TIMEOUT（600秒）。
 import { fileURLToPath } from "node:url";
@@ -75,6 +75,7 @@ const OUTCOME_EXIT_CODES = {
     timeout: 3,
     closed: 4,
     rate_limited: 6,
+    error: 7,
 };
 export async function main(argv) {
     const cmd = parseArgs(argv);

package/dist/core.js

@@ -16,9 +16,9 @@ import * as rtk from "./rtk.js";
 import { AitermError, telemetryOwnedFailure, ownTelemetryFailure } from "./errors.js";
 import { isWin, SOCKDIR, tmuxCommand, sendPsmuxPayload, loadPtyBufferChunk, pasteBufferBaseArgs, TMUX_EMPTY_CONFIG, attachCommand, normalizePaneCommand, appendMarkSentinel, settlePaneLog, paneCwdArgument, } from "./tmux-runtime.js";
 import { sleep, currentUid, runtimeStateBase, safeStatSize, readFileRange, writeJson0600, createEmpty0600, shq, LAUNCH_ID_RE, AGENT_DONE_POLL_MS, AGENT_EVENT_MAX_BYTES, assertSessionName, agentsDir, agentEventPath, agentMetadataPath, writeAgentMetadata, AGENT_EVENT_TAIL_BYTES, agentLabel, agentHarness, subagentInstruction, agentLineageFields, } from "./agent-shared.js";
-import { GROK_MODEL_DEFAULTS, realGrokHome, resolveAndValidateGrokAuth, assertGrokModelAvailable, grokEventsTranscript, latestGrokCompletion, observeGrokDone, buildGrokAgentCmd, grokLaunchNote, grokEnvTokens, grokTuiReady, GROK_COMPOSER_MARKER_RE, grokFooterHasConfiguration, grokTranscriptText, createGrokAgentMetadata, } from "./harnesses/grok.js";
+import { GROK_MODEL_DEFAULTS, realGrokHome, resolveAndValidateGrokAuth, assertGrokModelAvailable, grokEventsTranscript, latestGrokCompletion, observeGrokDone, buildGrokAgentCmd, grokLaunchNote, grokEnvTokens, grokTuiReady, assertGrokSandboxNotRejected, GROK_COMPOSER_MARKER_RE, grokFooterHasConfiguration, grokTranscriptText, createGrokAgentMetadata, } from "./harnesses/grok.js";
 import { bindCodexTranscriptSession, latestCodexCompletion, observeCodexDone, buildCodexAgentCmd, codexLaunchNote, codexTuiReady, codexLaunchBlockingDialog, CODEX_COMPOSER_MARKER_RE, codexModelChoice, codexEffortChoice, codexMoreReasoningChoice, codexTranscriptText, createCodexAgentMetadata, } from "./harnesses/codex.js";
-import { OPERATION_ID_RE, CLAUDE_RESULT_MAX_BYTES, CLAUDE_EFFORTS, agentManagedClaudeSettingsPath, agentClaudeResultPath, agentClaudeOperationPath, agentClaudeApprovalReceiptPath, agentClaudeDispatchReceiptPath, validateOperationId, readClaudeResultText, assertClaudeAuthenticationReady, buildClaudeAgentCmd, claudeLaunchNote, claudeTuiReady, CLAUDE_COMPOSER_MARKER_RE, createClaudeAgentMetadata, } from "./harnesses/claude.js";
+import { OPERATION_ID_RE, CLAUDE_RESULT_MAX_BYTES, CLAUDE_EFFORTS, agentManagedClaudeSettingsPath, agentClaudeResultPath, agentClaudeOperationPath, agentClaudeApprovalReceiptPath, agentClaudeDispatchReceiptPath, validateOperationId, readClaudeResultText, assertClaudeAuthenticationReady, buildClaudeAgentCmd, claudeLaunchNote, claudeTuiReady, CLAUDE_COMPOSER_MARKER_RE, createClaudeAgentMetadata, claudeSessionTranscriptPath, claudeApiErrorFromLine, } from "./harnesses/claude.js";
 import { bindCursorTranscriptSession, cursorTurnBoundary, latestCursorCompletion, observeCursorDone, cursorTranscriptText, assertCursorAuthenticationReady, assertCursorModelAvailable, buildCursorAgentCmd, cursorPromptWithLineage, createCursorAgentMetadata, cursorLaunchNote, cursorEffortNavigation, cursorTuiReady, CURSOR_SUBMIT_SEQUENCE, CURSOR_COMPOSER_CONTENT_MARKER_RE, validateCursorModelEffort, } from "./harnesses/cursor.js";
 import { resolveAgentBin, resolveThroughlineBin, runThroughlineHandoffContext, isWindowsNativeExecutable, agentBinForPaneShell, resolveWinPaneShell } from "./agent-resolver.js";
 export { AitermError } from "./errors.js";
@@ -2251,7 +2251,7 @@ function assertInitialPromptNotPendingForSend(name, force) {
         `${agentWaitGuide(name)}完了後に再度 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以外は未完了`;
+export const AITERM_WAIT_OUTCOME_NOTE = `exit 0=done / 3=timeout（既定${DEFAULT_AGENT_DONE_TIMEOUT}秒・未完了） / 4=closed / 7=error（harnessの記録でturnがAPIエラー等で打ち切られた。結果は無い）。receiptのoutcomeが正で、done以外は未完了`;
 function quoteWindowsProcessArgument(value) {
     if (value !== "" && !/[\s"]/u.test(value))
         return value;
@@ -2393,7 +2393,12 @@ export async function observeAgentDone(name, o = {}) {
     let cursor = startOffset;
     let carry = "";
     let malformedEvents = 0;
-    const observation = (outcome, ev = null, rateLimit = null) => ({
+    // Claudeの会話記録はこの観測開始時点の末尾から先だけを読む。過去turnのAPIエラー行を今回の
+    // 終了と誤認しないため。dispatch直後に待機を始める親（receiptのwait_process）を前提にする。
+    const transcriptFile = claudeSessionTranscriptPath(meta);
+    let transcriptCursor = transcriptFile ? safeStatSize(transcriptFile) : 0;
+    let transcriptCarry = "";
+    const observation = (outcome, ev = null, rateLimit = null, apiError = null) => ({
         schema: "aiterm.agent-wait-result.v1",
         session_id: meta.aiterm_session,
         launch_id: meta.launch_id,
@@ -2404,8 +2409,9 @@ export async function observeAgentDone(name, o = {}) {
         vendor_session_id: ev?.vendor_session_id ?? meta.vendor_session_id ?? null,
         turn_id: ev?.turn_id ?? null,
         malformed_events: malformedEvents,
-        at: ev?.at ?? null,
+        at: ev?.at ?? apiError?.at ?? null,
         rate_limit: rateLimit,
+        error: apiError?.text ?? null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))
@@ -2431,6 +2437,24 @@ export async function observeAgentDone(name, o = {}) {
             if (scanned.event)
                 return observation("done", scanned.event);
         }
+        if (transcriptFile && fs.existsSync(transcriptFile)) {
+            const transcriptSize = safeStatSize(transcriptFile);
+            if (transcriptSize < transcriptCursor) {
+                transcriptCursor = 0;
+                transcriptCarry = "";
+            }
+            if (transcriptSize > transcriptCursor) {
+                transcriptCarry += readFileRange(transcriptFile, transcriptCursor, transcriptSize).toString("utf8");
+                transcriptCursor = transcriptSize;
+                const lines = transcriptCarry.split("\n");
+                transcriptCarry = lines.pop() ?? "";
+                for (const line of lines) {
+                    const apiError = claudeApiErrorFromLine(line);
+                    if (apiError)
+                        return observation("error", null, null, apiError);
+                }
+            }
+        }
         // timeout=0 は「待たずに一度だけ見る」照会＝未完了は失敗ではなく running。
         // 1秒以上を指定した待機の未完了は従来どおり timeout で、待ち方の意味は変えない。
         {
@@ -2518,6 +2542,8 @@ async function waitAgentTuiReadyImpl(kind, sample, sleepFn, opts = {}) {
     for (;;) {
         lastScreen = sample();
         samples++;
+        if (kind === "grok" || kind === "composer")
+            assertGrokSandboxNotRejected(lastScreen);
         if (isAgentTuiIdleReady(kind, lastScreen)) {
             readyStreak++;
             if (readyStreak >= stableSamples)

package/dist/harnesses/claude.js

@@ -2,6 +2,7 @@
 // core 所有のサービス（transcript 不在エラー）は引数で注入し、
 // 依存方向を core → harnesses → agent-shared の一方向に保つ。
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -216,3 +217,45 @@ export function createClaudeAgentMetadata(name, cwd, initialPrompt, launchOperat
     writeAgentMetadata(meta);
     return meta;
 }
+// ---------------------------------------------------------------- APIエラー終了の検知（会話記録）
+// Claude CodeはAPIエラー（529 Overloaded等）でturnを打ち切る時、Stop hookを走らせない。
+// 代わりに会話記録（<config dir>/projects/<cwd slug>/<session-id>.jsonl）へ
+// `type:"assistant", isApiErrorMessage:true, apiErrorStatus:<code>` の1行を書く（実測 2026-09-03、
+// BellTeamのチャイム席で70分の待機を生んだ529）。完了eventだけを待つと永久に running になるため、
+// dispatch後に増えた記録行からこの印を読み、outcome=error として親へ返す。
+export function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR ?? path.join(process.env.HOME ?? os.homedir(), ".claude");
+}
+// Claude Codeのproject slug: cwdの英数字以外を1文字ずつ "-" にする（実測: "/Users/kite/.throughline-x" → "-Users-kite--throughline-x"）。
+export function claudeProjectSlug(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+export function claudeSessionTranscriptPath(meta) {
+    if (meta.kind !== "claude" || !meta.vendor_session_id)
+        return null;
+    return path.join(claudeConfigDir(), "projects", claudeProjectSlug(meta.cwd ?? process.cwd()), `${meta.vendor_session_id}.jsonl`);
+}
+export function claudeApiErrorFromLine(line) {
+    if (!line.trim())
+        return null;
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (record?.type !== "assistant" || record?.isApiErrorMessage !== true)
+        return null;
+    const content = record?.message?.content;
+    const text = typeof content === "string"
+        ? content
+        : Array.isArray(content)
+            ? content.map((part) => (typeof part?.text === "string" ? part.text : "")).join("")
+            : "";
+    const status = record?.apiErrorStatus;
+    return {
+        text: text.trim() || (status != null ? `API Error: ${String(status)}` : "API Error"),
+        at: typeof record?.timestamp === "string" ? record.timestamp : null,
+    };
+}

package/dist/harnesses/codex.js

@@ -272,6 +272,7 @@ export async function observeCodexDone(meta, timeout, requestedCursor, detectRat
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))

package/dist/harnesses/cursor.js

@@ -202,6 +202,7 @@ export async function observeCursorDone(meta, timeout, requestedCursor, detectRa
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))

package/dist/harnesses/grok.js

@@ -81,7 +81,7 @@ export function grokEventsTranscript(meta) {
 export function grokCompletionEvent(meta, record) {
     if ((meta.kind !== "grok" && meta.kind !== "composer") ||
         record?.type !== "turn_ended" ||
-        (record?.outcome !== "completed" && record?.outcome !== "cancelled"))
+        (record?.outcome !== "completed" && record?.outcome !== "cancelled" && record?.outcome !== "error"))
         return null;
     const turnId = typeof record?.ts === "string" || typeof record?.ts === "number" ? String(record.ts) : null;
     return {
@@ -93,7 +93,9 @@ export function grokCompletionEvent(meta, record) {
         turn_id: turnId,
         operation_id: null,
         reason: `Grok transcript turn_ended:${record.outcome}`,
-        done_status: "turn_done",
+        // Grok CLIはAPIエラー等でturnを打ち切る時も turn_ended を書き、outcome だけが error になる
+        // （実測: 手元の events.jsonl に outcome=error が17件）。完了と同じ境界だが結果は無い。
+        done_status: record.outcome === "error" ? "turn_error" : "turn_done",
         stop_hook_active: false,
         at: typeof record?.ts === "string" ? record.ts : new Date().toISOString(),
     };
@@ -166,6 +168,7 @@ export async function observeGrokDone(meta, timeout, requestedCursor, detectRate
         malformed_events: malformedEvents,
         at: ev?.at ?? null,
         rate_limit: rateLimit,
+        error: ev?.done_status === "turn_error" ? ev.reason : null,
     });
     for (;;) {
         if (!fs.existsSync(metadataFile))
@@ -204,7 +207,7 @@ export async function observeGrokDone(meta, timeout, requestedCursor, detectRate
                     try {
                         const done = grokCompletionEvent(meta, JSON.parse(line));
                         if (done)
-                            return observation("done", done);
+                            return observation(done.done_status === "turn_error" ? "error" : "done", done);
                     }
                     catch {
                         malformedEvents++;
@@ -259,6 +262,17 @@ export function grokEnvTokens(meta) {
         "GROK_DISABLE_AUTOUPDATER=1",
     ];
 }
+export function assertGrokSandboxNotRejected(screen) {
+    // Grok 1.0.13はsandboxを適用できないと入力欄を作らず終了する。
+    // CLIが確定した拒否だけを拾い、警告単独や入力欄の引用では判定しない。
+    const failure = screen.match(/^[ \t]*error: could not apply the 'read-only' sandbox profile;[^\n]*/m);
+    if (!failure)
+        return;
+    const warning = screen.match(/^[ \t]*warning: sandbox could not be applied:[\s\S]*?(?=\n[ \t]*error:)/m);
+    throw new AitermError("GROK_SANDBOX_STARTUP_FAILED: Grok CLIがread-only sandboxを適用できず起動を拒否しました。文字列は送信していません。\n" +
+        `${warning?.[0] ?? ""}\n${failure[0]}\n` +
+        "CLIが示した設定の問題を、その設定の管理元で修正してください。修正後はpty_closeで対象sessionを閉じ、agent_launchで起動し直してください。", 2);
+}
 export function grokTuiReady(screen) {
     // Grok Build 0.2.117 は起動完了後に製品名を消し、model footerだけを残す。
     // Composerも同じfrontendでmodel名だけが異なるため、両方をharness UIの根拠にする。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiterm-mcp",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "mcpName": "io.github.kitepon/aiterm-mcp",
   "description": "Persistent terminal MCP with one harness-based launcher for Claude Code, Codex CLI, Grok CLI, and Cursor Agent CLI, plus durable PTYs for SSH, containers, and REPLs.",
   "keywords": [