@cat-factory/executor-harness 1.132.3 → 1.135.0

package/dist/pi.js

@@ -3,11 +3,13 @@ import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
+import { agentChildEnv } from './agent-env.js';
 import { pathExists } from './fs-utils.js';
 import { redactSecrets, secretsToRedact } from './redact.js';
 import { HarnessFailure } from './failure.js';
 import { log } from './logger.js';
 import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './progress-guard.js';
+import { createGuardDriver } from './guard-driver.js';
 import { ToolCallTracker, readToolCallId, toolCallResult, toolCallStart, } from './tool-trajectory.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
 import { PI_MAX_OUTPUT_TOKENS, PiRunReducer, isObject, } from './pi-reduction.js';
@@ -562,7 +564,7 @@ export function runPi(opts) {
         }
         const child = spawn('pi', ['-p', '--mode', 'json', '--model', `proxy/${opts.model}`, '--approve'], {
             cwd: opts.cwd,
-            env: { ...process.env, ...opts.extraEnv, PI_PROXY_TOKEN: opts.sessionToken },
+            env: agentChildEnv(opts.extraEnv, { PI_PROXY_TOKEN: opts.sessionToken }),
             // stdin is piped (not 'ignore') so the prompt is delivered out-of-band
             // rather than on argv — see the function doc for the injection rationale.
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -597,7 +599,6 @@ export function runPi(opts) {
         // spam): `{`-leading lines that failed to JSON.parse, and observer-callback throws.
         let malformedLines = 0;
         let observerErrors = 0;
-        const guard = new ProgressGuard(opts.guardLimits ?? progressGuardLimitsFromEnv(), opts.expectsEdits ?? true);
         // Pairs each tool call's start with its result, numbers the pairs and captures the two
         // bodies (scrubbed + capped). A call whose start Pi never emitted still gets an entry,
         // timed from the previous call's end — see `ToolCallTracker`.
@@ -612,6 +613,17 @@ export function runPi(opts) {
         // SIGTERM first, then SIGKILL if Pi ignores it. Shared by the watchdog abort
         // and the no-progress guard; the `close` handler turns it into a rejection.
         const killChild = () => killChildProcess(child);
+        // The guard, plus the driver that settles its one bound needing evidence from outside this
+        // stream (see `guard-driver.ts`). `processLine` is a synchronous reader, so the driver owns
+        // the probe's lifetime rather than this handler awaiting inside it.
+        const guardDriver = createGuardDriver({
+            guard: new ProgressGuard(opts.guardLimits ?? progressGuardLimitsFromEnv(), opts.expectsEdits ?? true),
+            probe: opts.workspaceProbe,
+            onAbort: (reason) => {
+                guardReason = reason;
+                killChild();
+            },
+        });
         // Parse each complete JSONL record once, retaining it for the close-of-run reductions and
         // feeding the todo-progress emitter and the no-progress guard. A tripped guard kills Pi
         // with a diagnostic the run then fails on.
@@ -668,13 +680,8 @@ export function runPi(opts) {
                     }
                 }
             }
-            if (!final && !guardReason && !aborted) {
-                const reason = guard.observe(event);
-                if (reason) {
-                    guardReason = reason;
-                    killChild();
-                }
-            }
+            if (!final && !guardReason && !aborted)
+                guardDriver.observeEvent(event);
         };
         // Pi's json mode is strict LF-framed JSONL; the reader buffers partial records across
         // chunks (bounded — see `JsonlLineReader`) so we only ever parse complete ones.

package/dist/progress-guard.d.ts

@@ -82,11 +82,35 @@ export declare function progressGuardLimitsFromEnv(env?: NodeJS.ProcessEnv): Pro
  */
 export declare function mergeGuardLimits(base: ProgressGuardLimits, overrides: Partial<ProgressGuardLimits> | undefined): ProgressGuardLimits;
 /**
- * Live anti-rabbithole guard: fed each streamed Pi event, it returns a diagnostic
- * reason the moment a run has plainly stopped making progress, so the harness can
- * kill Pi early instead of letting it burn the whole budget (and then surface a
- * useful failure instead of a generic "no file changes"). Pure and incremental so
- * it can be unit-tested over a fixed event sequence.
+ * What the guard concluded from one tool-call signal.
+ *
+ * `abort` is a settled judgement the caller acts on immediately: every STREAK bound
+ * (consecutive errors / web calls / MCP calls / non-action calls) reads only the stream, so the
+ * stream is all the evidence there is.
+ *
+ * `needs-workspace-evidence` is the no-edit bound, and it is deliberately NOT settled. That bound
+ * asks "has this run changed the repository yet", and the tool names are only a proxy for it: an
+ * agent writing files through `bash` reads as forty calls and no edits however much work it did.
+ * So the guard hands the question back with the diagnostic it would abort on, and the caller
+ * answers it from the working tree (see `workspace-probe.ts`) before anything is killed.
+ */
+export type ProgressVerdict = {
+    kind: 'abort';
+    reason: string;
+} | {
+    kind: 'needs-workspace-evidence';
+    reason: string;
+};
+/**
+ * Live anti-rabbithole guard: fed each streamed tool-call signal, it returns a {@link
+ * ProgressVerdict} the moment a run has plainly stopped making progress, so the harness can kill
+ * the CLI early instead of letting it burn the whole budget (and then surface a useful failure
+ * instead of a generic "no file changes").
+ *
+ * PURE, SYNCHRONOUS and INCREMENTAL, so it can be unit-tested over a fixed event sequence: it
+ * spawns nothing and reads nothing off disk. The one bound that needs evidence from outside the
+ * stream says so in its verdict and lets the caller fetch it, then reports the answer back
+ * through {@link noteWorkspaceMutation} / {@link rearmNoEditBound}.
  */
 export declare class ProgressGuard {
     private readonly limits;
@@ -98,14 +122,36 @@ export declare class ProgressGuard {
     private consecutiveWebCalls;
     private consecutiveMcpCalls;
     private consecutiveNonActionCalls;
+    private awaitingWorkspaceEvidence;
     constructor(limits: ProgressGuardLimits, 
     /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
     expectsEdits?: boolean);
-    /** Feed one parsed Pi event; returns a diagnostic reason when the run should abort, else null. */
-    observe(event: Record<string, unknown>): string | null;
+    /** Feed one parsed Pi event; returns a {@link ProgressVerdict} when the run is in trouble, else null. */
+    observe(event: Record<string, unknown>): ProgressVerdict | null;
+    /**
+     * Record that the run HAS changed the repository, however it did it. Satisfies the no-edit
+     * bound permanently, exactly as a recognised edit-tool call does, matching that bound's
+     * existing semantics: it guards a run only UNTIL its first edit, because an agent that has
+     * changed the tree has demonstrably started the work.
+     *
+     * Called by the driver when a workspace probe answers a `needs-workspace-evidence` verdict
+     * positively. Idempotent, and cheap enough that a caller who probes for other reasons may also
+     * report through it.
+     */
+    noteWorkspaceMutation(): void;
+    /**
+     * Re-arm the no-edit bound after a probe that could answer NEITHER way (it threw). The bound
+     * becomes trippable again once another `maxToolCallsWithoutEdit` action calls have gone by,
+     * rather than the run being killed on a git failure or left permanently unguarded by one.
+     *
+     * Failing open here is the deliberate half: killing a productive run is the expensive error,
+     * and the streak bounds, the inactivity watchdog and the job's wall-clock cap all still hold
+     * the run in the meantime.
+     */
+    rearmNoEditBound(): void;
     /**
-     * Feed one already-parsed tool-call signal (name + error flag), returning a diagnostic reason
-     * when the run should abort, else null. Split out of {@link observe} so a caller whose stream
+     * Feed one already-parsed tool-call signal (name + error flag), returning a {@link
+     * ProgressVerdict} when a bound is reached, else null. Split out of {@link observe} so a caller whose stream
      * is NOT Pi's `tool_execution_end` envelope — the claude-code runner, which correlates a
      * `tool_use` block's name with its `tool_result`'s `is_error` — can drive the SAME guard logic
      * without synthesising a fake Pi event.
@@ -113,5 +159,5 @@ export declare class ProgressGuard {
     observeSignal(tool: {
         name: string;
         isError: boolean;
-    }): string | null;
+    }): ProgressVerdict | null;
 }

package/dist/progress-guard.js

@@ -43,8 +43,14 @@ export const DEFAULT_PROGRESS_GUARD_LIMITS = {
 // broad on purpose: different models/extensions name the same capability differently
 // (`edit`/`write`, but also `apply_patch`/`patch`/`str_replace`/`multiedit`/`create`),
 // and a false "no edits" reading would kill a run that IS making changes. Matched
-// case-insensitively. NOTE: a file written purely via `bash` (e.g. a heredoc) is not
-// recognised here — broaden or move to a working-tree signal if that becomes common.
+// case-insensitively.
+//
+// A file written purely through `bash` (a heredoc, `sed -i`, `node -e`) is NOT recognised here,
+// and deliberately so: this set answers "did the model call a tool we already know edits files",
+// which is a cheap SUFFICIENT condition and never a necessary one. The necessary one is the
+// working tree itself, which is what the no-edit bound now actually decides on: see the
+// `needs-workspace-evidence` verdict and {@link ProgressGuard.noteWorkspaceMutation}. A hit here
+// still satisfies the bound outright, so the common case never pays for a probe.
 const FILE_EDIT_TOOLS = new Set([
     'edit',
     'write',
@@ -170,11 +176,15 @@ export function mergeGuardLimits(base, overrides) {
     };
 }
 /**
- * Live anti-rabbithole guard: fed each streamed Pi event, it returns a diagnostic
- * reason the moment a run has plainly stopped making progress, so the harness can
- * kill Pi early instead of letting it burn the whole budget (and then surface a
- * useful failure instead of a generic "no file changes"). Pure and incremental so
- * it can be unit-tested over a fixed event sequence.
+ * Live anti-rabbithole guard: fed each streamed tool-call signal, it returns a {@link
+ * ProgressVerdict} the moment a run has plainly stopped making progress, so the harness can kill
+ * the CLI early instead of letting it burn the whole budget (and then surface a useful failure
+ * instead of a generic "no file changes").
+ *
+ * PURE, SYNCHRONOUS and INCREMENTAL, so it can be unit-tested over a fixed event sequence: it
+ * spawns nothing and reads nothing off disk. The one bound that needs evidence from outside the
+ * stream says so in its verdict and lets the caller fetch it, then reports the answer back
+ * through {@link noteWorkspaceMutation} / {@link rearmNoEditBound}.
  */
 export class ProgressGuard {
     limits;
@@ -185,13 +195,18 @@ export class ProgressGuard {
     consecutiveWebCalls = 0;
     consecutiveMcpCalls = 0;
     consecutiveNonActionCalls = 0;
+    // Set when the no-edit bound has been reported as `needs-workspace-evidence` and the caller's
+    // probe has not answered yet. It suppresses a second report: the bound is a threshold, so every
+    // action call past it would otherwise re-raise the same unanswered question and the caller would
+    // probe git once per tool call. Cleared by whichever answer comes back.
+    awaitingWorkspaceEvidence = false;
     constructor(limits, 
     /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
     expectsEdits = true) {
         this.limits = limits;
         this.expectsEdits = expectsEdits;
     }
-    /** Feed one parsed Pi event; returns a diagnostic reason when the run should abort, else null. */
+    /** Feed one parsed Pi event; returns a {@link ProgressVerdict} when the run is in trouble, else null. */
     observe(event) {
         const tool = toolCallSignal(event);
         if (!tool)
@@ -199,8 +214,35 @@ export class ProgressGuard {
         return this.observeSignal(tool);
     }
     /**
-     * Feed one already-parsed tool-call signal (name + error flag), returning a diagnostic reason
-     * when the run should abort, else null. Split out of {@link observe} so a caller whose stream
+     * Record that the run HAS changed the repository, however it did it. Satisfies the no-edit
+     * bound permanently, exactly as a recognised edit-tool call does, matching that bound's
+     * existing semantics: it guards a run only UNTIL its first edit, because an agent that has
+     * changed the tree has demonstrably started the work.
+     *
+     * Called by the driver when a workspace probe answers a `needs-workspace-evidence` verdict
+     * positively. Idempotent, and cheap enough that a caller who probes for other reasons may also
+     * report through it.
+     */
+    noteWorkspaceMutation() {
+        this.edits++;
+        this.awaitingWorkspaceEvidence = false;
+    }
+    /**
+     * Re-arm the no-edit bound after a probe that could answer NEITHER way (it threw). The bound
+     * becomes trippable again once another `maxToolCallsWithoutEdit` action calls have gone by,
+     * rather than the run being killed on a git failure or left permanently unguarded by one.
+     *
+     * Failing open here is the deliberate half: killing a productive run is the expensive error,
+     * and the streak bounds, the inactivity watchdog and the job's wall-clock cap all still hold
+     * the run in the meantime.
+     */
+    rearmNoEditBound() {
+        this.toolCalls = 0;
+        this.awaitingWorkspaceEvidence = false;
+    }
+    /**
+     * Feed one already-parsed tool-call signal (name + error flag), returning a {@link
+     * ProgressVerdict} when a bound is reached, else null. Split out of {@link observe} so a caller whose stream
      * is NOT Pi's `tool_execution_end` envelope — the claude-code runner, which correlates a
      * `tool_use` block's name with its `tool_result`'s `is_error` — can drive the SAME guard logic
      * without synthesising a fake Pi event.
@@ -211,8 +253,11 @@ export class ProgressGuard {
         // isn't wedged in a failing-op loop), so it's updated before the planning skip.
         this.consecutiveErrors = tool.isError ? this.consecutiveErrors + 1 : 0;
         if (this.consecutiveErrors >= this.limits.maxConsecutiveErrors) {
-            return (`no progress: ${this.consecutiveErrors} consecutive failing tool calls — the agent is stuck ` +
-                `retrying a failing operation rather than making progress. Aborting.`);
+            return {
+                kind: 'abort',
+                reason: `no progress: ${this.consecutiveErrors} consecutive failing tool calls — the agent is stuck ` +
+                    `retrying a failing operation rather than making progress. Aborting.`,
+            };
         }
         // Web search/fetch loop: web tools are read-only (they don't count toward the
         // no-edit bound), so guard them separately — an uninterrupted streak of them is a
@@ -221,8 +266,11 @@ export class ProgressGuard {
             this.consecutiveWebCalls++;
             const webCap = this.limits.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls;
             if (this.consecutiveWebCalls >= webCap) {
-                return (`no progress: ${this.consecutiveWebCalls} consecutive web search/fetch calls without ` +
-                    `any other action — the agent is stuck researching instead of doing the work. Aborting.`);
+                return {
+                    kind: 'abort',
+                    reason: `no progress: ${this.consecutiveWebCalls} consecutive web search/fetch calls without ` +
+                        `any other action — the agent is stuck researching instead of doing the work. Aborting.`,
+                };
             }
         }
         else {
@@ -235,9 +283,12 @@ export class ProgressGuard {
             this.consecutiveMcpCalls++;
             const mcpCap = this.limits.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls;
             if (this.consecutiveMcpCalls >= mcpCap) {
-                return (`no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
-                    `any other action. The agent is stuck querying its tools instead of doing the work. ` +
-                    `Aborting.`);
+                return {
+                    kind: 'abort',
+                    reason: `no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
+                        `any other action. The agent is stuck querying its tools instead of doing the work. ` +
+                        `Aborting.`,
+                };
             }
         }
         else {
@@ -264,9 +315,12 @@ export class ProgressGuard {
             const nonActionCap = this.limits.maxConsecutiveNonActionCalls ??
                 DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls;
             if (this.consecutiveNonActionCalls >= nonActionCap) {
-                return (`no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
-                    `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
-                    `The agent is cycling through research instead of doing the work. Aborting.`);
+                return {
+                    kind: 'abort',
+                    reason: `no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
+                        `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
+                        `The agent is cycling through research instead of doing the work. Aborting.`,
+                };
             }
             return null;
         }
@@ -274,11 +328,19 @@ export class ProgressGuard {
         this.toolCalls++;
         if (FILE_EDIT_TOOLS.has(name))
             this.edits++;
+        // PROVISIONAL, not settled: the tool names say no recognised edit tool was called, which is
+        // not the same fact as "the repository is unchanged". The caller answers that from the
+        // working tree and reports back; until it does, the question is not re-raised.
         if (this.expectsEdits &&
             this.edits === 0 &&
+            !this.awaitingWorkspaceEvidence &&
             this.toolCalls >= this.limits.maxToolCallsWithoutEdit) {
-            return (`no progress: ${this.toolCalls} tool calls and not one file edit — the agent is exploring or ` +
-                `probing the environment without implementing anything. Aborting before it burns the whole run.`);
+            this.awaitingWorkspaceEvidence = true;
+            return {
+                kind: 'needs-workspace-evidence',
+                reason: `no progress: ${this.toolCalls} tool calls and no recognised file edit — the agent may be ` +
+                    `exploring or probing the environment without implementing anything.`,
+            };
         }
         return null;
     }

package/dist/runner.d.ts

@@ -99,7 +99,7 @@ export interface RunOptions {
     log?: Logger;
     /**
      * Extra environment for the agent's child process, scoped to THIS job. The CLI is spawned with
-     * `{...process.env, ...agentEnv}`, so these reach the agent and every shell tool it spawns.
+     * `agentChildEnv(agentEnv)`, so these reach the agent and every shell tool it spawns.
      *
      * This is the seam for anything per-job that would otherwise be written to a process- or
      * HOME-global (the tester's secrets, a private-registry npmrc pointer). Those globals are only

package/dist/salvage.d.ts

@@ -0,0 +1,180 @@
+import type { Logger } from './logger.js';
+/**
+ * Directory and file names never salvaged. A greenfield checkout may not have a `.gitignore` yet
+ * (the agent had not written one when it was killed), and git only excludes what a `.gitignore`
+ * tells it to, so without this a blanket salvage would commit `node_modules` into the PR.
+ *
+ * Matched against every SEGMENT of a path, so `packages/api/node_modules/x` is caught as surely as
+ * a root-level one. Deliberately a short list of the unambiguous ones: a cleverer heuristic starts
+ * discarding the deliverable, and a `dist/` that genuinely belonged in a commit is a far cheaper
+ * miss than a `node_modules/` that did not.
+ */
+export declare const SALVAGE_DENIED_SEGMENTS: readonly string[];
+/** Suffixes never salvaged: run output, not source. */
+export declare const SALVAGE_DENIED_SUFFIXES: readonly string[];
+/**
+ * Basenames and suffixes that carry CREDENTIALS, withheld from every salvage.
+ *
+ * The deny-list above trades a cheap miss (a `dist/` that belonged in a commit) against an
+ * expensive one (`node_modules/` in a PR). For a secret that trade INVERTS: a private key or a
+ * populated `.env` pushed to a branch is a disclosure that outlives the run, cannot be taken back
+ * by deleting the commit, and forces a rotation. Missing a file is recoverable; leaking one is not.
+ *
+ * This exists for the same reason the deny-list does: on the greenfield case the salvage was
+ * written for, the agent was killed before it wrote a `.gitignore`, so git excludes nothing and
+ * the harness is the only thing standing between an agent-authored key and the pull request.
+ *
+ * Unlike a junk path, a withheld secret is REPORTED (see {@link SalvageReport.withheld}): the file
+ * is real work that did not land, and whoever reads the run has to decide whether to re-create it
+ * or, if it holds a live credential, to rotate it.
+ */
+export declare const SALVAGE_SECRET_BASENAMES: readonly string[];
+/**
+ * Suffixes that mark a key store or an environment file, withheld for the reason above.
+ *
+ * `.env` is here as well as in {@link isSecretBearingName}'s own `.env` / `.env.*` test, so that
+ * `prod.env` and `local.env` are caught alongside `.env` and `.env.production`. The sample
+ * allow-list is unaffected: `.env.example` ends in `.example`, not in `.env`.
+ */
+export declare const SALVAGE_SECRET_SUFFIXES: readonly string[];
+/** Path segments that are credential or state stores rather than source. */
+export declare const SALVAGE_SECRET_SEGMENTS: readonly string[];
+/**
+ * The `.env` files that carry no secret and ARE the deliverable: the checked-in sample every
+ * scaffold ships so a reader knows which variables the service wants.
+ *
+ * An allow-list rather than a cleverer rule, because the two are the same shape and only the
+ * convention tells them apart. `.env` and every other `.env.<something>` is withheld: a scaffolded
+ * `.env.local` or `.env.production` is exactly where a real key ends up.
+ */
+export declare const SALVAGE_ENV_SAMPLE_BASENAMES: readonly string[];
+/** How much may be salvaged before the whole salvage is refused. */
+export interface SalvageBounds {
+    maxFiles: number;
+    maxBytes: number;
+}
+/**
+ * The default bounds. Generous enough for a scaffolded service (the run this was written for left
+ * about twenty source files) and far below anything that looks like a build output or a dependency
+ * tree that slipped past the deny-list.
+ */
+export declare const DEFAULT_SALVAGE_BOUNDS: SalvageBounds;
+/** What the salvage did, carried onto the run outcome so a human is told rather than left to infer. */
+export interface SalvageReport {
+    /**
+     * `none`: nothing was left uncommitted. `committed`: the files below are in `commitSha`.
+     * `refused`: there was work but it exceeded the bounds, so NOTHING was committed — a truncated
+     * salvage is worse than none, because a half-committed tree reads as a complete one.
+     * `failed`: the commit itself could not be made; the paths are named so the loss is on the record.
+     */
+    status: 'none' | 'committed' | 'refused' | 'failed';
+    /** The salvaged (or would-be salvaged) paths, capped for the log/wire; `fileCount` is the truth. */
+    files: string[];
+    fileCount: number;
+    totalBytes: number;
+    commitSha?: string;
+    /** Why a `refused`/`failed` salvage did not land. */
+    reason?: string;
+    /**
+     * Secret-bearing paths the salvage refused to commit, whatever its `status` (a run with nothing
+     * else to salvage still reports them, as `none`). Named rather than counted: the point is that
+     * someone can look at the file and decide whether it held a live credential.
+     */
+    withheld?: string[];
+}
+/**
+ * What the salvage does with one path.
+ *
+ * Three outcomes, not two, because the reasons for withholding a file are not the same fact. A
+ * `skip` is expected and uninteresting: nobody wants `node_modules` in a PR, and saying so would
+ * be noise on every run. A `secret` is a decision someone has to know about — the file was real
+ * work, it did not land, and it may hold a live credential that now needs rotating.
+ */
+export type SalvageDisposition = 'salvage' | 'skip' | 'secret';
+/** What the salvage would do with `path`: keep it, drop it quietly, or withhold it as a secret. */
+export declare function classifySalvagePath(path: string): SalvageDisposition;
+/**
+ * Split the untracked paths into what the salvage commits and what it withholds as secret-bearing.
+ *
+ * The secret check runs BEFORE the junk one, so a key under a denied directory is still counted as
+ * withheld rather than swallowed as junk: the point of the count is telling someone a credential
+ * may have been created, and where it happened to sit does not change that.
+ */
+export declare function partitionSalvageCandidates(paths: readonly string[]): {
+    candidates: string[];
+    withheld: string[];
+};
+/**
+ * Commit the new, untracked, non-ignored files the agent left behind in `dir`.
+ *
+ * Bounded by FILE COUNT and TOTAL BYTES, and over either bound it salvages NOTHING and says so:
+ * committing a prefix would produce a tree that looks complete and is not, which is the one
+ * outcome worse than the loss this exists to prevent.
+ *
+ * The message names the salvage as a salvage. A commit that arrives on a branch with no
+ * explanation is indistinguishable from work the agent chose to make, and this work was chosen by
+ * nobody — the run was killed with it still on the floor.
+ *
+ * CODING MODE ONLY: the caller decides that. A read-only kind has no branch to carry a commit and
+ * must never be given one.
+ */
+export declare function salvageUntrackedWork(args: {
+    dir: string;
+    /** How the run ended, which is what the commit message has to state. */
+    occasion: SalvageOccasion;
+    logger: Logger;
+    signal?: AbortSignal;
+    bounds?: SalvageBounds;
+}): Promise<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
+ * indistinguishable from work the agent chose to make and someone chose to keep.
+ */
+export type SalvageOccasion = 
+/** The run was killed mid-flight (guard, watchdog, eviction); `cause` is what killed it. */
+{
+    kind: 'aborted';
+    cause: string;
+}
+/** The agent finished but never added its own new files. */
+ | {
+    kind: 'settled';
+};
+/** The salvage commit's message: what it is, why it exists, and how much to trust it. */
+export declare function salvageCommitMessage(fileCount: number, occasion: SalvageOccasion): string;
+/**
+ * The banner for a pull request whose ENTIRE content is a salvage.
+ *
+ * A branch the agent never committed to, which exists only because the harness swept up the
+ * untracked files left in that checkout, is not a change anyone proposed. It is still worth
+ * opening (dropping it is the loss this whole module exists to prevent, and a peer repository in a
+ * multi-repo run is where a cross-service change most easily goes missing), but its reviewer has
+ * to be told that before reading it as a considered contribution: the agent may have been building
+ * there, or it may have left scratch work behind while working on a sibling repository, and
+ * nothing in the diff distinguishes the two.
+ *
+ * Lives here with {@link salvageCommitMessage} and {@link describeSalvage} because all three are
+ * the same job — saying what a salvage is to whoever finds it — and the three had better not drift
+ * into describing it differently. The caller decides WHERE it goes.
+ */
+export declare function salvageOnlyNotice(): string;
+/**
+ * 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
+ * files would have, so a note that does not say so describes a rescue that did not happen.
+ */
+export interface SalvageDelivery {
+    pushed: boolean;
+    /** Why the push did not land, when it did not. */
+    reason?: string;
+}
+/**
+ * What a human can act on, in one or two sentences. Joined onto the failure an aborted run
+ * 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.
+ *
+ * `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;