@pharaoh-so/mcp 0.3.24 → 0.3.26

package/dist/auth.d.ts

@@ -85,6 +85,12 @@ export declare function pollForToken(baseUrl: string, deviceCode: string, interv
  * 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.
+ *
+ * Test / CI escape hatch: set PHARAOH_MCP_DISABLE_BROWSER=1 when spawning the
+ * proxy as a child process during E2E testing. The openBrowser dependency-
+ * injection path in gateway.ts is sufficient for in-process tests, but child-
+ * process tests bypass module mocking — the env-var short-circuit catches
+ * every spawn path (gateway, printActivationPrompt, direct index.ts calls).
  */
 export declare function openBrowser(url: string): void;
 /**

package/dist/auth.js

@@ -112,8 +112,16 @@ export async function pollForToken(baseUrl, deviceCode, interval) {
  * 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.
+ *
+ * Test / CI escape hatch: set PHARAOH_MCP_DISABLE_BROWSER=1 when spawning the
+ * proxy as a child process during E2E testing. The openBrowser dependency-
+ * injection path in gateway.ts is sufficient for in-process tests, but child-
+ * process tests bypass module mocking — the env-var short-circuit catches
+ * every spawn path (gateway, printActivationPrompt, direct index.ts calls).
  */
 export function openBrowser(url) {
+    if (process.env.PHARAOH_MCP_DISABLE_BROWSER === "1")
+        return;
     if (process.platform === "darwin") {
         execFile("open", [url], () => { });
     }

package/dist/backend.d.ts

@@ -26,6 +26,12 @@ export interface Backend {
     start?(): Promise<void>;
     /** Optional teardown (e.g. close SSE). Idempotent. */
     stop?(): Promise<void>;
+    /**
+     * Optional long-running promise that completes on clean exit or rejects with
+     * a typed error (TokenExpiredError, TenantSuspendedError) the main loop can
+     * act on. Backends without a supervisor loop (AuthRequiredBackend) omit this.
+     */
+    waitForExit?(): Promise<void>;
 }
 /**
  * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
@@ -41,13 +47,16 @@ 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.
+ * reports the user has authorized (handleToolCall returns null), this backend
+ * invokes the onAuthorized callback so the caller (index.ts main loop) can
+ * swap the ProxyServer over to an SseProxyBackend. The backend itself does NOT
+ * swap — callbacks keep the ownership of the proxy reference in one place.
  */
 export declare class AuthRequiredBackend implements Backend {
     private readonly gateway;
+    private readonly onAuthorized?;
     readonly name: "auth-required";
-    constructor(gateway: DeviceFlowGateway);
+    constructor(gateway: DeviceFlowGateway, onAuthorized?: (() => Promise<void>) | undefined);
     listTools(): Promise<Tool[]>;
     callTool(_name: string, _args: Record<string, unknown>): Promise<CallToolResult>;
 }

package/dist/backend.js

@@ -48,14 +48,18 @@ export const AUTH_REQUIRED_TOOLS = [
 /**
  * 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.
+ * reports the user has authorized (handleToolCall returns null), this backend
+ * invokes the onAuthorized callback so the caller (index.ts main loop) can
+ * swap the ProxyServer over to an SseProxyBackend. The backend itself does NOT
+ * swap — callbacks keep the ownership of the proxy reference in one place.
  */
 export class AuthRequiredBackend {
     gateway;
+    onAuthorized;
     name = "auth-required";
-    constructor(gateway) {
+    constructor(gateway, onAuthorized) {
         this.gateway = gateway;
+        this.onAuthorized = onAuthorized;
     }
     async listTools() {
         return AUTH_REQUIRED_TOOLS;
@@ -63,9 +67,41 @@ export class AuthRequiredBackend {
     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.
+            // Credentials just became valid. Fire the authorization callback
+            // BEFORE returning success so the caller's backend swap is in place
+            // by the time the next tool call arrives.
+            if (this.onAuthorized) {
+                try {
+                    await this.onAuthorized();
+                }
+                catch (err) {
+                    // TenantSuspendedError from the post-auth SSE handshake means
+                    // the tenant was suspended between authorize and swap. Rethrow
+                    // so the supervisor exits cleanly instead of looping in
+                    // auth-required mode forever.
+                    if (err instanceof TenantSuspendedError)
+                        throw err;
+                    // Any other swap failure (SSE start rejected, gateway returned
+                    // no creds, network blip) must surface as an error to the
+                    // agent. Returning success would leave the proxy in a zombie
+                    // state — this backend still active, onAuthorized already
+                    // fired, every subsequent tool call burning a fresh device
+                    // flow cycle. isError:true lets the agent see the failure and
+                    // retry the tool call, which will re-enter the gateway's post-
+                    // auth branch and attempt the swap again.
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`Pharaoh: onAuthorized callback failed — ${msg}\n`);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Pharaoh: authenticated but backend swap failed — ${msg}. Retry the tool call.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
             return {
                 content: [
                     {
@@ -207,6 +243,16 @@ export class SseProxyBackend {
                 if (err instanceof TokenExpiredError || err instanceof TenantSuspendedError) {
                     throw err;
                 }
+                // connectOnce() inside reconnectAfter() can throw an SseError with
+                // code === 401 / 403 when the stored token is rejected on
+                // reconnect (the common mid-session token-expiry shape). Run it
+                // through classifySSEError — that helper throws typed errors,
+                // which propagate out of the current catch via the enclosing
+                // catch's implicit re-throw. The session supervisor sees the
+                // typed error and can swap backends instead of treating it as a
+                // transient retry.
+                if (err instanceof Error)
+                    classifySSEError(err);
                 // Do NOT increment attempt here — the try block already incremented
                 // it before calling reconnectAfter. A second bump would halve the
                 // effective retry budget so only ~3 of the 5 BACKOFF_MS slots

package/dist/gateway.js

@@ -17,17 +17,31 @@
 import { openBrowser, pollOnce, requestDeviceCode, } from "./auth.js";
 import { readCredentials, writeCredentials } from "./credentials.js";
 import { resolveSseUrl, tokenToCredentials } from "./helpers.js";
-function isAccessExpired(creds) {
+/**
+ * True when the credentials' access token is at or past its expiry.
+ *
+ * Takes `now` as a parameter so boundary tests (Date.now() === expires_at
+ * exactly) work naturally with the gateway's injected clock — previously
+ * this used Date.now() directly, which couldn't be controlled from tests.
+ */
+function isAccessExpired(creds, now) {
     const expiresAt = new Date(creds.expires_at).getTime();
     if (Number.isNaN(expiresAt))
         return true;
-    return Date.now() >= expiresAt;
+    return now() >= expiresAt;
 }
 function buildAuthResponse(device) {
+    // Stryker disable next-line StringLiteral: user-facing UX copy; wording
+    // changes are deliberate and covered by manual review, not mutation testing.
     const prefix = device.errorMessage ? `${device.errorMessage}\n\n` : "";
-    const text = `${prefix}Pharaoh authentication required.\n\n` +
+    const text = 
+    // Stryker disable next-line StringLiteral: user-facing UX copy
+    `${prefix}Pharaoh authentication required.\n\n` +
+        // Stryker disable next-line StringLiteral: user-facing UX copy
         `  1. Visit ${device.verification_uri_complete}\n` +
+        // Stryker disable next-line StringLiteral: user-facing UX copy
         `  2. Enter code: ${device.user_code}\n` +
+        // Stryker disable next-line StringLiteral: user-facing UX copy
         `  3. Re-run this tool after authorizing.`;
     return {
         content: [{ type: "text", text }],
@@ -45,6 +59,12 @@ function buildAuthResponse(device) {
  */
 export function createGateway(opts) {
     const now = opts.now ?? (() => Date.now());
+    // Stryker disable next-line LogicalOperator: the `??` fallback is exercised
+    // at runtime when no opts.openBrowser is passed, but tests vi.mock auth.js's
+    // openBrowser to a noop, so a mutated operator can't be distinguished via
+    // observable behavior. vi.mock is the safety net; the fallback is defense
+    // in depth for production. See packages/mcp-proxy/tests/*.test.ts for the
+    // module-level mock that keeps real browser-open calls out of CI.
     const openBrowserImpl = opts.openBrowser ?? openBrowser;
     let pending = null;
     let lastCreds = null;
@@ -91,8 +111,6 @@ export function createGateway(opts) {
     }
     /** 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;
     }
     /**
@@ -110,6 +128,7 @@ export function createGateway(opts) {
             // inline so the agent sees why; the user will naturally retry.
             pending = null;
             return {
+                // Stryker disable next-line StringLiteral: user-facing UX copy
                 content: [{ type: "text", text: `Pharaoh auth denied: ${result.error}` }],
                 isError: true,
                 _meta: {
@@ -153,7 +172,7 @@ export function createGateway(opts) {
         if (!creds)
             return false;
         lastCreds = creds;
-        return !isAccessExpired(creds);
+        return !isAccessExpired(creds, now);
     }
     function getCredentials() {
         return lastCreds;

package/dist/index.js

@@ -8,14 +8,19 @@
  *
  * Two modes determined by whether stdin is a TTY:
  * - Interactive (TTY): authenticate, print setup instructions, exit.
- * - Proxy (pipe):      require pre-existing credentials, bridge stdio ↔ SSE.
+ * - Proxy (pipe):      bridge stdio ↔ SSE. No valid creds? Run in auth-required
+ *                      mode until device flow completes, then swap to SSE in
+ *                      place — the stdio session never disconnects.
  */
 import { pollForToken, printActivationPrompt, printAuthSuccess, requestDeviceCode, } from "./auth.js";
-import { deleteCredentials, writeCredentials } from "./credentials.js";
+import { AuthRequiredBackend, createSseBackend } from "./backend.js";
+import { deleteCredentials, readCredentials, writeCredentials } from "./credentials.js";
+import { createGateway } from "./gateway.js";
 import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
 import { runInstallSkills } from "./install-skills.js";
-import { exitForReauth, handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
-import { startProxy, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
+import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { startInAuthRequiredMode, startInSseMode } from "./proxy-server.js";
 import { loadAndRefresh } from "./refresh.js";
 const BANNER = [
     "",
@@ -87,70 +92,177 @@ async function main() {
         process.exit(0);
     }
     // ── Proxy mode (Claude Code spawned us as a stdio MCP server) ──
-    // Load credentials; refresh silently if the access token is expired but the
-    // refresh token is still valid. Anything else → exit with guidance.
+    // Single flow: load creds → pick starting backend → wait for lifetime
+    // events → swap backends in place. Session C design note: we never exit
+    // on recoverable conditions (missing creds, expired-refresh, mid-session
+    // 401). The stdio session stays alive for the whole life of the agent;
+    // only non-recoverable failures (tenant suspended, transient refresh error
+    // on cold start) terminate the process.
     const outcome = await loadAndRefresh(server);
-    if (outcome === null) {
-        // No credentials file at all — first-time run or user logged out.
-        exitForReauth("no credentials — run authentication first");
-    }
-    if (!outcome.ok) {
-        handleRefreshFailure(outcome.action, outcome.message);
-        return; // unreachable — handleRefreshFailure calls process.exit
-    }
-    let creds = outcome.creds;
-    // Valid credentials — ensure skills are installed before starting proxy
-    // Silently installs/updates on first run or package update; fast no-op if current.
+    // Install skills opportunistically — must not block startup. Failures
+    // here include network hiccups (npm registry blips) and transient fs
+    // issues, neither of which should prevent the proxy serving MCP traffic.
+    // Log the message so "silent" is still distinguishable from "never ran."
     try {
         runInstallSkills();
     }
-    catch {
+    catch (err) {
         // ALLOWED-CATCH: skill install failure must not block MCP proxy startup
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Pharaoh: skill install skipped — ${msg}\n`);
     }
-    printLines(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting`);
-    try {
-        await startProxy(creds.sse_url, creds.access_token);
+    // Needs auth: either no creds file OR refresh token is terminally rejected.
+    // Both cases: start in auth-required mode, wait for the user to complete
+    // device flow, then swap to SSE via the onAuthorized callback.
+    const needsAuth = outcome === null || (!outcome.ok && outcome.action === "reauth");
+    if (needsAuth) {
+        // If we reached here via a rejected refresh, delete the stale creds
+        // file so the gateway's internal readCredentials() doesn't pick up the
+        // just-invalidated refresh token on restart.
+        if (outcome && !outcome.ok)
+            deleteCredentials();
+        // The callback closure captures `proxy` via the destructured `const`
+        // binding declared below. The closure is only invoked once authorization
+        // completes (after the user's device-flow round trip), long after the
+        // assignment — so TS's strict-binding checks accept the reference.
+        const { proxy } = await startInAuthRequiredMode(server, {
+            onAuthorized: async (creds) => {
+                printLines("Pharaoh: authenticated — swapping to SSE backend.");
+                await proxy.setBackend(createSseBackend(creds.sse_url, creds.access_token));
+            },
+        });
+        printLines("Pharaoh: awaiting authentication via Claude Code...");
+        await waitForProxyLifetime(proxy, server);
+        return;
     }
-    catch (err) {
-        if (err instanceof TokenExpiredError) {
-            // Mid-session token expired — attempt one silent refresh + retry
-            // before giving up. This is what makes the proxy self-heal across
-            // long sessions rather than dying at arbitrary moments.
-            const retryCreds = await tryMidSessionRefresh(creds, server);
-            if (retryCreds) {
-                creds = retryCreds;
-                printLines("Pharaoh: token refreshed mid-session — reconnecting");
-                try {
-                    await startProxy(creds.sse_url, creds.access_token);
-                    return;
+    // Non-recoverable refresh failure (transient / preserve). Don't delete
+    // creds; the next spawn will retry. Match the pre-Session-C behavior for
+    // these codepaths exactly — if we can't refresh on cold start, we can't
+    // serve any tool calls, so bailing is honest.
+    if (!outcome.ok) {
+        handleRefreshFailure(outcome.action, outcome.message);
+        return; // unreachable — handleRefreshFailure calls process.exit
+    }
+    // Happy path: valid credentials. Start SSE backend, wait for lifetime,
+    // handle any mid-session failures by swapping backends in place.
+    const creds = outcome.creds;
+    printLines(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting`);
+    const proxy = await startInSseMode(creds);
+    await waitForProxyLifetime(proxy, server);
+}
+/** Circuit breaker: abort after this many TokenExpiredError recoveries in the window. */
+const RECOVERY_WINDOW_MS = 60_000;
+const MAX_RECOVERIES_PER_WINDOW = 3;
+/**
+ * Block on proxy.waitForLifetime() and reconcile mid-session failures by
+ * swapping the backend in place. Loops so successive swaps (e.g. SSE → auth
+ * → SSE) all stay under the same stdio connection.
+ *
+ * Terminates (returns normally) only when:
+ *   - stdio closes (Claude Code disconnects), or
+ *   - a non-recoverable branch explicitly process.exit()s.
+ *
+ * Circuit breaker: a buggy or hostile upstream can force a SSE↔auth churn by
+ * issuing a fresh 401 immediately after each successful reauth. Cap the
+ * recovery rate so the proxy exits with a diagnostic instead of pinning the
+ * user in a loop that re-prompts device flow every few seconds.
+ */
+async function waitForProxyLifetime(proxy, server) {
+    const recoveryTimestamps = [];
+    while (true) {
+        try {
+            await proxy.waitForLifetime();
+            return; // stdio closed cleanly — end of session
+        }
+        catch (err) {
+            if (err instanceof TokenExpiredError) {
+                const now = Date.now();
+                // Drop timestamps older than the window.
+                while (recoveryTimestamps.length && now - recoveryTimestamps[0] > RECOVERY_WINDOW_MS) {
+                    recoveryTimestamps.shift();
                 }
-                catch (retryErr) {
-                    if (retryErr instanceof TokenExpiredError) {
-                        // Second 401 after a successful refresh — the fresh tokens
-                        // are already rejected, so the session is genuinely dead.
-                        // Delete creds before exit so the next spawn shows the
-                        // re-auth prompt instead of looping on the just-rejected
-                        // access token (which `isExpired` would still say is fresh).
-                        deleteCredentials();
-                        exitForReauth("token rejected after refresh");
-                    }
-                    if (retryErr instanceof TenantSuspendedError) {
-                        printLines(`Pharaoh: ${retryErr.message}`);
-                        process.exit(1);
-                    }
-                    throw retryErr;
+                recoveryTimestamps.push(now);
+                if (recoveryTimestamps.length > MAX_RECOVERIES_PER_WINDOW) {
+                    printLines(`Pharaoh: ${recoveryTimestamps.length} token-expired recoveries in ${RECOVERY_WINDOW_MS / 1000}s — aborting to avoid an auth loop. Restart to retry.`);
+                    process.exit(1);
                 }
+                const recovered = await recoverFromTokenExpired(proxy, server);
+                if (recovered)
+                    continue; // swapped to a new backend; keep waiting
+                return; // recovery exited / handed off to auth-required loop
             }
-            // Refresh failed — exit message already printed by tryMidSessionRefresh
-            process.exit(1);
-        }
-        if (err instanceof TenantSuspendedError) {
-            printLines(`Pharaoh: ${err.message}`);
-            process.exit(1);
+            if (err instanceof TenantSuspendedError) {
+                printLines(`Pharaoh: ${err.message}`);
+                process.exit(1);
+            }
+            throw err;
         }
-        throw err;
     }
 }
+/**
+ * Handle a mid-session 401 without tearing down the stdio session:
+ *   1. Attempt a silent refresh. If it works, swap to a fresh SSE backend.
+ *   2. If the refresh says reauth, swap to AuthRequiredBackend — the next
+ *      tool call surfaces the auth URL. The onAuthorized callback swaps us
+ *      back to SSE once the user completes device flow.
+ *   3. If the refresh is transient/preserve, the session can't recover here
+ *      — exit with the classified message.
+ *
+ * Returns `true` when a backend swap happened and the caller should keep
+ * waiting on waitForLifetime(); returns `false` when the caller's loop should
+ * exit (because this function either handed off to an async auth-required
+ * swap-back or process.exit()'d for a non-recoverable case).
+ */
+async function recoverFromTokenExpired(proxy, server) {
+    // Re-read creds from disk — the SSE backend doesn't expose its token, and
+    // a prior refresh may have rotated what's on disk. Silent-refresh the
+    // token regardless of the on-disk expiry (the 401 is authoritative: the
+    // server rejected us, so force a round trip).
+    const diskCreds = readCredentials();
+    if (!diskCreds) {
+        // No creds on disk — shouldn't happen mid-session, but if it does,
+        // fall through to auth-required mode to get new ones.
+        await swapToAuthRequired(proxy, server);
+        return true;
+    }
+    const result = await tryMidSessionRefresh(diskCreds, server);
+    if (result.ok) {
+        printLines("Pharaoh: token refreshed mid-session — swapping SSE backend");
+        await proxy.setBackend(createSseBackend(result.creds.sse_url, result.creds.access_token));
+        return true;
+    }
+    // Branch on the explicit classification returned by tryMidSessionRefresh
+    // rather than inferring from disk state. `reauth` means the refresh token
+    // is terminally rejected — swap to auth-required so the user can re-
+    // authenticate without the session tearing down. `preserve`/`transient`
+    // mean the server's temporarily unable to refresh us; exit with the
+    // message so the user knows their credentials are intact.
+    if (result.action === "reauth") {
+        await swapToAuthRequired(proxy, server);
+        return true;
+    }
+    printLines(`Pharaoh: mid-session refresh failed (${result.action}) — credentials preserved; restart to retry.`);
+    process.exit(1);
+}
+/**
+ * Swap the live ProxyServer over to an AuthRequiredBackend, wiring an
+ * onAuthorized callback that swaps back to SSE. Used on both mid-session
+ * reauth and first-missing-creds recovery.
+ */
+async function swapToAuthRequired(proxy, server) {
+    const gateway = createGateway({ server });
+    const authBackend = new AuthRequiredBackend(gateway, async () => {
+        const fresh = gateway.getCredentials();
+        if (!fresh) {
+            process.stderr.write("Pharaoh: swap-back aborted — gateway returned no creds\n");
+            return;
+        }
+        printLines("Pharaoh: re-authenticated — swapping back to SSE backend.");
+        await proxy.setBackend(createSseBackend(fresh.sse_url, fresh.access_token));
+    });
+    printLines("Pharaoh: re-authentication required — next tool call will surface the URL.");
+    await proxy.setBackend(authBackend);
+}
 main().catch((err) => {
     // Default: print only error name/code to avoid leaking tokens, internal URLs,
     // or stack fragments that persist in CI logs. Full message behind PHARAOH_DEBUG.

package/dist/lifecycle.d.ts

@@ -7,12 +7,22 @@
  */
 import { type Credentials } from "./credentials.js";
 import { type RefreshFailureAction } from "./refresh.js";
+/** Discriminated result from tryMidSessionRefresh. */
+export type MidSessionRefreshResult = {
+    ok: true;
+    creds: Credentials;
+} | {
+    ok: false;
+    action: RefreshFailureAction;
+    message: string;
+};
 /**
  * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
- * Returns new credentials on success, null on any failure (messages already
- * printed). Caller decides whether to retry startProxy.
+ * Returns new credentials on success, or a tagged failure carrying the
+ * RefreshFailureAction so the caller can branch on the real classification
+ * instead of re-inferring from disk state.
  */
-export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<Credentials | null>;
+export declare function tryMidSessionRefresh(creds: Credentials, server: string): Promise<MidSessionRefreshResult>;
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the
  * appropriate message and creds-file state per the classified action.

package/dist/lifecycle.js

@@ -10,14 +10,15 @@ import { NPX_COMMAND, printLines } from "./helpers.js";
 import { refreshIfNeeded } from "./refresh.js";
 /**
  * Attempt a silent refresh triggered by a mid-session TokenExpiredError.
- * Returns new credentials on success, null on any failure (messages already
- * printed). Caller decides whether to retry startProxy.
+ * Returns new credentials on success, or a tagged failure carrying the
+ * RefreshFailureAction so the caller can branch on the real classification
+ * instead of re-inferring from disk state.
  */
 export async function tryMidSessionRefresh(creds, server) {
     const outcome = await refreshIfNeeded(creds, server);
     if (outcome.ok)
-        return outcome.creds;
-    // Log the failure reason before caller's exit path runs.
+        return { ok: true, creds: outcome.creds };
+    // Log the failure reason before the caller decides what to do.
     if (outcome.action === "reauth") {
         printLines("Pharaoh: refresh rejected — re-authentication required.", `  ${NPX_COMMAND}`, "");
         deleteCredentials();
@@ -27,7 +28,7 @@ export async function tryMidSessionRefresh(creds, server) {
         // the user knows their credentials file is intact (matches startup path).
         printLines(`Pharaoh: refresh failed (${outcome.action}) — ${outcome.message}`, "Credentials preserved; next startup will retry.", "");
     }
-    return null;
+    return { ok: false, action: outcome.action, message: outcome.message };
 }
 /**
  * Handle a failed `loadAndRefresh` at startup. Exits the process with the

package/dist/proxy-server.d.ts

@@ -8,11 +8,18 @@
  *
  * - 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.
+ *   The caller supplies an `onAuthorized` callback that fires from inside the
+ *   backend the moment device flow completes — the callback swaps ProxyServer
+ *   over to an SseProxyBackend in place.
  *
  * - startInSseMode: happy path — valid credentials are already on disk. Starts
  *   the server directly with an SSE backend.
+ *
+ * Lifecycle:
+ * - `waitForLifetime()` is the single awaitable the main loop blocks on. It
+ *   resolves when Claude Code disconnects (stdio transport closed) and rejects
+ *   with typed errors when the active backend hits a terminal failure. Backend
+ *   swaps happen internally via callbacks; the main loop does NOT re-await.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { type Backend } from "./backend.js";
@@ -27,6 +34,8 @@ export declare class ProxyServer {
     private transport;
     private backend;
     private started;
+    private transportClosed;
+    private transportClosedResolve;
     constructor(initialBackend: Backend);
     /**
      * Wire up list/call handlers. Each handler reads this.backend fresh at
@@ -45,6 +54,26 @@ export declare class ProxyServer {
      * Kept separate from start() so the stdio wiring stays implicit in prod.
      */
     startWithTransport(transport: StdioServerTransport): Promise<void>;
+    /**
+     * Block until either (a) the stdio transport closes cleanly (Claude Code
+     * disconnected) or (b) the current backend's supervisor promise rejects
+     * with a terminal error. Returns when the transport closes. Throws when
+     * a backend's waitForExit rejects.
+     *
+     * Swap-aware: if setBackend() is called while waitForLifetime is blocked,
+     * the old backend's exit promise is abandoned and the new backend's is
+     * awaited. This matters for "SSE → auth-required → SSE2" flows where we
+     * want errors from SSE2 to bubble up, not the already-dead SSE1.
+     */
+    waitForLifetime(): Promise<void>;
+    /**
+     * Used by setBackend to wake waitForLifetime so it can re-sample. Default
+     * no-op so a swap fired before waitForLifetime's first iteration (e.g. an
+     * onAuthorized that completes between proxy.start() and the first
+     * waitForLifetime call) doesn't crash. The missed wake is harmless — the
+     * next waitForLifetime iteration samples this.backend directly.
+     */
+    private backendSwappedSignal;
     /**
      * 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
@@ -59,12 +88,15 @@ export declare class ProxyServer {
  * 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.
+ * The caller supplies `opts.onAuthorized`, which fires from inside the
+ * AuthRequiredBackend the moment device flow completes. Typical implementation:
+ * swap the ProxyServer over to an SseProxyBackend so the next tool call goes
+ * to the real server. This keeps the proxy reference under the caller's
+ * control — the backend never imports ProxyServer.
  */
-export declare function startInAuthRequiredMode(server: string): Promise<{
+export declare function startInAuthRequiredMode(server: string, opts: {
+    onAuthorized: (creds: Credentials) => Promise<void>;
+}): Promise<{
     proxy: ProxyServer;
     gateway: DeviceFlowGateway;
 }>;

package/dist/proxy-server.js

@@ -8,11 +8,18 @@
  *
  * - 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.
+ *   The caller supplies an `onAuthorized` callback that fires from inside the
+ *   backend the moment device flow completes — the callback swaps ProxyServer
+ *   over to an SseProxyBackend in place.
  *
  * - startInSseMode: happy path — valid credentials are already on disk. Starts
  *   the server directly with an SSE backend.
+ *
+ * Lifecycle:
+ * - `waitForLifetime()` is the single awaitable the main loop blocks on. It
+ *   resolves when Claude Code disconnects (stdio transport closed) and rejects
+ *   with typed errors when the active backend hits a terminal failure. Backend
+ *   swaps happen internally via callbacks; the main loop does NOT re-await.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -29,6 +36,8 @@ export class ProxyServer {
     transport = null;
     backend;
     started = false;
+    transportClosed;
+    transportClosedResolve;
     constructor(initialBackend) {
         this.backend = initialBackend;
         this.server = new Server({ name: "pharaoh-proxy", version: getPackageVersion() }, {
@@ -36,6 +45,9 @@ export class ProxyServer {
             // to throw; the SDK's assertNotificationCapability gates it.
             capabilities: { tools: { listChanged: true } },
         });
+        this.transportClosed = new Promise((resolve) => {
+            this.transportClosedResolve = resolve;
+        });
         this.registerHandlers();
     }
     /**
@@ -64,6 +76,11 @@ export class ProxyServer {
             await this.backend.start();
         this.transport = new StdioServerTransport();
         await this.server.connect(this.transport);
+        // Server.connect() wraps transport.onclose; use the Protocol-level hook
+        // instead so we don't clobber the SDK's chain. Fires when the transport
+        // closes cleanly (client disconnect) — not on error paths, which surface
+        // through backend.waitForExit() and the server's own onerror plumbing.
+        this.server.onclose = () => this.transportClosedResolve();
         this.started = true;
     }
     /**
@@ -78,8 +95,44 @@ export class ProxyServer {
         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.server.onclose = () => this.transportClosedResolve();
         this.started = true;
     }
+    /**
+     * Block until either (a) the stdio transport closes cleanly (Claude Code
+     * disconnected) or (b) the current backend's supervisor promise rejects
+     * with a terminal error. Returns when the transport closes. Throws when
+     * a backend's waitForExit rejects.
+     *
+     * Swap-aware: if setBackend() is called while waitForLifetime is blocked,
+     * the old backend's exit promise is abandoned and the new backend's is
+     * awaited. This matters for "SSE → auth-required → SSE2" flows where we
+     * want errors from SSE2 to bubble up, not the already-dead SSE1.
+     */
+    async waitForLifetime() {
+        while (true) {
+            const swapSignal = new Promise((resolve) => {
+                this.backendSwappedSignal = () => resolve("swap");
+            });
+            const backendExit = this.backend.waitForExit?.() ?? new Promise(() => { });
+            const outcome = await Promise.race([
+                this.transportClosed.then(() => "closed"),
+                backendExit.then(() => "exit"),
+                swapSignal,
+            ]);
+            if (outcome === "swap")
+                continue; // re-sample waitForExit against the new backend
+            return; // "closed" or "exit" (the backend's waitForExit resolved cleanly)
+        }
+    }
+    /**
+     * Used by setBackend to wake waitForLifetime so it can re-sample. Default
+     * no-op so a swap fired before waitForLifetime's first iteration (e.g. an
+     * onAuthorized that completes between proxy.start() and the first
+     * waitForLifetime call) doesn't crash. The missed wake is harmless — the
+     * next waitForLifetime iteration samples this.backend directly.
+     */
+    backendSwappedSignal = () => { };
     /**
      * 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
@@ -99,15 +152,26 @@ export class ProxyServer {
         // Fire the notification after the swap so a client that races a list
         // request against it sees 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.
+        // Wake any in-flight waitForLifetime so it re-samples the new backend's
+        // waitForExit. Without this, SSE2 errors after a swap-back would be lost.
+        this.backendSwappedSignal();
+        // Fire-and-forget stop of the old backend. The swap has already happened
+        // so stop failures can't break the running session — but log them so
+        // resource leaks (file descriptors, keepalive timers, EventSource auto-
+        // reconnect surviving a failed close) are visible.
         if (prev !== next && prev.stop) {
-            prev.stop().catch(() => { });
+            prev.stop().catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Pharaoh: previous backend stop() failed — ${msg}\n`);
+            });
         }
     }
     async stop() {
         if (this.backend.stop) {
-            await this.backend.stop().catch(() => { });
+            await this.backend.stop().catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Pharaoh: backend stop() failed during shutdown — ${msg}\n`);
+            });
         }
         if (this.transport) {
             await this.server.close().catch(() => { });
@@ -124,14 +188,28 @@ export class ProxyServer {
  * 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.
+ * The caller supplies `opts.onAuthorized`, which fires from inside the
+ * AuthRequiredBackend the moment device flow completes. Typical implementation:
+ * swap the ProxyServer over to an SseProxyBackend so the next tool call goes
+ * to the real server. This keeps the proxy reference under the caller's
+ * control — the backend never imports ProxyServer.
  */
-export async function startInAuthRequiredMode(server) {
+export async function startInAuthRequiredMode(server, opts) {
     const gateway = createGateway({ server });
-    const backend = new AuthRequiredBackend(gateway);
+    const backend = new AuthRequiredBackend(gateway, async () => {
+        // Pull fresh creds from the gateway (which just wrote them to disk) so
+        // the callback doesn't race a separate disk read. The gateway is the
+        // authoritative post-auth source.
+        const creds = gateway.getCredentials();
+        if (!creds) {
+            // Should never happen — gateway.handleToolCall() only returns null
+            // after persistAuthorizedToken sets lastCreds. Keep the guard so a
+            // future refactor doesn't silently ship a swap-to-nothing bug.
+            process.stderr.write("Pharaoh: authorized but no credentials available — skipping swap\n");
+            return;
+        }
+        await opts.onAuthorized(creds);
+    });
     const proxy = new ProxyServer(backend);
     await proxy.start();
     return { proxy, gateway };

package/dist/proxy.d.ts

@@ -1,16 +1,10 @@
 /**
- * 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.
+ * Typed SSE errors + classifier. The stdio ↔ SSE wiring itself lives in
+ * backend.ts (SseProxyBackend); this module exports only the error types and
+ * the classifier so both the backend and tests can produce/assert on the
+ * same typed errors.
  *
- * 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):
+ * RECONNECTION DESIGN (implemented in backend.ts 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)
@@ -33,14 +27,13 @@ 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 in
  * backend.ts.
- */
-export declare function classifySSEError(err: Error): void;
-/**
- * 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).
  *
- * @deprecated Session C will call ProxyServer / startInSseMode directly.
+ * The fallback uses status-prefix regex patterns rather than a bare
+ * `msg.includes("401")`. Session C calls this classifier on every reconnect
+ * error (not just SSE transport onerror events), so a substring match would
+ * misclassify any unrelated error text containing "401" — e.g. a port number,
+ * a timestamp suffix, or HTML body text echoed from a proxy. The regex
+ * requires an HTTP-shaped context so only actual status codes trigger a reauth
+ * loop.
  */
-export declare function startProxy(sseUrl: string, token: string): Promise<void>;
+export declare function classifySSEError(err: Error): void;

package/dist/proxy.js

@@ -1,16 +1,10 @@
 /**
- * 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.
+ * Typed SSE errors + classifier. The stdio ↔ SSE wiring itself lives in
+ * backend.ts (SseProxyBackend); this module exports only the error types and
+ * the classifier so both the backend and tests can produce/assert on the
+ * same typed errors.
  *
- * 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):
+ * RECONNECTION DESIGN (implemented in backend.ts 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)
@@ -39,10 +33,19 @@ export class TenantSuspendedError extends Error {
  * Classify an SSE error — detect 401/403 and throw typed errors.
  * Exported for testability; used internally by the reconnect loop in
  * backend.ts.
+ *
+ * The fallback uses status-prefix regex patterns rather than a bare
+ * `msg.includes("401")`. Session C calls this classifier on every reconnect
+ * error (not just SSE transport onerror events), so a substring match would
+ * misclassify any unrelated error text containing "401" — e.g. a port number,
+ * a timestamp suffix, or HTML body text echoed from a proxy. The regex
+ * requires an HTTP-shaped context so only actual status codes trigger a reauth
+ * loop.
  */
 export function classifySSEError(err) {
     const msg = err.message ?? "";
-    // SseError from SDK includes the HTTP status code
+    // SseError from SDK includes the HTTP status code on `.code` — the
+    // authoritative signal.
     if ("code" in err) {
         const code = err.code;
         if (code === 401)
@@ -50,35 +53,15 @@ export function classifySSEError(err) {
         if (code === 403)
             throw new TenantSuspendedError(msg || "Tenant suspended");
     }
-    // Fallback: check message for status codes
-    if (msg.includes("401"))
-        throw new TokenExpiredError();
-    if (msg.includes("403"))
-        throw new TenantSuspendedError(msg || "Tenant suspended");
-}
-/**
- * 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).
- *
- * @deprecated Session C will call ProxyServer / startInSseMode directly.
- */
-export async function startProxy(sseUrl, token) {
-    // 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();
-    }
-    finally {
-        await proxy.stop().catch(() => { });
+    // Fallback regex for errors that don't expose `.code`. Matches common HTTP
+    // status renderings: "HTTP 401", "HTTP/1.1 401", "401 Unauthorized",
+    // "status 401", "status: 401" — but NOT bare "401" anywhere in the string.
+    const m = msg.match(/\b(?:HTTP(?:\/[\d.]+)?|status:?)\s+(\d{3})\b|\b(\d{3})\s+(?:Unauthorized|Forbidden)\b/i);
+    if (m) {
+        const code = Number(m[1] ?? m[2]);
+        if (code === 401)
+            throw new TokenExpiredError();
+        if (code === 403)
+            throw new TenantSuspendedError(msg || "Tenant suspended");
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "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",