@cat-factory/executor-harness 1.132.3 → 1.135.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,11 +368,17 @@ 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.                                                    |
 | `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc; the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`): talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
+| `src/claude-cli.ts` | The claude-code CLI's INVOCATION surface: the built-in tools a run DECLARES with `--tools` (the CLI's headless default has no `Grep`/`Glob` and no plan tools, and does carry a dozen an ephemeral container can act on none of), the argv that declares them, and the read-back of the CLI's `init` event that warns when a required capability was granted no tool. The list is over-inclusive on purpose, which `--tools` makes safe: an unknown name is dropped silently and a RETIRED one is an alias onto its successor, so one pinned image can face several CLI versions. The web tools are unconditional, being served by the vendor the leased subscription pays rather than by this deployment's search proxy. The same list also rides the `--allowedTools` re-grant, which is ADDITIVE rather than inert, so the two are one value threaded rather than two lists. |
+| `src/claude-home.ts` | The PER-RUN claude-code config home (`codex-home.ts`'s sibling): the isolated `CLAUDE_CONFIG_DIR` outside the checkout, its onboarding pre-seed, the run's natively-installed skills, its `--mcp-config`, the child env carrying the leased credential, and the teardown that lifts the session transcripts out before deleting it. |
 | `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation: the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations, and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
 | `src/usage-attribution.ts` | Reconciles a subscription CLI's TWO token channels: the per-turn usage its stream narrates and the cumulative total its terminal event reports. They disagree routinely and in one direction (Claude Code's per-turn `output_tokens` is the message-START snapshot, single digits), so whatever the turns did not account for becomes ONE extra metric standing for the job (`standsForJob`, filed with a null turn index) rather than tokens grafted onto a real turn, which would make a derived number read as a measured one. Reconciled against the PARENT loop's calls alone, since the terminal cumulative covers only that conversation. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
@@ -350,6 +395,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 +420,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-capabilities.d.ts

@@ -173,39 +173,36 @@ export declare function parseMcpServerSpecs(value: unknown): McpServerSpec[] | u
 export declare function claudeMcpConfig(servers: McpServerSpec[]): {
     mcpServers: Record<string, Record<string, unknown>>;
 };
-/**
- * The claude-code CLI's own tools, named so an `--allowedTools` list can never take them away.
- *
- * An allow-list is whole-session: it does not scope itself to MCP just because every entry we
- * generate happens to be an `mcp__*` pattern. So the moment one tool server narrows its tools, the
- * list has to re-grant the agent's built-in file/bash/search tools or the run is handed a narrowed
- * MCP surface AND no way to read, edit or build anything.
- *
- * Bias this list toward OVER-inclusion. A name the CLI does not have is inert; a name it has and
- * this list lacks is a tool silently removed from a run — which surfaces as an agent that cannot
- * do its work, far from the registration that caused it. Historical/renamed spellings are kept for
- * the same reason: the harness image is pinned per workspace, so one image faces several CLI
- * versions. When the CLI gains a tool, add it here.
- */
-export declare const CLAUDE_BUILT_IN_TOOLS: readonly string[];
 /**
  * The tool-name list for `--allowedTools`: every declared server's tools in the CLI's
- * `mcp__<server>__<tool>` convention, PLUS {@link CLAUDE_BUILT_IN_TOOLS}. A server with no
- * restriction contributes the whole-server pattern, so an allow-list stays one entry per server.
+ * `mcp__<server>__<tool>` convention, PLUS the built-in tools this run declared with `--tools`
+ * (`CLAUDE_TOOL_SET`). A server with no restriction contributes the whole-server pattern, so
+ * an allow-list stays one entry per server.
  *
  * Returns undefined when NO server restricts its tools — there is then nothing to narrow, and the
  * safest list is the one we never send.
  *
+ * An allow-list is whole-session, not MCP-scoped: it does not confine itself to MCP just because
+ * every entry we generate happens to be an `mcp__*` pattern. So the moment one tool server narrows
+ * its tools, the list has to carry the built-in file/bash/search tools too or the run is handed a
+ * narrowed MCP surface AND no way to read, edit or build anything.
+ *
+ * And carrying them is not merely a re-grant. MEASURED against CLI 2.1.245, the list is ADDITIVE:
+ * `--allowedTools "Bash,Grep"` yields the CLI's default set PLUS `Glob` and `Grep`, and an EMPTY
+ * list yields the default set plus `Glob`, `Grep` and the four `Task*` tools. A name here UNLOCKS
+ * a tool. That is why `builtIns` is the run's OWN declared set passed by reference rather than a
+ * constant re-read here: a separately-derived list would silently re-grant exactly what the
+ * `--tools` declaration withheld, and only on the runs that happen to wire a narrowing tool
+ * server.
+ *
  * Whether the CLI ENFORCES this list is permission-mode dependent and not a contract we control:
  * the run uses `--permission-mode bypassPermissions` (the container is the sandbox and no human is
- * there to approve a call), under which an allow-list grants rather than gates. So this is written
- * to be correct under BOTH readings — if the list gates, the narrowing is real and the built-ins
- * survive it; if it is inert, sending it costs nothing. The always-present channel is the PROMPT,
- * which states each server's permitted tool names on every harness. Treat `allowedTools` as
- * scoping, not as a security boundary: a server the agent must not reach fully should not be
- * wired for that kind at all.
+ * there to approve a call), under which an allow-list grants rather than gates. The always-present
+ * channel is the PROMPT, which states each server's permitted tool names on every harness. Treat
+ * `allowedTools` as scoping, not as a security boundary: a server the agent must not reach fully
+ * should not be wired for that kind at all.
  */
-export declare function claudeAllowedToolPatterns(servers: McpServerSpec[]): string[] | undefined;
+export declare function claudeAllowedToolPatterns(servers: McpServerSpec[], builtIns: readonly string[]): string[] | undefined;
 /**
  * The `[mcp_servers.<id>]` TOML block Codex reads from its `CODEX_HOME/config.toml`. Codex's MCP
  * client is stdio-only, so an `http` server is skipped here.

package/dist/agent-capabilities.js

@@ -418,68 +418,40 @@ export function claudeMcpConfig(servers) {
     }
     return { mcpServers };
 }
-/**
- * The claude-code CLI's own tools, named so an `--allowedTools` list can never take them away.
- *
- * An allow-list is whole-session: it does not scope itself to MCP just because every entry we
- * generate happens to be an `mcp__*` pattern. So the moment one tool server narrows its tools, the
- * list has to re-grant the agent's built-in file/bash/search tools or the run is handed a narrowed
- * MCP surface AND no way to read, edit or build anything.
- *
- * Bias this list toward OVER-inclusion. A name the CLI does not have is inert; a name it has and
- * this list lacks is a tool silently removed from a run — which surfaces as an agent that cannot
- * do its work, far from the registration that caused it. Historical/renamed spellings are kept for
- * the same reason: the harness image is pinned per workspace, so one image faces several CLI
- * versions. When the CLI gains a tool, add it here.
- */
-export const CLAUDE_BUILT_IN_TOOLS = [
-    'Agent',
-    'Bash',
-    'BashOutput',
-    'Edit',
-    'ExitPlanMode',
-    'Glob',
-    'Grep',
-    'KillBash',
-    'KillShell',
-    'ListMcpResources',
-    'MultiEdit',
-    'NotebookEdit',
-    'NotebookRead',
-    'Read',
-    'ReadMcpResource',
-    'SlashCommand',
-    'Skill',
-    'Task',
-    'TaskCreate',
-    'TaskUpdate',
-    'TodoWrite',
-    'WebFetch',
-    'WebSearch',
-    'Write',
-];
 /**
  * The tool-name list for `--allowedTools`: every declared server's tools in the CLI's
- * `mcp__<server>__<tool>` convention, PLUS {@link CLAUDE_BUILT_IN_TOOLS}. A server with no
- * restriction contributes the whole-server pattern, so an allow-list stays one entry per server.
+ * `mcp__<server>__<tool>` convention, PLUS the built-in tools this run declared with `--tools`
+ * (`CLAUDE_TOOL_SET`). A server with no restriction contributes the whole-server pattern, so
+ * an allow-list stays one entry per server.
  *
  * Returns undefined when NO server restricts its tools — there is then nothing to narrow, and the
  * safest list is the one we never send.
  *
+ * An allow-list is whole-session, not MCP-scoped: it does not confine itself to MCP just because
+ * every entry we generate happens to be an `mcp__*` pattern. So the moment one tool server narrows
+ * its tools, the list has to carry the built-in file/bash/search tools too or the run is handed a
+ * narrowed MCP surface AND no way to read, edit or build anything.
+ *
+ * And carrying them is not merely a re-grant. MEASURED against CLI 2.1.245, the list is ADDITIVE:
+ * `--allowedTools "Bash,Grep"` yields the CLI's default set PLUS `Glob` and `Grep`, and an EMPTY
+ * list yields the default set plus `Glob`, `Grep` and the four `Task*` tools. A name here UNLOCKS
+ * a tool. That is why `builtIns` is the run's OWN declared set passed by reference rather than a
+ * constant re-read here: a separately-derived list would silently re-grant exactly what the
+ * `--tools` declaration withheld, and only on the runs that happen to wire a narrowing tool
+ * server.
+ *
  * Whether the CLI ENFORCES this list is permission-mode dependent and not a contract we control:
  * the run uses `--permission-mode bypassPermissions` (the container is the sandbox and no human is
- * there to approve a call), under which an allow-list grants rather than gates. So this is written
- * to be correct under BOTH readings — if the list gates, the narrowing is real and the built-ins
- * survive it; if it is inert, sending it costs nothing. The always-present channel is the PROMPT,
- * which states each server's permitted tool names on every harness. Treat `allowedTools` as
- * scoping, not as a security boundary: a server the agent must not reach fully should not be
- * wired for that kind at all.
+ * there to approve a call), under which an allow-list grants rather than gates. The always-present
+ * channel is the PROMPT, which states each server's permitted tool names on every harness. Treat
+ * `allowedTools` as scoping, not as a security boundary: a server the agent must not reach fully
+ * should not be wired for that kind at all.
  */
-export function claudeAllowedToolPatterns(servers) {
+export function claudeAllowedToolPatterns(servers, builtIns) {
     if (!servers.some((s) => s.allowedTools?.length))
         return undefined;
     const mcp = servers.flatMap((s) => s.allowedTools?.length ? s.allowedTools.map((t) => `mcp__${s.id}__${t}`) : [`mcp__${s.id}`]);
-    return [...mcp, ...CLAUDE_BUILT_IN_TOOLS];
+    return [...mcp, ...builtIns];
 }
 /** Escape a string as a TOML basic string (Codex config is TOML, not JSON). */
 function tomlString(value) {

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. */
@@ -152,6 +161,13 @@ export declare function carryClaudeSystemPrompt(systemPrompt: string, userPrompt
     prompt: string;
     folded: boolean;
 };
+/**
+ * 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 declare function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome>;
 /**
  * Run the Codex CLI headlessly against `opts.cwd`, authenticated with the leased