@deque/axe-auth 1.5.0-rc.bbbeb999 → 1.6.0-next.09b9233d

package/README.md

@@ -72,7 +72,7 @@ axe-auth logout
 
 ### Long-running sessions
 
-Access tokens are short-lived, so a session that outlives the token's TTL (an agent driving the MCP server for hours, say) would otherwise start seeing auth failures. `axe-auth run` handles this automatically: it launches and supervises the server, then keeps its access token fresh for the whole session with no restart and no manual step. Point your MCP client at `axe-auth run` as the server command; it manages the server process's lifetime like any stdio server. Your refresh token never leaves the machine; only short-lived access tokens are sent to the server.
+Access tokens are short-lived, so a session that outlives the token's TTL (an agent driving the MCP server for hours, say) would otherwise start seeing auth failures. `axe-auth run` handles this automatically: it launches and supervises the server, then keeps its access token fresh for the whole session with no restart and no manual step. Point your MCP client at `axe-auth run` as the server command; it manages the server process's lifetime like any stdio server. It also shuts the server down when the session ends: on stdin close, on a termination signal, and when the launching process disappears. The server itself exits when the client stops answering its liveness probes. Each session takes a fresh refresh port from the OS unless you pin one with `--port` or `AXE_TOKEN_REFRESH_PORT`, so a server left behind by an earlier session cannot hold the port this one needs. Pin one for containers, which only reach a port you publish: `run` detects `docker`, `podman`, and `nerdctl` and refuses to guess, but any other runtime or a wrapper script is yours to pin. Your refresh token never leaves the machine; only short-lived access tokens are sent to the server.
 
 The server just needs token refresh enabled on a port; `run` supplies the token and secret. Under Docker, publish the port on host loopback, forward the auth vars, and bind the listener to `0.0.0.0` inside the container so the published port can reach it:
 
@@ -92,10 +92,10 @@ AXE_TOKEN_REFRESH_PORT=9223 npx @deque/axe-auth run -- \
 Under npm the wrapped process inherits the values directly and the listener stays on loopback:
 
 ```sh
-AXE_TOKEN_REFRESH_PORT=9223 npx @deque/axe-auth run -- npx axe-mcp-server
+npx @deque/axe-auth run -- npx axe-mcp-server
 ```
 
-Set the port with `AXE_TOKEN_REFRESH_PORT` or `--port`. `run` generates the shared secret unless you pin one with `AXE_TOKEN_REFRESH_SECRET` / `--secret`. The secret authenticates the push; the server's listener binds loopback by default and never starts without a secret.
+`run` picks a free loopback port per session; pin one with `AXE_TOKEN_REFRESH_PORT` or `--port` only for containers, which can reach only a port you publish. `run` generates the shared secret unless you pin one with `AXE_TOKEN_REFRESH_SECRET` / `--secret`. The secret authenticates the push; the server's listener binds loopback by default and never starts without a secret.
 
 ## Architecture
 

package/dist/commands/run.help.d.ts

@@ -1,2 +1,2 @@
 /** Help text for `axe-auth run --help`. */
-export declare const HELP_RUN = "npx @deque/axe-auth run -- <server launch command>\n\nLaunch and supervise the axe MCP server so it keeps a valid OAuth access\ntoken for the whole session, refreshing before expiry without a restart. Use\nthis as your MCP client's server command; the client manages its lifetime like\nany stdio server. Everything after `--` is the command it launches.\n\nUsage:\n  npx @deque/axe-auth run [--port <port>] [--secret <secret>] -- <command> [args...]\n\n  The wrapped server must be started with token refresh on a loopback port.\n  Under Docker, publish it with `-p 127.0.0.1:<port>:<port>`, forward the auth\n  vars with `-e AXE_ACCESS_TOKEN -e AXE_TOKEN_REFRESH_PORT -e AXE_TOKEN_REFRESH_SECRET`,\n  and set `-e AXE_TOKEN_REFRESH_HOST=0.0.0.0` so the published port can reach the\n  listener; `run` supplies the token/port/secret values. Under npm the wrapped\n  node process inherits them directly.\n\nOptions:\n  --port <port>      Loopback port the server's refresh listener uses.\n                     Defaults to AXE_TOKEN_REFRESH_PORT.\n  --secret <secret>  Shared secret for the refresh channel. Defaults to\n                     AXE_TOKEN_REFRESH_SECRET, otherwise a generated one.\n                     Prefer the env var: a value passed here is visible to other\n                     local users via the process list.\n  -h, --help         Show this help.\n\nExit codes:\n  0    The wrapped server exited normally.\n  1    Not authenticated; run `npx @deque/axe-auth login` first.\n  2    Configuration or connectivity error (missing/invalid port, no command\n       after `--`, or the refresh channel could not reach the server).\n  <n>  Otherwise, the wrapped server's own exit code.";
+export declare const HELP_RUN = "npx @deque/axe-auth run -- <server launch command>\n\nLaunch and supervise the axe MCP server so it keeps a valid OAuth access\ntoken for the whole session, refreshing before expiry without a restart. Use\nthis as your MCP client's server command; the client manages its lifetime like\nany stdio server. Everything after `--` is the command it launches.\n\nUsage:\n  npx @deque/axe-auth run [--port <port>] [--secret <secret>] -- <command> [args...]\n\n  The wrapped server must be started with token refresh on a loopback port.\n  Under Docker, publish it with `-p 127.0.0.1:<port>:<port>`, forward the auth\n  vars with `-e AXE_ACCESS_TOKEN -e AXE_TOKEN_REFRESH_PORT -e AXE_TOKEN_REFRESH_SECRET`,\n  and set `-e AXE_TOKEN_REFRESH_HOST=0.0.0.0` so the published port can reach the\n  listener; `run` supplies the token/port/secret values. Under npm the wrapped\n  node process inherits them directly.\n\nOptions:\n  --port <port>      Loopback port the server's refresh listener uses.\n                     Defaults to AXE_TOKEN_REFRESH_PORT, otherwise a free\n                     port chosen per session. Pin one for a container,\n                     which can only reach a published port: docker,\n                     podman, and nerdctl are detected and refused\n                     without it; pin it yourself for anything else.\n  --secret <secret>  Shared secret for the refresh channel. Defaults to\n                     AXE_TOKEN_REFRESH_SECRET, otherwise a generated one.\n                     Prefer the env var: a value passed here is visible to other\n                     local users via the process list.\n  -h, --help         Show this help.\n\nExit codes:\n  0    The wrapped server exited normally.\n  1    Not authenticated; run `npx @deque/axe-auth login` first.\n  2    Configuration or connectivity error (an invalid port, a container\n       command with no port pinned, no command after `--`, or a pinned\n       refresh port the server could not be reached on).\n  <n>  Otherwise, the wrapped server's own exit code.";

package/dist/commands/run.help.js

@@ -21,7 +21,11 @@ Usage:
 
 Options:
   --port <port>      Loopback port the server's refresh listener uses.
-                     Defaults to AXE_TOKEN_REFRESH_PORT.
+                     Defaults to AXE_TOKEN_REFRESH_PORT, otherwise a free
+                     port chosen per session. Pin one for a container,
+                     which can only reach a published port: docker,
+                     podman, and nerdctl are detected and refused
+                     without it; pin it yourself for anything else.
   --secret <secret>  Shared secret for the refresh channel. Defaults to
                      AXE_TOKEN_REFRESH_SECRET, otherwise a generated one.
                      Prefer the env var: a value passed here is visible to other
@@ -31,6 +35,7 @@ Options:
 Exit codes:
   0    The wrapped server exited normally.
   1    Not authenticated; run \`npx @deque/axe-auth login\` first.
-  2    Configuration or connectivity error (missing/invalid port, no command
-       after \`--\`, or the refresh channel could not reach the server).
+  2    Configuration or connectivity error (an invalid port, a container
+       command with no port pinned, no command after \`--\`, or a pinned
+       refresh port the server could not be reached on).
   <n>  Otherwise, the wrapped server's own exit code.`;

package/dist/commands/run.js

@@ -6,8 +6,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dispatchRun = dispatchRun;
 const node_util_1 = require("node:util");
 const runSession_1 = __importDefault(require("../run/runSession"));
+const findFreePort_1 = __importDefault(require("../run/findFreePort"));
 const run_help_1 = require("./run.help");
 const errors_1 = require("../cli/errors");
+/** Container runtimes whose child cannot reach a host port it was not told to publish. */
+const CONTAINER_COMMANDS = new Set(["docker", "podman", "nerdctl"]);
+/** Whether `command` launches a container runtime rather than a local process. */
+function isContainerCommand(command) {
+    if (!command) {
+        return false;
+    }
+    const name = command.split(/[/\\]/).pop() ?? command;
+    return CONTAINER_COMMANDS.has(name.replace(/\.exe$/i, "").toLowerCase());
+}
 /**
  * `axe-auth run [--port] [--secret] -- <command> [args...]`. Unlike the other
  * verbs, everything after `--` is the wrapped server command, so this bypasses
@@ -45,16 +56,27 @@ async function dispatchRun(rest, deps) {
         deps.stderr.write("axe-auth run needs a command after `--`, e.g. `npx @deque/axe-auth run -- docker run ... axe-mcp-server`\n");
         return 2;
     }
+    // No port pinned: take a fresh one, so a leftover server from an earlier
+    // session cannot collide with it (dequelabs/axe-mcp-server#1013).
     const portRaw = values.port ?? env.AXE_TOKEN_REFRESH_PORT;
-    if (!portRaw) {
-        deps.stderr.write("axe-auth run needs a refresh port: set AXE_TOKEN_REFRESH_PORT or pass --port\n");
-        return 2;
+    let port;
+    const portWasAutoSelected = !portRaw;
+    if (portRaw) {
+        port = Number(portRaw);
+        if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
+            deps.stderr.write(`Invalid port ${portRaw}: must be a TCP port (1-65535)\n`);
+            return 2;
+        }
     }
-    const port = Number(portRaw);
-    if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
-        deps.stderr.write(`Invalid port ${portRaw}: must be a TCP port (1-65535)\n`);
+    else if (isContainerCommand(childArgv[0])) {
+        // A container only reaches a published port, so an ephemeral one would
+        // never be reachable. Fail now, not at the first refresh push.
+        deps.stderr.write("axe-auth run needs an explicit refresh port when the wrapped command is a container: set AXE_TOKEN_REFRESH_PORT or pass --port, and publish it with `-p 127.0.0.1:<port>:<port>`\n");
         return 2;
     }
+    else {
+        port = await (0, findFreePort_1.default)();
+    }
     // Mirror the server's minimum-length check so a short pinned secret fails
     // here, at the command the user ran, rather than as a downstream server
     // startup crash. An unset secret is generated by `runSession`.
@@ -69,6 +91,7 @@ async function dispatchRun(rest, deps) {
             command: childArgv[0],
             commandArgs: childArgv.slice(1),
             port,
+            portWasAutoSelected,
             secret,
             env,
             stderr: deps.stderr,

package/dist/run/findFreePort.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ask the OS for a free loopback port by binding port 0 and releasing it.
+ *
+ * Sessions used to share one fixed port, so a leftover server held it and the
+ * next session lost token refresh (dequelabs/axe-mcp-server#1013). The OS
+ * never hands out a port something is still bound to.
+ *
+ * It is released before the child binds it, so another process could take it
+ * in between. That window is not small: it spans minting a token against
+ * Keycloak and starting the child. Because the port was not the user's
+ * choice, losing it degrades the session to no token refresh rather than
+ * failing it (see `portWasAutoSelected` in `runSession`).
+ *
+ * Nothing proves the listener on that port is our child, so a process that
+ * takes it receives whatever is pushed there. Tracked in #1028.
+ */
+export default function findFreePort(host?: string): Promise<number>;

package/dist/run/findFreePort.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = findFreePort;
+const node_net_1 = require("node:net");
+/**
+ * Ask the OS for a free loopback port by binding port 0 and releasing it.
+ *
+ * Sessions used to share one fixed port, so a leftover server held it and the
+ * next session lost token refresh (dequelabs/axe-mcp-server#1013). The OS
+ * never hands out a port something is still bound to.
+ *
+ * It is released before the child binds it, so another process could take it
+ * in between. That window is not small: it spans minting a token against
+ * Keycloak and starting the child. Because the port was not the user's
+ * choice, losing it degrades the session to no token refresh rather than
+ * failing it (see `portWasAutoSelected` in `runSession`).
+ *
+ * Nothing proves the listener on that port is our child, so a process that
+ * takes it receives whatever is pushed there. Tracked in #1028.
+ */
+async function findFreePort(host = "127.0.0.1") {
+    const probe = (0, node_net_1.createServer)();
+    try {
+        return await new Promise((resolve, reject) => {
+            probe.once("error", reject);
+            probe.listen(0, host, () => {
+                const address = probe.address();
+                if (address === null) {
+                    reject(new Error("could not determine a free port"));
+                    return;
+                }
+                resolve(address.port);
+            });
+        });
+    }
+    finally {
+        await new Promise((resolve) => probe.close(() => resolve()));
+    }
+}

package/dist/run/pushToken.js

@@ -6,6 +6,8 @@ exports.default = pushToken;
 exports.REFRESH_SECRET_HEADER = "x-refresh-secret";
 /** Bound the push so a stalled server can't hang the caller. */
 const PUSH_TIMEOUT_MS = 5_000;
+/** How much of a failed push's response body is worth repeating to the user. */
+const MAX_DETAIL_LEN = 200;
 /** POST the fresh token to the server's loopback refresh listener. */
 async function pushToken({ port, secret, accessToken, }) {
     const res = await fetch(`http://127.0.0.1:${port}/token`, {
@@ -18,7 +20,16 @@ async function pushToken({ port, secret, accessToken, }) {
         signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
     });
     if (!res.ok) {
-        const detail = await res.text().catch(() => "");
+        // Whatever holds this port wrote the body, and it reaches the client's
+        // stderr, so take a little of it and strip anything that could forge log
+        // lines or redraw the terminal.
+        const detail = await res
+            .text()
+            .then((text) => text
+            .slice(0, MAX_DETAIL_LEN)
+            .replace(/[^\t\x20-\x7e]/g, " ")
+            .trim())
+            .catch(() => "");
         throw new Error(`server responded ${res.status}${detail ? `: ${detail}` : ""}`);
     }
 }

package/dist/run/runSession.d.ts

@@ -13,6 +13,12 @@ export interface RunSessionOptions {
     commandArgs: string[];
     /** Loopback port the server's refresh listener is on. */
     port: number;
+    /**
+     * Whether the port was chosen by us rather than by the user. An auto-picked
+     * port can lose a race it is not the user's fault to lose, so a first push
+     * that cannot reach it degrades the session instead of failing it.
+     */
+    portWasAutoSelected?: boolean;
     /** Shared secret authenticating pushes. Generated if omitted. */
     secret?: string;
     /** Cadence of the refresh-and-push loop, ms. */

package/dist/run/runSession.js

@@ -1,4 +1,37 @@
 "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 };
 };
@@ -9,7 +42,7 @@ 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 = __importDefault(require("./supervise"));
+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
@@ -21,6 +54,14 @@ const pushToken_1 = __importDefault(require("./pushToken"));
 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();
@@ -42,7 +83,7 @@ const realScheduler = (intervalMs, tick) => {
  * consecutive failures.
  */
 async function runSession(options) {
-    const { command, commandArgs, port, 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 { 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 : "",
@@ -68,6 +109,10 @@ async function runSession(options) {
         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;
@@ -78,6 +123,9 @@ async function runSession(options) {
     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.
@@ -113,13 +161,20 @@ async function runSession(options) {
                     await push({ port, secret, accessToken: fresh });
                 }
                 catch (err) {
-                    if (!pushedSuccessfully) {
-                        // The first push never reached the server — almost always a
-                        // misconfigured port/secret. Fail so the MCP client sees the exit.
+                    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;
                     }
-                    else {
-                        noteRecoverableFailure((0, errors_2.describeError)(err));
+                    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;
                 }
@@ -132,21 +187,33 @@ async function runSession(options) {
             }
         })();
     });
+    // 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([
-            supervise({
-                command,
-                args: commandArgs,
-                env: childEnv,
-                stdin,
-                stdout,
-                stderr,
-                onSignal,
-            }),
-            fatal,
-        ]);
+        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

@@ -1,4 +1,29 @@
 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`). */
@@ -15,6 +40,18 @@ export interface SuperviseOptions {
     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
@@ -25,7 +62,11 @@ export interface SuperviseOptions {
  * child is killed by a signal (shell convention); rejects only if the child
  * fails to spawn.
  *
- * This is the core of `axe-auth run`: it lets the MCP client spawn `axe-auth`
- * as its stdio server command while axe-auth manages tokens out of band.
+ * 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

@@ -3,11 +3,55 @@ 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
@@ -17,38 +61,165 @@ const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
  * child is killed by a signal (shell convention); rejects only if the child
  * fails to spawn.
  *
- * This is the core of `axe-auth run`: it lets the MCP client spawn `axe-auth`
- * as its stdio server command while axe-auth manages tokens out of band.
+ * 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);
-    }, } = options;
+    }, 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) => {
-        // Not `detached`: if this process dies without cleanup (e.g. SIGKILL), the
-        // closed stdin pipe gives the child EOF, which is how the wrapped server
-        // shuts down and avoids being orphaned. Detaching would sever that.
         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);
-            // The child may exit while the parent is still writing; a write to its
-            // closed stdin would otherwise throw EPIPE and crash the supervisor.
+            // Writing to a child that already exited throws EPIPE otherwise.
             child.stdin.on("error", () => { });
         }
-        // `end: false` so the child closing its stream never tears down the
-        // parent's shared stdout/stderr.
+        // 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, () => {
-                child.kill(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);
             }

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()),
+    ]);
+}

package/docs/architecture.md

@@ -134,6 +134,11 @@ sequenceDiagram
 
   User->>Client: set axe-auth run as the stdio server command
   Client->>CLI: spawn (stdio)
+  alt --port or AXE_TOKEN_REFRESH_PORT pinned
+    Note over CLI: use it as given (required for a container runtime)
+  else nothing pinned
+    Note over CLI: take a free loopback port from the OS,<br/>so a leftover server cannot collide
+  end
   Note over CLI: mint initial access token (refresh via Keycloak if near expiry)
   opt token near expiry
     CLI->>KC: POST /token (refresh_token)
@@ -149,15 +154,31 @@ sequenceDiagram
     KC-->>CLI: { access_token }
     CLI->>Server: POST /token (x-refresh-secret) — swap in-memory token
   end
-  Server-->>CLI: child exits
-  CLI-->>Client: exit with the child's code
+  alt wrapped server exits on its own
+    Server-->>CLI: child exits
+    CLI-->>Client: exit with the child's code
+  else session ends (stdin EOF, forwarded signal, launcher gone, or fatal startup abort)
+    CLI->>Server: polite rung — forwarded signal or SIGTERM across the process group, or a closed stdin on Windows
+    opt still alive after the grace period
+      CLI->>Server: SIGKILL (process group, or taskkill /T /F on Windows)
+    end
+    Server-->>CLI: child exits
+  end
 ```
 
-1. The developer points their MCP client at `axe-auth run -- <server launch command>` as the stdio server command, configuring a loopback refresh port via `--port` or `AXE_TOKEN_REFRESH_PORT`.
+1. The developer points their MCP client at `axe-auth run -- <server launch command>` as the stdio server command. A free loopback refresh port is taken from the OS per session, so a server left behind by an earlier session cannot collide with it; `--port` or `AXE_TOKEN_REFRESH_PORT` pins one instead. A container only reaches a host port it was told to publish with `-p`, so `run` refuses to guess one when it recognises the wrapped command as `docker`, `podman`, or `nerdctl`. Detection is by command name, so another runtime, or one reached through a wrapper script, takes an auto-selected port it cannot reach and degrades to no token refresh; pin a port yourself there.
 2. `run` obtains a currently-valid access token (exactly as `axe-auth token` does, refreshing against Keycloak if needed), generates a shared secret unless one is provided, and launches the wrapped server as a child process with the token, port, and secret injected into its environment.
 3. `run` transparently bridges the client's stdio to the child so the MCP session flows through untouched, and supervises the child for the session's lifetime.
 4. In the background, `run` keeps the access token fresh and pushes each new token to the server's loopback listener at `http://127.0.0.1:<port>/token` (secret in an `x-refresh-secret` header). The refresh token is never sent; only short-lived access tokens.
-5. When the wrapped server exits, `run` exits with the same code.
+5. When the wrapped server exits on its own, `run` exits with the same code.
+6. `run` also ends the session itself, so the server cannot outlive it holding the refresh port: on stdin EOF, on a forwarded `SIGINT`/`SIGTERM`/`SIGHUP`, when the launching process disappears, and on a fatal error. Each puts the child on a teardown ladder: a polite rung the server can shut down on, then a forced one. On macOS and Linux that is the forwarded signal (or `SIGTERM`), then `SIGKILL` across the process group. Windows has no polite signal, so the closed stdin pipe is the polite rung and the forced one is `taskkill /T /F` across the process tree. The wrapped server separately ends the session when the client stops answering `ping`, which catches a client that never closed the pipe.
+
+#### Known limitations
+
+Two cases are bounded rather than closed.
+
+- **A container can outlive an ungraceful teardown.** When the wrapped command is a container runtime, `axe-auth` supervises the client, not the container, so the polite rung is forwarded to the container but `SIGKILL` reaches only the client. A server that does not stop within the grace therefore leaves the container running on the port it published, which the next session cannot reuse. Recover with `docker rm -f <container>`. Pinning a port is already required here, so the collision is not silent. Tracked in [#1027](https://github.com/dequelabs/axe-mcp-server/issues/1027).
+- **A browser can outlive an ungraceful teardown.** On POSIX the final `SIGKILL` reaches the server's process group, but Playwright runs Chromium in its own, so a scan still mid-flight when the grace expires leaves a browser for the user to close by hand. It holds no port, so it does not block the next session. Windows is unaffected: the forced rung there walks the whole process tree.
 
 ### `axe-auth logout`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.5.0-rc.bbbeb999",
+  "version": "1.6.0-next.09b9233d",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -37,12 +37,12 @@
     "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.11",
+    "@hono/node-server": "^2.1.0",
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^24.13.2",
-    "c8": "^11.0.0",
-    "hono": "^4.12.34",
-    "tsx": "^4.22.4",
+    "@types/node": "^24.13.3",
+    "c8": "^12.0.0",
+    "hono": "^4.13.5",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3"
   },
   "scripts": {