mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -1,4 +1,5 @@
 // Deferred-pool and MCP-instruction manifests injected into BP2.
+import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 
 export function compactPromptManifestText(value, max = 250) {
   const text = String(value || '')
@@ -100,16 +101,21 @@ function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
  * names per server doubled the MCP share of the BP2 prefix (2026-08-05 audit).
  * Server membership stays evident from the mcp__<server>__ name prefix.
  */
-function buildMcpInstructionsManifest(mcpServerInstructions, poolNames) {
+function buildMcpInstructionsManifest(mcpServerInstructions, poolNames, catalog = []) {
   const map = mcpServerInstructions && typeof mcpServerInstructions === 'object' ? mcpServerInstructions : {};
   const pool = [
     ...new Set((Array.isArray(poolNames) ? poolNames : []).map((name) => sanitizeManifestName(name)).filter(Boolean)),
   ];
+  // Tool definitions carry their server (shortened names cannot be parsed).
+  const byName = new Map();
+  for (const tool of Array.isArray(catalog) ? catalog : []) {
+    const name = String(tool?.name || '').trim();
+    if (name && !byName.has(name)) byName.set(name, tool);
+  }
   const deferredServers = new Set();
   for (const name of pool) {
-    const match = name.match(/^mcp__(.+?)__(.+)$/);
-    if (!match) continue;
-    deferredServers.add(match[1]);
+    const server = parseMcpToolName(byName.get(name) || name)?.server;
+    if (server) deferredServers.add(server);
   }
   const servers = [...deferredServers]
     .filter((server) => sanitizeManifestName(server) && sanitizeMcpInstructionText(map[server]))
@@ -170,7 +176,7 @@ function composeDeferredBp2Manifest(session, pool) {
   const parts = [];
   const deferredManifest = buildDeferredToolManifest(deferredManifestEntries(session, pool));
   if (deferredManifest) parts.push(deferredManifest);
-  const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool);
+  const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool, session.deferredToolCatalog);
   if (mcpManifest) parts.push(mcpManifest);
   return parts.join('\n\n');
 }

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -3,15 +3,16 @@
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { maxMtimeRecursive } from '../cache-mtime.mjs';
+import { maxMtimeRecursive, mtimeSignatureRecursive } from '../cache-mtime.mjs';
 import { mixdogHome, resolvePluginData, mixdogRoot } from '../../../shared/plugin-paths.mjs';
-import { pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
+import { PLUGIN_MANIFEST_FILES, pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
 import {
   parseSkillDocument,
   SKILL_TRIGGER_LISTING_MAX,
   SKILL_TRIGGER_LISTING_MIN,
 } from '../../../shared/skill-document.mjs';
 import { readSkillToolDependencies, skillToolDependenciesRoot } from '../../../shared/skill-tool-dependencies.mjs';
+import { SKILL_LAUNCHER_COMMAND } from '../../../shared/skill-script-runtime.mjs';
 import { loadConfig, normalizeSkillsConfig } from '../config.mjs';
 import { builtinFeatureActive, withGrandfatheredBuiltins } from '../runtime-core/builtin-features.mjs';
 import { SKILL_TOOL } from '../runtime-core/tool-defs.mjs';
@@ -88,6 +89,32 @@ function pluginSkillDirs() {
   return dirs;
 }
 
+/** Paths whose own mtime (no recursion) gates the skill list for enabled
+ *  registered plugins: every manifest file, plus the nearest existing ancestor
+ *  of each candidate skills root (so a skills dir created later is noticed). */
+function pluginShallowWatchPaths() {
+  const registryPath = pluginRegistryPath();
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+  const paths = [];
+  for (const entry of Array.isArray(registry?.plugins) ? registry.plugins : []) {
+    if (entry?.enabled === false) continue;
+    const root = entry && typeof entry.root === 'string' ? entry.root : null;
+    if (!root || !existsSync(root)) continue;
+    for (const rel of PLUGIN_MANIFEST_FILES) paths.push(join(root, ...rel.split('/')));
+    for (const skillsDir of pluginSkillsRoots(root)) {
+      let dir = skillsDir;
+      while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
+      paths.push(dir);
+    }
+  }
+  return paths;
+}
+
 export function readSafe(path) {
   try {
     if (!existsSync(path)) return null;
@@ -216,24 +243,39 @@ function followsBuiltinFeature(skill) {
   return skill?.source === 'builtin' && Array.isArray(skill.requires) && skill.requires.length > 0;
 }
 
-function findCachedSkillByKey(key) {
-  return collectSkillsCached(null).find((entry) => normalizeSkillNameKey(entry.name) === key);
+function findCachedSkillByKey(key, skills = null) {
+  return (skills || collectSkillsCached(null)).find((entry) => normalizeSkillNameKey(entry.name) === key);
 }
 
-export function isSkillDisabled(name, config = null) {
+/** `skills`: optional snapshot from one collectSkillsCached() call, reused so a
+ *  batch of per-skill checks scans the disk once. */
+export function isSkillDisabled(name, config = null, skills = null) {
   const n = normalizeSkillNameKey(name);
   if (!n) return false;
-  const skill = findCachedSkillByKey(n);
+  const skill = findCachedSkillByKey(n, skills);
   if (!followsBuiltinFeature(skill) && getDisabledSkillNameSet(config).has(n)) return true;
   return Boolean(skill && missingFeature(skill, featureConfig(config)));
 }
 
 /** The built-in feature a skill needs that is not active, or null. */
-export function skillMissingFeature(name, config = null) {
-  const skill = findCachedSkillByKey(normalizeSkillNameKey(name));
+export function skillMissingFeature(name, config = null, skills = null) {
+  const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
   return skill ? missingFeature(skill, featureConfig(config)) : null;
 }
 
+/** True when an installed skill exists but its (or its plugin's) project scope
+ *  excludes `cwd` — the same scope rule filterSkillsExcludingDisabled applies. */
+export function skillOutsideScope(name, cwd, config = null, skills = null) {
+  const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
+  if (!skill) return false;
+  return !skillAllowedForCwd(extensionScopesFromConfig(featureConfig(config)), skill, cwd);
+}
+
+/** The Skill tool result for a skill skillOutsideScope refuses. */
+export function skillOutsideScopeError(name) {
+  return `Error: skill "${name}" is not available in this project (its project scope excludes the current folder)`;
+}
+
 /**
  * Skills a session may see: not switched off, feature available, and — when
  * `cwd` is given — inside the skill's (or its plugin's) project scope. Without
@@ -260,8 +302,6 @@ export function collectPromptSkillsCached(cwd, config = null) {
 }
 // --- Global skill cache (mtime-based) ---
 const _skillsCache = new Map();
-const _mtimeCache = new Map();
-const _MTIME_TTL_MS = 2000;
 
 export function collectSkillsCached(cwd) {
   if (skillsDisabled()) return [];
@@ -273,32 +313,41 @@ export function collectSkillsCached(cwd) {
   skillsDirs.push(...pluginSkillDirs().map(({ dir }) => dir), ...builtinSkillDirs());
   // registry.json itself gates plugin add/remove: removal deletes the
   // plugin's skills dir (so no dir mtime advances), but saveRegistry()
-  // always rewrites this file. maxMtimeRecursive stats plain files directly.
+  // always rewrites this file. mtimeSignatureRecursive stats plain files directly.
   const registryPath = pluginRegistryPath();
   if (registryPath) skillsDirs.push(registryPath);
-  const mtime = mtimeWithTtl(_mtimeCache, key, skillsDirs, _MTIME_TTL_MS);
+  // Exact, un-timed gate: stat every call. The shallow watch list covers
+  // manifest edits and skill roots that do not exist yet.
+  const signature = `${mtimeSignatureRecursive(skillsDirs)}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
   const entry = _skillsCache.get(key);
-  if (entry && entry.mtime >= mtime) {
+  if (entry && entry.signature === signature) {
     return entry.value;
   }
   const skills = collectSkills(cwd);
-  _skillsCache.set(key, { value: skills, mtime });
+  _skillsCache.set(key, { value: skills, signature });
   capMapSize(_skillsCache);
   return skills;
 }
 export function invalidateSkillsCache(cwd) {
   void cwd;
   _skillsCache.clear();
-  _mtimeCache.clear();
 }
-/** Drop only the mtime TTL so the next call re-stats the skill roots while the
- *  cached list stays — lets a test prove the gate itself notices an edit. */
-export function invalidateSkillsMtimeGate() {
-  _mtimeCache.clear();
+
+/**
+ * Directory the model hands to external processes for a skill. A packaged
+ * desktop runtime reads built-in skills from inside `runtime.asar`, which only
+ * Electron can open; the build ships them as real files beside the archive
+ * under `runtime.asar.unpacked`, so a built-in skill's directory points there.
+ * Every other source keeps its own on-disk directory.
+ */
+export function skillExecutionDir(dir, source) {
+  if (source !== 'builtin') return dir;
+  return String(dir).replace(/([\\/])runtime\.asar(?=[\\/]|$)/, '$1runtime.asar.unpacked');
 }
 
 /**
- * Load full skill content plus its on-disk directory (for base-dir + ${MIXDOG_SKILL_DIR}).
+ * Load full skill content plus its on-disk directory (for base-dir + ${MIXDOG_SKILL_DIR};
+ * ${MIXDOG_SKILL_NODE} is resolved at render time in buildSkillResultEnvelope).
  */
 export function loadSkillResource(name, cwd) {
   const skillName = String(name || '').trim();
@@ -311,7 +360,7 @@ export function loadSkillResource(name, cwd) {
   try {
     return {
       content: parseSkillDocument(content).body,
-      dir: dirname(skill.filePath),
+      dir: skillExecutionDir(dirname(skill.filePath), skill.source),
       filePath: skill.filePath,
       source: skill.source || 'global',
       toolDependencies: skill.toolDependencies || [],
@@ -335,6 +384,10 @@ export function buildSkillResultEnvelope(name, content, skillDir) {
   const escapedName = escapeSkillXmlText(name);
   let body = String(content == null ? '' : content);
   let dirLine = '';
+  // `${MIXDOG_SKILL_NODE}` runs a bundled script on this daemon's own runtime
+  // (plain node cannot load runtime internals from a packaged archive). It is
+  // one shell-neutral command name that model shells find on their PATH.
+  body = body.replace(/\$\{MIXDOG_SKILL_NODE\}/g, SKILL_LAUNCHER_COMMAND);
   if (skillDir) {
     const normDir = String(skillDir).replace(/\\/g, '/');
     body = body.replace(/\$\{MIXDOG_SKILL_DIR\}/g, normDir);

package/src/runtime/agent/orchestrator/mcp/client-config.mjs

@@ -3,6 +3,8 @@
  * kind, URL policy, env expansion, stdio environment, HTTP headers, timeouts,
  * and the log scrubbing that keeps credentials out of connection messages.
  */
+import { createHash } from 'node:crypto';
+import { rememberMcpToolIdentity } from '../../../shared/tool-primitives.mjs';
 
 /** Known auto-detect targets: the discovery-advert service name and the MCP
  *  endpoint path on its port.
@@ -77,20 +79,41 @@ export function mcpUrlForLog(raw) {
 
 function replaceSecret(text, value) {
   const secret = String(value || '');
-  return secret.length >= 4 ? text.split(secret).join('[redacted]') : text;
+  return secret ? text.split(secret).join('[redacted]') : text;
 }
 
-export function scrubMcpConnectionMessage(value, cfg = {}) {
-  let text = String(value || '');
+// Configured URL parts and header values shorter than 4 characters are left
+// alone: redacting e.g. the `1` of `?v=1` would mangle every message. Known
+// connection secrets (OAuth tokens) are redacted at any length.
+function replaceConfiguredSecret(text, value) {
+  return String(value || '').length >= 4 ? replaceSecret(text, value) : text;
+}
+
+/** `value` with every one of `secrets` redacted from its strings, recursing
+ *  into arrays and plain objects (tool results, JSON-RPC error data). */
+export function scrubMcpSecrets(value, secrets) {
+  if (secrets.length === 0) return value;
+  if (typeof value === 'string') return secrets.reduce(replaceSecret, value);
+  if (Array.isArray(value)) return value.map((item) => scrubMcpSecrets(item, secrets));
+  const proto = value && typeof value === 'object' ? Object.getPrototypeOf(value) : undefined;
+  if (proto !== Object.prototype && proto !== null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [scrubMcpSecrets(key, secrets), scrubMcpSecrets(item, secrets)])
+  );
+}
+
+/** `secrets` are values known only to the live connection (its OAuth tokens). */
+export function scrubMcpConnectionMessage(value, cfg = {}, secrets = []) {
+  let text = scrubMcpSecrets(String(value || ''), secrets);
   const rawUrl = expandEnvVars(String(cfg?.url || ''));
   if (rawUrl) {
     text = text.split(rawUrl).join(mcpUrlForLog(rawUrl));
     try {
       const parsed = new URL(rawUrl);
-      text = replaceSecret(text, parsed.username);
-      text = replaceSecret(text, parsed.password);
+      text = replaceConfiguredSecret(text, parsed.username);
+      text = replaceConfiguredSecret(text, parsed.password);
       for (const paramValue of parsed.searchParams.values()) {
-        text = replaceSecret(text, paramValue);
+        text = replaceConfiguredSecret(text, paramValue);
       }
     } catch {
       /* invalid URL is reported without echoing it */
@@ -99,7 +122,7 @@ export function scrubMcpConnectionMessage(value, cfg = {}) {
   const headers = resolveMcpHttpHeaders(cfg);
   for (const [name, headerValue] of Object.entries(headers)) {
     if (/authorization|cookie|token|secret|api[-_]?key|signature/i.test(name)) {
-      text = replaceSecret(text, headerValue);
+      text = replaceConfiguredSecret(text, headerValue);
     }
   }
   return text
@@ -108,30 +131,106 @@ export function scrubMcpConnectionMessage(value, cfg = {}) {
 }
 
 /**
- * Expand `${VAR}` and `${env:VAR}` references in string values using the
- * provided env map (defaults to process.env). Recurses into arrays/objects.
- * Unknown vars expand to an empty string. No shell execution.
+ * Expand `${VAR}`, `${env:VAR}` and `${VAR:-default}` references in string
+ * values using the provided env map (defaults to process.env). Recurses into
+ * arrays/objects. The default (possibly empty) applies only when the variable
+ * is unset, and runs to the first `}`. An unset variable without a default
+ * expands to an empty string and, when `missing` (a Set) is given, its name is
+ * recorded there. No shell execution.
  */
-export function expandEnvVars(value, env = process.env) {
+export function expandEnvVars(value, env = process.env, missing) {
   if (typeof value === 'string') {
-    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
+    return value.replace(/\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, fallback) => {
       const v = env?.[name];
-      return v == null ? '' : String(v);
+      if (v != null) return String(v);
+      if (fallback !== undefined) return fallback;
+      missing?.add(name);
+      return '';
     });
   }
   if (Array.isArray(value)) {
-    return value.map((v) => expandEnvVars(v, env));
+    return value.map((v) => expandEnvVars(v, env, missing));
   }
   if (value && typeof value === 'object') {
     const out = {};
     for (const [k, v] of Object.entries(value)) {
-      out[k] = expandEnvVars(v, env);
+      out[k] = expandEnvVars(v, env, missing);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Names (deduplicated, first-seen order) of variables a server config needs
+ * that are unset: `${VAR}` references without a default in command, args,
+ * env, url, headers and cwd, plus the variables named directly by
+ * `bearer_token_env_var`, `env_http_headers` values and `env_vars`. Names
+ * only — never values.
+ */
+export function findMissingMcpEnvVars(cfg = {}, env = process.env) {
+  const missing = new Set();
+  expandEnvVars([cfg.command, cfg.args, cfg.env, cfg.url, cfg.headers, cfg.cwd], env, missing);
+  const named = [
+    cfg.bearer_token_env_var,
+    ...(cfg.env_http_headers && typeof cfg.env_http_headers === 'object' && !Array.isArray(cfg.env_http_headers)
+      ? Object.values(cfg.env_http_headers)
+      : []),
+    ...(Array.isArray(cfg.env_vars) ? cfg.env_vars : []),
+  ];
+  for (const value of named) {
+    const name = typeof value === 'string' ? value.trim() : '';
+    if (name && envValue(env, name) == null) missing.add(name);
+  }
+  return [...missing];
+}
+
+// Windows variable names are case-insensitive.
+function envValue(env, name) {
+  if (process.platform !== 'win32') return env?.[name];
+  const actual = Object.keys(env || {}).find((key) => key.toLowerCase() === name.toLowerCase());
+  return actual ? env[actual] : undefined;
+}
+
+// Provider tool names: at most 64 characters of [A-Za-z0-9_-] (the strictest
+// limit among the providers Mixdog talks to).
+const PROVIDER_TOOL_NAME_MAX = 64;
+const PROVIDER_TOOL_NAME_RE = /^[A-Za-z0-9_-]+$/;
+const KEPT_SERVER_PART_MAX = 40;
+
+/**
+ * `mcp__<server>__<tool>` when that already fits provider limits (unchanged
+ * for every name that fits today). Otherwise a deterministic short form:
+ * the server part kept when it is safe (sanitized and cut short when not),
+ * the tool part sanitized and cut, and a hash of the full name appended so
+ * distinct tools never meet. Callers keep the original tool name alongside
+ * to dispatch the call.
+ */
+export function providerSafeMcpToolName(serverName, toolName) {
+  const server = String(serverName || '');
+  const tool = String(toolName || '');
+  const full = `mcp__${server}__${tool}`;
+  if (full.length <= PROVIDER_TOOL_NAME_MAX && PROVIDER_TOOL_NAME_RE.test(full)) return full;
+  const hash = createHash('sha1').update(full).digest('hex').slice(0, 8);
+  const serverPart =
+    /^[A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*$/.test(server) && server.length <= KEPT_SERVER_PART_MAX
+      ? server
+      : server
+          .replace(/[^A-Za-z0-9-]+/g, '-')
+          .replace(/^-+|-+$/g, '')
+          .slice(0, 24)
+          .replace(/-+$/, '') || 'server';
+  const room = PROVIDER_TOOL_NAME_MAX - `mcp__${serverPart}__`.length - hash.length - 1;
+  const toolPart = tool
+    .replace(/[^A-Za-z0-9_-]+/g, '_')
+    .slice(0, Math.max(0, room))
+    .replace(/_+$/, '');
+  const safe = `mcp__${serverPart}__${toolPart ? `${toolPart}_` : ''}${hash}`;
+  // Name-only consumers in this process (display, guards) resolve it back.
+  rememberMcpToolIdentity(safe, server, tool);
+  return safe;
+}
+
 const DEFAULT_STDIO_ENV_KEYS =
   process.platform === 'win32'
     ? [
@@ -208,6 +307,14 @@ export function resolveMcpTransportKind(cfg) {
   throw new Error(`Invalid config: need autoDetect, type (stdio/http/sse/ws), url (http), or command (stdio)`);
 }
 
+/** The exact URL OAuth credentials of an HTTP/SSE server config are stored
+ *  under; null for other transports. */
+export function resolveMcpOAuthUrl(cfg) {
+  const kind = resolveMcpTransportKind(cfg);
+  if (kind !== 'http' && kind !== 'sse') return null;
+  return normalizeMcpTransportUrl(expandEnvVars(String(cfg.url ?? '')), kind);
+}
+
 // MCP per-tool-call timeout. Default 2min: a hung/unresponsive MCP server
 // (e.g. a busy editor) must not stall a tool call indefinitely. Genuinely
 // long-running tools can raise/disable it via MIXDOG_MCP_CALL_TIMEOUT_MS or a

package/src/runtime/agent/orchestrator/mcp/client-handshake.mjs

@@ -6,6 +6,7 @@
 import { markServiceUnreachable, isConnRefuseError } from '../../../shared/service-discovery.mjs';
 import { MCP_MAX_TIMER_MS, resolveMcpStartupTimeoutMs } from './client-config.mjs';
 import { appendMcpStderrTail } from './client-transport.mjs';
+import { MCP_OAUTH_TIMEOUT_MS } from './oauth.mjs';
 
 // tools/list pagination bounds: a server that never stops handing out cursors
 // (or repeats one) cannot loop the client forever.
@@ -15,12 +16,15 @@ const MAX_MCP_TOOL_PAGES = 100;
  * Every tool of a server: follows `nextCursor` until it is exhausted, repeats,
  * or MAX_MCP_TOOL_PAGES is reached. A page with an invalid shape is returned
  * as-is so the caller's shape validation reports it.
+ * The SDK rebuilds its output validators from each page alone, so after a
+ * paginated listing they are rebuilt once from every page's tools.
  */
 export async function listAllMcpTools(client, requestOptions = undefined) {
   const tools = [];
   const seen = new Set();
   let cursor = null;
-  for (let page = 0; page < MAX_MCP_TOOL_PAGES; page += 1) {
+  let pages = 0;
+  for (; pages < MAX_MCP_TOOL_PAGES; pages += 1) {
     const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
     if (!result || !Array.isArray(result.tools)) return result;
     tools.push(...result.tools);
@@ -29,6 +33,7 @@ export async function listAllMcpTools(client, requestOptions = undefined) {
     seen.add(next);
     cursor = next;
   }
+  if (pages > 0) client.cacheToolMetadata?.(tools);
   return { tools };
 }
 
@@ -49,6 +54,15 @@ function startupTimeoutError(name, startupTimeoutMs) {
   return err;
 }
 
+const oauthLoginError = () => new Error('MCP OAuth login failed, cancelled, or timed out');
+
+/** Code of a connect cancelled (login cancel, disconnect, shutdown) before any
+ *  interactive login started. */
+export const MCP_CONNECT_CANCELLED = 'EMCPCONNECTCANCELLED';
+function connectCancelledError(name) {
+  return Object.assign(new Error(`MCP server "${name}" connect cancelled`), { code: MCP_CONNECT_CANCELLED });
+}
+
 /**
  * Bound the connect + listTools handshake so a slow/hung server can't stall
  * boot or the first turn. On expiry the pending transport/child is torn down
@@ -69,17 +83,43 @@ export async function runBoundedHandshake({
 }) {
   const startupTimeoutMs = resolveMcpStartupTimeoutMs(cfg);
   const guard = { timer: null, timedOut: false };
+  let rejectDeadline;
+  // True once an interactive login actually started (the server challenged
+  // and a browser sign-in was allowed).
+  let loginStarted = false;
+  const armDeadline = (ms, error = () => startupTimeoutError(name, ms)) => {
+    if (guard.timer) clearTimeout(guard.timer);
+    guard.timer = setTimeout(() => {
+      guard.timedOut = true;
+      rejectDeadline(error());
+    }, ms);
+  };
+  const deadline = new Promise((_, reject) => {
+    rejectDeadline = reject;
+  });
+  // A closed OAuth connection (login cancel, disconnect, shutdown) settles a
+  // handshake that would otherwise wait forever (an SSE stream closed while
+  // starting never settles). The SDK also closes the transport — and with it
+  // the OAuth connection — right before rethrowing a connect failure of its
+  // own (e.g. connection refused): deferring past the pending microtasks lets
+  // that real failure settle the race first.
+  const cancelOAuth = () =>
+    setImmediate(() => rejectDeadline(loginStarted ? oauthLoginError() : connectCancelledError(name)));
+  transport.oauth?.signal.addEventListener('abort', cancelOAuth, { once: true });
+  if (transport.oauth?.signal.aborted) cancelOAuth();
+  if (startupTimeoutMs > 0) armDeadline(startupTimeoutMs);
+  // Human authorization gets a separate, finite budget. The ordinary startup
+  // budget still applies until the server actually challenges authentication.
+  if (transport.oauth) {
+    transport.oauth.onStart = () => {
+      loginStarted = true;
+      armDeadline(MCP_OAUTH_TIMEOUT_MS, oauthLoginError);
+    };
+  }
   const handshake = performHandshake(client, transport, {
-    timeout: startupTimeoutMs > 0 ? startupTimeoutMs : MCP_MAX_TIMER_MS,
+    timeout: !transport.oauth && startupTimeoutMs > 0 ? startupTimeoutMs : MCP_MAX_TIMER_MS,
   });
   try {
-    if (startupTimeoutMs <= 0) return await handshake;
-    const deadline = new Promise((_, rej) => {
-      guard.timer = setTimeout(() => {
-        guard.timedOut = true;
-        rej(startupTimeoutError(name, startupTimeoutMs));
-      }, startupTimeoutMs);
-    });
     return await Promise.race([handshake, deadline]);
   } catch (err) {
     // A discovery-advert port that fails to connect is a corpse (recycled
@@ -88,7 +128,7 @@ export async function runBoundedHandshake({
     // ONLY — a startup/handshake timeout is a slow-but-alive server.
     if (autoDetectAdvert && isConnRefuseError(err))
       markServiceUnreachable(autoDetectAdvert.service, autoDetectAdvert.port);
-    if (guard.timedOut) {
+    if (guard.timedOut || transport.oauth?.signal.aborted) {
       // Tear down the pending transport/child so a hung handshake never
       // leaks a stdio process or socket — fire-and-forget (like the
       // tool-call timeout path) so a slow tree-kill never delays this
@@ -96,7 +136,7 @@ export async function runBoundedHandshake({
       try {
         closeServer({ client, transport }).catch(() => {});
       } catch {
-        /* ignore */
+        // Teardown is best effort: the handshake failure below is what gets reported.
       }
       // Never let the late handshake settle into an unhandled rejection.
       handshake.catch(() => {});
@@ -108,6 +148,9 @@ export async function runBoundedHandshake({
     }
     throw tail ? new Error(appendMcpStderrTail(String(err), tail)) : err;
   } finally {
+    transport.oauth?.finishConnect();
     if (guard.timer) clearTimeout(guard.timer);
+    transport.oauth?.signal.removeEventListener('abort', cancelOAuth);
+    if (transport.oauth) transport.oauth.onStart = () => {};
   }
 }