1262 lines
64 KiB
TypeScript
1262 lines
64 KiB
TypeScript
#!/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));
|