@cat-factory/executor-harness 1.50.18 → 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,
@@ -333,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;
@@ -355,7 +360,15 @@ export async function runClaudeCode(opts) {
                 ...appendArgs,
             ],
         }, prompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
-        return await assembleClaudeOutcome({ summary, stats, stderrTail, calls, usage, subagents });
+        return await assembleClaudeOutcome({
+            summary,
+            stats,
+            stderrTail,
+            calls,
+            publisher,
+            usage,
+            subagents,
+        });
     }
     finally {
         await subagents?.stop();
@@ -401,10 +414,14 @@ function buildClaudeEnv(opts, configHome) {
  * {@link runClaudeCode} verbatim to keep its cyclomatic complexity down.
  */
 async function assembleClaudeOutcome(args) {
-    const { summary, stats, stderrTail, calls, usage, subagents } = 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();
@@ -537,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,
@@ -547,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 = '';
@@ -571,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,
@@ -581,7 +598,7 @@ export async function runCodex(opts) {
                 cachedInputTokens: 0,
                 outputTokens: usage?.outputTokens ?? 0,
                 finishReason: null,
-            });
+            }, opts.onCallMetric);
         }
         return {
             summary,

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.18",
+  "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.143.1",
-    "@cat-factory/spend": "0.12.75"
+    "@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,
@@ -439,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
@@ -470,7 +488,15 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       onEvent,
     )
 
-    return await assembleClaudeOutcome({ summary, stats, stderrTail, calls, usage, subagents })
+    return await assembleClaudeOutcome({
+      summary,
+      stats,
+      stderrTail,
+      calls,
+      publisher,
+      usage,
+      subagents,
+    })
   } finally {
     await subagents?.stop()
     if (configHome) {
@@ -523,13 +549,19 @@ async function assembleClaudeOutcome(args: {
   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, usage, subagents } = 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()
@@ -668,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 = ''
     }
@@ -710,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/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
   }