@cat-factory/executor-harness 1.137.0 → 1.139.1

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,6 +11,7 @@ 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';
@@ -794,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 } : {};
@@ -866,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

package/dist/git.d.ts

@@ -185,6 +185,13 @@ export declare function workingTreeStatus(dir: string, signal?: AbortSignal): Pr
  * path in ONE command, that one name discards the whole all-or-nothing salvage, exactly as an
  * unquoted accented name did. `:(literal)` matches the entry as itself and nothing else.
  *
+ * The commit is SCOPED to those same pathspecs, and so is the staged-anything check above it. A
+ * bare `git commit` takes whatever the index holds, which is not the same set: an agent killed
+ * mid-flight leaves its own `git add` staged, and that content would then land under a message
+ * naming only the paths passed here, counted by a caller that had never looked at it. The commit
+ * and the claim made about it have to describe ONE set of files. Content the agent staged and this
+ * call did not name stays staged for whoever commits it next.
+ *
  * The caller has already decided WHICH paths belong; this only commits them.
  */
 export declare function commitPaths(dir: string, paths: string[], message: string, signal?: AbortSignal): Promise<string | null>;

package/dist/git.js

@@ -526,16 +526,27 @@ export async function workingTreeStatus(dir, signal) {
  * path in ONE command, that one name discards the whole all-or-nothing salvage, exactly as an
  * unquoted accented name did. `:(literal)` matches the entry as itself and nothing else.
  *
+ * The commit is SCOPED to those same pathspecs, and so is the staged-anything check above it. A
+ * bare `git commit` takes whatever the index holds, which is not the same set: an agent killed
+ * mid-flight leaves its own `git add` staged, and that content would then land under a message
+ * naming only the paths passed here, counted by a caller that had never looked at it. The commit
+ * and the claim made about it have to describe ONE set of files. Content the agent staged and this
+ * call did not name stays staged for whoever commits it next.
+ *
  * The caller has already decided WHICH paths belong; this only commits them.
  */
 export async function commitPaths(dir, paths, message, signal) {
     if (paths.length === 0)
         return null;
-    await git(['add', '--', ...paths.map(literalPathspec)], { cwd: dir, signal });
-    const staged = await git(['diff', '--cached', '--name-only'], { cwd: dir, signal });
+    const pathspecs = paths.map(literalPathspec);
+    await git(['add', '--', ...pathspecs], { cwd: dir, signal });
+    const staged = await git(['diff', '--cached', '--name-only', '--', ...pathspecs], {
+        cwd: dir,
+        signal,
+    });
     if (staged.trim() === '')
         return null;
-    await git(['commit', '-m', message], { cwd: dir, signal });
+    await git(['commit', '-m', message, '--', ...pathspecs], { cwd: dir, signal });
     return headCommit(dir, signal);
 }
 /** One path as a pathspec that matches only itself — see {@link commitPaths} for why. */

package/dist/multi-repo-coding.js

@@ -2,7 +2,7 @@ import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { makeDirClaimer } from './checkout-dir.js';
 import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
-import { salvageOnlyNotice, salvageUntrackedWork } from './salvage.js';
+import { salvageUntrackedWork, withSalvageOnlyNote } from './salvage.js';
 import { openPullRequest } from './vcs-api.js';
 import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription } from './pr-description.js';
 import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js';
@@ -305,16 +305,6 @@ async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
 export function probeDirsForLegs(legs) {
     return legs.filter((leg) => !leg.readOnly).map((leg) => leg.dir);
 }
-/**
- * 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.
- */
-function withSalvageOnlyNote(pr, salvageOnly) {
-    return salvageOnly ? { ...pr, body: `${salvageOnlyNotice()}\n\n${pr.body}` } : pr;
-}
 /**
  * Push phase for {@link runMultiRepoCoding}: commit forgotten tracked edits, then push + open a PR
  * for each repo the run actually changed (a repo the agent left untouched is skipped — no branch,

package/dist/salvage.d.ts

@@ -126,6 +126,28 @@ export declare function salvageUntrackedWork(args: {
     signal?: AbortSignal;
     bounds?: SalvageBounds;
 }): Promise<SalvageReport>;
+/**
+ * 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 declare function foldSalvageReports(previous: SalvageReport, next: SalvageReport): SalvageReport;
 /**
  * How the run that left these files behind ended. It decides what the commit message SAYS, which
  * is the whole point of marking a salvage: a commit arriving on a branch with no explanation is
@@ -159,6 +181,21 @@ export declare function salvageCommitMessage(fileCount: number, occasion: Salvag
  * into describing it differently. The caller decides WHERE it goes.
  */
 export declare function salvageOnlyNotice(): string;
+/**
+ * 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 declare function withSalvageOnlyNote<T extends {
+    body: string;
+}>(pr: T, salvageOnly: boolean): T;
 /**
  * Where a salvage commit ENDED UP, which the salvage itself cannot know: it commits, and someone
  * else pushes. A commit that was not pushed dies with the container exactly as the uncommitted
@@ -174,7 +211,13 @@ export interface SalvageDelivery {
  * 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 declare function describeSalvage(report: SalvageReport, delivery?: SalvageDelivery): string | undefined;
+export declare function describeSalvage(report: SalvageReport, occasion: SalvageOccasion, delivery?: SalvageDelivery): string | undefined;