Files
streamline/bin/claude-pty.ts
T
2026-11-16 17:26:44 -08:00

1262 lines
64 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env bun
/**
* claude-pty — drop-in replacement for `claude -p <prompt> --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 <prompt> --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 <fifo> | script -q /dev/null
* claude <args> <prompt>'`) with a scrubbed env and a fixed --session-id
* 3. tails the session transcript ~/.claude/projects/<dir>/<session>.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 <prompt>`: 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<string, unknown> = {
skipDangerousModePermissionPrompt: true,
// A project `.mcp.json` pops "New MCP server found in this project: <name>"
// 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/<task>, 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`
// 从源码跑是 `<repo>/bin/`,被打进 bundle 后变成 `<repo>/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<string, string> {
const env: Record<string, string> = {};
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<string, unknown>) {
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, unknown>): 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<string, unknown>; at: number; }
interface BgTask { desc: string; out?: string; } // out = task .output file (liveness probe target)
const runningBg = new Map<string, BgTask>(); // bg task id -> info
const pendingToolUses = new Map<string, ToolUse>(); // tool_use id -> info (no result yet)
const pendingQuestions = new Map<string, number>(); // 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<string>();
const totalUsage: Record<string, number> = {
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,
/<task-id>([\w-]+)<\/task-id>/,
/Monitor started \(task ([\w-]+)/i, // "Monitor started (task bad2ttc94, timeout 300000ms)"
/task id:?\s*([\w-]+)/i,
];
const BG_DONE_RES = [
/<task-id>([\w-]+)<\/task-id>[\s\S]*?<status>(?: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:
// "<task-notification><task-id>X</task-id>...<status>completed</status>..."
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
* <task-notification> whose <task-id> 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<string, unknown>;
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 <status>completed</status> 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<string>();
for (const block of text.matchAll(/<task-notification>[\s\S]*?(?:<\/task-notification>|$)/g)) {
const id = block[0].match(/<task-id>([\w-]+)<\/task-id>/)?.[1];
if (id && INTERIM_NOTE_RE.test(block[0])) interim.add(id);
}
const done = new Set<string>();
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: "<task-id>X</task-id> … <status>S</status>" with S terminal. Two tag
// spellings exist: task-notification uses <task-id>, TaskOutput results use
// <task_id>. 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(/<task[-_]id>([\w-]+)<\/task[-_]id>[\s\S]{0,600}?<status>(\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
* 只存在于 `<repo>/bin/`,读的是**节点自己的检出**,而部署链路一次都不碰它。于是一个
* wrapper 修复可以被合并、被部署、被报告成「已推送」,然后在任何地方都没运行——
* 因为节点只上报 dist/VERSION,面板上它看起来是最新的。折进同一个产物之后,这类漂移
* 从「容易忘」变成「不可能」,跟 record-evidence / conditions 走的是同一条路。
*
* `argv` 是程序名之后的参数,即 ["-p", "<prompt>", …]。
*
* 一次进程只跑一次:上面那些模块级的运行状态(runningBg / finalized / totalUsage …)
* 是跟着这一次运行的,不是可重入的。这和 record-evidence 一样——子命令进程是一次性的。
*/
export async function runClaudePty(argv: string[]): Promise<never> {
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 <cmd...>` 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 <fifo> | 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<void> {
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));