@cat-factory/executor-harness 1.80.0 → 1.84.0

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 {};

package/dist/claude-call-aggregator.js

@@ -77,6 +77,112 @@ export function createClaudeCallAggregator(handlers) {
         flush: complete,
     };
 }
+/**
+ * How much reconstructed transcript ONE conversation may retain.
+ *
+ * The stream feeds this without limit — a tool loop that reads large files grows the history by
+ * every one of them — and the reconstruction is held in the driver's own process. In the container
+ * that is a box sized for one job; in the BACKEND it is the orchestrator, where `streamCli` already
+ * refuses to retain the raw stream for exactly this reason (`harnessInline.ts` →
+ * `OUTPUT_TAIL_RETAIN_CHARS`: "a stalled tool-using run would otherwise park hundreds of MB in the
+ * orchestrator process — precisely on the runs worth diagnosing").
+ *
+ * 512 KiB because that is `LlmObservabilityService.MAX_BODY_CHARS`, the point past which the store
+ * truncates a body anyway: retaining more can only ever be thrown away. Deliberately NOT a
+ * per-deployment knob — it bounds a memory fault, and a number an operator can raise is one an
+ * operator can raise until the process dies.
+ */
+export const MAX_TRANSCRIPT_CHARS = 512 * 1024;
+/**
+ * The role a turn carries when it is not a turn at all, but the note saying what stopped being
+ * retained. A distinct namespaced role rather than `system`, so nothing downstream can read it as a
+ * message that was actually sent — the same reason `seed` exists.
+ */
+const ELIDED_ROLE = 'cat-factory:elided';
+/**
+ * Retain the transcript up to {@link MAX_TRANSCRIPT_CHARS} and then STOP, stating what it stopped
+ * retaining rather than silently ending mid-conversation.
+ *
+ * Freezing the tail (rather than evicting the head) keeps the seed and the early history — the
+ * task, and the turns that explain what the loop is doing — and keeps each call's `promptText` a
+ * stable PREFIX plus a changing note, so the backend's chain delta-compresses right up to the bound
+ * and only then degrades to storing the (now capped) array. Evicting the head would drop the task
+ * itself and break the prefix property from the first eviction on.
+ *
+ * The seed is never dropped: it is what the CALLER sent, so it is bounded by the caller's own
+ * prompt rather than by the stream, and it is the half a reader cannot reconstruct from anything
+ * else.
+ */
+function createBoundedTranscript(seed, secrets, maxChars) {
+    const turns = [...seed];
+    const sizeOf = (turn) => {
+        try {
+            return JSON.stringify(turn)?.length ?? 0;
+        }
+        catch {
+            // An un-serialisable turn cannot be retained at all, so charge it nothing and let the
+            // append below drop it on its own terms.
+            return Number.POSITIVE_INFINITY;
+        }
+    };
+    let retained = turns.reduce((n, turn) => n + sizeOf(turn), 0);
+    const dropped = { turns: 0, chars: 0 };
+    return {
+        append(turn) {
+            const size = sizeOf(turn);
+            if (retained + size > maxChars) {
+                dropped.turns += 1;
+                dropped.chars += Number.isFinite(size) ? size : 0;
+                return;
+            }
+            turns.push(turn);
+            retained += size;
+        },
+        snapshot() {
+            const encoded = dropped.turns
+                ? [
+                    ...turns,
+                    {
+                        role: ELIDED_ROLE,
+                        content: `${dropped.turns} later turn(s), ${dropped.chars} chars, were not retained: ` +
+                            `this conversation reached the ${maxChars}-char reconstruction bound`,
+                    },
+                ]
+                : turns;
+            return {
+                text: redactBody(safeSerialise(encoded), secrets),
+                messageCount: encoded.length,
+            };
+        },
+    };
+}
+/**
+ * Count the turns and assemble NO bodies — for a driver that has nowhere to put them (the backend
+ * with `LLM_RECORD_PROMPTS` off, where the store drops every body it is handed).
+ *
+ * `messageCount` stays real, because it is a COUNT rather than a body and every consumer of the
+ * metric wants it. The point is not to omit data the gate would keep; it is that serialising a
+ * transcript the gate is about to drop is pure cost, and the whole reason bodies travel to the
+ * recorder as thunks (`CLAUDE.md` → "Telemetry & agent-context observability").
+ */
+function createCountingTranscript(seed) {
+    let messageCount = seed.length;
+    return {
+        append() {
+            messageCount += 1;
+        },
+        snapshot: () => ({ text: '', messageCount }),
+    };
+}
+/** Serialise a transcript for the store, never throwing into the stream that produced it. */
+function safeSerialise(turns) {
+    try {
+        return JSON.stringify(turns) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Assemble ONE conversation's per-call telemetry from the CLI stream: the growing request
  * transcript and the per-call token/body metrics.
@@ -88,16 +194,20 @@ export function createClaudeCallAggregator(handlers) {
  * was not sent. A subagent's conversation seeds EMPTY — its prompt was minted by the CLI and never
  * crosses this stream — which is also why its first call carries `messageCount: 0` (the backend's
  * `latestChainTip` skips those on purpose: there is no re-sendable chain to delta against).
- * Bodies are credential-scrubbed; they can echo the leased token.
+ * Bodies are credential-scrubbed; they can echo the leased token — and assembled at all only when
+ * {@link ClaudeStreamTelemetryOptions.bodies} says a driver has somewhere to put them. The
+ * transcript is bounded either way ({@link MAX_TRANSCRIPT_CHARS}).
  *
  * Deliberately does NOT touch {@link PiRunStats}: the run's tool/output counters describe whether
  * the agent ACTED at all (`agentNeverActed`), which is true of a subagent's turns whichever channel
  * ends up owning their telemetry rows. The caller accumulates them off the raw stream instead.
  */
 export function createClaudeStreamTelemetry(opts) {
-    const messages = [...opts.seed];
-    let callPrompt = '';
-    let callMessageCount = 0;
+    const bodies = opts.bodies ?? true;
+    const transcript = bodies
+        ? createBoundedTranscript(opts.seed, opts.secrets, opts.maxTranscriptChars ?? MAX_TRANSCRIPT_CHARS)
+        : createCountingTranscript(opts.seed);
+    let sent = { text: '', messageCount: 0 };
     // The aggregator IS the surface: the transcript and metric work happens in its callbacks, so
     // there is nothing to wrap it in.
     return createClaudeCallAggregator({
@@ -105,16 +215,15 @@ export function createClaudeStreamTelemetry(opts) {
         // produced the response, and later envelopes of the same call must not see the turns it
         // went on to add.
         onCallStart: () => {
-            callPrompt = redactBody(JSON.stringify(messages), opts.secrets);
-            callMessageCount = messages.length;
+            sent = transcript.snapshot();
         },
         onCall: (call) => {
             opts.publish({
                 ...(call.model ? { model: call.model } : {}),
-                promptText: callPrompt,
-                messageCount: callMessageCount,
-                responseText: redactBody(call.text, opts.secrets),
-                reasoningText: redactBody(call.reasoning, opts.secrets),
+                promptText: sent.text,
+                messageCount: sent.messageCount,
+                responseText: bodies ? redactBody(call.text, opts.secrets) : '',
+                reasoningText: bodies ? redactBody(call.reasoning, opts.secrets) : '',
                 inputTokens: call.inputTokens,
                 cacheReadTokens: call.cacheReadTokens,
                 cacheWriteTokens: call.cacheWriteTokens,
@@ -123,9 +232,9 @@ export function createClaudeStreamTelemetry(opts) {
             });
             // Appended only now, so each call's prompt stays a strict prefix of the next and the
             // backend's telemetry chain delta-compresses cleanly.
-            messages.push({ role: 'assistant', content: call.content });
+            transcript.append({ role: 'assistant', content: call.content });
             for (const result of call.toolResults)
-                messages.push({ role: 'tool', content: result });
+                transcript.append({ role: 'tool', content: result });
         },
     });
 }
@@ -171,11 +280,8 @@ function createSubagentStreamTelemetry(opts) {
         let telemetry = perDispatch.get(dispatchId);
         if (!telemetry) {
             // Seeded EMPTY: the CLI minted this subagent's prompt and it never crossed the stream.
-            telemetry = createClaudeStreamTelemetry({
-                seed: [],
-                secrets: opts.secrets,
-                publish: opts.publish,
-            });
+            // Each dispatch gets its OWN retention bound, since each is its own conversation.
+            telemetry = createClaudeStreamTelemetry({ ...opts, seed: [] });
             perDispatch.set(dispatchId, telemetry);
         }
         return telemetry;

package/dist/claude-stream.d.ts

@@ -0,0 +1,56 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * The tool names the Claude Code CLI dispatches a parallel subagent under. `Agent` is what the
+ * shipped schema declares (`AgentInput` in `sdk-tools.d.ts`, carrying `description` / `prompt` /
+ * `subagent_type`); `Task` is the older name for the same dispatch. Both are matched because the
+ * harness runs against whatever CLI the image happens to bundle, and matching only the old name
+ * is what left a CLI 2.1.x pr-review reporting no slices at all.
+ *
+ * Note the asymmetry: keeping the legacy `Task` here is the one place a CLI rename could produce a
+ * FALSE signal rather than merely no signal — if a future build were to name a plain task-list
+ * tool `Task`, its writes would be counted as in-flight slices. We accept that because no shipped
+ * build does (the incremental plan tool is `TaskCreate`/`TaskUpdate`, tracked separately in
+ * `progress.ts`), and dropping legacy coverage is the more likely regression.
+ *
+ * Lives here rather than in `subagents.ts` because BOTH the slice tracker and the no-progress
+ * guard (`pi.ts`, which `subagents.ts` imports — so it cannot import back) must agree on what a
+ * subagent dispatch looks like.
+ */
+export declare const SUBAGENT_TOOL_NAMES: Set<string>;
+export declare function numberOf(value: unknown): number;
+/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
+export declare function redactBody(text: string, secrets: string[]): string;
+/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
+export declare function claudeAssistantContent(content: unknown[]): {
+    text: string;
+    reasoning: string;
+    toolUses: number;
+};
+/**
+ * The text a `tool_result` block carries. The CLI writes it either as a bare string or as an
+ * array of content blocks (the shape a subagent's terminal report arrives in), so both are read
+ * here rather than at each call site. Non-text blocks (an image a tool returned) contribute
+ * nothing. Returns '' when the block carries no readable text.
+ *
+ * This is what makes a parallel subagent's work observable to the harness at all: the parent
+ * stream shows a subagent's dispatch and its terminal `tool_result` and nothing in between, so
+ * this text is the ONLY place its findings surface outside its own untailed transcript.
+ */
+export declare function claudeToolResultText(block: Record<string, unknown>): string;
+/**
+ * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
+ * the cumulative `result` total).
+ *
+ * Anthropic reports all three input classes SEPARATELY and `input_tokens` is already
+ * exclusive of both caches, so the three fields here are orthogonal and additive:
+ * total input = `inputTokens + cacheReadTokens + cacheWriteTokens`. Do NOT re-lump the
+ * reads and the writes — a cache write costs 1.25–2× base input while a read costs ~0.1×,
+ * so a turn that keeps invalidating the prefix and one that rides a warm cache are
+ * indistinguishable once they are summed.
+ */
+export declare function claudeCallUsage(raw: unknown): {
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+};

package/dist/coding-agent.d.ts

@@ -0,0 +1,252 @@
+import type { AgentJob, AgentResult, HarnessAuthFields, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { HarnessCallMetric, PiRunStats } from './pi.js';
+import { type EffortReport } from './effort.js';
+import { type AgentPrDescription } from './pr-description.js';
+import type { ProgressGuardLimits } from './progress-guard.js';
+import type { RunOptions } from './runner.js';
+import { type Logger } from './logger.js';
+import { type ValidationChecksSpec, type ValidationReport } from './validation-checks.js';
+import { type ReproductionReport, type ReproductionSpec } from './reproduction-proof.js';
+import { type DependencyInstallSpec } from './dependency-install.js';
+/** What a coding agent run needs: where to clone, what to run, where to push. */
+export interface CodingAgentSpec extends HarnessAuthFields {
+    /** Short label for the temp dir + log lines (e.g. 'impl', 'ci-fix'). */
+    kind: string;
+    /** The job id, threaded into every log line for end-to-end tracing. */
+    jobId: string;
+    repo: RepoSpec;
+    /** Branch to clone and check out as the starting point. */
+    cloneBranch: string;
+    /** A fresh branch to create off the clone before running; omit to work directly on `cloneBranch`. */
+    newBranch?: string;
+    /** Branch the produced change is pushed to. */
+    pushBranch: string;
+    ghToken: string;
+    /** Composed role + best-practice fragments; written to Pi's global AGENTS.md context. */
+    systemPrompt: string;
+    /** The concrete task prompt handed to Pi. */
+    userPrompt: string;
+    model: string;
+    /** Commit message for any work the agent left uncommitted. */
+    commitMessage: string;
+    /** Per-kind web-search guidance (backend-composed); surfaced only when web search is on. */
+    webToolsGuidance?: string;
+    /** Enable proxy-backed web search for this run (see {@link AgentRunSpec.webSearchProxy}). */
+    webSearchProxy?: boolean;
+    /** Backend serves the phase-tagged completions route (see {@link AgentRunSpec.proxyPhasePath}). */
+    proxyPhasePath?: boolean;
+    /** Per-knob progress-guard overrides (loosen-only), set per agent kind by the backend. */
+    guardLimits?: Partial<ProgressGuardLimits>;
+    /**
+     * Reuse a stable per-repo checkout (clean-sweep + fetch + switch branch) instead of a
+     * fresh clone into a throwaway temp dir. Set only by the local warm-pool transport
+     * (its containers are reused across runs); absent everywhere else.
+     */
+    persistentCheckout?: boolean;
+    /**
+     * Tail the Coder's follow-up sentinel file ({@link FOLLOW_UPS_FILENAME}) and stream the
+     * forward-looking items it surfaces out on the job view (the Follow-up companion). Set
+     * only for the implementer (`coder`) dispatch; absent ⇒ no tailing (e.g. the CI-fixer).
+     */
+    streamFollowUps?: boolean;
+    /**
+     * Whether this dispatch OPENS a pull request (the caller passes `pr` to `openPullRequest`).
+     * Set, the harness looks for the repo's own pull-request template and asks the agent to fill it
+     * (see `pr-template.ts`). Absent for a dispatch that amends someone else's PR (the in-place
+     * fixers) — a template filled for a pull request nothing opens is wasted prompt and, worse,
+     * would have a CI-fixer rewrite the implementer's already-published description.
+     */
+    opensPr?: boolean;
+    /**
+     * READ-ONLY reference branches of THIS repo (the apriori-branches reference mode): fetched
+     * into `origin/<b>` after the checkout so the agent can inspect them but never commits to
+     * them. Best-effort per branch. Absent/empty ⇒ none fetched.
+     */
+    referenceBranches?: string[];
+    /**
+     * Ralph loop: run this programmatic completion command in the checkout AFTER the agent
+     * commits + pushes, capturing its exit code + a bounded output tail (the loop's exit
+     * condition — computed by the harness, never the model). Absent for every non-`ralph` run.
+     */
+    validation?: {
+        command: string;
+        iteration?: number;
+    };
+    /**
+     * PRE-PR VALIDATION: the service's configured check commands + repair-round budget. When set,
+     * the harness runs them against the checkout after the agent settles and, while they fail and
+     * budget remains, re-runs the agent with the captured output as its instruction. A red checkout
+     * at the end means the caller opens NO pull request and fails the job. Set only for a dispatch
+     * that opens a PR and whose service configured checks; absent everywhere else. See
+     * `docs/initiatives/pre-pr-validation.md`.
+     */
+    validationChecks?: ValidationChecksSpec;
+    /**
+     * DEPENDENCY PREPOPULATION: the service's install command, run against the checkout BEFORE the
+     * agent's first turn so it works against a tree whose dependencies are present. Best-effort —
+     * a failure becomes a note in the agent's prompt, never a failed run. Absent ⇒ no install
+     * phase. See `docs/initiatives/agent-dependency-prepopulation.md`.
+     */
+    dependencyInstall?: DependencyInstallSpec;
+    /**
+     * BUGFIX REPRODUCTION PROOF: the run's declared reproduction command + test files. When set, the
+     * harness runs that command against the pre-fix tree AND the tree the PR will open from, feeding
+     * a failed verification back to the agent while budget remains, and attaches the verdict to the
+     * outcome. Unlike {@link validationChecks} it NEVER gates the pull request — an unproven
+     * reproduction is weak evidence, which is a reviewer's call, not a machine's. Set only for a
+     * dispatch that opens a PR and whose run carries a declaration. See
+     * `docs/initiatives/bugfix-reproduction-proof.md`.
+     */
+    reproduction?: ReproductionSpec;
+    /**
+     * The skills to make available for this run — a `skill` step's pick and/or the running kind's
+     * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them
+     * harness-aware: natively under the ISOLATED `CLAUDE_CONFIG_DIR` for a leased-credential
+     * claude-code run, `.cat-context/skill/<name>/` for everything else (Pi, codex, and ambient
+     * claude-code, which has no isolated config dir). Absent ⇒ no skills.
+     */
+    skills?: SkillSpec[];
+    /**
+     * Tool servers (MCP) to wire into the agent CLI for this run. Forwarded verbatim — the backend
+     * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
+     */
+    mcpServers?: McpServerSpec[];
+}
+/** The outcome of a coding agent run, before each caller maps it to its own result shape. */
+export interface CodingAgentOutcome {
+    /** Whether the branch carries work and was therefore pushed (new commits, or resumed prior work). */
+    pushed: boolean;
+    /** Whether the run resumed an existing remote branch (prior work already pushed). */
+    resumed: boolean;
+    summary: string;
+    stats: PiRunStats;
+    stderrTail?: string;
+    /** Token usage from a subscription harness's CLI stream (absent for Pi). */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Per-model-call telemetry from a subscription harness's CLI stream (absent for Pi). */
+    callMetrics?: HarnessCallMetric[];
+    /** The agent's effort self-assessment, lifted from its sentinel file (absent when it wrote none). */
+    effortReport?: EffortReport;
+    /**
+     * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
+     * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+     * absent means the fallback text, unchanged.
+     */
+    prDescription?: AgentPrDescription;
+    /**
+     * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
+     * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
+     * was set. The exit code is the loop's authoritative completion signal.
+     */
+    validation?: {
+        validationPassed: boolean;
+        exitCode: number;
+        validationOutputTail?: string;
+        iteration?: number;
+        /** The work-branch HEAD the command was judged against (absent when it could not be read). */
+        headSha?: string;
+    };
+    /**
+     * The pre-PR validation loop's LAST attempt (present only when {@link CodingAgentSpec.validationChecks}
+     * was set). `passed: false` means the attempt budget was spent with the checkout still red —
+     * the caller must open no PR and fail the job with this as the evidence.
+     */
+    validationReport?: ValidationReport;
+    /**
+     * The bugfix reproduction proof's LAST attempt (present only when
+     * {@link CodingAgentSpec.reproduction} was set). Evidence, never a gate: `inconclusive` is
+     * attached to a perfectly successful run and the PR still opens.
+     */
+    reproductionReport?: ReproductionReport;
+}
+export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions): Promise<CodingAgentOutcome>;
+/**
+ * The Ralph-loop validation watchdog: the longest a completion command may run before it is
+ * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).
+ * Overridable via env for tests; defaults to 15 minutes.
+ */
+export declare function ralphValidationTimeoutMs(): number;
+/**
+ * How often the Ralph validation feeds the run's inactivity watchdog while its command runs.
+ * The command is exactly the activity-SILENT kind — a full `pnpm test`, a cold install-then-build
+ * — and the harness spawns it ITSELF rather than through the agent, so it emits no activity
+ * events of its own. `JOB_INACTIVITY_MS` (default 10 min) is TIGHTER than the command's own
+ * watchdog ({@link ralphValidationTimeoutMs}, default 15 min), so without this heartbeat any
+ * validation running past 10 minutes aborted the whole iteration as "inactivity" — mislabelling
+ * a healthy test suite as a wedge, and making the 15-minute watchdog unreachable at stock
+ * settings. The two sibling harness-run phases (pre-PR validation, reproduction proof) have
+ * always fed it; this one did not. Overridable via env for tests.
+ */
+export declare function ralphHeartbeatMs(): number;
+/**
+ * Bound on the validation output tail that crosses the wire. Deliberately smaller than
+ * `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`) and equal to the two sibling phases' budgets, for
+ * the same reason: this tail is persisted on the step (and on EVERY iteration of the attempt
+ * log) inside the run's `detail` JSON blob, which is re-serialized on every step-progress write.
+ */
+export declare const RALPH_VALIDATION_TAIL_CHARS = 4000;
+/**
+ * Ralph loop: run the programmatic completion command in the checkout and return its exit
+ * code, a bounded + redacted tail of its output, and the work branch's HEAD it ran against.
+ * The EXIT CODE is the loop's authoritative done signal (0 = the criterion is met) — computed
+ * here by the harness, never self-reported by the model, which is the whole point of a
+ * programmatic exit condition. The command runs INSIDE the sandboxed run container (the same
+ * trust boundary as the coding agent) — there is no host/backend execution.
+ *
+ * The spawn itself goes through {@link runCapturedCommand}, the ONE seam for a harness-run
+ * command, rather than the near-verbatim copy this used to be. That copy had drifted in two
+ * ways the seam exists to prevent: it scrubbed secrets AFTER the rolling truncation with no
+ * margin (so a credential straddling the cut lost its `KEY=` prefix and survived redaction as
+ * an unrecognised partial, on a tail that reaches the step, the notification and the SPA), and
+ * it published the full 16k capture where both siblings deliberately bound the wire tail.
+ *
+ * `headSha` is what lets the engine tell a loop that is iterating from one that is merely
+ * repeating: two consecutive failing iterations against an unchanged head means the agent
+ * committed nothing, and the loop is ended early instead of spending the rest of its budget.
+ * Best-effort — a head that cannot be read is simply omitted, and the engine's check fails open.
+ */
+export declare function runRalphValidation(repoDir: string, cwd: string, validation: {
+    command: string;
+    iteration?: number;
+}, logger: Logger, opts: RunOptions): Promise<{
+    validationPassed: boolean;
+    exitCode: number;
+    validationOutputTail?: string;
+    iteration?: number;
+    headSha?: string;
+}>;
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export declare function safeDirSegment(value: string): string;
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
+ * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
+ * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
+ * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
+ * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
+ * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
+ * independently, so a divergent rule would point the agent at a directory that does not exist.
+ */
+export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;
+/**
+ * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
+ * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
+ * that root (so it makes the cross-service change coherently across all of them), then commit +
+ * push each repo that actually changed and open one PR per dirty repo. The task's own-service PR
+ * is reported as `prUrl`/`branch`; the peer PRs as `peerPullRequests`.
+ *
+ * Deliberately simpler than the single-repo {@link runCodingAgent} for the first cut: NO mid-run
+ * checkpoint pushes (an evicted multi-repo run re-clones on retry — the deterministic work branch
+ * still lets it resume any commits it managed to push at the end), NO warm-pool persistent
+ * checkout (always ephemeral), and NO follow-up sentinel streaming. It reuses the SAME dir-scoped
+ * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
+ */
+export declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
+/**
+ * The "no changes" reason both coding agents report: a caller-supplied lead phrase
+ * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.
+ */
+export declare function noChangesReason(lead: string, stats: PiRunStats, stderrTail: string | undefined): string;