@cat-factory/executor-harness 1.145.1 → 1.149.0

package/dist/docker-capability.js

@@ -0,0 +1,510 @@
+import { readFile } from 'node:fs/promises';
+import { spawnDockerCommand, } from './docker-command.js';
+import { buildEgressCommand, buildProbeArchive, EGRESS_DNS_MARKER, EGRESS_TCP_MARKER, parseEgressTarget, payloadArchitecture, PROBE_COMMAND, PROBE_IMAGE_TAG, PROBE_SENTINEL, } from './docker-probe-image.js';
+import { log } from './logger.js';
+import { scrubbedExcerpt } from './redact.js';
+/**
+ * The statically linked binary the probe image is built from, overridable for an image variant
+ * that ships it elsewhere. Absent is a supported answer, not a failure: under
+ * `LOCAL_NATIVE_AGENTS` the harness runs on a developer's machine that never saw this image.
+ */
+const PAYLOAD_PATH = process.env.HARNESS_DOCKER_PROBE_BINARY?.trim() || '/bin/busybox';
+/**
+ * Where the egress check aims, overridable for a deployment whose network permits something else.
+ *
+ * A raw IPv4 address rather than a name, so the connect answers a question about ROUTING alone:
+ * pointing it at a hostname would make every verdict depend on DNS, which is the other half and
+ * is measured separately. `1.1.1.1:443` is an anycast address that answers TLS from everywhere
+ * and belongs to no API this repo calls; the name is npm's because npm is what the outage
+ * actually broke. Neither is validated here (see `parseEgressTarget`), so a rejected setting is
+ * reported rather than replaced.
+ *
+ * Both defaults aim at the PUBLIC internet, and a deployment that deliberately has none should
+ * point these at what it does run (an internal registry mirror and its own DNS zone). Left at
+ * the defaults there, the measurement is honest but narrow: it establishes that a container
+ * cannot reach these two, which is why the prompt built from a `blocked` verdict says which
+ * targets were tried rather than that nothing at all is reachable.
+ */
+const EGRESS_TARGET = process.env.HARNESS_DOCKER_EGRESS_TARGET?.trim() || '1.1.1.1:443';
+const EGRESS_DNS_NAME = process.env.HARNESS_DOCKER_EGRESS_DNS_NAME?.trim() || 'registry.npmjs.org';
+/**
+ * The ceiling on ONE WHOLE measurement, shared out across the docker commands it makes: each
+ * gets what is left of it, down to {@link MIN_COMMAND_MS}.
+ *
+ * One budget rather than a per-command ceiling, because a per-command one multiplies: three
+ * commands at 30s each is a minute and a half of dead time on a wedged daemon, on the critical
+ * path ahead of the clone. Sized for a WEDGED daemon and not for a slow one: the payload is a
+ * couple of megabytes already on local disk, so a daemon that works answers in about the time it
+ * takes to start one container, and a daemon that cannot mount fails immediately.
+ *
+ * What it does NOT do is bound the cost per JOB, and the comment that once claimed so was wrong.
+ * A POSITIVE verdict is memoised for the container's life; a negative is deliberately
+ * re-measured (see {@link createDockerWorkloadProbe}), and two independent sites ask per job (the
+ * environment inventory and the compose stand-up), so a serving-but-wedged daemon costs this
+ * twice per job. That is the price of not latching a warm container into a stale refusal, which
+ * is why the budget is the size it is and why an abandoned job stops paying it at once.
+ */
+const WORKLOAD_BUDGET_MS = 20_000;
+/** The floor on one command's share of the budget, so an exhausted budget still gets an answer. */
+const MIN_COMMAND_MS = 1_000;
+/**
+ * The ceiling on the egress container, which gets its OWN budget rather than a share of the one
+ * above.
+ *
+ * The argument for a single shared budget is that a per-command ceiling multiplies on a WEDGED
+ * daemon, and that argument does not reach here: this container is started only after another one
+ * has already run to completion, so the daemon is known to work by the time it is spawned. What
+ * it does have to allow for is a check that is SUPPOSED to be slow in the failing case, since a
+ * blocked route is silent rather than refused and both in-container timeouts have to expire.
+ * Taking that out of the workload budget would have starved the step this whole module exists
+ * for; leaving it unbounded would hand a wedged network the whole job.
+ */
+const EGRESS_BUDGET_MS = 20_000;
+/**
+ * The ceiling on removing the probe image again.
+ *
+ * Its own, and deliberately NOT given the caller's abort signal: the image is the platform's, and
+ * a cancelled job is the one case where nobody is left to clean up after it. Bounded separately
+ * so a wedged daemon cannot turn the cleanup into a second full budget.
+ */
+const CLEANUP_TIMEOUT_MS = 5_000;
+/** How much of a failing command's output is kept. It is quoted into an agent's system prompt. */
+const DETAIL_CHARS = 300;
+/** Build a {@link ProbeArchiveMemo}. Supplied only by {@link realDeps}, so a test memoises nothing. */
+export function oneSlotArchiveMemo() {
+    let held;
+    return {
+        read: (key) => (held?.key === key ? held.archive : undefined),
+        write: (key, archive) => {
+            held = { key, archive };
+        },
+    };
+}
+const realDeps = {
+    readPayload: (path) => readFile(path),
+    payloadPath: PAYLOAD_PATH,
+    runDocker: spawnDockerCommand,
+    arch: process.arch,
+    egress: { target: EGRESS_TARGET, dnsName: EGRESS_DNS_NAME },
+    archives: oneSlotArchiveMemo(),
+};
+/**
+ * Carry out one measurement. Pure of caching, so the suite states every branch directly.
+ *
+ * TOTAL: it never rejects, whatever happens inside it. The thing it replaced was total by
+ * construction (a `try/catch` around one `execFile`), and it is consulted from a stand-up path
+ * documented as best-effort, so a throw here would fail a job over a probe whose whole purpose is
+ * to make a failure legible. A throw is also, by definition, the platform's own machinery
+ * breaking, which is the `unknown` disposition and never the `unusable` one.
+ *
+ * That asymmetry is the design. Only the RUN produces `unusable`; everything before it produces
+ * `unknown`, because everything before it is the platform's own machinery and a bug in it must be
+ * able to say "I could not tell" and never "your daemon is broken". The load step in particular is
+ * the one this repo wrote itself.
+ */
+export async function measureDockerWorkload(deps = realDeps, signal) {
+    const seen = { daemonAnswered: false };
+    try {
+        return await measure(deps, seen, signal);
+    }
+    catch (err) {
+        const cause = describeThrown(err);
+        (deps.logger ?? log).warn('docker capability: the container check itself fell over', {
+            error: cause,
+        });
+        return undeterminable(`the platform's own container check could not be completed (${cause})`, seen.daemonAnswered);
+    }
+}
+async function measure(deps, seen, signal) {
+    const deadline = Date.now() + WORKLOAD_BUDGET_MS;
+    const share = () => Math.max(MIN_COMMAND_MS, deadline - Date.now());
+    const command = (args, stdin) => deps.runDocker(args, {
+        ...(stdin ? { stdin } : {}),
+        ...(signal ? { signal } : {}),
+        timeoutMs: share(),
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    });
+    // Ask the DAEMON which architecture it runs, rather than assuming it shares this process's.
+    // An external `DOCKER_HOST` is a supported path, and an arm64 harness against an amd64 sidecar
+    // (or a remote x86_64 daemon reached from an arm64 laptop) shares nothing with it but a socket:
+    // declaring the wrong one in the image config gets the run refused, which would report a
+    // perfectly good daemon as one that cannot run containers. It is also the cheapest proof that a
+    // daemon is answering at all, which is the fact `resolveDockerVerdict` reads back.
+    const asked = await command(['version', '--format', '{{.Server.Arch}}']);
+    if (asked.outcome !== 'ran' || asked.code !== 0) {
+        return undeterminable(`no Docker daemon answered the platform's container check (${describeOutcome(asked)})`, false);
+    }
+    seen.daemonAnswered = true;
+    const daemonArch = asked.stdout.trim();
+    if (!/^[a-z0-9_]+$/.test(daemonArch)) {
+        return undeterminable(`the Docker daemon did not name an architecture the platform can build an image for (${scrubbedExcerpt(daemonArch, 40) || 'it answered nothing'})`, true);
+    }
+    const payloadArch = payloadArchitecture(deps.arch);
+    if (!payloadArch) {
+        return undeterminable(`the platform has no container check for the ${deps.arch} architecture`, true);
+    }
+    if (payloadArch !== daemonArch) {
+        return undeterminable(`the platform's container check is built for ${payloadArch} and this daemon runs ${daemonArch}`, true);
+    }
+    const assembled = await assembleArchive(deps, daemonArch);
+    if ('reason' in assembled)
+        return undeterminable(assembled.reason, true);
+    const load = await command(['load'], assembled.archive);
+    if (load.outcome !== 'ran' || load.code !== 0) {
+        return undeterminable(`the platform could not load its own probe image (${describeOutcome(load)})`, true);
+    }
+    const run = await command([
+        'run',
+        '--rm',
+        '--pull',
+        'never',
+        '--network',
+        'none',
+        PROBE_IMAGE_TAG,
+        ...PROBE_COMMAND,
+    ]);
+    // A daemon that ran that container has answered the first question, and only then is there a
+    // second one worth asking. An `unusable` daemon cannot run the egress container either, and a
+    // check that could not be carried out has nothing to measure egress against.
+    const verdict = classifyRun(run);
+    const measured = verdict.status === 'usable'
+        ? { status: 'usable', egress: await measureEgress(deps, signal) }
+        : verdict;
+    // After both runs, whatever the verdict is: the probe image is the platform's, and an agent
+    // that runs `docker images` should not have to wonder whose it is.
+    await removeProbeImage(deps);
+    return measured;
+}
+/**
+ * Run the second container and read what it reached.
+ *
+ * On the DEFAULT network, deliberately, which is the one thing that separates it from the marker
+ * run above (`--network none`). What an agent's own `docker build` and `docker run` get is the
+ * bridge, and the bridge is exactly what a daemon started with `--iptables=false` fails to NAT.
+ *
+ * Never concludes anything about the DAEMON. Every failure here is either evidence about the
+ * network or evidence about this check, and the caller has already established that the daemon
+ * runs containers.
+ */
+async function measureEgress(deps, signal) {
+    const setting = parseEgressTarget(deps.egress.target, deps.egress.dnsName);
+    // A rejected setting is read from this container's own environment, so it answers the same way
+    // on every job: latched rather than re-measured, which would otherwise spend two container
+    // starts per job re-reading one unchanged string.
+    if ('invalid' in setting) {
+        return { status: 'undetermined', reason: setting.invalid, recheck: false };
+    }
+    const run = await deps.runDocker(['run', '--rm', '--pull', 'never', PROBE_IMAGE_TAG, ...buildEgressCommand(setting.target)], {
+        ...(signal ? { signal } : {}),
+        timeoutMs: EGRESS_BUDGET_MS,
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    });
+    return classifyEgress(run, setting.target);
+}
+/**
+ * What the egress container's output proves, over the four combinations its two markers can
+ * carry.
+ *
+ * Read off the STATUS each command printed rather than off the run's own exit code, because the
+ * two failures that look alike from outside need opposite answers: a refused connection is
+ * evidence about the network, and a 126/127 is busybox saying the image has no such applet, which
+ * is evidence about the platform's own payload and may never be reported as a network that is not
+ * there.
+ */
+function classifyEgress(run, target) {
+    const where = `${target.host}:${target.port}`;
+    if (run.outcome === 'failed') {
+        return {
+            status: 'undetermined',
+            reason: `the platform's egress check did not run (${run.reason})`,
+            // A spawn failure or a timeout is about this attempt and not about the container.
+            recheck: true,
+        };
+    }
+    const tcp = readMarker(run.stdout, EGRESS_TCP_MARKER);
+    const dns = readMarker(run.stdout, EGRESS_DNS_MARKER);
+    if (tcp === undefined || dns === undefined) {
+        // Nothing was measured, and the two ways to get here need different words. `docker run`
+        // failing at the DAEMON level (125, or its own "no such image") means the container never
+        // started, so the network was not the thing that did not answer; a container that started
+        // and printed something unrecognisable is the platform's own payload misbehaving. Reporting
+        // the first as "printed no verdict" tells an operator to go looking at the check's output
+        // for a container that produced none.
+        const refused = platformSideRunFailure(run) ?? (run.code === 125 ? daemonRefusedEgressRun : undefined);
+        return refused
+            ? {
+                status: 'undetermined',
+                reason: `the platform's egress container did not start (${refused}: ${describeOutcome(run)})`,
+                // The daemon just ran the marker container, so a bridge it could not attach now is
+                // the sort of thing that can differ on the next job.
+                recheck: true,
+            }
+            : {
+                status: 'undetermined',
+                reason: `the platform's egress check printed no verdict (${describeOutcome(run)})`,
+                // Same image, same argv, same output: asking again re-reads the same non-answer.
+                recheck: false,
+            };
+    }
+    if ([tcp, dns].some((code) => code === 126 || code === 127)) {
+        return {
+            status: 'undetermined',
+            reason: "the platform's egress check could not run inside its own probe container (the payload " +
+                'has no `nc` or `nslookup` applet)',
+            // A fact about the image this repo builds, which does not change under a running container.
+            recheck: false,
+        };
+    }
+    if (tcp === 0 && dns === 0)
+        return { status: 'reachable' };
+    if (tcp === 0) {
+        return {
+            status: 'blocked',
+            detail: `a container reached ${where} but could not resolve ${target.dnsName}: the route out works and DNS does not`,
+        };
+    }
+    if (dns === 0) {
+        // A resolved name proves a path out of the container exists, so the connect failing is far
+        // more likely to be about the ADDRESS than about the network. Saying "blocked" here would
+        // condemn a working sandbox over a target it happens to filter.
+        return {
+            status: 'undetermined',
+            reason: `a container resolved ${target.dnsName} but could not connect to ${where}, so this ` +
+                'deployment probably filters that address; point HARNESS_DOCKER_EGRESS_TARGET at one it permits',
+            // A filtered address is a standing property of the network this container sits in.
+            recheck: false,
+        };
+    }
+    return {
+        status: 'blocked',
+        detail: `a container could reach neither ${where} nor ${target.dnsName}, the two the platform is configured to try`,
+    };
+}
+/** What a 125 from the egress run means, kept beside the other platform-side run messages. */
+const daemonRefusedEgressRun = 'the daemon refused to create or start it';
+/**
+ * The exit status printed after `marker`, or undefined when the container never printed one.
+ *
+ * The LAST occurrence wins, so a marker that somehow reached the stream twice is read at its
+ * final value rather than at whichever came first.
+ */
+function readMarker(stdout, marker) {
+    const status = [...stdout.matchAll(new RegExp(`${marker}(\\d{1,3})`, 'g'))].pop()?.[1];
+    return status === undefined ? undefined : Number(status);
+}
+function classifyRun(run) {
+    if (run.outcome === 'failed') {
+        return undeterminable(`the platform's container check did not run (${run.reason})`, true);
+    }
+    if (run.code === 0) {
+        if (run.stdout.includes(PROBE_SENTINEL))
+            return { status: 'usable' };
+        // Nothing explains this: the container was reported as having run cleanly and produced none
+        // of the output it exists to produce. That is a fact about the check, not about the daemon.
+        return undeterminable("the platform's probe container exited cleanly without printing its marker", true);
+    }
+    const ours = platformSideRunFailure(run);
+    return ours
+        ? undeterminable(`${ours} (${describeOutcome(run)})`, true)
+        : { status: 'unusable', detail: describeOutcome(run) };
+}
+/** Messages that name the PLATFORM's half of a failed run rather than the daemon's. */
+const PLATFORM_SIDE_RUN_MESSAGES = [
+    {
+        pattern: /no such image|unable to find image/i,
+        cause: "the platform's probe image was not there to be run",
+    },
+    {
+        pattern: /exec format error/i,
+        cause: "the platform's probe binary cannot be executed on this daemon's machine",
+    },
+];
+function platformSideRunFailure(run) {
+    if (run.code === 126 || run.code === 127) {
+        return "the platform's probe binary could not be invoked inside the container";
+    }
+    const said = `${run.stderr}\n${run.stdout}`;
+    return PLATFORM_SIDE_RUN_MESSAGES.find((m) => m.pattern.test(said))?.cause;
+}
+/**
+ * Assemble the archive for the daemon's architecture, reusing the last one built.
+ *
+ * A read that fails is classified rather than asserted away: `HARNESS_DOCKER_PROBE_BINARY`
+ * pointing at a directory, at a path this user may not read, or at a failing mount is a
+ * misconfiguration an operator can fix, and "this machine does not have it" states the opposite
+ * fact. The sentence goes into an agent's system prompt and into `GET /health`, so a discarded
+ * cause is a cause nobody ever sees.
+ */
+async function assembleArchive(deps, architecture) {
+    const key = `${deps.payloadPath}::${architecture}`;
+    const held = deps.archives?.read(key);
+    if (held)
+        return { archive: held };
+    let payload;
+    try {
+        payload = await deps.readPayload(deps.payloadPath);
+    }
+    catch (err) {
+        return { reason: describePayloadFailure(err, deps.payloadPath) };
+    }
+    const archive = buildProbeArchive(payload, architecture);
+    deps.archives?.write(key, archive);
+    return { archive };
+}
+function describePayloadFailure(err, path) {
+    const needs = `the platform's own container check needs ${path}`;
+    switch (err.code) {
+        case 'ENOENT':
+        case 'ENOTDIR':
+            return `${needs}, which this machine does not have`;
+        case 'EACCES':
+        case 'EPERM':
+            return `${needs}, which it is not permitted to read`;
+        case 'EISDIR':
+            return `${needs} to be a file, and it is a directory`;
+        default:
+            return `${needs}, which could not be read (${describeThrown(err)})`;
+    }
+}
+/**
+ * Remove the probe image, and SAY SO when that did not work.
+ *
+ * The one line above it promises an agent will never find a `cat-factory-docker-probe` and wonder
+ * whose it is, and the daemon has two ordinary ways to refuse: a `--rm` teardown still in flight
+ * holds the image ("image is being used by stopped container"), and a wedged daemon does not
+ * answer at all. Discarding the outcome left both silent, so the promise was unverifiable in
+ * exactly the states that break it.
+ */
+async function removeProbeImage(deps) {
+    const removed = await deps.runDocker(['image', 'rm', '-f', PROBE_IMAGE_TAG], {
+        timeoutMs: CLEANUP_TIMEOUT_MS,
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    });
+    if (removed.outcome === 'ran' && removed.code === 0)
+        return;
+    (deps.logger ?? log).warn('docker capability: the probe image could not be removed', {
+        image: PROBE_IMAGE_TAG,
+        error: describeOutcome(removed),
+    });
+}
+function undeterminable(reason, daemonAnswered) {
+    return { status: 'unknown', reason, daemonAnswered };
+}
+/** A bounded, scrubbed one-line summary of what a command said, for a prompt or a log field. */
+function describeOutcome(outcome) {
+    if (outcome.outcome === 'failed')
+        return outcome.reason;
+    const said = `${outcome.stderr}\n${outcome.stdout}`
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join('; ');
+    return bounded(said) || `docker exited ${outcome.code} without saying why`;
+}
+/** The one describer for a thrown value here: scrubbed and bounded, like any other detail. */
+function describeThrown(err) {
+    return bounded(err instanceof Error ? err.message : String(err)) || 'it said nothing';
+}
+function bounded(text) {
+    return scrubbedExcerpt(text, DETAIL_CHARS);
+}
+/**
+ * Build a probe that measures at most once per container for a POSITIVE answer.
+ *
+ * A daemon that has run a container has proved something that does not stop being true, so that
+ * verdict is kept and every later job reads it for free. A negative is NOT kept, for the reason
+ * `resolveDockerVerdict` gives about the boot record: a container outlives its boot, a warm pool
+ * serves many jobs from one, and a daemon that was not ready for the first job must not latch
+ * the whole container into saying so. Re-measuring a negative is cheap; a daemon that cannot
+ * mount fails at once.
+ *
+ * A `usable` verdict whose EGRESS could not be determined is re-measured on the same rule and for
+ * the same reason. Whether the bridge is NATed is settled once and for the daemon's life, so a
+ * measured `reachable` or `blocked` is kept; a check that timed out measured nothing, and latching
+ * that would leave the container permanently unable to say which of the two it is.
+ *
+ * But only where asking again could ANSWER differently, which is what `ContainerEgress.recheck`
+ * carries. Most ways to reach `undetermined` are standing facts about this container: a rejected
+ * target setting, a payload with no `nc`, an address the deployment filters. Re-running the whole
+ * measurement on those never converges, and it is not cheap: it is `docker version`, the archive,
+ * `docker load`, two container starts and an `image rm`, per job, ahead of the clone.
+ *
+ * Concurrent callers share one in-flight measurement rather than each starting a container, and
+ * the measurement is cancelled when the LAST of them has abandoned it. Neither half is optional:
+ * one job's abort may not kill a measurement a sibling job is still waiting on (the local native
+ * transport serves every concurrent job from one process), and a measurement nobody is waiting
+ * for is a container start no job will read, which is what an abandoned run should stop paying
+ * for the moment it is abandoned.
+ */
+export function createDockerWorkloadProbe(deps = realDeps) {
+    let latest;
+    let inFlight;
+    const begin = () => {
+        const cancel = new AbortController();
+        const measurement = {
+            cancel,
+            waiters: 0,
+            result: measureDockerWorkload(deps, cancel.signal).then((verdict) => {
+                latest = verdict;
+                if (inFlight === measurement)
+                    inFlight = undefined;
+                return verdict;
+            }),
+        };
+        return measurement;
+    };
+    const probe = (async (signal) => {
+        if (latest?.status === 'usable' && !isWorthReMeasuring(latest.egress))
+            return latest;
+        const measurement = (inFlight ??= begin());
+        measurement.waiters += 1;
+        const watch = signal ? watchAbandonment(signal) : undefined;
+        try {
+            return watch
+                ? await Promise.race([measurement.result, watch.abandoned])
+                : await measurement.result;
+        }
+        finally {
+            watch?.dispose();
+            measurement.waiters -= 1;
+            if (measurement.waiters === 0 && inFlight === measurement)
+                measurement.cancel.abort();
+        }
+    });
+    probe.last = () => latest;
+    return probe;
+}
+/** Whether a kept verdict's egress half is one that asking again could still settle. */
+function isWorthReMeasuring(egress) {
+    return egress.status === 'undetermined' && egress.recheck;
+}
+/**
+ * A verdict for the caller whose job was cancelled while it waited, and the listener teardown
+ * that keeps a long-lived native-transport process from accumulating one per job.
+ */
+function watchAbandonment(signal) {
+    let give = () => { };
+    const abandoned = new Promise((resolve) => {
+        give = () => resolve(undeterminable("the job was cancelled before the platform's container check answered", false));
+        if (signal.aborted)
+            give();
+        else
+            signal.addEventListener('abort', give, { once: true });
+    });
+    return { abandoned, dispose: () => signal.removeEventListener('abort', give) };
+}
+/** The process-wide probe. One per container, which is what makes the positive memo worth having. */
+export const probeDockerWorkload = createDockerWorkloadProbe();
+/**
+ * What `GET /health` reports about the workload check.
+ *
+ * `unmeasured` is its own word rather than an omitted key or a `null`: this endpoint is polled
+ * from boot, so "nothing has needed the daemon yet" is the normal early answer and it must not
+ * read as either a broken daemon or a build that cannot report one.
+ */
+export function reportedDockerWorkload(probe = probeDockerWorkload) {
+    return (probe.last() ?? {
+        status: 'unmeasured',
+        reason: 'nothing in this container has needed the docker daemon yet',
+    });
+}

package/dist/docker-command.d.ts

@@ -0,0 +1,30 @@
+import { type Logger } from './logger.js';
+/** What running one docker command did, kept as raw as the spawn. */
+export type CommandOutcome = {
+    outcome: 'ran';
+    code: number;
+    stdout: string;
+    stderr: string;
+} | {
+    outcome: 'failed';
+    reason: string;
+};
+/** What one docker invocation is given. `timeoutMs` is required: an unbounded one has no caller. */
+export interface DockerCommandOptions {
+    /** Piped to the command's stdin and closed. */
+    stdin?: Buffer;
+    /** The job's signal. An abandoned job's command is killed rather than left running. */
+    signal?: AbortSignal;
+    timeoutMs: number;
+    logger?: Logger;
+}
+/** Run one `docker …` command. Injected so the suite drives every branch with no daemon. */
+export type DockerCommandRunner = (args: string[], opts: DockerCommandOptions) => Promise<CommandOutcome>;
+/**
+ * The real runner: spawn docker, feed it `stdin` when there is any, and report what happened.
+ *
+ * Never rejects. Every way a spawn can go wrong is one of the two outcomes, because the caller
+ * classifies them differently and an exception would collapse that distinction into whichever
+ * `catch` caught it first.
+ */
+export declare const spawnDockerCommand: DockerCommandRunner;

package/dist/docker-command.js

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { log } from './logger.js';
+import { killChildProcess, spawnDetached } from './process.js';
+// ---------------------------------------------------------------------------
+// How the harness runs one `docker …` command ON ITS OWN BEHALF, bounded and abortable.
+//
+// This is NOT a second `runCapturedCommand` (captured-command.ts), which stays the one way the
+// harness runs a DECLARED shell command: that one takes a shell string, merges both streams into
+// one rolling tail and answers with a conventional exit code, because its two callers report a
+// pass/fail plus a tail to a model. The docker checks need the three things it deliberately does
+// not offer: an argv (no shell, so nothing quotes an image tag), a STDIN body (the probe archive
+// is piped to `docker load`), and stdout kept APART from stderr, since the whole evidence that a
+// container ran is a marker on stdout while the evidence of why it did not is on stderr.
+//
+// What it does NOT re-decide is how a child dies: `killChildProcess` owns the SIGTERM→SIGKILL
+// escalation for every process this harness spawns, and a bespoke `SIGKILL` here would be one
+// path whose kill semantics drift from the rest with no test able to see it.
+// ---------------------------------------------------------------------------
+/** How much of each stream is buffered. The TAIL is kept: that is where a failure prints. */
+const OUTPUT_CAP_CHARS = 64 * 1024;
+/**
+ * The real runner: spawn docker, feed it `stdin` when there is any, and report what happened.
+ *
+ * Never rejects. Every way a spawn can go wrong is one of the two outcomes, because the caller
+ * classifies them differently and an exception would collapse that distinction into whichever
+ * `catch` caught it first.
+ */
+export const spawnDockerCommand = (args, opts) => new Promise((resolve) => {
+    const logger = opts.logger ?? log;
+    if (opts.signal?.aborted) {
+        resolve({ outcome: 'failed', reason: abandonedReason(args) });
+        return;
+    }
+    const child = spawn('docker', args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: spawnDetached,
+        windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', onAbort);
+        resolve(result);
+    };
+    const timer = setTimeout(() => {
+        logger.warn('docker: command did not answer in time, killing it', {
+            command: args[0] ?? '',
+            timeoutMs: opts.timeoutMs,
+        });
+        killChildProcess(child, undefined, logger);
+        finish({
+            outcome: 'failed',
+            reason: `\`docker ${args[0] ?? ''}\` did not answer within ${Math.round(opts.timeoutMs / 1000)}s`,
+        });
+    }, opts.timeoutMs);
+    timer.unref?.();
+    const onAbort = () => {
+        killChildProcess(child, undefined, logger);
+        finish({ outcome: 'failed', reason: abandonedReason(args) });
+    };
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+    // The tail, not the head: a `docker run` that failed says why in its last lines, and the
+    // marker a passing one prints is the whole of its output anyway.
+    child.stdout.on('data', (chunk) => {
+        stdout = (stdout + chunk.toString('utf8')).slice(-OUTPUT_CAP_CHARS);
+    });
+    child.stderr.on('data', (chunk) => {
+        stderr = (stderr + chunk.toString('utf8')).slice(-OUTPUT_CAP_CHARS);
+    });
+    child.on('error', (err) => {
+        finish({
+            outcome: 'failed',
+            reason: err.code === 'ENOENT'
+                ? 'the docker CLI is not on PATH'
+                : `the docker CLI could not be spawned (${err.code ?? err.message})`,
+        });
+    });
+    child.on('close', (code) => finish({ outcome: 'ran', code: code ?? -1, stdout, stderr }));
+    // A daemon that dies mid-load closes the pipe under us; `close` above already reports that,
+    // so the EPIPE here has nothing to add and must not become an unhandled error event.
+    child.stdin.on('error', () => { });
+    child.stdin.end(opts.stdin);
+});
+function abandonedReason(args) {
+    return `the job was cancelled before \`docker ${args[0] ?? ''}\` answered`;
+}