@a11ign/screenreader-fleet 0.1.0 → 0.3.0

package/dist/fleet-scripts.d.mts

@@ -8,4 +8,3 @@ export function fleetScriptPaths(): {
     fetchWindowsIso: string;
     provisioning: string;
 };
-//# sourceMappingURL=fleet-scripts.d.mts.map

package/dist/git-safe-env.d.mts

@@ -7,4 +7,3 @@
 export function sandboxGitEnv(extra?: Record<string, string>): Record<string, string | undefined>;
 /** @type {readonly string[]} */
 export const KNOWN_GIT_REDIRECT_VARS: readonly string[];
-//# sourceMappingURL=git-safe-env.d.mts.map

package/dist/guest-run.d.mts

@@ -23,4 +23,3 @@ export function wrapScript(body: string, outputFile: string): string;
 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/host-address.d.mts

@@ -30,4 +30,3 @@ export function hostAddressForWorker(workerUrl: string): string | undefined;
  * @returns {string}
  */
 export function hostPagesBase(workerUrl: string, port?: number | string): string;
-//# sourceMappingURL=host-address.d.mts.map

package/dist/host-address.mjs

@@ -1,105 +1,34 @@
-// @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) {
+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);
+    if (parts.length !== IPV4_OCTETS || parts.some((n)=>!Number.isInteger(n) || n < 0 || n > 255)) return null;
+    return parts.reduce((acc, octet)=>256 * acc + 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) {
+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;
+    if (null === guest) return;
+    for (const addresses of Object.values(networkInterfaces()))for (const a of addresses ?? []){
+        if ("IPv4" !== a.family || a.internal) continue;
+        const host = ipv4ToInt(a.address);
+        const mask = ipv4ToInt(a.netmask);
+        if (null !== host && null !== mask) {
+            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) {
+function hostAddressForWorker(workerUrl) {
     try {
         const { hostname } = new URL(workerUrl);
-        return ipv4ToInt(hostname) === null ? undefined : hostAddressFor(hostname);
-    }
-    catch {
-        return undefined;
+        return null === ipv4ToInt(hostname) ? void 0 : hostAddressFor(hostname);
+    } catch  {
+        return;
     }
 }
-/**
- * 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(/\/$/, "");
+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.");
-    }
+    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
+export { hostAddressFor, hostAddressForWorker, hostPagesBase, ipv4ToInt };

package/dist/host-capacity.d.mts

@@ -61,4 +61,3 @@ export function capacityReason({ limit, wanted, availableMb }: {
     wanted: number;
     availableMb: number | null;
 }): string | null;
-//# sourceMappingURL=host-capacity.d.mts.map

package/dist/host-capacity.mjs

@@ -1,152 +1,38 @@
-// @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;
+const MEMORY_PER_WORKER_MB = 5600;
+const HOST_APPS_RESERVE_MB = 12000;
+const HOST_HEADROOM_MB = 3000;
+function availableHostMemoryMb() {
+    if ("darwin" !== process.platform) return null;
     try {
-        const output = execFileSync("vm_stat", { encoding: "utf8", timeout: 5_000 });
+        const output = execFileSync("vm_stat", {
+            encoding: "utf8",
+            timeout: 5000
+        });
         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);
+        if (!Number.isFinite(pageSize)) return null;
+        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 Math.round(pages * pageSize / 1048576);
+    } 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));
+function totalHostMemoryMb() {
+    return Math.round(totalmem() / 1048576);
 }
-/**
- * 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()) {
+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
+function workersHostCanRun({ availableMb, alreadyRunning, totalMb = totalHostMemoryMb() }) {
+    if (null === availableMb) return 1 / 0;
     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.";
+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
+export { availableHostMemoryMb, capacityReason, totalHostMemoryMb, workerCeilingFromTotalRam, workersHostCanRun };

package/dist/host-metrics.d.mts

@@ -113,4 +113,3 @@ export type HostSnapshot = {
         residentMb: number;
     }[];
 };
-//# sourceMappingURL=host-metrics.d.mts.map

package/dist/index.d.ts

@@ -20,4 +20,3 @@ export type { AfterRun, WorkerLease, PoolLease } from "./local-vm.js";
  * they live: it had four, and one of them was wrong, which broke `leaseWorker` silently.
  */
 export declare function fleetScriptPaths(): Record<string, string>;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.mjs

@@ -0,0 +1,231 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { networkInterfaces } from "node:os";
+import { capacityReason, availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
+import { fleetScriptPaths as fleet_scripts_fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
+import { inventoryWorkerUrls } from "./fleet-env.mjs";
+import { warnUtmDeprecated } from "./src_utm-deprecated_mjs.mjs";
+const execFileAsync = promisify(execFile);
+const DEFAULT_WORKER = "http://localhost:8765";
+const CTL = fleet_scripts_fleetScriptPaths().workerCtl;
+const STATUS_TIMEOUT_MS = 30000;
+const LIFECYCLE_TIMEOUT_MS = 300000;
+const AFTER_RUN_VALUES = [
+    "restore",
+    "stop",
+    "pause",
+    "leave"
+];
+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)=>256 * acc + octet, 0);
+}
+function hostAddressFor(guestIp) {
+    const guest = ipv4ToInt(guestIp);
+    if (null === guest) return;
+    for (const addresses of Object.values(networkInterfaces()))for (const a of addresses ?? []){
+        if ("IPv4" !== a.family || a.internal) continue;
+        const host = ipv4ToInt(a.address);
+        const mask = ipv4ToInt(a.netmask);
+        if (null !== host && null !== mask) {
+            if ((host & mask) === (guest & mask)) return a.address;
+        }
+    }
+}
+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;
+}
+async function findLocalVm() {
+    if ("darwin" !== process.platform) return null;
+    try {
+        return JSON.parse(await ctl([
+            "json"
+        ], STATUS_TIMEOUT_MS));
+    } catch (e) {
+        if (process.env.A11Y_DEBUG_VM) process.stderr.write(`local VM lookup failed (continuing without one): ${e.message}\n`);
+        return null;
+    }
+}
+function restoreAction(stateBefore) {
+    if ("started" === stateBefore) return "leave";
+    if ("paused" === stateBefore) return "pause";
+    return "stop";
+}
+async function releaseVm(action, stateBefore) {
+    const resolved = "restore" === action ? restoreAction(stateBefore) : action;
+    if ("leave" === resolved) return;
+    const now = await findLocalVm();
+    if (now?.busy) return void process.stderr.write(`worker is busy with another capture; leaving the VM ${now.state}\n`);
+    process.stderr.write(`${"pause" === resolved ? "Pausing" : "Shutting down"} the local worker VM ...\n`);
+    await ctl([
+        resolved
+    ], LIFECYCLE_TIMEOUT_MS);
+}
+async function acquireLocalWorker(vm, after) {
+    const stateBefore = vm.state;
+    if ("started" === stateBefore && 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)=>{
+                process.stderr.write(`WARNING: could not release the local worker VM: ${e.message}\n`);
+            })
+    };
+}
+async function leaseWorker({ worker, after }, deps = {}) {
+    const release = async ()=>{};
+    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 ("0" === process.env.A11Y_LOCAL_VM) return {
+        worker: DEFAULT_WORKER,
+        source: "default",
+        release
+    };
+    const vm = deps.findLocalVm ? await deps.findLocalVm() : await findLocalVm();
+    if (!vm) return {
+        worker: DEFAULT_WORKER,
+        source: "default",
+        release
+    };
+    warnUtmDeprecated("this run (no worker named, no fleet configured)");
+    return acquireLocalWorker(vm, after);
+}
+function hostAddressForWorker(workerUrl) {
+    try {
+        const { hostname } = new URL(workerUrl);
+        return null === ipv4ToInt(hostname) ? void 0 : hostAddressFor(hostname);
+    } catch  {
+        return;
+    }
+}
+function guestReachableUrl(baseUrl, lease) {
+    const hostAddress = lease.hostAddress ?? hostAddressForWorker(lease.worker);
+    if (!hostAddress) return baseUrl;
+    const parsed = new URL(baseUrl);
+    if ("localhost" !== parsed.hostname && "127.0.0.1" !== parsed.hostname) return baseUrl;
+    parsed.hostname = hostAddress;
+    return parsed.toString().replace(/\/$/, "");
+}
+async function findLocalPool() {
+    if ("darwin" !== process.platform) return [];
+    try {
+        return JSON.parse(await ctl([
+            "pool"
+        ], STATUS_TIMEOUT_MS));
+    } catch  {
+        return [];
+    }
+}
+function configuredWorkerLimit() {
+    const configured = Number(process.env.A11Y_MAX_WORKERS);
+    return Number.isFinite(configured) && configured > 0 ? configured : null;
+}
+function chooseRunnableWorkers(pool) {
+    const availableMb = availableHostMemoryMb();
+    const running = pool.filter((vm)=>"started" === vm.state);
+    const limit = configuredWorkerLimit() ?? workersHostCanRun({
+        availableMb,
+        alreadyRunning: running.length
+    });
+    if (limit >= pool.length) return {
+        chosen: pool,
+        note: null
+    };
+    const chosen = [
+        ...running,
+        ...pool.filter((vm)=>"started" !== vm.state)
+    ].slice(0, limit);
+    return {
+        chosen,
+        note: capacityReason({
+            limit,
+            wanted: pool.length,
+            availableMb
+        })
+    };
+}
+async function leaseWorkerPool(after) {
+    warnUtmDeprecated("the local UTM worker pool");
+    const pool = await findLocalPool();
+    if (pool.length < 2) return null;
+    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 ("started" !== vm.state || !vm.healthy) {
+        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) {
+            process.stderr.write(`Local worker '${vm.name}' would not come up (${error.message.split("\n")[0]}); continuing without it\n`);
+        }
+    }
+    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) 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 = "restore" === after ? restoreAction(before.get(vm.name) ?? "stopped") : after;
+                if ("leave" !== action) try {
+                    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(`${"pause" === action ? "Pausing" : "Shutting down"} '${vm.name}' ...\n`);
+                    await ctl([
+                        action
+                    ], LIFECYCLE_TIMEOUT_MS, vm.name);
+                } catch (e) {
+                    process.stderr.write(`WARNING: could not ${action} '${vm.name}': ${e.message}\n`);
+                }
+            }
+        }
+    };
+}
+function fleetScriptPaths() {
+    return fleet_scripts_fleetScriptPaths();
+}
+export { DEFAULT_WORKER, fleetScriptPaths, guestReachableUrl, hostAddressForWorker, isAfterRun, leaseWorker, leaseWorkerPool };

package/dist/local-vm.d.ts

@@ -122,4 +122,3 @@ export interface PoolLease {
  */
 export declare function leaseWorkerPool(after: AfterRun): Promise<PoolLease | null>;
 export {};
-//# sourceMappingURL=local-vm.d.ts.map

package/dist/measure-guard.d.mts

@@ -31,4 +31,3 @@ export function sampleVitals(worker: string, { timeoutMs, request, warn }?: {
  * 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/normalise-fleet.d.mts

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

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

@@ -39,4 +39,3 @@ export function pnpmCliInvocation(args: string[]): {
     command: string;
     args: string[];
 };
-//# sourceMappingURL=npm-cli-executable.d.mts.map

package/dist/probe-outcome.d.mts

@@ -86,4 +86,3 @@ export type Probe = {
 };
 export type ProbeRequest = typeof requestJson;
 import { requestJson } from "./worker-http.mjs";
-//# sourceMappingURL=probe-outcome.d.mts.map