@cat-factory/executor-harness 1.58.0 → 1.62.0

package/README.md

@@ -63,9 +63,26 @@ 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. The PR's description prefers the agent-authored reviewer briefing over the generic
+   dispatch-time text the job body carries: a PR-opening agent is prompted to write one to the
+   `.cat-pr-description.md` sentinel at the checkout root (one per sibling repo in a multi-repo
+   run; an optional leading `# <title>` line, when it is the file's only `#` heading, sets the PR
+   title), and `src/pr-description.ts` lifts it — secret-scrubbed, size-capped with a visible
+   note, made inert for the host by `src/host-markdown.ts`, kept out of the commit like the
+   effort/follow-ups sentinels — onto `openPullRequest`. Absent or unusable ⇒ the fallback text,
+   unchanged. On a RESUMED run the PR already exists, so an agent briefing additionally refreshes
+   its title/description in place (carrying the engine's managed report region across); the
+   generic fallback never does, so a human's edit is safe.
 
 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 +150,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 +166,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

@@ -6,7 +6,9 @@ import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { inferVcsProvider, openPullRequest } from './vcs-api.js';
+import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -808,6 +810,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 +824,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, prDescription, } = 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 +856,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'agent',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -861,7 +871,7 @@ async function runSingleRepoCoding(job, opts) {
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...ralphVerdict,
-                ...validationFields,
+                ...verificationFields,
                 ...effort,
             };
         }
@@ -874,7 +884,7 @@ async function runSingleRepoCoding(job, opts) {
             failureCause: 'no-changes',
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -886,7 +896,11 @@ async function runSingleRepoCoding(job, opts) {
             ghToken: job.ghToken,
             head: pushBranch,
             base: job.repo.baseBranch,
-            pr: job.pr,
+            // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
+            pr: applyPrDescription(job.pr, prDescription),
+            // A resumed run's PR is already open, so refresh it rather than lose the briefing to the
+            // duplicate-PR 422 — only from a REAL briefing (see `refreshExisting` for why).
+            ...(prDescription ? { refreshExisting: true } : {}),
             apiBase: job.githubApiBase,
             // The provider (set by the server from the configured backend) selects GitHub-PR vs
             // GitLab-MR authoritatively; the clone URL supplies the GitLab REST base + project path.
@@ -908,7 +922,7 @@ async function runSingleRepoCoding(job, opts) {
                     stats,
                     ...(usage ? { usage } : {}),
                     ...(callMetrics ? { callMetrics } : {}),
-                    ...validationFields,
+                    ...verificationFields,
                     ...effort,
                 };
             }
@@ -921,7 +935,7 @@ async function runSingleRepoCoding(job, opts) {
                 failureCause: 'no-changes',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
-                ...validationFields,
+                ...verificationFields,
                 ...effort,
             };
         }
@@ -934,7 +948,7 @@ async function runSingleRepoCoding(job, opts) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...ralphVerdict,
-            ...validationFields,
+            ...verificationFields,
             ...effort,
         };
     }
@@ -946,7 +960,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,15 @@ 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, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
+import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.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
@@ -114,6 +117,9 @@ export async function runCodingAgent(spec, opts = {}) {
         // but that cannot un-stage a mid-run commit; the per-clone exclude is what prevents it. A bare
         // filename pattern matches the file in any subdirectory, so it covers a monorepo `workDir` too.
         await excludeFromGit(dir, EFFORT_REPORT_FILE, signal);
+        // Same treatment for the agent-authored PR-description sentinel: excluded locally so the
+        // agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
         // job view. Locally exclude it from git first so the agent's own `git add` can never
         // stage it and it never surfaces as an untracked leftover or in the PR. The sentinel
@@ -154,6 +160,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 +224,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 +368,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;
@@ -327,6 +381,12 @@ async function finalizeCodingRun(args) {
     // Safety net for forgotten edits: commit changes to TRACKED files only (never
     // untracked scratch files/artifacts — the agent owns committing new files).
     await commitTrackedEdits(dir, spec.commitMessage, signal);
+    // The agent-authored PR description, read AFTER the validation loop (a repair round may have
+    // changed what the briefing should say) and removed so it never lingers in the checkout. The
+    // prompt asks for it at the top level of the checkout; a monorepo agent working in a service
+    // subdirectory may drop it in its cwd instead, so probe the checkout root first, then the cwd.
+    const prDescription = (await readPrDescription(dir)) ??
+        (workDir !== dir ? await readPrDescription(workDir) : undefined);
     // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
     // push, so the two never run a concurrent `git push` to the same branch (the
     // final push below is then a fresh attempt whose failure is the real signal).
@@ -389,6 +449,7 @@ async function finalizeCodingRun(args) {
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
             ...(effortReport ? { effortReport } : {}),
+            ...(prDescription ? { prDescription } : {}),
         };
     }
     // Ralph loop: run the programmatic completion command against the pushed/committed
@@ -403,6 +464,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;
 }
 /**
@@ -645,7 +710,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             multiRepo: true,
         }, opts);
         // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
-        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts);
+        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts, root);
         const anyWork = primaryPushed || peerPullRequests.length > 0;
         if (!anyWork) {
             // Nothing changed in ANY repo. For the implementer this is a failure (as in the
@@ -746,6 +811,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
             await createBranch(dir, leg.workBranch, signal);
         }
         leg.dir = dir;
+        // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
+        // so the agent's own `git add` can never stage the briefing into the PR it describes.
+        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
         // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
         // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
         // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
@@ -791,7 +859,9 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
  * no PR; a read-only reference leg is never committed or pushed). Extracted so the multi-repo body
  * stays small; returns the primary's push/PR state plus the peer PRs.
  */
-async function pushMultiRepoLegs(legs, job, logger, opts) {
+async function pushMultiRepoLegs(legs, job, logger, opts, 
+/** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
+root) {
     const { signal } = opts;
     opts.onPhase?.('push');
     let primaryPushed = false;
@@ -802,6 +872,14 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
         // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
         if (leg.readOnly)
             continue;
+        // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
+        // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
+        // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
+        // read the prompt loosely may well have written a single briefing there instead. Fall back
+        // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
+        // describes, and the primary is the one the run is actually about.
+        const agentPrDescription = (await readPrDescription(leg.dir)) ??
+            (leg.primary ? await readPrDescription(root) : undefined);
         await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal);
         const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal);
         let hasWork = advanced || leg.resumed;
@@ -831,7 +909,10 @@ async function pushMultiRepoLegs(legs, job, logger, opts) {
                 ghToken: leg.ghToken,
                 head: leg.workBranch,
                 base: leg.repo.baseBranch,
-                pr: leg.pr,
+                pr: applyPrDescription(leg.pr, agentPrDescription),
+                // See the single-repo call site: refresh a resumed leg's already-open PR, but only
+                // when the text is the agent's own briefing rather than the dispatch-time fallback.
+                ...(agentPrDescription ? { refreshExisting: true } : {}),
                 apiBase: job.githubApiBase,
                 cloneUrl: leg.repo.cloneUrl,
                 ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),