@cat-factory/executor-harness 1.50.6 → 1.50.10

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
@@ -223,6 +219,20 @@ export async function runClaudeCode(opts) {
             { 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)) {
@@ -237,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.
@@ -261,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')
@@ -288,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
@@ -320,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',
@@ -339,16 +369,40 @@ export async function runClaudeCode(opts) {
                 ...appendArgs,
             ],
         }, 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
@@ -396,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
 // ---------------------------------------------------------------------------
@@ -669,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/agent.js

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
@@ -405,6 +405,28 @@ async function runExploreMode(job, opts) {
                 fetched: fetched.length,
             });
         }
+        // The pr-reviewer reviews an EXISTING PR: fetch its HEAD into `origin/pr-head` so the
+        // read-only agent can inspect the PROPOSED code — files the PR adds (absent from this base
+        // checkout) and the head version of every modified file. The agent holds no git credential
+        // of its own, so this harness-side fetch (token out of band) is the only way the head is
+        // reachable; the prompt then diffs `origin/<base>...origin/pr-head`. Best-effort: on failure
+        // the review proceeds on the base checkout + the injected `.cat-context/pr-diff.md`.
+        if (job.reviewPrNumber !== undefined) {
+            const provider = job.repo.provider ?? inferVcsProvider(job.repo.cloneUrl);
+            const fetched = await fetchPullRequestHead({
+                dir,
+                number: job.reviewPrNumber,
+                provider,
+                ghToken: job.ghToken,
+                signal: opts.signal,
+                onSkip: (reason) => logger.warn('agent(explore): PR head fetch skipped', {
+                    number: job.reviewPrNumber,
+                    provider,
+                    reason,
+                }),
+            });
+            logger.info('agent(explore): PR head fetch', { number: job.reviewPrNumber, fetched });
+        }
         // Optional infra stand-up (the tester): bring the service's docker-compose
         // dependencies up at the repo root for the duration of the run, tearing them down in
         // the `finally`. A stand-up failure is non-fatal — it's surfaced to the agent as a

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/git.js

@@ -691,6 +691,46 @@ export async function fetchReferenceBranches(opts) {
         await excludeFromGit(dir, `${REFERENCE_WORKTREE_DIR}/`, signal);
     return fetched;
 }
+/** The local tracking ref a fetched PR/MR head lands on, so the reviewer reads `origin/pr-head`. */
+export const PR_HEAD_REF = 'refs/remotes/origin/pr-head';
+/**
+ * The `git fetch` refspec that maps a PR/MR's server-side HEAD ref onto {@link PR_HEAD_REF}. A
+ * PR head is a synthetic ref the host maintains, NOT part of a normal clone: GitHub exposes it at
+ * `refs/pull/<n>/head`, GitLab at `refs/merge-requests/<n>/head`. Pure so the provider branch is
+ * unit-tested without a network. The leading `+` forces the update (the ref is read-only here).
+ */
+export function pullHeadRefspec(number, provider) {
+    const src = provider === 'gitlab' ? `refs/merge-requests/${number}/head` : `refs/pull/${number}/head`;
+    return `+${src}:${PR_HEAD_REF}`;
+}
+/**
+ * Fetch the reviewed PR/MR's HEAD into {@link PR_HEAD_REF} so a read-only reviewer can inspect the
+ * PROPOSED code — files the PR adds (absent from the base checkout) and the head version of every
+ * modified file — with `git diff origin/<base>...origin/pr-head`, `git show origin/pr-head:<path>`.
+ * The base clone never includes the pull ref, and the container agent holds no git credential of
+ * its own (the token lives with the harness), so the agent's own `git fetch pull/<n>/head` fails
+ * on a private repo — this harness-side fetch (which carries the token out of band via GIT_ASKPASS,
+ * exactly like {@link fetchReferenceBranches}) is what actually makes the head reachable.
+ *
+ * Best-effort: a fetch failure (a closed/deleted PR, a host without the pull ref, a transient
+ * network error) is reported via `onSkip` and swallowed — the review then proceeds on the base
+ * checkout + the injected diff, never fails. Returns whether the head was fetched.
+ */
+export async function fetchPullRequestHead(opts) {
+    const { dir, number, provider, ghToken, signal, onSkip } = opts;
+    try {
+        await git(['fetch', '--no-tags', 'origin', pullHeadRefspec(number, provider)], {
+            cwd: dir,
+            signal,
+            env: await authEnv(ghToken),
+        });
+        return true;
+    }
+    catch (err) {
+        onSkip?.(err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
 /**
  * Push the work branch to origin. The remote URL carries only the username, so
  * the token is supplied here via the askpass env (never in argv).

package/dist/job.js

@@ -684,6 +684,7 @@ export function parseAgentJob(input) {
     const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const validation = parseValidationSpec(o.validation);
+    const reviewPrNumber = posInt(o.reviewPrNumber);
     const job = {
         jobId: str(o.jobId, 'jobId'),
         mode,
@@ -715,6 +716,7 @@ export function parseAgentJob(input) {
         ...(peerRepos.length ? { peerRepos } : {}),
         ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(referenceBranches.length ? { referenceBranches } : {}),
+        ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),

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();
         }