bosun 0.34.6 → 0.34.8

package/agent-hook-bridge.mjs

@@ -2,6 +2,7 @@
 
 import { readFileSync } from "node:fs";
 import { executeBlockingHooks, executeHooks, loadHooks, registerBuiltinHooks } from "./agent-hooks.mjs";
+import { shouldRunAgentHookBridge } from "./task-context.mjs";
 
 const TAG = "[agent-hook-bridge]";
 
@@ -161,12 +162,11 @@ function mapEvents(sourceEvent, payload) {
 }
 
 async function run() {
-  // ── VE_MANAGED guard ──────────────────────────────────────────────────────
-  // Only execute hooks for sessions managed by bosun.
-  // bosun sets VE_MANAGED=1 in all spawned agent environments.
-  // If this env var is missing, we're running inside a standalone agent session
-  // that just happens to have the hook files in its config — exit silently.
-  if (!process.env.VE_MANAGED && !process.env.BOSUN_HOOKS_FORCE) {
+  // ── task-context guard ────────────────────────────────────────────────────
+  // Execute hooks only for active Bosun task sessions.
+  // This prevents globally scaffolded hook configs from affecting standalone
+  // sessions in user repos. BOSUN_HOOKS_FORCE remains an explicit override.
+  if (!shouldRunAgentHookBridge(process.env)) {
     process.exit(0);
   }
 

package/agent-pool.mjs

@@ -45,6 +45,16 @@ import { loadConfig } from "./config.mjs";
 import { resolveRepoRoot, resolveAgentRepoRoot } from "./repo-root.mjs";
 import { resolveCodexProfileRuntime } from "./codex-model-profiles.mjs";
 
+// Lazy-load MCP registry to avoid circular dependencies.
+// Cached at module scope per AGENTS.md hard rules.
+let _mcpRegistry = null;
+async function getMcpRegistry() {
+  if (!_mcpRegistry) {
+    _mcpRegistry = await import("./mcp-registry.mjs");
+  }
+  return _mcpRegistry;
+}
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -897,7 +907,7 @@ async function launchCodexThread(prompt, cwd, timeoutMs, extra = {}) {
  * Build CLI arguments for ephemeral Copilot agent-pool sessions.
  * Mirrors copilot-shell.mjs buildCliArgs() for feature parity.
  */
-function buildPoolCopilotCliArgs() {
+function buildPoolCopilotCliArgs(mcpConfigPath) {
   const args = [];
   if (!envFlagEnabled(process.env.COPILOT_NO_EXPERIMENTAL)) {
     args.push("--experimental");
@@ -915,9 +925,10 @@ function buildPoolCopilotCliArgs() {
   if (envFlagEnabled(process.env.COPILOT_DISABLE_BUILTIN_MCPS)) {
     args.push("--disable-builtin-mcps");
   }
-  const mcpConfigPath = process.env.COPILOT_ADDITIONAL_MCP_CONFIG;
-  if (mcpConfigPath) {
-    args.push("--additional-mcp-config", mcpConfigPath);
+  // MCP config: prefer per-launch resolved config, fall back to env var
+  const effectiveMcpConfig = mcpConfigPath || process.env.COPILOT_ADDITIONAL_MCP_CONFIG;
+  if (effectiveMcpConfig) {
+    args.push("--additional-mcp-config", effectiveMcpConfig);
   }
   return args;
 }
@@ -1024,7 +1035,17 @@ async function launchCopilotThread(prompt, cwd, timeoutMs, extra = {}) {
         clientOpts = { cliUrl, env: clientEnv };
       } else {
         // Local mode (default): stdio for full capability
-        const cliArgs = buildPoolCopilotCliArgs();
+        // Write temp MCP config if resolved MCP servers are available
+        let mcpConfigPath = null;
+        if (extra._resolvedMcpServers?.length) {
+          try {
+            const registry = await getMcpRegistry();
+            mcpConfigPath = registry.writeTempCopilotMcpConfig(cwd, extra._resolvedMcpServers);
+          } catch (mcpErr) {
+            console.warn(`${TAG} copilot MCP config write failed (non-fatal): ${mcpErr.message}`);
+          }
+        }
+        const cliArgs = buildPoolCopilotCliArgs(mcpConfigPath);
         clientOpts = {
           cwd,
           env: clientEnv,
@@ -1465,6 +1486,27 @@ async function launchClaudeThread(prompt, cwd, timeoutMs, extra = {}) {
   }
 
   // ── 4. Execute query ─────────────────────────────────────────────────────
+  // Inject MCP server config for Claude via environment variable
+  let _claudeMcpEnvCleanup = null;
+  if (extra._resolvedMcpServers?.length) {
+    try {
+      const registry = await getMcpRegistry();
+      const { envVar } = registry.buildClaudeMcpEnv(extra._resolvedMcpServers);
+      if (envVar) {
+        const prev = process.env.CLAUDE_MCP_SERVERS;
+        process.env.CLAUDE_MCP_SERVERS = envVar;
+        _claudeMcpEnvCleanup = () => {
+          if (prev === undefined) {
+            delete process.env.CLAUDE_MCP_SERVERS;
+          } else {
+            process.env.CLAUDE_MCP_SERVERS = prev;
+          }
+        };
+      }
+    } catch (mcpErr) {
+      console.warn(`${TAG} claude MCP env setup failed (non-fatal): ${mcpErr.message}`);
+    }
+  }
   try {
     const msgQueue = createMessageQueue();
 
@@ -1596,6 +1638,7 @@ async function launchClaudeThread(prompt, cwd, timeoutMs, extra = {}) {
 
     const output =
       finalResponse.trim() || "(Agent completed with no text output)";
+    if (typeof _claudeMcpEnvCleanup === "function") _claudeMcpEnvCleanup();
     return {
       success: true,
       output,
@@ -1605,6 +1648,7 @@ async function launchClaudeThread(prompt, cwd, timeoutMs, extra = {}) {
       threadId: activeClaudeSessionId,
     };
   } catch (err) {
+    if (typeof _claudeMcpEnvCleanup === "function") _claudeMcpEnvCleanup();
     clearAbortScope();
     if (hardTimer) clearTimeout(hardTimer);
     if (steerKey) unregisterActiveSession(steerKey);
@@ -1714,6 +1758,32 @@ export async function launchEphemeralThread(
   timeoutMs = DEFAULT_TIMEOUT_MS,
   extra = {},
 ) {
+  // ── Resolve MCP servers for this launch ──────────────────────────────────
+  try {
+    if (!extra._mcpResolved) {
+      const cfg = loadConfig();
+      const mcpCfg = cfg.mcpServers || {};
+      if (mcpCfg.enabled !== false) {
+        const requestedIds = extra.mcpServers || [];
+        const defaultIds = mcpCfg.defaultServers || [];
+        if (requestedIds.length || defaultIds.length) {
+          const registry = await getMcpRegistry();
+          const resolved = await registry.resolveMcpServersForAgent(
+            cwd,
+            requestedIds,
+            { defaultServers: defaultIds, catalogOverrides: mcpCfg.catalogOverrides || {} },
+          );
+          if (resolved.length) {
+            extra._resolvedMcpServers = resolved;
+          }
+        }
+      }
+      extra._mcpResolved = true;
+    }
+  } catch (mcpErr) {
+    console.warn(`${TAG} MCP server resolution failed (non-fatal): ${mcpErr.message}`);
+  }
+
   // Determine the primary SDK to try
   const requestedSdk = extra.sdk
     ? String(extra.sdk).trim().toLowerCase()

package/agent-work-analyzer.mjs

@@ -63,6 +63,88 @@ const activeSessions = new Map();
 // Alert cooldowns: "alert_type:attempt_id" -> timestamp
 const alertCooldowns = new Map();
 const ALERT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes between same alert
+const FAILED_SESSION_ALERT_MIN_COOLDOWN_MS = 60 * 60 * 1000; // Keep noisy failed-session summaries coarse-grained
+const ALERT_COOLDOWN_RETENTION_MS = Math.max(
+  FAILED_SESSION_ALERT_MIN_COOLDOWN_MS * 3,
+  3 * 60 * 60 * 1000,
+); // keep cooldown history bounded
+const ALERT_COOLDOWN_REPLAY_MAX_BYTES = Math.max(
+  256 * 1024,
+  Number(process.env.AGENT_ALERT_COOLDOWN_REPLAY_MAX_BYTES || 2 * 1024 * 1024) || 2 * 1024 * 1024,
+);
+
+function getAlertCooldownMs(alert) {
+  const type = String(alert?.type || "").trim().toLowerCase();
+  if (type === "failed_session_high_errors") {
+    return Math.max(ALERT_COOLDOWN_MS, FAILED_SESSION_ALERT_MIN_COOLDOWN_MS);
+  }
+  return Math.max(0, ALERT_COOLDOWN_MS);
+}
+
+function extractTaskToken(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) return "";
+  const prefixMatch = normalized.match(
+    /^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(?:-|$)/i,
+  );
+  return prefixMatch?.[1] || normalized;
+}
+
+function deriveAlertScopeId(alert) {
+  const taskId = extractTaskToken(alert?.task_id);
+  if (taskId) return taskId;
+  return extractTaskToken(alert?.attempt_id);
+}
+
+function buildAlertCooldownKey(alert) {
+  const type = String(alert?.type || "unknown").trim().toLowerCase() || "unknown";
+  const scopeId = deriveAlertScopeId(alert);
+  if (scopeId && (type === "failed_session_high_errors" || type === "stuck_agent")) {
+    return `${type}:task:${scopeId}`;
+  }
+  return `${type}:${String(alert?.attempt_id || "unknown")}`;
+}
+
+function pruneStaleAlertCooldowns(nowMs = Date.now()) {
+  const now = Number(nowMs) || Date.now();
+  const cutoff = now - ALERT_COOLDOWN_RETENTION_MS;
+  for (const [key, ts] of alertCooldowns.entries()) {
+    const lastTs = Number(ts);
+    if (!Number.isFinite(lastTs) || lastTs < cutoff) {
+      alertCooldowns.delete(key);
+    }
+  }
+}
+
+async function hydrateAlertCooldownsFromLog() {
+  if (!existsSync(ALERTS_LOG)) return;
+  try {
+    const fileStat = await stat(ALERTS_LOG);
+    if (!fileStat.size) return;
+    const start = Math.max(0, fileStat.size - ALERT_COOLDOWN_REPLAY_MAX_BYTES);
+    const stream = createReadStream(ALERTS_LOG, { start, encoding: "utf8" });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    const maxCooldownMs = Math.max(ALERT_COOLDOWN_MS, FAILED_SESSION_ALERT_MIN_COOLDOWN_MS);
+    const cutoff = Date.now() - maxCooldownMs;
+    for await (const line of rl) {
+      const trimmed = String(line || "").trim();
+      if (!trimmed) continue;
+      try {
+        const entry = JSON.parse(trimmed);
+        const ts = Date.parse(String(entry?.timestamp || ""));
+        if (!Number.isFinite(ts) || ts < cutoff) continue;
+        const cooldownMs = getAlertCooldownMs(entry);
+        if (ts < Date.now() - cooldownMs) continue;
+        const key = String(entry?._cooldown_key || "").trim() || buildAlertCooldownKey(entry);
+        alertCooldowns.set(key, ts);
+      } catch {
+        // ignore malformed jsonl
+      }
+    }
+  } catch {
+    // best-effort hydration only
+  }
+}
 
 // ── Log Tailing ─────────────────────────────────────────────────────────────
 
@@ -70,6 +152,14 @@ let filePosition = 0;
 let isRunning = false;
 let stuckSweepTimer = null;
 
+function parseEnvBoolean(value, fallback = false) {
+  if (value == null || value === "") return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
 /**
  * Start the analyzer loop
  */
@@ -88,14 +178,29 @@ export async function startAnalyzer() {
     if (!existsSync(ALERTS_LOG)) {
       await writeFile(ALERTS_LOG, "");
     }
+    await hydrateAlertCooldownsFromLog();
   } catch (err) {
     console.warn(`[agent-work-analyzer] Failed to init alerts log: ${err.message}`);
   }
 
-  // Initial read of existing log
+  // Initial positioning for existing log.
+  // Default behavior is true tailing (start at EOF) to avoid replaying stale
+  // historical sessions on monitor restart, which can re-emit old alerts and
+  // trigger noisy false-positive loops. Operators can opt in to replay for
+  // forensics via AGENT_ANALYZER_REPLAY_STARTUP=1.
   if (existsSync(AGENT_WORK_STREAM)) {
-    filePosition = await processLogFile(filePosition);
-    pruneStaleSessionsAfterReplay();
+    const replayStartup = parseEnvBoolean(
+      process.env.AGENT_ANALYZER_REPLAY_STARTUP,
+      false,
+    );
+    if (replayStartup) {
+      filePosition = await processLogFile(filePosition);
+      pruneStaleSessionsAfterReplay();
+    } else {
+      const streamStats = await stat(AGENT_WORK_STREAM);
+      filePosition = Math.max(0, Number(streamStats?.size || 0));
+      activeSessions.clear();
+    }
   } else {
     // Ensure the stream file exists so the watcher doesn't throw
     try {
@@ -154,7 +259,12 @@ export function stopAnalyzer() {
 async function processLogFile(startPosition) {
   try {
     const stats = await stat(AGENT_WORK_STREAM);
-    if (stats.size <= startPosition) {
+    if (stats.size < startPosition) {
+      // Log file was truncated/rotated. Reset offset so new entries are not
+      // skipped forever after rotation.
+      return 0;
+    }
+    if (stats.size === startPosition) {
       return startPosition; // No new data
     }
 
@@ -163,12 +273,29 @@ async function processLogFile(startPosition) {
       encoding: "utf8",
     });
 
-    const rl = createInterface({ input: stream });
-    let bytesRead = startPosition;
+    let chunkText = "";
+    for await (const chunk of stream) {
+      chunkText += String(chunk || "");
+    }
+    if (!chunkText) {
+      return startPosition;
+    }
 
-    for await (const line of rl) {
-      bytesRead += Buffer.byteLength(line, "utf8") + 1; // +1 for newline
+    const lastNewlineIdx = chunkText.lastIndexOf("\n");
+    let processText = "";
+    let trailing = "";
+    if (lastNewlineIdx >= 0) {
+      processText = chunkText.slice(0, lastNewlineIdx + 1);
+      trailing = chunkText.slice(lastNewlineIdx + 1);
+    } else {
+      trailing = chunkText;
+    }
 
+    const lines = processText
+      .split(/\r?\n/)
+      .map((line) => String(line || "").trim())
+      .filter(Boolean);
+    for (const line of lines) {
       try {
         const event = JSON.parse(line);
         await analyzeEvent(event);
@@ -179,7 +306,21 @@ async function processLogFile(startPosition) {
       }
     }
 
-    return bytesRead;
+    // If trailing text is present without newline, treat it as a potentially
+    // partial line and only consume it when it is valid JSON. This avoids data
+    // loss when writers flush an incomplete line temporarily.
+    const trailingTrimmed = String(trailing || "").trim();
+    if (trailingTrimmed) {
+      try {
+        const trailingEvent = JSON.parse(trailingTrimmed);
+        await analyzeEvent(trailingEvent);
+        return startPosition + Buffer.byteLength(chunkText, "utf8");
+      } catch {
+        return startPosition + Buffer.byteLength(processText, "utf8");
+      }
+    }
+
+    return startPosition + Buffer.byteLength(processText, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(`[agent-work-analyzer] Error reading log: ${err.message}`);
@@ -450,11 +591,12 @@ function startStuckSweep() {
  * @param {Object} alert - Alert data
  */
 async function emitAlert(alert) {
-  const alertKey = `${alert.type}:${alert.attempt_id}`;
+  const alertKey = buildAlertCooldownKey(alert);
+  const cooldownMs = getAlertCooldownMs(alert);
 
   // Check cooldown
   const lastAlert = alertCooldowns.get(alertKey);
-  if (lastAlert && Date.now() - lastAlert < ALERT_COOLDOWN_MS) {
+  if (lastAlert && Date.now() - lastAlert < cooldownMs) {
     return; // Skip duplicate alerts
   }
 
@@ -462,6 +604,7 @@ async function emitAlert(alert) {
 
   const alertEntry = {
     timestamp: new Date().toISOString(),
+    _cooldown_key: alertKey,
     ...alert,
   };
 
@@ -477,7 +620,7 @@ async function emitAlert(alert) {
 
 // ── Cleanup Old Sessions ────────────────────────────────────────────────────
 
-setInterval(() => {
+const cleanupTimer = setInterval(() => {
   const cutoff = Date.now() - 60 * 60 * 1000; // 1 hour
 
   for (const [attemptId, session] of activeSessions.entries()) {
@@ -486,7 +629,8 @@ setInterval(() => {
       activeSessions.delete(attemptId);
     }
   }
+  pruneStaleAlertCooldowns();
 }, 10 * 60 * 1000); // Cleanup every 10 minutes
+cleanupTimer.unref?.();
 
 // ── Exports ─────────────────────────────────────────────────────────────────
-

package/bosun.schema.json

@@ -606,6 +606,37 @@
       "type": "object",
       "description": "Hook definitions loaded by agent-hooks.mjs (event -> hook list).",
       "additionalProperties": true
+    },
+    "mcpServers": {
+      "type": "object",
+      "description": "MCP (Model Context Protocol) server management. Controls which MCP servers are available to agents.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable MCP server integration for agent launches"
+        },
+        "defaultServers": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "MCP server IDs attached to every agent launch by default (e.g. [\"context7\", \"microsoft-docs\"])"
+        },
+        "catalogOverrides": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "description": "Per-server environment variable overrides",
+            "additionalProperties": { "type": "string" }
+          },
+          "description": "Environment variable overrides keyed by MCP server ID"
+        },
+        "autoInstallDefaults": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically install defaultServers from catalog if not already installed"
+        }
+      }
     }
   }
 }

package/cli.mjs

@@ -1484,14 +1484,21 @@ function detectExistingMonitorLockOwner(excludePid = null) {
   return null;
 }
 
-function runMonitor() {
+function runMonitor({ restartReason = "" } = {}) {
   return new Promise((resolve, reject) => {
     const monitorPath = fileURLToPath(
       new URL("./monitor.mjs", import.meta.url),
     );
+    const childEnv = { ...process.env };
+    if (restartReason) {
+      childEnv.BOSUN_MONITOR_RESTART_REASON = restartReason;
+    } else {
+      delete childEnv.BOSUN_MONITOR_RESTART_REASON;
+    }
     monitorChild = fork(monitorPath, process.argv.slice(2), {
       stdio: "inherit",
       execArgv: ["--max-old-space-size=4096"],
+      env: childEnv,
       windowsHide: IS_DAEMON_CHILD && process.platform === "win32",
     });
     daemonCrashTracker.markStart();
@@ -1504,7 +1511,7 @@ function runMonitor() {
           "\n  \u21BB Monitor restarting with fresh modules...\n",
         );
         // Small delay to let file writes / port releases settle
-        setTimeout(() => resolve(runMonitor()), 2000);
+        setTimeout(() => resolve(runMonitor({ restartReason: "self-restart" })), 2000);
       } else {
         const exitCode = code ?? (signal ? 1 : 0);
         const existingOwner =
@@ -1572,7 +1579,15 @@ function runMonitor() {
             restartAttempt: daemonRestartCount,
             maxRestarts: IS_DAEMON_CHILD ? DAEMON_MAX_RESTARTS : 0,
           }).catch(() => {});
-          setTimeout(() => resolve(runMonitor()), delayMs);
+          setTimeout(
+            () =>
+              resolve(
+                runMonitor({
+                  restartReason: isOSKill ? "os-kill" : "crash",
+                }),
+              ),
+            delayMs,
+          );
           return;
         }
 

package/codex-config.mjs

@@ -2,12 +2,15 @@
  * codex-config.mjs — Manages the Codex CLI config (~/.codex/config.toml)
  *
  * Ensures the user's Codex CLI configuration has:
- *   1. A vibe_kanban MCP server section with the correct env vars
- *   2. Sufficient stream_idle_timeout_ms on all model providers
- *   3. Recommended defaults for long-running agentic workloads
- *   4. Feature flags for sub-agents, memory, undo, collaboration
- *   5. Sandbox permissions and shell environment policy
- *   6. Common MCP servers (context7, microsoft-docs)
+ *   1. Sufficient stream_idle_timeout_ms on all model providers
+ *   2. Recommended defaults for long-running agentic workloads
+ *   3. Feature flags for sub-agents, memory, undo, collaboration
+ *   4. Sandbox permissions and shell environment policy
+ *   5. Common MCP servers (context7, microsoft-docs)
+ *
+ * NOTE: Vibe-Kanban MCP is workspace-scoped and managed by repo-config.mjs
+ * inside each repo's `.codex/config.toml`. Global config no longer auto-adds
+ * `[mcp_servers.vibe_kanban]`.
  *
  * SCOPE: This manages the GLOBAL ~/.codex/config.toml which contains:
  *   - Model provider configs (API keys, base URLs) — MUST be global
@@ -1305,13 +1308,15 @@ export function ensureRetrySettings(toml, providerName) {
  * @param {object} opts
  * @param {string}  [opts.vkBaseUrl]
  * @param {boolean} [opts.skipVk]
+ * @param {boolean} [opts.manageVkMcp]  Explicit opt-in to manage VK MCP in global config
  * @param {boolean} [opts.dryRun]  If true, returns result without writing
  * @param {object}  [opts.env]     Environment overrides (defaults to process.env)
  * @param {string}  [opts.primarySdk]  Primary agent SDK: "codex", "copilot", or "claude"
  */
 export function ensureCodexConfig({
   vkBaseUrl = "http://127.0.0.1:54089",
-  skipVk = false,
+  skipVk = true,
+  manageVkMcp = false,
   dryRun = false,
   env = process.env,
   primarySdk,
@@ -1424,7 +1429,8 @@ export function ensureCodexConfig({
   result.featuresAdded = featureResult.added;
   toml = featureResult.toml;
 
-  if (skipVk) {
+  const shouldManageGlobalVkMcp = Boolean(manageVkMcp) && !skipVk;
+  if (!shouldManageGlobalVkMcp) {
     if (hasVibeKanbanMcp(toml)) {
       toml = removeVibeKanbanMcp(toml);
       result.vkRemoved = true;
@@ -1564,7 +1570,7 @@ export function printConfigSummary(result, log = console.log) {
   }
 
   if (result.vkRemoved) {
-    log("  🗑️  Removed Vibe-Kanban MCP server (VK backend not active)");
+    log("  🗑️  Removed Vibe-Kanban MCP server from global config (workspace-scoped only)");
   }
 
   if (result.vkEnvUpdated) {

package/copilot-shell.mjs

@@ -17,6 +17,15 @@ import { getGitHubToken } from "./github-auth-manager.mjs";
 
 const __dirname = resolve(fileURLToPath(new URL(".", import.meta.url)));
 
+// Lazy-import MCP registry — cached at module scope per AGENTS.md rules.
+let _mcpRegistry = null;
+async function getMcpRegistry() {
+  if (!_mcpRegistry) {
+    _mcpRegistry = await import("./mcp-registry.mjs");
+  }
+  return _mcpRegistry;
+}
+
 // ── Configuration ────────────────────────────────────────────────────────────
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000; // 60 min for agentic tasks
@@ -174,7 +183,7 @@ function logSessionEvent(logPath, event) {
  * Enables experimental features (fleet, autopilot), auto-permissions,
  * sub-agents, and autonomy.
  */
-function buildCliArgs() {
+async function buildCliArgs() {
   const args = [];
 
   // Always enable experimental features (fleet, autopilot, persisted permissions, etc.)
@@ -218,6 +227,26 @@ function buildCliArgs() {
     args.push("--additional-mcp-config", mcpConfigPath);
   }
 
+  // Also write a temp MCP config from the library if installed servers exist
+  // (non-fatal: library MCP is a convenience, not a hard requirement)
+  if (!mcpConfigPath) {
+    try {
+      const registry = await getMcpRegistry();
+      const installed = await registry.listInstalledMcpServers(REPO_ROOT);
+      if (installed && installed.length) {
+        const ids = installed.map((e) => e.id);
+        const resolved = await registry.resolveMcpServersForAgent(REPO_ROOT, ids);
+        if (resolved && resolved.length) {
+          const tmpPath = registry.writeTempCopilotMcpConfig(REPO_ROOT, resolved);
+          args.push("--additional-mcp-config", tmpPath);
+          console.log(`[copilot-shell] injected ${resolved.length} library MCP server(s) via CLI args`);
+        }
+      }
+    } catch (err) {
+      console.warn(`[copilot-shell] failed to inject library MCP servers into CLI args: ${err.message}`);
+    }
+  }
+
   if (args.length > 0) {
     console.log(`[copilot-shell] cliArgs: ${args.join(" ")}`);
   }
@@ -399,7 +428,7 @@ async function ensureClientStarted() {
   const sessionMode = (process.env.COPILOT_SESSION_MODE || "local").trim().toLowerCase();
 
   // Build cliArgs for experimental features, permissions, and autonomy
-  const cliArgs = buildCliArgs();
+  const cliArgs = await buildCliArgs();
 
   let clientOptions;
   if (transport === "url") {
@@ -553,7 +582,46 @@ function loadMcpServers(profile = null) {
   return loadMcpServersFromFile(configPath);
 }
 
-function buildSessionConfig() {
+/**
+ * Merge installed MCP library servers into an existing mcpServers map.
+ * Called during session build to inject library-managed MCP servers into
+ * the Copilot SDK session alongside any profile/env servers.
+ *
+ * Non-fatal: if the registry is unavailable or encounters errors, the
+ * original servers map is returned unchanged.
+ *
+ * @param {Object|null} existingServers — mcpServers from profile/env/config
+ * @returns {Promise<Object|null>} — merged servers map
+ */
+async function mergeLibraryMcpServers(existingServers) {
+  try {
+    const registry = await getMcpRegistry();
+    const installed = await registry.listInstalledMcpServers(REPO_ROOT);
+    if (!installed || !installed.length) return existingServers;
+
+    // Resolve all installed servers into full configs
+    const installedIds = installed.map((e) => e.id);
+    const resolved = await registry.resolveMcpServersForAgent(REPO_ROOT, installedIds);
+    if (!resolved || !resolved.length) return existingServers;
+
+    // Convert to Copilot mcpServers format: { [id]: { command, args, env? } | { url } }
+    const copilotJson = registry.buildCopilotMcpJson(resolved);
+    const libraryServers = copilotJson?.mcpServers || {};
+    if (!Object.keys(libraryServers).length) return existingServers;
+
+    // Merge: existing servers take precedence over library ones (user overrides win)
+    const merged = { ...libraryServers, ...(existingServers || {}) };
+    console.log(
+      `[copilot-shell] Merged ${Object.keys(libraryServers).length} library MCP server(s) into session`,
+    );
+    return merged;
+  } catch (err) {
+    console.warn(`[copilot-shell] Failed to merge library MCP servers: ${err.message}`);
+    return existingServers;
+  }
+}
+
+async function buildSessionConfig() {
   const profile = resolveCopilotProfile();
   const config = {
     streaming: true,
@@ -588,7 +656,9 @@ function buildSessionConfig() {
     config.reasoningEffort = effort.toLowerCase();
   }
 
-  const mcpServers = loadMcpServers(profile);
+  // Load MCP servers from profile/env/config, then merge library-managed servers
+  const baseServers = loadMcpServers(profile);
+  const mcpServers = await mergeLibraryMcpServers(baseServers);
   if (mcpServers) config.mcpServers = mcpServers;
   return config;
 }
@@ -600,7 +670,7 @@ async function getSession() {
   const started = await ensureClientStarted();
   if (!started) throw new Error("Copilot SDK not available");
 
-  const config = buildSessionConfig();
+  const config = await buildSessionConfig();
 
   if (activeSessionId && typeof copilotClient?.resumeSession === "function") {
     try {