@cat-factory/executor-harness 1.135.0 → 1.137.0

package/README.md

@@ -116,6 +116,51 @@ Bootstrap differs at the ends: it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+### The environment is probed once, not by the agent
+
+Before any mode branches, `handleAgent` probes the machine it is about to run on and appends an
+`ENVIRONMENT INVENTORY` block to the job's system prompt (`src/environment-inventory.ts`). It names
+the toolchain that answered and its versions, the curated list of tools that did not, and whether a
+Docker DAEMON is actually reachable.
+
+It exists because the platform used to ask every agent to find this out for itself, and every agent
+did: in one measured run an architect ran `for c in docker kubectl helm kustomize; …` and then
+`docker info`, and the coder it handed off to rediscovered both answers thirty calls later. Four
+calls out of a forty-call budget for facts this process holds before the agent's first turn. The
+backend cannot hold them (it composes its prompt before a transport is chosen, and the same body
+reaches this image, a deployment's own image variant and, under `LOCAL_NATIVE_AGENTS`, the
+developer's own machine), so it states the POLICY and names no tooling at all.
+
+Three rules bind anything added to it:
+
+- **A failed probe is not an absence.** Only `ENOENT` means "not installed"; a timeout or a refused
+  spawn renders on its own line as could-not-be-determined, because the two lead an agent to
+  opposite next moves.
+- **An unlisted tool is unknown too**, which the block's last line says. The probe list is curated,
+  so silence about `terraform` must not read as its absence.
+- **The Docker daemon is answered by running `docker info`**, never by finding the CLI. The CLI is
+  installed in this image unconditionally, `entrypoint.sh` starts the rootless daemon best-effort
+  and execs the server without waiting for it, so at job start this probe is the only thing that
+  knows how that went.
+- **A daemon that is STARTING is not a daemon that is absent.** Because the entrypoint does not
+  wait, the backend dispatches seconds before there is a socket, and `docker info` is then refused
+  at once rather than slowly. So a refusal is read against `DOCKER_HOST`, which the entrypoint sets
+  whenever something is meant to serve a daemon here: unset means nothing was coming and the
+  absence is stated definitively, set means one short retry and then could-not-be-determined. The
+  absent wording tells an agent `docker compose up` "will fail here whatever the CLI reports", which
+  is a prohibition, so it may only be reached where nothing is going to answer.
+- **A tool the platform did not provide is not installable system-wide either**, since the job runs
+  unprivileged. The line says that instead of banning installation outright: `pnpm` is absent from
+  this image (only the UI variant carries it), so it is routinely the package manager the job's own
+  repository declares, and a flat prohibition pushed agents onto `npm install` against a pnpm
+  lockfile. Reaching a project's own manager for that project alone is allowed and named.
+
+Composed at exactly ONE point, onto the job's own `systemPrompt`, which every mode already forwards
+and all three CLIs already carry (claude-code's `--append-system-prompt` and its oversized-argv
+fallback, Codex's fold, Pi's `AGENTS.md`). `test/environment-inventory.coverage.test.ts` pins that:
+a mode that folded its own copy would state the machine twice, and one that folded none would leave
+its agent probing, with nothing failing either way.
+
 ### The work-branch push is CHECKPOINTED, so it is lease-guarded
 
 Step 8's push is not the run's first: every `JOB_CHECKPOINT_INTERVAL_MS` (60s) the harness pushes
@@ -393,6 +438,7 @@ verdict is stated.
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/artifact-upload.ts` | The OUTBOUND half of the artifact seam: parses the body's `artifactUpload` and projects it onto the agent's env as `ARTIFACT_UPLOAD_URL` / `ARTIFACT_UPLOAD_TOKEN`, registering the token for redaction first. Passes through what the body carries and decides nothing: which kinds get the seam is the backend's call. |
 | `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/environment-inventory.ts` | What the MACHINE holds, probed once per job and appended to the agent's system prompt as an ENVIRONMENT INVENTORY block. The only layer that can state it: the backend composes its prompt before a transport is chosen, and the same body serves this image, a deployment's own variant and the developer's laptop under `LOCAL_NATIVE_AGENTS`. Three-valued on purpose, so a probe that failed renders as unknown rather than as an absence, and the Docker DAEMON is answered by running `docker info` rather than by finding the CLI, which is installed here either way. See [The environment is probed once, not by the agent](#the-environment-is-probed-once-not-by-the-agent). |
 | `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). |

package/dist/agent.js

@@ -17,6 +17,7 @@ import { runMultiRepoCoding } from './multi-repo-coding.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';
+import { appendEnvironmentInventory } from './environment-inventory.js';
 import { runBootstrap } from './bootstrap-mode.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
@@ -126,9 +127,27 @@ export async function handleAgent(job, opts = {}) {
         });
         if (job.mode === 'preview')
             return await runPreviewMode(job, scoped);
-        return job.mode === 'coding'
-            ? await runCodingMode(job, scoped)
-            : await runExploreMode(job, scoped);
+        // THE composition point for the environment inventory (see `environment-inventory.ts`): the
+        // machine is probed ONCE here, before any mode branches, and the result is folded onto the
+        // job's own system prompt. Every mode, every repair round and all three agent CLIs read that
+        // one field, so none of them can end up without the block and none can carry it twice.
+        // `preview` returns above because it runs no agent at all, so there is no prompt to fold onto.
+        //
+        // This sits on the critical path AHEAD of the clone, which is the cost of having one
+        // composition point instead of one per mode (each mode owns its own clone, so there is no
+        // single post-clone place to put this). The pass is sized for that: everything in it runs
+        // concurrently, every probe is a call that answers in milliseconds or is wedged, and the one
+        // deliberate wait is a single short retry for a daemon that is still starting.
+        const staged = {
+            ...job,
+            systemPrompt: await appendEnvironmentInventory(job.systemPrompt, {
+                ...(opts.signal ? { signal: opts.signal } : {}),
+                ...(opts.log ? { log: opts.log } : {}),
+            }),
+        };
+        return staged.mode === 'coding'
+            ? await runCodingMode(staged, scoped)
+            : await runExploreMode(staged, scoped);
     }
     finally {
         if (scopeDir)

package/dist/environment-inventory.d.ts

@@ -0,0 +1,158 @@
+import { type Logger } from './logger.js';
+/**
+ * What running one probe did, kept as RAW as the spawn: whether the binary ran, and with what.
+ * Classification into presence lives in pure code below, because the two callers classify the
+ * same result differently: a non-zero exit proves an ordinary tool is installed and proves the
+ * Docker daemon is not reachable.
+ *
+ * `found` is the outcome with no exit code, and it exists so that the Windows second look cannot
+ * be mistaken for a run: the platform's own oracle located the binary and NOTHING WAS EXECUTED.
+ * Collapsing it into `ran` with a synthesised `exitCode: 0` is what let `docker info` report a
+ * reachable daemon on the strength of `where docker`, which is the CLI-for-daemon half-truth this
+ * whole file exists to remove.
+ */
+export type ProbeResult = {
+    outcome: 'ran';
+    exitCode: number;
+    output: string;
+} | {
+    outcome: 'found';
+} | {
+    outcome: 'missing';
+} | {
+    outcome: 'failed';
+    reason: string;
+};
+/** Run one probe. Injected so the suite drives every branch without needing the real binaries. */
+export type ProbeRunner = (command: string, args: string[]) => Promise<ProbeResult>;
+/** What one probe learned. `unknown` is a THIRD answer, never folded into `absent`. */
+export type ToolPresence = {
+    status: 'present';
+    version?: string;
+} | {
+    status: 'absent';
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/** One probed entry: the name the agent would type, and what came back. */
+export interface ProbedTool {
+    name: string;
+    presence: ToolPresence;
+    /** Whether the rendered line carries the version. Off where a yes/no is the whole answer. */
+    showVersion: boolean;
+}
+/** Everything one job's probe pass learned about the machine it is about to run on. */
+export interface EnvironmentInventory {
+    tools: ProbedTool[];
+    /**
+     * Whether a Docker daemon actually answered: the readiness fact, not the CLI's presence. The
+     * image's `entrypoint.sh` starts a rootless daemon BEST-EFFORT and execs the server without
+     * waiting for it, so at job start this probe is the only thing that knows how that went, and
+     * "has not answered yet" is one of its answers (see {@link probeDockerDaemon}).
+     */
+    dockerDaemon: ToolPresence;
+}
+/**
+ * The real runner: spawn the tool, bounded, and report what the spawn did.
+ *
+ * The Windows second look is for the NATIVE transport on a developer's own machine, not for the
+ * image. `execFile` without a shell resolves `.exe` and not `.cmd`, and Node refuses to spawn a
+ * `.cmd` at all without one, so a perfectly installed `npm` or `pnpm` comes back `ENOENT` there and
+ * would be stated to the agent as NOT INSTALLED. `where` is the platform's own presence oracle and
+ * answers that without running the shim, at the cost of the version, which is the honest trade: the
+ * rendered line then names the tool with no number rather than claiming one or denying the tool.
+ *
+ * It answers PRESENCE and nothing else, which is why it returns `found` and why it ignores `args`
+ * without pretending otherwise: `where <command>` locates a binary, so it can say nothing about
+ * what that binary would have printed or exited with. The version is not the only thing lost. A
+ * probe whose ANSWER is its exit code (`docker info`) gets no answer at all from this branch, and
+ * {@link daemonPresence} is where that is turned into an unknown rather than a reachable daemon.
+ */
+export declare function spawnProbeRunner(signal?: AbortSignal): ProbeRunner;
+/**
+ * What the `where` oracle's own result says about the TOOL. Pure, and separate from the spawn, so
+ * every branch is asserted on any platform: reproducing the failing one for real needs a process
+ * whose PATH cannot reach `where`, and mutating the live `PATH` to get one leaks into whatever test
+ * runs next (on Windows `PATH` and `Path` are one variable, so restoring them is not symmetric).
+ *
+ * The distinction the branches exist for: `where` exiting non-zero IS the tool's absence, but
+ * `where` not answering at all says nothing about the tool, so that becomes a FAILED probe. Passing
+ * the oracle's result straight back reported the ORACLE's own `missing` as the tool's, which put a
+ * fully installed npm on the "Not installed" line on any host where `where` cannot be spawned.
+ *
+ * A located tool is `found`, never a synthesised `ran` with `exitCode: 0`: the oracle located a
+ * binary and executed nothing, so it cannot answer for a probe whose answer IS its exit code.
+ */
+export declare function readOracle(located: ProbeResult): ProbeResult;
+/**
+ * An ordinary tool's presence: it ran (whatever it exited with) ⇒ installed, `ENOENT` ⇒ not
+ * installed, anything else ⇒ the probe failed and we do not know. `helm version` on a host with
+ * no cluster config exits non-zero and still proves helm is installed.
+ */
+export declare function toolPresence(result: ProbeResult): ToolPresence;
+/**
+ * The daemon's presence, which reads the SAME result differently in exactly TWO places, and
+ * delegates the rest: duplicating the other three branches to add these two is how a change to
+ * how a version is read, or how a failure reason is carried, gets made in one classifier only.
+ *
+ *   - A non-zero exit is "cannot connect to the Docker daemon", so it is an absence rather than the
+ *     proof-of-install a non-zero exit is everywhere else.
+ *   - `found` means the Windows oracle located the CLI and ran NOTHING, so the daemon was never
+ *     asked. That is an unknown. Reading it as `toolPresence` would is what made `where docker`
+ *     enough to tell an agent `docker build` works here.
+ */
+export declare function daemonPresence(result: ProbeResult): ToolPresence;
+/** What one probe pass may be told, so the suite drives the daemon's retry without waiting on it. */
+export interface ProbeEnvironmentOptions {
+    /** Injected so tests exercise the retry without paying {@link DAEMON_RETRY_DELAY_MS}. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Whether a daemon is CONFIGURED to serve this machine, defaulting to {@link daemonIsConfigured}.
+     * Stated as the fact rather than as the `DOCKER_HOST` string it is read from, so a test can drive
+     * both sides of the branch without an ambient environment variable deciding the outcome for it.
+     */
+    daemonExpected?: boolean;
+}
+/**
+ * Probe the machine. EVERYTHING runs concurrently, the daemon included.
+ *
+ * The daemon probe used to be sequenced after the tool pass, so that a missing CLI could
+ * short-circuit it. That bought a cleaner `absent` and charged the whole job for it: two ceilings
+ * back to back on the critical path, ahead of the clone, on every dispatch. It is unnecessary,
+ * because `docker info` answers the CLI question too: with no CLI on PATH the spawn comes back
+ * `missing`, which {@link daemonPresence} already reads as the same absence the short-circuit
+ * produced. Asking directly also removes a second defect the sequencing needed: reading the CLI's
+ * presence back out of `tools` defaulted a MISSING list entry to `absent`, so trimming the curated
+ * list would have had the block assert "NO Docker daemon is reachable" with nothing ever asked.
+ */
+export declare function probeEnvironment(run: ProbeRunner, opts?: ProbeEnvironmentOptions): Promise<EnvironmentInventory>;
+/**
+ * The block appended to the agent's system prompt. Pure, so what the agent reads is asserted
+ * against a probe result rather than against whichever machine the suite happens to run on.
+ *
+ * Each line is a different KIND of claim, and they are kept apart because collapsing them is the
+ * failure this replaces: what is here, what is not, what could not be determined, what the Docker
+ * daemon actually said, and, last because it governs everything the other lines omit, that the
+ * list is bounded.
+ */
+export declare function renderEnvironmentInventory(inventory: EnvironmentInventory): string;
+/**
+ * Probe the machine and fold the inventory onto `systemPrompt`. THE composition point: the harness
+ * calls this once per job, in `handleAgent`, before any mode branches, so every mode and every CLI
+ * (claude-code, codex, Pi) inherits it from the job's own system prompt instead of each folding a
+ * copy, which is how one of them would silently end up without it, and another with it twice.
+ *
+ * It rides the SYSTEM prompt rather than the task prompt so it survives the claude runner's
+ * argv-size branch (`carryClaudeSystemPrompt` folds an oversized system prompt into stdin whole),
+ * Codex's unconditional fold and Pi's `AGENTS.md` write, none of which can drop part of it.
+ *
+ * Never throws: an inventory is context, and a job whose probe pass fell over is still a job worth
+ * running. A probe that fails is already reported as unknown by construction, so this catch is for
+ * the pass itself, and it says so in a log line rather than silently shortening the prompt.
+ */
+export declare function appendEnvironmentInventory(systemPrompt: string, opts?: {
+    signal?: AbortSignal;
+    log?: Logger;
+    run?: ProbeRunner;
+} & ProbeEnvironmentOptions): Promise<string>;

package/dist/environment-inventory.js

@@ -0,0 +1,412 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { log } from './logger.js';
+// ---------------------------------------------------------------------------
+// What this machine actually has, probed ONCE per job and stated to the agent.
+//
+// The platform used to tell every agent to discover its own environment ("probe for a tool before
+// relying on it"), and every agent did, repeatedly, and often twice within one run: an architect
+// ran `for c in docker kubectl helm kustomize; do command -v $c; done`, then `docker info`, and
+// the coder it handed off to rediscovered both answers thirty calls later. Four calls out of a
+// forty-call budget, spent on facts the harness holds before the agent's first turn.
+//
+// This is the layer that CAN hold them, and the only one. The backend composes its prompt before a
+// transport is even chosen, and the same job body serves the harness image, a deployment's own
+// image variant and (under `LOCAL_NATIVE_AGENTS`) the developer's own machine, where the
+// toolchain is theirs. So the backend states the POLICY (no cluster credentials; an artifact this
+// environment cannot execute is still a correct artifact) and names no tooling at all, while this
+// file states the FACTS, from a probe of the machine the agent is about to run on.
+//
+// Three rules the block is built around:
+//
+//   - ABSENT and UNKNOWN must not render the same. Only a spawn that came back `ENOENT` is an
+//     absence; a probe that failed says so and is reported as neither present nor absent.
+//   - A tool NOT ON THE LIST is unknown too, which the block's last line says. The list is curated
+//     (what agents were observed rediscovering), so silence about `terraform` has to read as
+//     "nobody looked", never as "it isn't there".
+//   - The Docker DAEMON is a separate fact from the docker CLI, and it is the one that decides
+//     anything: `command -v docker` succeeds in this image and `docker build` still fails, which
+//     is the half-truth the old instruction produced. It is answered by RUNNING `docker info`, and
+//     a daemon this machine is CONFIGURED for but which has not answered yet is a fourth state
+//     that resolves to `unknown`, never to the absence a refused connection looks like: the
+//     image's daemon is started in the background and the job begins before it is ready.
+//
+// Deliberately NOT here: the agent's own tools (web search, file tools, MCP servers). Those are
+// the CLI's, they differ per harness, and each is already stated where it is true. Claiming one
+// here would be the platform asserting a capability the dispatch may not have delivered, which is
+// the defect this whole change exists to remove.
+// ---------------------------------------------------------------------------
+const execFileAsync = promisify(execFile);
+/**
+ * The curated probe list: the toolchain an agent assumes, plus the tools runs were observed
+ * burning calls to discover. Kept SHORT on purpose. Every entry is a spawn and a few more words
+ * in every system prompt, and the block's closing line keeps an unlisted tool honestly unknown
+ * rather than implicitly absent.
+ *
+ * `showVersion` is on where the number changes what the agent does (comparing against a target's
+ * declared engines, a language's syntax level) and off where presence is the whole question.
+ */
+const PROBES = [
+    { name: 'node', command: 'node', args: ['--version'], showVersion: true },
+    { name: 'npm', command: 'npm', args: ['--version'], showVersion: true },
+    { name: 'pnpm', command: 'pnpm', args: ['--version'], showVersion: true },
+    { name: 'git', command: 'git', args: ['--version'], showVersion: true },
+    { name: 'python3', command: 'python3', args: ['--version'], showVersion: true },
+    { name: 'docker', command: 'docker', args: ['--version'], showVersion: false },
+    { name: 'jq', command: 'jq', args: ['--version'], showVersion: false },
+    { name: 'rg', command: 'rg', args: ['--version'], showVersion: false },
+    { name: 'curl', command: 'curl', args: ['--version'], showVersion: false },
+    { name: 'make', command: 'make', args: ['--version'], showVersion: false },
+    { name: 'kubectl', command: 'kubectl', args: ['version', '--client'], showVersion: false },
+    { name: 'helm', command: 'helm', args: ['version'], showVersion: false },
+    { name: 'kustomize', command: 'kustomize', args: ['version'], showVersion: false },
+];
+/** The daemon readiness probe: the one probe whose EXIT CODE, not its presence, is the answer. */
+const DOCKER_INFO = {
+    command: 'docker',
+    args: ['info', '--format', '{{.ServerVersion}}'],
+};
+/**
+ * Every probe here is either instant or wedged: a `--version` banner, and a `docker info` that
+ * either connects or is REFUSED by a missing socket in milliseconds. So the ceiling is sized to
+ * cut a wedged binary out of the job's critical path, not to wait for anything.
+ *
+ * It used to be ten seconds, on the stated grounds that `docker info` "can genuinely take a
+ * moment" against a daemon still coming up. That was wrong in the way that matters: a daemon that
+ * is not up yet has no socket to connect to, so docker exits non-zero AT ONCE and the ceiling is
+ * never reached. Waiting for a starting daemon is a different problem and is solved where it
+ * actually lives, in {@link probeDockerDaemon}'s retry.
+ */
+const PROBE_TIMEOUT_MS = 5_000;
+/**
+ * How long a daemon that was EXPECTED here gets to answer before the block says it could not be
+ * determined. One short retry, not a readiness wait: the honest verdict for a daemon still coming
+ * up is `unknown`, which the rendered line turns into "try it if you need it", so there is nothing
+ * to buy by blocking the agent's first turn any longer than this.
+ */
+const DAEMON_RETRY_DELAY_MS = 1_500;
+/**
+ * The real runner: spawn the tool, bounded, and report what the spawn did.
+ *
+ * The Windows second look is for the NATIVE transport on a developer's own machine, not for the
+ * image. `execFile` without a shell resolves `.exe` and not `.cmd`, and Node refuses to spawn a
+ * `.cmd` at all without one, so a perfectly installed `npm` or `pnpm` comes back `ENOENT` there and
+ * would be stated to the agent as NOT INSTALLED. `where` is the platform's own presence oracle and
+ * answers that without running the shim, at the cost of the version, which is the honest trade: the
+ * rendered line then names the tool with no number rather than claiming one or denying the tool.
+ *
+ * It answers PRESENCE and nothing else, which is why it returns `found` and why it ignores `args`
+ * without pretending otherwise: `where <command>` locates a binary, so it can say nothing about
+ * what that binary would have printed or exited with. The version is not the only thing lost. A
+ * probe whose ANSWER is its exit code (`docker info`) gets no answer at all from this branch, and
+ * {@link daemonPresence} is where that is turned into an unknown rather than a reachable daemon.
+ */
+export function spawnProbeRunner(signal) {
+    const attempt = async (command, args) => {
+        try {
+            const { stdout, stderr } = await execFileAsync(command, args, {
+                timeout: PROBE_TIMEOUT_MS,
+                maxBuffer: 256 * 1024,
+                windowsHide: true,
+                ...(signal ? { signal } : {}),
+            });
+            return { outcome: 'ran', exitCode: 0, output: `${stdout}\n${stderr}` };
+        }
+        catch (err) {
+            return spawnFailure(err);
+        }
+    };
+    return async (command, args) => {
+        const first = await attempt(command, args);
+        if (first.outcome !== 'missing' || process.platform !== 'win32')
+            return first;
+        return readOracle(await attempt('where', [command]));
+    };
+}
+/**
+ * What the `where` oracle's own result says about the TOOL. Pure, and separate from the spawn, so
+ * every branch is asserted on any platform: reproducing the failing one for real needs a process
+ * whose PATH cannot reach `where`, and mutating the live `PATH` to get one leaks into whatever test
+ * runs next (on Windows `PATH` and `Path` are one variable, so restoring them is not symmetric).
+ *
+ * The distinction the branches exist for: `where` exiting non-zero IS the tool's absence, but
+ * `where` not answering at all says nothing about the tool, so that becomes a FAILED probe. Passing
+ * the oracle's result straight back reported the ORACLE's own `missing` as the tool's, which put a
+ * fully installed npm on the "Not installed" line on any host where `where` cannot be spawned.
+ *
+ * A located tool is `found`, never a synthesised `ran` with `exitCode: 0`: the oracle located a
+ * binary and executed nothing, so it cannot answer for a probe whose answer IS its exit code.
+ */
+export function readOracle(located) {
+    if (located.outcome === 'ran') {
+        return located.exitCode === 0 ? { outcome: 'found' } : { outcome: 'missing' };
+    }
+    if (located.outcome === 'found')
+        return located;
+    return {
+        outcome: 'failed',
+        reason: located.outcome === 'failed'
+            ? located.reason
+            : 'the tool could not be spawned, and `where` could not be run to locate it',
+    };
+}
+/**
+ * Read a rejected `execFile` back into a {@link ProbeResult}.
+ *
+ * `ENOENT` is the ONLY absence: the binary is not on PATH. A numeric `code` means the binary RAN
+ * and exited non-zero, which is a different fact and belongs to whoever asked. Everything else
+ * (a timeout, where the child is killed and there is no exit code; `EACCES`; an aborted job) is a
+ * failure OF THE PROBE, which is what keeps it out of the absent list.
+ *
+ * Every reason is WRITTEN HERE, in words, and the raw `code` is never one of them. The reason is
+ * rendered verbatim into the agent's system prompt, so passing `String(e.code)` through published
+ * `ABORT_ERR` (a cancelled job, on all thirteen entries at once), `EACCES` and
+ * `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` to a model as prose. A code nobody has mapped yet says only
+ * that the probe did not run, which is the whole of what the block needs from it.
+ */
+function spawnFailure(err) {
+    const e = err;
+    if (e.code === 'ENOENT')
+        return { outcome: 'missing' };
+    if (typeof e.code === 'number') {
+        return { outcome: 'ran', exitCode: e.code, output: `${e.stdout ?? ''}\n${e.stderr ?? ''}` };
+    }
+    // Abort before the timeout check: `execFile`'s `AbortError` carries no `killed`, so an aborted
+    // job would otherwise fall through to the catch-all and read as a machine that answered nothing.
+    if (e.code === 'ABORT_ERR' || e.name === 'AbortError') {
+        return { outcome: 'failed', reason: 'the job was cancelled before the probe finished' };
+    }
+    if (e.killed)
+        return { outcome: 'failed', reason: 'the probe timed out' };
+    if (e.code === 'EACCES' || e.code === 'EPERM') {
+        return { outcome: 'failed', reason: 'the probe was not permitted to run here' };
+    }
+    return { outcome: 'failed', reason: 'the probe could not be run' };
+}
+/**
+ * The first version-shaped token in a `--version` banner, capped so a chatty tool can't run away.
+ *
+ * Deliberately no leading `\b`: the token is routinely glued to a letter (`v26.7.0`, `helm
+ * v3.16.2`), and a word boundary between `v` and `2` does not exist, so the anchored form skipped
+ * the major and reported `26.7.0` as `7.0`.
+ */
+function firstVersion(output) {
+    const match = /\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?/.exec(output);
+    return match ? match[0].slice(0, 24) : undefined;
+}
+/**
+ * An ordinary tool's presence: it ran (whatever it exited with) ⇒ installed, `ENOENT` ⇒ not
+ * installed, anything else ⇒ the probe failed and we do not know. `helm version` on a host with
+ * no cluster config exits non-zero and still proves helm is installed.
+ */
+export function toolPresence(result) {
+    if (result.outcome === 'missing')
+        return { status: 'absent' };
+    if (result.outcome === 'failed')
+        return { status: 'unknown', reason: result.reason };
+    if (result.outcome === 'found')
+        return { status: 'present' };
+    const version = firstVersion(result.output);
+    return version ? { status: 'present', version } : { status: 'present' };
+}
+/**
+ * The daemon's presence, which reads the SAME result differently in exactly TWO places, and
+ * delegates the rest: duplicating the other three branches to add these two is how a change to
+ * how a version is read, or how a failure reason is carried, gets made in one classifier only.
+ *
+ *   - A non-zero exit is "cannot connect to the Docker daemon", so it is an absence rather than the
+ *     proof-of-install a non-zero exit is everywhere else.
+ *   - `found` means the Windows oracle located the CLI and ran NOTHING, so the daemon was never
+ *     asked. That is an unknown. Reading it as `toolPresence` would is what made `where docker`
+ *     enough to tell an agent `docker build` works here.
+ */
+export function daemonPresence(result) {
+    if (result.outcome === 'found') {
+        return {
+            status: 'unknown',
+            reason: 'only the docker CLI was located; the daemon was not asked',
+        };
+    }
+    if (result.outcome === 'ran' && result.exitCode !== 0)
+        return { status: 'absent' };
+    return toolPresence(result);
+}
+/**
+ * Whether anything is supposed to serve a Docker daemon here, which `entrypoint.sh` makes knowable:
+ * it EXPORTS `DOCKER_HOST` both when a pool hands us an external daemon and when it starts the
+ * rootless one, and leaves it unset in the one branch where no daemon is coming. Reading the
+ * machine's own configuration, not per-job state, so `process.env` is the right source here.
+ */
+function daemonIsConfigured() {
+    return (process.env.DOCKER_HOST ?? '').trim() !== '';
+}
+/**
+ * Probe the machine. EVERYTHING runs concurrently, the daemon included.
+ *
+ * The daemon probe used to be sequenced after the tool pass, so that a missing CLI could
+ * short-circuit it. That bought a cleaner `absent` and charged the whole job for it: two ceilings
+ * back to back on the critical path, ahead of the clone, on every dispatch. It is unnecessary,
+ * because `docker info` answers the CLI question too: with no CLI on PATH the spawn comes back
+ * `missing`, which {@link daemonPresence} already reads as the same absence the short-circuit
+ * produced. Asking directly also removes a second defect the sequencing needed: reading the CLI's
+ * presence back out of `tools` defaulted a MISSING list entry to `absent`, so trimming the curated
+ * list would have had the block assert "NO Docker daemon is reachable" with nothing ever asked.
+ */
+export async function probeEnvironment(run, opts = {}) {
+    const [tools, dockerDaemon] = await Promise.all([
+        Promise.all(PROBES.map(async (probe) => ({
+            name: probe.name,
+            showVersion: probe.showVersion,
+            presence: toolPresence(await run(probe.command, probe.args)),
+        }))),
+        probeDockerDaemon(run, opts),
+    ]);
+    return { tools, dockerDaemon };
+}
+/**
+ * Ask the daemon itself, and do not mistake a daemon that is STARTING for one that is not there.
+ *
+ * `entrypoint.sh` launches `dockerd-rootless.sh` detached and `exec`s the server without waiting,
+ * so `/health` answers (and the backend POSTs `/run`) seconds before the rootless daemon has
+ * finished its userns and fuse-overlayfs setup. Until then there is no socket, so `docker info`
+ * is refused AT ONCE. Read as a plain absence that produced the block's most consequential line,
+ * "NO Docker daemon is reachable ... will fail here whatever the CLI reports", on a machine whose
+ * daemon was up moments later, which authoritatively told a tester step not to try.
+ *
+ * Whether a daemon is CONFIGURED here is what separates the two (see {@link daemonIsConfigured}):
+ *
+ *   - refused with no `DOCKER_HOST` ⇒ ABSENT. Nothing was coming. This is also the developer's
+ *     laptop with Docker Desktop shut down, where absent is exactly right.
+ *   - refused with `DOCKER_HOST` set ⇒ one short retry, then UNKNOWN. A daemon was expected and
+ *     has not answered yet, which is neither of the other two answers, and the rendered line turns
+ *     it into "try it if you need it" rather than into a prohibition.
+ */
+async function probeDockerDaemon(run, opts) {
+    const expected = opts.daemonExpected ?? daemonIsConfigured();
+    const ask = async () => daemonPresence(await run(DOCKER_INFO.command, DOCKER_INFO.args));
+    const first = await ask();
+    if (first.status !== 'absent' || !expected)
+        return first;
+    await (opts.sleep ?? defaultSleep)(DAEMON_RETRY_DELAY_MS);
+    const second = await ask();
+    if (second.status !== 'absent')
+        return second;
+    return {
+        status: 'unknown',
+        reason: 'a daemon is configured for this machine but had not answered when the job started; it may ' +
+            'still be coming up',
+    };
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Render one tool for the `Installed:` line: `node 26.7.0`, or just `jq`. */
+function installedLabel(tool) {
+    const version = tool.presence.status === 'present' ? tool.presence.version : undefined;
+    return tool.showVersion && version ? `${tool.name} ${version}` : tool.name;
+}
+/**
+ * The block appended to the agent's system prompt. Pure, so what the agent reads is asserted
+ * against a probe result rather than against whichever machine the suite happens to run on.
+ *
+ * Each line is a different KIND of claim, and they are kept apart because collapsing them is the
+ * failure this replaces: what is here, what is not, what could not be determined, what the Docker
+ * daemon actually said, and, last because it governs everything the other lines omit, that the
+ * list is bounded.
+ */
+export function renderEnvironmentInventory(inventory) {
+    const installed = inventory.tools.filter((t) => t.presence.status === 'present');
+    const absent = inventory.tools.filter((t) => t.presence.status === 'absent');
+    // Flattened while the presence is still narrowed: the REASON is what makes an entry an unknown
+    // rather than an absence, so it has to reach the rendered line, and picking it back out of a
+    // `ProbedTool` later needs a re-narrowing branch nothing can ever take.
+    const unknown = inventory.tools.flatMap((t) => t.presence.status === 'unknown' ? [`${t.name} (${t.presence.reason})`] : []);
+    const lines = [
+        'ENVIRONMENT INVENTORY: the platform probed this machine when the job started. These are ' +
+            'facts about where you are running; do not spend turns re-checking them.',
+    ];
+    if (installed.length > 0) {
+        lines.push(`Installed: ${installed.map(installedLabel).join(', ')}.`);
+    }
+    if (absent.length > 0) {
+        lines.push(`Not installed: ${absent.map((t) => t.name).join(', ')}. You are unprivileged here, so a ` +
+            'SYSTEM install of one of these will fail, and a tool the platform did not provide is not ' +
+            "a defect in the work. Where one of them is the project's own package manager, reaching " +
+            'it for that project alone (`npx <manager>`, a repo-local install) is fine and is the one ' +
+            'thing worth trying.');
+    }
+    if (unknown.length > 0) {
+        lines.push('Could not be determined, because the PROBE itself failed. Treat each as neither present ' +
+            `nor absent: ${unknown.join(', ')}.`);
+    }
+    lines.push(dockerDaemonLine(inventory.dockerDaemon));
+    // Stated as a FACT and not as an errand. This block is appended to the system prompt after the
+    // effort-report directive, whose closing sentences are the prompt's ordering rule (write the
+    // sentinel, then reply, and no tool call after the reply). "Check for that one yourself before
+    // relying on it" sat after that rule and invited exactly the trailing tool call it forbids, which
+    // is the displacement that once cost an architect run its design. The agent needs to know the
+    // list is bounded; when to go looking is the sandbox directive's business, and it is not last.
+    lines.push('Nothing else was probed. A tool named on none of these lines is unknown to the platform ' +
+        'rather than missing.');
+    return lines.join('\n');
+}
+/** The Docker line, which says something different in each of the three cases. */
+function dockerDaemonLine(daemon) {
+    if (daemon.status === 'present') {
+        const server = daemon.version ? ` (server ${daemon.version})` : '';
+        return (`A Docker daemon is reachable${server}: \`docker build\`, \`docker run\` and ` +
+            '`docker compose up` work here.');
+    }
+    if (daemon.status === 'unknown') {
+        return ('Whether a Docker daemon is reachable could not be determined ' +
+            `(${daemon.reason}): try it if you need it, and do not read a failure as a defect in the work.`);
+    }
+    return ('NO Docker daemon is reachable: `docker build`, `docker run` and `docker compose up` will ' +
+        'fail here whatever the CLI reports. Produce the Dockerfile or compose file you were asked ' +
+        'for, say in one line that you could not build it here, and move on.');
+}
+/**
+ * Probe the machine and fold the inventory onto `systemPrompt`. THE composition point: the harness
+ * calls this once per job, in `handleAgent`, before any mode branches, so every mode and every CLI
+ * (claude-code, codex, Pi) inherits it from the job's own system prompt instead of each folding a
+ * copy, which is how one of them would silently end up without it, and another with it twice.
+ *
+ * It rides the SYSTEM prompt rather than the task prompt so it survives the claude runner's
+ * argv-size branch (`carryClaudeSystemPrompt` folds an oversized system prompt into stdin whole),
+ * Codex's unconditional fold and Pi's `AGENTS.md` write, none of which can drop part of it.
+ *
+ * Never throws: an inventory is context, and a job whose probe pass fell over is still a job worth
+ * running. A probe that fails is already reported as unknown by construction, so this catch is for
+ * the pass itself, and it says so in a log line rather than silently shortening the prompt.
+ */
+export async function appendEnvironmentInventory(systemPrompt, opts = {}) {
+    const logger = opts.log ?? log;
+    try {
+        const inventory = await probeEnvironment(opts.run ?? spawnProbeRunner(opts.signal), {
+            ...(opts.sleep ? { sleep: opts.sleep } : {}),
+            ...(opts.daemonExpected === undefined ? {} : { daemonExpected: opts.daemonExpected }),
+        });
+        logger.info('agent: probed the environment', {
+            installed: inventory.tools
+                .filter((t) => t.presence.status === 'present')
+                .map((t) => t.name)
+                .join(','),
+            dockerDaemon: inventory.dockerDaemon.status,
+            // The unknowns, by NAME: the block tells the agent a probe failed, and this is the only place
+            // an operator can see WHICH, since the reason the agent reads is deliberately wordy prose.
+            unknown: inventory.tools
+                .filter((t) => t.presence.status === 'unknown')
+                .map((t) => t.name)
+                .join(','),
+        });
+        return `${systemPrompt}\n\n${renderEnvironmentInventory(inventory)}`;
+    }
+    catch (err) {
+        logger.warn('agent: the environment probe pass failed; dispatching without an inventory', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return systemPrompt;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.135.0",
+  "version": "1.137.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",
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@cat-factory/kernel": "0.321.0",
-    "@cat-factory/server": "0.306.5",
+    "@cat-factory/server": "0.306.6",
     "@cat-factory/spend": "0.16.17",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.2.0",

package/src/agent.ts

@@ -37,6 +37,7 @@ import { runMultiRepoCoding } from './multi-repo-coding.js'
 import { validationFailureMessage } from './validation-checks.js'
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js'
 import { agentCapabilities, mergeEffort } from './agent-shared.js'
+import { appendEnvironmentInventory } from './environment-inventory.js'
 import { runBootstrap } from './bootstrap-mode.js'
 import {
   acquireRepoCheckout,
@@ -176,9 +177,28 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
       ...artifactUploadEnv(job.artifactUpload),
     })
     if (job.mode === 'preview') return await runPreviewMode(job, scoped)
-    return job.mode === 'coding'
-      ? await runCodingMode(job, scoped)
-      : await runExploreMode(job, scoped)
+    // THE composition point for the environment inventory (see `environment-inventory.ts`): the
+    // machine is probed ONCE here, before any mode branches, and the result is folded onto the
+    // job's own system prompt. Every mode, every repair round and all three agent CLIs read that
+    // one field, so none of them can end up without the block and none can carry it twice.
+    // `preview` returns above because it runs no agent at all, so there is no prompt to fold onto.
+    //
+    // This sits on the critical path AHEAD of the clone, which is the cost of having one
+    // composition point instead of one per mode (each mode owns its own clone, so there is no
+    // single post-clone place to put this). The pass is sized for that: everything in it runs
+    // concurrently, every probe is a call that answers in milliseconds or is wedged, and the one
+    // deliberate wait is a single short retry for a daemon that is still starting.
+
+    const staged: AgentJob = {
+      ...job,
+      systemPrompt: await appendEnvironmentInventory(job.systemPrompt, {
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.log ? { log: opts.log } : {}),
+      }),
+    }
+    return staged.mode === 'coding'
+      ? await runCodingMode(staged, scoped)
+      : await runExploreMode(staged, scoped)
   } finally {
     if (scopeDir) await rm(scopeDir, { recursive: true, force: true }).catch(() => {})
   }

package/src/environment-inventory.ts

@@ -0,0 +1,512 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { log, type Logger } from './logger.js'
+
+// ---------------------------------------------------------------------------
+// What this machine actually has, probed ONCE per job and stated to the agent.
+//
+// The platform used to tell every agent to discover its own environment ("probe for a tool before
+// relying on it"), and every agent did, repeatedly, and often twice within one run: an architect
+// ran `for c in docker kubectl helm kustomize; do command -v $c; done`, then `docker info`, and
+// the coder it handed off to rediscovered both answers thirty calls later. Four calls out of a
+// forty-call budget, spent on facts the harness holds before the agent's first turn.
+//
+// This is the layer that CAN hold them, and the only one. The backend composes its prompt before a
+// transport is even chosen, and the same job body serves the harness image, a deployment's own
+// image variant and (under `LOCAL_NATIVE_AGENTS`) the developer's own machine, where the
+// toolchain is theirs. So the backend states the POLICY (no cluster credentials; an artifact this
+// environment cannot execute is still a correct artifact) and names no tooling at all, while this
+// file states the FACTS, from a probe of the machine the agent is about to run on.
+//
+// Three rules the block is built around:
+//
+//   - ABSENT and UNKNOWN must not render the same. Only a spawn that came back `ENOENT` is an
+//     absence; a probe that failed says so and is reported as neither present nor absent.
+//   - A tool NOT ON THE LIST is unknown too, which the block's last line says. The list is curated
+//     (what agents were observed rediscovering), so silence about `terraform` has to read as
+//     "nobody looked", never as "it isn't there".
+//   - The Docker DAEMON is a separate fact from the docker CLI, and it is the one that decides
+//     anything: `command -v docker` succeeds in this image and `docker build` still fails, which
+//     is the half-truth the old instruction produced. It is answered by RUNNING `docker info`, and
+//     a daemon this machine is CONFIGURED for but which has not answered yet is a fourth state
+//     that resolves to `unknown`, never to the absence a refused connection looks like: the
+//     image's daemon is started in the background and the job begins before it is ready.
+//
+// Deliberately NOT here: the agent's own tools (web search, file tools, MCP servers). Those are
+// the CLI's, they differ per harness, and each is already stated where it is true. Claiming one
+// here would be the platform asserting a capability the dispatch may not have delivered, which is
+// the defect this whole change exists to remove.
+// ---------------------------------------------------------------------------
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * What running one probe did, kept as RAW as the spawn: whether the binary ran, and with what.
+ * Classification into presence lives in pure code below, because the two callers classify the
+ * same result differently: a non-zero exit proves an ordinary tool is installed and proves the
+ * Docker daemon is not reachable.
+ *
+ * `found` is the outcome with no exit code, and it exists so that the Windows second look cannot
+ * be mistaken for a run: the platform's own oracle located the binary and NOTHING WAS EXECUTED.
+ * Collapsing it into `ran` with a synthesised `exitCode: 0` is what let `docker info` report a
+ * reachable daemon on the strength of `where docker`, which is the CLI-for-daemon half-truth this
+ * whole file exists to remove.
+ */
+export type ProbeResult =
+  | { outcome: 'ran'; exitCode: number; output: string }
+  | { outcome: 'found' }
+  | { outcome: 'missing' }
+  | { outcome: 'failed'; reason: string }
+
+/** Run one probe. Injected so the suite drives every branch without needing the real binaries. */
+export type ProbeRunner = (command: string, args: string[]) => Promise<ProbeResult>
+
+/** What one probe learned. `unknown` is a THIRD answer, never folded into `absent`. */
+export type ToolPresence =
+  | { status: 'present'; version?: string }
+  | { status: 'absent' }
+  | { status: 'unknown'; reason: string }
+
+/** One probed entry: the name the agent would type, and what came back. */
+export interface ProbedTool {
+  name: string
+  presence: ToolPresence
+  /** Whether the rendered line carries the version. Off where a yes/no is the whole answer. */
+  showVersion: boolean
+}
+
+/** Everything one job's probe pass learned about the machine it is about to run on. */
+export interface EnvironmentInventory {
+  tools: ProbedTool[]
+  /**
+   * Whether a Docker daemon actually answered: the readiness fact, not the CLI's presence. The
+   * image's `entrypoint.sh` starts a rootless daemon BEST-EFFORT and execs the server without
+   * waiting for it, so at job start this probe is the only thing that knows how that went, and
+   * "has not answered yet" is one of its answers (see {@link probeDockerDaemon}).
+   */
+  dockerDaemon: ToolPresence
+}
+
+/**
+ * The curated probe list: the toolchain an agent assumes, plus the tools runs were observed
+ * burning calls to discover. Kept SHORT on purpose. Every entry is a spawn and a few more words
+ * in every system prompt, and the block's closing line keeps an unlisted tool honestly unknown
+ * rather than implicitly absent.
+ *
+ * `showVersion` is on where the number changes what the agent does (comparing against a target's
+ * declared engines, a language's syntax level) and off where presence is the whole question.
+ */
+const PROBES: ReadonlyArray<{
+  name: string
+  command: string
+  args: string[]
+  showVersion: boolean
+}> = [
+  { name: 'node', command: 'node', args: ['--version'], showVersion: true },
+  { name: 'npm', command: 'npm', args: ['--version'], showVersion: true },
+  { name: 'pnpm', command: 'pnpm', args: ['--version'], showVersion: true },
+  { name: 'git', command: 'git', args: ['--version'], showVersion: true },
+  { name: 'python3', command: 'python3', args: ['--version'], showVersion: true },
+  { name: 'docker', command: 'docker', args: ['--version'], showVersion: false },
+  { name: 'jq', command: 'jq', args: ['--version'], showVersion: false },
+  { name: 'rg', command: 'rg', args: ['--version'], showVersion: false },
+  { name: 'curl', command: 'curl', args: ['--version'], showVersion: false },
+  { name: 'make', command: 'make', args: ['--version'], showVersion: false },
+  { name: 'kubectl', command: 'kubectl', args: ['version', '--client'], showVersion: false },
+  { name: 'helm', command: 'helm', args: ['version'], showVersion: false },
+  { name: 'kustomize', command: 'kustomize', args: ['version'], showVersion: false },
+]
+
+/** The daemon readiness probe: the one probe whose EXIT CODE, not its presence, is the answer. */
+const DOCKER_INFO: { command: string; args: string[] } = {
+  command: 'docker',
+  args: ['info', '--format', '{{.ServerVersion}}'],
+}
+
+/**
+ * Every probe here is either instant or wedged: a `--version` banner, and a `docker info` that
+ * either connects or is REFUSED by a missing socket in milliseconds. So the ceiling is sized to
+ * cut a wedged binary out of the job's critical path, not to wait for anything.
+ *
+ * It used to be ten seconds, on the stated grounds that `docker info` "can genuinely take a
+ * moment" against a daemon still coming up. That was wrong in the way that matters: a daemon that
+ * is not up yet has no socket to connect to, so docker exits non-zero AT ONCE and the ceiling is
+ * never reached. Waiting for a starting daemon is a different problem and is solved where it
+ * actually lives, in {@link probeDockerDaemon}'s retry.
+ */
+const PROBE_TIMEOUT_MS = 5_000
+
+/**
+ * How long a daemon that was EXPECTED here gets to answer before the block says it could not be
+ * determined. One short retry, not a readiness wait: the honest verdict for a daemon still coming
+ * up is `unknown`, which the rendered line turns into "try it if you need it", so there is nothing
+ * to buy by blocking the agent's first turn any longer than this.
+ */
+const DAEMON_RETRY_DELAY_MS = 1_500
+
+/**
+ * The real runner: spawn the tool, bounded, and report what the spawn did.
+ *
+ * The Windows second look is for the NATIVE transport on a developer's own machine, not for the
+ * image. `execFile` without a shell resolves `.exe` and not `.cmd`, and Node refuses to spawn a
+ * `.cmd` at all without one, so a perfectly installed `npm` or `pnpm` comes back `ENOENT` there and
+ * would be stated to the agent as NOT INSTALLED. `where` is the platform's own presence oracle and
+ * answers that without running the shim, at the cost of the version, which is the honest trade: the
+ * rendered line then names the tool with no number rather than claiming one or denying the tool.
+ *
+ * It answers PRESENCE and nothing else, which is why it returns `found` and why it ignores `args`
+ * without pretending otherwise: `where <command>` locates a binary, so it can say nothing about
+ * what that binary would have printed or exited with. The version is not the only thing lost. A
+ * probe whose ANSWER is its exit code (`docker info`) gets no answer at all from this branch, and
+ * {@link daemonPresence} is where that is turned into an unknown rather than a reachable daemon.
+ */
+export function spawnProbeRunner(signal?: AbortSignal): ProbeRunner {
+  const attempt = async (command: string, args: string[]): Promise<ProbeResult> => {
+    try {
+      const { stdout, stderr } = await execFileAsync(command, args, {
+        timeout: PROBE_TIMEOUT_MS,
+        maxBuffer: 256 * 1024,
+        windowsHide: true,
+        ...(signal ? { signal } : {}),
+      })
+      return { outcome: 'ran', exitCode: 0, output: `${stdout}\n${stderr}` }
+    } catch (err) {
+      return spawnFailure(err)
+    }
+  }
+  return async (command, args) => {
+    const first = await attempt(command, args)
+    if (first.outcome !== 'missing' || process.platform !== 'win32') return first
+    return readOracle(await attempt('where', [command]))
+  }
+}
+
+/**
+ * What the `where` oracle's own result says about the TOOL. Pure, and separate from the spawn, so
+ * every branch is asserted on any platform: reproducing the failing one for real needs a process
+ * whose PATH cannot reach `where`, and mutating the live `PATH` to get one leaks into whatever test
+ * runs next (on Windows `PATH` and `Path` are one variable, so restoring them is not symmetric).
+ *
+ * The distinction the branches exist for: `where` exiting non-zero IS the tool's absence, but
+ * `where` not answering at all says nothing about the tool, so that becomes a FAILED probe. Passing
+ * the oracle's result straight back reported the ORACLE's own `missing` as the tool's, which put a
+ * fully installed npm on the "Not installed" line on any host where `where` cannot be spawned.
+ *
+ * A located tool is `found`, never a synthesised `ran` with `exitCode: 0`: the oracle located a
+ * binary and executed nothing, so it cannot answer for a probe whose answer IS its exit code.
+ */
+export function readOracle(located: ProbeResult): ProbeResult {
+  if (located.outcome === 'ran') {
+    return located.exitCode === 0 ? { outcome: 'found' } : { outcome: 'missing' }
+  }
+  if (located.outcome === 'found') return located
+  return {
+    outcome: 'failed',
+    reason:
+      located.outcome === 'failed'
+        ? located.reason
+        : 'the tool could not be spawned, and `where` could not be run to locate it',
+  }
+}
+
+/**
+ * Read a rejected `execFile` back into a {@link ProbeResult}.
+ *
+ * `ENOENT` is the ONLY absence: the binary is not on PATH. A numeric `code` means the binary RAN
+ * and exited non-zero, which is a different fact and belongs to whoever asked. Everything else
+ * (a timeout, where the child is killed and there is no exit code; `EACCES`; an aborted job) is a
+ * failure OF THE PROBE, which is what keeps it out of the absent list.
+ *
+ * Every reason is WRITTEN HERE, in words, and the raw `code` is never one of them. The reason is
+ * rendered verbatim into the agent's system prompt, so passing `String(e.code)` through published
+ * `ABORT_ERR` (a cancelled job, on all thirteen entries at once), `EACCES` and
+ * `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` to a model as prose. A code nobody has mapped yet says only
+ * that the probe did not run, which is the whole of what the block needs from it.
+ */
+function spawnFailure(err: unknown): ProbeResult {
+  const e = err as NodeJS.ErrnoException & { killed?: boolean; stdout?: string; stderr?: string }
+  if (e.code === 'ENOENT') return { outcome: 'missing' }
+  if (typeof e.code === 'number') {
+    return { outcome: 'ran', exitCode: e.code, output: `${e.stdout ?? ''}\n${e.stderr ?? ''}` }
+  }
+  // Abort before the timeout check: `execFile`'s `AbortError` carries no `killed`, so an aborted
+  // job would otherwise fall through to the catch-all and read as a machine that answered nothing.
+  if (e.code === 'ABORT_ERR' || (e as Error).name === 'AbortError') {
+    return { outcome: 'failed', reason: 'the job was cancelled before the probe finished' }
+  }
+  if (e.killed) return { outcome: 'failed', reason: 'the probe timed out' }
+  if (e.code === 'EACCES' || e.code === 'EPERM') {
+    return { outcome: 'failed', reason: 'the probe was not permitted to run here' }
+  }
+  return { outcome: 'failed', reason: 'the probe could not be run' }
+}
+
+/**
+ * The first version-shaped token in a `--version` banner, capped so a chatty tool can't run away.
+ *
+ * Deliberately no leading `\b`: the token is routinely glued to a letter (`v26.7.0`, `helm
+ * v3.16.2`), and a word boundary between `v` and `2` does not exist, so the anchored form skipped
+ * the major and reported `26.7.0` as `7.0`.
+ */
+function firstVersion(output: string): string | undefined {
+  const match = /\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?/.exec(output)
+  return match ? match[0].slice(0, 24) : undefined
+}
+
+/**
+ * An ordinary tool's presence: it ran (whatever it exited with) ⇒ installed, `ENOENT` ⇒ not
+ * installed, anything else ⇒ the probe failed and we do not know. `helm version` on a host with
+ * no cluster config exits non-zero and still proves helm is installed.
+ */
+export function toolPresence(result: ProbeResult): ToolPresence {
+  if (result.outcome === 'missing') return { status: 'absent' }
+  if (result.outcome === 'failed') return { status: 'unknown', reason: result.reason }
+  if (result.outcome === 'found') return { status: 'present' }
+  const version = firstVersion(result.output)
+  return version ? { status: 'present', version } : { status: 'present' }
+}
+
+/**
+ * The daemon's presence, which reads the SAME result differently in exactly TWO places, and
+ * delegates the rest: duplicating the other three branches to add these two is how a change to
+ * how a version is read, or how a failure reason is carried, gets made in one classifier only.
+ *
+ *   - A non-zero exit is "cannot connect to the Docker daemon", so it is an absence rather than the
+ *     proof-of-install a non-zero exit is everywhere else.
+ *   - `found` means the Windows oracle located the CLI and ran NOTHING, so the daemon was never
+ *     asked. That is an unknown. Reading it as `toolPresence` would is what made `where docker`
+ *     enough to tell an agent `docker build` works here.
+ */
+export function daemonPresence(result: ProbeResult): ToolPresence {
+  if (result.outcome === 'found') {
+    return {
+      status: 'unknown',
+      reason: 'only the docker CLI was located; the daemon was not asked',
+    }
+  }
+  if (result.outcome === 'ran' && result.exitCode !== 0) return { status: 'absent' }
+  return toolPresence(result)
+}
+
+/** What one probe pass may be told, so the suite drives the daemon's retry without waiting on it. */
+export interface ProbeEnvironmentOptions {
+  /** Injected so tests exercise the retry without paying {@link DAEMON_RETRY_DELAY_MS}. */
+  sleep?: (ms: number) => Promise<void>
+  /**
+   * Whether a daemon is CONFIGURED to serve this machine, defaulting to {@link daemonIsConfigured}.
+   * Stated as the fact rather than as the `DOCKER_HOST` string it is read from, so a test can drive
+   * both sides of the branch without an ambient environment variable deciding the outcome for it.
+   */
+  daemonExpected?: boolean
+}
+
+/**
+ * Whether anything is supposed to serve a Docker daemon here, which `entrypoint.sh` makes knowable:
+ * it EXPORTS `DOCKER_HOST` both when a pool hands us an external daemon and when it starts the
+ * rootless one, and leaves it unset in the one branch where no daemon is coming. Reading the
+ * machine's own configuration, not per-job state, so `process.env` is the right source here.
+ */
+function daemonIsConfigured(): boolean {
+  return (process.env.DOCKER_HOST ?? '').trim() !== ''
+}
+
+/**
+ * Probe the machine. EVERYTHING runs concurrently, the daemon included.
+ *
+ * The daemon probe used to be sequenced after the tool pass, so that a missing CLI could
+ * short-circuit it. That bought a cleaner `absent` and charged the whole job for it: two ceilings
+ * back to back on the critical path, ahead of the clone, on every dispatch. It is unnecessary,
+ * because `docker info` answers the CLI question too: with no CLI on PATH the spawn comes back
+ * `missing`, which {@link daemonPresence} already reads as the same absence the short-circuit
+ * produced. Asking directly also removes a second defect the sequencing needed: reading the CLI's
+ * presence back out of `tools` defaulted a MISSING list entry to `absent`, so trimming the curated
+ * list would have had the block assert "NO Docker daemon is reachable" with nothing ever asked.
+ */
+export async function probeEnvironment(
+  run: ProbeRunner,
+  opts: ProbeEnvironmentOptions = {},
+): Promise<EnvironmentInventory> {
+  const [tools, dockerDaemon] = await Promise.all([
+    Promise.all(
+      PROBES.map(async (probe) => ({
+        name: probe.name,
+        showVersion: probe.showVersion,
+        presence: toolPresence(await run(probe.command, probe.args)),
+      })),
+    ),
+    probeDockerDaemon(run, opts),
+  ])
+  return { tools, dockerDaemon }
+}
+
+/**
+ * Ask the daemon itself, and do not mistake a daemon that is STARTING for one that is not there.
+ *
+ * `entrypoint.sh` launches `dockerd-rootless.sh` detached and `exec`s the server without waiting,
+ * so `/health` answers (and the backend POSTs `/run`) seconds before the rootless daemon has
+ * finished its userns and fuse-overlayfs setup. Until then there is no socket, so `docker info`
+ * is refused AT ONCE. Read as a plain absence that produced the block's most consequential line,
+ * "NO Docker daemon is reachable ... will fail here whatever the CLI reports", on a machine whose
+ * daemon was up moments later, which authoritatively told a tester step not to try.
+ *
+ * Whether a daemon is CONFIGURED here is what separates the two (see {@link daemonIsConfigured}):
+ *
+ *   - refused with no `DOCKER_HOST` ⇒ ABSENT. Nothing was coming. This is also the developer's
+ *     laptop with Docker Desktop shut down, where absent is exactly right.
+ *   - refused with `DOCKER_HOST` set ⇒ one short retry, then UNKNOWN. A daemon was expected and
+ *     has not answered yet, which is neither of the other two answers, and the rendered line turns
+ *     it into "try it if you need it" rather than into a prohibition.
+ */
+async function probeDockerDaemon(
+  run: ProbeRunner,
+  opts: ProbeEnvironmentOptions,
+): Promise<ToolPresence> {
+  const expected = opts.daemonExpected ?? daemonIsConfigured()
+  const ask = async (): Promise<ToolPresence> =>
+    daemonPresence(await run(DOCKER_INFO.command, DOCKER_INFO.args))
+  const first = await ask()
+  if (first.status !== 'absent' || !expected) return first
+  await (opts.sleep ?? defaultSleep)(DAEMON_RETRY_DELAY_MS)
+  const second = await ask()
+  if (second.status !== 'absent') return second
+  return {
+    status: 'unknown',
+    reason:
+      'a daemon is configured for this machine but had not answered when the job started; it may ' +
+      'still be coming up',
+  }
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+/** Render one tool for the `Installed:` line: `node 26.7.0`, or just `jq`. */
+function installedLabel(tool: ProbedTool): string {
+  const version = tool.presence.status === 'present' ? tool.presence.version : undefined
+  return tool.showVersion && version ? `${tool.name} ${version}` : tool.name
+}
+
+/**
+ * The block appended to the agent's system prompt. Pure, so what the agent reads is asserted
+ * against a probe result rather than against whichever machine the suite happens to run on.
+ *
+ * Each line is a different KIND of claim, and they are kept apart because collapsing them is the
+ * failure this replaces: what is here, what is not, what could not be determined, what the Docker
+ * daemon actually said, and, last because it governs everything the other lines omit, that the
+ * list is bounded.
+ */
+export function renderEnvironmentInventory(inventory: EnvironmentInventory): string {
+  const installed = inventory.tools.filter((t) => t.presence.status === 'present')
+  const absent = inventory.tools.filter((t) => t.presence.status === 'absent')
+  // Flattened while the presence is still narrowed: the REASON is what makes an entry an unknown
+  // rather than an absence, so it has to reach the rendered line, and picking it back out of a
+  // `ProbedTool` later needs a re-narrowing branch nothing can ever take.
+  const unknown = inventory.tools.flatMap((t) =>
+    t.presence.status === 'unknown' ? [`${t.name} (${t.presence.reason})`] : [],
+  )
+  const lines = [
+    'ENVIRONMENT INVENTORY: the platform probed this machine when the job started. These are ' +
+      'facts about where you are running; do not spend turns re-checking them.',
+  ]
+  if (installed.length > 0) {
+    lines.push(`Installed: ${installed.map(installedLabel).join(', ')}.`)
+  }
+  if (absent.length > 0) {
+    lines.push(
+      `Not installed: ${absent.map((t) => t.name).join(', ')}. You are unprivileged here, so a ` +
+        'SYSTEM install of one of these will fail, and a tool the platform did not provide is not ' +
+        "a defect in the work. Where one of them is the project's own package manager, reaching " +
+        'it for that project alone (`npx <manager>`, a repo-local install) is fine and is the one ' +
+        'thing worth trying.',
+    )
+  }
+  if (unknown.length > 0) {
+    lines.push(
+      'Could not be determined, because the PROBE itself failed. Treat each as neither present ' +
+        `nor absent: ${unknown.join(', ')}.`,
+    )
+  }
+  lines.push(dockerDaemonLine(inventory.dockerDaemon))
+  // Stated as a FACT and not as an errand. This block is appended to the system prompt after the
+  // effort-report directive, whose closing sentences are the prompt's ordering rule (write the
+  // sentinel, then reply, and no tool call after the reply). "Check for that one yourself before
+  // relying on it" sat after that rule and invited exactly the trailing tool call it forbids, which
+  // is the displacement that once cost an architect run its design. The agent needs to know the
+  // list is bounded; when to go looking is the sandbox directive's business, and it is not last.
+  lines.push(
+    'Nothing else was probed. A tool named on none of these lines is unknown to the platform ' +
+      'rather than missing.',
+  )
+  return lines.join('\n')
+}
+
+/** The Docker line, which says something different in each of the three cases. */
+function dockerDaemonLine(daemon: ToolPresence): string {
+  if (daemon.status === 'present') {
+    const server = daemon.version ? ` (server ${daemon.version})` : ''
+    return (
+      `A Docker daemon is reachable${server}: \`docker build\`, \`docker run\` and ` +
+      '`docker compose up` work here.'
+    )
+  }
+  if (daemon.status === 'unknown') {
+    return (
+      'Whether a Docker daemon is reachable could not be determined ' +
+      `(${daemon.reason}): try it if you need it, and do not read a failure as a defect in the work.`
+    )
+  }
+  return (
+    'NO Docker daemon is reachable: `docker build`, `docker run` and `docker compose up` will ' +
+    'fail here whatever the CLI reports. Produce the Dockerfile or compose file you were asked ' +
+    'for, say in one line that you could not build it here, and move on.'
+  )
+}
+
+/**
+ * Probe the machine and fold the inventory onto `systemPrompt`. THE composition point: the harness
+ * calls this once per job, in `handleAgent`, before any mode branches, so every mode and every CLI
+ * (claude-code, codex, Pi) inherits it from the job's own system prompt instead of each folding a
+ * copy, which is how one of them would silently end up without it, and another with it twice.
+ *
+ * It rides the SYSTEM prompt rather than the task prompt so it survives the claude runner's
+ * argv-size branch (`carryClaudeSystemPrompt` folds an oversized system prompt into stdin whole),
+ * Codex's unconditional fold and Pi's `AGENTS.md` write, none of which can drop part of it.
+ *
+ * Never throws: an inventory is context, and a job whose probe pass fell over is still a job worth
+ * running. A probe that fails is already reported as unknown by construction, so this catch is for
+ * the pass itself, and it says so in a log line rather than silently shortening the prompt.
+ */
+export async function appendEnvironmentInventory(
+  systemPrompt: string,
+  opts: { signal?: AbortSignal; log?: Logger; run?: ProbeRunner } & ProbeEnvironmentOptions = {},
+): Promise<string> {
+  const logger = opts.log ?? log
+  try {
+    const inventory = await probeEnvironment(opts.run ?? spawnProbeRunner(opts.signal), {
+      ...(opts.sleep ? { sleep: opts.sleep } : {}),
+      ...(opts.daemonExpected === undefined ? {} : { daemonExpected: opts.daemonExpected }),
+    })
+    logger.info('agent: probed the environment', {
+      installed: inventory.tools
+        .filter((t) => t.presence.status === 'present')
+        .map((t) => t.name)
+        .join(','),
+      dockerDaemon: inventory.dockerDaemon.status,
+      // The unknowns, by NAME: the block tells the agent a probe failed, and this is the only place
+      // an operator can see WHICH, since the reason the agent reads is deliberately wordy prose.
+      unknown: inventory.tools
+        .filter((t) => t.presence.status === 'unknown')
+        .map((t) => t.name)
+        .join(','),
+    })
+    return `${systemPrompt}\n\n${renderEnvironmentInventory(inventory)}`
+  } catch (err) {
+    logger.warn('agent: the environment probe pass failed; dispatching without an inventory', {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return systemPrompt
+  }
+}