@cat-factory/executor-harness 1.50.18 → 1.52.2

package/dist/subagents.js

@@ -2,6 +2,56 @@ 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';
+// 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
+// harness, which only reads the PARENT process's stream-json stdout:
+//
+//  - the parent stream falls quiet for the whole (potentially 15+ minute) parallel
+//    review, so the inactivity heartbeat freezes and a healthy run looks wedged (P3);
+//  - every subagent's token spend is written to a SEPARATE `subagents/*.jsonl`
+//    transcript under the CLI's config home and never reaches the parent stream, so
+//    the run's telemetry reports ~0 tokens while hundreds of thousands are spent (P3).
+//
+// This module closes both without disabling the (context-bounding, ADR-0023-wanted)
+// subagent parallelism:
+//
+//  - {@link createSliceTracker} derives the slice plan + per-slice progress from the
+//    PARENT stream alone — the subagent-dispatch tool_use and its terminal tool_result
+//    DO appear there (only the subagent's intermediate turns don't), so slices/progress
+//    need no file watching (D2.1). `pickProgress` (./progress.ts) reconciles it with the
+//    parent's own plan (ADR 0027 Defect B);
+//  - {@link startSubagentWatcher} tails the `subagents/*.jsonl` transcripts for the
+//    heartbeat (any new bytes ⇒ `onActivity`) and sums each subagent turn's usage into
+//    the run's telemetry (D3).
+//
+// The CLI does NOT write those transcripts to `<configHome>/subagents` (the location ADR
+// 0026 assumed, which never exists — ADR 0027 Defect A). It writes them PER SESSION under
+// `<configHome>/projects/<encoded-cwd>/<session-uuid>/subagents/agent-*.jsonl`, and the
+// session-uuid dir isn't known before the CLI mints it — so the watcher is pointed at the
+// `projects` root and DISCOVERS the `subagents/` dir by walking (see
+// {@link findSubagentTranscripts}).
+//
+// Both degrade gracefully: the CLI's subagent transcript layout is not a stable contract,
+// so a missing directory, an unreadable file, or an unparseable line is swallowed and the
+// harness falls back to today's parent-stream-only behaviour.
+// ---------------------------------------------------------------------------
+// Slice / progress tracking off the PARENT stream (D2.1)
+// ---------------------------------------------------------------------------
+/**
+ * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
+ * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
+ * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
+ * harness runs against whatever CLI the image happens to bundle, and matching only the old name
+ * is what left a CLI 2.1.x pr-review reporting no slices at all.
+ *
+ * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
+ * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
+ * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
+ * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
+ * `progress.ts`), and dropping legacy coverage is the more likely regression.
+ */
+const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
 export function createSliceTracker() {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();
@@ -10,7 +60,9 @@ export function createSliceTracker() {
             if (!Array.isArray(content))
                 return;
             for (const block of content) {
-                if (!isObject(block) || block.type !== 'tool_use' || block.name !== 'Task')
+                if (!isObject(block) || block.type !== 'tool_use')
+                    continue;
+                if (typeof block.name !== 'string' || !SUBAGENT_TOOL_NAMES.has(block.name))
                     continue;
                 const id = typeof block.id === 'string' ? block.id : undefined;
                 if (!id || slices.has(id))
@@ -54,32 +106,6 @@ export function createSliceTracker() {
         },
     };
 }
-/**
- * Reconcile the two redundant views of the same slice work into the one to surface
- * (ADR 0027 Defect B). A pr-reviewer run has BOTH a parent `TodoWrite` plan (the slices,
- * written once at grouping time) and the {@link SliceTracker}'s `Task`-dispatch view. The
- * sequential shape advances the todo plan; the parallel-subagent shape advances ONLY the
- * slice tracker (the CLI writes the plan once and never marks it done, while the parallel
- * `Task`s report in-flight/complete). Neither alone covers both shapes, and gating the
- * slice tracker OFF whenever a todo plan exists (the old behaviour) pinned parallel runs
- * at 0%. So prefer whichever view is further along: more `completed`, then more
- * `inProgress` (an all-pending todo plan must not beat live in-flight slices), then more
- * `total` (the richer view — the todo plan can carry an extra "aggregate" entry), else the
- * todo plan. Pure + total; returns whichever single input is present when only one is.
- */
-export function pickProgress(todo, slice) {
-    if (!todo)
-        return slice;
-    if (!slice)
-        return todo;
-    if (slice.completed !== todo.completed)
-        return slice.completed > todo.completed ? slice : todo;
-    if (slice.inProgress !== todo.inProgress)
-        return slice.inProgress > todo.inProgress ? slice : todo;
-    if (slice.total !== todo.total)
-        return slice.total > todo.total ? slice : todo;
-    return todo;
-}
 // ---------------------------------------------------------------------------
 // Subagent transcript watcher (heartbeat + usage) (D3)
 // ---------------------------------------------------------------------------
@@ -164,7 +190,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 +206,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.2",
   "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.1",
+    "@cat-factory/spend": "0.12.77"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -10,10 +10,25 @@ 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'
+import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import {
+  createTaskPlanTracker,
+  normalizeStatus,
+  pickProgress,
+  toProgress,
+  todosToProgress,
+} from './progress.js'
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
@@ -81,6 +96,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,19 +345,31 @@ 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
+  // sources. The parent's subagent dispatches + their terminal tool_results DO appear on this
   // stream (only a subagent's intermediate turns don't), so `sliceTracker` derives per-slice
-  // progress for the parallel-subagent shape; a parent `TodoWrite` plan (the sequential
-  // shape) is tracked in `lastTodo`. `pickProgress` picks whichever is further along on each
-  // update, so neither masks the other — the pr-reviewer prompt writes its todo plan ONCE
-  // and never marks it done, which used to gate the slice signal off and pin progress at 0%.
+  // progress for the parallel shape; the parent's own plan (the sequential shape) is tracked
+  // by `planTracker` + `lastTodo`. `pickProgress` picks whichever is further along on each
+  // update, so neither masks the other — the pr-reviewer prompt writes its plan ONCE and never
+  // marks it done, which used to gate the slice signal off and pin progress at 0%.
+  //
+  // The plan arrives in one of two tool vocabularies depending on the bundled CLI build:
+  // `TodoWrite` (whole-list snapshots, tracked in `lastTodo`) or the incremental
+  // `TaskCreate`/`TaskUpdate` pair (tracked by `planTracker`, which needs the tool RESULTS too
+  // because the task id is minted there). Both are read — see ./progress.ts.
   const sliceTracker = createSliceTracker()
+  const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
   const emitProgress = (): void => {
     if (!opts.onProgress) return
-    const progress = pickProgress(lastTodo, sliceTracker.progress())
+    const progress = pickProgress(
+      pickProgress(lastTodo, planTracker.progress()),
+      sliceTracker.progress(),
+    )
     if (progress) opts.onProgress(progress)
   }
 
@@ -355,12 +388,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         }
       }
       sliceTracker.onAssistant(content)
+      planTracker.onAssistant(content)
       emitProgress()
       // Record this call BEFORE appending its turn: the prompt is the history that
       // produced this response. The append-only array keeps each call's prompt a strict
       // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
       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,
@@ -377,6 +411,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       const content = (event.message as Record<string, unknown>).content
       if (Array.isArray(content)) {
         sliceTracker.onUser(content)
+        planTracker.onUser(content)
         emitProgress()
         messages.push({ role: 'tool', content })
       }
@@ -439,6 +474,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 +506,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 +567,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()
@@ -552,24 +602,6 @@ async function assembleClaudeOutcome(args: {
   }
 }
 
-/** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
-function todosToProgress(todos: unknown): TodoProgress | undefined {
-  if (!Array.isArray(todos)) return undefined
-  const items = todos.filter(isObject).map((t) => ({
-    label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
-    status: normalizeStatus(t.status),
-  }))
-  const completed = items.filter((i) => i.status === 'completed').length
-  const inProgress = items.filter((i) => i.status === 'in_progress').length
-  return { completed, inProgress, total: items.length, items }
-}
-
-function normalizeStatus(status: unknown): 'pending' | 'in_progress' | 'completed' {
-  if (status === 'completed') return 'completed'
-  if (status === 'in_progress') return 'in_progress'
-  return 'pending'
-}
-
 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
@@ -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,
@@ -789,9 +829,7 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
     status: normalizeStatus(s.status),
   }))
   if (items.length === 0) return undefined
-  const completed = items.filter((i) => i.status === 'completed').length
-  const inProgress = items.filter((i) => i.status === 'in_progress').length
-  return { completed, inProgress, total: items.length, items }
+  return toProgress(items)
 }
 
 /**

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. */