@cat-factory/executor-harness 1.132.1 → 1.134.0

package/README.md

@@ -14,6 +14,7 @@ accepts the job and returns immediately with a `jobId`; the driver then polls
 - [Job protocol](#job-protocol)
 - [What a job does](#what-a-job-does)
 - [No secrets in the image](#no-secrets-in-the-image)
+- [Local infra: the container's Docker daemon](#local-infra-the-containers-docker-daemon)
 - [Layout](#layout)
 - [Runner lifecycle knobs](#runner-lifecycle-knobs)
 - [Build / test](#build--test)
@@ -316,6 +317,44 @@ signed, model-locked LLM-proxy **session token** in the request body. Pi reaches
 models only through the Worker proxy, which injects the real provider key (qwen /
 Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 
+## Local infra: the container's Docker daemon
+
+The Tester's local-mode infra stand-up runs `docker compose up --wait` INSIDE this container, so
+the container needs a daemon of its own. It runs rootless, as the unprivileged `harness` user:
+Cloudflare Containers (and most managed runners) give no root and no privileged mode, and a host
+Docker socket would hand the container root on the host.
+
+`entrypoint.sh` starts it, waits for it in the background, and RECORDS the verdict
+(`src/docker-status.ts`). Two things consume that record and nothing else does:
+
+- `GET /health` reports it, so an operator (and a boot-time probe) can see what the container
+  concluded about itself.
+- The compose stand-up REFUSES on a decided absence and says why, instead of running compose
+  against nothing and handing the agent a connection error to interpret. The refusal rides back on
+  the Tester step as `infraSetup.dockerAvailable: false` with the cause.
+
+The verdict is three-valued, and that is the point. `false` is a decided absence. `undefined` is
+"nothing decided" — the probe is still in flight, or nothing recorded anything at all, which is the
+normal state under the native host transport (`LOCAL_NATIVE_AGENTS`) where the harness runs on a
+developer's machine with no entrypoint. Undecided attempts the stand-up; only a decided absence
+refuses it.
+
+What is recorded describes BOOT, and a container outlives its boot: a warm pool serves many jobs
+from one, and a sidecar daemon that took longer to come up than the entrypoint's bounded wait
+allows is serving perfectly well by the second job. So a recorded absence is a hypothesis, not the
+refusal: `resolveDockerVerdict` re-checks it against a live daemon at the moment a stand-up is
+about to run, and the record supplies what only the record holds, the cause and the daemon's own
+log tail. `GET /health` deliberately keeps reporting the boot record rather than probing per poll,
+since it is not the surface that acts on the answer.
+
+Why it is written down at all: the image shipped for months with `docker-ce-rootless-extras` (the
+wrappers that START a daemon) and no `docker-ce` (the daemon itself), and no `iproute2` for the
+network rootlesskit builds. The entrypoint backgrounded the start in a subshell where its exit
+status could not be observed, so every local-infra Tester run degraded silently to a no-infra run
+whose only trace was a compose error in a prompt note. A capability that reports itself present and
+then degrades in silence is worse than one that is absent, so the daemon is installed AND the
+verdict is stated.
+
 ## Layout
 
 | File               | Responsibility                                                                                          |
@@ -329,6 +368,10 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/pi-reduction.ts` | Reducing a Pi event stream to what the run PRODUCED (summary, stats, diagnostics, terminal failure), FOLDED as records stream rather than over a retained array — memory is O(largest record), not O(records). The array-taking entry points offline tooling uses are defined in terms of the same reducer. |
 | `src/tool-silence.ts` | The tool-silence watchdog (F13) and the `ToolProgressWindow` an agent stream opens, beats and closes. Separate from the phase marker on purpose: a window is only meaningful while something able to reset it is running. |
 | `src/git.ts`       | clone / branch / commit / push (lease-guarded: [The work-branch push is CHECKPOINTED, so it is lease-guarded](#the-work-branch-push-is-checkpointed-so-it-is-lease-guarded)) + GitHub PR creation; bootstrap history reset + force-push. |
+| `src/progress-guard.ts` | The live anti-rabbithole bounds every agent run is held to, plus the tool-name vocabulary they classify calls with. PURE and SYNCHRONOUS: it spawns nothing and reads nothing off disk, so it can be driven over a fixed event sequence in a unit test. Shared by both runners, because two copies of a bound are two bounds. |
+| `src/workspace-probe.ts` | The working-tree answer to "has this run actually changed the repository": a dirty tree, or HEAD moved off the sha the pass began at. What the no-edit bound decides on, since the tool names it can see are a fact about which tool the model picked and not about the repo (an agent writing everything through `bash` heredocs read as making no edits at all). Gitignored paths are excluded by git, which is what keeps a dependency install from reading as progress. Order carries the "is this a repository at all" question: the status runs first and is never caught, while a missing HEAD is the from-scratch case rather than a failure. A run whose cwd is a workspace of sibling checkouts composes one probe over them, where a checkout that could not be probed makes the answer inconclusive rather than clean. |
+| `src/guard-driver.ts` | The bridge between the synchronous guard and the async evidence one of its bounds needs. Both runners feed the guard from a sync stream handler, so the driver owns the probe's lifetime: at most one probe per run, a positive answer satisfying the bound permanently, a negative one aborting with the evidence quoted, and a THROWN one inconclusive (re-arm and warn, never kill). Also hosts the claude-code stream's tool_use/tool_result pairing. |
+| `src/salvage.ts` | Committing the new, untracked files an agent left behind, under a dependency/build deny-list and file-count + byte bounds that refuse ALL-or-nothing rather than truncating. Coding modes only. A credential-bearing name (`.env`, a private key, `.npmrc`) is a THIRD disposition, not a fourth junk entry: it is withheld like the rest but NAMED on the outcome, because for a secret the deny-list's usual trade inverts (a missed file is recoverable, a leaked key is not) and someone has to decide whether to rotate it. Every message here states the salvage's own provenance: a commit arriving with no explanation is indistinguishable from work someone chose to keep, and nobody chose this. |
 | `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
 | `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
@@ -350,6 +393,8 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/codex-images.ts` | Codex's own `image_gen` output, staged where the agent can reach it: creates `$CODEX_HOME/generated_images` as a symlink into `.cat-context/binary-output/generated/` before the CLI starts, sweeps anything a failed redirect left behind, and unlinks (never follows) the redirect at teardown — a failed unlink is REPORTED, because that unlink is what stops the recursive delete reaching the checkout. Exists because codex exposes no path for what it generated AND `$CODEX_HOME` holds the run's decrypted credential, so neither asking the agent nor sending it there is available. |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
+| `src/docker-status.ts` | This container's own verdict about its Docker daemon, as recorded by `entrypoint.sh`. Three-valued on purpose: a daemon that FAILED and a daemon nobody asked about are different facts, and only a DECIDED absence refuses a stand-up. See [Local infra: the container's Docker daemon](#local-infra-the-containers-docker-daemon). |
+| `src/agent-env.ts` | The env for anything the harness spawns into the agent's CHECKOUT: its own environment minus the variables that are facts about the HARNESS. Today that is `NODE_ENV` — the harness runs in production mode, and an inherited `NODE_ENV=production` makes npm omit devDependencies in a checkout that never asked for it. |
 
 ## Runner lifecycle knobs
 
@@ -373,6 +418,8 @@ runner):
 | `REPRODUCTION_TOTAL_BUDGET_MS` | `2700000` (45m) | Wall-clock ceiling on the WHOLE proof phase (every attempt, both trees, setup included). Attempts multiply two full tree runs each and the heartbeat above deliberately stops the inactivity watchdog from firing, so this is what bounds the phase. Checked at phase boundaries; exceeding it settles `inconclusive`, never a run failure. |
 | `HARNESS_TRANSCRIPT_TTL_MS` | `259200000` (3d) | How long lifted subscription-CLI session transcripts are kept before the retention sweep prunes them. |
 | `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content, though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
+| `HARNESS_DOCKER_READY_TIMEOUT_SECONDS` | `60` | How long `entrypoint.sh` waits for the container's Docker daemon before recording it unavailable. Only a HUNG daemon pays this in full: the wait ends early both when the socket answers and when the daemon process is gone. It runs in the BACKGROUND, so it never delays the container's boot. |
+| `HARNESS_DOCKER_STATUS_FILE` | `/tmp/harness-docker-status.json` | Where that verdict is recorded. `entrypoint.sh` writes it and the harness reads it, so an override must be set for BOTH (they share one process env). |
 
 ## Build / test
 

package/dist/agent-env.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Variables of the HARNESS PROCESS that must not reach the agent's checkout.
+ *
+ * Deliberately short, and it stays short: the bar is a variable whose value is a fact about the
+ * harness that a tool in the checkout will silently act on. It is not a sandbox (an agent can set
+ * whatever it likes in its own shell) and not a secret filter (the harness holds per-job secrets
+ * in `agentEnv`, never in `process.env`).
+ */
+export declare const HARNESS_ONLY_ENV_NAMES: readonly string[];
+/**
+ * The child env for a command run in the agent's checkout: the harness's own environment minus
+ * {@link HARNESS_ONLY_ENV_NAMES}, with each layer merged over it in order.
+ *
+ * A layer may still SET a stripped name — a job that explicitly asks for `NODE_ENV` gets it. The
+ * strip removes what was merely INHERITED, which is the thing nobody chose.
+ */
+export declare function agentChildEnv(...layers: (Record<string, string | undefined> | undefined)[]): NodeJS.ProcessEnv;

package/dist/agent-env.js

@@ -0,0 +1,47 @@
+// The environment the harness hands to everything it spawns INTO the agent's checkout: the agent
+// CLI itself, the captured commands (dependency prepopulation, validation checks, the reproduction
+// proof) and the frontend build/serve.
+//
+// The rule this exists for: the harness process and the agent's checkout are two different
+// programs, and a few of the harness's own environment variables are actively wrong for the
+// second. `NODE_ENV=production` is the one that bit: npm reads it as `omit=dev`, so `npm install`
+// in a checkout silently skips devDependencies, leaving the agent with no test runner, no linter
+// and no build tool. One measured coder run spent six of its forty budgeted tool calls
+// discovering and undoing that (install, `npm ls`, `npm config get omit`, reinstall with
+// `--include=dev`, re-check the bin directory, approve an install script) — all of it caused by a
+// variable the platform set, on a project the platform knows nothing about.
+//
+// Stripping it at THIS seam rather than in the image is what makes it true everywhere: the
+// container gets `NODE_ENV=production` from `entrypoint.sh` (so the harness itself still runs in
+// production mode) and the native host transport sets the same variable on the harness process it
+// spawns, so an image-only fix would have left the developer's own machine leaking it.
+//
+// Per-job env NEVER goes through `process.env` (CLAUDE.md, "Harness rules"): the native transport
+// serves every concurrent `ambientAuth` job from one long-lived process, so a mutation here would
+// be a cross-job leak. This function only READS the process env and returns a fresh object.
+/**
+ * Variables of the HARNESS PROCESS that must not reach the agent's checkout.
+ *
+ * Deliberately short, and it stays short: the bar is a variable whose value is a fact about the
+ * harness that a tool in the checkout will silently act on. It is not a sandbox (an agent can set
+ * whatever it likes in its own shell) and not a secret filter (the harness holds per-job secrets
+ * in `agentEnv`, never in `process.env`).
+ */
+export const HARNESS_ONLY_ENV_NAMES = ['NODE_ENV'];
+/**
+ * The child env for a command run in the agent's checkout: the harness's own environment minus
+ * {@link HARNESS_ONLY_ENV_NAMES}, with each layer merged over it in order.
+ *
+ * A layer may still SET a stripped name — a job that explicitly asks for `NODE_ENV` gets it. The
+ * strip removes what was merely INHERITED, which is the thing nobody chose.
+ */
+export function agentChildEnv(...layers) {
+    const env = { ...process.env };
+    for (const name of HARNESS_ONLY_ENV_NAMES)
+        delete env[name];
+    for (const layer of layers) {
+        if (layer)
+            Object.assign(env, layer);
+    }
+    return env;
+}

package/dist/agent-runner.d.ts

@@ -2,7 +2,8 @@ import { type Logger } from './logger.js';
 import { type ToolProgressWindow } from './tool-silence.js';
 import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress, type ToolSpan } from './pi.js';
 import { type McpServerSpec, type ObservedMcpServer, type SkillSpec } from './agent-capabilities.js';
-import { type ProgressGuardLimits } from './progress-guard.js';
+import type { ProgressGuardLimits } from './progress-guard.js';
+import type { WorkspaceProbe } from './workspace-probe.js';
 import { type SliceReview } from './subagents.js';
 /** Which subscription harness to run (the Pi harness uses `runPi` directly). */
 export type SubscriptionHarness = 'claude-code' | 'codex';
@@ -65,7 +66,7 @@ export interface SubscriptionRunOptions {
     generateImages?: boolean;
     /**
      * Extra environment for the CLI child, scoped to this job (the tester's secrets, a
-     * private-registry npmrc pointer). Merged over the inherited `process.env` at spawn, so the
+     * private-registry npmrc pointer). Merged over the inherited env at spawn (`agentChildEnv`), so the
      * agent and its shell tools see them without the harness mutating its OWN environment — which
      * is shared by every concurrent job under the native host-process transport. See
      * `RunOptions.agentEnv`.
@@ -84,6 +85,14 @@ export interface SubscriptionRunOptions {
     guardLimits?: ProgressGuardLimits;
     /** Whether this run is expected to edit files (false for assess-only runs); gates the no-edit bound. */
     expectsEdits?: boolean;
+    /**
+     * Probes the working tree for evidence the agent changed the repository. The guard's no-edit
+     * bound asks that question and can only see TOOL NAMES, so an agent writing files through
+     * `bash` reads as making no edits at all; this is what settles it before anything is killed.
+     * Injected so the guard stays pure, and consulted at most once per run (only when the bound is
+     * about to abort). Omitted ⇒ the bound falls back to its tool-name-only judgement.
+     */
+    workspaceProbe?: WorkspaceProbe;
     /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
     onActivity?: () => void;
     /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */

package/dist/agent-runner.js

@@ -11,9 +11,10 @@ import { NO_TOOL_WINDOW } from './tool-silence.js';
 import { publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js';
-import { ProgressGuard } from './progress-guard.js';
+import { createClaudeProgressGuard } from './guard-driver.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
 import { killChildProcess, spawnDetached } from './process.js';
+import { agentChildEnv } from './agent-env.js';
 import { abortReasonOf } from './failure.js';
 import { describeProcessExit } from './process-exit.js';
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js';
@@ -42,7 +43,7 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
         }
         const child = spawn(command, args, {
             cwd: opts.cwd,
-            env: { ...process.env, ...env },
+            env: agentChildEnv(env),
             stdio: ['pipe', 'pipe', 'pipe'],
             // Own process group (POSIX) so killChildProcess reaps the CLI's grandchildren too.
             detached: spawnDetached,
@@ -383,52 +384,6 @@ function reportToolServerStartup(event, onToolServers) {
     if (observed)
         onToolServers(observed);
 }
-/**
- * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
- * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
- * the assistant turn (`rememberTool`) and hands the following user turn's content to `feedGuard`,
- * which pairs each `tool_result`'s `is_error` with that name. The FIRST reason trips it: the
- * diagnostic is recorded (readable via `reason()`, which the catch surfaces over the generic abort
- * message) and `guardAbort` fires — folded into streamCli's signal so a tripped guard kills the CLI
- * the same way the external watchdog does. Disabled when the caller supplies no limits (only the
- * external watchdog then bounds the run).
- *
- * Split out of {@link runClaudeCode} for the per-function line budget.
- */
-function createClaudeProgressGuard(opts) {
-    const guard = opts.guardLimits
-        ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
-        : undefined;
-    const toolNames = new Map();
-    const guardAbort = new AbortController();
-    let guardReason;
-    const feedGuard = (content) => {
-        if (!guard || guardReason)
-            return;
-        for (const block of content) {
-            if (!isObject(block) || block.type !== 'tool_result')
-                continue;
-            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
-            const name = id ? toolNames.get(id) : undefined;
-            if (id)
-                toolNames.delete(id);
-            if (!name)
-                continue;
-            const reason = guard.observeSignal({ name, isError: block.is_error === true });
-            if (reason) {
-                guardReason = reason;
-                guardAbort.abort();
-                return;
-            }
-        }
-    };
-    return {
-        rememberTool: (id, name) => toolNames.set(id, name),
-        feedGuard,
-        guardAbort,
-        reason: () => guardReason,
-    };
-}
 /**
  * The run's TRAJECTORY, on the claude-code stream: each `tool_use` block paired with the
  * `tool_result` that answers it on the following user turn, numbered and captured (scrubbed +

package/dist/agent.d.ts

@@ -1,17 +1,6 @@
 import type { AgentJob, AgentResult, TestSecretSpec } from './job.js';
 import { runCodingAgent } from './coding-agent.js';
 import type { RunOptions } from './runner.js';
-/**
- * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
- * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
- * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
- * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
- * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
- */
-export declare function buildInfraNotes(managed: {
-    note?: string;
-    serveUrl?: string;
-}): string[];
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export declare function handleAgent(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
 /**

package/dist/agent.js

@@ -1,12 +1,13 @@
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { mkdir, mkdtemp, rm } from 'node:fs/promises';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+// The preview mode drives the frontend stand-up directly rather than through `manageInfra`:
+// its serve/WireMock children outlive the job on purpose, so it wants no cleanup handle.
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
+import { buildInfraNotes, manageInfra } from './infra-standup.js';
 import { artifactUploadEnv } from './artifact-upload.js';
 import { configurePackageRegistries } from './package-registries.js';
-import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
+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';
@@ -36,132 +37,6 @@ import { log } from './logger.js';
 // target repo. These are the deliberate, documented exceptions — do NOT grow this into a
 // general `if (job.someFlag)` dispatch; anything that doesn't need a checkout belongs in
 // backend pre/post-ops. See backend/docs/custom-agents.md.
-const exec = promisify(execFile);
-/**
- * Bring the service's docker-compose dependencies up (local infra only). Best-effort:
- * runs `docker compose -f <path> up -d --wait` in the checkout. A missing Docker daemon
- * or a compose failure is logged and surfaced to the agent (as a prompt note) rather
- * than failing the job — the agent can still run unit-level tests and report what it
- * could. A no-op for ephemeral / no-infra / no-compose-path runs.
- *
- * Whether it succeeds or fails, the (redacted, bounded) command output is captured into a
- * {@link InfraSetupRecord} returned alongside the prompt `note`, so the backend can surface
- * the in-container dependency stand-up logs on the Tester step — the failure-class artifact
- * the orchestrator-side provisioning logs can't see.
- */
-async function standUpInfra(dir, infra, signal, logger) {
-    if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) {
-        return { started: false };
-    }
-    const startedAt = Date.now();
-    try {
-        logger.info('agent(explore): standing up infra', { composePath: infra.composePath });
-        // Raise maxBuffer well above the 1MB default so a chatty compose stand-up can't fail the
-        // (best-effort) infra step with ENOBUFS; the captured output is tail-bounded on storage.
-        const { stdout, stderr } = await exec('docker', ['compose', '-f', infra.composePath, 'up', '-d', '--wait'], { cwd: dir, signal, timeout: 5 * 60_000, maxBuffer: 16 * 1024 * 1024 });
-        const logs = captureRedactedOutput(stdout, stderr);
-        return {
-            started: true,
-            record: {
-                started: true,
-                composePath: infra.composePath,
-                at: Date.now(),
-                durationMs: Date.now() - startedAt,
-                ...(logs ? { logs } : {}),
-            },
-        };
-    }
-    catch (err) {
-        const note = err instanceof Error ? err.message : String(err);
-        logger.warn('agent(explore): infra stand-up failed', { error: note });
-        // `execFile` rejections carry the partial stdout/stderr on the error object — capture them
-        // so the stored logs explain the failure (a port clash, a pull-auth error, an exited
-        // dependency), not just the one-line exit message.
-        const e = err;
-        const logs = captureRedactedOutput(e.stdout, e.stderr);
-        return {
-            started: false,
-            note,
-            record: {
-                started: false,
-                composePath: infra.composePath,
-                at: Date.now(),
-                durationMs: Date.now() - startedAt,
-                error: redactSecrets(note),
-                ...(logs ? { logs } : {}),
-            },
-        };
-    }
-}
-/**
- * Stand the run's infra up and return a single cleanup handle, dispatching on the spec's
- * `kind`: the frontend UI-test flow (`kind: 'frontend'`) builds/serves the app + WireMock as
- * processes (torn down by killing them); the default backend-service flow stands the
- * docker-compose stack up (torn down with `docker compose down`). Unifying the two here keeps
- * `runExploreMode` free of the branch and guarantees the matching teardown runs in its finally.
- *
- * `dir` is the clone ROOT; `workDir` is the service subtree (equal to `dir` when the run is not
- * monorepo-scoped). The docker-compose stand-up runs at the root (its `composePath` is
- * repo-relative), but the FRONTEND stand-up runs in `workDir`: a monorepo frontend's
- * `package.json` / `outputDir` / `mocks/` all live under the service subtree, so installing,
- * building, serving and seeding WireMock from the root would target the wrong directory.
- */
-async function manageInfra(dir, workDir, infra, opts, logger) {
-    if (infra.kind === 'frontend') {
-        // `onActivity` feeds the inactivity watchdog through the frontend build/serve stand-up,
-        // which (unlike docker-compose's 5-min-capped `up`) can run past the inactivity window.
-        // Runs in `workDir` so a monorepo frontend builds/serves from its own package subtree.
-        const fe = await standUpFrontend(workDir, infra, opts, logger);
-        return {
-            ...(fe.note ? { note: fe.note } : {}),
-            ...(fe.serveUrl ? { serveUrl: fe.serveUrl } : {}),
-            record: fe.record,
-            cleanup: () => tearDownFrontend(fe.processes, logger),
-        };
-    }
-    const standUp = await standUpInfra(dir, infra, opts.signal, logger);
-    return {
-        ...(standUp.note ? { note: standUp.note } : {}),
-        ...(standUp.record ? { record: standUp.record } : {}),
-        cleanup: () => tearDownInfra(dir, infra),
-    };
-}
-/**
- * Build the dynamic infra notes appended to the agent's user prompt from a stand-up outcome.
- * A stand-up problem (a failed build / compose) is flagged as a concern to test around; a
- * frontend serve URL points the UI tester at the app that was just built + served and pre-empts
- * a live-backend CORS failure being mis-reported as an app defect. Pure (no IO) so the exact
- * wording + ordering is unit-tested; returns the notes in order (problem first, serve URL next).
- */
-export function buildInfraNotes(managed) {
-    const notes = [];
-    if (managed.note) {
-        notes.push(`standing the infra up reported a problem (${managed.note}). Test what you can and ` +
-            `flag any dependency-related gaps as concerns.`);
-    }
-    if (managed.serveUrl) {
-        notes.push(`The frontend under test is built and served at ${managed.serveUrl}, with its other ` +
-            `backend upstreams handled by WireMock. Drive your UI tests against ${managed.serveUrl}. ` +
-            `If a call to a live backend fails with a CORS / cross-origin error, that is an infra ` +
-            `gap (the backend must allow the ${managed.serveUrl} origin), not an app defect — flag ` +
-            `it as a concern rather than a failing test.`);
-    }
-    return notes;
-}
-/** Tear the docker-compose dependencies down (best-effort; a no-op when none were started). */
-async function tearDownInfra(dir, infra) {
-    if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath)
-        return;
-    try {
-        await exec('docker', ['compose', '-f', infra.composePath, 'down', '-v'], {
-            cwd: dir,
-            timeout: 2 * 60_000,
-        });
-    }
-    catch {
-        // The container is ephemeral and torn down with the run anyway — ignore.
-    }
-}
 /**
  * Parse an agent's final reply into the structured JSON `custom`, shared by the explore and
  * coding structured-output paths. With repair enabled (default) a malformed reply gets ONE
@@ -262,9 +137,9 @@ export async function handleAgent(job, opts = {}) {
 }
 /**
  * Layer extra child-process env onto a job's {@link RunOptions}. The agent CLI is spawned with
- * `{...process.env, ...agentEnv}`, so this is how per-job values reach the agent (and the shell
- * tools it spawns) WITHOUT mutating the harness's own `process.env` — which is shared by every
- * concurrent job when the harness runs as a native host process. Empty `env` ⇒ `opts` unchanged.
+ * `agentChildEnv(agentEnv)`, so this is how per-job values reach the agent (and the shell tools it
+ * spawns) WITHOUT mutating the harness's own `process.env` — which is shared by every concurrent
+ * job when the harness runs as a native host process. Empty `env` ⇒ `opts` unchanged.
  */
 function withAgentEnv(opts, env) {
     if (Object.keys(env).length === 0)

package/dist/captured-command.d.ts

@@ -22,7 +22,7 @@ export interface CapturedCommandResult {
  * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
  * from settling.
  *
- * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over `agentChildEnv`),
  * not a mutated global: the harness spawns this itself rather than through the agent, so without
  * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
  * had this been staged in `process.env`, against a sibling job's state).

package/dist/captured-command.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { killChildProcess, spawnDetached } from './process.js';
+import { agentChildEnv } from './agent-env.js';
 import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
 // The ONE way the harness runs a declared shell command on its own behalf (rather than through
 // the agent) and keeps a bounded, secret-scrubbed record of what it printed.
@@ -33,7 +34,7 @@ const CAPTURE_MARGIN_CHARS = 512;
  * tree on timeout and an aborted run resolves non-zero, so a phase is never what blocks a job
  * from settling.
  *
- * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over the process env),
+ * The child inherits the JOB's environment (`RunOptions.agentEnv` layered over `agentChildEnv`),
  * not a mutated global: the harness spawns this itself rather than through the agent, so without
  * the explicit merge a native-mode job would run without the private-registry npmrc pointer (and,
  * had this been staged in `process.env`, against a sibling job's state).
@@ -53,7 +54,7 @@ export async function runCapturedCommand(args) {
             cwd,
             detached: spawnDetached,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, ...opts.agentEnv },
+            env: agentChildEnv(opts.agentEnv),
         });
         // Keep only the tail (plus the scrub margin); guard against unbounded buffering on a chatty
         // command.

package/dist/coding-agent.d.ts

@@ -9,6 +9,7 @@ import { type Logger } from './logger.js';
 import { type ValidationChecksSpec, type ValidationReport } from './validation-checks.js';
 import { type ReproductionReport, type ReproductionSpec } from './reproduction-proof.js';
 import { type DependencyInstallSpec } from './dependency-install.js';
+import { type SalvageReport } from './salvage.js';
 /** What a coding agent run needs: where to clone, what to run, where to push. */
 export interface CodingAgentSpec extends HarnessAuthFields {
     /** Short label for the temp dir + log lines (e.g. 'impl', 'ci-fix'). */
@@ -192,8 +193,42 @@ export interface CodingAgentOutcome {
      * attached to a perfectly successful run and the PR still opens.
      */
     reproductionReport?: ReproductionReport;
+    /**
+     * What became of the new files the agent created and never committed. Absent means there were
+     * none to consider; `status: 'refused'` or `'failed'` means work was left behind and is NOT in
+     * the push, which the backend must be able to tell a human rather than presenting the run as a
+     * clean pass.
+     */
+    salvage?: SalvageReport;
 }
 export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions): Promise<CodingAgentOutcome>;
+/**
+ * Salvage what an aborted run left uncommitted, push it, and return the error to rethrow with the
+ * salvage stated on it.
+ *
+ * Returns rather than throws so the caller's `throw` stays visible at the call site, and so this
+ * can never REPLACE the failure being reported: a salvage that throws is swallowed, because the
+ * reason the run died is strictly more useful than the reason its rescue did.
+ *
+ * The push is what makes the salvage worth anything — the commit lives in a container that is
+ * about to be reclaimed — and it is reported HONESTLY: a commit that could not be pushed is lost
+ * exactly as the uncommitted files would have been, so the note says so rather than naming a sha
+ * nobody will ever be able to fetch.
+ *
+ * Two things have to happen before the salvage, and the caller has already stopped the checkpoint
+ * interval for the first. The second is here: any push the checkpoint had IN FLIGHT is drained,
+ * because `pushWorkOnce` coalesces onto it and would otherwise hand the rescue a push that was
+ * made before the salvage commit existed.
+ *
+ * Exported for its test: every collaborator it needs is a parameter, so the ordering and the
+ * signal it pushes on can be asserted against a real repository without a container.
+ */
+export declare function withSalvagedWork(error: unknown, args: {
+    dir: string;
+    logger: Logger;
+    pushWorkOnce: (override?: AbortSignal) => Promise<void>;
+    inFlightPush: () => Promise<void> | null;
+}): Promise<unknown>;
 /**
  * The Ralph-loop validation watchdog: the longest a completion command may run before it is
  * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).