@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/validation-checks.d.ts

@@ -0,0 +1,159 @@
+import type { RunOptions } from './runner.js';
+import type { Logger } from './logger.js';
+/** One configured check, as it arrives on the job body. */
+export interface ValidationCheckSpec {
+    label: string;
+    command: string;
+}
+/** The whole validation config a job carries. */
+export interface ValidationChecksSpec {
+    checks: ValidationCheckSpec[];
+    /** How many agent+check rounds the loop may run (1 = check once, no repair round). */
+    maxAttempts: number;
+}
+/** One command's outcome within an attempt. */
+export interface ValidationCheckOutcome {
+    label: string;
+    command: string;
+    exitCode: number;
+    passed: boolean;
+    outputTail?: string;
+    durationMs?: number;
+    timedOut?: boolean;
+}
+/**
+ * One attempt's result: the REPORT that crosses the wire, plus the FULL (scrubbed, 16k) output
+ * tails kept in memory for the repair prompt. The two are deliberately separate — see
+ * {@link VALIDATION_REPORT_TAIL_CHARS}.
+ */
+export interface ValidationAttempt {
+    report: ValidationReport;
+    /** Full scrubbed output per check label — never leaves the container. */
+    fullTails: Map<string, string>;
+}
+/**
+ * The ceiling the harness clamps a body-supplied `validationChecks.maxAttempts` to, and the
+ * default it applies when the body omits one.
+ *
+ * DELIBERATE DUPLICATES of `VALIDATION_MAX_ATTEMPTS_CEILING` / `VALIDATION_DEFAULT_MAX_ATTEMPTS`
+ * in `@cat-factory/contracts` — the published image takes no schema dependency, so the harness
+ * cannot import them. Keep the two in step: the API validates writes against the contracts
+ * values, so a harness clamping to a DIFFERENT ceiling would silently cap a budget an operator
+ * was allowed to save, with nothing to flag the mismatch.
+ */
+export declare const VALIDATION_MAX_ATTEMPTS_CEILING = 10;
+export declare const VALIDATION_DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * Parse the optional PRE-PR VALIDATION CHECKS envelope off the job body: the service's ordered
+ * `{ label, command }` pairs and the repair-round budget. Every entry needs a non-empty command;
+ * entries without one are dropped, and a spec that ends up with no usable check returns
+ * `undefined` — so a malformed body degrades to the exact pre-feature behaviour (no loop, PR
+ * opens as before) rather than failing an otherwise-good coding run. `maxAttempts` is clamped to
+ * a sane range so a bad body can't make a container loop forever.
+ *
+ * Lives with the feature rather than in `job.ts` so each pre-PR verification phase owns its own
+ * job-body parser next to the loop that consumes it (the reproduction proof's
+ * `parseReproductionSpec` is the sibling); `job.ts` stays the job SHAPE plus the generic
+ * assembly.
+ */
+export declare function parseValidationChecksSpec(value: unknown): ValidationChecksSpec | undefined;
+/** One attempt's report — what the backend records on the step. */
+export interface ValidationReport {
+    passed: boolean;
+    attempts: number;
+    maxAttempts: number;
+    outcomes: ValidationCheckOutcome[];
+    at: number;
+}
+/**
+ * Per-command output kept on the REPORT (what crosses the wire and lands in the run's persisted
+ * `detail` blob). Deliberately smaller than `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`), which is what the
+ * AGENT sees in its repair prompt: the agent needs the full failure to fix it, the operator needs
+ * enough to recognise it, and a chatty build must not inflate every run's stored state.
+ */
+export declare const VALIDATION_REPORT_TAIL_CHARS = 4000;
+/**
+ * The per-command watchdog: the longest a single check may run before it is killed and treated
+ * as a failure, so one hung `pnpm test` cannot wedge a run. Overridable via env for tests;
+ * defaults to 15 minutes (matching the ralph completion command's watchdog).
+ */
+export declare function validationCommandTimeoutMs(): number;
+/**
+ * How often the check loop feeds the run's inactivity watchdog. Well under the harness's own
+ * `JOB_INACTIVITY_MS` (default 10 min) so a single slow command can never look wedged; matches
+ * the frontend stand-up's heartbeat, which exists for exactly the same reason. Overridable via
+ * env for tests, like {@link validationCommandTimeoutMs}.
+ */
+export declare function validationHeartbeatMs(): number;
+/**
+ * Run every configured check IN ORDER against `cwd` and build the attempt's report.
+ *
+ * Runs all of them even after one fails, rather than short-circuiting: the agent repairing the
+ * checkout should see every problem at once instead of rediscovering the next one on the next
+ * round, which is the difference between one repair round and four. (A check whose failure makes
+ * the rest meaningless — e.g. a failed install — still costs only the cheap downstream failures.)
+ *
+ * Keeps the run's inactivity watchdog fed for the whole attempt. These commands are exactly the
+ * activity-SILENT kind — a cold `install`, a full `test` run, a `build` — and the harness spawns
+ * them itself rather than through the agent, so they emit no activity events of their own. The
+ * job-level watchdog (`JOB_INACTIVITY_MS`, default 10 min) is TIGHTER than one command's own
+ * watchdog ({@link validationCommandTimeoutMs}, default 15 min), so without this a legitimately
+ * slow check would abort the entire run as "inactivity" — mislabelling a healthy build as a
+ * wedge, and making the per-command timeout unreachable at stock settings.
+ */
+export declare function runValidationChecks(cwd: string, spec: ValidationChecksSpec, attempt: number, logger: Logger, opts: RunOptions): Promise<ValidationAttempt>;
+/**
+ * The repair instruction handed to the agent after a failed attempt: the failing commands and
+ * their captured output, plus an explicit statement of the exit condition and the remaining
+ * budget. The FULL captured tail is used here (not the report's smaller bound) — the agent needs
+ * the whole failure to fix it, and this text never leaves the container.
+ *
+ * Deliberately prescriptive about scope: a validation loop that lets the agent "fix" the failure
+ * by weakening the check is worse than no loop at all, so the prompt forbids editing the
+ * commands' configuration to make them pass.
+ */
+export declare function buildRepairPrompt(report: ValidationReport, fullTails: Map<string, string>, 
+/**
+ * New files the agent created but never `git add`ed, if the caller can tell. The harness only
+ * auto-stages TRACKED edits (`git add -u`), so an uncommitted new file is invisible to the push
+ * — yet fully visible to the checks, which run against the working tree. Naming them here is
+ * what stops the loop going green on work the pull request would not contain.
+ */
+untrackedFiles?: string[]): string;
+/**
+ * The pre-PR validation LOOP: run the checks, and while they fail and budget remains, hand the
+ * captured output back to the agent as its next instruction and check again. Returns the LAST
+ * attempt's report — `passed: true` means the caller may open the PR; `passed: false` means the
+ * budget is spent and the caller must FAIL the job with this report as the evidence, opening
+ * nothing.
+ *
+ * Generic by construction: it knows nothing about agent kinds, repos or PRs — only how to run
+ * commands in a directory and how to ask for another pass. Every input (`workDir`, `spec`,
+ * `opts.agentEnv`) is per-job, so two concurrent jobs on the ONE local-native host process cannot
+ * see each other's configuration (`validation-checks.concurrency.test.ts` pins this).
+ *
+ * `onAttempt` publishes each completed attempt on the job view so the loop is observable while it
+ * runs; `onAgentPass` lets the caller fold each repair pass's stats/usage/telemetry into the run's
+ * totals, so a 3-round loop reports what all 3 rounds actually spent.
+ */
+export declare function runValidationLoop<TRun>(args: {
+    workDir: string;
+    spec: ValidationChecksSpec;
+    logger: Logger;
+    opts: RunOptions;
+    runAgentPass: (userPrompt: string) => Promise<TRun>;
+    onAgentPass?: (run: TRun) => void;
+    /**
+     * Optional: the new files left uncommitted in the checkout, folded into each repair prompt.
+     * Injected rather than read here so this module stays git-agnostic (it knows only how to run
+     * commands in a directory and how to ask for another pass); the coding agent, which owns the
+     * checkout, supplies it. A throw is swallowed — a missing warning must never fail the loop.
+     */
+    listUncommittedNewFiles?: () => Promise<string[]>;
+}): Promise<ValidationReport>;
+/**
+ * The failure message for a run whose pre-PR validation never went green: which checks failed
+ * (with exit codes) and the last one's captured output. Read by the operator on the step's
+ * failure card, so it must say what broke without needing the full report opened.
+ */
+export declare function validationFailureMessage(report: ValidationReport): string;

package/dist/vcs-api.d.ts

@@ -0,0 +1,73 @@
+import type { PrSpec } from './job.js';
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export declare function describePrOpenFailure(status: number, provider: 'github' | 'gitlab'): string | undefined;
+export interface OpenPullRequestOptions {
+    owner: string;
+    name: string;
+    ghToken: string;
+    head: string;
+    base: string;
+    pr: PrSpec;
+    apiBase?: string;
+    /**
+     * The repo's clone URL. Used (when {@link provider} is absent) to detect the provider and,
+     * for GitLab, to derive the REST base + project path from its host — so the harness opens a
+     * GitLab **merge request** rather than POSTing to GitHub's pulls API. Absent ⇒ GitHub.
+     */
+    cloneUrl?: string;
+    /**
+     * The VCS provider, when the dispatcher knows it (the server derives it from the configured
+     * source-control backend and sets `repo.provider`). AUTHORITATIVE — it overrides host
+     * inference — so a self-managed GitLab on an arbitrarily-named host (e.g. `git.acme.com`,
+     * which {@link inferVcsProvider} can't recognise) still opens a merge request instead of
+     * being misrouted to GitHub's API. Absent ⇒ inferred from {@link cloneUrl}'s host.
+     */
+    provider?: 'github' | 'gitlab';
+    /**
+     * When the PR/MR for {@link head} ALREADY exists (a resumed run pushing onto a branch whose PR
+     * is open), replace its title and description with {@link pr} instead of leaving them alone.
+     *
+     * Set ONLY when {@link pr} carries the agent's own reviewer briefing. A resumed run is exactly
+     * the case that matters — eviction + re-dispatch, a ralph iteration, a retry — and without this
+     * the agent writes a briefing the platform reads, scrubs, caps and then silently drops. It must
+     * stay opt-in, though: refreshing from the GENERIC dispatch-time fallback would overwrite a
+     * description a human (or an earlier, better-informed run) had already written.
+     *
+     * The engine's managed verification-report region is carried across the rewrite by
+     * {@link preserveManagedSection}, and the update is best-effort — a failed refresh keeps the
+     * run's real outcome, which is the pushed work.
+     */
+    refreshExisting?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * The VCS host a clone URL points at. The harness is otherwise provider-agnostic (its git
+ * auth is a host-neutral GIT_ASKPASS credential), but the "open the PR/MR" REST call is not:
+ * GitHub and GitLab have different endpoints, so infer which to call from the host. GitHub is
+ * the default; a host of `gitlab.com` or one in the `gitlab.*` / `*.gitlab.*` family (covering
+ * self-managed instances named that way) is treated as GitLab.
+ */
+export declare function inferVcsProvider(cloneUrl: string): 'github' | 'gitlab';
+/** The GitLab REST v4 base for a clone URL's host, e.g. `https://gitlab.com/api/v4`. */
+export declare function gitlabApiBaseFromCloneUrl(cloneUrl: string): string;
+/**
+ * The URL-encoded GitLab project path from a clone URL — the full namespace path (so subgroups
+ * survive), with the trailing `.git` stripped, e.g.
+ * `https://gitlab.com/group/sub/proj.git` → `group%2Fsub%2Fproj`.
+ */
+export declare function gitlabProjectPath(cloneUrl: string): string;
+/**
+ * Open a PR (GitHub) or merge request (GitLab) for the pushed branch; returns its web URL.
+ * The provider is chosen from the EXPLICIT `opts.provider` when the dispatcher set it,
+ * falling back to host inference from the clone URL only when it didn't — so a self-managed
+ * GitLab whose host isn't named `gitlab.*` still opens an MR instead of being misrouted to
+ * GitHub's API. The GitHub path is unchanged.
+ */
+export declare function openPullRequest(opts: OpenPullRequestOptions): Promise<string | null>;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The running harness version, or undefined when it cannot be determined. */
+export declare const HARNESS_VERSION: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.78.0",
+  "version": "1.82.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",
@@ -15,7 +15,11 @@
   "main": "./dist/server.js",
   "exports": {
     ".": "./dist/server.js",
-    "./embed": "./src/embed.ts"
+    "./embed": "./src/embed.ts",
+    "./claude-call-aggregator": {
+      "types": "./dist/claude-call-aggregator.d.ts",
+      "default": "./dist/claude-call-aggregator.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -26,9 +30,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/kernel": "0.201.0",
+    "@cat-factory/server": "0.185.1",
+    "@cat-factory/spend": "0.12.131"
   },
   "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-call-aggregator.ts

@@ -12,6 +12,19 @@ import type { HarnessCallMetric } from './pi.js'
 // This aggregator folds every envelope sharing a `message.id` back into the one call it belongs to,
 // and buffers that call's tool_result turns so the reconstructed prompt chain keeps the shape the
 // model was actually sent: one assistant turn holding all its blocks, then the results.
+//
+// TWO CONSUMERS, and a change here reaches both. The container/host harness drives it from a
+// coding job's stdout (`agent-runner.ts`), and the BACKEND drives it from the host `claude` an
+// inline step runs on (`runtimes/local/src/harnessInline.ts`, importing this module through the
+// package's `./claude-call-aggregator` subpath). Both parse the SAME `stream-json`, and the second
+// used to carry its own lesser fold — which is how the inline path came to report one lumped call
+// per step while the container path reported every turn. Keep this the only implementation; it is
+// also the one place the per-block over-count above is fixed.
+//
+// The second consumer is why the transcript is BOUNDED and body assembly is OPTIONAL (see
+// {@link MAX_TRANSCRIPT_CHARS} and `bodies`). Inside a container the reconstruction is one job's
+// worth of memory in a box sized for it; in the backend it runs per concurrent inline step, in the
+// orchestrator process, on precisely the long tool loops worth diagnosing.
 
 /** One model call, assembled from every stream envelope that carried a piece of it. */
 export interface AggregatedClaudeCall {
@@ -134,6 +147,128 @@ interface TranscriptTurn {
   content: unknown
 }
 
+/**
+ * How much reconstructed transcript ONE conversation may retain.
+ *
+ * The stream feeds this without limit — a tool loop that reads large files grows the history by
+ * every one of them — and the reconstruction is held in the driver's own process. In the container
+ * that is a box sized for one job; in the BACKEND it is the orchestrator, where `streamCli` already
+ * refuses to retain the raw stream for exactly this reason (`harnessInline.ts` →
+ * `OUTPUT_TAIL_RETAIN_CHARS`: "a stalled tool-using run would otherwise park hundreds of MB in the
+ * orchestrator process — precisely on the runs worth diagnosing").
+ *
+ * 512 KiB because that is `LlmObservabilityService.MAX_BODY_CHARS`, the point past which the store
+ * truncates a body anyway: retaining more can only ever be thrown away. Deliberately NOT a
+ * per-deployment knob — it bounds a memory fault, and a number an operator can raise is one an
+ * operator can raise until the process dies.
+ */
+export const MAX_TRANSCRIPT_CHARS = 512 * 1024
+
+/**
+ * The role a turn carries when it is not a turn at all, but the note saying what stopped being
+ * retained. A distinct namespaced role rather than `system`, so nothing downstream can read it as a
+ * message that was actually sent — the same reason `seed` exists.
+ */
+const ELIDED_ROLE = 'cat-factory:elided'
+
+/** The growing request transcript behind a conversation's `promptText`. */
+interface Transcript {
+  /** The history as of NOW: what the call starting at this moment was sent. */
+  snapshot(): { text: string; messageCount: number }
+  /** Add a turn the conversation has now completed. */
+  append(turn: TranscriptTurn): void
+}
+
+/**
+ * Retain the transcript up to {@link MAX_TRANSCRIPT_CHARS} and then STOP, stating what it stopped
+ * retaining rather than silently ending mid-conversation.
+ *
+ * Freezing the tail (rather than evicting the head) keeps the seed and the early history — the
+ * task, and the turns that explain what the loop is doing — and keeps each call's `promptText` a
+ * stable PREFIX plus a changing note, so the backend's chain delta-compresses right up to the bound
+ * and only then degrades to storing the (now capped) array. Evicting the head would drop the task
+ * itself and break the prefix property from the first eviction on.
+ *
+ * The seed is never dropped: it is what the CALLER sent, so it is bounded by the caller's own
+ * prompt rather than by the stream, and it is the half a reader cannot reconstruct from anything
+ * else.
+ */
+function createBoundedTranscript(
+  seed: TranscriptTurn[],
+  secrets: string[],
+  maxChars: number,
+): Transcript {
+  const turns: TranscriptTurn[] = [...seed]
+  const sizeOf = (turn: TranscriptTurn): number => {
+    try {
+      return JSON.stringify(turn)?.length ?? 0
+    } catch {
+      // An un-serialisable turn cannot be retained at all, so charge it nothing and let the
+      // append below drop it on its own terms.
+      return Number.POSITIVE_INFINITY
+    }
+  }
+  let retained = turns.reduce((n, turn) => n + sizeOf(turn), 0)
+  const dropped = { turns: 0, chars: 0 }
+  return {
+    append(turn) {
+      const size = sizeOf(turn)
+      if (retained + size > maxChars) {
+        dropped.turns += 1
+        dropped.chars += Number.isFinite(size) ? size : 0
+        return
+      }
+      turns.push(turn)
+      retained += size
+    },
+    snapshot() {
+      const encoded = dropped.turns
+        ? [
+            ...turns,
+            {
+              role: ELIDED_ROLE,
+              content:
+                `${dropped.turns} later turn(s), ${dropped.chars} chars, were not retained: ` +
+                `this conversation reached the ${maxChars}-char reconstruction bound`,
+            },
+          ]
+        : turns
+      return {
+        text: redactBody(safeSerialise(encoded), secrets),
+        messageCount: encoded.length,
+      }
+    },
+  }
+}
+
+/**
+ * Count the turns and assemble NO bodies — for a driver that has nowhere to put them (the backend
+ * with `LLM_RECORD_PROMPTS` off, where the store drops every body it is handed).
+ *
+ * `messageCount` stays real, because it is a COUNT rather than a body and every consumer of the
+ * metric wants it. The point is not to omit data the gate would keep; it is that serialising a
+ * transcript the gate is about to drop is pure cost, and the whole reason bodies travel to the
+ * recorder as thunks (`CLAUDE.md` → "Telemetry & agent-context observability").
+ */
+function createCountingTranscript(seed: TranscriptTurn[]): Transcript {
+  let messageCount = seed.length
+  return {
+    append() {
+      messageCount += 1
+    },
+    snapshot: () => ({ text: '', messageCount }),
+  }
+}
+
+/** Serialise a transcript for the store, never throwing into the stream that produced it. */
+function safeSerialise(turns: TranscriptTurn[]): string {
+  try {
+    return JSON.stringify(turns) ?? ''
+  } catch {
+    return ''
+  }
+}
+
 /** The per-call telemetry the Claude Code stream yields, assembled behind one small surface. */
 export interface ClaudeStreamTelemetry {
   /** Fold an `assistant` envelope in (parent-loop turns only — see {@link isSubagentEvent}). */
@@ -155,20 +290,26 @@ export interface ClaudeStreamTelemetry {
  * was not sent. A subagent's conversation seeds EMPTY — its prompt was minted by the CLI and never
  * crosses this stream — which is also why its first call carries `messageCount: 0` (the backend's
  * `latestChainTip` skips those on purpose: there is no re-sendable chain to delta against).
- * Bodies are credential-scrubbed; they can echo the leased token.
+ * Bodies are credential-scrubbed; they can echo the leased token — and assembled at all only when
+ * {@link ClaudeStreamTelemetryOptions.bodies} says a driver has somewhere to put them. The
+ * transcript is bounded either way ({@link MAX_TRANSCRIPT_CHARS}).
  *
  * Deliberately does NOT touch {@link PiRunStats}: the run's tool/output counters describe whether
  * the agent ACTED at all (`agentNeverActed`), which is true of a subagent's turns whichever channel
  * ends up owning their telemetry rows. The caller accumulates them off the raw stream instead.
  */
-export function createClaudeStreamTelemetry(opts: {
-  seed: TranscriptTurn[]
-  secrets: string[]
-  publish: (metric: HarnessCallMetric) => void
-}): ClaudeStreamTelemetry {
-  const messages: TranscriptTurn[] = [...opts.seed]
-  let callPrompt = ''
-  let callMessageCount = 0
+export function createClaudeStreamTelemetry(
+  opts: ClaudeStreamTelemetryOptions,
+): ClaudeStreamTelemetry {
+  const bodies = opts.bodies ?? true
+  const transcript = bodies
+    ? createBoundedTranscript(
+        opts.seed,
+        opts.secrets,
+        opts.maxTranscriptChars ?? MAX_TRANSCRIPT_CHARS,
+      )
+    : createCountingTranscript(opts.seed)
+  let sent = { text: '', messageCount: 0 }
 
   // The aggregator IS the surface: the transcript and metric work happens in its callbacks, so
   // there is nothing to wrap it in.
@@ -177,16 +318,15 @@ export function createClaudeStreamTelemetry(opts: {
     // produced the response, and later envelopes of the same call must not see the turns it
     // went on to add.
     onCallStart: () => {
-      callPrompt = redactBody(JSON.stringify(messages), opts.secrets)
-      callMessageCount = messages.length
+      sent = transcript.snapshot()
     },
     onCall: (call) => {
       opts.publish({
         ...(call.model ? { model: call.model } : {}),
-        promptText: callPrompt,
-        messageCount: callMessageCount,
-        responseText: redactBody(call.text, opts.secrets),
-        reasoningText: redactBody(call.reasoning, opts.secrets),
+        promptText: sent.text,
+        messageCount: sent.messageCount,
+        responseText: bodies ? redactBody(call.text, opts.secrets) : '',
+        reasoningText: bodies ? redactBody(call.reasoning, opts.secrets) : '',
         inputTokens: call.inputTokens,
         cacheReadTokens: call.cacheReadTokens,
         cacheWriteTokens: call.cacheWriteTokens,
@@ -195,12 +335,30 @@ export function createClaudeStreamTelemetry(opts: {
       })
       // Appended only now, so each call's prompt stays a strict prefix of the next and the
       // backend's telemetry chain delta-compresses cleanly.
-      messages.push({ role: 'assistant', content: call.content })
-      for (const result of call.toolResults) messages.push({ role: 'tool', content: result })
+      transcript.append({ role: 'assistant', content: call.content })
+      for (const result of call.toolResults) transcript.append({ role: 'tool', content: result })
     },
   })
 }
 
+/** How one conversation's per-call telemetry is assembled. */
+export interface ClaudeStreamTelemetryOptions {
+  seed: TranscriptTurn[]
+  secrets: string[]
+  publish: (metric: HarnessCallMetric) => void
+  /**
+   * Whether to assemble the prompt/response BODIES at all. Absent ⇒ true (the container harness,
+   * whose job result carries them).
+   *
+   * `false` for a driver whose store will drop them — the backend with `LLM_RECORD_PROMPTS` off —
+   * where reconstructing a transcript per call is pure cost. Token counts, `messageCount` and
+   * finish reasons are unaffected: only the bodies go.
+   */
+  bodies?: boolean
+  /** Retention bound override (tests). Absent ⇒ {@link MAX_TRANSCRIPT_CHARS}. */
+  maxTranscriptChars?: number
+}
+
 /**
  * The dispatch (`Agent`/`Task` tool_use) id a stream envelope is tagged with, or `undefined` for a
  * parent-loop turn.
@@ -238,10 +396,7 @@ export function isSubagentEvent(event: Record<string, unknown>): boolean {
  * one stream: folding them into a single chain is exactly the defect this whole module removes,
  * one level down.
  */
-function createSubagentStreamTelemetry(opts: {
-  secrets: string[]
-  publish: (metric: HarnessCallMetric) => void
-}): {
+function createSubagentStreamTelemetry(opts: Omit<ClaudeStreamTelemetryOptions, 'seed'>): {
   onAssistant(dispatchId: string, message: Record<string, unknown>): void
   onToolResult(dispatchId: string, content: unknown[]): void
   flush(): void
@@ -251,11 +406,8 @@ function createSubagentStreamTelemetry(opts: {
     let telemetry = perDispatch.get(dispatchId)
     if (!telemetry) {
       // Seeded EMPTY: the CLI minted this subagent's prompt and it never crossed the stream.
-      telemetry = createClaudeStreamTelemetry({
-        seed: [],
-        secrets: opts.secrets,
-        publish: opts.publish,
-      })
+      // Each dispatch gets its OWN retention bound, since each is its own conversation.
+      telemetry = createClaudeStreamTelemetry({ ...opts, seed: [] })
       perDispatch.set(dispatchId, telemetry)
     }
     return telemetry
@@ -301,12 +453,9 @@ export interface ClaudeRunTelemetry {
  * 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.
  */
-export function createClaudeRunTelemetry(opts: {
-  seed: TranscriptTurn[]
-  secrets: string[]
-  watcherOwnsSubagents: boolean
-  publish: (metric: HarnessCallMetric) => void
-}): ClaudeRunTelemetry {
+export function createClaudeRunTelemetry(
+  opts: ClaudeStreamTelemetryOptions & { watcherOwnsSubagents: boolean },
+): ClaudeRunTelemetry {
   const parent = createClaudeStreamTelemetry(opts)
   const subagents = opts.watcherOwnsSubagents ? undefined : createSubagentStreamTelemetry(opts)
   let sawSubagentTurn = false

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.