@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/mcp/__tests__/mcp-oauth-client-registration.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Reuse and invalidation of the stored dynamic client registration.
+ *
+ * Dynamic registration writes a record on the authorization server, so
+ * registering per attempt leaves records behind that nobody cleans up. The
+ * stored registration is therefore reused, and only withheld when it
+ * provably no longer applies. Both halves matter: reusing one bound to a
+ * stale redirect URI produces authorization requests the server rejects,
+ * and re-registering unnecessarily is the accumulation this exists to stop.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const CALLBACK_URL =
+  "https://platform.example/v1/gateway/callbacks/abc/webhooks/oauth/callback/";
+
+let resolvedCallbackUrl = CALLBACK_URL;
+
+mock.module("../../inbound/platform-callback-registration.js", () => ({
+  resolveCallbackUrl: async () => resolvedCallbackUrl,
+}));
+
+mock.module("../../inbound/public-ingress-urls.js", () => ({
+  getOAuthCallbackUrl: () => resolvedCallbackUrl,
+}));
+
+mock.module("../../config/loader.js", () => ({
+  loadConfig: () => ({}),
+}));
+
+/** In-memory stand-in for the credential store. */
+const store = new Map<string, string>();
+
+mock.module("../../security/secure-keys.js", () => ({
+  getSecureKeyAsync: async (k: string) => store.get(k) ?? null,
+  setSecureKeyAsync: async (k: string, v: string) => {
+    store.set(k, v);
+    return true;
+  },
+  deleteSecureKeyAsync: async (k: string) =>
+    store.delete(k) ? "deleted" : "not-found",
+}));
+
+mock.module("../../daemon/identity-helpers.js", () => ({
+  getAssistantName: () => "Jarvis",
+}));
+
+mock.module("../../config/env.js", () => ({
+  getPlatformAssistantId: () => "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+}));
+
+const { McpOAuthProvider } = await import("../mcp-oauth-provider.js");
+
+const REGISTRATION = { client_id: "generated-client-id" };
+
+function newProvider() {
+  return new McpOAuthProvider(
+    "unabyss",
+    "https://mcp.unabyss.com",
+    /* interactive */ false,
+  );
+}
+
+/** Seed discovery state the way the SDK would after running discovery. */
+async function seedDiscovery(
+  provider: InstanceType<typeof McpOAuthProvider>,
+  issuer: string,
+): Promise<void> {
+  await provider.saveDiscoveryState({
+    authorizationServerUrl: issuer,
+    authorizationServerMetadata: { issuer },
+  } as never);
+}
+
+/** Run one registration the way a completed flow would. */
+async function register(issuer = "https://mcp.unabyss.com"): Promise<void> {
+  const provider = newProvider();
+  await provider.startCallbackServer();
+  await seedDiscovery(provider, issuer);
+  await provider.saveClientInformation(REGISTRATION as never);
+  provider.stopCallbackServer();
+}
+
+beforeEach(() => {
+  store.clear();
+  resolvedCallbackUrl = CALLBACK_URL;
+});
+
+describe("McpOAuthProvider client registration reuse", () => {
+  test("a stored registration is reused on the next flow", async () => {
+    await register();
+
+    const next = newProvider();
+    await next.startCallbackServer();
+    await seedDiscovery(next, "https://mcp.unabyss.com");
+
+    // Returning the stored value is what keeps the server from accruing a
+    // fresh client record on every `assistant mcp auth`.
+    expect(await next.clientInformation()).toEqual(REGISTRATION as never);
+  });
+
+  test("no stored registration means the SDK registers", async () => {
+    const provider = newProvider();
+    await provider.startCallbackServer();
+    expect(await provider.clientInformation()).toBeUndefined();
+  });
+
+  test("a changed redirect URI withholds the registration", async () => {
+    await register();
+
+    // The assistant moved, so its callback URL moved with it. The stored
+    // client is registered for the old one and the server would reject it.
+    resolvedCallbackUrl = "https://other.example/webhooks/oauth/callback";
+    const next = newProvider();
+    await next.startCallbackServer();
+    await seedDiscovery(next, "https://mcp.unabyss.com");
+
+    expect(await next.clientInformation()).toBeUndefined();
+  });
+
+  test("a changed authorization server withholds the registration", async () => {
+    await register("https://auth.unabyss.com");
+
+    const next = newProvider();
+    await next.startCallbackServer();
+    await seedDiscovery(next, "https://different-auth.example");
+
+    expect(await next.clientInformation()).toBeUndefined();
+  });
+
+  test("a silent reconnect reuses the registration without a redirect URI", async () => {
+    await register();
+
+    // `McpClient.connect` never prepares a callback, so `_redirectUrl` is
+    // unset. Treating that as a mismatch would turn every background
+    // reconnect into a registration.
+    const silent = newProvider();
+    await seedDiscovery(silent, "https://mcp.unabyss.com");
+
+    expect(await silent.clientInformation()).toEqual(REGISTRATION as never);
+  });
+
+  test("a registration stored before bindings existed is kept", async () => {
+    // Upgrading must not invalidate every existing registration at once.
+    store.set(
+      "mcp:unabyss:client_info",
+      JSON.stringify({ client_id: "legacy" }),
+    );
+
+    const provider = newProvider();
+    await provider.startCallbackServer();
+    await seedDiscovery(provider, "https://mcp.unabyss.com");
+
+    expect(await provider.clientInformation()).toEqual({
+      client_id: "legacy",
+    } as never);
+  });
+
+  test("invalidating the client drops its binding too", async () => {
+    await register();
+    expect(store.has("mcp:unabyss:client_binding")).toBe(true);
+
+    const provider = newProvider();
+    await provider.invalidateCredentials("client");
+
+    expect(store.has("mcp:unabyss:client_info")).toBe(false);
+    // A surviving binding would let the next registration inherit the
+    // previous one's issuer and redirect URI.
+    expect(store.has("mcp:unabyss:client_binding")).toBe(false);
+  });
+});
+
+describe("McpOAuthProvider client metadata", () => {
+  test("registers under the assistant's own name", async () => {
+    const provider = newProvider();
+    expect(provider.clientMetadata.client_name).toEqual("Jarvis");
+  });
+
+  test("carries the assistant id as software_id", async () => {
+    const provider = newProvider();
+    expect(provider.clientMetadata.software_id).toEqual(
+      "019d6d4f-6dbd-779f-91d3-cb273b9429a5",
+    );
+  });
+
+  test("presents an anonymously fetchable logo", async () => {
+    // The consent screen loads this without credentials, so it cannot be
+    // the assistant's own avatar, which is served behind authentication.
+    const provider = newProvider();
+    expect(provider.clientMetadata.logo_uri).toEqual(
+      "https://www.vellum.ai/favicon.svg",
+    );
+  });
+
+  test("registers the resolved callback URL as the redirect URI", async () => {
+    const provider = newProvider();
+    await provider.startCallbackServer();
+    expect(provider.clientMetadata.redirect_uris).toEqual([CALLBACK_URL]);
+  });
+});

package/src/mcp/__tests__/mcp-oauth-provider.test.ts

@@ -16,22 +16,24 @@ mock.module("../../inbound/public-ingress-urls.js", () => ({
 
 mock.module("../../config/loader.js", () => ({
   loadConfig: () => ({}),
+  // `clientMetadata` reads the assistant's name, which pulls the persona
+  // resolver into the provider's import graph, and that reads config.
+  getConfig: () => ({}),
 }));
 
 // ── Import SUT after mocks ────────────────────────────────────────────────────
 
 const { McpOAuthProvider } = await import("../mcp-oauth-provider.js");
 
-function newGatewayProvider() {
+function newProvider() {
   return new McpOAuthProvider(
     "comms",
     "https://comms.example/mcp",
     /* interactive */ false,
-    "gateway",
   );
 }
 
-describe("McpOAuthProvider gateway callback", () => {
+describe("McpOAuthProvider callback", () => {
   test("stopCallbackServer() before a consumer attaches does not emit an unhandled rejection", async () => {
     // stopCallbackServer() rejects the deferred code promise. When no consumer
     // is attached, that rejection must stay observed so it does not surface as
@@ -40,7 +42,7 @@ describe("McpOAuthProvider gateway callback", () => {
     const onUnhandled = (reason: unknown) => unhandled.push(reason);
     process.on("unhandledRejection", onUnhandled);
     try {
-      const provider = newGatewayProvider();
+      const provider = newProvider();
 
       // Intentionally do NOT consume the returned codePromise — this mirrors the
       // early-exit paths where connect() throws before the OAuth tail is wired up.
@@ -53,7 +55,7 @@ describe("McpOAuthProvider gateway callback", () => {
       const cancelRejections = unhandled.filter(
         (r) =>
           r instanceof Error &&
-          r.message.includes("MCP OAuth gateway callback cancelled"),
+          r.message.includes("MCP OAuth callback cancelled"),
       );
       expect(cancelRejections).toHaveLength(0);
     } finally {
@@ -62,14 +64,12 @@ describe("McpOAuthProvider gateway callback", () => {
   });
 
   test("stopCallbackServer() still rejects a consumer that is awaiting the code", async () => {
-    const provider = newGatewayProvider();
+    const provider = newProvider();
     await provider.startCallbackServer();
 
     const codePromise = provider.waitForCode();
     provider.stopCallbackServer();
 
-    await expect(codePromise).rejects.toThrow(
-      "MCP OAuth gateway callback cancelled",
-    );
+    await expect(codePromise).rejects.toThrow("MCP OAuth callback cancelled");
   });
 });

package/src/mcp/__tests__/plugin-server-credential-isolation.test.ts

@@ -0,0 +1,95 @@
+/**
+ * A plugin-declared server must connect without resolving
+ * `mcp:<serverId>:*` from the workspace credential store.
+ *
+ * A plugin controls both its server key and its URL, so a stored
+ * credential whose id happens to match would otherwise be sent to an
+ * endpoint the plugin chose. The listing route avoids this by never
+ * probing a plugin server; the connect path avoids it by reading the
+ * server's own `source`, so the rule cannot be lost by a caller that
+ * forgets to pass something.
+ */
+
+import { beforeEach, describe, expect, jest, mock, test } from "bun:test";
+
+const getSecureKeyAsync = jest.fn(async (_key: string) => "stored-oauth-token");
+const getMcpHeaders = jest.fn(async (_serverId: string) => ({
+  Authorization: "Bearer workspace-secret",
+}));
+
+mock.module("../../security/secure-keys.js", () => ({
+  getSecureKeyAsync,
+  setSecureKeyAsync: jest.fn(async () => true),
+  deleteSecureKeyAsync: jest.fn(async () => "deleted"),
+}));
+
+mock.module("../mcp-header-store.js", () => ({
+  getMcpHeaders,
+  setMcpHeaders: jest.fn(async () => {}),
+  deleteMcpHeaders: jest.fn(async () => true),
+}));
+
+// `McpOAuthProvider` is left real: its constructor only assigns fields, and
+// mocking the module here would bleed into the sibling provider tests.
+const { McpServerManager } = await import("../manager.js");
+
+/** Refused immediately, so `connect` fails after the credential lookups. */
+const UNREACHABLE = "http://127.0.0.1:1/mcp";
+
+function httpServer(source: "workspace" | "plugin") {
+  return {
+    transport: { type: "streamable-http" as const, url: UNREACHABLE },
+    enabled: true,
+    defaultRiskLevel: "low" as const,
+    maxTools: 20,
+    source,
+  };
+}
+
+describe("plugin-declared MCP servers", () => {
+  beforeEach(() => {
+    getSecureKeyAsync.mockClear();
+    getMcpHeaders.mockClear();
+  });
+
+  test("connect without resolving workspace credentials", async () => {
+    const manager = new McpServerManager();
+
+    await manager.start({
+      servers: { unabyss: httpServer("plugin") },
+      globalMaxTools: 50,
+    });
+
+    expect(getMcpHeaders).not.toHaveBeenCalled();
+    expect(getSecureKeyAsync).not.toHaveBeenCalled();
+  });
+
+  test("workspace servers keep resolving theirs", async () => {
+    const manager = new McpServerManager();
+
+    await manager.start({
+      servers: { "from-workspace": httpServer("workspace") },
+      globalMaxTools: 50,
+    });
+
+    expect(getMcpHeaders).toHaveBeenCalledWith("from-workspace");
+    expect(getSecureKeyAsync).toHaveBeenCalledWith("mcp:from-workspace:tokens");
+  });
+
+  test("isolation is per-server, not per-start", async () => {
+    // Both kinds start together in one call — the plugin one must not
+    // widen credential access for the workspace one, or vice versa.
+    const manager = new McpServerManager();
+
+    await manager.start({
+      servers: {
+        unabyss: httpServer("plugin"),
+        "from-workspace": httpServer("workspace"),
+      },
+      globalMaxTools: 50,
+    });
+
+    const lookedUpIds = getMcpHeaders.mock.calls.map(([id]) => id);
+    expect(lookedUpIds).toEqual(["from-workspace"]);
+  });
+});

package/src/mcp/client.ts

@@ -5,8 +5,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 
-import { getIsPlatform } from "../config/env-registry.js";
-import type { McpTransport } from "../config/schemas/mcp.js";
+import type { McpServerSource, McpTransport } from "../config/schemas/mcp.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { getMcpHeaders } from "./mcp-header-store.js";
@@ -55,6 +54,12 @@ export interface McpCallResult {
 
 export class McpClient {
   readonly serverId: string;
+  /**
+   * Where this server was declared. Only a `workspace` server resolves
+   * `mcp:<serverId>:tokens` / `mcp:<serverId>:headers` from the credential
+   * store — see {@link McpServerSource} for why a plugin server must not.
+   */
+  readonly source: McpServerSource;
   private client: Client;
   private transport:
     | StdioClientTransport
@@ -74,8 +79,9 @@ export class McpClient {
     return this.connected;
   }
 
-  constructor(serverId: string) {
+  constructor(serverId: string, source: McpServerSource = "workspace") {
     this.serverId = serverId;
+    this.source = source;
     this.client = new Client({
       name: "vellum-assistant",
       version: "1.0.0",
@@ -100,22 +106,21 @@ export class McpClient {
     const isHttpTransport =
       transportConfig.type === "sse" ||
       transportConfig.type === "streamable-http";
+    const usesStoredCredentials = this.source === "workspace";
 
-    // For HTTP transports, only attach an OAuth provider if cached tokens exist.
-    // This avoids triggering client registration (which binds to a random port)
-    // during daemon startup. If no tokens, try without auth — if the server
-    // requires it, skip silently.
-    if (isHttpTransport) {
+    // For HTTP transports, only attach an OAuth provider if cached tokens
+    // exist. This avoids triggering client registration during daemon
+    // startup. If no tokens, try without auth: if the server requires it,
+    // skip silently.
+    if (isHttpTransport && usesStoredCredentials) {
       const cachedTokens = await getSecureKeyAsync(
         `mcp:${this.serverId}:tokens`,
       );
       if (cachedTokens) {
-        const callbackTransport = getIsPlatform() ? "gateway" : "loopback";
         this.oauthProvider = new McpOAuthProvider(
           this.serverId,
           transportConfig.url,
           /* interactive */ false,
-          callbackTransport,
         );
       }
     }
@@ -123,7 +128,7 @@ export class McpClient {
     // Resolve static auth headers from credential store, falling back to
     // any legacy headers in the transport config for backward compatibility.
     let effectiveConfig = transportConfig;
-    if (isHttpTransport) {
+    if (isHttpTransport && usesStoredCredentials) {
       const storedHeaders = await getMcpHeaders(this.serverId);
       if (storedHeaders) {
         effectiveConfig = {

package/src/mcp/effective-config.ts

@@ -0,0 +1,113 @@
+/**
+ * The MCP configuration the daemon actually runs.
+ *
+ * Two sources contribute servers: the workspace `config.json`, which the
+ * user owns, and each installed plugin's `mcp.json`, which its author
+ * owns. Both must reach the MCP manager, so every consumer that starts
+ * servers builds its config through here rather than reading
+ * `config.mcp` directly — a path that only reads the workspace half
+ * leaves a plugin's tools silently missing.
+ *
+ * Every server comes out attributed with its {@link McpServerSource}, so
+ * the one place origin still matters downstream — a plugin server must
+ * never resolve `mcp:<serverId>:*` from the credential store — reads it
+ * off the server rather than from a caller-supplied list.
+ */
+
+import {
+  type McpConfig,
+  McpConfigSchema,
+  type ResolvedMcpConfig,
+  type ResolvedMcpServerConfig,
+} from "../config/schemas/mcp.js";
+import { readPluginMcpServers } from "../plugins/mcp-servers.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("mcp-effective-config");
+
+/**
+ * Fingerprint of the plugin-declared servers in the config last built here.
+ * Null until the first build, which happens during daemon startup.
+ */
+let lastBuiltPluginFingerprint: string | null = null;
+
+/**
+ * Merge the workspace MCP config with the servers plugins declare.
+ *
+ * A workspace entry outranks a plugin's declaration of the same id: the
+ * user's own configuration is the more specific statement, and it is the
+ * one they can edit. `internal_mcp_list` applies the same precedence, so
+ * what the listing shows is what the daemon runs.
+ */
+export function buildEffectiveMcpConfig(
+  workspaceConfig?: McpConfig,
+): ResolvedMcpConfig {
+  // An absent `mcp` key still has to yield the schema's own defaults
+  // (`globalMaxTools`), since plugin servers alone are enough to need them.
+  const base = workspaceConfig ?? McpConfigSchema.parse({});
+  const servers: Record<string, ResolvedMcpServerConfig> = {};
+  for (const [id, config] of Object.entries(base.servers)) {
+    servers[id] = { ...config, source: "workspace" };
+  }
+
+  const { servers: pluginServers, issues } = readPluginMcpServers();
+  for (const issue of issues) {
+    log.warn(
+      {
+        plugin: issue.pluginName,
+        ...(issue.serverKey && { serverKey: issue.serverKey }),
+      },
+      `Plugin MCP declaration problem: ${issue.message}`,
+    );
+  }
+
+  for (const server of pluginServers) {
+    if (Object.hasOwn(servers, server.id)) {
+      log.warn(
+        { plugin: server.pluginName, serverId: server.id },
+        "Plugin MCP server shadowed by a workspace server of the same id; skipping",
+      );
+      continue;
+    }
+    servers[server.id] = server.config;
+  }
+
+  lastBuiltPluginFingerprint = fingerprintPluginServers();
+
+  return { ...base, servers };
+}
+
+/**
+ * Whether the plugin-declared servers on disk differ from the ones in the
+ * config last built by {@link buildEffectiveMcpConfig}.
+ *
+ * The plugin source reconcile asks this after an install / uninstall /
+ * upgrade / enable / disable, so an MCP reload happens exactly when a
+ * plugin actually changed the server set — not on every unrelated plugin
+ * edit, which would tear down healthy workspace connections for nothing.
+ *
+ * True before the first build, since nothing has been applied yet.
+ */
+export function pluginMcpServersChangedSinceLastBuild(): boolean {
+  return fingerprintPluginServers() !== lastBuiltPluginFingerprint;
+}
+
+/**
+ * Stable digest of every plugin-declared server: its id and the config it
+ * resolves to. Covers a server appearing, disappearing, or changing its
+ * transport — a disabled or uninstalled plugin contributes nothing, so it
+ * drops out of the digest the same way a deleted `mcp.json` entry does.
+ */
+function fingerprintPluginServers(): string {
+  const { servers } = readPluginMcpServers();
+  return JSON.stringify(
+    [...servers]
+      .sort((a, b) => a.id.localeCompare(b.id))
+      .map((s) => [s.id, s.config]),
+  );
+}
+
+/** Test seam: forget the last built config, as on a fresh daemon. */
+export function resetEffectiveMcpConfigForTests(): void {
+  lastBuiltPluginFingerprint = null;
+}

package/src/mcp/manager.ts

@@ -1,4 +1,7 @@
-import type { McpConfig, McpServerConfig } from "../config/schemas/mcp.js";
+import type {
+  ResolvedMcpConfig,
+  ResolvedMcpServerConfig,
+} from "../config/schemas/mcp.js";
 import { getLogger } from "../util/logger.js";
 import { McpClient, type McpToolInfo } from "./client.js";
 
@@ -6,15 +9,15 @@ const log = getLogger("mcp-manager");
 
 export interface McpServerToolInfo {
   serverId: string;
-  serverConfig: McpServerConfig;
+  serverConfig: ResolvedMcpServerConfig;
   tools: McpToolInfo[];
 }
 
 export class McpServerManager {
   private clients = new Map<string, McpClient>();
-  private serverConfigs = new Map<string, McpServerConfig>();
+  private serverConfigs = new Map<string, ResolvedMcpServerConfig>();
 
-  async start(config: McpConfig): Promise<McpServerToolInfo[]> {
+  async start(config: ResolvedMcpConfig): Promise<McpServerToolInfo[]> {
     const results: McpServerToolInfo[] = [];
 
     console.log(
@@ -40,7 +43,9 @@ export class McpServerManager {
             "HTTP transport — OAuth provider will be available if server requires authentication",
           );
         }
-        const client = new McpClient(serverId);
+        // The server's own origin decides whether it may resolve
+        // `mcp:<serverId>:*` from the credential store.
+        const client = new McpClient(serverId, serverConfig.source);
         await client.connect(serverConfig.transport);
 
         if (!client.isConnected) {
@@ -142,7 +147,7 @@ export class McpServerManager {
 
   private filterTools(
     tools: McpToolInfo[],
-    config: McpServerConfig,
+    config: ResolvedMcpServerConfig,
   ): McpToolInfo[] {
     let filtered = tools;
 

package/src/mcp/mcp-auth-orchestrator.ts

@@ -13,7 +13,6 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
-import { getIsContainerized } from "../config/env-registry.js";
 import { reloadMcpServers } from "../daemon/mcp-reload-service.js";
 import { getLogger } from "../util/logger.js";
 import {
@@ -22,10 +21,7 @@ import {
   setMcpAuthPending,
 } from "./mcp-auth-state.js";
 import { getMcpHeaders } from "./mcp-header-store.js";
-import {
-  type McpOAuthCallbackTransport,
-  McpOAuthProvider,
-} from "./mcp-oauth-provider.js";
+import { McpOAuthProvider } from "./mcp-oauth-provider.js";
 
 const log = getLogger("mcp-auth-orchestrator");
 
@@ -53,20 +49,11 @@ export async function orchestrateMcpOAuthConnect(args: {
 }): Promise<OrchestrateMcpOAuthConnectResult> {
   const { serverId, transport } = args;
 
-  // Containerized deployments (platform-managed AND self-hosted Docker) must
-  // use the gateway transport: the browser is outside the daemon container,
-  // so a loopback callback inside the container is unreachable. Bare-metal
-  // daemons can use loopback as before.
-  const callbackTransport: McpOAuthCallbackTransport = getIsContainerized()
-    ? "gateway"
-    : "loopback";
-
   let capturedAuthUrl: string | undefined;
   const provider = new McpOAuthProvider(
     serverId,
     transport.url,
     /* interactive */ false,
-    callbackTransport,
     {
       onAuthorizationUrl: (url) => {
         capturedAuthUrl = url;
@@ -74,8 +61,11 @@ export async function orchestrateMcpOAuthConnect(args: {
     },
   );
 
-  // Clear stale credentials so the flow starts fresh
-  await provider.invalidateCredentials("client");
+  // Re-discover, but keep the client registration. Discovery is a read and
+  // costs a request; registration is a write on the authorization server,
+  // and remaking it per attempt leaves a record behind every time. The
+  // provider drops a stored registration on its own when the redirect URI
+  // or the authorization server it was made against has changed.
   await provider.invalidateCredentials("discovery");
 
   // Register the pending callback in the daemon heap
@@ -146,10 +136,9 @@ export async function orchestrateMcpOAuthConnect(args: {
   // so the daemon can reconnect on the next MCP reload without re-connecting here.
   void (async () => {
     try {
-      // Apply an explicit timeout: the loopback callback path has a built-in
-      // 2-minute timer, but the gateway transport's deferred promise relies on
-      // the caller for time-boxing. Without this race, gateway-mode tails leak
-      // forever if the user never completes the OAuth handshake.
+      // Apply an explicit timeout: the deferred code promise relies on the
+      // caller for time-boxing. Without this race, a tail leaks forever if
+      // the user never completes the OAuth handshake.
       const code = await Promise.race([
         codePromise,
         new Promise<never>((_, reject) => {
@@ -215,6 +204,8 @@ export async function orchestrateMcpOAuthConnect(args: {
   return { auth_url: capturedAuthUrl };
 }
 
-// Matches the loopback callback timeout; keep both in lockstep so loopback
-// and gateway transports time-box OAuth identically.
+// How long a user has to complete the browser handshake before the tail
+// gives up. Shorter than the callback registry's own 5-minute TTL, so the
+// failure surfaces here with a clear message rather than as a registry
+// expiry the caller cannot attribute.
 const CALLBACK_TIMEOUT_MS = 2 * 60 * 1000;