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

package/README.md

@@ -1,3 +1,95 @@
-# @a11ign/screenreader-fleet
+# `@a11ign/screenreader-fleet`
 
-Reserved name. Real releases are published from https://github.com/a11ign/screenreader-fleet.
+Host-side lifecycle, health and capacity for a fleet of Windows NVDA capture workers. Runs on the machine that
+*drives* the workers — no NVDA, no guidepup, no Windows.
+
+```bash
+npm install @a11ign/screenreader-fleet
+npx a11ign-doctor          # can I run right now? every check names its own fix
+```
+
+```js
+import { leaseWorker } from "@a11ign/screenreader-fleet";
+
+const lease = await leaseWorker({ after: "stop" });
+try {
+  // ... capture against lease.url
+} finally {
+  await lease.release();   // puts the VM back the way it was found
+}
+```
+
+## A lease, not a lifecycle you own
+
+`leaseWorker` decides what to capture against in priority order: an explicit worker you named, then
+`inventory.yml`'s bare-metal fleet if one is declared, then a **local UTM VM (deprecated — "The UTM is
+deprecated, that was a testing thing," repository owner, 2026-09-05)**, then the historical
+`http://localhost:8765` default. Reaching the UTM branch prints a warning naming `fleet:*` as the
+replacement; it is not refused outright because some machines still only have a UTM guest to reach, and
+deleting the ~2,460 lines that manage it is a separate decision from warning about it. Only the VM case
+has a lifecycle to manage — a bare-metal box is always on — so `release()` is a no-op for every other
+source. It starts what is missing and **puts a VM back as it found it**: one that was already running is
+left running, a stopped one is stopped again. A long run must not shut down something another run is
+using.
+
+**Stopped worker VMs are the correct resting state.** `all stopped` is a READY state, not a fault — `a11ign-doctor`
+says so explicitly, because "go and start a worker" is the wrong instinct and costs time.
+
+**The local UTM VM is not how this project's own corpus is captured.** It is the DEPRECATED default for a
+solo contributor with no bare-metal fleet, kept working precisely because it is still the right path for
+that case — this repo's own corpus is captured on ten bare-metal workers driven by
+`inventory.yml`, which `leaseWorker` checks first. If you are consuming this package standalone with your
+own Windows box, the VM lifecycle below still applies to you exactly as written.
+
+## Capacity is measured, never assumed
+
+```js
+import { availableHostMemoryMb, workersHostCanRun } from "@a11ign/screenreader-fleet/capacity";
+```
+
+A worker VM costs the host **~8 GB**, not the 4 GB it is configured with — QEMU's overhead on top of guest RAM
+that Windows dirties and never returns. So three do not fit on a 36 GB Mac, and over-committing does not merely
+slow a run: the same page took 44.5 s with three guests up and 27.4 s with one, and the starved guests produced
+"NVDA is running but not speaking" failures and `/health` blackouts. From outside that reads as *the workers are
+degrading*, which is how it was misdiagnosed for a day.
+
+Two rules follow, both learned the hard way:
+
+- **Never `os.freemem()`.** It reported 402 MB on a host with ~12 GB to give, because macOS counts compressed
+  and inactive pages as used. The reading comes from `vm_stat`.
+- **`vm_stat` is distorted by the very condition it must detect** — a swapped-out guest's pages count as
+  available, so the estimate *rises* as the host gets sicker; it advertised 13.7 GB free while two guests were
+  starving. The cap is therefore the lower of that estimate and a ceiling derived from physical RAM, which no
+  feedback loop can move.
+
+## Health: watch `recoveries`, not failures
+
+```js
+import { assessWorker } from "@a11ign/screenreader-fleet/health";
+```
+
+The worst worker fault this fleet has had produced **zero failures**. One guest's NVDA went mute on 4 of 4
+captures, the worker's own retry absorbed every one, so every capture succeeded and the eviction rule — three
+consecutive *failures* — could never fire. The only symptom was 122.9 s per capture against a healthy peer's
+40.6 s.
+
+`vitals.recoveries` counts the faults a worker papered over. It is the number that rises while everything still
+appears to work.
+
+## The provisioning scripts ship with the package
+
+```js
+import { fleetScriptPaths } from "@a11ign/screenreader-fleet";
+fleetScriptPaths().workerCtl;   // absolute path to worker-ctl.sh
+```
+
+They are shell, so a consumer spawns them, and they are resolved from the module rather than the cwd — a
+cwd-relative path is right exactly when the cwd is the repo root. Getting that wrong is not subtle: during this
+extraction `doctor` reported "no local VM tooling here" on a host with three registered VMs.
+
+**macOS + UTM** is what the VM lifecycle assumes. `utmctl` needs the UTM app running, or a perfectly healthy VM
+reports its state as `unknown`; and UTM cannot suspend a guest with an emulated NVMe device, so stop/start is
+the only real lifecycle — a cold boot to ready is 15–45 s, which is fine.
+
+Not exported: `host-metrics`, `worker-stats`, `fleet-consistency`. They are measurement internals whose shapes
+change every time something new gets measured.

package/dist/capture-client.d.mts

@@ -0,0 +1,49 @@
+/**
+ * Ask the worker for a capture we already paid for but may not have received.
+ *
+ * Returns null when there is nothing to recover — a worker predating the endpoint (404 from the router's
+ * fallback), one that restarted and lost its memory, or a capture still running. Null means "capture
+ * again", which is what every client did before the endpoint existed.
+ *
+ * A recovered FAILURE is RETURNED rather than swallowed, so a replay is indistinguishable from the original
+ * response. That keeps the worker's `fault` code — the thing it worked out, and which we would otherwise
+ * replace with "no answer" — and lets the caller's own classification decide, as it would have all along.
+ * (The dataset runner's version THREW here, because it wrapped a `fetchJson` that rejects on non-2xx;
+ * `requestJson` resolves instead, so the same intent is expressed by returning the response.)
+ *
+ * @param {string} worker @param {string} captureId
+ */
+export function recoverCapture(worker: string, captureId: string): Promise<{
+    status: number;
+    ok: boolean;
+    text: string;
+    json: any;
+} | null>;
+/**
+ * POST a capture, and on a TRANSIENT failure ask whether it actually finished before paying again.
+ *
+ * Returns what `requestJson` returns — `{status, ok, text, json}` — plus `recovered`, so this is a
+ * drop-in at the call sites that already POST `/capture` and read `response.ok` / `body.error`. Keeping
+ * their own classification is deliberate: a shared client that also decided what counts as a failure would
+ * be changing ten behaviours at once while claiming to change one.
+ *
+ * `requestJson` RESOLVES on an HTTP error and REJECTS only on a transport one, so the `catch` below is
+ * reached exactly by the case this exists for — `ETIMEDOUT`, `ECONNRESET`, a socket dying mid-answer.
+ *
+ * `waitForWorker` is deliberately NOT called here. The dataset runner has one, tuned to a corpus run's
+ * tolerance for a box gone for minutes; a gate wants an answer quickly. So this asks once, immediately,
+ * and a caller that wants to wait first passes `beforeRecovery`.
+ *
+ * @param {{ worker: string, body: object, timeoutMs?: number,
+ *           beforeRecovery?: (error: unknown) => Promise<void>,
+ *           onProgress?: (progress: object) => void, sync?: boolean }} request
+ */
+export function captureTolerantly({ worker, body, timeoutMs, beforeRecovery, onProgress, sync }: {
+    worker: string;
+    body: object;
+    timeoutMs?: number;
+    beforeRecovery?: (error: unknown) => Promise<void>;
+    onProgress?: (progress: object) => void;
+    sync?: boolean;
+}): Promise<any>;
+//# sourceMappingURL=capture-client.d.mts.map

package/dist/capture-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-client.d.mts","sourceRoot":"","sources":["../src/capture-client.mjs"],"names":[],"mappings":"AAkFA;;;;;;;;;;;;;;GAcG;AACH,uCAFW,MAAM,aAAiB,MAAM;;;;;UAwBvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,iGAJW;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACjD,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,gBAwBrE"}

package/dist/capture-client.mjs

@@ -0,0 +1,352 @@
+// @ts-check
+/**
+ * ONE CAPTURE, TOLERANT OF THE SOCKET DYING UNDER IT — and the only place that knows how.
+ *
+ * The worker has stored completed captures under a caller-chosen id since the `captureId` work landed:
+ * `POST /capture {captureId}` then `GET /capture/<id>` returns the original response verbatim, so a lost
+ * socket costs a round trip instead of 12-520 s of real screen-reader work. That is the idempotency-key
+ * shape, for the reason payment APIs use it.
+ *
+ * TEN CLIENTS POST TO `/capture`. ONE USED THE RECOVERY. This repo's most expensive recurring shape is a
+ * remedy applied at one call site when the behaviour reaches several — `anchorToTop`, `ensureSpeechChannel`,
+ * `waitForAnnouncement`, `refreshBrowseBuffer` — and this is that shape at its largest here.
+ *
+ * MEASURED COST, 2026-08-28: `gate:stability` lost THREE canaries to `FAILED read ETIMEDOUT` across two
+ * runs — `filter-status-silent-solar/bad` on one box, then `form-error-silent/bad` and
+ * `disclosure-state-silent/good` on two others. Different pages, different machines, so it is the transport
+ * and not either. Each one turned the determinism gate INCONCLUSIVE while the capture it lost had already
+ * COMPLETED and was sitting in the worker's store, which is precisely what the store exists to serve back.
+ *
+ * The worker is bare metal on real Ethernet with real power management, which is why this arrived now: on
+ * three VMs sharing one Mac the socket was a virtual bridge and effectively lossless.
+ *
+ * MOVED HERE from `packages/lab/src/capture/capture-client.mjs` — architecture-audit.md §5, item 6: the
+ * product CLI sent no `captureId` at all, so this recovery path was unavailable to the one caller that is
+ * a user. `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 — so this is the
+ * seventh capture client and the last one, not an eighth copy of the recovery logic beside it.
+ */
+import { randomUUID } from "node:crypto";
+import { requestJson, CAPTURE_CLIENT_TIMEOUT_MS } from "./worker-http.mjs";
+import { isTransient } from "./transient-fault.mjs";
+/** Long enough to survive a worker that is briefly busy, short enough not to double a capture's cost. */
+const RECOVERY_TIMEOUT_MS = 30_000;
+/**
+ * THE ESCAPE HATCH BACK TO THE SYNCHRONOUS PATH, and it says so when used.
+ *
+ * Kept because a protocol change wants a way back that does not need a deploy, and removed only once a
+ * corpus run has gone through the async path end to end.
+ */
+/**
+ * READ PER CALL, NOT AT MODULE LOAD, and the difference is not stylistic. A value fixed at import is one
+ * no test can vary and no process can change -- `fileProductVersion` memoised Edge's version that way and
+ * stamped five days of captures with a build they were not taken under. So it is a PARAMETER with an env
+ * default, which also lets both paths be driven from one test file.
+ */
+const syncByEnv = () => process.env.A11Y_SYNC_CAPTURE === "1";
+/** Accepting a capture is a handshake, not the work: it either answers in seconds or the box is unwell. */
+const ACCEPT_TIMEOUT_MS = 30_000;
+/** Between polls. Short enough that a 12 s capture is not padded, long enough not to hammer a busy box. */
+const POLL_MS = 2_000;
+/** A read of an array already in memory; if this cannot answer, the guest's event loop is blocked. */
+const PROGRESS_TIMEOUT_MS = 10_000;
+/**
+ * Consecutive failed POLLS before giving up.
+ *
+ * Not one: a single dropped poll is precisely the transport fault this design exists to survive, and
+ * treating it as a failed capture would reintroduce the defect through the new door. Not unbounded either,
+ * or a box that has genuinely gone would be waited on for the whole capture budget.
+ */
+const MAX_POLL_FAILURES = 5;
+const sleep = (/** @type {number} */ ms) => new Promise((r) => setTimeout(r, ms));
+const base = (/** @type {string} */ worker) => String(worker).replace(/\/$/, "");
+/**
+ * What is left of the OPERATION'S budget, never negative — architecture-audit.md §14.5.
+ *
+ * Every wait inside the poll loop used its own fixed constant regardless of how little of `timeoutMs`
+ * remained: a two-second sleep, a ten-second progress read and a thirty-second result read, none clipped
+ * to what was actually left. A caller asking for `timeoutMs: 20` measured 2,012 ms before an answer,
+ * because the unconditional sleep ran to completion first regardless of the deadline it was about to blow
+ * past. This is the one place that number is computed, so every wait below shares one clock.
+ *
+ * @param {number} deadline
+ */
+const remaining = (deadline) => Math.max(0, deadline - Date.now());
+/**
+ * Ask the worker for a capture we already paid for but may not have received.
+ *
+ * Returns null when there is nothing to recover — a worker predating the endpoint (404 from the router's
+ * fallback), one that restarted and lost its memory, or a capture still running. Null means "capture
+ * again", which is what every client did before the endpoint existed.
+ *
+ * A recovered FAILURE is RETURNED rather than swallowed, so a replay is indistinguishable from the original
+ * response. That keeps the worker's `fault` code — the thing it worked out, and which we would otherwise
+ * replace with "no answer" — and lets the caller's own classification decide, as it would have all along.
+ * (The dataset runner's version THREW here, because it wrapped a `fetchJson` that rejects on non-2xx;
+ * `requestJson` resolves instead, so the same intent is expressed by returning the response.)
+ *
+ * @param {string} worker @param {string} captureId
+ */
+export async function recoverCapture(worker, captureId) {
+    let response;
+    try {
+        response = await requestJson(`${base(worker)}/capture/${captureId}`, { timeoutMs: RECOVERY_TIMEOUT_MS });
+    }
+    catch (error) {
+        // The worker went away again mid-question. Not worth a second round trip; the caller falls back to
+        // capturing, which is what it would have done anyway.
+        void error;
+        return null;
+    }
+    // 500 IS AN ANSWER, NOT AN OBSTACLE: it is the worker's own account of a failed capture, carrying the
+    // `fault` code it worked out. Returning it lets the caller's existing classification decide, exactly as
+    // it would have on the original response -- and losing it replaces a diagnosis with "no answer", which
+    // this project has repeatedly misread as a dead machine.
+    if (response.status === 500)
+        return response;
+    // 404 from the endpoint, or from an older worker's router fallback: nothing kept, so capture again.
+    if (response.status === 404)
+        return null;
+    if (!response.ok)
+        return null;
+    // "Still running" and "never heard of it" are DIFFERENT ANSWERS and must stay that way. Neither is
+    // recoverable here, but only one means the work is still being done.
+    if ( /** @type {any} */(response.json)?.state === "running")
+        return null;
+    return response;
+}
+/**
+ * POST a capture, and on a TRANSIENT failure ask whether it actually finished before paying again.
+ *
+ * Returns what `requestJson` returns — `{status, ok, text, json}` — plus `recovered`, so this is a
+ * drop-in at the call sites that already POST `/capture` and read `response.ok` / `body.error`. Keeping
+ * their own classification is deliberate: a shared client that also decided what counts as a failure would
+ * be changing ten behaviours at once while claiming to change one.
+ *
+ * `requestJson` RESOLVES on an HTTP error and REJECTS only on a transport one, so the `catch` below is
+ * reached exactly by the case this exists for — `ETIMEDOUT`, `ECONNRESET`, a socket dying mid-answer.
+ *
+ * `waitForWorker` is deliberately NOT called here. The dataset runner has one, tuned to a corpus run's
+ * tolerance for a box gone for minutes; a gate wants an answer quickly. So this asks once, immediately,
+ * and a caller that wants to wait first passes `beforeRecovery`.
+ *
+ * @param {{ worker: string, body: object, timeoutMs?: number,
+ *           beforeRecovery?: (error: unknown) => Promise<void>,
+ *           onProgress?: (progress: object) => void, sync?: boolean }} request
+ */
+export async function captureTolerantly({ worker, body, timeoutMs = CAPTURE_CLIENT_TIMEOUT_MS, beforeRecovery, onProgress, sync = syncByEnv() }) {
+    const captureId = randomUUID();
+    if (!sync)
+        return pollForResult({ worker, body, captureId, timeoutMs, onProgress });
+    // Said once, at the moment it applies, rather than at import: the synchronous form holds a connection
+    // open and silent for the whole capture, which is the shape that lost 9 of 40 responses on this fleet.
+    process.stderr.write("A11Y_SYNC_CAPTURE — holding one connection open for this capture\n");
+    try {
+        return { ...await post(worker, { ...body, captureId }, timeoutMs), recovered: false, pollsSurvived: 0 };
+    }
+    catch (error) {
+        if (!isTransient(error))
+            throw error;
+        // The error is handed over so a caller can SAY why it is waiting. The dataset runner prints
+        // "worker unreachable (<message>)" before a multi-minute wait, and a wait with no stated cause is
+        // one an operator kills.
+        if (beforeRecovery)
+            await beforeRecovery(error);
+        const recovered = await recoverCapture(worker, captureId);
+        // A recovered capture is the ORIGINAL response, returned rather than re-requested. `recovered` travels
+        // with it because a caller measuring the transport needs to know this one cost a round trip and not a
+        // capture -- reporting it as a clean first attempt would hide the very fault this exists for.
+        if (recovered)
+            return { ...recovered, recovered: true, pollsSurvived: 0 };
+        return { ...await post(worker, { ...body, captureId: randomUUID() }, timeoutMs), recovered: false, pollsSurvived: 0 };
+    }
+}
+/**
+ * DISPATCH, THEN POLL — the async path, and the reason this module exists.
+ *
+ * `POST {async:true}` returns 202 in milliseconds, so no connection is held while NVDA reads a page. The
+ * result is collected from the store with `GET /capture/<id>`, which is the endpoint that has existed for
+ * this shape all along and was only ever reached after a failure. **The recovery path is now the normal
+ * path**, which is what stops it rotting: a route that runs only when something breaks is one nobody
+ * notices has broken.
+ *
+ * A dropped poll costs one round trip and is simply retried; the capture is unaffected because nothing is
+ * riding on that socket. That is the whole difference from the synchronous form, where the answer existed
+ * only in the connection that was carrying it.
+ */
+/**
+ * @param {{ worker: string, body: object, captureId: string, timeoutMs: number,
+ *           onProgress?: (progress: object) => void }} request
+ */
+async function pollForResult({ worker, body, captureId, timeoutMs, onProgress }) {
+    const deadline = Date.now() + timeoutMs;
+    let accepted;
+    try {
+        accepted = await post(worker, { ...body, captureId, async: true }, ACCEPT_TIMEOUT_MS);
+    }
+    catch (error) {
+        if (!isTransient(error))
+            throw error;
+        const reconciled = await reconcileLostAcceptance(worker, captureId, deadline);
+        if (reconciled.state === "done")
+            return { ...reconciled.response, recovered: true, pollsSurvived: 0 };
+        if (reconciled.state === "unknown") {
+            // CONFIRMED nothing is running under this id -- only now is a fresh one safe, exactly as the
+            // synchronous escape hatch already does for the identical failure. Minting one on the first sign
+            // of trouble, before asking, is what the audit's remedy forbids: it would risk a second real
+            // capture running under a worker that already accepted the first.
+            return pollForResult({
+                worker, body, captureId: randomUUID(), timeoutMs: Math.max(0, deadline - Date.now()), onProgress,
+            });
+        }
+        // reconciled.state === "running": the worker DID accept it under the id we already hold -- the 202
+        // was lost, not the acceptance. Fall through to the ordinary poll loop below exactly as a received
+        // 202 would have.
+    }
+    // A worker too old to know `async` runs the capture SYNCHRONOUSLY and answers 200 with the result. That
+    // is not an error and must not be retried -- it is the additive-field contract this project uses for
+    // every wire change, and it means a host can be deployed before the fleet.
+    if (accepted && accepted.status !== 202)
+        return { ...accepted, recovered: false, pollsSurvived: 0 };
+    return awaitCompletion({ worker, captureId, deadline, timeoutMs, onProgress });
+}
+/**
+ * ASKING ABOUT A CAPTURE WE MAY OR MAY NOT HAVE STARTED, using the SAME three-way discrimination a
+ * dropped poll already relies on (`pollOnce`) rather than `recoverCapture`, which collapses "running"
+ * and "unknown" into one null and cannot tell them apart -- the exact distinction this exists to make.
+ *
+ * A 404 here is not quite `pollOnce`'s documented "worker restarted mid-capture": no 202 was ever
+ * received, so there is nothing to have restarted AWAY FROM. It means the POST itself never reached the
+ * worker, which is what makes minting a fresh id safe once this returns "unknown" and not before.
+ *
+ * The audit's own caveat applies in principle: "unknown does not prove execution never occurred" if the
+ * result were evicted (§14.4) before this ever asks — but that needs seven OTHER captures to finish on
+ * this worker in the seconds between the lost 202 and this reconciliation, which the worker's own `busy`
+ * gate (one capture at a time) makes impossible while nothing else is running under this id.
+ *
+ * @param {string} worker @param {string} captureId @param {number} deadline
+ * @returns {Promise<{ state: "running" } | { state: "unknown" } | { state: "done", response: any }>}
+ */
+async function reconcileLostAcceptance(worker, captureId, deadline) {
+    let lastError;
+    while (Date.now() < deadline) {
+        const poll = await pollOnce(worker, captureId, Math.min(RECOVERY_TIMEOUT_MS, remaining(deadline)));
+        if (poll.running)
+            return { state: "running" };
+        if (poll.done)
+            return { state: "done", response: poll.response };
+        if (poll.lost)
+            return { state: "unknown" };
+        lastError = poll.error;
+        await sleep(Math.min(POLL_MS, remaining(deadline)));
+    }
+    // Never resolved within the budget: neither confirmed running nor confirmed absent. The ORIGINAL
+    // acceptance failure is the fault that actually occurred, so it is what surfaces -- not a generic
+    // timeout that would hide which of the two things went wrong.
+    throw lastError ?? Object.assign(new Error(`could not confirm capture ${captureId} was accepted, within its remaining budget`), { code: "ETIMEDOUT" });
+}
+/**
+ * DISPATCH, THEN POLL — the async path, and the reason this module exists.
+ *
+ * `POST {async:true}` returns 202 in milliseconds, so no connection is held while NVDA reads a page. The
+ * result is collected from the store with `GET /capture/<id>`, which is the endpoint that has existed for
+ * this shape all along and was only ever reached after a failure. **The recovery path is now the normal
+ * path**, which is what stops it rotting: a route that runs only when something breaks is one nobody
+ * notices has broken.
+ *
+ * A dropped poll costs one round trip and is simply retried; the capture is unaffected because nothing is
+ * riding on that socket. That is the whole difference from the synchronous form, where the answer existed
+ * only in the connection that was carrying it.
+ *
+ * @param {{ worker: string, captureId: string, deadline: number, timeoutMs: number,
+ *           onProgress?: (progress: object) => void }} request
+ */
+async function awaitCompletion({ worker, captureId, deadline, timeoutMs, onProgress }) {
+    let transportFailures = 0;
+    let survived = 0;
+    while (Date.now() < deadline) {
+        // CLIPPED, EACH TIME, TO WHAT IS LEFT — architecture-audit.md §14.5. A budget of 20 ms must not spend
+        // a full 2 s sleeping before it is even allowed to check the clock again.
+        await sleep(Math.min(POLL_MS, remaining(deadline)));
+        if (onProgress)
+            await readProgress(worker, onProgress, Math.min(PROGRESS_TIMEOUT_MS, remaining(deadline)));
+        const poll = await pollOnce(worker, captureId, Math.min(RECOVERY_TIMEOUT_MS, remaining(deadline)));
+        if (poll.done) {
+            // WHAT THE TRANSPORT DID, carried out with the result. Under the synchronous protocol a dropped
+            // response destroyed the capture; here it costs one poll -- but "harmless" and "not happening" are
+            // different facts, and only one of them means the network is healthy. Reporting it keeps the
+            // question answerable after the fix that stopped it mattering.
+            return { ...poll.response, recovered: false, pollsSurvived: survived };
+        }
+        if (poll.lost) {
+            throw Object.assign(new Error(`worker forgot capture ${captureId} after accepting it — it restarted `
+                + "mid-capture, so the work is gone and the case must be re-issued"), { code: "CAPTURE_LOST" });
+        }
+        // A FAILED POLL IS NOT A FAILED CAPTURE, and conflating them would give back the defect this design
+        // removes: the worker is still working, we merely could not ask. Retried until a RUN of them says the
+        // box has gone, rather than on the first one -- a single dropped request is the exact fault this exists
+        // to survive.
+        if (poll.unreachable)
+            survived += 1;
+        transportFailures = poll.unreachable ? transportFailures + 1 : 0;
+        if (transportFailures >= MAX_POLL_FAILURES)
+            throw poll.error;
+    }
+    throw Object.assign(new Error(`capture ${captureId} did not finish within ${timeoutMs} ms`), { code: "ETIMEDOUT" });
+}
+/**
+ * ONE POLL, WITH FOUR DISTINCT ANSWERS — and keeping them apart is the whole job.
+ *
+ *   done        the capture finished (200 or 500); the 500 carries the worker's own fault code
+ *   lost        404 AFTER a 202 acceptance: the worker restarted, the work is gone, re-issue
+ *   running     202; keep waiting
+ *   unreachable we could not ask; the capture is unaffected
+ *
+ * NOT `recoverCapture`, and that is the correction. It SWALLOWS a transport error and returns null, which
+ * is right for its own job — "we already failed, is the result there?" — and wrong here, because it makes
+ * "could not ask" indistinguishable from "still running". Written that way first, and the retry counter
+ * built on it was unreachable: found by mutation, since deleting the retry changed nothing.
+ *
+ * @param {string} worker @param {string} captureId @param {number} [timeoutMs] clipped to the operation's
+ *   remaining budget by the caller — see `remaining()` — so this read cannot outlive the deadline it is
+ *   answering to on its own.
+ */
+async function pollOnce(worker, captureId, timeoutMs = RECOVERY_TIMEOUT_MS) {
+    let response;
+    try {
+        response = await requestJson(`${base(worker)}/capture/${captureId}`, { timeoutMs });
+    }
+    catch (error) {
+        return { unreachable: true, error };
+    }
+    if (response.status === 404)
+        return { lost: true };
+    if (response.status === 202)
+        return { running: true };
+    // 200 and 500 are both ANSWERS: the second is the worker's diagnosis, and losing it would replace a
+    // fault code with silence -- which this project has repeatedly misread as a dead machine.
+    if (response.ok || response.status === 500)
+        return { done: true, response };
+    // Anything else is a worker speaking a protocol we do not know; treat it as unreachable rather than as
+    // an answer, so it is retried and then surfaces with its own status rather than being read as a capture.
+    return { unreachable: true, error: new Error(`unexpected ${response.status} polling ${captureId}`) };
+}
+/** The phase the worker is IN, so a caller can tell a slow capture from a wedged one. */
+async function readProgress(/** @type {string} */ worker, /** @type {(p: object) => void} */ onProgress, 
+/** @type {number} */ timeoutMs = PROGRESS_TIMEOUT_MS) {
+    try {
+        const { json } = await requestJson(`${base(worker)}/progress`, { timeoutMs });
+        if (json && typeof json === "object")
+            onProgress(json);
+    }
+    catch (error) {
+        // Progress is a convenience; failing to read it must never fail a capture that is going fine.
+        void error;
+    }
+}
+/** @param {string} worker @param {object} body @param {number} timeoutMs */
+function post(worker, body, timeoutMs) {
+    // `requestJson` serialises the body and sets the headers; passing a string here would double-encode it.
+    return requestJson(`${base(worker)}/capture`, { method: "POST", body, timeoutMs });
+}
+//# sourceMappingURL=capture-client.mjs.map

package/dist/capture-client.mjs.map

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

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * 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, local, inventory, }?: {
+    named?: typeof configuredWorkers | undefined;
+    local?: typeof localPoolUrls | undefined;
+    inventory?: typeof inventoryWorkerUrls | undefined;
+}): {
+    urls: string[];
+    source: string;
+};
+import { configuredWorkers } from "./fleet-env.mjs";
+/** The local UTM pool, or none — `utmctl` is absent on a machine that never had one. */
+declare function localPoolUrls(): any;
+import { inventoryWorkerUrls } from "./fleet-env.mjs";
+export {};
+//# sourceMappingURL=check-worker-code.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check-worker-code.d.mts","sourceRoot":"","sources":["../src/check-worker-code.mjs"],"names":[],"mappings":";AA0CA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;EAQC;kCAnDyE,iBAAiB;AAqD3F,wFAAwF;AACxF,sCAWC;oCAjEyE,iBAAiB"}