@cat-factory/executor-harness 1.56.0 → 1.60.0

package/README.md

@@ -63,9 +63,17 @@ The implementation job (`POST /run`) is the canonical sequence:
    configured check commands (install/lint/test/build) run with `sh -c` in the checkout, and
    while they fail and the attempt budget remains the agent is re-run with the captured output
    as its instruction (see [pre-PR validation](../../../docs/initiatives/pre-pr-validation.md)),
-5. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
+5. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
+   run against the pre-fix tree and the tree the PR will open from, in two freshly-created
+   symmetric `git worktree` checkouts, and only red-then-green is reported as proof (see
+   [bugfix reproduction proof](../../../docs/initiatives/bugfix-reproduction-proof.md)). Unlike
+   step 4 this NEVER gates the PR: a failed verification is fed back to the agent while budget
+   remains, then recorded as `inconclusive`. It runs BEFORE step 4 so validation stays the last
+   thing to touch the tree,
+6. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
    ONLY if step 4 ended green. A spent budget returns an error result with the validation report
-   and opens no PR. Absent `validationChecks`, step 4 does not happen at all.
+   and opens no PR. Absent `validationChecks` / `reproduction`, steps 4 and 5 do not happen at
+   all.
 
 Bootstrap differs at the ends — it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
@@ -133,7 +141,9 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `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/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/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic — keyed off the job body, never the agent kind. |
+| `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic — keyed off the job body, never the agent kind. |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 
 ## Runner lifecycle knobs
@@ -147,6 +157,9 @@ runner):
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
 | `VALIDATION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a pre-PR validation check; a timeout counts as a failure (exit 124) so one hung command can't wedge the loop. |
+| `REPRODUCTION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a reproduction-proof setup or check command; a timeout counts as a failure (exit 124). |
+| `REPRODUCTION_HEARTBEAT_MS` | `30000` (30s) | How often the reproduction proof feeds the job inactivity watchdog while it runs commands the agent is not producing output for. |
+| `REPRODUCTION_TOTAL_BUDGET_MS` | `2700000` (45m) | Wall-clock ceiling on the WHOLE proof phase (every attempt, both trees, setup included). Attempts multiply two full tree runs each and the heartbeat above deliberately stops the inactivity watchdog from firing, so this is what bounds the phase. Checked at phase boundaries; exceeding it settles `inconclusive`, never a run failure. |
 | `HARNESS_TRANSCRIPT_TTL_MS` | `259200000` (3d) | How long lifted subscription-CLI session transcripts are kept before the retention sweep prunes them. |
 | `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content — though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
 

package/dist/agent.js

@@ -808,6 +808,10 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
         // Forwarded straight off the job body — the loop is generic machinery keyed on the data, not
         // on the agent kind.
         ...(job.validationChecks ? { validationChecks: job.validationChecks } : {}),
+        // Bugfix reproduction proof: the declared command run against the pre-fix and final trees
+        // (see docs/initiatives/bugfix-reproduction-proof.md). Forwarded straight off the job body —
+        // like the checks above, the loop is generic machinery keyed on the data, not the agent kind.
+        ...(job.reproduction ? { reproduction: job.reproduction } : {}),
     };
 }
 /**
@@ -818,16 +822,20 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, effortReport, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
     // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
     // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
     const ralphVerdict = validation ? { ralphVerdict: validation } : {};
     // The agent's effort self-assessment, spread onto every result path below (mirrors ralphVerdict).
     const effort = effortReport ? { effortReport } : {};
-    // The pre-PR validation report, spread onto every result path below: on the passing path it is
-    // the captured proof the checkout was green when the PR opened; on the exhausted path it is the
-    // evidence behind the failure below. Absent when the service configured no checks.
-    const validationFields = validationReport ? { validationReport } : {};
+    // The two PRE-PR VERIFICATION reports, spread onto every result path below. The validation one:
+    // on the passing path it is the captured proof the checkout was green when the PR opened; on the
+    // exhausted path it is the evidence behind the failure below. The reproduction one is evidence
+    // on every path — it never gates the PR. Each is absent when its phase was not configured.
+    const verificationFields = {
+        ...(validationReport ? { validationReport } : {}),
+        ...(reproductionReport ? { reproductionReport } : {}),
+    };
     // Pre-PR validation spent its attempt budget with the checkout still red. FAIL the job — do
     // NOT open a pull request, and do not pretend the push succeeded as a deliverable. The work is
     // still on the branch (a retry resumes on it); the report carries each failing command's exit
@@ -846,7 +854,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'agent',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -861,7 +869,7 @@ async function runSingleRepoCoding(job, opts) {
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...ralphVerdict,
-                ...validationFields,
+                ...verificationFields,
                 ...effort,
             };
         }
@@ -874,7 +882,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'no-changes',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -908,7 +916,7 @@ async function runSingleRepoCoding(job, opts) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
-                    ...validationFields,
+                    ...verificationFields,
                     ...effort,
                 };
             }
@@ -921,7 +929,7 @@ async function runSingleRepoCoding(job, opts) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
-                ...validationFields,
+                ...verificationFields,
                 ...effort,
             };
         }
@@ -934,7 +942,7 @@ async function runSingleRepoCoding(job, opts) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...ralphVerdict,
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -946,7 +954,7 @@ async function runSingleRepoCoding(job, opts) {
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
-        ...validationFields,
+        ...verificationFields,
         ...effort,
     };
 }

package/dist/captured-command.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { killChildProcess, spawnDetached } from './process.js';
+import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
+// The ONE way the harness runs a declared shell command on its own behalf (rather than through
+// the agent) and keeps a bounded, secret-scrubbed record of what it printed.
+//
+// Both pre-PR verification phases need exactly this — the PRE-PR VALIDATION checks
+// (`validation-checks.ts`) and the BUGFIX REPRODUCTION PROOF (`reproduction-proof.ts`) — and they
+// need it to behave IDENTICALLY: same watchdog semantics, same abort handling, same conventional
+// exit codes, same scrub-then-bound pipeline. They were two near-verbatim copies; a fix applied to
+// one of them (a redaction ordering, an exit-code convention) silently missed the other, which is
+// the whole reason this seam exists.
+//
+// Everything is PER-JOB by construction: the command, the cwd and the environment all arrive as
+// arguments and nothing is read from or written to `process.env`/`HOME`. The local NATIVE
+// transport serves every concurrent job from ONE host process, so a global would leak one job's
+// state into a sibling's — and the container path would never catch it.
+/**
+ * A little slack kept in the rolling capture buffer ON TOP of {@link MAX_CAPTURED_OUTPUT_CHARS},
+ * so scrubbing sees whole secrets.
+ *
+ * The buffer discards from the FRONT as output arrives, and `redactSecrets` only runs once the
+ * command settles. Without the margin a token straddling that rolling cut would already have lost
+ * its `KEY=` prefix by scrub time and would survive as an unrecognised partial. Capturing a bit
+ * more than we keep, scrubbing, and only THEN bounding to the real limit closes that window; 512
+ * chars comfortably exceeds any single credential assignment the rules match.
+ */
+const CAPTURE_MARGIN_CHARS = 512;
+/**
+ * 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 async function runCapturedCommand(args) {
+    const { cwd, command, timeoutMs, reportTailChars, logLabel, logFields, logger, opts } = args;
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let out = '';
+        let settled = false;
+        let timedOut = false;
+        const child = spawn('sh', ['-c', command], {
+            cwd,
+            detached: spawnDetached,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...opts.agentEnv },
+        });
+        // Keep only the tail (plus the scrub margin); guard against unbounded buffering on a chatty
+        // command.
+        const capture = (chunk) => {
+            out = (out + chunk.toString('utf8')).slice(-(MAX_CAPTURED_OUTPUT_CHARS + CAPTURE_MARGIN_CHARS));
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+            const trimmed = out.trim();
+            // Scrub BEFORE either bound: the pattern rules need a whole assignment to match, so the
+            // margin above is trimmed away only once the secrets are already gone.
+            const scrubbed = trimmed ? redactSecrets(trimmed).slice(-MAX_CAPTURED_OUTPUT_CHARS) : '';
+            resolve({
+                exitCode,
+                passed: exitCode === 0,
+                ...(scrubbed ? { outputTail: boundTail(scrubbed, reportTailChars) } : {}),
+                durationMs: Date.now() - startedAt,
+                ...(timedOut ? { timedOut: true } : {}),
+                ...(scrubbed ? { fullTail: scrubbed } : {}),
+            });
+        };
+        const timer = setTimeout(() => {
+            logger.warn(`${logLabel}: command timed out`, { ...logFields, timeoutMs });
+            timedOut = true;
+            killChildProcess(child, undefined, logger);
+            finish(124); // conventional timeout exit code (a non-zero fail)
+        }, timeoutMs);
+        timer.unref?.();
+        const onAbort = () => {
+            killChildProcess(child, undefined, logger);
+            finish(130); // aborted (a non-zero fail)
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (err) => {
+            logger.warn(`${logLabel}: command failed to spawn`, {
+                ...logFields,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            finish(127); // spawn error / command not found (a non-zero fail)
+        });
+        child.on('close', (code) => finish(code ?? 1));
+    });
+}
+/** Bound an already-scrubbed output tail to what a REPORT carries, saying what it dropped. */
+export function boundTail(scrubbed, maxChars) {
+    if (scrubbed.length <= maxChars)
+        return scrubbed;
+    const trimmed = scrubbed.length - maxChars;
+    return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-maxChars)}`;
+}

package/dist/coding-agent.js

@@ -3,12 +3,13 @@ import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { killChildProcess, spawnDetached } from './process.js';
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
-import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
+import { runReproductionLoop, } from './reproduction-proof.js';
 /**
  * How often the harness checkpoints the agent's work mid-run by pushing the branch.
  * A per-run container can be evicted at any moment; pushing the agent's commits
@@ -154,6 +155,55 @@ export async function runCodingAgent(spec, opts = {}) {
             opts.onPhase?.('agent');
             logger.info('coding-agent: running agent', { serviceDirectory });
             let agentRun = await runAgentPass(spec.userPrompt);
+            const foldPass = (run) => {
+                agentRun = mergeAgentPasses(agentRun, run);
+            };
+            // The new files the agent left unadded, folded into either loop's repair prompt. Both
+            // loops judge state the push will NOT carry unless it is committed — the checks run
+            // against the working tree, the proof against committed trees — so an unadded file is
+            // exactly the thing to name. A throw degrades to "no warning" inside each loop.
+            const listUncommittedNewFiles = () => listUntrackedFiles(workDir, opts.signal);
+            // BUGFIX REPRODUCTION PROOF: run the run's declared reproduction command against the
+            // pre-fix tree and the tree the PR will open from, and record whether it was red then
+            // green. Runs BEFORE the validation loop below, deliberately: validation is the GATE
+            // ("only a green checkout opens a PR"), so it has to stay the last thing that touches the
+            // tree — otherwise a reproduction repair round could leave the checkout red behind it and
+            // the PR would open anyway. Keyed purely off the job body carrying a spec (no agent-kind
+            // switch); absent ⇒ a no-op and the flow below is byte-for-byte what it was.
+            const reproduction = spec.reproduction;
+            let reproductionReport;
+            if (reproduction && (await producedWork(dir, spec, baseSha, resumed, opts))) {
+                opts.onPhase?.('reproduction');
+                reproductionReport = await runReproductionLoop({
+                    dir,
+                    baseSha,
+                    // Re-read per attempt: a repair pass commits, so the final tree moves under the loop.
+                    // `producedWork` has already committed forgotten tracked edits, and each repair round
+                    // re-commits before the next read.
+                    resolveFinalSha: async () => {
+                        await commitTrackedEdits(dir, spec.commitMessage, signal);
+                        return headCommit(dir, signal);
+                    },
+                    ...(serviceDirectory ? { serviceDirectory } : {}),
+                    spec: reproduction,
+                    logger,
+                    opts,
+                    runAgentPass,
+                    onAgentPass: foldPass,
+                    listUncommittedNewFiles,
+                    // Only a RESUMED run can have a pre-fix tree that already carries work: a fresh run
+                    // branched off base, so `baseSha` IS base. Wiring the probe unconditionally would buy
+                    // an always-empty answer for the price of a fetch — and a fresh clone is shallow, so
+                    // it could not resolve a merge base to answer with anyway. Lazy inside the loop: it
+                    // only runs if a tree comes back green.
+                    ...(resumed
+                        ? {
+                            listBaseTreeChanges: () => changedFilesSinceBase(dir, spec.repo.baseBranch, spec.ghToken, baseSha, opts.signal),
+                        }
+                        : {}),
+                });
+                opts.onPhase?.('agent');
+            }
             // PRE-PR VALIDATION: run the service's configured checks against the checkout and, while
             // they fail and budget remains, hand the captured output back to the agent and run it
             // again. Sits BETWEEN the agent and the finalize/push/PR step so a red checkout never
@@ -169,17 +219,16 @@ export async function runCodingAgent(spec, opts = {}) {
                     logger,
                     opts,
                     runAgentPass,
-                    onAgentPass: (run) => {
-                        agentRun = mergeAgentPasses(agentRun, run);
-                    },
+                    onAgentPass: foldPass,
                     // The checks run against the WORKING TREE, but only tracked edits are staged for the
                     // push — so a repair round can go green on a new file the PR would never contain.
                     // Name those files in the next repair prompt so the agent adds them.
-                    listUncommittedNewFiles: () => listUntrackedFiles(workDir, opts.signal),
+                    listUncommittedNewFiles,
                 });
             }
             outcome = await finalizeCodingRun({
                 validationReport,
+                reproductionReport,
                 dir,
                 spec,
                 logger,
@@ -314,7 +363,7 @@ async function prepareCodingCheckout(dir, spec, logger, opts) {
  * {@link runCodingAgent} so its body stays small; returns the built {@link CodingAgentOutcome}.
  */
 async function finalizeCodingRun(args) {
-    const { validationReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
+    const { validationReport, reproductionReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
     const { signal } = opts;
     const { summary, stats, stderrTail, usage, callMetrics, effortReport } = agentRun;
     let outcome;
@@ -403,6 +452,10 @@ async function finalizeCodingRun(args) {
     // backend to record on the step.
     if (validationReport)
         outcome.validationReport = validationReport;
+    // The reproduction proof: attached to EVERY outcome, including a no-op or an `inconclusive`
+    // verdict. It is evidence about the change, not a gate on it — see the loop's D6 note.
+    if (reproductionReport)
+        outcome.reproductionReport = reproductionReport;
     return outcome;
 }
 /**

package/dist/git.js

@@ -509,6 +509,40 @@ export async function branchAheadOfBase(dir, baseBranch, ghToken, signal) {
         return undefined;
     }
 }
+/**
+ * The files `commitish` changes relative to its merge base with the PR base branch — i.e.
+ * everything the work branch has added on top of base, `git diff --name-only <base>...<commitish>`.
+ *
+ * The BUGFIX REPRODUCTION PROOF uses this to answer the one question that decides whether a GREEN
+ * pre-fix tree means anything: does that tree ALREADY carry non-test work committed on this
+ * branch? A resumed run's `baseSha` is whatever the branch tip was when this pass started, which
+ * in the designed flow is the reproduction step's test commit — but after an eviction it is this
+ * same coder step's own interrupted work, fix included. Reporting "the check passed before your
+ * change, so it does not demonstrate the defect" in that case is simply false.
+ *
+ * `undefined` means "could not determine" (a shallow clone with no reachable merge base, a fetch
+ * failure, an unknown ref), never an empty list: the caller must degrade to its prior behaviour
+ * rather than read a failed probe as "the tree is clean".
+ *
+ * NUL-delimited so a path containing a newline (legal in git) cannot split into two entries.
+ */
+export async function changedFilesSinceBase(dir, baseBranch, ghToken, commitish, signal) {
+    try {
+        await git(['fetch', 'origin', `+refs/heads/${baseBranch}:refs/cat-factory/base`], {
+            cwd: dir,
+            signal,
+            env: await authEnv(ghToken),
+        });
+        const out = await git(['diff', '--name-only', '-z', `refs/cat-factory/base...${commitish}`], {
+            cwd: dir,
+            signal,
+        });
+        return out.split('\0').filter((p) => p !== '');
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Whether the checked-out branch has a real, examinable diff against
  * `origin/<baseBranch>` — i.e. the base branch's remote-tracking ref exists (so the
@@ -565,6 +599,80 @@ export async function hasAgentChanges(dir, signal) {
 export async function headCommit(dir, signal) {
     return (await git(['rev-parse', 'HEAD'], { cwd: dir, signal })).trim();
 }
+/**
+ * Add a DETACHED worktree of `commitish` at `worktreePath`, sharing `dir`'s object database.
+ *
+ * The bugfix reproduction proof runs the declared check against two trees of the SAME clone (the
+ * pre-fix tree and the final tree), so a worktree is the only mechanism that gets both without a
+ * second clone, a second fetch, or disturbing the agent's own checkout — which must stay exactly
+ * as the agent left it, since the push and the PR come off it.
+ *
+ * `--detach` (rather than a branch) is deliberate: a worktree that claimed a branch would collide
+ * with the work branch checked out in `dir`, and nothing here ever commits.
+ *
+ * `worktreePath` is expected to live OUTSIDE the checkout (a per-job temp root), so the worktree's
+ * `.git` pointer file can never be swept into the agent's commit by a broad `git add -A`.
+ */
+export async function addWorktree(dir, worktreePath, commitish, signal) {
+    await git(['worktree', 'add', '--detach', worktreePath, commitish], { cwd: dir, signal });
+}
+/**
+ * Remove a worktree previously added by {@link addWorktree} and prune the stale administrative
+ * entry, never throwing: teardown is bookkeeping, and a run whose PROOF succeeded must not fail
+ * because a temp directory could not be cleaned up. The caller still deletes the temp root, so a
+ * failure here leaks only a `.git/worktrees/<name>` record inside a container that is about to be
+ * destroyed anyway.
+ */
+export async function removeWorktree(dir, worktreePath, signal) {
+    try {
+        await git(['worktree', 'remove', '--force', worktreePath], { cwd: dir, signal });
+    }
+    catch {
+        // Fall through to the prune, which cleans up the record even when the directory is gone.
+    }
+    try {
+        await git(['worktree', 'prune'], { cwd: dir, signal });
+    }
+    catch {
+        // Best-effort by design (see the doc comment).
+    }
+}
+/**
+ * Which of `paths` actually exist in `commitish`'s tree. Used by the reproduction proof to tell a
+ * DECLARED test file that was committed from one that only ever existed as an untracked working-
+ * tree file: the proof runs against committed trees, so an unadded test is invisible to it — and
+ * equally invisible to the push, which is the point worth telling the agent about rather than
+ * reporting a verdict computed without the reproduction in it.
+ *
+ * Returns the input order/spelling of the paths that matched, so the caller can diff against its
+ * declared list to name the missing ones verbatim.
+ */
+export async function pathsPresentAtCommit(dir, commitish, paths, signal) {
+    if (paths.length === 0)
+        return [];
+    const out = await git(['ls-tree', '-r', '--name-only', '-z', commitish, '--', ...paths], {
+        cwd: dir,
+        signal,
+    });
+    // NUL-delimited so a path containing a newline (legal in git) can't split into two entries.
+    const present = new Set(out.split('\0').filter((p) => p !== ''));
+    return paths.filter((p) => present.has(p));
+}
+/**
+ * Check `paths` out of `commitish` into `dir`'s working tree (and index), leaving every other file
+ * untouched.
+ *
+ * This is how the reproduction's declared TEST files are placed onto the pre-fix worktree, and the
+ * narrowness is the whole safety property: a whole-tree checkout would drag the FIX across too and
+ * green the base, manufacturing a "the test does not capture the defect" verdict out of a
+ * perfectly good reproduction. Only the paths the caller has already sanitized are passed, and
+ * `--` stops any of them being read as a revision.
+ */
+export async function checkoutPathsFrom(dir, commitish, paths, signal) {
+    if (paths.length === 0)
+        return;
+    await git(['checkout', commitish, '--', ...paths], { cwd: dir, signal });
+}
 /** Stage everything and commit; returns false when there was nothing to commit. */
 export async function commitAll(dir, message, signal) {
     await git(['add', '-A'], { cwd: dir, signal });

package/dist/job.js

@@ -1,3 +1,5 @@
+import { parseValidationChecksSpec, } from './validation-checks.js';
+import { parseReproductionSpec, } from './reproduction-proof.js';
 function str(value, path) {
     if (typeof value !== 'string' || value.length === 0) {
         throw new Error(`Invalid job: '${path}' must be a non-empty string`);
@@ -66,39 +68,6 @@ function parseValidationSpec(value) {
         ...(iteration !== undefined ? { iteration } : {}),
     };
 }
-/**
- * Parse the optional PRE-PR VALIDATION CHECKS spec (see
- * docs/initiatives/pre-pr-validation.md): 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.
- */
-function parseValidationChecksSpec(value) {
-    if (typeof value !== 'object' || value === null)
-        return undefined;
-    const o = value;
-    if (!Array.isArray(o.checks))
-        return undefined;
-    const checks = [];
-    for (const raw of o.checks) {
-        if (typeof raw !== 'object' || raw === null)
-            continue;
-        const c = raw;
-        if (typeof c.command !== 'string' || c.command.trim() === '')
-            continue;
-        const label = typeof c.label === 'string' && c.label.trim() ? c.label.trim() : c.command;
-        checks.push({ label, command: c.command });
-    }
-    if (checks.length === 0)
-        return undefined;
-    const parsed = posInt(o.maxAttempts);
-    return {
-        checks,
-        maxAttempts: Math.min(parsed ?? VALIDATION_DEFAULT_MAX_ATTEMPTS, VALIDATION_MAX_ATTEMPTS_CEILING),
-    };
-}
 /**
  * Parse the shared per-job auth fields, validating per harness: a subscription
  * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
@@ -386,18 +355,6 @@ export function parseTestSecrets(value) {
     }
     return entries;
 }
-/**
- * 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 const VALIDATION_MAX_ATTEMPTS_CEILING = 10;
-export const VALIDATION_DEFAULT_MAX_ATTEMPTS = 3;
 /** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
 function parseAgentBootstrapSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -717,6 +674,7 @@ export function parseAgentJob(input) {
         guardLimits: parseGuardLimits(o.guardLimits),
         validation: parseValidationSpec(o.validation),
         validationChecks: parseValidationChecksSpec(o.validationChecks),
+        reproduction: parseReproductionSpec(o.reproduction),
         reviewPrNumber: posInt(o.reviewPrNumber),
     });
     assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
@@ -773,7 +731,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, validationChecks, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -801,6 +759,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(guardLimits ? { guardLimits } : {}),
         ...(validation ? { validation } : {}),
         ...(validationChecks ? { validationChecks } : {}),
+        ...(reproduction ? { reproduction } : {}),
     };
 }
 /**