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

package/dist/deploy-worker.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// @ts-check
+// Deploy the worker's code to the guests, in one command, and prove it landed.
+//
+//   node scripts/deploy-worker.mjs              # every local worker VM, one at a time
+//   node scripts/deploy-worker.mjs --vm=a11y-worker-2
+//
+// Why this exists: deploying was a documented twelve-step manual dance — push four files with
+// `utmctl file push`, stop the VM, start it, then run `worker:code` and hope. Two things about that
+// were unacceptable for something we rely on:
+//
+//  - **It is easy to get wrong, and I got it wrong.** Pushing three of the four files leaves a guest
+//    running a mix; the symptom is a `worker:code` mismatch with no clue which file is stale.
+//  - **`utmctl exec` cannot be trusted to restart the worker**, so the reboot is mandatory and easy to
+//    skip. Skipping it makes the guest serve the previous code while reporting success — which cost two
+//    workers an hour of running stale code once already.
+//
+// So: one command, every hashed file, a real reboot, and a hash check over HTTP afterwards. The hash
+// check is the whole point — it shares no failure mode with the push, which is why `/health.code`
+// exists rather than reading the guest's files back through the same broken channel.
+//
+// Deploys the WORKING TREE, deliberately: that is what you are testing. Roll back by checking out the
+// ref you want and running this again — git is the source of truth for "the previous version", so there
+// is no bespoke backup to go stale.
+import { pathToFileURL } from "node:url";
+import { execFile, execFileSync } from "node:child_process";
+import { sandboxGitEnv } from "./git-safe-env.mjs";
+import { createReadStream, realpathSync } from "node:fs";
+import { promisify } from "node:util";
+import { resolve } from "node:path";
+// By SUBPATH, never the package ROOT: the index re-exports `capture-core.mjs`, which imports guidepup and
+// throws `No available supported screen readers` at import on any host without one. This file only
+// runs on a Mac, where VoiceOver makes that throw invisible — which is exactly why it went unnoticed.
+// `no-win32-imports.test.ts` found it.
+import { WORKER_FILES } from "@a11ign/screenreader-worker/worker-files";
+import { workerSourceDir, codeVersion } from "@a11ign/screenreader-worker/code-version";
+// The WORKING-TREE value, imported rather than regex-scraped — architecture-audit.md §5, item 3.
+// `protocol-version.mjs` is dependency-free for exactly this: safe to import from a portable tree, unlike
+// the package ROOT or `capture-core.mjs` itself, which reach guidepup. The git-HEAD comparison below still
+// has to scrape TEXT, because `git show` returns a historical file's bytes, not something importable.
+import { CAPTURE_PROTOCOL_VERSION as PROTOCOL_IN_TREE } from "@a11ign/screenreader-worker/protocol-version";
+import { fleetScriptPaths } from "./fleet-scripts.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
+import { warnUtmDeprecated } from "./utm-deprecated.mjs";
+import { requestJson } from "./worker-http.mjs";
+import { RECAPTURE_COST } from "./protocol-guard.mjs";
+/**
+ * `--allow-protocol-change` is the flag that lets a CAPTURE_PROTOCOL_VERSION bump ship, invalidating
+ * every cached capture. A typo silently means "do not allow", which is the safe direction — but
+ * `--vm=` mistyped deploys to EVERY guest instead of the one named.
+ *
+ * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
+ */
+refuseUnknownFlags(["--vm=", "--allow-protocol-change"], { entry: import.meta.url, command: "npm run worker:deploy" });
+const run = promisify(execFile);
+// From the worker PACKAGE, not from the cwd. This was `resolve("src/capture/nvda")` and then
+// `resolve("packages/nvda-worker/src")` — a repo-layout guess that had to be edited every time the worker
+// moved, and that silently pointed at nothing whenever the cwd was not the repo root.
+const NVDA_DIR = workerSourceDir();
+// The guest's layout deliberately does NOT mirror the repo's. It is where provisioning put the files and
+// where the scheduled task points, so renaming it means re-provisioning every guest — and M5 moving the host
+// directory to `packages/nvda-worker/src` changed nothing here. All the worker needs is that its files land in
+// one directory together.
+const GUEST_DIR = "C:\\Users\\witness\\a11y-witness\\src\\capture\\nvda";
+// Resolved from THIS module: the fleet scripts ship with this package, so a cwd-relative path was only ever
+// right when run from the repo root.
+const CTL = fleetScriptPaths().workerCtl;
+const LIFECYCLE_TIMEOUT_MS = 420_000;
+// `pool` launches UTM if it is closed and polls every VM's /health. 90s was too short: it timed out
+// mid-deploy while three guests were transitioning, and the whole run died with a bare SIGTERM.
+const POOL_TIMEOUT_MS = 240_000;
+const HEALTH_TIMEOUT_MS = 20_000;
+const only = flagValue(process.argv, "vm");
+/**
+ * The files that make up the worker's code version.
+ *
+ * Imported from the one module that defines them. This used to parse `check-worker-code.mjs`'s SOURCE with a
+ * regex for the same list — better than a third copy, which is what the comment here used to argue, but it
+ * still broke silently if that loop were ever rewritten, and "a file missing from the list deploys invisibly"
+ * is the failure it was guarding against.
+ */
+function hashedFiles() {
+    return WORKER_FILES;
+}
+/**
+ * The SHARED hasher, not a local copy of it.
+ *
+ * This used to hash raw bytes while `codeVersion()` normalises CRLF to LF -- and that difference is not
+ * cosmetic: a worker whose repo was git-cloned on Windows checks out CRLF, so the two sides hashed
+ * different bytes for identical code and the deploy verification reported STALE for ever. Measured on the
+ * first bare-metal worker: 31979b551b7a2cfa against a checkout's 22822b7a3a08969c.
+ *
+ * `code-version.test.ts` claims to enforce "one hasher" but only greps for the file list, so this file
+ * satisfied it while keeping its own implementation. Two implementations of a comparison are two chances
+ * to disagree, and the whole point of this check is that both sides agree.
+ */
+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((/** @type {{ name: string }} */ vm) => vm.name === only) : all;
+}
+/** @param {string} action @param {string} vmName */
+function ctl(action, vmName) {
+    return run(CTL, [action], {
+        timeout: LIFECYCLE_TIMEOUT_MS, encoding: "utf8",
+        env: { ...process.env, A11Y_VM_NAME: vmName },
+    });
+}
+/**
+ * Push one file. `utmctl file push` reads the content from stdin, which execFile cannot stream, so the
+ * child is spawned and the file piped in.
+ */
+/** @param {string} uuid @param {string} file @returns {Promise<void>} */
+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}: ${ /** @type {Error} */(error).message}`)) : done());
+        if (child.stdin)
+            createReadStream(resolve(NVDA_DIR, file)).pipe(child.stdin);
+    });
+}
+/** @param {string} ip @param {number} port */
+async function healthCode(ip, port) {
+    // `requestJson`, not `fetch` -- audit §9's "the HTTP client" row: a second hand-rolled probe of the
+    // same worker JSON API, with its own timeout mechanism, buys nothing and carries `fetch`'s
+    // undifferentiated `TypeError: fetch failed` in place of a real error CODE (`ECONNREFUSED`,
+    // `EHOSTUNREACH`) -- the exact distinction `isTransient` and this repo's own diagnostics rely on
+    // elsewhere. This site was found by a tree-wide sweep, not the original audit's four named ones.
+    const response = await requestJson(`http://${ip}:${port}/health`, { timeoutMs: HEALTH_TIMEOUT_MS });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} from /health`);
+    // `requestJson` returns `undefined` for unparseable JSON rather than throwing (its own docstring: a
+    // cache miss is a normal outcome for its usual callers) -- `fetch`'s `.json()` threw, and
+    // `healthCodeWhenAwake`'s retry loop relies on that to keep polling on garbage the same as on silence.
+    if (response.json === undefined)
+        throw new Error(`invalid JSON from http://${ip}:${port}/health`);
+    return response.json.code;
+}
+/** How long a rebooted guest gets to start answering before a deploy calls the verification failed. */
+const VERIFY_BUDGET_MS = 240_000;
+const VERIFY_POLL_MS = 10_000;
+/**
+ * Read the guest's code hash, waiting for it to finish booting first.
+ *
+ * A guest that is not answering YET is not a failed deploy, and reading `/health` once immediately after the
+ * reboot conflated the two: `worker:deploy` printed "stale or failed" while `npm run worker:code` — run a
+ * minute later against the same guest — reported `matches`. That false alarm sent me redeploying guests that
+ * had deployed correctly, repeatedly, and the deploy is the tool whose whole job is telling you whether the
+ * push landed.
+ *
+ * Only SILENCE is waited on. A hash that answers and differs is returned straight to the caller, which
+ * compares it — so a genuine stale deploy still fails immediately and only a booting guest costs time. Boot
+ * times measured on this fleet run from 30 s to 147 s depending on how much Edge-profile hygiene the guest has
+ * to do first, so the budget is well above the slowest honest answer.
+ */
+/** @param {string} ip @param {number} port */
+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})`);
+}
+/**
+ * Wait until a VM is no longer `stopping`, so the next deploy does not start a guest on top of one still
+ * holding its memory.
+ *
+ * Bounded and non-fatal: if it never settles we continue and let the next deploy report its own failure,
+ * because a deploy that hangs forever is worse than one that reports a stale worker.
+ */
+/** @param {string} name @param {number} [limitMs] */
+async function waitUntilSettled(name, limitMs = 120_000) {
+    const deadline = Date.now() + limitMs;
+    while (Date.now() < deadline) {
+        const vm = (await pool()).find((/** @type {{ name: string }} */ v) => v.name === name);
+        if (!vm || vm.state !== "stopping")
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 5_000));
+    }
+    process.stdout.write(`  note: ${name} is still stopping; continuing anyway\n`);
+}
+/** @param {Record<string, any>} vm @param {string[]} files @param {string} expected */
+async function deployTo(vm, files, expected) {
+    process.stdout.write(`\n=== ${vm.name} ===\n`);
+    // Push needs the guest running; the reboot afterwards is what actually loads the new code.
+    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);
+    // The restore is in a `finally` because it used to be on the SUCCESS path only, and the failure path is
+    // exactly when it matters. A guest whose health check threw was left RUNNING, and the loop then started
+    // the next VM on top of it — on a host `doctor` reports as having room for one of two, that guarantees
+    // the second times out too. It is then printed as "stale or failed", which reads as a broken guest and
+    // sent me looking to rebuild one that boots to ready in 33 s.
+    try {
+        const fresh = await pool();
+        const back = fresh.find((/** @type {{ name: string }} */ 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 {
+        // Put it back where it was found, the same contract the run's lease honours.
+        if (vm.state !== "started")
+            await ctl("stop", vm.name).catch(() => undefined);
+    }
+}
+/**
+ * Refuse to deploy a CAPTURE_PROTOCOL_VERSION change unless it is asked for explicitly.
+ *
+ * This deploys the WORKING TREE, which is right for testing a change and dangerous for one specific
+ * change: the protocol version is a capture-cache key input, so shipping a bump invalidates every capture
+ * on disk and forces a full recapture (`RECAPTURE_COST`, in protocol-guard.mjs, says how big).
+ *
+ * The trap is real and was live in this repo. An uncommitted bump in a shared checkout makes
+ * `npm run worker:code` report every worker STALE, and the remedy it prints is "redeploy" — which would
+ * deploy the bump, wipe the cache, and give no clue why the next run recaptured everything.
+ */
+function guardProtocolChange() {
+    const inTree = String(PROTOCOL_IN_TREE);
+    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 {
+        // Two very different situations, and one of them is a guard that has quietly stopped guarding: there may
+        // be no git checkout at all, or the PATH may have moved (M5 relocated this file from `src/capture/nvda/`;
+        // it moved AGAIN out of `capture-core.mjs` into its own file on architecture-audit.md §5, item 3) so
+        // `git show` finds nothing. The second would silently disable the most expensive check in this script,
+        // which is exactly the shape this repo keeps paying for, so it says so.
+        try {
+            execFileSync("git", ["rev-parse", "--verify", "HEAD"], { stdio: "ignore", env: sandboxGitEnv() });
+            process.stdout.write("  note: cannot compare CAPTURE_PROTOCOL_VERSION against HEAD — "
+                + `${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 { /* genuinely not a git checkout: nothing to compare, and nothing to warn about */ }
+        return;
+    }
+    if (!inTree || !committed || inTree === committed)
+        return;
+    if (process.argv.includes("--allow-protocol-change")) {
+        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");
+        return;
+    }
+    process.stderr.write(`\nREFUSING TO DEPLOY: the working tree has CAPTURE_PROTOCOL_VERSION = ${inTree}, but HEAD has ` +
+        `${committed}.\n\n` +
+        "That value is a capture-cache key, so deploying it invalidates all cached captures and forces a\n" +
+        `full recapture: ${RECAPTURE_COST}. If a \`worker:code\` STALE report sent you here, the stale\n` +
+        "hash 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);
+}
+/**
+ * Nothing here runs on import.
+ *
+ * This module used to execute its whole deploy at module scope, so merely importing it — which I did, to read a
+ * path constant — ran `guardProtocolChange()` and began enumerating VMs. With guests running it would have
+ * pushed files and rebooted them. A program that reboots machines must be invoked, never merely mentioned.
+ *
+ * `check-worker-code.mjs` got the same treatment. The four remaining scripts in this repo that execute at
+ * module scope are pure programs nothing imports; they are left alone deliberately rather than restructured for
+ * symmetry.
+ */
+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: ${ /** @type {Error} */(error).message}\n`);
+            failed.push(vm.name);
+        }
+        // A `stop` returns before the guest has actually released its memory — one was observed sitting in
+        // `stopping` for minutes. Starting the next VM into that overlap is the same over-commitment by a
+        // second route, so wait for the host to be quiet before moving on.
+        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);
+}
+// REALPATH'D: `import.meta.url` is resolved through symlinks by Node's ESM loader and `process.argv[1]`
+// is not, so a bin reached via its `.bin` symlink (which is how npm always installs one) mismatched here
+// and this guard silently read false — the tool loaded, did nothing, and exited 0. `/var` and `/tmp` are
+// themselves symlinks on macOS, so this fired every time. Same defect, same fix, as `cli.ts`'s `isProgram`.
+if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href)
+    await main();
+//# sourceMappingURL=deploy-worker.mjs.map

package/dist/deploy-worker.mjs.map

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

package/dist/doctor.d.mts

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * The remedy for a failed local-pool query, as a runnable command plus the advice that is not one.
+ *
+ * #1059: THE DEPRECATION REFUSAL GETS THE FLEET, NOT THE SCRIPT THAT JUST REFUSED. `worker-ctl.sh` refuses
+ * on a machine the deprecation is aimed at and says so -- *"Capture on the bare-metal fleet instead:
+ * npm run fleet:status"* -- and the `fix:` line beside it said to re-run the script. **Following it
+ * exactly reproduces the refusal**, which is the one thing a refusal must never do, and it contradicted
+ * the message printed directly above it.
+ * @param {string} observed
+ * @returns {{ fix: string|null, note: string|null }}
+ */
+export function workerControlFix(observed: string): {
+    fix: string | null;
+    note: string | null;
+};
+/**
+ * Pure: does `resolvedRealPath` (already realpath'd) live under `thisCheckoutRoot` (also realpath'd)?
+ * Both must be realpath'd BEFORE calling this, never inside it -- comparing a symlinked path against a
+ * realpath'd root would report every worktree as foreign to itself, since a worktree's own files are
+ * reached through no symlink while its `node_modules` is one.
+ *
+ * @param {string} resolvedRealPath
+ * @param {string} thisCheckoutRootReal
+ * @returns {boolean}
+ */
+export function resolvesToThisCheckout(resolvedRealPath: string, thisCheckoutRootReal: string): boolean;
+/**
+ * Pure: which checkout root does a resolved `packages/<name>/dist/...` path belong to? Everything before
+ * the first `/packages/` -- this repo's own, fixed layout, not a guess. `null` when the path does not look
+ * like it, which a caller must treat as "could not tell", never as "this checkout".
+ *
+ * @param {string} resolvedRealPath
+ * @returns {string | null}
+ */
+export function checkoutRootFor(resolvedRealPath: string): string | null;
+/**
+ * Whether `tsc --build --dry` -- the SAME authority the real build uses, deferred to rather than
+ * reimplemented -- considers `tsconfigPath`'s own outputs up to date.
+ *
+ * NOT a timestamp comparison, and that correction cost a wrong first version of this check (#256, live-
+ * measured): a directory's mtime does not move on rewrite; a file's mtime moves on `git checkout` with no
+ * content change at all, which is the ordinary case of switching branches; and `tsc --build` itself is
+ * content-addressed for the files it actually recompiles, so a real build can be legitimately up to date
+ * with source files whose mtimes are newer than its outputs. Measured on two live worktrees straight
+ * after a branch switch: several source files newer than `dist/index.js`, and `tsc --build --dry` still
+ * correctly reported "is up to date". A raw mtime comparison would have flagged both as stale --
+ * permanently, on every worktree, the moment `git checkout` runs -- which is exactly the "readiness
+ * command that cries wolf" this file's own `advise` doc warns against.
+ *
+ * `null`, not `false`, when the run failed outright or its report never mentioned this project at all --
+ * "could not tell" and "not up to date" need opposite responses (investigate vs. rebuild), and this repo's
+ * own rule is that a lookup failure is never silently read as a clean answer.
+ *
+ * @param {string} tsconfigPath
+ * @param {{ run?: (cmd: string, args: string[]) => string }} [deps]
+ * @returns {boolean | null}
+ */
+export function tscProjectUpToDate(tsconfigPath: string, { run }?: {
+    run?: (cmd: string, args: string[]) => string;
+}): boolean | null;
+/**
+ * The agreement sentence, with WHICH FIELDS AGREED DERIVED rather than retyped — #1997.
+ *
+ * "OF N CONFIGURED", because agreement among a SUBSET is not agreement. Unreachable guests are skipped
+ * by the caller — correctly, that check is not their business — so without the denominator "3 guests
+ * agree" reads as a whole fleet on a fleet of five, which is the examined-nothing shape one step in from
+ * zero.
+ *
+ * AND THE FIELD NAMES ARE NOT TYPED HERE. This line used to read "agree on browser, screen reader, OS
+ * and protocol": four names, by hand, beside a `MUST_MATCH` that has ten. `guidepupVersion`,
+ * `architecture`, `browserProfile`, `screenReaderSettings`, `provisionRevision` and `displayMode` were
+ * all compared and none of them was mentioned, and the remediation string repeated the same four — so
+ * the sentence had been making a POSITIVE, false claim about its own scope since the fifth field was
+ * added, and no test could notice because nothing tied the words to the list. A sentence enumerating
+ * what a machine compared is a second copy of that machine's predicate; derived, it cannot go stale.
+ *
+ * `fleet:status` says nothing about field coverage and this said something untrue about it, which is why
+ * #1997's fix has to reach both. Never a FAIL either way: a mismatched pool is worse than a matched one
+ * and far better than no pool, and a diagnostic must not be the thing that takes the fleet offline.
+ *
+ * AND THE LIST IS WHAT EVERY COMPARED GUEST REPORTED, NOT WHAT ANY ONE OF THEM DID — #2034, carrying
+ * #2019's ruling into the second of the two commands #1997 named. `fields.compared` is TRUE-IF-ANYBODY,
+ * so a field ONE guest of three reported was named inside a list introduced by the words "guests agree
+ * on", and the reporter count contradicting it sat in the same return value. Measured 2026-09-22 at
+ * #2033's head: `coverage: {"field":"displayMode","reported":1,"asked":3}` beside `3 of 3 guests agree
+ * on 10 compared field(s) (..., displayMode)`. One guest's display was read. Naming it is worse than
+ * counting it, because the naming is what #1997 added to make the sentence actionable.
+ *
+ * THREE FACTS, THREE SENTENCES, and that split is #2019's ruling rather than a style choice: `N of N`
+ * is agreement, `k of N` is *some boxes did not report it* and sends a reader to the BOXES, `0 of N` is
+ * *nobody could be asked* and sends them to the FIELD. Collapsing the middle one into either of the
+ * outer two is the defect this fixes in one direction and #1997's in the other.
+ *
+ * DERIVED FROM `coverage`, AND NOT FROM `compared`/`unchecked` — the same call `fleet:status` makes
+ * (`fieldCoverageGap`, #2019). The two lists are that same measurement thresholded at "anybody", so
+ * reading the whole case off one and the partial case off the other gives one fact two sources that can
+ * disagree. The lists stay in the return value, where a caller greps them for the remedy.
+ *
+ * @param {{ agreeing: number, configured: number,
+ *           fields: { compared: string[], unchecked: string[],
+ *                     coverage?: { field: string, reported: number, asked: number }[] } }} input
+ * @returns {string}
+ */
+export function fleetAgreementLine({ agreeing, configured, fields }: {
+    agreeing: number;
+    configured: number;
+    fields: {
+        compared: string[];
+        unchecked: string[];
+        coverage?: {
+            field: string;
+            reported: number;
+            asked: number;
+        }[];
+    };
+}): string;
+/**
+ * #1059: A COMMAND, OR `null`. Never a sentence.
+ *
+ * `--json`'s `next_command` is the field CLAUDE.md tells an agent to read and obey, so anything in it that
+ * is not runnable makes an automated reader loop -- which is exactly what happened when a failing `worker`
+ * check put *"unlock the Mac if it is locked, then re-run …"* here.
+ *
+ * **`null` and an unrunnable string are different reports**, and a JSON consumer can act on the first: it
+ * means read the checks. `contention` has no command because waiting is not one, and it says so with
+ * `null` and a `note` rather than with an imperative nobody can execute.
+ * THE PARAMETER TYPE IS WHAT THIS FUNCTION READS, not the whole check shape: `ok` and `fix`, and nothing
+ * else. A test injecting a two-field object is stating exactly the inputs the verdict depends on, and a
+ * wider type would have made it carry an `id` and a `detail` the answer cannot possibly turn on.
+ * @param {{ok: boolean, fix: string|null}[]} [checkList]
+ * @returns {string|null}
+ */
+export function nextCommand(checkList?: {
+    ok: boolean;
+    fix: string | null;
+}[]): string | null;
+/**
+ * Is `line` something a shell can run? The shape `next_command` must have, and prose must not.
+ *
+ * #1059: the field carried *"unlock the Mac if it is locked, then re-run …"*, and CLAUDE.md tells an agent
+ * to read it and do that. A shape check is the only thing that can tell a command from an imperative
+ * sentence without running it: **a command begins with an executable token** — a pnpm/npm/node/git invocation,
+ * a path, or a `VAR=value` prefix — **and an English sentence begins with a verb or an article.**
+ * @param {string|null} line
+ * @returns {boolean}
+ */
+export function isRunnableCommand(line: string | null): boolean;
+/**
+ * Only when RUN, never on import.
+ *
+ * Every check here probes something real -- it spawns the Python scorer, polls each worker's `/health`,
+ * looks for strays on the pages port and reads the run's progress file -- and then calls `process.exit`.
+ * So importing this file ran the whole diagnostic against the fleet and then terminated the IMPORTING
+ * process with doctor's verdict.
+ *
+ * A brace-depth scan for dangerous calls at module scope reports this file CLEAN, because the work is one
+ * call deeper inside `checkJudge`/`checkWorker`/`checkDatasetPages`. Indirection is that check's blind
+ * spot, which is why these guards were placed by reading each file rather than by running a tool over them.
+ */
+/**
+ * `ready` over the checks that GATE. Exported so the case nobody runs -- a clean clone whose only failing
+ * check is `dataset` -- is drivable without a clean clone.
+ * @param {{name: string, ok: boolean}[]} checkList
+ * @returns {boolean}
+ */
+export function readyFrom(checkList: {
+    name: string;
+    ok: boolean;
+}[]): boolean;
+/**
+ * #1082: A `--json` RUN THAT CANNOT PRODUCE JSON STILL PRODUCES JSON.
+ *
+ * Measured on `1e74e3d0`: a check threw, `doctor --json` exited 1 with **zero bytes on stdout** and 1,155
+ * bytes of stack on stderr — where a `--json` consumer never looks. **"Could not ask" and "no output" are
+ * different for a caller**, and only the first is actionable; the second is indistinguishable from a
+ * command that was never run.
+ *
+ * `2>&1` IS NOT THE FIX HERE, which is what makes this different from #1068's watch job. That job's stdout
+ * is prose, so merging stderr in was free. This stdout is a PARSED format, and redirecting into it
+ * produces invalid JSON — **worse than nothing, because a consumer that parses gets a syntax error rather
+ * than a document.** The fix has to be in the tool.
+ *
+ * `checks` is present and EMPTY rather than absent OR PARTIAL — and the partial list is the one actually
+ * worth refusing. A consumer reading `.checks[]` off an absent key crashes; off a partial one it reads a
+ * list that looks exactly like a complete verdict, with **no way to tell a check that is missing because
+ * it passed from one that is missing because the run died under it.** Empty says "no verdict" and cannot
+ * be mistaken for a short one.
+ * @param {unknown} error
+ * @returns {{ready: false, error: string, checks: never[]}}
+ */
+export function errorDocument(error: unknown): {
+    ready: false;
+    error: string;
+    checks: never[];
+};
+/**
+ * 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]
+ * @returns {Promise<number>}
+ */
+export function doctorRun(deps?: {
+    steps?: (() => unknown)[];
+    json?: boolean;
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+}): Promise<number>;
+export function addCheck(name: string, ok: boolean, detail: string, remedy?: string | null | {
+    fix: string | null;
+    note?: string | null;
+}): void;
+export function allChecks(): string[];
+export function gatingChecks(): string[];
+//# sourceMappingURL=doctor.d.mts.map

package/dist/doctor.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.mts","sourceRoot":"","sources":["../src/doctor.mjs"],"names":[],"mappings":";AAiLA;;;;;;;;;;GAUG;AACH,2CAHW,MAAM,GACJ;IAAE,GAAG,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,CAmBnD;AA4GD;;;;;;;;;GASG;AACH,yDAJW,MAAM,wBACN,MAAM,GACJ,OAAO,CAKnB;AAED;;;;;;;GAOG;AACH,kDAHW,MAAM,GACJ,MAAM,GAAG,IAAI,CAKzB;AAKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iDAJW,MAAM,YACN;IAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;CAAE,GAC/C,OAAO,GAAG,IAAI,CAkB1B;AAuSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qEALW;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IACrC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAA;CAAE,GAC7E,MAAM,CAkBlB;AA+GD;;;;;;;;;;;;;;;GAeG;AACH,wCAHW;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,EAAE,GAC/B,MAAM,GAAC,IAAI,CAMvB;AAED;;;;;;;;;GASG;AACH,wCAHW,MAAM,GAAC,IAAI,GACT,OAAO,CAMnB;AAED;;;;;;;;;;;GAWG;AACH;;;;;GAKG;AACH,qCAHW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAC,EAAE,GAC3B,OAAO,CAInB;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAHW,OAAO,GACL;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAC,CAK1D;AAED;;;;;;GAMG;AACH,iCAJW;IAAE,KAAK,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC9B,OAAO,CAAC,MAAM,CAAC,CAgB3B;AAxzBM,+BANI,MAAM,MACN,OAAO,UACP,MAAM,WACN,MAAM,GAAC,IAAI,GAAC;IAAC,GAAG,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,QAa5D;AAsvBM,sCAA0C;AAG1C,yCAAmG"}