@cat-factory/executor-harness 1.135.0 → 1.139.0

package/README.md

@@ -116,6 +116,51 @@ 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
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+### The environment is probed once, not by the agent
+
+Before any mode branches, `handleAgent` probes the machine it is about to run on and appends an
+`ENVIRONMENT INVENTORY` block to the job's system prompt (`src/environment-inventory.ts`). It names
+the toolchain that answered and its versions, the curated list of tools that did not, and whether a
+Docker DAEMON is actually reachable.
+
+It exists because the platform used to ask every agent to find this out for itself, and every agent
+did: in one measured run an architect ran `for c in docker kubectl helm kustomize; …` and then
+`docker info`, and the coder it handed off to rediscovered both answers thirty calls later. Four
+calls out of a forty-call budget for facts this process holds before the agent's first turn. The
+backend cannot hold them (it composes its prompt before a transport is chosen, and the same body
+reaches this image, a deployment's own image variant and, under `LOCAL_NATIVE_AGENTS`, the
+developer's own machine), so it states the POLICY and names no tooling at all.
+
+Three rules bind anything added to it:
+
+- **A failed probe is not an absence.** Only `ENOENT` means "not installed"; a timeout or a refused
+  spawn renders on its own line as could-not-be-determined, because the two lead an agent to
+  opposite next moves.
+- **An unlisted tool is unknown too**, which the block's last line says. The probe list is curated,
+  so silence about `terraform` must not read as its absence.
+- **The Docker daemon is answered by running `docker info`**, never by finding the CLI. The CLI is
+  installed in this image unconditionally, `entrypoint.sh` starts the rootless daemon best-effort
+  and execs the server without waiting for it, so at job start this probe is the only thing that
+  knows how that went.
+- **A daemon that is STARTING is not a daemon that is absent.** Because the entrypoint does not
+  wait, the backend dispatches seconds before there is a socket, and `docker info` is then refused
+  at once rather than slowly. So a refusal is read against `DOCKER_HOST`, which the entrypoint sets
+  whenever something is meant to serve a daemon here: unset means nothing was coming and the
+  absence is stated definitively, set means one short retry and then could-not-be-determined. The
+  absent wording tells an agent `docker compose up` "will fail here whatever the CLI reports", which
+  is a prohibition, so it may only be reached where nothing is going to answer.
+- **A tool the platform did not provide is not installable system-wide either**, since the job runs
+  unprivileged. The line says that instead of banning installation outright: `pnpm` is absent from
+  this image (only the UI variant carries it), so it is routinely the package manager the job's own
+  repository declares, and a flat prohibition pushed agents onto `npm install` against a pnpm
+  lockfile. Reaching a project's own manager for that project alone is allowed and named.
+
+Composed at exactly ONE point, onto the job's own `systemPrompt`, which every mode already forwards
+and all three CLIs already carry (claude-code's `--append-system-prompt` and its oversized-argv
+fallback, Codex's fold, Pi's `AGENTS.md`). `test/environment-inventory.coverage.test.ts` pins that:
+a mode that folded its own copy would state the machine twice, and one that folded none would leave
+its agent probing, with nothing failing either way.
+
 ### The work-branch push is CHECKPOINTED, so it is lease-guarded
 
 Step 8's push is not the run's first: every `JOB_CHECKPOINT_INTERVAL_MS` (60s) the harness pushes
@@ -393,6 +438,7 @@ verdict is stated.
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/artifact-upload.ts` | The OUTBOUND half of the artifact seam: parses the body's `artifactUpload` and projects it onto the agent's env as `ARTIFACT_UPLOAD_URL` / `ARTIFACT_UPLOAD_TOKEN`, registering the token for redaction first. Passes through what the body carries and decides nothing: which kinds get the seam is the backend's call. |
 | `src/codex-images.ts` | Codex's own `image_gen` output, staged where the agent can reach it: creates `$CODEX_HOME/generated_images` as a symlink into `.cat-context/binary-output/generated/` before the CLI starts, sweeps anything a failed redirect left behind, and unlinks (never follows) the redirect at teardown — a failed unlink is REPORTED, because that unlink is what stops the recursive delete reaching the checkout. Exists because codex exposes no path for what it generated AND `$CODEX_HOME` holds the run's decrypted credential, so neither asking the agent nor sending it there is available. |
+| `src/environment-inventory.ts` | What the MACHINE holds, probed once per job and appended to the agent's system prompt as an ENVIRONMENT INVENTORY block. The only layer that can state it: the backend composes its prompt before a transport is chosen, and the same body serves this image, a deployment's own variant and the developer's laptop under `LOCAL_NATIVE_AGENTS`. Three-valued on purpose, so a probe that failed renders as unknown rather than as an absence, and the Docker DAEMON is answered by running `docker info` rather than by finding the CLI, which is installed here either way. See [The environment is probed once, not by the agent](#the-environment-is-probed-once-not-by-the-agent). |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 | `src/docker-status.ts` | This container's own verdict about its Docker daemon, as recorded by `entrypoint.sh`. Three-valued on purpose: a daemon that FAILED and a daemon nobody asked about are different facts, and only a DECIDED absence refuses a stand-up. See [Local infra: the container's Docker daemon](#local-infra-the-containers-docker-daemon). |

package/dist/agent-runner.js

@@ -425,6 +425,15 @@ export async function runClaudeCode(opts) {
     // The built-in tools this run declares, named ONCE: the same list rides `--tools` and the
     // `--allowedTools` re-grant, which is additive rather than inert (see `claudeAllowedToolPatterns`).
     const tools = CLAUDE_TOOL_SET;
+    // ...but `--tools` itself is withheld from an ambient run, whose `claude` is the developer's own
+    // rather than this image's pinned one: an unrecognised FLAG fails the whole run, where an
+    // unrecognised tool NAME is merely dropped. See `claudeCliArgs`. The re-grant is unaffected
+    // (`--allowedTools` long predates this), so a tool-server run still unlocks what it wires.
+    const declareTools = opts.ambientAuth !== true;
+    const declaredTools = declareTools ? tools : [];
+    if (!declareTools) {
+        opts.log?.info('claude-code: taking the CLI’s default tool surface (ambient CLI, version unknown)');
+    }
     const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [];
     const capture = openClaudeCallCapture(opts, { prompt, folded, secrets });
     const telemetry = capture.telemetry;
@@ -468,7 +477,7 @@ export async function runClaudeCode(opts) {
         reportToolServerStartup(event, opts.onToolServers);
         // The same startup event answers what the CLI granted of what we asked for; a capability it
         // named no tool for is a silent capability loss otherwise (see `assertClaudeToolsCurrent`).
-        assertClaudeToolsCurrent(event, tools, opts.log);
+        assertClaudeToolsCurrent(event, declaredTools, opts.log);
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
         // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
         // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on
@@ -560,7 +569,13 @@ export async function runClaudeCode(opts) {
     try {
         const { stderrTail } = await streamCli({
             command: 'claude',
-            args: claudeCliArgs({ model: opts.model, tools, mcpArgs: home.mcpArgs, appendArgs }),
+            args: claudeCliArgs({
+                model: opts.model,
+                tools,
+                declareTools,
+                mcpArgs: home.mcpArgs,
+                appendArgs,
+            }),
         }, prompt, { ...opts, signal: runSignal }, home.env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // The stream has ended, so the last call has no successor envelope to complete it.
         telemetry.flush();

package/dist/agent.js

@@ -11,12 +11,14 @@ import { registerKnownSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, unmergedPaths, } from './git.js';
 import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
+import { withSalvageOnlyNote } from './salvage.js';
 import { makeDirClaimer } from './checkout-dir.js';
 import { noChangesReason, runCodingAgent } from './coding-agent.js';
 import { runMultiRepoCoding } from './multi-repo-coding.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';
+import { appendEnvironmentInventory } from './environment-inventory.js';
 import { runBootstrap } from './bootstrap-mode.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
@@ -126,9 +128,27 @@ export async function handleAgent(job, opts = {}) {
         });
         if (job.mode === 'preview')
             return await runPreviewMode(job, scoped);
-        return job.mode === 'coding'
-            ? await runCodingMode(job, scoped)
-            : await runExploreMode(job, scoped);
+        // THE composition point for the environment inventory (see `environment-inventory.ts`): the
+        // machine is probed ONCE here, before any mode branches, and the result is folded onto the
+        // job's own system prompt. Every mode, every repair round and all three agent CLIs read that
+        // one field, so none of them can end up without the block and none can carry it twice.
+        // `preview` returns above because it runs no agent at all, so there is no prompt to fold onto.
+        //
+        // This sits on the critical path AHEAD of the clone, which is the cost of having one
+        // composition point instead of one per mode (each mode owns its own clone, so there is no
+        // single post-clone place to put this). The pass is sized for that: everything in it runs
+        // concurrently, every probe is a call that answers in milliseconds or is wedged, and the one
+        // deliberate wait is a single short retry for a daemon that is still starting.
+        const staged = {
+            ...job,
+            systemPrompt: await appendEnvironmentInventory(job.systemPrompt, {
+                ...(opts.signal ? { signal: opts.signal } : {}),
+                ...(opts.log ? { log: opts.log } : {}),
+            }),
+        };
+        return staged.mode === 'coding'
+            ? await runCodingMode(staged, scoped)
+            : await runExploreMode(staged, scoped);
     }
     finally {
         if (scopeDir)
@@ -775,7 +795,7 @@ export 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, reproductionReport, effortReport, prDescription, } = await runCodingAgent(buildSingleRepoCodingSpec(job, pushBranch), opts);
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation, validationReport, reproductionReport, effortReport, prDescription, salvageOnly, } = 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 } : {};
@@ -847,8 +867,10 @@ async function runSingleRepoCoding(job, opts) {
             ghToken: job.ghToken,
             head: pushBranch,
             base: job.repo.baseBranch,
-            // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text.
-            pr: applyPrDescription(job.pr, prDescription),
+            // The agent-authored briefing (title/body) wins field-wise over the dispatch-time text,
+            // and a branch that is nothing but salvage says so above whichever body won: the agent
+            // committed nothing here, so no briefing on it describes a change anyone proposed.
+            pr: withSalvageOnlyNote(applyPrDescription(job.pr, prDescription), salvageOnly === true),
             // 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 } : {}),

package/dist/claude-cli.d.ts

@@ -67,6 +67,18 @@ export declare function claudeCliArgs(opts: {
     model: string;
     /** The built-in tools this run asks for; see {@link CLAUDE_TOOL_SET}. */
     tools: readonly string[];
+    /**
+     * Whether to DECLARE that set with `--tools`, or take whatever the CLI defaults to.
+     *
+     * False for an `ambientAuth` run, which is the one case where the CLI is not this image's. A
+     * name the build does not carry is dropped silently, which is what makes {@link CLAUDE_TOOL_SET}
+     * safe to be over-inclusive, but that rule is about tool NAMES. An unrecognised FLAG is a
+     * different failure: the CLI exits before the run starts. Everywhere else the image pins the
+     * version and the flag is measured against it; on a developer's own machine the harness knows
+     * neither which `claude` is on the PATH nor how old it is, and the cost of guessing wrong is
+     * every local native run, not a thinner tool surface on one.
+     */
+    declareTools: boolean;
     /** `--mcp-config` + `--strict-mcp-config` + any `--allowedTools`; empty when no server is wired. */
     mcpArgs: readonly string[];
     /** `--append-system-prompt <prompt>`, or empty when the prompt was folded into stdin. */
@@ -85,6 +97,11 @@ export declare function claudeCliArgs(opts: {
  * Best-effort and never throws: a run whose tool surface is short is still a run, and the honest
  * disposition for a floor this image cannot verify is to SAY it could not be read, not to fail the
  * job and not to stay silent (which reads exactly like a satisfied request).
+ *
+ * `requested` is what the argv actually DECLARED, so an ambient run (which declares nothing, see
+ * {@link claudeCliArgs}) passes none and the line says the surface is the CLI's own default. The
+ * floor is still read back there: "the default set carries no search tool" and "we asked for one
+ * and did not get it" are both worth a line, and they are not the same fact or the same fix.
  */
 export declare function assertClaudeToolsCurrent(event: Record<string, unknown>, requested: readonly string[], log: Logger | undefined): void;
 export {};

package/dist/claude-cli.js

@@ -131,8 +131,7 @@ export function claudeCliArgs(opts) {
         '--model',
         opts.model,
         // Declared rather than defaulted: see this module's header for what the default set costs.
-        '--tools',
-        opts.tools.join(','),
+        ...(opts.declareTools ? ['--tools', opts.tools.join(',')] : []),
         ...opts.mcpArgs,
         ...opts.appendArgs,
     ];
@@ -150,6 +149,11 @@ export function claudeCliArgs(opts) {
  * Best-effort and never throws: a run whose tool surface is short is still a run, and the honest
  * disposition for a floor this image cannot verify is to SAY it could not be read, not to fail the
  * job and not to stay silent (which reads exactly like a satisfied request).
+ *
+ * `requested` is what the argv actually DECLARED, so an ambient run (which declares nothing, see
+ * {@link claudeCliArgs}) passes none and the line says the surface is the CLI's own default. The
+ * floor is still read back there: "the default set carries no search tool" and "we asked for one
+ * and did not get it" are both worth a line, and they are not the same fact or the same fix.
  */
 export function assertClaudeToolsCurrent(event, requested, log) {
     if (!log || event.type !== 'system' || event.subtype !== 'init')
@@ -158,7 +162,7 @@ export function assertClaudeToolsCurrent(event, requested, log) {
     const cliVersion = version ? { cliVersion: version } : {};
     if (!Array.isArray(event.tools)) {
         log.warn('claude-code announced no tool list, so this run has an unverified tool surface', {
-            requestedTools: [...requested],
+            ...(requested.length > 0 ? { requestedTools: [...requested] } : { toolsDeclared: false }),
             ...cliVersion,
         });
         return;
@@ -166,7 +170,7 @@ export function assertClaudeToolsCurrent(event, requested, log) {
     const granted = new Set(event.tools.filter((t) => typeof t === 'string'));
     const missing = CLAUDE_TOOL_FLOOR.filter((c) => !c.spellings.some((s) => granted.has(s))).map((c) => c.capability);
     const fields = {
-        requestedTools: [...requested],
+        ...(requested.length > 0 ? { requestedTools: [...requested] } : { toolsDeclared: false }),
         grantedTools: [...granted].sort(),
         ...cliVersion,
     };

package/dist/coding-agent.d.ts

@@ -200,6 +200,12 @@ export interface CodingAgentOutcome {
      * clean pass.
      */
     salvage?: SalvageReport;
+    /**
+     * This branch is NOTHING BUT salvage: the agent committed to it not once, and everything on it
+     * is files it left uncommitted in the checkout. Set only when a pull request would present that
+     * as a proposed change, so the caller can say so in the body before anyone reads the diff.
+     */
+    salvageOnly?: boolean;
 }
 export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions): Promise<CodingAgentOutcome>;
 /**
@@ -225,6 +231,8 @@ export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions)
  */
 export declare function withSalvagedWork(error: unknown, args: {
     dir: string;
+    /** The message the run's own commits carry, reused for the tracked edits rescued below. */
+    commitMessage: string;
     logger: Logger;
     pushWorkOnce: (override?: AbortSignal) => Promise<void>;
     inFlightPush: () => Promise<void> | null;

package/dist/coding-agent.js

@@ -11,7 +11,7 @@ import { runValidationLoop, } from './validation-checks.js';
 import { runReproductionLoop, } from './reproduction-proof.js';
 import { prepopulateDependencies, withDependencyNote, } from './dependency-install.js';
 import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
-import { describeSalvage, salvageUntrackedWork, } from './salvage.js';
+import { describeSalvage, foldSalvageReports, salvageUntrackedWork, } from './salvage.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
@@ -292,47 +292,24 @@ export async function runCodingAgent(spec, opts = {}) {
             // 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');
-            }
+            // Commit what the agent left uncommitted, BEFORE the two pre-PR phases below read the
+            // branch. See {@link settleAgentWork} for why the order is the whole point.
+            const { committedOwnWork, preGateSalvage } = await settleAgentWork(dir, spec, baseSha, logger, opts);
+            // BUGFIX REPRODUCTION PROOF, run before the validation loop below. See
+            // {@link runReproductionPhase} for why that order is load-bearing. A no-op when the job
+            // body carries no reproduction spec.
+            const reproductionReport = await runReproductionPhase({
+                dir,
+                spec,
+                baseSha,
+                resumed,
+                logger,
+                opts,
+                ...(serviceDirectory ? { serviceDirectory } : {}),
+                runAgentPass,
+                onAgentPass: foldPass,
+                listUncommittedNewFiles,
+            });
             // 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
@@ -358,6 +335,8 @@ export async function runCodingAgent(spec, opts = {}) {
             outcome = await finalizeCodingRun({
                 validationReport,
                 reproductionReport,
+                preGateSalvage,
+                committedOwnWork,
                 dir,
                 spec,
                 logger,
@@ -390,7 +369,13 @@ export async function runCodingAgent(spec, opts = {}) {
             // handed the rescue's push and a rescue starting behind a checkpoint would be handed a
             // push made BEFORE the salvage commit existed — reporting as pushed a commit that is not.
             clearInterval(checkpoint);
-            throw await withSalvagedWork(error, { dir, logger, pushWorkOnce, inFlightPush });
+            throw await withSalvagedWork(error, {
+                dir,
+                commitMessage: spec.commitMessage,
+                logger,
+                pushWorkOnce,
+                inFlightPush,
+            });
         }
         finally {
             // Safety net for the throw path (the happy path already cleared these above).
@@ -414,9 +399,16 @@ function withSalvageNote(summary, salvage) {
     const missedWork = salvage.status === 'refused' || salvage.status === 'failed';
     if (!missedWork && (salvage.withheld?.length ?? 0) === 0)
         return summary;
-    const note = describeSalvage(salvage);
+    const note = describeSalvage(salvage, SETTLED);
     return note ? `${note}\n\n${summary}` : summary;
 }
+/**
+ * How the run ended, for every salvage on the settle path: the agent finished, it simply never
+ * added these files. Named once because the commit message and the human-readable note are both
+ * given it, and a settle-path salvage that describes itself as an abort reports a failure that
+ * did not happen.
+ */
+const SETTLED = { kind: 'settled' };
 /**
  * How long the rescue of an aborted run's work gets, on its own clock.
  *
@@ -466,18 +458,30 @@ function rescueSignal() {
  */
 export async function withSalvagedWork(error, args) {
     const cause = error instanceof Error ? error.message : String(error);
+    const occasion = { kind: 'aborted', cause };
     const signal = rescueSignal();
     await drainInFlightPush(args.inFlightPush, args.logger);
+    // Edits to files git ALREADY tracks, committed under the run's own message before the salvage
+    // takes the untracked ones. On the settle path this has run several times already; here it has
+    // never run at all, and a killed agent leaves edits behind exactly as it leaves new files.
+    // Naming them separately is also what keeps the salvage's own count honest: `commitPaths`
+    // commits the paths it was given and no others, so anything not swept up here is simply lost.
+    // Best-effort: a failure here must not cost the salvage that follows it.
+    await commitTrackedEdits(args.dir, args.commitMessage, signal).catch((commitError) => {
+        args.logger.warn('coding-agent: could not commit the tracked edits an aborted run left', {
+            reason: commitError instanceof Error ? commitError.message : String(commitError),
+        });
+    });
     const note = await salvageUntrackedWork({
         dir: args.dir,
-        occasion: { kind: 'aborted', cause },
+        occasion,
         logger: args.logger,
         signal,
     })
         .then(async (report) => {
         if (report.status !== 'committed')
-            return describeSalvage(report);
-        return describeSalvage(report, await deliverSalvage(args, signal));
+            return describeSalvage(report, occasion);
+        return describeSalvage(report, occasion, await deliverSalvage(args, signal));
     })
         .catch((salvageError) => {
         args.logger.error('coding-agent: salvage of an aborted run failed', {
@@ -631,7 +635,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, reproductionReport, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, prTemplate, } = args;
+    const { validationReport, reproductionReport, preGateSalvage, committedOwnWork, dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, prTemplate, } = args;
     const { signal } = opts;
     const { stats, stderrTail, usage, callMetrics, effortReport } = agentRun;
     let outcome;
@@ -662,19 +666,21 @@ async function finalizeCodingRun(args) {
     const inflight = inFlightPush();
     if (inflight)
         await inflight.catch(() => { });
-    // Recover the untracked, non-ignored files the agent left behind. `commitTrackedEdits` above
-    // only captures edits to ALREADY tracked files, so a NEW file the agent created and forgot to
-    // commit used to be listed, warned about and dropped — and on a greenfield task EVERY file is
-    // new, which made that warning the whole deliverable going in the bin. Observable is not
-    // recovered, so commit them. Guardrails (a dependency/build deny-list, a file-count and byte
-    // bound, an all-or-nothing refusal over it) live in `salvage.ts`; this path is coding mode by
-    // construction, which is the other rule it must obey.
-    const salvage = await salvageUntrackedWork({
+    // The MOP-UP salvage. The caller already ran one ahead of the pre-PR phases (see there for why
+    // the order matters); this second pass exists because a validation or reproduction REPAIR round
+    // runs the agent afresh and can leave new files of its own after that first pass. On a run with
+    // no repair round it finds nothing and folds away to the earlier report.
+    const salvage = foldSalvageReports(preGateSalvage, await salvageUntrackedWork({
         dir,
-        occasion: { kind: 'settled' },
+        occasion: SETTLED,
         logger,
         ...(signal ? { signal } : {}),
-    });
+    }));
+    // A branch whose ENTIRE content is salvage is not a change anyone proposed, and its reviewer has
+    // to be told that before reading it as one. `committedOwnWork` is the caller's pre-salvage read;
+    // a RESUMED run carries prior commits of the agent's own regardless of what this pass added, so
+    // it is never salvage-only. The multi-repo path marks its peer PRs the same way.
+    const salvageOnly = !resumed && !committedOwnWork && salvage.status === 'committed';
     // A salvage that COMMITTED needs no announcement: its files are in the push and its commit
     // message says where they came from. A refused or failed one means work the agent produced is
     // NOT in the pull request, on a run that otherwise reads as a clean pass — so say it in the
@@ -728,6 +734,7 @@ async function finalizeCodingRun(args) {
             ...(effortReport ? { effortReport } : {}),
             ...(prDescription ? { prDescription } : {}),
             ...(salvage.status === 'none' ? {} : { salvage }),
+            ...(salvageOnly ? { salvageOnly: true } : {}),
         };
     }
     // Ralph loop: run the programmatic completion command against the pushed/committed
@@ -758,14 +765,103 @@ async function finalizeCodingRun(args) {
  *
  * Commits forgotten edits to tracked files first, exactly as {@link finalizeCodingRun} does, so
  * an agent that edited-but-didn't-commit still counts as work. That call is idempotent, so
- * finalize repeating it later is a no-op. Uncommitted NEW files are invisible here — but they
- * are equally invisible to finalize, so a run whose only product is an uncommitted new file is
- * a no-op on both paths, and the checks would have nothing to gate anyway.
+ * finalize repeating it later is a no-op.
+ *
+ * Uncommitted NEW files are invisible to it, which is why {@link settleAgentWork} runs ahead of
+ * every caller and commits them. Reading commits is the whole point of this gate, and it used to
+ * mean that a run whose only product was new files (a greenfield task, where that is ALL of
+ * them) answered `false` here and skipped the checks, only for the salvage to commit the lot
+ * afterwards and open a pull request nothing had validated.
  */
 async function producedWork(dir, spec, baseSha, resumed, opts) {
     await commitTrackedEdits(dir, spec.commitMessage, opts.signal);
     return resumed || (await branchHasCommitsSince(dir, baseSha, opts.signal));
 }
+/**
+ * The 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 pre-PR validation loop, 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 ⇒ `undefined` and
+ * the flow around it is byte-for-byte what it was.
+ */
+async function runReproductionPhase(args) {
+    const { dir, spec, baseSha, resumed, logger, opts, serviceDirectory } = args;
+    const { signal } = opts;
+    const reproduction = spec.reproduction;
+    if (!reproduction || !(await producedWork(dir, spec, baseSha, resumed, opts)))
+        return undefined;
+    opts.onPhase?.('reproduction');
+    const report = 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: args.runAgentPass,
+        onAgentPass: args.onAgentPass,
+        listUncommittedNewFiles: args.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');
+    return report;
+}
+/**
+ * Commit everything the settled agent left behind, and say whether the branch already carried
+ * commits of its OWN before that.
+ *
+ * Runs between the agent and the two pre-PR phases, and the ORDER is the whole point. Both phases
+ * are gated on {@link producedWork}, which reads COMMITS. The salvage used to run last, at the
+ * settle, which left that gate false for exactly the runs the salvage exists to save: a greenfield
+ * task whose every file is new and uncommitted skipped the validation loop entirely, and then
+ * opened a pull request with no validation report at all, so "only a green checkout opens a PR"
+ * held for every run except those. Committing first is what puts that work in front of the gate.
+ *
+ * `commitTrackedEdits` only captures edits to files git ALREADY tracks, so a NEW file the agent
+ * created and forgot to add used to be listed, warned about and dropped. Guardrails on what may be
+ * swept up (a dependency/build deny-list, a file-count and byte bound, an all-or-nothing refusal
+ * over it) live in `salvage.ts`; this path is coding mode by construction, which is the other rule
+ * it must obey.
+ *
+ * `committedOwnWork` is read BETWEEN the two, and that is not incidental. Afterwards the salvage's
+ * own commit makes the branch look advanced, and the two are not the same claim: work the agent
+ * committed is a change it chose to make, where a salvage-only branch is one built entirely out of
+ * what it left lying in the checkout. Only the second has to say so on the pull request it opens.
+ *
+ * A repair round runs the agent afresh and can leave new files of its own, so `finalizeCodingRun`
+ * runs a second, mop-up pass and folds the two reports.
+ */
+async function settleAgentWork(dir, spec, baseSha, logger, opts) {
+    const { signal } = opts;
+    await commitTrackedEdits(dir, spec.commitMessage, signal);
+    const committedOwnWork = await branchHasCommitsSince(dir, baseSha, signal);
+    const preGateSalvage = await salvageUntrackedWork({
+        dir,
+        occasion: SETTLED,
+        logger,
+        ...(signal ? { signal } : {}),
+    });
+    return { committedOwnWork, preGateSalvage };
+}
 /**
  * Fold a pre-PR validation REPAIR pass's run into the accumulated agent outcome, so a looped run
  * reports what every round actually spent rather than only the first. Counts and telemetry are