@a11ign/screenreader-fleet 0.5.2 → 0.6.0

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

@@ -0,0 +1,95 @@
+/**
+ * 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
+ *
+ * `resolveExpectedWorkerCode` 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 } from "./code-drift.js";
+/**
+ * The hash every worker is expected to be serving, and WHERE IT CAME FROM. ONE function, asked by `a11ign-worker-code` and by
+ * `assertFleetRunsThisCheckout` alike, so the two cannot be given different hashers again (a11ign/a11ign#3781).
+ *
+ * With a layer clone present it is the CLONE's: the clone's own `code-version.mjs` over the clone's `src/`, which is what
+ * `layerCodeVersion("nvda-worker")` computes for the deploy and the lab, and what a guest is told to be on (`--layer-ref`). Asking the
+ * installed package instead made every worker read stale the first time a guest was deployed at a sha whose `.mjs` differed from the
+ * release, with a remedy ("redeploy") that could not clear it.
+ *
+ * With none it is the installed package's (a11ign/a11ign#3740: the one the package was RELEASED with, `codeVersion()` and no
+ * directory, because the built package's `workerSourceDir()` is `dist/` and holds none of the files a guest runs), and `source` and
+ * `note` say so, so a reading is never silent about which it was.
+ *
+ * ASYNC because the clone's hasher can only be imported dynamically, as `layerCodeVersion` does.
+ *
+ * @param {{ checkoutRoot?: string }} [options]
+ * @returns {Promise<{ code: string, source: "clone" | "installed", sourceDir: string, note: string }>}
+ */
+export declare function resolveExpectedWorkerCode({ checkoutRoot }?: {
+    checkoutRoot?: string;
+}): Promise<{
+    code: string;
+    source: "clone" | "installed";
+    sourceDir: string;
+    note: string;
+}>;
+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[], checkoutRoot?: string}} options
+ */
+export declare function assertFleetRunsThisCheckout(workers: string[], options?: {
+    when?: string;
+    allow?: boolean;
+    read?: (url: string) => Promise<string | null>;
+    bareMetalUrls?: string[];
+    checkoutRoot?: string;
+}): Promise<void>;

package/dist/worker-code-check.mjs

@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { requestJson } from "./worker-http.mjs";
-import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
+import { sandboxGitEnv } from "./src_git-safe-env_ts.mjs";
 const HEALTH_TIMEOUT_MS = 15000;
 function codeDrift(expected, readings) {
     const stale = [];

package/dist/{worker-health.d.mts → worker-health.d.ts}

@@ -36,7 +36,7 @@
  * @param {{ busy?: boolean, ready?: boolean } | null | undefined} health
  * @returns {boolean}
  */
-export function workerIsUsable(health: {
+export declare function workerIsUsable(health: {
     busy?: boolean;
     ready?: boolean;
 } | null | undefined): boolean;
@@ -44,7 +44,7 @@ export function workerIsUsable(health: {
  * @param {{ captures?: number, recoveries?: number, failures?: number } | null | undefined} vitals
  * @returns {{ degraded: boolean, reason: string | null, recoveryShare: number | null }}
  */
-export function assessWorker(vitals: {
+export declare function assessWorker(vitals: {
     captures?: number;
     recoveries?: number;
     failures?: number;

package/dist/{worker-http.d.mts → worker-http.d.ts}

@@ -1,3 +1,52 @@
+/**
+ * How long a CLIENT should wait for a capture. One definition, because five had drifted.
+ *
+ * It must exceed the worker's own hard timeout (`CAPTURE_HARD_TIMEOUT_DEFAULT_MS`, 520 s) or the client
+ * gives up first, and a capture the worker would have completed is reported as a client failure. Five
+ * clients sat at 300 s -- `compare-workers`, `bench-capture`, `evidence-check`, `repeat-capture` and
+ * `capture-real-pages` -- against that 520 s. On the generated corpus nothing noticed, because a 1,338-byte
+ * page finishes in seconds. On REAL pages it silently dropped whatever used its budget, biasing the
+ * real-page corpus toward small simple pages: precisely the axis that corpus exists to add.
+ *
+ * 560,000 -> 620,000 on architecture-audit.md §14.5: `runCapture` (server.mjs) spends up to
+ * `DESKTOP_PREPARE_TIMEOUT_MS` (60 s) clearing the desktop BEFORE the hard-timeout-wrapped capture attempt
+ * even starts, sequentially rather than overlapping it -- so the true worst case a worker can legitimately
+ * take is 60 s + 520 s = 580 s, not 520 s alone. The old 560 s ceiling sat BELOW that, so a real page that
+ * used the full prepare budget and the full capture budget was killed by the CLIENT first and reported as
+ * a client failure for work the worker would have finished -- the exact shape this constant already exists
+ * to prevent, one rung further out. 620,000 keeps the same 40 s margin above the new true worst case that
+ * the original 560,000 kept above 520,000. `budget-ladder.test.ts` asserts the full sequence, not only the
+ * capture attempt inside it.
+ *
+ * Deliberately NOT imported from `@a11ign/screenreader-worker`: this package runs on macOS and Linux and must
+ * not depend on a win32-only one. `budget-ladder.test.ts` enforces the relationship instead, over every
+ * client it DISCOVERS rather than a list -- which is how the 300 s clients stayed invisible while a guard
+ * for exactly this existed and read one hardcoded path.
+ *
+ * `DATASET_CAPTURE_TIMEOUT_MS` still overrides it in the dataset runner, which is the only client that
+ * wants a per-run ceiling.
+ */
+export declare const CAPTURE_CLIENT_TIMEOUT_MS = 620000;
+/**
+ * How long a capture's silent connection may idle before the OS proves it is still there.
+ *
+ * 15 s, and RAISING IT TO 60 s WAS TRIED AND REVERTED — by this file's own test, which refuses a delay
+ * above ~30 s because common NAT idle timeouts start there.
+ *
+ * The reasoning for raising it was that the async path removed the long-lived connection, so nothing needs
+ * an aggressive value. That is true of the async path and FALSE of the `A11Y_SYNC_CAPTURE` escape hatch,
+ * which still holds one socket silent for a whole capture. At 60 s the first probe would fire after the
+ * reap, so the hatch would be unprotected while the constant looked deliberate — a guard weakened for a
+ * reason that did not cover the case it exists for.
+ *
+ * It stays aggressive until item D explains why THIS path reaps in seconds when the literature says
+ * minutes. An unexplained number is not a solved problem.
+ *
+ * EXPORTED so its test can key on the exact value. Node's own HTTP SERVER calls `setKeepAlive(true, 5000)`
+ * on every socket it accepts, so a test that merely looked for "keepalive with a plausible delay" matched
+ * the server's call and passed with this hook DELETED — found by mutation, not by reading.
+ */
+export declare const KEEPALIVE_DELAY_MS = 15000;
 /**
  * A worker address, validated at the BOUNDARY where it enters the program.
  *
@@ -26,7 +75,7 @@
  * @param {{ source?: string }} [options] what to name in the error, e.g. "--worker"
  * @returns {string} the address, trailing slash removed
  */
-export function assertWorkerUrl(value: string | null | undefined, { source }?: {
+export declare function assertWorkerUrl(value: string | null | undefined, { source }?: {
     source?: string;
 }): string;
 /**
@@ -41,7 +90,7 @@ export function assertWorkerUrl(value: string | null | undefined, { source }?: {
  *   strictly worse than saying the value is untyped. The SHAPE that matters is checked where it is
  *   defined: `capture-core`'s `Capture` typedef, and the worker's own `/health` contract.
  */
-export function requestJson(url: string, { method, body, timeoutMs }?: {
+export declare function requestJson(url: string, { method, body, timeoutMs }?: {
     method?: string;
     body?: unknown;
     timeoutMs?: number;
@@ -51,52 +100,3 @@ export function requestJson(url: string, { method, body, timeoutMs }?: {
     text: string;
     json: any;
 }>;
-/**
- * How long a CLIENT should wait for a capture. One definition, because five had drifted.
- *
- * It must exceed the worker's own hard timeout (`CAPTURE_HARD_TIMEOUT_DEFAULT_MS`, 520 s) or the client
- * gives up first, and a capture the worker would have completed is reported as a client failure. Five
- * clients sat at 300 s -- `compare-workers`, `bench-capture`, `evidence-check`, `repeat-capture` and
- * `capture-real-pages` -- against that 520 s. On the generated corpus nothing noticed, because a 1,338-byte
- * page finishes in seconds. On REAL pages it silently dropped whatever used its budget, biasing the
- * real-page corpus toward small simple pages: precisely the axis that corpus exists to add.
- *
- * 560,000 -> 620,000 on architecture-audit.md §14.5: `runCapture` (server.mjs) spends up to
- * `DESKTOP_PREPARE_TIMEOUT_MS` (60 s) clearing the desktop BEFORE the hard-timeout-wrapped capture attempt
- * even starts, sequentially rather than overlapping it -- so the true worst case a worker can legitimately
- * take is 60 s + 520 s = 580 s, not 520 s alone. The old 560 s ceiling sat BELOW that, so a real page that
- * used the full prepare budget and the full capture budget was killed by the CLIENT first and reported as
- * a client failure for work the worker would have finished -- the exact shape this constant already exists
- * to prevent, one rung further out. 620,000 keeps the same 40 s margin above the new true worst case that
- * the original 560,000 kept above 520,000. `budget-ladder.test.ts` asserts the full sequence, not only the
- * capture attempt inside it.
- *
- * Deliberately NOT imported from `@a11ign/screenreader-worker`: this package runs on macOS and Linux and must
- * not depend on a win32-only one. `budget-ladder.test.ts` enforces the relationship instead, over every
- * client it DISCOVERS rather than a list -- which is how the 300 s clients stayed invisible while a guard
- * for exactly this existed and read one hardcoded path.
- *
- * `DATASET_CAPTURE_TIMEOUT_MS` still overrides it in the dataset runner, which is the only client that
- * wants a per-run ceiling.
- */
-export const CAPTURE_CLIENT_TIMEOUT_MS: 620000;
-/**
- * How long a capture's silent connection may idle before the OS proves it is still there.
- *
- * 15 s, and RAISING IT TO 60 s WAS TRIED AND REVERTED — by this file's own test, which refuses a delay
- * above ~30 s because common NAT idle timeouts start there.
- *
- * The reasoning for raising it was that the async path removed the long-lived connection, so nothing needs
- * an aggressive value. That is true of the async path and FALSE of the `A11Y_SYNC_CAPTURE` escape hatch,
- * which still holds one socket silent for a whole capture. At 60 s the first probe would fire after the
- * reap, so the hatch would be unprotected while the constant looked deliberate — a guard weakened for a
- * reason that did not cover the case it exists for.
- *
- * It stays aggressive until item D explains why THIS path reaps in seconds when the literature says
- * minutes. An unexplained number is not a solved problem.
- *
- * EXPORTED so its test can key on the exact value. Node's own HTTP SERVER calls `setKeepAlive(true, 5000)`
- * on every socket it accepts, so a test that merely looked for "keepalive with a plausible delay" matched
- * the server's call and passed with this hook DELETED — found by mutation, not by reading.
- */
-export const KEEPALIVE_DELAY_MS: 15000;

package/dist/{worker-stats.d.mts → worker-stats.d.ts}

@@ -1,6 +1,42 @@
+/**
+ * Robust statistics for comparing workers, and an explicit refusal to call a difference real when the
+ * samples do not support it.
+ *
+ * This module exists because of a specific, repeated mistake: concluding from one measurement. Over one
+ * session a 2x difference between two guests was attributed, in turn, to the display being blanked, to
+ * in-memory accumulation, to background CPU, to Edge's launch, to the Edge profile, to the sweep, and to
+ * Edge's startup boost. Every one of those was a single measurement, and every one was wrong.
+ *
+ * Two things caused that, and both are fixed here rather than in a comment.
+ *
+ * **Means lied.** One 63 s outlier in an eight-run sample moved the mean by 5 s and made a healthy
+ * worker look broken. Capture time has a long right tail by nature — a mute screen reader costs ~86 s
+ * against a normal ~12 s — so the mean measures how often the tail was hit, not what a capture costs.
+ * The median and the interquartile range do not move when one run goes bad.
+ *
+ * **Sequential sampling confounded.** Measuring worker A for five minutes and then worker B for five
+ * minutes attributes any drift in the host during those ten minutes to the difference between the
+ * workers. Interleaving round-robin makes drift common to all of them.
+ */
+/**
+ * One worker's samples, summarised.
+ *
+ * Named as a typedef rather than repeated inline because four functions pass it around, and this module's
+ * whole purpose is refusing to claim a difference the samples do not support — so `q1`, `q3` and `iqr`
+ * travelling together, as one thing with one name, is the point rather than a formality.
+ */
+export type Summary = {
+    n: number;
+    median: number;
+    q1: number;
+    q3: number;
+    iqr: number;
+    min: number;
+    max: number;
+};
 /** Linear-interpolated quantile. Fine for the sample sizes here and has no dependencies. */
 /** @param {number[]} values @param {number} q @returns {number|null} */
-export function quantile(values: number[], q: number): number | null;
+export declare function quantile(values: number[], q: number): number | null;
 /**
  * The shape of one worker's samples.
  *
@@ -11,7 +47,7 @@ export function quantile(values: number[], q: number): number | null;
  * @param {number[]} values
  * @returns {Summary|null}
  */
-export function describe(values: number[]): Summary | null;
+export declare function describe(values: number[]): Summary | null;
 /**
  * Compare workers and say, conservatively, whether a difference is supported.
  *
@@ -25,7 +61,7 @@ export function describe(values: number[]): Summary | null;
  * @returns {{ stats: Record<string, Summary>, slowest: string|null, fastest: string|null,
  *             distinguishable: boolean, verdict: string }}
  */
-export function compareWorkers(samplesByWorker: Record<string, number[]>): {
+export declare function compareWorkers(samplesByWorker: Record<string, number[]>): {
     stats: Record<string, Summary>;
     slowest: string | null;
     fastest: string | null;
@@ -43,23 +79,7 @@ export function compareWorkers(samplesByWorker: Record<string, number[]>): {
  * @returns {Record<string, number | null>} null where the worker captured nothing — "no idea", which
  *   must not be confused with a rate of zero ("perfectly reliable").
  */
-export function recoveryRates(deltas: Record<string, {
+export declare function recoveryRates(deltas: Record<string, {
     recoveries: number;
     captures: number;
 }>): Record<string, number | null>;
-/**
- * One worker's samples, summarised.
- *
- * Named as a typedef rather than repeated inline because four functions pass it around, and this module's
- * whole purpose is refusing to claim a difference the samples do not support — so `q1`, `q3` and `iqr`
- * travelling together, as one thing with one name, is the point rather than a formality.
- */
-export type Summary = {
-    n: number;
-    median: number;
-    q1: number;
-    q3: number;
-    iqr: number;
-    min: number;
-    max: number;
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11ign/screenreader-fleet",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Host-side lifecycle, health and capacity for a fleet of Windows NVDA capture workers: lease one, judge whether it is degrading, and know how many the host can afford.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -10,47 +10,47 @@
       "default": "./dist/index.mjs"
     },
     "./health": {
-      "types": "./dist/worker-health.d.mts",
+      "types": "./dist/worker-health.d.ts",
       "default": "./dist/worker-health.mjs"
     },
     "./capacity": {
-      "types": "./dist/host-capacity.d.mts",
+      "types": "./dist/host-capacity.d.ts",
       "default": "./dist/host-capacity.mjs"
     },
     "./probe-outcome": {
-      "types": "./dist/probe-outcome.d.mts",
+      "types": "./dist/probe-outcome.d.ts",
       "default": "./dist/probe-outcome.mjs"
     },
     "./worker-http": {
-      "types": "./dist/worker-http.d.mts",
+      "types": "./dist/worker-http.d.ts",
       "default": "./dist/worker-http.mjs"
     },
     "./cli-flags": {
-      "types": "./dist/cli-flags.d.mts",
+      "types": "./dist/cli-flags.d.ts",
       "default": "./dist/cli-flags.mjs"
     },
     "./transient-fault": {
-      "types": "./dist/transient-fault.d.mts",
+      "types": "./dist/transient-fault.d.ts",
       "default": "./dist/transient-fault.mjs"
     },
     "./capture-client": {
-      "types": "./dist/capture-client.d.mts",
+      "types": "./dist/capture-client.d.ts",
       "default": "./dist/capture-client.mjs"
     },
     "./host-address": {
-      "types": "./dist/host-address.d.mts",
+      "types": "./dist/host-address.d.ts",
       "default": "./dist/host-address.mjs"
     },
     "./fleet-env": {
-      "types": "./dist/fleet-env.d.mts",
+      "types": "./dist/fleet-env.d.ts",
       "default": "./dist/fleet-env.mjs"
     },
     "./fleet-consistency": {
-      "types": "./dist/fleet-consistency.d.mts",
+      "types": "./dist/fleet-consistency.d.ts",
       "default": "./dist/fleet-consistency.mjs"
     },
     "./worker-code-check": {
-      "types": "./dist/worker-code-check.d.mts",
+      "types": "./dist/worker-code-check.d.ts",
       "default": "./dist/worker-code-check.mjs"
     }
   },
@@ -73,9 +73,18 @@
   },
   "devDependencies": {
     "@a11ign/evidence": "0.1.0",
-    "@a11ign/toolchain": "0.1.4",
+    "@a11ign/toolchain": "0.3.1",
+    "@changesets/cli": "3.0.3",
+    "@eslint/js": "^10.0.1",
     "@rslib/core": "1.0.3",
+    "@rstest/core": "0.12.3",
+    "@types/node": "^26.6.4",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "jiti": "^2.7.0",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
     "yaml": "^2.9.1"
   },
   "engines": {
@@ -84,11 +93,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/a11ign/screenreader-fleet.git",
-    "directory": "packages/worker-fleet"
-  },
   "homepage": "https://github.com/a11ign/screenreader-fleet",
   "keywords": [
     "accessibility",
@@ -99,7 +103,14 @@
     "utm",
     "vm"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a11ign/screenreader-fleet.git"
+  },
   "scripts": {
-    "build": "rslib build"
+    "build": "rslib build",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "rstest run"
   }
 }

package/src/local-worker/build-vm.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Build a local NVDA capture worker VM on Apple Silicon, unattended.
 #
-#   ./packages/worker-fleet/src/local-worker/build-vm.sh /path/to/Win11_ARM64.iso
+#   ./src/local-worker/build-vm.sh /path/to/Win11_ARM64.iso
 #
 # Produces a self-contained VM directory (default ~/a11y-worker-vm) holding the disk
 # image, UEFI vars and a run script. That directory IS the portable artifact: copy it
@@ -40,7 +40,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 die() { echo "error: $*" >&2; exit 1; }
 info() { echo "==> $*"; }
 
-[ -n "$WIN_ISO" ] || die "usage: $0 <windows-11-arm64.iso>   (build one with CrystalFetch, or packages/worker-fleet/src/local-worker/fetch-windows-iso.sh)"
+[ -n "$WIN_ISO" ] || die "usage: $0 <windows-11-arm64.iso>   (build one with CrystalFetch, or src/local-worker/fetch-windows-iso.sh)"
 [ -f "$WIN_ISO" ] || die "not found: $WIN_ISO"
 command -v qemu-system-aarch64 >/dev/null || die "qemu missing: brew install qemu"
 command -v qemu-img >/dev/null || die "qemu-img missing: brew install qemu"

package/src/local-worker/clone-worker.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Clone the local NVDA worker VM into an additional, independent worker.
 #
-#   ./packages/worker-fleet/src/local-worker/clone-worker.sh [new-name]      # default: a11y-worker-2
+#   ./src/local-worker/clone-worker.sh [new-name]      # default: a11y-worker-2
 #
 # One worker serves one capture at a time by design (one desktop, one foreground window, one
 # NVDA), so throughput scales by running more of them. On APFS the clone is copy-on-write, so

package/src/local-worker/create-utm-vm.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Create the NVDA worker VM in UTM, fully from the CLI. No GUI clicking.
 #
-#   ./packages/worker-fleet/src/local-worker/create-utm-vm.sh <windows-arm64.iso> [support.iso]
+#   ./src/local-worker/create-utm-vm.sh <windows-arm64.iso> [support.iso]
 #
 # Why UTM rather than plain QEMU: homebrew QEMU + HVF cannot boot Windows 11 ARM64 on
 # Apple Silicon (open upstream bug, https://gitlab.com/qemu-project/qemu/-/issues/2893,

package/src/local-worker/fetch-windows-iso.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Build an official Windows 11 ARM64 ISO on macOS, from the CLI.
 #
-#   ./packages/worker-fleet/src/local-worker/fetch-windows-iso.sh [outdir]
+#   ./src/local-worker/fetch-windows-iso.sh [outdir]
 #
 # Microsoft's ARM64 ISO download is a session-token web flow that does not script
 # cleanly, so this uses UUP dump: it fetches the same Unified Update Platform packages
@@ -16,7 +16,7 @@ set -euo pipefail
 
 # architecture-audit.md §8: builds an ISO for a local UTM worker VM, which is deprecated -- "The UTM is
 # deprecated, that was a testing thing." (repository owner, 2026-09-05). Bare-metal boxes install via
-# PXE/autounattend.xml instead — see packages/worker-fleet/src/provisioning/bare-metal/.
+# PXE/autounattend.xml instead — see src/provisioning/bare-metal/.
 echo "DEPRECATED: fetch-windows-iso.sh feeds a local UTM worker VM build. UTM was a testing path and is not the fleet." >&2
 echo "Capture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy." >&2
 
@@ -100,7 +100,7 @@ cd "$OUT_DIR"
 EXISTING="$(ls -t "$OUT_DIR"/*.ISO "$OUT_DIR"/*.iso 2>/dev/null | grep -vi support | head -1 || true)"
 if [ -n "$EXISTING" ] && xorriso -indev "$EXISTING" -report_el_torito plain 2>/dev/null | grep -q UEFI; then
   echo "ISO ready (already built): $EXISTING"
-  echo "Next:  ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$EXISTING\""
+  echo "Next:  ./src/local-worker/create-utm-vm.sh \"$EXISTING\""
   exit 0
 fi
 if [ -n "$EXISTING" ]; then
@@ -234,5 +234,5 @@ fi
 
 echo
 echo "ISO ready: $ISO"
-echo "Next:  ./packages/worker-fleet/src/local-worker/build-vm.sh \"$ISO\""
-echo "       ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$ISO\""
+echo "Next:  ./src/local-worker/build-vm.sh \"$ISO\""
+echo "       ./src/local-worker/create-utm-vm.sh \"$ISO\""

package/src/local-worker/worker-ctl.sh

@@ -3,20 +3,20 @@
 # while you are not capturing.
 #
 #   npm run worker:ctl -- up                           # make it ready (start or resume), wait for /health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pause         # freeze it: ~0.6% CPU, instant resume, RAM not guaranteed
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh stop          # shut it down: nothing held, ~15 s to come back
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh status        # state, resource use, health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh json          # the same, machine-readable (used by the CLI)
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool          # every a11y-worker* VM, as JSON
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-up       # start them all, wait for health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-stop     # shut the whole pool down
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-pause    # freeze the whole pool
+#   ./src/local-worker/worker-ctl.sh pause         # freeze it: ~0.6% CPU, instant resume, RAM not guaranteed
+#   ./src/local-worker/worker-ctl.sh stop          # shut it down: nothing held, ~15 s to come back
+#   ./src/local-worker/worker-ctl.sh status        # state, resource use, health
+#   ./src/local-worker/worker-ctl.sh json          # the same, machine-readable (used by the CLI)
+#   ./src/local-worker/worker-ctl.sh pool          # every a11y-worker* VM, as JSON
+#   ./src/local-worker/worker-ctl.sh pool-up       # start them all, wait for health
+#   ./src/local-worker/worker-ctl.sh pool-stop     # shut the whole pool down
+#   ./src/local-worker/worker-ctl.sh pool-pause    # freeze the whole pool
 #
 # One VM serves one capture at a time, so throughput comes from more VMs. `pool` reports the
 # lot; add one with clone-worker.sh (which handles the duplicate-MAC trap).
 # Operate on a single named VM with A11Y_VM_NAME=a11y-worker-2.
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh idle-pause 15 # watch, then pause after 15 idle minutes
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh idle-stop 30  # same but shut down instead
+#   ./src/local-worker/worker-ctl.sh idle-pause 15 # watch, then pause after 15 idle minutes
+#   ./src/local-worker/worker-ctl.sh idle-stop 30  # same but shut down instead
 #
 # Measured on an M4 Max, 4 vCPU / 8 GB guest. Every number here was observed on this
 # machine; none is an estimate:
@@ -117,7 +117,7 @@ resolve_uuid() {
   [ -n "${A11Y_VM_UUID:-}" ] && { echo "$A11Y_VM_UUID"; return; }
   local matches
   matches="$(utmctl list | awk -v n="$VM_NAME" '$3 == n { print $1 }')"
-  [ -n "$matches" ] || die "no VM named '$VM_NAME' (create one: packages/worker-fleet/src/local-worker/create-utm-vm.sh)"
+  [ -n "$matches" ] || die "no VM named '$VM_NAME' (create one: src/local-worker/create-utm-vm.sh)"
   if [ "$(echo "$matches" | wc -l | tr -d ' ')" -gt 1 ]; then
     # Do NOT guess, and do NOT suggest deleting one. Duplicate registrations under the same
     # name point at the SAME <name>.utm bundle, so `utmctl delete` on either removes that
@@ -317,7 +317,7 @@ case "$CMD" in
         echo "         it is down for 5-10s during a restart; if it persists:" >&2
         echo "         utmctl exec <uuid> --cmd powershell.exe -NoProfile -Command 'Start-ScheduledTask -TaskName a11ysrv'" >&2
       else
-        # `$0` is this file's path, which after M6 is `packages/worker-fleet/src/local-worker/worker-ctl.sh` — true,
+        # `$0` is this file's path, which after M6 is `src/local-worker/worker-ctl.sh` — true,
         # and not what anyone wants to type. The npm alias is the stable way to say it, and it is what the docs use.
         echo "         no guest IP either, so the VM itself is not ready. Try 'npm run worker:ctl -- up'." >&2
       fi

package/src/provisioning/apply-foreground-lock-timeout.ps1

@@ -22,7 +22,7 @@
 # and run-server.cmd (so every worker start re-applies it for that session).
 #
 # Style note: `#` line comments and no param() block, matching the other scripts here --
-# see packages/worker-fleet/src/provisioning/diagnose-nvda-worker.ps1 for why.
+# see src/provisioning/diagnose-nvda-worker.ps1 for why.
 
 $ErrorActionPreference = 'Stop'
 

package/src/provisioning/bootstrap-windows-worker.ps1

@@ -3,7 +3,7 @@
 # Run this ONCE, in the VM, in an elevated PowerShell, right after Windows setup:
 #
 #   Set-ExecutionPolicy -Scope Process Bypass -Force
-#   irm https://raw.githubusercontent.com/a11ign/a11ign/main/packages/worker-fleet/src/provisioning/bootstrap-windows-worker.ps1 | iex
+#   irm https://raw.githubusercontent.com/a11ign/screenreader-fleet/main/src/provisioning/bootstrap-windows-worker.ps1 | iex
 #
 # ...or, if you already have the repo, just run this file. It installs the
 # prerequisites, makes the box reachable over SSH, clones the repo, and then hands

package/src/provisioning/diagnose-nvda-worker.ps1

@@ -4,7 +4,7 @@
 # VERDICT per layer rather than raw dumps, so the first FAIL is the thing to fix.
 # Exits non-zero if any check failed. Copy it over and run it with -File:
 #
-#   scp packages/worker-fleet/src/provisioning/diagnose-nvda-worker.ps1 user@host:C:/Users/user/
+#   scp src/provisioning/diagnose-nvda-worker.ps1 user@host:C:/Users/user/
 #   ssh user@host "powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\user\diagnose-nvda-worker.ps1"
 #
 # Do NOT pipe this to `powershell -Command -`. That mode silently truncated this

package/src/provisioning/stamp-provision-revision.ps1

@@ -47,8 +47,8 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
-# TWO OF THE FIVE PATHS ARE NOT WRITTEN HERE (ADR 0039 item 6d, #3397). Where the worker layer lives is
-# declared in `packages/control/layers.json`, and what its launchers reach outside it in the layer's own
+# THREE OF THE FIVE PATHS ARE NOT WRITTEN HERE (ADR 0039 item 6d, #3397; this repository's own file since the flat layout, a11ign/a11ign#4216).
+# Where the worker layer and this fleet layer live is declared in `packages/control/layers.json`, and what its launchers reach outside it in the layer's own
 # `src/launcher-reach.cmd`, which `run-capture-check.cmd` `call`s. Both are READ, so a path cannot change in
 # the launcher and stay behind in the stamp. A declaration that is absent or does not say THROWS: the stamp
 # must not fall back to a literal, because a literal that was right yesterday is the stamp describing less
@@ -77,7 +77,7 @@ $FOREGROUND_LOCK = Get-DeclaredReach -Name 'FLT'
 # The single definition. Explicit paths rather than a filename search, because `main.yml` is not unique
 # in this repo and a search would silently pick the wrong one.
 $ENVIRONMENT_FILES = @(
-    'packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1'
+    (Get-LayerFile -Layer 'screenreader-fleet' -Relative 'src/provisioning/provision-nvda-worker.ps1')
     $RUN_SERVER
     $FOREGROUND_LOCK
     'packages/control/ansible/roles/worker/defaults/main.yml'

package/dist/source-walk.d.mts

@@ -1,11 +0,0 @@
-/**
- * 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;