@deque/axe-auth 1.4.0 → 1.5.0-next.7a5a136d

package/dist/run/runSession.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runSession;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../oauth/errors");
+const getValidAccessToken_1 = require("../oauth/getValidAccessToken");
+const tokenStore_1 = require("../oauth/tokenStore");
+const errors_2 = require("../cli/errors");
+const supervise_1 = __importStar(require("./supervise"));
+const pushToken_1 = __importDefault(require("./pushToken"));
+/**
+ * Cadence of the refresh-and-push loop. Must be shorter than the access-token
+ * TTL: each tick mints (which refreshes when the token is near expiry) and
+ * pushes any change, so the token only lapses if a whole TTL elapses between
+ * ticks. 60s suits typical Keycloak access-token lifetimes (minutes); a
+ * deployment issuing sub-minute tokens would need a shorter interval.
+ */
+const DEFAULT_REFRESH_INTERVAL_MS = 60_000;
+/** Consecutive mid-session refresh failures before escalating from a per-tick line to one loud diagnostic. */
+const CONSECUTIVE_FAILURE_WARNING_THRESHOLD = 3;
+/**
+ * Extra time, on top of {@link MAX_TEARDOWN_MS}, given to `supervise`'s exit
+ * promise to settle after `teardown.abort()` before this function stops
+ * waiting on it. Covers the gap between the ladder's last signal firing and
+ * the child's `exit` event actually reaching us (process teardown, event-loop
+ * scheduling) — not more ladder; `supervise` itself is what bounds that.
+ */
+const TEARDOWN_SETTLE_BUFFER_MS = 500;
+const realScheduler = (intervalMs, tick) => {
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+};
+/**
+ * Supervise the wrapped server command for a session: mint an initial access
+ * token, inject it plus the refresh secret and port into the child's
+ * environment, and keep the running server's token fresh by refreshing and
+ * pushing before expiry. Resolves with the child's exit code.
+ *
+ * Fails fast with a `NOT_AUTHENTICATED` {@link CLIError} if there are no stored
+ * credentials to mint from, and with `REFRESH_UNREACHABLE` if the very first
+ * push cannot reach the server (almost always a misconfigured port/secret) —
+ * exiting so the MCP client sees the failure rather than letting the session
+ * silently die at expiry. Once a push has succeeded, a later refresh failure is
+ * logged (the server keeps its last good token) rather than tearing the session
+ * down, with one louder diagnostic after {@link CONSECUTIVE_FAILURE_WARNING_THRESHOLD}
+ * consecutive failures.
+ */
+async function runSession(options) {
+    const { command, commandArgs, port, portWasAutoSelected = false, secret = (0, node_crypto_1.randomBytes)(24).toString("hex"), refreshIntervalMs = DEFAULT_REFRESH_INTERVAL_MS, getToken = getValidAccessToken_1.getValidAccessToken, tokenStore = new tokenStore_1.KeyringTokenStore(), push = pushToken_1.default, supervise = supervise_1.default, scheduler = realScheduler, env = process.env, stdin, stdout, stderr = process.stderr, onSignal, } = options;
+    const loaded = await tokenStore.load();
+    const coordinates = {
+        issuerURL: loaded.ok ? loaded.entry.issuerURL : "",
+        clientId: loaded.ok ? loaded.entry.clientId : "",
+        allowInsecureIssuer: loaded.ok ? loaded.entry.allowInsecureIssuer : false,
+    };
+    // No `loadedEntry`: each call re-reads the store so it picks up the rotated
+    // refresh token from the previous refresh instead of replaying a stale one.
+    const mint = async () => {
+        try {
+            return await getToken({ ...coordinates, tokenStore });
+        }
+        catch (err) {
+            if (err instanceof errors_1.OAuthFlowError && err.code === "NOT_AUTHENTICATED") {
+                throw new errors_2.CLIError("NOT_AUTHENTICATED", err.message);
+            }
+            throw err;
+        }
+    };
+    const initialToken = await mint();
+    const childEnv = {
+        ...env,
+        AXE_ACCESS_TOKEN: initialToken,
+        AXE_TOKEN_REFRESH_PORT: String(port),
+        AXE_TOKEN_REFRESH_SECRET: secret,
+        // Only a container needs a non-loopback bind, and a container always pins
+        // its port. On an auto-picked port a stale `0.0.0.0` inherited from the
+        // environment would expose the token endpoint off-host, so pin loopback.
+        ...(portWasAutoSelected ? { AXE_TOKEN_REFRESH_HOST: "127.0.0.1" } : {}),
+    };
+    let lastPushed = initialToken;
+    let pushedSuccessfully = false;
+    let consecutiveFailures = 0;
+    let refreshing = false;
+    // Lets a fatal first-push failure interrupt the awaited `supervise` below.
+    let rejectFatal;
+    const fatal = new Promise((_, reject) => {
+        rejectFatal = reject;
+    });
+    // When `fatal` wins the race below, nothing else would ever tear the child
+    // down: this process exits while the wrapped server keeps the refresh port.
+    const teardown = new AbortController();
+    // A recoverable refresh failure: log it, and once failures pile up emit one
+    // louder line (they will keep failing every tick otherwise). The session
+    // stays alive on its last good token.
+    const noteRecoverableFailure = (message) => {
+        stderr.write(`axe-auth run: token refresh failed: ${message}\n`);
+        consecutiveFailures += 1;
+        if (consecutiveFailures === CONSECUTIVE_FAILURE_WARNING_THRESHOLD) {
+            stderr.write(`axe-auth run: token refresh has failed ${consecutiveFailures} times in a row; the server's access token will expire and calls will start failing — check that the refresh listener is reachable\n`);
+        }
+    };
+    const cancel = scheduler(refreshIntervalMs, () => {
+        if (refreshing) {
+            return;
+        }
+        refreshing = true;
+        void (async () => {
+            try {
+                let fresh;
+                try {
+                    fresh = await mint();
+                }
+                catch (err) {
+                    // Mint failure (e.g. a transient Keycloak blip): the injected token
+                    // may still be valid, so keep the session alive rather than exiting.
+                    noteRecoverableFailure((0, errors_2.describeError)(err));
+                    return;
+                }
+                if (fresh === lastPushed) {
+                    consecutiveFailures = 0;
+                    return;
+                }
+                try {
+                    await push({ port, secret, accessToken: fresh });
+                }
+                catch (err) {
+                    if (!pushedSuccessfully && !portWasAutoSelected) {
+                        // The first push never reached a port the user chose — almost
+                        // always a misconfigured port/secret. Fail so the client sees it.
+                        rejectFatal(new errors_2.CLIError("REFRESH_UNREACHABLE", `token refresh could not reach the server on port ${port} (${(0, errors_2.describeError)(err)}); check the refresh port and secret`));
+                        return;
+                    }
+                    noteRecoverableFailure((0, errors_2.describeError)(err));
+                    if (!pushedSuccessfully) {
+                        // Nothing ever answered on a port we chose, so the server did not
+                        // get it. Stop rather than re-offering a token every interval to
+                        // whatever else may hold it (#1028). The session keeps running;
+                        // it just has no refresh.
+                        cancel();
+                        stderr.write("axe-auth run: no token-refresh listener answered on the port this session picked; continuing without refresh\n");
+                    }
+                    return;
+                }
+                lastPushed = fresh;
+                pushedSuccessfully = true;
+                consecutiveFailures = 0;
+            }
+            finally {
+                refreshing = false;
+            }
+        })();
+    });
+    // Held separately so the `finally` can await it: if `fatal` wins the race,
+    // this is still pending with the wrapped server mid-teardown.
+    const superviseResult = supervise({
+        command,
+        args: commandArgs,
+        env: childEnv,
+        stdin,
+        stdout,
+        stderr,
+        onSignal,
+        signal: teardown.signal,
+    });
+    try {
+        return await Promise.race([superviseResult, fatal]);
+    }
+    finally {
+        cancel();
+        teardown.abort();
+        // The entrypoint calls `process.exit` with no macrotask in between, so
+        // without this the ladder's timers never run and the child is orphaned.
+        // Bounded so a `supervise` bug cannot hang the CLI.
+        await Promise.race([
+            superviseResult.catch(() => { }),
+            new Promise((resolve) => {
+                const settleTimer = setTimeout(resolve, supervise_1.MAX_TEARDOWN_MS + TEARDOWN_SETTLE_BUFFER_MS);
+                settleTimer.unref();
+            }),
+        ]);
+    }
+}

package/dist/run/supervise.d.ts

@@ -0,0 +1,72 @@
+import type { Readable, Writable } from "node:stream";
+/**
+ * Grace the wrapped server gets before `SIGKILL`. Must exceed that server's
+ * own teardown budget or its graceful path never completes: axe-mcp-server
+ * publishes {@link SERVER_TEARDOWN_BUDGET_MS}, so this leaves a second of
+ * margin. Raising that budget means raising this.
+ *
+ * TODO(nayanrajDQ): measure a live Chromium teardown against this grace.
+ */
+export declare const TEARDOWN_GRACE_MS = 4000;
+/**
+ * The budget axe-mcp-server publishes as `MAX_TEARDOWN_BUDGET_MS`. Restated
+ * here because the two are separately released packages with no shared code;
+ * a test pins each side so raising one without the other fails loudly.
+ */
+export declare const SERVER_TEARDOWN_BUDGET_MS = 3000;
+/** Each rung's signal and how long to wait *before* sending it. */
+export type TeardownLadder = ReadonlyArray<{
+    signal: NodeJS.Signals;
+    delayBeforeMs: number;
+}>;
+/**
+ * Upper bound on the ladder once teardown starts. Exported so `runSession`
+ * bounds its wait on the ladder's arithmetic, not a constant of its own.
+ */
+export declare const MAX_TEARDOWN_MS: number;
+/** Options for {@link supervise}. */
+export interface SuperviseOptions {
+    /** Executable to run (e.g. `docker`, `npx`). */
+    command: string;
+    /** Arguments passed to the executable. */
+    args: string[];
+    /** Environment for the child. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Stream feeding the child's stdin. Defaults to `process.stdin`. */
+    stdin?: Readable;
+    /** Stream the child's stdout is written to. Defaults to `process.stdout`. */
+    stdout?: Writable;
+    /** Stream the child's stderr is written to. Defaults to `process.stderr`. */
+    stderr?: Writable;
+    /** Registers a termination-signal handler. Injectable for tests; defaults to `process.on`. */
+    onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+    /** Registers a parent-death watchdog. Injectable for tests; defaults to polling {@link SuperviseOptions.readParentPID}. */
+    onParentExit?: (handler: () => void) => void;
+    /** Reads the launching process's pid. Injectable for tests; defaults to `process.ppid`. */
+    readParentPID?: () => number;
+    /** Tears the child down when aborted, e.g. because the caller hit a fatal error. */
+    signal?: AbortSignal;
+    /**
+     * Signal-and-wait rungs teardown escalates through. Injectable so tests can
+     * exercise an escalation without sleeping out the shipped grace; defaults to
+     * the real ladder, which one test keeps covered at its true timings.
+     */
+    ladder?: TeardownLadder;
+}
+/**
+ * Spawn `command` and transparently bridge this process's stdio to it: the
+ * parent's stdin drives the child's stdin (so the MCP client's JSON-RPC stream
+ * reaches the wrapped server untouched), the child's stdout and stderr flow
+ * back out, termination signals are forwarded, and the child's exit is
+ * propagated. Resolves with the child's exit code, or `128 + signal` when the
+ * child is killed by a signal (shell convention); rejects only if the child
+ * fails to spawn.
+ *
+ * stdin EOF, a forwarded signal, {@link SuperviseOptions.signal}, and the
+ * launching process vanishing each put the child on a bounded teardown ladder.
+ *
+ * A client that leaks stdin open without signalling or exiting fires none of
+ * those. The wrapped server catches that itself by probing the client, and its
+ * exit unwinds this supervisor.
+ */
+export default function supervise(options: SuperviseOptions): Promise<number>;

package/dist/run/supervise.js

@@ -0,0 +1,234 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEARDOWN_MS = exports.SERVER_TEARDOWN_BUDGET_MS = exports.TEARDOWN_GRACE_MS = void 0;
+exports.default = supervise;
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Signals forwarded from this process to the supervised child. */
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * Grace the wrapped server gets before `SIGKILL`. Must exceed that server's
+ * own teardown budget or its graceful path never completes: axe-mcp-server
+ * publishes {@link SERVER_TEARDOWN_BUDGET_MS}, so this leaves a second of
+ * margin. Raising that budget means raising this.
+ *
+ * TODO(nayanrajDQ): measure a live Chromium teardown against this grace.
+ */
+exports.TEARDOWN_GRACE_MS = 4_000;
+/**
+ * The budget axe-mcp-server publishes as `MAX_TEARDOWN_BUDGET_MS`. Restated
+ * here because the two are separately released packages with no shared code;
+ * a test pins each side so raising one without the other fails loudly.
+ */
+exports.SERVER_TEARDOWN_BUDGET_MS = 3_000;
+/**
+ * The shipped POSIX ladder. On a forwarded signal the caller's signal is the
+ * polite rung, so only the SIGKILL wait runs.
+ */
+const TEARDOWN_LADDER = [
+    { signal: "SIGTERM", delayBeforeMs: 2_000 },
+    { signal: "SIGKILL", delayBeforeMs: exports.TEARDOWN_GRACE_MS },
+];
+/**
+ * Windows has no signalable process group and no polite signal, so the whole
+ * ladder is one rung: close the child's stdin, wait out the same grace, then
+ * force-kill the tree. Sharing {@link TEARDOWN_LADDER} would force-kill at its
+ * first rung, giving the server less grace than it publishes.
+ */
+const WINDOWS_TEARDOWN_LADDER = [
+    { signal: "SIGKILL", delayBeforeMs: exports.TEARDOWN_GRACE_MS },
+];
+/**
+ * Upper bound on the ladder once teardown starts. Exported so `runSession`
+ * bounds its wait on the ladder's arithmetic, not a constant of its own.
+ */
+exports.MAX_TEARDOWN_MS = TEARDOWN_LADDER.reduce((total, rung) => total + rung.delayBeforeMs, 0);
+/**
+ * How often the watchdog samples `process.ppid`. A launcher that vanishes
+ * without closing stdin or signalling is only observable by polling.
+ */
+const PARENT_POLL_INTERVAL_MS = 1_000;
+/**
+ * Spawn `command` and transparently bridge this process's stdio to it: the
+ * parent's stdin drives the child's stdin (so the MCP client's JSON-RPC stream
+ * reaches the wrapped server untouched), the child's stdout and stderr flow
+ * back out, termination signals are forwarded, and the child's exit is
+ * propagated. Resolves with the child's exit code, or `128 + signal` when the
+ * child is killed by a signal (shell convention); rejects only if the child
+ * fails to spawn.
+ *
+ * stdin EOF, a forwarded signal, {@link SuperviseOptions.signal}, and the
+ * launching process vanishing each put the child on a bounded teardown ladder.
+ *
+ * A client that leaks stdin open without signalling or exiting fires none of
+ * those. The wrapped server catches that itself by probing the client, and its
+ * exit unwinds this supervisor.
+ */
+function supervise(options) {
+    const { command, args, env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, onSignal = (signal, handler) => {
+        process.on(signal, handler);
+    }, readParentPID = () => process.ppid, onParentExit = (handler) => {
+        const parentPID = readParentPID();
+        const timer = setInterval(() => {
+            // Reparenting is the only portable signal that the parent died.
+            if (readParentPID() !== parentPID) {
+                handler();
+            }
+        }, PARENT_POLL_INTERVAL_MS);
+        timer.unref();
+    }, signal: abortSignal, ladder = process.platform === "win32"
+        ? WINDOWS_TEARDOWN_LADDER
+        : TEARDOWN_LADDER, } = options;
+    return new Promise((resolve, reject) => {
+        const child = (0, cross_spawn_1.default)(command, args, {
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+            // POSIX only: own process group so a kill reaches the whole tree, since
+            // a dead child's children reparent away and cannot be walked after. The
+            // pipes are untouched, so EOF still arrives if this process is SIGKILLed.
+            // Windows gets the same reach via `taskkill /T`; see `signalTree`.
+            detached: process.platform !== "win32",
+        });
+        let exited = false;
+        let tearingDown = false;
+        let rungTimer;
+        /**
+         * Signal the child's whole process tree.
+         *
+         * TODO(stephenmathieson): a container runtime's container is a child of
+         * the daemon, so `SIGKILL` reaches only the client and can leave the
+         * container running on its published port (#1027).
+         *
+         * Windows has no signalable process group and `process.kill` there maps
+         * every signal onto `TerminateProcess`, which kills the direct child and
+         * orphans the grandchild holding the port. `taskkill /T` walks the tree.
+         *
+         * Both rungs pass `/F`: Windows has no graceful termination to ask for,
+         * and `/T` alone leaves a console process running.
+         */
+        const signalTree = (signal) => {
+            if (exited || child.pid === undefined) {
+                return;
+            }
+            if (process.platform === "win32") {
+                // Absolute path: Windows resolution searches the working directory
+                // first, and we launch from the user's project folder, so a planted
+                // `taskkill.exe` would win.
+                const taskkill = process.env.SystemRoot
+                    ? (0, node_path_1.join)(process.env.SystemRoot, "System32", "taskkill.exe")
+                    : "taskkill";
+                const killer = (0, cross_spawn_1.default)(taskkill, ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+                killer.on("error", () => { });
+                killer.unref();
+                return;
+            }
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch {
+                // Already reaped, or the signal means nothing on this platform.
+            }
+        };
+        /** Walk the remaining rungs of the ladder, stopping as soon as the child exits. */
+        const escalate = (rungs) => {
+            const [next, ...rest] = rungs;
+            if (exited || next === undefined) {
+                return;
+            }
+            rungTimer = setTimeout(() => {
+                if (exited) {
+                    return;
+                }
+                // No pid means spawn failed after the ladder was armed. Nothing to
+                // kill, so don't claim one happened.
+                if (next.signal === "SIGKILL" && child.pid !== undefined) {
+                    stderr.write(process.platform === "win32"
+                        ? "axe-auth run: wrapped server did not stop when asked; killing its process tree\n"
+                        : "axe-auth run: wrapped server did not stop when asked; killing its process group\n");
+                }
+                signalTree(next.signal);
+                escalate(rest);
+            }, next.delayBeforeMs);
+        };
+        /**
+         * Start the teardown ladder. `asked` is the signal already sent for the
+         * caller, or `undefined` on the stdin-EOF path where the closed pipe is
+         * itself the polite request.
+         */
+        const beginTeardown = (asked) => {
+            if (exited || tearingDown) {
+                return;
+            }
+            tearingDown = true;
+            if (process.platform === "win32") {
+                // No polite signal exists here: `signalTree` is always a forced tree
+                // kill, so forwarding the caller's signal would skip the grace
+                // entirely. The closed pipe is the only graceful rung, and it is what
+                // the wrapped server shuts down on.
+                child.stdin?.end();
+                escalate(ladder);
+                return;
+            }
+            if (asked) {
+                // The caller's signal was the polite rung; only harder ones remain.
+                signalTree(asked);
+                escalate(ladder.slice(1));
+                return;
+            }
+            // The closed pipe was the polite request; run the full ladder.
+            escalate(ladder);
+        };
+        child.once("error", reject);
+        if (child.stdin) {
+            stdin.pipe(child.stdin);
+            // Writing to a child that already exited throws EPIPE otherwise.
+            child.stdin.on("error", () => { });
+        }
+        // The server shuts down on the closed pipe, but may not obey.
+        stdin.once("end", () => {
+            beginTeardown(undefined);
+        });
+        // `end: false` so the child cannot close the parent's shared streams.
+        child.stdout?.pipe(stdout, { end: false });
+        child.stderr?.pipe(stderr, { end: false });
+        for (const signal of FORWARDED_SIGNALS) {
+            onSignal(signal, () => {
+                beginTeardown(signal);
+            });
+        }
+        onParentExit(() => {
+            if (exited || tearingDown) {
+                return;
+            }
+            stderr.write("axe-auth run: the process that launched this session is gone; shutting down the wrapped server\n");
+            beginTeardown("SIGTERM");
+        });
+        // An already-aborted signal fires no event, so subscribing alone would
+        // spawn the child and never tear it down.
+        if (abortSignal?.aborted) {
+            beginTeardown("SIGTERM");
+        }
+        else {
+            abortSignal?.addEventListener("abort", () => {
+                beginTeardown("SIGTERM");
+            }, { once: true });
+        }
+        child.once("exit", (code, signal) => {
+            exited = true;
+            clearTimeout(rungTimer);
+            if (child.stdin) {
+                stdin.unpipe(child.stdin);
+            }
+            if (code !== null) {
+                resolve(code);
+            }
+            else {
+                resolve(128 + (node_os_1.constants.signals[signal ?? "SIGTERM"] ?? 0));
+            }
+        });
+    });
+}

package/dist/run/testUtils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How long a test waits on a teardown before calling it hung. Derived, so
+ * moving a ladder rung cannot turn these assertions into flakes.
+ */
+export declare const MAX_TEARDOWN_WAIT_MS: number;
+/** Whether `pid` still exists (a reaped process's signal 0 throws ESRCH). */
+export declare function alive(pid: number): boolean;
+/** Poll until `predicate` holds or time runs out. */
+export declare function waitFor(predicate: () => boolean, timeoutMs?: number): Promise<void>;
+/**
+ * The resolved value, or `"hung"` if `work` was still pending after `ms`.
+ * A bounded assertion is the point: an unbounded `await` on a supervisor that
+ * never tears down just hangs the test run instead of failing it.
+ */
+export declare function settleWithin<T>(work: Promise<T>, ms?: number): Promise<T | "hung">;

package/dist/run/testUtils.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEARDOWN_WAIT_MS = void 0;
+exports.alive = alive;
+exports.waitFor = waitFor;
+exports.settleWithin = settleWithin;
+const supervise_1 = require("./supervise");
+/**
+ * How long a test waits on a teardown before calling it hung. Derived, so
+ * moving a ladder rung cannot turn these assertions into flakes.
+ */
+exports.MAX_TEARDOWN_WAIT_MS = supervise_1.MAX_TEARDOWN_MS + 2_000;
+/** Whether `pid` still exists (a reaped process's signal 0 throws ESRCH). */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Poll until `predicate` holds or time runs out. */
+async function waitFor(predicate, timeoutMs = exports.MAX_TEARDOWN_WAIT_MS) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs) {
+            throw new Error("waitFor timed out");
+        }
+        await new Promise((r) => setTimeout(r, 20));
+    }
+}
+/**
+ * The resolved value, or `"hung"` if `work` was still pending after `ms`.
+ * A bounded assertion is the point: an unbounded `await` on a supervisor that
+ * never tears down just hangs the test run instead of failing it.
+ */
+async function settleWithin(work, ms = exports.MAX_TEARDOWN_WAIT_MS) {
+    return await Promise.race([
+        work,
+        new Promise((r) => setTimeout(() => r("hung"), ms).unref()),
+    ]);
+}