@a11ign/screenreader-fleet 0.0.0-reserved.0 → 0.1.0

package/dist/check-worker-code.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// @ts-check
+// Is every worker running the code in this checkout?
+//
+//   npm run worker:code
+//
+// Deploying is push-then-restart and both halves fail silently: `utmctl exec` reports success
+// whether or not it ran, so a worker can serve the previous process indefinitely. Reading the
+// guest's file hash does not help, because that read goes through exec too -- when exec is
+// dead the check returns empty rather than mismatched, which reads as a flaky tool instead of a
+// failed deploy. That cost an hour, and the stale workers looked exactly like a logic bug.
+//
+// This asks each worker over HTTP, which is reachable exactly when the worker is usable and
+// involves no guest agent. Exit 0 when every worker matches, 1 otherwise.
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
+import { sandboxGitEnv } from "./git-safe-env.mjs";
+// The WORKING-TREE value, imported rather than regex-scraped — architecture-audit.md §5, item 3.
+// `protocol-version.mjs` is dependency-free for exactly this: safe to import from a portable tree.
+import { CAPTURE_PROTOCOL_VERSION as PROTOCOL_IN_TREE } from "@a11ign/screenreader-worker/protocol-version";
+import { workerSourceDir } from "@a11ign/screenreader-worker/code-version";
+import { fleetScriptPaths } from "./fleet-scripts.mjs";
+import { configuredWorkers, inventoryWorkerUrls, resolveWorkerPool } from "./fleet-env.mjs";
+// The comparison, the remedy and the expected hash live in ONE place, because the capture entry points ask
+// the same question before every run and a second copy of "is this worker stale" is a second answer.
+import { expectedWorkerCode, codeDrift, remedyLines } from "./worker-code-check.mjs";
+import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { errorText } from "@a11ign/screenreader-worker/error-text";
+import { requestJson } from "./worker-http.mjs";
+/**
+ * takes NO flags — it asks every worker what code it is running and compares. Any flag passed to it
+ * today is discarded in silence.
+ *
+ * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
+ */
+refuseUnknownFlags([], { entry: import.meta.url, command: "npm run worker:code" });
+// Resolved from THIS module: the fleet scripts ship with this package, so a cwd-relative path was only ever
+// right when run from the repo root.
+const CTL = fleetScriptPaths().workerCtl;
+// /health now reports installed runtime versions as well as the code hash. The first
+// request after a Windows boot may need PowerShell file-version discovery, so four seconds
+// was too tight and made a healthy worker look unreachable.
+const HEALTH_TIMEOUT_MS = 15000;
+// The guest and the host now call the SAME function over the SAME list, so they cannot disagree by
+// construction. This used to be two copies of one loop kept in step by a comment.
+/**
+ * A STALE report is usually a real stale guest — but not when the working tree carries an uncommitted
+ * CAPTURE_PROTOCOL_VERSION bump. Then every worker reports stale because the LOCAL hash moved, and the
+ * obvious remedy (redeploy) would ship the bump and invalidate every cached capture.
+ *
+ * Saying so here costs one line and saves someone an unexplained full recapture.
+ */
+function protocolBumpNote() {
+    try {
+        const inTree = String(PROTOCOL_IN_TREE);
+        const committed = /CAPTURE_PROTOCOL_VERSION = (\d+)/.exec(execFileSync("git", ["-C", workerSourceDir(), "show", "HEAD:./protocol-version.mjs"], { encoding: "utf8", env: sandboxGitEnv() }))?.[1];
+        if (inTree && committed && inTree !== committed) {
+            return `\nNOTE: your working tree has CAPTURE_PROTOCOL_VERSION = ${inTree} but HEAD has ${committed}.\n` +
+                "That alone changes the local hash, so the guests may not be stale at all. Deploying it would\n" +
+                "invalidate every cached capture — `npm run worker:deploy` refuses unless you pass\n" +
+                "--allow-protocol-change.\n";
+        }
+    }
+    catch { /* not a git checkout; nothing to add */ }
+    return "";
+}
+/**
+ * Which workers to ask, AND WHERE THAT LIST CAME FROM — the second half is not decoration.
+ *
+ * This used to answer the local UTM pool or nothing, and print "no worker is running — nothing to compare"
+ * when it found neither. Measured 2026-08-28 with five bare-metal workers serving `/health` and all five
+ * STALE against this checkout: the bare command reported nothing to compare, and the same command with
+ * `A11Y_WORKERS` set reported `5 stale worker(s)`. One env var apart, and the quiet answer was the wrong one.
+ *
+ * That is `lab:inventory`'s lesson at a different layer — *"'none here' and 'none anywhere' are different
+ * answers, and it now refuses to turn the first into the second"* — and it lands harder here, because this
+ * command exists to stop a corpus being captured on the wrong code. A false clean from it is the failure it
+ * was written to prevent, delivered by the tool itself.
+ *
+ * The inventory was already imported and already read, twelve lines below, to print the REMEDY. So the
+ * command could name the five workers it should have checked while insisting it had none to check.
+ *
+ * Reading it here is safe in a way it would not be for a capture run: this probes `/health` and starts
+ * nothing, so the rule that naming workers means you are managing them does not apply.
+ */
+export function workerUrls({ named = configuredWorkers, local = localPoolUrls, inventory = inventoryWorkerUrls, } = {}) {
+    // ONE PRECEDENCE, in fleet-env.mjs. This function held its own -- named, then the LOCAL UTM POOL, then
+    // the inventory -- while `doctor` went named then inventory, so on any Mac with a registered guest the
+    // two commands described different fleets. That is the divergence the comment here used to claim it had
+    // closed; it closed the NAMED half only.
+    return resolveWorkerPool({ named, inventory, local });
+}
+/** The local UTM pool, or none — `utmctl` is absent on a machine that never had one. */
+function localPoolUrls() {
+    try {
+        const pool = JSON.parse(execFileSync(CTL, ["pool"], { encoding: "utf8" }));
+        return pool.filter((/** @type {{ip?: string}} */ vm) => vm.ip)
+            .map((/** @type {{ip: string, port: number}} */ vm) => `http://${vm.ip}:${vm.port}`);
+    }
+    catch (e) {
+        // Never silent: "there is no UTM here" and "utmctl failed" are different, and the second is the one
+        // that would otherwise send somebody to the inventory believing the local pool was empty.
+        if (process.env.A11Y_DEBUG)
+            console.log(`  (local pool unavailable: ${errorText(e)})`);
+        return [];
+    }
+}
+/** @param {string} url */
+async function versionOf(url) {
+    // `requestJson`, not `fetch`: gains a real error CODE (`ECONNREFUSED`, `EHOSTUNREACH`) for the per-worker
+    // `errorText(e)` line below, in place of fetch's undifferentiated `TypeError: fetch failed`.
+    const response = await requestJson(`${url.replace(/\/$/, "")}/health`, { timeoutMs: HEALTH_TIMEOUT_MS });
+    // `requestJson` returns `undefined` for unparseable JSON rather than throwing (its own docstring: a cache
+    // miss is a normal outcome for its usual callers) -- `fetch`'s `.json()` threw, and the caller here relies
+    // on that to report "unreachable" for a worker that answered garbage. Restored explicitly.
+    if (response.json === undefined)
+        throw new Error(`invalid JSON from ${url}`);
+    return response.json.code ?? "absent";
+}
+/**
+ * Nothing here runs on import, for the same reason as `deploy-worker.mjs`: a module that probes every worker
+ * over HTTP should be invoked, not merely mentioned. It also lets `code-version.test.ts` import this rather
+ * than parse its source as text.
+ */
+async function main() {
+    const expected = expectedWorkerCode();
+    const { urls, source } = workerUrls();
+    console.log(`this checkout: ${expected}`);
+    if (!urls.length) {
+        console.log("no worker configured, running locally, or listed in inventory.yml — nothing to compare");
+        process.exit(0);
+    }
+    // Say which list this is. A reading of "all current" means nothing until you know whether it examined
+    // the fleet you are about to capture on or the empty pool on your laptop.
+    console.log(`checking ${urls.length} worker(s) from ${source}`);
+    // Read first, CLASSIFY second, and the classifier is the one the capture preflight uses. This loop used
+    // to decide staleness itself with `actual === expected` — the same judgement in a second place, which is
+    // exactly what `worker-code-check.mjs` exists to stop. `versionOf` stays only because the CLI reports the
+    // network error text per worker, which a preflight has no use for.
+    const readings = [];
+    for (const url of urls) {
+        try {
+            // "absent" means the worker predates /health.code, which is itself a stale deploy.
+            readings.push({ worker: url, code: await versionOf(url) });
+        }
+        catch (e) {
+            console.log(`  ${url}  unreachable (${errorText(e)})`);
+            readings.push({ worker: url, code: null });
+        }
+    }
+    const { stale } = codeDrift(expected, readings);
+    const staleUrls = stale.map((s) => s.worker);
+    const isStale = new Set(staleUrls);
+    for (const { worker, code } of readings.filter((r) => r.code !== null)) {
+        console.log(`  ${worker}  ${code}  ${isStale.has(worker) ? "STALE — redeploy and REBOOT the guest" : "matches"}`);
+    }
+    if (staleUrls.length) {
+        for (const line of remedyLines(staleUrls, inventoryWorkerUrls()))
+            console.log(line);
+        const note = protocolBumpNote();
+        if (note)
+            console.log(note);
+    }
+    process.exit(staleUrls.length ? 1 : 0);
+}
+// REALPATH'D: `import.meta.url` is resolved through symlinks by Node's ESM loader and `process.argv[1]`
+// is not, so a bin reached via its `.bin` symlink (which is how npm always installs one) mismatched here
+// and this guard silently read false — the tool loaded, did nothing, and exited 0. `/var` and `/tmp` are
+// themselves symlinks on macOS, so this fired every time. Same defect, same fix, as `cli.ts`'s `isProgram`.
+if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href)
+    await main();
+//# sourceMappingURL=check-worker-code.mjs.map

package/dist/check-worker-code.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-worker-code.mjs","sourceRoot":"","sources":["../src/check-worker-code.mjs"],"names":[],"mappings":"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"}

package/dist/cli-flags.d.mts

@@ -0,0 +1,71 @@
+/**
+ * The flag name alone: `--shard=0/4` and `--shard` both name `--shard`.
+ * @param {string} argument @returns {string}
+ */
+export function nameOf(argument: string): string;
+/**
+ * `--name=value`'s value, or `undefined` if `--name=` was never passed. audit §9's "argv parsing" row:
+ * VALIDATION is owned here (`refuseUnknownFlags`), but 15+ files each hand-rolled this exact three-line
+ * idiom for EXTRACTION, and one of them had already drifted from the rest.
+ *
+ * MEASURED before writing this, across all fifteen, against five vectors (a normal value, a missing flag,
+ * an empty value, a repeated flag, and a value containing its own `=`): fourteen agreed on all five —
+ * `argv.find((a) => a.startsWith("--name=")).slice("--name=".length)`, verbatim or with `name` templated
+ * in. `fleet-discover.mjs`'s `arg()` used `.split("=")[1]` instead, which is identical on four vectors and
+ * silently WRONG on the fifth: `--url=http://host?a=b` came back as `"http://host?a"`, truncated at the
+ * value's own `=`. Dormant today — that helper is only ever asked for `--cidr=` and `--port=`, neither of
+ * which can contain one — but a live discrepancy the day it is asked for a URL or a `key=value` pair.
+ *
+ * Kept as `.slice`, matching the fourteen rather than the one, and `fleet-discover.mjs` converted to it.
+ *
+ * @param {readonly string[]} argv @param {string} name
+ * @returns {string | undefined}
+ */
+export function flagValue(argv: readonly string[], name: string): string | undefined;
+/**
+ * Which of `argv` are flags this command does not know. PURE, so it is testable without a process.
+ *
+ * A bare `--` is npm's separator and never a flag. Anything not starting with `-` is positional — a URL,
+ * a worker address, a page path — and is not this guard's business.
+ *
+ * SINGLE-DASH FLAGS ARE INSPECTED TOO, AND THE OMISSION COST A 14-MINUTE FLEET OPERATION.
+ *
+ * This read `startsWith("--")`, on the reasoning that only long flags are ever this repo's own. But an
+ * ANSIBLE-shaped argument is single-dash, and several of these commands wrap `ansible-playbook` — so
+ * `npm run fleet:provision -- -e worker_edge_allow_downgrade=true` passed straight through the guard,
+ * was never forwarded by the wrapper, and the whole fleet was provisioned WITHOUT the authorisation the
+ * operator believed they had given. Measured 2026-09-05. The role then refused, correctly, with a message
+ * telling the operator to pass the very flag they had just passed.
+ *
+ * That is precisely the defect this file exists to prevent — "an ignored flag runs the default and reports
+ * success" — surviving inside its own remedy, because the remedy was written to match one flag SHAPE
+ * rather than the idea of a flag. `-e` is not a URL and not a page path; nothing positional here begins
+ * with a dash followed by a letter, which is what makes this safe to refuse rather than merely warn on.
+ */
+/**
+ * @param {string[]} argv @param {string[]} known @returns {string[]}
+ */
+export function unknownFlags(argv: string[], known: string[]): string[];
+/**
+ * The closest known flag, when there is one close enough to be a likely typo rather than a guess.
+ * @param {string} flag @param {string[]} known @returns {string | undefined}
+ */
+export function didYouMean(flag: string, known: string[]): string | undefined;
+/**
+ * Refuse, naming the flag and what this command does take. Exits 2; does not return on failure.
+ *
+ * `command` names the thing a human typed — the npm script, not the file — because that is what they will
+ * retype. Defaults to the script's basename, which is right for the ones invoked directly.
+ */
+/**
+ * @param {string[]} known  Every flag this command reads, `--name` or `--name=`.
+ * @param {{entry: string, argv?: string[], command?: string}} options
+ *   `entry` is the caller's `import.meta.url`, and it is REQUIRED. `command` names the thing a HUMAN
+ *   typed — the npm script, not the file — because that is what they will retype.
+ */
+export function refuseUnknownFlags(known: string[], { entry, argv, command }: {
+    entry: string;
+    argv?: string[];
+    command?: string;
+}): void;
+//# sourceMappingURL=cli-flags.d.mts.map

package/dist/cli-flags.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-flags.d.mts","sourceRoot":"","sources":["../src/cli-flags.mjs"],"names":[],"mappings":"AAgDA;;;GAGG;AACH,iCAFW,MAAM,GAAqB,MAAM,CAK3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,gCAHW,SAAS,MAAM,EAAE,QAAe,MAAM,GACpC,MAAM,GAAG,SAAS,CAM9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;GAEG;AACH,mCAFW,MAAM,EAAE,SAAe,MAAM,EAAE,GAAkB,MAAM,EAAE,CAQnE;AAED;;;GAGG;AACH,iCAFW,MAAM,SAAe,MAAM,EAAE,GAAkB,MAAM,GAAG,SAAS,CAO3E;AAED;;;;;GAKG;AACH;;;;;GAKG;AAMH,0CAVW,MAAM,EAAE,4BACR;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,QA+E5D"}

package/dist/cli-flags.mjs

@@ -0,0 +1,207 @@
+// @ts-check
+/**
+ * Refuse a flag this command does not read.
+ *
+ * Every CLI here parses argv the same way — `process.argv.find((a) => a.startsWith("--only="))` or
+ * `process.argv.includes("--resume")` — and every one of them therefore IGNORES anything it does not
+ * recognise. A mistyped, renamed or hallucinated flag runs the default and reports success, and the
+ * operator believes their value was applied. That is the same defect as an Ansible extra var a job does
+ * not read, one layer out, and this repo has paid for it twice:
+ *
+ *   - a blocker's own message told the reader to run `--write-baseline`; the flag is `--update-baseline`
+ *   - `--only=route-title-stale` covered 1 of the 7 cases in that family, because the match was exact-id
+ *
+ * Neither produced an error. Both produced a plausible wrong answer, which this file's governing rule
+ * says to replace with a refusal that names the cause.
+ *
+ * ## Why the known list is passed in rather than read from the caller's source
+ *
+ * Deriving it at runtime — reading the calling module and regexing out its `--flags` — needs no
+ * maintenance, and is wrong for one reason that matters: a CLI whose flags are consumed by a HELPER in
+ * another module would refuse them, so the guard would break exactly the commands with the most moving
+ * parts. The list is explicit here and `cli-flags.test.ts` derives the same set from source and pins the
+ * two equal, which is this repo's remedy when a duplication is forced.
+ */
+import { basename } from "node:path";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/** How far apart two flags may be and still be worth suggesting. One typo, or one word. */
+const NEAR = 4;
+/**
+ * Levenshtein, small and iterative — the inputs are flag names, never long strings.
+ * @param {string} a @param {string} b @returns {number}
+ */
+function distance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_unused, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            row[j] = Math.min(row[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = row;
+    }
+    return previous[b.length];
+}
+/**
+ * The flag name alone: `--shard=0/4` and `--shard` both name `--shard`.
+ * @param {string} argument @returns {string}
+ */
+export function nameOf(argument) {
+    const equals = argument.indexOf("=");
+    return equals === -1 ? argument : argument.slice(0, equals);
+}
+/**
+ * `--name=value`'s value, or `undefined` if `--name=` was never passed. audit §9's "argv parsing" row:
+ * VALIDATION is owned here (`refuseUnknownFlags`), but 15+ files each hand-rolled this exact three-line
+ * idiom for EXTRACTION, and one of them had already drifted from the rest.
+ *
+ * MEASURED before writing this, across all fifteen, against five vectors (a normal value, a missing flag,
+ * an empty value, a repeated flag, and a value containing its own `=`): fourteen agreed on all five —
+ * `argv.find((a) => a.startsWith("--name=")).slice("--name=".length)`, verbatim or with `name` templated
+ * in. `fleet-discover.mjs`'s `arg()` used `.split("=")[1]` instead, which is identical on four vectors and
+ * silently WRONG on the fifth: `--url=http://host?a=b` came back as `"http://host?a"`, truncated at the
+ * value's own `=`. Dormant today — that helper is only ever asked for `--cidr=` and `--port=`, neither of
+ * which can contain one — but a live discrepancy the day it is asked for a URL or a `key=value` pair.
+ *
+ * Kept as `.slice`, matching the fourteen rather than the one, and `fleet-discover.mjs` converted to it.
+ *
+ * @param {readonly string[]} argv @param {string} name
+ * @returns {string | undefined}
+ */
+export function flagValue(argv, name) {
+    const prefix = `--${name}=`;
+    const hit = argv.find((a) => a.startsWith(prefix));
+    return hit === undefined ? undefined : hit.slice(prefix.length);
+}
+/**
+ * Which of `argv` are flags this command does not know. PURE, so it is testable without a process.
+ *
+ * A bare `--` is npm's separator and never a flag. Anything not starting with `-` is positional — a URL,
+ * a worker address, a page path — and is not this guard's business.
+ *
+ * SINGLE-DASH FLAGS ARE INSPECTED TOO, AND THE OMISSION COST A 14-MINUTE FLEET OPERATION.
+ *
+ * This read `startsWith("--")`, on the reasoning that only long flags are ever this repo's own. But an
+ * ANSIBLE-shaped argument is single-dash, and several of these commands wrap `ansible-playbook` — so
+ * `npm run fleet:provision -- -e worker_edge_allow_downgrade=true` passed straight through the guard,
+ * was never forwarded by the wrapper, and the whole fleet was provisioned WITHOUT the authorisation the
+ * operator believed they had given. Measured 2026-09-05. The role then refused, correctly, with a message
+ * telling the operator to pass the very flag they had just passed.
+ *
+ * That is precisely the defect this file exists to prevent — "an ignored flag runs the default and reports
+ * success" — surviving inside its own remedy, because the remedy was written to match one flag SHAPE
+ * rather than the idea of a flag. `-e` is not a URL and not a page path; nothing positional here begins
+ * with a dash followed by a letter, which is what makes this safe to refuse rather than merely warn on.
+ */
+/**
+ * @param {string[]} argv @param {string[]} known @returns {string[]}
+ */
+export function unknownFlags(argv, known) {
+    const accepted = new Set(known.map(nameOf));
+    return argv
+        .filter((argument) => argument !== "--" && (argument.startsWith("--") || /^-[A-Za-z]/.test(argument)))
+        .map(nameOf)
+        .filter((flag) => !accepted.has(flag));
+}
+/**
+ * The closest known flag, when there is one close enough to be a likely typo rather than a guess.
+ * @param {string} flag @param {string[]} known @returns {string | undefined}
+ */
+export function didYouMean(flag, known) {
+    const ranked = known.map(nameOf)
+        .map((candidate) => ({ candidate, gap: distance(flag, candidate) }))
+        .sort((left, right) => left.gap - right.gap);
+    return ranked[0] && ranked[0].gap <= NEAR ? ranked[0].candidate : undefined;
+}
+/**
+ * Refuse, naming the flag and what this command does take. Exits 2; does not return on failure.
+ *
+ * `command` names the thing a human typed — the npm script, not the file — because that is what they will
+ * retype. Defaults to the script's basename, which is right for the ones invoked directly.
+ */
+/**
+ * @param {string[]} known  Every flag this command reads, `--name` or `--name=`.
+ * @param {{entry: string, argv?: string[], command?: string}} options
+ *   `entry` is the caller's `import.meta.url`, and it is REQUIRED. `command` names the thing a HUMAN
+ *   typed — the npm script, not the file — because that is what they will retype.
+ */
+// NO `= {}` DEFAULT, because `entry` is required and the docstring above has always said so. A default
+// that lets the whole options object be omitted contradicts that: it produces `entry === undefined`, and
+// the guard below decides whether THIS module is the command by comparing `entry` against argv[1] -- so a
+// caller who forgot it would get a guard that silently never fires. Types found the contradiction the
+// moment this file entered the program. Every one of the 60 real call sites passes it.
+export function refuseUnknownFlags(known, { entry, argv = process.argv.slice(2), command }) {
+    // ONLY WHEN THIS MODULE IS THE COMMAND, never when it is imported.
+    //
+    // These calls sit at module top level, so they run on IMPORT — and then inspect the IMPORTING process's
+    // argv. Measured 2026-08-27, an hour after the guards went in: `capture-real-pages --role=calibration`
+    // imports `fleet-env.mjs`, whose guard woke up, saw `--role`, decided it did not know it, and killed a
+    // 50-page capture with "unknown flag --role — did you mean --list?". The guard was right about its own
+    // flags and asking the wrong process.
+    //
+    // `entry` is REQUIRED rather than defaulted, for the reason `createHostThrottle`'s `minGapMs` is: a
+    // default here would silently restore exactly this behaviour for any caller who forgot it, and the
+    // failure mode is a guard that fires on somebody else's command line.
+    if (!entry) {
+        throw new TypeError("refuseUnknownFlags needs { entry: import.meta.url } — without it the guard runs "
+            + "on import and inspects the importing process's flags");
+    }
+    // REALPATH'D, and without it this guard silently does not fire through a symlink — #237.
+    //
+    // An entry guard in the realpath'd form reads
+    // `import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href`, and
+    // this comparison had no `realpathSync`. So when `argv[1]` reaches such a script through a symlink — npm's
+    // own `.bin` links are symlinks, which is why those call sites resolve — the OUTER condition is true and
+    // this one is FALSE. `main()` runs; the flag guard returns early and inspects nothing.
+    //
+    // NOT EVERY CALL SITE HAS THAT FORM (#1248). Some still compare the plain, symlink-blind
+    // `pathToFileURL(process.argv[1] ?? "")`, which fails the other way through a symlink: the OUTER condition is
+    // false, `main()` never runs, and the tool exits 0. Which files still do is `KNOWN_PLAIN_ENTRY_GUARDS` in
+    // `entry-points.test.ts` (#1086), a ratchet that may shrink and may not grow. It is the list of record, so no
+    // count is repeated here.
+    //
+    // Measured on `piped-exit-status-guard.mjs`, same file, same flag:
+    //
+    //   node scripts/tmp-symlink-probe.mjs --bogus 'echo hi'   -> ran, exit 0, flag IGNORED
+    //   node packages/guards/src/piped-exit-status-guard.mjs --bogus '...'  -> refused, exit 2
+    //
+    // Through the symlink the mistyped flag is ignored and the command reports success — which is the
+    // sentence this refusal itself prints as the reason it exists.
+    //
+    // It is a remedy whose TRIGGER is narrower than the thing it guards, the `refreshBrowseBuffer` shape:
+    // reachable from the right path, with a condition that could not be true there. And the census
+    // (`cli-flags.test.ts`) cannot see it, because it asserts a file CONTAINS `refuseUnknownFlags(` — it
+    // cannot ask whether that call can FIRE, so every guarded CLI reads GUARDED either way.
+    //
+    // `realpathSync` THROWS on a path that does not exist, and `process.argv[1]` is absent for `node -e`
+    // and `node --eval`. Absent stays absent rather than becoming a throw: the guard must be inert when
+    // there is no script, never fatal.
+    /** The invoking script's REAL path as a URL, so a symlinked `argv[1]` still matches `entry`. */
+    let invoked;
+    try {
+        invoked = process.argv[1] ? pathToFileURL(realpathSync(process.argv[1])).href : "";
+    }
+    catch {
+        invoked = pathToFileURL(process.argv[1] ?? "").href; // unresolvable: compare what we were given
+    }
+    if (entry !== invoked)
+        return;
+    const unknown = unknownFlags(argv, known);
+    if (unknown.length === 0)
+        return;
+    const name = command ?? basename(process.argv[1] ?? "this command");
+    for (const flag of unknown) {
+        const near = didYouMean(flag, known);
+        console.error(`  ${name}: unknown flag ${flag}${near ? ` — did you mean ${near}?` : ""}`);
+    }
+    // "It takes: " with nothing after it is what a command taking NO flags printed, and that reads like the
+    // guard failed to find its own list rather than like an answer. First hit by `release:provenance`, the
+    // first zero-flag CLI here -- the branch existed for months with no caller to exercise it.
+    const accepted = [...known].map(nameOf).sort();
+    console.error(accepted.length === 0
+        ? "  It takes no flags at all."
+        : `  It takes: ${accepted.join(" ")}`);
+    console.error("  Refusing rather than ignoring it: an ignored flag runs the default and reports success.");
+    process.exit(2);
+}
+//# sourceMappingURL=cli-flags.mjs.map

package/dist/cli-flags.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-flags.mjs","sourceRoot":"","sources":["../src/cli-flags.mjs"],"names":[],"mappings":"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"}

package/dist/code-drift.d.mts

@@ -0,0 +1,140 @@
+/**
+ * Split a set of `/health.code` readings into stale and unreachable. PURE.
+ *
+ * `null` is UNREACHABLE and is not a finding, matching `assertOneBrowserAcross`: a box that is asleep
+ * contributes no evidence and no mismatch, and treating silence as a fault is how a check earns a
+ * reputation for crying wolf. `"absent"` IS a finding — a worker predating `/health.code` is itself a
+ * stale deploy.
+ *
+ * `answered` is returned rather than left to be inferred from the two lists, because "nothing was wrong"
+ * and "nothing was examined" produce the SAME empty `stale` — and a caller with only the lists cannot
+ * distinguish 3 clean workers from 3 silent ones. Every number carrying what it was computed from is this
+ * file's parent rule; this is the one number that was missing.
+ *
+ * @param {string} expected
+ * @param {Array<{worker: string, code: string|null|undefined}>} readings
+ * @returns {{expected: string, stale: Array<{worker: string, serving: string}>, unreachable: string[],
+ *            answered: number}}
+ */
+export function codeDrift(expected: string, readings: Array<{
+    worker: string;
+    code: string | null | undefined;
+}>): {
+    expected: string;
+    stale: Array<{
+        worker: string;
+        serving: string;
+    }>;
+    unreachable: string[];
+    answered: number;
+};
+/**
+ * Name the deploy route that can actually reach these workers.
+ *
+ * There are two, they share no mechanism, and the wrong one wastes real time. `worker:deploy` is
+ * `utmctl file push` plus a `utmctl` reboot: it takes a VM UUID and fails immediately off macOS, so it
+ * cannot touch a physical box. Bare-metal workers are git-cloned and deploy by PULLING, through Ansible.
+ *
+ * This printed the utmctl advice unconditionally, including to a fleet of four mini PCs where none of it
+ * applies — a tool confidently prescribing a remedy for a different kind of machine. Which kind a worker is
+ * is not a guess: `inventory.yml` is the single source of truth for the bare-metal fleet (ADR 0012).
+ *
+ * PURE, and the bare-metal list is a parameter rather than a read, because a remedy that only appears when
+ * something is already broken is one nobody sees until it matters. This repo has shipped an inert remedy
+ * before (`refreshBrowseBuffer`, whose trigger was never set) and confirmed it by results it had no part in
+ * producing. Returning lines makes both branches assertable with nothing stale and no fleet.
+ *
+ * @param {string[]} staleUrls
+ * @param {string[]} bareMetalUrls
+ * @returns {string[]}
+ */
+export function remedyLines(staleUrls: string[], bareMetalUrls: string[]): string[];
+/**
+ * The refusal text, or `null` when the fleet is running this checkout. PURE.
+ *
+ * Every number it reports carries what it was computed from, which is this file's parent rule: the hash,
+ * which side is dirty, and how many boxes were silent rather than merely absent from the count.
+ *
+ * @param {{expected: string, stale: Array<{worker: string, serving: string}>, unreachable: string[],
+ *           answered?: number}} drift
+ * @param {{when?: string, bareMetalUrls?: string[], sourceDirty?: string}} options
+ * @returns {string|null}
+ */
+export function describeCodeDrift(drift: {
+    expected: string;
+    stale: Array<{
+        worker: string;
+        serving: string;
+    }>;
+    unreachable: string[];
+    answered?: number;
+}, { when, bareMetalUrls, sourceDirty }?: {
+    when?: string;
+    bareMetalUrls?: string[];
+    sourceDirty?: string;
+}): string | null;
+/** What a single worker is serving, or `null` when it did not answer. */
+/** @param {string} url */
+export function readWorkerCode(url: string): Promise<any>;
+/**
+ * Is the worker source in `sourceDir` modified against HEAD?
+ *
+ * The DIRECTORY IS THE CALLER'S, never a path guessed here: this file is reached from `control` (which asks
+ * `layer-checkouts.mjs`) and from `worker-fleet` (which asks the worker package by name), and a guessed
+ * monorepo path would read the wrong tree the day the layer lives in another repository (#3394).
+ *
+ * Guarded, exactly like `protocolBumpNote`: outside a git checkout there is simply nothing to add, and a
+ * precondition that throws because `git` is missing is worse than the drift it was checking for.
+ *
+ * @param {string} sourceDir
+ */
+export function workerSourceDirty(sourceDir: string): string;
+/**
+ * AN EMPTY POOL IS NOT A CLEAN FLEET — the refusal, as a value, so it can be tested without exiting.
+ *
+ * `assertFleetRunsThisCheckout([])` used to print "Fleet runs this checkout (worker code …, 0 worker(s)
+ * checked)" and return: an affirmative claim about a fleet it had not looked at. The count sitting in the
+ * sentence is the only reason that was ever arguable, and "0 worker(s) checked" under a heading saying the
+ * fleet is fine is precisely how "verified" comes to mean "unexamined".
+ *
+ * REFUSED, not reported-and-continued. The pre-push hook's loud skip is right for `runs/`, whose absence is
+ * legitimate; an empty pool at a capture boundary never is. Both callers pass a pool a capture is about to
+ * dispatch to, so failing here with a named cause beats failing later as "0 captured".
+ *
+ * Returned rather than written, and that split is this file's own convention: the classification and the
+ * message are pure and driven directly by the tests, because a function that calls `process.exit` cannot be
+ * asserted on without stubbing the runtime out from under it.
+ *
+ * @param {string[] | undefined} workers
+ * @param {string} expected
+ * @returns {string | null} the refusal, or null when there is a pool to check
+ */
+export function describeEmptyPool(workers: string[] | undefined, expected: string): string | null;
+/**
+ * Refuse to run against a fleet that is not serving `expected` — the shared body of
+ * `assertFleetRunsThisCheckout`, taking the hash as a parameter rather than computing it.
+ *
+ * That split is the whole reason this function exists rather than living only in `worker-code-check.mjs`:
+ * computing `expected` needs `codeVersion`/`workerSourceDir`, and reaching those from `packages/control`
+ * cannot go through a relative path (TS5055 in `worker-fleet`'s own build) or a package-name import (no
+ * `node_modules` on the control plane, ADR 0012) at once — see this file's header. So the CALLER computes
+ * `expected` however it can safely reach a hasher, and this function starts from the answer.
+ *
+ * Exits 3, matching `assertOneBrowserAcross`: a precondition the operator must act on, distinct from 1
+ * (captures failed) and 2 (the request was malformed).
+ *
+ * @param {string} expected
+ * @param {string[]} workers
+ * `sourceDir` is the worker source the `expected` hash was computed over, so a dirty tree is read from the
+ * same place the hash came from.
+ *
+ * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[], sourceDir: string}} options
+ */
+export function assertWorkersServe(expected: string, workers: string[], options: {
+    when?: string;
+    allow?: boolean;
+    read?: (url: string) => Promise<string | null>;
+    bareMetalUrls?: string[];
+    sourceDir: string;
+}): Promise<void>;
+//# sourceMappingURL=code-drift.d.mts.map

package/dist/code-drift.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-drift.d.mts","sourceRoot":"","sources":["../src/code-drift.mjs"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCALW,MAAM,YACN,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAC,IAAI,GAAC,SAAS,CAAA;CAAC,CAAC,GAClD;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IACzF,QAAQ,EAAE,MAAM,CAAA;CAAC,CAgB9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uCAJW,MAAM,EAAE,iBACR,MAAM,EAAE,GACN,MAAM,EAAE,CAmBpB;AAED;;;;;;;;;;GAUG;AACH,yCALW;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAC,yCACpB;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAC,GAC7D,MAAM,GAAC,IAAI,CA0DvB;AAED,yEAAyE;AACzE,0BAA0B;AAC1B,oCADY,MAAM,gBAoBjB;AAED;;;;;;;;;;;GAWG;AACH,6CAFW,MAAM,UAahB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2CAJW,MAAM,EAAE,GAAG,SAAS,YACpB,MAAM,GACJ,MAAM,GAAG,IAAI,CAOzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CAPW,MAAM,WACN,MAAM,EAAE,WAIR;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAC,IAAI,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,iBA2BrI"}