@cat-factory/executor-harness 1.78.0 → 1.82.0

package/README.md

@@ -206,6 +206,7 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
 | `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc — the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`) — talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
+| `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation — the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations — and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
 | `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls — it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort — every failure shape becomes a note, never a failed job. Generic — keyed off the job body, never the agent kind. |

package/dist/agent-capabilities.d.ts

@@ -0,0 +1,130 @@
+/** One materialisable resource file of a skill. */
+export interface SkillResourceSpec {
+    /** Path within the skill directory, e.g. `templates/report.md` (subdirs preserved, no traversal). */
+    relPath: string;
+    content: string;
+}
+/**
+ * A skill to make available for a run. Materialised HARNESS-AWARE:
+ * `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md` (+ resources) for the claude-code CLI to load
+ * natively, or `.cat-context/skill/<name>/<relPath>` for the Pi/codex checkout (their prompt
+ * carries the instructions). A dedicated top-level body field, never a context file.
+ */
+export interface SkillSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    resources: SkillResourceSpec[];
+}
+/**
+ * A tool server (MCP) to wire into the agent CLI for this run, with its transport and any
+ * credentials the backend resolved. Only the CLIs that speak MCP receive these; the backend has
+ * already dropped anything this harness cannot serve, so the harness never has to decide.
+ *
+ * The values here are SECRET-BEARING (`env` / `headers` carry resolved credentials), which is why
+ * the config files this module writes always live outside the checkout and are never logged.
+ */
+export interface McpServerSpec {
+    /** The server name the CLI exposes tools under (`mcp__<id>__<tool>`). Id-safe by construction. */
+    id: string;
+    transport: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    /** Bare tool names the agent may call. Absent ⇒ every tool the server exposes. */
+    allowedTools?: string[];
+    /**
+     * Which keys of `env` / `headers` hold a RESOLVED CREDENTIAL rather than declared configuration.
+     * {@link mcpServerSecretValues} reads exactly these for redaction — scrubbing the whole map
+     * instead would turn every later occurrence of an ordinary config string into `***`.
+     */
+    secretKeys?: string[];
+}
+/**
+ * The credential values carried by a run's tool servers, for {@link registerKnownSecrets}. An MCP
+ * server that fails to start routinely echoes its own argv or request headers into stderr, and
+ * that tail reaches the step's diagnostics — so these have to be scrubbed exactly like the leased
+ * subscription token. Only the keys the backend MARKED as secret are read (see `secretKeys`).
+ */
+export declare function mcpServerSecretValues(servers: readonly McpServerSpec[]): string[];
+/**
+ * Validate the optional `skills` field. Names are de-duplicated: two skills sharing a directory
+ * name would overwrite each other's `SKILL.md`, leaving the agent pointed at whichever landed
+ * last — so the first wins and the collision is dropped rather than silently mixing two playbooks.
+ */
+export declare function parseSkillSpecs(value: unknown): SkillSpec[] | undefined;
+/**
+ * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
+ *
+ * Kept byte-identical to kernel's `MCP_SERVER_ID_PATTERN` (the harness image is built from `src/`
+ * plus typescript alone, so it can carry no runtime dependency on a workspace package) and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts` — the same copy-plus-pin arrangement
+ * `src/host-markdown.ts` uses.
+ */
+export declare const MCP_SERVER_ID_PATTERN: RegExp;
+/**
+ * Whether an HTTP tool server's URL may be started. Mirrors kernel's `isAllowedMcpHttpUrl` (see
+ * {@link MCP_SERVER_ID_PATTERN} for why it is a copy, and the conformity suite that pins it):
+ * `https` anywhere, plain `http` only on loopback, since the headers carry a resolved credential.
+ * The backend refuses the same URLs at registration — this is the boundary check, so a body that
+ * reached the container by any other route is held to the rule too.
+ */
+export declare function isAllowedMcpHttpUrl(raw: string): boolean;
+/** Validate the optional `mcpServers` field, dropping malformed entries and duplicate ids. */
+export declare function parseMcpServerSpecs(value: unknown): McpServerSpec[] | undefined;
+/**
+ * The `--mcp-config` document Claude Code reads: `{ "mcpServers": { "<id>": {...} } }`. An `http`
+ * server declares `type: "http"` with its headers; a `stdio` one declares its command/args/env.
+ */
+export declare function claudeMcpConfig(servers: McpServerSpec[]): {
+    mcpServers: Record<string, Record<string, unknown>>;
+};
+/**
+ * The claude-code CLI's own tools, named so an `--allowedTools` list can never take them away.
+ *
+ * An allow-list is whole-session: it does not scope itself to MCP just because every entry we
+ * generate happens to be an `mcp__*` pattern. So the moment one tool server narrows its tools, the
+ * list has to re-grant the agent's built-in file/bash/search tools or the run is handed a narrowed
+ * MCP surface AND no way to read, edit or build anything.
+ *
+ * Bias this list toward OVER-inclusion. A name the CLI does not have is inert; a name it has and
+ * this list lacks is a tool silently removed from a run — which surfaces as an agent that cannot
+ * do its work, far from the registration that caused it. Historical/renamed spellings are kept for
+ * the same reason: the harness image is pinned per workspace, so one image faces several CLI
+ * versions. When the CLI gains a tool, add it here.
+ */
+export declare const CLAUDE_BUILT_IN_TOOLS: readonly string[];
+/**
+ * The tool-name list for `--allowedTools`: every declared server's tools in the CLI's
+ * `mcp__<server>__<tool>` convention, PLUS {@link CLAUDE_BUILT_IN_TOOLS}. A server with no
+ * restriction contributes the whole-server pattern, so an allow-list stays one entry per server.
+ *
+ * Returns undefined when NO server restricts its tools — there is then nothing to narrow, and the
+ * safest list is the one we never send.
+ *
+ * Whether the CLI ENFORCES this list is permission-mode dependent and not a contract we control:
+ * the run uses `--permission-mode bypassPermissions` (the container is the sandbox and no human is
+ * there to approve a call), under which an allow-list grants rather than gates. So this is written
+ * to be correct under BOTH readings — if the list gates, the narrowing is real and the built-ins
+ * survive it; if it is inert, sending it costs nothing. The always-present channel is the PROMPT,
+ * which states each server's permitted tool names on every harness. Treat `allowedTools` as
+ * scoping, not as a security boundary: a server the agent must not reach fully should not be
+ * wired for that kind at all.
+ */
+export declare function claudeAllowedToolPatterns(servers: McpServerSpec[]): string[] | undefined;
+/**
+ * The `[mcp_servers.<id>]` TOML block Codex reads from its `CODEX_HOME/config.toml`. Codex's MCP
+ * client is stdio-only, so an `http` server is skipped here — the backend states such a server as
+ * unavailable when it declares `harnesses: ['claude-code']`, and a deployment that wires an HTTP
+ * server for Codex gets a no-op rather than a malformed config.
+ */
+export declare function codexMcpConfigToml(servers: McpServerSpec[]): string;
+/**
+ * Write the Claude Code MCP config for this run and return its path, or undefined when there are
+ * no servers. The file is written into the caller's PER-RUN directory (an isolated config home, or
+ * an ambient job's own scratch dir) — never the checkout (it would land in a commit) and never a
+ * HOME-global path (a second concurrent job would clobber it, and it carries this job's credentials).
+ */
+export declare function writeClaudeMcpConfig(dir: string, servers: McpServerSpec[]): Promise<string | undefined>;

package/dist/agent-runner.d.ts

@@ -0,0 +1,114 @@
+import type { Logger } from './logger.js';
+import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress } from './pi.js';
+import { type McpServerSpec, type SkillSpec } from './agent-capabilities.js';
+import { type ProgressGuardLimits } from './progress-guard.js';
+import { type SliceReview } from './subagents.js';
+/** Which subscription harness to run (the Pi harness uses `runPi` directly). */
+export type SubscriptionHarness = 'claude-code' | 'codex';
+export interface SubscriptionRunOptions {
+    /** Prepared working directory (cloned/scaffolded by the caller). */
+    cwd: string;
+    /** Real vendor model id, e.g. `claude-opus-4-8` / `gpt-5.5-codex`. */
+    model: string;
+    /** Composed role + best-practice fragments, supplied as the system prompt. */
+    systemPrompt: string;
+    /** The concrete task prompt handed to the CLI over stdin. */
+    userPrompt: string;
+    /**
+     * The decrypted subscription credential: an OAuth token (claude) or auth.json blob
+     * (codex). Omitted when `ambientAuth` is set — the CLI uses the developer's own login.
+     */
+    subscriptionToken?: string;
+    /**
+     * Anthropic-compatible base URL for a non-Anthropic Claude-Code vendor (GLM/Kimi).
+     * Present ⇒ ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN; absent ⇒ CLAUDE_CODE_OAUTH_TOKEN.
+     */
+    subscriptionBaseUrl?: string;
+    /**
+     * Native local execution: run the developer's ALREADY-INSTALLED CLI with its OWN
+     * ambient login (`~/.claude` / `~/.codex`) — no leased credential, no isolated config
+     * home. Set ONLY by the local native transport (which runs the harness as a host
+     * process); a no-op everywhere else. The agent then runs with the user's personal
+     * subscription, unsandboxed, on their own machine — the explicit trade for skipping the
+     * container.
+     */
+    ambientAuth?: boolean;
+    /**
+     * The skills to install natively before launch. The claude-code runner writes each to
+     * `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md` (+ resource files) so the CLI loads them — but ONLY
+     * when it owns an isolated config home, i.e. NOT under `ambientAuth`. The codex runner ignores
+     * them outright. Every case that skips the native install reads the checkout's
+     * `.cat-context/skill/<name>/`, materialised by the caller.
+     */
+    skills?: SkillSpec[];
+    /**
+     * Tool servers (MCP) to wire into the CLI for this run. Written to a PER-RUN config the CLI is
+     * pointed at — never a HOME-global one, which a second concurrent job would clobber and which
+     * carries this job's credentials. Absent ⇒ the CLI's built-in tools only.
+     */
+    mcpServers?: McpServerSpec[];
+    /**
+     * Extra environment for the CLI child, scoped to this job (the tester's secrets, a
+     * private-registry npmrc pointer). Merged over the inherited `process.env` at spawn, so the
+     * agent and its shell tools see them without the harness mutating its OWN environment — which
+     * is shared by every concurrent job under the native host-process transport. See
+     * `RunOptions.agentEnv`.
+     */
+    extraEnv?: Record<string, string>;
+    /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
+    signal?: AbortSignal;
+    /**
+     * Fully-resolved no-progress guard limits (env defaults merged loosen-only with the kind's
+     * tuning + any complexity-scaled allowance). When set, the claude-code runner runs the SAME
+     * {@link ProgressGuard} as Pi over the CLI's tool stream and kills a run that has plainly
+     * stopped making progress (no-edit probing, error-retry loop, web rabbit-hole) rather than
+     * letting it burn the whole wall-clock budget. Omitted ⇒ the guard is disabled for this run
+     * (only the external watchdog bounds it), preserving the pre-guard behaviour.
+     */
+    guardLimits?: ProgressGuardLimits;
+    /** Whether this run is expected to edit files (false for assess-only runs); gates the no-edit bound. */
+    expectsEdits?: boolean;
+    /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
+    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
+     * 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.
+     */
+    log?: Logger;
+}
+/**
+ * Decide how the Claude Code runner carries the composed system prompt. Small prompts ride
+ * `--append-system-prompt` (a real system turn, cacheable) as before; a prompt too large for a
+ * single argv string is instead folded into the stdin task prompt (like the Codex runner), which
+ * has no size ceiling. Pure so the branch is unit-testable without spawning the CLI.
+ */
+export declare function carryClaudeSystemPrompt(systemPrompt: string, userPrompt: string): {
+    appendArgs: string[];
+    prompt: string;
+    folded: boolean;
+};
+export declare function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome>;
+/**
+ * Run the Codex CLI headlessly against `opts.cwd`, authenticated with the leased
+ * ChatGPT `auth.json` bundle written to an isolated CODEX_HOME, talking direct to
+ * the ChatGPT backend. Streams `codex exec --json`, mapping plan/todo updates onto
+ * subtask progress and the running cumulative token usage onto the outcome.
+ */
+export declare function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutcome>;
+/** Dispatch to the configured subscription harness runner. */
+export declare function runSubscriptionHarness(harness: SubscriptionHarness, opts: SubscriptionRunOptions): Promise<PiRunOutcome>;

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

@@ -0,0 +1,18 @@
+import type { AgentJob, AgentResult, McpServerSpec, SkillSpec } from './job.js';
+import type { EffortReport } from './effort.js';
+/**
+ * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
+ * onto its final result. Every container mode routes its result through this so the report reaches
+ * the backend uniformly. A run that wrote no report passes through unchanged.
+ */
+export declare function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult;
+/**
+ * The agent-capability fields (skills + tool servers) every agent-running flow forwards to
+ * {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow cannot silently
+ * be the one that drops a kind's declared playbook or tool server — the failure mode is invisible
+ * (the agent simply works without it) and would only show up as degraded output.
+ */
+export declare function agentCapabilities(job: AgentJob): {
+    skills?: SkillSpec[];
+    mcpServers?: McpServerSpec[];
+};

package/dist/agent.d.ts

@@ -0,0 +1,66 @@
+import type { AgentJob, AgentResult, TestSecretSpec } from './job.js';
+import { runCodingAgent } from './coding-agent.js';
+import type { RunOptions } from './runner.js';
+/**
+ * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
+ * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
+ * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
+ * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
+ * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
+ */
+export declare function buildInfraNotes(managed: {
+    note?: string;
+    serveUrl?: string;
+}): string[];
+/** Run one generic agent job end to end, dispatching on `mode`. */
+export declare function handleAgent(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
+/**
+ * Decide a preview stand-up's outcome from its result (pure, so the success/failure boundary
+ * is unit-tested without spawning a build). A preview must actually come up: unlike the tester's
+ * "test what you can" fallback, a stand-up that produced no reachable serve URL (failed build /
+ * server never bound) is a hard failure and its `note` becomes the failure reason. When the app
+ * is up but WireMock is not, the `note` rides along as a non-fatal warning.
+ */
+export declare function buildPreviewOutcome(standUp: {
+    serveUrl?: string;
+    note?: string;
+}): {
+    ok: true;
+    url: string;
+    note?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Build the env carrying the tester's sensitive secrets, so the agent's shell tools (spawned as
+ * child processes that inherit it) can read `$KEY` — the out-of-band delivery channel. Each value
+ * is registered for redaction so it can't leak into captured output/logs. Reserved/toolchain env
+ * names were already dropped at parse. No secrets ⇒ an empty env.
+ *
+ * Returned as EXPLICIT child env rather than written onto `process.env`: a process-global
+ * set/restore is only safe when the process runs one job, which the native host-process transport
+ * breaks (it serves every concurrent ambient job from one process). There, two overlapping tester
+ * runs would read each other's secrets, and whichever finished first would delete the other's
+ * mid-run. Scoping them to the spawn env makes the delivery correct under concurrency and drops
+ * the restore step entirely.
+ */
+export declare function testSecretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
+/**
+ * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
+ * peer repos or read-only reference repos). The post-commit validation command is only wired into
+ * the single-repo flow, so a multi-repo run would silently skip it and degenerate the loop into a
+ * one-shot with no completion gate — multi-repo ralph is out of scope for v1 (see
+ * backend/docs/ralph-loop.md), so {@link runCodingMode} fails loudly on this instead.
+ */
+export declare function ralphUnsupportedOnMultiRepo(job: Pick<AgentJob, 'validation' | 'peerRepos' | 'referenceRepos'>): boolean;
+/**
+ * Assemble the {@link runCodingAgent} spec for the ordinary single-repo coding flow. Extracted
+ * from {@link runSingleRepoCoding} so the many optional-field spreads don't inflate that
+ * function's cyclomatic complexity; the mapping is a straight field copy off `job`.
+ *
+ * Exported for the `opensPr` assertion: whether a dispatch fills the repo's PR template turns on
+ * this one spread, and the in-place fixers reach it through the SAME function as the implementer,
+ * so no structural guard can tell their cases apart.
+ */
+export declare function buildSingleRepoCodingSpec(job: AgentJob, pushBranch: string): Parameters<typeof runCodingAgent>[0];

package/dist/bootstrap-mode.d.ts

@@ -0,0 +1,20 @@
+import type { AgentJob, AgentResult } from './job.js';
+import type { RunOptions } from './runner.js';
+/**
+ * Repo-bootstrap coding flow (the bootstrapper): with a reference architecture, clone it →
+ * the agent adapts it in place per the instructions; without one (`fromScratch`), start from
+ * an empty directory → the agent scaffolds the new service. Either way the result's history
+ * is reset to a single commit and force-pushed to the SEPARATE, pre-created target repo's
+ * default branch. Diverges from the ordinary coding flow in pushing to a different repo with
+ * a reinitialised history rather than a work branch + PR on the cloned repo.
+ */
+export declare function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResult>;
+/**
+ * Whether the bootstrapper actually produced repository content, so a no-op run (the agent
+ * never reached the model / never wrote anything) is failed rather than force-pushed as an
+ * empty repo. With a reference architecture, "produced content" means the agent changed the
+ * clone; scaffolding from scratch, it means at least one file now exists in the working
+ * directory. (The harness writes its prompt context to Pi's global `~/.pi/agent/AGENTS.md`,
+ * never into `dir`, so nothing here needs to be filtered out as harness boilerplate.)
+ */
+export declare function producedRepoContent(dir: string, hasReference: boolean, signal?: AbortSignal): Promise<boolean>;

package/dist/captured-command.d.ts

@@ -0,0 +1,58 @@
+import type { RunOptions } from './runner.js';
+import type { Logger } from './logger.js';
+/** What one harness-spawned command did, as both phases record it. */
+export interface CapturedCommandResult {
+    /** Exit code (0 = pass); 124 on watchdog timeout, 127 on spawn failure, 130 on abort. */
+    exitCode: number;
+    passed: boolean;
+    /** Scrubbed output bounded to the caller's REPORT budget (what crosses the wire). */
+    outputTail?: string;
+    durationMs: number;
+    timedOut?: boolean;
+    /**
+     * The FULL scrubbed tail (up to {@link MAX_CAPTURED_OUTPUT_CHARS}) for a repair prompt. Never
+     * leaves the container — the agent needs the whole failure to act on it, the wire does not.
+     */
+    fullTail?: string;
+}
+/**
+ * Run ONE command as `sh -c` in `cwd`, capturing a bounded, secret-scrubbed tail of its combined
+ * stdout+stderr. The exit code is the verdict — computed here by the harness, never self-reported
+ * by the model, which is the whole point of a programmatic phase. A watchdog kills the process
+ * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
+ * from settling.
+ *
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * not a mutated global: the harness spawns this itself rather than through the agent, so without
+ * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
+ * had this been staged in `process.env`, against a sibling job's state).
+ *
+ * `logLabel`/`logFields` shape only the two warnings this runner emits itself (the watchdog kill
+ * and a spawn failure); the caller keeps its own start/finish logging, which knows what the
+ * command MEANS.
+ */
+export declare function runCapturedCommand(args: {
+    cwd: string;
+    command: string;
+    timeoutMs: number;
+    /** Bound for {@link CapturedCommandResult.outputTail} — the caller's per-report budget. */
+    reportTailChars: number;
+    logLabel: string;
+    logFields?: Record<string, unknown>;
+    logger: Logger;
+    opts: RunOptions;
+}): Promise<CapturedCommandResult>;
+/**
+ * Wrap captured command output in a fenced block that the output itself cannot break out of.
+ *
+ * Every consumer of a captured tail embeds it in markdown a MODEL then reads — a repair prompt,
+ * the dependency-install note — and a package manager legitimately prints backticks (a linter
+ * quoting a template literal, a test echoing a fenced snippet from a fixture). A fixed three-tick
+ * fence closes on the first such run, and everything after it reads as prose: the remaining
+ * output, and worse, the INSTRUCTIONS that follow the block. Sizing the fence one tick longer than
+ * the longest run in the body is what CommonMark specifies for exactly this, so the block always
+ * spans the whole tail.
+ */
+export declare function fencedOutput(text: string): string;
+/** Bound an already-scrubbed output tail to what a REPORT carries, saying what it dropped. */
+export declare function boundTail(scrubbed: string, maxChars: number): string;

package/dist/claude-call-aggregator.d.ts

@@ -0,0 +1,164 @@
+import type { HarnessCallMetric } from './pi.js';
+/** One model call, assembled from every stream envelope that carried a piece of it. */
+export interface AggregatedClaudeCall {
+    model?: string;
+    /** Every content block of the response, in arrival order. */
+    content: unknown[];
+    text: string;
+    reasoning: string;
+    stopReason: string | null;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    /** The `user` turns carrying this call's tool_result blocks, in arrival order. */
+    toolResults: unknown[][];
+    /** tool_use blocks across the whole response (the run's `stats.toolCalls` term). */
+    toolUses: number;
+}
+export interface ClaudeCallAggregator {
+    /**
+     * Fold one `assistant` envelope in. A new `message.id` completes the call in flight first, so
+     * `onCallStart` for the new call always runs after `onCall` for the previous one.
+     */
+    onAssistant(message: Record<string, unknown>): void;
+    /** Buffer a `user` turn's content against the call in flight (dropped when none is). */
+    onToolResult(content: unknown[]): void;
+    /** Complete the call still in flight, if any. Call once the stream has ended. */
+    flush(): void;
+}
+/**
+ * Assemble per-call telemetry out of Claude Code's per-block stream envelopes.
+ *
+ * `onCallStart` fires when a call's FIRST envelope arrives, which is the moment the caller must
+ * snapshot the prompt: the history at that point is what produced the response. `onCall` fires
+ * once the call is complete (a different `message.id` began, or the stream ended).
+ *
+ * Usage is merged as the MAXIMUM of each bucket across the call's envelopes rather than the last
+ * one seen. The envelopes carry a snapshot of the same call's usage, and which of them holds the
+ * final output count is a CLI detail we should not depend on; a max is right whether the value is
+ * repeated verbatim or grows.
+ *
+ * An envelope with no `message.id` cannot be attributed, so it is treated as a call of its own —
+ * the pre-aggregation behaviour, kept so a CLI build (or a transcript) that omits the id degrades
+ * to over-counting rather than to silently merging unrelated calls.
+ */
+export declare function createClaudeCallAggregator(handlers: {
+    onCallStart?: () => void;
+    onCall: (call: AggregatedClaudeCall) => void;
+}): ClaudeCallAggregator;
+/** One turn of the reconstructed request transcript, in the proxy's chat-array shape. */
+interface TranscriptTurn {
+    role: string;
+    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 declare const MAX_TRANSCRIPT_CHARS: number;
+/** 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}). */
+    onAssistant(message: Record<string, unknown>): void;
+    /** Fold a `user` turn's tool_result content in, against the call in flight. */
+    onToolResult(content: unknown[]): void;
+    /** Publish the call still in flight. Idempotent; safe to call on both the clean and error path. */
+    flush(): void;
+}
+/**
+ * Assemble ONE conversation's per-call telemetry from the CLI stream: the growing request
+ * transcript and the per-call token/body metrics.
+ *
+ * Owns the transcript because the two are one concern — a call's `promptText` is the transcript as
+ * of that call, and its turns may only be appended once the call that produced them is complete.
+ * `seed` is what the harness supplied and the stream therefore never shows (the system + first user
+ * message, or the single folded user turn), so the reconstruction never claims a system turn that
+ * 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 — 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 declare function createClaudeStreamTelemetry(opts: ClaudeStreamTelemetryOptions): ClaudeStreamTelemetry;
+/** 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.
+ *
+ * Claude Code streams the turns of the subagents it dispatches onto the parent's stdout, tagged
+ * with the tool_use id that spawned them. Those same turns are also written to the per-session
+ * `subagents/*.jsonl` transcripts the watcher reads, so recording both channels counted every
+ * subagent call twice — and splicing them into the parent's message reconstruction produced a
+ * `promptText` chain that interleaves several conversations and therefore matches no real request.
+ *
+ * The id is what makes the fallback below possible: concurrent subagents interleave on one stdout,
+ * so it is the ONLY thing separating their conversations.
+ */
+export declare function subagentDispatchId(event: Record<string, unknown>): string | undefined;
+/** Whether a stream envelope describes a SUBAGENT's turn rather than the parent loop's. */
+export declare function isSubagentEvent(event: Record<string, unknown>): boolean;
+/** All per-call telemetry for ONE claude-code run: the parent loop, and whoever bills the subagents. */
+export interface ClaudeRunTelemetry {
+    /** Fold an `assistant` envelope in, routed by its dispatch tag (`undefined` ⇒ the parent loop). */
+    onAssistant(dispatchId: string | undefined, message: Record<string, unknown>): void;
+    /** Fold a `user` turn's tool_result content in, against the same conversation. */
+    onToolResult(dispatchId: string | undefined, content: unknown[]): void;
+    /** Publish every conversation's call in flight. Idempotent; safe on the clean and error paths. */
+    flush(): void;
+    /**
+     * Subagent turns crossed the stream AND the watcher was the channel meant to record them — so a
+     * watcher that captured nothing means this run's subagent rows are simply missing.
+     */
+    expectsWatcherCalls(): boolean;
+}
+/**
+ * Assemble a run's per-call telemetry, routing each envelope to the conversation it belongs to.
+ *
+ * The routing is the whole point. A subagent's turns ride the parent's stdout tagged with the
+ * dispatch that spawned them, and they must never join the PARENT's chain — that splice produced a
+ * `promptText` interleaving several conversations, matching no request that was ever sent.
+ *
+ * Who RECORDS them is a separate question, decided once per run rather than per event:
+ * `watcherOwnsSubagents` says a `subagents/*.jsonl` watcher will run, and it is the better source
+ * (it reads the settled transcript, so its usage and stop reason are final). With no watcher — an
+ * `ambientAuth` run has no isolated config home to watch — the tagged turns are recorded here
+ * 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 declare function createClaudeRunTelemetry(opts: ClaudeStreamTelemetryOptions & {
+    watcherOwnsSubagents: boolean;
+}): ClaudeRunTelemetry;
+export {};