@cat-factory/executor-harness 1.50.4 → 1.50.8

package/dist/agent-runner.js

@@ -2,16 +2,12 @@ import { spawn } from 'node:child_process';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { claudeAssistantContent, claudeCallUsage, isObject, numberOf, redactBody, } from './claude-stream.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
+import { createSliceTracker, startSubagentWatcher } from './subagents.js';
+import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
-function isObject(value) {
-    return typeof value === 'object' && value !== null;
-}
-/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
-function redactBody(text, secrets) {
-    return secrets.length ? redact(text, secrets) : text;
-}
 /**
  * Fallback token attribution: if a CLI reported a cumulative total but no per-turn
  * usage (so every captured call has zero tokens), pin the whole total onto the LAST
@@ -34,10 +30,11 @@ function attributeCumulativeUsage(calls, usage) {
  * never argv), `onActivity` on every chunk, abort kills the child, and the close
  * handler resolves/rejects. The caller's `onEvent` accumulates the outcome.
  *
- * `prompt` is fed over stdin: for Claude Code that is just the task prompt (the
- * system prompt rides `--append-system-prompt`); for Codex — which has no
- * system-prompt flag — the caller prepends the composed system prompt to it so
- * the role + best-practice context is not lost.
+ * `prompt` is fed over stdin: for Claude Code that is normally just the task prompt (the
+ * system prompt rides `--append-system-prompt`), unless the system prompt is too large for
+ * argv, in which case it is folded into `prompt` (see `carryClaudeSystemPrompt`); for Codex
+ * — which has no system-prompt flag — the caller always prepends the composed system prompt
+ * so the role + best-practice context is not lost.
  */
 function streamCli(cli, prompt, opts, env, secrets, onEvent) {
     const { command, args } = cli;
@@ -122,6 +119,40 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
         });
     });
 }
+/**
+ * Fold a composed system prompt into the task prompt so the role + best-practice context
+ * rides stdin as a single user turn. Used by the Codex runner (no system-prompt flag) and
+ * by the Claude runner's argv-overflow fallback. Empty system prompt ⇒ the task prompt is
+ * returned unchanged.
+ */
+function foldSystemPrompt(systemPrompt, userPrompt) {
+    return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
+}
+/**
+ * Linux caps a SINGLE argv string at MAX_ARG_STRLEN (32 pages = 128 KiB) — a per-string limit,
+ * distinct from (and reached long before) the far larger total ARG_MAX for argv + env combined. A
+ * system prompt with best-practice fragments folded in can exceed that per-string cap, and `execve`
+ * then fails the whole spawn with `E2BIG` before the agent runs at all — the failure mode seen on
+ * the `pr-reviewer` step (a ~150 KiB composed prompt). The binding constraint is that per-string
+ * cap; 96 KiB stays comfortably under 128 KiB so the system-prompt argv can never approach it.
+ */
+const MAX_ARGV_STRING_BYTES = 96 * 1024;
+/**
+ * Decide how the Claude Code runner carries the composed system prompt. Small prompts ride
+ * `--append-system-prompt` (a real system turn, cacheable) as before; a prompt too large for a
+ * single argv string is instead folded into the stdin task prompt (like the Codex runner), which
+ * has no size ceiling. Pure so the branch is unit-testable without spawning the CLI.
+ */
+export function carryClaudeSystemPrompt(systemPrompt, userPrompt) {
+    if (Buffer.byteLength(systemPrompt, 'utf8') <= MAX_ARGV_STRING_BYTES) {
+        return {
+            appendArgs: ['--append-system-prompt', systemPrompt],
+            prompt: userPrompt,
+            folded: false,
+        };
+    }
+    return { appendArgs: [], prompt: foldSystemPrompt(systemPrompt, userPrompt), folded: true };
+}
 // ---------------------------------------------------------------------------
 // Claude Code
 // ---------------------------------------------------------------------------
@@ -161,19 +192,47 @@ export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
     let usage;
+    // Decide how the composed system prompt is carried up front, so the telemetry seed below
+    // reflects what actually reaches the model: a small prompt rides `--append-system-prompt`
+    // (a real system turn), while an argv-overflowing prompt is folded into the first user turn
+    // — in which case NO system turn of ours is sent (the `E2BIG` fallback).
+    const { appendArgs, prompt, folded } = carryClaudeSystemPrompt(opts.systemPrompt, opts.userPrompt);
+    if (folded) {
+        opts.log?.warn('system prompt exceeds argv limit; folding into the task prompt', {
+            bytes: Buffer.byteLength(opts.systemPrompt, 'utf8'),
+        });
+    }
     // Reconstruct the full per-call request/response bodies for telemetry from the
     // stream. `--output-format stream-json --verbose` emits each turn as a near-verbatim
     // Anthropic Messages envelope, so `assistant` events carry the complete response
     // (text + tool_use blocks + usage), and `user` events carry the tool_result blocks
-    // fed back — together the growing prompt transcript. We seed it with the two inputs
-    // the harness supplies (they never appear in the stream): the system + first user
-    // message. Bodies are credential-scrubbed (they can echo the leased token).
+    // fed back — together the growing prompt transcript. We seed it with the inputs the
+    // harness supplies (they never appear in the stream): the system + first user message
+    // when the prompt rides argv, or a single folded user turn when it doesn't — so the
+    // reconstruction never shows a system turn that was never sent. Bodies are
+    // credential-scrubbed (they can echo the leased token).
     const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [];
-    const messages = [
-        { role: 'system', content: opts.systemPrompt },
-        { role: 'user', content: opts.userPrompt },
-    ];
+    const messages = folded
+        ? [{ role: 'user', content: prompt }]
+        : [
+            { role: 'system', content: opts.systemPrompt },
+            { role: 'user', content: opts.userPrompt },
+        ];
     const calls = [];
+    // ADR 0026 D2.1: derive slice progress from the parent stream's `Task` dispatches +
+    // their terminal tool_results (both DO appear here — only a subagent's intermediate
+    // turns don't). A real parent TodoWrite plan, when the agent writes one, wins; the
+    // slice-derived progress is the fallback for the parallel-subagent shape that writes no
+    // parent plan (the pr-reviewer failure this fixes).
+    const sliceTracker = createSliceTracker();
+    let sawTodoPlan = false;
+    const emitSliceProgress = () => {
+        if (sawTodoPlan || !opts.onProgress)
+            return;
+        const progress = sliceTracker.progress();
+        if (progress)
+            opts.onProgress(progress);
+    };
     const onEvent = (event) => {
         const type = event.type;
         if (type === 'assistant' && isObject(event.message)) {
@@ -188,10 +247,14 @@ export async function runClaudeCode(opts) {
                     block.name === 'TodoWrite' &&
                     opts.onProgress) {
                     const progress = todosToProgress(block.input?.todos);
-                    if (progress)
+                    if (progress) {
+                        sawTodoPlan = true;
                         opts.onProgress(progress);
+                    }
                 }
             }
+            sliceTracker.onAssistant(content);
+            emitSliceProgress();
             // Record this call BEFORE appending its turn: the prompt is the history that
             // produced this response. The append-only array keeps each call's prompt a strict
             // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
@@ -212,8 +275,11 @@ export async function runClaudeCode(opts) {
         else if (type === 'user' && isObject(event.message)) {
             // tool_result blocks the harness fed back to the model — part of the next prompt.
             const content = event.message.content;
-            if (Array.isArray(content))
+            if (Array.isArray(content)) {
+                sliceTracker.onUser(content);
+                emitSliceProgress();
                 messages.push({ role: 'tool', content });
+            }
         }
         else if (type === 'result') {
             if (typeof event.result === 'string')
@@ -239,12 +305,12 @@ export async function runClaudeCode(opts) {
     // as already accepted so `-p` starts straight into the run. Best-effort: written
     // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
     // (Ambient mode skips this — the developer's own config is already onboarded.)
+    // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
+    // version, so a future first-run gate this set doesn't cover (which looks identical to
+    // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
     if (configHome) {
-        await writeFile(join(configHome, '.claude.json'), JSON.stringify({
-            hasCompletedOnboarding: true,
-            bypassPermissionsModeAccepted: true,
-            hasTrustDialogAccepted: true,
-        }), { mode: 0o600 }).catch(() => { });
+        await writeOnboardingPreseed(configHome);
+        await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
     }
     // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
     // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
@@ -271,6 +337,19 @@ export async function runClaudeCode(opts) {
                 }
                 : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
         };
+    // ADR 0026 D2.1/D3: while the run is live, tail the CLI's `subagents/*.jsonl`
+    // transcripts (under the isolated config home) so a parallel-subagent review keeps the
+    // inactivity heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible
+    // token spend is lifted into the run's telemetry. Ambient mode has no isolated home to
+    // watch. Best-effort — a missing/renamed transcript layout just yields no extra signal.
+    const subagents = configHome
+        ? startSubagentWatcher(join(configHome, 'subagents'), {
+            ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+            secrets,
+            model: opts.model,
+            ...(opts.log ? { log: opts.log } : {}),
+        })
+        : undefined;
     try {
         const { stderrTail } = await streamCli({
             command: 'claude',
@@ -287,20 +366,43 @@ export async function runClaudeCode(opts) {
                 'bypassPermissions',
                 '--model',
                 opts.model,
-                '--append-system-prompt',
-                opts.systemPrompt,
+                ...appendArgs,
             ],
-        }, opts.userPrompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        }, prompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
+        // subagent calls, which carry their own per-turn tokens, are concatenated).
         attributeCumulativeUsage(calls, usage);
+        // Final drain of any subagent transcript writes that landed after the last poll, then
+        // fold the subagents' usage + per-call telemetry into the run's outcome — their tokens
+        // never appear on the parent stream, so this is the only place they are accounted.
+        await subagents?.stop();
+        const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 };
+        const subCalls = subagents?.calls() ?? [];
+        const mergedCalls = [...calls, ...subCalls];
+        // INVARIANT (do not "fix" this into a double count): the run total is the parent usage
+        // PLUS the subagent usage because the two are disjoint sources. The parent `usage` here
+        // is the terminal `result` event's cumulative, which covers ONLY the parent loop — the
+        // ADR 0026 incident is itself the proof: a heavily subagent-parallelised review reported
+        // ~0 tokens, i.e. the parent stream (and its `result` total) never included the subagent
+        // spend. The subagent tokens live exclusively in the `subagents/*.jsonl` transcripts (a
+        // directory distinct from the parent's `projects/` session transcript), which the watcher
+        // reads and nothing else does — so neither `calls` nor `usage` can already contain them.
+        const mergedUsage = usage || subUsage.inputTokens || subUsage.outputTokens
+            ? {
+                inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+                outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+            }
+            : undefined;
         return {
             summary,
             stats,
             stderrTail,
-            ...(usage ? { usage } : {}),
-            ...(calls.length ? { callMetrics: calls } : {}),
+            ...(mergedUsage ? { usage: mergedUsage } : {}),
+            ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
         };
     }
     finally {
+        await subagents?.stop();
         if (configHome) {
             // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
             // home is deleted — the credential lives at the home root, never in `projects/`, so this
@@ -348,38 +450,6 @@ function claudeUsage(raw) {
         return undefined;
     return { inputTokens: input, outputTokens: output };
 }
-/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
-function claudeAssistantContent(content) {
-    let text = '';
-    let reasoning = '';
-    let toolUses = 0;
-    for (const block of content) {
-        if (!isObject(block))
-            continue;
-        if (block.type === 'text' && typeof block.text === 'string')
-            text += block.text;
-        else if (block.type === 'thinking' && typeof block.thinking === 'string')
-            reasoning += block.thinking;
-        else if (block.type === 'tool_use')
-            toolUses += 1;
-    }
-    return { text, reasoning, toolUses };
-}
-/**
- * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
- */
-function claudeCallUsage(raw) {
-    if (!isObject(raw))
-        return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 };
-    const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens);
-    return {
-        inputTokens: numberOf(raw.input_tokens) + cached,
-        cachedInputTokens: cached,
-        outputTokens: numberOf(raw.output_tokens),
-    };
-}
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------
@@ -422,10 +492,9 @@ export async function runCodex(opts) {
         await writeFile(join(codexHome, 'config.toml'), 'cli_auth_credentials_store = "file"\n', 'utf8');
     }
     // Codex has no system-prompt flag, so fold the composed role + best-practice
-    // context into the prompt itself (Claude Code instead rides --append-system-prompt).
-    const prompt = opts.systemPrompt
-        ? `${opts.systemPrompt}\n\n---\n\n${opts.userPrompt}`
-        : opts.userPrompt;
+    // context into the prompt itself (Claude Code instead rides --append-system-prompt,
+    // falling back to this same fold when the prompt overflows argv).
+    const prompt = foldSystemPrompt(opts.systemPrompt, opts.userPrompt);
     // Codex's `exec --json` is far thinner than Claude Code's stream: it surfaces only
     // flat assistant text and (on `token_count` events) the per-turn `last_token_usage`
     // plus a cumulative total. It never exposes the request transcript or structured
@@ -622,9 +691,6 @@ function codexLastTurnUsage(event) {
         return undefined;
     return { inputTokens: input, cachedInputTokens: cached, outputTokens: output };
 }
-function numberOf(value) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
-}
 /** Dispatch to the configured subscription harness runner. */
 export function runSubscriptionHarness(harness, opts) {
     return harness === 'claude-code' ? runClaudeCode(opts) : runCodex(opts);

package/dist/claude-stream.js

@@ -0,0 +1,48 @@
+import { redact } from './redact.js';
+// Shared parsing of Claude Code's stream-json / session-transcript envelope. The parent
+// runner (`agent-runner.ts`) reads these off the CLI's stdout; the subagent watcher
+// (`subagents.ts`) reads the same shapes off the `subagents/*.jsonl` transcripts. Kept in
+// one place so both read usage/content identically and the cycle between the two modules
+// is broken.
+export function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function numberOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
+export function redactBody(text, secrets) {
+    return secrets.length ? redact(text, secrets) : text;
+}
+/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
+export function claudeAssistantContent(content) {
+    let text = '';
+    let reasoning = '';
+    let toolUses = 0;
+    for (const block of content) {
+        if (!isObject(block))
+            continue;
+        if (block.type === 'text' && typeof block.text === 'string')
+            text += block.text;
+        else if (block.type === 'thinking' && typeof block.thinking === 'string')
+            reasoning += block.thinking;
+        else if (block.type === 'tool_use')
+            toolUses += 1;
+    }
+    return { text, reasoning, toolUses };
+}
+/**
+ * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
+ * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
+ * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ */
+export function claudeCallUsage(raw) {
+    if (!isObject(raw))
+        return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 };
+    const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens);
+    return {
+        inputTokens: numberOf(raw.input_tokens) + cached,
+        cachedInputTokens: cached,
+        outputTokens: numberOf(raw.output_tokens),
+    };
+}

package/dist/onboarding-preseed.js

@@ -0,0 +1,67 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// ADR 0026 D4 (paired assertion). A brand-new Claude Code config home would otherwise
+// make `claude -p` block on the interactive onboarding / "trust this folder" /
+// bypass-permissions acknowledgement prompts — which never get answered headlessly,
+// hanging the job until the inactivity watchdog kills it with no output. We pre-seed a
+// `.claude.json` marking those gates as already accepted.
+//
+// The hazard the ADR calls out: if a future CLI version adds a NEW first-run gate this
+// set does not cover, the symptom is identical to a healthy-but-quiet subagent run (no
+// stdout, low CPU), so the cold-start watchdog can't tell them apart on its own. This
+// module centralises the pre-seeded keys as ONE source of truth and logs the pinned set
+// (with the installed CLI version) so that, when the cold-start watchdog fires, an
+// operator has the exact keys-vs-version pairing to diff against a new gate.
+/**
+ * The onboarding gates we pre-accept in a fresh config home. Kept as a single constant so
+ * the write and the assertion below can never drift, and so a new gate is added in exactly
+ * one place. If the CLI renames/adds a key, this is where the fix lands.
+ */
+export const ONBOARDING_PRESEED_KEYS = {
+    hasCompletedOnboarding: true,
+    bypassPermissionsModeAccepted: true,
+    hasTrustDialogAccepted: true,
+};
+/** Write the onboarding pre-seed into `<configHome>/.claude.json`. Best-effort; never throws. */
+export async function writeOnboardingPreseed(configHome) {
+    await writeFile(join(configHome, '.claude.json'), JSON.stringify(ONBOARDING_PRESEED_KEYS), {
+        mode: 0o600,
+    }).catch(() => { });
+}
+/**
+ * Verify the pre-seed actually landed and log the pinned onboarding keys alongside the
+ * installed CLI version — the "one-line assertion after the pre-seed" from D4. It cannot
+ * introspect the CLI's true first-run gate set (the CLI never exposes it), so it does the
+ * two things it CAN do cheaply and deterministically: confirm every key we intended is
+ * present + truthy in the written file (catching a botched write), and emit a structured
+ * record pairing the keys with the CLI version so a future onboarding regression — surfaced
+ * by the cold-start watchdog as a silent, output-less start — is diffable against a new gate.
+ * Best-effort; never throws.
+ */
+export async function assertOnboardingKeysCurrent(configHome, cliVersion, log) {
+    const expected = Object.keys(ONBOARDING_PRESEED_KEYS);
+    let parsed = {};
+    try {
+        parsed = JSON.parse(await readFile(join(configHome, '.claude.json'), 'utf8'));
+    }
+    catch {
+        log?.warn('onboarding pre-seed could not be read back after write', {
+            onboardingKeys: expected,
+            ...(cliVersion ? { cliVersion } : {}),
+        });
+        return;
+    }
+    const missing = expected.filter((k) => parsed[k] !== true);
+    if (missing.length > 0) {
+        log?.warn('onboarding pre-seed is missing expected keys', {
+            onboardingKeys: expected,
+            missing,
+            ...(cliVersion ? { cliVersion } : {}),
+        });
+        return;
+    }
+    log?.info('onboarding pre-seed applied', {
+        onboardingKeys: expected,
+        ...(cliVersion ? { cliVersion } : {}),
+    });
+}

package/dist/runner.js

@@ -5,6 +5,13 @@ function intEnv(value, fallback) {
     const n = value ? Number(value) : NaN;
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
+/** Like {@link intEnv} but allows an explicit 0 (used to DISABLE a window). */
+function intEnvAllowZero(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
 export function loadRunnerLimits(env = process.env) {
     return {
         // 60 minutes: generous headroom for serious multi-file coding tasks while
@@ -17,6 +24,9 @@ export function loadRunnerLimits(env = process.env) {
         // with git's own clear reason rather than this watchdog's "likely hung" message,
         // for any configured window. See the invariant note in git.ts.
         inactivityMs: intEnv(env.JOB_INACTIVITY_MS, 10 * 60_000),
+        // 2 minutes: comfortably longer than a warm agent's time-to-first-token yet far
+        // under the 10-minute inactivity kill, so a truly output-less start is flagged early.
+        coldStartMs: intEnvAllowZero(env.JOB_COLD_START_MS, 2 * 60_000),
     };
 }
 function toView(entry) {
@@ -154,7 +164,27 @@ export class JobRegistry {
             killReason ??= 'max-duration';
             controller.abort(new Error('max duration exceeded'));
         }, this.limits.maxDurationMs);
+        // ADR 0026 D4: a one-shot cold-start watchdog. If the job produces no activity within
+        // `coldStartMs`, record a structured diagnostic (a likely onboarding/auth wedge) so it
+        // is legible early — it does NOT abort the run (the inactivity watchdog still owns
+        // that). Cleared the moment the first activity arrives.
+        let sawActivity = false;
+        let coldStart;
+        if (this.limits.coldStartMs > 0) {
+            coldStart = setTimeout(() => {
+                if (sawActivity)
+                    return;
+                const secs = Math.round(this.limits.coldStartMs / 1000);
+                const message = `agent produced no output ${secs}s after start; possible onboarding/auth wedge (phase: ${phase})`;
+                entry.coldStart = { atMs: Date.now(), message };
+                jobLog.warn('cold-start: no agent output', { afterMs: this.limits.coldStartMs, phase });
+            }, this.limits.coldStartMs);
+        }
         const heartbeat = () => {
+            if (!sawActivity) {
+                sawActivity = true;
+                clearTimeout(coldStart);
+            }
             entry.heartbeatAt = Date.now();
             resetInactivity();
         };
@@ -213,6 +243,7 @@ export class JobRegistry {
         finally {
             clearTimeout(inactivity);
             clearTimeout(cap);
+            clearTimeout(coldStart);
             entry.abort = undefined;
             entry.heartbeatAt = Date.now();
         }