@cat-factory/executor-harness 1.132.3 → 1.135.0

package/dist/agent-runner.js

@@ -1,7 +1,5 @@
 import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js';
 import { claudeUsage, unaccountedUsageCall } from './usage-attribution.js';
 import { createClaudeRunTelemetry, subagentDispatchId, } from './claude-call-aggregator.js';
@@ -9,18 +7,19 @@ import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js'
 import { log } from './logger.js';
 import { NO_TOOL_WINDOW } from './tool-silence.js';
 import { publishCallMetric, } from './pi.js';
-import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { observeClaudeMcpInit, } from './agent-capabilities.js';
+import { openClaudeRunHome } from './claude-home.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';
+import { redact, secretsToRedact } from './redact.js';
 import { createSliceTracker, startSubagentWatcher } from './subagents.js';
 import { createTaskPlanTracker, mergeProgress, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
-import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
-import { retainSessionTranscripts } from './transcript-retention.js';
+import { assertClaudeToolsCurrent, claudeCliArgs, CLAUDE_TOOL_SET } from './claude-cli.js';
 /**
  * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
  * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
@@ -42,7 +41,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,
@@ -255,80 +254,6 @@ export function carryClaudeSystemPrompt(systemPrompt, userPrompt) {
 // ---------------------------------------------------------------------------
 // Claude Code
 // ---------------------------------------------------------------------------
-/**
- * Run the Claude Code CLI headlessly against `opts.cwd`, authenticated with the
- * leased subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN), talking direct to
- * api.anthropic.com. Streams `--output-format stream-json`, mapping the
- * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
- * onto the summary + usage.
- */
-/**
- * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
- * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
- * expects) plus every resource file at its path within the skill directory. Resource sub-paths
- * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
- *
- * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
- * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
- * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
- * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
- * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
- */
-async function writeNativeSkill(skillsRoot, skill) {
-    const dir = join(skillsRoot, skill.name);
-    await mkdir(dir, { recursive: true });
-    const name = JSON.stringify(skill.name);
-    const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '));
-    const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`;
-    await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8');
-    for (const resource of skill.resources) {
-        const dest = join(dir, resource.relPath);
-        await mkdir(dirname(dest), { recursive: true });
-        await writeFile(dest, resource.content, 'utf8');
-    }
-}
-/**
- * Prepare the Claude Code CLI's MCP wiring for one run: write the servers to a PER-RUN config and
- * return the argv that points the CLI at it, plus the cleanup for a directory we had to mint.
- *
- * Two decisions live here. `--strict-mcp-config` makes that file the ONLY source of servers, so an
- * ambient run on a developer's own machine can never silently hand the agent their personal ones.
- * And `--allowedTools` is passed ONLY when a server actually narrows its tools — an allow-list is
- * whole-session, not MCP-scoped, so `claudeAllowedToolPatterns` re-grants the CLI's built-in
- * file/bash tools in the same list; see it for why that holds whichever way the run's permission
- * mode treats an allow-list.
- *
- * The config carries this job's resolved credentials, so it goes in the isolated config home when
- * we own one and a throwaway per-JOB directory otherwise — never the checkout (it would land in a
- * commit) and never a shared HOME path (a concurrent job would clobber it).
- */
-async function setUpClaudeMcp(servers, configHome) {
-    const noop = { args: [], cleanup: async () => { } };
-    if (!servers?.length)
-        return noop;
-    // Before anything can spawn: a failing MCP server echoes its own argv/headers into stderr, and
-    // that tail is carried onto the step's diagnostics.
-    registerKnownSecrets(mcpServerSecretValues(servers));
-    const home = configHome ?? (await mkdtemp(join(tmpdir(), 'cf-claude-mcp-')));
-    const owned = home === configHome ? undefined : home;
-    const cleanup = async () => {
-        if (owned)
-            await rm(owned, { recursive: true, force: true }).catch(() => { });
-    };
-    const configPath = await writeClaudeMcpConfig(home, servers);
-    if (!configPath)
-        return { args: [], cleanup };
-    const allowedTools = claudeAllowedToolPatterns(servers);
-    return {
-        args: [
-            '--mcp-config',
-            configPath,
-            '--strict-mcp-config',
-            ...(allowedTools?.length ? ['--allowedTools', allowedTools.join(',')] : []),
-        ],
-        cleanup,
-    };
-}
 /**
  * The LIVE publishers of a claude-code run: everything the stream has revealed so far that the
  * backend should see before the run ends, rather than only in its terminal result.
@@ -383,52 +308,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 +
@@ -520,6 +399,13 @@ function openClaudeCallCapture(opts, stream) {
         },
     };
 }
+/**
+ * Run the Claude Code CLI headlessly against `opts.cwd`, authenticated with the
+ * leased subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN), talking direct to
+ * api.anthropic.com. Streams `--output-format stream-json`, mapping the
+ * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
+ * onto the summary + usage.
+ */
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -536,6 +422,9 @@ export async function runClaudeCode(opts) {
             bytes: Buffer.byteLength(opts.systemPrompt, 'utf8'),
         });
     }
+    // The built-in tools this run declares, named ONCE: the same list rides `--tools` and the
+    // `--allowedTools` re-grant, which is additive rather than inert (see `claudeAllowedToolPatterns`).
+    const tools = CLAUDE_TOOL_SET;
     const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [];
     const capture = openClaudeCallCapture(opts, { prompt, folded, secrets });
     const telemetry = capture.telemetry;
@@ -577,6 +466,9 @@ export async function runClaudeCode(opts) {
     const onEvent = (event, meta) => {
         const type = event.type;
         reportToolServerStartup(event, opts.onToolServers);
+        // The same startup event answers what the CLI granted of what we asked for; a capability it
+        // named no tool for is a silent capability loss otherwise (see `assertClaudeToolsCurrent`).
+        assertClaudeToolsCurrent(event, tools, opts.log);
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
         // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
         // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on
@@ -638,7 +530,7 @@ export async function runClaudeCode(opts) {
             terminalReport = claudeResultReport(event) || terminalReport;
         }
     };
-    const home = await openClaudeRunHome(opts);
+    const home = await openClaudeRunHome(opts, tools);
     const { configHome } = home;
     // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
     // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
@@ -668,22 +560,7 @@ export async function runClaudeCode(opts) {
     try {
         const { stderrTail } = await streamCli({
             command: 'claude',
-            args: [
-                '-p',
-                '--output-format',
-                'stream-json',
-                '--verbose',
-                // The per-run container IS the sandbox, and the run is fully headless (no one
-                // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
-                // would auto-accept file edits but still gate Bash, which in `-p` mode is then
-                // denied, leaving the agent unable to run builds/tests/git to verify its work.
-                '--permission-mode',
-                'bypassPermissions',
-                '--model',
-                opts.model,
-                ...home.mcpArgs,
-                ...appendArgs,
-            ],
+            args: claudeCliArgs({ model: opts.model, tools, mcpArgs: home.mcpArgs, appendArgs }),
         }, prompt, { ...opts, signal: runSignal }, home.env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // The stream has ended, so the last call has no successor envelope to complete it.
         telemetry.flush();
@@ -732,91 +609,6 @@ export async function runClaudeCode(opts) {
         await home.dispose();
     }
 }
-async function openClaudeRunHome(opts) {
-    // Native (ambient) mode: run the developer's installed `claude` with its OWN login —
-    // no isolated config home, no injected credential, no onboarding pre-seed. Otherwise,
-    // Claude Code persists user config/credentials under its config dir; point that at an
-    // isolated, per-run temp dir OUTSIDE the cloned checkout (`opts.cwd`). Otherwise the
-    // agents that finish with `git add -A` (blueprint/requirements/bootstrap) could stage a
-    // stray `.claude/` directory — and any cached credential in it — into the pushed branch.
-    // Mirrors the Codex CODEX_HOME isolation below; removed by `dispose`.
-    if (!opts.ambientAuth && !opts.subscriptionToken) {
-        throw new Error('claude-code harness requires a subscription token (or ambientAuth)');
-    }
-    const configHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-claude-'));
-    // The config dir is brand-new every run, so Claude Code would otherwise treat this
-    // as a first launch and BLOCK on the interactive onboarding / "trust this folder" /
-    // bypass-permissions acknowledgement prompts — which never get answered headlessly,
-    // hanging the job until the watchdog kills it. Pre-seed the config that marks those
-    // as already accepted so `-p` starts straight into the run. Best-effort: written
-    // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
-    // (Ambient mode skips this — the developer's own config is already onboarded.)
-    // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
-    // version, so a future first-run gate this set doesn't cover (which looks identical to
-    // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
-    if (configHome) {
-        await writeOnboardingPreseed(configHome);
-        await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
-    }
-    // Skills: install each as a native skill under the config dir's `skills/<name>/` so the CLI
-    // discovers and can invoke it. ONLY into the isolated per-run config home — never the
-    // developer's own `~/.claude` (ambient/native mode), where it would persist in their personal
-    // setup after the run and two concurrent jobs carrying same-named skills would clobber each
-    // other. An ambient run reads the skills from the checkout instead (`.cat-context/skill/<name>/`,
-    // materialised by the caller). Best-effort: a write failure must not wedge the run — the prompt
-    // still names the skills.
-    if (configHome) {
-        for (const skill of opts.skills ?? []) {
-            await writeNativeSkill(join(configHome, 'skills'), skill).catch(() => { });
-        }
-    }
-    // Tool servers (MCP): the CLI is pointed at a per-run config rather than discovering an ambient
-    // one. See `setUpClaudeMcp` for why that matters and what has to be cleaned up afterwards.
-    const mcp = await setUpClaudeMcp(opts.mcpServers, configHome);
-    return {
-        configHome,
-        mcpArgs: mcp.args,
-        env: buildClaudeEnv(opts, configHome),
-        dispose: async () => {
-            // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
-            await mcp.cleanup();
-            if (!configHome)
-                return;
-            // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
-            // home is deleted — the credential lives at the home root, never in `projects/`, so this
-            // keeps the debugging artifact without leaking the token. Best-effort; never throws.
-            await retainSessionTranscripts(configHome, ['projects'], {
-                label: 'claude-code',
-                ...(opts.log ? { log: opts.log } : {}),
-            });
-            // Never leave the config dir (and any cached credential) on disk past the run.
-            await rm(configHome, { recursive: true, force: true }).catch(() => { });
-        },
-    };
-}
-/**
- * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
- * auth (Anthropic OAuth token, or an Anthropic-compatible base URL + auth token for a
- * non-Anthropic Claude-Code vendor like GLM/Kimi/DeepSeek), or an empty env in ambient mode
- * (the developer's own logged-in `~/.claude` is used). Extracted from {@link runClaudeCode} to
- * keep its cyclomatic complexity down; behaviour is a straight move of the original expression.
- */
-function buildClaudeEnv(opts, configHome) {
-    // The job-scoped env rides along in BOTH modes; the credential/config vars below are what
-    // ambient mode drops (the developer's own logged-in `~/.claude` is used instead).
-    if (opts.ambientAuth)
-        return { ...opts.extraEnv };
-    return {
-        ...opts.extraEnv,
-        CLAUDE_CONFIG_DIR: configHome,
-        ...(opts.subscriptionBaseUrl
-            ? {
-                ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
-                ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken,
-            }
-            : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
-    };
-}
 /**
  * Merge the parent-loop telemetry with the subagents' out-of-band usage + per-call metrics into
  * the run outcome. INVARIANT (do not "fix" this into a double count): the run total is the parent
@@ -969,6 +761,12 @@ export async function runCodex(opts) {
                 'exec',
                 '--json',
                 '--skip-git-repo-check',
+                // No `--tools` analogue here, and its absence is a FINDING rather than an oversight:
+                // codex has no flag that declares a built-in tool set, because it has no set to choose
+                // from. Its surface is shell + apply_patch + the plan tool, and the optional extras are
+                // individual `CODEX_HOME/config.toml` switches the harness already sets deliberately
+                // (`[features] image_generation`, see `codex-home.ts`). So there is nothing here that
+                // silently drifts with a CLI version the way claude-code's headless default did.
                 // The per-run container IS the sandbox; let Codex write files and reach the
                 // vendor unrestricted, with no approval prompts (the run is headless).
                 '--dangerously-bypass-approvals-and-sandbox',

package/dist/agent-shared.d.ts

@@ -7,11 +7,18 @@ import type { EffortReport } from './effort.js';
  */
 export declare function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult;
 /**
- * The agent-capability fields (skills, tool servers, reference designs) every agent-running flow
- * forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow
- * cannot silently be the one that drops a kind's declared playbook, tool server or reference
- * gallery: the failure mode is invisible (the agent simply works without it) and would only show
- * up as degraded output.
+ * The agent-capability fields (skills, tool servers, reference designs, web research) every
+ * agent-running flow forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow
+ * spread, so a flow cannot silently be the one that drops a kind's declared playbook, tool server,
+ * reference gallery or web access: the failure mode is invisible (the agent simply works without
+ * it) and would only show up as degraded output.
+ *
+ * Web research joined the helper after the conflict-resolver and bootstrap flows were found to be
+ * forwarding neither half of it: both build their own spec literal, and the two web fields were
+ * hand-written at the four sites that remembered them. That is exactly the drift this helper
+ * exists to make unrepresentable, so they are read here rather than at each call site. Both halves
+ * travel together on purpose: the guidance NAMES the tools, so a flow carrying one without the
+ * other either describes tools the run was never given or hands it tools nothing introduced.
  */
 export declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
@@ -19,4 +26,6 @@ export declare function agentCapabilities(job: AgentJob): {
     generateImages?: boolean;
     referenceScreenshots?: ImageManifestSpec;
     designImages?: ImageManifestSpec;
+    webSearchProxy?: boolean;
+    webToolsGuidance?: string;
 };

package/dist/agent-shared.js

@@ -10,11 +10,18 @@ export function mergeEffort(result, effortReport) {
     return effortReport ? { ...result, effortReport } : result;
 }
 /**
- * The agent-capability fields (skills, tool servers, reference designs) every agent-running flow
- * forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow
- * cannot silently be the one that drops a kind's declared playbook, tool server or reference
- * gallery: the failure mode is invisible (the agent simply works without it) and would only show
- * up as degraded output.
+ * The agent-capability fields (skills, tool servers, reference designs, web research) every
+ * agent-running flow forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow
+ * spread, so a flow cannot silently be the one that drops a kind's declared playbook, tool server,
+ * reference gallery or web access: the failure mode is invisible (the agent simply works without
+ * it) and would only show up as degraded output.
+ *
+ * Web research joined the helper after the conflict-resolver and bootstrap flows were found to be
+ * forwarding neither half of it: both build their own spec literal, and the two web fields were
+ * hand-written at the four sites that remembered them. That is exactly the drift this helper
+ * exists to make unrepresentable, so they are read here rather than at each call site. Both halves
+ * travel together on purpose: the guidance NAMES the tools, so a flow carrying one without the
+ * other either describes tools the run was never given or hands it tools nothing introduced.
  */
 export function agentCapabilities(job) {
     return {
@@ -23,5 +30,7 @@ export function agentCapabilities(job) {
         ...(job.generateImages ? { generateImages: true } : {}),
         ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
         ...(job.designImages ? { designImages: job.designImages } : {}),
+        ...(job.webSearch ? { webSearchProxy: true } : {}),
+        ...(job.webToolsGuidance ? { webToolsGuidance: job.webToolsGuidance } : {}),
     };
 }

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)
@@ -541,8 +416,6 @@ async function runExploreMode(job, opts) {
                 // Read-only: it inspects and reports, making no edits — so the no-progress
                 // guard's no-edit bound must not fire on its legitimately edit-free run.
                 expectsEdits: false,
-                webToolsGuidance: job.webToolsGuidance,
-                webSearchProxy: job.webSearch,
                 contextFiles: job.contextFiles,
                 guardLimits: job.guardLimits,
                 ...agentCapabilities(job),
@@ -750,8 +623,6 @@ async function runMultiRepoExplore(job, opts) {
             sessionToken: job.sessionToken,
             // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
             expectsEdits: false,
-            webToolsGuidance: job.webToolsGuidance,
-            webSearchProxy: job.webSearch,
             ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
             guardLimits: job.guardLimits,
             ...agentCapabilities(job),
@@ -856,8 +727,6 @@ export function buildSingleRepoCodingSpec(job, pushBranch) {
         proxyPhasePath: job.proxyPhasePath,
         sessionToken: job.sessionToken,
         commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
         guardLimits: job.guardLimits,
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),

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.