@mjasnikovs/pi-task 0.38.10 → 0.38.11

package/dist/task/boot-probe.js

@@ -0,0 +1,806 @@
+/**
+ * boot-probe — does the assembled product actually START, and does the page it
+ * serves actually render?
+ *
+ * Lifted out of final-gate.ts, where it was 42% of a 2185-line file and the largest
+ * of seven unrelated concerns. Nothing inside `src/` imported any of it except the
+ * one call site in `runFinalIntegrationGate`; the de-facto module boundary already
+ * existed in the CONSUMERS — seven validation harnesses under `scripts/` import
+ * exactly this surface and nothing else from the gate.
+ *
+ * The public surface is those six names: `discoverBootCommand`, `detectsServedApp`,
+ * `runBootCheck`, `bootSkipVerdict`, `nonLaunchScriptReason` and `BootDeps`. The
+ * listener parsers stay exported because their tests are worth keeping, but they are
+ * now a sibling module's surface rather than noise in the gate's. Everything else —
+ * orphan-port recovery, pgid probing, the HTTP evidence probe, port reservation —
+ * is private, which it could not be while it shared a file with the gate.
+ *
+ * The boot check is deliberately NOT a CLOSURE_SCANS row: it is an async, stateful,
+ * port-binding exercise, and every row would need its own escape hatch. This is a
+ * file move, not a re-shaping.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
+import { outputTail } from './command-run.js';
+import { packageScripts, makeHasTarget } from './launch-manifest.js';
+import { collectProjectEnv, pinnedLocalPort } from './deep-render-check.js';
+/** Leading `FOO=bar` env assignments and `sudo`/`exec` wrappers carry no verb. */
+function commandTokens(member) {
+    const t = member.trim().split(/\s+/).filter(Boolean);
+    while (t.length > 0
+        && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t[0]) || /^(?:sudo|exec|env)$/.test(t[0]))) {
+        t.shift();
+    }
+    return t;
+}
+/** The chain members of a shell script body, in order (`&&`, `||`, `;`, `|`). */
+function chainMembers(body) {
+    return body
+        .split(/&&|\|\||;|\|/)
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+}
+/** Container/infra orchestration: `docker compose … up`, `docker-compose … up -d`,
+ *  `podman-compose … up`, `docker run …`. The verb must be a bare token, so a
+ *  filename like `docker-compose.dev.yml` never counts as one. */
+function isContainerOrchestration(member) {
+    const t = commandTokens(member);
+    if (t.length === 0)
+        return false;
+    const bin = path.posix.basename(t[0]);
+    if (!/^(?:docker|podman|nerdctl)(?:-compose)?$/.test(bin))
+        return false;
+    const verbs = new Set(['up', 'start', 'run']);
+    return t.slice(1).some(tok => verbs.has(tok));
+}
+const MULTIPLEXER_RE = /^(?:concurrently|npm-run-all|run-p|run-s|turbo)$/;
+/** A watcher that recompiles ASSETS and never listens: the tool is a
+ *  bundler/compiler/preprocessor AND it is in watch mode. `bun run --watch x.ts`
+ *  is deliberately NOT here — that re-executes an entrypoint, which may serve. */
+const ASSET_TOOL_RE = /(?:^|[\s/@])(?:tailwindcss|postcss|sass|node-sass|less|stylus|esbuild|rollup|webpack|parcel|swc|babel|tsc|tsup|chokidar)(?:$|[\s"'])/;
+const WATCH_FLAG_RE = /(?:^|\s)(?:--watch|-w|--watch=[^\s]*)(?:\s|$)/;
+/** The quoted commands a multiplexer runs, or its bare script-name arguments
+ *  resolved through the manifest (`run-p dev:css dev:js`). One level only. */
+function multiplexerChildren(member, scripts) {
+    const quoted = [...member.matchAll(/"([^"]+)"|'([^']+)'/g)].map(m => m[1] ?? m[2]);
+    if (quoted.length > 0)
+        return quoted;
+    const t = commandTokens(member)
+        .slice(1)
+        .filter(a => !a.startsWith('-'));
+    return t.flatMap(name => (scripts[name] !== undefined ? [scripts[name]] : []));
+}
+/** Every member of the chain that could plausibly stay up and serve. Members that
+ *  are one-shot setup (`mkdir`, `sleep`, an `until … done` wait loop) are not
+ *  themselves launches, but they are not disqualifying either — only the two
+ *  shapes below are. */
+function isWatcherOnlyMultiplexer(member, scripts) {
+    const t = commandTokens(member);
+    if (t.length === 0)
+        return false;
+    const bin = path.posix.basename(t[0]);
+    const runner = /^(?:npx|bunx|pnpm|yarn|npm)$/.test(bin);
+    const head = runner ?
+        (t.slice(1).find(a => !a.startsWith('-') && a !== 'exec' && a !== 'dlx' && a !== 'run')
+            ?? '')
+        : bin;
+    if (!MULTIPLEXER_RE.test(path.posix.basename(head)))
+        return false;
+    const children = multiplexerChildren(member, scripts);
+    if (children.length === 0)
+        return false;
+    // Every child is an ASSET watcher ⇒ nothing in here ever listens.
+    return children.every(c => ASSET_TOOL_RE.test(c) && WATCH_FLAG_RE.test(c));
+}
+/**
+ * Why this script is NOT a launch of the shipped app, or null when it plausibly
+ * is one (mx5 run 18, validated).
+ *
+ * Run 18's boot command resolved to `bun run dev`, whose body is
+ * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
+ * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
+ * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
+ * the boot SKIPPED as an environment gap — while the shipped app had no HTTP listener
+ * at all. A script whose first act is `docker compose up` cannot distinguish "the app
+ * is broken" from "this box has no docker", so it is not evidence either way: better
+ * to discover NO boot command — reported as "nothing to boot" — and let the static
+ * serve-entry check (serve-entry.ts) carry the signal, than to spend the grace window
+ * producing an unfalsifiable skip.
+ *
+ * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
+ * decidable from the script text alone:
+ *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
+ *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
+ *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
+ *      i.e. nothing in it can ever listen.
+ * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
+ * src/index.ts`, and any multiplexer with one non-asset child — is accepted
+ * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
+ * is exactly what the static serve-entry check is for.
+ */
+export function nonLaunchScriptReason(body, scripts = {}) {
+    const members = chainMembers(body);
+    if (members.length === 0)
+        return null;
+    if (isContainerOrchestration(members[0])) {
+        return 'it opens with container orchestration, which starts infrastructure rather than the app';
+    }
+    if (members.every(m => isWatcherOnlyMultiplexer(m, scripts))) {
+        return 'its only long-running member multiplexes asset watchers, none of which serves';
+    }
+    return null;
+}
+/**
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
+ *
+ * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
+ * `docker compose up` orchestrator) is rejected here and falls through to the
+ * next candidate, then to null. Discovering nothing is strictly better than
+ * discovering something unfalsifiable: an env-gap skip of an orchestration script
+ * says nothing about the app, and null is reported as "nothing to boot".
+ */
+export function discoverBootCommand(cwd) {
+    if (existsSync(path.join(cwd, 'package.json'))) {
+        const s = packageScripts(cwd);
+        for (const name of ['start', 'dev']) {
+            if (s[name] && nonLaunchScriptReason(s[name], s) === null)
+                return ['bun', ['run', name]];
+        }
+        return null;
+    }
+    if (existsSync(path.join(cwd, 'Makefile')) && makeHasTarget(cwd, 'run')) {
+        return ['make', ['run']];
+    }
+    return null;
+}
+/**
+ * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
+ * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
+ * boot command means bootSkipVerdict has no label to name, and a project whose test
+ * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
+ * served app whose only declared launch script cannot start it was not observed to
+ * run, and must say so.
+ */
+export function rejectedLaunchScript(cwd) {
+    if (!existsSync(path.join(cwd, 'package.json')))
+        return null;
+    const s = packageScripts(cwd);
+    for (const name of ['start', 'dev']) {
+        if (!s[name])
+            continue;
+        const reason = nonLaunchScriptReason(s[name], s);
+        if (reason === null)
+            return null; // this one IS a launch — it was chosen
+        return { name, reason };
+    }
+    return null;
+}
+/** Recognise an "address already in use" bind failure across runtimes (Node
+ *  EADDRINUSE, Bun "Is port N in use?", Go "address already in use", generic). */
+function isAddressInUse(text) {
+    return /EADDRINUSE|address already in use|address in use|port \d+ (?:is |already )?in use/i.test(text);
+}
+/** Best-effort port number from a bind-failure message, for the diagnosis line. The
+ *  digit run ends on any non-digit (a `(?!\d)` lookahead, NOT `\b`): runtimes often
+ *  print ":3000" flush against the next token with no separating space/newline
+ *  ("…:3000error: script exited"), where a trailing `\b` would never match. */
+function extractPort(text) {
+    const m = /(?:port|:)\s*(\d{2,5})(?!\d)/i.exec(text) ?? /\baddress[^0-9]*(\d{2,5})(?!\d)/i.exec(text);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return n > 0 && n < 65536 ? n : null;
+}
+/** Stamped on a PASS the boot check could not actually observe, so the trail says
+ *  so out loud instead of implying the listener requirement was met. */
+const UNOBSERVED_LISTENER_NOTE = 'listener check UNOBSERVED: no socket-enumeration tool (ss/netstat/lsof) in this '
+    + 'environment and the app never answered on the port it was given — passed on the '
+    + 'survival rule (the process stayed up), NOT on observed serving';
+/** Package deps that mean "this project stands up an HTTP server" — the deterministic
+ *  proxy for "the plan/spec promised a served app". Bare framework names plus the
+ *  scoped families whose presence implies a listener at runtime. */
+function isServerFrameworkDep(name) {
+    return (/^(?:hono|express|fastify|koa|polka|restify|next|nuxt|http-server|serve|ws|socket\.io)$/.test(name) || /^@(?:hono|fastify|koa|nestjs|sveltejs|remix-run)\//.test(name));
+}
+/** Spec/plan phrasings that promise a listening server, for the text signal. */
+const SERVE_TEXT_RE = /\b(?:https?\s+server|web\s+server|serves?\b|listen(?:s|ing)?\b|Bun\.serve|app\.listen|createServer|serve\s+(?:static|the)|\/api\/|endpoints?\b)/i;
+/**
+ * Does the finished run stand up a listening HTTP server? Deterministic, from the
+ * built manifest (a server-framework dependency is the plan's own artifact) OR, when
+ * available, the plan/spec text. Used to decide whether the boot check must observe a
+ * LISTENER (served app) or may pass on mere survival / quick exit (CLI project).
+ */
+export function detectsServedApp(cwd, planText) {
+    try {
+        const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        const all = { ...(j.dependencies ?? {}), ...(j.devDependencies ?? {}) };
+        if (Object.keys(all).some(isServerFrameworkDep))
+            return true;
+    }
+    catch {
+        // no/unreadable manifest → fall through to the text signal
+    }
+    return planText !== undefined && SERVE_TEXT_RE.test(planText);
+}
+/** `ss -tlnpH` rows → {pid, port}. Column 4 (0-based 3) is the local address; the
+ *  port is its last `:`-suffixed number ("0.0.0.0:3000", "[::]:3000"). */
+export function parseSsListeners(stdout) {
+    const out = [];
+    for (const line of stdout.split('\n')) {
+        const pm = /pid=(\d+)/.exec(line);
+        if (!pm)
+            continue;
+        const local = line.trim().split(/\s+/)[3] ?? '';
+        const portm = /:(\d+)$/.exec(local);
+        if (!portm)
+            continue;
+        out.push({ pid: Number(pm[1]), port: Number(portm[1]) });
+    }
+    return out;
+}
+/**
+ * `netstat -tlnp` rows → {pid, port} (mx5 run 14, validated: the agent-sandbox
+ * image ships NEITHER ss NOR lsof — only ps and netstat — so the served-app boot
+ * check could never observe a listener and failed unfalsifiably). The pid rides
+ * in the trailing "PID/Program name" column ("1234/bun"); rows the kernel will
+ * not attribute to us print "-" there and are skipped.
+ */
+export function parseNetstatListeners(stdout) {
+    const out = [];
+    for (const line of stdout.split('\n')) {
+        if (!/^\s*tcp/i.test(line))
+            continue;
+        const cols = line.trim().split(/\s+/);
+        const local = cols[3] ?? '';
+        const portm = /:(\d+)$/.exec(local);
+        if (!portm)
+            continue;
+        const pidm = /^(\d+)\//.exec(cols[cols.length - 1] ?? '');
+        if (!pidm)
+            continue;
+        out.push({ pid: Number(pidm[1]), port: Number(portm[1]) });
+    }
+    return out;
+}
+/** `lsof -iTCP -sTCP:LISTEN -n -P` rows → {pid, port}. */
+export function parseLsofListeners(stdout) {
+    const out = [];
+    for (const line of stdout.split('\n').slice(1)) {
+        const cols = line.trim().split(/\s+/);
+        const pid = Number(cols[1]);
+        const name = cols.find(c => /:\d+$/.test(c)) ?? '';
+        const portm = /:(\d+)$/.exec(name);
+        if (Number.isInteger(pid) && pid > 0 && portm) {
+            out.push({ pid, port: Number(portm[1]) });
+        }
+    }
+    return out;
+}
+/** The socket-enumeration tools we can attribute listeners with, in preference
+ *  order: ss (richest), netstat (present where ss is not), lsof (BSD/macOS). */
+const LISTENER_TOOLS = [
+    { bin: 'ss', args: ['-tlnpH'], parse: parseSsListeners },
+    { bin: 'netstat', args: ['-tlnp'], parse: parseNetstatListeners },
+    { bin: 'lsof', args: ['-iTCP', '-sTCP:LISTEN', '-n', '-P'], parse: parseLsofListeners }
+];
+/** Listening TCP sockets as {pid, port} pairs (best-effort; ss, then netstat, then
+ *  lsof). Empty on any failure — the caller then cannot attribute a listener to our
+ *  group and the served-app check degrades to survival (never a false FAIL). */
+function listeningSockets() {
+    for (const { bin, args, parse } of LISTENER_TOOLS) {
+        try {
+            const t = spawnSync(bin, args, { encoding: 'utf8', timeout: 4000 });
+            if (t.error || !t.stdout)
+                continue;
+            const rows = parse(t.stdout);
+            if (rows.length > 0)
+                return rows;
+        }
+        catch {
+            // tool missing/unusable — try the next one
+        }
+    }
+    return [];
+}
+/**
+ * Can ANY socket-enumeration tool run here at all? (mx5 run 14: the sandbox had
+ * none, so `groupHasListener` returned false forever and the boot check emitted
+ * "never opened a listening socket" no matter what the app did — an unfalsifiable
+ * FAIL that failed a run whose app demonstrably served.) This is a CAPABILITY
+ * question, deliberately separate from "did we see a listener": a tool that ran
+ * and found nothing is an observation; no tool at all is blindness, and blindness
+ * must degrade to the survival rule exactly like win32 — never a false FAIL on a
+ * platform we cannot probe.
+ *
+ * "Ran" = spawned without ENOENT and either exited 0 or printed something (lsof
+ * exits 1 on an empty match set; a netstat that rejects `-p` prints nothing).
+ * Memoised: the answer is a property of the box, not of the run.
+ */
+let listenerToolCapability = null;
+export function canEnumerateListeners() {
+    if (listenerToolCapability !== null)
+        return listenerToolCapability;
+    listenerToolCapability = LISTENER_TOOLS.some(({ bin, args }) => {
+        try {
+            const r = spawnSync(bin, args, { encoding: 'utf8', timeout: 4000 });
+            if (r.error)
+                return false;
+            return r.status === 0 || (r.stdout ?? '').trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    return listenerToolCapability;
+}
+/**
+ * A free TCP port on the loopback interface, or null if one cannot be reserved.
+ * The boot check hands this to the child as PORT so that a successful HTTP
+ * request to it is OWNERSHIP evidence: nobody else knows the number (mx5 runs
+ * 8/10/11 — orphaned servers from earlier checks answered curl on the
+ * conventional :3000 and passed checks the app had not earned).
+ */
+export function pickFreePort() {
+    return new Promise(resolve => {
+        try {
+            const srv = net.createServer();
+            srv.once('error', () => resolve(null));
+            srv.listen(0, '127.0.0.1', () => {
+                const a = srv.address();
+                const port = typeof a === 'object' && a !== null ? a.port : null;
+                srv.close(() => resolve(port));
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
+export function isPortFree(port) {
+    return new Promise(resolve => {
+        try {
+            const srv = net.createServer();
+            srv.once('error', () => resolve(false));
+            srv.listen(port, '127.0.0.1', () => srv.close(() => resolve(true)));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * The project's own declared local port, but only if nothing is holding it — the
+ * default `preferredPort` for the gate. A declared port that is BUSY falls back to
+ * a reserved one rather than colliding: a stranger's server on :3000 must never be
+ * mistaken for the app we just booted.
+ */
+export async function preferredDeclaredPort(cwd) {
+    const port = pinnedLocalPort(collectProjectEnv(cwd));
+    if (port === null)
+        return null;
+    return (await isPortFree(port)) ? port : null;
+}
+/**
+ * Does anything answer HTTP on 127.0.0.1:`port`? Any response at all (404, 500 —
+ * a status is a listener) counts; only a connection error or timeout is a no.
+ * Runs in a throwaway child of our own runtime so it needs no curl on PATH and
+ * stays synchronous inside the boot poll.
+ */
+function defaultHttpProbe(port) {
+    const script = `fetch('http://127.0.0.1:${port}/').then(()=>process.exit(0),()=>process.exit(1));`
+        + `setTimeout(()=>process.exit(1),2000)`;
+    try {
+        const r = spawnSync(process.execPath, ['-e', script], {
+            encoding: 'utf8',
+            timeout: 5000
+        });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Process-group id of `pid`, or null if it cannot be read. */
+function pgidOf(pid) {
+    try {
+        const r = spawnSync('ps', ['-o', 'pgid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        const n = Number((r.stdout ?? '').trim());
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default listener probe: any LISTENing socket owned by a pid in process group
+ *  `pgid` (the detached boot child IS its own group leader, so pgid === child.pid). */
+function defaultGroupHasListener(pgid) {
+    for (const { pid } of listeningSockets()) {
+        if (pgidOf(pid) === pgid)
+            return true;
+    }
+    return false;
+}
+/** Default port lookup for the render check: the LOWEST port among the group's
+ *  listeners (a dev toolchain may open an HMR socket too; the app's own server
+ *  conventionally sits on the lower, configured port). Null when undeterminable. */
+function defaultGroupListeningPort(pgid) {
+    const ports = listeningSockets()
+        .filter(({ pid }) => pgidOf(pid) === pgid)
+        .map(({ port }) => port);
+    return ports.length > 0 ? Math.min(...ports) : null;
+}
+/** Default port-holder lookup: `lsof` first, then `ss`/`fuser`. Returns null on any
+ *  failure (the diagnosis then omits the pid — never blocks). */
+export function defaultFindPortHolder(port) {
+    try {
+        const t = spawnSync('lsof', ['-i', `:${port}`, '-sTCP:LISTEN', '-t', '-P', '-n'], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        const pid = Number((t.stdout ?? '').split('\n')[0]?.trim());
+        if (!Number.isInteger(pid) || pid <= 0)
+            return null;
+        const ps = spawnSync('ps', ['-o', 'args=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        return { pid, command: (ps.stdout ?? '').trim() || `pid ${pid}` };
+    }
+    catch {
+        return null;
+    }
+}
+function defaultReap(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        setTimeout(() => {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }, 1_000).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Does the port holder look like one of OUR gate children (a `dev`/`start` run of
+ *  the discovered boot command)? Only then do we reap it — never a foreign process
+ *  the user happens to be running. */
+function holderIsOurs(command, boot) {
+    const script = boot[1][boot[1].length - 1] ?? ''; // 'start' | 'dev' | 'run'
+    const c = command.toLowerCase();
+    return ((c.includes('bun') || c.includes('node') || c.includes('npm') || c.includes('make'))
+        && (c.includes(` ${script}`) || c.endsWith(script)));
+}
+/**
+ * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
+ * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
+ * forever without ever listening, and a type-only entrypoint exits 0 in <1s having
+ * served nothing (mx5 run 10 — both were blessed by the survival rule). The boot then
+ * PASSes only once a LISTENing socket owned by our process group is observed; if the
+ * command exits, or the grace window closes, with no listener ever seen → FAIL naming
+ * that a listening server was expected.
+ *
+ * OBSERVABILITY is a precondition of that FAIL (mx5 run 14, validated). The listener
+ * requirement needs pgid-attributed socket enumeration; win32 has none, and neither
+ * does a Linux image shipping no ss/netstat/lsof — run 14's sandbox was exactly that,
+ * so the check emitted "never opened a listening socket" against an app that
+ * demonstrably served, three autofix passes could not falsify it, and the run was
+ * recorded failed. Two defences, in order:
+ *
+ *   - the child is spawned with a freshly reserved, otherwise-unused PORT, and an
+ *     HTTP answer on THAT port proves a listener regardless of tooling. The private
+ *     port is what makes the HTTP probe trustworthy: an orphaned server from an
+ *     earlier check answers on :3000, but nobody else knows this number.
+ *   - if nothing can enumerate listeners AND the assigned port never answered, the
+ *     served-app requirement is unobservable here, so `expectServer` collapses to
+ *     the survival rule and the PASS is stamped UNOBSERVED. An app that ignores PORT
+ *     is indistinguishable from one that never listened — an observer limitation,
+ *     not an app defect, and it may not be reported as one.
+ *
+ * A child that EXITS non-zero still FAILs in every environment: "the process died"
+ * needs no socket probe, so run 14's original true positive (a `--hot` runtime
+ * pinning a crashed app) stays reportable wherever the tooling exists.
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
+ * inside the chain (exit 127, or the runner's own wording where the platform
+ * reports it that way — see isCommandNotFound) → skip.
+ */
+export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
+    const expectServer = (opts.expectServer ?? false) && process.platform !== 'win32';
+    const groupHasListener = opts.deps?.groupHasListener ?? defaultGroupHasListener;
+    const httpProbe = opts.deps?.httpProbe ?? defaultHttpProbe;
+    const canEnumerate = expectServer ? (opts.deps?.enumerationCapable ?? canEnumerateListeners)() : true;
+    // Only served apps get an assigned port: a CLI project has nothing to bind, and
+    // an unexpected PORT in its env is noise.
+    // The app's OWN declared local port wins when it is free (see pinnedLocalPort):
+    // a client whose base URL was baked in at build time calls that origin and no
+    // other, so serving it anywhere else makes the whole authenticated half
+    // unobservable. Anything else — no declaration, a port already held — falls back
+    // to the freshly reserved private port that run 14's ownership evidence needs.
+    const noPreference = () => Promise.resolve(null);
+    const preferred = expectServer ? await (opts.deps?.preferredPort ?? noPreference)() : null;
+    const assignedPort = preferred ?? (expectServer ? await (opts.deps?.pickPort ?? pickFreePort)() : null);
+    // Runner resolution (mx5 run 16): same contract as runGateCommand — resolve
+    // the runner and carry its directory on PATH so the boot script's own chain
+    // can re-invoke it.
+    const runner = resolveRunner(bin);
+    return new Promise(resolve => {
+        const child = spawn(runner.bin, args, {
+            cwd,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: {
+                ...runnerEnv(runner),
+                ...(assignedPort !== null ? { PORT: String(assignedPort) } : {})
+            }
+        });
+        // Best-effort cleanup only: killGroup below can silently fail to reap the
+        // process (platform/sandbox-specific — observed on a GH Actions Linux
+        // runner where the group-kill did not take, hanging the whole `bun test
+        // --isolate` run on the leaked child's piped stdio). unref() so a child
+        // we already tried to kill can never itself keep this process alive.
+        child.unref();
+        let out = '';
+        let err = '';
+        let listenerSeen = false;
+        const cap = (s) => (s.length > 8000 ? s.slice(-8000) : s);
+        child.stdout?.on('data', (d) => (out = cap(out + String(d))));
+        child.stderr?.on('data', (d) => (err = cap(err + String(d))));
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
+            resolve(r);
+        };
+        const killGroup = (sig) => {
+            try {
+                if (!child.pid)
+                    return;
+                if (process.platform === 'win32') {
+                    // Windows has no process groups / negative-pid kill. taskkill
+                    // /T tears down the whole tree (the detached child plus any
+                    // grandchildren it spawned); /F forces it, so the SIGTERM→
+                    // SIGKILL escalation collapses to one idempotent call.
+                    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F']);
+                }
+                else {
+                    process.kill(-child.pid, sig);
+                }
+            }
+            catch {
+                // group already gone
+            }
+        };
+        const passAndKill = (renderNote) => {
+            settle(renderNote ? { outcome: 'pass', renderNote } : { outcome: 'pass' });
+            killGroup('SIGTERM');
+            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        };
+        const failAndKill = (detail) => {
+            settle({ outcome: 'fail', detail });
+            killGroup('SIGTERM');
+            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        };
+        // Served apps only: poll for a listening socket owned by our process group.
+        // As soon as one appears the boot has demonstrably served → run the render
+        // check against the LIVE listener (mx5 runs 8/11: a listener that serves a
+        // permanently blank page passed every curl-shaped check), then PASS/FAIL.
+        // The probe is spawnSync, so the interval cannot re-enter mid-check.
+        // The deep probe is asynchronous (it drives a browser session), so the
+        // interval body must not re-enter while one is in flight — a second session
+        // would race the first for the same still-booting child.
+        let probing = false;
+        const poll = expectServer ?
+            setInterval(() => {
+                if (settled || probing || !child.pid)
+                    return;
+                // pgid attribution first (precise, cheap). If it saw nothing — or
+                // cannot see anything here — fall back to the private assigned
+                // port: an HTTP answer on a number only this child was told is
+                // proof of OUR listener, not of some orphan on :3000.
+                const byGroup = canEnumerate && groupHasListener(child.pid);
+                const byPort = !byGroup && assignedPort !== null && httpProbe(assignedPort);
+                if (!byGroup && !byPort)
+                    return;
+                listenerSeen = true;
+                const probe = opts.deps?.renderProbe;
+                if (!probe)
+                    return passAndKill();
+                const port = byGroup ?
+                    (opts.deps?.groupListeningPort ?? defaultGroupListeningPort)(child.pid)
+                    : assignedPort;
+                if (port === null) {
+                    return passAndKill('render check UNOBSERVED: a listener was seen but its port could not be determined');
+                }
+                const url = `http://127.0.0.1:${port}/`;
+                const rr = probe(url);
+                if (rr.outcome === 'fail') {
+                    return failAndKill(`listens on :${port} but ${rr.detail}`);
+                }
+                const deep = opts.deps?.deepRenderProbe;
+                if (rr.outcome !== 'pass' || !deep) {
+                    return passAndKill(rr.outcome === 'skip' ?
+                        `render check UNOBSERVED: ${rr.note}`
+                        : undefined);
+                }
+                // The page renders. Now sign in and prove the AUTHENTICATED half
+                // is alive (mx5 run 17): the server accepted the login and the
+                // client never used it. Async, so the interval is held off by
+                // `probing` until this settles.
+                probing = true;
+                void Promise.resolve(deep(url)).then(dr => {
+                    if (settled)
+                        return;
+                    if (dr.outcome === 'fail') {
+                        return failAndKill(`listens on :${port} but ${dr.detail}`);
+                    }
+                    passAndKill(dr.outcome === 'skip' ?
+                        `authenticated render check UNOBSERVED: ${dr.note}`
+                        : undefined);
+                }, () => {
+                    // The deep probe may never fail the gate on its own fault.
+                    if (!settled)
+                        passAndKill();
+                });
+            }, 500)
+            : null;
+        const onGrace = () => {
+            // A browser session in flight outlives the grace window by design (it
+            // signs in and waits for the app's data calls). Settling here would kill
+            // the server under it and discard its verdict, so the window re-arms
+            // until the probe resolves — which it always does, on its own hard
+            // timeout (DEEP_RENDER_TIMEOUT_MS).
+            if (probing) {
+                timer = setTimeout(onGrace, 500);
+                return;
+            }
+            if (expectServer && !listenerSeen) {
+                // Blind here (no enumeration tool, and the assigned port never
+                // answered) ⇒ we cannot tell "never listened" from "ignores PORT".
+                // Survival rule, stamped UNOBSERVED — an observer limitation is not
+                // an app defect (mx5 run 14).
+                if (!canEnumerate)
+                    return passAndKill(UNOBSERVED_LISTENER_NOTE);
+                settle({
+                    outcome: 'fail',
+                    detail: `still running after ${graceMs}ms but never opened a listening socket — the spec/dependencies promise an HTTP server`
+                });
+                killGroup('SIGTERM');
+                setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+                return;
+            }
+            passAndKill();
+        };
+        let timer = setTimeout(onGrace, graceMs);
+        child.on('error', () => settle({ outcome: 'skip', spawnFailed: true }));
+        child.on('exit', (status, signal) => {
+            if (status === 0) {
+                if (expectServer && !listenerSeen) {
+                    if (!canEnumerate) {
+                        return settle({ outcome: 'pass', renderNote: UNOBSERVED_LISTENER_NOTE });
+                    }
+                    return settle({
+                        outcome: 'fail',
+                        detail: 'exited 0 without ever opening a listening socket — the spec/dependencies '
+                            + 'promise an HTTP server, so a boot that serves nothing is not a launch'
+                    });
+                }
+                return settle({ outcome: 'pass' });
+            }
+            // Command-not-found inside the boot chain — 127 on a posix shell, or
+            // the runner's own wording where it isn't (Windows bun exits 1). Either
+            // way the boot never RAN, so it is an environment gap, not an app fault.
+            if (isCommandNotFound(status, `${out}\n${err}`)
+                || (status === null && signal === null)) {
+                return settle({ outcome: 'skip' });
+            }
+            const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
+            const tail = outputTail(out, err);
+            // A bind collision is an environment condition, not an app defect — hand
+            // it back distinctly so the gate can reap our own orphan and retry rather
+            // than reporting the app "crashed" (mx5 run 9 item 3).
+            if (isAddressInUse(`${out}\n${err}`)) {
+                settle({
+                    outcome: 'orphan-port',
+                    port: extractPort(`${out}\n${err}`),
+                    detail: `${what}${tail ? ` — ${tail}` : ''}`
+                });
+                return;
+            }
+            settle({ outcome: 'fail', detail: `${what}${tail ? ` — ${tail}` : ''}` });
+        });
+    });
+}
+/**
+ * The SAME third verdict, at the door unobservedVerdict cannot reach: the boot
+ * check specifically (mx5 run 18, validated).
+ *
+ * Run 18 shipped an app with no HTTP server behind a converged final gate. Its
+ * `src/server/index.ts` ends at `export {app}` — no `Bun.serve`, no
+ * `export default app`, no `start` script — so `bun run src/server/index.ts` exits
+ * 0 immediately and the product cannot be started at all. The gate's boot command
+ * resolved to `bun run dev`, whose body begins `docker compose … up -d`; the gate
+ * sandbox had no docker, so the boot SKIPPED as an environment gap. Skips
+ * contribute nothing to `dynObserved`, and `bun run test`, `test:ct`, `build`,
+ * `lint`, `seed` and `migrate` all ran — so `dynObserved > 0`, the full-skip
+ * blindness guard (observabilityGapFailure) stayed correctly quiet, and the trail
+ * read `final-gate: autofix converged — statics + … passed` with 24/24 tasks green.
+ *
+ * The defect is that "the app was never observed to boot" and "the app booted
+ * fine" produced BYTE-IDENTICAL gate output. That is the class scripts/ab-verdict.ts
+ * exists to kill one layer up: absence of evidence rendered in the shape of
+ * evidence. So a discovered-but-skipped boot now names itself, and — unlike every
+ * other skip — it CANNOT be cancelled by observations from other commands.
+ * Component tests are the trap here, not the alibi: run 18 had 51 green Playwright
+ * CT tests, and CT mounts components in a browser without ever assembling or
+ * starting the server.
+ *
+ * DECIDED, do not silently re-open:
+ *  - NOT a FAIL. A boot skip on a docker-less box is a genuine environment gap, and
+ *    failing it re-creates run 16's unfalsifiable-FAIL mistake pointing the other
+ *    way. UNOBSERVED blocks nothing while being loud and durable (the caller records
+ *    it as final-gate debt the next run re-surfaces), and it keeps "boot never ran"
+ *    out of the autofix child's seed — a child cannot fix a missing docker, so the
+ *    highest-probability response would be to FABRICATE a bootable command, the
+ *    class that refuted the `## verified tooling` harvest.
+ *  - BOTH skip flavours count. Run 18's skip carried `spawnFailed: false` (127 inside
+ *    the script chain, not an ENOENT on the runner), so keying off spawnFailed would
+ *    have missed the actual defect.
+ *  - SERVED APPS ONLY. `expectServer === false` (a CLI/library project) is fenced off
+ *    deliberately: a CLI whose `dev` script needs an absent tool has no server to be
+ *    unobserved, and widening the lever there buys warnings nobody can act on.
+ */
+export function bootSkipVerdict(args) {
+    if (args.label === null || !args.skipped || !args.expectServer)
+        return null;
+    // Deliberately short: the run-level trail slices the reason at 300 chars and this
+    // note leads it, so the command name always survives.
+    return (`boot check: \`${args.label}\` NEVER RAN (environment gap) — the app was not observed `
+        + 'to start, and no test suite substitutes for that.');
+}
+/**
+ * Boot check hit an address-in-use bind failure. If the port is held by one of OUR
+ * own orphaned gate children (a `dev`/`start` run), reap it and retry the boot once
+ * so the app gets a fair launch; otherwise leave the (foreign) holder alone and let
+ * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
+ * to ourselves.
+ */
+export async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, expectServer) {
+    if (first.port === null)
+        return first;
+    const holder = (deps.findPortHolder ?? defaultFindPortHolder)(first.port);
+    if (!holder || !holderIsOurs(holder.command, boot))
+        return first;
+    const reaped = (deps.reap ?? defaultReap)(holder.pid);
+    if (!reaped)
+        return first;
+    // Give the OS a moment to release the socket, then re-run the boot once.
+    await new Promise(r => setTimeout(r, 1_500));
+    return runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps });
+}