@cat-factory/executor-harness 1.78.0 → 1.82.0

package/dist/runner.d.ts

@@ -0,0 +1,282 @@
+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 { type Logger } from './logger.js';
+import { type FailureCause } from './failure.js';
+/** Non-secret correlation fields a job carries on every log line (jobId, repo, branch, …). */
+type LogFields = Record<string, unknown>;
+/** Options threaded into the long-running git/Pi work so a watchdog can cancel it. */
+export interface RunOptions {
+    signal?: AbortSignal;
+    onActivity?: () => void;
+    /** Receives the latest subtask counts as Pi updates its todo list. */
+    onProgress?: (progress: TodoProgress) => void;
+    /** Receives one compact {@link ToolSpan} per completed tool call (observability). */
+    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 completed PRE-PR VALIDATION attempt the moment the harness finishes running
+     * the service's check commands, so the backend can surface the repair loop LIVE ("lint failed,
+     * repairing — attempt 2 of 3") instead of only in the terminal result. Latest-wins (NOT a drain
+     * buffer): a published attempt is final, and the loop republishes a whole new one per round.
+     */
+    onValidationReport?: (report: ValidationReport) => void;
+    /**
+     * Receives each completed BUGFIX REPRODUCTION PROOF attempt the moment the harness finishes
+     * running the declared check against both trees, so the backend can surface a failed
+     * verification WHILE the repair loop still runs rather than only in the terminal result.
+     * Latest-wins (NOT a drain buffer), exactly like {@link onValidationReport}: a published
+     * 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
+     * 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
+     * per-phase wall-clock is logged on completion. Free-form; unknown phases just show verbatim.
+     */
+    onPhase?: (phase: string) => void;
+    /**
+     * The phase most recently marked via {@link onPhase} — the read side of the same marker, for
+     * work that has to TELL the backend which phase it is in rather than merely record it. Today
+     * that is the Pi path, whose calls are metered server-side by the LLM proxy: the harness tags
+     * the proxy URL with this so a repair round's spend is attributable
+     * (`docs/initiatives/token-burn-instrumentation.md`). Absent ⇒ no phase is carried and those
+     * calls land in the backend's unattributed slice.
+     */
+    currentPhase?: () => string;
+    /** A per-job child logger carrying the run's correlation fields (jobId, repo, branch, …). */
+    log?: Logger;
+    /**
+     * Extra environment for the agent's child process, scoped to THIS job. The CLI is spawned with
+     * `{...process.env, ...agentEnv}`, so these reach the agent and every shell tool it spawns.
+     *
+     * This is the seam for anything per-job that would otherwise be written to a process- or
+     * HOME-global (the tester's secrets, a private-registry npmrc pointer). Those globals are only
+     * per-job when the process is — true for a container, FALSE for the local native host-process
+     * transport, which serves every concurrent ambient job from one process on the developer's own
+     * HOME. Set it via `withAgentEnv`; never mutate `process.env` for a job.
+     */
+    agentEnv?: Record<string, string>;
+}
+export type JobState = 'running' | 'done' | 'failed';
+/**
+ * The minimum a job result must expose: a structured `error` marks a job-level
+ * failure even when the HTTP run itself succeeded. Every agent result (explore /
+ * coding / bootstrap / conflict) satisfies this, so {@link JobRegistry} is generic
+ * over the result it tracks while reusing one watchdog/lifecycle.
+ */
+export interface JobResultBase {
+    error?: string;
+    /**
+     * The structured reason a clean-exit result failed (set alongside `error` by a handler that
+     * finished but produced an unusable/failed result — no-usable-output, no-changes, …). The
+     * registry copies it onto the job view's `failureCause`. Absent on a watchdog/throw failure
+     * (the registry sets that cause itself). See {@link FailureCause}.
+     */
+    failureCause?: FailureCause;
+}
+/** The job view returned by GET /jobs/{id}, generic over the orchestration's result. */
+export interface JobView<TResult extends JobResultBase = JobResultBase> {
+    id: string;
+    state: JobState;
+    startedAt: number;
+    /** Epoch ms of the last sign of progress (job start, or Pi output). */
+    heartbeatAt: number;
+    /**
+     * The coarse lifecycle phase the job is CURRENTLY in (`starting` → `clone` → `agent`
+     * → `push` → `done`/`failed`), so the backend can surface WHAT the container is doing
+     * rather than a blank "working" state — is it still cloning/preparing the checkout, or
+     * has the agent begun making calls? The same per-phase marker that drives the stuck-run
+     * breadcrumb on a failure, exposed live here while the job runs. Free-form; unknown
+     * phases just show verbatim. Always present (seeded `starting` at job start).
+     */
+    phase?: string;
+    /**
+     * Latest subtask progress from Pi's `todo` tool while the job runs — the
+     * Worker poll surfaces it to the board (e.g. "3/8 done"). Absent until Pi
+     * first touches its todo list (or if the model never uses it).
+     */
+    progress?: TodoProgress;
+    /** Present when `state === 'done'`: the orchestration's structured result. */
+    result?: TResult;
+    /** Present when `state === 'failed'`: why the job faulted (or was killed). */
+    error?: string;
+    /**
+     * Present when `state === 'failed'`: the STRUCTURED failure cause, so the backend can
+     * classify the failure without regex-matching {@link error}. Backward compatible — the
+     * backend prefers this and falls back to the (still-stable) `error` regex when absent.
+     * Container eviction is NOT represented here (the runtime facade detects that from a
+     * vanished container); see {@link FailureCause}.
+     */
+    failureCause?: FailureCause;
+    /**
+     * Present when `state === 'failed'`: an extended, redacted diagnostic (phase-timing
+     * breakdown, last-tool breadcrumb, …) distinct from the one-line {@link error}. The
+     * backend surfaces it as the failure `detail` on the board card. Best-effort.
+     */
+    detail?: string;
+    /**
+     * Tool spans accumulated SINCE THE LAST POLL (drain-on-read): the GET /jobs/{id}
+     * handler returns the spans buffered since the previous poll and clears the buffer,
+     * so the harness only ever holds one poll-interval's worth. Best-effort observability
+     * — a dropped poll response loses at most one window. Absent until a tool runs.
+     */
+    spans?: ToolSpan[];
+    /**
+     * Forward-looking follow-up / question items the Coder streamed SINCE THE LAST POLL
+     * (drain-on-read, exactly like {@link spans}): the GET /jobs/{id} handler returns the
+     * items buffered since the previous poll and clears the buffer. The backend appends them
+     * to the run's step so the Follow-up companion surfaces them live. Absent until the Coder
+     * 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.
+     * This does NOT fail the job (the inactivity/max-duration watchdogs still own that).
+     *
+     * Legibility is via the per-job container log line emitted the moment it fires (the
+     * ~2-minute early signal the ADR wants), this field on the GET /jobs/{id} view for an
+     * operator hitting the endpoint, and — when the job goes on to fail — a sentence folded into
+     * {@link detail}, which is the path that reaches the run without a new field on every
+     * transport hop. Surfacing it on a still-RUNNING step (the early warning) remains deferred.
+     * Absent on a job that produced output promptly (the overwhelming common case). Sticky once set.
+     */
+    coldStart?: {
+        atMs: number;
+        message: string;
+    };
+    /**
+     * The LATEST completed pre-PR validation attempt (see `docs/initiatives/pre-pr-validation.md`).
+     * Unlike {@link spans}/{@link followUps} this is NOT drain-on-read: it is a whole-value latest
+     * publish, so re-reading it on a later poll is harmless and a dropped poll loses nothing (the
+     * next round republishes). Absent for a job whose service configured no checks.
+     */
+    validationReport?: ValidationReport;
+    /**
+     * The LATEST completed bugfix reproduction-proof attempt (see
+     * `docs/initiatives/bugfix-reproduction-proof.md`). Like {@link validationReport} — and unlike
+     * {@link spans}/{@link followUps} — this is a whole-value latest publish, not drain-on-read, so
+     * re-reading it on a later poll is harmless and a dropped poll loses nothing. Absent for a job
+     * 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[];
+}
+/** Watchdog windows that bound every job. Tunable via the container's env. */
+export interface RunnerLimits {
+    /** Hard ceiling on total job wall-clock before it's force-failed. */
+    maxDurationMs: number;
+    /** Force-fail the job if the agent produces no output for this long (hang guard). */
+    inactivityMs: number;
+    /**
+     * ADR 0026 D4: a short first-output window. If the job produces NO activity within this
+     * long after start, emit a structured cold-start diagnostic (a likely onboarding/auth
+     * wedge) — WITHOUT killing the run. Purely a legibility signal so a genuine cold-start
+     * wedge surfaces in a couple of minutes instead of waiting out the full inactivity
+     * window. Safely under the clone-inclusive phases (a large clone still streams git
+     * progress, which counts as activity). Set to 0 to disable.
+     */
+    coldStartMs: number;
+}
+export declare function loadRunnerLimits(env?: NodeJS.ProcessEnv): RunnerLimits;
+/**
+ * Tracks background jobs by id. Keyed by the backend-supplied job id (the per-step
+ * job id) so a re-dispatched start re-attaches to the running job rather than starting
+ * a duplicate — which keeps the durable driver's retries idempotent and avoids redoing
+ * already-running work. Generic over the job/result shape so the same lifecycle +
+ * inactivity/max-duration watchdogs drive every agent run.
+ */
+export declare class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResultBase> {
+    private readonly limits;
+    private readonly run;
+    private readonly describe;
+    private readonly jobs;
+    constructor(limits: RunnerLimits, run: (job: TJob, opts: RunOptions) => Promise<TResult>, describe?: (job: TJob) => LogFields);
+    /** Start the job for `id`, or return the existing one (idempotent re-attach). */
+    start(id: string, job: TJob): JobView<TResult>;
+    /**
+     * 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;
+    /**
+     * Abort every RUNNING job (fires each run's abort signal, which SIGTERM→SIGKILLs its
+     * CLI/git children via `killChildProcess`). The graceful-shutdown hook: a harness dying
+     * to SIGTERM must not orphan a live agent subprocess — reparented, it would keep working
+     * unsupervised (and, in native local mode, on the developer's own login). Returns the
+     * number of jobs aborted.
+     */
+    abortAll(reason: string): number;
+    /**
+     * How many jobs are still RUNNING. Graceful shutdown polls this so it can exit the moment the
+     * aborted jobs have actually settled (the common case: the CLI honours SIGTERM in ms) instead
+     * of waiting out a fixed kill-grace window.
+     */
+    runningCount(): number;
+    private drive;
+    /**
+     * Build the redacted one-line `error`, the structured {@link FailureCause}, and the extended
+     * `detail` for a failed job. Watchdog kills set their structured cause (`inactivity-timeout` /
+     * `max-duration`) — the backend classifies on that, so their message is a human-readable
+     * breadcrumb of where they hung, no longer a regex-stable phrase; a thrown error keeps its own
+     * message and its structured cause when tagged (a git op → `git`, an upstream API call → `api`),
+     * else `agent`. All strings are credential-scrubbed.
+     *
+     * `detail` is where the evidence the harness already holds but the one-line `error` has no room
+     * for lands: the phase breakdown, the {@link failureBreadcrumb} (last completed tool + how long
+     * the run had been silent), and the cold-start diagnostic when that watchdog recorded one. It is
+     * the only one of the three that reaches the run's failure record, so a diagnostic that isn't
+     * folded in here is effectively invisible outside the container log.
+     */
+    private describeFailure;
+}
+export {};

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/server.d.ts

@@ -0,0 +1,3 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+declare const server: import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+export { server };

package/dist/structured-output.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Declarative definition of one structured-output kind: how to label it, what shape
+ * to ask the repair model for, and how to turn the agent's text into the domain value.
+ * `parse` returns null (or throws) when the text is unusable. Built per-job when the
+ * parser needs job context (e.g. a fallback service name).
+ */
+export interface StructuredOutputSpec<T> {
+    /** Label for logs/telemetry, e.g. `requirements` / `blueprint` / `merger`. */
+    label: string;
+    /** Compact human description of the expected top-level JSON shape, fed to the model. */
+    shapeHint: string;
+    /** Parse the agent's text into the domain value, or null/throw when unusable. */
+    parse: (text: string) => T | null;
+}
+/** Runtime wiring to reach the LLM proxy for the repair call. */
+export interface ProxyAccess {
+    /** Pi-harness proxy base URL; absent for subscription harnesses (no proxy repair). */
+    proxyBaseUrl?: string;
+    /**
+     * The backend serves the phase-tagged completions route, so the repair call can be attributed
+     * to {@link STRUCTURED_REPAIR_PHASE} rather than piling into the unattributed slice
+     * (see {@link HarnessAuthFields.proxyPhasePath}).
+     */
+    proxyPhasePath?: boolean;
+    /** Pi-harness proxy session token; absent for subscription harnesses. */
+    sessionToken?: string;
+    model: string;
+    jobId: string;
+    signal?: AbortSignal;
+    /** Carried for context (the subscription harnesses can't use the proxy for repair). */
+    harness?: string;
+    subscriptionToken?: string;
+    subscriptionBaseUrl?: string;
+}
+/** Structured diagnostics for a resolution attempt, surfaced to logs + the failure reason. */
+export interface StructuredOutputDiagnostics {
+    /** Which attempt produced a usable value (or `none` when both failed). */
+    parsedOn: 'primary' | 'repair' | 'none';
+    /** Length of the agent's primary (Pi) output, in characters. */
+    primaryChars: number;
+    /** Whether the primary output looked token-doubled (advisory heuristic). */
+    looksDoubled: boolean;
+    /** Whether a repair call was made. */
+    repairAttempted: boolean;
+    /** Whether the repair call produced a usable value. */
+    repairSucceeded: boolean;
+    /** One-line reason the repair call itself failed (HTTP error / still-unparseable), if any. */
+    repairError?: string;
+}
+export interface StructuredOutputResult<T> {
+    value: T | null;
+    diagnostics: StructuredOutputDiagnostics;
+}
+/**
+ * Heuristic detector for the token-doubling corruption ("serviceservice",
+ * "observobservabilityability", `{\n{\n`). Greedy scan over a bounded prefix: at each
+ * position, find the longest 2..{@link MAX_DOUBLE_RUN}-char run that is immediately
+ * repeated and count both copies as "doubled", then measure the doubled fraction of
+ * the scanned text. Token-doubled text (consecutive `t t` pairs) scores near 1.0;
+ * normal JSON/prose scores low (only incidental short repeats). Advisory ONLY — it
+ * labels a failure for telemetry, it never mutates output.
+ */
+export declare function looksTokenDoubled(text: string): {
+    doubled: boolean;
+    ratio: number;
+};
+/**
+ * Resolve a structured output: parse the agent's `primaryText` via `spec.parse`; on
+ * failure, make ONE structured repair call and re-parse. Returns the value (or null
+ * when both attempts fail) plus {@link StructuredOutputDiagnostics}. Logging side
+ * effects only; never throws (a repair transport error is captured in the diagnostics).
+ */
+export declare function resolveStructuredOutput<T>(spec: StructuredOutputSpec<T>, primaryText: string, access: ProxyAccess): Promise<StructuredOutputResult<T>>;
+/** Append a compact, human-readable diagnostics suffix to a no-document failure reason. */
+export declare function diagnosticsSuffix(d: StructuredOutputDiagnostics): string;

package/dist/subagents.d.ts

@@ -0,0 +1,88 @@
+import type { Logger } from './logger.js';
+import { type HarnessCallMetric, type TodoProgress } from './pi.js';
+/**
+ * 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 declare const SLICE_REPORT_MAX_CHARS = 24000;
+/** 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 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;
+    /**
+     * Progress derived from the dispatched subagents (completed / in-flight / total),
+     * or undefined when none have been dispatched. Reconciled with the parent's own plan
+     * by `pickProgress` (./progress.ts) — it is NOT gated off by the presence of a plan
+     * (that gate was ADR 0027 Defect B: the pr-reviewer prompt writes the plan ONCE at
+     * grouping time and never marks it done, which used to permanently mask this signal).
+     */
+    progress(): TodoProgress | undefined;
+}
+/**
+ * @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 declare function createSliceTracker(secrets?: string[]): SliceTracker;
+export interface SubagentWatcherOptions {
+    /** Fed the heartbeat when a transcript grows, so the inactivity watchdog sees the run is alive. */
+    onActivity?: () => void;
+    /** Leased-credential strings to scrub from captured bodies (the transcripts can echo the token). */
+    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;
+}
+export interface SubagentWatcher {
+    /** Do a final poll, then stop watching. Idempotent; never throws. */
+    stop(): Promise<void>;
+    /** Cumulative subagent usage lifted so far (input + output tokens). */
+    usage(): {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** The per-call telemetry rows lifted from the subagent transcripts so far. */
+    calls(): HarnessCallMetric[];
+}
+/**
+ * Start watching `root` (the CLI's `<configHome>/projects` tree) for subagent `*.jsonl`
+ * transcripts — any file under a `subagents/` directory beneath it (see
+ * {@link findSubagentTranscripts}) — tailing each file by byte offset. New content feeds
+ * `onActivity` (heartbeat) and each assistant turn carrying usage is lifted into a
+ * {@link HarnessCallMetric} + summed into the cumulative usage. Best-effort throughout: the
+ * tree may not exist yet (created lazily by the CLI), a file may be mid-write, and the
+ * line/usage shape may change across CLI versions — every such case is swallowed so the
+ * watcher can only ever ADD signal, never break the run.
+ */
+export declare function startSubagentWatcher(root: string, opts: SubagentWatcherOptions): SubagentWatcher;

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/dist/transcript-retention.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from './logger.js';
+/**
+ * A marker file dropped into every retention dir THIS module creates. The pruner deletes ONLY
+ * dirs carrying it, so pointing `HARNESS_TRANSCRIPT_ROOT` at a shared (non-dedicated) directory
+ * can never `rm -rf` unrelated sibling content — we only ever sweep our own retained transcripts.
+ */
+export declare const RETENTION_MARKER = ".cf-retained";
+export interface RetainOptions {
+    /** A short label for the run/harness, folded into the retention log line. */
+    label?: string;
+    /** The per-job child logger, so the retained path is logged with the run's correlation fields. */
+    log?: Logger;
+}
+/**
+ * Move the named transcript `subdirs` out of the credential-bearing config `home` into the
+ * retention root (so the caller's subsequent `rm(home)` can't take them), then prune retained
+ * transcripts older than the TTL. Both steps are best-effort: any failure is swallowed (logged
+ * at debug) so this can never fail an otherwise-successful run. Returns the destination dir when
+ * something was retained (for logging/tests), else `undefined`.
+ */
+export declare function retainSessionTranscripts(home: string, subdirs: string[], options?: RetainOptions): Promise<string | undefined>;