#!/usr/bin/env bun /** * claude-pty — drop-in replacement for `claude -p --output-format stream-json` * that runs Claude Code in INTERACTIVE mode under a pseudo-terminal instead of print * mode, while emitting the same stream-json lines on stdout. * * Why: print mode (-p) ends the process at the first end_turn even when background * tasks (Bash run_in_background / watch tasks) are still running, so the agent never * gets the "task completed" wake-up. Interactive mode keeps the session alive and the * harness re-invokes the model when a background task finishes. This wrapper: * * 1. accepts the exact CLI shape the satellite already uses: * claude-pty -p --output-format stream-json --verbose \ * --dangerously-skip-permissions [--add-dir X] [...] * (print-only flags are stripped; everything else is passed through) * 2. spawns claude under a PTY (`sh -c 'cat | script -q /dev/null * claude '`) with a scrubbed env and a fixed --session-id * 3. tails the session transcript ~/.claude/projects//.jsonl and * re-emits user/assistant frames as `claude -p --output-format stream-json * --verbose` would * 4. tracks background tasks (started / completed) from the transcript; the run is * finished at the first end_turn with ZERO running background tasks, after which * it emits a final {"type":"result"} frame, sends /exit to the TUI and reaps it * 5. auto-dismisses interactive blockers: AskUserQuestion / ExitPlanMode tool_uses * with no tool_result get an Enter keypress (selects the recommended option), * and an --append-system-prompt tells the model not to ask in the first place. * * Self-contained: no global config writes. The one-time interactive dialogs are * bypassed via an inline --settings JSON (bypass-permissions consent) and the * CLAUDE_CODE_SANDBOXED=1 env (workspace trust) — see buildFlagSettings(). * * Env knobs: * CLAUDE_PTY_BIN real claude binary (default "claude") * CLAUDE_PTY_SETTINGS path to a settings JSON merged into the injected * --settings (default: claude-pty.settings.json * next to this script, if present) * CLAUDE_PTY_IDLE_TIMEOUT_MS idle window after a turn ends (default 0 = OFF: * wait forever, exactly like interactive claude — * run termination belongs to the caller's sentinel * watchdog / hard timeout / abort). When set >0, * expiry checks GROUND TRUTH via lsof on each * task's .output file: writers alive → extend * (long builds survive any duration); all dead → * wedge grace then finalize (claude wedged); * liveness unknown → finalize after the window * CLAUDE_PTY_WEDGE_GRACE_MS grace for late notifications after all bg * writers died (default 2 min; only with idle >0) * CLAUDE_PTY_HARD_TIMEOUT_MS absolute cap on the whole run (default 0 = off; * the caller usually has its own watchdog) * CLAUDE_PTY_STALL_NUDGE_MS how long the transcript may make zero forward * progress before we inject "继续" (default 20 min; * 0 = off). Fires even mid-turn: a hung socket and * a prompt sitting idle look the same from here, * and a queued "继续" is harmless if the model was * actually still working. Bounded by * CLAUDE_PTY_MAX_STALL_NUDGES so the runner's 1h * stall-kill remains the backstop. * CLAUDE_PTY_MAX_STALL_NUDGES cap on those stall "继续" injections (default 3) * CLAUDE_PTY_SUBMIT_RETRIES extra Enters sent when an injected message has not * echoed back yet (default 6; api-error then * finalizes, stall-nudge just gives up this attempt) * CLAUDE_PTY_SUBMIT_INTERVAL_MS gap between those Enters (default 1500) * CLAUDE_PTY_DEBUG=1 mirror PTY screen output + wrapper decisions to stderr */ import { spawn, type Subprocess } from "bun"; import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync, writeSync, } from "node:fs"; import { homedir } from "node:os"; import path from "node:path"; import { randomUUID } from "node:crypto"; import { AGENT_SESSION_KIND_ENV, recordAgentSessionIdFromEnv } from "../shared/src/agent_session"; import { securityUsageLimitMessage } from "../shared/src/security_agent_failure"; const REAL_CLAUDE = process.env.CLAUDE_PTY_BIN || "claude"; /** Numeric knob: a non-numeric value ("1500ms") would otherwise yield NaN, and every * comparison against NaN is false — enough to disable a timer or strand a retry loop. */ function envNum(name: string, def: number): number { const raw = process.env[name]; if (raw === undefined || raw === "") return def; const n = Number(raw); return Number.isFinite(n) ? Math.max(0, n) : def; } const IDLE_TIMEOUT_MS = envNum("CLAUDE_PTY_IDLE_TIMEOUT_MS", 0); const HARD_TIMEOUT_MS = envNum("CLAUDE_PTY_HARD_TIMEOUT_MS", 0); const DEBUG = process.env.CLAUDE_PTY_DEBUG === "1"; const CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), ".claude"); function dbg(msg: string) { if (DEBUG) console.error(`[claude-pty] ${msg}`); } // ── arg parsing ─────────────────────────────────────────────────────────── // Strip print-only flags, capture the prompt (from -p value or positional), // pass everything else through to interactive claude. function parseArgs(argv: string[]): { prompt: string; passthrough: string[]; sessionUuid: string | null; resumeUuid: string | null; } { const passthrough: string[] = []; let prompt: string | null = null; let sessionUuid: string | null = null; let resumeUuid: string | null = null; const FLAGS_WITH_VALUE = new Set([ "--output-format", "--input-format", "--fallback-model", "--max-budget-usd", "--json-schema", ]); const DROP_BARE = new Set(["--verbose", "--print", "-p", "--include-partial-messages", "--replay-user-messages", "--no-session-persistence"]); for (let i = 0; i < argv.length; i++) { const a = argv[i]; if (a === "-p" || a === "--print") { // `claude -p `: the value right after -p is the prompt (the // satellite always calls it this way). If the next token is another // flag, -p was bare and the prompt is positional. const next = argv[i + 1]; if (next !== undefined && !next.startsWith("-")) { prompt = next; i++; } continue; } if (a === "--session-id") { sessionUuid = argv[++i] ?? null; continue; } if (a === "--resume") { resumeUuid = argv[++i] ?? null; continue; } if (DROP_BARE.has(a)) continue; if (FLAGS_WITH_VALUE.has(a)) { i++; continue; } if (FLAGS_WITH_VALUE.has(a.split("=")[0])) continue; if (!a.startsWith("-") && prompt === null) { prompt = a; continue; } passthrough.push(a); } if (prompt === null) { console.error("claude-pty: no prompt found in args"); process.exit(2); } if (sessionUuid && resumeUuid) { console.error("claude-pty: --session-id and --resume are mutually exclusive"); process.exit(2); } return { prompt, passthrough, sessionUuid, resumeUuid }; } // ── interactive one-time dialogs ────────────────────────────────────────── // Interactive mode pops dialogs that would deadlock a headless PTY. None of them // needs a ~/.claude.json mutation (verified against the 2.1.176 bundle, keys // re-checked against 2.1.259): // - bypass-permissions consent → settings key `skipDangerousModePermissionPrompt` // is honored from flagSettings, i.e. an inline `--settings` JSON. // - workspace trust dialog → `CLAUDE_CODE_SANDBOXED=1` env short-circuits the // trust check (its only functional use in the binary). // - project MCP approval → settings key `enableAllProjectMcpServers`, below. // So the wrapper stays self-contained: deployable with the repo, no global // config writes. Project-local overrides can ship alongside the script in // claude-pty.settings.json (or a file pointed at by CLAUDE_PTY_SETTINGS). function buildFlagSettings(passthrough: string[]): string { const settings: Record = { skipDangerousModePermissionPrompt: true, // A project `.mcp.json` pops "New MCP server found in this project: " // and BLOCKS on it — before the session exists, so before there is any // transcript for the auto-dismiss logic below to see. Measured on // evaluator-android-01, 2026-09-09: 8 consecutive evaluations died on `actl` // at exactly 120s with reason=transcript-missing and num_turns=0. // // Answering it by hand once does NOT help, for two independent reasons: // - the answer is written to the PROJECT's .claude/settings.local.json, and // localSettings is skipped entirely unless that project is trusted/ungated // (CLAUDE_CODE_SANDBOXED short-circuits the trust DIALOG, not the settings // gate), so it is never read back — the dialog returns every launch; // - eval worktrees live at eval-worktrees/, a fresh path per task, so a // per-project answer would not carry to the next task anyway. // flagSettings is always in the honored source list, so this is the one place // the approval sticks. It is also what the pipeline needs: `actl` IS the // device-control server the evaluators drive the phone with, and the dialog's // highlighted default ("Continue without using this MCP server") is the one // answer that would silently strip it. enableAllProjectMcpServers: true, // Remote-control mirroring re-routes transcript persistence; force it off // unless the caller explicitly asked for --remote-control. ...(passthrough.includes("--remote-control") ? {} : { remoteControlAtStartup: false }), }; if (passthrough.includes("--settings")) { // commander keeps the LAST --settings value; the caller's would silently // replace ours (and the dialog-skip keys with it). Surface that loudly. console.error("claude-pty: warning: caller passed --settings; it overrides the injected dialog-skip settings"); } // 候选路径按顺序取第一个存在的。第三条是折进 bundle 之后补的兼容位:`import.meta.dir` // 从源码跑是 `/bin/`,被打进 bundle 后变成 `/satellite/dist/`,只留第二条 // 会让节点上已有的 `bin/claude-pty.settings.json` 在某次部署后**悄悄不再生效**—— // 这类静默失效正是把 wrapper 折进 bundle 要消灭的东西,不该在搬家时自己制造一个。 const overrideCandidates = [ process.env.CLAUDE_PTY_SETTINGS, path.join(import.meta.dir, "claude-pty.settings.json"), path.join(import.meta.dir, "../../bin/claude-pty.settings.json"), ].filter((p): p is string => !!p); for (const overridePath of overrideCandidates) { try { if (!existsSync(overridePath)) continue; Object.assign(settings, JSON.parse(readFileSync(overridePath, "utf8"))); dbg(`merged settings overrides from ${overridePath}`); break; } catch (e) { dbg(`ignoring unreadable settings override ${overridePath}: ${(e as Error).message}`); } } return JSON.stringify(settings); } // ── env scrubbing ───────────────────────────────────────────────────────── // If the wrapper itself runs under a Claude Code session (CLAUDECODE=1 / // CLAUDE_CODE_CHILD_SESSION=1 leak through), the child believes it's a managed // subprocess and SKIPS local transcript persistence — which is our only data // channel. Scrub everything session-identifying. function cleanEnv(): Record { const env: Record = {}; for (const [k, v] of Object.entries(process.env)) { if (v === undefined) continue; if (/^(CLAUDECODE|CLAUDE_CODE_(SSE_PORT|ENTRYPOINT|SESSION_ID|CHILD_SESSION|EXECPATH|SIMPLE|SAFE_MODE)|AI_AGENT|CLAUDE_EFFORT)$/.test(k)) continue; env[k] = v; } env.TERM = "xterm-256color"; // Skips the interactive workspace-trust dialog (sole functional use of this // var in the CLI bundle) — no per-project ~/.claude.json writes needed. env.CLAUDE_CODE_SANDBOXED = "1"; return env; } // ── stream-json emission ────────────────────────────────────────────────── const t0 = Date.now(); let numTurns = 0; function emit(obj: Record) { process.stdout.write(JSON.stringify(obj) + "\n"); } // ── transcript tailer ───────────────────────────────────────────────────── class TranscriptTail { private offset: number; private floorOffset: number; private partial = ""; constructor(public filePath: string, initialOffset = 0) { this.offset = initialOffset; this.floorOffset = initialOffset; } private read(start: number, len: number): { text: string; bytes: number } { const fd = openSync(this.filePath, "r"); try { const buf = Buffer.alloc(len); const n = readSync(fd, buf, 0, len, start); return { text: buf.toString("utf8", 0, n), bytes: n }; } finally { closeSync(fd); } } /** Read any newly appended complete lines. */ readNew(): string[] { let size: number; try { size = statSync(this.filePath).size; } catch { return []; } if (size <= this.offset) return []; const { text, bytes } = this.read(this.offset, size - this.offset); this.offset += bytes; const lines = (this.partial + text).split("\n"); this.partial = lines.pop() ?? ""; return lines.filter((l) => l.trim()); } /** Last `maxBytes` of the file, without disturbing readNew's cursor. */ readTail(maxBytes: number): string { let size: number; try { size = statSync(this.filePath).size; } catch { return ""; } const start = Math.max(this.floorOffset, size - maxBytes); return this.read(start, size - start).text; } } /** ANSI/OSC-stripped, blank-collapsed tail of a PTY screen dump, for logs. */ function visibleScreenTail(raw: string, maxChars = 1500): string { const text = raw .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "") // OSC .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // CSI .replace(/\x1b[()][A-Z0-9]/g, "") // charset selection .replace(/\x1b[=>]/g, "") .replace(/\r/g, "\n"); const lines = text.split("\n").map((l) => l.trimEnd()).filter((l) => l.trim()); return lines.join("\n").slice(-maxChars); } /** First `n` non-empty lines, joined so they fit one log line / reason field. */ function firstLines(text: string, n: number): string { return text.split("\n").filter((l) => l.trim()).slice(0, n).join(" | ").slice(0, 200); } /** * Every settings file claude reads at startup: the user config dir, then * `.claude/` in cwd and each ancestor up to $HOME — claude resolves the project * root by walking up, so an ancestor's file counts (an eval worktree has no * `.claude/` of its own; the workspace two levels up does). */ function settingsFileCandidates(cwd: string): string[] { const out = [path.join(CONFIG_DIR, "settings.json"), path.join(CONFIG_DIR, "settings.local.json")]; const home = homedir(); let dir = cwd; for (let i = 0; i < 12; i++) { out.push(path.join(dir, ".claude", "settings.json"), path.join(dir, ".claude", "settings.local.json")); if (dir === home || dir === path.dirname(dir)) break; dir = path.dirname(dir); } return out; } /** * ONE malformed settings file stops claude on a modal ("Settings Error … Invalid * or malformed JSON / 1. Fix with Claude / 2. Exit / 3. Continue without these * settings") before the session starts, which from out here is indistinguishable * from any other 120s hang. Typing our way past it is not an option — the * highlighted default is "Fix with Claude", i.e. an interactive repair session — * so fail in 0s naming the file instead of burning two minutes and an attempt. * Observed on evaluator-android-01, 2026-09-09: a trailing comma in * ~/.claude/settings.json, on a node where nothing else was wrong. */ function malformedSettingsFiles(cwd: string): string[] { const bad: string[] = []; for (const f of settingsFileCandidates(cwd)) { if (!existsSync(f)) continue; try { JSON.parse(readFileSync(f, "utf8")); } catch { if (!bad.includes(f)) bad.push(f); } } return bad; } /** Find the transcript file for sessionId under any project dir. */ function findTranscript(sessionId: string): string | null { const projects = path.join(CONFIG_DIR, "projects"); let dirs: string[] = []; try { dirs = readdirSync(projects); } catch { return null; } for (const d of dirs) { const p = path.join(projects, d, `${sessionId}.jsonl`); if (existsSync(p)) return p; } return null; } // ── per-step timing sidecar ─────────────────────────────────────────────── /** * 每一次工具调用花了多久,以及调用之间模型想了多久 —— 写到一份旁路文件,不进会话日志。 * * ## 为什么必须插桩,而不是事后从日志里算 * * 2026-09-17 想回答「一轮的时间到底花在哪一步」,三条路全断: * * 1. 对 109 轮做非负最小二乘(轮时长 ~ 各类调用次数),R²=0.635 看着还行,但系数是 * 共线性假象 —— 跑出「记录 Conditions 每次 3.8 分钟」(实际瞬时)、「等待/轮询 * 每次 0 分钟」(实际它就是在等)。弃用。 * 2. `duration_api_ms` 在这个版本里恒等于 `duration_ms`,`num_turns` 恒为 1 —— 数据是坏的。 * 3. 会话日志(stream-json)**没有逐条时间戳**。 * * 结论和 ClawTrace(arXiv:2604.23853)一致:这个信号只能靠插桩记,事后补不出来。 * 没有它,就分不清「补一步来修 bug」和「删掉一步不影响结果的贵操作」。 * * ## 为什么落在这里 * * 这个 wrapper 本来就在逐条读 Claude Code 的 transcript 并重发 stream-json, * `pendingToolUses` 已经在做 tool_use ↔ tool_result 的配对 —— 计时只是给它加一个 * 时间戳字段。反过来,若在卫星侧做,就得把多 MB 的字节流引进那个单进程的事件循环, * 而它被同步 git 堵住 167 秒的事故刚过去一周(见 satellite/src/git_exec.ts)。 * * ## 两条设计约束 * * - **时刻取自 transcript 条目自带的 `timestamp`**,不是我们观察到它的时刻 —— * tailer 是轮询的,用 `Date.now()` 会把轮询延迟算进每一步。拿不到才退回本地时钟。 * - **不设,则完全不做事**(连文件都不开)。计时是观测,不该改变被观测的东西; * 环境变量没给就是零开销。 */ const STEP_TIMING_PATH = process.env.STREAMLINE_STEP_TIMING || ""; /** * 完整模式(只在 RSI 实验机的复跑任务上开,STREAMLINE_STEP_TIMING_FULL=1):命令留 4000 字而不是 * 200 字,另记工具发起的绝对时刻 `ts` 和结果末尾 300 字 `r`。2026-10 算业务指标时发现,200 字 * 截断让六成 record-evidence 命令看不出输出文件名;实验机不接生产任务,记全的代价只落在本机磁盘。 */ const STEP_TIMING_FULL = process.env.STREAMLINE_STEP_TIMING_FULL === "1"; let stepFd: number | null = null; let stepSeq = 0; let lastStepEndAt = 0; // 上一次 tool_result 的时刻 —— 到下一次 tool_use 之间就是模型在想 /** 这一步在动什么。只留可复盘的那点信息,截断;和 SessionDigest 的失败命令同一尺度。 */ function stepArg(name: string, input: Record): string { const pick = name === "Bash" ? input.command : (name === "Read" || name === "Write" || name === "Edit" || name === "NotebookEdit") ? input.file_path : name === "Grep" ? input.pattern : name === "Glob" ? input.pattern : name === "Skill" ? input.skill : input.description; return String(pick ?? "").replace(/\s+/g, " ").trim().slice(0, STEP_TIMING_FULL ? 4000 : 200); } /** tool_result 的正文末尾(完整模式用)。 */ function resultTail(content: unknown): string { const text = typeof content === "string" ? content : Array.isArray(content) ? content.map((b) => (b && typeof b === "object" && "text" in b ? String((b as { text: unknown }).text) : "")).join("\n") : ""; return text.replace(/\s+/g, " ").trim().slice(-300); } function recordStep(tu: ToolUse, endAt: number, ok: boolean, result?: unknown): void { if (!STEP_TIMING_PATH) return; try { if (stepFd == null) stepFd = openSync(STEP_TIMING_PATH, "a"); const rec = { i: ++stepSeq, t: tu.name, // 工具自己跑了多久。<0 不可能,但 transcript 时间戳来自不同进程,钳一下更稳。 ms: Math.max(0, endAt - tu.at), // 上一步结束到这一步发起之间 —— 模型思考 + 生成的时间。首步为 null。 gap: lastStepEndAt ? Math.max(0, tu.at - lastStepEndAt) : null, ok, a: stepArg(tu.name, tu.input), ...(STEP_TIMING_FULL ? { ts: tu.at, r: resultTail(result) } : {}), }; writeSync(stepFd, JSON.stringify(rec) + "\n"); lastStepEndAt = endAt; } catch { /* 计时写不动不该影响执行 —— 观测永远让位于被观测的东西 */ } } // ── background-task + interaction tracking ─────────────────────────────── interface ToolUse { id: string; name: string; input: Record; at: number; } interface BgTask { desc: string; out?: string; } // out = task .output file (liveness probe target) const runningBg = new Map(); // bg task id -> info const pendingToolUses = new Map(); // tool_use id -> info (no result yet) const pendingQuestions = new Map(); // AskUserQuestion-ish tool_use id -> first-seen ts let sawEndTurnAfterBgDrain = false; let lastAssistantText = ""; let lastTranscriptActivity = Date.now(); let turnEndedWhileBgRunning = false; let lastEndTurnMsgId = ""; // one API message = several transcript entries (thinking/text), all carrying the same stop_reason let pendingSubmit: { attempts: number; nextAt: number; kind: "api-error" | "stall-nudge" } | null = null; let promptEchoSkipped = false; // `claude -p` does not emit the initial prompt as a user frame // Cumulative usage for the final result frame, like -p reports. One API message // appears as several transcript entries sharing message.id — count each once. const usageSeenMsgIds = new Set(); const totalUsage: Record = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0, }; // True while a turn is in flight (user message injected / model responding / // foreground tool executing). The idle timeout must NOT fire in this state: a // foreground clean build legitimately keeps the transcript silent for 30-60min // and the turn only "ends" at the next end_turn / turn_duration marker. let turnOpen = false; let allDeadSince = 0; // first time we saw idle + every undrained bg writer dead const WEDGE_GRACE_MS = envNum("CLAUDE_PTY_WEDGE_GRACE_MS", 120_000); const BG_START_RES = [ /running in background with ID:?\s*([\w-]+)/i, /background task (?:started|launched)[^\w]*(?:id:?\s*)?([\w-]+)/i, /([\w-]+)<\/task-id>/, /Monitor started \(task ([\w-]+)/i, // "Monitor started (task bad2ttc94, timeout 300000ms)" /task id:?\s*([\w-]+)/i, ]; const BG_DONE_RES = [ /([\w-]+)<\/task-id>[\s\S]*?(?:completed|failed|killed|aborted)<\/status>/, /background (?:task|command|bash)\s+([\w-]+)[^\n]*\((?:status: )?(?:completed|failed|killed|exited)/i, ]; function contentToText(content: unknown): string { if (typeof content === "string") return content; if (Array.isArray(content)) { return content .map((c) => (c && typeof c === "object" && typeof (c as any).text === "string" ? (c as any).text : "")) .join("\n"); } return ""; } /** Inspect one transcript entry; update bg/question/turn state. */ function track(entry: any) { // 条目自带的时刻优先:tailer 是轮询的,用本地 now() 会把轮询延迟算进每一步。 const entryAt = (() => { const t = typeof entry?.timestamp === "string" ? Date.parse(entry.timestamp) : NaN; return Number.isFinite(t) ? t : Date.now(); })(); const msg = entry.message; if (entry.type === "assistant" && msg?.content) { turnOpen = !(msg.stop_reason === "end_turn" || msg.stop_reason === "stop_sequence"); if (msg.usage && typeof msg.id === "string" && !usageSeenMsgIds.has(msg.id)) { usageSeenMsgIds.add(msg.id); for (const k of Object.keys(totalUsage)) { if (typeof msg.usage[k] === "number") totalUsage[k] += msg.usage[k]; } } const texts: string[] = []; for (const c of msg.content) { if (c.type === "tool_use") { pendingToolUses.set(c.id, { id: c.id, name: c.name, input: c.input ?? {}, at: entryAt }); if (c.name === "AskUserQuestion" || c.name === "ExitPlanMode") { pendingQuestions.set(c.id, Date.now()); dbg(`interactive blocker detected: ${c.name} (${c.id})`); } if (c.name === "KillShell" || c.name === "TaskStop") { const id = String(c.input?.shell_id ?? c.input?.task_id ?? ""); if (id && runningBg.delete(id)) dbg(`bg ${id} removed via ${c.name}`); } } else if (c.type === "text" && typeof c.text === "string") { texts.push(c.text); } } if (texts.length) lastAssistantText = texts.join("\n").trim() || lastAssistantText; if ((msg.stop_reason === "end_turn" || msg.stop_reason === "stop_sequence") && msg.id !== lastEndTurnMsgId) { lastEndTurnMsgId = msg.id; numTurns++; onTurnEnd("stop_reason=" + msg.stop_reason); } } else if (entry.type === "user" && msg?.content) { turnOpen = true; // prompt / tool_result / injected notification → model gets (re)invoked if (pendingSubmit) { const marker = pendingSubmit.kind === "stall-nudge" ? STALL_NUDGE_MSG : RECOVERY_MARKER; if (contentToText(msg.content).includes(marker)) { dbg(`${pendingSubmit.kind} message submitted after ${pendingSubmit.attempts} extra Enter(s)`); pendingSubmit = null; } } const tur = entry.toolUseResult; const structuredBgId = structuredBackgroundId(tur); const content = Array.isArray(msg.content) ? msg.content : []; for (const c of content) { if (c.type !== "tool_result") continue; const tu = pendingToolUses.get(c.tool_use_id); pendingToolUses.delete(c.tool_use_id); pendingQuestions.delete(c.tool_use_id); // 这一步的耗时 = 本条 tool_result 的时刻 − 对应 tool_use 的时刻。 // 只在配得上对时记;配不上(被中断、日志截断)就没有这一步,宁缺勿造。 if (tu) recordStep(tu, entryAt, c.is_error !== true, c.content); const text = contentToText(c.content); const bgId = structuredBgId ?? (tu && wantsBackground(tu) ? matchFirst(text, BG_START_RES) : null); if (bgId) { const out = text.match(/Output is being written to:?\s*(\S+\.output)/)?.[1]; runningBg.set(bgId, { desc: String(tu?.input?.command ?? tu?.input?.description ?? tu?.name ?? "bg").slice(0, 80), out, }); dbg(`bg started: ${bgId} (${runningBg.size} running)${out ? "" : " [no output path — fixed idle timeout applies]"}`); } // Tool results can also carry completion info (e.g. TaskOutput/BashOutput // showing a terminal status, or KillShell confirmation). markCompletions(text); } // String-content user entries = injected notifications: // "X...completed..." const flat = contentToText(msg.content) + (typeof tur === "string" ? tur : ""); markCompletions(flat); } else if (entry.type === "system" && entry.subtype === "turn_duration") { // Backup turn-end marker for assistant frames lacking stop_reason. turnOpen = false; onTurnEnd("turn_duration"); } } /** * Structured signal (preferred) that a tool result started a background task: * - backgrounded Bash / Monitor: {"backgroundTaskId": "br5e715ft", ...} * - background subagent (Agent tool): {"isAsync": true, "status": "async_launched", * "agentId": "af0fbe1446b3f034a", ...}. Its completion arrives as a * whose is that agentId, so markCompletions * drains it like any other bg task. * Missing the subagent shape let a turn that ended "waiting for the agent" finalize * the whole run at once (2026-10-14, feature 62640d3e: three evals in a row came back * with no ASSESSMENT and were stamped 信息不足). */ export function structuredBackgroundId(tur: unknown): string | null { if (!tur || typeof tur !== "object") return null; const r = tur as Record; if (typeof r.backgroundTaskId === "string") return r.backgroundTaskId; if (r.status === "async_launched" && typeof r.agentId === "string") return r.agentId; return null; } function wantsBackground(tu: ToolUse): boolean { return tu.input?.run_in_background === true || tu.name === "Monitor" || tu.input?.runInBackground === true; } function matchFirst(text: string, res: RegExp[]): string | null { for (const re of res) { const m = text.match(re); if (m) return m[1]; } return null; } /** * A background subagent that ends its turn while ITS OWN bg work is still running * notifies completed plus a note that the result may be interim; * the same task-id notifies again once it really finishes. Draining on the interim * one finalized the run and killed the subagent mid-wait. */ const INTERIM_NOTE_RE = /background work of its own still running|result below may be interim/i; /** Task ids that `text` reports as finished, excluding interim subagent stops. */ export function terminalTaskIds(text: string): string[] { if (!text) return []; const interim = new Set(); for (const block of text.matchAll(/[\s\S]*?(?:<\/task-notification>|$)/g)) { const id = block[0].match(/([\w-]+)<\/task-id>/)?.[1]; if (id && INTERIM_NOTE_RE.test(block[0])) interim.add(id); } const done = new Set(); for (const re of BG_DONE_RES) { for (const m of text.matchAll(new RegExp(re.source, re.flags + (re.flags.includes("g") ? "" : "g")))) { done.add(m[1]); } } // Generic: "X … S" with S terminal. Two tag // spellings exist: task-notification uses , TaskOutput results use // . Notifications land in the transcript in different entry shapes // depending on whether the turn was active (queue-operation / attachment // entries) or idle (plain user string entry), so callers feed us RAW lines. for (const m of text.matchAll(/([\w-]+)<\/task[-_]id>[\s\S]{0,600}?(\w+)<\/status>/g)) { if (m[2] !== "running") done.add(m[1]); } return [...done].filter((id) => !interim.has(id)); } function markCompletions(text: string) { if (!text) return; if (INTERIM_NOTE_RE.test(text)) dbg("interim subagent stop seen — keeping its task tracked"); for (const id of terminalTaskIds(text)) { if (runningBg.delete(id)) dbg(`bg completed: ${id} (${runningBg.size} left)`); } } /** True if some process still holds the task's .output file open — i.e. the * background command is genuinely running (a 45-min build and a watch task * both count; the point is it's NOT a lost/dead task). */ function bgWriterAlive(out: string): boolean { try { const p = Bun.spawnSync({ cmd: ["lsof", "-t", out] }); return (p.stdout?.toString() || "").trim().length > 0; } catch { return false; } } function onTurnEnd(why: string) { // An API-error turn end must NOT be gated on bg drain. When claude surfaces an // "API Error:" the turn genuinely died — claude is idle at the prompt and any // still-tracked bg task is now orphaned (its completion frame will never be // consumed by this dead turn). Waiting for that drain hangs forever, which is // exactly what left runs wedged in `fixing`. Treat it as a finalize trigger so // the API-error recovery/finalize block downstream can run. if (runningBg.size === 0 || endedOnApiError()) { if (runningBg.size > 0) { dbg(`turn ended (${why}) on API error with ${runningBg.size} orphaned bg task(s) -> recover/finalize anyway`); runningBg.clear(); // abandon the dead turn's bg tracking so a later idle check can't re-wedge } else { dbg(`turn ended (${why}) with no background tasks -> finalize`); } sawEndTurnAfterBgDrain = true; } else { turnEndedWhileBgRunning = true; dbg(`turn ended (${why}) but ${runningBg.size} bg task(s) still running: ${[...runningBg.keys()].join(", ")}`); } } // ── API 错误分类 / 重投 ──────────────────────────────────────────────────── // 这一段留在模块作用域:上面的 track() / onTurnEnd() 直接在用它,它属于「定义」 // 那一半,不属于 runClaudePty 里那一次具体的运行。 let tail: TranscriptTail | null = null; const STALL_NUDGE_MS = envNum("CLAUDE_PTY_STALL_NUDGE_MS", 20 * 60 * 1000); const MAX_STALL_NUDGES = envNum("CLAUDE_PTY_MAX_STALL_NUDGES", 3); const SUBMIT_RETRIES = envNum("CLAUDE_PTY_SUBMIT_RETRIES", 6); const SUBMIT_INTERVAL_MS = envNum("CLAUDE_PTY_SUBMIT_INTERVAL_MS", 1500); let apiRecoveries = 0; let lastApiRecoveryAt = 0; let stallNudges = 0; /** 连续 4 次 API 错误才放弃;距上次自愈满 10 分钟则从 1 重新计。 */ const API_RECOVERY_LIMIT = 4; const API_RECOVERY_RESET_MS = 10 * 60 * 1000; /** One API-error turn end. The cap is a consecutive streak, not the whole run. */ export function decideApiRecovery( state: { count: number; lastAt: number }, now: number, ): { action: "recover" | "exhaust"; count: number; lastAt: number; reset: boolean } { const reset = state.lastAt > 0 && now - state.lastAt >= API_RECOVERY_RESET_MS; const count = reset ? 0 : state.count; if (count < API_RECOVERY_LIMIT) return { action: "recover", count: count + 1, lastAt: now, reset }; return { action: "exhaust", count, lastAt: state.lastAt, reset }; } const RECOVERY_MSG = "上一步出现 API 错误(可能是某张图片无法处理已被移除,或服务临时过载)。请重试刚才的操作并继续完成原任务,不要中途停下;若某个附件/图片始终无法读取,就跳过它并基于现有信息继续,最终仍按原任务要求给出结果(该打印的 STATUS/ASSESSMENT 行照常打印)。"; /** Match on a prefix, not the whole message: the TUI may wrap or reflow the injected * text before it echoes back into the transcript. Computed once, not per user entry. */ const RECOVERY_MARKER = RECOVERY_MSG.slice(0, 24); /** Stall fallback: a single word, queued harmlessly if the model was still working. */ const STALL_NUDGE_MSG = "继续"; /** claude surfaces API failures as a message that BEGINS with "API Error:". * Anchored at the start so a genuine final answer merely mentioning the phrase * isn't caught. */ function isApiErrorText(t: string): boolean { return /^\s*API Error:/i.test(t || ""); } const TAIL_SCAN_BYTES = 256 * 1024; /** Newest assistant text read straight from the transcript. * `lastAssistantText` only moves on text-bearing entries, but one API message is * split across several entries (thinking / text) and the stop_reason can arrive on * a thinking-only one — classifying that turn against the accumulated value grades * it by the PREVIOUS turn's text, which silently turns an API-error death into a * clean `success`. Returns "" when the window holds no complete assistant record * (a single tool_result line can exceed it), so callers fall back. */ function transcriptLastAssistantText(): string { if (!tail) return ""; const lines = tail.readTail(TAIL_SCAN_BYTES).split("\n"); for (let i = lines.length - 1; i >= 0; i--) { if (!lines[i].includes('"assistant"')) continue; // cheap filter, tolerant of spacing let entry: any; try { entry = JSON.parse(lines[i].trim()); } catch { continue; } // may be a partial record if (entry.isSidechain || entry.type !== "assistant") continue; const text = contentToText(entry.message?.content).trim(); if (text) return text; } return ""; } /** Turn-end API-error classification. The transcript is ahead of the accumulated * text (readNew reads the whole file, track applies it line by line), so it wins; * the accumulator is the fallback for an unreadable or oversized window. */ function endedOnApiError(): boolean { return isApiErrorText(transcriptLastAssistantText() || lastAssistantText); } // ── main ────────────────────────────────────────────────────────────────── /** * 跑一次 PTY 包装的 agent。可以从两个地方进来: * * 1. 直接跑 —— `bun bin/claude-pty.ts -p …`(开发 / 源码树) * 2. 作为卫星 bundle 的 `claude-pty` 子命令,经 satellite/src/entry.ts 进来 * * (2) 是本次重构的全部目的。热部署只发一个产物 satellite.js;在此之前这个 wrapper * 只存在于 `/bin/`,读的是**节点自己的检出**,而部署链路一次都不碰它。于是一个 * wrapper 修复可以被合并、被部署、被报告成「已推送」,然后在任何地方都没运行—— * 因为节点只上报 dist/VERSION,面板上它看起来是最新的。折进同一个产物之后,这类漂移 * 从「容易忘」变成「不可能」,跟 record-evidence / conditions 走的是同一条路。 * * `argv` 是程序名之后的参数,即 ["-p", "", …]。 * * 一次进程只跑一次:上面那些模块级的运行状态(runningBg / finalized / totalUsage …) * 是跟着这一次运行的,不是可重入的。这和 record-evidence 一样——子命令进程是一次性的。 */ export async function runClaudePty(argv: string[]): Promise { const { prompt, passthrough, sessionUuid, resumeUuid } = parseArgs(argv); const isManagedSecurityRun = process.env[AGENT_SESSION_KIND_ENV] === "security"; const resuming = Boolean(resumeUuid); const sessionId = resumeUuid || sessionUuid || randomUUID(); const cwd = process.cwd(); const priorTranscript = resuming ? findTranscript(sessionId) : null; let priorTranscriptSize = 0; if (priorTranscript) { try { priorTranscriptSize = statSync(priorTranscript).size; } catch { /* start at zero */ } } const AUTOMODE_SYSPROMPT = [ "本会话运行在无人值守的自动化流水线中,没有任何人类在观看或会作出回应。", "绝对禁止使用 AskUserQuestion 工具或以提问等待用户回复的方式中断任务;", "如必须在多个方案中取舍,直接采用你推荐的(或第一个可行的)方案并继续执行,事后在输出中说明即可。", "如需计划确认(ExitPlanMode),直接按你的计划执行。任务必须自主推进到完成。", ].join(""); const claudeArgs = [ "--dangerously-skip-permissions", resuming ? "--resume" : "--session-id", sessionId, "--append-system-prompt", AUTOMODE_SYSPROMPT, "--settings", buildFlagSettings(passthrough), ...passthrough.filter((a) => a !== "--dangerously-skip-permissions"), prompt, ]; dbg(`spawning: ${REAL_CLAUDE} (session ${sessionId}) cwd=${cwd}`); emit({ type: "system", subtype: "init", cwd, session_id: sessionId, tools: [], model: "", permissionMode: "bypassPermissions", apiKeySource: "none", mcp_servers: [], slash_commands: [], claude_pty: true, }); /** Rolling tail of the PTY screen, filled by the drain loop below. Kept for * EVERY run and not just security ones: when claude blocks on a startup modal * the screen is the only witness, and throwing it away is what made 8 identical * `transcript-missing` failures produce no clue at all (evaluator-android-01, * 2026-09-09). Declared up here because finalize() may read it on any path. */ let ptyTail = ""; const badSettings = malformedSettingsFiles(cwd); if (badSettings.length) { console.error(`[claude-pty] refusing to start: malformed settings JSON: ${badSettings.join(", ")}`); finalize("error_during_execution", true, `bad-settings-json:${badSettings.join(",")}`); process.exit(1); } // `script -q /dev/null ` allocates the PTY. Its stdin must be a REAL // pipe(2): macOS tcgetattr() on Bun's socketpair-backed "pipe" AND on FIFOs // returns EOPNOTSUPP ("Operation not supported on socket") which `script` // treats as fatal; only pipe(2)/char devices give the benign ENOTTY. So we // build the pipe inside sh: `cat | script ...` — cat forwards our // keystrokes from the fifo as they arrive, and because we hold the fifo open // O_RDWR it never sees EOF while we live (EOF on the pty = Ctrl-D = quit). // // NOT `tail -f`: BSD tail treats a FIFO as a non-seekable input and must read // it to EOF before it can print "the last N lines" — with no EOF ever coming // it forwards nothing, ever (`-n +1` does not change that). Every keystroke // this wrapper types — the API-error recovery, the stall nudge, /exit — went // into that black hole; verified 2026-09-21 with `tail -f fifo | script cat` // echoing nothing while `cat fifo | script cat` echoes everything. const fifoPath = path.join("/tmp", `claude-pty-${sessionId}.in`); Bun.spawnSync({ cmd: ["mkfifo", fifoPath] }); const fifoFd = openSync(fifoPath, "r+"); // O_RDWR: keeps fifo writable + readable, never blocks process.on("exit", () => { try { Bun.spawnSync({ cmd: ["rm", "-f", fifoPath] }); } catch {} // Last-resort sweep, on EVERY exit path including the ones that never reach // shutdown() (an uncaught throw, an explicit process.exit elsewhere). Nothing // may be awaited here, so this is SIGKILL directly — by the time the wrapper // is exiting, a surviving claude has no reader and no purpose, and leaving it // is what the orphan pile-up was made of. On the normal path both patterns // match nothing: the tree is already gone. for (const pat of [fifoPath, sessionId]) { try { Bun.spawnSync({ cmd: ["pkill", "-KILL", "-f", pat] }); } catch {} } }); const child: Subprocess<"ignore", "pipe", "pipe"> = spawn({ cmd: ["sh", "-c", 'cat "$0" | script -q /dev/null "$@"', fifoPath, REAL_CLAUDE, ...claudeArgs], cwd, env: cleanEnv(), stdin: "ignore", stdout: "pipe", stderr: "pipe", }); function ptyWrite(s: string) { try { const { writeSync } = require("node:fs") as typeof import("node:fs"); writeSync(fifoFd, s); } catch (e) { dbg(`ptyWrite failed: ${(e as Error).message}`); } } /** How long the tree gets to honour SIGTERM before we stop asking. */ const KILL_GRACE_MS = envNum("CLAUDE_PTY_KILL_GRACE_MS", 5_000); /** * Is any of the tree still alive? Matched the same way we kill it — the session * id is in claude's argv and the fifo path in tail's, both unique per run, so * pgrep -f is precise. (`sessionId` is generated in THIS process and never put * on our own command line, so we can never match ourselves.) */ function treeAlive(): boolean { for (const pat of [sessionId, fifoPath]) { try { const r = Bun.spawnSync({ cmd: ["pgrep", "-f", pat], stdout: "pipe", stderr: "pipe" }); if (r.exitCode === 0) return true; } catch { /* pgrep missing → fall through to "assume dead" */ } } return false; } /** * Kill the whole claude tree — and make sure it actually died. * * The escalation is the point. This used to send SIGTERM and return, with * `process.exit()` on the very next line: nothing ever checked, and a claude * under `script` that was slow to handle the signal simply outlived us. Every * such run left a live process nobody was reading any more, and on a node the * control plane was retrying every few minutes they accumulated until the * machine could no longer start claude within the 120s transcript wait below — * at which point every generation on it failed, which produced more retries. * 100+ orphans measured on one node, 2026-08-22. * * SIGTERM first (claude gets to flush its transcript), then SIGKILL for * whatever is left, then one last look so the leftover is at least *stated* * rather than silently normal. */ async function killTree(): Promise { try { child.kill(); } catch {} for (const pat of [sessionId, fifoPath]) { try { Bun.spawnSync({ cmd: ["pkill", "-TERM", "-f", pat] }); } catch {} } const deadline = Date.now() + KILL_GRACE_MS; while (Date.now() < deadline && treeAlive()) await Bun.sleep(200); if (!treeAlive()) return; dbg(`tree survived SIGTERM after ${KILL_GRACE_MS}ms; escalating to SIGKILL`); try { child.kill(9); } catch {} for (const pat of [sessionId, fifoPath]) { try { Bun.spawnSync({ cmd: ["pkill", "-KILL", "-f", pat] }); } catch {} } const hardDeadline = Date.now() + 1_000; while (Date.now() < hardDeadline && treeAlive()) await Bun.sleep(100); // SIGKILL is not refusable, so anything still matching is a process we do not // own (a zombie awaiting reap, or a same-uuid match we should know about). if (treeAlive()) dbg(`WARNING: processes still match ${sessionId} after SIGKILL`); } // Drain PTY screen output (we don't parse it — transcript is the data channel — // but the OSC 9 "waiting for your input" marker is a useful idle hint, and // DEBUG mode mirrors everything for troubleshooting). let ptyIdleHintAt = 0; (async () => { const dec = new TextDecoder(); for await (const chunk of child.stdout) { const s = dec.decode(chunk); ptyTail = `${ptyTail}${s}`.slice(-32 * 1024); if (s.includes("Claude is waiting for your input")) ptyIdleHintAt = Date.now(); if (DEBUG) process.stderr.write(s); } })().catch(() => {}); (async () => { const dec = new TextDecoder(); for await (const chunk of child.stderr) { if (DEBUG) process.stderr.write(dec.decode(chunk)); } })().catch(() => {}); let childExited = false; child.exited.then(() => { childExited = true; }); // ── API-error in-session recovery ────────────────────────────────────────── // When a turn ends because claude surfaced an API error (its OWN "API Error: …" // message — e.g. an image that couldn't be processed and was removed, or a // transient overload/5xx), the model is still alive at the prompt: the task is // NOT done. The old behaviour finalized a fake `success` (result text = that // error), which upstream then misread as a real "no STATUS/ASSESSMENT" failure. // Instead we inject a continue and let claude recover IN the same session, // preserving all context. Bounded; on exhaustion we emit an error-flagged // result so upstream can retry / route it distinctly. /** * 收到信号时把现场留一句:父进程还在不在。 * * 卫星按看门狗 / abort 杀我们时父进程活着;父进程自己先没了(ppid 变 1,我们被 * 挂到 launchd 上)则是整棵树被端。此前 `error_during_execution` 这一帧对两种情况 * 长得一模一样,事后只能靠「137 那条 tool_result 有没有被镜像进会话日志」反推。 */ function parentState(): string { const ppid = process.ppid; if (ppid <= 1) return "parent=none(reparented)"; try { process.kill(ppid, 0); return `parent=${ppid}(alive)`; } catch { return `parent=${ppid}(gone)`; } } let finalized = false; /** * 收尾。`reason` 说的是**走了哪条收尾路径**,和 `subtype`(结果是什么)是两件事: * 同一个 `error_during_execution` 既可能是收到 SIGTERM,也可能是 claude 自己崩了, * 而这两种的处置完全不同。它挂在终态 result 帧上 —— 下游本来就要回扫到这一帧 * (isInfraError / 摘要 / 面板都是),不必再单开一行。 */ function finalize(subtype: string, isError: boolean, reason: string) { if (finalized) return; finalized = true; // Safety net for every finalize path: never report a clean success when the // last thing claude said was an API error — coerce to an error-flagged frame // so upstream classification can't mistake it for a real agent verdict. if (!isError && subtype === "success" && endedOnApiError()) { subtype = "api_error"; isError = true; reason = `${reason}+api-error-tail`; } const usageLimit = isError && isManagedSecurityRun ? securityUsageLimitMessage("claude", ptyTail) : null; if (usageLimit) { subtype = "usage_limit"; isError = true; reason = `${reason}+usage-limit`; } emit({ type: "result", subtype, reason, is_error: isError, duration_ms: Date.now() - t0, duration_api_ms: Date.now() - t0, num_turns: numTurns, result: usageLimit ? `Claude usage limit: ${usageLimit}` : lastAssistantText, stop_reason: isError ? null : "end_turn", session_id: sessionId, uuid: randomUUID(), total_cost_usd: 0, // not derivable from the transcript; usage tokens are usage: totalUsage, }); } async function shutdown(exitCode: number) { // Graceful: /exit through the TUI; fall back to killing the tree. if (!childExited) { ptyWrite("/exit"); setTimeout(() => ptyWrite("\r"), 150); const deadline = Date.now() + 5000; while (!childExited && Date.now() < deadline) await Bun.sleep(200); } if (!childExited) { dbg("child did not exit after /exit; killing tree"); await killTree(); } process.exit(exitCode); } for (const sig of ["SIGINT", "SIGTERM"] as const) { process.on(sig, () => { dbg(`got ${sig}; killing claude`); finalize("error_during_execution", true, `signal:${sig} ${parentState()}`); // Await the escalation before exiting. Returning from the handler // immediately is what let a killed wrapper leave its claude behind — and // this is the path the satellite's own watchdog and 空档部署 both take, so // it is the one that produced orphans in bulk. void killTree().finally(() => process.exit(143)); }); } // ── main loop ───────────────────────────────────────────────────────────── const startWait = Date.now(); while (true) { if (HARD_TIMEOUT_MS > 0 && Date.now() - t0 > HARD_TIMEOUT_MS) { dbg("hard timeout reached"); finalize("error_max_duration", true, "hard-timeout"); await shutdown(1); } if (!tail) { const p = findTranscript(sessionId); if (p) { const initialOffset = resuming && priorTranscript === p ? priorTranscriptSize : 0; tail = new TranscriptTail(p, initialOffset); recordAgentSessionIdFromEnv("claude", sessionId); dbg(`transcript found: ${p}`); } else if (childExited) { finalize("error_during_execution", true, "child-exit-before-transcript"); await shutdown(1); } else if (Date.now() - startWait > 120_000) { // claude is alive but never created a session — essentially always a modal // it is waiting on. Print the screen and carry an excerpt in `reason`: a // bare "transcript-missing" reads as an API/infra outage (that is how the // runner classifies it) and sends whoever opens the panel hunting for one. const screen = visibleScreenTail(ptyTail); dbg("transcript never appeared within 120s"); console.error(`[claude-pty] transcript never appeared within 120s; last PTY screen:\n${screen}`); finalize( "error_during_execution", true, `transcript-missing${screen ? ` screen:${firstLines(screen, 2)}` : ""}`, ); await shutdown(1); } } if (tail) { for (const line of tail.readNew()) { lastTranscriptActivity = Date.now(); allDeadSince = 0; // fresh activity invalidates any previous wedge episode let entry: any; try { entry = JSON.parse(line); } catch { continue; } if (entry.isSidechain) continue; // Completion scan — ONLY on entries the agent actually CONSUMES: user // entries (dequeued notification / tool_result with TaskOutput status) // and attachment/queued_command entries (notification injected into the // next turn). Deliberately NOT on queue-operation enqueue lines: a task // finishing mid-turn is enqueued (and hits the transcript) BEFORE the // agent has seen it — draining there made an end_turn that raced the // dequeue finalize the run prematurely, so the agent's reaction turn to // the last completion never happened. if (entry.type === "user") markCompletions(line); else if (entry.type === "attachment" && entry.attachment) markCompletions(JSON.stringify(entry.attachment)); if (entry.type === "user" || entry.type === "assistant") { // Parity with -p: the initial prompt is NOT echoed as a user frame. const isPromptEcho = !promptEchoSkipped && entry.type === "user" && entry.message?.content === prompt; if (isPromptEcho) promptEchoSkipped = true; if (entry.message && !isPromptEcho) { emit({ type: entry.type, message: entry.message, session_id: sessionId, parent_tool_use_id: null, uuid: entry.uuid, ...(typeof entry.requestId === "string" ? { request_id: entry.requestId } : {}), ...(entry.type === "user" && entry.toolUseResult !== undefined ? { tool_use_result: entry.toolUseResult } : {}), }); } track(entry); } else if (entry.type === "system" && entry.subtype) { // forward system frames (e.g. compact_boundary) — print mode emits these too emit({ ...entry, session_id: sessionId }); track(entry); } } } if (sawEndTurnAfterBgDrain) { const apiError = endedOnApiError(); if (apiError) { // Recoverable interruption: claude is idle at the prompt after surfacing an // API error, NOT finished. The budget is a consecutive streak — a long run // drops the connection every so often, and those isolated drops must not // share one lifetime cap with a tight burst that never actually recovers. const decision = decideApiRecovery( { count: apiRecoveries, lastAt: lastApiRecoveryAt }, Date.now(), ); if (decision.action === "recover") { apiRecoveries = decision.count; lastApiRecoveryAt = decision.lastAt; dbg(`API-error turn end (recovery ${apiRecoveries}/${API_RECOVERY_LIMIT}${decision.reset ? ", streak reset" : ""}); injecting continue instead of finalizing`); sawEndTurnAfterBgDrain = false; // clear the finalize trigger; wait for the next turn ptyWrite(RECOVERY_MSG); await Bun.sleep(250); ptyWrite("\r"); pendingSubmit = { attempts: 0, nextAt: Date.now() + SUBMIT_INTERVAL_MS, kind: "api-error" }; } else { // Consecutive recoveries exhausted — surface a real, error-flagged result. dbg(`API-error persisted after ${decision.count} consecutive recovery attempt(s); finalizing as api_error`); finalize("api_error", true, `api-error-exhausted:${decision.count}`); await shutdown(1); } } else { finalize("success", false, "end-turn"); await shutdown(0); } } // The recovery text is TYPED into claude's TUI, so the injection only counts once // the prompt is submitted. A single Enter can land while the TUI is still redrawing // after the API error and submit nothing, leaving the session idle at the prompt // forever with no watchdog behind it. Re-press until the message echoes back as a // user entry. api-error then gives up with an honest verdict; stall-nudge just // drops this attempt (the next 20-min silence window can try again). if (pendingSubmit && Date.now() >= pendingSubmit.nextAt) { if (pendingSubmit.attempts < SUBMIT_RETRIES) { pendingSubmit.attempts++; dbg(`${pendingSubmit.kind} not submitted yet; Enter retry ${pendingSubmit.attempts}/${SUBMIT_RETRIES}`); ptyWrite("\r"); pendingSubmit.nextAt = Date.now() + SUBMIT_INTERVAL_MS; } else if (pendingSubmit.kind === "stall-nudge") { dbg(`stall nudge never submitted after ${SUBMIT_RETRIES} retries — waiting for next stall window`); pendingSubmit = null; } else { dbg(`recovery never submitted after ${SUBMIT_RETRIES} retries — finalizing as api_error`); pendingSubmit = null; finalize("api_error", true, "recovery-not-submitted"); await shutdown(1); } } // Transcript (and therefore the runner's session log) has made zero forward // progress for STALL_NUDGE_MS. The API-error path above only fires on a // classified end_turn; this is the broader fallback — claude sitting at the // prompt after a silent failure, a lost bg wake-up, or a half-dead socket // that never produced an "API Error:" line. Injecting "继续" is a no-op if // the model was actually still working (it queues) and the nudge that // unsticks the idle-at-prompt cases. Capped so a true hang still reaches // the runner's 1h stall-kill instead of resetting that clock forever. if ( tail && STALL_NUDGE_MS > 0 && !pendingSubmit && pendingQuestions.size === 0 && stallNudges < MAX_STALL_NUDGES && Date.now() - lastTranscriptActivity >= STALL_NUDGE_MS ) { stallNudges++; const mins = Math.round(STALL_NUDGE_MS / 60_000); dbg(`transcript silent ${mins}min (nudge ${stallNudges}/${MAX_STALL_NUDGES}); injecting "${STALL_NUDGE_MSG}"`); console.error(`[claude-pty] transcript silent ${mins}min; injecting ${STALL_NUDGE_MSG} (${stallNudges}/${MAX_STALL_NUDGES})`); ptyWrite(STALL_NUDGE_MSG); await Bun.sleep(250); ptyWrite("\r"); lastTranscriptActivity = Date.now(); // re-arm; real growth overwrites this pendingSubmit = { attempts: 0, nextAt: Date.now() + SUBMIT_INTERVAL_MS, kind: "stall-nudge" }; } // A turn ended while bg tasks were running and they have all since drained, // but the wake-up turn may not add a new end_turn if claude crashed — also // treat "bg empty + turn previously ended + long PTY idle" via idle timeout. if (turnEndedWhileBgRunning && runningBg.size === 0) { // bg drained — claude should wake and produce a fresh end_turn; just keep // looping. (sawEndTurnAfterBgDrain fires on that next end_turn.) } // Auto-answer interactive blockers: Enter selects the highlighted // (recommended/first) option of AskUserQuestion / ExitPlanMode. const now = Date.now(); for (const [id, firstSeen] of pendingQuestions) { if (now - firstSeen > 3000) { dbg(`pressing Enter to dismiss pending interactive prompt ${id}`); ptyWrite("\r"); pendingQuestions.set(id, now); // re-arm; repeats every 3s until result shows up } } if (childExited) { // flush whatever's left, then finalize with what we have if (tail) { for (const line of tail.readNew()) { try { const entry = JSON.parse(line); if (entry.type === "user") markCompletions(line); else if (entry.type === "attachment" && entry.attachment) markCompletions(JSON.stringify(entry.attachment)); if (!entry.isSidechain && (entry.type === "user" || entry.type === "assistant") && entry.message) { const isPromptEcho = !promptEchoSkipped && entry.type === "user" && entry.message?.content === prompt; if (isPromptEcho) { promptEchoSkipped = true; track(entry); continue; } emit({ type: entry.type, message: entry.message, session_id: sessionId, parent_tool_use_id: null, uuid: entry.uuid }); track(entry); } } catch {} } } // claude exited on its own (crash, /exit). Honest grading: success only if // our end condition was actually met — bg drained and the last turn closed. const ok = sawEndTurnAfterBgDrain || (!turnOpen && runningBg.size === 0 && !!lastAssistantText); finalize(ok ? "success" : "error_during_execution", !ok, "child-exit"); process.exit(ok ? 0 : 1); } // Idle handling — ONLY when claude is genuinely idle (turn ended; while a // turn is open the transcript is legitimately silent, e.g. an hour-long // foreground build, and nothing here may fire). Once idle has exceeded the // window, decide by GROUND TRUTH instead of guessing from duration alone: // each undrained bg task's processes hold its .output file open, so lsof // tells us whether it is genuinely still running. // - any writer alive → a real long task (or a watch task): EXTEND, never // kill — a 45-min build that outlives any fixed window survives. True // watch tasks keep the run open; ending those is the caller's sentinel // watchdog / hard timeout's job. // - all writers dead → the tasks finished but their notifications never // got consumed (wedged claude): short WEDGE_GRACE, then finalize. // - liveness unknown (no .output path captured) → old fixed-window bail. if (IDLE_TIMEOUT_MS > 0 && !turnOpen && Date.now() - lastTranscriptActivity > IDLE_TIMEOUT_MS) { const tasks = [...runningBg.values()]; const known = tasks.filter((t) => t.out); const anyAlive = known.some((t) => bgWriterAlive(t.out!)); if (anyAlive) { dbg(`idle ${IDLE_TIMEOUT_MS}ms but bg writer(s) still alive — extending wait (${[...runningBg.keys()].join(",")})`); lastTranscriptActivity = Date.now(); // re-arm a full idle window allDeadSince = 0; } else if (tasks.length > 0 && known.length === tasks.length) { if (!allDeadSince) { allDeadSince = Date.now(); dbg(`idle and ALL bg writers dead — ${WEDGE_GRACE_MS}ms wedge grace for late notifications`); } else if (Date.now() - allDeadSince > WEDGE_GRACE_MS) { dbg("wedge grace expired — finalizing"); finalize(lastAssistantText ? "success" : "error_during_execution", !lastAssistantText, "idle-wedge"); await shutdown(lastAssistantText ? 0 : 1); } } else { // bg tasks with unknown liveness, or none at all (claude wedged after // drain without a final end_turn) — fixed-window bail as before. dbg(`idle ${IDLE_TIMEOUT_MS}ms after turn end with ${runningBg.size} bg task(s), liveness unknown — finalizing`); finalize(lastAssistantText ? "success" : "error_during_execution", !lastAssistantText, "idle-window"); await shutdown(lastAssistantText ? 0 : 1); } } await Bun.sleep(300); } } // 只有当这个文件本身是入口时才自动跑。被折进卫星 bundle 时它不是入口,于是 import // 它不产生任何副作用,由 entry.ts 调用上面那个导出。 if (import.meta.main) await runClaudePty(process.argv.slice(2));