@haywoodmarx/agent-pager 0.1.0

package/dist/src/broker/snapshot.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { LOOPBACK_HOST } from "../configuration-defaults.js";
+import { closeServer, listenServer, urlHost, writeJson } from "../shared/http.js";
+/**
+ * Start the loopback-only snapshot HTTP endpoint.
+ * @param broker - Durable broker port that owns message state.
+ * @param port - Requested loopback port, with zero selecting an ephemeral port.
+ * @param host - Network interface to bind and advertise.
+ * @returns - Handle carrying the bound base URL and a `close` that resolves once the server has stopped.
+ */
+export async function startSnapshotServer(broker, port = 0, host = LOOPBACK_HOST) {
+    const server = createServer((request, response) => {
+        void handleSnapshotRequest(broker, request, response);
+    });
+    await listenServer(server, port, host);
+    const address = server.address();
+    return {
+        url: `http://${urlHost(address.address)}:${String(address.port)}`,
+        close: () => closeServer(server),
+    };
+}
+async function handleSnapshotRequest(broker, request, response) {
+    try {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (request.method !== "GET" &&
+            !(request.method === "POST" && /^\/snapshot\/messages\/[^/]+\/expire$/u.test(url.pathname))) {
+            throw new Error("GET required");
+        }
+        const body = request.method === "POST" ? await mutateSnapshotPath(broker, url.pathname) : selectSnapshotPath(broker, url);
+        writeJson(response, 200, body, { "cache-control": "no-store" });
+    }
+    catch (error) {
+        writeJson(response, 400, { error: error instanceof Error ? error.message : "Snapshot failed" }, {
+            "cache-control": "no-store",
+        });
+    }
+}
+function selectSnapshotPath(broker, url) {
+    const messageBody = /^\/snapshot\/messages\/([^/]+)\/body$/u.exec(url.pathname);
+    const messageId = messageBody?.[1];
+    if (messageId)
+        return broker.readMessageBody(decodeURIComponent(messageId));
+    // Health answers a liveness deadline, so it must not pay for a projection it does not read.
+    if (url.pathname === "/snapshot/health")
+        return broker.snapshotHealth();
+    const snapshot = broker.snapshot(url.searchParams.get("workspace") ?? undefined);
+    switch (url.pathname) {
+        case "/snapshot":
+            return snapshot;
+        case "/snapshot/workspaces":
+            return { workspaces: snapshot.workspaces };
+        case "/snapshot/agents":
+            return { agents: snapshot.agents, connections: snapshot.connections };
+        case "/snapshot/deliveries":
+            return { deliveries: snapshot.deliveries };
+        case "/snapshot/diagnostics":
+            return snapshot.diagnostics;
+        default:
+            throw new Error("Unknown snapshot endpoint");
+    }
+}
+function mutateSnapshotPath(broker, pathname) {
+    const expire = /^\/snapshot\/messages\/([^/]+)\/expire$/u.exec(pathname);
+    const messageId = expire?.[1];
+    if (!messageId)
+        throw new Error("Unknown snapshot endpoint");
+    broker.expireMessage(decodeURIComponent(messageId), "operator");
+    return broker.status(decodeURIComponent(messageId));
+}
+/**
+ * Return a non-secret stable marker for restart detection without exposing process-binding tokens.
+ * @param epoch - Broker generation used to fence stale sessions.
+ * @returns - Non-secret epoch fingerprint suitable for public diagnostics.
+ */
+export function publicEpoch(epoch) {
+    return createHash("sha256").update(epoch).digest("hex").slice(0, 16);
+}

package/dist/src/configuration-defaults.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Names the loopback interface every local HTTP server binds and advertises by default.
+ *
+ * The broker has no authentication and no `Origin` or `Host` validation; the loopback bind is what
+ * keeps it unreachable from the network, so `PagerConfig.bindHost` is validated to equal
+ * this and nothing else (`configuration.ts`); every bind site reads it (or this constant) rather
+ * than restating the address.
+ */
+export declare const LOOPBACK_HOST = "127.0.0.1";
+/** Names every user-configurable Pager runtime setting. */
+export type PagerConfig = {
+    /** Names the absolute SQLite database path retained across service restarts. */
+    databasePath: string;
+    /** Names the network interface used by local HTTP servers; rejected unless loopback. */
+    bindHost: string;
+    /** Selects the MCP TCP port in the inclusive range 0..65535. */
+    mcpPort: number;
+    /** Selects the snapshot TCP port in the inclusive range 0..65535. */
+    snapshotPort: number;
+    /** Selects the operator update-stream TCP port in the inclusive range 0..65535. */
+    operatorPort: number;
+    /** Sets the lifetime in milliseconds of an unacknowledged message claim. */
+    visibilityTimeoutMs: number;
+    /** Sets the delay in milliseconds before the first redelivery wake for an unclaimed inbox. */
+    redeliveryBaseDelayMs: number;
+    /** Sets how long in milliseconds an inbox is retried before its messages are dead-lettered. */
+    redeliveryGiveUpMs: number;
+    /** Sets the lifetime in milliseconds of an unattached launch reservation. */
+    reservationTtlMs: number;
+    /** Sets the lifetime in milliseconds of an attached agent lease. */
+    leaseTtlMs: number;
+    /** Sets the maximum non-negative sends allowed for one sender-recipient pair per window. */
+    perPairRateLimit: number;
+    /** Sets the pair-rate measurement window in milliseconds. */
+    perPairRateWindowMs: number;
+    /** Sets the maximum non-negative queued or claimed messages retained for one recipient. */
+    maxInboxMessages: number;
+    /** Sets the maximum non-negative wakes delivered to one agent per window. */
+    wakeBudget: number;
+    /** Sets the wake-budget measurement window in milliseconds. */
+    wakeBudgetWindowMs: number;
+    /** Sets the adapter heartbeat interval in milliseconds. */
+    adapterHeartbeatIntervalMs: number;
+    /** Bounds waiting for an on-demand service to publish endpoints, in milliseconds. */
+    serviceStartupTimeoutMs: number;
+};
+/**
+ * Supplies the default values used for configurable runtime settings.
+ *
+ * `databasePath` is never effective: `loadPagerConfiguration` derives the real default from
+ * the resolved store directory at load time, since it depends on a path not known here.
+ */
+export declare const PAGER_DEFAULTS: Readonly<PagerConfig>;
+/** Names the configured adapter heartbeat cadence published to launched implementation processes. */
+export declare const ADAPTER_HEARTBEAT_INTERVAL_ENVIRONMENT = "PAGER_ADAPTER_HEARTBEAT_INTERVAL_MS";
+/**
+ * Resolve the heartbeat cadence one implementation process should renew its attachment on.
+ *
+ * A heartbeat renews the attachment lease, so a value that is not a positive integer is ignored
+ * rather than allowed to stall renewal.
+ * @param processEnv - Environment the launching process published to this one.
+ * @returns - Milliseconds between attachment heartbeats.
+ */
+export declare function adapterHeartbeatIntervalMs(processEnv: Readonly<NodeJS.ProcessEnv>): number;

package/dist/src/configuration-defaults.js

@@ -0,0 +1,48 @@
+/**
+ * Names the loopback interface every local HTTP server binds and advertises by default.
+ *
+ * The broker has no authentication and no `Origin` or `Host` validation; the loopback bind is what
+ * keeps it unreachable from the network, so `PagerConfig.bindHost` is validated to equal
+ * this and nothing else (`configuration.ts`); every bind site reads it (or this constant) rather
+ * than restating the address.
+ */
+export const LOOPBACK_HOST = "127.0.0.1";
+/**
+ * Supplies the default values used for configurable runtime settings.
+ *
+ * `databasePath` is never effective: `loadPagerConfiguration` derives the real default from
+ * the resolved store directory at load time, since it depends on a path not known here.
+ */
+export const PAGER_DEFAULTS = Object.freeze({
+    databasePath: "",
+    bindHost: LOOPBACK_HOST,
+    mcpPort: 43112,
+    snapshotPort: 43113,
+    operatorPort: 43114,
+    visibilityTimeoutMs: 300_000,
+    redeliveryBaseDelayMs: 60_000,
+    redeliveryGiveUpMs: 86_400_000,
+    reservationTtlMs: 300_000,
+    leaseTtlMs: 120_000,
+    perPairRateLimit: 60,
+    perPairRateWindowMs: 60_000,
+    maxInboxMessages: 1_000,
+    wakeBudget: 60,
+    wakeBudgetWindowMs: 60_000,
+    adapterHeartbeatIntervalMs: 10_000,
+    serviceStartupTimeoutMs: 10_000,
+});
+/** Names the configured adapter heartbeat cadence published to launched implementation processes. */
+export const ADAPTER_HEARTBEAT_INTERVAL_ENVIRONMENT = "PAGER_ADAPTER_HEARTBEAT_INTERVAL_MS";
+/**
+ * Resolve the heartbeat cadence one implementation process should renew its attachment on.
+ *
+ * A heartbeat renews the attachment lease, so a value that is not a positive integer is ignored
+ * rather than allowed to stall renewal.
+ * @param processEnv - Environment the launching process published to this one.
+ * @returns - Milliseconds between attachment heartbeats.
+ */
+export function adapterHeartbeatIntervalMs(processEnv) {
+    const configured = Number(processEnv[ADAPTER_HEARTBEAT_INTERVAL_ENVIRONMENT]);
+    return Number.isSafeInteger(configured) && configured > 0 ? configured : PAGER_DEFAULTS.adapterHeartbeatIntervalMs;
+}

package/dist/src/configuration.d.ts

@@ -0,0 +1,76 @@
+import { type PagerConfig } from "./configuration-defaults.js";
+export { PAGER_DEFAULTS, type PagerConfig } from "./configuration-defaults.js";
+/** Reports a rejected configuration boundary value without losing its source location. */
+export declare class ConfigurationError extends Error {
+    /** Identifies configuration validation failures to callers. */
+    readonly code = "configuration_invalid";
+    /** Names the source file containing the rejected value. */
+    readonly filePath: string;
+    /** Names the rejected key, or `$` for document-level failures. */
+    readonly key: string;
+    /**
+     * Construct a configuration failure.
+     * @param filePath - Configuration source containing the rejected value.
+     * @param key - Rejected key, or `$` when the whole document is invalid.
+     * @param reason - Caller-visible reason the value cannot be used.
+     */
+    constructor(filePath: string, key: string, reason: string);
+}
+/** Describes resolved configuration and whether a user file supplied values. */
+export type LoadedConfiguration = {
+    /** Carries every validated runtime setting after precedence resolution. */
+    config: PagerConfig;
+    /** Names the user file that supplied values, or null when discovery found none. */
+    filePath: string | null;
+    /** Names the resolved user store directory, as `resolvePagerStoreDirectory` returns it. */
+    storeDirectory: string;
+};
+/** Supplies explicit configuration layers and IO seams to the loader. */
+export type ConfigurationLoadOptions = {
+    /** Supplies environment variables, which take precedence over the file. */
+    environment?: NodeJS.ProcessEnv;
+    /** Supplies the operating system identifier used for path discovery. */
+    platform?: NodeJS.Platform;
+    /** Supplies the home directory without reading process-global user state. */
+    homeDirectory: string;
+    /** Reads a discovered file as UTF-8 text for boundary validation. */
+    readFile?: (path: string) => string;
+    /** Reports whether a discovered file exists. */
+    fileExists?: (path: string) => boolean;
+};
+/**
+ * Resolve the platform-specific user store directory.
+ * @param platform - Operating-system identifier being resolved.
+ * @param homeDirectory - Absolute user home directory used as the discovery root.
+ * @returns - Absolute directory containing user configuration and durable state.
+ */
+export declare function resolvePagerStoreDirectory(platform: NodeJS.Platform, homeDirectory: string): string;
+/** Precedence layers for {@link resolveConfigurationSetting}, ordered from lowest to highest precedence. */
+export type ConfigurationSettingPrecedence<T> = {
+    /** Repository-owned fallback value. */
+    defaultValue: T;
+    /** Validated user-file value, when supplied. */
+    fileValue?: T | undefined;
+    /** Parsed environment value, when supplied. */
+    environmentValue?: T | undefined;
+};
+/**
+ * Resolve one setting according to environment, file, then default precedence.
+ * @param precedence - The setting's three sources, named by precedence rather than argument order.
+ * @returns - Highest-precedence supplied value.
+ */
+export declare function resolveConfigurationSetting<T>({ environmentValue, fileValue, defaultValue, }: ConfigurationSettingPrecedence<T>): T;
+/**
+ * Load and validate user configuration without creating durable state.
+ * @param options - Explicit path inputs, precedence layers, and file IO seams.
+ * @returns - Fully resolved settings, source path, and shared store directory.
+ */
+export declare function loadPagerConfiguration(options: ConfigurationLoadOptions): LoadedConfiguration;
+/**
+ * Create the directory that owns the resolved database before SQLite opens it.
+ * @param loaded - Resolved configuration whose database parent must exist.
+ * @param createDirectory - Filesystem seam that recursively creates the database parent.
+ */
+export declare function initializePagerStore(loaded: LoadedConfiguration, createDirectory?: (path: string, options: {
+    recursive: true;
+}) => unknown): void;

package/dist/src/configuration.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { PAGER_DEFAULTS } from "./configuration-defaults.js";
+export { PAGER_DEFAULTS } from "./configuration-defaults.js";
+/** Reports a rejected configuration boundary value without losing its source location. */
+export class ConfigurationError extends Error {
+    /** Identifies configuration validation failures to callers. */
+    code = "configuration_invalid";
+    /** Names the source file containing the rejected value. */
+    filePath;
+    /** Names the rejected key, or `$` for document-level failures. */
+    key;
+    /**
+     * Construct a configuration failure.
+     * @param filePath - Configuration source containing the rejected value.
+     * @param key - Rejected key, or `$` when the whole document is invalid.
+     * @param reason - Caller-visible reason the value cannot be used.
+     */
+    constructor(filePath, key, reason) {
+        super(`Invalid Pager configuration at ${filePath}, key ${key}: ${reason}`);
+        this.name = "ConfigurationError";
+        this.filePath = filePath;
+        this.key = key;
+    }
+}
+const configKeys = Object.keys(PAGER_DEFAULTS);
+const portKeys = new Set(["mcpPort", "snapshotPort", "operatorPort"]);
+const pathKeys = new Set(["databasePath"]);
+const stringKeys = new Set(["databasePath", "bindHost"]);
+/**
+ * Resolve the platform-specific user store directory.
+ * @param platform - Operating-system identifier being resolved.
+ * @param homeDirectory - Absolute user home directory used as the discovery root.
+ * @returns - Absolute directory containing user configuration and durable state.
+ */
+export function resolvePagerStoreDirectory(platform, homeDirectory) {
+    if (platform !== "darwin")
+        throw new Error(`Pager supports macOS only; got platform ${platform}`);
+    if (!isAbsolute(homeDirectory))
+        throw new Error(`Pager home directory must be absolute: ${homeDirectory}`);
+    return join(homeDirectory, "Library", "Application Support", "pager");
+}
+/**
+ * Resolve one setting according to environment, file, then default precedence.
+ * @param precedence - The setting's three sources, named by precedence rather than argument order.
+ * @returns - Highest-precedence supplied value.
+ */
+export function resolveConfigurationSetting({ environmentValue, fileValue, defaultValue, }) {
+    if (environmentValue !== undefined)
+        return environmentValue;
+    if (fileValue !== undefined)
+        return fileValue;
+    return defaultValue;
+}
+/**
+ * Load and validate user configuration without creating durable state.
+ * @param options - Explicit path inputs, precedence layers, and file IO seams.
+ * @returns - Fully resolved settings, source path, and shared store directory.
+ */
+export function loadPagerConfiguration(options) {
+    const environment = options.environment ?? {};
+    const platform = options.platform ?? process.platform;
+    const storeDirectory = resolvePagerStoreDirectory(platform, options.homeDirectory);
+    const discoveredPath = join(storeDirectory, "config.json");
+    const configPath = environment.PAGER_CONFIG ?? discoveredPath;
+    if (!isAbsolute(configPath))
+        throw new ConfigurationError(configPath, "configPath", "path must be absolute");
+    const exists = options.fileExists ?? existsSync;
+    const read = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+    const filePresent = exists(configPath);
+    const file = filePresent ? parseConfigurationFile(configPath, read(configPath)) : {};
+    const defaults = { ...PAGER_DEFAULTS, databasePath: join(storeDirectory, "broker.sqlite") };
+    const environmentLayer = parseEnvironment(configPath, environment);
+    const config = Object.fromEntries(configKeys.map((key) => [
+        key,
+        resolveConfigurationSetting({
+            environmentValue: environmentLayer[key],
+            fileValue: file[key],
+            defaultValue: defaults[key],
+        }),
+    ]));
+    validateResolvedConfiguration(configPath, config);
+    return { config, filePath: filePresent ? configPath : null, storeDirectory };
+}
+/**
+ * Create the directory that owns the resolved database before SQLite opens it.
+ * @param loaded - Resolved configuration whose database parent must exist.
+ * @param createDirectory - Filesystem seam that recursively creates the database parent.
+ */
+export function initializePagerStore(loaded, createDirectory = mkdirSync) {
+    try {
+        createDirectory(resolve(loaded.config.databasePath, ".."), { recursive: true });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ConfigurationError(loaded.filePath ?? join(loaded.storeDirectory, "config.json"), "databasePath", reason);
+    }
+}
+function parseConfigurationFile(path, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigurationError(path, "$", error instanceof Error ? error.message : "malformed JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new ConfigurationError(path, "$", "expected an object");
+    const record = parsed;
+    for (const key of Object.keys(record)) {
+        if (!configKeys.includes(key))
+            throw new ConfigurationError(path, key, "unknown key");
+    }
+    for (const key of configKeys) {
+        const value = record[key];
+        if (value !== undefined)
+            validateValue(path, key, value);
+    }
+    return record;
+}
+function parseEnvironment(path, environment) {
+    const result = {};
+    for (const key of configKeys) {
+        const environmentKey = `PAGER_${key.replace(/[A-Z]/gu, (letter) => `_${letter}`).toUpperCase()}`;
+        const raw = environment[environmentKey];
+        if (raw === undefined)
+            continue;
+        const value = stringKeys.has(key) ? raw : Number(raw);
+        validateValue(path, key, value);
+        Object.assign(result, { [key]: value });
+    }
+    if (environment.PAGER_DB !== undefined) {
+        validateValue(path, "databasePath", environment.PAGER_DB);
+        result.databasePath = environment.PAGER_DB;
+    }
+    return result;
+}
+function validateResolvedConfiguration(path, config) {
+    for (const key of configKeys)
+        validateValue(path, key, config[key]);
+}
+function validateValue(path, key, value) {
+    if (stringKeys.has(key)) {
+        if (typeof value !== "string" || value.length === 0)
+            throw new ConfigurationError(path, key, "expected a non-empty string");
+        if (pathKeys.has(key) && !isAbsolute(value))
+            throw new ConfigurationError(path, key, "path must be absolute");
+        if (key === "bindHost" && value !== PAGER_DEFAULTS.bindHost)
+            throw new ConfigurationError(path, key, "v1 services must bind to loopback 127.0.0.1");
+        return;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0)
+        throw new ConfigurationError(path, key, "expected a non-negative integer");
+    if (portKeys.has(key) && value > 65_535)
+        throw new ConfigurationError(path, key, "port must be in range 0..65535");
+}

package/dist/src/implementations/claude/environment.d.ts

@@ -0,0 +1,8 @@
+/** Names the broker endpoint supplied to launched Claude sessions. */
+export declare const CLAUDE_BROKER_URL_ENVIRONMENT = "PAGER_BROKER_URL";
+/** Names the single-use messaging attachment consumed by the stdio gateway. */
+export declare const CLAUDE_MESSAGING_RESERVATION_ENVIRONMENT = "PAGER_ATTACH_RESERVATION";
+/** Names the inbox socket Claude Code exports to every process it starts for a session. */
+export declare const CLAUDE_INBOX_SOCKET_ENVIRONMENT = "CLAUDE_CODE_MESSAGING_SOCKET";
+/** Names the per-session token Claude Code exports beside the inbox socket. */
+export declare const CLAUDE_INBOX_TOKEN_ENVIRONMENT = "CLAUDE_CODE_MESSAGING_TOKEN";

package/dist/src/implementations/claude/environment.js

@@ -0,0 +1,9 @@
+import { PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT } from "../../launch/environment.js";
+/** Names the broker endpoint supplied to launched Claude sessions. */
+export const CLAUDE_BROKER_URL_ENVIRONMENT = PAGER_BROKER_URL_ENVIRONMENT;
+/** Names the single-use messaging attachment consumed by the stdio gateway. */
+export const CLAUDE_MESSAGING_RESERVATION_ENVIRONMENT = PAGER_ATTACH_RESERVATION_ENVIRONMENT;
+/** Names the inbox socket Claude Code exports to every process it starts for a session. */
+export const CLAUDE_INBOX_SOCKET_ENVIRONMENT = "CLAUDE_CODE_MESSAGING_SOCKET";
+/** Names the per-session token Claude Code exports beside the inbox socket. */
+export const CLAUDE_INBOX_TOKEN_ENVIRONMENT = "CLAUDE_CODE_MESSAGING_TOKEN";

package/dist/src/implementations/claude/gateway-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/implementations/claude/gateway-cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { readRuntimeEnvironment } from "../../launch/environment.js";
+import { ensureBrokerService } from "../../launch/on-demand.js";
+import { assertSupportedBunRuntime } from "../../launch/runtime.js";
+import { ClaudeMcpGateway, createClaudeDiscoveryServer, createClaudeGatewayServer, createClaudeGatewayUpstream, rejoinKeyAfterRefusedAttach, retryBrokerUrlAfterUnreachableLaunch, } from "./gateway.js";
+import { registerClaudeAgent, registerClaudeConversation, resolveClaudeGatewayIdentity, } from "./gateway-identity.js";
+import { unattachedCause } from "./instructions.js";
+import { claudeContinuedSessionKey } from "./session-continuation.js";
+import { claudeSessionKey } from "./session-identity.js";
+import { claudeDeliveryAddress } from "./socket-delivery.js";
+try {
+    assertSupportedBunRuntime();
+    const workspacePath = process.cwd();
+    const identityPorts = {
+        environment: process.env,
+        workspacePath,
+        sessionKey: () => claudeSessionKey(process.env),
+        continuedSessionKey: () => claudeContinuedSessionKey(process.env, workspacePath),
+        brokerUrl: async () => (await ensureBrokerService(readRuntimeEnvironment())).mcpUrl,
+        register: (brokerUrl, request) => registerClaudeAgent(fetch, brokerUrl, request),
+    };
+    const resolution = await resolveClaudeGatewayIdentity(identityPorts);
+    if (resolution.attached) {
+        let gateway;
+        try {
+            gateway = await startAttachedGateway(resolution);
+        }
+        catch (error) {
+            // Claude Code restarts a stdio server with the environment of the original launch, whose
+            // reservation the first process already spent. The conversation key is what still identifies
+            // this session, so it registers by key and rejoins the identity the launch bound the key to.
+            const sessionKey = rejoinKeyAfterRefusedAttach(resolution, error);
+            if (sessionKey !== undefined) {
+                try {
+                    const registered = await registerClaudeConversation(identityPorts, resolution.brokerUrl, sessionKey);
+                    gateway = await startAttachedGateway({
+                        ...resolution,
+                        reservation: registered.reservation,
+                        reservationOrigin: "registration",
+                    });
+                }
+                catch (retryError) {
+                    await serveUnattached({
+                        attached: false,
+                        reason: "registration_failed",
+                        brokerUrl: resolution.brokerUrl,
+                        detail: retryError instanceof Error ? retryError.message : String(retryError),
+                    });
+                }
+            }
+            else {
+                // A launch broker that is unreachable is brought back and the same reservation retried
+                // once, since its database persists across a restart.
+                const runtime = readRuntimeEnvironment();
+                const brokerUrl = await retryBrokerUrlAfterUnreachableLaunch(resolution, error, {
+                    configuredBrokerUrl: `http://${runtime.config.bindHost}:${String(runtime.config.mcpPort)}/mcp`,
+                    ensureBrokerService: () => ensureBrokerService(runtime),
+                });
+                if (brokerUrl !== undefined) {
+                    try {
+                        gateway = await startAttachedGateway({ ...resolution, brokerUrl });
+                    }
+                    catch {
+                        throw error;
+                    }
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        if (gateway) {
+            const attached = gateway;
+            const shutdown = () => {
+                void attached.close().finally(() => process.exit(0));
+            };
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        }
+    }
+    else {
+        await serveUnattached(resolution);
+    }
+}
+catch (error) {
+    process.stderr.write(`pager Claude gateway failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}
+/**
+ * Serve Claude a tool-less server carrying the cause, and say the same on stderr.
+ * @param unattached - Cause this process resolved.
+ */
+async function serveUnattached(unattached) {
+    process.stderr.write(`pager Claude gateway is serving no tools: ${unattachedCause(unattached)}\n`);
+    const discoveryServer = createClaudeDiscoveryServer(unattached);
+    const shutdown = () => {
+        void discoveryServer.close().finally(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    await discoveryServer.connect(new StdioServerTransport());
+}
+/**
+ * Attach to the broker with the given credentials and begin serving Claude over stdio.
+ * @param identity - Endpoint, reservation, and conversation key to attach with.
+ * @returns - Running gateway; rejects, with the upstream released, when the attach is refused.
+ */
+async function startAttachedGateway(identity) {
+    const deliveryAddress = claudeDeliveryAddress(process.env);
+    const upstream = createClaudeGatewayUpstream(identity.brokerUrl, identity.reservation, {
+        ...(identity.sessionKey ? { sessionKey: identity.sessionKey } : {}),
+        ...(deliveryAddress.known ? { deliveryAddress: deliveryAddress.value } : {}),
+        scheduler: {
+            schedule: (delayMs, task) => {
+                const timeout = setTimeout(() => {
+                    void task().catch(() => undefined);
+                }, delayMs);
+                timeout.unref();
+                return () => {
+                    clearTimeout(timeout);
+                };
+            },
+        },
+    });
+    const server = createClaudeGatewayServer(upstream, identity.brokerUrl);
+    const gateway = new ClaudeMcpGateway(upstream, server, new StdioServerTransport());
+    try {
+        await gateway.start();
+    }
+    catch (error) {
+        await gateway.close().catch(() => undefined);
+        throw error;
+    }
+    return gateway;
+}