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

package/dist/doctor.mjs

@@ -0,0 +1,962 @@
+#!/usr/bin/env node
+// @ts-check
+// Can I run right now? One command, one answer.
+//
+//   pnpm run doctor           human-readable, with the fix for anything broken
+//   pnpm run doctor -- --json machine-readable, for an agent
+//
+// This exists because "is the environment ready" took five commands and some inference, and
+// the inference went wrong: a healthy VM was reported as a corrupted one because `utmctl`
+// answers `unknown` when the UTM app is closed. Every check below therefore reports what it
+// observed AND the exact command that fixes it, so nothing has to be deduced.
+//
+// Exit codes: 0 ready, 1 something is broken (details in the report).
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+// The canonical scrubber for this package -- `packages/guards/src/git-env.mjs` re-exports the same function for the
+// repo-root scripts. One helper, two entry points, so a git spawn cannot inherit GIT_DIR by either door.
+import { sandboxGitEnv } from "./git-safe-env.mjs";
+import { availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
+import { fleetConsistency, describeMismatches } from "./fleet-consistency.mjs";
+import { assessWorker } from "./worker-health.mjs";
+import { controlPlaneIsolation } from "./control-plane-isolation.mjs";
+import { fleetScriptPaths } from "./fleet-scripts.mjs";
+import { configuredWorkers, namedInventoryWorkers } from "./fleet-env.mjs";
+import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { pnpmCliInvocation } from "./npm-cli-executable.mjs";
+import { requestJson } from "./worker-http.mjs";
+/**
+ * a mistyped `--json` prints for a human where a script expected a machine-readable answer, and the
+ * caller parses the prose.
+ *
+ * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
+ */
+refuseUnknownFlags(["--json"], { entry: import.meta.url, command: "pnpm run doctor" });
+const run = promisify(execFile);
+const JSON_OUT = process.argv.includes("--json");
+// A11Y_WORKERS (plural) is how a bare-metal fleet is configured -- bootstrap-control-plane.sh tells you
+// to set exactly that -- and this read only A11Y_WORKER. So doctor reported "no A11Y_WORKER set and no
+// local VM tooling here" against a healthy fleet of ten machines, and doctor is the FIRST command
+// CLAUDE.md tells an agent to run. The environment was fine and the entry point said it was broken.
+//
+// Parsed by fleet-env.mjs, which is the ONE place that answers "what is the fleet" -- see there for why
+// the precedence had to be settled: doctor and worker:code disagreed, so they could report on two
+// different sets of machines with nothing to say so.
+const WORKERS_ENV = configuredWorkers();
+const PAGES_PORT = Number(process.env.DATASET_PAGES_PORT || 5050);
+// The lifecycle script ships beside this one in the fleet package. It was `../scripts/local-worker/...`,
+// resolved from this module — correct while doctor lived in `scripts/`, and silently wrong the moment it
+// moved: doctor then reported "no local VM tooling here" on a host with three registered VMs, which reads as
+// a broken environment rather than a broken path.
+const CTL = fleetScriptPaths().workerCtl;
+// Resolved from THIS module, never the cwd. The scorer being resolved against `process.cwd()` is the
+// defect that made a fresh clone unable to run its own default judge (see packages/scorer/src/index.ts),
+// so nothing here may repeat it.
+const SCORER_MODEL_DIR = fileURLToPath(new URL("../../scorer/models/screenreader-scorer/", import.meta.url));
+// Same rule as SCORER_MODEL_DIR above: resolved from THIS module, never the cwd. `@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 — this is the same computation,
+// duplicated for that reason rather than left cwd-anchored.
+const DATASET = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/screenreader-dataset");
+const PROBE_TIMEOUT_MS = 8000;
+/** @type {{name: string, id: string, ok: boolean, detail: string, fix: string|null, note?: string|null,
+ *    advisory?: boolean}[]} */
+const checks = [];
+/**
+ * DOES THIS CHECK DECIDE `ready`? -- #1073, product-manager's ruling: **the dataset check must REPORT and
+ * not gate.**
+ *
+ * `const ready = checks.every((c) => c.ok)` made every check a gate, so a freshly cloned checkout with a
+ * worker configured read **NOT READY** — because the stranger had not generated a TRAINING CORPUS they
+ * have no reason to want. `doctor` is the first command the README names and CLAUDE.md tells an agent to
+ * obey its `next_command`; a verdict of NOT READY on a machine that is ready for the documented purpose
+ * **teaches the reader that the verdict is not about them**, which is #1059's defect one level up.
+ *
+ * DECLARED HERE AND ENFORCED BY `add`, WHICH THROWS ON AN UNDECLARED NAME. A list that merely sat beside
+ * the checks would drift from them silently; a list a new check cannot bypass cannot. **The author of the
+ * next check has to say which kind it is**, which is the property the row asked for — not the location.
+ *
+ * THE GATE NARROWS, IT DOES NOT VANISH. Everything a capture run actually needs still decides: a
+ * readiness command that is always ready is worse than one that is never ready, because it is believed.
+ * `dataset` is the single entry that reports without deciding, and its absence is real information on the
+ * lab path -- which is why it is still PRINTED with its fix.
+ * @type {Readonly<Record<string, boolean>>}
+ */
+const GATES = Object.freeze({
+    worker: true, // no worker, no capture
+    fleet: true, // the fleet is the worker, on a configured machine
+    judge: true, // a run that cannot score is not a run
+    pages: true, // the dataset page server a capture fetches from
+    run: true, // a run left mid-flight is a real obstruction
+    contention: true, // another session holds the pool
+    isolation: true, // the control-plane boundary
+    "dist-freshness": true,
+    "dist-resolution": true,
+    dataset: false, // #1073: lab work. Reported, never a reason a capture cannot happen.
+    // THE THREE BELOW ALWAYS PASS `ok: true` TODAY, so their gating value is not currently observable --
+    // stated so nobody reads these as decisions that were tested. They are declared because the throw
+    // demands it, and the reasons are what make the table a decision rather than a list.
+    "primary checkout": false, // a capture runs fine in a linked worktree; this guards the SHARED tree's
+    // read-only rule, which is a different kind of cannot-proceed and not one
+    // that stops a run. It reports, loudly, via `advise` on the unmarked case.
+    "fleet reach": false, // it fires only when SOME box is unreachable and says "the run will dispatch
+    // to the rest" -- a partial fleet is a smaller fleet, not no fleet. `fleet`
+    // above is the check that decides whether there is a fleet at all.
+    "host memory": false, // reports how many workers the host has room for; the run starts fewer
+    // rather than failing, which is the whole point of the number.
+});
+/**
+ * One check's verdict, and its REMEDY. Every parameter is typed here rather than inferred, because
+ * `remedy` defaulting to `null` infers as exactly `null` -- so the argument that matters most, what a
+ * reader is to do about a failed check, was the one the compiler refused.
+ *
+ * `id` is always `name` -- #256 is the first check queried individually by `--json`
+ * (`.checks[] | select(.id=="dist-freshness")`), and every check already has a unique `name`, so a
+ * separate parameter here would be a second spelling of the same fact rather than a new one.
+ *
+ * #1059: `fix` IS A COMMAND OR IT IS `null`, and human advice goes in `note`.
+ *
+ * CLAUDE.md tells an agent to read `next_command` and do that, and `next_command` is `fix`. A sentence
+ * there ("unlock the Mac if it is locked, then re-run …") is not something anything can run, so an
+ * automated reader loops. The advice is not lost -- it moves to the field nothing executes.
+ * ONE `remedy` ARGUMENT, not two: a bare string stays a command (which is what every existing call site
+ * passes), and the object form carries the advice beside it. Four parameters is the house limit and
+ * bundling cohesive arguments is the house answer to it.
+ * @param {string} name
+ * @param {boolean} ok
+ * @param {string} detail
+ * @param {string|null|{fix: string|null, note?: string|null}} [remedy] a runnable command, `null` when
+ *   none can be constructed, or `{ fix, note }` when there is advice a shell cannot run
+ */
+export const addCheck = (name, ok, detail, remedy = null) => {
+    // #1073: an undeclared check cannot inherit a default. The throw is the forcing function.
+    if (!Object.hasOwn(GATES, name)) {
+        throw new Error(`doctor: check "${name}" declares no entry in GATES -- say whether it decides `
+            + "`ready` (a capture cannot happen without it) or only reports (true/false in GATES).");
+    }
+    const { fix, note } = typeof remedy === "string" || remedy === null
+        ? { fix: remedy, note: null }
+        : { note: null, ...remedy };
+    checks.push({ name, id: name, ok, detail, fix, note });
+};
+/** The name every call site uses; `addCheck` is the same function, exported so a test can drive the
+ * GATES refusal through the real thing rather than through a copy of its rule. */
+const add = addCheck;
+/**
+ * A finding that is REAL and does not stop a run — reported every time, never blocking.
+ *
+ * `doctor` exits 0 when a run can PROCEED, and that contract is load-bearing: agents are told to read
+ * `next_command` and act on it. An architectural debt is not a reason a capture cannot happen, so filing
+ * one as a failure would make `doctor` say NOT READY on a machine that is fine — and a readiness command
+ * that cries wolf is one people stop running, which is how the checks it does own stop being read.
+ *
+ * Distinct from `ok: true` for the opposite reason: silence is how ADR 0012 went years describing a system
+ * that did not exist. It is stated on every run and excluded from the verdict.
+ */
+const advise = (/** @type {string} */ name, /** @type {string} */ detail, /** @type {string|null} */ fix = null) => checks.push({ name, id: name, ok: true, advisory: true, detail, fix });
+function commandError(/** @type {any} */ error) {
+    const observed = [error?.stderr, error?.stdout, /** @type {any} */ (error)?.message]
+        .map((value) => String(value ?? "").trim())
+        .find(Boolean) || "unknown command failure";
+    return observed.replace(/\s+/g, " ").slice(0, 400);
+}
+/**
+ * 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) {
+    // The deprecation names itself; matching the REFUSAL rather than the script's name, because the same
+    // script succeeds under `A11Y_LOCAL_VM=1` and that is a different situation with a different remedy.
+    if (/DEPRECATED|refusing: set A11Y_LOCAL_VM/i.test(observed)) {
+        return {
+            fix: "pnpm run fleet:status",
+            note: "the local UTM VM path is deprecated and refused to run; capture on the bare-metal fleet. "
+                + `To use the deprecated local VM anyway: A11Y_LOCAL_VM=1 ${CTL} pool`,
+        };
+    }
+    if (/no VM named|no worker VM registered/i.test(observed)) {
+        return { fix: `${CTL} pool`,
+            note: "UTM has no registered worker VM; re-register the existing a11y-worker*.utm bundles in UTM first" };
+    }
+    return existsSync("/Applications/UTM.app")
+        ? { fix: `${CTL} pool`, note: "unlock the Mac first if it is locked" }
+        : { fix: `${CTL} pool`, note: "this launches UTM if it is installed" };
+}
+async function shell(/** @type {any} */ cmd, /** @type {any} */ args, timeout = 30000) {
+    const { stdout } = await run(cmd, args, { timeout, encoding: "utf8" });
+    return stdout.trim();
+}
+// `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 cost this project a silent-truncation
+// bug once already (worker-http.mjs's own header). `requestJson` also carries the failure's CODE
+// (`ECONNREFUSED`, `EHOSTUNREACH`) rather than fetch's undifferentiated `TypeError: fetch failed`.
+async function httpJson(/** @type {any} */ url) {
+    const response = await requestJson(url, { timeoutMs: PROBE_TIMEOUT_MS });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    // `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()` throws, and this function's
+    // callers rely on that to distinguish "answered with garbage" from "answered correctly". Restored here.
+    if (response.json === undefined)
+        throw new Error(`invalid JSON from ${url}`);
+    return response.json;
+}
+// --- the checks -----------------------------------------------------------
+/**
+ * IS THE FLEET KEY SITTING NEXT TO 100 MB OF PACKAGES NOBODY AUDITED? — ADR 0012, checked rather than
+ * asserted.
+ *
+ * Found on 2026-08-29 to be violated on BOTH machines the ADR is about: the control plane carried 56 MB
+ * and 121 packages beside the key, and this laptop carries 103 MB beside the same key plus the lab key.
+ * The document was accurate about the intent and described a system that did not exist — which is worse
+ * than no document, because it is read as a guarantee.
+ *
+ * Reported by `doctor` because that is the command whose whole promise is that every check names its own
+ * fix, and because a check nobody runs is one this repo has learned not to write.
+ */
+/**
+ * IS THIS CHECKOUT MARKED AS THE PRIMARY, and does that match what it looks like?
+ *
+ * The primary-checkout guards (`pre-commit`, `post-checkout`) are OPT-IN as of #198: they fire only where
+ * `git config --local a11y.primaryCheckout` is `true`. That is the correct default — inferring it from
+ * `.git` being a directory made the hook fire on the lab, which is an ordinary clone, and broke every
+ * `lab:job -e ref=<branch>`.
+ *
+ * But an opt-in guard nobody can find the switch for is an OFF guard, and "unmarked" must not read the
+ * same as "safe". So this reports the state on every run rather than only when something is wrong — the
+ * `isolation` check above takes the same shape for the same reason: a debt that is reported every run is
+ * a known one, and a debt reported never is a forgotten one.
+ *
+ * ADVISORY, never a hard failure. `doctor` exits 0 when a RUN can proceed, and an unmarked checkout can
+ * run perfectly well — it is the fleet-driving machine's protection that is missing, not its capability.
+ * A doctor that refused READY over this would be ignored, which is how a guard gets switched off.
+ *
+ * It does not GUESS which machine deserves the mark. `doctor` runs on laptops, worktrees, the lab and CI,
+ * and telling four of those five to mark themselves would be the #198 defect wearing an advisory's
+ * clothes. It states what is true and names the command; the operator decides.
+ */
+function checkPrimaryCheckoutMark() {
+    const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
+    // A linked worktree's `.git` is a FILE (`gitdir: ...`) and it SHARES `.git/config` with the repository
+    // it was created from -- so the mark alone reads true inside every worktree off a marked primary. Both
+    // conditions, exactly as `scripts/git-hooks/lib/is-primary-checkout.sh` requires them; a doctor that
+    // disagreed with the hook it reports on would be worse than silent.
+    /** A linked worktree's `.git` is a FILE; an absent one is neither, and neither is the primary. */
+    let linked;
+    try {
+        linked = !statSync(resolve(root, ".git")).isDirectory();
+    }
+    catch {
+        linked = false;
+    }
+    /** `git config --get` exits 1 on an absent key: not marked, not an error. */
+    let marked;
+    try {
+        marked = execFileSync("git", ["config", "--local", "--get", "a11y.primaryCheckout"], { cwd: root, encoding: "utf8", env: sandboxGitEnv() }).trim() === "true";
+    }
+    catch {
+        marked = false;
+    }
+    if (linked) {
+        return add("primary checkout", true, "a linked worktree — never the primary, whatever the shared .git/config says");
+    }
+    if (marked) {
+        return add("primary checkout", true, "MARKED — pre-commit refuses commits here and post-checkout keeps it detached at origin/main");
+    }
+    advise("primary checkout", "not marked, so the primary-checkout guards are INERT here. Correct for the lab, a worker or a "
+        + "colleague's clone; wrong for the machine that drives the fleet.", "pnpm run primary:mark -- --set   (only on the fleet-driving checkout — see docs/primary-checkout.md)");
+}
+function checkControlPlaneIsolation() {
+    // `~` is a SHELL expansion, not a filesystem one: `existsSync("~/.ssh/...")` is always false, which
+    // would make this guard report every machine as compliant. The silent-pass failure mode, in the guard
+    // written because a document silently passed.
+    const raw = process.env.A11Y_SSH_KEY || "~/.ssh/a11y-witness_ed25519";
+    const keyPath = raw.startsWith("~/") ? resolve(homedir(), raw.slice(2)) : raw;
+    const hasFleetKey = existsSync(keyPath);
+    const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
+    const hasNodeModules = existsSync(resolve(root, "node_modules"));
+    // A workspace is a checkout with sources, which is what makes "delete node_modules" the wrong advice
+    // here and the right advice on a control plane.
+    const isWorkspace = existsSync(resolve(root, "packages")) && existsSync(resolve(root, "package.json"));
+    const verdict = controlPlaneIsolation({ hasNodeModules, hasFleetKey, isWorkspace });
+    // NOT a hard failure: this machine cannot do its job without the key today, and a doctor that refuses
+    // to say READY over an architectural debt would simply be ignored. It is reported every run so it stays
+    // visible, which is the difference between a known debt and a forgotten one.
+    if (!verdict.violated)
+        return add("isolation", true, verdict.why);
+    advise("isolation", verdict.why, "docs/control-plane-plan.md L3 — drive the control plane rather than holding its keys");
+}
+/**
+ * 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, thisCheckoutRootReal) {
+    return resolvedRealPath === thisCheckoutRootReal
+        || resolvedRealPath.startsWith(thisCheckoutRootReal.endsWith("/") ? thisCheckoutRootReal : `${thisCheckoutRootReal}/`);
+}
+/**
+ * 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) {
+    const idx = resolvedRealPath.indexOf("/packages/");
+    return idx === -1 ? null : resolvedRealPath.slice(0, idx);
+}
+/** @type {(cmd: string, args: string[]) => string} */
+const defaultTscRun = (cmd, args) => execFileSync(cmd, args, { encoding: "utf8" });
+/**
+ * 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, { run = defaultTscRun } = {}) {
+    /** @type {string} */
+    let output;
+    try {
+        const tsc = pnpmCliInvocation(["exec", "tsc", "--build", "--dry", tsconfigPath]);
+        output = run(tsc.command, tsc.args);
+    }
+    catch (error) {
+        // `--dry` still exits 0 for a stale project (measured); a thrown error here is a REAL failure --
+        // a missing tsconfig, a syntax error blocking even the dry check -- and its stdout, if any, is still
+        // worth reading rather than discarded.
+        output = /** @type {{stdout?: string}} */ (error)?.stdout ?? "";
+        if (!output)
+            return null;
+    }
+    const line = output.split("\n").find((l) => l.includes(tsconfigPath));
+    if (!line)
+        return null;
+    return /is up to date/.test(line);
+}
+/**
+ * ", N commit(s) behind origin/main" or "" -- best-effort, and silently empty on any failure (not a git
+ * checkout at all, no `origin/main`, `otherRoot` unknown). This is a NOTE on an already-advisory finding,
+ * not itself a fact `doctor` promises; the resolution mismatch is reported either way.
+ *
+ * @param {string | null} otherRoot
+ * @returns {string}
+ */
+function behindOriginMainNote(otherRoot) {
+    if (!otherRoot)
+        return "";
+    try {
+        const behindBy = execFileSync("git", ["rev-list", "--count", "HEAD..origin/main"], { cwd: otherRoot, encoding: "utf8", env: sandboxGitEnv() }).trim();
+        return behindBy === "0" ? "" : `, ${behindBy} commit(s) behind origin/main`;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * WHOSE dist a cross-package import actually resolves to, and is IT stale (#256) -- both computed from
+ * the exact SPECIFIER a real import site in this repo uses, never the bare package name. CLAUDE.md's own
+ * recorded lesson: "resolving @a11ign/judge does not prove @a11ign/judge/rules came from your
+ * tree" -- a package can export subpaths from elsewhere, so resolving the root proves nothing about a
+ * subpath. `@a11ign/judge/rules` is a real specifier this repo imports
+ * (`packages/lab/scripts/score-rules.ts` and others), not a synthetic probe.
+ *
+ * ADVISORY, never a hard failure -- same reasoning as `isolation` above: a worktree resolving to the
+ * primary's dist can still run every command correctly today, and a doctor that refused READY over an
+ * environmental fact would be ignored, which is how a guard gets switched off. It is reported every run
+ * so a stale answer is a known condition, not a silent one.
+ */
+function checkCrossPackageDist() {
+    const specifier = "@a11ign/judge/rules";
+    const thisCheckoutRoot = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
+    /** @type {string} */
+    let resolvedRealPath;
+    try {
+        resolvedRealPath = realpathSync(createRequire(import.meta.url).resolve(specifier));
+    }
+    catch (error) {
+        return advise("dist-resolution", `could not resolve ${specifier} to check whose dist it comes from -- `
+            + `${ /** @type {Error} */(error).message}`, "pnpm run build");
+    }
+    if (resolvesToThisCheckout(resolvedRealPath, realpathSync(thisCheckoutRoot))) {
+        add("dist-resolution", true, `${specifier} resolves to this checkout's own dist`);
+    }
+    else {
+        const behindNote = behindOriginMainNote(checkoutRootFor(resolvedRealPath));
+        advise("dist-resolution", `${specifier} resolves to ${resolvedRealPath} (NOT this checkout${behindNote})`, "pnpm run primary:update && pnpm run build   # if that is the primary checkout");
+    }
+    // THE HALF A RESOLUTION CHECK ALONE MISSES: resolving to your OWN tree is no protection if your own
+    // dist is stale -- so this checks freshness of whichever checkout the specifier ACTUALLY resolved to,
+    // not always this one. `tsc --build --dry`, never a raw mtime comparison -- see `tscProjectUpToDate`'s
+    // own doc for the live-measured reason.
+    const distRoot = checkoutRootFor(resolvedRealPath) ?? thisCheckoutRoot;
+    const tsconfigPath = resolve(distRoot, "packages/judge/tsconfig.json");
+    const upToDate = tscProjectUpToDate(tsconfigPath);
+    if (upToDate === null) {
+        return advise("dist-freshness", `could not ask tsc whether ${tsconfigPath} is up to date`, "pnpm run build");
+    }
+    if (upToDate) {
+        return add("dist-freshness", true, `packages/judge under ${distRoot} is up to date (tsc --build --dry)`);
+    }
+    advise("dist-freshness", `packages/judge under ${distRoot} is NOT up to date (tsc --build --dry) -- a `
+        + "build compiled before the source it now reflects", "pnpm run build   # in that checkout");
+}
+// The DEFAULT here was "codex", and every part of that was wrong. `judge.ts` has no codex case at all —
+// it offers local, anthropic and openai — so with JUDGE_BACKEND unset (the normal case) this told the
+// operator to "install Codex and run: codex login" for a backend the product cannot use. And setting
+// JUDGE_BACKEND=local fell into the other branch and checked JUDGE_BASE_URL, which local does not need.
+// Both answers were wrong, in a command whose whole promise is that every check names its own fix.
+//
+// Mirrors judge.ts's default deliberately: a doctor that disagrees with the thing it inspects is worse
+// than no doctor.
+async function checkJudge() {
+    // `||`, not `??`: an env var set to the EMPTY string is how CI passes "unset", and `??` only defaults
+    // on nullish — so an empty JUDGE_BACKEND matched no backend and reported a typo that nobody made.
+    const backend = (process.env.JUDGE_BACKEND || "local").toLowerCase();
+    if (backend === "local") {
+        const weights = resolve(SCORER_MODEL_DIR, "model.safetensors");
+        return add("judge", existsSync(weights), existsSync(weights) ? "backend=local, trained scorer present" : "backend=local, but the trained scorer is missing", `expected weights at ${weights} — they ship in the repo, so this means an incomplete checkout`);
+    }
+    if (backend === "anthropic" || backend === "openai") {
+        const key = backend === "anthropic" ? "ANTHROPIC_API_KEY" : "JUDGE_BASE_URL";
+        return add("judge", !!process.env[key], `backend=${backend}`, `export ${key}=...`);
+    }
+    // Refuse an unknown backend rather than reporting on one that will not run — the same rule action.yml
+    // applies, because a typo must not quietly change which judge assessed the page.
+    add("judge", false, `backend=${backend} is not one of local, anthropic, openai`, "unset JUDGE_BACKEND to use the default local scorer");
+}
+// Workers, as a POOL, and with the right idea of what "ready" means.
+//
+// This check used to look at one VM and fail if it was not started. That was true before runs
+// managed the VM themselves; now a stopped worker is the correct resting state -- a run starts
+// what it needs and puts it back afterwards -- so reporting it as FAIL told an agent the
+// environment was broken when it was idle. One did exactly that: it went hunting for a
+// decommissioned worker on another host and then reached for the UTM GUI.
+//
+// Ready means "a run can proceed", not "everything is already running".
+async function checkWorker() {
+    if (WORKERS_ENV.length)
+        return checkConfiguredFleet(WORKERS_ENV);
+    // THE INVENTORY IS A FLEET, and `doctor` could not see one.
+    //
+    // It resolved A11Y_WORKERS, then the local UTM pool, then gave up — so on a Mac with any registered VM
+    // it reported the DEPRECATED local guests and never `inventory.yml`, which every other fleet command
+    // treats as the source of truth. Measured 2026-08-29 on one machine, at one moment: `doctor` said
+    // "2 worker(s), all stopped — READY" while `worker:code` said "checking 5 worker(s) from inventory.yml"
+    // and `fleet:status` showed those five busy with a corpus run.
+    //
+    // Three commands describing three different fleets, and `doctor` is the one CLAUDE.md tells an agent to
+    // run FIRST. Its `next_command` said `training:capture`, which would have captured on the wrong machines.
+    //
+    // THE INVENTORY WINS OUTRIGHT. The local UTM pool is deprecated — it was a testing arrangement — so it
+    // is a fallback for a machine with no inventory, never a contender with one. Anything else reproduces
+    // the divergence above on any developer Mac that still has a bundle registered.
+    const inventory = namedInventoryWorkers();
+    if (inventory.length)
+        return checkConfiguredFleet(inventory);
+    if (process.platform !== "darwin" || !existsSync(CTL)) {
+        return add("worker", false, "no A11Y_WORKERS set, no inventory.yml fleet, and no local VM tooling here", "set A11Y_WORKERS=http://host:8765[,http://host2:8765], or see docs/getting-started.md");
+    }
+    let pool;
+    try {
+        pool = JSON.parse(await shell(CTL, ["pool"], 90000));
+    }
+    catch (e) {
+        return add("worker", false, `could not query the local pool (${commandError(e)})`, workerControlFix(commandError(e)));
+    }
+    if (!pool.length) {
+        return add("worker", false, "no worker VM registered", "UTM has no registered worker VM; re-register an existing a11y-worker*.utm bundle, or build one from docs/getting-started.md");
+    }
+    const running = pool.filter((/** @type {any} */ vm) => vm.state === "started");
+    const healthy = pool.filter((/** @type {any} */ vm) => vm.healthy);
+    const brokenlyRunning = running.filter((/** @type {any} */ vm) => !vm.healthy);
+    const summary = pool.map((/** @type {any} */ vm) => `${vm.name}=${vm.healthy ? vm.ip : vm.state}`).join(" ");
+    // A VM that is RUNNING but not answering is a genuine fault. One that is stopped is not.
+    if (brokenlyRunning.length) {
+        add("worker", false, `${summary} — ${brokenlyRunning.map((/** @type {any} */ v) => v.name).join(", ")} running but not answering`, "Start-ScheduledTask -TaskName a11ysrv on that guest, or " + `${CTL} stop && ${CTL} up`);
+    }
+    else if (healthy.length) {
+        add("worker", true, `${healthy.length}/${pool.length} ready — ${summary}`);
+    }
+    else {
+        add("worker", true, `${pool.length} worker(s), all stopped — a run starts them automatically (${summary})`);
+    }
+    // Same shape as a configured fleet, so the two diagnostics below have ONE implementation. They were
+    // pure functions over /health JSON that only the UTM branch could reach, which meant a bare-metal
+    // fleet -- the direction this project is going -- got neither.
+    const reachable = pool.filter((/** @type {any} */ v) => v.healthy && v.ip)
+        .map((/** @type {any} */ v) => ({ name: v.name, url: `http://${v.ip}:${v.port}` }));
+    const probed = await probeAll(reachable);
+    await checkDegradedWorkers(probed);
+    checkFleetConsistency(probed, pool.length);
+    checkHostCapacity(pool);
+    const busy = pool.filter((/** @type {any} */ vm) => vm.busy);
+    if (busy.length) {
+        add("contention", false, `${busy.map((/** @type {any} */ v) => v.name).join(", ")} busy with a capture — another shell or agent is using the pool`, 
+        // #1059: no `fix`, because waiting is not a command. The advice is a note and `next_command` is null.
+        { fix: null, note: "wait for it, or you will both see the other's restarts as breakage" });
+    }
+}
+/**
+ * The fleet named by A11Y_WORKERS: probe every one, report per worker, never fail on a single loss.
+ *
+ * "Ready means a run can proceed" is this file's own rule, and for a fleet that means AT LEAST ONE
+ * worker answering -- not all of them. The dispatcher already evicts a worker after three consecutive
+ * failures and requeues its cases (capture-decisions.mjs), so one dead machine costs throughput, not
+ * the run. Failing the whole check for it would tell an agent the environment is broken when nine
+ * workers are sitting idle and ready, which is the exact mistake the comment above checkWorker
+ * describes for a stopped VM.
+ */
+/**
+ * Ask every worker once, and keep the failures as data.
+ *
+ * Shared because both fleet branches feed the same two diagnostics, and because `doctor` used to probe
+ * `/health` THREE times per worker — once here, once for degradation, once for consistency — so the three
+ * sections could describe three different moments. A box that went busy between them was reported ready by
+ * one and silently skipped by the next.
+ *
+ * @param {{name: string, url: string}[]} workers
+ */
+async function probeAll(workers) {
+    const probed = [];
+    for (const w of workers) {
+        try {
+            probed.push({ ...w, health: await httpJson(`${w.url}/health`) });
+        }
+        catch (e) {
+            probed.push({ ...w, health: null, error: /** @type {any} */ (e).message });
+        }
+    }
+    return probed;
+}
+async function checkConfiguredFleet(/** @type {any} */ workers) {
+    const probed = await probeAll(workers);
+    const reachable = probed.filter((p) => p.health);
+    const ready = reachable.filter((p) => p.health.ready);
+    const state = (/** @type {any} */ p) => {
+        if (!p.health)
+            return "unreachable";
+        if (p.health.busy)
+            return "busy";
+        return p.health.ready ? "ready" : "not-ready";
+    };
+    const summary = probed.map((p) => `${p.name}=${state(p)}`).join(" ");
+    if (!reachable.length) {
+        return add("worker", false, `${workers.length} configured, none answering — ${summary}`, "check those machines are up and their a11ysrv task is running; "
+            + `curl ${workers[0].url}/health from this host`);
+    }
+    // A worker that answers but is not ready is normal right after a boot and clears on its own --
+    // /health's own note says so -- which is why this reports the count rather than failing on it.
+    add("worker", true, `${ready.length}/${workers.length} ready — ${summary}`);
+    const unreachable = probed.filter((p) => !p.health);
+    if (unreachable.length) {
+        add("fleet reach", true, `${unreachable.length} not answering: ${unreachable.map((p) => p.name).join(", ")}`
+            + " — the run will dispatch to the rest");
+    }
+    // ONE PROBE, PASSED DOWN. These re-probed `/health` themselves, so `doctor` made three requests per
+    // worker and the three sections could describe three different moments — a box that went busy or
+    // unreachable between them was reported ready by one and silently skipped by the next.
+    await checkDegradedWorkers(probed);
+    await checkFleetConsistency(probed, workers.length);
+    // Contention only matters when there is nowhere left to dispatch. One busy worker in a fleet of ten
+    // is a run in progress, not a conflict -- flagging it would make doctor fail during normal use.
+    if (reachable.length && reachable.every((p) => p.health.busy)) {
+        add("contention", false, `all ${reachable.length} reachable worker(s) busy — another run or agent has the fleet`, 
+        // #1059: no `fix`, because waiting is not a command. The advice is a note and `next_command` is null.
+        { fix: null, note: "wait for it, or you will both see the other's restarts as breakage" });
+    }
+}
+// A guest whose NVDA fails on every capture keeps serving and keeps passing — it just costs 4x.
+//
+// The run's eviction rule needs three consecutive FAILURES, and the worker's own retry means there are
+// none, so this never surfaced anywhere. Measured on this pool: one worker needed a recovery on 4 of 4
+// captures (nvdaStart 19.1s each, WALL 122.9s) beside one that needed none (WALL 40.6s). Reported, not
+// failed: a degraded worker is slow, not broken, and pulling it costs more throughput than it saves.
+async function checkDegradedWorkers(/** @type {any} */ probed) {
+    for (const w of probed) {
+        if (!w.health)
+            continue; // unreachable is already the worker check's business
+        const { degraded, reason } = assessWorker(w.health.vitals);
+        if (degraded) {
+            add(`worker ${w.name}`, true, `DEGRADED — ${reason}`, `re-provision ${w.name}: packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1, elevated,`
+                + " in the interactive session");
+        }
+    }
+}
+/**
+ * Are the guests interchangeable?
+ *
+ * The pool assumes so: cases go to whichever worker is free, the cache lets any guest reuse another's
+ * evidence, and a good/bad pair is only comparable because both halves came from equivalent machines.
+ * Two real divergences happened in one day -- Edge auto-updated on one guest while the others stayed
+ * behind, and StartupBoostEnabled read 1 on two guests and 0 on a third -- and BOTH were caught by a
+ * human reading a console by eye. That is not a detection mechanism.
+ *
+ * Never a FAIL. A run on slightly mismatched guests is worse than one on matched guests and far better
+ * than no run, and a diagnostic must not be the thing that takes the pool offline.
+ */
+function checkFleetConsistency(/** @type {any} */ probed, /** @type {number} */ configured) {
+    const guests = probed.filter((/** @type {any} */ w) => w.health)
+        .map((/** @type {any} */ w) => ({ worker: w.url, environment: w.health.environment, policy: undefined }));
+    const { consistent, mismatches, fields } = fleetConsistency(guests);
+    if (guests.length < 2)
+        return;
+    if (consistent) {
+        add("fleet", true, fleetAgreementLine({ agreeing: guests.length, configured, fields }));
+        return;
+    }
+    // The remedy NAMES THE FIELDS THAT DIFFER, derived from the mismatches, and that is the same fix as
+    // the agreement line below: it used to retype "browser, screen reader, OS and protocol" too, so a
+    // fleet split on `displayMode` was told to go and align four fields that already matched.
+    add("fleet", true, `INCONSISTENT — ${describeMismatches(mismatches).join("; ")}`, "re-provision the odd one out so every worker reports the same "
+        + `${mismatches.map((/** @type {any} */ m) => m.field).join(", ")}`);
+}
+/**
+ * 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 }) {
+    const rest = agreeing < configured ? " — the rest could not be asked" : "";
+    const coverage = fields.coverage;
+    // NO COUNTS SUPPLIED IS A CANNOT-ASK, NOT A PASS — `fleet:status` takes the same line on the same
+    // shape. A caller carrying the pre-#2019 `fields` has answered "did anybody report each field" and
+    // not "how many", so it cannot rule out the 1-of-3 case; falling back to `compared` here would
+    // restore the sentence this function exists to stop making, and nothing would say so.
+    if (coverage === undefined) {
+        return `${agreeing} of ${configured} guests agree, and no field coverage was supplied, so WHICH `
+            + `fields were compared, and by HOW MANY guests, was never asked${rest}`;
+    }
+    const whole = coverage.filter(({ reported, asked }) => reported === asked).map(({ field }) => field);
+    const named = whole.length === 0 ? "" : ` (${whole.join(", ")})`;
+    const gaps = [partialClause(coverage), uncheckedClause(coverage)].filter((clause) => clause !== "");
+    return `${agreeing} of ${configured} guests agree on ${whole.length} of ${coverage.length} `
+        + `field(s)${named}${rest}${gaps.join("")}`;
+}
+/** "it"/"them" for a clause that names a list, so one gap does not read as a plural. */
+const itOrThem = (/** @type {number} */ count) => (count === 1 ? "it" : "them");
+/**
+ * #2034's clause: the fields SOME compared guests reported and others did not, each with its `k of N`.
+ *
+ * NAMED WITH ITS COUNT, never counted — the same choice `fleet:status`' `partialClause` makes, and for
+ * the same reason #1997 gave for naming the zero case. "1 field was partly reported" sends a reader back
+ * to `doctor`; "displayMode (1 of 3 reported it)" tells them two boxes owe an answer, which is the
+ * finding — either the converge did not reach them, or their probe for the field failed (#1953).
+ *
+ * @param {{ field: string, reported: number, asked: number }[]} coverage
+ * @returns {string} empty when no field is partly reported
+ */
+function partialClause(coverage) {
+    const partial = coverage.filter(({ reported, asked }) => reported > 0 && reported < asked);
+    if (partial.length === 0)
+        return "";
+    const named = partial.map(({ field, reported, asked }) => `${field} (${reported} of ${asked} reported it)`);
+    return `; reported by only SOME of the compared guests, so agreement says nothing about `
+        + `${itOrThem(partial.length)}: ${named.join(", ")}`;
+}
+/**
+ * #1997's clause: the fields asked of everybody and answered by nobody.
+ *
+ * NAMED, not counted: "one field was not compared" sends a reader back to doctor, and "displayMode was
+ * not compared" sends them to the deploy that would report it.
+ *
+ * @param {{ field: string, reported: number, asked: number }[]} coverage
+ * @returns {string} empty when every asked field drew at least one value
+ */
+function uncheckedClause(coverage) {
+    const unchecked = coverage.filter(({ reported }) => reported === 0).map(({ field }) => field);
+    if (unchecked.length === 0)
+        return "";
+    return `; NOT compared on any guest, so agreement says nothing about ${itOrThem(unchecked.length)}: `
+        + unchecked.join(", ");
+}
+// Can this host actually hold the pool it has registered?
+//
+// Not a fault, and never a FAIL: a capped pool runs fine, just narrower. It is reported because the
+// alternative is invisible. Three guests on this 36 GB Mac made every capture 1.6x slower than one
+// and produced mute-NVDA failures, and from outside that reads as "the workers are degrading" rather
+// than "the host is out of memory" — which is exactly how it was misread for a day.
+function checkHostCapacity(/** @type {any} */ pool) {
+    const availableMb = availableHostMemoryMb();
+    if (availableMb === null || !pool.length)
+        return;
+    // Guests already up have paid for their memory and are not counted in `availableMb`, so they are
+    // added back — otherwise a running worker makes the host look smaller than it is.
+    const running = pool.filter((/** @type {any} */ vm) => vm.state === "started").length;
+    const poolSize = pool.length;
+    const limit = workersHostCanRun({ availableMb, alreadyRunning: running });
+    const detail = `~${availableMb} MB available — room for ${Math.min(limit, poolSize)} of ${poolSize} worker(s)`;
+    add("host memory", true, limit >= poolSize
+        ? detail
+        : `${detail}; the rest stay stopped so the run does not swap (override: A11Y_MAX_WORKERS)`);
+}
+// Dataset capture needs the pages served, and the guest must be able to reach them — the
+// host's localhost is not reachable from inside the VM. The capture command leases the page
+// server for the run, so an idle host with no listener on this port is ready, not broken.
+async function checkDatasetPages() {
+    const manifestPath = resolve(DATASET, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        return add("dataset", false, "no manifest — the dataset has not been generated", "pnpm run training:generate");
+    }
+    // Ask for a REAL page, not `/`.
+    //
+    // "Something answers on :5050" is not the same as "our pages are being served", and the difference
+    // has already cost a dataset: a stray server on that port reported "Capture complete: 3/3 cases"
+    // while every transcript read "Error code: 404". A leftover `npx serve` from another directory
+    // answers the root happily and 404s every case. Four of them were running on this host today, which
+    // is how likely that is.
+    const sample = JSON.parse(readFileSync(manifestPath, "utf8")).cases?.[0]?.id;
+    const probe = sample ? `${sample}/good.html` : "";
+    try {
+        const response = await fetch(`http://localhost:${PAGES_PORT}/${probe}`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!response.ok) {
+            return add("pages", false, `:${PAGES_PORT} answers but returns HTTP ${response.status} for ${probe} — wrong directory`, `something else holds the port. Stop it; training:capture will lease the dataset server automatically`);
+        }
+        add("pages", true, `serving the dataset on :${PAGES_PORT} (verified ${probe || "/"})`);
+    }
+    catch {
+        add("pages", true, `nothing serving on :${PAGES_PORT} — training:capture leases it automatically`);
+    }
+}
+// A run left mid-flight is the difference between "start" and "--resume", and getting it
+// wrong either re-captures for hours or silently skips work.
+function checkRunState() {
+    const progress = resolve(DATASET, "capture-progress.json");
+    if (!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");
+    if (!p.finishedAt) {
+        return add("run", false, `a run is UNFINISHED (started ${p.startedAt})`, "pnpm run training:wait, or pnpm run training:capture -- --resume --no-cache");
+    }
+    const failed = Object.values(p.cases ?? {}).filter((c) => c.status === "failed").length;
+    add("run", failed === 0, `last run ${p.outcome ?? "finished"}`, failed ? "pnpm run training:capture -- --resume --no-cache" : null);
+}
+// --- report ---------------------------------------------------------------
+// The single most useful line for anything automated: what to run next. A list of green ticks
+// still leaves a caller deciding, and deciding is where they go wrong.
+/**
+ * #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 = checks) {
+    const broken = checkList.find((c) => !c.ok);
+    if (!broken)
+        return "pnpm run training:capture";
+    return broken.fix ?? 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) {
+    if (line === null)
+        return false; // absent is not unrunnable; the caller distinguishes them
+    const first = line.trim().split(/\s+/)[0] ?? "";
+    return /^(?:[A-Z][A-Z0-9_]*=\S*|pnpm|npm|npx|node|git|\.?\.?\/\S+|[a-z0-9_-]+\.(?:sh|mjs|js|ts|py))$/.test(first);
+}
+/**
+ * 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) {
+    return checkList.every((c) => c.ok || GATES[c.name] === false);
+}
+/** Every DECLARED check name, gating or not -- so a test can compare the two sets without a literal. */
+export const allChecks = () => Object.keys(GATES);
+/** Which checks decide `ready`, for a test that must not retype the list. */
+export const gatingChecks = () => Object.entries(GATES).filter(([, gates]) => gates).map(([name]) => name);
+/** The checks `doctor` runs, in order. Injectable so a throwing one can be driven without breaking a tree. */
+const DEFAULT_STEPS = [checkPrimaryCheckoutMark, checkControlPlaneIsolation, checkCrossPackageDist,
+    checkJudge, checkWorker, checkDatasetPages, checkRunState];
+/**
+ * #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) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ready: false, error: message, checks: [] };
+}
+/**
+ * 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 async function doctorRun(deps = {}) {
+    const { steps = DEFAULT_STEPS, json = JSON_OUT, out = console.log, err = console.error } = deps;
+    try {
+        for (const step of steps)
+            await step();
+    }
+    catch (error) {
+        // NOTHING BUT JSON REACHES STDOUT IN `--json` MODE. A `console.log` here would corrupt the document
+        // for every consumer, which is the failure this exists to prevent rather than to introduce.
+        if (json)
+            out(JSON.stringify(errorDocument(error), null, 2));
+        // The HUMAN path keeps the stack. Only the parsed format has to give it up, and it gives it up for a
+        // document a consumer can read -- not to make the failure quieter.
+        else
+            err(error instanceof Error && error.stack ? error.stack : `doctor: ${errorDocument(error).error}`);
+        return 1;
+    }
+    return renderDoctor({ json, out });
+}
+/**
+ * @param {{ json: boolean, out: (line: string) => void }} deps
+ * @returns {number}
+ */
+function renderDoctor({ json, out }) {
+    const ready = readyFrom(checks);
+    if (json) {
+        out(JSON.stringify({ ready, next_command: nextCommand(), checks }, null, 2));
+    }
+    else {
+        for (const c of checks) {
+            out(`${c.advisory ? "DEBT" : c.ok ? "OK  " : "FAIL"}  ${c.name.padEnd(11)} ${c.detail}`);
+            if ((!c.ok || c.advisory) && c.fix)
+                out(`        fix: ${c.fix}`);
+            // #1059: the advice a shell cannot run is PRINTED, just not in the field something executes.
+            if ((!c.ok || c.advisory) && c.note)
+                out(`        note: ${c.note}`);
+        }
+        out(`\n${ready ? "READY" : "NOT READY — see the fixes above"}`);
+        const next = nextCommand();
+        // NO COMMAND IS SAID AS SUCH. "next: null" would read as a bug; "no single command" is the answer.
+        out(next === null ? "next: no single command — read the fixes and notes above" : `next: ${next}`);
+    }
+    return ready ? 0 : 1;
+}
+async function main() {
+    process.exit(await doctorRun());
+}
+// 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=doctor.mjs.map