@a11ign/screenreader-fleet 0.3.0 → 0.4.1

package/dist/code-drift.d.mts

@@ -31,9 +31,10 @@ export function codeDrift(expected: string, readings: Array<{
 /**
  * Name the deploy route that can actually reach these workers.
  *
- * There are two, they share no mechanism, and the wrong one wastes real time. `worker:deploy` is
- * `utmctl file push` plus a `utmctl` reboot: it takes a VM UUID and fails immediately off macOS, so it
- * cannot touch a physical box. Bare-metal workers are git-cloned and deploy by PULLING, through Ansible.
+ * Only bare-metal workers have one: they are git-cloned and deploy by PULLING, through Ansible. The UTM
+ * route (`a11ign-worker-deploy`, `utmctl file push` plus a `utmctl` reboot, keyed on a VM UUID) is gone: it
+ * pushed from the worker package's `src`, which a built install does not have (#3765), and no fleet box
+ * was ever reachable by it.
  *
  * This printed the utmctl advice unconditionally, including to a fleet of four mini PCs where none of it
  * applies — a tool confidently prescribing a remedy for a different kind of machine. Which kind a worker is

package/dist/compare-workers.d.mts

@@ -1,2 +1,18 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Where the report is written: under the caller's `--runs-dir=`, else the monorepo's own `runs/`, else a refusal naming
+ * the directory and the flag (a11ign/a11ign#3767).
+ *
+ * Resolved from THIS module, never the cwd -- same reason as `doctor.mjs`'s `runsDirFor`, which this duplicates because
+ * this package cannot import `@a11ign/lab`'s canonical `runs/` resolution without a dependency cycle. From an INSTALLED
+ * package `../../../` is `node_modules`, so the default would write the report under the dependency. A supplied
+ * directory need not exist: the report's own `mkdirSync` makes it, which is what asking for one means.
+ * `baseDir` is INJECTED so a test can stand in for either layout.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {string}
+ */
+export function outDirFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): string;

package/dist/compare-workers.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { describeProbe, probeHealth, WORKER_PROBE_TIMEOUT_MS } from "./probe-outcome.mjs";
 import { CAPTURE_CLIENT_TIMEOUT_MS, requestJson } from "./worker-http.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 async function refuseIfBusy(workers, { what, timeoutMs = WORKER_PROBE_TIMEOUT_MS, request }) {
     const states = await Promise.all(workers.map(async (worker)=>{
         const probe = await probeHealth(worker, {
@@ -221,12 +221,22 @@ function diffHost(before, after) {
 }
 refuseUnknownFlags([
     "--rounds=",
-    "--runs="
+    "--runs=",
+    "--runs-dir="
 ], {
     entry: import.meta.url,
     command: "npm run worker:compare"
 });
-const OUT = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/worker-compare");
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const isMonorepoRoot = (root)=>existsSync(resolve(root, "packages")) && existsSync(resolve(root, "package.json"));
+function outDirFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const supplied = flagValue(argv, "runs-dir");
+    if ("" === supplied) throw new Error("worker:compare: --runs-dir= is empty. Pass --runs-dir=<the runs directory>.");
+    if (void 0 !== supplied) return resolve(supplied, "worker-compare");
+    const root = resolve(baseDir, "..", "..", "..");
+    if (isMonorepoRoot(root)) return resolve(root, "runs", "worker-compare");
+    throw new Error(`worker:compare: no runs directory: ${root} is not a checkout (this is an installed package), so there is no runs/ to write worker-compare/ under. Pass --runs-dir=<the runs directory>.`);
+}
 const MS_PER_S = 1000;
 function refuseIfRunsReadonly() {
     if ("1" !== process.env.A11Y_RUNS_READONLY) return;
@@ -234,6 +244,14 @@ function refuseIfRunsReadonly() {
     console.error("  Unset A11Y_RUNS_READONLY to run this for real.");
     process.exit(3);
 }
+function refuseUnlessOutDir() {
+    try {
+        return outDirFor();
+    } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+        return process.exit(2);
+    }
+}
 const compare_workers_args = process.argv.slice(2);
 const runs = Number(compare_workers_args.find((a)=>a.startsWith("--rounds="))?.slice(9) ?? compare_workers_args.find((a)=>a.startsWith("--runs="))?.slice(7) ?? 6);
 const [page, ...compare_workers_workers] = compare_workers_args.filter((a)=>!a.startsWith("--"));
@@ -297,6 +315,7 @@ async function main() {
         process.stderr.write("usage: npm run worker:compare -- <page-url> <worker> <worker> [--rounds=6]\n");
         process.exit(2);
     }
+    const outDir = refuseUnlessOutDir();
     refuseIfRunsReadonly();
     await refuseIfBusy(compare_workers_workers, {
         what: `worker:compare against ${page}`
@@ -334,10 +353,11 @@ async function main() {
         results,
         vitalsBefore,
         vitalsAfter,
-        hostBefore
+        hostBefore,
+        outDir
     });
 }
-function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
+function report({ results, vitalsBefore, vitalsAfter, hostBefore, outDir }) {
     const allPhases = [
         ...new Set(Object.values(results).flatMap((r)=>r.phases.flatMap(Object.keys)))
     ];
@@ -355,10 +375,10 @@ function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
     const { foundations, hostAfter } = reportFoundations({
         hostBefore
     });
-    mkdirSync(OUT, {
+    mkdirSync(outDir, {
         recursive: true
     });
-    writeFileSync(resolve(OUT, "compare.json"), JSON.stringify({
+    writeFileSync(resolve(outDir, "compare.json"), JSON.stringify({
         page: page,
         rounds: runs,
         results,
@@ -368,7 +388,7 @@ function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
         hostBefore,
         hostAfter
     }, null, 2) + "\n", "utf8");
-    process.stdout.write(`\nReport: ${resolve(OUT, "compare.json")}\n`);
+    process.stdout.write(`\nReport: ${resolve(outDir, "compare.json")}\n`);
 }
 function reportWallTime({ results, vitalsBefore, vitalsAfter }) {
     const wallSeconds = Object.fromEntries(compare_workers_workers.map((w)=>[
@@ -458,3 +478,4 @@ function reportFoundations({ hostBefore }) {
     };
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href) await main();
+export { outDirFor };

package/dist/doctor.d.mts

@@ -1,4 +1,21 @@
 #!/usr/bin/env node
+/**
+ * The `runs/` directory doctor reads the dataset from: the caller's `--runs-dir=`, else the monorepo's own `runs/`,
+ * else a refusal naming the directory and the flag (a11ign/a11ign#3767).
+ *
+ * `@a11ign/lab` owns the canonical `runs/` resolution (`packages/lab/src/dataset-paths.mjs`), but `lab` depends on
+ * `worker-fleet`, so this package cannot import it without a cycle: the same computation, duplicated (and again in
+ * `compare-workers.mjs`) rather than left cwd-anchored. From an INSTALLED package `../../../` is `node_modules`, so the
+ * default is taken only when that directory is a checkout; a missing `runs/` inside one is normal (a fresh clone).
+ * `baseDir` is INJECTED so a test can stand in for either layout.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {string}
+ */
+export function runsDirFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): string;
 /**
  * The remedy for a failed local-pool query, as a runnable command plus the advice that is not one.
  *
@@ -198,7 +215,7 @@ export function errorDocument(error: unknown): {
  * The whole run, as a function of its steps and its streams, returning an exit code.
  *
  * @param {{ steps?: (() => unknown)[], json?: boolean, out?: (line: string) => void,
- *           err?: (line: string) => void }} [deps]
+ *           err?: (line: string) => void, runsDir?: () => string }} [deps]
  * @returns {Promise<number>}
  */
 export function doctorRun(deps?: {
@@ -206,6 +223,7 @@ export function doctorRun(deps?: {
     json?: boolean;
     out?: (line: string) => void;
     err?: (line: string) => void;
+    runsDir?: () => string;
 }): Promise<number>;
 export function addCheck(name: string, ok: boolean, detail: string, remedy?: string | null | {
     fix: string | null;

package/dist/doctor.mjs

@@ -10,7 +10,7 @@ import { availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
 import { fleetConsistency, describeMismatches } from "./fleet-consistency.mjs";
 import { fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
 import { namedInventoryWorkers, configuredWorkers } from "./fleet-env.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 import { requestJson } from "./worker-http.mjs";
 import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
 import { assessWorker } from "./worker-health.mjs";
@@ -72,18 +72,32 @@ function shimInvocation(shim, script, args) {
     };
 }
 refuseUnknownFlags([
-    "--json"
+    "--json",
+    "--runs-dir="
 ], {
     entry: import.meta.url,
     command: "pnpm run doctor"
 });
 const doctor_run = promisify(execFile);
 const JSON_OUT = process.argv.includes("--json");
+const REFUSED = 2;
 const WORKERS_ENV = configuredWorkers();
 const PAGES_PORT = Number(process.env.DATASET_PAGES_PORT || 5050);
 const CTL = fleetScriptPaths().workerCtl;
 const SCORER_MODEL_DIR = fileURLToPath(new URL("../../scorer/models/screenreader-scorer/", import.meta.url));
-const DATASET = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/screenreader-dataset");
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const isMonorepoRoot = (root)=>external_node_fs_existsSync(resolve(root, "packages")) && external_node_fs_existsSync(resolve(root, "package.json"));
+function runsDirFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const supplied = flagValue(argv, "runs-dir");
+    if (void 0 !== supplied) {
+        if (external_node_fs_existsSync(supplied)) return resolve(supplied);
+        throw new Error(`doctor: --runs-dir=${supplied} does not exist. Pass --runs-dir=<the runs directory>.`);
+    }
+    const root = resolve(baseDir, "..", "..", "..");
+    if (isMonorepoRoot(root)) return resolve(root, "runs");
+    throw new Error(`doctor: no runs directory: ${root} is not a checkout (this is an installed package), so there is no runs/ to default to. Pass --runs-dir=<the runs directory>.`);
+}
+const datasetDir = ()=>resolve(runsDirFor(), "screenreader-dataset");
 const PROBE_TIMEOUT_MS = 8000;
 const checks = [];
 const GATES = Object.freeze({
@@ -419,7 +433,7 @@ function checkHostCapacity(pool) {
     add("host memory", true, limit >= poolSize ? detail : `${detail}; the rest stay stopped so the run does not swap (override: A11Y_MAX_WORKERS)`);
 }
 async function checkDatasetPages() {
-    const manifestPath = resolve(DATASET, "manifest.json");
+    const manifestPath = resolve(datasetDir(), "manifest.json");
     if (!external_node_fs_existsSync(manifestPath)) return add("dataset", false, "no manifest — the dataset has not been generated", "pnpm run training:generate");
     const sample = JSON.parse(readFileSync(manifestPath, "utf8")).cases?.[0]?.id;
     const probe = sample ? `${sample}/good.html` : "";
@@ -434,7 +448,7 @@ async function checkDatasetPages() {
     }
 }
 function checkRunState() {
-    const progress = resolve(DATASET, "capture-progress.json");
+    const progress = resolve(datasetDir(), "capture-progress.json");
     if (!external_node_fs_existsSync(progress)) return add("run", true, "no capture run recorded");
     const p = JSON.parse(readFileSync(progress, "utf8"));
     if (!p.startedAt) return add("run", true, "no capture run recorded");
@@ -475,7 +489,14 @@ function errorDocument(error) {
     };
 }
 async function doctorRun(deps = {}) {
-    const { steps = DEFAULT_STEPS, json = JSON_OUT, out = console.log, err = console.error } = deps;
+    const { steps = DEFAULT_STEPS, json = JSON_OUT, out = console.log, err = console.error, runsDir = runsDirFor } = deps;
+    try {
+        runsDir();
+    } catch (error) {
+        if (json) out(JSON.stringify(errorDocument(error), null, 2));
+        else err(error.message);
+        return REFUSED;
+    }
     try {
         for (const step of steps)await step();
     } catch (error) {
@@ -511,4 +532,4 @@ async function main() {
     process.exit(await doctorRun());
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ? external_node_fs_realpathSync(process.argv[1]) : "").href) await main();
-export { addCheck, allChecks, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, nextCommand, readyFrom, resolvesToThisCheckout, tscProjectUpToDate, workerControlFix };
+export { addCheck, allChecks, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, nextCommand, readyFrom, resolvesToThisCheckout, runsDirFor, tscProjectUpToDate, workerControlFix };

package/dist/fleet-env.d.mts

@@ -20,6 +20,27 @@ export function configuredWorkers(): Array<{
     name: string;
     url: string;
 }>;
+/**
+ * The two files the COMMAND reads, from the caller or else from the monorepo layout, and a refusal naming the path
+ * and the flag when the one it would read is not there (a11ign/a11ign#3767).
+ *
+ * `INVENTORY` above points into `packages/control`, which an installed `@a11ign/screenreader-fleet` does not have, so
+ * `fleet-env --list` there died on an ENOENT for a path nobody could have guessed. The library functions keep their
+ * default because their answer for "no inventory here" is `[]`, which is supported; a command that prints
+ * `export A11Y_WORKERS=''` for a missing file would be the same silent wrong answer, so it refuses.
+ *
+ * `baseDir` is INJECTED so a test can stand in for either layout without moving a file.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {{ inventoryPath: string, groupVarsPath: string }}
+ */
+export function inventoryPathsFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): {
+    inventoryPath: string;
+    groupVarsPath: string;
+};
 /**
  * Which group each line of the inventory sits in, index-aligned with `text.split(/\r?\n/)`.
  *
@@ -90,7 +111,7 @@ export function portFromGroupVars(text: string): number;
  *
  * Exists so a caller can tell a physical box from a local UTM VM, which decides how it is deployed to and
  * therefore what remedy to print. `worker:code` used to tell every stale worker to run `utmctl` and
- * `npm run worker:deploy`, which CANNOT reach a bare-metal box — it is a `utmctl file push` keyed on a VM
+ * `npm run worker:deploy` (since removed, #3765), which CANNOT reach a bare-metal box — it was a `utmctl file push` keyed on a VM
  * UUID and fails immediately off macOS. Following that advice on this fleet wastes the time it takes to
  * discover the tool was describing a different kind of machine.
  *

package/dist/fleet-env.mjs

@@ -1,9 +1,12 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertWorkerUrl } from "./worker-http.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 refuseUnknownFlags([
-    "--list"
+    "--list",
+    "--inventory=",
+    "--group-vars="
 ], {
     entry: import.meta.url,
     command: "npm run fleet:env"
@@ -19,8 +22,32 @@ function configuredWorkers() {
             url
         }));
 }
-const INVENTORY = fileURLToPath(new URL("../../control/ansible/inventory.yml", import.meta.url));
-const GROUP_VARS = fileURLToPath(new URL("../../control/ansible/group_vars/a11y_workers.yml", import.meta.url));
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const monorepoAnsibleFile = (relative, baseDir = MODULE_DIR)=>resolve(baseDir, "..", "..", "control", "ansible", relative);
+const INVENTORY = monorepoAnsibleFile("inventory.yml");
+const GROUP_VARS = monorepoAnsibleFile("group_vars/a11y_workers.yml");
+function inventoryPathsFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const inventoryPath = existingPath({
+        flag: "inventory",
+        supplied: flagValue(argv, "inventory"),
+        fallback: monorepoAnsibleFile("inventory.yml", baseDir)
+    });
+    const groupVarsPath = existingPath({
+        flag: "group-vars",
+        supplied: flagValue(argv, "group-vars"),
+        fallback: monorepoAnsibleFile("group_vars/a11y_workers.yml", baseDir)
+    });
+    return {
+        inventoryPath,
+        groupVarsPath
+    };
+}
+function existingPath({ flag, supplied, fallback }) {
+    const path = supplied ?? fallback;
+    if (existsSync(path)) return path;
+    const origin = void 0 === supplied ? "the monorepo layout this command defaults to has no such file" : "no such file";
+    throw new Error(`fleet:env: ${path} does not exist (${origin}). Pass --${flag}=<file>.`);
+}
 const HOST_LINE = /^\s*ansible_host\s*:\s*(\S+)\s*$/;
 const SUSPECT = /ansible_host\s*:/;
 const KEY_LINE = /^(\s*)([A-Za-z_][\w.-]*)\s*:/;
@@ -207,8 +234,16 @@ function fleetEnvOutput(text, { port = DEFAULT_WORKER_PORT, mode = "env" } = {})
     };
 }
 function main() {
-    const port = portFromGroupVars(readFileSync(GROUP_VARS, "utf8"));
-    const { stdout, stderr } = fleetEnvOutput(readFileSync(INVENTORY, "utf8"), {
+    let paths;
+    try {
+        paths = inventoryPathsFor();
+    } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const port = portFromGroupVars(readFileSync(paths.groupVarsPath, "utf8"));
+    const { stdout, stderr } = fleetEnvOutput(readFileSync(paths.inventoryPath, "utf8"), {
         port,
         mode: process.argv.includes("--list") ? "list" : "env"
     });
@@ -216,4 +251,4 @@ function main() {
     process.stdout.write(stdout);
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();
-export { DEFAULT_WORKER_PORT, WORKER_GROUP, configuredWorkers, fleetEnvOutput, groupPerLine, hostsOutOfCaptureSet, inventoryWorkerUrls, namedInventoryWorkers, portFromGroupVars, resolveWorkerPool, workerNamesFromInventory, workersFromInventory };
+export { DEFAULT_WORKER_PORT, WORKER_GROUP, configuredWorkers, fleetEnvOutput, groupPerLine, hostsOutOfCaptureSet, inventoryPathsFor, inventoryWorkerUrls, namedInventoryWorkers, portFromGroupVars, resolveWorkerPool, workerNamesFromInventory, workersFromInventory };

package/dist/index.mjs

@@ -4,7 +4,9 @@ import { networkInterfaces } from "node:os";
 import { capacityReason, availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
 import { fleetScriptPaths as fleet_scripts_fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
 import { inventoryWorkerUrls } from "./fleet-env.mjs";
-import { warnUtmDeprecated } from "./src_utm-deprecated_mjs.mjs";
+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`);
+}
 const execFileAsync = promisify(execFile);
 const DEFAULT_WORKER = "http://localhost:8765";
 const CTL = fleet_scripts_fleetScriptPaths().workerCtl;

package/dist/worker-code-check.mjs

@@ -33,8 +33,8 @@ function remedyLines(staleUrls, bareMetalUrls) {
     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");
+    if (physical.length) lines.push(`\n  ${physical.length} in inventory.yml — bare metal, so they deploy by PULLING:`, "    npm run fleet:deploy", "  The UTM push (`a11ign-worker-deploy`) was removed and never reached these.");
+    if (vms.length) lines.push(`\n  ${vms.length} not in inventory.yml — local VM(s). No command deploys to them any more`, "  (`a11ign-worker-deploy` was removed, #3765): re-provision the VM, or declare it in inventory.yml", "  so `npm run fleet:deploy` reaches it.");
     return lines;
 }
 function describeCodeDrift(drift, { when = "before the run", bareMetalUrls = [], sourceDirty = "" } = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11ign/screenreader-fleet",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -58,8 +58,7 @@
     "a11ign-doctor": "./dist/doctor.mjs",
     "a11ign-worker-code": "./dist/check-worker-code.mjs",
     "a11ign-worker-compare": "./dist/compare-workers.mjs",
-    "a11ign-worker-ctl": "./src/local-worker/worker-ctl.sh",
-    "a11ign-worker-deploy": "./dist/deploy-worker.mjs"
+    "a11ign-worker-ctl": "./src/local-worker/worker-ctl.sh"
   },
   "files": [
     "dist",

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

@@ -66,7 +66,7 @@ PORT="${A11Y_PORT:-8765}"
 
 # Accept `--vm=<name>` as well as A11Y_VM_NAME, and accept it in ANY position.
 #
-# `worker:deploy` has always taken `--vm=`, so anyone who has used that reaches for it here too — and this
+# `worker:deploy` (since removed, #3765) always took `--vm=`, so anyone who used that reaches for it here too — and this
 # script silently ignored it, then reported a DIFFERENT VM's state under the name you asked for. Silently,
 # because a stray argument was simply never read. Two tools in one fleet disagreeing about how to name a
 # machine is the kind of paper cut that gets diagnosed as "the guest is broken".

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

@@ -589,7 +589,7 @@ if (-not $handedOff) {
   #   - `workerCode` is recorded on every capture so you know what produced it. A worker that
   #     silently updates itself on reboot can span two code versions inside one corpus run, and the
   #     provenance stops meaning anything.
-  #   - `worker:deploy` exists and VERIFIES over /health.code, which shares no failure mode with the
+  #   - `fleet:deploy` VERIFIES over /health.code, which shares no failure mode with the
   #     push. An unattended self-update has no such check.
   #   - one bad push would then brick every box in the fleet at its next restart, simultaneously.
   if (Get-ScheduledTask -TaskName 'a11ybootstrap' -ErrorAction SilentlyContinue) {

package/dist/deploy-worker.d.mts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/deploy-worker.mjs

@@ -1,192 +0,0 @@
-#!/usr/bin/env node
-import { pathToFileURL } from "node:url";
-import { execFile, execFileSync } from "node:child_process";
-import { createReadStream, realpathSync } from "node:fs";
-import { promisify } from "node:util";
-import { resolve as external_node_path_resolve } from "node:path";
-import { WORKER_FILES } from "@a11ign/screenreader-worker/worker-files";
-import { codeVersion, workerSourceDir } from "@a11ign/screenreader-worker/code-version";
-import { CAPTURE_PROTOCOL_VERSION } from "@a11ign/screenreader-worker/protocol-version";
-import { requestJson as worker_http_requestJson } from "./worker-http.mjs";
-import { fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
-import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
-import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
-import { warnUtmDeprecated } from "./src_utm-deprecated_mjs.mjs";
-const MANIFEST_CASES = 1715;
-const CAPTURES_PER_CASE = 2;
-const RECAPTURE_COST = `${(MANIFEST_CASES * CAPTURES_PER_CASE).toLocaleString("en-US")} captures (${MANIFEST_CASES.toLocaleString("en-US")} cases in manifest.json x ${CAPTURES_PER_CASE}, read 2026-09-23T14:26Z; how long that takes depends on the fleet, so time a run rather than trust a figure)`;
-refuseUnknownFlags([
-    "--vm=",
-    "--allow-protocol-change"
-], {
-    entry: import.meta.url,
-    command: "npm run worker:deploy"
-});
-const run = promisify(execFile);
-const NVDA_DIR = workerSourceDir();
-const GUEST_DIR = "C:\\Users\\witness\\a11y-witness\\src\\capture\\nvda";
-const CTL = fleetScriptPaths().workerCtl;
-const LIFECYCLE_TIMEOUT_MS = 420000;
-const POOL_TIMEOUT_MS = 240000;
-const deploy_worker_HEALTH_TIMEOUT_MS = 20000;
-const only = flagValue(process.argv, "vm");
-function hashedFiles() {
-    return WORKER_FILES;
-}
-function localVersion() {
-    return codeVersion(NVDA_DIR);
-}
-async function pool() {
-    const { stdout } = await run(CTL, [
-        "pool"
-    ], {
-        timeout: POOL_TIMEOUT_MS,
-        encoding: "utf8"
-    });
-    const all = JSON.parse(stdout);
-    return only ? all.filter((vm)=>vm.name === only) : all;
-}
-function ctl(action, vmName) {
-    return run(CTL, [
-        action
-    ], {
-        timeout: LIFECYCLE_TIMEOUT_MS,
-        encoding: "utf8",
-        env: {
-            ...process.env,
-            A11Y_VM_NAME: vmName
-        }
-    });
-}
-function push(uuid, file) {
-    return new Promise((done, fail)=>{
-        const child = execFile("utmctl", [
-            "file",
-            "push",
-            uuid,
-            `${GUEST_DIR}\\${file}`
-        ], (error)=>error ? fail(new Error(`push ${file}: ${error.message}`)) : done());
-        if (child.stdin) createReadStream(external_node_path_resolve(NVDA_DIR, file)).pipe(child.stdin);
-    });
-}
-async function healthCode(ip, port) {
-    const response = await worker_http_requestJson(`http://${ip}:${port}/health`, {
-        timeoutMs: deploy_worker_HEALTH_TIMEOUT_MS
-    });
-    if (!response.ok) throw new Error(`HTTP ${response.status} from /health`);
-    if (void 0 === response.json) throw new Error(`invalid JSON from http://${ip}:${port}/health`);
-    return response.json.code;
-}
-const VERIFY_BUDGET_MS = 240000;
-const VERIFY_POLL_MS = 10000;
-async function healthCodeWhenAwake(ip, port) {
-    const deadline = Date.now() + VERIFY_BUDGET_MS;
-    let last = "no answer";
-    let waited = false;
-    while(Date.now() < deadline)try {
-        const actual = await healthCode(ip, port);
-        if (waited) process.stdout.write("\n");
-        return actual;
-    } catch (error) {
-        last = error instanceof Error ? error.message : String(error);
-        if (!waited) process.stdout.write("  waiting for the guest to answer /health ");
-        waited = true;
-        process.stdout.write(".");
-        await new Promise((resolve)=>setTimeout(resolve, VERIFY_POLL_MS));
-    }
-    if (waited) process.stdout.write("\n");
-    throw new Error(`${ip}:${port} never answered /health within ${VERIFY_BUDGET_MS / 1000}s (last: ${last})`);
-}
-async function waitUntilSettled(name, limitMs = 120000) {
-    const deadline = Date.now() + limitMs;
-    while(Date.now() < deadline){
-        const vm = (await pool()).find((v)=>v.name === name);
-        if (!vm || "stopping" !== vm.state) return;
-        await new Promise((resolve)=>setTimeout(resolve, 5000));
-    }
-    process.stdout.write(`  note: ${name} is still stopping; continuing anyway\n`);
-}
-async function deployTo(vm, files, expected) {
-    process.stdout.write(`\n=== ${vm.name} ===\n`);
-    await ctl("up", vm.name);
-    for (const file of files){
-        await push(vm.uuid, file);
-        process.stdout.write(`  pushed ${file}\n`);
-    }
-    process.stdout.write("  rebooting (utmctl exec cannot be trusted to restart the worker) ...\n");
-    await ctl("stop", vm.name);
-    await ctl("up", vm.name);
-    try {
-        const fresh = await pool();
-        const back = fresh.find((v)=>v.name === vm.name);
-        if (!back?.ip) throw new Error(`${vm.name} did not come back with an address`);
-        const actual = await healthCodeWhenAwake(back.ip, back.port);
-        const ok = actual === expected;
-        process.stdout.write(`  /health.code ${actual} ${ok ? "== expected" : `!= expected ${expected}`}\n`);
-        return ok;
-    } finally{
-        if ("started" !== vm.state) await ctl("stop", vm.name).catch(()=>void 0);
-    }
-}
-function guardProtocolChange() {
-    const inTree = String(CAPTURE_PROTOCOL_VERSION);
-    let committed;
-    try {
-        committed = /CAPTURE_PROTOCOL_VERSION = (\d+)/.exec(execFileSync("git", [
-            "-C",
-            NVDA_DIR,
-            "show",
-            "HEAD:./protocol-version.mjs"
-        ], {
-            encoding: "utf8",
-            env: sandboxGitEnv()
-        }))?.[1];
-    } catch  {
-        try {
-            execFileSync("git", [
-                "rev-parse",
-                "--verify",
-                "HEAD"
-            ], {
-                stdio: "ignore",
-                env: sandboxGitEnv()
-            });
-            process.stdout.write(`  note: cannot compare CAPTURE_PROTOCOL_VERSION against HEAD — ${external_node_path_resolve(NVDA_DIR, "protocol-version.mjs")} is not in HEAD.\n        Expected for a brand-new or just-moved file; if the path moved, fix it here or this guard is off.\n`);
-        } catch  {}
-        return;
-    }
-    if (!inTree || !committed || inTree === committed) return;
-    if (process.argv.includes("--allow-protocol-change")) return void process.stdout.write(`\nDeploying CAPTURE_PROTOCOL_VERSION ${committed} -> ${inTree} as requested. Every cached capture is now invalid and the next run will recapture all of them.\n`);
-    process.stderr.write(`\nREFUSING TO DEPLOY: the working tree has CAPTURE_PROTOCOL_VERSION = ${inTree}, but HEAD has ${committed}.\n\nThat value is a capture-cache key, so deploying it invalidates all cached captures and forces a\nfull recapture: ${RECAPTURE_COST}. If a \`worker:code\` STALE report sent you here, the stale\nhash is probably caused by this uncommitted bump rather than by the guests being out of date.\n\n  git stash                            # deploy without the bump, or\n  npm run worker:deploy -- --allow-protocol-change   # deploy it deliberately\n`);
-    process.exit(3);
-}
-async function main() {
-    warnUtmDeprecated("npm run worker:deploy");
-    guardProtocolChange();
-    const files = hashedFiles();
-    const expected = localVersion();
-    const vms = await pool();
-    if (!vms.length) {
-        process.stderr.write(only ? `no local worker VM named ${only}\n` : "no local worker VMs registered\n");
-        process.exit(2);
-    }
-    process.stdout.write(`Deploying ${files.length} file(s) to ${vms.length} worker(s)\n`);
-    process.stdout.write(`Files: ${files.join(", ")}\nExpected code: ${expected}\n`);
-    const failed = [];
-    for (const vm of vms){
-        try {
-            if (!await deployTo(vm, files, expected)) failed.push(vm.name);
-        } catch (error) {
-            process.stdout.write(`  FAILED: ${error.message}\n`);
-            failed.push(vm.name);
-        }
-        await waitUntilSettled(vm.name);
-    }
-    process.stdout.write(`\n${vms.length - failed.length}/${vms.length} worker(s) on ${expected}\n`);
-    if (failed.length) {
-        process.stdout.write(`stale or failed: ${failed.join(", ")}\n`);
-        process.stdout.write("Re-run this command; if it persists, the guest is not rebooting — see docs/nvda-worker-runbook.md\n");
-    }
-    process.exit(failed.length ? 1 : 0);
-}
-if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href) await main();

package/dist/src_utm-deprecated_mjs.mjs

@@ -1,4 +0,0 @@
-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 };