@cat-factory/executor-harness 1.80.0 → 1.84.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

@@ -326,6 +326,52 @@ async function setUpClaudeMcp(servers, configHome) {
         cleanup,
     };
 }
+/**
+ * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
+ * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
+ * the assistant turn (`rememberTool`) and hands the following user turn's content to `feedGuard`,
+ * which pairs each `tool_result`'s `is_error` with that name. The FIRST reason trips it: the
+ * diagnostic is recorded (readable via `reason()`, which the catch surfaces over the generic abort
+ * message) and `guardAbort` fires — folded into streamCli's signal so a tripped guard kills the CLI
+ * the same way the external watchdog does. Disabled when the caller supplies no limits (only the
+ * external watchdog then bounds the run).
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function createClaudeProgressGuard(opts) {
+    const guard = opts.guardLimits
+        ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
+        : undefined;
+    const toolNames = new Map();
+    const guardAbort = new AbortController();
+    let guardReason;
+    const feedGuard = (content) => {
+        if (!guard || guardReason)
+            return;
+        for (const block of content) {
+            if (!isObject(block) || block.type !== 'tool_result')
+                continue;
+            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+            const name = id ? toolNames.get(id) : undefined;
+            if (id)
+                toolNames.delete(id);
+            if (!name)
+                continue;
+            const reason = guard.observeSignal({ name, isError: block.is_error === true });
+            if (reason) {
+                guardReason = reason;
+                guardAbort.abort();
+                return;
+            }
+        }
+    };
+    return {
+        rememberTool: (id, name) => toolNames.set(id, name),
+        feedGuard,
+        guardAbort,
+        reason: () => guardReason,
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -411,37 +457,8 @@ export async function runClaudeCode(opts) {
     // `tool_use` id to feed the guard a {name,isError} signal. A tripped guard aborts the CLI via
     // `guardAbort` (folded into streamCli's signal below) and the run then fails with its
     // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
-    const guard = opts.guardLimits
-        ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
-        : undefined;
-    const toolNames = new Map();
-    const guardAbort = new AbortController();
-    let guardReason;
-    // Feed a user turn's settled tool calls to the guard, pairing each `tool_result`'s `is_error`
-    // with the name captured for its `tool_use` id on the assistant turn. The FIRST reason trips
-    // it: record the diagnostic and abort the CLI (streamCli's close handler rejects; the catch
-    // below surfaces `guardReason` over the generic abort message). A standalone closure so the
-    // per-block loop doesn't nest onEvent past the readable-depth limit.
-    const feedGuard = (content) => {
-        if (!guard || guardReason)
-            return;
-        for (const block of content) {
-            if (!isObject(block) || block.type !== 'tool_result')
-                continue;
-            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
-            const name = id ? toolNames.get(id) : undefined;
-            if (id)
-                toolNames.delete(id);
-            if (!name)
-                continue;
-            const reason = guard.observeSignal({ name, isError: block.is_error === true });
-            if (reason) {
-                guardReason = reason;
-                guardAbort.abort();
-                return;
-            }
-        }
-    };
+    const progressGuard = createClaudeProgressGuard(opts);
+    const { rememberTool, feedGuard, guardAbort } = progressGuard;
     const onEvent = (event, meta) => {
         const type = event.type;
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
@@ -463,7 +480,7 @@ export async function runClaudeCode(opts) {
                 // Remember each call's name against its id so the guard can pair it with the
                 // `is_error` its `tool_result` carries on the next `user` turn.
                 if (typeof block.id === 'string' && typeof block.name === 'string') {
-                    toolNames.set(block.id, block.name);
+                    rememberTool(block.id, block.name);
                 }
                 if (block.name === 'TodoWrite') {
                     const progress = todosToProgress(block.input?.todos);
@@ -571,6 +588,7 @@ export async function runClaudeCode(opts) {
         // report is appended after them when the CLI managed to emit one before it was killed, which
         // is uncommon but is the same evidence a bad exit now carries — a guard trip is no reason to
         // discard it.
+        const guardReason = progressGuard.reason();
         if (guardReason) {
             const tail = err?.stderrTail;
             const report = capReport(redact(terminalReport, secrets).trim());

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;