@cat-factory/executor-harness 1.145.1 → 1.149.0

package/dist/infra-standup.js

@@ -4,7 +4,7 @@
 // guarantees the matching teardown. `manageInfra` is the one entry point a mode calls.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { probeDockerServing, readDockerStatus, resolveDockerVerdict, } from './docker-status.js';
+import { probeLiveDockerCapability, readDockerStatus, resolveDockerVerdict, } from './docker-status.js';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { captureRedactedOutput, redactSecrets } from './redact.js';
 const exec = promisify(execFile);
@@ -15,19 +15,22 @@ const exec = promisify(execFile);
  * still run unit-level tests and report what it could. A no-op for ephemeral / no-infra /
  * no-compose-path runs.
  *
- * A CONFIRMED absence of a Docker daemon short-circuits it: the container's own probe
- * ({@link readDockerStatus}, recorded by `entrypoint.sh`) already knows there is nothing to
- * talk to, so running compose against it would only turn a fact this container holds into a
- * connection error the agent has to interpret. The record then carries `dockerAvailable: false`
- * and the stated cause, which is what makes the Tester step say why it ran no infra instead of
- * looking like a Tester that simply chose not to. Anything OTHER than a confirmed absence
- * attempts as before (`DockerStatus.available` in docker-status.ts states why "undecided" is its
- * own value).
+ * A CONFIRMED absence of a USABLE Docker daemon short-circuits it: the container already knows
+ * compose cannot work, so running it would only turn a fact this container holds into an error
+ * the agent has to interpret. The record then carries the stated cause plus the two facts that
+ * decide where a human should look (`dockerAvailable`: was anything answering, `dockerWorkload`:
+ * what a container did on it), which is what makes the Tester step say why it ran no infra
+ * instead of looking like a Tester that simply chose not to. Anything OTHER than a confirmed
+ * negative attempts as before (`DockerStatus.available` in docker-status.ts states why
+ * "undecided" is its own value).
  *
- * "Confirmed", not merely recorded: {@link resolveDockerVerdict} re-checks a recorded absence
- * against a live daemon first, so a warm-pool container whose sidecar came up late is not
- * latched into refusing infra that works. `probe` is that check, injected so the unit suite can
- * state both answers on a machine that has its own daemon either way.
+ * "Confirmed", not merely recorded: {@link resolveDockerVerdict} re-checks the boot record
+ * against a live daemon first, so a warm-pool container whose sidecar came up late is not latched
+ * into refusing infra that works. It re-checks a recorded PRESENCE too, by running an actual
+ * container: a rootless daemon in a sandbox answers `docker version` while being unable to mount
+ * an image, and compose against that one died on a mount error inside the very mechanism that
+ * exists to explain why infra did not come up. `probe` is that check, injected so the unit suite
+ * can state every answer on a machine that has its own daemon either way.
  *
  * Whether it succeeds or fails, the (redacted, bounded) command output is captured into a
  * {@link InfraSetupRecord} returned alongside the prompt `note`, so the backend can surface
@@ -38,26 +41,45 @@ const exec = promisify(execFile);
  * this container makes about itself, and the acceptance suite can only exercise it on a machine
  * where the daemon genuinely fails.
  */
-export async function standUpInfra(dir, infra, signal, logger, probe = probeDockerServing) {
+export async function standUpInfra(dir, infra, signal, logger, probe = probeLiveDockerCapability) {
     if (infra.environment !== 'local' || infra.noInfraDependencies || !infra.composePath) {
         return { started: false };
     }
     const startedAt = Date.now();
     const recorded = await readDockerStatus();
-    const docker = await resolveDockerVerdict(recorded, probe);
+    const docker = await resolveDockerVerdict(recorded, {
+        probe,
+        ...(signal ? { signal } : {}),
+        logger,
+    });
     if (docker.refusal) {
         const note = `the dependencies could not be started: ${docker.refusal}`;
-        logger.warn('agent(explore): infra stand-up refused, no docker daemon', {
+        logger.warn('agent(explore): infra stand-up refused, no usable docker daemon', {
             composePath: infra.composePath,
             dockerSource: recorded.source,
             dockerReason: recorded.reason,
+            // What the LIVE check found, which is the only place the second refusal cause exists: the
+            // 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 {
             started: false,
             note,
             record: {
                 started: false,
-                dockerAvailable: false,
+                // NOT a flat `false`. Two refusals reach this branch and they have opposite fixes: with
+                // nothing answering, the executor image or the sandbox running it is what to go and look
+                // at; with a daemon that answers and cannot run a container, that daemon is up and an
+                // operator sent to restart it finds nothing wrong. `dockerAvailable` answers only the
+                // first question and `dockerWorkload` the second, so neither has to carry the other's
+                // fact (the same rule the compose-failure branch below states for its own `false`).
+                dockerAvailable: docker.daemon === true,
+                ...workloadRecord(docker.workload),
                 composePath: infra.composePath,
                 at: Date.now(),
                 durationMs: Date.now() - startedAt,
@@ -76,6 +98,7 @@ export async function standUpInfra(dir, infra, signal, logger, probe = probeDock
             record: {
                 started: true,
                 dockerAvailable: true,
+                ...workloadRecord(docker.workload),
                 composePath: infra.composePath,
                 at: Date.now(),
                 durationMs: Date.now() - startedAt,
@@ -96,12 +119,13 @@ export async function standUpInfra(dir, infra, signal, logger, probe = probeDock
             note,
             record: {
                 started: false,
-                // A compose failure with a REACHABLE daemon: the two `false`s above and here are
-                // different diagnoses (nothing to talk to vs the stack itself did not come up), and
-                // only stating both keeps the second from being read as the first. Read off the
-                // RESOLVED verdict, so a container whose daemon came up after boot claims the daemon it
-                // actually reached rather than the one its boot record still denies.
-                ...(docker.available === true ? { dockerAvailable: true } : {}),
+                // A compose failure with a REACHABLE daemon, which is a third diagnosis again: the stack
+                // itself did not come up. Read off the RESOLVED verdict, so a container whose daemon came
+                // up after boot claims the daemon it actually reached rather than the one its boot record
+                // still denies, and OMITTED rather than `false` when nothing answered the live check,
+                // because the boot record's word for that is a hypothesis and not a measurement.
+                ...(docker.daemon === true ? { dockerAvailable: true } : {}),
+                ...workloadRecord(docker.workload),
                 composePath: infra.composePath,
                 at: Date.now(),
                 durationMs: Date.now() - startedAt,
@@ -111,6 +135,32 @@ export async function standUpInfra(dir, infra, signal, logger, probe = probeDock
         };
     }
 }
+/**
+ * What the live check measured, for the record the Tester step shows.
+ *
+ * Its own field beside `dockerAvailable` because the two answer different questions and only one
+ * of them has a boolean's worth of answers: a daemon either answered or it did not, while what a
+ * 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 };
+}
 /**
  * Stand the run's infra up and return a single cleanup handle, dispatching on the spec's
  * `kind`: the frontend UI-test flow (`kind: 'frontend'`) builds/serves the app + WireMock as

package/dist/job.d.ts

@@ -556,6 +556,26 @@ export interface InfraSetupRecord {
      * mistake that let a daemon-less image read as an ordinary infra failure for months.
      */
     dockerAvailable?: boolean;
+    /**
+     * What a real container DID on that daemon, when the platform measured it.
+     *
+     * The third diagnosis, and the one `dockerAvailable` structurally cannot carry: a rootless
+     * daemon nested in a sandbox answers throughout while unable to mount any image layer, so it is
+     * `dockerAvailable: true` and no stack can come up on it (issue #2120). Reporting that as an
+     * absent daemon sends a human to restart one that is already up. `undetermined` is a check that
+     * 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.145.1",
+  "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.334.0",
-    "@cat-factory/kernel": "0.323.2",
-    "@cat-factory/server": "0.307.9",
-    "@cat-factory/spend": "0.16.26",
+    "@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

@@ -187,8 +187,14 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
     // 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.
+    // 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 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,