@cat-factory/executor-harness 1.80.0 → 1.82.0

package/dist/runner.d.ts

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

package/dist/server.d.ts

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

package/dist/structured-output.d.ts

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

package/dist/subagents.d.ts

@@ -0,0 +1,88 @@
+import type { Logger } from './logger.js';
+import { type HarnessCallMetric, type TodoProgress } from './pi.js';
+/**
+ * How much of one slice's terminal report is kept. A slice review is prose (findings for a handful
+ * of files), not a transcript, so this is far above a real report while still bounding what a
+ * runaway subagent can push onto the step — the reports ride the job view on every poll and are
+ * persisted on the run.
+ */
+export declare const SLICE_REPORT_MAX_CHARS = 24000;
+/** One slice's live review, as published on the job view. Mirrors `prReviewSliceReviewSchema`. */
+export interface SliceReview {
+    label: string;
+    status: 'in_progress' | 'completed';
+    report?: string | null;
+}
+/** Tracks parallel subagents seen on the parent stream to derive slice progress. */
+export interface SliceTracker {
+    /** Feed an `assistant` message's content blocks: registers any subagent dispatches. */
+    onAssistant(content: unknown[]): void;
+    /**
+     * Feed a `user` message's content blocks: marks the paired subagent(s) complete AND captures
+     * each one's terminal report (see {@link SliceTracker.sliceReviews}).
+     */
+    onUser(content: unknown[]): void;
+    /**
+     * Every dispatched slice with its status and captured report, in dispatch order — the durable
+     * half of this tracker. Published as a whole value on each poll (NOT drain-on-read): the set
+     * only grows, and a dropped poll response must never permanently lose a finished slice's
+     * review, which is the entire point of capturing it. Empty when nothing was dispatched.
+     */
+    sliceReviews(): SliceReview[];
+    /** Whether any `Task` subagent has been dispatched (⇒ this run parallelised). */
+    hasSlices(): boolean;
+    /**
+     * Progress derived from the dispatched subagents (completed / in-flight / total),
+     * or undefined when none have been dispatched. Reconciled with the parent's own plan
+     * by `pickProgress` (./progress.ts) — it is NOT gated off by the presence of a plan
+     * (that gate was ADR 0027 Defect B: the pr-reviewer prompt writes the plan ONCE at
+     * grouping time and never marks it done, which used to permanently mask this signal).
+     */
+    progress(): TodoProgress | undefined;
+}
+/**
+ * @param secrets Leased-credential strings scrubbed from every captured report. A subagent can
+ *   echo a token it saw in the checkout, and these reports are persisted on the run, so they are
+ *   redacted on the way in rather than trusting each consumer to do it.
+ */
+export declare function createSliceTracker(secrets?: string[]): SliceTracker;
+export interface SubagentWatcherOptions {
+    /** Fed the heartbeat when a transcript grows, so the inactivity watchdog sees the run is alive. */
+    onActivity?: () => void;
+    /** Leased-credential strings to scrub from captured bodies (the transcripts can echo the token). */
+    secrets?: string[];
+    /** Fallback model id stamped on a subagent call whose transcript omits one. */
+    model?: string;
+    /**
+     * Streams each lifted subagent call to the live telemetry drain (the run's `RunOptions`
+     * hook). Subagent work is exactly where a long review spends most of its tokens, and it is
+     * the phase the parent stream goes quiet for — so without this a run killed mid-fan-out
+     * reports nothing at all.
+     */
+    onCallMetric?: (call: HarnessCallMetric) => void;
+    /** Poll cadence (ms); overridable for tests. */
+    intervalMs?: number;
+    log?: Logger;
+}
+export interface SubagentWatcher {
+    /** Do a final poll, then stop watching. Idempotent; never throws. */
+    stop(): Promise<void>;
+    /** Cumulative subagent usage lifted so far (input + output tokens). */
+    usage(): {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** The per-call telemetry rows lifted from the subagent transcripts so far. */
+    calls(): HarnessCallMetric[];
+}
+/**
+ * Start watching `root` (the CLI's `<configHome>/projects` tree) for subagent `*.jsonl`
+ * transcripts — any file under a `subagents/` directory beneath it (see
+ * {@link findSubagentTranscripts}) — tailing each file by byte offset. New content feeds
+ * `onActivity` (heartbeat) and each assistant turn carrying usage is lifted into a
+ * {@link HarnessCallMetric} + summed into the cumulative usage. Best-effort throughout: the
+ * tree may not exist yet (created lazily by the CLI), a file may be mid-write, and the
+ * line/usage shape may change across CLI versions — every such case is swallowed so the
+ * watcher can only ever ADD signal, never break the run.
+ */
+export declare function startSubagentWatcher(root: string, opts: SubagentWatcherOptions): SubagentWatcher;

package/dist/transcript-retention.d.ts

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

package/dist/validation-checks.d.ts

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