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

package/dist/npm-cli-executable.mjs

@@ -0,0 +1,159 @@
+// A DELIBERATE, DISCLOSED DUPLICATE of `scripts/npm-cli-executable.mjs` at the repo root.
+//
+// #492: never spawn `npx`/`npm` at all -- resolve npm's own CLI script and run it through
+// `process.execPath`, since Node's CVE-2024-27980 fix permanently made `spawn`/`spawnSync`/`execFileSync`
+// refuse to launch a `.bat`/`.cmd` file directly without `shell` (and `ceo`'s ruling is no `shell: true`,
+// anywhere). See `scripts/npm-cli-executable.mjs`'s own header for the full incident and the two-layout
+// resolution this file duplicates behaviourally.
+//
+// This package publishes `check-worker-code.mjs` and `deploy-worker.mjs` as `bin` entries
+// (`package.json`), so every file they import -- `doctor.mjs` among them -- ships in the published
+// tarball and can only import from INSIDE `@a11ign/screenreader-fleet`. The repo-root `scripts/` directory
+// does not exist once this package is installed from npm, so importing it here would work in this
+// monorepo and break for every real consumer. That is the entire reason this file exists rather than a
+// relative import to the root: not stylistic preference, a publish-boundary constraint (see ADR 0004,
+// and `git-safe-env.mjs`'s own header beside this file for the identical shape).
+//
+// #2890: `pnpmCliInvocation` (#2301) and the two helpers it uses are copied verbatim, because `doctor.mjs`
+// spawns pnpm now, not npm; the npm half stays so the pin below keeps comparing whole files.
+//
+// Kept behaviourally identical to `scripts/npm-cli-executable.mjs` and pinned equal to it by
+// `npm-cli-executable.test.ts`, which is this repo's own remedy #3 ("pin them equal with a test") for a
+// fact that CANNOT be stated once because the two copies cross a package-publishing boundary neither can
+// import through.
+import { existsSync, realpathSync } from "node:fs";
+import { join, dirname, delimiter } from "node:path";
+/**
+ * @param {"npx" | "npm"} name
+ * @returns {string}
+ */
+function cliScriptName(name) {
+    return name === "npx" ? "npx-cli.js" : "npm-cli.js";
+}
+/**
+ * @param {"npx" | "npm"} name
+ * @returns {string[]}
+ */
+export function npmCliScriptCandidates(name) {
+    const script = cliScriptName(name);
+    const nodeDir = dirname(process.execPath);
+    const fixed = [
+        join(nodeDir, "node_modules", "npm", "bin", script),
+        join(nodeDir, "..", "lib", "node_modules", "npm", "bin", script),
+    ];
+    const fromPath = pathDerivedCandidate(name, script);
+    return fromPath === null ? fixed : [...fixed, fromPath];
+}
+/**
+ * #1268: THE THIRD LAYOUT. Debian and Ubuntu package npm at `/usr/share/nodejs/npm/bin/`, nowhere near
+ * `node`, and put `/usr/bin/npm` and `/usr/bin/npx` on PATH as symlinks straight to the CLI scripts. So
+ * the executable on PATH, symlinks resolved, IS the script (Debian) or sits in the script's directory
+ * (the upstream tarball's `bin/npx` wrapper). Tried LAST so the two fixed layouts keep their order on
+ * the platforms they were measured on; `null` when nothing named `name` is on PATH, so the candidate
+ * list never carries a path that cannot exist. Found by the first `npm ci` on the agents host.
+ * @param {"npx" | "npm"} name
+ * @param {string} script
+ * @returns {string | null}
+ */
+function pathDerivedCandidate(name, script) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        const executable = join(dir, name);
+        if (!existsSync(executable))
+            continue;
+        const real = realpathSync(executable);
+        return real.endsWith(script) ? real : join(dirname(real), script);
+    }
+    return null;
+}
+/**
+ * @param {"npx" | "npm"} name
+ * @returns {string}
+ */
+export function resolveNpmCliScript(name) {
+    const candidates = npmCliScriptCandidates(name);
+    const found = candidates.find((path) => existsSync(path));
+    if (!found) {
+        throw new Error(`could not find npm's own ${cliScriptName(name)} beside this Node install -- tried:\n`
+            + candidates.map((path) => `  ${path}`).join("\n"));
+    }
+    return found;
+}
+/**
+ * @param {"npx" | "npm"} name
+ * @param {string[]} args
+ * @returns {{ command: string, args: string[] }}
+ */
+export function npmCliInvocation(name, args) {
+    return { command: process.execPath, args: [resolveNpmCliScript(name), ...args] };
+}
+/**
+ * #2301: `pnpm <args>` WITHOUT SPAWNING A `.cmd`, for the same reason `npmCliInvocation` exists, and with the
+ * added problem that pnpm is not always ON `PATH` at all: this host and the Windows workers run it as
+ * `corepack pnpm` (`packageManager` in the root manifest pins the version), while a CI runner has the
+ * shim `pnpm/action-setup` puts there. Three ways to reach it, tried in this order, each ending in an argv
+ * that `execFileSync` can run with no shell:
+ *
+ *   1. `npm_execpath`, when this process was itself started BY pnpm (`pnpm run ...`, `pnpm exec ...`): pnpm
+ *      says which script it is, so nothing is searched for and no other pnpm can be picked up by mistake.
+ *   2. a `pnpm` on `PATH`: the executable itself on POSIX; on Windows the shim is `pnpm.cmd`, so the
+ *      `pnpm.cjs` beside it is run through `process.execPath` instead.
+ *   3. `corepack` on `PATH`, the same way: `corepack pnpm` on POSIX, `corepack.js` beside `node.exe`
+ *      through `process.execPath` on Windows.
+ *
+ * Throws NAMING WHAT WAS TRIED, for the reason `resolveNpmCliScript` does.
+ * @param {string[]} args
+ * @returns {{ command: string, args: string[] }}
+ */
+export function pnpmCliInvocation(args) {
+    const fromParent = process.env.npm_execpath ?? "";
+    if (/pnpm\.c?js$/.test(fromParent) && existsSync(fromParent)) {
+        return { command: process.execPath, args: [fromParent, ...args] };
+    }
+    const shim = onPath("pnpm");
+    if (shim !== null)
+        return shimInvocation(shim, join("node_modules", "pnpm", "bin", "pnpm.cjs"), args);
+    const corepack = onPath("corepack");
+    if (corepack !== null) {
+        return shimInvocation(corepack, join("node_modules", "corepack", "dist", "corepack.js"), ["pnpm", ...args]);
+    }
+    throw new Error("could not find pnpm: `npm_execpath` is not a pnpm script, and neither `pnpm` nor `corepack` "
+        + "is on PATH. `packageManager` in the root package.json names the version -- `corepack enable` or "
+        + "`pnpm/action-setup` provides it.");
+}
+/**
+ * The first executable called `name` on PATH, or `null`. On Windows the executable is `name.cmd`, which
+ * `existsSync` finds only when the extension is tried, so both spellings are.
+ * @param {string} name
+ * @returns {string | null}
+ */
+function onPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const candidate of [join(dir, name), join(dir, `${name}.cmd`)]) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * A POSIX shim is spawned as it is; a `.cmd` shim is never spawned (CVE-2024-27980, see the header), so the
+ * package script it wraps is run through `process.execPath`, found beside the shim (the layout `pnpm add -g`
+ * and `pnpm/action-setup` share) or beside `node` (corepack's).
+ * @param {string} shim
+ * @param {string} script the wrapped script, relative to the shim's directory or to `node`'s
+ * @param {string[]} args
+ * @returns {{ command: string, args: string[] }}
+ */
+function shimInvocation(shim, script, args) {
+    if (!shim.endsWith(".cmd"))
+        return { command: shim, args };
+    const found = [join(dirname(shim), script), join(dirname(process.execPath), script)].find((path) => existsSync(path));
+    if (found === undefined)
+        throw new Error(`${shim} is a .cmd shim and its script ${script} is not beside it or beside node`);
+    return { command: process.execPath, args: [found, ...args] };
+}
+//# sourceMappingURL=npm-cli-executable.mjs.map

package/dist/npm-cli-executable.mjs.map

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

package/dist/probe-outcome.d.mts

@@ -0,0 +1,89 @@
+/**
+ * @param {string} worker the worker's base URL
+ * @param {{ timeoutMs?: number, request?: ProbeRequest }} [options]
+ * @returns {Promise<Probe>}
+ */
+export function probeHealth(worker: string, { timeoutMs, request }?: {
+    timeoutMs?: number;
+    request?: ProbeRequest;
+}): Promise<Probe>;
+/**
+ * One sentence per outcome, in the words of what was OBSERVED. Only `refused`, `not-ready` and `busy` say the box is
+ * up, because only those are things the box itself said; a silent probe says "did not answer" and never "down".
+ *
+ * @param {Probe} probe
+ * @param {{ worker: string, timeoutMs?: number }} about
+ * @returns {string}
+ */
+export function describeProbe(probe: Probe, { worker, timeoutMs }: {
+    worker: string;
+    timeoutMs?: number;
+}): string;
+/** @typedef {typeof requestJson} ProbeRequest */
+/**
+ * THE PER-PROBE TIMEOUT, WITH ITS READING. A probe that outlives it is UNKNOWN, never "down", so this number
+ * decides how much slowness a healthy box is allowed.
+ *
+ * All of it READ by others on the real fleet (`orchestrator`, #2671) and none measured by this row, whose
+ * engineer is barred from probing it:
+ *   - the slowest HEALTHY box: 2.80 to 3.09 s on a11y-worker-13, -14 and -16, twelve others 0.53 to 0.76 s;
+ *   - that is the FIRST answer after the box has been quiet more than 5 s, because the worker rebuilds its
+ *     environment block with two synchronous `powershell.exe` calls when it is older than that, so a probe made
+ *     by hand is nearly always the slow case;
+ *   - a LOADED box (one that has just stopped a capture) can take up to about 10 s: each of the two calls is
+ *     bounded at 5 s and they stop the worker's event loop for the whole time.
+ * 12 s is that loaded ceiling plus 2 s, the number `fleet-wake.mjs` `HEALTH_TIMEOUT_MS` states for the same
+ * reading. Before #2683 these entries used 5 s (`witness`, 1.91 s over the 3.09 s box and none over a loaded
+ * one), 8 s (`auth:leak-check`) and 10 s (`worker:compare`'s busy guard), read at `d119fb0f2`. Cost of the
+ * generosity: a box that really is off costs one 12 s wait before the message. A refusal costs nothing, it comes
+ * back at once.
+ */
+export const WORKER_PROBE_TIMEOUT_MS: 12000;
+/** How to wake a box from a checkout of this repo. The published entries do not do it themselves. */
+export const WAKE_HINT: string;
+/**
+ * WHAT ONE `/health` PROBE CAN SAY, for the entries that reach a worker from the PUBLISHED side and by hand
+ * (`witness`, `worker:compare`, `auth:leak-check`, #2683 of #2655).
+ *
+ * Imports `worker-http` and nothing else: no `control` (this package is published and `@a11ign/control` never
+ * is, `worker-fleet-does-not-read-control.test.ts`) and no corpus reader, so a test may import it without
+ * pulling the corpus closure in. These entries do NOT wake a box (ADR 0012, product-manager 2026-09-26): they
+ * say it did not answer, and name the command that wakes one. `packages/control/src/fleet-wake.mjs` keeps its
+ * own `probeWorker` with the same five outcomes because it is the unpublished side of that line.
+ *
+ * The outcomes, and the one distinction that matters (an unanswered probe is UNKNOWN, never "down"):
+ *
+ *   ready       the box's own report, `ready: true`
+ *   busy        the box's own report, `busy: true`: a capture is running. Up, and not free
+ *   not-ready   it answered and its own `ready:false` says why, or it answered a non-2xx status. UP
+ *   refused     the connection was refused, so something answered the TCP handshake with a reset: the BOX IS UP
+ *               and the worker is not listening. UP
+ *   no-answer   nothing came back inside the timeout (`timedOut`), or the transport failed some other way
+ *               (unreachable, reset). One silent probe cannot separate "off" from "slow" from "the path dropped
+ *               it", so it is never called down
+ *
+ * `health` is the body the box sent, on the three outcomes where one arrived, because "usable" is a different
+ * question in different entries (`workerIsUsable` counts a worker predating the `ready` field as usable; the
+ * measurement guard wants `ready: true`) and this module does not choose for them.
+ */
+export type Probe = {
+    outcome: "ready";
+    health: any;
+} | {
+    outcome: "busy";
+    health: any;
+} | {
+    outcome: "not-ready";
+    reason: string;
+    health: any;
+} | {
+    outcome: "refused";
+    message: string;
+} | {
+    outcome: "no-answer";
+    message: string;
+    timedOut: boolean;
+};
+export type ProbeRequest = typeof requestJson;
+import { requestJson } from "./worker-http.mjs";
+//# sourceMappingURL=probe-outcome.d.mts.map

package/dist/probe-outcome.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-outcome.d.mts","sourceRoot":"","sources":["../src/probe-outcome.mjs"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH,oCAJW,MAAM,2BACN;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,YAAY,CAAA;CAAE,GAC5C,OAAO,CAAC,KAAK,CAAC,CAmB1B;AAMD;;;;;;;GAOG;AACH,qCAJW,KAAK,yBACL;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,MAAM,CAalB;AArED,iDAAiD;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAAuC,KAAM,CAAC;AA0B9C,qGAAqG;AACrG,+BAC6E;;;;;;;;;;;;;;;;;;;;;;;;;;oBAvDhE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAC1E;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACrD;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE;2BAIrD,OAAO,WAAW;4BAFJ,mBAAmB"}

package/dist/probe-outcome.mjs

@@ -0,0 +1,104 @@
+// @ts-check
+/**
+ * WHAT ONE `/health` PROBE CAN SAY, for the entries that reach a worker from the PUBLISHED side and by hand
+ * (`witness`, `worker:compare`, `auth:leak-check`, #2683 of #2655).
+ *
+ * Imports `worker-http` and nothing else: no `control` (this package is published and `@a11ign/control` never
+ * is, `worker-fleet-does-not-read-control.test.ts`) and no corpus reader, so a test may import it without
+ * pulling the corpus closure in. These entries do NOT wake a box (ADR 0012, product-manager 2026-09-26): they
+ * say it did not answer, and name the command that wakes one. `packages/control/src/fleet-wake.mjs` keeps its
+ * own `probeWorker` with the same five outcomes because it is the unpublished side of that line.
+ *
+ * The outcomes, and the one distinction that matters (an unanswered probe is UNKNOWN, never "down"):
+ *
+ *   ready       the box's own report, `ready: true`
+ *   busy        the box's own report, `busy: true`: a capture is running. Up, and not free
+ *   not-ready   it answered and its own `ready:false` says why, or it answered a non-2xx status. UP
+ *   refused     the connection was refused, so something answered the TCP handshake with a reset: the BOX IS UP
+ *               and the worker is not listening. UP
+ *   no-answer   nothing came back inside the timeout (`timedOut`), or the transport failed some other way
+ *               (unreachable, reset). One silent probe cannot separate "off" from "slow" from "the path dropped
+ *               it", so it is never called down
+ *
+ * `health` is the body the box sent, on the three outcomes where one arrived, because "usable" is a different
+ * question in different entries (`workerIsUsable` counts a worker predating the `ready` field as usable; the
+ * measurement guard wants `ready: true`) and this module does not choose for them.
+ *
+ * @typedef {{ outcome: "ready", health: any } | { outcome: "busy", health: any }
+ *   | { outcome: "not-ready", reason: string, health: any }
+ *   | { outcome: "refused", message: string }
+ *   | { outcome: "no-answer", message: string, timedOut: boolean }} Probe
+ */
+import { requestJson } from "./worker-http.mjs";
+/** @typedef {typeof requestJson} ProbeRequest */
+/**
+ * THE PER-PROBE TIMEOUT, WITH ITS READING. A probe that outlives it is UNKNOWN, never "down", so this number
+ * decides how much slowness a healthy box is allowed.
+ *
+ * All of it READ by others on the real fleet (`orchestrator`, #2671) and none measured by this row, whose
+ * engineer is barred from probing it:
+ *   - the slowest HEALTHY box: 2.80 to 3.09 s on a11y-worker-13, -14 and -16, twelve others 0.53 to 0.76 s;
+ *   - that is the FIRST answer after the box has been quiet more than 5 s, because the worker rebuilds its
+ *     environment block with two synchronous `powershell.exe` calls when it is older than that, so a probe made
+ *     by hand is nearly always the slow case;
+ *   - a LOADED box (one that has just stopped a capture) can take up to about 10 s: each of the two calls is
+ *     bounded at 5 s and they stop the worker's event loop for the whole time.
+ * 12 s is that loaded ceiling plus 2 s, the number `fleet-wake.mjs` `HEALTH_TIMEOUT_MS` states for the same
+ * reading. Before #2683 these entries used 5 s (`witness`, 1.91 s over the 3.09 s box and none over a loaded
+ * one), 8 s (`auth:leak-check`) and 10 s (`worker:compare`'s busy guard), read at `d119fb0f2`. Cost of the
+ * generosity: a box that really is off costs one 12 s wait before the message. A refusal costs nothing, it comes
+ * back at once.
+ */
+export const WORKER_PROBE_TIMEOUT_MS = 12_000;
+/**
+ * @param {string} worker the worker's base URL
+ * @param {{ timeoutMs?: number, request?: ProbeRequest }} [options]
+ * @returns {Promise<Probe>}
+ */
+export async function probeHealth(worker, { timeoutMs = WORKER_PROBE_TIMEOUT_MS, request = requestJson } = {}) {
+    let response;
+    try {
+        response = await request(`${worker.replace(/\/$/, "")}/health`, { timeoutMs });
+    }
+    catch (error) {
+        const { code, message } = /** @type {NodeJS.ErrnoException} */ (error);
+        // `message` is EMPTY for a raw ECONNREFUSED on this Node version, so it falls back to the code.
+        if (code === "ECONNREFUSED")
+            return { outcome: "refused", message: message || code };
+        return { outcome: "no-answer", timedOut: code === "ETIMEDOUT",
+            message: `${code ? `${code}: ` : ""}${message}` };
+    }
+    const health = response.json;
+    if (!response.ok)
+        return { outcome: "not-ready", reason: `/health answered HTTP ${response.status}`, health };
+    if (health?.busy === true)
+        return { outcome: "busy", health };
+    if (health?.ready === true)
+        return { outcome: "ready", health };
+    return { outcome: "not-ready", health,
+        reason: response.json?.reason ?? "/health answered without `ready: true` and without a reason" };
+}
+/** How to wake a box from a checkout of this repo. The published entries do not do it themselves. */
+export const WAKE_HINT = "If it is a fleet box that has gone to sleep, wake it from a checkout of the a11ign repo with "
+    + "`npm run fleet:wake -- <name>` (<name> is its entry in inventory.yml).";
+/**
+ * One sentence per outcome, in the words of what was OBSERVED. Only `refused`, `not-ready` and `busy` say the box is
+ * up, because only those are things the box itself said; a silent probe says "did not answer" and never "down".
+ *
+ * @param {Probe} probe
+ * @param {{ worker: string, timeoutMs?: number }} about
+ * @returns {string}
+ */
+export function describeProbe(probe, { worker, timeoutMs = WORKER_PROBE_TIMEOUT_MS }) {
+    switch (probe.outcome) {
+        case "ready": return `${worker} answered and is ready.`;
+        case "busy": return `${worker} is up and busy with a capture.`;
+        case "not-ready": return `${worker} is up and answered, but it says it is not ready: ${probe.reason}.`;
+        case "refused": return `${worker} refused the connection (${probe.message}): the machine is up and the worker `
+            + "is not listening. Waking it will not help; start the worker on it.";
+        case "no-answer": return `${worker} did not answer${probe.timedOut ? ` within ${timeoutMs / 1000} s` : ""} `
+            + `(${probe.message}). That does not say it is off: it may be asleep, slow, or not reachable from here. ${WAKE_HINT}`;
+        default: throw new Error(`unknown probe outcome: ${JSON.stringify(probe)}`);
+    }
+}
+//# sourceMappingURL=probe-outcome.mjs.map

package/dist/probe-outcome.mjs.map

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

package/dist/protocol-guard.d.mts

@@ -0,0 +1,34 @@
+/**
+ * Decide whether a deploy may proceed.
+ *
+ * @param {{ local: number|string|null, served: {worker: string, protocol: number|string|null}[],
+ *           allowed: boolean, source?: string }} input
+ * @returns {{ refuse: boolean, message: string }}
+ */
+export function protocolVerdict({ local, served, allowed, source }: {
+    local: number | string | null;
+    served: {
+        worker: string;
+        protocol: number | string | null;
+    }[];
+    allowed: boolean;
+    source?: string;
+}): {
+    refuse: boolean;
+    message: string;
+};
+/**
+ * Ask each worker which protocol it serves.
+ *
+ * A worker that cannot be reached reports `null` rather than being dropped, so the caller can tell "the
+ * fleet agrees" from "we could not ask" — the distinction the verdict above turns on.
+ *
+ * @param {string[]} urls
+ * @returns {Promise<{worker: string, protocol: number|string|null}[]>}
+ */
+export function servedProtocols(urls: string[]): Promise<{
+    worker: string;
+    protocol: number | string | null;
+}[]>;
+export const RECAPTURE_COST: string;
+//# sourceMappingURL=protocol-guard.d.mts.map

package/dist/protocol-guard.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-guard.d.mts","sourceRoot":"","sources":["../src/protocol-guard.mjs"],"names":[],"mappings":"AAqDA;;;;;;GAMG;AACH,oEAJW;IAAE,KAAK,EAAE,MAAM,GAAC,MAAM,GAAC,IAAI,CAAC;IAAC,MAAM,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,MAAM,GAAC,IAAI,CAAA;KAAC,EAAE,CAAC;IACpF,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAmChD;AAED;;;;;;;;GAQG;AACH,sCAHW,MAAM,EAAE,GACN,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,MAAM,GAAC,IAAI,CAAA;CAAC,EAAE,CAAC,CAqBrE;AA9ED,oCAG6G"}

package/dist/protocol-guard.mjs

@@ -0,0 +1,121 @@
+/**
+ * REFUSE A DEPLOY THAT WOULD SILENTLY INVALIDATE THE CORPUS.
+ *
+ * `CAPTURE_PROTOCOL_VERSION` is a capture-cache key. Shipping a change to it invalidates every cached
+ * capture — `RECAPTURE_COST` below says how many a full re-run produces — and that is sometimes exactly
+ * what you want. What must never happen is it going out without somebody deciding.
+ *
+ * **The guard existed and reached only the DEPRECATED path.** `deploy-worker.mjs` refuses without
+ * `--allow-protocol-change`, and that script is `utmctl file push` against a VM UUID: it cannot reach a
+ * bare-metal worker and fails immediately off macOS. Every box in `inventory.yml` is bare metal and
+ * deploys through `fleet:deploy`, which had no such check. So the only live deploy path was the unguarded
+ * one — this repo's signature defect (a remedy that reaches one call site when the behaviour reaches
+ * several) with the remedy on the path nobody uses.
+ *
+ * **This asks the FLEET, not git, and that is the stronger question.** The UTM guard compares the working
+ * tree against HEAD, which answers "did I commit the bump". Useful, and not the thing at risk: what
+ * decides whether the cache survives is whether the version about to ship differs from the one the boxes
+ * are *already serving*, because that is the version every cached capture was stamped under. Reading it
+ * from `/health` also means the check shares no failure mode with the action — the deploy goes over SSH,
+ * the verification over HTTP — which is this repo's rule after a hash-check that returned EMPTY whenever
+ * the channel it used was broken, and read as a flaky tool rather than a failed deploy.
+ */
+import { requestJson } from "./worker-http.mjs";
+/**
+ * WHAT A FULL RECAPTURE COSTS, in the words the two deploy refusals print -- derived here and shown, not
+ * retyped (#2244). The refusals printed 2,122, a count from 2026-07-26; on 2026-09-23 the cache held 4,500
+ * captures across 1,715 cases.
+ *
+ * **The population is what a full RE-RUN produces, not what the cache holds.** A run captures each case
+ * `manifest.json` lists, twice; the cache holds 4,500 captures because it also holds cases the manifest no
+ * longer lists, and a protocol bump does not make those cost anything, since nothing will ask for them
+ * again. So 1,715 x 2 = 3,430 is the price an operator is deciding on, and 4,500 is not.
+ *
+ * The inputs are `orchestrator`'s reading on the corpus host, 2026-09-23T14:26Z (#1561 comment
+ * 5796655391), and are not re-measured here. This file cannot read the manifest -- the control host that
+ * runs the guard does not have the corpus -- so the reading is dated in the message itself, where a stale
+ * one is visible to the person who acts on it.
+ *
+ * **NO WALL-CLOCK.** This used to say "about four hours of fleet time". That was a rate times the 1,061-case
+ * corpus of 2026-07-26 on a fleet of a size nothing in this file can read, and #2155 dropped its own estimates for the same
+ * reason. The rate is what `npm run fleet:status` can show; the product is somebody's to time.
+ */
+const MANIFEST_CASES = 1715;
+const CAPTURES_PER_CASE = 2;
+export const RECAPTURE_COST = `${(MANIFEST_CASES * CAPTURES_PER_CASE).toLocaleString("en-US")} captures `
+    + `(${MANIFEST_CASES.toLocaleString("en-US")} cases in manifest.json x ${CAPTURES_PER_CASE}, read `
+    + "2026-09-23T14:26Z; how long that takes depends on the fleet, so time a run rather than trust a figure)";
+/** How long a worker gets to answer `/health` before it counts as unreachable. */
+const HEALTH_TIMEOUT_MS = 5_000;
+/**
+ * Decide whether a deploy may proceed.
+ *
+ * @param {{ local: number|string|null, served: {worker: string, protocol: number|string|null}[],
+ *           allowed: boolean, source?: string }} input
+ * @returns {{ refuse: boolean, message: string }}
+ */
+export function protocolVerdict({ local, served, allowed, source }) {
+    if (local === null || local === undefined) {
+        // NAMES THE FILE IT WAS GIVEN, never a hardcoded one. This message said "from capture-core.mjs" while
+        // the caller had long since been pointed elsewhere, so the one sentence a broken guard prints sent the
+        // reader to a file that was not the problem.
+        return { refuse: true, message: `cannot read CAPTURE_PROTOCOL_VERSION from ${source ?? "the worker "
+                + "source"}, so this deploy cannot say whether it would invalidate the corpus. That is a broken `
+                + "guard, not a clean one." };
+    }
+    const reachable = served.filter((s) => s.protocol !== null && s.protocol !== undefined);
+    // EXAMINED NOTHING IS NOT AGREEMENT. If no worker answered, the guard has no opinion — and a guard with
+    // no opinion that reports success is the `evidence:check` defect: it exited 0 saying "evidence unchanged"
+    // having compared 2 of 48, because its own guard covered only `compared === 0` and called that "the
+    // extreme case rather than a different one". Nothing here is the extreme case of that; it IS that.
+    if (reachable.length === 0) {
+        return { refuse: !allowed, message: "no worker answered /health, so nothing could say which "
+                + `CAPTURE_PROTOCOL_VERSION the fleet is serving. Local is ${local}. Deploying blind could invalidate `
+                + "every cached capture. Check `npm run fleet:status`, or pass --allow-protocol-change if you mean it." };
+    }
+    const differing = reachable.filter((s) => String(s.protocol) !== String(local));
+    if (differing.length === 0)
+        return { refuse: false, message: "" };
+    const detail = differing.map((s) => `    ${s.worker} serves ${s.protocol}`).join("\n");
+    if (allowed) {
+        return { refuse: false, message: `\n  Deploying CAPTURE_PROTOCOL_VERSION ${local} as requested.\n${detail}\n`
+                + "  Every cached capture becomes invalid and the next run recaptures all of them.\n" };
+    }
+    return { refuse: true, message: `\nREFUSING TO DEPLOY: this checkout has CAPTURE_PROTOCOL_VERSION = ${local}, and the fleet does not.\n\n`
+            + `${detail}\n\n`
+            + "That value is a capture-cache key, so deploying it invalidates every cached capture and forces a\n"
+            + `full recapture: ${RECAPTURE_COST}.\n\n`
+            + "  If that is what you want:   npm run fleet:deploy -- --allow-protocol-change\n"
+            + "  If it is not:               check what changed in packages/nvda-worker/src/capture-core.mjs\n" };
+}
+/**
+ * Ask each worker which protocol it serves.
+ *
+ * A worker that cannot be reached reports `null` rather than being dropped, so the caller can tell "the
+ * fleet agrees" from "we could not ask" — the distinction the verdict above turns on.
+ *
+ * @param {string[]} urls
+ * @returns {Promise<{worker: string, protocol: number|string|null}[]>}
+ */
+export async function servedProtocols(urls) {
+    return Promise.all(urls.map(async (url) => {
+        try {
+            // `requestJson`, not `fetch` -- the same worker JSON API this repo's own audit found duplicated with
+            // its own timeout mechanism at several other call sites (worker-http.mjs's own header), and this one
+            // is on the deploy-guard path: a swallowed truncation here would misreport a fleet mid-protocol-bump
+            // as unreachable rather than as differing, silently weakening the one check standing between a
+            // deploy and an unannounced cache wipe.
+            const response = await requestJson(`${url.replace(/\/$/, "")}/health`, { timeoutMs: HEALTH_TIMEOUT_MS });
+            // `?? null` and never `?? 0`: a worker predating the field has no opinion, and reading absence as a
+            // number is the defect this project pays for most often. `response.json` is `undefined` rather than
+            // a throw on unparseable JSON (requestJson's own contract), which `?.` already treats as "no opinion".
+            return { worker: url, protocol: response.json?.environment?.captureProtocol ?? null };
+        }
+        catch {
+            // Deliberately not rethrown: unreachable is a VERDICT here, handled by `protocolVerdict`, not an
+            // error. Swallowing it would be wrong only if nothing downstream distinguished it, and something does.
+            return { worker: url, protocol: null };
+        }
+    }));
+}
+//# sourceMappingURL=protocol-guard.mjs.map

package/dist/protocol-guard.mjs.map

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

package/dist/source-walk.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Every non-test source file under `packages/`, as `[relativePath, source]`.
+ *
+ * @param {{ root?: string }} [options]
+ * @returns {Array<[string, string]>}
+ */
+export function sourceFiles({ root }?: {
+    root?: string;
+}): Array<[string, string]>;
+/** The `packages/` directory, resolved from this module rather than from the caller's cwd. */
+export const PACKAGES: string;
+//# sourceMappingURL=source-walk.d.mts.map

package/dist/source-walk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-walk.d.mts","sourceRoot":"","sources":["../src/source-walk.mjs"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,uCAHW;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACf,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAkBnC;AA3BD,8FAA8F;AAC9F,8BAAkF"}

package/dist/source-walk.mjs

@@ -0,0 +1,56 @@
+// @ts-check
+/**
+ * Every source file under `packages/`, so a guard can be written over what EXISTS rather than over a list.
+ *
+ * This repo's most expensive recurring shape is a check that only examines the places somebody already
+ * thought of. Two instances are recorded in `budget-ladder.test.ts` alone: the worker-file list that let a
+ * file deploy invisibly, and the ladder guard that read ONE hardcoded path and therefore could not see
+ * `capture-real-pages.mjs` declaring 300 s against a 520 s hard timeout — inverted, on the client that
+ * needed it most.
+ *
+ * Extracted here because there were about to be TWO copies of the walk: one for capture budgets and one for
+ * `--worker` validation. A duplicated discovery is a discovery that drifts, which is the same defect one
+ * level up.
+ *
+ * `dist` is excluded because it is build output of the very files being checked, so including it
+ * double-counts and reports a stale copy as a violation after the source has been fixed. Test files are
+ * excluded because a guard asserting on other guards' source is noise.
+ *
+ * Dot-directories are skipped, as `.gitignore` would, because this walk reads the FILESYSTEM and a test may
+ * plant a transient one inside the repository (`corpus-backup.test.ts` does, as `.corpus-backup-mutation-*`,
+ * so a copied script can resolve `node_modules`). Listing it and reading the file after the other test has
+ * removed it failed `pnpm run verify` with ENOENT (#3337, after #2876 and #1919). No tracked source lives in
+ * one, and a dot-directory is not a place a guard's population should come from.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The `packages/` directory, resolved from this module rather than from the caller's cwd. */
+export const PACKAGES = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SKIPPED_DIRECTORY = /^(node_modules|dist|\..*)$/;
+/**
+ * Every non-test source file under `packages/`, as `[relativePath, source]`.
+ *
+ * @param {{ root?: string }} [options]
+ * @returns {Array<[string, string]>}
+ */
+export function sourceFiles({ root = PACKAGES } = {}) {
+    /** @type {Array<[string, string]>} */
+    const found = [];
+    /** @param {string} dir */
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRECTORY.test(entry.name))
+                    walk(path);
+            }
+            else if (/\.(mjs|ts)$/.test(entry.name) && !entry.name.includes(".test.")) {
+                found.push([path.slice(root.length + 1), readFileSync(path, "utf8")]);
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+//# sourceMappingURL=source-walk.mjs.map

package/dist/source-walk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-walk.mjs","sourceRoot":"","sources":["../src/source-walk.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAElF,MAAM,iBAAiB,GAAG,4BAA4B,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,GAAG,EAAE;IAClD,sCAAsC;IACtC,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,0BAA0B;IAC1B,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,EAAE;QACnB,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,CAAC;iBAAM,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5E,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;YACxE,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,CAAC;IACX,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/transient-fault.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @param {unknown} error  anything a failed request threw — a node:http Error, an undici one, a string
+ * @returns {boolean}
+ */
+export function isTransient(error: unknown): boolean;
+//# sourceMappingURL=transient-fault.d.mts.map

package/dist/transient-fault.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-fault.d.mts","sourceRoot":"","sources":["../src/transient-fault.mjs"],"names":[],"mappings":"AAsEA;;;GAGG;AACH,mCAHW,OAAO,GACL,OAAO,CAanB"}