@pharaoh-so/mcp 0.3.25 → 0.3.27

package/commands/plan.md

@@ -39,11 +39,12 @@ Do NOT review from memory or assumptions. Query the actual codebase first.
 ### If Pharaoh MCP tools are available:
 
 1. `get_codebase_map` — current modules, hot files, dependency graph
-2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
-3. `get_module_context` on affected modules — entry points, patterns, conventions
-4. `query_dependencies` between affected modules — coupling, circular deps
-5. `get_blast_radius` on the primary target of the change — know what breaks
-6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
+2. `get_vision_docs` — read the repo's architectural contract. If the plan touches a domain with a MUST-bullet, the assertion is a hard constraint on the plan. Raise it explicitly in Section 1. If `get_vision_docs` returns an empty-state scaffold, flag that the repo needs `/pharaoh:vision` before planning anything architectural.
+3. `search_functions` for keywords related to the plan — find existing code to reuse/extend
+4. `get_module_context` on affected modules — entry points, patterns, conventions
+5. `query_dependencies` between affected modules — coupling, circular deps
+6. `get_blast_radius` on the primary target of the change — know what breaks
+7. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
 
 ### Without Pharaoh (graceful fallback):
 
@@ -71,10 +72,17 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
+- **Vision alignment (check FIRST).** Does this plan touch a domain
+  governed by a MUST-bullet in `docs/VISION.md`? If yes, quote the
+  assertion and verify the plan doesn't violate it. If the plan would
+  violate a MUST, STOP and raise with the user — either the plan changes
+  or VISION.md needs an update first (with user approval).
 - Component boundaries and coupling concerns
 - Dependency graph: does this change shrink or expand surface area?
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
+- **If this plan introduces a new invariant**, call it out and include a
+  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 

package/commands/review.md

@@ -65,7 +65,8 @@ Then call these additional tools for data recon doesn't cover:
 - `get_regression_risk` — overall change risk score for the repo
 - `get_consolidation_opportunities` — duplicate logic the PR may introduce
 - `check_reachability` — are new exports wired to entry points?
-- `get_vision_gaps` — do changes align with or drift from specs?
+- `get_vision_docs` — read the repo's architectural contract. For every touched module, pull its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
+- `get_vision_gaps` — do changes align with or drift from specs? New complex functions without a matching assertion are flagged; retired specs with implementing code are flagged.
 
 **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, regression risk level, duplication findings, reachability status, and spec alignment.
 
@@ -249,7 +250,8 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 - Unreachable exports (new public code with zero callers)
 - New circular dependencies between modules
 - HIGH regression risk without corresponding test coverage
-- Vision spec violations (building against spec intent)
+- **A MUST-bullet in `docs/VISION.md` is violated by this change** (without VISION.md being updated in the same PR with user approval)
+- Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
 - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
 - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
 - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)

package/commands/vision.md

@@ -0,0 +1,184 @@
+---
+description: Draft a VISION.md for this repo by filling a graph-derived scaffold
+---
+
+# Vision Drafting
+
+Author a VISION.md that captures this repo's invariants — what must always be
+true about its behavior. The file becomes a machine-readable contract that
+Pharaoh's linter, PR Guard, and MCP tools reason against on every change.
+
+## Why this matters (explain this to the user before drafting)
+
+A VISION.md is leverage, not paperwork. Once the repo has one:
+
+- **PR Guard** checks every pull request against its assertions. Changes that
+  contradict a MUST-bullet surface as a Check on the PR — the team sees drift
+  from intent at the exact moment it happens, not months later.
+- **`get_vision_gaps`** becomes useful. Pharaoh cross-references every spec
+  against the function graph and surfaces both sides of the drift: specs
+  without implementing code (dead intent) and complex functions with no spec
+  (invisible invariants).
+- **`get_vision_docs`** returns spec-to-code traceability. Each assertion
+  shows the functions that implement it — a direct map from intent → code.
+- **CI enforces it.** Every MUST bullet pairs with a TEST reference. The
+  linter fails when an assertion has no enforcing test. No more wishlist
+  specs that drift over time.
+
+Without a VISION.md, the tools above return empty. The graph sees code; it
+doesn't see intent. The file is the bridge.
+
+## When to Use
+
+- The repo has no `docs/VISION.md` yet and the user wants Pharaoh's full
+  value — PR Guard, vision-gaps, spec traceability all depend on the file.
+- `get_vision_docs` returned the "No VISION.md yet" onboarding response.
+- The user said "draft a vision doc", "add a VISION.md", or "scaffold vision".
+- A user is new to Pharaoh and asking what they should do next.
+
+## The flow — collaborative, not solo
+
+This is a short working session with the user. Do not solo-fill the scaffold
+— the graph can tell you the shape of the code, but only the user knows what
+must not break. Ask questions, propose, let them steer.
+
+1. **Get the scaffold.** Call `get_vision_docs` with the repo name. When no
+   vision doc exists, the tool returns a deterministic scaffold plus the
+   agent directive. Use that as your starting structure. Never invent a
+   scaffold from scratch; the archetypes encode Pharaoh's framework shape
+   and drift is surfaced by the framework-linter.
+
+2. **Interview the user.** Before filling anything, ask: *"What are the 3-5
+   things about this repo that must not break, no matter what?"* Their
+   answer drives the assertions. If they can't articulate it, probe with
+   follow-ups — "what would a P0 incident look like here?", "what would
+   wake you up on a weekend?". The goal is to extract real invariants, not
+   to generate plausible-sounding ones from graph evidence.
+
+3. **Ground each domain in real code.** For every `## Domain` the scaffold
+   rendered, call `get_module_context` for the module(s) that back that
+   domain. For example, an "Authentication and Authorization" domain →
+   `get_module_context` on the auth module + any session/token modules.
+   Read the exported functions, endpoints, env vars, and DB access.
+
+4. **Replace TODOs with WHAT statements.**
+   - Every `### TODO:` heading becomes a real assertion title. Describe the
+     invariant in plain language — "Sessions expire after 30 minutes of
+     inactivity", not "checkSession() returns null after timeout".
+   - Every `- MUST: TODO —` bullet becomes a WHAT statement. Banned
+     content: function names, file paths, class names, identifiers.
+   - Add a `- TEST: path/to/test.ts` line for every assertion. If the test
+     doesn't exist yet, write it before committing. A MUST without a TEST
+     is not an invariant, it's a wish.
+
+5. **Trim irrelevant domains.** If a rendered `## Domain` doesn't match
+   anything real in this repo, delete that whole section. The scaffold is a
+   starting point, not a contract to honor exhaustively.
+
+6. **Write the file.** Save to `docs/VISION.md` in the repo. Remove the
+   `<!-- scaffold-generated -->` marker and the `<!-- AGENT DIRECTIVE -->`
+   block once every TODO is resolved.
+
+7. **Wire it into CLAUDE.md.** This is non-negotiable — it's what turns the
+   vision doc from a file on disk into a contract future sessions respect.
+   If `CLAUDE.md` exists at the repo root, append (or edit) a section:
+
+   ```markdown
+   ## Vision docs
+
+   `docs/VISION.md` is this repo's architectural contract. Before any
+   non-trivial change, call `get_vision_docs` to read the relevant
+   assertions. After any large refactor, run `get_vision_gaps` to surface
+   drift between intent and implementation. When adding a new invariant,
+   open `docs/VISION.md`, add a `### assertion` under the right `##` domain,
+   and pair every `- MUST:` with a `- TEST:` referencing the enforcing test.
+
+   Never introduce code that would violate a MUST-bullet without first
+   updating `docs/VISION.md` (with the user's approval).
+   ```
+
+   If no `CLAUDE.md` exists, create a minimal one with the section above
+   plus any project-specific instructions you already have context for.
+
+8. **Verify.** Run `pharaoh vision lint --framework` (or instruct the user
+   to). Zero errors. Zero TODO warnings. Zero unresolved placeholders.
+
+## Hard rules
+
+- **No HOW in MUST bullets.** Banned: function names, file paths, camelCase
+  identifiers, backtick-wrapped code. The linter enforces this as a warning;
+  treat it as a hard rule.
+- **Every MUST needs a TEST.** The format-linter errors if a MUST bullet
+  has no matching TEST reference to an existing file.
+- **One MUST per line.** Don't pack multiple invariants into a single bullet.
+- **Max 10 prose lines per assertion.** Keep each `###` section tight.
+- **Mirror Pharaoh's canonical domains when they fit.** Rename only when the
+  user's project truly has a different shape. The framework-linter warns on
+  unrecognized domains so drift is visible.
+
+## What to avoid
+
+- **Do NOT** write VISION.md from scratch without calling `get_vision_docs`
+  first — you'll miss domains the graph detected and duplicate ones it
+  already included.
+- **Do NOT** carry forward the AGENT DIRECTIVE or scaffold-generated marker
+  into the committed file. Those are drafting aids, not document content.
+- **Do NOT** write speculative assertions ("sessions will expire someday").
+  Only assert what the code enforces today or what you'll commit a test for.
+- **Do NOT** use `pharaoh vision init` — that only drops the format guide,
+  not a graph-grounded scaffold. Always go through `get_vision_docs`.
+
+## Completion checklist
+
+- [ ] User was interviewed for their real invariants (not graph-guessed)
+- [ ] Every rendered `## Domain` either has ≥1 real assertion or was deleted
+- [ ] Every `### TODO:` heading replaced with a real title
+- [ ] Every `- MUST: TODO —` replaced with a WHAT statement
+- [ ] Every assertion has a `- TEST:` line pointing at an existing test file
+- [ ] Scaffold marker + AGENT DIRECTIVE block removed
+- [ ] `CLAUDE.md` updated (or created) with the Vision docs section
+- [ ] `pharaoh vision lint --framework` exits clean
+
+## After it ships — tell the user what they unlocked
+
+Once `docs/VISION.md` is committed, call out the new capabilities concretely:
+
+1. **Every future AI session reads it.** Because CLAUDE.md now references
+   `docs/VISION.md`, any agent working in this repo (Claude Code, Cursor,
+   anyone else connecting Pharaoh) will consult the file before touching
+   architecture. Continuity across sessions, across people, across tools.
+2. **`get_vision_docs`** now returns spec-to-code traceability per
+   assertion. The user can see which functions implement each invariant.
+3. **`get_vision_gaps`** surfaces drift. Unspecified complex functions
+   get flagged; specs with no implementing code get flagged for review
+   (either write the code or retire the spec).
+4. **Their next PR is checked.** PR Guard now evaluates touched code
+   against relevant assertions. First-time use often catches real drift.
+5. **`/pharaoh:plan`** will surface relevant assertions during reconnaissance.
+6. **`/pharaoh:review`** will flag PRs that touch code governed by a MUST.
+
+The bigger payoff: architectural invariants are now enforced in CI the same
+way unit tests enforce behavior. Intent and implementation stop drifting.
+
+## Ongoing maintenance — it's a living file
+
+VISION.md rots if it's not maintained. Part of your job in future sessions
+(even ones that aren't about vision directly) is to keep it current:
+
+- **When a MUST changes**, update VISION.md in the same PR as the code
+  change. Don't let the file lag — stale assertions are worse than none.
+- **When a new architectural decision lands**, add a new `###` assertion
+  under the right `##` domain with a pairing TEST. One assertion per
+  decision, not batches.
+- **When an assertion stops being load-bearing**, delete it. Retirement is
+  as important as addition.
+- **When `get_vision_gaps` shows >5 unimplemented specs**, the doc has
+  drifted into wishlist territory. Prune.
+- **Quarterly**: run `pharaoh vision lint --framework` and address warnings.
+
+Format reference: https://pharaoh.so/vision-format.md
+---
+
+Here is any additional context for the vision draft:
+
+$ARGUMENTS

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/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.