@cat-factory/executor-harness 1.147.0 → 1.149.0

package/dist/docker-probe-image.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { scrubbedExcerpt } from './redact.js';
 // ---------------------------------------------------------------------------
 // The one-container image the platform runs to find out whether this machine's Docker daemon
 // can actually run a container, built here in memory rather than pulled.
@@ -39,6 +40,140 @@ const PROBE_BINARY_PATH = 'busybox';
 export const PROBE_SENTINEL = 'cat-factory-docker-probe-ok';
 /** The argv the probe container runs. `busybox` dispatches on its own name, so this is an echo. */
 export const PROBE_COMMAND = [`/${PROBE_BINARY_PATH}`, 'echo', PROBE_SENTINEL];
+// ---------------------------------------------------------------------------
+// The second thing the same image is asked, and the one the marker run above structurally cannot
+// answer: whether a container started on this daemon can reach the NETWORK.
+//
+// Loading and running a local image needs no network at all, so a daemon whose nested containers
+// are cut off passes the marker run exactly as a working one does. That is not hypothetical: the
+// published executor image ran its rootless daemon with `--iptables=false`, which drops the
+// MASQUERADE rule for the bridge, and every nested container on it had no egress whatsoever
+// (issue #2173). The harness reported `dockerDaemon: "usable"` throughout, and each agent
+// discovered otherwise about seven minutes into an `npm ci` inside a `docker build` (issue
+// #2174). An agent TOLD it has no egress can plan around it; an agent told docker works cannot.
+//
+// It runs as its own container rather than as one more command in the marker run, because the
+// marker run is deliberately `--network none`. The two need opposite networking, so they cannot
+// be the same `docker run`, and keeping them apart has a second payoff: a failure of anything
+// below can only ever produce an EGRESS verdict, never a verdict about the daemon.
+// ---------------------------------------------------------------------------
+/**
+ * What the egress container prints for each observation: the marker, then the exit STATUS of the
+ * command that made it.
+ *
+ * The status rather than a pass/fail marker, because the two failures need different answers.
+ * A refused connection is evidence about the network; a 127 is busybox saying it has no such
+ * applet, which is evidence about the platform's own probe image and may never be reported as a
+ * network that is not there.
+ */
+export const EGRESS_TCP_MARKER = 'cat-factory-egress-tcp=';
+export const EGRESS_DNS_MARKER = 'cat-factory-egress-dns=';
+/** How long the in-container connect may take. Short: a blocked route is silent, not slow. */
+const EGRESS_CONNECT_TIMEOUT_SECONDS = 3;
+/**
+ * How long busybox is given to print its own `nc` usage, for the capability check below. Bounded
+ * like everything else in that container: an applet that somehow blocks may not take the budget
+ * of the measurement it is only a preamble to.
+ */
+const EGRESS_USAGE_TIMEOUT_SECONDS = 2;
+/**
+ * How long the in-container lookup may take. Its own ceiling because busybox's `nslookup` retries
+ * on its own schedule, and an unbounded one would spend the whole check's budget on the half that
+ * is the diagnostic rather than the verdict.
+ */
+const EGRESS_LOOKUP_TIMEOUT_SECONDS = 6;
+/**
+ * How much of a rejected setting is quoted back. Enough to recognise which value was refused,
+ * short of letting a pasted blob be most of an agent's system prompt.
+ */
+const SETTING_CHARS = 60;
+/** An IPv4 literal. Names are refused on purpose: a target that needs DNS cannot TEST DNS. */
+const IPV4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])$/;
+/** A hostname, in the narrow shape a DNS lookup can be aimed at. */
+const HOSTNAME = /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/i;
+/**
+ * Read the configured target, or say why it cannot be used.
+ *
+ * Validated rather than trusted, and strictly, for two reasons that both matter. The host and the
+ * name are interpolated into a `sh -c` script INSIDE the probe container, so anything else there
+ * would be running whatever a deployment's environment happened to hold; and a target that is
+ * quietly wrong produces a confident `blocked` about a daemon that is fine, which is the exact
+ * class of lie this whole module exists to remove. A rejected setting is REPORTED as a check that
+ * could not be carried out, never silently swapped for the default: an operator who pointed this
+ * at an address their network permits is entitled to find out that it was ignored.
+ */
+export function parseEgressTarget(target, dnsName) {
+    const [host = '', port = '', ...rest] = target.split(':');
+    if (rest.length > 0 || !IPV4.test(host)) {
+        return {
+            invalid: `the platform's egress check is configured with \`${scrubbedExcerpt(target, SETTING_CHARS)}\`, which is not an \`IPv4:port\` address`,
+        };
+    }
+    const parsed = Number(port);
+    if (!/^[0-9]{1,5}$/.test(port) || parsed < 1 || parsed > 65535) {
+        return {
+            invalid: `the platform's egress check is configured with \`${scrubbedExcerpt(target, SETTING_CHARS)}\`, whose port is not a number between 1 and 65535`,
+        };
+    }
+    if (!HOSTNAME.test(dnsName)) {
+        return {
+            invalid: `the platform's egress check is configured to resolve \`${scrubbedExcerpt(dnsName, SETTING_CHARS)}\`, which is not a hostname`,
+        };
+    }
+    return { target: { host, port: parsed, dnsName } };
+}
+/**
+ * The argv the egress container runs: connect, say what that returned, resolve, say the same.
+ *
+ * Both observations are made and BOTH are reported, because they fail for different reasons and
+ * have different fixes. A connect to a raw address needs only a route; a lookup needs the
+ * daemon's embedded resolver to be reachable and to forward. Reporting only the first would call
+ * a container with a working route and broken DNS "reachable", and nothing an agent fetches by
+ * name would work there.
+ *
+ * Every applet is called by its full path (`/busybox nc`) rather than by name. The image holds
+ * one file and no PATH, and busybox's standalone-shell dispatch is a build-time option nothing
+ * here may assume.
+ *
+ * The connect is the half that is easy to get silently wrong, and `nc -w SEC` alone gets it
+ * wrong. busybox documents that flag as the timeout for connects AND FINAL NET READS: once stdin
+ * hits EOF `nc` half-closes and then waits to be spoken to, so a connect that SUCCEEDED to a peer
+ * which expects the client to speak first (every TLS port, the default `1.1.1.1:443` included)
+ * hits the alarm and exits non-zero. Read off the exit status alone that is indistinguishable
+ * from a refusal, so a working network reports a route that is not there. `-z` means "connect,
+ * then stop", which is the question being asked, so it is used wherever the payload's busybox was
+ * built with it; where it was not, the connect runs with no `-w`, which is the build whose `nc`
+ * exits on its own when stdin closes.
+ *
+ * Both halves are wrapped in `${busybox} timeout` either way, since a blackholed route is silent
+ * rather than refused and the applet's own ceiling is the thing this comment exists because we
+ * cannot assume.
+ */
+export function buildEgressCommand(target) {
+    const busybox = `/${PROBE_BINARY_PATH}`;
+    const bounded = (seconds, command) => `${busybox} timeout ${seconds} ${command}`;
+    const where = `${target.host} ${target.port}`;
+    const connectSeconds = EGRESS_CONNECT_TIMEOUT_SECONDS + 1;
+    const connect = [
+        'nc_z=no',
+        `case "$(${bounded(EGRESS_USAGE_TIMEOUT_SECONDS, `${busybox} nc`)} 2>&1)" in *-z*) nc_z=yes ;; esac`,
+        'if [ "$nc_z" = yes ]; then',
+        `  ${bounded(connectSeconds, `${busybox} nc -w ${EGRESS_CONNECT_TIMEOUT_SECONDS} -z ${where}`)} >/dev/null 2>&1`,
+        'else',
+        `  ${bounded(connectSeconds, `${busybox} nc ${where}`)} </dev/null >/dev/null 2>&1`,
+        'fi',
+    ].join('\n');
+    const resolve = bounded(EGRESS_LOOKUP_TIMEOUT_SECONDS, `${busybox} nslookup ${target.dnsName}`);
+    return [
+        busybox,
+        'sh',
+        '-c',
+        [
+            `${connect}\necho "${EGRESS_TCP_MARKER}$?"`,
+            `${resolve} >/dev/null 2>&1; echo "${EGRESS_DNS_MARKER}$?"`,
+        ].join('\n'),
+    ];
+}
 /**
  * Node's architecture names mapped onto the docker name for the same machine.
  *

package/dist/docker-status.d.ts

@@ -31,7 +31,20 @@ export type DockerSource =
 export interface DockerStatus {
     available: boolean | undefined;
     source: DockerSource;
-    /** Why, in the entrypoint's own closed vocabulary (`serving`/`failed`/`missing`/…). */
+    /**
+     * Why, in the entrypoint's own closed vocabulary (`serving`, `serving-without-nat`,
+     * `still-starting`, `failed`, `missing`, `unreachable`, `probing`).
+     *
+     * Reported and never branched on, which is what lets the entrypoint add a word without anything
+     * here having to know it. Two are worth knowing about. `serving-without-nat`: the daemon that
+     * manages its own firewall rules exited without serving, so the one that came up runs with
+     * `--iptables=false` and its NESTED containers have no egress. That is a CAUSE, and the only
+     * place one exists; what MEASURES the consequence is the egress half of the workload check
+     * (docker-capability.ts), from inside a container, with no way to learn why. `still-starting`
+     * is a daemon that had not answered when the boot budget ran out and is STILL RUNNING, which is
+     * the one absence that routinely stops being true: it is exactly what the live re-probe below
+     * exists to catch.
+     */
     reason: string;
     /** A human detail for the failing cases: the dockerd log tail, or what was unreachable. */
     detail?: string;

package/dist/environment-inventory.d.ts

@@ -1,5 +1,5 @@
 import { type Logger } from './logger.js';
-import { type DockerWorkload } from './docker-capability.js';
+import { type ContainerEgress, type DockerWorkload } from './docker-capability.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
@@ -50,10 +50,16 @@ export type ToolPresence = {
  *   - `serving`:  it answered, and the workload check could not be carried out (no payload on
  *                   this machine, an unmapped architecture, a timeout). Neither of the other two,
  *                   and rendered as "try it if you need it".
+ *
+ * `usable` then carries what a nested container could REACH, which is a second fact and not a
+ * sixth state: what an agent may do with the daemon and what its containers can fetch are
+ * different questions, and each of the three egress answers changes the advice without changing
+ * the verdict on the daemon.
  */
 export type DockerCapability = {
     status: 'usable';
     server?: string;
+    egress: ContainerEgress;
 } | {
     status: 'unusable';
     server?: string;

package/dist/environment-inventory.js

@@ -2,7 +2,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { log } from './logger.js';
 import { harnessListenPort } from './harness-port.js';
-import { probeDockerWorkload } from './docker-capability.js';
+import { probeDockerWorkload, } from './docker-capability.js';
 // ---------------------------------------------------------------------------
 // What this machine actually has, probed ONCE per job and stated to the agent.
 //
@@ -38,6 +38,12 @@ import { probeDockerWorkload } from './docker-capability.js';
 //     all fail (issue #2120). Only a container that RAN settles that, so the reachable case is
 //     split by a real workload (docker-capability.ts) into `usable`, `unusable`, and a daemon
 //     that answered while the check itself could not be carried out.
+//   - And a daemon that runs containers is still not one whose containers have a NETWORK, which
+//     is the same mistake one level in again. Loading and running a local image needs no network,
+//     so a daemon started with `--iptables=false` passes the workload check while every nested
+//     container is cut off (issue #2174): what an agent then hits is a `docker build` whose
+//     `RUN npm ci` sits in retry backoff for about seven minutes before failing. So `usable`
+//     carries its own egress verdict, and the line below says something different for each.
 //
 // 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
@@ -289,7 +295,7 @@ async function probeDockerCapability(run, opts) {
     const server = daemon.version ? { server: daemon.version } : {};
     const workload = await (opts.workload ?? probeDockerWorkload)(opts.signal);
     if (workload.status === 'usable')
-        return { status: 'usable', ...server };
+        return { status: 'usable', ...server, egress: workload.egress };
     if (workload.status === 'unusable')
         return { status: 'unusable', ...server, detail: workload.detail };
     return { status: 'serving', ...server, reason: workload.reason };
@@ -420,8 +426,7 @@ function dockerDaemonLine(daemon) {
     const server = 'server' in daemon && daemon.server ? ` (server ${daemon.server})` : '';
     switch (daemon.status) {
         case 'usable':
-            return (`A Docker daemon is reachable${server} and the platform ran a container on it: ` +
-                '`docker build`, `docker run` and `docker compose up` work here.');
+            return `A Docker daemon is reachable${server} and the platform ran a container on it: ${usableCommands(daemon.egress)} work here. ${egressSentence(daemon.egress)}`;
         case 'unusable':
             return (`A Docker daemon is reachable${server} but it CANNOT run a container: the platform ` +
                 `built a one-layer image and tried to run it here, and that failed (${daemon.detail}). ` +
@@ -448,6 +453,70 @@ function dockerDaemonLine(daemon) {
 function unnamedCapability(daemon) {
     return `Whether a Docker daemon is reachable could not be determined (the platform reported an unrecognised verdict ${JSON.stringify(daemon)}): try it if you need it.`;
 }
+/**
+ * Which commands the `usable` line may claim, which is the EGRESS verdict's business and not the
+ * daemon's.
+ *
+ * Split out because the line used to open with the full list and then, one sentence later, tell
+ * the agent that every `RUN` line which fetches anything fails. A block that also says not to
+ * spend turns re-checking it cannot afford to state and then retract the same fact: an agent
+ * reading the first sentence has already been told `docker build` works here, which is the exact
+ * shape of the lie issue #2174 is about. TOTAL over {@link ContainerEgress}, like its sibling.
+ */
+function usableCommands(egress) {
+    switch (egress.status) {
+        case 'blocked':
+            // Deliberately omits `docker build`: it is the one the missing NAT rule actually breaks,
+            // and the sentence that follows explains which part of it and why.
+            return '`docker run` and `docker compose up` of images that are already built';
+        case 'reachable':
+        case 'undetermined':
+            return '`docker build`, `docker run` and `docker compose up`';
+        default:
+            return unnamedEgressCommands(egress);
+    }
+}
+/** The commands claimed for an egress verdict this build does not know: none of them. */
+function unnamedEgressCommands(egress) {
+    return `the docker commands the platform could name for its verdict ${JSON.stringify(egress)}`;
+}
+/**
+ * The second half of the `usable` line: what a container started HERE can reach, and what to do
+ * about it. TOTAL over {@link ContainerEgress} for the same reason the line above is over the
+ * daemon's states.
+ *
+ * The `blocked` arm is the one this exists for, and it is precise about WHICH commands break,
+ * because "docker has no network" is not true and an agent that believed it would skip work it
+ * could have done. The daemon has a network: it pulls base images and compose pulls its services
+ * normally. What has none is the container each `RUN` line executes in. The seven minutes are
+ * named because the failure does not look like a failure from inside the agent's loop: npm turns
+ * "no route" into `EAI_AGAIN` only once its retry backoff gives up, so the build reads as a hang
+ * and the natural response is to wait longer.
+ */
+function egressSentence(egress) {
+    switch (egress.status) {
+        case 'reachable':
+            return 'A container started here also reaches the network, so a build that installs dependencies works.';
+        case 'blocked':
+            return ('A container started here could reach NOTHING the platform tried, and that is a fact ' +
+                `about this sandbox rather than about your work (${egress.detail}). The daemon itself is ` +
+                'fine: it pulls base images, and `docker compose up` of pre-built images works. What ' +
+                'fails is every `RUN` line in a `docker build` that fetches from the public internet ' +
+                '(`npm ci`, `apk add`, `pip install`), and it fails SLOWLY: npm reports `EAI_AGAIN` only ' +
+                'after some seven minutes of retry backoff, so it reads as a hang. Do not wait it out ' +
+                'and do not retry. Vendor what you need, skip the image build, verify some other way, or ' +
+                'say in one line that you could not verify it here. If this project already builds ' +
+                'against a mirror inside this network, that is not one of the addresses tried above and ' +
+                'is worth one attempt.');
+        case 'undetermined':
+            return `Whether a container started here can reach the network was NOT established (${egress.reason}), so try it if you need it and do not read a failure as a defect in the work.`;
+        default:
+            return unnamedEgress(egress);
+    }
+}
+function unnamedEgress(egress) {
+    return `Whether a container started here can reach the network could not be determined (the platform reported an unrecognised verdict ${JSON.stringify(egress)}).`;
+}
 /**
  * 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
@@ -477,6 +546,12 @@ export async function appendEnvironmentInventory(systemPrompt, opts = {}) {
                 .map((t) => t.name)
                 .join(','),
             dockerDaemon: inventory.dockerDaemon.status,
+            // Present only when a nested container was actually asked, which is the one state that has
+            // an egress answer at all. A word here for every other state would report "no measurement"
+            // and "measured, and it cannot get out" in the same field.
+            ...(inventory.dockerDaemon.status === 'usable'
+                ? { dockerEgress: inventory.dockerDaemon.egress.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

package/dist/infra-standup.js

@@ -62,6 +62,9 @@ export async function standUpInfra(dir, infra, signal, logger, probe = probeLive
             // boot record's own words for a daemon that answers and cannot run anything are `serving`
             // and nothing else, so a log line carrying the record alone describes the wrong failure.
             dockerWorkload: docker.workload?.status ?? 'unmeasured',
+            ...(docker.workload?.status === 'usable'
+                ? { dockerEgress: docker.workload.egress.status }
+                : {}),
             ...(docker.workload?.status === 'unusable' ? { dockerDetail: docker.workload.detail } : {}),
         });
         return {
@@ -140,10 +143,22 @@ export async function standUpInfra(dir, infra, signal, logger, probe = probeLive
  * container DID on it is `usable`, `unusable`, or a check that could not be carried out. Absent
  * when nothing was measured at all (an undecided boot record probes nothing), which is not the
  * same as a check that ran and could not tell.
+ *
+ * THREE fields rather than two, because `usable` is not one fact. A daemon running with
+ * `--iptables=false` runs containers perfectly and gives them no network, so it is `usable` and
+ * every `docker build` that fetches anything on it is guaranteed to fail. The agent's prompt and
+ * `GET /health` both learn that; without `dockerEgress` the record a human reads on the Tester
+ * step, and every backend consumer of it, sees the same undifferentiated `usable` as a sandbox
+ * where the stack actually works. Present only on `usable`, which is the one verdict that has an
+ * egress half at all: on any other, a word here would report "no measurement" and "measured, and
+ * it cannot get out" in the same field.
  */
 function workloadRecord(workload) {
     if (!workload)
         return {};
+    if (workload.status === 'usable') {
+        return { dockerWorkload: 'usable', dockerEgress: workload.egress.status };
+    }
     return { dockerWorkload: workload.status === 'unknown' ? 'undetermined' : workload.status };
 }
 /**

package/dist/job.d.ts

@@ -566,6 +566,16 @@ export interface InfraSetupRecord {
      * ran and could not tell; ABSENT means nothing was measured at all.
      */
     dockerWorkload?: 'usable' | 'unusable' | 'undetermined';
+    /**
+     * What a container started ON that daemon could REACH, when the platform measured it.
+     *
+     * The fourth diagnosis, and the one `dockerWorkload: 'usable'` structurally cannot carry: a
+     * rootless daemon started with `--iptables=false` installs no MASQUERADE rule for its bridge,
+     * so it runs containers perfectly and none of them has a route out. The stack comes up and
+     * every `docker build` that fetches a dependency fails, slowly. Present only alongside
+     * `usable`, which is the one verdict with an egress half; absent means nothing measured it.
+     */
+    dockerEgress?: 'reachable' | 'blocked' | 'undetermined';
     /** The repo-relative compose file that was stood up. */
     composePath?: string;
     /** Epoch ms the stand-up attempt finished. */

package/dist/redact.d.ts

@@ -11,6 +11,21 @@ export declare function registerKnownSecrets(values: readonly string[]): void;
 export declare function redact(input: string, knownSecrets?: readonly string[]): string;
 /** Pattern + registered-value redaction. Kept for callers without a per-call secret list. */
 export declare function redactSecrets(input: string): string;
+/**
+ * A scrubbed, length-bounded excerpt of a string that is about to be QUOTED at a human or a
+ * model: a failing command's output, a rejected setting, a thrown message.
+ *
+ * One helper rather than a private `bounded()` per module, which is what this replaced. Two of
+ * them had drifted: `docker-probe-image.ts` echoed a rejected `HARNESS_DOCKER_EGRESS_TARGET`
+ * verbatim into a string that reaches every agent's system prompt and `GET /health`, while its
+ * same-named neighbour in `docker-capability.ts` scrubbed first. A proxy URL with an embedded
+ * token in that setting is the ordinary way that becomes a leak, and two helpers with one name
+ * in sibling files is what kept the divergence invisible.
+ *
+ * Scrub BEFORE bounding, so the cut cannot land inside a credential and leave half of it
+ * quotable, and mark a trimmed value so a reader never takes the head for the whole.
+ */
+export declare function scrubbedExcerpt(text: string, maxChars: number): string;
 /** Cap on captured command output kept on an infra record (tail-biased — failures show last). */
 export declare const MAX_CAPTURED_OUTPUT_CHARS = 16000;
 /**

package/dist/redact.js

@@ -65,6 +65,24 @@ export function redact(input, knownSecrets = []) {
 export function redactSecrets(input) {
     return redact(input);
 }
+/**
+ * A scrubbed, length-bounded excerpt of a string that is about to be QUOTED at a human or a
+ * model: a failing command's output, a rejected setting, a thrown message.
+ *
+ * One helper rather than a private `bounded()` per module, which is what this replaced. Two of
+ * them had drifted: `docker-probe-image.ts` echoed a rejected `HARNESS_DOCKER_EGRESS_TARGET`
+ * verbatim into a string that reaches every agent's system prompt and `GET /health`, while its
+ * same-named neighbour in `docker-capability.ts` scrubbed first. A proxy URL with an embedded
+ * token in that setting is the ordinary way that becomes a leak, and two helpers with one name
+ * in sibling files is what kept the divergence invisible.
+ *
+ * Scrub BEFORE bounding, so the cut cannot land inside a credential and leave half of it
+ * quotable, and mark a trimmed value so a reader never takes the head for the whole.
+ */
+export function scrubbedExcerpt(text, maxChars) {
+    const scrubbed = redactSecrets(text);
+    return scrubbed.length > maxChars ? `${scrubbed.slice(0, maxChars)}…` : scrubbed;
+}
 /** Cap on captured command output kept on an infra record (tail-biased — failures show last). */
 export const MAX_CAPTURED_OUTPUT_CHARS = 16_000;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.147.0",
+  "version": "1.149.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -25,10 +25,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@cat-factory/contracts": "0.338.0",
-    "@cat-factory/kernel": "0.327.0",
-    "@cat-factory/server": "0.310.1",
-    "@cat-factory/spend": "0.17.3",
+    "@cat-factory/contracts": "0.343.0",
+    "@cat-factory/kernel": "0.332.0",
+    "@cat-factory/server": "0.311.3",
+    "@cat-factory/spend": "0.17.8",
     "@hono/node-server": "^2.1.1",
     "@types/node": "^26.4.0",
     "hono": "^4.13.5",

package/src/agent.ts

@@ -189,9 +189,12 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
     // single post-clone place to put this). The pass is sized for that: everything in it runs
     // concurrently, and every probe either answers in milliseconds or is bounded. Two of them are
     // deliberate waits rather than instant answers: one short retry for a daemon that is still
-    // starting, and, only once a daemon has answered, the container the platform runs to find out
-    // whether it can run one at all (`docker-capability.ts`, budgeted and memoised per container
-    // for a positive). Both take the job's signal, so an abandoned run stops paying at once.
+    // starting, and, only once a daemon has answered, the CONTAINERS the platform runs to find out
+    // what this daemon can do (`docker-capability.ts`: one to prove it runs a container at all,
+    // then one on the default network to see what that container reaches). Both are budgeted, and
+    // the pair is memoised per container once it has SETTLED, which is any positive plus every
+    // negative that cannot change under a running container. Both take the job's signal, so an
+    // abandoned run stops paying at once.
 
     const staged: AgentJob = {
       ...job,