@a11ign/screenreader-fleet 0.1.0 → 0.3.0

package/dist/probe-outcome.mjs

@@ -1,104 +1,58 @@
-// @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 } = {}) {
+const WORKER_PROBE_TIMEOUT_MS = 12000;
+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}` };
+        response = await request(`${worker.replace(/\/$/, "")}/health`, {
+            timeoutMs
+        });
+    } catch (error) {
+        const { code, message } = error;
+        if ("ECONNREFUSED" === code) return {
+            outcome: "refused",
+            message: message || code
+        };
+        return {
+            outcome: "no-answer",
+            timedOut: "ETIMEDOUT" === code,
+            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" };
+    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)}`);
+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).";
+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
+export { WAKE_HINT, WORKER_PROBE_TIMEOUT_MS, describeProbe, probeHealth };

package/dist/protocol-guard.d.mts

@@ -31,4 +31,3 @@ export function servedProtocols(urls: string[]): Promise<{
     protocol: number | string | null;
 }[]>;
 export const RECAPTURE_COST: string;
-//# sourceMappingURL=protocol-guard.d.mts.map

package/dist/source-walk.d.mts

@@ -9,4 +9,3 @@ export function sourceFiles({ root }?: {
 }): 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/src_fleet-scripts_mjs.mjs

@@ -0,0 +1,16 @@
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+const assetDir = ()=>fileURLToPath(new URL("../src/local-worker/", import.meta.url));
+function fleetScriptPaths() {
+    const dir = assetDir();
+    return {
+        dir,
+        workerCtl: join(dir, "worker-ctl.sh"),
+        buildVm: join(dir, "build-vm.sh"),
+        cloneWorker: join(dir, "clone-worker.sh"),
+        createUtmVm: join(dir, "create-utm-vm.sh"),
+        fetchWindowsIso: join(dir, "fetch-windows-iso.sh"),
+        provisioning: fileURLToPath(new URL("../src/provisioning/", import.meta.url))
+    };
+}
+export { fleetScriptPaths };

package/dist/src_git-safe-env_mjs.mjs

@@ -0,0 +1,9 @@
+function sandboxGitEnv(extra = {}) {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(process.env))if (!key.startsWith("GIT_")) scrubbed[key] = value;
+    return {
+        ...scrubbed,
+        ...extra
+    };
+}
+export { sandboxGitEnv };

package/dist/src_utm-deprecated_mjs.mjs

@@ -0,0 +1,4 @@
+function warnUtmDeprecated(what) {
+    process.stderr.write(`DEPRECATED: ${what} manages a local UTM worker VM. UTM was a testing path and is not the fleet.\nCapture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy. See CLAUDE.md's\n"Working on a Mac" section.\n`);
+}
+export { warnUtmDeprecated };

package/dist/transient-fault.d.mts

@@ -3,4 +3,3 @@
  * @returns {boolean}
  */
 export function isTransient(error: unknown): boolean;
-//# sourceMappingURL=transient-fault.d.mts.map

package/dist/transient-fault.mjs

@@ -1,86 +1,26 @@
-// @ts-check
-/**
- * Is a capture-worker failure recoverable, or the end of this case?
- *
- * MOVED HERE from `packages/lab/src/training/capture-decisions.mjs` — architecture-audit.md §5, item 3:
- * "the protocol version and fault codes are reached by scraping" because no shared, dependency-free home
- * existed for classification that both the lab AND anything else speaking to a worker over HTTP need. This
- * package already exists for exactly that ("host-side lifecycle, health and capacity for a fleet of
- * Windows NVDA capture workers"), and `capture-client.mjs` — which needs this to decide whether a lost
- * response is worth reconciling rather than failing outright — moved here alongside it for the same
- * reason: `packages/cli` can depend on `@a11ign/screenreader-fleet` (it already does, for `requestJson`)
- * but must never depend on `@a11ign/lab`, which is private and never published.
- *
- * `capture-decisions.mjs` re-exports `isTransient` from here so every existing lab-side importer is
- * unchanged.
- */
-// BY CODE, from the module that defines them — architecture-audit.md §5, item 3 and item 4: "fault codes
-// are copied as string literals... because no ./capture-faults subpath is exported". `capture-faults.mjs`
-// has no imports of its own, so it was always safe to expose; the subpath just did not exist. Reading the
-// actual codes here means a renamed fault cannot silently stop being recognised as recoverable.
 import { FAULT } from "@a11ign/screenreader-worker/capture-faults";
-/**
- * Recoverable, or the end of this case?
- *
- * Everything here heals on its own, which is why waiting beats failing. The connection errors are
- * here because the first full dataset run lost its last four cases to one guest bugchecking — it came
- * back by itself, but the run had already recorded four permanent failures.
- *
- * `running but not speaking` and `hard timeout` are the subtle ones: both make the worker STOP its
- * screen reader, so the next capture cold-starts a fresh one. They are self-healing by construction,
- * and classifying them fatal cost a case in the run that proved it.
- */
-const TRANSIENT = new RegExp([
-    "fetch failed", "ECONNREFUSED", "ECONNRESET", "socket hang up", "timed out", "aborted",
-    "HTTP 429.*capture is already in progress",
-    "running but not speaking",
-    "hard timeout",
-].join("|"), "i");
-/**
- * Faults the WORKER named for us, which never need matching against prose.
- *
- * Both self-heal: the worker stops NVDA on any failed capture, so the next attempt cold-starts a clean
- * one. The worker now retries these itself before answering, so seeing one here means even its retry
- * did not clear it — still worth reissuing the case rather than recording a permanent failure.
- */
-const TRANSIENT_FAULTS = new Set([FAULT.SCREEN_READER_MUTE, FAULT.SCREEN_READER_START_FAILED]);
-/**
- * Network failures that heal on their own, by CODE rather than by wording.
- *
- * These became visible when the capture clients moved off `fetch` to `node:http` (see
- * `worker-fleet/src/worker-http.mjs` for why they had to). `fetch` collapsed every network failure into
- * `TypeError: fetch failed`, which the regex above matched — so the whole class was transient by accident,
- * through a wrapper's wording rather than through anything we had decided.
- *
- * `EHOSTUNREACH` is the one that would have bitten. It is how a bare-metal worker presents while its NIC
- * wakes from selective suspend, recorded in provision-nvda-worker.ps1: 48 instant failures in one
- * evidence-check run, and the box answered a curl thirty seconds later. Under the real code, and without
- * this set, that would now be classified FATAL and fail 48 cases permanently.
- *
- * `ETIMEDOUT` covers both a dead peer and our own deadline in `requestJson`, which is deliberate: a
- * capture that outran its budget is exactly the case the worker recovers from by cold-starting NVDA.
- */
+const TRANSIENT = new RegExp("fetch failed|ECONNREFUSED|ECONNRESET|socket hang up|timed out|aborted|HTTP 429.*capture is already in progress|running but not speaking|hard timeout", "i");
+const TRANSIENT_FAULTS = new Set([
+    FAULT.SCREEN_READER_MUTE,
+    FAULT.SCREEN_READER_START_FAILED
+]);
 const TRANSIENT_NETWORK_CODES = new Set([
-    "ECONNREFUSED", "ECONNRESET", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN",
-    "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EPIPE",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT"
 ]);
-/**
- * @param {unknown} error  anything a failed request threw — a node:http Error, an undici one, a string
- * @returns {boolean}
- */
-export function isTransient(error) {
-    const failure = /** @type {{ code?: string, cause?: { code?: string }, message?: string }} */ (error);
-    // Prefer the code. The regex below is the fallback for older workers and for host-side failures
-    // (a dropped socket has no fault code), but a message is prose and prose gets reworded — see
-    // packages/nvda-worker/src/capture-faults.mjs for what that cost.
-    if (TRANSIENT_FAULTS.has(failure?.code ?? ""))
-        return true;
-    if (TRANSIENT_NETWORK_CODES.has(failure?.code ?? ""))
-        return true;
-    // A node:http error carries its code on the error itself; an undici one hides it on `cause`. Checking
-    // both means the classification does not depend on which client the caller happened to use.
-    if (TRANSIENT_NETWORK_CODES.has(failure?.cause?.code ?? ""))
-        return true;
+function isTransient(error) {
+    const failure = error;
+    if (TRANSIENT_FAULTS.has(failure?.code ?? "")) return true;
+    if (TRANSIENT_NETWORK_CODES.has(failure?.code ?? "")) return true;
+    if (TRANSIENT_NETWORK_CODES.has(failure?.cause?.code ?? "")) return true;
     return TRANSIENT.test(String(failure?.message ?? error ?? ""));
 }
-//# sourceMappingURL=transient-fault.mjs.map
+export { isTransient };

package/dist/utm-deprecated.d.mts

@@ -3,4 +3,3 @@
  *   specific to what actually fired, not a generic banner every UTM-adjacent file prints identically.
  */
 export function warnUtmDeprecated(what: string): void;
-//# sourceMappingURL=utm-deprecated.d.mts.map

package/dist/worker-code-check.d.mts

@@ -26,4 +26,3 @@ import { readWorkerCode } from "./code-drift.mjs";
 import { remedyLines } from "./code-drift.mjs";
 import { workerSourceDirty } from "./code-drift.mjs";
 export { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty };
-//# sourceMappingURL=worker-code-check.d.mts.map

package/dist/worker-code-check.mjs

@@ -1,78 +1,129 @@
-// @ts-check
-/**
- * Is the fleet running the code this checkout expects — asked BEFORE a capture run, not after it.
- *
- * ## The hole this closes
- *
- * `run-job.yml` refuses to run at a commit other than the one asked for, and the comment above that
- * refusal says why: *"a job that quietly runs four commits behind reports success for code you did not
- * ask for."* That guard covers the LAB. It says nothing about the twelve machines that actually take the
- * captures, and those are a second checkout, deployed by a separate command nobody is forced to run.
- *
- * So a capture run could be dispatched at the right commit, on a lab that proved it was at the right
- * commit, and still capture with the PREVIOUS release of `capture-core.mjs`. Measured on 2026-08-25: after
- * `MAX_TAB_STOPS` went 12 -> 150 and `collectByType` started recording `prevCount`, the real-page corpus
- * held both populations at once, and the only way to read it was to bucket captures by whether they
- * carried the new diagnostic mark at all. The evidence was mixed, the run reported success, and the
- * separation had to be done by hand afterwards.
- *
- * `npm run worker:code` has answered this question correctly the whole time. It is a separate command a
- * human must remember, which is this repo's own definition of a check that does not happen — and it was
- * remembered by hand four times in one day before this existed.
- *
- * ## Why a REFUSAL, and why on any difference at all
- *
- * `workerCode` is deliberately outside the capture cache key ("it changes when a comment changes, and
- * invalidating the WHOLE corpus over a reworded comment is how a cache becomes something people turn
- * off") and deliberately outside
- * `fleet-consistency.mjs`'s `MUST_MATCH` for the same reason. Both of those are the right call for
- * the questions they answer — *is this evidence still valid* and *are these guests interchangeable*.
- *
- * This is a third question with a different answer: *am I about to capture with the code I asked for*. A
- * comment-only drift is a false alarm here and it costs one `fleet:deploy`; a real drift costs a corpus and
- * is invisible, because nothing downstream keys on `workerCode`. That asymmetry is the whole argument.
- *
- * It is a PRECONDITION and never a key: nothing here invalidates a cached capture.
- *
- * ## The comparison itself lives in `code-drift.mjs`, and this file is the reason for the split
- *
- * `expectedWorkerCode` below needs `codeVersion`/`workerSourceDir`, reached through a SUBPATH export
- * (`@a11ign/screenreader-worker/code-version`) rather than a relative path — a relative one drags
- * `nvda-worker`'s `.mjs` files into this package's own tsc project and the build dies with TS5055 ("would
- * overwrite input file"). That subpath resolves through `node_modules`, which is exactly what
- * `packages/control` does not have (ADR 0012) — so when `lab-job.mjs` needed this same comparison BEFORE
- * dispatching to the lab, it could not import this file. `code-drift.mjs` is the part of this file with no
- * opinion about what "expected" means: it takes the hash as a parameter, imports nothing but
- * `node:child_process`, and is safe from both places. This file supplies the one thing only it can compute.
- */
-import { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty, assertWorkersServe } from "./code-drift.mjs";
-// A SUBPATH export, not a deep relative path: `../../nvda-worker/src/...` drags those .mjs files into
-// worker-fleet's tsc project and the build dies with TS5055 "would overwrite input file". The subpath is
-// also the shape already in use for the same reason -- `@a11ign/screenreader-fleet/worker-http`.
-// `code-version.mjs` imports nothing but node stdlib and `worker-files.mjs`, which is why it is safe and
-// why it is its own module. Still the ONE hasher: the subpath is the same function.
+import { execFileSync } from "node:child_process";
 import { codeVersion, workerSourceDir } from "@a11ign/screenreader-worker/code-version";
-/** The hash this checkout expects every worker to be serving. One hasher, shared with the guest. */
-export const expectedWorkerCode = () => codeVersion(workerSourceDir());
-// Re-exported rather than duplicated: existing callers (`capture-real-pages.mjs`,
-// `capture-screenreader-dataset.mjs`, and this module's own test) import these from here, and moving their
-// implementation to `code-drift.mjs` must not become a second place either has to be found.
-export { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty };
-/**
- * Refuse to capture with a fleet that is not running this checkout.
- *
- * Called at the boundary of every capture entry point, for the reason `assertWorkerUrl` is: the
- * alternative is discovering it in the evidence weeks later, where a stale worker looks like a page that
- * changed. **Both entry points, not one** — a remedy that reaches one of several paths is the shape this
- * repo has paid for three times over (`anchorToTop`, `ensureSpeechChannel`, `waitForAnnouncement`), and
- * `capture-preflight.test.ts` pins that both call it.
- *
- * A thin wrapper over `assertWorkersServe`, supplying the one thing only this file can compute: the hash.
- *
- * @param {string[]} workers
- * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[]}} options
- */
-export async function assertFleetRunsThisCheckout(workers, options = {}) {
-    return assertWorkersServe(expectedWorkerCode(), workers, { ...options, sourceDir: workerSourceDir() });
+import { requestJson } from "./worker-http.mjs";
+import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
+const HEALTH_TIMEOUT_MS = 15000;
+function codeDrift(expected, readings) {
+    const stale = [];
+    const unreachable = [];
+    let answered = 0;
+    for (const reading of readings ?? []){
+        const code = reading?.code;
+        if (null == code) {
+            unreachable.push(reading?.worker);
+            continue;
+        }
+        answered += 1;
+        if (code !== expected) stale.push({
+            worker: reading.worker,
+            serving: String(code)
+        });
+    }
+    return {
+        expected,
+        stale,
+        unreachable,
+        answered
+    };
 }
-//# sourceMappingURL=worker-code-check.mjs.map
+function remedyLines(staleUrls, bareMetalUrls) {
+    const bareMetal = new Set(bareMetalUrls);
+    const physical = staleUrls.filter((u)=>bareMetal.has(u));
+    const vms = staleUrls.filter((u)=>!bareMetal.has(u));
+    const lines = [
+        `\n${staleUrls.length} stale worker(s).`
+    ];
+    if (physical.length) lines.push(`\n  ${physical.length} in inventory.yml — bare metal, so they deploy by PULLING:`, "    npm run fleet:deploy", "  `npm run worker:deploy` cannot reach these: it is utmctl, keyed on a VM UUID.");
+    if (vms.length) lines.push(`\n  ${vms.length} not in inventory.yml — local VM(s). A restart via \`utmctl exec\``, "  silently does nothing on some guests; rebooting always picks up a pushed file:", "    npm run worker:deploy");
+    return lines;
+}
+function describeCodeDrift(drift, { when = "before the run", bareMetalUrls = [], sourceDirty = "" } = {}) {
+    if (drift?.answered === 0 && drift?.unreachable?.length) return [
+        "",
+        `REFUSING to vouch for the fleet ${when}: ${drift.unreachable.length} worker(s) were asked and NONE`,
+        `answered, so nothing was compared against this checkout (${drift.expected}).`,
+        ...drift.unreachable.map((w)=>`  ${w}`),
+        "",
+        "This is not a clean fleet, it is an unexamined one. A capture is about to dispatch to these boxes,",
+        "so silence here is a broken invocation rather than a pass. Common causes: the fleet is powered",
+        "down (npm run fleet:status), or a deploy just rebooted it and nothing waited.",
+        "",
+        "Or pass --allow-stale-workers if you know something this check does not.",
+        ""
+    ].join("\n");
+    if (!drift?.stale?.length) return null;
+    const lines = [
+        `\nFLEET IS NOT RUNNING THIS CHECKOUT ${when}.`,
+        `This checkout expects worker code ${drift.expected}; ${drift.stale.length} worker(s) serve something else:`,
+        ...drift.stale.map(({ worker, serving })=>`  ${worker}  ${serving}`)
+    ];
+    if (drift.unreachable.length) lines.push(`  (${drift.unreachable.length} worker(s) did not answer and were not judged: ${drift.unreachable.join(", ")})`);
+    lines.push("", "A capture stamps the commit the LAB is at, and nothing downstream keys on the worker's code —", "`workerCode` is outside the cache key on purpose — so evidence taken by a stale worker is", "indistinguishable from current evidence for ever after.");
+    if (sourceDirty) lines.push("", "But the drift is on THIS side: the worker source in this checkout is modified against HEAD —", `  ${sourceDirty}`, "so the fleet may be perfectly current and deploying would ship uncommitted work. Commit or revert", "first, then re-check. Do not reach for the remedy below until this is clean.");
+    lines.push(...remedyLines(drift.stale.map((s)=>s.worker), bareMetalUrls));
+    lines.push("", "Or pass --allow-stale-workers if you know something this check does not; it will say so in", "the output rather than passing quietly.");
+    return `${lines.join("\n")}\n`;
+}
+async function readWorkerCode(url) {
+    try {
+        const response = await requestJson(`${String(url).replace(/\/$/, "")}/health`, {
+            timeoutMs: HEALTH_TIMEOUT_MS
+        });
+        if (void 0 === response.json) throw new Error(`invalid JSON from ${url}`);
+        return response.json.code ?? "absent";
+    } catch  {
+        return null;
+    }
+}
+function workerSourceDirty(sourceDir) {
+    if ("string" != typeof sourceDir || !sourceDir) throw new TypeError("workerSourceDirty needs the worker source directory to read; there is no default");
+    try {
+        return execFileSync("git", [
+            "-C",
+            sourceDir,
+            "status",
+            "--porcelain",
+            "--",
+            "."
+        ], {
+            encoding: "utf8",
+            env: sandboxGitEnv()
+        }).trim().split("\n").filter(Boolean).join("; ");
+    } catch  {
+        return "";
+    }
+}
+function describeEmptyPool(workers, expected) {
+    if (workers?.length) return null;
+    return `REFUSING to vouch for the fleet: no workers were given, so nothing was compared against this checkout (${expected}). A capture dispatches to workers, so an empty pool is a broken invocation rather than a clean fleet — check A11Y_WORKER(S), the local pool, or inventory.yml.\n`;
+}
+async function assertWorkersServe(expected, workers, options) {
+    const { when = "before the run", allow = false, read = readWorkerCode, bareMetalUrls = [], sourceDir } = options;
+    if (allow) return void process.stdout.write("--allow-stale-workers: NOT checking that the fleet runs this checkout.\n");
+    const empty = describeEmptyPool(workers, expected);
+    if (empty) {
+        process.stderr.write(empty);
+        process.exit(3);
+    }
+    const readings = await Promise.all(workers.map(async (worker)=>({
+            worker,
+            code: await read(worker)
+        })));
+    const drift = codeDrift(expected, readings);
+    const refusal = describeCodeDrift(drift, {
+        when,
+        bareMetalUrls,
+        sourceDirty: workerSourceDirty(sourceDir)
+    });
+    if (!refusal) return void process.stdout.write(`Fleet runs this checkout (worker code ${expected}, ${drift.unreachable.length ? `${readings.length - drift.unreachable.length} of ` : ""}${readings.length} worker(s) checked).\n`);
+    process.stderr.write(refusal);
+    process.exit(3);
+}
+const expectedWorkerCode = ()=>codeVersion();
+async function assertFleetRunsThisCheckout(workers, options = {}) {
+    return assertWorkersServe(expectedWorkerCode(), workers, {
+        ...options,
+        sourceDir: workerSourceDir()
+    });
+}
+export { assertFleetRunsThisCheckout, codeDrift, describeCodeDrift, describeEmptyPool, expectedWorkerCode, readWorkerCode, remedyLines, workerSourceDirty };

package/dist/worker-health.d.mts

@@ -53,4 +53,3 @@ export function assessWorker(vitals: {
     reason: string | null;
     recoveryShare: number | null;
 };
-//# sourceMappingURL=worker-health.d.mts.map

package/dist/worker-health.mjs

@@ -1,73 +1,28 @@
-// @ts-check
-/**
- * Is a worker healthy, degraded, or unusable — from the vitals it reports.
- *
- * This exists because a guest whose NVDA was broken on **every single capture** sat in the pool at four
- * times the cost of its neighbours and nothing noticed. Measured, same page, same code, same moment:
- *
- *   worker 1   4 captures, 4 recoveries, 0 failures   nvdaStart 19.1s/capture   WALL 122.9s
- *   worker 2   9 captures, 0 recoveries, 0 failures   nvdaStart  0.0s/capture   WALL  40.6s
- *
- * Two things conspired to hide it. The worker's own retry absorbed every fault, so `failures` stayed 0
- * and the run's eviction rule — three consecutive FAILURES — could never fire. And wall-clock time only
- * said "slower", which I twice misattributed to Edge.
- *
- * So degradation is defined on the recovery RATE, not on failures. `recoveries` counts faults the worker
- * papered over for the caller, which makes it the one number that rises while everything still appears
- * to work.
- *
- * **Degraded workers keep taking work.** They are slow, not broken, and pulling one from a three-VM pool
- * costs more throughput than it saves. This mirrors the standard health-check split — a degraded service
- * returns 200 and is *surfaced* rather than restarted, because declaring degraded things unhealthy is how
- * you end up with nothing left to serve (Distributed Systems with Node.js, ch. 4).
- */
-/**
- * Can this worker take a capture right now? ONE definition, because there were four that disagreed.
- *
- * `ready` is about the ENVIRONMENT — Edge resolvable, ForegroundLockTimeout 0, the worker free — and a
- * worker reports `ready: false` while NVDA warms up after a boot, which is normal and self-correcting.
- *
- * The subtlety, and the reason this is `!== false` rather than `=== true`: **a worker predating the
- * field reports neither.** Treating absent as ready keeps an un-redeployed guest working instead of
- * stalling a run against it forever; staleness has its own detector in `npm run worker:code`. The
- * dataset runner got this right and said so. `repeat-capture.mjs` tested `health.ready` for truthiness
- * and `capture-real-pages.mjs` tested `=== true`, so both would have waited out their whole readiness
- * budget against a perfectly good older worker and then blamed the page.
- *
- * @param {{ busy?: boolean, ready?: boolean } | null | undefined} health
- * @returns {boolean}
- */
-export function workerIsUsable(health) {
-    if (!health)
-        return false;
-    return !health.busy && health.ready !== false;
+function workerIsUsable(health) {
+    if (!health) return false;
+    return !health.busy && false !== health.ready;
 }
-/** Below this many captures the rate is noise: one recovery out of one capture is not a pattern. */
 const MIN_CAPTURES_TO_JUDGE = 4;
-/** Above this share of captures needing a recovery, the guest is not merely unlucky. */
 const DEGRADED_RECOVERY_SHARE = 0.5;
-/**
- * @param {{ captures?: number, recoveries?: number, failures?: number } | null | undefined} vitals
- * @returns {{ degraded: boolean, reason: string | null, recoveryShare: number | null }}
- */
-export function assessWorker(vitals) {
+function assessWorker(vitals) {
     const captures = vitals?.captures ?? 0;
     const recoveries = vitals?.recoveries ?? 0;
-    // Recoveries are counted per capture served, so the share can exceed nothing sensible above 1.
     const attempted = captures + (vitals?.failures ?? 0);
-    if (attempted < MIN_CAPTURES_TO_JUDGE) {
-        return { degraded: false, reason: null, recoveryShare: null };
-    }
+    if (attempted < MIN_CAPTURES_TO_JUDGE) return {
+        degraded: false,
+        reason: null,
+        recoveryShare: null
+    };
     const recoveryShare = recoveries / attempted;
-    if (recoveryShare <= DEGRADED_RECOVERY_SHARE) {
-        return { degraded: false, reason: null, recoveryShare };
-    }
+    if (recoveryShare <= DEGRADED_RECOVERY_SHARE) return {
+        degraded: false,
+        reason: null,
+        recoveryShare
+    };
     return {
         degraded: true,
         recoveryShare,
-        reason: `${recoveries} of ${attempted} captures needed a screen-reader recovery ` +
-            `(${Math.round(recoveryShare * 100)}%) — this guest's NVDA is failing and every capture pays for it. ` +
-            "Reinstall NVDA or re-provision it (docs/nvda-worker-runbook.md); it is still serving, just slowly.",
+        reason: `${recoveries} of ${attempted} captures needed a screen-reader recovery (${Math.round(100 * recoveryShare)}%) — this guest's NVDA is failing and every capture pays for it. Reinstall NVDA or re-provision it (docs/nvda-worker-runbook.md); it is still serving, just slowly.`
     };
 }
-//# sourceMappingURL=worker-health.mjs.map
+export { assessWorker, workerIsUsable };

package/dist/worker-http.d.mts

@@ -100,4 +100,3 @@ export const CAPTURE_CLIENT_TIMEOUT_MS: 620000;
  * the server's call and passed with this hook DELETED — found by mutation, not by reading.
  */
 export const KEEPALIVE_DELAY_MS: 15000;
-//# sourceMappingURL=worker-http.d.mts.map