@cat-factory/executor-harness 1.132.1 → 1.134.0

package/dist/usage-attribution.d.ts

@@ -49,6 +49,14 @@ export declare function claudeUsage(raw: unknown): {
  *
  * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
  * reported the two inconsistently, and negative spend is not a thing to record.
+ *
+ * {@link HarnessCallMetric.spendOnly} is decided HERE, and it is not the same question as
+ * `standsForJob`. The row never occupies a turn, but whether it is a CALL depends on whether any
+ * turn was narrated beside it: with costed turns present this only corrects THEIR under-reporting
+ * (counting it would report one phantom call per dispatch), while with none it is the job's ONLY
+ * record and excluding it would report a step that spent tokens across zero calls. Only this
+ * function can answer that — the backend records a job's calls in BATCHES as the live drain
+ * delivers them, so a batch holding just this row cannot tell the two cases apart.
  */
 export declare function unaccountedUsageCall(parentCalls: readonly HarnessCallMetric[], usage: {
     inputTokens: number;

package/dist/usage-attribution.js

@@ -62,6 +62,14 @@ export function claudeUsage(raw) {
  *
  * Clamped at 0 per side: a CLI whose terminal figure is LOWER than its own per-turn sum has
  * reported the two inconsistently, and negative spend is not a thing to record.
+ *
+ * {@link HarnessCallMetric.spendOnly} is decided HERE, and it is not the same question as
+ * `standsForJob`. The row never occupies a turn, but whether it is a CALL depends on whether any
+ * turn was narrated beside it: with costed turns present this only corrects THEIR under-reporting
+ * (counting it would report one phantom call per dispatch), while with none it is the job's ONLY
+ * record and excluding it would report a step that spent tokens across zero calls. Only this
+ * function can answer that — the backend records a job's calls in BATCHES as the live drain
+ * delivers them, so a batch holding just this row cannot tell the two cases apart.
  */
 export function unaccountedUsageCall(parentCalls, usage) {
     if (!usage)
@@ -92,5 +100,6 @@ export function unaccountedUsageCall(parentCalls, usage) {
         outputTokens,
         finishReason: null,
         standsForJob: true,
+        spendOnly: parentCalls.length > 0,
     };
 }

package/dist/workspace-probe.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The harness's own side-channel sentinels, written INTO the checkout by the platform rather than
+ * by the agent. Excluded from the dirty check, or a run that wrote nothing but its effort report
+ * reads as productive and the guard it is meant to satisfy never fires again.
+ *
+ * Deliberately just this list. A cleverer rule (anything dotted, anything the harness has ever
+ * touched) would start excluding the agent's own work — a `.github/workflows/ci.yml` or an
+ * `eslint.config.js` is exactly the greenfield deliverable this whole change exists to keep.
+ */
+export declare const HARNESS_SENTINEL_FILES: readonly string[];
+/** What a workspace probe found. Never `undefined`: a probe that cannot answer THROWS. */
+export interface WorkspaceEvidence {
+    /** Whether the repository changed: a dirty working tree, or HEAD moved off the pass's base. */
+    mutated: boolean;
+    /** HEAD at probe time, quoted in the guard's diagnostic so the evidence is on the record. */
+    headSha: string;
+    /** Whether HEAD moved off the sha the pass started from (the agent committed). */
+    headMoved: boolean;
+    /** How many non-sentinel paths the working tree reports as changed. */
+    dirtyPathCount: number;
+}
+/** Probes the working tree for evidence the agent changed the repository. Throws if it cannot. */
+export type WorkspaceProbe = () => Promise<WorkspaceEvidence>;
+/**
+ * The non-sentinel paths in a porcelain status — the working-tree half of the evidence.
+ *
+ * Pure, so the sentinel rule is unit-testable without a repository. A sentinel matches by BASENAME
+ * as well as by exact path: the agent's cwd is a service subdirectory in a monorepo, so its effort
+ * report lands at `services/api/.cat-effort.json`, and a root-anchored comparison would miss it.
+ */
+export declare function agentChangedPaths(status: string): string[];
+/**
+ * Build the probe for one pass: the working tree at `dir`, judged against the sha the pass
+ * started from.
+ *
+ * The repository changed if the tree is dirty or HEAD has moved off `baseSha`. Both are the agent
+ * changing the repo, and between them they cover the two shapes the tool-name proxy missed: files
+ * written through `bash` and left in the tree, and files written and then committed. Gitignored
+ * paths are excluded by git itself, so an `npm install` still reads as nothing.
+ *
+ * ORDER MATTERS, and carries the "is this a repository at all" question. The status runs FIRST and
+ * is never caught: a `dir` that is no git repository fails there, and the driver treats a throw as
+ * inconclusive (re-arm and warn, never abort). HEAD is read second and a failure to read it is
+ * NOT a failed probe: a scaffold-from-scratch checkout has no commit yet, so `rev-parse HEAD`
+ * errors in exactly the case the dirty-tree half was written for. It reads as the empty sha, which
+ * is what the pass baselined against too, so the two agree that HEAD has not moved and the tree
+ * decides. Catching it around the status instead would turn "not a repository" into "no evidence
+ * of change" and hand the guard a clean verdict it has no business acting on.
+ *
+ * INJECTED, never imported by the guard: the guard stays pure and synchronous so it can be driven
+ * over a fixed event sequence in a unit test, and the git access lives out here where a test
+ * substitutes a stub.
+ */
+export declare function createWorkspaceProbe(deps: {
+    dir: string;
+    /** HEAD when this pass began — a repair round's base is its own start, not the clone's. */
+    baseSha: string;
+    signal?: AbortSignal;
+}): WorkspaceProbe;
+/**
+ * HEAD at `dir`, or the empty sha where there is no commit to read.
+ *
+ * The one shared reader for both the pass BASELINE and the probe, so the two can never disagree
+ * about what a commit-less checkout is worth: if the baseline tolerates a missing HEAD and the
+ * probe throws on it, a from-scratch build has no working bound at all.
+ */
+export declare function readHeadOrEmpty(dir: string, signal?: AbortSignal): Promise<string>;
+/**
+ * One probe over SEVERAL checkouts, for a run whose cwd is not itself a repository.
+ *
+ * A multi-repo run works at a WORKSPACE ROOT holding sibling checkouts, so probing the cwd asks
+ * git about a directory that is no repository: every probe throws, the driver re-arms forever and
+ * the no-edit bound is permanently unenforceable. The honest question there is "did the run change
+ * ANY of the repositories it was given", which is this.
+ *
+ * Mutation is a disjunction and inconclusiveness WINS OVER cleanliness. A leg that answers
+ * `mutated` settles it, since one changed repository is the run making progress. But a leg that
+ * THREW might have been the changed one, so `mutated: false` is only reported when every leg
+ * actually answered; otherwise this throws and the driver re-arms, which is the same fail-open
+ * disposition a single failing probe already gets. Killing a productive run is the expensive error.
+ *
+ * `headSha` joins the answering legs' shas, because a workspace has no single HEAD and quoting one
+ * leg's would put a sha in the abort diagnostic that says nothing about where the run actually was.
+ */
+export declare function composeWorkspaceProbes(probes: readonly WorkspaceProbe[]): WorkspaceProbe;

package/dist/workspace-probe.js

@@ -0,0 +1,124 @@
+import { changedPathsFromPorcelain, headCommit, workingTreeStatus } from './git.js';
+import { EFFORT_REPORT_FILE } from './effort.js';
+import { FOLLOW_UPS_FILENAME } from './follow-ups.js';
+import { PR_DESCRIPTION_FILE } from './pr-description.js';
+// The working-tree answer to "has this run actually changed the repository". The no-progress
+// guard's no-edit bound used to answer it from TOOL NAMES, which is a fact about which tool the
+// model happened to pick, not about the repo: an agent writing every file through `bash`
+// (heredocs, `sed -i`, `node -e`) read as forty calls and not one edit however much it had built,
+// and the guard killed it. This module is the evidence the guard now decides on instead.
+//
+// Kept OFF the hot path. The bound only matters at the instant it is about to abort, so the probe
+// runs there and at most once per run (see `guard-driver.ts`), never per tool call.
+/**
+ * The harness's own side-channel sentinels, written INTO the checkout by the platform rather than
+ * by the agent. Excluded from the dirty check, or a run that wrote nothing but its effort report
+ * reads as productive and the guard it is meant to satisfy never fires again.
+ *
+ * Deliberately just this list. A cleverer rule (anything dotted, anything the harness has ever
+ * touched) would start excluding the agent's own work — a `.github/workflows/ci.yml` or an
+ * `eslint.config.js` is exactly the greenfield deliverable this whole change exists to keep.
+ */
+export const HARNESS_SENTINEL_FILES = [
+    EFFORT_REPORT_FILE,
+    FOLLOW_UPS_FILENAME,
+    PR_DESCRIPTION_FILE,
+];
+/**
+ * The non-sentinel paths in a porcelain status — the working-tree half of the evidence.
+ *
+ * Pure, so the sentinel rule is unit-testable without a repository. A sentinel matches by BASENAME
+ * as well as by exact path: the agent's cwd is a service subdirectory in a monorepo, so its effort
+ * report lands at `services/api/.cat-effort.json`, and a root-anchored comparison would miss it.
+ */
+export function agentChangedPaths(status) {
+    const sentinels = new Set(HARNESS_SENTINEL_FILES);
+    return changedPathsFromPorcelain(status).filter((path) => {
+        const basename = path.slice(path.lastIndexOf('/') + 1);
+        return !sentinels.has(path) && !sentinels.has(basename);
+    });
+}
+/**
+ * Build the probe for one pass: the working tree at `dir`, judged against the sha the pass
+ * started from.
+ *
+ * The repository changed if the tree is dirty or HEAD has moved off `baseSha`. Both are the agent
+ * changing the repo, and between them they cover the two shapes the tool-name proxy missed: files
+ * written through `bash` and left in the tree, and files written and then committed. Gitignored
+ * paths are excluded by git itself, so an `npm install` still reads as nothing.
+ *
+ * ORDER MATTERS, and carries the "is this a repository at all" question. The status runs FIRST and
+ * is never caught: a `dir` that is no git repository fails there, and the driver treats a throw as
+ * inconclusive (re-arm and warn, never abort). HEAD is read second and a failure to read it is
+ * NOT a failed probe: a scaffold-from-scratch checkout has no commit yet, so `rev-parse HEAD`
+ * errors in exactly the case the dirty-tree half was written for. It reads as the empty sha, which
+ * is what the pass baselined against too, so the two agree that HEAD has not moved and the tree
+ * decides. Catching it around the status instead would turn "not a repository" into "no evidence
+ * of change" and hand the guard a clean verdict it has no business acting on.
+ *
+ * INJECTED, never imported by the guard: the guard stays pure and synchronous so it can be driven
+ * over a fixed event sequence in a unit test, and the git access lives out here where a test
+ * substitutes a stub.
+ */
+export function createWorkspaceProbe(deps) {
+    return async () => {
+        const status = await workingTreeStatus(deps.dir, deps.signal);
+        const dirty = agentChangedPaths(status);
+        const headSha = await readHeadOrEmpty(deps.dir, deps.signal);
+        const headMoved = headSha !== deps.baseSha;
+        return {
+            mutated: dirty.length > 0 || headMoved,
+            headSha,
+            headMoved,
+            dirtyPathCount: dirty.length,
+        };
+    };
+}
+/**
+ * HEAD at `dir`, or the empty sha where there is no commit to read.
+ *
+ * The one shared reader for both the pass BASELINE and the probe, so the two can never disagree
+ * about what a commit-less checkout is worth: if the baseline tolerates a missing HEAD and the
+ * probe throws on it, a from-scratch build has no working bound at all.
+ */
+export async function readHeadOrEmpty(dir, signal) {
+    return headCommit(dir, signal).catch(() => '');
+}
+/**
+ * One probe over SEVERAL checkouts, for a run whose cwd is not itself a repository.
+ *
+ * A multi-repo run works at a WORKSPACE ROOT holding sibling checkouts, so probing the cwd asks
+ * git about a directory that is no repository: every probe throws, the driver re-arms forever and
+ * the no-edit bound is permanently unenforceable. The honest question there is "did the run change
+ * ANY of the repositories it was given", which is this.
+ *
+ * Mutation is a disjunction and inconclusiveness WINS OVER cleanliness. A leg that answers
+ * `mutated` settles it, since one changed repository is the run making progress. But a leg that
+ * THREW might have been the changed one, so `mutated: false` is only reported when every leg
+ * actually answered; otherwise this throws and the driver re-arms, which is the same fail-open
+ * disposition a single failing probe already gets. Killing a productive run is the expensive error.
+ *
+ * `headSha` joins the answering legs' shas, because a workspace has no single HEAD and quoting one
+ * leg's would put a sha in the abort diagnostic that says nothing about where the run actually was.
+ */
+export function composeWorkspaceProbes(probes) {
+    if (probes.length === 1)
+        return probes[0];
+    return async () => {
+        const settled = await Promise.allSettled(probes.map((probe) => probe()));
+        const answered = settled.filter((result) => result.status === 'fulfilled');
+        const evidence = answered.map((result) => result.value);
+        const mutated = evidence.some((one) => one.mutated);
+        if (!mutated && answered.length < probes.length) {
+            const first = settled.find((result) => result.status === 'rejected');
+            throw new Error(`${probes.length - answered.length} of ${probes.length} checkouts could not be probed and ` +
+                `none of the rest had changed, so whether this run changed anything is unknown`, { cause: first?.status === 'rejected' ? first.reason : undefined });
+        }
+        return {
+            mutated,
+            headSha: evidence.map((one) => one.headSha).join(', '),
+            headMoved: evidence.some((one) => one.headMoved),
+            dirtyPathCount: evidence.reduce((total, one) => total + one.dirtyPathCount, 0),
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.132.1",
+  "version": "1.134.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -25,9 +25,9 @@
     "access": "public"
   },
   "devDependencies": {
-    "@cat-factory/kernel": "0.318.1",
-    "@cat-factory/server": "0.306.1",
-    "@cat-factory/spend": "0.16.13",
+    "@cat-factory/kernel": "0.321.0",
+    "@cat-factory/server": "0.306.5",
+    "@cat-factory/spend": "0.16.17",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",
     "hono": "^4.13.4",

package/src/agent-env.ts

@@ -0,0 +1,49 @@
+// 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: readonly string[] = ['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: (Record<string, string | undefined> | undefined)[]
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...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/src/agent-runner.ts

@@ -34,9 +34,12 @@ import {
   type SkillSpec,
 } from './agent-capabilities.js'
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js'
-import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
+import type { ProgressGuardLimits } from './progress-guard.js'
+import { createClaudeProgressGuard } from './guard-driver.js'
+import type { WorkspaceProbe } from './workspace-probe.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'
@@ -129,7 +132,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`.
@@ -148,6 +151,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. */
@@ -234,7 +245,7 @@ function streamCli(
     }
     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,
@@ -607,56 +618,6 @@ function reportToolServerStartup(
   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: SubscriptionRunOptions): {
-  rememberTool: (id: string, name: string) => void
-  feedGuard: (content: unknown[]) => void
-  guardAbort: AbortController
-  reason: () => string | undefined
-} {
-  const guard = opts.guardLimits
-    ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
-    : undefined
-  const toolNames = new Map<string, string>()
-  const guardAbort = new AbortController()
-  let guardReason: string | undefined
-
-  const feedGuard = (content: unknown[]): void => {
-    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/src/agent.ts

@@ -1,8 +1,6 @@
 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'
 import type {
   AgentInfraSpec,
   AgentJob,
@@ -11,10 +9,13 @@ import type {
   ServiceInfraSpec,
   TestSecretSpec,
 } from './job.js'
+// 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,
@@ -71,158 +72,6 @@ import { log, type Logger } from './logger.js'
 // 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: string,
-  infra: ServiceInfraSpec,
-  signal: AbortSignal | undefined,
-  logger: Logger,
-): Promise<{ started: boolean; note?: string; record?: InfraSetupRecord }> {
-  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 as { stdout?: unknown; stderr?: unknown }
-    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: string,
-  workDir: string,
-  infra: AgentInfraSpec,
-  opts: RunOptions,
-  logger: Logger,
-): Promise<{
-  note?: string
-  serveUrl?: string
-  record?: InfraSetupRecord
-  cleanup: () => Promise<void>
-}> {
-  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: { note?: string; serveUrl?: string }): string[] {
-  const notes: string[] = []
-  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: string, infra: ServiceInfraSpec): Promise<void> {
-  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
@@ -337,9 +186,9 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
 
 /**
  * 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: RunOptions, env: Record<string, string>): RunOptions {
   if (Object.keys(env).length === 0) return opts

package/src/captured-command.ts

@@ -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'
 import type { RunOptions } from './runner.js'
 import type { Logger } from './logger.js'
@@ -54,7 +55,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).
@@ -84,7 +85,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.