@a11ign/screenreader-fleet 0.5.2 → 0.6.0

package/dist/fleet-consistency.mjs

@@ -52,6 +52,10 @@ const REPORTED_ONLY = [
     {
         path: "displayAdapter",
         why: "the adapter is what decides whether a pinned display mode can be held at all -- on 2026-09-22 workers 7-11 were on Microsoft's Basic Display Adapter and captured at 640x480 under a `provisionRevision` identical to their peers' (#1955); the pinned Intel driver install resolved that, and all ten read an Intel adapter at CM_PROB_NONE on 2026-09-23. NOT a gate, and no longer because nobody reports it: 10 of 10 guests report it since 2026-09-23T18:02Z, reading `Intel(R) UHD Graphics 630` on nine and `Intel(R) HD Graphics 630` on one as of 2026-09-23. That single letter is a real hardware difference rather than a driver fallback, so no provisioning run can converge it and a gate would refuse that guest for ever (#2063, reading on #2170)"
+    },
+    {
+        path: "windowsBuild",
+        why: "two boxes one cumulative update apart share a `windowsVersion` and are not the same Windows; the revision (`CurrentBuild.UBR`) is what tells them apart. NOT a gate yet: it graduates to MUST_MATCH once the fleet reads one value (#4433, #4405)"
     }
 ];
 const POLICY_MUST_MATCH = [

package/dist/{fleet-env.d.mts → fleet-env.d.ts}

@@ -1,3 +1,4 @@
+export declare const DEFAULT_WORKER_PORT = 8765;
 /**
  * The fleet named by the environment — ONE parser, because there were three that did not agree.
  *
@@ -16,7 +17,7 @@
  *
  * @returns {Array<{ name: string, url: string }>}
  */
-export function configuredWorkers(): Array<{
+export declare function configuredWorkers(): Array<{
     name: string;
     url: string;
 }>;
@@ -34,13 +35,46 @@ export function configuredWorkers(): Array<{
  * @param {{ argv?: readonly string[], baseDir?: string }} [options]
  * @returns {{ inventoryPath: string, groupVarsPath: string }}
  */
-export function inventoryPathsFor({ argv, baseDir }?: {
+export declare function inventoryPathsFor({ argv, baseDir }?: {
     argv?: readonly string[];
     baseDir?: string;
 }): {
     inventoryPath: string;
     groupVarsPath: string;
 };
+/**
+ * The inventory group whose hosts are capture workers.
+ *
+ * This reader was GROUPLESS until 2026-08-21, and that was a live hazard rather than an untidiness: every
+ * `ansible_host:` in the file became `http://<addr>:8765`, so adding any non-worker host to `inventory.yml`
+ * -- the lab container, the control container, a switch -- would have silently added a phantom worker to
+ * `A11Y_WORKERS`, and a run would have dispatched capture cases to it. That is the exact failure this
+ * module's own header says it exists to prevent ("dispatched to but never updated", "both of those are
+ * silent"), arriving through the door nobody had shut.
+ */
+export declare const WORKER_GROUP = "a11y_workers";
+/**
+ * One frame of the indentation stack: a key and the column it started at.
+ */
+export type Frame = {
+    indent: number;
+    key: string;
+};
+/**
+ * A host as the inventory declares it — the ADDRESS and the NAME together.
+ *
+ * They travel as one value because separating them is what sent `fleet:sleep` at the wrong machine: every
+ * tool that ACTS on a worker takes the name, every tool that REPORTS on one printed the address, and
+ * nothing mapped between them. `collectHost` explains the incident.
+ *
+ * `capture` is false for a host that declares `a11y_capture: false`: enrolled, served, deployed to, and not
+ * handed corpus cases.
+ */
+export type Host = {
+    name: string | undefined;
+    host: string;
+    capture: boolean;
+};
 /**
  * Which group each line of the inventory sits in, index-aligned with `text.split(/\r?\n/)`.
  *
@@ -53,7 +87,7 @@ export function inventoryPathsFor({ argv, baseDir }?: {
  * @param {string} text
  * @returns {Array<string | undefined>}
  */
-export function groupPerLine(text: string): Array<string | undefined>;
+export declare function groupPerLine(text: string): Array<string | undefined>;
 /**
  * Worker URLs from the text of an inventory file.
  *
@@ -70,7 +104,7 @@ export function groupPerLine(text: string): Array<string | undefined>;
  * @param {{ port?: number, group?: string, scope?: "fleet" | "capture" }} [options]
  * @returns {string[]}
  */
-export function workersFromInventory(text: string, { port, group, scope }?: {
+export declare function workersFromInventory(text: string, { port, group, scope }?: {
     port?: number;
     group?: string;
     scope?: "fleet" | "capture";
@@ -82,7 +116,7 @@ export function workersFromInventory(text: string, { port, group, scope }?: {
  * @param {{ port?: number, group?: string }} [options]
  * @returns {{name: string, url: string}[]}
  */
-export function hostsOutOfCaptureSet(text: string, { port, group }?: {
+export declare function hostsOutOfCaptureSet(text: string, { port, group }?: {
     port?: number;
     group?: string;
 }): {
@@ -99,13 +133,13 @@ export function hostsOutOfCaptureSet(text: string, { port, group }?: {
  * @param {{ port?: number, group?: string }} [options]
  * @returns {Record<string, string>}
  */
-export function workerNamesFromInventory(text: string, { port, group }?: {
+export declare function workerNamesFromInventory(text: string, { port, group }?: {
     port?: number;
     group?: string;
 }): Record<string, string>;
 /** The port the group vars declare, so it is stated once and not guessed here. */
 /** @param {string} text @returns {number} */
-export function portFromGroupVars(text: string): number;
+export declare function portFromGroupVars(text: string): number;
 /**
  * The workers declared in `inventory.yml` — i.e. the BARE-METAL fleet.
  *
@@ -122,7 +156,7 @@ export function portFromGroupVars(text: string): number;
  *
  * @param {{ inventoryPath?: string, groupVarsPath?: string }} [paths]
  */
-export function inventoryWorkerUrls({ inventoryPath, groupVarsPath }?: {
+export declare function inventoryWorkerUrls({ inventoryPath, groupVarsPath }?: {
     inventoryPath?: string;
     groupVarsPath?: string;
 }): string[];
@@ -142,7 +176,7 @@ export function inventoryWorkerUrls({ inventoryPath, groupVarsPath }?: {
  * @param {{ inventoryPath?: string, groupVarsPath?: string }} [paths]
  * @returns {{name: string, url: string}[]} empty when no inventory is declared, like `inventoryWorkerUrls`
  */
-export function namedInventoryWorkers({ inventoryPath, groupVarsPath }?: {
+export declare function namedInventoryWorkers({ inventoryPath, groupVarsPath }?: {
     inventoryPath?: string;
     groupVarsPath?: string;
 }): {
@@ -183,7 +217,7 @@ export function namedInventoryWorkers({ inventoryPath, groupVarsPath }?: {
  * @param {{ named?: () => {url: string}[], inventory?: () => string[], local?: () => string[] }} readers
  * @returns {{ urls: string[], source: string }}
  */
-export function resolveWorkerPool({ named, inventory, local, }?: {
+export declare function resolveWorkerPool({ named, inventory, local, }?: {
     named?: () => {
         url: string;
     }[];
@@ -205,44 +239,10 @@ export function resolveWorkerPool({ named, inventory, local, }?: {
  * @param {{ port?: number, mode?: "env" | "list" }} [options]
  * @returns {{stdout: string, stderr: string}}
  */
-export function fleetEnvOutput(text: string, { port, mode }?: {
+export declare function fleetEnvOutput(text: string, { port, mode }?: {
     port?: number;
     mode?: "env" | "list";
 }): {
     stdout: string;
     stderr: string;
 };
-export const DEFAULT_WORKER_PORT: 8765;
-/**
- * The inventory group whose hosts are capture workers.
- *
- * This reader was GROUPLESS until 2026-08-21, and that was a live hazard rather than an untidiness: every
- * `ansible_host:` in the file became `http://<addr>:8765`, so adding any non-worker host to `inventory.yml`
- * -- the lab container, the control container, a switch -- would have silently added a phantom worker to
- * `A11Y_WORKERS`, and a run would have dispatched capture cases to it. That is the exact failure this
- * module's own header says it exists to prevent ("dispatched to but never updated", "both of those are
- * silent"), arriving through the door nobody had shut.
- */
-export const WORKER_GROUP: "a11y_workers";
-/**
- * One frame of the indentation stack: a key and the column it started at.
- */
-export type Frame = {
-    indent: number;
-    key: string;
-};
-/**
- * A host as the inventory declares it — the ADDRESS and the NAME together.
- *
- * They travel as one value because separating them is what sent `fleet:sleep` at the wrong machine: every
- * tool that ACTS on a worker takes the name, every tool that REPORTS on one printed the address, and
- * nothing mapped between them. `collectHost` explains the incident.
- *
- * `capture` is false for a host that declares `a11y_capture: false`: enrolled, served, deployed to, and not
- * handed corpus cases.
- */
-export type Host = {
-    name: string | undefined;
-    host: string;
-    capture: boolean;
-};

package/dist/{fleet-scripts.d.mts → fleet-scripts.d.ts}

@@ -1,5 +1,5 @@
 /** Absolute paths to the provisioning and lifecycle scripts. Absolute, because a consumer spawns them. */
-export function fleetScriptPaths(): {
+export declare function fleetScriptPaths(): {
     dir: string;
     workerCtl: string;
     buildVm: string;

package/dist/{git-safe-env.d.mts → git-safe-env.d.ts}

@@ -1,9 +1,9 @@
+/** @type {readonly string[]} */
+export declare const KNOWN_GIT_REDIRECT_VARS: readonly string[];
 /**
  * `process.env` with every `GIT_*` key removed, `extra` applied on top. A prefix strip, never a list
  * lookup, so a new `GIT_*` variable is caught without this file needing to know its name.
  * @param {Record<string, string>} [extra]
  * @returns {Record<string, string | undefined>}
  */
-export function sandboxGitEnv(extra?: Record<string, string>): Record<string, string | undefined>;
-/** @type {readonly string[]} */
-export const KNOWN_GIT_REDIRECT_VARS: readonly string[];
+export declare function sandboxGitEnv(extra?: Record<string, string>): Record<string, string | undefined>;

package/dist/{guest-run.d.mts → guest-run.d.ts}

@@ -1,3 +1,5 @@
+/** Written by the wrapper as its last act. Absent means still running, or it died. */
+export declare const DONE_SENTINEL = "---GUEST-RUN-DONE---";
 /**
  * The cmd line that registers and starts the elevated task.
  *
@@ -5,7 +7,7 @@
  * 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 }: {
+export declare function scheduleCommand({ scriptPath, taskName }: {
     scriptPath: string;
     taskName?: string;
 }): string;
@@ -16,10 +18,8 @@ export function scheduleCommand({ scriptPath, taskName }: {
  * 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;
+export declare 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---";
+export declare function isComplete(output: string | null): boolean;

package/dist/{host-address.d.mts → host-address.d.ts}

@@ -1,6 +1,6 @@
 /** 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;
+export declare 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.
  *
@@ -10,14 +10,14 @@ export function ipv4ToInt(ip: string): number | null;
  * @param {string} guestIp
  * @returns {string | undefined}
  */
-export function hostAddressFor(guestIp: string): string | undefined;
+export declare 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;
+export declare function hostAddressForWorker(workerUrl: string): string | undefined;
 /**
  * The base URL a worker should use to fetch host-served pages.
  *
@@ -29,4 +29,4 @@ export function hostAddressForWorker(workerUrl: string): string | undefined;
  * @param {number | string} [port]
  * @returns {string}
  */
-export function hostPagesBase(workerUrl: string, port?: number | string): string;
+export declare function hostPagesBase(workerUrl: string, port?: number | string): string;

package/dist/{host-capacity.d.mts → host-capacity.d.ts}

@@ -9,9 +9,9 @@
  * 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;
+export declare 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;
+export declare function totalHostMemoryMb(): number;
 /**
  * The most workers this machine can EVER hold, from physical RAM alone.
  *
@@ -23,7 +23,7 @@ export function totalHostMemoryMb(): number;
  *
  * @returns {number} workers, from physical memory
  */
-export function workerCeilingFromTotalRam(totalMb?: number): number;
+export declare function workerCeilingFromTotalRam(totalMb?: number): number;
 /**
  * How many workers may be RUNNING at once, given what the host has spare.
  *
@@ -45,7 +45,7 @@ export function workerCeilingFromTotalRam(totalMb?: number): number;
  * @param {{ availableMb: number | null, alreadyRunning: number, totalMb?: number }} host
  * @returns {number}
  */
-export function workersHostCanRun({ availableMb, alreadyRunning, totalMb }: {
+export declare function workersHostCanRun({ availableMb, alreadyRunning, totalMb }: {
     availableMb: number | null;
     alreadyRunning: number;
     totalMb?: number;
@@ -56,7 +56,7 @@ export function workersHostCanRun({ availableMb, alreadyRunning, totalMb }: {
  * @param {{ limit: number, wanted: number, availableMb: number | null }} cap
  * @returns {string | null}
  */
-export function capacityReason({ limit, wanted, availableMb }: {
+export declare function capacityReason({ limit, wanted, availableMb }: {
     limit: number;
     wanted: number;
     availableMb: number | null;

package/dist/{host-metrics.d.mts → host-metrics.d.ts}

@@ -6,7 +6,7 @@
  *
  * @param {string} output
  */
-export function parseVmStat(output: string): {
+export declare function parseVmStat(output: string): {
     freeMb: number;
     activeMb: number;
     inactiveMb: number;
@@ -24,7 +24,7 @@ export function parseVmStat(output: string): {
  * @param {string} output
  * @returns {Array<{device: string, kbPerTransfer: number, transfersPerSecond: number, mbPerSecond: number}>}
  */
-export function parseIostat(output: string): Array<{
+export declare function parseIostat(output: string): Array<{
     device: string;
     kbPerTransfer: number;
     transfersPerSecond: number;
@@ -34,7 +34,7 @@ export function parseIostat(output: string): Array<{
  * Load averages, or null.
  * @param {string} output
  */
-export function parseLoadAverage(output: string): {
+export declare function parseLoadAverage(output: string): {
     one: number;
     five: number;
     fifteen: number;
@@ -46,7 +46,7 @@ export function parseLoadAverage(output: string): {
  * @param {string} psOutput output of `ps -o pid=,rss=,comm=`
  * @param {string} match substring of the command to keep
  */
-export function parseProcessMemory(psOutput: string, match: string): {
+export declare function parseProcessMemory(psOutput: string, match: string): {
     pid: number;
     residentMb: number;
     command: string;
@@ -60,7 +60,7 @@ export function parseProcessMemory(psOutput: string, match: string): {
  *
  * @param {{ processMatch?: string }} options
  */
-export function sampleHost({ processMatch }?: {
+export declare function sampleHost({ processMatch }?: {
     processMatch?: string;
 }): {
     at: string;
@@ -91,18 +91,14 @@ export function sampleHost({ processMatch }?: {
     }[];
 };
 /**
- * @param {HostSnapshot} before
- * @param {HostSnapshot} after
+ * What changed between two snapshots.
+ *
+ * Paging is reported as a DELTA because the absolute counters are since-boot and therefore enormous
+ * and useless: 6.6 GB of swap left over from an incident hours ago looks identical to a host swapping
+ * right now. Only the delta distinguishes them, and that distinction was worth an afternoon.
  */
-export function diffHost(before: HostSnapshot, after: HostSnapshot): {
-    pageoutsDelta: number;
-    pageinsDelta: number;
-    swappingDuringRun: boolean;
-    compressorMb: number | null;
-    freeMb: number | null;
-    residentMbTotal: number;
-};
 /**
+ *
  * Named because the first attempt at annotating this called it `Record<string, number>` -- flat numbers,
  * which is what the CALL SITES read out of it and not what it is. A shape guessed from its uses is the
  * same defect as a type inferred from its defaults, one file over.
@@ -113,3 +109,15 @@ export type HostSnapshot = {
         residentMb: number;
     }[];
 };
+/**
+ * @param {HostSnapshot} before
+ * @param {HostSnapshot} after
+ */
+export declare function diffHost(before: HostSnapshot, after: HostSnapshot): {
+    pageoutsDelta: number;
+    pageinsDelta: number;
+    swappingDuringRun: boolean;
+    compressorMb: number | null;
+    freeMb: number | null;
+    residentMbTotal: number;
+};

package/dist/index.mjs

@@ -2,7 +2,7 @@ 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 { fleetScriptPaths as fleet_scripts_fleetScriptPaths } from "./src_fleet-scripts_ts.mjs";
 import { inventoryWorkerUrls } from "./fleet-env.mjs";
 function warnUtmDeprecated(what) {
     process.stderr.write(`DEPRECATED: ${what} manages a local UTM worker VM. UTM was a testing path and is not the fleet.\nCapture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy. See CLAUDE.md's\n"Working on a Mac" section.\n`);

package/dist/{measure-guard.d.mts → measure-guard.d.ts}

@@ -1,33 +1,33 @@
 /**
  * @param {string[]} workers
- * @param {{ what: string, timeoutMs?: number, request?: import("./probe-outcome.mjs").ProbeRequest }} about
+ * @param {{ what: string, timeoutMs?: number, request?: import("./probe-outcome.ts").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 }: {
+export declare function refuseIfBusy(workers: string[], { what, timeoutMs, request }: {
     what: string;
     timeoutMs?: number;
-    request?: import("./probe-outcome.mjs").ProbeRequest;
+    request?: import("./probe-outcome.js").ProbeRequest;
 }): Promise<void>;
+/**
+ * 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 declare const VITALS_TIMEOUT_MS = 20000;
 /**
  * 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]
+ * @param {{ timeoutMs?: number, request?: import("./probe-outcome.ts").ProbeRequest, warn?: (line: string) => void }} [options]
  * @returns {Promise<any>}
  */
-export function sampleVitals(worker: string, { timeoutMs, request, warn }?: {
+export declare function sampleVitals(worker: string, { timeoutMs, request, warn }?: {
     timeoutMs?: number;
-    request?: import("./probe-outcome.mjs").ProbeRequest;
+    request?: import("./probe-outcome.js").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;

package/dist/{npm-cli-executable.d.mts → npm-cli-executable.d.ts}

@@ -2,18 +2,18 @@
  * @param {"npx" | "npm"} name
  * @returns {string[]}
  */
-export function npmCliScriptCandidates(name: "npx" | "npm"): string[];
+export declare function npmCliScriptCandidates(name: "npx" | "npm"): string[];
 /**
  * @param {"npx" | "npm"} name
  * @returns {string}
  */
-export function resolveNpmCliScript(name: "npx" | "npm"): string;
+export declare 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[]): {
+export declare function npmCliInvocation(name: "npx" | "npm", args: string[]): {
     command: string;
     args: string[];
 };
@@ -35,7 +35,7 @@ export function npmCliInvocation(name: "npx" | "npm", args: string[]): {
  * @param {string[]} args
  * @returns {{ command: string, args: string[] }}
  */
-export function pnpmCliInvocation(args: string[]): {
+export declare function pnpmCliInvocation(args: string[]): {
     command: string;
     args: string[];
 };

package/dist/{probe-outcome.d.mts → probe-outcome.d.ts}

@@ -1,46 +1,3 @@
-/**
- * @param {string} worker the worker's base URL
- * @param {{ timeoutMs?: number, request?: ProbeRequest }} [options]
- * @returns {Promise<Probe>}
- */
-export function probeHealth(worker: string, { timeoutMs, request }?: {
-    timeoutMs?: number;
-    request?: ProbeRequest;
-}): Promise<Probe>;
-/**
- * One sentence per outcome, in the words of what was OBSERVED. Only `refused`, `not-ready` and `busy` say the box is
- * up, because only those are things the box itself said; a silent probe says "did not answer" and never "down".
- *
- * @param {Probe} probe
- * @param {{ worker: string, timeoutMs?: number }} about
- * @returns {string}
- */
-export function describeProbe(probe: Probe, { worker, timeoutMs }: {
-    worker: string;
-    timeoutMs?: number;
-}): string;
-/** @typedef {typeof requestJson} ProbeRequest */
-/**
- * THE PER-PROBE TIMEOUT, WITH ITS READING. A probe that outlives it is UNKNOWN, never "down", so this number
- * decides how much slowness a healthy box is allowed.
- *
- * All of it READ by others on the real fleet (`orchestrator`, #2671) and none measured by this row, whose
- * engineer is barred from probing it:
- *   - the slowest HEALTHY box: 2.80 to 3.09 s on a11y-worker-13, -14 and -16, twelve others 0.53 to 0.76 s;
- *   - that is the FIRST answer after the box has been quiet more than 5 s, because the worker rebuilds its
- *     environment block with two synchronous `powershell.exe` calls when it is older than that, so a probe made
- *     by hand is nearly always the slow case;
- *   - a LOADED box (one that has just stopped a capture) can take up to about 10 s: each of the two calls is
- *     bounded at 5 s and they stop the worker's event loop for the whole time.
- * 12 s is that loaded ceiling plus 2 s, the number `fleet-wake.mjs` `HEALTH_TIMEOUT_MS` states for the same
- * reading. Before #2683 these entries used 5 s (`witness`, 1.91 s over the 3.09 s box and none over a loaded
- * one), 8 s (`auth:leak-check`) and 10 s (`worker:compare`'s busy guard), read at `d119fb0f2`. Cost of the
- * generosity: a box that really is off costs one 12 s wait before the message. A refusal costs nothing, it comes
- * back at once.
- */
-export const WORKER_PROBE_TIMEOUT_MS: 12000;
-/** How to wake a box from a checkout of this repo. The published entries do not do it themselves. */
-export const WAKE_HINT: string;
 /**
  * WHAT ONE `/health` PROBE CAN SAY, for the entries that reach a worker from the PUBLISHED side and by hand
  * (`witness`, `worker:compare`, `auth:leak-check`, #2683 of #2655).
@@ -84,5 +41,47 @@ export type Probe = {
     message: string;
     timedOut: boolean;
 };
+import { requestJson } from "./worker-http.js";
 export type ProbeRequest = typeof requestJson;
-import { requestJson } from "./worker-http.mjs";
+/**
+ * THE PER-PROBE TIMEOUT, WITH ITS READING. A probe that outlives it is UNKNOWN, never "down", so this number
+ * decides how much slowness a healthy box is allowed.
+ *
+ * All of it READ by others on the real fleet (`orchestrator`, #2671) and none measured by this row, whose
+ * engineer is barred from probing it:
+ *   - the slowest HEALTHY box: 2.80 to 3.09 s on a11y-worker-13, -14 and -16, twelve others 0.53 to 0.76 s;
+ *   - that is the FIRST answer after the box has been quiet more than 5 s, because the worker rebuilds its
+ *     environment block with two synchronous `powershell.exe` calls when it is older than that, so a probe made
+ *     by hand is nearly always the slow case;
+ *   - a LOADED box (one that has just stopped a capture) can take up to about 10 s: each of the two calls is
+ *     bounded at 5 s and they stop the worker's event loop for the whole time.
+ * 12 s is that loaded ceiling plus 2 s, the number `fleet-wake.mjs` `HEALTH_TIMEOUT_MS` states for the same
+ * reading. Before #2683 these entries used 5 s (`witness`, 1.91 s over the 3.09 s box and none over a loaded
+ * one), 8 s (`auth:leak-check`) and 10 s (`worker:compare`'s busy guard), read at `d119fb0f2`. Cost of the
+ * generosity: a box that really is off costs one 12 s wait before the message. A refusal costs nothing, it comes
+ * back at once.
+ */
+export declare const WORKER_PROBE_TIMEOUT_MS = 12000;
+/**
+ * @param {string} worker the worker's base URL
+ * @param {{ timeoutMs?: number, request?: ProbeRequest }} [options]
+ * @returns {Promise<Probe>}
+ */
+export declare function probeHealth(worker: string, { timeoutMs, request }?: {
+    timeoutMs?: number;
+    request?: ProbeRequest;
+}): Promise<Probe>;
+/** How to wake a box from a checkout of this repo. The published entries do not do it themselves. */
+export declare const WAKE_HINT: string;
+/**
+ * One sentence per outcome, in the words of what was OBSERVED. Only `refused`, `not-ready` and `busy` say the box is
+ * up, because only those are things the box itself said; a silent probe says "did not answer" and never "down".
+ *
+ * @param {Probe} probe
+ * @param {{ worker: string, timeoutMs?: number }} about
+ * @returns {string}
+ */
+export declare function describeProbe(probe: Probe, { worker, timeoutMs }: {
+    worker: string;
+    timeoutMs?: number;
+}): string;

package/dist/{protocol-guard.d.mts → protocol-guard.d.ts}

@@ -1,3 +1,4 @@
+export declare const RECAPTURE_COST: string;
 /**
  * Decide whether a deploy may proceed.
  *
@@ -5,7 +6,7 @@
  *           allowed: boolean, source?: string }} input
  * @returns {{ refuse: boolean, message: string }}
  */
-export function protocolVerdict({ local, served, allowed, source }: {
+export declare function protocolVerdict({ local, served, allowed, source }: {
     local: number | string | null;
     served: {
         worker: string;
@@ -26,8 +27,7 @@ export function protocolVerdict({ local, served, allowed, source }: {
  * @param {string[]} urls
  * @returns {Promise<{worker: string, protocol: number|string|null}[]>}
  */
-export function servedProtocols(urls: string[]): Promise<{
+export declare function servedProtocols(urls: string[]): Promise<{
     worker: string;
     protocol: number | string | null;
 }[]>;
-export const RECAPTURE_COST: string;

package/dist/source-walk.d.ts

@@ -0,0 +1,11 @@
+/** The repository root, resolved from this module rather than from the caller's cwd. */
+export declare const REPOSITORY: string;
+/**
+ * Every non-test source file under the repository root, as `[relativePath, source]`.
+ *
+ * @param {{ root?: string }} [options]
+ * @returns {Array<[string, string]>}
+ */
+export declare function sourceFiles({ root }?: {
+    root?: string;
+}): Array<[string, string]>;

package/dist/{transient-fault.d.mts → transient-fault.d.ts}

@@ -2,4 +2,4 @@
  * @param {unknown} error  anything a failed request threw — a node:http Error, an undici one, a string
  * @returns {boolean}
  */
-export function isTransient(error: unknown): boolean;
+export declare function isTransient(error: unknown): boolean;

package/dist/tsx-import.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The arguments that let a plain `node` run a `.ts` file (ADR 0043, Decision 8): the host's Node has no type stripping, so a test that
+ * starts a source file as a child process, as an operator would, starts it under `tsx`. Resolved to an absolute URL because those children
+ * run from a temporary directory, where a bare `tsx` would not resolve.
+ */
+export declare const TSX_ARGS: string[];

package/dist/{utm-deprecated.d.mts → utm-deprecated.d.ts}

@@ -2,4 +2,4 @@
  * @param {string} what The command or module the caller is about to run — named so the message is
  *   specific to what actually fired, not a generic banner every UTM-adjacent file prints identically.
  */
-export function warnUtmDeprecated(what: string): void;
+export declare function warnUtmDeprecated(what: string): void;