@cat-factory/executor-harness 1.78.0 → 1.80.0

package/dist/agent-runner.js

@@ -384,7 +384,7 @@ export async function runClaudeCode(opts) {
     // either/or; the plan then MERGES with the dispatch view (`mergeProgress`) rather than
     // competing with it — picking the further-along view collapsed the list to the dispatched
     // slices alone the moment the first subagent returned. See ./progress.ts.
-    const sliceTracker = createSliceTracker();
+    const sliceTracker = createSliceTracker(secrets);
     const planTracker = createTaskPlanTracker();
     let lastTodo;
     const emitProgress = () => {
@@ -394,6 +394,17 @@ export async function runClaudeCode(opts) {
         if (progress)
             opts.onProgress(progress);
     };
+    // Publish the per-slice reviews the tracker has captured. Separate from `emitProgress` because
+    // the two answer different questions and have different lifetimes: progress is a disposable
+    // count the UI renders, while these carry the slices' actual review WORK and are persisted so a
+    // run that dies before its aggregation can be resumed from them.
+    const emitSliceReviews = () => {
+        if (!opts.onSliceReviews)
+            return;
+        const reviews = sliceTracker.sliceReviews();
+        if (reviews.length > 0)
+            opts.onSliceReviews(reviews);
+    };
     // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
     // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
     // turn and that call's RESULT (`is_error`) on the following `user` turn, so correlate them by
@@ -471,6 +482,9 @@ export async function runClaudeCode(opts) {
                 sliceTracker.onUser(content);
                 planTracker.onUser(content);
                 emitProgress();
+                // A slice's report lands on exactly this turn, so publish here: waiting for the next
+                // progress tick would risk the job dying with the report captured but never surfaced.
+                emitSliceReviews();
                 // Not on the at-close flush: the CLI has already exited, so tripping the guard there
                 // would kill nothing and only convert a clean exit into a spurious failure.
                 if (!meta?.final)

package/dist/claude-stream.js

@@ -49,6 +49,29 @@ export function claudeAssistantContent(content) {
     }
     return { text, reasoning, toolUses };
 }
+/**
+ * The text a `tool_result` block carries. The CLI writes it either as a bare string or as an
+ * array of content blocks (the shape a subagent's terminal report arrives in), so both are read
+ * here rather than at each call site. Non-text blocks (an image a tool returned) contribute
+ * nothing. Returns '' when the block carries no readable text.
+ *
+ * This is what makes a parallel subagent's work observable to the harness at all: the parent
+ * stream shows a subagent's dispatch and its terminal `tool_result` and nothing in between, so
+ * this text is the ONLY place its findings surface outside its own untailed transcript.
+ */
+export function claudeToolResultText(block) {
+    const content = block.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const part of content) {
+        if (isObject(part) && part.type === 'text' && typeof part.text === 'string')
+            text += part.text;
+    }
+    return text;
+}
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
  * the cumulative `result` total).

package/dist/pi-workspace.js

@@ -182,6 +182,10 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             expectsEdits: spec.expectsEdits ?? true,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            // Per-slice review capture, so a parallel review's finished slices are persisted as they
+            // land rather than only in the terminal output. Only the subscription runners fan work out
+            // across subagents, so this is the only path that can produce it.
+            onSliceReviews: opts.onSliceReviews,
             // 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.

package/dist/runner.js

@@ -220,6 +220,9 @@ export class JobRegistry {
                 onValidationReport: (report) => {
                     entry.validationReport = report;
                 },
+                onSliceReviews: (reviews) => {
+                    entry.sliceReviews = reviews;
+                },
                 onReproductionProof: (report) => {
                     entry.reproductionReport = report;
                 },

package/dist/subagents.js

@@ -1,9 +1,62 @@
 import { readdir, stat } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { basename, join } from 'node:path';
-import { claudeAssistantContent, claudeCallUsage, isObject, redactBody, SUBAGENT_TOOL_NAMES, } from './claude-stream.js';
+import { claudeAssistantContent, claudeCallUsage, claudeToolResultText, isObject, redactBody, SUBAGENT_TOOL_NAMES, } from './claude-stream.js';
 import { publishCallMetric } from './pi.js';
-export function createSliceTracker() {
+// 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 in the sense that a missing directory, an unreadable file, or an
+// unparseable line is swallowed rather than failing the run — the CLI's subagent transcript layout
+// is not a stable contract. But note what that costs SINCE the per-call fold landed: the parent
+// loop's telemetry now filters the subagent turns the CLI tags onto its stdout (they were being
+// counted twice and spliced into the parent's message chain), so when this watcher is wired and
+// yields nothing, the run's subagent calls are recorded by NEITHER channel. `runClaudeCode` warns
+// on exactly that shape, and an `ambientAuth` run — which has no config home to watch, so no
+// watcher — keeps recording them off the parent stream instead
+// (`createSubagentStreamTelemetry`). Do not "simplify" that fallback away.
+// ---------------------------------------------------------------------------
+// Slice / progress tracking off the PARENT stream (D2.1)
+// ---------------------------------------------------------------------------
+/**
+ * How much of one slice's terminal report is kept. A slice review is prose (findings for a handful
+ * of files), not a transcript, so this is far above a real report while still bounding what a
+ * runaway subagent can push onto the step — the reports ride the job view on every poll and are
+ * persisted on the run.
+ */
+export const SLICE_REPORT_MAX_CHARS = 24_000;
+/**
+ * @param secrets Leased-credential strings scrubbed from every captured report. A subagent can
+ *   echo a token it saw in the checkout, and these reports are persisted on the run, so they are
+ *   redacted on the way in rather than trusting each consumer to do it.
+ */
+export function createSliceTracker(secrets = []) {
     // Insertion-ordered so the progress `items` render in dispatch order.
     const slices = new Map();
     return {
@@ -33,10 +86,27 @@ export function createSliceTracker() {
                     continue;
                 const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
                 const slice = id ? slices.get(id) : undefined;
-                if (slice)
-                    slice.done = true;
+                if (!slice)
+                    continue;
+                slice.done = true;
+                // The report is captured here or nowhere: this `tool_result` is the only place the
+                // subagent's findings appear on the parent stream, and the next poll may be the last one
+                // this job ever answers.
+                const report = redactBody(claudeToolResultText(block), secrets).trim();
+                if (report)
+                    slice.report = report.slice(0, SLICE_REPORT_MAX_CHARS);
             }
         },
+        sliceReviews() {
+            return [...slices.values()].map((s) => ({
+                label: s.description,
+                status: (s.done ? 'completed' : 'in_progress'),
+                // A slice that finished but whose result carried no readable text is reported as
+                // completed with a null report rather than being dropped: a resume must still know it
+                // does not need re-reviewing, and silently omitting it would send it round again.
+                report: s.report ?? null,
+            }));
+        },
         hasSlices() {
             return slices.size > 0;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.78.0",
+  "version": "1.80.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,9 +26,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.193.0",
-    "@cat-factory/spend": "0.12.123",
-    "@cat-factory/server": "0.178.2"
+    "@cat-factory/server": "0.183.0",
+    "@cat-factory/kernel": "0.197.0",
+    "@cat-factory/spend": "0.12.127"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -26,7 +26,7 @@ import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { describeProcessExit } from './process-exit.js'
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
-import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import { createSliceTracker, startSubagentWatcher, type SliceReview } from './subagents.js'
 import {
   createTaskPlanTracker,
   mergeProgress,
@@ -123,6 +123,13 @@ 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 the FULL set of per-slice reviews each time one lands, so the backend can persist
+   * a parallel review's completed work as it happens instead of only from the terminal result.
+   * A whole value rather than a delta: the set only grows and losing a finished slice's report to
+   * a dropped poll would defeat the point (see `SliceTracker.sliceReviews`).
+   */
+  onSliceReviews?: (reviews: SliceReview[]) => 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
@@ -542,7 +549,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // either/or; the plan then MERGES with the dispatch view (`mergeProgress`) rather than
   // competing with it — picking the further-along view collapsed the list to the dispatched
   // slices alone the moment the first subagent returned. See ./progress.ts.
-  const sliceTracker = createSliceTracker()
+  const sliceTracker = createSliceTracker(secrets)
   const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
   const emitProgress = (): void => {
@@ -553,6 +560,15 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     )
     if (progress) opts.onProgress(progress)
   }
+  // Publish the per-slice reviews the tracker has captured. Separate from `emitProgress` because
+  // the two answer different questions and have different lifetimes: progress is a disposable
+  // count the UI renders, while these carry the slices' actual review WORK and are persisted so a
+  // run that dies before its aggregation can be resumed from them.
+  const emitSliceReviews = (): void => {
+    if (!opts.onSliceReviews) return
+    const reviews = sliceTracker.sliceReviews()
+    if (reviews.length > 0) opts.onSliceReviews(reviews)
+  }
 
   // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
   // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
@@ -626,6 +642,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         sliceTracker.onUser(content)
         planTracker.onUser(content)
         emitProgress()
+        // A slice's report lands on exactly this turn, so publish here: waiting for the next
+        // progress tick would risk the job dying with the report captured but never surfaced.
+        emitSliceReviews()
         // Not on the at-close flush: the CLI has already exited, so tripping the guard there
         // would kill nothing and only convert a clean exit into a spurious failure.
         if (!meta?.final) feedGuard(content)

package/src/claude-stream.ts

@@ -57,6 +57,27 @@ export function claudeAssistantContent(content: unknown[]): {
   return { text, reasoning, toolUses }
 }
 
+/**
+ * The text a `tool_result` block carries. The CLI writes it either as a bare string or as an
+ * array of content blocks (the shape a subagent's terminal report arrives in), so both are read
+ * here rather than at each call site. Non-text blocks (an image a tool returned) contribute
+ * nothing. Returns '' when the block carries no readable text.
+ *
+ * This is what makes a parallel subagent's work observable to the harness at all: the parent
+ * stream shows a subagent's dispatch and its terminal `tool_result` and nothing in between, so
+ * this text is the ONLY place its findings surface outside its own untailed transcript.
+ */
+export function claudeToolResultText(block: Record<string, unknown>): string {
+  const content = block.content
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  let text = ''
+  for (const part of content) {
+    if (isObject(part) && part.type === 'text' && typeof part.text === 'string') text += part.text
+  }
+  return text
+}
+
 /**
  * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
  * the cumulative `result` total).

package/src/pi-workspace.ts

@@ -325,6 +325,10 @@ export async function runAgentInWorkspace(
       expectsEdits: spec.expectsEdits ?? true,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
+      // Per-slice review capture, so a parallel review's finished slices are persisted as they
+      // land rather than only in the terminal output. Only the subscription runners fan work out
+      // across subagents, so this is the only path that can produce it.
+      onSliceReviews: opts.onSliceReviews,
       // 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.

package/src/runner.ts

@@ -2,6 +2,7 @@ import { redactSecrets } from './redact.js'
 import type { FollowUpLine } from './follow-ups.js'
 import type { ValidationReport } from './validation-checks.js'
 import type { ReproductionReport } from './reproduction-proof.js'
+import type { SliceReview } from './subagents.js'
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
@@ -47,6 +48,14 @@ export interface RunOptions {
    * attempt is final, and the loop republishes a whole new one — with a fresh `at` — per round.
    */
   onReproductionProof?: (report: ReproductionReport) => void
+  /**
+   * Receives the full set of per-slice reviews a parallel review has captured, republished each
+   * time a slice's subagent returns. Latest-wins (NOT a drain buffer), for the same reason as
+   * {@link onValidationReport} but with more at stake: these carry the slices' actual review work,
+   * and a review whose aggregation never finishes is recoverable ONLY from what the backend
+   * already persisted. Absent for a job that dispatched no subagents.
+   */
+  onSliceReviews?: (reviews: SliceReview[]) => 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
@@ -203,6 +212,18 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * that carried no reproduction declaration.
    */
   reproductionReport?: ReproductionReport
+  /**
+   * The per-slice reviews captured so far on a parallel (subagent-fanned) review — each slice's
+   * label, whether its subagent returned, and its verbatim report. A whole-value latest publish
+   * like {@link validationReport}, not drain-on-read.
+   *
+   * This is the durable half of a PR review. The reviewer returns `slices`/`findings` only in its
+   * TERMINAL structured output, so before this existed a review killed mid-run (or one whose
+   * aggregation pass wedged) lost every finished slice and could only be re-run from zero. The
+   * backend persists these onto the step as they arrive, which is what a manual resume re-aggregates
+   * from. Absent for a job that dispatched no subagents.
+   */
+  sliceReviews?: SliceReview[]
 }
 
 interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
@@ -473,6 +494,9 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         onValidationReport: (report) => {
           entry.validationReport = report
         },
+        onSliceReviews: (reviews) => {
+          entry.sliceReviews = reviews
+        },
         onReproductionProof: (report) => {
           entry.reproductionReport = report
         },

package/src/subagents.ts

@@ -4,6 +4,7 @@ import { basename, join } from 'node:path'
 import {
   claudeAssistantContent,
   claudeCallUsage,
+  claudeToolResultText,
   isObject,
   redactBody,
   SUBAGENT_TOOL_NAMES,
@@ -54,20 +55,52 @@ import { publishCallMetric, type HarnessCallMetric, type TodoProgress } from './
 // Slice / progress tracking off the PARENT stream (D2.1)
 // ---------------------------------------------------------------------------
 
+/**
+ * How much of one slice's terminal report is kept. A slice review is prose (findings for a handful
+ * of files), not a transcript, so this is far above a real report while still bounding what a
+ * runaway subagent can push onto the step — the reports ride the job view on every poll and are
+ * persisted on the run.
+ */
+export const SLICE_REPORT_MAX_CHARS = 24_000
+
 interface TrackedSlice {
   /** The dispatch's tool_use id, used to pair the terminal tool_result. */
   toolUseId: string
   /** The subagent's description (`Review <slice> slice`), rendered as the progress label. */
   description: string
   done: boolean
+  /**
+   * The subagent's verbatim terminal report, captured from the paired `tool_result`; undefined
+   * until it lands. This is the slice's actual review work — the reason a stuck aggregation no
+   * longer costs the whole run (see `prReviewSliceReviewSchema`). Truncated to
+   * {@link SLICE_REPORT_MAX_CHARS} and scrubbed of leased credentials before it leaves here.
+   */
+  report?: string
+}
+
+/** One slice's live review, as published on the job view. Mirrors `prReviewSliceReviewSchema`. */
+export interface SliceReview {
+  label: string
+  status: 'in_progress' | 'completed'
+  report?: string | null
 }
 
 /** Tracks parallel subagents seen on the parent stream to derive slice progress. */
 export interface SliceTracker {
   /** Feed an `assistant` message's content blocks: registers any subagent dispatches. */
   onAssistant(content: unknown[]): void
-  /** Feed a `user` message's content blocks: marks the paired subagent(s) complete. */
+  /**
+   * Feed a `user` message's content blocks: marks the paired subagent(s) complete AND captures
+   * each one's terminal report (see {@link SliceTracker.sliceReviews}).
+   */
   onUser(content: unknown[]): void
+  /**
+   * Every dispatched slice with its status and captured report, in dispatch order — the durable
+   * half of this tracker. Published as a whole value on each poll (NOT drain-on-read): the set
+   * only grows, and a dropped poll response must never permanently lose a finished slice's
+   * review, which is the entire point of capturing it. Empty when nothing was dispatched.
+   */
+  sliceReviews(): SliceReview[]
   /** Whether any `Task` subagent has been dispatched (⇒ this run parallelised). */
   hasSlices(): boolean
   /**
@@ -80,7 +113,12 @@ export interface SliceTracker {
   progress(): TodoProgress | undefined
 }
 
-export function createSliceTracker(): SliceTracker {
+/**
+ * @param secrets Leased-credential strings scrubbed from every captured report. A subagent can
+ *   echo a token it saw in the checkout, and these reports are persisted on the run, so they are
+ *   redacted on the way in rather than trusting each consumer to do it.
+ */
+export function createSliceTracker(secrets: string[] = []): SliceTracker {
   // Insertion-ordered so the progress `items` render in dispatch order.
   const slices = new Map<string, TrackedSlice>()
 
@@ -106,9 +144,25 @@ export function createSliceTracker(): SliceTracker {
         if (!isObject(block) || block.type !== 'tool_result') continue
         const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
         const slice = id ? slices.get(id) : undefined
-        if (slice) slice.done = true
+        if (!slice) continue
+        slice.done = true
+        // The report is captured here or nowhere: this `tool_result` is the only place the
+        // subagent's findings appear on the parent stream, and the next poll may be the last one
+        // this job ever answers.
+        const report = redactBody(claudeToolResultText(block), secrets).trim()
+        if (report) slice.report = report.slice(0, SLICE_REPORT_MAX_CHARS)
       }
     },
+    sliceReviews() {
+      return [...slices.values()].map((s) => ({
+        label: s.description,
+        status: (s.done ? 'completed' : 'in_progress') as 'completed' | 'in_progress',
+        // A slice that finished but whose result carried no readable text is reported as
+        // completed with a null report rather than being dropped: a resume must still know it
+        // does not need re-reviewing, and silently omitting it would send it round again.
+        report: s.report ?? null,
+      }))
+    },
     hasSlices() {
       return slices.size > 0
     },