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

package/dist/git-safe-env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-safe-env.mjs","sourceRoot":"","sources":["../src/git-safe-env.mjs"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,EAAE;AACF,yGAAyG;AACzG,iGAAiG;AACjG,qHAAqH;AACrH,qCAAqC;AACrC,EAAE;AACF,0FAA0F;AAC1F,uGAAuG;AACvG,2GAA2G;AAC3G,kGAAkG;AAClG,uGAAuG;AACvG,uGAAuG;AACvG,EAAE;AACF,0FAA0F;AAC1F,uGAAuG;AACvG,oGAAoG;AACpG,kBAAkB;AAElB,gCAAgC;AAChC,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS;IACT,eAAe;IACf,gBAAgB;IAChB,yBAAyB;IACzB,sBAAsB;IACtB,kCAAkC;IAClC,gBAAgB;CACjB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAK,GAAG,EAAE;IACtC,iDAAiD;IACjD,MAAM,QAAQ,GAAG,EAAE,CAAC;IACpB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;AACnC,CAAC"}

package/dist/guest-run.d.mts

@@ -0,0 +1,26 @@
+/**
+ * The cmd line that registers and starts the elevated task.
+ *
+ * Built as a single string on purpose -- see trap 1 above. Exported so the quoting is testable without
+ * a guest, because it is the part that silently produces wrong answers rather than errors.
+ */
+/** @param {{ scriptPath: string, taskName?: string }} where */
+export function scheduleCommand({ scriptPath, taskName }: {
+    scriptPath: string;
+    taskName?: string;
+}): string;
+/**
+ * Wrap a caller's script so it always terminates with the sentinel.
+ *
+ * Without this there is no way to distinguish "still running" from "died on line one" -- which is
+ * exactly how a trim that crashed immediately looked identical to a trim in progress, for three boots.
+ */
+/** @param {string} body @param {string} outputFile */
+export function wrapScript(body: string, outputFile: string): string;
+/** Did the run finish? Exported because "no sentinel" and "no file" are different failures. */
+/** @param {string} output */
+/** @param {string | null} output */
+export function isComplete(output: string | null): boolean;
+/** Written by the wrapper as its last act. Absent means still running, or it died. */
+export const DONE_SENTINEL: "---GUEST-RUN-DONE---";
+//# sourceMappingURL=guest-run.d.mts.map

package/dist/guest-run.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-run.d.mts","sourceRoot":"","sources":["../src/guest-run.mjs"],"names":[],"mappings":"AAuDA;;;;;GAKG;AACH,+DAA+D;AAC/D,0DADY;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,UAIpD;AAED;;;;;GAKG;AACH,sDAAsD;AACtD,iCADY,MAAM,cAAe,MAAM,UAWtC;AAED,+FAA+F;AAC/F,6BAA6B;AAC7B,oCAAoC;AACpC,mCADY,MAAM,GAAG,IAAI,WAGxB;AAxCD,sFAAsF;AACtF,4BAA6B,sBAAsB,CAAC"}

package/dist/guest-run.mjs

@@ -0,0 +1,164 @@
+// @ts-check
+// Run a script on a guest, elevated, and get its output back.
+//
+//   node packages/worker-fleet/src/guest-run.mjs <vm-name> <local-script.cmd> [--timeout=600]
+//
+// This exists because there was no reliable way to do it, and the workarounds each failed differently:
+//
+//   utmctl exec        runs as NT AUTHORITY\SYSTEM -- fully elevated -- but returns NO OUTPUT and exit
+//                      code 0 whether or not the command ran. Fine for firing something, useless for
+//                      knowing what happened.
+//   the worker's HTTP  unelevated. The worker task is RunLevel Limited on purpose (NVDA does not need
+//                      elevation), so DISM, sc.exe and Defender's registry keys are all closed to it.
+//   Register-ScheduledTask from the worker  "Access is denied" -- registering an elevated task itself
+//                      needs elevation.
+//   ssh / WinRM / RDP  not installed; ports 22, 5985, 5986, 3389 and 445 are all closed.
+//
+// The combination that works: `utmctl exec` (SYSTEM) registers a scheduled task at RunLevel HIGHEST,
+// starts it, and the task writes its output to a file we pull back. Elevation from the exec channel,
+// results through the file channel, neither depending on the other.
+//
+// TWO TRAPS, both of which produced wrong answers today and are handled here:
+//
+//   1. `utmctl exec ... -- a b c` passes a, b and c as SEPARATE argv entries. A cmd line containing
+//      parentheses, `&` or quotes gets split across them and cmd receives fragments. A `reg query`
+//      written that way reported "key not found" for a key that certainly existed, and nearly led to
+//      the conclusion that a real configuration drift was a false alarm. The command is passed as ONE
+//      argument here, always.
+//   2. A detached child dies with the exec that spawned it. `start /b` looked like it worked -- exit 0,
+//      no output -- and the child never ran. A scheduled task survives because the Task Scheduler
+//      service owns it.
+import { execFile } from "node:child_process";
+import { createReadStream, readFileSync, existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { basename, resolve } from "node:path";
+import { promisify } from "node:util";
+import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { warnUtmDeprecated } from "./utm-deprecated.mjs";
+/**
+ * takes a VM name and a script POSITIONALLY, which this guard does not touch, plus `--timeout=`;
+ * a mistyped timeout silently falls back to 600s on an operation that may legitimately need longer.
+ *
+ * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
+ */
+refuseUnknownFlags(["--timeout="], { entry: import.meta.url, command: "npm run guest:run" });
+const run = promisify(execFile);
+const UTMCTL = "/Applications/UTM.app/Contents/MacOS/utmctl";
+const GUEST_DIR = "C:\\Users\\witness\\a11y-witness";
+const TASK_NAME = "a11yguestrun";
+/** Written by the wrapper as its last act. Absent means still running, or it died. */
+export const DONE_SENTINEL = "---GUEST-RUN-DONE---";
+const POLL_MS = 5_000;
+/**
+ * The cmd line that registers and starts the elevated task.
+ *
+ * Built as a single string on purpose -- see trap 1 above. Exported so the quoting is testable without
+ * a guest, because it is the part that silently produces wrong answers rather than errors.
+ */
+/** @param {{ scriptPath: string, taskName?: string }} where */
+export function scheduleCommand({ scriptPath, taskName = TASK_NAME }) {
+    return `schtasks /create /tn ${taskName} /tr "${scriptPath}" /sc once /st 00:00 ` +
+        `/ru SYSTEM /rl HIGHEST /f >nul 2>&1 & schtasks /run /tn ${taskName} >nul 2>&1`;
+}
+/**
+ * Wrap a caller's script so it always terminates with the sentinel.
+ *
+ * Without this there is no way to distinguish "still running" from "died on line one" -- which is
+ * exactly how a trim that crashed immediately looked identical to a trim in progress, for three boots.
+ */
+/** @param {string} body @param {string} outputFile */
+export function wrapScript(body, outputFile) {
+    const lines = [
+        "@echo off",
+        `cd /d ${GUEST_DIR}`,
+        `set OUT=${outputFile}`,
+        `> ${outputFile} echo === guest-run ===`,
+        ...body.split(/\r?\n/).filter((/** @type {string} */ l) => !/^@echo off\s*$/i.test(l)).map((/** @type {string} */ l) => l.trimEnd()),
+        `>> ${outputFile} echo ${DONE_SENTINEL}`,
+    ];
+    return lines.join("\r\n") + "\r\n";
+}
+/** Did the run finish? Exported because "no sentinel" and "no file" are different failures. */
+/** @param {string} output */
+/** @param {string | null} output */
+export function isComplete(output) {
+    return typeof output === "string" && output.includes(DONE_SENTINEL);
+}
+/** @param {string} vmName */
+async function uuidFor(vmName) {
+    const { stdout } = await run(UTMCTL, ["list"]);
+    const line = stdout.split("\n").find((l) => l.trim().endsWith(` ${vmName}`) || l.trim().endsWith(`\t${vmName}`));
+    const uuid = line?.trim().split(/\s+/)[0];
+    if (!uuid)
+        throw new Error(`no VM named '${vmName}'`);
+    return uuid;
+}
+/** @param {string} uuid @param {string} guestPath @param {string} localPath @returns {Promise<void>} */
+function push(uuid, guestPath, localPath) {
+    return new Promise((done, fail) => {
+        const child = execFile(UTMCTL, ["file", "push", uuid, guestPath], (error) => error ? fail(new Error(`push failed: ${ /** @type {Error} */(error).message}`)) : done());
+        if (child.stdin)
+            createReadStream(localPath).pipe(child.stdin);
+    });
+}
+/** @param {string} uuid @param {string} guestPath */
+async function pull(uuid, guestPath) {
+    try {
+        const { stdout } = await run(UTMCTL, ["file", "pull", uuid, guestPath], { maxBuffer: 1 << 24 });
+        return stdout;
+    }
+    catch {
+        return null; // not written yet
+    }
+}
+async function main() {
+    warnUtmDeprecated("node packages/worker-fleet/src/guest-run.mjs");
+    const args = process.argv.slice(2);
+    const [vmName, scriptFile] = args.filter((a) => !a.startsWith("--"));
+    const timeoutS = Number(args.find((a) => a.startsWith("--timeout="))?.split("=")[1] ?? 600);
+    if (!vmName || !scriptFile) {
+        process.stderr.write("usage: node packages/worker-fleet/src/guest-run.mjs <vm-name> <script.cmd> [--timeout=600]\n");
+        process.exit(2);
+    }
+    const local = resolve(scriptFile);
+    if (!existsSync(local))
+        throw new Error(`no such script: ${local}`);
+    const name = basename(scriptFile).replace(/\.[^.]+$/, "");
+    const guestScript = `${GUEST_DIR}\\${name}.cmd`;
+    const guestOutput = `${GUEST_DIR}\\.${name}.out`;
+    const wrapped = resolve(process.env.TMPDIR ?? "/tmp", `${name}.wrapped.cmd`);
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(wrapped, wrapScript(readFileSync(local, "utf8"), guestOutput), "utf8");
+    const uuid = await uuidFor(vmName);
+    process.stdout.write(`==> ${vmName} (${uuid})\n`);
+    await push(uuid, guestScript, wrapped);
+    process.stdout.write(`    pushed ${name}.cmd\n`);
+    // One argument. See trap 1.
+    await run(UTMCTL, ["exec", uuid, "--cmd", "cmd.exe", "--", "/c",
+        scheduleCommand({ scriptPath: guestScript })]);
+    process.stdout.write("    running as SYSTEM at RunLevel HIGHEST\n");
+    const deadline = Date.now() + timeoutS * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_MS));
+        const output = await pull(uuid, guestOutput);
+        if (isComplete(output)) {
+            process.stdout.write((output ?? "").replace(DONE_SENTINEL, "").trimEnd() + "\n");
+            process.stdout.write("    done\n");
+            return;
+        }
+    }
+    throw new Error(`no ${DONE_SENTINEL} within ${timeoutS}s — the script may still be running; ` +
+        `pull ${guestOutput} to see how far it got`);
+}
+// `import.meta.url === pathToFileURL(process.argv[1])`, not `endsWith("guest-run.mjs")`. The old form
+// worked but matched on a SUFFIX, so any entry point whose path happened to end that way -- a
+// `my-guest-run.mjs`, a copy under another directory -- would have run this file's main instead of its own.
+// Every other entry point in this repo now uses the exact comparison; one idiom, so there is one thing to
+// get right.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    main().catch((error) => {
+        process.stderr.write(`guest-run failed: ${error.message}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=guest-run.mjs.map

package/dist/guest-run.mjs.map

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

package/dist/host-address.d.mts

@@ -0,0 +1,33 @@
+/** Dotted quad to a comparable integer, or null if it is not one (a hostname, IPv6, nonsense). */
+/** @param {string} ip */
+export function ipv4ToInt(ip: string): number | null;
+/**
+ * This host's address on the same subnet as `guestIp`, or undefined if we have no interface onto it.
+ *
+ * Undefined rather than a guess: a caller that is told "we do not know" can ask to be told, whereas
+ * a caller handed a plausible-but-dead address discovers it as a timeout somewhere else entirely.
+ *
+ * @param {string} guestIp
+ * @returns {string | undefined}
+ */
+export function hostAddressFor(guestIp: string): string | undefined;
+/**
+ * This host's address as seen from a worker at `workerUrl`, when the two share a subnet.
+ *
+ * @param {string} workerUrl
+ * @returns {string | undefined}
+ */
+export function hostAddressForWorker(workerUrl: string): string | undefined;
+/**
+ * The base URL a worker should use to fetch host-served pages.
+ *
+ * Throws rather than returning something unusable. The four call sites all feed this straight into a
+ * capture request, and a wrong page URL does not present as a page-server fault — it presents as
+ * captures that read an error page, which is evidence rot rather than an outage.
+ *
+ * @param {string} workerUrl
+ * @param {number | string} [port]
+ * @returns {string}
+ */
+export function hostPagesBase(workerUrl: string, port?: number | string): string;
+//# sourceMappingURL=host-address.d.mts.map

package/dist/host-address.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-address.d.mts","sourceRoot":"","sources":["../src/host-address.mjs"],"names":[],"mappings":"AAiCA,kGAAkG;AAClG,yBAAyB;AACzB,8BADY,MAAM,iBAKjB;AAED;;;;;;;;GAQG;AACH,wCAHW,MAAM,GACJ,MAAM,GAAG,SAAS,CAiB9B;AAED;;;;;GAKG;AACH,gDAHW,MAAM,GACJ,MAAM,GAAG,SAAS,CAS9B;AAED;;;;;;;;;;GAUG;AACH,yCAJW,MAAM,SACN,MAAM,GAAG,MAAM,GACb,MAAM,CAWlB"}

package/dist/host-address.mjs

@@ -0,0 +1,105 @@
+// @ts-check
+/**
+ * This host's address as a WORKER sees it — one definition, because there were five.
+ *
+ * A worker cannot reach the host's `localhost`, so anything the host serves to a worker (the dataset
+ * page server, above all) must be addressed by the host's LAN IP. `local-vm.ts` worked this out
+ * correctly and said why:
+ *
+ *   > 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.
+ *
+ * Four harnesses then reimplemented it inline as exactly the assumption that comment rejects:
+ *
+ *     new URL(worker).hostname.replace(/\.\d+$/, ".1")
+ *
+ * That is right for UTM, where the Mac really is the `.1` gateway of the shared network, and wrong
+ * for every other network. Measured: against a bare-metal worker on the fleet's own LAN it produced
+ * the ROUTER's address instead — so `evidence:check` refused to run because the pages
+ * were not being served. On a fleet of bare-metal boxes it fails every time.
+ *
+ * The failure mode is why this matters more than tidiness. `guestReachableUrl`'s own note records
+ * what happened last time this was wrong: the guest fetched its own localhost, Edge showed
+ * "localhost refused to connect", the title check rejected the capture, and three attempts were
+ * burned per page before giving up — a page-server problem wearing a capture problem's costume.
+ *
+ * Plain `.mjs` on purpose: `capture-check.mjs` runs under bare node on the guest (see
+ * `run-capture-check.cmd`) and cannot import TypeScript.
+ */
+import { networkInterfaces } from "node:os";
+const IPV4_OCTETS = 4;
+/** Dotted quad to a comparable integer, or null if it is not one (a hostname, IPv6, nonsense). */
+/** @param {string} ip */
+export function ipv4ToInt(ip) {
+    const parts = String(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 `guestIp`, or undefined if we have no interface onto it.
+ *
+ * Undefined rather than a guess: a caller that is told "we do not know" can ask to be told, whereas
+ * a caller handed a plausible-but-dead address discovers it as a timeout somewhere else entirely.
+ *
+ * @param {string} guestIp
+ * @returns {string | undefined}
+ */
+export 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 coercion, so addresses above 2^31 comparing as negative
+            // is harmless here.
+            if ((host & mask) === (guest & mask))
+                return a.address;
+        }
+    }
+    return undefined;
+}
+/**
+ * This host's address as seen from a worker at `workerUrl`, when the two share a subnet.
+ *
+ * @param {string} workerUrl
+ * @returns {string | undefined}
+ */
+export function hostAddressForWorker(workerUrl) {
+    try {
+        const { hostname } = new URL(workerUrl);
+        return ipv4ToInt(hostname) === null ? undefined : hostAddressFor(hostname);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The base URL a worker should use to fetch host-served pages.
+ *
+ * Throws rather than returning something unusable. The four call sites all feed this straight into a
+ * capture request, and a wrong page URL does not present as a page-server fault — it presents as
+ * captures that read an error page, which is evidence rot rather than an outage.
+ *
+ * @param {string} workerUrl
+ * @param {number | string} [port]
+ * @returns {string}
+ */
+export function hostPagesBase(workerUrl, port = process.env.DATASET_PAGES_PORT || 5050) {
+    if (process.env.DATASET_BASE_URL)
+        return process.env.DATASET_BASE_URL.replace(/\/$/, "");
+    const address = hostAddressForWorker(workerUrl);
+    if (!address) {
+        throw new Error(`Cannot work out this host's address as seen from ${workerUrl}: no local interface shares its subnet. `
+            + "Set DATASET_BASE_URL to the URL the worker should fetch dataset pages from.");
+    }
+    return `http://${address}:${port}`;
+}
+//# sourceMappingURL=host-address.mjs.map

package/dist/host-address.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-address.mjs","sourceRoot":"","sources":["../src/host-address.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,kGAAkG;AAClG,yBAAyB;AACzB,MAAM,UAAU,SAAS,CAAC,EAAE;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChD,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;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAO;IACpC,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,yFAAyF;YACzF,oBAAoB;YACpB,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;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAS;IAC5C,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;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,IAAI;IACpF,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,oDAAoD,SAAS,0CAA0C;cACrG,6EAA6E,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,UAAU,OAAO,IAAI,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/dist/host-capacity.d.mts

@@ -0,0 +1,64 @@
+/**
+ * Available memory on macOS, in MB, or null if it cannot be read.
+ *
+ * `os.freemem()` is useless here: it reported 402 MB on a host that comfortably had ~12 GB to give,
+ * because macOS counts compressed and inactive pages as used. The pages that can actually be handed
+ * out without swapping are free + inactive + speculative + purgeable, which is what `vm_stat` reports.
+ *
+ * Returns null rather than throwing on any surprise — a capacity check that cannot read the host must
+ * not stop a run. This codebase already applies that rule to foregroundLockTimeout(): a broken
+ * diagnostic taking the pool offline is worse than the fault it looks for.
+ */
+export function availableHostMemoryMb(): number | null;
+/** Physical RAM in MB. Unlike `os.freemem()` this cannot lie — it is a property of the machine. */
+export function totalHostMemoryMb(): number;
+/**
+ * The most workers this machine can EVER hold, from physical RAM alone.
+ *
+ * This exists because the dynamic estimate below is computed from `vm_stat`, and `vm_stat` is
+ * distorted by exactly the situation it needs to detect. Once guests are swapped out, their pages are
+ * counted as compressed/inactive — which `availableHostMemoryMb` reports as *available* — so a host
+ * three guests deep in swap advertised 13.7 GB free while two of the three could not answer an HTTP
+ * health check within 75 seconds. Total RAM is immune to that feedback loop.
+ *
+ * @returns {number} workers, from physical memory
+ */
+export function workerCeilingFromTotalRam(totalMb?: number): number;
+/**
+ * How many workers may be RUNNING at once, given what the host has spare.
+ *
+ * **A running worker is not automatically an affordable one.** This used to return
+ * `alreadyRunning + canStart` on the reasoning that guests already up had "paid for" their memory and
+ * `availableMb` was what remained after them. That is true of a healthy host and false of the one case
+ * that matters: when the host is in swap, the running guests are being paid for out of disk, and adding
+ * their count back ratifies the very over-commitment that is breaking the run. The result could never
+ * be lower than the number of VMs already up, so the cap was structurally unable to hold back a pool
+ * somebody had already started — which is how three guests came to share a 36 GB Mac, drive 6.6 GB of
+ * swap, and black out two of the three workers mid-run.
+ *
+ * So the answer is the lower of the dynamic estimate and the physical-RAM ceiling, and it is allowed to
+ * come out below `alreadyRunning`. The run then dispatches to fewer workers than are up, which is the
+ * conservative direction: the extra guest wastes memory but no longer takes work.
+ *
+ * Never returns less than one: a run with no workers is a worse outcome than a slow one.
+ *
+ * @param {{ availableMb: number | null, alreadyRunning: number, totalMb?: number }} host
+ * @returns {number}
+ */
+export function workersHostCanRun({ availableMb, alreadyRunning, totalMb }: {
+    availableMb: number | null;
+    alreadyRunning: number;
+    totalMb?: number;
+}): number;
+/**
+ * Why the pool was capped, in words a human can act on. Null when nothing was held back.
+ *
+ * @param {{ limit: number, wanted: number, availableMb: number | null }} cap
+ * @returns {string | null}
+ */
+export function capacityReason({ limit, wanted, availableMb }: {
+    limit: number;
+    wanted: number;
+    availableMb: number | null;
+}): string | null;
+//# sourceMappingURL=host-capacity.d.mts.map

package/dist/host-capacity.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-capacity.d.mts","sourceRoot":"","sources":["../src/host-capacity.mjs"],"names":[],"mappings":"AAkEA;;;;;;;;;;GAUG;AACH,uDAcC;AAED,mGAAmG;AACnG,4CAEC;AAED;;;;;;;;;;GAUG;AACH,6DAFa,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAHW;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,MAAM,CAOlB;AAED;;;;;GAKG;AACH,+DAHW;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC3D,MAAM,GAAG,IAAI,CASzB"}

package/dist/host-capacity.mjs

@@ -0,0 +1,152 @@
+// @ts-check
+/**
+ * How many worker VMs will actually fit on this Mac?
+ *
+ * The pool used to start every VM it found. On a 36 GB host that meant three guests, and measurement
+ * says three do not fit: with all three up a capture took 44.5 s, and with one up it took 27.4 s of
+ * the same page on the same worker — a 1.6x penalty paid by every capture in the run. The guests were
+ * being swapped out from under NVDA, which also produced "NVDA is running but not speaking" failures
+ * and blackouts on /health. More workers were making the run slower AND less reliable.
+ *
+ * So capacity is a property of the host, not a count of the VMs that happen to be registered.
+ *
+ * `.mjs` rather than `.ts` because `npm run doctor` runs under plain node — it is the first thing an
+ * agent runs and must not depend on a transpiler — while the pool lease is TypeScript. Same reason
+ * capture-decisions.mjs is .mjs.
+ */
+import { execFileSync } from "node:child_process";
+import { totalmem } from "node:os";
+/**
+ * What one worker VM costs the host.
+ *
+ * Measured with `top -o mem`, which agrees with phys_footprint. Host cost tracks the guest's CONFIGURED
+ * RAM at ~1.8x, not its usage:
+ *
+ *   4096 MB configured -> 8,048-8,127 MB host
+ *   3072 MB configured -> 5,494 MB host          <- what the guests now run at
+ *   2560 MB configured -> 4,952 MB host          <- measured, and too small: the guest pages
+ *
+ * 3072 MB is the setting because it is the smallest that does not page. The guest commits ~1,859 MB, so
+ * 2560 leaves too little above it: capture phases went from a 12.1 s median (IQR 0.4, 0 recoveries in
+ * 10) to 36.6 s (IQR 38, 4 recoveries in 10). Less RAM stopped being cheaper the moment Windows started
+ * swapping, and four cramped workers measured worse than three comfortable ones.
+ *
+ * The ~1.8x multiplier is QEMU's own overhead on top of guest RAM that Windows dirties and never gives
+ * back (there is no balloon driver). That is why the CONFIGURED size is the lever and the guest's usage
+ * is not: Windows expands to fill whatever ceiling it is given.
+ *
+ * This constant has been wrong twice, in the same direction. 7,600 was an underestimate from a short
+ * sample; 8,100 was right for 4096 MB guests and became wrong the moment they were re-sized. Re-measure
+ * it whenever guest RAM changes -- it is a property of the configuration, not of the software.
+ *
+ * Deliberately the high end of the range. Under-committing costs a little parallelism; over-committing
+ * costs correctness, because a swapped-out guest fails captures rather than merely slowing them.
+ */
+const MEMORY_PER_WORKER_MB = 5_600;
+/**
+ * What the host's own software needs, beyond the run.
+ *
+ * Measured on this Mac while it was doing nothing unusual: Wispr Flow 2.3 GB, tessl 2.0 GB, stable
+ * 1.3 GB, mds_stores 1.1 GB, WindowServer 1.1 GB, Codex 0.9 GB and the rest — about 11 GB before a
+ * single guest starts. This module only ever runs on macOS (see availableHostMemoryMb), so it is
+ * always somebody's desktop, never a dedicated hypervisor.
+ */
+const HOST_APPS_RESERVE_MB = 12_000;
+/**
+ * Memory left for the host itself.
+ *
+ * The Mac is somebody's desktop, not a dedicated hypervisor — Chrome, Spotify and the editor were all
+ * resident during the measurements above. Taking the last of the available memory pushes the HOST into
+ * swap, which slows every guest at once.
+ */
+const HOST_HEADROOM_MB = 3_000;
+/**
+ * Available memory on macOS, in MB, or null if it cannot be read.
+ *
+ * `os.freemem()` is useless here: it reported 402 MB on a host that comfortably had ~12 GB to give,
+ * because macOS counts compressed and inactive pages as used. The pages that can actually be handed
+ * out without swapping are free + inactive + speculative + purgeable, which is what `vm_stat` reports.
+ *
+ * Returns null rather than throwing on any surprise — a capacity check that cannot read the host must
+ * not stop a run. This codebase already applies that rule to foregroundLockTimeout(): a broken
+ * diagnostic taking the pool offline is worse than the fault it looks for.
+ */
+export function availableHostMemoryMb() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const output = execFileSync("vm_stat", { encoding: "utf8", timeout: 5_000 });
+        const pageSize = Number(/page size of (\d+) bytes/.exec(output)?.[1]);
+        if (!Number.isFinite(pageSize))
+            return null;
+        /** @param {string} label */
+        const pagesFor = (label) => Number(new RegExp(`Pages ${label}:\\s+(\\d+)`).exec(output)?.[1] ?? 0);
+        const pages = pagesFor("free") + pagesFor("inactive") + pagesFor("speculative") + pagesFor("purgeable");
+        return Math.round((pages * pageSize) / (1024 * 1024));
+    }
+    catch {
+        return null;
+    }
+}
+/** Physical RAM in MB. Unlike `os.freemem()` this cannot lie — it is a property of the machine. */
+export function totalHostMemoryMb() {
+    return Math.round(totalmem() / (1024 * 1024));
+}
+/**
+ * The most workers this machine can EVER hold, from physical RAM alone.
+ *
+ * This exists because the dynamic estimate below is computed from `vm_stat`, and `vm_stat` is
+ * distorted by exactly the situation it needs to detect. Once guests are swapped out, their pages are
+ * counted as compressed/inactive — which `availableHostMemoryMb` reports as *available* — so a host
+ * three guests deep in swap advertised 13.7 GB free while two of the three could not answer an HTTP
+ * health check within 75 seconds. Total RAM is immune to that feedback loop.
+ *
+ * @returns {number} workers, from physical memory
+ */
+export function workerCeilingFromTotalRam(totalMb = totalHostMemoryMb()) {
+    return Math.floor((totalMb - HOST_APPS_RESERVE_MB - HOST_HEADROOM_MB) / MEMORY_PER_WORKER_MB);
+}
+/**
+ * How many workers may be RUNNING at once, given what the host has spare.
+ *
+ * **A running worker is not automatically an affordable one.** This used to return
+ * `alreadyRunning + canStart` on the reasoning that guests already up had "paid for" their memory and
+ * `availableMb` was what remained after them. That is true of a healthy host and false of the one case
+ * that matters: when the host is in swap, the running guests are being paid for out of disk, and adding
+ * their count back ratifies the very over-commitment that is breaking the run. The result could never
+ * be lower than the number of VMs already up, so the cap was structurally unable to hold back a pool
+ * somebody had already started — which is how three guests came to share a 36 GB Mac, drive 6.6 GB of
+ * swap, and black out two of the three workers mid-run.
+ *
+ * So the answer is the lower of the dynamic estimate and the physical-RAM ceiling, and it is allowed to
+ * come out below `alreadyRunning`. The run then dispatches to fewer workers than are up, which is the
+ * conservative direction: the extra guest wastes memory but no longer takes work.
+ *
+ * Never returns less than one: a run with no workers is a worse outcome than a slow one.
+ *
+ * @param {{ availableMb: number | null, alreadyRunning: number, totalMb?: number }} host
+ * @returns {number}
+ */
+export function workersHostCanRun({ availableMb, alreadyRunning, totalMb = totalHostMemoryMb() }) {
+    if (availableMb === null)
+        return Number.POSITIVE_INFINITY; // unreadable: do not constrain the run
+    const spareMb = availableMb - HOST_HEADROOM_MB;
+    const dynamic = alreadyRunning + Math.max(0, Math.floor(spareMb / MEMORY_PER_WORKER_MB));
+    return Math.max(1, Math.min(dynamic, workerCeilingFromTotalRam(totalMb)));
+}
+/**
+ * Why the pool was capped, in words a human can act on. Null when nothing was held back.
+ *
+ * @param {{ limit: number, wanted: number, availableMb: number | null }} cap
+ * @returns {string | null}
+ */
+export function capacityReason({ limit, wanted, availableMb }) {
+    if (!Number.isFinite(limit) || limit >= wanted)
+        return null;
+    return `host has ${totalHostMemoryMb()} MB of RAM and ~${availableMb} MB available, and each worker ` +
+        `costs ~${MEMORY_PER_WORKER_MB} MB, so ${limit} of ${wanted} local workers will be used. ` +
+        "Measured: an over-committed host made every capture 1.6x slower, caused mute-NVDA failures, and " +
+        "once starved two of three guests until they stopped answering /health at all. " +
+        "Override with A11Y_MAX_WORKERS if you know better.";
+}
+//# sourceMappingURL=host-capacity.mjs.map

package/dist/host-capacity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-capacity.mjs","sourceRoot":"","sources":["../src/host-capacity.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAG,MAAM,CAAC,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,EAAE,CACzB,MAAM,CAAC,IAAI,MAAM,CAAC,SAAS,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACzE,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACxG,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAO,GAAG,iBAAiB,EAAE;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,oBAAoB,GAAG,gBAAgB,CAAC,GAAG,oBAAoB,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,GAAG,iBAAiB,EAAE,EAAE;IAC9F,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAC,uCAAuC;IAClG,MAAM,OAAO,GAAG,WAAW,GAAG,gBAAgB,CAAC;IAC/C,MAAM,OAAO,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,oBAAoB,CAAC,CAAC,CAAC;IACzF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,yBAAyB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC;IAC5D,OAAO,YAAY,iBAAiB,EAAE,mBAAmB,WAAW,iCAAiC;QACnG,UAAU,oBAAoB,WAAW,KAAK,OAAO,MAAM,+BAA+B;QAC1F,kGAAkG;QAClG,gFAAgF;QAChF,oDAAoD,CAAC;AACzD,CAAC"}