pi-mcp-extension 1.9.3 → 1.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/auth-challenge.ts

@@ -17,6 +17,31 @@ export interface ManualAuthChallengeOptions {
   fetchFn?: AuthChallengeFetch | undefined;
   timeoutMs?: number | undefined;
   headers?: Record<string, string> | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+/**
+ * Wrap a fetch implementation so configured server headers are attached as
+ * defaults on every request (e.g. during SDK OAuth metadata discovery and
+ * token exchange) without overriding explicit per-request headers.
+ */
+export function createHeadersFetch(
+  baseHeaders?: Record<string, string>,
+  baseFetch: typeof fetch = fetch,
+): typeof fetch {
+  if (!baseHeaders || Object.keys(baseHeaders).length === 0) {
+    return baseFetch;
+  }
+  return async (input, init) => {
+    const merged = new Headers(baseHeaders);
+    if (init?.headers) {
+      const incoming = new Headers(init.headers);
+      incoming.forEach((value, key) => {
+        merged.set(key, value);
+      });
+    }
+    return baseFetch(input, { ...init, headers: merged });
+  };
 }
 
 /**
@@ -32,14 +57,33 @@ export async function discoverManualAuthChallenge(
   options: ManualAuthChallengeOptions = {},
 ): Promise<ManualAuthChallenge> {
   const fetchFn = options.fetchFn ?? fetch;
+  const timeoutSignal = AbortSignal.timeout(options.timeoutMs ?? AUTH_CHALLENGE_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
   const headers = new Headers(options.headers);
   headers.set("Accept", "application/json, text/event-stream");
-  const response = await fetchFn(serverUrl, {
+  let response = await fetchFn(serverUrl, {
     method: "GET",
     headers,
-    signal: AbortSignal.timeout(options.timeoutMs ?? AUTH_CHALLENGE_TIMEOUT_MS),
+    signal,
   });
 
+  if (response.status === 405) {
+    // WHY: Streamable HTTP MCP servers may only accept POST and return 405 on GET without
+    // a WWW-Authenticate challenge. Probe with a minimal JSON-RPC ping POST to elicit 401/403.
+    await response.body?.cancel().catch(() => {
+      // WHY: Body cancel errors during challenge probe cleanup are non-fatal.
+    });
+    const postHeaders = new Headers(options.headers);
+    postHeaders.set("Accept", "application/json, text/event-stream");
+    postHeaders.set("Content-Type", "application/json");
+    response = await fetchFn(serverUrl, {
+      method: "POST",
+      headers: postHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "ping", id: 0 }),
+      signal,
+    });
+  }
+
   try {
     if (response.status !== 401 && response.status !== 403) {
       return {};
@@ -55,6 +99,8 @@ export async function discoverManualAuthChallenge(
       ...(scope ? { scope } : {}),
     };
   } finally {
-    await response.body?.cancel().catch(() => {});
+    await response.body?.cancel().catch(() => {
+      // WHY: Body cancel errors during challenge probe cleanup are non-fatal.
+    });
   }
 }

package/src/auth-lock.ts

@@ -91,7 +91,7 @@ export interface AuthLockTimer {
 export interface AuthLockClock {
   now(): number;
   setInterval(callback: () => void, ms: number): ReturnType<typeof setInterval> | AuthLockTimer;
-  clearInterval(timer: any): void;
+  clearInterval(timer: ReturnType<typeof setInterval> | AuthLockTimer): void;
 }
 
 export interface AuthLockDeps {
@@ -108,6 +108,7 @@ export interface AcquireAuthLockOptions {
 }
 
 export type AuthLockHandle = (() => Promise<void>) & {
+  unlock: () => Promise<void>;
   assertHeld: () => Promise<void>;
   isLost: () => boolean;
 };
@@ -153,7 +154,7 @@ export function createDefaultAuthLockDeps(): AuthLockDeps {
     clock: {
       now: () => Date.now(),
       setInterval: (cb, ms) => setInterval(cb, ms),
-      clearInterval: (timer) => clearInterval(timer),
+      clearInterval: (timer) => clearInterval(timer as ReturnType<typeof setInterval>),
     },
     pid: process.pid,
     hostname: osHostname(),
@@ -204,6 +205,33 @@ function formatHolderDetails(record: LockRecord | null): string | undefined {
 
 const MAX_ACQUIRE_ATTEMPTS = 3;
 
+async function readLockRecordWithRetry(
+  fs: AuthLockFs,
+  path: string,
+  usingRealFs = false,
+): Promise<LockRecord | null> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      const raw = await fs.readFile(path, "utf8");
+      return parseLockRecord(raw);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT" && i < 2) {
+        // WHY: During stale-lock inspection, a contender briefly renames `path` to
+        // `movedPath` and restores it via `link(movedPath, path)` on nonce mismatch.
+        // Yield across microtasks (and a brief macrotask on real fs) before treating ENOENT as genuine lock loss.
+        await Promise.resolve();
+        await Promise.resolve();
+        if (usingRealFs && i === 1) {
+          await new Promise<void>((resolve) => setTimeout(resolve, 5));
+        }
+        continue;
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
 export async function acquireAuthLock(
   serverName: string,
   storageDir?: string,
@@ -239,8 +267,12 @@ export async function acquireAuthLock(
         await file.writeFile(JSON.stringify(myRecord));
         await file.sync();
       } catch (writeErr) {
-        await file.close().catch(() => {});
-        await deps.fs.unlink(path).catch(() => {});
+        await file.close().catch(() => {
+          // WHY: Best-effort file handle close after write failure.
+        });
+        await deps.fs.unlink(path).catch(() => {
+          // WHY: Best-effort cleanup of partially written lock file before rethrowing writeErr.
+        });
         throw writeErr;
       }
       await file.close();
@@ -257,7 +289,9 @@ export async function acquireAuthLock(
       };
 
       const onExit = () => {
-        if (released || lost || !usingRealFs) return;
+        // WHY: Do not skip cleanup when `lost` is true — if a contender restored our
+        // lock file via `link()` after a transient rename, we must still unlink our own nonce.
+        if (released || !usingRealFs) return;
         try {
           const raw = readFileSync(path, "utf8");
           const current = parseLockRecord(raw);
@@ -265,7 +299,7 @@ export async function acquireAuthLock(
             unlinkSync(path);
           }
         } catch {
-          // Best-effort cleanup on process exit
+          // WHY: Best-effort synchronous cleanup on process exit; lock file may already be unlinked.
         }
       };
 
@@ -273,7 +307,6 @@ export async function acquireAuthLock(
         if (lost || released) return;
         lost = true;
         stopHeartbeat();
-        process.removeListener("exit", onExit);
         options?.onLost?.();
       };
 
@@ -281,13 +314,7 @@ export async function acquireAuthLock(
 
       heartbeatTimer = deps.clock.setInterval(async () => {
         if (released || lost) return;
-        let current: LockRecord | null = null;
-        try {
-          const raw = await deps.fs.readFile(path, "utf8");
-          current = parseLockRecord(raw);
-        } catch {
-          current = null;
-        }
+        const current = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
         if (released || lost) return;
         if (!current || current.nonce !== myRecord.nonce) {
           markLost();
@@ -298,7 +325,15 @@ export async function acquireAuthLock(
           await deps.fs.utimes(path, nowSec, nowSec);
         } catch {
           if (!released && !lost) {
-            markLost();
+            const after = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
+            if (!after || after.nonce !== myRecord.nonce) {
+              markLost();
+            } else {
+              await deps.fs.utimes(path, nowSec, nowSec).catch(() => {
+                // WHY: If utimes still fails after verifying the restored lock nonce, mark lock lost.
+                if (!released && !lost) markLost();
+              });
+            }
           }
         }
       }, HEARTBEAT_MS);
@@ -308,13 +343,7 @@ export async function acquireAuthLock(
         if (lost || released) {
           throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
         }
-        let current: LockRecord | null = null;
-        try {
-          const raw = await deps.fs.readFile(path, "utf8");
-          current = parseLockRecord(raw);
-        } catch {
-          current = null;
-        }
+        const current = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
         if (!current || current.nonce !== myRecord.nonce) {
           markLost();
           throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
@@ -326,20 +355,18 @@ export async function acquireAuthLock(
         released = true;
         stopHeartbeat();
         process.removeListener("exit", onExit);
-        if (lost) return;
-        let current: LockRecord | null = null;
-        try {
-          const raw = await deps.fs.readFile(path, "utf8");
-          current = parseLockRecord(raw);
-        } catch {
-          current = null;
-        }
+        // WHY: Always check and unlink if the file on disk still carries our nonce, even if
+        // `lost` was set during a contender's temporary stale-check rename+link window.
+        const current = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
         if (current && current.nonce === myRecord.nonce) {
-          await deps.fs.unlink(path).catch(() => {});
+          await deps.fs.unlink(path).catch(() => {
+            // WHY: Best-effort lock removal on unlock; ignore ENOENT if concurrently removed.
+          });
         }
       };
 
       return Object.assign(unlock, {
+        unlock,
         assertHeld,
         isLost: () => lost,
       });
@@ -410,12 +437,18 @@ export async function acquireAuthLock(
       }
 
       if (matchesStale) {
-        await deps.fs.unlink(movedPath).catch(() => {});
+        await deps.fs.unlink(movedPath).catch(() => {
+          // WHY: Best-effort removal of reclaimed stale lock file.
+        });
         continue;
       }
 
-      await deps.fs.link(movedPath, path).catch(() => {});
-      await deps.fs.unlink(movedPath).catch(() => {});
+      await deps.fs.link(movedPath, path).catch(() => {
+        // WHY: Best-effort restore of contender's fresh lock file if path was not already recreated.
+      });
+      await deps.fs.unlink(movedPath).catch(() => {
+        // WHY: Best-effort cleanup of temporary stale-check file.
+      });
       throw new AuthLockError(serverName, formatHolderDetails(movedRecord));
     }
   }

package/src/index.ts

@@ -33,7 +33,7 @@ import {
 import { CallbackUrlValidationError, isSafeAuthorizationUrl, parseCallbackUrl } from "./callback-url.js";
 import { setCallbackPort, McpOAuthProvider, acquireAuthLock, type AuthLockHandle } from "./oauth-provider.js";
 import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
-import { discoverManualAuthChallenge } from "./auth-challenge.js";
+import { discoverManualAuthChallenge, createHeadersFetch } from "./auth-challenge.js";
 import type { ManualAuthChallenge } from "./auth-challenge.js";
 
 export interface BrowserOpenCommand {
@@ -487,6 +487,9 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
     });
   });
   manager.setServerStoppedCallback((name) => bridge.deactivateServer(name));
+  bridge.setAuthErrorCallback(async (serverName, err) => {
+    await manager.handleUnauthorizedServerError(serverName, err);
+  });
 
   // ── 3. Session lifecycle ──────────────────────────────────────────────────
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
@@ -731,6 +734,8 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           host: callbackServerConfig.host,
           allowPortFallback: callbackServerConfig.allowPortFallback,
         });
+        if (signal.aborted) throw new AuthCancelledError(serverName);
+        if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
         setCallbackPort(port);
 
         // 2. Generate a cryptographically secure state parameter for CSRF protection
@@ -771,8 +776,28 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           false,
           () => signal.aborted,
           () => unlock!.assertHeld(),
+          config.url,
         );
 
+        if (!reset) {
+          // WHY: authorize() is only entered after silent connect failed with AuthRequiredError.
+          // If a refresh_token remained on disk (e.g. accepted by the Authorization Server
+          // while the Resource Server rejects the refreshed access token), the SDK's auth()
+          // would silently refresh and return "AUTHORIZED" without opening the browser.
+          // Clear stored tokens while preserving clientInfo and discoveryState.
+          try {
+            await authProvider.invalidateCredentials("tokens");
+          } catch (err) {
+            if (err instanceof McpError && err.code === "config" && /Corrupt OAuth state file/i.test(err.message)) {
+              console.error(`[pi-mcp] ${err.message}`);
+            } else {
+              throw err;
+            }
+          }
+          if (signal.aborted) throw new AuthCancelledError(serverName);
+          if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
+        }
+
         // Why set state before calling auth(): the SDK reads provider.state() while
         // building the authorization URL inside auth(), and omits the state parameter
         // if empty, which the callback server then rejects as a CSRF error.
@@ -781,23 +806,33 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
         // 4. Discover protected-resource challenge metadata from the server.
         const authChallenge: ManualAuthChallenge = await discoverManualAuthChallenge(config.url, {
           headers: config.headers,
+          signal,
         }).catch((): ManualAuthChallenge => {
+          if (signal.aborted) {
+            throw new AuthCancelledError(serverName);
+          }
           console.warn(
             `[pi-mcp] Failed to discover OAuth challenge for "${serverName}"; falling back to standard discovery`,
           );
           return {};
         });
+        if (signal.aborted) throw new AuthCancelledError(serverName);
+        if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
 
         // 5. Register the callback immediately before auth() can open the browser.
         // Attach a catch handler so cancellation after immediate authorization
         // does not produce an unhandled rejection.
         const callbackPromise = waitForCallback(oauthState);
-        callbackPromise.catch(() => {});
+        callbackPromise.catch(() => {
+          // WHY: Suppress unhandled rejection when callbackPromise is cancelled after immediate authorization.
+        });
 
+        const customFetch = config.headers ? createHeadersFetch(config.headers) : undefined;
         const authOptions: {
           serverUrl: string;
           resourceMetadataUrl?: URL;
           scope?: string;
+          fetchFn?: typeof fetch;
         } = { serverUrl: config.url };
         if (authChallenge.resourceMetadataUrl) {
           authOptions.resourceMetadataUrl = authChallenge.resourceMetadataUrl;
@@ -805,13 +840,28 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
         if (authChallenge.scope) {
           authOptions.scope = authChallenge.scope;
         }
+        if (customFetch) {
+          authOptions.fetchFn = customFetch;
+        }
 
         // 6. Start the auth flow.
         // Why branch on the return value: the SDK auth() call returns "AUTHORIZED" when
         // stored or refreshed tokens already succeeded without opening a browser, or
         // "REDIRECT" after invoking redirectToAuthorization(), in which case we must
         // wait for the callback code and call auth() a second time with authorizationCode.
-        const authResult = await auth(authProvider, authOptions);
+        let authResult: "AUTHORIZED" | "REDIRECT";
+        try {
+          authResult = await auth(authProvider, authOptions);
+        } catch (err) {
+          if (err instanceof McpError && err.code === "config" && /Corrupt OAuth state file/i.test(err.message)) {
+            // WHY: McpOAuthProvider._loadState() backed up and removed the corrupt state file.
+            // Retry auth() once so interactive authorization proceeds cleanly.
+            console.error(`[pi-mcp] ${err.message}`);
+            authResult = await auth(authProvider, authOptions);
+          } else {
+            throw err;
+          }
+        }
         if (signal.aborted) throw new AuthCancelledError(serverName);
         if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
 
@@ -852,6 +902,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
             authorizationCode: string;
             resourceMetadataUrl?: URL;
             scope?: string;
+            fetchFn?: typeof fetch;
           } = {
             serverUrl: config.url,
             authorizationCode: code,
@@ -862,8 +913,13 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           if (authChallenge.scope) {
             finishAuthOptions.scope = authChallenge.scope;
           }
+          if (customFetch) {
+            finishAuthOptions.fetchFn = customFetch;
+          }
 
           const finishAuthResult = await auth(authProvider, finishAuthOptions);
+          if (signal.aborted) throw new AuthCancelledError(serverName);
+          if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);
 
           if (finishAuthResult !== "AUTHORIZED") {
             throw new McpError(
@@ -1027,11 +1083,28 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
     parameters: Type.Object({}),
     async execute() {
       const rows = await Promise.all(manager.getAllServers().map(async (server) => {
-        const auth = server.config.auth ? await manager.getServerAuthStatus(server.name) : null;
+        let auth: Awaited<ReturnType<typeof manager.getServerAuthStatus>> = null;
+        let authCorrupt = false;
+        if (server.config.auth) {
+          try {
+            auth = await manager.getServerAuthStatus(server.name);
+          } catch (err) {
+            // WHY: Never let a single server's corrupt state file abort mcp_status for all servers.
+            // getAuthStatus() already backed up and deleted the corrupt file before throwing.
+            console.error(`[pi-mcp] ${err instanceof Error ? err.message : String(err)}`);
+            authCorrupt = true;
+          }
+        }
         return {
           name: server.name, lifecycle: server.config.lifecycle, state: server.state,
           tools: bridge.getToolActivity(server.name),
-          auth: server.config.auth ? auth?.hasTokens ? "credentials stored" : "authorization may be required" : "not configured",
+          auth: server.config.auth
+            ? authCorrupt
+              ? "corrupt state file backed up (re-auth required)"
+              : auth?.hasTokens
+                ? "credentials stored"
+                : "authorization may be required"
+            : "not configured",
           error: server.lastError
             ? server.lastError instanceof AuthRequiredError
               ? "Authorization required: use mcp_connect in an interactive Pi session"
@@ -1082,6 +1155,12 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       const { name, reset } = parseAuthArguments(args, manager.getAllServers().map((server) => server.name));
       if (!name) { ctx.ui.notify("Usage: /mcp:auth <name> [--reset]", "error"); return; }
       if (!manager.getServer(name)?.config.auth) { ctx.ui.notify(`No OAuth server named ${name}`, "error"); return; }
+      if (!reset && manager.getServer(name)?.state === "ready") {
+        // WHY: Explicit /mcp:auth on an already-ready server must tear down the existing
+        // connection and force a fresh reconnect/auth check rather than returning a no-op.
+        bridge.deactivateServer(name);
+        await manager.stopServer(name);
+      }
       try { await connectRequested(name, ctx, undefined, reset); ctx.ui.notify(`pi-mcp: ${name} ready`, "info"); }
       catch (err) {
         ctx.ui.notify(`pi-mcp: ${err instanceof Error ? err.message : String(err)}`, err instanceof AuthCancelledError ? "info" : "error");

package/src/oauth-provider.ts

@@ -68,11 +68,46 @@ export function getCallbackPort(): number {
   return callbackPort;
 }
 
+// ─── URL Canonicalization & Origin-Binding Helpers ────────────────────────────
+
+export function canonicalServerUrl(rawUrl: string): string {
+  try {
+    const u = new URL(rawUrl);
+    const path = u.pathname.length > 1 ? u.pathname.replace(/\/+$/, "") : u.pathname;
+    return `${u.origin}${path}${u.search}`;
+  } catch {
+    return rawUrl.trim();
+  }
+}
+
+export function urlsMatch(storedUrl: string, expectedUrl: string): boolean {
+  return canonicalServerUrl(storedUrl) === canonicalServerUrl(expectedUrl);
+}
+
+function isResourceCompatibleWithServerUrl(resource: string, expectedServerUrl: string): boolean {
+  if (urlsMatch(resource, expectedServerUrl)) return true;
+  try {
+    const req = new URL(canonicalServerUrl(expectedServerUrl));
+    const cfg = new URL(canonicalServerUrl(resource));
+    if (req.origin !== cfg.origin) return false;
+    if (req.pathname.length < cfg.pathname.length) return false;
+    const reqPath = req.pathname.endsWith("/") ? req.pathname : `${req.pathname}/`;
+    const cfgPath = cfg.pathname.endsWith("/") ? cfg.pathname : `${cfg.pathname}/`;
+    return reqPath.startsWith(cfgPath);
+  } catch {
+    return false;
+  }
+}
+
 // ─── Persistent State Types & Schema ──────────────────────────────────────────
 
 interface StoredClientInfo {
   client_id: string;
   client_secret: string | undefined;
+  client_id_issued_at: number | undefined;
+  client_secret_expires_at: number | undefined;
+  token_endpoint_auth_method: string | undefined;
+  redirect_uris: string[] | undefined;
 }
 
 interface StoredTokens {
@@ -86,6 +121,7 @@ interface StoredTokens {
 }
 
 interface StoredState {
+  serverUrl?: string | undefined;
   clientInfo: StoredClientInfo | undefined;
   tokens: StoredTokens | undefined;
   discoveryState: OAuthDiscoveryState | undefined;
@@ -94,6 +130,10 @@ interface StoredState {
 const StoredClientInfoSchema = z.object({
   client_id: z.string(),
   client_secret: z.string().optional(),
+  client_id_issued_at: z.number().optional(),
+  client_secret_expires_at: z.number().optional(),
+  token_endpoint_auth_method: z.string().optional(),
+  redirect_uris: z.array(z.string()).optional(),
 });
 
 const StoredTokensSchema = z.object({
@@ -106,6 +146,7 @@ const StoredTokensSchema = z.object({
 });
 
 export const StoredStateSchema = z.object({
+  serverUrl: z.string().optional(),
   clientInfo: StoredClientInfoSchema.optional(),
   tokens: StoredTokensSchema.optional(),
   discoveryState: z.record(z.unknown()).optional(),
@@ -113,7 +154,11 @@ export const StoredStateSchema = z.object({
 
 // ─── File helpers ─────────────────────────────────────────────────────────────
 
-async function loadState(serverName: string, storageDir?: string): Promise<StoredState> {
+async function loadState(
+  serverName: string,
+  storageDir?: string,
+  expectedServerUrl?: string,
+): Promise<StoredState> {
   const path = statePath(serverName, storageDir);
   let raw: string;
   try {
@@ -121,6 +166,7 @@ async function loadState(serverName: string, storageDir?: string): Promise<Store
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === "ENOENT") {
       return {
+        serverUrl: expectedServerUrl ? canonicalServerUrl(expectedServerUrl) : undefined,
         clientInfo: undefined,
         tokens: undefined,
         discoveryState: undefined,
@@ -144,11 +190,47 @@ async function loadState(serverName: string, storageDir?: string): Promise<Store
     );
   }
 
+  let discoveryState = parsed.discoveryState as OAuthDiscoveryState | undefined;
+
+  if (expectedServerUrl !== undefined) {
+    // WHY: Bind OAuth state to the canonical server URL so a project config with the same
+    // server name cannot inherit global Bearer tokens for a different origin/path.
+    if (parsed.serverUrl !== undefined && !urlsMatch(parsed.serverUrl, expectedServerUrl)) {
+      return {
+        serverUrl: canonicalServerUrl(expectedServerUrl),
+        clientInfo: undefined,
+        tokens: undefined,
+        discoveryState: undefined,
+      };
+    }
+
+    const resource = (discoveryState?.resourceMetadata as { resource?: unknown } | undefined)?.resource;
+    if (typeof resource === "string" && !isResourceCompatibleWithServerUrl(resource, expectedServerUrl)) {
+      if (parsed.serverUrl === undefined) {
+        // Legacy state file without top-level serverUrl whose cached resourceMetadata belongs to another server URL
+        return {
+          serverUrl: canonicalServerUrl(expectedServerUrl),
+          clientInfo: undefined,
+          tokens: undefined,
+          discoveryState: undefined,
+        };
+      }
+      // WHY: Discard mismatched discoveryState so the MCP SDK's selectResourceURL()
+      // never throws "Protected resource ... does not match expected".
+      discoveryState = undefined;
+    }
+  }
+
   return {
+    serverUrl: parsed.serverUrl ?? (expectedServerUrl ? canonicalServerUrl(expectedServerUrl) : undefined),
     clientInfo: parsed.clientInfo
       ? {
           client_id: parsed.clientInfo.client_id,
           client_secret: parsed.clientInfo.client_secret,
+          client_id_issued_at: parsed.clientInfo.client_id_issued_at,
+          client_secret_expires_at: parsed.clientInfo.client_secret_expires_at,
+          token_endpoint_auth_method: parsed.clientInfo.token_endpoint_auth_method,
+          redirect_uris: parsed.clientInfo.redirect_uris,
         }
       : undefined,
     tokens: parsed.tokens
@@ -161,7 +243,7 @@ async function loadState(serverName: string, storageDir?: string): Promise<Store
           saved_at: parsed.tokens.saved_at,
         }
       : undefined,
-    discoveryState: parsed.discoveryState as OAuthDiscoveryState | undefined,
+    discoveryState,
   };
 }
 
@@ -176,6 +258,7 @@ async function saveState(
   await chmod(directory, 0o700);
   // Only write defined fields (never write codeVerifier to shared state)
   const toWrite: Record<string, unknown> = {};
+  if (state.serverUrl !== undefined) toWrite.serverUrl = state.serverUrl;
   if (state.clientInfo !== undefined) toWrite.clientInfo = state.clientInfo;
   if (state.tokens !== undefined) toWrite.tokens = state.tokens;
   if (state.discoveryState !== undefined) toWrite.discoveryState = state.discoveryState;
@@ -186,13 +269,17 @@ async function saveState(
     await writeFile(tmpPath, JSON.stringify(toWrite, null, 2), { encoding: "utf8", mode: 0o600 });
     await chmod(tmpPath, 0o600);
     if (isCancelled()) {
-      await unlink(tmpPath).catch(() => {});
+      await unlink(tmpPath).catch(() => {
+        // WHY: Best-effort cleanup of temporary state file when cancelled before rename.
+      });
       throw new AuthRequiredError(serverName, "Authorization cancelled");
     }
     await rename(tmpPath, path);
     await chmod(path, 0o600);
   } catch (err) {
-    await unlink(tmpPath).catch(() => {});
+    await unlink(tmpPath).catch(() => {
+      // WHY: Best-effort cleanup of temporary state file after write or rename failure.
+    });
     throw err;
   }
 }
@@ -207,6 +294,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
   private _oauthState: string | undefined;
   private _codeVerifier: string | undefined;
   private _cachedTokens: StoredTokens | undefined;
+  private _lastReadTokens: StoredTokens | undefined;
+  private _reloadedPeerTokens = false;
 
   constructor(
     serverName: string,
@@ -216,6 +305,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
     private readonly silent = false,
     private readonly isCancelled: () => boolean = () => false,
     private readonly assertLockHeld?: (() => Promise<void>) | undefined,
+    private readonly serverUrl?: string | undefined,
   ) {
     this.serverName = serverName;
     this.authConfig = authConfig;
@@ -256,12 +346,45 @@ export class McpOAuthProvider implements OAuthClientProvider {
       };
     }
     // Otherwise load from persisted DCR state
-    const state = await loadState(this.serverName, this.storageDir);
-    if (state.clientInfo) {
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    const info = state.clientInfo;
+    if (info) {
+      if (
+        info.client_secret !== undefined &&
+        typeof info.client_secret_expires_at === "number" &&
+        info.client_secret_expires_at > 0 &&
+        info.client_secret_expires_at * 1000 <= Date.now()
+      ) {
+        if (this.silent) {
+          throw new AuthRequiredError(
+            this.serverName,
+            "Stored OAuth client secret has expired; interactive re-authentication required",
+          );
+        }
+        return undefined;
+      }
+      if (
+        !this.silent &&
+        Array.isArray(info.redirect_uris) &&
+        info.redirect_uris.length > 0 &&
+        !info.redirect_uris.includes(String(this.redirectUrl))
+      ) {
+        // WHY: If the callback port or configured redirectUrl changed since DCR,
+        // return undefined in interactive mode so the SDK re-registers with the new redirect_uri.
+        return undefined;
+      }
       return {
-        client_id: state.clientInfo.client_id,
-        ...(state.clientInfo.client_secret && { client_secret: state.clientInfo.client_secret }),
-      };
+        client_id: info.client_id,
+        ...(info.client_secret !== undefined && { client_secret: info.client_secret }),
+        ...(info.client_id_issued_at !== undefined && { client_id_issued_at: info.client_id_issued_at }),
+        ...(info.client_secret_expires_at !== undefined && {
+          client_secret_expires_at: info.client_secret_expires_at,
+        }),
+        ...(info.token_endpoint_auth_method !== undefined && {
+          token_endpoint_auth_method: info.token_endpoint_auth_method,
+        }),
+        ...(info.redirect_uris !== undefined && { redirect_uris: info.redirect_uris }),
+      } as OAuthClientInformationMixed;
     }
     if (this.silent) throw new AuthRequiredError(this.serverName);
     return undefined;
@@ -272,10 +395,30 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void> {
     if (this.silent) throw new AuthRequiredError(this.serverName);
     await this.assertLockHeld?.();
-    const state = await loadState(this.serverName, this.storageDir);
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    if (this.serverUrl) {
+      state.serverUrl = canonicalServerUrl(this.serverUrl);
+    }
+    const fullInfo = clientInformation as Partial<{
+      client_id_issued_at: number;
+      client_secret_expires_at: number;
+      token_endpoint_auth_method: string;
+      redirect_uris: Array<string | URL>;
+    }>;
     state.clientInfo = {
       client_id: clientInformation.client_id,
       client_secret: clientInformation.client_secret,
+      client_id_issued_at:
+        typeof fullInfo.client_id_issued_at === "number" ? fullInfo.client_id_issued_at : undefined,
+      client_secret_expires_at:
+        typeof fullInfo.client_secret_expires_at === "number" ? fullInfo.client_secret_expires_at : undefined,
+      token_endpoint_auth_method:
+        typeof fullInfo.token_endpoint_auth_method === "string"
+          ? fullInfo.token_endpoint_auth_method
+          : undefined,
+      redirect_uris: Array.isArray(fullInfo.redirect_uris)
+        ? fullInfo.redirect_uris.map((u) => String(u))
+        : undefined,
     };
     await this.assertLockHeld?.();
     await saveState(this.serverName, state, this.storageDir, this.isCancelled);
@@ -284,8 +427,10 @@ export class McpOAuthProvider implements OAuthClientProvider {
   // --- tokens ---
 
   async tokens(): Promise<OAuthTokens | undefined> {
-    const storedTokens = this._cachedTokens ?? (await loadState(this.serverName, this.storageDir)).tokens;
+    const storedTokens =
+      this._cachedTokens ?? (await loadState(this.serverName, this.storageDir, this.serverUrl)).tokens;
     if (!storedTokens) return undefined;
+    this._lastReadTokens = storedTokens;
 
     // Always return stored tokens — even if expired.
     // The SDK's auth() function checks tokens?.refresh_token and attempts
@@ -302,11 +447,13 @@ export class McpOAuthProvider implements OAuthClientProvider {
     //   → user must re-authenticate in browser
 
     // Build OAuthTokens — only include defined fields
-    const tokens: Record<string, string> = {
+    const tokens: Record<string, unknown> = {
       access_token: storedTokens.access_token,
     };
     if (storedTokens.token_type !== undefined) tokens.token_type = storedTokens.token_type;
     if (storedTokens.refresh_token !== undefined) tokens.refresh_token = storedTokens.refresh_token;
+    if (storedTokens.expires_in !== undefined) tokens.expires_in = storedTokens.expires_in;
+    if (storedTokens.scope !== undefined) tokens.scope = storedTokens.scope;
     return tokens as unknown as OAuthTokens;
   }
 
@@ -323,26 +470,46 @@ export class McpOAuthProvider implements OAuthClientProvider {
     };
 
     if (this.silent) {
+      let handle: AuthLockHandle | undefined;
       try {
-        const state = await loadState(this.serverName, this.storageDir);
+        handle = await acquireAuthLock(this.serverName, this.storageDir);
+        const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+        if (this.serverUrl) {
+          state.serverUrl = canonicalServerUrl(this.serverUrl);
+        }
         state.tokens = storedTokens;
         await saveState(this.serverName, state, this.storageDir, this.isCancelled);
         this._cachedTokens = undefined;
+        this._lastReadTokens = storedTokens;
+        this._reloadedPeerTokens = false;
       } catch (err) {
+        // WHY: When another process holds the interactive auth lock (e.g. during --reset),
+        // keep the refreshed tokens in memory for this session without clobbering disk state.
         this._cachedTokens = storedTokens;
-        console.error(`[pi-mcp] Failed to persist refreshed OAuth tokens for "${this.serverName}":`, err);
+        this._lastReadTokens = storedTokens;
+        this._reloadedPeerTokens = false;
+        if (!(err instanceof AuthLockError)) {
+          console.error(`[pi-mcp] Failed to persist refreshed OAuth tokens for "${this.serverName}":`, err);
+        }
+      } finally {
+        await handle?.();
       }
       return;
     }
 
     if (this.isCancelled()) throw new AuthRequiredError(this.serverName, "Authorization cancelled");
     await this.assertLockHeld?.();
-    const state = await loadState(this.serverName, this.storageDir);
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    if (this.serverUrl) {
+      state.serverUrl = canonicalServerUrl(this.serverUrl);
+    }
     state.tokens = storedTokens;
     if (this.isCancelled()) throw new AuthRequiredError(this.serverName, "Authorization cancelled");
     await this.assertLockHeld?.();
     await saveState(this.serverName, state, this.storageDir, this.isCancelled);
     this._cachedTokens = undefined;
+    this._lastReadTokens = storedTokens;
+    this._reloadedPeerTokens = false;
   }
 
   // --- redirectToAuthorization ---
@@ -380,14 +547,17 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async saveDiscoveryState(discState: OAuthDiscoveryState): Promise<void> {
     if (this.silent) return; // No shared state writes from background discovery.
     await this.assertLockHeld?.();
-    const state = await loadState(this.serverName, this.storageDir);
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    if (this.serverUrl) {
+      state.serverUrl = canonicalServerUrl(this.serverUrl);
+    }
     state.discoveryState = discState;
     await this.assertLockHeld?.();
     await saveState(this.serverName, state, this.storageDir, this.isCancelled);
   }
 
   async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
-    const state = await loadState(this.serverName, this.storageDir);
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
     return state.discoveryState;
   }
 
@@ -412,12 +582,17 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
   // --- Credential invalidation ---
 
-  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void> {
-    if (this.silent) throw new AuthRequiredError(this.serverName);
-    await this.assertLockHeld?.();
-    const state = await loadState(this.serverName, this.storageDir);
+  private _applyInvalidation(
+    state: StoredState,
+    scope: "all" | "client" | "tokens" | "verifier" | "discovery",
+  ): boolean {
+    let changedDisk = false;
     switch (scope) {
       case "all":
+        changedDisk =
+          state.clientInfo !== undefined ||
+          state.tokens !== undefined ||
+          state.discoveryState !== undefined;
         state.clientInfo = undefined;
         state.tokens = undefined;
         state.discoveryState = undefined;
@@ -425,9 +600,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this._cachedTokens = undefined;
         break;
       case "client":
+        changedDisk = state.clientInfo !== undefined;
         state.clientInfo = undefined;
         break;
       case "tokens":
+        changedDisk = state.tokens !== undefined;
         state.tokens = undefined;
         this._cachedTokens = undefined;
         break;
@@ -435,27 +612,126 @@ export class McpOAuthProvider implements OAuthClientProvider {
         this._codeVerifier = undefined;
         break;
       case "discovery":
+        changedDisk = state.discoveryState !== undefined;
         state.discoveryState = undefined;
         break;
     }
+    return changedDisk;
+  }
+
+  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void> {
+    if (this.silent) {
+      if (scope === "tokens" && !this._reloadedPeerTokens) {
+        let diskState: StoredState | undefined;
+        try {
+          diskState = await loadState(this.serverName, this.storageDir, this.serverUrl);
+        } catch {
+          // WHY: If disk state is unreadable, fall through to invalidation and AuthRequiredError.
+          diskState = undefined;
+        }
+        if (
+          diskState?.tokens &&
+          (diskState.tokens.refresh_token !== this._lastReadTokens?.refresh_token ||
+            diskState.tokens.access_token !== this._lastReadTokens?.access_token)
+        ) {
+          // WHY: Another Pi process rotated the single-use refresh token on disk while
+          // our refresh request was in flight. Reload the peer's tokens instead of deleting
+          // them or throwing AuthRequiredError so the SDK's auth() retry succeeds.
+          this._cachedTokens = diskState.tokens;
+          this._lastReadTokens = diskState.tokens;
+          this._reloadedPeerTokens = true;
+          return;
+        }
+      }
+
+      this._cachedTokens = undefined;
+      this._reloadedPeerTokens = false;
+      if (scope === "verifier") {
+        this._codeVerifier = undefined;
+        throw new AuthRequiredError(this.serverName);
+      }
+      let handle: AuthLockHandle | undefined;
+      try {
+        handle = await acquireAuthLock(this.serverName, this.storageDir);
+        const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+        const changedDisk = this._applyInvalidation(state, scope);
+        if (changedDisk) {
+          if (this.serverUrl) {
+            state.serverUrl = canonicalServerUrl(this.serverUrl);
+          }
+          await saveState(this.serverName, state, this.storageDir, this.isCancelled);
+        }
+      } catch {
+        // WHY: Best-effort cleanup of rejected credentials on disk; if another process
+        // holds the lock or disk is unavailable, still throw AuthRequiredError.
+      } finally {
+        await handle?.();
+      }
+      throw new AuthRequiredError(this.serverName);
+    }
+
     await this.assertLockHeld?.();
-    await saveState(this.serverName, state, this.storageDir, this.isCancelled);
+    if (this.isCancelled()) throw new AuthRequiredError(this.serverName, "Authorization cancelled");
+    const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+    const changedDisk = this._applyInvalidation(state, scope);
+    await this.assertLockHeld?.();
+    if (this.isCancelled()) throw new AuthRequiredError(this.serverName, "Authorization cancelled");
+    if (changedDisk) {
+      // WHY: Only write back to disk when stored state for this serverUrl actually had
+      // credentials to clear, preventing a cancelled or unauthenticated project override
+      // from overwriting another server URL's state file before new credentials are saved.
+      if (this.serverUrl) {
+        state.serverUrl = canonicalServerUrl(this.serverUrl);
+      }
+      await saveState(this.serverName, state, this.storageDir, this.isCancelled);
+    }
   }
 }
 
 // ─── Public Helpers ────────────────────────────────────────────────────────────
 
+/**
+ * Best-effort invalidation of stored tokens on disk when a resource server
+ * rejects an access token with HTTP 401/403. Preserves clientInfo and discoveryState.
+ */
+export async function invalidateStoredTokens(
+  serverName: string,
+  storageDir?: string,
+  serverUrl?: string,
+): Promise<void> {
+  let handle: AuthLockHandle | undefined;
+  try {
+    handle = await acquireAuthLock(serverName, storageDir);
+    const state = await loadState(serverName, storageDir, serverUrl);
+    if (state.tokens !== undefined) {
+      state.tokens = undefined;
+      if (serverUrl) {
+        state.serverUrl = canonicalServerUrl(serverUrl);
+      }
+      await saveState(serverName, state, storageDir);
+    }
+  } catch {
+    // WHY: Best-effort token cleanup when a server rejects credentials; ignore lock contention or I/O errors.
+  } finally {
+    await handle?.();
+  }
+}
+
 /**
  * Get auth status info for a server — whether tokens exist, when they were saved, etc.
  * Returns null if no auth state file exists at all.
  */
-export async function getAuthStatus(serverName: string, storageDir?: string): Promise<{
+export async function getAuthStatus(
+  serverName: string,
+  storageDir?: string,
+  serverUrl?: string,
+): Promise<{
   hasTokens: boolean;
   hasClientInfo: boolean;
   savedAt: string | undefined;
   scope: string | undefined;
 } | null> {
-  const state = await loadState(serverName, storageDir);
+  const state = await loadState(serverName, storageDir, serverUrl);
   if (
     state.clientInfo === undefined &&
     state.tokens === undefined &&
@@ -483,3 +759,4 @@ export async function resetAuth(serverName: string, storageDir?: string): Promis
     throw err;
   }
 }
+

package/src/server-manager.ts

@@ -24,16 +24,93 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { McpError } from "./errors.js";
 import type { McpConfig, ServerConfig, Settings } from "./config.js";
-import { McpOAuthProvider, AuthRequiredError, getAuthStatus, resetAuth } from "./oauth-provider.js";
+import { McpOAuthProvider, AuthRequiredError, getAuthStatus, resetAuth, invalidateStoredTokens } from "./oauth-provider.js";
 import { UnauthorizedError, type OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 
-export function isOAuthUnauthorizedError(error: unknown): boolean {
-  return (
-    error instanceof AuthRequiredError ||
-    error instanceof UnauthorizedError ||
-    (typeof (error as { code?: unknown })?.code === "number" && (error as { code: number }).code === 401) ||
-    /\b(401|Unauthorized)\b/i.test(error instanceof Error ? error.message : String(error))
+export function isOAuthUnauthorizedError(error: unknown, seen = new Set<unknown>()): boolean {
+  if (!error || seen.has(error)) {
+    return false;
+  }
+  if (typeof error === "object") {
+    seen.add(error);
+  }
+
+  if (error instanceof AuthRequiredError || error instanceof UnauthorizedError) {
+    return true;
+  }
+
+  if (error instanceof McpError) {
+    // WHY: Tool-level application errors (`isError: true`) come from tool execution logic
+    // (e.g. "found 401 items in database") and must never trigger MCP OAuth re-authentication.
+    if (error.code === "tool") {
+      return false;
+    }
+    if (error.cause !== undefined && isOAuthUnauthorizedError(error.cause, seen)) {
+      return true;
+    }
+  }
+
+  if (typeof error === "object") {
+    const rec = error as { code?: unknown; status?: unknown; statusCode?: unknown; cause?: unknown };
+    if (rec.cause !== undefined && isOAuthUnauthorizedError(rec.cause, seen)) {
+      return true;
+    }
+    const numericCode =
+      typeof rec.code === "number"
+        ? rec.code
+        : typeof rec.status === "number"
+          ? rec.status
+          : typeof rec.statusCode === "number"
+            ? rec.statusCode
+            : undefined;
+    // WHY: Only treat 100..599 as HTTP status codes so negative JSON-RPC error codes
+    // (e.g. -32000) still inspect the error message for wrapped HTTP 401/403 status text.
+    if (numericCode !== undefined && numericCode >= 100 && numericCode <= 599) {
+      if (numericCode === 401) return true;
+      const msg = error instanceof Error ? error.message : String(error);
+      if (numericCode === 403 && /\b(insufficient_scope|trying upscoping)\b/i.test(msg)) {
+        return true;
+      }
+      return false;
+    }
+  }
+
+  const msg = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  if (!msg) return false;
+
+  // Reject messages that explicitly report a non-401/403 HTTP status code
+  const httpStatusMatch = msg.match(
+    /\b(?:HTTP\s+|status(?:\s+code)?[:\s]+|(?:POSTing|GETting|connecting)\s+to\s+\S+:\s*|(?:Non-200\s+status\s+code\s*\())(\d{3})\b/i,
   );
+  if (httpStatusMatch) {
+    const status = Number(httpStatusMatch[1]);
+    if (status !== 401 && status !== 403) {
+      return false;
+    }
+  }
+
+  if (
+    /^\s*401\s*$/.test(msg) ||
+    /\bHTTP\s+401\b/i.test(msg) ||
+    /\bstatus(?:\s+code)?[:\s(]+401\b/i.test(msg) ||
+    /\breturned\s+401\b/i.test(msg) ||
+    /\b401\s+Unauthorized\b/i.test(msg) ||
+    /:\s*401\b/.test(msg) ||
+    /\(401\)/.test(msg) ||
+    /\bUnauthorized\b/i.test(msg) ||
+    /\binvalid_token\b/i.test(msg)
+  ) {
+    return true;
+  }
+
+  if (
+    /\b(403|Forbidden)\b/i.test(msg) &&
+    /\b(insufficient_scope|trying upscoping)\b/i.test(msg)
+  ) {
+    return true;
+  }
+
+  return false;
 }
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -90,7 +167,16 @@ function createTransport(
   let authProvider: OAuthClientProvider | undefined;
   if (config.auth && config.transport !== "stdio") {
     // Silent transport attempts must not write PKCE or launch a browser.
-    authProvider = new McpOAuthProvider(serverName, config.auth, undefined, storageDir, true);
+    authProvider = new McpOAuthProvider(
+      serverName,
+      config.auth,
+      undefined,
+      storageDir,
+      true,
+      undefined,
+      undefined,
+      config.url,
+    );
   }
 
   switch (config.transport) {
@@ -206,7 +292,25 @@ export class ServerManager {
     savedAt: string | undefined;
     scope: string | undefined;
   } | null> {
-    return getAuthStatus(name, this.storageDir);
+    const serverUrl = this.servers.get(name)?.config.url;
+    return getAuthStatus(name, this.storageDir, serverUrl);
+  }
+
+  /**
+   * Mark an OAuth server as requiring re-authorization when a mid-session
+   * request (tools/list or tools/call) fails with 401/403 insufficient_scope.
+   */
+  async handleUnauthorizedServerError(name: string, _cause?: unknown): Promise<void> {
+    const server = this.servers.get(name);
+    if (!server || !server.config.auth || server.config.transport === "stdio") {
+      return;
+    }
+    await invalidateStoredTokens(name, this.storageDir, server.config.url);
+    const authError = new AuthRequiredError(name);
+    if (server.state === "ready") {
+      await this._shutdown(server);
+    }
+    server.lastError = authError;
   }
 
   /** Get recent stderr output for a server. */
@@ -296,7 +400,12 @@ export class ServerManager {
 
   // ─── Internal ───────────────────────────────────────────────────────────────
 
-  private async _connect(server: ManagedServer, cwd: string, signal: AbortSignal): Promise<void> {
+  private async _connect(
+    server: ManagedServer,
+    cwd: string,
+    signal: AbortSignal,
+    corruptStateRecovered = false,
+  ): Promise<void> {
     server.lastError = null;
     // Note: retryCount is NOT reset here — it's only reset after successful connect.
     // This ensures the retry limit is respected across reconnection attempts.
@@ -409,17 +518,39 @@ export class ServerManager {
       if (server.client === client) { server.client = null; server.childPid = null; }
       if (signal.aborted) throw new Error("Connection cancelled");
       const error = err instanceof Error ? err : new Error(String(err));
+      if (
+        !corruptStateRecovered &&
+        error instanceof McpError &&
+        error.code === "config" &&
+        /Corrupt OAuth state file/i.test(error.message)
+      ) {
+        // WHY: McpOAuthProvider._loadState() already backed up and removed the corrupt
+        // state file before throwing this error. Log the warning and retry once immediately
+        // without consuming retryCount so OAuth can proceed cleanly into AuthRequiredError.
+        console.error(`[pi-mcp] ${error.message}`);
+        if (signal.aborted) throw new Error("Connection cancelled");
+        return this._connect(server, cwd, signal, true);
+      }
       server.lastError = error;
-      if (error instanceof AuthRequiredError || (error instanceof McpError && error.code === "protocol")) {
+      if (error instanceof AuthRequiredError) {
         server.state = "stopped";
         throw error;
       }
       if (Boolean(server.config.auth) && server.config.transport !== "stdio" && isOAuthUnauthorizedError(error)) {
+        // WHY: Check OAuth unauthorized errors BEFORE the generic `error.code === "protocol"`
+        // fast-fail so 401/403 failures during initial tools/list (`onToolRefresh`) are
+        // classified as `AuthRequiredError` rather than raw protocol failures, and stale
+        // tokens on disk are invalidated before interactive re-authorization runs.
+        await invalidateStoredTokens(server.name, this.storageDir, server.config.url);
         const authError = new AuthRequiredError(server.name);
         server.lastError = authError;
         server.state = "stopped";
         throw authError;
       }
+      if (error instanceof McpError && error.code === "protocol") {
+        server.state = "stopped";
+        throw error;
+      }
       if (server.retryCount >= this.settings.maxRetries) {
         server.state = "stopped";
         throw new McpError(`Connection failed after ${server.retryCount} retries: ${error.message}`, server.name, "connection", err);
@@ -433,7 +564,7 @@ export class ServerManager {
         }, { once: true });
       });
       if (signal.aborted) throw new Error("Connection cancelled");
-      return this._connect(server, cwd, signal);
+      return this._connect(server, cwd, signal, corruptStateRecovered);
     }
   }
 

package/src/tool-bridge.ts

@@ -20,6 +20,7 @@ import type { TSchema } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { McpError } from "./errors.js";
 import type { Settings } from "./config.js";
+import { isOAuthUnauthorizedError } from "./server-manager.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -681,12 +682,18 @@ export class ToolBridge {
   private readonly toolOwners = new Map<string, string>();
   /** Monotonic per-server generation counter to discard out-of-order refreshTools responses. */
   private readonly refreshGenerations = new Map<string, number>();
+  private onAuthError?: ((serverName: string, error: unknown) => Promise<void> | void) | undefined;
 
   constructor(settings: Settings, pi: PiExtensionAPI) {
     this.settings = settings;
     this.pi = pi;
   }
 
+  /** Register callback invoked when a mid-session tools/list or tools/call fails with 401/403. */
+  setAuthErrorCallback(cb: (serverName: string, error: unknown) => Promise<void> | void): void {
+    this.onAuthError = cb;
+  }
+
   /** Update bridge settings when session config is reloaded on session_start. */
   updateSettings(settings: Settings): void {
     this.settings = settings;
@@ -712,6 +719,9 @@ export class ToolBridge {
     try {
       tools = await listAllTools(client, timeoutMs);
     } catch (err) {
+      if (isOAuthUnauthorizedError(err)) {
+        await this.onAuthError?.(serverName, err);
+      }
       throw new McpError(
         `Failed to list tools from ${serverName}: ${err instanceof Error ? err.message : String(err)}`,
         serverName,
@@ -847,6 +857,7 @@ export class ToolBridge {
 
     const schema = convertJsonSchemaToTypebox(tool.inputSchema);
     const timeoutMs = this.settings.requestTimeoutMs;
+    const notifyAuthError = (err: unknown) => this.onAuthError?.(serverName, err);
 
     this.pi.registerTool({
       name: piName,
@@ -899,6 +910,9 @@ export class ToolBridge {
           return { content, details: {} };
         } catch (err) {
           if (err instanceof McpError) throw err;
+          if (isOAuthUnauthorizedError(err)) {
+            await notifyAuthError(err);
+          }
           // Protocol-level errors (JSON-RPC error response, timeout, etc.)
           throw new McpError(
             err instanceof Error ? err.message : String(err),