@cat-factory/executor-harness 1.116.0 → 1.118.0

package/README.md

@@ -335,6 +335,7 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc; the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`): talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
 | `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation: the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations, and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
+| `src/usage-attribution.ts` | Reconciles a subscription CLI's TWO token channels: the per-turn usage its stream narrates and the cumulative total its terminal event reports. They disagree routinely and in one direction (Claude Code's per-turn `output_tokens` is the message-START snapshot, single digits), so whatever the turns did not account for becomes ONE extra metric standing for the job (`standsForJob`, filed with a null turn index) rather than tokens grafted onto a real turn, which would make a derived number read as a measured one. Reconciled against the PARENT loop's calls alone, since the terminal cumulative covers only that conversation. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
 | `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls; it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort: every failure shape becomes a note, never a failed job. Generic: keyed off the job body, never the agent kind. |

package/dist/agent-runner.js

@@ -3,11 +3,12 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js';
-import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js';
+import { claudeUsage, unaccountedUsageCall } from './usage-attribution.js';
+import { createClaudeRunTelemetry, subagentDispatchId, } from './claude-call-aggregator.js';
 import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js';
 import { log } from './logger.js';
 import { NO_TOOL_WINDOW } from './tool-silence.js';
-import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
+import { publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js';
 import { ProgressGuard } from './progress-guard.js';
@@ -19,22 +20,6 @@ import { createSliceTracker, startSubagentWatcher } from './subagents.js';
 import { createTaskPlanTracker, mergeProgress, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
-/**
- * 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
- * call rather than dropping it — the run's tokens are still accounted, just not split
- * per turn. A no-op when the calls already carry per-turn tokens.
- */
-function attributeCumulativeUsage(calls, usage) {
-    if (!usage || calls.length === 0)
-        return;
-    const anyTokens = calls.some((c) => c.inputTokens > 0 || c.outputTokens > 0);
-    if (anyTokens)
-        return;
-    const last = calls[calls.length - 1];
-    last.inputTokens = usage.inputTokens;
-    last.outputTokens = usage.outputTokens;
-}
 /**
  * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
  * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
@@ -472,6 +457,59 @@ function openToolWindow(opts) {
 function carriesToolResult(content) {
     return content.some((block) => isObject(block) && block.type === 'tool_result');
 }
+/**
+ * Open the per-call telemetry capture for one claude-code run.
+ *
+ * It reconstructs the full per-call request/response bodies from the stream.
+ * `--output-format stream-json --verbose` emits a near-verbatim Anthropic Messages envelope per
+ * response CONTENT BLOCK (not per call), so the aggregator folds the envelopes sharing a
+ * `message.id` back into one call and buffers that call's `user` tool_result turns — together the
+ * growing prompt transcript, in the shape the model was actually sent. It is SEEDED 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).
+ *
+ * The parent loop's calls are tracked SEPARATELY, by reference into the same list, because the
+ * terminal `result` event's cumulative usage covers only the parent conversation. In `ambientAuth`
+ * mode there is no transcript watcher, so the CLI's tagged subagent turns are captured here too and
+ * `calls` holds both; reconciling against that mixed list is what once billed a subagent for the
+ * parent's whole output shortfall.
+ */
+function openClaudeCallCapture(opts, stream) {
+    const calls = [];
+    const parentCalls = [];
+    const publish = (metric) => publishCallMetric(calls, metric, opts.onCallMetric);
+    // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring in the caller: it is started
+    // only when the CLI has an isolated config home to watch, which an `ambientAuth` run does not
+    // have. The telemetry routes the CLI's tagged subagent turns accordingly — see
+    // `createClaudeRunTelemetry`.
+    const telemetry = createClaudeRunTelemetry({
+        seed: stream.folded
+            ? [{ role: 'user', content: stream.prompt }]
+            : [
+                { role: 'system', content: opts.systemPrompt },
+                { role: 'user', content: opts.userPrompt },
+            ],
+        secrets: stream.secrets,
+        watcherOwnsSubagents: !opts.ambientAuth,
+        publish: (metric) => {
+            parentCalls.push(metric);
+            publish(metric);
+        },
+        publishSubagent: publish,
+    });
+    return {
+        calls,
+        telemetry,
+        settleUsage: (usage) => {
+            // Published like any other call so the live drain records it too, which is also what stamps
+            // its `seq` and therefore its stable row id.
+            const remainder = unaccountedUsageCall(parentCalls, usage);
+            if (remainder)
+                publish(remainder);
+        },
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -488,34 +526,9 @@ export async function runClaudeCode(opts) {
             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 a near-verbatim Anthropic
-    // Messages envelope per response CONTENT BLOCK (not per call), so the aggregator below
-    // folds the envelopes sharing a `message.id` back into one call and buffers that call's
-    // `user` tool_result turns — together the growing prompt transcript, in the shape the
-    // model was actually sent. 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 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);
-    // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring below: it is started only when
-    // the CLI has an isolated config home to watch, which an `ambientAuth` run does not have. The
-    // telemetry routes the CLI's tagged subagent turns accordingly — see `createClaudeRunTelemetry`.
-    const telemetry = createClaudeRunTelemetry({
-        seed: folded
-            ? [{ role: 'user', content: prompt }]
-            : [
-                { role: 'system', content: opts.systemPrompt },
-                { role: 'user', content: opts.userPrompt },
-            ],
-        secrets,
-        watcherOwnsSubagents: !opts.ambientAuth,
-        publish: (metric) => publisher.publish(metric),
-    });
+    const capture = openClaudeCallCapture(opts, { prompt, folded, secrets });
+    const telemetry = capture.telemetry;
     // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from the two views the run
     // produces of the SAME slicing. The parent's subagent dispatches + their terminal tool_results
     // appear on this stream (as do the subagents' own intermediate turns, tagged with the dispatch
@@ -668,8 +681,7 @@ export async function runClaudeCode(opts) {
             summary,
             stats,
             stderrTail,
-            calls,
-            publisher,
+            capture,
             usage,
             subagents,
             expectSubagentCalls: telemetry.expectsWatcherCalls(),
@@ -678,11 +690,11 @@ export async function runClaudeCode(opts) {
     }
     catch (err) {
         // The stream ended abnormally (guard trip, watchdog kill, CLI crash). Complete the call in
-        // flight anyway, and release whatever the publisher was withholding: a killed run never
-        // returns an outcome, so the live channel is the ONLY record of what it spent, and dropping
-        // its last turn is what the streaming exists to avoid.
+        // flight anyway: a killed run never returns an outcome, so the live channel is the ONLY record
+        // of what it spent, and dropping its last turn is what the streaming exists to avoid. No
+        // terminal `result` event arrived, so there is no cumulative total to reconcile against and no
+        // remainder row to file — every captured turn already streamed as it was completed.
         telemetry.flush();
-        publisher.flush();
         // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
         // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail it
         // attached, since that is usually the only evidence of what the CLI was doing when it was
@@ -808,14 +820,11 @@ function buildClaudeEnv(opts, configHome) {
  * loop's telemetry must filter them (`subagentDispatchId`) for this concatenation to hold.
  */
 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();
+    const { summary, stats, stderrTail, capture, usage, subagents } = args;
+    const calls = capture.calls;
+    // What the parent's narrated turns did not account for, as its OWN row (never tokens grafted onto
+    // a real turn).
+    capture.settleUsage(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.
     await subagents?.stop();
@@ -840,21 +849,6 @@ async function assembleClaudeOutcome(args) {
         ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     };
 }
-function claudeUsage(raw) {
-    if (!isObject(raw))
-        return undefined;
-    // Count every input bucket Anthropic bills: fresh input plus BOTH cache reads and
-    // cache writes (cache_creation_input_tokens), which are real consumed tokens — and
-    // are the dominant share on a long agent run. Omitting them under-weights a token's
-    // true load in the usage-aware rotation window.
-    const input = numberOf(raw.input_tokens) +
-        numberOf(raw.cache_read_input_tokens) +
-        numberOf(raw.cache_creation_input_tokens);
-    const output = numberOf(raw.output_tokens);
-    if (input === 0 && output === 0)
-        return undefined;
-    return { inputTokens: input, outputTokens: output };
-}
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------

package/dist/claude-call-aggregator.d.ts

@@ -157,8 +157,17 @@ export interface ClaudeRunTelemetry {
  * `ambientAuth` run has no isolated config home to watch — the tagged turns are recorded here
  * instead, on per-dispatch transcripts of their own. Dropping them in that case would leave the run
  * billed by neither channel, and an under-count reads as a cheap run rather than as an error.
+ *
+ * Which is also why the two are published through SEPARATE callbacks. A caller reconciling the
+ * parent's terminal cumulative usage needs the parent's calls alone, and with one shared callback
+ * the fallback channel silently mixed subagent turns into that list — where they both understated
+ * the shortfall and, being last, attracted it (`unaccountedUsageCall`). `publishSubagent` is
+ * optional so a caller that draws no distinction (a test, the settled-transcript path where nothing
+ * arrives here anyway) keeps one sink.
  */
 export declare function createClaudeRunTelemetry(opts: ClaudeStreamTelemetryOptions & {
     watcherOwnsSubagents: boolean;
+    /** Where a SUBAGENT conversation's call goes. Absent ⇒ `publish`, the parent's sink. */
+    publishSubagent?: (metric: HarnessCallMetric) => void;
 }): ClaudeRunTelemetry;
 export {};

package/dist/claude-call-aggregator.js

@@ -311,10 +311,19 @@ function createSubagentStreamTelemetry(opts) {
  * `ambientAuth` run has no isolated config home to watch — the tagged turns are recorded here
  * instead, on per-dispatch transcripts of their own. Dropping them in that case would leave the run
  * billed by neither channel, and an under-count reads as a cheap run rather than as an error.
+ *
+ * Which is also why the two are published through SEPARATE callbacks. A caller reconciling the
+ * parent's terminal cumulative usage needs the parent's calls alone, and with one shared callback
+ * the fallback channel silently mixed subagent turns into that list — where they both understated
+ * the shortfall and, being last, attracted it (`unaccountedUsageCall`). `publishSubagent` is
+ * optional so a caller that draws no distinction (a test, the settled-transcript path where nothing
+ * arrives here anyway) keeps one sink.
  */
 export function createClaudeRunTelemetry(opts) {
     const parent = createClaudeStreamTelemetry(opts);
-    const subagents = opts.watcherOwnsSubagents ? undefined : createSubagentStreamTelemetry(opts);
+    const subagents = opts.watcherOwnsSubagents
+        ? undefined
+        : createSubagentStreamTelemetry({ ...opts, publish: opts.publishSubagent ?? opts.publish });
     let sawSubagentTurn = false;
     return {
         onAssistant(dispatchId, message) {

package/dist/inline.js

@@ -13,14 +13,27 @@ import { runSubscriptionHarness } from './agent-runner.js';
 // `auth.json`), so the container and coding paths can never disagree on how a credential
 // is injected.
 /**
- * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the
- * inline `finishReason` the reviewer keys off. Only Claude Code reports it (`max_tokens` on
- * a `--output-format stream-json` result); Codex's thinner stream exposes none, so it reads
- * as `stop` — the same one-shot limitation the host-CLI runner has.
+ * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the inline
+ * `finishReason` the reviewer keys off, or `undefined` when the CLI reported NONE.
+ *
+ * Undefined rather than `stop`, which is what this returned for years on the strength of a
+ * comment claiming Claude Code reports the reason. It does not: its `stream-json` `assistant`
+ * envelopes carry the message-START snapshot, whose `stop_reason` is null, so every call metric
+ * a claude-code or codex run produces has a null reason and this answered `stop` for all of them.
+ * `stop` is a positive claim that the model finished of its own accord, and it is the exact claim
+ * a truncation check is trying to disprove — so the one caller keyed off it
+ * (`finishReason === 'length'`) could never fire, and every store that kept the row recorded a
+ * clean stop nobody observed.
+ *
+ * Kept as a MAPPING rather than deleted because the field remains reachable: a subagent turn is
+ * read from a completed JSONL transcript, which does carry `stop_reason`, and a future CLI build
+ * (or `--include-partial-messages`) would restore it on the parent stream too.
  */
 function deriveFinishReason(calls) {
     const last = calls?.[calls.length - 1];
-    const reason = last?.finishReason?.toLowerCase() ?? '';
+    const reason = last?.finishReason?.toLowerCase();
+    if (!reason)
+        return undefined;
     return reason === 'max_tokens' || reason === 'length' ? 'length' : 'stop';
 }
 /**
@@ -51,9 +64,10 @@ export async function handleInline(job, opts) {
             ...(opts.signal ? { signal: opts.signal } : {}),
             ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
         });
+        const finishReason = deriveFinishReason(outcome.callMetrics);
         return {
             text: outcome.summary,
-            finishReason: deriveFinishReason(outcome.callMetrics),
+            ...(finishReason ? { finishReason } : {}),
             ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
             ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
         };

package/dist/job.d.ts

@@ -673,7 +673,14 @@ export interface InlineJob extends HarnessAuthFields {
 /** The inline completion result: the reply text plus lifted token usage / per-call telemetry. */
 export interface InlineResult {
     text: string;
-    /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
+    /**
+     * `length` when the model hit its output cap (the reviewer rejects a truncated doc), `stop`
+     * when it finished of its own accord, ABSENT when the CLI reported no stop reason at all.
+     *
+     * Absent is the normal case today: neither subscription CLI exposes a per-call stop reason on
+     * its parent stream, and the three states must stay distinct because a reader that takes
+     * absent for `stop` is asserting the one thing a truncation check exists to disprove.
+     */
     finishReason?: 'stop' | 'length';
     /**
      * The job's token usage with the input side split into its three ORTHOGONAL classes:

package/dist/pi.d.ts

@@ -304,6 +304,16 @@ export interface HarnessCallMetric {
      * never disagree about which phase billed a call.
      */
     phase?: string;
+    /**
+     * This row is not a TURN: it stands for the job as a whole, carrying the spend the CLI reported
+     * in its terminal cumulative total and did not attribute to any turn it narrated (see
+     * {@link unaccountedUsageCall}). It has no bodies, because there was no request to capture.
+     *
+     * The backend files it with a NULL turn index for that reason, while still deriving its row id
+     * from {@link seq} so a replayed poll re-records instead of duplicating. Absent on every real
+     * turn. `CliInlineLanguageModel`'s step-level row is the same idea on the inline path.
+     */
+    standsForJob?: boolean;
 }
 /**
  * Publish one captured model call: append it to the run's list (which becomes the terminal
@@ -318,32 +328,15 @@ export interface HarnessCallMetric {
  * 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 declare function publishCallMetric(calls: HarnessCallMetric[], call: HarnessCallMetric, onCallMetric?: (call: HarnessCallMetric) => void): void;
-/** 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.
+ * reaches the store.
  *
- * 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.
+ * That is a rule about every producer, and it is why the cumulative-usage reconciliation files its
+ * shortfall as a NEW row here at the end of the run (`unaccountedUsageCall`) rather than growing the
+ * last captured turn. This used to be wrapped by a publisher that withheld the turn attribution
+ * could still rewrite, trading a turn of streaming lag for that mutability; with nothing mutated,
+ * the wrapper had no reason left to exist.
  */
-export declare function createCallMetricPublisher(calls: HarnessCallMetric[], onCallMetric?: (call: HarnessCallMetric) => void): CallMetricPublisher;
+export declare function publishCallMetric(calls: HarnessCallMetric[], call: HarnessCallMetric, onCallMetric?: (call: HarnessCallMetric) => void): void;
 /** Pi's assistant summary plus {@link PiRunStats} describing what it did. */
 export interface PiRunOutcome {
     summary: string;

package/dist/pi.js

@@ -436,52 +436,18 @@ export async function writeWebToolsConfig(config) {
  * 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.
+ * reaches the store.
+ *
+ * That is a rule about every producer, and it is why the cumulative-usage reconciliation files its
+ * shortfall as a NEW row here at the end of the run (`unaccountedUsageCall`) rather than growing the
+ * last captured turn. This used to be wrapped by a publisher that withheld the turn attribution
+ * could still rewrite, trading a turn of streaming lag for that mutability; with nothing mutated,
+ * the wrapper had no reason left to exist.
  */
 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/usage-attribution.d.ts

@@ -0,0 +1,56 @@
+import type { HarnessCallMetric } from './pi.js';
+/**
+ * Read Claude Code's terminal cumulative usage.
+ *
+ * Counts every input bucket Anthropic bills: fresh input plus BOTH cache reads and cache writes
+ * (`cache_creation_input_tokens`), which are real consumed tokens and are the dominant share on a
+ * long agent run. Omitting them under-weights a token's true load in the usage-aware rotation
+ * window. `undefined` when the event carried no usage at all, so a caller can tell that from a
+ * genuine zero.
+ */
+export declare function claudeUsage(raw: unknown): {
+    inputTokens: number;
+    outputTokens: number;
+} | undefined;
+/**
+ * The row standing for whatever the per-turn channel did NOT account for: the terminal cumulative
+ * usage minus the sum of the turns already costed, computed PER SIDE. `undefined` when the turns
+ * add up, so nothing is double counted.
+ *
+ * The per-side part is why this exists at all, and it replaced an all-or-nothing guard
+ * (`calls.some(c => c.inputTokens > 0 || c.outputTokens > 0)` ⇒ return) that only ever fired for a
+ * CLI reporting no per-turn usage at all. Claude Code reports plenty: its `assistant` envelopes
+ * carry the message-START usage snapshot, whose INPUT and cache counts are final and whose
+ * `output_tokens` is the 1-5 tokens produced when the message opened. So the guard saw costed
+ * turns, returned, and the run's whole output side stayed at that snapshot. Measured on a real
+ * board: a `coder` step recorded 198 output tokens across 34 calls against the 14,033 the terminal
+ * `result` event reported, an `initiative-analyst` 531 against 30,471. Input matched the terminal
+ * figure exactly, which is what made the shortfall invisible to a check that asked whether ANY
+ * tokens had been reported.
+ *
+ * **It is its OWN row rather than tokens added to the last captured call.** Growing a real turn by
+ * thousands of output tokens it did not produce makes a fabricated number indistinguishable from a
+ * measured one everywhere a per-call figure is read (`/api/v1/debug/*`, the observability panel, a
+ * step's per-call breakdown), and there is nothing on the row to mark it. The sibling rule on the
+ * inline path (`CliInlineLanguageModel.fileUnaccounted`) reached that conclusion first and files a
+ * step-level row; this is the same answer for the channel that has a call list. {@link
+ * HarnessCallMetric.standsForJob} is what keeps it from reading as a turn.
+ *
+ * **`calls` must be the PARENT loop's alone.** The terminal `result` event's cumulative covers the
+ * parent conversation only — a subagent's tokens live in its own transcript — so subtracting a
+ * subagent turn's tokens from it understates the shortfall, and pinning the remainder near one
+ * would bill a conversation for spend it never saw. Both were live in `ambientAuth` mode, where the
+ * CLI streams subagent turns onto the parent's stdout and no transcript watcher runs, so those
+ * turns are captured through the same publisher as the parent's.
+ *
+ * {@link claudeUsage} sums every billed input bucket, so the already-accounted input is the sum of
+ * all THREE per-call input classes, not `inputTokens` (fresh) alone. A residual input shortfall
+ * lands on `inputTokens` because nothing in the terminal event says which class it belonged to.
+ *
+ * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
+ * reported the two inconsistently, and negative spend is not a thing to record.
+ */
+export declare function unaccountedUsageCall(parentCalls: readonly HarnessCallMetric[], usage: {
+    inputTokens: number;
+    outputTokens: number;
+} | undefined): HarnessCallMetric | undefined;

package/dist/usage-attribution.js

@@ -0,0 +1,96 @@
+import { isObject, numberOf } from './claude-stream.js';
+// How a subscription CLI's TWO token channels are reconciled into the per-call rows the backend
+// stores: the per-turn usage the stream narrates, and the cumulative total the terminal `result`
+// event reports. They disagree routinely and in a specific direction, so the reconciliation is a
+// concern of its own rather than a helper beside the stream reader that happens to need it.
+//
+// Split out of `agent-runner.ts` when it hit its size budget.
+/**
+ * Read Claude Code's terminal cumulative usage.
+ *
+ * Counts every input bucket Anthropic bills: fresh input plus BOTH cache reads and cache writes
+ * (`cache_creation_input_tokens`), which are real consumed tokens and are the dominant share on a
+ * long agent run. Omitting them under-weights a token's true load in the usage-aware rotation
+ * window. `undefined` when the event carried no usage at all, so a caller can tell that from a
+ * genuine zero.
+ */
+export function claudeUsage(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const input = numberOf(raw.input_tokens) +
+        numberOf(raw.cache_read_input_tokens) +
+        numberOf(raw.cache_creation_input_tokens);
+    const output = numberOf(raw.output_tokens);
+    if (input === 0 && output === 0)
+        return undefined;
+    return { inputTokens: input, outputTokens: output };
+}
+/**
+ * The row standing for whatever the per-turn channel did NOT account for: the terminal cumulative
+ * usage minus the sum of the turns already costed, computed PER SIDE. `undefined` when the turns
+ * add up, so nothing is double counted.
+ *
+ * The per-side part is why this exists at all, and it replaced an all-or-nothing guard
+ * (`calls.some(c => c.inputTokens > 0 || c.outputTokens > 0)` ⇒ return) that only ever fired for a
+ * CLI reporting no per-turn usage at all. Claude Code reports plenty: its `assistant` envelopes
+ * carry the message-START usage snapshot, whose INPUT and cache counts are final and whose
+ * `output_tokens` is the 1-5 tokens produced when the message opened. So the guard saw costed
+ * turns, returned, and the run's whole output side stayed at that snapshot. Measured on a real
+ * board: a `coder` step recorded 198 output tokens across 34 calls against the 14,033 the terminal
+ * `result` event reported, an `initiative-analyst` 531 against 30,471. Input matched the terminal
+ * figure exactly, which is what made the shortfall invisible to a check that asked whether ANY
+ * tokens had been reported.
+ *
+ * **It is its OWN row rather than tokens added to the last captured call.** Growing a real turn by
+ * thousands of output tokens it did not produce makes a fabricated number indistinguishable from a
+ * measured one everywhere a per-call figure is read (`/api/v1/debug/*`, the observability panel, a
+ * step's per-call breakdown), and there is nothing on the row to mark it. The sibling rule on the
+ * inline path (`CliInlineLanguageModel.fileUnaccounted`) reached that conclusion first and files a
+ * step-level row; this is the same answer for the channel that has a call list. {@link
+ * HarnessCallMetric.standsForJob} is what keeps it from reading as a turn.
+ *
+ * **`calls` must be the PARENT loop's alone.** The terminal `result` event's cumulative covers the
+ * parent conversation only — a subagent's tokens live in its own transcript — so subtracting a
+ * subagent turn's tokens from it understates the shortfall, and pinning the remainder near one
+ * would bill a conversation for spend it never saw. Both were live in `ambientAuth` mode, where the
+ * CLI streams subagent turns onto the parent's stdout and no transcript watcher runs, so those
+ * turns are captured through the same publisher as the parent's.
+ *
+ * {@link claudeUsage} sums every billed input bucket, so the already-accounted input is the sum of
+ * all THREE per-call input classes, not `inputTokens` (fresh) alone. A residual input shortfall
+ * lands on `inputTokens` because nothing in the terminal event says which class it belonged to.
+ *
+ * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
+ * reported the two inconsistently, and negative spend is not a thing to record.
+ */
+export function unaccountedUsageCall(parentCalls, usage) {
+    if (!usage)
+        return undefined;
+    let accountedInput = 0;
+    let accountedOutput = 0;
+    for (const call of parentCalls) {
+        accountedInput += call.inputTokens + call.cacheReadTokens + call.cacheWriteTokens;
+        accountedOutput += call.outputTokens;
+    }
+    const inputTokens = Math.max(0, usage.inputTokens - accountedInput);
+    const outputTokens = Math.max(0, usage.outputTokens - accountedOutput);
+    if (!inputTokens && !outputTokens)
+        return undefined;
+    return {
+        // No `model`: the terminal event names none, and the recorder then files the row under the
+        // model the step DISPATCHED, which is the same answer without this claiming to have observed
+        // it. (Claude Code serves some turns with a different model, so a guess here misprices.)
+        promptText: '',
+        messageCount: 0,
+        responseText: '',
+        reasoningText: '',
+        inputTokens,
+        // Both 0 rather than a split of `inputTokens`: the terminal figure is one number and says
+        // nothing about which input class the remainder belonged to.
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        outputTokens,
+        finishReason: null,
+        standsForJob: true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.116.0",
+  "version": "1.118.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",
@@ -30,9 +30,9 @@
     "hono": "^4.13.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.298.0",
-    "@cat-factory/server": "0.284.0",
-    "@cat-factory/spend": "0.15.89"
+    "@cat-factory/kernel": "0.298.1",
+    "@cat-factory/server": "0.284.1",
+    "@cat-factory/spend": "0.15.90"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -3,7 +3,12 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js'
-import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js'
+import { claudeUsage, unaccountedUsageCall } from './usage-attribution.js'
+import {
+  createClaudeRunTelemetry,
+  subagentDispatchId,
+  type ClaudeRunTelemetry,
+} from './claude-call-aggregator.js'
 import {
   ToolCallTracker,
   type TrackedToolCall,
@@ -12,9 +17,7 @@ import {
 import { log, type Logger } from './logger.js'
 import { NO_TOOL_WINDOW, type ToolProgressWindow } from './tool-silence.js'
 import {
-  createCallMetricPublisher,
   publishCallMetric,
-  type CallMetricPublisher,
   type HarnessCallMetric,
   type PiRunOutcome,
   type TodoProgress,
@@ -202,24 +205,6 @@ export interface SubscriptionRunOptions {
   log?: Logger
 }
 
-/**
- * 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
- * call rather than dropping it — the run's tokens are still accounted, just not split
- * per turn. A no-op when the calls already carry per-turn tokens.
- */
-function attributeCumulativeUsage(
-  calls: HarnessCallMetric[],
-  usage: { inputTokens: number; outputTokens: number } | undefined,
-): void {
-  if (!usage || calls.length === 0) return
-  const anyTokens = calls.some((c) => c.inputTokens > 0 || c.outputTokens > 0)
-  if (anyTokens) return
-  const last = calls[calls.length - 1]!
-  last.inputTokens = usage.inputTokens
-  last.outputTokens = usage.outputTokens
-}
-
 /**
  * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
  * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
@@ -711,6 +696,75 @@ function carriesToolResult(content: unknown[]): boolean {
   return content.some((block) => isObject(block) && block.type === 'tool_result')
 }
 
+/** One claude-code run's per-call telemetry: what was captured, and how it is settled. */
+interface ClaudeCallCapture {
+  /** Every captured call, terminal-result order — the parent's, the subagents', the remainder. */
+  calls: HarnessCallMetric[]
+  telemetry: ClaudeRunTelemetry
+  /**
+   * File whatever the parent's narrated turns did not account for, once its terminal cumulative
+   * usage is known. A no-op when they add up. See {@link unaccountedUsageCall}.
+   */
+  settleUsage: (usage: { inputTokens: number; outputTokens: number } | undefined) => void
+}
+
+/**
+ * Open the per-call telemetry capture for one claude-code run.
+ *
+ * It reconstructs the full per-call request/response bodies from the stream.
+ * `--output-format stream-json --verbose` emits a near-verbatim Anthropic Messages envelope per
+ * response CONTENT BLOCK (not per call), so the aggregator folds the envelopes sharing a
+ * `message.id` back into one call and buffers that call's `user` tool_result turns — together the
+ * growing prompt transcript, in the shape the model was actually sent. It is SEEDED 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).
+ *
+ * The parent loop's calls are tracked SEPARATELY, by reference into the same list, because the
+ * terminal `result` event's cumulative usage covers only the parent conversation. In `ambientAuth`
+ * mode there is no transcript watcher, so the CLI's tagged subagent turns are captured here too and
+ * `calls` holds both; reconciling against that mixed list is what once billed a subagent for the
+ * parent's whole output shortfall.
+ */
+function openClaudeCallCapture(
+  opts: SubscriptionRunOptions,
+  stream: { prompt: string; folded: boolean; secrets: string[] },
+): ClaudeCallCapture {
+  const calls: HarnessCallMetric[] = []
+  const parentCalls: HarnessCallMetric[] = []
+  const publish = (metric: HarnessCallMetric): void =>
+    publishCallMetric(calls, metric, opts.onCallMetric)
+  // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring in the caller: it is started
+  // only when the CLI has an isolated config home to watch, which an `ambientAuth` run does not
+  // have. The telemetry routes the CLI's tagged subagent turns accordingly — see
+  // `createClaudeRunTelemetry`.
+  const telemetry = createClaudeRunTelemetry({
+    seed: stream.folded
+      ? [{ role: 'user', content: stream.prompt }]
+      : [
+          { role: 'system', content: opts.systemPrompt },
+          { role: 'user', content: opts.userPrompt },
+        ],
+    secrets: stream.secrets,
+    watcherOwnsSubagents: !opts.ambientAuth,
+    publish: (metric) => {
+      parentCalls.push(metric)
+      publish(metric)
+    },
+    publishSubagent: publish,
+  })
+  return {
+    calls,
+    telemetry,
+    settleUsage: (usage) => {
+      // Published like any other call so the live drain records it too, which is also what stamps
+      // its `seq` and therefore its stable row id.
+      const remainder = unaccountedUsageCall(parentCalls, usage)
+      if (remainder) publish(remainder)
+    },
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -729,34 +783,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     })
   }
 
-  // Reconstruct the full per-call request/response bodies for telemetry from the
-  // stream. `--output-format stream-json --verbose` emits a near-verbatim Anthropic
-  // Messages envelope per response CONTENT BLOCK (not per call), so the aggregator below
-  // folds the envelopes sharing a `message.id` back into one call and buffers that call's
-  // `user` tool_result turns — together the growing prompt transcript, in the shape the
-  // model was actually sent. 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 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)
-  // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring below: it is started only when
-  // the CLI has an isolated config home to watch, which an `ambientAuth` run does not have. The
-  // telemetry routes the CLI's tagged subagent turns accordingly — see `createClaudeRunTelemetry`.
-  const telemetry = createClaudeRunTelemetry({
-    seed: folded
-      ? [{ role: 'user', content: prompt }]
-      : [
-          { role: 'system', content: opts.systemPrompt },
-          { role: 'user', content: opts.userPrompt },
-        ],
-    secrets,
-    watcherOwnsSubagents: !opts.ambientAuth,
-    publish: (metric) => publisher.publish(metric),
-  })
+  const capture = openClaudeCallCapture(opts, { prompt, folded, secrets })
+  const telemetry = capture.telemetry
 
   // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from the two views the run
   // produces of the SAME slicing. The parent's subagent dispatches + their terminal tool_results
@@ -917,8 +946,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       summary,
       stats,
       stderrTail,
-      calls,
-      publisher,
+      capture,
       usage,
       subagents,
       expectSubagentCalls: telemetry.expectsWatcherCalls(),
@@ -926,11 +954,11 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     })
   } catch (err) {
     // The stream ended abnormally (guard trip, watchdog kill, CLI crash). Complete the call in
-    // flight anyway, and release whatever the publisher was withholding: a killed run never
-    // returns an outcome, so the live channel is the ONLY record of what it spent, and dropping
-    // its last turn is what the streaming exists to avoid.
+    // flight anyway: a killed run never returns an outcome, so the live channel is the ONLY record
+    // of what it spent, and dropping its last turn is what the streaming exists to avoid. No
+    // terminal `result` event arrived, so there is no cumulative total to reconcile against and no
+    // remainder row to file — every captured turn already streamed as it was completed.
     telemetry.flush()
-    publisher.flush()
     // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
     // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail it
     // attached, since that is usually the only evidence of what the CLI was doing when it was
@@ -1088,9 +1116,8 @@ 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
+  /** This run's per-call telemetry, settled here with the terminal usage. */
+  capture: ClaudeCallCapture
   usage: { inputTokens: number; outputTokens: number } | undefined
   subagents: ReturnType<typeof startSubagentWatcher> | undefined
   /**
@@ -1102,14 +1129,11 @@ async function assembleClaudeOutcome(args: {
   expectSubagentCalls: boolean
   log?: Logger
 }): 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()
+  const { summary, stats, stderrTail, capture, usage, subagents } = args
+  const calls = capture.calls
+  // What the parent's narrated turns did not account for, as its OWN row (never tokens grafted onto
+  // a real turn).
+  capture.settleUsage(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.
   await subagents?.stop()
@@ -1138,21 +1162,6 @@ async function assembleClaudeOutcome(args: {
   }
 }
 
-function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number } | undefined {
-  if (!isObject(raw)) return undefined
-  // Count every input bucket Anthropic bills: fresh input plus BOTH cache reads and
-  // cache writes (cache_creation_input_tokens), which are real consumed tokens — and
-  // are the dominant share on a long agent run. Omitting them under-weights a token's
-  // true load in the usage-aware rotation window.
-  const input =
-    numberOf(raw.input_tokens) +
-    numberOf(raw.cache_read_input_tokens) +
-    numberOf(raw.cache_creation_input_tokens)
-  const output = numberOf(raw.output_tokens)
-  if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, outputTokens: output }
-}
-
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------

package/src/claude-call-aggregator.ts

@@ -452,12 +452,25 @@ export interface ClaudeRunTelemetry {
  * `ambientAuth` run has no isolated config home to watch — the tagged turns are recorded here
  * instead, on per-dispatch transcripts of their own. Dropping them in that case would leave the run
  * billed by neither channel, and an under-count reads as a cheap run rather than as an error.
+ *
+ * Which is also why the two are published through SEPARATE callbacks. A caller reconciling the
+ * parent's terminal cumulative usage needs the parent's calls alone, and with one shared callback
+ * the fallback channel silently mixed subagent turns into that list — where they both understated
+ * the shortfall and, being last, attracted it (`unaccountedUsageCall`). `publishSubagent` is
+ * optional so a caller that draws no distinction (a test, the settled-transcript path where nothing
+ * arrives here anyway) keeps one sink.
  */
 export function createClaudeRunTelemetry(
-  opts: ClaudeStreamTelemetryOptions & { watcherOwnsSubagents: boolean },
+  opts: ClaudeStreamTelemetryOptions & {
+    watcherOwnsSubagents: boolean
+    /** Where a SUBAGENT conversation's call goes. Absent ⇒ `publish`, the parent's sink. */
+    publishSubagent?: (metric: HarnessCallMetric) => void
+  },
 ): ClaudeRunTelemetry {
   const parent = createClaudeStreamTelemetry(opts)
-  const subagents = opts.watcherOwnsSubagents ? undefined : createSubagentStreamTelemetry(opts)
+  const subagents = opts.watcherOwnsSubagents
+    ? undefined
+    : createSubagentStreamTelemetry({ ...opts, publish: opts.publishSubagent ?? opts.publish })
   let sawSubagentTurn = false
 
   return {

package/src/inline.ts

@@ -18,14 +18,26 @@ import type { RunOptions } from './runner.js'
 // is injected.
 
 /**
- * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the
- * inline `finishReason` the reviewer keys off. Only Claude Code reports it (`max_tokens` on
- * a `--output-format stream-json` result); Codex's thinner stream exposes none, so it reads
- * as `stop` — the same one-shot limitation the host-CLI runner has.
+ * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the inline
+ * `finishReason` the reviewer keys off, or `undefined` when the CLI reported NONE.
+ *
+ * Undefined rather than `stop`, which is what this returned for years on the strength of a
+ * comment claiming Claude Code reports the reason. It does not: its `stream-json` `assistant`
+ * envelopes carry the message-START snapshot, whose `stop_reason` is null, so every call metric
+ * a claude-code or codex run produces has a null reason and this answered `stop` for all of them.
+ * `stop` is a positive claim that the model finished of its own accord, and it is the exact claim
+ * a truncation check is trying to disprove — so the one caller keyed off it
+ * (`finishReason === 'length'`) could never fire, and every store that kept the row recorded a
+ * clean stop nobody observed.
+ *
+ * Kept as a MAPPING rather than deleted because the field remains reachable: a subagent turn is
+ * read from a completed JSONL transcript, which does carry `stop_reason`, and a future CLI build
+ * (or `--include-partial-messages`) would restore it on the parent stream too.
  */
-function deriveFinishReason(calls: HarnessCallMetric[] | undefined): 'stop' | 'length' {
+function deriveFinishReason(calls: HarnessCallMetric[] | undefined): 'stop' | 'length' | undefined {
   const last = calls?.[calls.length - 1]
-  const reason = last?.finishReason?.toLowerCase() ?? ''
+  const reason = last?.finishReason?.toLowerCase()
+  if (!reason) return undefined
   return reason === 'max_tokens' || reason === 'length' ? 'length' : 'stop'
 }
 
@@ -57,9 +69,10 @@ export async function handleInline(job: InlineJob, opts: RunOptions): Promise<In
       ...(opts.signal ? { signal: opts.signal } : {}),
       ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
     })
+    const finishReason = deriveFinishReason(outcome.callMetrics)
     return {
       text: outcome.summary,
-      finishReason: deriveFinishReason(outcome.callMetrics),
+      ...(finishReason ? { finishReason } : {}),
       ...(outcome.usage ? { usage: inlineUsage(outcome.usage, outcome.callMetrics) } : {}),
       ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
     }

package/src/job.ts

@@ -1164,7 +1164,14 @@ export interface InlineJob extends HarnessAuthFields {
 /** The inline completion result: the reply text plus lifted token usage / per-call telemetry. */
 export interface InlineResult {
   text: string
-  /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
+  /**
+   * `length` when the model hit its output cap (the reviewer rejects a truncated doc), `stop`
+   * when it finished of its own accord, ABSENT when the CLI reported no stop reason at all.
+   *
+   * Absent is the normal case today: neither subscription CLI exposes a per-call stop reason on
+   * its parent stream, and the three states must stay distinct because a reader that takes
+   * absent for `stop` is asserting the one thing a truncation check exists to disprove.
+   */
   finishReason?: 'stop' | 'length'
   /**
    * The job's token usage with the input side split into its three ORTHOGONAL classes:

package/src/pi.ts

@@ -642,6 +642,16 @@ export interface HarnessCallMetric {
    * never disagree about which phase billed a call.
    */
   phase?: string
+  /**
+   * This row is not a TURN: it stands for the job as a whole, carrying the spend the CLI reported
+   * in its terminal cumulative total and did not attribute to any turn it narrated (see
+   * {@link unaccountedUsageCall}). It has no bodies, because there was no request to capture.
+   *
+   * The backend files it with a NULL turn index for that reason, while still deriving its row id
+   * from {@link seq} so a replayed poll re-records instead of duplicating. Absent on every real
+   * turn. `CliInlineLanguageModel`'s step-level row is the same idea on the inline path.
+   */
+  standsForJob?: boolean
 }
 
 /**
@@ -657,9 +667,13 @@ export interface HarnessCallMetric {
  * 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.
+ * reaches the store.
+ *
+ * That is a rule about every producer, and it is why the cumulative-usage reconciliation files its
+ * shortfall as a NEW row here at the end of the run (`unaccountedUsageCall`) rather than growing the
+ * last captured turn. This used to be wrapped by a publisher that withheld the turn attribution
+ * could still rewrite, trading a turn of streaming lag for that mutability; with nothing mutated,
+ * the wrapper had no reason left to exist.
  */
 export function publishCallMetric(
   calls: HarnessCallMetric[],
@@ -670,54 +684,6 @@ export function publishCallMetric(
   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. */
 export interface PiRunOutcome {
   summary: string

package/src/usage-attribution.ts

@@ -0,0 +1,102 @@
+import { isObject, numberOf } from './claude-stream.js'
+import type { HarnessCallMetric } from './pi.js'
+
+// How a subscription CLI's TWO token channels are reconciled into the per-call rows the backend
+// stores: the per-turn usage the stream narrates, and the cumulative total the terminal `result`
+// event reports. They disagree routinely and in a specific direction, so the reconciliation is a
+// concern of its own rather than a helper beside the stream reader that happens to need it.
+//
+// Split out of `agent-runner.ts` when it hit its size budget.
+
+/**
+ * Read Claude Code's terminal cumulative usage.
+ *
+ * Counts every input bucket Anthropic bills: fresh input plus BOTH cache reads and cache writes
+ * (`cache_creation_input_tokens`), which are real consumed tokens and are the dominant share on a
+ * long agent run. Omitting them under-weights a token's true load in the usage-aware rotation
+ * window. `undefined` when the event carried no usage at all, so a caller can tell that from a
+ * genuine zero.
+ */
+export function claudeUsage(
+  raw: unknown,
+): { inputTokens: number; outputTokens: number } | undefined {
+  if (!isObject(raw)) return undefined
+  const input =
+    numberOf(raw.input_tokens) +
+    numberOf(raw.cache_read_input_tokens) +
+    numberOf(raw.cache_creation_input_tokens)
+  const output = numberOf(raw.output_tokens)
+  if (input === 0 && output === 0) return undefined
+  return { inputTokens: input, outputTokens: output }
+}
+
+/**
+ * The row standing for whatever the per-turn channel did NOT account for: the terminal cumulative
+ * usage minus the sum of the turns already costed, computed PER SIDE. `undefined` when the turns
+ * add up, so nothing is double counted.
+ *
+ * The per-side part is why this exists at all, and it replaced an all-or-nothing guard
+ * (`calls.some(c => c.inputTokens > 0 || c.outputTokens > 0)` ⇒ return) that only ever fired for a
+ * CLI reporting no per-turn usage at all. Claude Code reports plenty: its `assistant` envelopes
+ * carry the message-START usage snapshot, whose INPUT and cache counts are final and whose
+ * `output_tokens` is the 1-5 tokens produced when the message opened. So the guard saw costed
+ * turns, returned, and the run's whole output side stayed at that snapshot. Measured on a real
+ * board: a `coder` step recorded 198 output tokens across 34 calls against the 14,033 the terminal
+ * `result` event reported, an `initiative-analyst` 531 against 30,471. Input matched the terminal
+ * figure exactly, which is what made the shortfall invisible to a check that asked whether ANY
+ * tokens had been reported.
+ *
+ * **It is its OWN row rather than tokens added to the last captured call.** Growing a real turn by
+ * thousands of output tokens it did not produce makes a fabricated number indistinguishable from a
+ * measured one everywhere a per-call figure is read (`/api/v1/debug/*`, the observability panel, a
+ * step's per-call breakdown), and there is nothing on the row to mark it. The sibling rule on the
+ * inline path (`CliInlineLanguageModel.fileUnaccounted`) reached that conclusion first and files a
+ * step-level row; this is the same answer for the channel that has a call list. {@link
+ * HarnessCallMetric.standsForJob} is what keeps it from reading as a turn.
+ *
+ * **`calls` must be the PARENT loop's alone.** The terminal `result` event's cumulative covers the
+ * parent conversation only — a subagent's tokens live in its own transcript — so subtracting a
+ * subagent turn's tokens from it understates the shortfall, and pinning the remainder near one
+ * would bill a conversation for spend it never saw. Both were live in `ambientAuth` mode, where the
+ * CLI streams subagent turns onto the parent's stdout and no transcript watcher runs, so those
+ * turns are captured through the same publisher as the parent's.
+ *
+ * {@link claudeUsage} sums every billed input bucket, so the already-accounted input is the sum of
+ * all THREE per-call input classes, not `inputTokens` (fresh) alone. A residual input shortfall
+ * lands on `inputTokens` because nothing in the terminal event says which class it belonged to.
+ *
+ * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
+ * reported the two inconsistently, and negative spend is not a thing to record.
+ */
+export function unaccountedUsageCall(
+  parentCalls: readonly HarnessCallMetric[],
+  usage: { inputTokens: number; outputTokens: number } | undefined,
+): HarnessCallMetric | undefined {
+  if (!usage) return undefined
+  let accountedInput = 0
+  let accountedOutput = 0
+  for (const call of parentCalls) {
+    accountedInput += call.inputTokens + call.cacheReadTokens + call.cacheWriteTokens
+    accountedOutput += call.outputTokens
+  }
+  const inputTokens = Math.max(0, usage.inputTokens - accountedInput)
+  const outputTokens = Math.max(0, usage.outputTokens - accountedOutput)
+  if (!inputTokens && !outputTokens) return undefined
+  return {
+    // No `model`: the terminal event names none, and the recorder then files the row under the
+    // model the step DISPATCHED, which is the same answer without this claiming to have observed
+    // it. (Claude Code serves some turns with a different model, so a guess here misprices.)
+    promptText: '',
+    messageCount: 0,
+    responseText: '',
+    reasoningText: '',
+    inputTokens,
+    // Both 0 rather than a split of `inputTokens`: the terminal figure is one number and says
+    // nothing about which input class the remainder belonged to.
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens,
+    finishReason: null,
+    standsForJob: true,
+  }
+}