@pharaoh-so/mcp 0.3.22 → 0.3.23

package/dist/auth.d.ts

@@ -28,17 +28,65 @@ export interface TokenResponse {
     provisional?: boolean;
     install_url?: string;
 }
+/**
+ * Result of a single poll against /device/token.
+ *
+ * This type is the contract between the state-machine gateway (gateway.ts),
+ * the blocking interactive poller (pollForToken), and the test harness. It
+ * collapses HTTP details into the four lifecycle outcomes callers actually
+ * need to branch on, plus a network_error bucket so callers can distinguish
+ * "server said no" from "couldn't reach server."
+ */
+export type PollResult = {
+    status: "pending";
+    slowDown?: boolean;
+} | {
+    status: "authorized";
+    token: TokenResponse;
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+    error: string;
+} | {
+    status: "network_error";
+    error: string;
+};
 /**
  * Request a device code from the Pharaoh server (RFC 8628 §3.1).
  * Returns the device code, user code, and verification URIs.
  */
 export declare function requestDeviceCode(baseUrl: string): Promise<DeviceCodeResponse>;
+/**
+ * Perform one POST to /device/token. No loop, no sleep — maps HTTP responses
+ * into a PollResult discriminated union.
+ *
+ * Called in two shapes:
+ * - pollForToken() (TTY path): loops with interval+jitter until terminal state.
+ * - gateway.handleToolCall() (proxy path): called once per tool call, gated
+ *   by a last_poll_at check against the server's interval.
+ *
+ * Note: slow_down is mapped to "pending" — the caller's pacing logic is what
+ * responds to it. pollForToken bumps its local interval; gateway relies on the
+ * server-specified interval it already tracks. This keeps pollOnce stateless.
+ */
+export declare function pollOnce(baseUrl: string, deviceCode: string): Promise<PollResult>;
 /**
  * Poll for device authorization completion (RFC 8628 §3.5).
  * Blocks until the user authorizes, the code expires, or an error occurs.
  * Adds 1s jitter to the server-specified interval to avoid thundering herd.
  */
 export declare function pollForToken(baseUrl: string, deviceCode: string, interval: number): Promise<TokenResponse>;
+/**
+ * Open a URL in the user's default browser.
+ * Uses platform-specific commands; fails silently if unavailable.
+ *
+ * Exported for gateway.ts — the state machine fires this once per device code
+ * to pre-fill the activation URL in the user's browser. Silent-on-failure is
+ * critical for headless environments: a missing `open`/`xdg-open` binary must
+ * not crash the proxy.
+ */
+export declare function openBrowser(url: string): void;
 /**
  * Print the device activation prompt to stderr.
  * Shows the user code and verification URI in a visible box,

package/dist/auth.js

@@ -19,48 +19,94 @@ export async function requestDeviceCode(baseUrl) {
     }
     return (await res.json());
 }
+/**
+ * Perform one POST to /device/token. No loop, no sleep — maps HTTP responses
+ * into a PollResult discriminated union.
+ *
+ * Called in two shapes:
+ * - pollForToken() (TTY path): loops with interval+jitter until terminal state.
+ * - gateway.handleToolCall() (proxy path): called once per tool call, gated
+ *   by a last_poll_at check against the server's interval.
+ *
+ * Note: slow_down is mapped to "pending" — the caller's pacing logic is what
+ * responds to it. pollForToken bumps its local interval; gateway relies on the
+ * server-specified interval it already tracks. This keeps pollOnce stateless.
+ */
+export async function pollOnce(baseUrl, deviceCode) {
+    const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    let res;
+    try {
+        res = await fetch(`${baseUrl}/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
+        });
+    }
+    catch (err) {
+        return {
+            status: "network_error",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (res.ok) {
+        const token = (await res.json());
+        return { status: "authorized", token };
+    }
+    const body = (await res.json().catch(() => ({ error: "unknown" })));
+    if (body.error === "authorization_pending") {
+        return { status: "pending" };
+    }
+    if (body.error === "slow_down") {
+        return { status: "pending", slowDown: true };
+    }
+    if (body.error === "expired_token") {
+        return { status: "expired" };
+    }
+    if (body.error === "access_denied") {
+        return { status: "denied", error: "Authorization was denied." };
+    }
+    return {
+        status: "denied",
+        error: `Device token error: ${body.error} — ${body.error_description ?? ""}`,
+    };
+}
 /**
  * Poll for device authorization completion (RFC 8628 §3.5).
  * Blocks until the user authorizes, the code expires, or an error occurs.
  * Adds 1s jitter to the server-specified interval to avoid thundering herd.
  */
 export async function pollForToken(baseUrl, deviceCode, interval) {
-    const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    let currentInterval = interval;
     while (true) {
         // Wait interval + 0–1s jitter before each poll
         const jitterMs = Math.random() * 1000;
-        await sleep(interval * 1000 + jitterMs);
-        const res = await fetch(`${baseUrl}/device/token`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
-        });
-        if (res.ok) {
-            return (await res.json());
-        }
-        const body = (await res.json().catch(() => ({ error: "unknown" })));
-        if (body.error === "authorization_pending") {
-            continue;
-        }
-        if (body.error === "slow_down") {
-            // RFC 8628 §3.5: increase interval by 5 seconds
-            interval += 5;
-            continue;
-        }
-        if (body.error === "expired_token") {
+        await sleep(currentInterval * 1000 + jitterMs);
+        const result = await pollOnce(baseUrl, deviceCode);
+        if (result.status === "authorized")
+            return result.token;
+        if (result.status === "expired") {
             throw new Error("Device code expired. Please try again.");
         }
-        if (body.error === "access_denied") {
-            throw new Error("Authorization was denied.");
-        }
-        throw new Error(`Device token error: ${body.error} — ${body.error_description ?? ""}`);
+        if (result.status === "denied")
+            throw new Error(result.error);
+        if (result.status === "network_error")
+            throw new Error(result.error);
+        // result.status === "pending". RFC 8628 §3.5: only bump interval on
+        // slow_down (authorization_pending is the normal polling response).
+        if (result.slowDown)
+            currentInterval += 5;
     }
 }
 /**
  * Open a URL in the user's default browser.
  * Uses platform-specific commands; fails silently if unavailable.
+ *
+ * Exported for gateway.ts — the state machine fires this once per device code
+ * to pre-fill the activation URL in the user's browser. Silent-on-failure is
+ * critical for headless environments: a missing `open`/`xdg-open` binary must
+ * not crash the proxy.
  */
-function openBrowser(url) {
+export function openBrowser(url) {
     if (process.platform === "darwin") {
         execFile("open", [url], () => { });
     }

package/dist/backend.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Backend interface — the abstraction the ProxyServer delegates tool calls to.
+ *
+ * Two concrete implementations:
+ *
+ * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
+ *    turns every invocation into a device-flow state step. Used while the
+ *    proxy is waiting for the user to authorize.
+ *
+ * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
+ *    connected to the remote Pharaoh SSE server. Forwards list/call requests
+ *    verbatim and preserves the ghost-session reconnect fix from proxy.ts.
+ *
+ * ProxyServer swaps between the two by reassigning a reference. The SDK
+ * resolves each tool call's handler at request-arrival time, so in-flight
+ * calls complete against whichever backend started them.
+ */
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { DeviceFlowGateway } from "./gateway.js";
+/** The contract ProxyServer uses to delegate tool handling. */
+export interface Backend {
+    readonly name: "auth-required" | "sse";
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    /** Optional one-time startup (e.g. connect SSE). Idempotent. */
+    start?(): Promise<void>;
+    /** Optional teardown (e.g. close SSE). Idempotent. */
+    stop?(): Promise<void>;
+}
+/**
+ * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
+ * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
+ * tool most agents try. Keeping this at 1 means the swap to the real catalog
+ * fires a clean visible sendToolListChanged delta.
+ *
+ * If you add tools here, sync with src/mcp/tool-registry.ts in the main
+ * package — descriptions should match so agents get consistent behavior
+ * across the pre-auth / authorized transition.
+ */
+export declare const AUTH_REQUIRED_TOOLS: Tool[];
+/**
+ * Pre-auth backend. Every tool call triggers a device-flow state step via the
+ * gateway; returns a structured auth-required response. Once the gateway
+ * reports the user has authorized (handleToolCall returns null), the caller
+ * (ProxyServer) swaps to SseProxyBackend — this backend does NOT swap itself.
+ */
+export declare class AuthRequiredBackend implements Backend {
+    private readonly gateway;
+    readonly name: "auth-required";
+    constructor(gateway: DeviceFlowGateway);
+    listTools(): Promise<Tool[]>;
+    callTool(_name: string, _args: Record<string, unknown>): Promise<CallToolResult>;
+}
+/**
+ * Real SSE-backed backend. Owns an MCP Client + SSEClientTransport and a
+ * reconnect loop. Forwards listTools/callTool to the remote server.
+ *
+ * Reconnect semantics (preserved verbatim from the old startProxy):
+ *   EventSource's built-in auto-reconnect creates ghost sessions on the
+ *   server (new auth, new session ID per 3s reconnect). On any non-fatal
+ *   error we explicitly close() the transport to kill EventSource, then
+ *   let this loop create a fresh transport for the next attempt. 5 retries
+ *   (2s, 4s, 8s, 16s, 32s) before giving up.
+ */
+declare class SseProxyBackend implements Backend {
+    private readonly sseUrl;
+    private readonly token;
+    readonly name: "sse";
+    private client;
+    private transport;
+    private stopped;
+    private reconnectPromise;
+    constructor(sseUrl: string, token: string);
+    start(): Promise<void>;
+    /**
+     * Expose the long-running reconnect loop so a supervisor can await it.
+     * Session C uses this to bubble TokenExpiredError / TenantSuspendedError
+     * up to the same handler that used to wrap `startProxy`.
+     */
+    waitForExit(): Promise<void>;
+    private connectOnce;
+    /** Wait for the current transport to close, then decide what to do. */
+    private waitForClose;
+    private reconnectAfter;
+    private runReconnectLoop;
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    stop(): Promise<void>;
+}
+/**
+ * Public factory — ProxyServer / Session C build SSE backends via this.
+ * Keeps the SseProxyBackend class private so callers can't accidentally
+ * depend on its internal reconnect state.
+ */
+export declare function createSseBackend(sseUrl: string, token: string): SseProxyBackend;
+export {};

package/dist/backend.js

@@ -0,0 +1,250 @@
+/**
+ * Backend interface — the abstraction the ProxyServer delegates tool calls to.
+ *
+ * Two concrete implementations:
+ *
+ * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
+ *    turns every invocation into a device-flow state step. Used while the
+ *    proxy is waiting for the user to authorize.
+ *
+ * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
+ *    connected to the remote Pharaoh SSE server. Forwards list/call requests
+ *    verbatim and preserves the ghost-session reconnect fix from proxy.ts.
+ *
+ * ProxyServer swaps between the two by reassigning a reference. The SDK
+ * resolves each tool call's handler at request-arrival time, so in-flight
+ * calls complete against whichever backend started them.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { getPackageVersion } from "./version.js";
+/**
+ * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
+ * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
+ * tool most agents try. Keeping this at 1 means the swap to the real catalog
+ * fires a clean visible sendToolListChanged delta.
+ *
+ * If you add tools here, sync with src/mcp/tool-registry.ts in the main
+ * package — descriptions should match so agents get consistent behavior
+ * across the pre-auth / authorized transition.
+ */
+export const AUTH_REQUIRED_TOOLS = [
+    {
+        name: "get_codebase_map",
+        description: "Pharaoh — call this FIRST to understand the codebase structure. " +
+            "Requires authentication; calling this tool will surface the auth URL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Optional repo slug (owner/name) to map.",
+                },
+            },
+        },
+    },
+];
+/**
+ * Pre-auth backend. Every tool call triggers a device-flow state step via the
+ * gateway; returns a structured auth-required response. Once the gateway
+ * reports the user has authorized (handleToolCall returns null), the caller
+ * (ProxyServer) swaps to SseProxyBackend — this backend does NOT swap itself.
+ */
+export class AuthRequiredBackend {
+    gateway;
+    name = "auth-required";
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    async listTools() {
+        return AUTH_REQUIRED_TOOLS;
+    }
+    async callTool(_name, _args) {
+        const response = await this.gateway.handleToolCall();
+        if (response === null) {
+            // Credentials just became valid. Return a success result so the
+            // agent's current tool call doesn't error out. ProxyServer checks
+            // gateway.hasValidCredentials() after each call and swaps backends.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Pharaoh: authenticated. Call this tool again to get the codebase map.",
+                    },
+                ],
+                isError: false,
+            };
+        }
+        // The gateway response shape is CallToolResult-compatible (content,
+        // isError, _meta) — the MCP SDK accepts it verbatim.
+        return response;
+    }
+}
+/** Backoff schedule for reconnect attempts (milliseconds). */
+const BACKOFF_MS = [2000, 4000, 8000, 16000, 32000];
+/**
+ * Build the SSEClientTransport with Bearer token auth. Injects the
+ * Authorization header into both the SSE connection (via custom fetch) and
+ * POST requests (via requestInit).
+ */
+function createSSETransport(sseUrl, token) {
+    const authHeader = `Bearer ${token}`;
+    return new SSEClientTransport(new URL(sseUrl), {
+        eventSourceInit: {
+            fetch: (url, init) => {
+                const h = new Headers(init.headers);
+                h.set("Authorization", authHeader);
+                return fetch(url, { ...init, headers: h });
+            },
+        },
+        requestInit: {
+            headers: { Authorization: authHeader },
+        },
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Real SSE-backed backend. Owns an MCP Client + SSEClientTransport and a
+ * reconnect loop. Forwards listTools/callTool to the remote server.
+ *
+ * Reconnect semantics (preserved verbatim from the old startProxy):
+ *   EventSource's built-in auto-reconnect creates ghost sessions on the
+ *   server (new auth, new session ID per 3s reconnect). On any non-fatal
+ *   error we explicitly close() the transport to kill EventSource, then
+ *   let this loop create a fresh transport for the next attempt. 5 retries
+ *   (2s, 4s, 8s, 16s, 32s) before giving up.
+ */
+class SseProxyBackend {
+    sseUrl;
+    token;
+    name = "sse";
+    client = null;
+    transport = null;
+    stopped = false;
+    reconnectPromise = null;
+    constructor(sseUrl, token) {
+        this.sseUrl = sseUrl;
+        this.token = token;
+    }
+    async start() {
+        if (this.client)
+            return; // idempotent
+        await this.connectOnce();
+        // Keep the reconnect loop alive in the background. It resolves when
+        // the SSE stream closes cleanly; on typed errors (401/403) it throws.
+        this.reconnectPromise = this.runReconnectLoop();
+        // Surface typed errors at the top level so the CLI (or future
+        // supervisor) can act on them.
+        this.reconnectPromise.catch(() => {
+            /* error is retrieved via waitForExit() when needed */
+        });
+    }
+    /**
+     * Expose the long-running reconnect loop so a supervisor can await it.
+     * Session C uses this to bubble TokenExpiredError / TenantSuspendedError
+     * up to the same handler that used to wrap `startProxy`.
+     */
+    waitForExit() {
+        return this.reconnectPromise ?? Promise.resolve();
+    }
+    async connectOnce() {
+        this.transport = createSSETransport(this.sseUrl, this.token);
+        this.client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: {} });
+        await this.client.connect(this.transport);
+    }
+    /** Wait for the current transport to close, then decide what to do. */
+    waitForClose() {
+        return new Promise((resolve, reject) => {
+            if (!this.transport) {
+                resolve();
+                return;
+            }
+            const sse = this.transport;
+            sse.onclose = () => resolve();
+            sse.onerror = (err) => {
+                try {
+                    classifySSEError(err);
+                }
+                catch (typed) {
+                    reject(typed);
+                    return;
+                }
+                // Non-fatal — explicitly close the transport to kill
+                // EventSource's built-in auto-reconnect. Without this,
+                // EventSource reconnects every ~3s, creating ghost sessions
+                // on the server (100+ auth successes, zero tool calls
+                // completing). close() fires onclose which resolves this
+                // promise, handing control back to the backoff loop.
+                sse.close().catch(() => { });
+            };
+        });
+    }
+    async reconnectAfter(attempt) {
+        const delay = BACKOFF_MS[attempt - 1];
+        process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${attempt}/${BACKOFF_MS.length})...\n`);
+        await sleep(delay);
+        await this.connectOnce();
+        process.stderr.write("Pharaoh: reconnected\n");
+    }
+    async runReconnectLoop() {
+        process.stderr.write("Pharaoh: connected\n");
+        let attempt = 0;
+        while (!this.stopped) {
+            try {
+                await this.waitForClose();
+                attempt++;
+                if (attempt > BACKOFF_MS.length) {
+                    process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");
+                    throw new Error("SSE connection failed after maximum retries");
+                }
+                await this.reconnectAfter(attempt);
+                attempt = 0;
+            }
+            catch (err) {
+                if (err instanceof TokenExpiredError || err instanceof TenantSuspendedError) {
+                    throw err;
+                }
+                attempt++;
+                if (attempt > BACKOFF_MS.length) {
+                    throw err instanceof Error
+                        ? err
+                        : new Error("SSE connection failed after maximum retries");
+                }
+            }
+        }
+    }
+    async listTools() {
+        if (!this.client)
+            throw new Error("SseProxyBackend.listTools() before start()");
+        const res = await this.client.listTools();
+        return res.tools;
+    }
+    async callTool(name, args) {
+        if (!this.client)
+            throw new Error("SseProxyBackend.callTool() before start()");
+        const res = await this.client.callTool({ name, arguments: args });
+        return res;
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.transport) {
+            await this.transport.close().catch(() => { });
+            this.transport = null;
+        }
+        if (this.client) {
+            await this.client.close().catch(() => { });
+            this.client = null;
+        }
+    }
+}
+/**
+ * Public factory — ProxyServer / Session C build SSE backends via this.
+ * Keeps the SseProxyBackend class private so callers can't accidentally
+ * depend on its internal reconnect state.
+ */
+export function createSseBackend(sseUrl, token) {
+    return new SseProxyBackend(sseUrl, token);
+}

package/dist/gateway.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure-logic device-flow state machine for the auth-required proxy mode.
+ *
+ * When Claude Code spawns the proxy without valid credentials, we can't just
+ * exit — that would force the user to restart their agent every time. Instead,
+ * the proxy stays alive, advertises a single MCP tool, and turns every tool
+ * call into a device-flow lifecycle step: request a code, surface the URL,
+ * poll once per tool call (rate-limited), and swap to the SSE backend once
+ * the user authorizes.
+ *
+ * This module owns the state. It has no MCP imports and no knowledge of the
+ * stdio transport — those live in backend.ts and proxy-server.ts. The only
+ * side effects are (a) POSTing to the Pharaoh /device and /device/token
+ * endpoints via auth.ts, (b) opening a browser once per cycle, and (c)
+ * writing credentials to disk on authorization.
+ */
+import { type Credentials } from "./credentials.js";
+/**
+ * Structured MCP tool response returned when the proxy is waiting for auth.
+ *
+ * Shape rationale: MCP clients that inspect `_meta` can render the auth URL
+ * and user code directly in their UI (Claude Code does this). Clients that
+ * only read `content[0].text` see the same information in human-readable form.
+ * `isError: true` ensures Claude Code surfaces this to the user as an actionable
+ * error rather than silently eating the response.
+ */
+export interface ToolAuthResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+    _meta: {
+        auth_url: string;
+        user_code: string;
+        expires_in_seconds: number;
+    };
+}
+/** Public surface consumed by AuthRequiredBackend. */
+export interface DeviceFlowGateway {
+    /**
+     * Called on every pre-auth tool invocation. Returns null when credentials
+     * just became valid (caller should swap to SSE backend); otherwise returns
+     * the auth-required tool response. Never throws — all error paths collapse
+     * into a ToolAuthResponse the agent can surface.
+     */
+    handleToolCall(): Promise<ToolAuthResponse | null>;
+    /** True when credentials on disk are present and not access-expired. */
+    hasValidCredentials(): boolean;
+    /** The last credentials loaded from disk; null if never loaded successfully. */
+    getCredentials(): Credentials | null;
+}
+/**
+ * Create a fresh state-machine instance. Each proxy spawn gets one gateway;
+ * its lifecycle is the lifecycle of the stdio process.
+ */
+export declare function createGateway(opts: {
+    server: string;
+    credentialsPath?: string;
+    /** Test hook for deterministic expiry/interval math. Do not use in prod. */
+    now?: () => number;
+    /**
+     * Override the browser-open side effect. Tests MUST pass a noop — the real
+     * impl calls `open`/`xdg-open` on the OS, which hits a user's actual browser
+     * even when the URL points at an ephemeral test server that's already closed.
+     * Default: the platform-native open from auth.ts.
+     */
+    openBrowser?: (url: string) => void;
+}): DeviceFlowGateway;

package/dist/gateway.js

@@ -0,0 +1,162 @@
+/**
+ * Pure-logic device-flow state machine for the auth-required proxy mode.
+ *
+ * When Claude Code spawns the proxy without valid credentials, we can't just
+ * exit — that would force the user to restart their agent every time. Instead,
+ * the proxy stays alive, advertises a single MCP tool, and turns every tool
+ * call into a device-flow lifecycle step: request a code, surface the URL,
+ * poll once per tool call (rate-limited), and swap to the SSE backend once
+ * the user authorizes.
+ *
+ * This module owns the state. It has no MCP imports and no knowledge of the
+ * stdio transport — those live in backend.ts and proxy-server.ts. The only
+ * side effects are (a) POSTing to the Pharaoh /device and /device/token
+ * endpoints via auth.ts, (b) opening a browser once per cycle, and (c)
+ * writing credentials to disk on authorization.
+ */
+import { openBrowser, pollOnce, requestDeviceCode, } from "./auth.js";
+import { readCredentials, writeCredentials } from "./credentials.js";
+import { resolveSseUrl, tokenToCredentials } from "./helpers.js";
+function isAccessExpired(creds) {
+    const expiresAt = new Date(creds.expires_at).getTime();
+    if (Number.isNaN(expiresAt))
+        return true;
+    return Date.now() >= expiresAt;
+}
+function buildAuthResponse(device) {
+    const prefix = device.errorMessage ? `${device.errorMessage}\n\n` : "";
+    const text = `${prefix}Pharaoh authentication required.\n\n` +
+        `  1. Visit ${device.verification_uri_complete}\n` +
+        `  2. Enter code: ${device.user_code}\n` +
+        `  3. Re-run this tool after authorizing.`;
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+        _meta: {
+            auth_url: device.verification_uri_complete,
+            user_code: device.user_code,
+            expires_in_seconds: device.expires_in,
+        },
+    };
+}
+/**
+ * Create a fresh state-machine instance. Each proxy spawn gets one gateway;
+ * its lifecycle is the lifecycle of the stdio process.
+ */
+export function createGateway(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const openBrowserImpl = opts.openBrowser ?? openBrowser;
+    let pending = null;
+    let lastCreds = null;
+    /** Start a new device-flow cycle: POST /device, open browser, cache state. */
+    async function startNewCycle() {
+        const device = await requestDeviceCode(opts.server);
+        // Browser-open is opportunistic. Headless environments (SSH, containers,
+        // CI runners with no DE) are first-class — the URL surfaces in the tool
+        // response regardless, so a throwing opener must not mask it.
+        try {
+            openBrowserImpl(device.verification_uri_complete);
+        }
+        catch {
+            // ALLOWED-CATCH: browser-open failures are non-fatal by design
+        }
+        const response = buildAuthResponse(device);
+        // last_poll_at is seeded with now() — the cycle start counts as a
+        // server round-trip, so the next tool call shouldn't immediately
+        // re-hit /device/token within the interval window. This is what
+        // makes scenario "rapid-fire calls right after auth URL appears"
+        // not flood the server's 20/min rate limiter.
+        pending = {
+            device_code: device.device_code,
+            user_code: device.user_code,
+            verification_uri: device.verification_uri,
+            verification_uri_complete: device.verification_uri_complete,
+            expires_at: now() + device.expires_in * 1000,
+            interval_ms: device.interval * 1000,
+            last_poll_at: now(),
+            response,
+        };
+        return response;
+    }
+    /**
+     * Persist a new session's credentials. Separated so handleToolCall stays
+     * simple — see how success is collapsed into `pending = null; return null`.
+     */
+    function persistAuthorizedToken(token) {
+        const sseUrl = resolveSseUrl(token.sse_url, opts.server);
+        const creds = tokenToCredentials(token, sseUrl);
+        writeCredentials(creds, opts.credentialsPath);
+        lastCreds = creds;
+        pending = null;
+    }
+    /** Decide whether the cached response is still valid without polling. */
+    function shouldSkipPoll(state) {
+        if (state.last_poll_at === null)
+            return false;
+        return now() - state.last_poll_at < state.interval_ms;
+    }
+    /**
+     * Handle the result of a single /device/token poll. Mutates state as a
+     * side effect and returns the outbound response (or null on authorization).
+     * Network errors fall through silently (no state change, retry on next call).
+     */
+    function applyPollResult(state, result) {
+        if (result.status === "authorized") {
+            persistAuthorizedToken(result.token);
+            return null;
+        }
+        if (result.status === "denied") {
+            // Clear state so the next call starts fresh. Return the error text
+            // inline so the agent sees why; the user will naturally retry.
+            pending = null;
+            return {
+                content: [{ type: "text", text: `Pharaoh auth denied: ${result.error}` }],
+                isError: true,
+                _meta: {
+                    auth_url: state.verification_uri,
+                    user_code: state.user_code,
+                    expires_in_seconds: 0,
+                },
+            };
+        }
+        // pending, expired, network_error: keep cached response. Expired is
+        // handled by the expiry check in handleToolCall; we don't force it here
+        // because applyPollResult runs AFTER the expiry check, which means an
+        // expired server code here is a rare race (<1s window) and getting the
+        // same response back is fine.
+        return state.response;
+    }
+    async function handleToolCall() {
+        // No active cycle — start one.
+        if (pending === null) {
+            return startNewCycle();
+        }
+        // Client-side expiry check. If the device code has expired, the server
+        // will reject further polls; clear state and start a fresh cycle. This
+        // is the only state transition triggered purely by time.
+        if (now() >= pending.expires_at) {
+            pending = null;
+            return startNewCycle();
+        }
+        // Rate-limit: respect the server's interval so we don't hammer /token
+        // when agents rapid-fire tool calls on failure.
+        if (shouldSkipPoll(pending)) {
+            return pending.response;
+        }
+        const state = pending;
+        state.last_poll_at = now();
+        const result = await pollOnce(opts.server, state.device_code);
+        return applyPollResult(state, result);
+    }
+    function hasValidCredentials() {
+        const creds = readCredentials(opts.credentialsPath);
+        if (!creds)
+            return false;
+        lastCreds = creds;
+        return !isAccessExpired(creds);
+    }
+    function getCredentials() {
+        return lastCreds;
+    }
+    return { handleToolCall, hasValidCredentials, getCredentials };
+}

package/dist/proxy-server.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ProxyServer — owns the stdio MCP Server and delegates tool calls through a
+ * mutable Backend reference. The whole point of this abstraction is that we
+ * can swap the backend under a running server without restarting stdio, which
+ * means Claude Code never has to reconnect.
+ *
+ * Two entry points cover the interesting startup shapes:
+ *
+ * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
+ *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
+ *   Session C then polls hasValidCredentials() and calls setBackend() to swap
+ *   to the SSE backend once the user finishes the device flow.
+ *
+ * - startInSseMode: happy path — valid credentials are already on disk. Starts
+ *   the server directly with an SSE backend.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { type Backend } from "./backend.js";
+import type { Credentials } from "./credentials.js";
+import { type DeviceFlowGateway } from "./gateway.js";
+/**
+ * Stdio MCP server with a swappable backend. The Server instance is
+ * long-lived across backend swaps; only the Backend reference moves.
+ */
+export declare class ProxyServer {
+    private server;
+    private transport;
+    private backend;
+    private started;
+    constructor(initialBackend: Backend);
+    /**
+     * Wire up list/call handlers. Each handler reads this.backend fresh at
+     * dispatch time — do NOT hoist the reference into a local, or setBackend()
+     * won't take effect for subsequent calls. This is the core property that
+     * makes mutable-backend swaps safe.
+     */
+    private registerHandlers;
+    /**
+     * Start the backend (if it has a start hook) and connect stdio. Idempotent.
+     * Tests inject an alternate transport via startWithTransport().
+     */
+    start(): Promise<void>;
+    /**
+     * Test hook: start with a caller-supplied transport (e.g. InMemoryTransport).
+     * Kept separate from start() so the stdio wiring stays implicit in prod.
+     */
+    startWithTransport(transport: StdioServerTransport): Promise<void>;
+    /**
+     * Swap the backend reference and fire a tools/list_changed notification so
+     * the client re-fetches. No in-flight tracking — the SDK routes each call
+     * to whichever backend is current at dispatch time.
+     */
+    setBackend(next: Backend): Promise<void>;
+    stop(): Promise<void>;
+    getBackend(): Backend;
+}
+/**
+ * Cold-start entry point. No credentials (or refresh-expired creds) — start
+ * the proxy in auth-required mode so the stdio connection stays alive while
+ * the user completes the device flow.
+ *
+ * Returns the running ProxyServer and its gateway. Session C awaits
+ * gateway.hasValidCredentials() on each tool call boundary, and once that
+ * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
+ * real catalog.
+ */
+export declare function startInAuthRequiredMode(server: string): Promise<{
+    proxy: ProxyServer;
+    gateway: DeviceFlowGateway;
+}>;
+/**
+ * Happy-path entry point. Credentials are fresh — start directly with the
+ * SSE backend. Returned proxy is running and ready for tool calls.
+ */
+export declare function startInSseMode(creds: Credentials): Promise<ProxyServer>;

package/dist/proxy-server.js

@@ -0,0 +1,143 @@
+/**
+ * ProxyServer — owns the stdio MCP Server and delegates tool calls through a
+ * mutable Backend reference. The whole point of this abstraction is that we
+ * can swap the backend under a running server without restarting stdio, which
+ * means Claude Code never has to reconnect.
+ *
+ * Two entry points cover the interesting startup shapes:
+ *
+ * - startInAuthRequiredMode: cold start, no (or expired-refresh) credentials.
+ *   Spins up a gateway, wraps it in AuthRequiredBackend, starts the server.
+ *   Session C then polls hasValidCredentials() and calls setBackend() to swap
+ *   to the SSE backend once the user finishes the device flow.
+ *
+ * - startInSseMode: happy path — valid credentials are already on disk. Starts
+ *   the server directly with an SSE backend.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { AuthRequiredBackend, createSseBackend } from "./backend.js";
+import { createGateway } from "./gateway.js";
+import { getPackageVersion } from "./version.js";
+/**
+ * Stdio MCP server with a swappable backend. The Server instance is
+ * long-lived across backend swaps; only the Backend reference moves.
+ */
+export class ProxyServer {
+    server;
+    transport = null;
+    backend;
+    started = false;
+    constructor(initialBackend) {
+        this.backend = initialBackend;
+        this.server = new Server({ name: "pharaoh-proxy", version: getPackageVersion() }, {
+            // tools.listChanged is required for sendToolListChanged() not
+            // to throw; the SDK's assertNotificationCapability gates it.
+            capabilities: { tools: { listChanged: true } },
+        });
+        this.registerHandlers();
+    }
+    /**
+     * Wire up list/call handlers. Each handler reads this.backend fresh at
+     * dispatch time — do NOT hoist the reference into a local, or setBackend()
+     * won't take effect for subsequent calls. This is the core property that
+     * makes mutable-backend swaps safe.
+     */
+    registerHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: await this.backend.listTools(),
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+            const result = await this.backend.callTool(req.params.name, req.params.arguments ?? {});
+            return result;
+        });
+    }
+    /**
+     * Start the backend (if it has a start hook) and connect stdio. Idempotent.
+     * Tests inject an alternate transport via startWithTransport().
+     */
+    async start() {
+        if (this.started)
+            return;
+        if (this.backend.start)
+            await this.backend.start();
+        this.transport = new StdioServerTransport();
+        await this.server.connect(this.transport);
+        this.started = true;
+    }
+    /**
+     * Test hook: start with a caller-supplied transport (e.g. InMemoryTransport).
+     * Kept separate from start() so the stdio wiring stays implicit in prod.
+     */
+    async startWithTransport(transport) {
+        if (this.started)
+            return;
+        if (this.backend.start)
+            await this.backend.start();
+        this.transport = transport;
+        // biome-ignore lint/suspicious/noExplicitAny: test transport is a Transport, but the type import chain is awkward here
+        await this.server.connect(transport);
+        this.started = true;
+    }
+    /**
+     * Swap the backend reference and fire a tools/list_changed notification so
+     * the client re-fetches. No in-flight tracking — the SDK routes each call
+     * to whichever backend is current at dispatch time.
+     */
+    async setBackend(next) {
+        const prev = this.backend;
+        this.backend = next;
+        if (next.start)
+            await next.start();
+        // Only emit after backend reference is swapped — if the client races
+        // a list request against the notification, we want them to see the
+        // new catalog.
+        await this.server.sendToolListChanged();
+        // Fire-and-forget stop of the old backend. Errors here don't affect
+        // the running session — the swap has already happened.
+        if (prev !== next && prev.stop) {
+            prev.stop().catch(() => { });
+        }
+    }
+    async stop() {
+        if (this.backend.stop) {
+            await this.backend.stop().catch(() => { });
+        }
+        if (this.transport) {
+            await this.server.close().catch(() => { });
+            this.transport = null;
+        }
+        this.started = false;
+    }
+    getBackend() {
+        return this.backend;
+    }
+}
+/**
+ * Cold-start entry point. No credentials (or refresh-expired creds) — start
+ * the proxy in auth-required mode so the stdio connection stays alive while
+ * the user completes the device flow.
+ *
+ * Returns the running ProxyServer and its gateway. Session C awaits
+ * gateway.hasValidCredentials() on each tool call boundary, and once that
+ * flips true, calls proxy.setBackend(createSseBackend(...)) to swap in the
+ * real catalog.
+ */
+export async function startInAuthRequiredMode(server) {
+    const gateway = createGateway({ server });
+    const backend = new AuthRequiredBackend(gateway);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    return { proxy, gateway };
+}
+/**
+ * Happy-path entry point. Credentials are fresh — start directly with the
+ * SSE backend. Returned proxy is running and ready for tool calls.
+ */
+export async function startInSseMode(creds) {
+    const backend = createSseBackend(creds.sse_url, creds.access_token);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    return proxy;
+}

package/dist/proxy.d.ts

@@ -1,18 +1,25 @@
 /**
- * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
- * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
+ * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
+ * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
+ * from here. Session C will rewrite index.ts to use ProxyServer/Backend
+ * directly and `startProxy` will disappear at that point.
  *
- * RECONNECTION DESIGN:
- * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
- * (every 3 seconds by default). This auto-reconnect is problematic because:
- *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ * Typed error classes and SSE classification live here because both the
+ * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
+ * to produce the same typed errors so downstream consumers don't care which
+ * path surfaced them.
+ *
+ * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
+ * auto-reconnect (every 3s by default). This is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
  *   2. The proxy's reconnect loop doesn't know about the internal reconnect
  *   3. Tool calls get lost between the stale and new sessions
  *
- * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
- * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
- * create a fresh SSEClientTransport for the next attempt. This ensures one session
- * at a time and clean reconnection semantics.
+ * Solution: on any non-fatal SSE error, explicitly close() the transport to
+ * kill the EventSource, then let the proxy's own backoff loop create a fresh
+ * transport for the next attempt. See backend.ts SseProxyBackend.waitForClose.
  */
 /** Thrown when the remote server returns 401 — token is expired or revoked. */
 export declare class TokenExpiredError extends Error {
@@ -24,21 +31,16 @@ export declare class TenantSuspendedError extends Error {
 }
 /**
  * Classify an SSE error — detect 401/403 and throw typed errors.
- * Exported for testability; used internally by the reconnect loop.
+ * Exported for testability; used internally by the reconnect loop in
+ * backend.ts.
  */
 export declare function classifySSEError(err: Error): void;
 /**
- * Start the stdio ↔ SSE proxy. Blocks until the connection is permanently closed.
- *
- * Message flow:
- *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
- *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
- *
- * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
- * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
- * gets permanently lost ("send error — Not connected"), and the client times out.
+ * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
+ * until the underlying SSE backend exits. Preserved so index.ts (Session C)
+ * keeps compiling until the wiring PR; the return/throw contract matches the
+ * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
  *
- * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
- * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ * @deprecated Session C will call ProxyServer / startInSseMode directly.
  */
 export declare function startProxy(sseUrl: string, token: string): Promise<void>;

package/dist/proxy.js

@@ -1,21 +1,26 @@
 /**
- * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
- * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ * Stdio ↔ SSE proxy entry point. Legacy export surface kept for the
+ * in-flight handoff between Sessions B and C: index.ts (Session C's scope)
+ * still imports `startProxy`, `TokenExpiredError`, and `TenantSuspendedError`
+ * from here. Session C will rewrite index.ts to use ProxyServer/Backend
+ * directly and `startProxy` will disappear at that point.
  *
- * RECONNECTION DESIGN:
- * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
- * (every 3 seconds by default). This auto-reconnect is problematic because:
- *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ * Typed error classes and SSE classification live here because both the
+ * legacy startProxy wrapper and the new SseProxyBackend (in backend.ts) need
+ * to produce the same typed errors so downstream consumers don't care which
+ * path surfaced them.
+ *
+ * RECONNECTION DESIGN (inherited by SseProxyBackend):
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in
+ * auto-reconnect (every 3s by default). This is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new ID)
  *   2. The proxy's reconnect loop doesn't know about the internal reconnect
  *   3. Tool calls get lost between the stale and new sessions
  *
- * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
- * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
- * create a fresh SSEClientTransport for the next attempt. This ensures one session
- * at a time and clean reconnection semantics.
+ * Solution: on any non-fatal SSE error, explicitly close() the transport to
+ * kill the EventSource, then let the proxy's own backoff loop create a fresh
+ * transport for the next attempt. See backend.ts SseProxyBackend.waitForClose.
  */
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 /** Thrown when the remote server returns 401 — token is expired or revoked. */
 export class TokenExpiredError extends Error {
     constructor() {
@@ -30,11 +35,10 @@ export class TenantSuspendedError extends Error {
         this.name = "TenantSuspendedError";
     }
 }
-/** Backoff schedule for reconnect attempts (milliseconds). */
-const BACKOFF_MS = [2000, 4000, 8000, 16000, 32000];
 /**
  * Classify an SSE error — detect 401/403 and throw typed errors.
- * Exported for testability; used internally by the reconnect loop.
+ * Exported for testability; used internally by the reconnect loop in
+ * backend.ts.
  */
 export function classifySSEError(err) {
     const msg = err.message ?? "";
@@ -53,120 +57,28 @@ export function classifySSEError(err) {
         throw new TenantSuspendedError(msg || "Tenant suspended");
 }
 /**
- * Create an SSEClientTransport with Bearer token auth.
- * Injects the Authorization header into both the SSE connection (via custom fetch)
- * and POST requests (via requestInit).
- */
-function createSSETransport(sseUrl, token) {
-    const authHeader = `Bearer ${token}`;
-    return new SSEClientTransport(new URL(sseUrl), {
-        eventSourceInit: {
-            fetch: (url, init) => {
-                const h = new Headers(init.headers);
-                h.set("Authorization", authHeader);
-                return fetch(url, { ...init, headers: h });
-            },
-        },
-        requestInit: {
-            headers: { Authorization: authHeader },
-        },
-    });
-}
-/**
- * Start the stdio ↔ SSE proxy. Blocks until the connection is permanently closed.
+ * Legacy thin wrapper that starts the new ProxyServer in SSE mode and blocks
+ * until the underlying SSE backend exits. Preserved so index.ts (Session C)
+ * keeps compiling until the wiring PR; the return/throw contract matches the
+ * original (resolves on clean exit, throws TokenExpiredError / TenantSuspendedError).
  *
- * Message flow:
- *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
- *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
- *
- * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
- * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
- * gets permanently lost ("send error — Not connected"), and the client times out.
- *
- * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
- * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
+ * @deprecated Session C will call ProxyServer / startInSseMode directly.
  */
 export async function startProxy(sseUrl, token) {
-    const stdio = new StdioServerTransport();
-    let sse = createSSETransport(sseUrl, token);
-    let reconnectAttempt = 0;
-    let stdioStarted = false;
-    /** Wire up bidirectional message relay between the two transports. */
-    function bridge(sseTransport) {
-        stdio.onmessage = (msg) => {
-            sseTransport.send(msg).catch((err) => {
-                process.stderr.write(`Pharaoh: send error — ${err instanceof Error ? err.message : String(err)}\n`);
-            });
-        };
-        sseTransport.onmessage = (msg) => {
-            stdio.send(msg).catch((err) => {
-                process.stderr.write(`Pharaoh: stdout error — ${err instanceof Error ? err.message : String(err)}\n`);
-            });
-        };
+    // Lazy imports to keep module load order clean — backend.ts imports from
+    // proxy.ts for the typed errors and classifier above, so a top-level
+    // import would create a cycle.
+    const { createSseBackend } = await import("./backend.js");
+    const { ProxyServer } = await import("./proxy-server.js");
+    const backend = createSseBackend(sseUrl, token);
+    const proxy = new ProxyServer(backend);
+    await proxy.start();
+    // Block on the SSE reconnect loop — matches the original semantics of
+    // startProxy, which resolved only when the connection terminated.
+    try {
+        await backend.waitForExit();
     }
-    // Connect SSE with reconnect loop — stdio starts AFTER first successful connection
-    await connectWithReconnect();
-    /** Attempt SSE connection with exponential backoff on failure. */
-    async function connectWithReconnect() {
-        while (reconnectAttempt <= BACKOFF_MS.length) {
-            try {
-                if (reconnectAttempt > 0) {
-                    const delay = BACKOFF_MS[reconnectAttempt - 1];
-                    process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${reconnectAttempt}/${BACKOFF_MS.length})...\n`);
-                    await sleep(delay);
-                    sse = createSSETransport(sseUrl, token);
-                }
-                await sse.start();
-                reconnectAttempt = 0; // Reset on successful connection
-                // Bridge AFTER SSE is connected — messages can now be forwarded
-                bridge(sse);
-                // Start stdio AFTER first SSE connection — prevents initialize race
-                if (!stdioStarted) {
-                    process.stderr.write("Pharaoh: connected\n");
-                    await stdio.start();
-                    stdioStarted = true;
-                }
-                else {
-                    process.stderr.write("Pharaoh: reconnected\n");
-                }
-                // Wait for close — this promise resolves when SSE disconnects
-                await new Promise((resolve, reject) => {
-                    sse.onclose = () => resolve();
-                    sse.onerror = (err) => {
-                        try {
-                            classifySSEError(err);
-                        }
-                        catch (typed) {
-                            reject(typed);
-                            return;
-                        }
-                        // Non-fatal error — explicitly close the transport to kill
-                        // EventSource's built-in auto-reconnect. Without this, EventSource
-                        // reconnects every ~3s, creating ghost sessions on the server
-                        // (100+ auth successes, zero tool calls completing).
-                        // close() fires onclose which resolves this promise, handing
-                        // control back to the proxy's backoff loop.
-                        sse.close().catch(() => { });
-                    };
-                });
-                // SSE closed — attempt reconnect
-                reconnectAttempt++;
-            }
-            catch (err) {
-                if (err instanceof TokenExpiredError || err instanceof TenantSuspendedError) {
-                    await stdio.close().catch(() => { });
-                    throw err;
-                }
-                reconnectAttempt++;
-                if (reconnectAttempt > BACKOFF_MS.length) {
-                    process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");
-                    await stdio.close().catch(() => { });
-                    throw new Error("SSE connection failed after maximum retries");
-                }
-            }
-        }
+    finally {
+        await proxy.stop().catch(() => { });
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.22",
+  "version": "0.3.23",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",