pi-mcp-extension 1.9.7 → 1.9.9

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-mcp-extension.svg)](https://www.npmjs.com/package/pi-mcp-extension)
 [![license](https://img.shields.io/npm/l/pi-mcp-extension.svg)](https://github.com/irahardianto/pi-mcp-extension/blob/main/LICENSE)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/irahardianto/pi-mcp-extension/badge)](https://scorecard.dev/viewer/?uri=github.com/irahardianto/pi-mcp-extension)
 
 **Connect [Pi](https://pi.dev) to any MCP server.** Supabase, DeepSource, Playwright, Context7, filesystem, databases — if it speaks [MCP](https://modelcontextprotocol.io), Pi can use it.
 
@@ -183,8 +184,8 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/mcp <name>` | Show detailed status and stderr log for a specific server |
 | `/mcp:start <name>` | Connect a server and wait for tool discovery |
 | `/mcp:stop <name>` | Cancel a pending connection, startup prompt, or authorization, or stop a running server and deactivate its tools |
-| `/mcp:auth <name>` | Connect with stored OAuth credentials; request browser authorization only if needed |
-| `/mcp:auth <name> --reset` | Discard stored OAuth credentials and request fresh authorization |
+| `/mcp:auth <name>` | Connect with stored OAuth credentials and client registration; request browser authorization only if needed |
+| `/mcp:auth <name> --reset` | Discard stored tokens and client registration (re-running Dynamic Client Registration) and request fresh authorization |
 
 Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, discovered and active tool counts, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.
 
@@ -194,6 +195,7 @@ Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and
 - **Startup prompt for eager OAuth servers**: Silent startup and background reconnects never open a browser unprompted or trigger Dynamic Client Registration when no client credentials are stored. When an `eager` OAuth server needs interactive authorization at startup in an interactive Pi session, Pi presents a sequential `<name> needs authorization` prompt (`Authorize now` / `Not now`). Choosing `Authorize now` runs the interactive OAuth flow; choosing `Not now` leaves the server stopped, shows a `run /mcp:auth <name>` footer hint, and remembers the decline for the rest of the session.
 - **Headless and SSH support**: While authorization is pending, Pi displays the authorization URL and offers `Retry: open browser again`, `Paste redirect URL`, and `Cancel authentication`. On remote/SSH or headless machines, open the URL locally and either forward the callback port (`ssh -L <port>:127.0.0.1:<port>`) or paste the browser's final `http://127.0.0.1:<port>/callback?code=...&state=...` redirect URL into `Paste redirect URL`. Only `https:` (or loopback `http:`) authorization URLs are passed to the system browser opener.
 - **Coordinated connects and cross-process locks**: Concurrent connect requests join an in-flight attempt, while `--reset` supersedes a normal connect and shares one pending reset. Cross-process interactive flows are serialized per server via `<agent dir>/mcp-auth/<hash>.json.lock` with a 30s heartbeat and automatic reclamation of locks from dead local PIDs or stale heartbeats (>90s), while allowing silent token refreshes to persist rotated tokens.
+- **Resetting stale client registrations (`--reset`)**: `/mcp:auth <name>` reuses the cached Dynamic Client Registration (`clientInfo.client_id`) stored in `<agent dir>/mcp-auth/<hash>.json`. If an OAuth provider expires or purges a previously registered client—for example, when the browser displays `{"message":"Unrecognized client_id"}` or `invalid_client` on the authorization page without redirecting back to the local callback—run `/mcp:auth <name> --reset` to discard the cached `client_id`, register a new client via Dynamic Client Registration, and start a fresh authorization flow.
 
 ### Connection readiness and active tools
 
@@ -266,6 +268,9 @@ Implements the **MCP 2025-03-26** specification for tool clients:
 # Install dependencies
 npm install
 
+# Lint (type-aware ESLint)
+npm run lint
+
 # Type check (strict mode)
 npm run typecheck
 
@@ -285,6 +290,10 @@ The test suite includes:
 - **Tool bridge & management tools** — JSON Schema → TypeBox conversion, name sanitization, image content passthrough, `isError` filtering, activate/deactivate, `mcp_status` / `mcp_connect`, and slash command completions
 - **End-to-end integration** — Real mock MCP and OAuth servers over stdio and HTTP with tool discovery and execution
 
+## Security
+
+Please report vulnerabilities privately, not in public issues. See [SECURITY.md](https://github.com/irahardianto/pi-mcp-extension/blob/main/SECURITY.md) for scope, supported versions, and how to report.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.9.7",
+  "version": "1.9.9",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [
@@ -33,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^3.25.0"
   },
   "peerDependencies": {
@@ -42,13 +42,18 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
     "tsx": "^4.19.4",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.71.2"
   },
   "scripts": {
+    "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test ./tests/*.test.ts",
+    "test:coverage": "node --import tsx/esm --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=83 ./tests/*.test.ts",
     "test:integration": "node --import tsx/esm --test ./tests/server-manager.test.ts"
   }
 }

package/src/auth-lock.ts

@@ -171,6 +171,9 @@ export function parseLockRecord(raw: string): LockRecord | null {
     const result = LockRecordSchema.safeParse(parsed);
     return result.success ? result.data : null;
   } catch {
+    // WHY: JSON.parse on a string throws SyntaxError if the lock file is corrupt or
+    // partially written. LockRecordSchema.safeParse does not throw. Unparseable lock
+    // files map to null so isLockStale() can fall back to mtime-based staleness.
     return null;
   }
 }
@@ -312,7 +315,7 @@ export async function acquireAuthLock(
 
       process.once("exit", onExit);
 
-      heartbeatTimer = deps.clock.setInterval(async () => {
+      const heartbeatTick = async (): Promise<void> => {
         if (released || lost) return;
         const current = await readLockRecordWithRetry(deps.fs, path, usingRealFs);
         if (released || lost) return;
@@ -336,6 +339,9 @@ export async function acquireAuthLock(
             }
           }
         }
+      };
+      heartbeatTimer = deps.clock.setInterval(() => {
+        void heartbeatTick();
       }, HEARTBEAT_MS);
       heartbeatTimer.unref?.();
 

package/src/config.ts

@@ -64,7 +64,7 @@ const AuthConfigSchema = z.preprocess(
           callbackServerConfigFromRedirectUrl(auth.redirectUrl);
         } catch (err) {
           ctx.addIssue({
-            code: z.ZodIssueCode.custom,
+            code: "custom",
             path: ["redirectUrl"],
             message: err instanceof Error ? err.message : String(err),
           });
@@ -104,7 +104,7 @@ export const ServerConfigSchema = z.preprocess(
        * These merge with process.env; project env overrides parent env.
        * No ${VAR} interpolation — set vars in your shell environment instead.
        */
-      env: z.record(z.string()).optional(),
+      env: z.record(z.string(), z.string()).optional(),
       /** Transport protocol. Default: "stdio" (or "streamable-http" when "url" is provided). */
       transport: z.enum(["stdio", "streamable-http", "sse"]).default("stdio"),
       /**
@@ -117,7 +117,7 @@ export const ServerConfigSchema = z.preprocess(
        * Useful for API-key-based auth (e.g. { "Authorization": "Bearer <key>" }).
        * For OAuth2, use the "auth" field instead.
        */
-      headers: z.record(z.string()).optional(),
+      headers: z.record(z.string(), z.string()).optional(),
       /**
        * OAuth2 configuration for servers that require authorization.
        * When set, the transport will use the SDK's OAuth flow (discovery,
@@ -139,27 +139,36 @@ export const ServerConfigSchema = z.preprocess(
        */
       healthCheckIntervalMs: z.number().positive().optional(),
     })
-    .refine(
-      (cfg) => {
-        if (cfg.transport === "stdio") return cfg.command !== undefined;
-        return cfg.url !== undefined;
-      },
-      (cfg) => ({
-        message:
-          cfg.transport === "stdio"
-            ? `"command" is required for stdio transport`
-            : `"url" is required for ${cfg.transport} transport`,
-      }),
-    )
-    .refine(
-      (cfg) => !(cfg.transport === "stdio" && cfg.auth !== undefined),
-      {
-        message: "OAuth authentication is only supported for 'sse' and 'streamable-http' transports, not 'stdio'",
-        path: ["auth"],
-      },
-    ),
+    .superRefine((cfg, ctx) => {
+      if (cfg.transport === "stdio") {
+        if (cfg.command === undefined) {
+          ctx.addIssue({
+            code: "custom",
+            message: '"command" is required for stdio transport',
+          });
+        }
+        if (cfg.auth !== undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["auth"],
+            message: "OAuth authentication is only supported for 'sse' and 'streamable-http' transports, not 'stdio'",
+          });
+        }
+      } else if (cfg.url === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          message: `"url" is required for ${cfg.transport} transport`,
+        });
+      }
+    }),
 );
 
+const DEFAULT_SETTINGS = {
+  toolPrefix: "mcp",
+  requestTimeoutMs: 30000,
+  maxRetries: 5,
+} as const;
+
 const SettingsSchema = z.object({
   /**
    * Prefix used in Pi tool names: <prefix>_<server>_<tool>.
@@ -168,16 +177,16 @@ const SettingsSchema = z.object({
   toolPrefix: z
     .string()
     .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "toolPrefix must start with a letter and contain only alphanumeric characters and underscores")
-    .default("mcp"),
+    .default(DEFAULT_SETTINGS.toolPrefix),
   /** Default per-request timeout in ms for all servers. Default: 30000. */
-  requestTimeoutMs: z.number().positive().default(30000),
+  requestTimeoutMs: z.number().positive().default(DEFAULT_SETTINGS.requestTimeoutMs),
   /** Maximum retry attempts when a server fails to connect. Default: 5. */
-  maxRetries: z.number().int().min(0).max(10).default(5),
+  maxRetries: z.number().int().min(0).max(10).default(DEFAULT_SETTINGS.maxRetries),
 });
 
 const McpConfigSchema = z.object({
-  settings: SettingsSchema.default({}),
-  mcpServers: z.record(ServerConfigSchema).default({}),
+  settings: SettingsSchema.default(() => ({ ...DEFAULT_SETTINGS })),
+  mcpServers: z.record(z.string(), ServerConfigSchema).default({}),
 });
 
 /**
@@ -195,7 +204,7 @@ const ProjectSettingsSchema = z.object({
 });
 const ProjectConfigSchema = z.object({
   settings: ProjectSettingsSchema.default({}),
-  mcpServers: z.record(ServerConfigSchema).default({}),
+  mcpServers: z.record(z.string(), ServerConfigSchema).default({}),
 });
 type ProjectConfig = z.output<typeof ProjectConfigSchema>;
 

package/src/errors.ts

@@ -15,7 +15,7 @@ export type McpErrorCode =
 export class McpError extends Error {
   public readonly server: string;
   public readonly code: McpErrorCode;
-  public readonly cause: unknown;
+  public override readonly cause: unknown;
 
   constructor(
     message: string,

package/src/index.ts

@@ -16,6 +16,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { loadConfig, parseRegisteredServerConfig, type McpConfig, type ServerConfig } from "./config.js";
 import { ServerManager } from "./server-manager.js";
+import { sanitizeTerminalText } from "./terminal-text.js";
 import { AuthLockError, AuthRequiredError } from "./oauth-provider.js";
 import * as Type from "typebox";
 import { ToolBridge } from "./tool-bridge.js";
@@ -65,7 +66,7 @@ function openBrowser(url: string): Promise<void> {
     });
 
     child.once("error", (err) => {
-      console.error(`[pi-mcp] Failed to open browser: ${err.message}`);
+      console.error(`[pi-mcp] Failed to open browser: ${sanitizeTerminalText(err.message)}`);
       reject(err);
     });
 
@@ -86,7 +87,7 @@ export const startupAuthLaterOption = "Not now";
 
 function formatErrorMessage(err: unknown): string {
   const msg = err instanceof McpError ? err.userMessage : err instanceof Error ? err.message : String(err);
-  return msg.replace(/^AuthRequiredError:\s*/, "");
+  return sanitizeTerminalText(msg.replace(/^AuthRequiredError:\s*/, ""));
 }
 
 interface OAuthCallbackResult {
@@ -220,7 +221,7 @@ export async function waitForOAuthCallback(
         });
       } catch (err) {
         if (err instanceof CallbackUrlValidationError) {
-          context.ui.notify?.(`pi-mcp: Invalid redirect URL — ${err.message}`, "error");
+          context.ui.notify?.(`pi-mcp: Invalid redirect URL — ${sanitizeTerminalText(err.message)}`, "error");
           continue;
         }
         throw err;
@@ -346,7 +347,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
   } catch (err) {
     // Can't notify yet (no ctx), so log to stderr. The session_start handler
     // will re-try with the real cwd and surface errors properly.
-    console.error(`[pi-mcp] Config error: ${err instanceof McpError ? err.message : String(err)}`);
+    console.error(`[pi-mcp] Config error: ${sanitizeTerminalText(err instanceof McpError ? err.message : String(err))}`);
   }
 
   const getRegisteredEntries = (): RegisteredMcpServer[] =>
@@ -357,12 +358,12 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
   let extensionServers = collectRegisteredServers(
     getRegisteredEntries(),
     fileConfig.mcpServers,
-    (err) => console.error(`[pi-mcp] Config error: ${err instanceof McpError ? err.message : String(err)}`),
+    (err) => console.error(`[pi-mcp] Config error: ${sanitizeTerminalText(err instanceof McpError ? err.message : String(err))}`),
   );
   let config: McpConfig = mergeWithRegisteredServers(fileConfig, extensionServers);
 
   // ── 2. Initialize bridge components ──────────────────────────────────────
-  const manager = new ServerManager(config, undefined, paths.authStorageDir);
+  const manager = new ServerManager(config, paths.authStorageDir);
   const bridge = new ToolBridge(config.settings, pi);
   const connectAttempts = new Map<string, { promise: Promise<void>; controller: AbortController; reset: boolean; waiters: number }>();
   const declinedStartupAuth = new Set<string>();
@@ -391,7 +392,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
             resolve();
           }
         },
-        (err) => {
+        (err: unknown) => {
           signal.removeEventListener("abort", onAbort);
           reject(err);
         },
@@ -513,7 +514,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
                   promptController.signal.removeEventListener("abort", onAbort);
                   resolve(value);
                 },
-                (err) => {
+                (err: unknown) => {
                   promptController.signal.removeEventListener("abort", onAbort);
                   if (promptController.signal.aborted) resolve(undefined);
                   else reject(err);
@@ -639,8 +640,8 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       );
     }
   });
-  bridge.setAuthErrorCallback(async (serverName, err) => {
-    await manager.handleUnauthorizedServerError(serverName, err);
+  bridge.setAuthErrorCallback(async (serverName) => {
+    await manager.handleUnauthorizedServerError(serverName);
   });
 
   // ── 3. Session lifecycle ──────────────────────────────────────────────────
@@ -808,7 +809,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           `Server: ${serverName}`,
           `State:  ${server.state}`,
           `Retries: ${server.retryCount}`,
-          server.lastError ? `Last error: ${server.lastError.message}` : null,
+          server.lastError ? `Last error: ${sanitizeTerminalText(server.lastError.message)}` : null,
           "",
           "Recent output:",
           logs,
@@ -867,7 +868,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
         ctx.ui.notify(`pi-mcp: Started ${serverName}`, "info");
       } catch (err) {
         if (err instanceof AuthCancelledError) {
-          ctx.ui.notify(`pi-mcp: ${err.message}`, "info");
+          ctx.ui.notify(`pi-mcp: ${sanitizeTerminalText(err.message)}`, "info");
           return;
         }
         const msg = formatErrorMessage(err);
@@ -950,7 +951,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
             );
           } catch (err) {
             ctx.ui.notify(
-              `pi-mcp: Failed to open browser for ${serverName} (${err instanceof Error ? err.message : String(err)}). Open ${url.toString()} manually or choose "${authPasteOption}".`,
+              `pi-mcp: Failed to open browser for ${serverName} (${sanitizeTerminalText(err instanceof Error ? err.message : String(err))}). Open ${url.toString()} manually or choose "${authPasteOption}".`,
               "error",
             );
           }
@@ -977,7 +978,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
             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}`);
+              console.error(`[pi-mcp] ${sanitizeTerminalText(err.message)}`);
             } else {
               throw err;
             }
@@ -999,7 +1000,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           if (signal.aborted) {
             throw new AuthCancelledError(serverName);
           }
-          console.warn(
+          console.error(
             `[pi-mcp] Failed to discover OAuth challenge for "${serverName}"; falling back to standard discovery`,
           );
           return {};
@@ -1044,7 +1045,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           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}`);
+            console.error(`[pi-mcp] ${sanitizeTerminalText(err.message)}`);
             authResult = await auth(authProvider, authOptions);
           } else {
             throw err;
@@ -1292,7 +1293,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           } 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)}`);
+            console.error(`[pi-mcp] ${sanitizeTerminalText(err instanceof Error ? err.message : String(err))}`);
             authCorrupt = true;
           }
         }
@@ -1364,7 +1365,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
       }
       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");
+        ctx.ui.notify(`pi-mcp: ${sanitizeTerminalText(err instanceof Error ? err.message : String(err))}`, err instanceof AuthCancelledError ? "info" : "error");
       }
     },
     getArgumentCompletions: (prefix) => serverNameCompletions(prefix, manager.getAllServers(), { authOnly: true }),

package/src/oauth-provider.ts

@@ -76,6 +76,9 @@ export function canonicalServerUrl(rawUrl: string): string {
     const path = u.pathname.length > 1 ? u.pathname.replace(/\/+$/, "") : u.pathname;
     return `${u.origin}${path}${u.search}`;
   } catch {
+    // WHY: new URL() throws TypeError per WHATWG URL spec on malformed or relative
+    // URL strings. Falling back to trimmed rawUrl allows graceful degradation for
+    // non-standard or unparseable URLs without crashing callers.
     return rawUrl.trim();
   }
 }
@@ -95,6 +98,9 @@ function isResourceCompatibleWithServerUrl(resource: string, expectedServerUrl:
     const cfgPath = cfg.pathname.endsWith("/") ? cfg.pathname : `${cfg.pathname}/`;
     return reqPath.startsWith(cfgPath);
   } catch {
+    // WHY: new URL() throws TypeError per WHATWG URL spec if canonicalServerUrl produced
+    // an invalid or relative URL. If either URL cannot be parsed into an absolute URL,
+    // they cannot be origin/path-compatible, so returning false is the safe fallback.
     return false;
   }
 }
@@ -108,6 +114,7 @@ interface StoredClientInfo {
   client_secret_expires_at: number | undefined;
   token_endpoint_auth_method: string | undefined;
   redirect_uris: string[] | undefined;
+  issuer: string | undefined;
 }
 
 interface StoredTokens {
@@ -118,6 +125,7 @@ interface StoredTokens {
   scope: string | undefined;
   /** ISO timestamp when tokens were saved (for expiry estimation). */
   saved_at: string | undefined;
+  issuer: string | undefined;
 }
 
 interface StoredState {
@@ -127,6 +135,11 @@ interface StoredState {
   discoveryState: OAuthDiscoveryState | undefined;
 }
 
+// WHY: Credentials persisted before SDK 1.31 (GHSA-6qxp-vccf-f47h) have no `issuer`
+// property. We allow `issuer: z.string().optional()` so legacy state loads gracefully;
+// the SDK binds them to the discovered authorization server on first successful use.
+// Unknown keys are stripped by z.object, so explicit schema inclusion is required to
+// persist and return the SDK's issuer stamp.
 const StoredClientInfoSchema = z.object({
   client_id: z.string(),
   client_secret: z.string().optional(),
@@ -134,6 +147,7 @@ const StoredClientInfoSchema = z.object({
   client_secret_expires_at: z.number().optional(),
   token_endpoint_auth_method: z.string().optional(),
   redirect_uris: z.array(z.string()).optional(),
+  issuer: z.string().optional(),
 });
 
 const StoredTokensSchema = z.object({
@@ -143,13 +157,14 @@ const StoredTokensSchema = z.object({
   expires_in: z.number().optional(),
   scope: z.string().optional(),
   saved_at: z.string().optional(),
+  issuer: z.string().optional(),
 });
 
 export const StoredStateSchema = z.object({
   serverUrl: z.string().optional(),
   clientInfo: StoredClientInfoSchema.optional(),
   tokens: StoredTokensSchema.optional(),
-  discoveryState: z.record(z.unknown()).optional(),
+  discoveryState: z.record(z.string(), z.unknown()).optional(),
 });
 
 // ─── File helpers ─────────────────────────────────────────────────────────────
@@ -231,6 +246,7 @@ async function loadState(
           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,
+          issuer: parsed.clientInfo.issuer,
         }
       : undefined,
     tokens: parsed.tokens
@@ -241,6 +257,7 @@ async function loadState(
           expires_in: parsed.tokens.expires_in,
           scope: parsed.tokens.scope,
           saved_at: parsed.tokens.saved_at,
+          issuer: parsed.tokens.issuer,
         }
       : undefined,
     discoveryState,
@@ -340,9 +357,13 @@ export class McpOAuthProvider implements OAuthClientProvider {
   async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
     // If static credentials provided, use those
     if (this.authConfig.clientId) {
+      const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+      const boundIssuer =
+        state.clientInfo?.client_id === this.authConfig.clientId ? state.clientInfo.issuer : undefined;
       return {
         client_id: this.authConfig.clientId,
         ...(this.authConfig.clientSecret && { client_secret: this.authConfig.clientSecret }),
+        ...(boundIssuer !== undefined && { issuer: boundIssuer }),
       };
     }
     // Otherwise load from persisted DCR state
@@ -384,7 +405,8 @@ export class McpOAuthProvider implements OAuthClientProvider {
           token_endpoint_auth_method: info.token_endpoint_auth_method,
         }),
         ...(info.redirect_uris !== undefined && { redirect_uris: info.redirect_uris }),
-      } as OAuthClientInformationMixed;
+        ...(info.issuer !== undefined && { issuer: info.issuer }),
+      };
     }
     if (this.silent) throw new AuthRequiredError(this.serverName);
     return undefined;
@@ -393,9 +415,88 @@ export class McpOAuthProvider implements OAuthClientProvider {
   // --- saveClientInformation (DCR) ---
 
   async saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void> {
-    if (this.silent) throw new AuthRequiredError(this.serverName);
+    const issuerToBind =
+      typeof clientInformation.issuer === "string" ? clientInformation.issuer : undefined;
+
+    if (this.silent) {
+      const knownClientId = this.authConfig.clientId;
+      let handle: AuthLockHandle | undefined;
+      try {
+        handle = await acquireAuthLock(this.serverName, this.storageDir);
+        const state = await loadState(this.serverName, this.storageDir, this.serverUrl);
+        const storedClient = state.clientInfo;
+        const matchingId = knownClientId ?? storedClient?.client_id;
+        if (!matchingId || clientInformation.client_id !== matchingId) {
+          // WHY: Silent background connections must never execute Dynamic Client Registration
+          // for a new or different client_id without interactive user consent.
+          throw new AuthRequiredError(this.serverName);
+        }
+        if (storedClient?.issuer !== undefined && issuerToBind !== undefined && storedClient.issuer !== issuerToBind) {
+          // WHY: A stored client already bound to an authorization server issuer must never be
+          // re-bound to a different issuer. Switching authorization servers requires an explicit reset.
+          throw new McpError(
+            `OAuth client for "${this.serverName}" is already bound to authorization server ${storedClient.issuer} and cannot be bound to ${issuerToBind}. Run /mcp:auth ${this.serverName} --reset to re-authorize.`,
+            this.serverName,
+            "auth",
+          );
+        }
+        if (this.serverUrl) {
+          state.serverUrl = canonicalServerUrl(this.serverUrl);
+        }
+        if (storedClient) {
+          // WHY: Mirror silent saveTokens: pure issuer binding of the already-known client
+          // preserves all stored credentials and DCR metadata on disk while stamping issuer.
+          if (this.authConfig.clientId) {
+            storedClient.client_secret = undefined;
+          }
+          storedClient.issuer = issuerToBind ?? storedClient.issuer;
+        } else {
+          state.clientInfo = {
+            client_id: clientInformation.client_id,
+            client_secret: this.authConfig.clientId
+              ? undefined
+              : (this.authConfig.clientSecret ?? clientInformation.client_secret),
+            client_id_issued_at: undefined,
+            client_secret_expires_at: undefined,
+            token_endpoint_auth_method: undefined,
+            redirect_uris: undefined,
+            issuer: issuerToBind,
+          };
+        }
+        await saveState(this.serverName, state, this.storageDir, this.isCancelled);
+      } catch (err) {
+        if (err instanceof AuthRequiredError || err instanceof McpError) {
+          throw err;
+        }
+        // WHY: When another process holds the interactive auth lock (e.g. during an interactive
+        // /mcp:auth or --reset), acquireAuthLock fails fast. We skip this background binding
+        // without failing the refresh — the SDK will bind client information again on the next refresh.
+        if (!(err instanceof AuthLockError)) {
+          console.error(`[pi-mcp] Failed to persist OAuth client info 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, this.serverUrl);
+    if (
+      state.clientInfo?.client_id === clientInformation.client_id &&
+      state.clientInfo.issuer !== undefined &&
+      issuerToBind !== undefined &&
+      state.clientInfo.issuer !== issuerToBind
+    ) {
+      // WHY: A stamped client is never re-stamped with a different authorization server issuer.
+      // To switch authorization servers, credentials must be explicitly reset via /mcp:auth <server> --reset.
+      throw new McpError(
+        `OAuth client for "${this.serverName}" is already bound to authorization server ${state.clientInfo.issuer} and cannot be bound to ${issuerToBind}. Run /mcp:auth ${this.serverName} --reset to re-authorize.`,
+        this.serverName,
+        "auth",
+      );
+    }
     if (this.serverUrl) {
       state.serverUrl = canonicalServerUrl(this.serverUrl);
     }
@@ -407,18 +508,28 @@ export class McpOAuthProvider implements OAuthClientProvider {
     }>;
     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"
+      client_secret: this.authConfig.clientId ? undefined : clientInformation.client_secret,
+      client_id_issued_at: this.authConfig.clientId
+        ? undefined
+        : typeof fullInfo.client_id_issued_at === "number"
+          ? fullInfo.client_id_issued_at
+          : undefined,
+      client_secret_expires_at: this.authConfig.clientId
+        ? undefined
+        : typeof fullInfo.client_secret_expires_at === "number"
+          ? fullInfo.client_secret_expires_at
+          : undefined,
+      token_endpoint_auth_method: this.authConfig.clientId
+        ? undefined
+        : 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,
+      redirect_uris: this.authConfig.clientId
+        ? undefined
+        : Array.isArray(fullInfo.redirect_uris)
+          ? fullInfo.redirect_uris.map((u) => String(u))
+          : undefined,
+      issuer: issuerToBind,
     };
     await this.assertLockHeld?.();
     await saveState(this.serverName, state, this.storageDir, this.isCancelled);
@@ -454,6 +565,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
     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;
+    if (storedTokens.issuer !== undefined) tokens.issuer = storedTokens.issuer;
     return tokens as unknown as OAuthTokens;
   }
 
@@ -467,6 +579,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
       expires_in: tokens.expires_in,
       scope: tokens.scope,
       saved_at: new Date().toISOString(),
+      issuer: typeof tokens.issuer === "string" ? tokens.issuer : undefined,
     };
 
     if (this.silent) {

package/src/server-manager.ts

@@ -34,8 +34,16 @@ import {
   getClientDefaultOptions,
   type ToolRefreshOptions,
 } from "./tool-bridge.js";
+import { sanitizeTerminalText, type SanitizeTerminalTextOptions } from "./terminal-text.js";
 
-export { setClientDefaultOptions, getClientDefaultOptions, type ToolRefreshOptions, AuthCancelledError };
+export {
+  setClientDefaultOptions,
+  getClientDefaultOptions,
+  type ToolRefreshOptions,
+  AuthCancelledError,
+  sanitizeTerminalText,
+  type SanitizeTerminalTextOptions,
+};
 
 
 export function isOAuthUnauthorizedError(error: unknown, seen = new Set<unknown>()): boolean {
@@ -101,12 +109,19 @@ export function isOAuthUnauthorizedError(error: unknown, seen = new Set<unknown>
   }
 
   if (
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /^\s*401\s*$/.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /\bHTTP\s+401\b/i.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /\bstatus(?:\s+code)?[:\s(]+401\b/i.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /\breturned\s+401\b/i.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /\b401\s+Unauthorized\b/i.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /:\s*401\b/.test(msg) ||
+    // nosemgrep: pi-mcp.no-401-substring -- WHY: intentional message-text fallback after structured checks for SDK paths that only surface text
     /\(401\)/.test(msg) ||
     /\bUnauthorized\b/i.test(msg) ||
     /\binvalid_token\b/i.test(msg)
@@ -129,13 +144,7 @@ export function isOAuthUnauthorizedError(error: unknown, seen = new Set<unknown>
  * control characters from a single server stderr line before storing or logging.
  */
 export function sanitizeStderrLine(line: string): string {
-  return line
-    .replace(/\r$/, "")
-    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
-    .replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, "")
-    .replace(/\x1b[P^_][\s\S]*?\x1b\\/g, "")
-    .replace(/\x1b[@-Z\\-_]/g, "")
-    .replace(/\x1b|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "");
+  return sanitizeTerminalText(line);
 }
 
 function resolveEnv(extra?: Record<string, string>): Record<string, string> {
@@ -192,11 +201,6 @@ export type ToolRefreshCallback = (
 /** Called when background auto-recovery after a disconnect or health check fails. */
 export type RecoveryFailedCallback = (serverName: string, error: Error) => void;
 
-export interface TransportAuthCallbacks {
-  /** Legacy callback type. Background transport attempts never invoke this callback. */
-  onAuthRequired: (serverName: string, authorizationUrl: URL) => void | Promise<void>;
-}
-
 // ─── Transport Factory ────────────────────────────────────────────────────────
 
 export function createTransport(
@@ -310,7 +314,7 @@ export function createTransport(
               rejectPendingStart = null;
               resolve();
             },
-            (err) => {
+            (err: unknown) => {
               rejectPendingStart = null;
               reject(err);
             },
@@ -338,7 +342,7 @@ export class ServerManager {
   private onServerStopped: ((name: string) => void) | null = null;
   private onRecoveryFailed: RecoveryFailedCallback | null = null;
 
-  constructor(config: McpConfig, _authCallbacks?: TransportAuthCallbacks, private readonly storageDir?: string) {
+  constructor(config: McpConfig, private readonly storageDir?: string) {
     this.settings = config.settings;
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
       this.servers.set(name, {
@@ -416,7 +420,7 @@ export class ServerManager {
     if (all.length === 0) return "pi-mcp: No servers configured (create ~/.pi/agent/mcp.json)";
     const lines = all.map((s) => {
       const icon = s.state === "ready" ? "✓" : s.state === "starting" ? "⟳" : "✗";
-      const err = s.lastError ? ` — ${s.lastError.message}` : "";
+      const err = s.lastError ? ` — ${sanitizeTerminalText(s.lastError.message)}` : "";
       return `  ${icon} ${s.name} (${s.state})${err}`;
     });
     const ready = all.filter((s) => s.state === "ready").length;
@@ -443,7 +447,7 @@ export class ServerManager {
     * 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> {
+  async handleUnauthorizedServerError(name: string): Promise<void> {
     const server = this.servers.get(name);
     if (!server || !server.config.auth || server.config.transport === "stdio") {
       return;
@@ -825,9 +829,9 @@ export class ServerManager {
               signal,
             });
           } catch (err) {
+            const msg = sanitizeTerminalText(err instanceof Error ? err.message : String(err));
             console.error(
-              `[pi-mcp] Failed to refresh tools for ${server.name}:`,
-              err,
+              `[pi-mcp] Failed to refresh tools for ${server.name}: ${msg}`,
             );
           }
         }
@@ -839,9 +843,12 @@ export class ServerManager {
       LoggingMessageNotificationSchema,
       async (notification) => {
         const { level = "info", logger = server.name, data } = notification.params ?? {};
-        const msg = typeof data === "string" ? data : JSON.stringify(data);
-        console.error(`[pi-mcp:${server.name}] [${level}] ${logger}: ${msg}`);
-        appendStderr(`[${level}] ${logger}: ${msg}`);
+        const rawMsg = typeof data === "string" ? data : JSON.stringify(data);
+        const safeLevel = sanitizeTerminalText(String(level), { maxLength: 32 });
+        const safeLogger = sanitizeTerminalText(String(logger), { maxLength: 100 });
+        const safeMsg = sanitizeTerminalText(rawMsg ?? "");
+        console.error(`[pi-mcp:${server.name}] [${safeLevel}] ${safeLogger}: ${safeMsg}`);
+        appendStderr(`[${safeLevel}] ${safeLogger}: ${safeMsg}`);
       },
     );
 
@@ -871,7 +878,7 @@ export class ServerManager {
       }
       if (server.config.healthCheckIntervalMs) {
         let pingInFlight = false;
-        server.healthCheckTimer = setInterval(async () => {
+        const runHealthCheck = async (): Promise<void> => {
           if (pingInFlight || server.state !== "ready" || !server.client || signal.aborted) {
             return;
           }
@@ -908,6 +915,10 @@ export class ServerManager {
               }),
             ]);
           } catch {
+            // WHY: Ping failure triggers background recovery if the server is still ready.
+            // The ping error is intentionally not kept on lastError because _recover() →
+            // _shutdown() synchronously resets lastError during teardown before any reader
+            // observes it; if reconnection fails, _recover() records the failure on lastError.
             if (server.state === "ready" && !signal.aborted) {
               void this._recover(server, server.cwd ?? cwd);
             }
@@ -917,6 +928,9 @@ export class ServerManager {
             }
             pingInFlight = false;
           }
+        };
+        server.healthCheckTimer = setInterval(() => {
+          void runHealthCheck();
         }, server.config.healthCheckIntervalMs);
       }
       // Unexpected transport close (e.g. the server subprocess crashes
@@ -954,14 +968,15 @@ export class ServerManager {
         if (server.state !== "ready" || signal.aborted || server.client !== client) {
           return;
         }
-        const msg = err instanceof Error ? err.message : String(err);
+        const rawMsg = err instanceof Error ? err.message : String(err);
         if (
           /unknown message ID|Received a response for an unknown message ID|notifications\/progress|unknown token/i.test(
-            msg,
+            rawMsg,
           )
         ) {
           return;
         }
+        const msg = sanitizeTerminalText(rawMsg);
         if (server.config.transport === "sse") {
           console.error(`[pi-mcp] Server ${server.name} SSE stream error, reconnecting: ${msg}`);
           scheduleErrorRecovery();
@@ -980,7 +995,7 @@ export class ServerManager {
           // on GET. Ignore it so POST-only servers do not enter a spurious recovery loop; genuine
           // stream drops on established streams report "SSE stream disconnected" or
           // "Maximum reconnection attempts (0) exceeded." instead.
-          if (/Failed to open SSE stream:/i.test(msg)) {
+          if (/Failed to open SSE stream:/i.test(rawMsg)) {
             return;
           }
           console.error(`[pi-mcp] Server ${server.name} HTTP stream error, reconnecting: ${msg}`);
@@ -1015,7 +1030,7 @@ export class ServerManager {
         // 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}`);
+        console.error(`[pi-mcp] ${sanitizeTerminalText(error.message)}`);
         if (signal.aborted) throw new AuthCancelledError(server.name);
         return this._connect(server, server.cwd ?? cwd, signal, true);
       }
@@ -1087,7 +1102,7 @@ export class ServerManager {
           if (err instanceof AuthCancelledError) return;
           const error = err instanceof Error ? err : new Error(String(err));
           server.lastError = error;
-          console.error(`[pi-mcp] [${server.name}] Background recovery failed: ${error.message}`);
+          console.error(`[pi-mcp] [${server.name}] Background recovery failed: ${sanitizeTerminalText(error.message)}`);
           this.onRecoveryFailed?.(server.name, error);
         });
       });

package/src/terminal-text.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure terminal-text sanitization helpers.
+ *
+ * Strips ANSI/VT escape sequences (7-bit ESC and 8-bit C1 CSI/OSC/DCS/PM/APC),
+ * C0/C1 control characters, and embedded line breaks, and bounds string length
+ * before server-controlled strings reach Pi UI notifications or process.stderr.
+ */
+
+/** Default maximum character budget for a single log or notification string. */
+export const DEFAULT_TERMINAL_TEXT_MAX_LENGTH = 500;
+
+export interface SanitizeTerminalTextOptions {
+  /** Maximum UTF-16 code units before truncating with `…` (default: 500). */
+  maxLength?: number | undefined;
+}
+
+function isHighSurrogate(code: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff;
+}
+
+function isLowSurrogate(code: number): boolean {
+  return code >= 0xdc00 && code <= 0xdfff;
+}
+
+/**
+ * Strip ANSI CSI/OSC/DCS/PM/APC sequences (7-bit and 8-bit C1), single-char ESC
+ * sequences, and C0/C1 control characters, collapse embedded CR/LF into spaces
+ * so a single log or notification cannot inject fake lines, and bound length
+ * with `…` without splitting a UTF-16 surrogate pair.
+ */
+export function sanitizeTerminalText(
+  text: string,
+  opts?: SanitizeTerminalTextOptions,
+): string {
+  const maxLength = opts?.maxLength ?? DEFAULT_TERMINAL_TEXT_MAX_LENGTH;
+  if (maxLength <= 0) {
+    return "";
+  }
+
+  const cleaned = text
+    .replace(/\r$/, "")
+    .replace(/(?:\x1b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/(?:\x1b\]|\u009d)[\s\S]*?(?:\x07|\x1b\\|\u009c|$)/g, "")
+    .replace(/(?:\x1b[PX^_]|[\u0090\u0098\u009e\u009f])[\s\S]*?(?:\x1b\\|\u009c|\x07|$)/g, "")
+    .replace(/\x1b[@-Z\\-_]/g, "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\x1b|[\x00-\x1f\x7f-\x9f]/g, "");
+
+  if (cleaned.length <= maxLength) {
+    return cleaned;
+  }
+
+  if (maxLength === 1) {
+    return "…";
+  }
+
+  let end = maxLength - 1;
+  if (
+    end > 0 &&
+    isHighSurrogate(cleaned.charCodeAt(end - 1)) &&
+    isLowSurrogate(cleaned.charCodeAt(end))
+  ) {
+    end -= 1;
+  }
+
+  return `${cleaned.slice(0, end)}…`;
+}

package/src/tool-bridge.ts

@@ -110,7 +110,7 @@ function extractSchemaOptions(schema: Record<string, unknown>): Record<string, u
 
 function withSchemaOptions(schema: TSchema, opts: Record<string, unknown>): TSchema {
   if (Object.keys(opts).length === 0) return schema;
-  const clone = Object.defineProperties({}, Object.getOwnPropertyDescriptors(schema)) as TSchema;
+  const clone = Object.defineProperties<TSchema>({}, Object.getOwnPropertyDescriptors(schema));
   return Object.assign(clone, opts);
 }
 
@@ -566,6 +566,7 @@ export function convertJsonSchemaToTypebox(
       // rather than `Type.Record` (`patternProperties`), which Gemini and OpenAI reject.
       return Type.Object(props, objOpts);
     }
+    case undefined:
     default:
       return Type.Any(opts);
   }
@@ -678,7 +679,7 @@ export async function listAllTools(
       throw new AuthCancelledError(serverName);
     }
     if (pageCount >= MAX_PAGES) {
-      console.warn(
+      console.error(
         `[pi-mcp] tools/list pagination exceeded ${MAX_PAGES} pages, stopping. The server may be malfunctioning.`,
       );
       break;