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

package/dist/local-vm.js

@@ -0,0 +1,360 @@
+/**
+ * On-demand lifecycle for the local UTM worker VM.
+ *
+ * A Windows guest is never really idle -- Defender, Update and the search indexer keep it
+ * busy -- so leaving one running between captures costs the host real CPU. Cold start is
+ * cheap enough (12-15s to /health, measured) that starting it per run and shutting it down
+ * afterwards is the better trade.
+ *
+ * The default is to LEAVE THE VM AS FOUND, which needs no configuration to do the right
+ * thing: a VM that was stopped gets stopped again, a paused one gets re-paused, and one you
+ * had already started yourself is left alone. That last case matters -- a run must never
+ * shut down a VM somebody else is using.
+ *
+ * Everything UTM-specific lives in `local-worker/worker-ctl.sh` in this package (`json` emits the
+ * state this module reads). Nothing here knows about utmctl, bundles or bookmarks.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { networkInterfaces } from "node:os";
+import { availableHostMemoryMb, capacityReason, workersHostCanRun } from "./host-capacity.mjs";
+import { fleetScriptPaths } from "./fleet-scripts.mjs";
+import { inventoryWorkerUrls } from "./fleet-env.mjs";
+import { warnUtmDeprecated } from "./utm-deprecated.mjs";
+const execFileAsync = promisify(execFile);
+/** Where a hand-started worker on this machine has always lived. */
+export const DEFAULT_WORKER = "http://localhost:8765";
+// Relative to this module, not the process cwd: `npm run` happens to start in the repo
+// root, but a direct `tsx src/cli.ts` from elsewhere would not.
+const CTL = fleetScriptPaths().workerCtl;
+const STATUS_TIMEOUT_MS = 30_000;
+// Generous on purpose: `up` boots Windows, waits for auto-logon and then polls /health,
+// and worker-ctl gives that 180s of its own before giving up.
+const LIFECYCLE_TIMEOUT_MS = 300_000;
+const AFTER_RUN_VALUES = ["restore", "stop", "pause", "leave"];
+export function isAfterRun(v) {
+    return AFTER_RUN_VALUES.includes(v);
+}
+const IPV4_OCTETS = 4;
+function ipv4ToInt(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== IPV4_OCTETS || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return null;
+    return parts.reduce((acc, octet) => acc * 256 + octet, 0);
+}
+/**
+ * This host's address on the same subnet as the guest -- the gateway end of UTM's shared
+ * network (bridge100 on macOS). Derived by matching interfaces against the guest's address
+ * rather than assuming the usual `x.y.z.1`, because guessing an address that silently does
+ * not answer is worse than reporting that we could not find one.
+ */
+function hostAddressFor(guestIp) {
+    const guest = ipv4ToInt(guestIp);
+    if (guest === null)
+        return undefined;
+    for (const addresses of Object.values(networkInterfaces())) {
+        for (const a of addresses ?? []) {
+            if (a.family !== "IPv4" || a.internal)
+                continue;
+            const host = ipv4ToInt(a.address);
+            const mask = ipv4ToInt(a.netmask);
+            if (host === null || mask === null)
+                continue;
+            // Both sides go through the same int32 coercion, so addresses above 2^31 comparing
+            // as negative is harmless here.
+            if ((host & mask) === (guest & mask))
+                return a.address;
+        }
+    }
+    return undefined;
+}
+async function ctl(args, timeoutMs, vmName) {
+    const env = vmName ? { ...process.env, A11Y_VM_NAME: vmName } : process.env;
+    const { stdout } = await execFileAsync(CTL, args, { timeout: timeoutMs, encoding: "utf8", env });
+    return stdout;
+}
+/**
+ * The registered local VM, or null when there is nothing to manage: not macOS, no UTM, no
+ * VM registered under that name, or duplicate registrations (worker-ctl refuses to guess
+ * between those rather than risk acting on the wrong one).
+ */
+export async function findLocalVm() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        return JSON.parse(await ctl(["json"], STATUS_TIMEOUT_MS));
+    }
+    catch (e) {
+        // Absence is the normal case for anyone without a local VM, so this is a debug
+        // breadcrumb rather than a warning -- but never a silent catch.
+        if (process.env.A11Y_DEBUG_VM) {
+            process.stderr.write(`local VM lookup failed (continuing without one): ${e.message}\n`);
+        }
+        return null;
+    }
+}
+/** Which lifecycle action returns the VM to `stateBefore`. */
+function restoreAction(stateBefore) {
+    if (stateBefore === "started")
+        return "leave";
+    if (stateBefore === "paused")
+        return "pause";
+    return "stop";
+}
+async function releaseVm(action, stateBefore) {
+    const resolved = action === "restore" ? restoreAction(stateBefore) : action;
+    if (resolved === "leave")
+        return;
+    // Another run may have started a capture while ours was finishing. Shutting the guest
+    // down underneath it would look exactly like a worker crash, so stand down instead.
+    const now = await findLocalVm();
+    if (now?.busy) {
+        process.stderr.write(`worker is busy with another capture; leaving the VM ${now.state}\n`);
+        return;
+    }
+    process.stderr.write(`${resolved === "pause" ? "Pausing" : "Shutting down"} the local worker VM ...\n`);
+    await ctl([resolved], LIFECYCLE_TIMEOUT_MS);
+}
+/**
+ * Start (or resume) the local VM, returning its worker URL and the matching cleanup.
+ * Throws if the VM never becomes healthy -- there is no point judging a capture that could
+ * not happen.
+ */
+export async function acquireLocalWorker(vm, after) {
+    const stateBefore = vm.state;
+    if (stateBefore === "started" && vm.healthy) {
+        process.stderr.write(`Using the running local worker VM '${vm.name}' at ${vm.ip}\n`);
+    }
+    else {
+        process.stderr.write(`Local worker VM '${vm.name}' is ${stateBefore}; bringing it up ...\n`);
+        process.stderr.write(await ctl(["up"], LIFECYCLE_TIMEOUT_MS));
+    }
+    const ready = await findLocalVm();
+    if (!ready?.healthy || !ready.ip) {
+        throw new Error(`Local worker VM '${vm.name}' did not become healthy. Check it directly: ${CTL} status`);
+    }
+    return {
+        worker: `http://${ready.ip}:${ready.port}`,
+        source: "local-vm",
+        hostAddress: hostAddressFor(ready.ip),
+        release: () => releaseVm(after, stateBefore).catch((e) => {
+            // Report and move on. The run's verdict is the product; a VM left running is a
+            // resource leak the user can fix with one command, not a reason to fail the run.
+            process.stderr.write(`WARNING: could not release the local worker VM: ${e.message}\n`);
+        }),
+    };
+}
+/**
+ * Decide what to capture against, in priority order:
+ *
+ *   1. A worker the caller named is used as-is. Naming one is a statement that you are
+ *      managing it yourself, so the VM lifecycle is never touched.
+ *   2. Otherwise, `inventory.yml`'s bare-metal fleet — always-on boxes, so there is no VM
+ *      lifecycle to run: the first declared worker is leased with a no-op release.
+ *   3. Otherwise, a registered local UTM VM is started on demand and released afterwards.
+ *   4. Otherwise, the historical default, so a hand-run worker on this machine still works.
+ *
+ * FOUND 2026-09-06 (`docs/backlog.md` §8): this used to go straight from (1) to (3), never
+ * reading the inventory at all -- so a checkout WITH a bare-metal fleet declared and a UTM guest
+ * still registered (the ordinary state of a Mac that used to run the deprecated pool) leased the
+ * VM by default, exactly the wrong turn CLAUDE.md already records costing a capture-path change:
+ * "a deprecated path that is still the first one documented is not deprecated". `resolveWorkerPool`
+ * (`fleet-env.mjs`) already had the corrected order for the POOL case; this brings the single-worker
+ * case into line, and `worker-precedence.test.ts` is what is supposed to keep them there.
+ *
+ * Step 2 costs nothing and throws nothing for anyone without an `inventory.yml` -- a public
+ * consumer who installs this package -- because `inventoryWorkerUrls()` already treats an absent
+ * or unparsable file as "no fleet declared here" and returns `[]`. So the fall-through to (3) and
+ * (4) is byte-for-byte what it was before this change for that consumer; only a checkout that
+ * DECLARES a fleet sees new behaviour, and it sees the behaviour `doctor` and `worker:code`
+ * already assumed it had.
+ *
+ * A11Y_LOCAL_VM=0 skips step 3 for anyone who wants the pre-inventory local-VM behaviour back --
+ * unchanged in what it does, moved because inventory now sits ahead of it.
+ *
+ * Shared by every entry point that needs a worker, so the priority order cannot drift
+ * between them.
+ *
+ * `deps` is the injection seam: real callers get the real inventory reader and the real (shells
+ * out to `utmctl`) VM lookup, and a test supplies fakes for both, so the precedence can be proven
+ * without a filesystem `inventory.yml` or a UTM install. Called as `deps.inventory?.() ?? inventoryWorkerUrls()`
+ * rather than resolved into a local first — deliberately, so `inventoryWorkerUrls(` and `findLocalVm(`
+ * both appear as real CALLS at the exact decision point, which is what lets `worker-precedence.test.ts`
+ * read this function's actual order rather than only the shape of its signature.
+ */
+export async function leaseWorker({ worker, after }, deps = {}) {
+    const release = async () => { };
+    // Strip a trailing slash once, here, so no caller has to remember that `${worker}/capture`
+    // would otherwise produce a double slash.
+    if (worker)
+        return { worker: worker.replace(/\/$/, ""), source: "explicit", release };
+    const fleet = deps.inventory ? deps.inventory() : inventoryWorkerUrls();
+    if (fleet.length)
+        return { worker: fleet[0].replace(/\/$/, ""), source: "inventory.yml", release };
+    if (process.env.A11Y_LOCAL_VM === "0")
+        return { worker: DEFAULT_WORKER, source: "default", release };
+    // Reached only with no explicit worker and no inventory.yml entry — architecture-audit.md §8's own
+    // finding, named exactly: this fallback IS the deprecated path being the CLI's default. Warned, not
+    // refused, because deleting it is a separate proposal and some machines still only have a UTM guest
+    // to reach.
+    const vm = deps.findLocalVm ? await deps.findLocalVm() : await findLocalVm();
+    if (!vm)
+        return { worker: DEFAULT_WORKER, source: "default", release };
+    // Only once a VM exists: the notice says this run "manages a local UTM worker VM", which is false
+    // on a machine with none, and the stranger running the published `npx a11ign` is that machine (#3219).
+    warnUtmDeprecated("this run (no worker named, no fleet configured)");
+    return acquireLocalWorker(vm, after);
+}
+/**
+ * Rewrite a base URL the GUEST has to fetch so it points at this host rather than at
+ * `localhost`, which from inside the guest means the guest.
+ *
+ * This is the trap in dataset capture: the pages are served by a plain HTTP server on the
+ * Mac, and the default base URL is `http://localhost:5050`. Left alone, every capture
+ * loads the guest's own empty port and the transcripts come back describing nothing --
+ * with no error, because a connection refused inside Edge is not a worker failure.
+ */
+/**
+ * This host's address as seen from a worker at `workerUrl`, when the two share a subnet.
+ * Returns undefined for a hostname, or for a worker somewhere we have no interface onto --
+ * in which case the caller must be told where to reach us rather than have it guessed.
+ */
+export function hostAddressForWorker(workerUrl) {
+    try {
+        const { hostname } = new URL(workerUrl);
+        return ipv4ToInt(hostname) === null ? undefined : hostAddressFor(hostname);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function guestReachableUrl(baseUrl, lease) {
+    // Fall back to deriving it from the worker's own address.
+    //
+    // hostAddress used to be set only on the managed-VM path, so naming a worker explicitly --
+    // A11Y_WORKER, or any pool -- silently skipped the rewrite and every capture fetched the
+    // GUEST's localhost. Edge shows "localhost refused to connect", the title check rejects the
+    // capture, and three attempts are burned per page before it gives up. The worker being
+    // remote or explicit does not change the fact that it cannot reach our localhost.
+    const hostAddress = lease.hostAddress ?? hostAddressForWorker(lease.worker);
+    if (!hostAddress)
+        return baseUrl;
+    const parsed = new URL(baseUrl);
+    if (parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1")
+        return baseUrl;
+    parsed.hostname = hostAddress;
+    return parsed.toString().replace(/\/$/, "");
+}
+/** Every local worker VM, whatever state each is in. */
+async function findLocalPool() {
+    if (process.platform !== "darwin")
+        return [];
+    try {
+        return JSON.parse(await ctl(["pool"], STATUS_TIMEOUT_MS));
+    }
+    catch {
+        return [];
+    }
+}
+/** A11Y_MAX_WORKERS wins over the measurement: the operator may know something we cannot measure. */
+function configuredWorkerLimit() {
+    const configured = Number(process.env.A11Y_MAX_WORKERS);
+    return Number.isFinite(configured) && configured > 0 ? configured : null;
+}
+/**
+ * Which registered VMs should actually be running for this run?
+ *
+ * The pool used to start all of them. Three guests on a 36 GB host made every capture 1.6x slower
+ * than one, and caused mute-NVDA failures, because the guests were swapped out from under NVDA — so
+ * "how many VMs exist" was the wrong question and "how much memory is there" is the right one.
+ *
+ * Already-running VMs are preferred over stopped ones: starting a guest in order to leave a running
+ * one idle is pure churn. Note that a VM someone else has already started is never stopped here — it
+ * is simply not used — because a run must not shut down a worker it did not start.
+ */
+function chooseRunnableWorkers(pool) {
+    const availableMb = availableHostMemoryMb();
+    const running = pool.filter((vm) => vm.state === "started");
+    const limit = configuredWorkerLimit()
+        ?? workersHostCanRun({ availableMb, alreadyRunning: running.length });
+    if (limit >= pool.length)
+        return { chosen: pool, note: null };
+    const chosen = [...running, ...pool.filter((vm) => vm.state !== "started")].slice(0, limit);
+    return { chosen, note: capacityReason({ limit, wanted: pool.length, availableMb }) };
+}
+/**
+ * Lease every local worker VM: start what is not running, and put each one back afterwards.
+ *
+ * This exists because the pool path used to hand back a no-op release, so a pooled run left
+ * every VM running indefinitely — which is precisely the cost the single-worker lease was
+ * written to avoid, reintroduced the moment pooling became the normal way to run.
+ *
+ * Per-VM restore, not a blanket stop: a VM you had already started stays started, exactly as
+ * in the single-worker case. A long dataset run must not shut down a worker somebody else is
+ * using, and with a pool that is likelier, not less.
+ */
+export async function leaseWorkerPool(after) {
+    warnUtmDeprecated("the local UTM worker pool");
+    const pool = await findLocalPool();
+    if (pool.length < 2)
+        return null; // one VM is the single-worker path's job
+    const { chosen, note } = chooseRunnableWorkers(pool);
+    if (note)
+        process.stderr.write(note + "\n");
+    const chosenNames = new Set(chosen.map((vm) => vm.name));
+    const before = new Map(pool.map((vm) => [vm.name, vm.state]));
+    for (const vm of chosen) {
+        if (vm.state === "started" && vm.healthy)
+            continue;
+        process.stderr.write(`Local worker '${vm.name}' is ${vm.state}; bringing it up ...\n`);
+        try {
+            await ctl(["up"], LIFECYCLE_TIMEOUT_MS, vm.name);
+        }
+        catch (error) {
+            // One sick VM must not cancel the run. This threw and killed a resume outright while two other
+            // workers sat ready: a guest wedged in "stopping" failed `up`, the exception escaped the lease,
+            // and 1,000 cases went nowhere. Bringing up a pool is best-effort per member -- the readiness
+            // filter below is what decides who actually takes work, and it already fails loudly if nobody
+            // does.
+            process.stderr.write(`Local worker '${vm.name}' would not come up (${error.message.split("\n")[0]}); ` +
+                "continuing without it\n");
+        }
+    }
+    // Only workers we CHOSE, even if a VM we declined is up and healthy: taking work to a guest the
+    // capacity check excluded would defeat the check, and it may belong to somebody else's run.
+    const ready = (await findLocalPool()).filter((vm) => vm.healthy && vm.ip && chosenNames.has(vm.name));
+    if (!ready.length)
+        throw new Error("no local worker became healthy; check: worker-ctl.sh pool");
+    const missing = chosen.length - ready.length;
+    if (missing > 0) {
+        // Never silent: a run that quietly used two of three workers looks like an unexplained slowdown.
+        process.stderr.write(`${missing} of ${chosen.length} local workers are unavailable; running on the rest\n`);
+    }
+    process.stderr.write(`Pool of ${ready.length}: ${ready.map((v) => v.name).join(", ")}\n`);
+    return {
+        workers: ready.map((vm) => `http://${vm.ip}:${vm.port}`),
+        hostAddress: hostAddressFor(ready[0].ip),
+        release: async () => {
+            for (const vm of ready) {
+                const action = after === "restore" ? restoreAction(before.get(vm.name) ?? "stopped") : after;
+                if (action === "leave")
+                    continue;
+                try {
+                    // Check per VM: another run may have picked this one up while ours was finishing.
+                    const now = (await findLocalPool()).find((v) => v.name === vm.name);
+                    if (now?.busy) {
+                        process.stderr.write(`'${vm.name}' is busy with another capture; leaving it ${now.state}\n`);
+                        continue;
+                    }
+                    process.stderr.write(`${action === "pause" ? "Pausing" : "Shutting down"} '${vm.name}' ...\n`);
+                    await ctl([action], LIFECYCLE_TIMEOUT_MS, vm.name);
+                }
+                catch (e) {
+                    // One VM failing to stop must not strand the others.
+                    process.stderr.write(`WARNING: could not ${action} '${vm.name}': ${e.message}\n`);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=local-vm.js.map

package/dist/local-vm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-vm.js","sourceRoot":"","sources":["../src/local-vm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAEtD,uFAAuF;AACvF,gEAAgE;AAChE,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC,SAAS,CAAC;AAEzC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACjC,wFAAwF;AACxF,8DAA8D;AAC9D,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAKrC,MAAM,gBAAgB,GAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAE3E,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAQ,gBAA6B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AA6BD,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,SAAS,SAAS,CAAC,EAAU;IAC3B,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7G,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC,EAAE,CAAC;QAC3D,KAAK,MAAM,CAAC,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;YAChC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,QAAQ;gBAAE,SAAS;YAChD,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAClC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;gBAAE,SAAS;YAC7C,mFAAmF;YACnF,gCAAgC;YAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC,OAAO,CAAC;QACzD,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,SAAiB,EAAE,MAAe;IACnE,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAC5E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACjG,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAa,CAAC;IACxE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,+EAA+E;QAC/E,gEAAgE;QAChE,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oDAAqD,CAAW,CAAC,OAAO,IAAI,CAAC,CAAC;QACrG,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,SAAS,aAAa,CAAC,WAAmB;IACxC,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC9C,IAAI,WAAW,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,MAAgB,EAAE,WAAmB;IAC5D,MAAM,QAAQ,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5E,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO;IACjC,sFAAsF;IACtF,oFAAoF;IACpF,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;IAChC,IAAI,GAAG,EAAE,IAAI,EAAE,CAAC;QACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uDAAuD,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;QAC3F,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,4BAA4B,CAAC,CAAC;IACxG,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAY,EAAE,KAAe;IACpE,MAAM,WAAW,GAAG,EAAE,CAAC,KAAK,CAAC;IAC7B,IAAI,WAAW,KAAK,SAAS,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACvF,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE,CAAC,IAAI,QAAQ,WAAW,wBAAwB,CAAC,CAAC;QAC7F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,WAAW,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,oBAAoB,EAAE,CAAC,IAAI,gDAAgD,GAAG,SAAS,CACxF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,UAAU,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE;QAC1C,MAAM,EAAE,UAAU;QAClB,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,GAAG,EAAE,CACZ,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,CAAQ,EAAE,EAAE;YAC/C,+EAA+E;YAC/E,iFAAiF;YACjF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QACzF,CAAC,CAAC;KACL,CAAC;AACJ,CAAC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAE,MAAM,EAAE,KAAK,EAAgB,EAC/B,OAAqF,EAAE;IAEvF,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;IAC/B,2FAA2F;IAC3F,0CAA0C;IAC1C,IAAI,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAEtF,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;IACxE,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;IAEnG,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAErG,mGAAmG;IACnG,oGAAoG;IACpG,oGAAoG;IACpG,YAAY;IACZ,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC;IAC7E,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACvE,kGAAkG;IAClG,uGAAuG;IACvG,iBAAiB,CAAC,iDAAiD,CAAC,CAAC;IACrE,OAAO,kBAAkB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,KAAkB;IACnE,0DAA0D;IAC1D,EAAE;IACF,2FAA2F;IAC3F,yFAAyF;IACzF,4FAA4F;IAC5F,uFAAuF;IACvF,kFAAkF;IAClF,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,oBAAoB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5E,IAAI,CAAC,WAAW;QAAE,OAAO,OAAO,CAAC;IACjC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IACvF,MAAM,CAAC,QAAQ,GAAG,WAAW,CAAC;IAC9B,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AASD,wDAAwD;AACxD,KAAK,UAAU,aAAa;IAC1B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAe,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,qGAAqG;AACrG,SAAS,qBAAqB;IAC5B,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACxD,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,qBAAqB,CAAC,IAAgB;IAC7C,MAAM,WAAW,GAAG,qBAAqB,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,qBAAqB,EAAE;WAChC,iBAAiB,CAAC,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxE,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9D,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC5F,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAe;IACnD,iBAAiB,CAAC,2BAA2B,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,MAAM,aAAa,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,yCAAyC;IAE3E,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,IAAI;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9D,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,OAAO;YAAE,SAAS;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,KAAK,wBAAwB,CAAC,CAAC;QACvF,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,oBAAoB,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,+FAA+F;YAC/F,gGAAgG;YAChG,8FAA8F;YAC9F,8FAA8F;YAC9F,QAAQ;YACR,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB,EAAE,CAAC,IAAI,wBAAyB,KAAe,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK;gBAC5F,yBAAyB,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,gGAAgG;IAChG,4FAA4F;IAC5F,MAAM,KAAK,GAAG,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACtG,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAChG,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,iGAAiG;QACjG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,OAAO,MAAM,CAAC,MAAM,uDAAuD,CAAC,CAAC;IAC9G,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE1F,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACxD,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBACvB,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC7F,IAAI,MAAM,KAAK,OAAO;oBAAE,SAAS;gBACjC,IAAI,CAAC;oBACH,kFAAkF;oBAClF,MAAM,GAAG,GAAG,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;oBACpE,IAAI,GAAG,EAAE,IAAI,EAAE,CAAC;wBACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,8CAA8C,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;wBAC7F,SAAS;oBACX,CAAC;oBACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,KAAK,EAAE,CAAC,IAAI,SAAS,CAAC,CAAC;oBAC/F,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;gBACrD,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,qDAAqD;oBACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,MAAM,KAAK,EAAE,CAAC,IAAI,MAAO,CAAW,CAAC,OAAO,IAAI,CAAC,CAAC;gBAC/F,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/measure-guard.d.mts

@@ -0,0 +1,34 @@
+/**
+ * @param {string[]} workers
+ * @param {{ what: string, timeoutMs?: number, request?: import("./probe-outcome.mjs").ProbeRequest }} about
+ *   `what` names the measurement, so a refusal says what was NOT measured; `timeoutMs` and `request` are injectable
+ * @returns {Promise<void>} resolves when every worker is free; throws naming the busy ones
+ */
+export function refuseIfBusy(workers: string[], { what, timeoutMs, request }: {
+    what: string;
+    timeoutMs?: number;
+    request?: import("./probe-outcome.mjs").ProbeRequest;
+}): Promise<void>;
+/**
+ * A worker's `/health` `vitals`, or `null` when there are none to be had, and SAYS WHY through `warn`: a box that did
+ * not answer, one that refused, and one that answered without vitals are three different reasons for the same empty
+ * column in the report, and the run used to print none of them.
+ *
+ * @param {string} worker
+ * @param {{ timeoutMs?: number, request?: import("./probe-outcome.mjs").ProbeRequest, warn?: (line: string) => void }} [options]
+ * @returns {Promise<any>}
+ */
+export function sampleVitals(worker: string, { timeoutMs, request, warn }?: {
+    timeoutMs?: number;
+    request?: import("./probe-outcome.mjs").ProbeRequest;
+    warn?: (line: string) => void;
+}): Promise<any>;
+/**
+ * THE VITALS PROBE'S TIMEOUT, WITH ITS READING (#2683). `worker:compare` reads `vitals` before the rounds and again
+ * straight AFTER the last capture, so the second read is the LOADED case: a box that has just finished one can take
+ * up to about 10 s to answer (#2671, the reading beside `WORKER_PROBE_TIMEOUT_MS`), against 3.09 s for the slowest
+ * healthy first-after-idle answer. 20 s is that ceiling twice over, kept from before #2683 because it already clears
+ * both. A vitals sample that times out costs the run one column, so there is no reason to give it less.
+ */
+export const VITALS_TIMEOUT_MS: 20000;
+//# sourceMappingURL=measure-guard.d.mts.map

package/dist/measure-guard.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-guard.d.mts","sourceRoot":"","sources":["../src/measure-guard.mjs"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,sCALW,MAAM,EAAE,gCACR;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,YAAY,CAAA;CAAE,GAExF,OAAO,CAAC,IAAI,CAAC,CAmBzB;AAWD;;;;;;;;GAQG;AACH,qCAJW,MAAM,iCACN;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,YAAY,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACzG,OAAO,CAAC,GAAG,CAAC,CASxB;AAzBD;;;;;;GAMG;AACH,gCAAiC,KAAM,CAAC"}

package/dist/measure-guard.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * REFUSE TO MEASURE A BOX THAT IS BUSY — because the rule alone does not work.
+ *
+ * "Do not measure while something else is running" is written in `capture-protocol-plan.md`, by the person
+ * who then broke it FOUR times in two days:
+ *
+ *   a page-status audit        against :5050 while `capture:check` held it with a different root -> 4 false 404s
+ *   a transport probe          against a box running a gate -> 12 consecutive 429s read as timings
+ *   an idle-reap measurement   that timed `keepAliveTimeout` instead of the capture case
+ *   a capture-reap measurement against a busy fleet -> "responses" at 0.0-1.6 s, which are 429s
+ *
+ * Every one produced a NUMBER, which is what makes it dangerous: a measurement that fails loudly is
+ * harmless, and one that returns a plausible wrong figure gets believed. Three of the four were caught only
+ * because the number looked odd afterwards.
+ *
+ * So this is the repo's own housekeeping rule applied to measurement: anything a human has to remember is
+ * something that does not happen. A measurement script asks the box whether it is free FIRST, and refuses
+ * with the reason rather than sampling whatever a busy worker happens to say.
+ */
+import { describeProbe, probeHealth, WORKER_PROBE_TIMEOUT_MS } from "./probe-outcome.mjs";
+/**
+ * @param {string[]} workers
+ * @param {{ what: string, timeoutMs?: number, request?: import("./probe-outcome.mjs").ProbeRequest }} about
+ *   `what` names the measurement, so a refusal says what was NOT measured; `timeoutMs` and `request` are injectable
+ * @returns {Promise<void>} resolves when every worker is free; throws naming the busy ones
+ */
+export async function refuseIfBusy(workers, { what, timeoutMs = WORKER_PROBE_TIMEOUT_MS, request }) {
+    const states = await Promise.all(workers.map(async (worker) => {
+        const probe = await probeHealth(worker, { timeoutMs, request });
+        // `ready` is the right field, not `ok`: `ok` only ever meant "the HTTP server is answering", and a
+        // worker answered it while NVDA could not start. `ready` is false while a capture holds the box.
+        if (probe.outcome === "ready")
+            return { worker, free: true, why: "" };
+        // NOT ANSWERING IS NOT FREE, AND IT IS NOT "DOWN" EITHER. Measuring against a box that cannot answer /health
+        // produces exactly the kind of plausible-looking nonsense this guard exists to prevent, so it refuses; but
+        // what it says is the observed thing (#2683), one sentence per outcome from `describeProbe`.
+        return { worker, free: false, why: describeProbe(probe, { worker, timeoutMs }) };
+    }));
+    const busy = states.filter((s) => !s.free);
+    if (!busy.length)
+        return;
+    throw new Error(`REFUSING to measure ${what}: ${busy.length} of ${workers.length} worker(s) are not free `
+        + `— ${busy.map((b) => b.why).join(" ")} A measurement taken against a busy box `
+        + "samples its 429s, not its behaviour, and returns a number that looks real. Wait, or pass a worker "
+        + "that is free.");
+}
+/**
+ * THE VITALS PROBE'S TIMEOUT, WITH ITS READING (#2683). `worker:compare` reads `vitals` before the rounds and again
+ * straight AFTER the last capture, so the second read is the LOADED case: a box that has just finished one can take
+ * up to about 10 s to answer (#2671, the reading beside `WORKER_PROBE_TIMEOUT_MS`), against 3.09 s for the slowest
+ * healthy first-after-idle answer. 20 s is that ceiling twice over, kept from before #2683 because it already clears
+ * both. A vitals sample that times out costs the run one column, so there is no reason to give it less.
+ */
+export const VITALS_TIMEOUT_MS = 20_000;
+/**
+ * A worker's `/health` `vitals`, or `null` when there are none to be had, and SAYS WHY through `warn`: a box that did
+ * not answer, one that refused, and one that answered without vitals are three different reasons for the same empty
+ * column in the report, and the run used to print none of them.
+ *
+ * @param {string} worker
+ * @param {{ timeoutMs?: number, request?: import("./probe-outcome.mjs").ProbeRequest, warn?: (line: string) => void }} [options]
+ * @returns {Promise<any>}
+ */
+export async function sampleVitals(worker, { timeoutMs = VITALS_TIMEOUT_MS, request, warn = () => { } } = {}) {
+    const probe = await probeHealth(worker, { timeoutMs, request });
+    if (probe.outcome === "refused" || probe.outcome === "no-answer") {
+        warn(`  no vitals sampled: ${describeProbe(probe, { worker, timeoutMs })}\n`);
+        return null;
+    }
+    return probe.health?.vitals ?? null;
+}
+//# sourceMappingURL=measure-guard.mjs.map

package/dist/measure-guard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-guard.mjs","sourceRoot":"","sources":["../src/measure-guard.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,uBAAuB,EAAE,OAAO,EAAE;IAChG,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAC5D,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;QAChE,mGAAmG;QACnG,iGAAiG;QACjG,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;QACtE,6GAA6G;QAC7G,2GAA2G;QAC3G,6FAA6F;QAC7F,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACnF,CAAC,CAAC,CAAC,CAAC;IACJ,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO;IACzB,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,KAAK,IAAI,CAAC,MAAM,OAAO,OAAO,CAAC,MAAM,0BAA0B;UACtG,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,0CAA0C;UAC/E,oGAAoG;UACpG,eAAe,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAM,EAAE,EAAE,SAAS,GAAG,iBAAiB,EAAE,OAAO,EAAE,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,EAAE,GAAG,EAAE;IACzG,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;QACjE,IAAI,CAAC,wBAAwB,aAAa,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,IAAI,CAAC;AACtC,CAAC"}

package/dist/normalise-fleet.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=normalise-fleet.d.mts.map

package/dist/normalise-fleet.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalise-fleet.d.mts","sourceRoot":"","sources":["../src/normalise-fleet.mjs"],"names":[],"mappings":""}

package/dist/normalise-fleet.mjs

@@ -0,0 +1,76 @@
+// @ts-check
+// Bring every local guest to the same baseline, elevated, and prove it took.
+//
+//   npm run fleet:normalise
+//
+// Fleet CONSISTENCY is the point, more than any individual setting. Measured today:
+// StartupBoostEnabled was 1 on two guests and 0 on a third, and Edge had auto-updated from 150 to 151
+// on one before the others. Two guests with different browser behaviour producing into one corpus is
+// the same class of problem as a mixed OS image -- the cache key cannot see it, and the evidence is
+// quietly heterogeneous.
+//
+// Runs scripts/guest/normalise-fleet.cmd on each guest through guest-run.mjs, which is the only
+// channel that can do elevated work on these VMs (see that file for why the obvious ones cannot).
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { warnUtmDeprecated } from "./utm-deprecated.mjs";
+/**
+ * takes no flags: it brings every local guest to one baseline.
+ *
+ * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
+ */
+refuseUnknownFlags([], { entry: import.meta.url, command: "npm run fleet:normalise" });
+// A SIBLING in this package, resolved from this module. It was the cwd-relative path `scripts/guest-run.mjs`,
+// which stopped existing when M8 moved the fleet tooling — and was only ever right when the cwd happened to be
+// the repo root.
+const GUEST_RUN = fileURLToPath(new URL("./guest-run.mjs", import.meta.url));
+const run = promisify(execFile);
+const UTMCTL = "/Applications/UTM.app/Contents/MacOS/utmctl";
+// Only when RUN, never on import. Unguarded, importing this file SHELLED OUT to `utmctl list` and then
+// drove DISM across every registered guest -- so `node -e "import('./normalise-fleet.mjs')"`, which
+// CLAUDE.md makes the only real check that this file still loads, normalised the fleet as a side effect.
+//
+// This file has already been broken once by a path that nothing exercised: it read
+// `scripts/guest/normalise-fleet.cmd`, which the packages/ restructure moved, and `npm run fleet:normalise`
+// stayed broken while `doctor` printed it as the FIX for a failed consistency check. The import check is
+// what catches that class, so it has to be safe to run.
+async function main() {
+    warnUtmDeprecated("npm run fleet:normalise");
+    const { stdout } = await run(UTMCTL, ["list"]);
+    const vms = stdout.split("\n").slice(1)
+        .map((l) => l.trim().split(/\s+/))
+        .filter((c) => c.length >= 3 && c[2].startsWith("a11y-worker"))
+        .map((c) => ({ uuid: c[0], state: c[1], name: c[2] }));
+    if (!vms.length) {
+        process.stderr.write("no a11y-worker VMs registered\n");
+        process.exit(2);
+    }
+    // Resolved from THIS module, never the cwd. It read `scripts/guest/normalise-fleet.cmd` -- a path the
+    // packages/ restructure moved and nothing noticed, so `npm run fleet:normalise` has been broken, and
+    // doctor printed it as the FIX for a failed consistency check. A path spelled relative to the working
+    // directory is a path that breaks the moment anyone runs the command from somewhere else.
+    const script = fileURLToPath(new URL("./guest/normalise-fleet.cmd", import.meta.url));
+    const failures = [];
+    for (const vm of vms) {
+        // One at a time. Three guests doing DISM and service work simultaneously is exactly the disk
+        // contention this project spent a day diagnosing.
+        try {
+            const { stdout: out } = await run("node", [GUEST_RUN, vm.name, script, "--timeout=900"], { maxBuffer: 1 << 24 });
+            process.stdout.write(out);
+        }
+        catch (error) {
+            failures.push(vm.name);
+            process.stdout.write(`==> ${vm.name}: FAILED — ${(error instanceof Error ? error.message : String(error)).split("\n")[0]}\n`);
+        }
+    }
+    process.stdout.write(`\n${vms.length - failures.length}/${vms.length} guest(s) normalised` +
+        (failures.length ? `; failed: ${failures.join(", ")}\n` : "\n"));
+    process.stdout.write("Verify with: npm run doctor\n");
+    if (failures.length)
+        process.exit(1);
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href)
+    await main();
+//# sourceMappingURL=normalise-fleet.mjs.map

package/dist/normalise-fleet.mjs.map

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

package/dist/npm-cli-executable.d.mts

@@ -0,0 +1,42 @@
+/**
+ * @param {"npx" | "npm"} name
+ * @returns {string[]}
+ */
+export function npmCliScriptCandidates(name: "npx" | "npm"): string[];
+/**
+ * @param {"npx" | "npm"} name
+ * @returns {string}
+ */
+export function resolveNpmCliScript(name: "npx" | "npm"): string;
+/**
+ * @param {"npx" | "npm"} name
+ * @param {string[]} args
+ * @returns {{ command: string, args: string[] }}
+ */
+export function npmCliInvocation(name: "npx" | "npm", args: string[]): {
+    command: string;
+    args: string[];
+};
+/**
+ * #2301: `pnpm <args>` WITHOUT SPAWNING A `.cmd`, for the same reason `npmCliInvocation` exists, and with the
+ * added problem that pnpm is not always ON `PATH` at all: this host and the Windows workers run it as
+ * `corepack pnpm` (`packageManager` in the root manifest pins the version), while a CI runner has the
+ * shim `pnpm/action-setup` puts there. Three ways to reach it, tried in this order, each ending in an argv
+ * that `execFileSync` can run with no shell:
+ *
+ *   1. `npm_execpath`, when this process was itself started BY pnpm (`pnpm run ...`, `pnpm exec ...`): pnpm
+ *      says which script it is, so nothing is searched for and no other pnpm can be picked up by mistake.
+ *   2. a `pnpm` on `PATH`: the executable itself on POSIX; on Windows the shim is `pnpm.cmd`, so the
+ *      `pnpm.cjs` beside it is run through `process.execPath` instead.
+ *   3. `corepack` on `PATH`, the same way: `corepack pnpm` on POSIX, `corepack.js` beside `node.exe`
+ *      through `process.execPath` on Windows.
+ *
+ * Throws NAMING WHAT WAS TRIED, for the reason `resolveNpmCliScript` does.
+ * @param {string[]} args
+ * @returns {{ command: string, args: string[] }}
+ */
+export function pnpmCliInvocation(args: string[]): {
+    command: string;
+    args: string[];
+};
+//# sourceMappingURL=npm-cli-executable.d.mts.map

package/dist/npm-cli-executable.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm-cli-executable.d.mts","sourceRoot":"","sources":["../src/npm-cli-executable.mjs"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,6CAHW,KAAK,GAAG,KAAK,GACX,MAAM,EAAE,CAWpB;AAwBD;;;GAGG;AACH,0CAHW,KAAK,GAAG,KAAK,GACX,MAAM,CAUlB;AAED;;;;GAIG;AACH,uCAJW,KAAK,GAAG,KAAK,QACb,MAAM,EAAE,GACN;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAI/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wCAHW,MAAM,EAAE,GACN;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAgB/C"}