@cat-factory/executor-harness 1.56.0 → 1.60.0

package/dist/validation-checks.js

@@ -1,9 +1,58 @@
-import { spawn } from 'node:child_process';
-import { killChildProcess, spawnDetached } from './process.js';
-import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
+import { runCapturedCommand } from './captured-command.js';
+/**
+ * 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 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 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 = typeof o.maxAttempts === 'number' && Number.isFinite(o.maxAttempts) && o.maxAttempts > 0
+        ? Math.floor(o.maxAttempts)
+        : undefined;
+    return {
+        checks,
+        maxAttempts: Math.min(parsed ?? VALIDATION_DEFAULT_MAX_ATTEMPTS, VALIDATION_MAX_ATTEMPTS_CEILING),
+    };
+}
 /**
  * Per-command output kept on the REPORT (what crosses the wire and lands in the run's persisted
- * `detail` blob). Deliberately smaller than {@link MAX_CAPTURED_OUTPUT_CHARS}, which is what the
+ * `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.
  */
@@ -75,88 +124,27 @@ export async function runValidationChecks(cwd, spec, attempt, logger, opts) {
     return { report, fullTails };
 }
 /**
- * Run ONE check as `sh -c <command>` 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 gate. A watchdog kills
- * the process tree on timeout and an aborted run resolves non-zero, so the loop is never blocked.
- *
- * 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 its checks without the private-registry npmrc
- * pointer (and against a sibling job's state, had this been staged in `process.env`).
+ * Run ONE check through the shared {@link runCapturedCommand} seam and shape it as a check
+ * outcome. The exit code is the verdict — computed by the harness, never self-reported by the
+ * model, which is the whole point of a programmatic gate.
  */
 async function runOneCheck(cwd, check, logger, opts) {
-    const timeoutMs = validationCommandTimeoutMs();
-    const startedAt = Date.now();
     logger.info('validation: running check', { label: check.label });
-    return new Promise((resolve) => {
-        let out = '';
-        let settled = false;
-        let timedOut = false;
-        const child = spawn('sh', ['-c', check.command], {
-            cwd,
-            detached: spawnDetached,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, ...opts.agentEnv },
-        });
-        // Keep only the tail; guard against unbounded buffering on a chatty command.
-        const capture = (chunk) => {
-            out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_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 truncating: a token straddling the cut would otherwise survive as a
-            // partial, and the pattern rules need the whole assignment to match.
-            const scrubbed = trimmed ? redactSecrets(trimmed) : '';
-            logger.info('validation: check finished', { label: check.label, exitCode });
-            resolve({
-                outcome: {
-                    label: check.label,
-                    command: check.command,
-                    exitCode,
-                    passed: exitCode === 0,
-                    ...(scrubbed ? { outputTail: tailFor(scrubbed) } : {}),
-                    durationMs: Date.now() - startedAt,
-                    ...(timedOut ? { timedOut: true } : {}),
-                },
-                ...(scrubbed ? { fullTail: scrubbed } : {}),
-            });
-        };
-        const timer = setTimeout(() => {
-            logger.warn('validation: check timed out', { label: check.label, 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('validation: check failed to spawn', {
-                label: check.label,
-                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));
+    const { fullTail, ...run } = await runCapturedCommand({
+        cwd,
+        command: check.command,
+        timeoutMs: validationCommandTimeoutMs(),
+        reportTailChars: VALIDATION_REPORT_TAIL_CHARS,
+        logLabel: 'validation',
+        logFields: { label: check.label },
+        logger,
+        opts,
     });
-}
-/** Bound an already-scrubbed output tail to what the REPORT carries. */
-function tailFor(scrubbed) {
-    if (scrubbed.length <= VALIDATION_REPORT_TAIL_CHARS)
-        return scrubbed;
-    const trimmed = scrubbed.length - VALIDATION_REPORT_TAIL_CHARS;
-    return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-VALIDATION_REPORT_TAIL_CHARS)}`;
+    logger.info('validation: check finished', { label: check.label, exitCode: run.exitCode });
+    return {
+        outcome: { label: check.label, command: check.command, ...run },
+        ...(fullTail ? { fullTail } : {}),
+    };
 }
 /**
  * The repair instruction handed to the agent after a failed attempt: the failing commands and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.56.0",
+  "version": "1.60.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -21,13 +21,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.0.12",
     "@types/node": "^26.1.1",
-    "hono": "^4.12.30",
+    "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.149.0",
-    "@cat-factory/spend": "0.12.83"
+    "@cat-factory/server": "0.154.0",
+    "@cat-factory/spend": "0.12.90"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -972,6 +972,10 @@ function buildSingleRepoCodingSpec(
     // 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 } : {}),
   }
 }
 
@@ -992,6 +996,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     callMetrics,
     validation,
     validationReport,
+    reproductionReport,
     effortReport,
   } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts)
   // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
@@ -999,10 +1004,14 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
   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
@@ -1022,7 +1031,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'agent',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1038,7 +1047,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
         ...ralphVerdict,
-        ...validationFields,
+        ...verificationFields,
         ...effort,
       }
     }
@@ -1051,7 +1060,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       failureCause: 'no-changes',
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1086,7 +1095,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
           stats,
           ...(usage ? { usage } : {}),
           ...(callMetrics ? { callMetrics } : {}),
-          ...validationFields,
+          ...verificationFields,
           ...effort,
         }
       }
@@ -1103,7 +1112,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         failureCause: 'no-changes',
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
-        ...validationFields,
+        ...verificationFields,
         ...effort,
       }
     }
@@ -1116,7 +1125,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
       ...ralphVerdict,
-      ...validationFields,
+      ...verificationFields,
       ...effort,
     }
   }
@@ -1128,7 +1137,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
     ...ralphVerdict,
-    ...validationFields,
+    ...verificationFields,
     ...effort,
   }
 }

package/src/captured-command.ts

@@ -0,0 +1,144 @@
+import { spawn } from 'node:child_process'
+import { killChildProcess, spawnDetached } from './process.js'
+import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js'
+import type { RunOptions } from './runner.js'
+import type { Logger } from './logger.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
+
+/** What one harness-spawned command did, as both phases record it. */
+export interface CapturedCommandResult {
+  /** Exit code (0 = pass); 124 on watchdog timeout, 127 on spawn failure, 130 on abort. */
+  exitCode: number
+  passed: boolean
+  /** Scrubbed output bounded to the caller's REPORT budget (what crosses the wire). */
+  outputTail?: string
+  durationMs: number
+  timedOut?: boolean
+  /**
+   * The FULL scrubbed tail (up to {@link MAX_CAPTURED_OUTPUT_CHARS}) for a repair prompt. Never
+   * leaves the container — the agent needs the whole failure to act on it, the wire does not.
+   */
+  fullTail?: string
+}
+
+/**
+ * Run ONE command as `sh -c` in `cwd`, capturing a bounded, secret-scrubbed tail of its combined
+ * stdout+stderr. The exit code is the verdict — computed here by the harness, never self-reported
+ * by the model, which is the whole point of a programmatic phase. A watchdog kills the process
+ * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
+ * from settling.
+ *
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * not a mutated global: the harness spawns this itself rather than through the agent, so without
+ * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
+ * had this been staged in `process.env`, against a sibling job's state).
+ *
+ * `logLabel`/`logFields` shape only the two warnings this runner emits itself (the watchdog kill
+ * and a spawn failure); the caller keeps its own start/finish logging, which knows what the
+ * command MEANS.
+ */
+export async function runCapturedCommand(args: {
+  cwd: string
+  command: string
+  timeoutMs: number
+  /** Bound for {@link CapturedCommandResult.outputTail} — the caller's per-report budget. */
+  reportTailChars: number
+  logLabel: string
+  logFields?: Record<string, unknown>
+  logger: Logger
+  opts: RunOptions
+}): Promise<CapturedCommandResult> {
+  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: Buffer): void => {
+      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: number): void => {
+      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 = (): void => {
+      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: string, maxChars: number): string {
+  if (scrubbed.length <= maxChars) return scrubbed
+  const trimmed = scrubbed.length - maxChars
+  return `…(${trimmed} earlier chars trimmed)\n${scrubbed.slice(-maxChars)}`
+}

package/src/coding-agent.ts

@@ -14,6 +14,7 @@ import type {
 } from './job.js'
 import {
   branchAheadOfBase,
+  changedFilesSinceBase,
   branchHasCommitsSince,
   cloneExistingBranch,
   cloneRepo,
@@ -47,6 +48,11 @@ import {
   type ValidationChecksSpec,
   type ValidationReport,
 } from './validation-checks.js'
+import {
+  runReproductionLoop,
+  type ReproductionReport,
+  type ReproductionSpec,
+} from './reproduction-proof.js'
 
 // The shared skeleton for the container coding agents that clone a repo, run Pi
 // against it and push the result on a branch. The implementation (`/run`) and
@@ -117,6 +123,16 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * `docs/initiatives/pre-pr-validation.md`.
    */
   validationChecks?: ValidationChecksSpec
+  /**
+   * 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
   /**
    * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
    * into {@link runAgentInWorkspace}, which installs it harness-aware: natively under the ISOLATED
@@ -158,6 +174,12 @@ export interface CodingAgentOutcome {
    * 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
 }
 
 /**
@@ -323,6 +345,64 @@ export async function runCodingAgent(
         opts.onPhase?.('agent')
         logger.info('coding-agent: running agent', { serviceDirectory })
         let agentRun = await runAgentPass(spec.userPrompt)
+        const foldPass = (run: typeof agentRun): void => {
+          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 = (): Promise<string[]> =>
+          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: ReproductionReport | undefined
+        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
@@ -338,17 +418,16 @@ export async function runCodingAgent(
             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,
@@ -499,6 +578,8 @@ async function prepareCodingCheckout(
 async function finalizeCodingRun(args: {
   /** The pre-PR validation loop's last attempt, attached to the outcome (absent when unconfigured). */
   validationReport?: ValidationReport
+  /** The reproduction proof's last attempt, attached to the outcome (absent when unconfigured). */
+  reproductionReport?: ReproductionReport
   dir: string
   spec: CodingAgentSpec
   logger: Logger
@@ -515,6 +596,7 @@ async function finalizeCodingRun(args: {
 }): Promise<CodingAgentOutcome> {
   const {
     validationReport,
+    reproductionReport,
     dir,
     spec,
     logger,
@@ -618,6 +700,9 @@ async function finalizeCodingRun(args: {
   // reaches the PR-opening caller); attach its verdict for the caller to gate on and for the
   // 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
 }