@cat-factory/executor-harness 1.137.0 → 1.139.0

package/dist/salvage.js

@@ -206,6 +206,59 @@ export async function salvageUntrackedWork(args) {
         return { status: 'failed', ...report, reason };
     }
 }
+/**
+ * Fold a later salvage pass onto an earlier one, so a run that salvaged TWICE reports what both
+ * passes did rather than only the last.
+ *
+ * A coding run salvages at each point where the next thing to happen reads COMMITS rather than the
+ * working tree: once before the pre-PR gates (which is what lets them run at all on a run whose
+ * only product is untracked files), and again at the settle, because a gate's repair round runs
+ * the agent afresh and can leave new files of its own. On almost every run the second pass is
+ * `none` (the first one already committed everything), so this is a cheap way to keep ONE honest
+ * report instead of two half-truths.
+ *
+ * Counts are summed only when BOTH passes committed, because only then are the two sets disjoint.
+ * A pass that refused or failed sees the same files again on the next pass, so summing there would
+ * double-count the one loss; instead the more significant status wins outright, `failed` over
+ * `refused` over `committed`, on the rule that a pass which could NOT keep its files is the fact a
+ * human has to act on and must not be hidden by a later pass that found nothing left to do. Ties
+ * take the later pass, whose numbers are the current ones.
+ *
+ * `withheld` is always the union: a credential-bearing file either pass declined to commit has to
+ * be named whatever else happened, since naming it is what lets someone rotate what it held.
+ */
+export function foldSalvageReports(previous, next) {
+    if (next.status === 'none')
+        return withWithheld(previous, next);
+    if (previous.status === 'none')
+        return withWithheld(next, previous);
+    if (previous.status === 'committed' && next.status === 'committed') {
+        return withWithheld({
+            status: 'committed',
+            files: [...previous.files, ...next.files].slice(0, REPORTED_PATHS),
+            fileCount: previous.fileCount + next.fileCount,
+            totalBytes: previous.totalBytes + next.totalBytes,
+            ...((next.commitSha ?? previous.commitSha)
+                ? { commitSha: next.commitSha ?? previous.commitSha }
+                : {}),
+        }, previous);
+    }
+    return SALVAGE_STATUS_RANK[previous.status] > SALVAGE_STATUS_RANK[next.status]
+        ? withWithheld(previous, next)
+        : withWithheld(next, previous);
+}
+/** Which status a fold keeps when the two passes disagree; see {@link foldSalvageReports}. */
+const SALVAGE_STATUS_RANK = {
+    none: 0,
+    committed: 1,
+    refused: 2,
+    failed: 3,
+};
+/** `kept` with `other`'s withheld paths merged in, de-duplicated and order-preserving. */
+function withWithheld(kept, other) {
+    const union = [...new Set([...(kept.withheld ?? []), ...(other.withheld ?? [])])];
+    return union.length > 0 ? { ...kept, withheld: union } : kept;
+}
 /** The salvage commit's message: what it is, why it exists, and how much to trust it. */
 export function salvageCommitMessage(fileCount, occasion) {
     const noun = fileCount === 1 ? 'file' : 'files';
@@ -240,6 +293,21 @@ export function salvageOnlyNotice() {
         `not be discarded with the container. Nothing has reviewed them for completeness or ` +
         `relevance, and some may be scratch work from the agent's task in a sibling repository.`);
 }
+/**
+ * Put {@link salvageOnlyNotice} at the top of a pull request that is nothing but a salvage.
+ *
+ * Only the BODY is marked. A title carrying it would follow the PR into every list and
+ * notification a maintainer sees, which is a lot of noise for a caveat that belongs beside the
+ * diff, and the salvage commit's own message elaborates on it there.
+ *
+ * Lives here rather than beside either caller because BOTH open pull requests off a salvage-only
+ * branch: the multi-repo push phase, per leg, and the single-repo one. It was the multi-repo path
+ * alone for a while, which meant the same branch shape opened an unmarked PR depending only on how
+ * many repositories the run happened to clone.
+ */
+export function withSalvageOnlyNote(pr, salvageOnly) {
+    return salvageOnly ? { ...pr, body: `${salvageOnlyNotice()}\n\n${pr.body}` } : pr;
+}
 /** Total size of `paths` under `dir`; a file that cannot be stat'd counts as zero rather than failing. */
 async function measure(dir, paths) {
     const sizes = await Promise.all(paths.map((path) => stat(join(dir, path)).then((info) => info.size, () => 0)));
@@ -250,15 +318,21 @@ async function measure(dir, paths) {
  * reports, so the person reading "the run was killed" is told in the same breath what became of
  * its work: on the branch and reviewed by nobody, still in the container, or never committed.
  *
+ * `occasion` is the SAME fact {@link salvageCommitMessage} is given, and for the same reason: how
+ * the run ended is what decides how much to trust the files. A run that was killed left them
+ * mid-thought; a run that settled simply never added them, and telling a human a clean run "was
+ * aborted" describes a failure that did not happen. The two texts had drifted precisely here,
+ * which is why the occasion is now a parameter of both rather than a constant inside one.
+ *
  * `delivery` is supplied by whoever pushed. Absent means the caller is on a path where the
  * ordinary push follows (the settle path), so there is nothing extra to say.
  */
-export function describeSalvage(report, delivery) {
-    const parts = [describeOutcome(report, delivery), describeWithheld(report)].filter((part) => part !== undefined);
+export function describeSalvage(report, occasion, delivery) {
+    const parts = [describeOutcome(report, occasion, delivery), describeWithheld(report)].filter((part) => part !== undefined);
     return parts.length > 0 ? parts.join(' ') : undefined;
 }
 /** The fate of the files the salvage DID try to keep. */
-function describeOutcome(report, delivery) {
+function describeOutcome(report, occasion, delivery) {
     switch (report.status) {
         case 'none':
             return undefined;
@@ -267,8 +341,11 @@ function describeOutcome(report, delivery) {
                 ? `commit ${report.commitSha ?? 'unknown'}, which could NOT be pushed ` +
                     `(${delivery.reason ?? 'the push failed'}) and so is lost with the container`
                 : `commit ${report.commitSha ?? 'unknown'}`;
+            const why = occasion.kind === 'aborted'
+                ? 'this run was aborted'
+                : 'the agent finished without committing them';
             return (`${report.fileCount} uncommitted new file(s) the agent left behind were salvaged into ` +
-                `${landed}; this run was aborted, so review them before trusting them.`);
+                `${landed}; ${why}, so review them before trusting them.`);
         }
         case 'refused':
             return `Uncommitted new files were NOT salvaged: ${report.reason ?? 'over the salvage bounds'}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.137.0",
+  "version": "1.139.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",
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@cat-factory/kernel": "0.321.0",
-    "@cat-factory/server": "0.306.6",
+    "@cat-factory/server": "0.306.7",
     "@cat-factory/spend": "0.16.17",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",

package/src/agent-runner.ts

@@ -683,6 +683,17 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // 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 })
@@ -730,7 +741,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     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
@@ -820,7 +831,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     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 },

package/src/agent.ts

@@ -31,6 +31,7 @@ import {
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.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'
@@ -945,6 +946,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     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`.
@@ -1020,8 +1022,10 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       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/src/claude-cli.ts

@@ -141,6 +141,18 @@ export 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. */
@@ -160,8 +172,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,
   ]
@@ -180,6 +191,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: Record<string, unknown>,
@@ -192,7 +208,7 @@ export function assertClaudeToolsCurrent(
   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
@@ -202,7 +218,7 @@ export function assertClaudeToolsCurrent(
     (c) => c.capability,
   )
   const fields = {
-    requestedTools: [...requested],
+    ...(requested.length > 0 ? { requestedTools: [...requested] } : { toolsDeclared: false }),
     grantedTools: [...granted].sort(),
     ...cliVersion,
   }

package/src/coding-agent.ts

@@ -68,8 +68,10 @@ import {
 } from './pr-template.js'
 import {
   describeSalvage,
+  foldSalvageReports,
   salvageUntrackedWork,
   type SalvageDelivery,
+  type SalvageOccasion,
   type SalvageReport,
 } from './salvage.js'
 
@@ -267,6 +269,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
 }
 
 /**
@@ -597,54 +605,31 @@ export async function runCodingAgent(
         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')
-        }
+        // 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
@@ -670,6 +655,8 @@ export async function runCodingAgent(
         outcome = await finalizeCodingRun({
           validationReport,
           reproductionReport,
+          preGateSalvage,
+          committedOwnWork,
           dir,
           spec,
           logger,
@@ -701,7 +688,13 @@ export async function runCodingAgent(
         // 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).
         clearInterval(checkpoint)
@@ -724,10 +717,18 @@ export async function runCodingAgent(
 function withSalvageNote(summary: string, salvage: SalvageReport): string {
   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: SalvageOccasion = { kind: 'settled' }
+
 /**
  * How long the rescue of an aborted run's work gets, on its own clock.
  *
@@ -781,23 +782,37 @@ export async 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
   },
 ): Promise<unknown> {
   const cause = error instanceof Error ? error.message : String(error)
+  const occasion: SalvageOccasion = { 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: unknown) => {
+    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))
+      if (report.status !== 'committed') return describeSalvage(report, occasion)
+      return describeSalvage(report, occasion, await deliverSalvage(args, signal))
     })
     .catch((salvageError: unknown) => {
       args.logger.error('coding-agent: salvage of an aborted run failed', {
@@ -975,6 +990,10 @@ async function finalizeCodingRun(args: {
   validationReport?: ValidationReport
   /** The reproduction proof's last attempt, attached to the outcome (absent when unconfigured). */
   reproductionReport?: ReproductionReport
+  /** What the salvage pass that ran ahead of the pre-PR phases recovered; folded with the mop-up. */
+  preGateSalvage: SalvageReport
+  /** Whether the branch carried commits of the agent's OWN, read before that salvage committed. */
+  committedOwnWork: boolean
   dir: string
   spec: CodingAgentSpec
   logger: Logger
@@ -994,6 +1013,8 @@ async function finalizeCodingRun(args: {
   const {
     validationReport,
     reproductionReport,
+    preGateSalvage,
+    committedOwnWork,
     dir,
     spec,
     logger,
@@ -1043,19 +1064,24 @@ 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({
-    dir,
-    occasion: { kind: 'settled' },
-    logger,
-    ...(signal ? { signal } : {}),
-  })
+  // 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: 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
@@ -1109,6 +1135,7 @@ async function finalizeCodingRun(args: {
       ...(effortReport ? { effortReport } : {}),
       ...(prDescription ? { prDescription } : {}),
       ...(salvage.status === 'none' ? {} : { salvage }),
+      ...(salvageOnly ? { salvageOnly: true } : {}),
     }
   }
 
@@ -1139,9 +1166,13 @@ 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: string,
@@ -1154,6 +1185,110 @@ async function producedWork(
   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<TRun>(args: {
+  dir: string
+  spec: CodingAgentSpec
+  baseSha: string
+  resumed: boolean
+  logger: Logger
+  opts: RunOptions
+  serviceDirectory?: string
+  runAgentPass: (userPrompt: string) => Promise<TRun>
+  onAgentPass: (run: TRun) => void
+  listUncommittedNewFiles: () => Promise<string[]>
+}): Promise<ReproductionReport | undefined> {
+  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: string,
+  spec: CodingAgentSpec,
+  baseSha: string,
+  logger: Logger,
+  opts: RunOptions,
+): Promise<{ committedOwnWork: boolean; preGateSalvage: SalvageReport }> {
+  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