@cat-factory/executor-harness 1.50.16 → 1.52.0

package/README.md

@@ -35,6 +35,19 @@ are surfaced as `progress` while a job runs. The exact request/response shapes
 cat-factory sends are documented in
 [`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md).
 
+`GET /jobs/{id}` is also the harness's observability channel: `spans`, `followUps`
+and `callMetrics` are **drain-on-read** — each poll returns what accumulated since
+the previous one and clears the buffer. That is deliberate. A job that dies before
+it can return a terminal result (an evicted container, an OOM-killed process) has
+still reported the tool spans it ran and the model calls it paid for. Each drained
+`callMetrics` entry carries a job-scoped `seq`, and the terminal result repeats the
+complete list, so the backend can take both channels without double-counting a call.
+
+Because the backend records a call as soon as it drains it (and ignores the terminal
+repeat), a drained call is FINAL. A call whose tokens are still open — a CLI that reports
+only a cumulative total, costed at the end — is withheld from the drain until it is
+complete; see `createCallMetricPublisher` in `src/pi.ts`.
+
 ## What a job does
 
 The implementation job (`POST /run`) is the canonical sequence:

package/dist/agent-runner.js

@@ -3,6 +3,7 @@ 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 { createCallMetricPublisher, publishCallMetric, } from './pi.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
 import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js';
@@ -219,6 +220,9 @@ export async function runClaudeCode(opts) {
             { role: 'user', content: opts.userPrompt },
         ];
     const calls = [];
+    // Streams each call as the CLI yields it, EXCEPT one whose tokens `attributeCumulativeUsage`
+    // may still rewrite below (a published call must be final — see the publisher).
+    const publisher = createCallMetricPublisher(calls, opts.onCallMetric);
     // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
     // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
     // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
@@ -256,7 +260,7 @@ export async function runClaudeCode(opts) {
             // 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.
             const u = claudeCallUsage(message.usage);
-            calls.push({
+            publisher.publish({
                 ...(typeof message.model === 'string' ? { model: message.model } : {}),
                 promptText: redactBody(JSON.stringify(messages), secrets),
                 messageCount: messages.length,
@@ -319,21 +323,7 @@ export async function runClaudeCode(opts) {
             : join(homedir(), '.claude', 'skills');
         await writeNativeSkill(skillsRoot, opts.skill).catch(() => { });
     }
-    // Anthropic itself authenticates with the subscription OAuth token; a
-    // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
-    // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.
-    // Ambient mode injects neither — the CLI uses the developer's logged-in `~/.claude`.
-    const env = opts.ambientAuth
-        ? {}
-        : {
-            CLAUDE_CONFIG_DIR: configHome,
-            ...(opts.subscriptionBaseUrl
-                ? {
-                    ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
-                    ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken,
-                }
-                : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
-        };
+    const env = buildClaudeEnv(opts, configHome);
     // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
     // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
     // heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible token spend is
@@ -347,6 +337,7 @@ export async function runClaudeCode(opts) {
             ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
             secrets,
             model: opts.model,
+            ...(opts.onCallMetric ? { onCallMetric: opts.onCallMetric } : {}),
             ...(opts.log ? { log: opts.log } : {}),
         })
         : undefined;
@@ -369,38 +360,15 @@ 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 per-session `subagents/*.jsonl`
-        // transcripts, which the watcher reads and nothing else does; it deliberately EXCLUDES the
-        // sibling parent session transcript (whose usage `result` already totals), so neither
-        // `calls` nor `usage` can already contain the subagent spend.
-        const mergedUsage = usage || subUsage.inputTokens || subUsage.outputTokens
-            ? {
-                inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
-                outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
-            }
-            : undefined;
-        return {
+        return await assembleClaudeOutcome({
             summary,
             stats,
             stderrTail,
-            ...(mergedUsage ? { usage: mergedUsage } : {}),
-            ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
-        };
+            calls,
+            publisher,
+            usage,
+            subagents,
+        });
     }
     finally {
         await subagents?.stop();
@@ -417,6 +385,63 @@ export async function runClaudeCode(opts) {
         }
     }
 }
+/**
+ * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
+ * auth (Anthropic OAuth token, or an Anthropic-compatible base URL + auth token for a
+ * non-Anthropic Claude-Code vendor like GLM/Kimi/DeepSeek), or an empty env in ambient mode
+ * (the developer's own logged-in `~/.claude` is used). Extracted from {@link runClaudeCode} to
+ * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
+ */
+function buildClaudeEnv(opts, configHome) {
+    if (opts.ambientAuth)
+        return {};
+    return {
+        CLAUDE_CONFIG_DIR: configHome,
+        ...(opts.subscriptionBaseUrl
+            ? {
+                ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
+                ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken,
+            }
+            : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
+    };
+}
+/**
+ * Merge the parent-loop telemetry with the subagents' out-of-band usage + per-call metrics into
+ * the run outcome. 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` (the
+ * terminal `result` event's cumulative) covers ONLY the parent loop, and the subagent tokens live
+ * exclusively in the per-session `subagents/*.jsonl` transcripts the watcher reads. Extracted from
+ * {@link runClaudeCode} verbatim to keep its cyclomatic complexity down.
+ */
+async function assembleClaudeOutcome(args) {
+    const { summary, stats, stderrTail, calls, publisher, usage, subagents } = args;
+    // 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);
+    // The withheld calls are final only NOW, so stream them: the completion poll drains them
+    // alongside the result, and the backend records the attributed numbers rather than the zeros
+    // they carried while the run was in flight.
+    publisher.flush();
+    // 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.
+    await subagents?.stop();
+    const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 };
+    const subCalls = subagents?.calls() ?? [];
+    const mergedCalls = [...calls, ...subCalls];
+    const mergedUsage = usage || subUsage.inputTokens || subUsage.outputTokens
+        ? {
+            inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+            outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+        }
+        : undefined;
+    return {
+        summary,
+        stats,
+        stderrTail,
+        ...(mergedUsage ? { usage: mergedUsage } : {}),
+        ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
+    };
+}
 /** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
 function todosToProgress(todos) {
     if (!Array.isArray(todos))
@@ -529,7 +554,7 @@ export async function runCodex(opts) {
         // assistant text seen since the previous turn as one telemetry call.
         const perTurn = codexLastTurnUsage(event);
         if (perTurn) {
-            calls.push({
+            publishCallMetric(calls, {
                 model: opts.model,
                 promptText: redactBody(JSON.stringify(messages), secrets),
                 messageCount: messages.length,
@@ -539,7 +564,7 @@ export async function runCodex(opts) {
                 cachedInputTokens: perTurn.cachedInputTokens,
                 outputTokens: perTurn.outputTokens,
                 finishReason: null,
-            });
+            }, opts.onCallMetric);
             if (pendingText)
                 messages.push({ role: 'assistant', content: pendingText });
             pendingText = '';
@@ -563,7 +588,7 @@ export async function runCodex(opts) {
         // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
         // single call from the cumulative total + final text so the run is still observable.
         if (calls.length === 0 && (usage || summary)) {
-            calls.push({
+            publishCallMetric(calls, {
                 model: opts.model,
                 promptText: redactBody(JSON.stringify(messages), secrets),
                 messageCount: messages.length,
@@ -573,7 +598,7 @@ export async function runCodex(opts) {
                 cachedInputTokens: 0,
                 outputTokens: usage?.outputTokens ?? 0,
                 finishReason: null,
-            });
+            }, opts.onCallMetric);
         }
         return {
             summary,

package/dist/agent.js

@@ -745,14 +745,12 @@ async function runCodingMode(job, opts) {
     return result;
 }
 /**
- * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
- * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
- * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal no-op for
- * the in-place fixers (and for a seed-only kind like `repro-test`).
+ * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
+ * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
+ * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
  */
-async function runSingleRepoCoding(job, opts) {
-    const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } = await runCodingAgent({
+function buildSingleRepoCodingSpec(job, pushBranch) {
+    return {
         kind: 'agent',
         jobId: job.jobId,
         repo: job.repo,
@@ -789,7 +787,17 @@ async function runSingleRepoCoding(job, opts) {
                 },
             }
             : {}),
-    }, opts);
+    };
+}
+/**
+ * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
+ * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
+ * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal no-op for
+ * the in-place fixers (and for a seed-only kind like `repro-test`).
+ */
+async function runSingleRepoCoding(job, opts) {
+    const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
     // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
     // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
     const ralphVerdict = validation ? { ralphVerdict: validation } : {};

package/dist/job.js

@@ -555,6 +555,24 @@ function isReservedEnvName(key) {
     const lower = key.toLowerCase();
     return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
 }
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+function parseInfraEnv(raw) {
+    const env = {};
+    if (typeof raw === 'object' && raw !== null) {
+        for (const [key, val] of Object.entries(raw)) {
+            if (key && !isReservedEnvName(key) && typeof val === 'string')
+                env[key] = val;
+        }
+    }
+    return env;
+}
 /** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
 function parseFrontendInfraSpec(o) {
     const packageManager = o.packageManager === 'pnpm' || o.packageManager === 'npm' || o.packageManager === 'yarn'
@@ -562,18 +580,7 @@ function parseFrontendInfraSpec(o) {
         : undefined;
     const serveMode = o.serveMode === 'static' || o.serveMode === 'command' ? o.serveMode : undefined;
     const envInjection = o.envInjection === 'build' || o.envInjection === 'runtime' ? o.envInjection : undefined;
-    // Only string→string entries survive; a non-string value is dropped so a malformed
-    // binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved names
-    // that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
-    // dropped too: they are spread over `process.env` at build time, so a binding named `PATH`
-    // would replace it with a URL and the build would no longer find its tools.
-    const env = {};
-    if (typeof o.env === 'object' && o.env !== null) {
-        for (const [key, val] of Object.entries(o.env)) {
-            if (key && !isReservedEnvName(key) && typeof val === 'string')
-                env[key] = val;
-        }
-    }
+    const env = parseInfraEnv(o.env);
     const servePort = port(o.servePort);
     const wiremockPort = port(o.wiremockPort);
     // The app's monorepo subdirectory becomes the install/build/serve cwd, so it goes through the
@@ -732,11 +739,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ghToken: str(o.ghToken, 'ghToken'),
         repo: parseRepoSpec(repo),
         branch: str(o.branch, 'branch'),
-        ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
-        ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
-        ...(o.webSearch === true ? { webSearch: true } : {}),
-        ...(o.full === true ? { full: true } : {}),
-        ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+        ...collectOptionalRequestFields(o),
         ...(bootstrap ? { bootstrap } : {}),
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
@@ -744,20 +747,35 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(skill ? { skill } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
-        ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
-        ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
-        ...(typeof o.commitMessage === 'string' && o.commitMessage
-            ? { commitMessage: o.commitMessage }
-            : {}),
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),
         ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(referenceBranches.length ? { referenceBranches } : {}),
         ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
+        ...(guardLimits ? { guardLimits } : {}),
+        ...(validation ? { validation } : {}),
+    };
+}
+/**
+ * The optional {@link AgentJob} fields read directly off the request `o` (booleans + trimmed
+ * strings). Extracted from {@link assembleAgentJob} to keep its cyclomatic complexity down; every
+ * key is unique so grouping the conditional spreads is behaviour-neutral (spread order is
+ * irrelevant with no colliding keys).
+ */
+function collectOptionalRequestFields(o) {
+    return {
+        ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
+        ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
+        ...(o.webSearch === true ? { webSearch: true } : {}),
+        ...(o.full === true ? { full: true } : {}),
+        ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+        ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
+        ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
+        ...(typeof o.commitMessage === 'string' && o.commitMessage
+            ? { commitMessage: o.commitMessage }
+            : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
-        ...(guardLimits ? { guardLimits } : {}),
-        ...(validation ? { validation } : {}),
     };
 }

package/dist/pi-workspace.js

@@ -147,6 +147,10 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             signal: opts.signal,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            // Stream this run's per-call telemetry to the job's live drain. The subscription
+            // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
+            // proxy as they happen), so this is the only path that needs the hook.
+            onCallMetric: opts.onCallMetric,
             ...(opts.log ? { log: opts.log } : {}),
         });
         return withEffortReport(spec.dir, subOutcome);

package/dist/pi.js

@@ -344,6 +344,65 @@ export async function writeWebToolsConfig(config) {
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
+/**
+ * Publish one captured model call: append it to the run's list (which becomes the terminal
+ * result's `callMetrics`) AND hand the SAME object to the live stream, where the job registry
+ * stamps its {@link HarnessCallMetric.seq} and buffers it for the next poll to drain.
+ *
+ * Every producer goes through here rather than a bare `calls.push`, so the two channels can't
+ * drift: a call that reaches the terminal list but never the live stream would be invisible
+ * until the job ends, and one that reaches only the live stream would go unrecorded if the
+ * poll response were lost.
+ *
+ * A published call must be FINAL. The backend records it the moment the drain reaches it and
+ * IGNORES the terminal repeat (first write wins, so its stored prompt delta stays valid against
+ * the chain tip it was written against), which means a field mutated after publishing never
+ * reaches the store. A producer whose calls can still change (the cumulative-usage fallback,
+ * whose totals arrive with the CLI's terminal `result` event) publishes through
+ * {@link createCallMetricPublisher} instead, which withholds exactly those.
+ */
+export function publishCallMetric(calls, call, onCallMetric) {
+    calls.push(call);
+    onCallMetric?.(call);
+}
+/**
+ * A {@link publishCallMetric} wrapper for a producer whose per-call tokens may be filled in at
+ * the END of the run: a CLI that reports only a cumulative total leaves every turn at zero, and
+ * `attributeCumulativeUsage` pins the total onto the last call once the terminal `result` event
+ * arrives.
+ *
+ * Since a published call must be final (the backend stores it on the drain and ignores the
+ * terminal repeat), a call the CLI did NOT cost is appended to the list but WITHHELD from the
+ * live stream — otherwise it records as a zero-token row and the attributed numbers never land.
+ * The withholding window closes the moment any call IS costed: attribution can no longer fire, so
+ * everything held is final and released at once, in capture order, and every later call streams
+ * immediately whatever its tokens. {@link flush} covers the run that was never costed at all.
+ */
+export function createCallMetricPublisher(calls, onCallMetric) {
+    const withheld = [];
+    let anyCosted = false;
+    const flush = () => {
+        for (const call of withheld)
+            onCallMetric?.(call);
+        withheld.length = 0;
+    };
+    return {
+        publish(call) {
+            const costed = call.inputTokens > 0 || call.outputTokens > 0;
+            if (!costed && !anyCosted) {
+                publishCallMetric(calls, call);
+                withheld.push(call);
+                return;
+            }
+            if (costed)
+                anyCosted = true;
+            // Released BEFORE this call so the live sequence stays in capture order.
+            flush();
+            publishCallMetric(calls, call, onCallMetric);
+        },
+        flush,
+    };
+}
 /**
  * Pull the `todo` tool's result `details` out of a Pi `--mode json` event, or
  * undefined if the event isn't a successful `todo` tool result.

package/dist/runner.js

@@ -30,7 +30,7 @@ export function loadRunnerLimits(env = process.env) {
     };
 }
 function toView(entry) {
-    const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, abort: _abort, ...view } = entry;
+    const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, callMetricBuffer: _callMetricBuffer, callMetricSeq: _callMetricSeq, abort: _abort, ...view } = entry;
     return { ...view };
 }
 /**
@@ -75,15 +75,18 @@ export class JobRegistry {
             promise: Promise.resolve(),
             spanBuffer: [],
             followUpBuffer: [],
+            callMetricBuffer: [],
+            callMetricSeq: 0,
         };
         this.jobs.set(id, entry);
         entry.promise = this.drive(entry, job);
         return toView(entry);
     }
     /**
-     * Poll the job — and DRAIN its tool-span buffer (drain-on-read). The GET /jobs/{id}
-     * handler is the sole caller, so each poll returns the spans accumulated since the
-     * previous poll and clears them, bounding the harness buffer to one poll interval.
+     * Poll the job — and DRAIN its observability buffers (drain-on-read). The GET /jobs/{id}
+     * handler is the sole caller, so each poll returns the spans / follow-ups / call metrics
+     * accumulated since the previous poll and clears them, bounding the harness buffers to one
+     * poll interval.
      */
     get(id) {
         const entry = this.jobs.get(id);
@@ -98,6 +101,10 @@ export class JobRegistry {
             view.followUps = entry.followUpBuffer;
             entry.followUpBuffer = [];
         }
+        if (entry.callMetricBuffer.length > 0) {
+            view.callMetrics = entry.callMetricBuffer;
+            entry.callMetricBuffer = [];
+        }
         return view;
     }
     /**
@@ -206,6 +213,13 @@ export class JobRegistry {
                 onFollowUp: (items) => {
                     entry.followUpBuffer.push(...items);
                 },
+                onCallMetric: (call) => {
+                    // Stamp the job-scoped sequence on the metric OBJECT: the handler keeps the same
+                    // instance for its terminal result, so both channels carry the same `seq` and the
+                    // backend mints one stable row id per call.
+                    call.seq = entry.callMetricSeq++;
+                    entry.callMetricBuffer.push(call);
+                },
                 onPhase: (next) => markPhase(next),
                 log: jobLog,
             });

package/dist/subagents.js

@@ -2,6 +2,7 @@ import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { basename, join } from 'node:path';
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
+import { publishCallMetric } from './pi.js';
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();
@@ -164,7 +165,7 @@ export function startSubagentWatcher(root, opts) {
             return;
         const content = Array.isArray(message.content) ? message.content : [];
         const { text, reasoning } = claudeAssistantContent(content);
-        calls.push({
+        publishCallMetric(calls, {
             ...(typeof message.model === 'string'
                 ? { model: message.model }
                 : opts.model
@@ -180,7 +181,7 @@ export function startSubagentWatcher(root, opts) {
             cachedInputTokens: u.cachedInputTokens,
             outputTokens: u.outputTokens,
             finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
-        });
+        }, opts.onCallMetric);
         usage.inputTokens += u.inputTokens;
         usage.outputTokens += u.outputTokens;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.16",
+  "version": "1.52.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.142.0",
-    "@cat-factory/spend": "0.12.74"
+    "@cat-factory/server": "0.144.0",
+    "@cat-factory/spend": "0.12.77"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -10,7 +10,15 @@ import {
   redactBody,
 } from './claude-stream.js'
 import type { Logger } from './logger.js'
-import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
+import {
+  createCallMetricPublisher,
+  publishCallMetric,
+  type CallMetricPublisher,
+  type HarnessCallMetric,
+  type PiRunOutcome,
+  type PiRunStats,
+  type TodoProgress,
+} from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
 import { createSliceTracker, pickProgress, startSubagentWatcher } from './subagents.js'
@@ -81,6 +89,12 @@ export interface SubscriptionRunOptions {
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
   onProgress?: (progress: TodoProgress) => void
+  /**
+   * Called with each per-call telemetry row as the CLI stream yields it, so the backend can
+   * record the run's model calls WHILE it runs instead of only from its terminal result. The
+   * same row still rides the result, so a lost poll response costs nothing.
+   */
+  onCallMetric?: (call: HarnessCallMetric) => void
   /**
    * The per-job child logger (jobId/repo/branch correlation). Threaded so the retained
    * session-transcript path is logged for the run when the isolated config home is torn down.
@@ -324,6 +338,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         { role: 'user', content: opts.userPrompt },
       ]
   const calls: HarnessCallMetric[] = []
+  // Streams each call as the CLI yields it, EXCEPT one whose tokens `attributeCumulativeUsage`
+  // may still rewrite below (a published call must be final — see the publisher).
+  const publisher = createCallMetricPublisher(calls, opts.onCallMetric)
 
   // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from TWO reconciled
   // sources. The parent's `Task` dispatches + their terminal tool_results DO appear on this
@@ -360,7 +377,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       // 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.
       const u = claudeCallUsage(message.usage)
-      calls.push({
+      publisher.publish({
         ...(typeof message.model === 'string' ? { model: message.model } : {}),
         promptText: redactBody(JSON.stringify(messages), secrets),
         messageCount: messages.length,
@@ -424,21 +441,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     await writeNativeSkill(skillsRoot, opts.skill).catch(() => {})
   }
 
-  // Anthropic itself authenticates with the subscription OAuth token; a
-  // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
-  // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.
-  // Ambient mode injects neither — the CLI uses the developer's logged-in `~/.claude`.
-  const env: Record<string, string> = opts.ambientAuth
-    ? {}
-    : {
-        CLAUDE_CONFIG_DIR: configHome!,
-        ...(opts.subscriptionBaseUrl
-          ? {
-              ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
-              ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken!,
-            }
-          : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
-      }
+  const env = buildClaudeEnv(opts, configHome)
 
   // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
   // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
@@ -453,6 +456,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
         secrets,
         model: opts.model,
+        ...(opts.onCallMetric ? { onCallMetric: opts.onCallMetric } : {}),
         ...(opts.log ? { log: opts.log } : {}),
       })
     : undefined
@@ -484,39 +488,15 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       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 per-session `subagents/*.jsonl`
-    // transcripts, which the watcher reads and nothing else does; it deliberately EXCLUDES the
-    // sibling parent session transcript (whose usage `result` already totals), so neither
-    // `calls` nor `usage` can already contain the subagent spend.
-    const mergedUsage =
-      usage || subUsage.inputTokens || subUsage.outputTokens
-        ? {
-            inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
-            outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
-          }
-        : undefined
-    return {
+    return await assembleClaudeOutcome({
       summary,
       stats,
       stderrTail,
-      ...(mergedUsage ? { usage: mergedUsage } : {}),
-      ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
-    }
+      calls,
+      publisher,
+      usage,
+      subagents,
+    })
   } finally {
     await subagents?.stop()
     if (configHome) {
@@ -533,6 +513,77 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   }
 }
 
+/**
+ * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
+ * auth (Anthropic OAuth token, or an Anthropic-compatible base URL + auth token for a
+ * non-Anthropic Claude-Code vendor like GLM/Kimi/DeepSeek), or an empty env in ambient mode
+ * (the developer's own logged-in `~/.claude` is used). Extracted from {@link runClaudeCode} to
+ * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
+ */
+function buildClaudeEnv(
+  opts: SubscriptionRunOptions,
+  configHome: string | undefined,
+): Record<string, string> {
+  if (opts.ambientAuth) return {}
+  return {
+    CLAUDE_CONFIG_DIR: configHome!,
+    ...(opts.subscriptionBaseUrl
+      ? {
+          ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
+          ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken!,
+        }
+      : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
+  }
+}
+
+/**
+ * Merge the parent-loop telemetry with the subagents' out-of-band usage + per-call metrics into
+ * the run outcome. 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` (the
+ * terminal `result` event's cumulative) covers ONLY the parent loop, and the subagent tokens live
+ * exclusively in the per-session `subagents/*.jsonl` transcripts the watcher reads. Extracted from
+ * {@link runClaudeCode} verbatim to keep its cyclomatic complexity down.
+ */
+async function assembleClaudeOutcome(args: {
+  summary: string
+  stats: PiRunStats
+  stderrTail: string
+  calls: HarnessCallMetric[]
+  /** The live-stream publisher, flushed once attribution has finalised the calls' tokens. */
+  publisher: CallMetricPublisher
+  usage: { inputTokens: number; outputTokens: number } | undefined
+  subagents: ReturnType<typeof startSubagentWatcher> | undefined
+}): Promise<PiRunOutcome> {
+  const { summary, stats, stderrTail, calls, publisher, usage, subagents } = args
+  // 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)
+  // The withheld calls are final only NOW, so stream them: the completion poll drains them
+  // alongside the result, and the backend records the attributed numbers rather than the zeros
+  // they carried while the run was in flight.
+  publisher.flush()
+  // 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.
+  await subagents?.stop()
+  const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 }
+  const subCalls = subagents?.calls() ?? []
+  const mergedCalls = [...calls, ...subCalls]
+  const mergedUsage =
+    usage || subUsage.inputTokens || subUsage.outputTokens
+      ? {
+          inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+          outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+        }
+      : undefined
+  return {
+    summary,
+    stats,
+    stderrTail,
+    ...(mergedUsage ? { usage: mergedUsage } : {}),
+    ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
+  }
+}
+
 /** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
 function todosToProgress(todos: unknown): TodoProgress | undefined {
   if (!Array.isArray(todos)) return undefined
@@ -649,17 +700,21 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     // assistant text seen since the previous turn as one telemetry call.
     const perTurn = codexLastTurnUsage(event)
     if (perTurn) {
-      calls.push({
-        model: opts.model,
-        promptText: redactBody(JSON.stringify(messages), secrets),
-        messageCount: messages.length,
-        responseText: redactBody(pendingText, secrets),
-        reasoningText: '',
-        inputTokens: perTurn.inputTokens,
-        cachedInputTokens: perTurn.cachedInputTokens,
-        outputTokens: perTurn.outputTokens,
-        finishReason: null,
-      })
+      publishCallMetric(
+        calls,
+        {
+          model: opts.model,
+          promptText: redactBody(JSON.stringify(messages), secrets),
+          messageCount: messages.length,
+          responseText: redactBody(pendingText, secrets),
+          reasoningText: '',
+          inputTokens: perTurn.inputTokens,
+          cachedInputTokens: perTurn.cachedInputTokens,
+          outputTokens: perTurn.outputTokens,
+          finishReason: null,
+        },
+        opts.onCallMetric,
+      )
       if (pendingText) messages.push({ role: 'assistant', content: pendingText })
       pendingText = ''
     }
@@ -691,17 +746,21 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
     // single call from the cumulative total + final text so the run is still observable.
     if (calls.length === 0 && (usage || summary)) {
-      calls.push({
-        model: opts.model,
-        promptText: redactBody(JSON.stringify(messages), secrets),
-        messageCount: messages.length,
-        responseText: redactBody(summary, secrets),
-        reasoningText: '',
-        inputTokens: usage?.inputTokens ?? 0,
-        cachedInputTokens: 0,
-        outputTokens: usage?.outputTokens ?? 0,
-        finishReason: null,
-      })
+      publishCallMetric(
+        calls,
+        {
+          model: opts.model,
+          promptText: redactBody(JSON.stringify(messages), secrets),
+          messageCount: messages.length,
+          responseText: redactBody(summary, secrets),
+          reasoningText: '',
+          inputTokens: usage?.inputTokens ?? 0,
+          cachedInputTokens: 0,
+          outputTokens: usage?.outputTokens ?? 0,
+          finishReason: null,
+        },
+        opts.onCallMetric,
+      )
     }
     return {
       summary,

package/src/agent.ts

@@ -903,6 +903,55 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
   return result
 }
 
+/**
+ * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
+ * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
+ * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
+ */
+function buildSingleRepoCodingSpec(
+  job: AgentJob,
+  pushBranch: string,
+): Parameters<typeof runCodingAgent>[0] {
+  return {
+    kind: 'agent',
+    jobId: job.jobId,
+    repo: job.repo,
+    cloneBranch: job.branch,
+    ...(job.newBranch ? { newBranch: job.newBranch } : {}),
+    pushBranch,
+    ghToken: job.ghToken,
+    systemPrompt: job.systemPrompt,
+    userPrompt: job.userPrompt,
+    model: job.model,
+    harness: job.harness,
+    subscriptionToken: job.subscriptionToken,
+    subscriptionBaseUrl: job.subscriptionBaseUrl,
+    ambientAuth: job.ambientAuth,
+    proxyBaseUrl: job.proxyBaseUrl,
+    sessionToken: job.sessionToken,
+    commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
+    webToolsGuidance: job.webToolsGuidance,
+    webSearchProxy: job.webSearch,
+    guardLimits: job.guardLimits,
+    ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
+    ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+    ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
+    // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
+    ...(job.skill ? { skill: job.skill } : {}),
+    // Ralph loop: run the completion command after the agent commits and report its verdict.
+    ...(job.validation
+      ? {
+          validation: {
+            command: job.validation.command,
+            ...(job.validation.iteration !== undefined
+              ? { iteration: job.validation.iteration }
+              : {}),
+          },
+        }
+      : {}),
+  }
+}
+
 /**
  * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
  * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
@@ -912,47 +961,7 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
 async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
   const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch
   const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, effortReport } =
-    await runCodingAgent(
-      {
-        kind: 'agent',
-        jobId: job.jobId,
-        repo: job.repo,
-        cloneBranch: job.branch,
-        ...(job.newBranch ? { newBranch: job.newBranch } : {}),
-        pushBranch,
-        ghToken: job.ghToken,
-        systemPrompt: job.systemPrompt,
-        userPrompt: job.userPrompt,
-        model: job.model,
-        harness: job.harness,
-        subscriptionToken: job.subscriptionToken,
-        subscriptionBaseUrl: job.subscriptionBaseUrl,
-        ambientAuth: job.ambientAuth,
-        proxyBaseUrl: job.proxyBaseUrl,
-        sessionToken: job.sessionToken,
-        commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
-        guardLimits: job.guardLimits,
-        ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
-        ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
-        ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
-        // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
-        ...(job.skill ? { skill: job.skill } : {}),
-        // Ralph loop: run the completion command after the agent commits and report its verdict.
-        ...(job.validation
-          ? {
-              validation: {
-                command: job.validation.command,
-                ...(job.validation.iteration !== undefined
-                  ? { iteration: job.validation.iteration }
-                  : {}),
-              },
-            }
-          : {}),
-      },
-      opts,
-    )
+    await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
   // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
   // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
   const ralphVerdict = validation ? { ralphVerdict: validation } : {}

package/src/job.ts

@@ -1124,6 +1124,24 @@ function isReservedEnvName(key: string): boolean {
   return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p))
 }
 
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+function parseInfraEnv(raw: unknown): Record<string, string> {
+  const env: Record<string, string> = {}
+  if (typeof raw === 'object' && raw !== null) {
+    for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+      if (key && !isReservedEnvName(key) && typeof val === 'string') env[key] = val
+    }
+  }
+  return env
+}
+
 /** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
 function parseFrontendInfraSpec(o: Record<string, unknown>): FrontendInfraSpec {
   const packageManager =
@@ -1133,17 +1151,7 @@ function parseFrontendInfraSpec(o: Record<string, unknown>): FrontendInfraSpec {
   const serveMode = o.serveMode === 'static' || o.serveMode === 'command' ? o.serveMode : undefined
   const envInjection =
     o.envInjection === 'build' || o.envInjection === 'runtime' ? o.envInjection : undefined
-  // Only string→string entries survive; a non-string value is dropped so a malformed
-  // binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved names
-  // that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
-  // dropped too: they are spread over `process.env` at build time, so a binding named `PATH`
-  // would replace it with a URL and the build would no longer find its tools.
-  const env: Record<string, string> = {}
-  if (typeof o.env === 'object' && o.env !== null) {
-    for (const [key, val] of Object.entries(o.env as Record<string, unknown>)) {
-      if (key && !isReservedEnvName(key) && typeof val === 'string') env[key] = val
-    }
-  }
+  const env = parseInfraEnv(o.env)
   const servePort = port(o.servePort)
   const wiremockPort = port(o.wiremockPort)
   // The app's monorepo subdirectory becomes the install/build/serve cwd, so it goes through the
@@ -1376,11 +1384,7 @@ function assembleAgentJob(
     ghToken: str(o.ghToken, 'ghToken'),
     repo: parseRepoSpec(repo),
     branch: str(o.branch, 'branch'),
-    ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
-    ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
-    ...(o.webSearch === true ? { webSearch: true } : {}),
-    ...(o.full === true ? { full: true } : {}),
-    ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+    ...collectOptionalRequestFields(o),
     ...(bootstrap ? { bootstrap } : {}),
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
@@ -1388,20 +1392,36 @@ function assembleAgentJob(
     ...(skill ? { skill } : {}),
     ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
-    ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
-    ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
-    ...(typeof o.commitMessage === 'string' && o.commitMessage
-      ? { commitMessage: o.commitMessage }
-      : {}),
     ...(pr ? { pr } : {}),
     ...(peerRepos.length ? { peerRepos } : {}),
     ...(referenceRepos.length ? { referenceRepos } : {}),
     ...(referenceBranches.length ? { referenceBranches } : {}),
     ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
+    ...(guardLimits ? { guardLimits } : {}),
+    ...(validation ? { validation } : {}),
+  }
+}
+
+/**
+ * The optional {@link AgentJob} fields read directly off the request `o` (booleans + trimmed
+ * strings). Extracted from {@link assembleAgentJob} to keep its cyclomatic complexity down; every
+ * key is unique so grouping the conditional spreads is behaviour-neutral (spread order is
+ * irrelevant with no colliding keys).
+ */
+function collectOptionalRequestFields(o: Record<string, unknown>): Partial<AgentJob> {
+  return {
+    ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
+    ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
+    ...(o.webSearch === true ? { webSearch: true } : {}),
+    ...(o.full === true ? { full: true } : {}),
+    ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+    ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
+    ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
+    ...(typeof o.commitMessage === 'string' && o.commitMessage
+      ? { commitMessage: o.commitMessage }
+      : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
-    ...(guardLimits ? { guardLimits } : {}),
-    ...(validation ? { validation } : {}),
   }
 }

package/src/pi-workspace.ts

@@ -271,6 +271,10 @@ export async function runAgentInWorkspace(
       signal: opts.signal,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
+      // Stream this run's per-call telemetry to the job's live drain. The subscription
+      // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
+      // proxy as they happen), so this is the only path that needs the hook.
+      onCallMetric: opts.onCallMetric,
       ...(opts.log ? { log: opts.log } : {}),
     })
     return withEffortReport(spec.dir, subOutcome)

package/src/pi.ts

@@ -505,6 +505,93 @@ export interface HarnessCallMetric {
   outputTokens: number
   /** The provider finish/stop reason when the CLI reports one (else null). */
   finishReason: string | null
+  /**
+   * This call's position in the JOB's telemetry sequence, stamped by the job registry the
+   * moment the call is emitted (see `RunOptions.onCallMetric`). It is what makes a call's
+   * recorded row id stable across the two channels that carry it: the live drain (per poll,
+   * so a run's telemetry is inspectable WHILE it runs) and the terminal result (the complete
+   * list, so a transport that doesn't drain still records everything). Both channels hold the
+   * SAME metric objects, so both mint the same `<jobId>-hc-<seq>` row id and the backend's
+   * second write of an already-recorded call is a no-op instead of a duplicate row.
+   *
+   * Absent only when a producer built a metric without emitting it live; the recorder then
+   * falls back to the array index, which is what it always used before streaming existed.
+   */
+  seq?: number
+}
+
+/**
+ * Publish one captured model call: append it to the run's list (which becomes the terminal
+ * result's `callMetrics`) AND hand the SAME object to the live stream, where the job registry
+ * stamps its {@link HarnessCallMetric.seq} and buffers it for the next poll to drain.
+ *
+ * Every producer goes through here rather than a bare `calls.push`, so the two channels can't
+ * drift: a call that reaches the terminal list but never the live stream would be invisible
+ * until the job ends, and one that reaches only the live stream would go unrecorded if the
+ * poll response were lost.
+ *
+ * A published call must be FINAL. The backend records it the moment the drain reaches it and
+ * IGNORES the terminal repeat (first write wins, so its stored prompt delta stays valid against
+ * the chain tip it was written against), which means a field mutated after publishing never
+ * reaches the store. A producer whose calls can still change (the cumulative-usage fallback,
+ * whose totals arrive with the CLI's terminal `result` event) publishes through
+ * {@link createCallMetricPublisher} instead, which withholds exactly those.
+ */
+export function publishCallMetric(
+  calls: HarnessCallMetric[],
+  call: HarnessCallMetric,
+  onCallMetric?: (call: HarnessCallMetric) => void,
+): void {
+  calls.push(call)
+  onCallMetric?.(call)
+}
+
+/** Appends captured calls to a run's list, streaming each one as soon as it is final. */
+export interface CallMetricPublisher {
+  /** Append a captured call, streaming it now unless its tokens can still be rewritten. */
+  publish(call: HarnessCallMetric): void
+  /** Stream whatever is still withheld. Call once the run's totals are attributed. */
+  flush(): void
+}
+
+/**
+ * A {@link publishCallMetric} wrapper for a producer whose per-call tokens may be filled in at
+ * the END of the run: a CLI that reports only a cumulative total leaves every turn at zero, and
+ * `attributeCumulativeUsage` pins the total onto the last call once the terminal `result` event
+ * arrives.
+ *
+ * Since a published call must be final (the backend stores it on the drain and ignores the
+ * terminal repeat), a call the CLI did NOT cost is appended to the list but WITHHELD from the
+ * live stream — otherwise it records as a zero-token row and the attributed numbers never land.
+ * The withholding window closes the moment any call IS costed: attribution can no longer fire, so
+ * everything held is final and released at once, in capture order, and every later call streams
+ * immediately whatever its tokens. {@link flush} covers the run that was never costed at all.
+ */
+export function createCallMetricPublisher(
+  calls: HarnessCallMetric[],
+  onCallMetric?: (call: HarnessCallMetric) => void,
+): CallMetricPublisher {
+  const withheld: HarnessCallMetric[] = []
+  let anyCosted = false
+  const flush = (): void => {
+    for (const call of withheld) onCallMetric?.(call)
+    withheld.length = 0
+  }
+  return {
+    publish(call) {
+      const costed = call.inputTokens > 0 || call.outputTokens > 0
+      if (!costed && !anyCosted) {
+        publishCallMetric(calls, call)
+        withheld.push(call)
+        return
+      }
+      if (costed) anyCosted = true
+      // Released BEFORE this call so the live sequence stays in capture order.
+      flush()
+      publishCallMetric(calls, call, onCallMetric)
+    },
+    flush,
+  }
 }
 
 /** Pi's assistant summary plus {@link PiRunStats} describing what it did. */

package/src/runner.ts

@@ -1,6 +1,6 @@
 import { redactSecrets } from './redact.js'
 import type { FollowUpLine } from './follow-ups.js'
-import type { TodoProgress, ToolSpan } from './pi.js'
+import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
   type FailureCause,
@@ -30,6 +30,19 @@ export interface RunOptions {
   onSpan?: (span: ToolSpan) => void
   /** Receives the forward-looking follow-up / question items the Coder streamed since the last poll. */
   onFollowUp?: (items: FollowUpLine[]) => void
+  /**
+   * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
+   * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
+   * result. The registry stamps the call's job-scoped {@link HarnessCallMetric.seq} and buffers
+   * it for the next poll to drain.
+   *
+   * Call this for every metric you also put on the result — the SAME object, not a copy: the
+   * stamped `seq` is what lets the backend recognise the terminal write of an already-recorded
+   * call and skip it. A run that dies mid-flight (the container is evicted, the harness process
+   * is OOM-killed) never produces a terminal result, so without this its entire token spend and
+   * every prompt/response body are lost — exactly the run an operator most needs to inspect.
+   */
+  onCallMetric?: (call: HarnessCallMetric) => void
   /**
    * Mark the coarse lifecycle phase the handler has entered (`clone` / `agent` / `push` / …).
    * Drives the stuck-run breadcrumb: an inactivity kill reports WHICH phase was hung, and the
@@ -114,6 +127,17 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * surfaces the first one (and only on a follow-ups-enabled coding run).
    */
   followUps?: FollowUpLine[]
+  /**
+   * Per-model-call telemetry the agent's CLI stream yielded SINCE THE LAST POLL
+   * (drain-on-read, exactly like {@link spans}). The backend records these into
+   * `llm_call_metrics` as they arrive, so a run's token spend and prompt/response bodies are
+   * queryable while it is still running — and survive it dying before it can produce a
+   * terminal result. Each carries a job-scoped `seq` so the terminal
+   * {@link JobResultBase} list can re-offer the same calls without duplicating rows.
+   * Absent until the agent's first model call (and on the proxy-metered Pi harness, whose
+   * calls the LLM proxy meters directly).
+   */
+  callMetrics?: HarnessCallMetric[]
   /**
    * ADR 0026 D4: set when the cold-start watchdog fired — the job produced NO activity
    * within {@link RunnerLimits.coldStartMs} of starting, a likely onboarding/auth wedge.
@@ -136,6 +160,13 @@ interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
   spanBuffer: ToolSpan[]
   /** Follow-up items buffered since the last drain (see {@link JobView.followUps}). */
   followUpBuffer: FollowUpLine[]
+  /** Call telemetry buffered since the last drain (see {@link JobView.callMetrics}). */
+  callMetricBuffer: HarnessCallMetric[]
+  /**
+   * Next job-scoped {@link HarnessCallMetric.seq} to stamp. Monotonic for the life of the job
+   * (never reset by a drain), so a call's row id stays unique across every poll window.
+   */
+  callMetricSeq: number
   /** Abort the in-flight run (see {@link JobRegistry.abortAll}); set while running only. */
   abort?: (reason: string) => void
 }
@@ -192,6 +223,8 @@ function toView<TResult extends JobResultBase>(entry: JobEntry<TResult>): JobVie
     promise: _promise,
     spanBuffer: _spanBuffer,
     followUpBuffer: _followUpBuffer,
+    callMetricBuffer: _callMetricBuffer,
+    callMetricSeq: _callMetricSeq,
     abort: _abort,
     ...view
   } = entry
@@ -237,6 +270,8 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
       promise: Promise.resolve(),
       spanBuffer: [],
       followUpBuffer: [],
+      callMetricBuffer: [],
+      callMetricSeq: 0,
     }
     this.jobs.set(id, entry)
     entry.promise = this.drive(entry, job)
@@ -244,9 +279,10 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
   }
 
   /**
-   * Poll the job — and DRAIN its tool-span buffer (drain-on-read). The GET /jobs/{id}
-   * handler is the sole caller, so each poll returns the spans accumulated since the
-   * previous poll and clears them, bounding the harness buffer to one poll interval.
+   * Poll the job — and DRAIN its observability buffers (drain-on-read). The GET /jobs/{id}
+   * handler is the sole caller, so each poll returns the spans / follow-ups / call metrics
+   * accumulated since the previous poll and clears them, bounding the harness buffers to one
+   * poll interval.
    */
   get(id: string): JobView<TResult> | undefined {
     const entry = this.jobs.get(id)
@@ -260,6 +296,10 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
       view.followUps = entry.followUpBuffer
       entry.followUpBuffer = []
     }
+    if (entry.callMetricBuffer.length > 0) {
+      view.callMetrics = entry.callMetricBuffer
+      entry.callMetricBuffer = []
+    }
     return view
   }
 
@@ -374,6 +414,13 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         onFollowUp: (items) => {
           entry.followUpBuffer.push(...items)
         },
+        onCallMetric: (call) => {
+          // Stamp the job-scoped sequence on the metric OBJECT: the handler keeps the same
+          // instance for its terminal result, so both channels carry the same `seq` and the
+          // backend mints one stable row id per call.
+          call.seq = entry.callMetricSeq++
+          entry.callMetricBuffer.push(call)
+        },
         onPhase: (next) => markPhase(next),
         log: jobLog,
       })

package/src/subagents.ts

@@ -3,7 +3,7 @@ import { createReadStream, type Dirent } from 'node:fs'
 import { basename, join } from 'node:path'
 import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js'
 import type { Logger } from './logger.js'
-import type { HarnessCallMetric, TodoProgress } from './pi.js'
+import { publishCallMetric, type HarnessCallMetric, type TodoProgress } from './pi.js'
 
 // ADR 0026 D2.1 + D3, corrected by ADR 0027. When the Claude Code CLI reviews a large PR
 // it fans the work out across parallel `Task` subagents. Two things then go dark to the
@@ -155,6 +155,13 @@ export interface SubagentWatcherOptions {
   secrets?: string[]
   /** Fallback model id stamped on a subagent call whose transcript omits one. */
   model?: string
+  /**
+   * Streams each lifted subagent call to the live telemetry drain (the run's `RunOptions`
+   * hook). Subagent work is exactly where a long review spends most of its tokens, and it is
+   * the phase the parent stream goes quiet for — so without this a run killed mid-fan-out
+   * reports nothing at all.
+   */
+  onCallMetric?: (call: HarnessCallMetric) => void
   /** Poll cadence (ms); overridable for tests. */
   intervalMs?: number
   log?: Logger
@@ -244,23 +251,27 @@ export function startSubagentWatcher(root: string, opts: SubagentWatcherOptions)
     if (u.inputTokens === 0 && u.outputTokens === 0) return
     const content = Array.isArray(message.content) ? message.content : []
     const { text, reasoning } = claudeAssistantContent(content)
-    calls.push({
-      ...(typeof message.model === 'string'
-        ? { model: message.model }
-        : opts.model
-          ? { model: opts.model }
-          : {}),
-      // The subagent's own transcript isn't a re-sendable prompt chain, so we don't
-      // reconstruct the request side (kept empty); the response + tokens are faithful.
-      promptText: '',
-      messageCount: 0,
-      responseText: redactBody(text, secrets),
-      reasoningText: redactBody(reasoning, secrets),
-      inputTokens: u.inputTokens,
-      cachedInputTokens: u.cachedInputTokens,
-      outputTokens: u.outputTokens,
-      finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
-    })
+    publishCallMetric(
+      calls,
+      {
+        ...(typeof message.model === 'string'
+          ? { model: message.model }
+          : opts.model
+            ? { model: opts.model }
+            : {}),
+        // The subagent's own transcript isn't a re-sendable prompt chain, so we don't
+        // reconstruct the request side (kept empty); the response + tokens are faithful.
+        promptText: '',
+        messageCount: 0,
+        responseText: redactBody(text, secrets),
+        reasoningText: redactBody(reasoning, secrets),
+        inputTokens: u.inputTokens,
+        cachedInputTokens: u.cachedInputTokens,
+        outputTokens: u.outputTokens,
+        finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
+      },
+      opts.onCallMetric,
+    )
     usage.inputTokens += u.inputTokens
     usage.outputTokens += u.outputTokens
   }