@ouro.bot/cli 0.1.0-alpha.810 → 0.1.0-alpha.811

package/dist/repertoire/mcp-manager.js

@@ -1,257 +1,350 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpManager = void 0;
 exports.getSharedMcpManager = getSharedMcpManager;
 exports.releaseRuntimeMcpServers = releaseRuntimeMcpServers;
 exports.shutdownSharedMcpManager = shutdownSharedMcpManager;
 exports.resetSharedMcpManager = resetSharedMcpManager;
+const path = __importStar(require("node:path"));
 const mcp_client_1 = require("./mcp-client");
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
 const credential_access_1 = require("./credential-access");
 const plugin_mcp_1 = require("./plugin-mcp");
+const tool_arguments_1 = require("./tool-arguments");
+const mcp_tools_1 = require("./mcp-tools");
 const MAX_RESTART_RETRIES = 5;
 const RESTART_DELAY_MS = 1000;
-/**
- * Merge builtin (agent.json mcpServers) + plugin-declared (.mcp.json) servers.
- *
- * Builtin wins on name collision. Returns the merged config map plus a
- * `pluginOrigins` map (server-name → plugin-id) for tools-surfacing namespace.
- *
- * Shared by `getSharedMcpManager()` (initial start) and `McpManager.reconcile()`
- * (re-read on each turn). Both code paths MUST use the same merge logic — if
- * reconcile reads only builtin, plugin servers get classified as "removed"
- * on the second turn and torn down. See alpha.635 fix.
- *
- * `runtimeServers` are per-turn, per-agent overrides (e.g. Workbench's
- * `ouro_workbench`) supplied as PARAMETER data for the current turn — never read
- * from module state. They merge with the HIGHEST precedence (after builtin), so
- * a stale `agent.json` entry loses to the live runtime path. Because they are a
- * parameter, a turn that omits them produces a merged set WITHOUT them, and
- * `reconcile()` then tears the runtime server down — this is the no-leak
- * invariant that keeps the runtime MCP from bleeding into a different agent's
- * concurrent turn on the shared daemon.
- */
-function buildMergedServerConfig(runtimeServers) {
-    const config = (0, identity_1.loadAgentConfig)();
-    const builtinServers = config.mcpServers ?? {};
-    const pluginServers = (0, plugin_mcp_1.listPluginMcpServers)();
-    const mergedServers = {};
-    const pluginOrigins = {};
-    for (const p of pluginServers) {
-        if (builtinServers[p.serverName] !== undefined)
-            continue;
-        mergedServers[p.serverName] = (0, plugin_mcp_1.pluginMcpServerToConfig)(p);
-        pluginOrigins[p.serverName] = p.pluginId;
+function isOwner(value) {
+    return typeof value === "object" && value !== null
+        && "agentName" in value && typeof value.agentName === "string" && value.agentName.length > 0
+        && "agentRoot" in value && typeof value.agentRoot === "string" && path.isAbsolute(value.agentRoot);
+}
+function captureOwner(owner) {
+    if (!isOwner(owner)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.owner_invalid", component: "repertoire",
+            message: "MCP requires an explicit owner", meta: { reason: "agent name and absolute root are required" },
+        });
+        throw new mcp_tools_1.McpCallRejectedError("MCP requires an explicit owner");
+    }
+    return Object.freeze({ agentName: owner.agentName, agentRoot: owner.agentRoot });
+}
+function sameOwner(left, right) {
+    return left.agentName === right.agentName && left.agentRoot === right.agentRoot;
+}
+function serverKey(owner, name) {
+    return JSON.stringify([owner.agentName, owner.agentRoot, name]);
+}
+function buildMergedServerConfig(owner, runtimeServers) {
+    const config = (0, identity_1.loadAgentConfig)(owner);
+    const desired = new Map();
+    for (const plugin of (0, plugin_mcp_1.listPluginMcpServers)(undefined, owner)) {
+        if (desired.has(plugin.serverName))
+            throw new mcp_tools_1.McpCallRejectedError(`MCP server name collision: ${plugin.serverName}`);
+        desired.set(plugin.serverName, {
+            config: (0, plugin_mcp_1.pluginMcpServerToConfig)(plugin), source: "plugin", pluginId: plugin.pluginId,
+        });
     }
-    for (const [name, cfg] of Object.entries(builtinServers)) {
-        mergedServers[name] = cfg;
+    for (const [name, server] of Object.entries(config.mcpServers ?? {})) {
+        desired.set(name, { config: server, source: "builtin" });
     }
-    // Runtime overrides win over both plugin and builtin (highest precedence).
-    // They are NOT recorded in pluginOrigins, so they surface as builtin-style
-    // (un-namespaced) tools — matching how an agent.json mcpServers entry would.
-    if (runtimeServers) {
-        for (const [name, cfg] of Object.entries(runtimeServers)) {
-            mergedServers[name] = cfg;
-            delete pluginOrigins[name];
-        }
+    for (const [name, server] of Object.entries(runtimeServers ?? {})) {
+        desired.set(name, { config: server, source: "runtime" });
     }
-    return { mergedServers, pluginOrigins };
+    return desired;
 }
-function sameMcpServerConfig(left, right) {
-    const leftEnv = Object.entries(left.env ?? {}).sort();
-    const rightEnv = Object.entries(right.env ?? {}).sort();
-    return left.command === right.command
-        && JSON.stringify(left.args ?? []) === JSON.stringify(right.args ?? [])
-        && JSON.stringify(leftEnv) === JSON.stringify(rightEnv)
-        && (left.cwd ?? "") === (right.cwd ?? "");
+function configurationDigest(owner, desired) {
+    return (0, tool_arguments_1.digestJson)({
+        agentName: owner.agentName, agentRoot: owner.agentRoot,
+        source: desired.source, pluginId: desired.pluginId ?? null,
+        command: desired.config.command, args: desired.config.args ?? [],
+        env: desired.config.env ?? {}, cwd: desired.config.cwd ?? "",
+    });
 }
 class McpManager {
     servers = new Map();
     desiredGenerations = new Map();
     nextGeneration = 0;
-    shuttingDown = false;
-    async start(servers, pluginOrigins = {}, ownerAgent) {
+    lifecycle = Promise.resolve();
+    shutdownPromise;
+    constructor() {
         (0, runtime_1.emitNervesEvent)({
-            event: "mcp.manager_start",
-            component: "repertoire",
-            message: "starting MCP manager",
-            meta: {
-                serverCount: Object.keys(servers).length,
-                pluginServerCount: Object.keys(pluginOrigins).length,
-            },
+            event: "mcp.manager_start", component: "repertoire",
+            message: "starting MCP manager", meta: { serverCount: 0 },
         });
-        const entries = Object.entries(servers);
-        for (const [name, config] of entries) {
-            await this.connectServer(name, config, pluginOrigins[name], ownerAgent);
-        }
     }
-    listAllTools() {
-        const result = [];
-        for (const [name, entry] of this.servers) {
-            result.push({ server: name, tools: entry.cachedTools, pluginId: entry.pluginId });
-        }
+    // One lifecycle tail; external tool and canary results do not hold it.
+    enqueue(operation) {
+        const result = this.lifecycle.then(operation);
+        this.lifecycle = result.then(() => undefined, () => undefined);
         return result;
     }
-    async callTool(server, tool, args) {
-        let entry = this.servers.get(server);
-        if (!entry) {
-            throw new Error(`Unknown server: ${server}`);
-        }
-        if (!entry.client.isConnected()) {
-            await this.recoverStaleTransport(server, "pre-call disconnected");
-            entry = this.servers.get(server);
-            if (!entry?.client.isConnected()) {
-                throw new Error(`Server "${server}" is disconnected`);
+    enqueueBackground(operation) {
+        void this.enqueue(operation).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error", event: "mcp.lifecycle_error", component: "repertoire",
+                message: "MCP background lifecycle operation failed",
+                meta: { reason: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    async start(ownerInput, servers, pluginOrigins = {}) {
+        const owner = captureOwner(ownerInput);
+        const desired = new Map(Object.entries(structuredClone(servers)).map(([name, config]) => [
+            name, { config, source: pluginOrigins[name] ? "plugin" : "builtin", pluginId: pluginOrigins[name] },
+        ]));
+        return this.enqueue(async () => {
+            if (this.shutdownPromise)
+                return null;
+            await this.applyDesired(owner, desired);
+            return this.shutdownPromise ? null : this.freezeView(owner);
+        });
+    }
+    async reconcile(ownerInput, runtimeServers) {
+        const owner = captureOwner(ownerInput);
+        const runtime = runtimeServers ? structuredClone(runtimeServers) : undefined;
+        return this.enqueue(async () => {
+            if (this.shutdownPromise)
+                return null;
+            try {
+                const desired = buildMergedServerConfig(owner, runtime);
+                await this.applyDesired(owner, desired);
+                return this.shutdownPromise || desired.size === 0 ? null : this.freezeView(owner);
             }
-        }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn", event: "mcp.reconcile_error", component: "repertoire",
+                    message: "failed to reconcile MCP servers",
+                    meta: { reason: error instanceof Error ? error.message : String(error) },
+                });
+                for (const entry of this.ownedEntries(owner))
+                    this.removeEntry(entry);
+                return null;
+            }
+        });
+    }
+    listAllTools(owner) {
+        captureOwner(owner);
+        return this.ownedEntries(owner).filter((entry) => this.isCurrentEntry(entry)).map((entry) => ({
+            server: entry.name, tools: structuredClone(entry.cachedTools), pluginId: entry.pluginId,
+        }));
+    }
+    async callTool(binding, args, ownerInput) {
+        const owner = captureOwner(ownerInput);
+        const call = await this.enqueue(async () => {
+            let entry = this.currentBinding(binding, owner);
+            if (!entry.client.isConnected()) {
+                await this.recoverStaleTransport(entry, "pre-call disconnected");
+                entry = this.currentBinding(binding, owner);
+                if (!entry.client.isConnected())
+                    throw new mcp_tools_1.McpCallRejectedError(`Server "${entry.name}" is disconnected`);
+            }
+            return { entry, result: entry.client.callTool(binding.rawName, args) };
+        });
         try {
-            return await entry.client.callTool(tool, args);
+            return await call.result;
         }
         catch (error) {
-            if (!(0, mcp_client_1.isMcpTransportError)(error)) {
+            if (!(0, mcp_client_1.isMcpTransportError)(error))
                 throw error;
-            }
             const reason = error instanceof Error ? error.message : String(error);
-            await this.recoverStaleTransport(server, reason);
-            const recovered = this.servers.get(server);
-            if (!recovered?.client.isConnected()) {
-                throw new Error(`Server "${server}" is disconnected after recovery: ${reason}`);
-            }
-            return recovered.client.callTool(tool, args);
+            // Recovery prepares later calls; the server may already have performed this one.
+            this.enqueueBackground(async () => {
+                if (this.isCurrentEntry(call.entry))
+                    await this.recoverStaleTransport(call.entry, reason);
+            });
+            throw error;
         }
     }
-    async runCanaries() {
+    async validateToolBinding(binding, ownerInput) {
+        const owner = captureOwner(ownerInput);
+        await this.enqueue(() => { this.currentBinding(binding, owner); });
+    }
+    async runCanaries(ownerInput) {
+        const owner = captureOwner(ownerInput);
+        const entries = await this.enqueue(() => this.ownedEntries(owner));
         const results = [];
-        for (const [server, entry] of [...this.servers]) {
+        for (const entry of entries) {
+            let current = entry;
             try {
-                if (!entry.client.isConnected()) {
-                    await this.recoverStaleTransport(server, "canary disconnected");
-                }
-                const current = this.servers.get(server);
-                if (!current?.client.isConnected()) {
-                    results.push({ server, ok: false, detail: "disconnected after recovery attempt" });
+                const refresh = await this.enqueue(async () => {
+                    if (!this.isCurrentEntry(entry))
+                        return null;
+                    if (!entry.client.isConnected())
+                        await this.recoverStaleTransport(entry, "canary disconnected");
+                    const recovered = this.servers.get(serverKey(owner, entry.name));
+                    if (!recovered || !this.isCurrentEntry(recovered) || !recovered.client.isConnected())
+                        return null;
+                    current = recovered;
+                    return { result: recovered.client.refreshTools() };
+                });
+                if (!refresh) {
+                    results.push({ server: entry.name, ok: false, detail: "disconnected after recovery attempt" });
                     continue;
                 }
-                const tools = await current.client.refreshTools();
-                current.cachedTools = tools;
-                current.consecutiveFailures = 0;
-                results.push({ server, ok: true, detail: `${tools.length} tools listed` });
+                const tools = await refresh.result;
+                const updated = await this.enqueue(() => {
+                    if (!this.isCurrentEntry(current))
+                        return false;
+                    current.cachedTools = structuredClone(tools);
+                    current.consecutiveFailures = 0;
+                    return true;
+                });
+                results.push({
+                    server: entry.name, ok: updated,
+                    detail: updated ? `${tools.length} tools listed` : "server changed during canary",
+                });
             }
             catch (error) {
                 const reason = error instanceof Error ? error.message : String(error);
                 if ((0, mcp_client_1.isMcpTransportError)(error)) {
-                    await this.recoverStaleTransport(server, reason);
+                    await this.enqueue(async () => {
+                        if (this.isCurrentEntry(current))
+                            await this.recoverStaleTransport(current, reason);
+                    });
                 }
-                results.push({ server, ok: false, detail: reason });
+                results.push({ server: entry.name, ok: false, detail: reason });
             }
         }
         return results;
     }
-    /** Re-read agent config AND enabled-plugin .mcp.json files, then connect new
-     *  servers / disconnect removed ones. Must include plugin-declared servers
-     *  in the desired set — otherwise plugin servers (e.g. mcp__desk__*) are
-     *  treated as "removed" on every call and get torn down between turns.
-     *
-     *  `runtimeServers` are the current turn's per-agent overrides. They MUST be
-     *  passed on every reconcile for the agent that owns them, otherwise the
-     *  runtime server (e.g. ouro_workbench) is classified as "removed" and torn
-     *  down — which is exactly the desired no-leak behavior for a turn that omits
-     *  them. */
-    async reconcile(runtimeServers) {
-        try {
-            const { mergedServers, pluginOrigins } = buildMergedServerConfig(runtimeServers);
-            const ownerAgent = (0, identity_1.getAgentName)();
-            const currentNames = new Set(this.servers.keys());
-            const desiredNames = new Set(Object.keys(mergedServers));
-            // Connect new servers
-            for (const [name, cfg] of Object.entries(mergedServers)) {
-                const current = this.servers.get(name);
-                const pluginId = pluginOrigins[name];
-                if (!current) {
-                    (0, runtime_1.emitNervesEvent)({
-                        event: "mcp.server_added",
-                        component: "repertoire",
-                        message: `connecting new MCP server: ${name}`,
-                        meta: { server: name, command: cfg.command },
-                    });
-                    await this.connectServer(name, cfg, pluginId, ownerAgent);
-                }
-                else if (!sameMcpServerConfig(current.config, cfg)
-                    || current.pluginId !== pluginId
-                    || current.ownerAgent !== ownerAgent) {
-                    (0, runtime_1.emitNervesEvent)({
-                        event: "mcp.server_changed",
-                        component: "repertoire",
-                        message: `reconnecting changed MCP server: ${name}`,
-                        meta: { server: name, command: cfg.command },
-                    });
-                    current.client.shutdown();
-                    this.servers.delete(name);
-                    await this.connectServer(name, cfg, pluginId, ownerAgent);
-                }
-            }
-            // Disconnect removed servers
-            for (const name of currentNames) {
-                if (!desiredNames.has(name)) {
-                    (0, runtime_1.emitNervesEvent)({
-                        event: "mcp.server_removed",
-                        component: "repertoire",
-                        message: `disconnecting removed MCP server: ${name}`,
-                        meta: { server: name },
-                    });
-                    const entry = this.servers.get(name);
-                    /* v8 ignore next -- defensive: name comes from this.servers.keys() this same tick, so entry is always present; the guard only protects against an awaited connectServer crash-handler racing a delete @preserve */
-                    if (entry)
-                        entry.client.shutdown();
-                    this.servers.delete(name);
-                    this.desiredGenerations.delete(name);
-                }
-            }
-            return true;
-        }
-        catch (error) {
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        // Publish closing before queued cleanup so pending network work cannot revive clients.
+        this.shutdownPromise = this.enqueue(() => {
             (0, runtime_1.emitNervesEvent)({
-                level: "warn",
-                event: "mcp.reconcile_error",
-                component: "repertoire",
-                message: "failed to reconcile MCP servers",
-                meta: { reason: error instanceof Error ? error.message : String(error) },
+                event: "mcp.manager_end", component: "repertoire",
+                message: "shutting down MCP manager", meta: { serverCount: this.servers.size },
             });
-            this.shutdown();
+            for (const entry of [...this.servers.values()])
+                this.removeEntry(entry);
+            this.desiredGenerations.clear();
+        });
+        return this.shutdownPromise;
+    }
+    ownedEntries(owner) {
+        return [...this.servers.values()].filter((entry) => sameOwner(entry.owner, owner));
+    }
+    isCurrentEntry(entry) {
+        const key = serverKey(entry.owner, entry.name);
+        return !this.shutdownPromise && this.servers.get(key) === entry
+            && this.desiredGenerations.get(key) === entry.generation;
+    }
+    freezeView(owner) {
+        const entries = this.ownedEntries(owner).filter((entry) => this.isCurrentEntry(entry)).map((entry) => Object.freeze({
+            server: entry.name, source: entry.source, pluginId: entry.pluginId,
+            configDigest: entry.configDigest, generation: entry.generation,
+            tools: (0, tool_arguments_1.freezeToolValue)(structuredClone(entry.cachedTools)),
+        }));
+        return Object.freeze({ manager: this, owner, entries: Object.freeze(entries) });
+    }
+    matchesBinding(entry, binding, owner) {
+        if (binding.manager !== this || !sameOwner(binding, owner) || !sameOwner(entry.owner, owner)
+            || !this.isCurrentEntry(entry) || entry.name !== binding.server
+            || entry.source !== binding.source || entry.pluginId !== binding.pluginId
+            || entry.configDigest !== binding.configDigest || entry.generation !== binding.generation)
+            return false;
+        const tools = entry.cachedTools.filter((tool) => tool.name === binding.rawName);
+        if (tools.length !== 1)
             return false;
+        const schema = (0, mcp_tools_1.mcpToolSchema)({ server: entry.name, pluginId: entry.pluginId }, tools[0]);
+        return schema.function.name === binding.surfacedName && (0, tool_arguments_1.digestJson)(schema) === binding.schemaDigest;
+    }
+    currentBinding(binding, owner) {
+        const entry = this.servers.get(serverKey(owner, binding.server));
+        if (!entry || !this.matchesBinding(entry, binding, owner)) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn", event: "mcp.tool_rejected", component: "repertoire",
+                message: "MCP tool binding is no longer current", meta: { reason: "stale or unavailable owned tool" },
+            });
+            throw new mcp_tools_1.McpCallRejectedError("MCP tool binding is stale or unavailable");
         }
+        return entry;
     }
-    shutdown() {
-        this.shuttingDown = true;
-        // `_end` (not `_stop`) to pair with `mcp.manager_start` under the
-        // nerves audit start/end pairing rule.
-        (0, runtime_1.emitNervesEvent)({
-            event: "mcp.manager_end",
-            component: "repertoire",
-            message: "shutting down MCP manager",
-            meta: { serverCount: this.servers.size },
-        });
-        for (const [, entry] of this.servers) {
-            entry.client.shutdown();
+    removeEntry(entry) {
+        const key = serverKey(entry.owner, entry.name);
+        this.desiredGenerations.delete(key);
+        if (entry.restartTimer)
+            clearTimeout(entry.restartTimer);
+        entry.client.shutdown();
+        this.servers.delete(key);
+    }
+    async applyDesired(owner, desired) {
+        for (const [name, requested] of desired) {
+            if (this.shutdownPromise)
+                return;
+            const descriptor = { ...requested, config: structuredClone(requested.config) };
+            const configDigest = configurationDigest(owner, descriptor);
+            const current = this.servers.get(serverKey(owner, name));
+            if (current && this.isCurrentEntry(current) && current.configDigest === configDigest)
+                continue;
+            if (current) {
+                (0, runtime_1.emitNervesEvent)({
+                    event: "mcp.server_changed", component: "repertoire",
+                    message: `reconnecting changed MCP server: ${name}`, meta: { server: name },
+                });
+                this.removeEntry(current);
+            }
+            else {
+                (0, runtime_1.emitNervesEvent)({
+                    event: "mcp.server_added", component: "repertoire",
+                    message: `connecting new MCP server: ${name}`, meta: { server: name },
+                });
+            }
+            await this.connectServer({
+                ...descriptor, owner, name, configDigest, generation: ++this.nextGeneration, consecutiveFailures: 0,
+            });
+        }
+        for (const entry of this.ownedEntries(owner)) {
+            if (desired.has(entry.name))
+                continue;
+            (0, runtime_1.emitNervesEvent)({
+                event: "mcp.server_removed", component: "repertoire",
+                message: `disconnecting removed MCP server: ${entry.name}`, meta: { server: entry.name },
+            });
+            this.removeEntry(entry);
         }
-        this.servers.clear();
-        this.desiredGenerations.clear();
     }
-    /**
-     * Resolve `vault:DOMAIN/FIELD` references in server env config.
-     * Returns resolved env or throws with a descriptive error.
-     */
-    async resolveVaultEnv(_serverName, env, ownerAgent) {
+    async resolveVaultEnv(env, owner) {
         const resolved = { ...env };
-        // Short-circuit: only spin up a credential store if at least one env value
-        // actually requests vault resolution. Plugin MCP servers commonly ship with
-        // `env: {}` or pure-string envs, and we shouldn't pay the credential-store
-        // boot cost (or fail in test envs that have no vault) for those cases.
-        const hasVaultRef = Object.values(resolved).some((v) => /^vault:/.test(v));
-        if (!hasVaultRef)
+        if (!Object.values(resolved).some((value) => /^vault:/.test(value)))
             return resolved;
-        const store = (0, credential_access_1.getCredentialStore)(ownerAgent);
+        const store = (0, credential_access_1.getCredentialStore)(owner.agentName);
         for (const [key, value] of Object.entries(resolved)) {
             const match = value.match(/^vault:([^/]+)\/(.+)$/);
             if (!match)
@@ -260,240 +353,131 @@ class McpManager {
             try {
                 resolved[key] = await store.getRawSecret(domain, field);
             }
-            catch (err) {
-                /* v8 ignore next -- reason @preserve */
-                const reason = err instanceof Error ? err.message : String(err);
-                // Classify the error for actionable messaging
-                let classification = "vault unreachable";
-                if (reason.includes("no credential found")) {
-                    classification = "item not found";
-                }
-                else if (reason.includes("field") && reason.includes("not found")) {
-                    classification = "field empty";
-                }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                const classification = reason.includes("no credential found") ? "item not found"
+                    : reason.includes("field") && reason.includes("not found") ? "field empty" : "vault unreachable";
                 throw new Error(`vault:${domain}/${field} could not be resolved: ${classification}`);
             }
         }
         return resolved;
     }
-    async connectServer(name, config, pluginId, ownerAgent) {
-        const generation = ++this.nextGeneration;
-        this.desiredGenerations.set(name, generation);
-        // Resolve vault: references in env before spawning
-        let resolvedConfig = config;
+    async connectServer(desired) {
+        const key = serverKey(desired.owner, desired.name);
+        this.desiredGenerations.set(key, desired.generation);
+        let config = desired.config;
         if (config.env) {
             try {
-                const resolvedEnv = await this.resolveVaultEnv(name, config.env, ownerAgent);
-                resolvedConfig = { ...config, env: resolvedEnv };
+                config = { ...config, env: await this.resolveVaultEnv(config.env, desired.owner) };
             }
-            catch (err) {
-                /* v8 ignore next -- reason @preserve */
-                const reason = err instanceof Error ? err.message : String(err);
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
                 (0, runtime_1.emitNervesEvent)({
-                    level: "error",
-                    event: "mcp.vault_resolve_error",
-                    component: "repertoire",
-                    message: `skipping MCP server "${name}": ${reason}`,
-                    meta: { server: name, reason },
+                    level: "error", event: "mcp.vault_resolve_error", component: "repertoire",
+                    message: `skipping MCP server "${desired.name}": ${reason}`, meta: { server: desired.name, reason },
                 });
-                if (this.desiredGenerations.get(name) === generation) {
-                    this.desiredGenerations.delete(name);
-                }
-                return; // Skip this server, continue to next
+                this.desiredGenerations.delete(key);
+                return;
             }
         }
-        if (this.shuttingDown || this.desiredGenerations.get(name) !== generation)
+        if (this.shutdownPromise || this.desiredGenerations.get(key) !== desired.generation)
             return;
-        const client = new mcp_client_1.McpClient(resolvedConfig);
-        const entry = {
-            name,
-            config,
-            client,
-            cachedTools: [],
-            consecutiveFailures: 0,
-            pluginId,
-            ownerAgent,
-            generation,
-        };
-        this.servers.set(name, entry);
-        client.onClose(() => {
-            if (this.shuttingDown)
-                return;
-            if (this.servers.get(name)?.client !== client)
-                return;
-            this.handleServerCrash(name, client);
-        });
+        const client = new mcp_client_1.McpClient(config);
+        const entry = { ...desired, client, cachedTools: [] };
+        this.servers.set(key, entry);
+        client.onClose(() => { this.enqueueBackground(() => this.handleServerCrash(entry)); });
         try {
             await client.connect();
+            if (!this.isCurrentEntry(entry)) {
+                client.shutdown();
+                return;
+            }
             const tools = await client.listTools();
-            if (this.shuttingDown
-                || this.desiredGenerations.get(name) !== generation
-                || this.servers.get(name)?.client !== client) {
+            if (!this.isCurrentEntry(entry)) {
                 client.shutdown();
                 return;
             }
-            entry.cachedTools = tools;
-            entry.consecutiveFailures = 0;
+            entry.cachedTools = structuredClone(tools);
         }
         catch (error) {
             const reason = error instanceof Error ? error.message : String(error);
             (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "mcp.connect_error",
-                component: "repertoire",
-                message: `failed to connect MCP server "${name}" (command: ${config.command}). Check that the command exists and is properly configured. Reason: ${reason}`,
-                meta: {
-                    server: name,
-                    command: config.command,
-                    args: config.args,
-                    reason,
-                },
+                level: "error", event: "mcp.connect_error", component: "repertoire",
+                message: `failed to connect MCP server "${desired.name}"`,
+                meta: { server: desired.name, reason },
             });
         }
     }
-    handleServerCrash(name, crashedClient) {
-        const entry = this.servers.get(name);
-        /* v8 ignore next -- defensive: entry removed or replaced between close event and handler @preserve */
-        if (!entry || entry.client !== crashedClient)
+    handleServerCrash(entry) {
+        if (!this.isCurrentEntry(entry) || entry.restartTimer)
             return;
         entry.consecutiveFailures++;
         if (entry.consecutiveFailures > MAX_RESTART_RETRIES) {
             (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "mcp.connect_error",
-                component: "repertoire",
-                message: `MCP server "${name}" exceeded max restart retries (${MAX_RESTART_RETRIES}). Giving up — check that "${entry.config.command}" exists and is properly configured in agent.json mcpServers.`,
-                meta: { server: name, command: entry.config.command, failures: entry.consecutiveFailures },
+                level: "error", event: "mcp.connect_error", component: "repertoire",
+                message: `MCP server "${entry.name}" exceeded max restart retries`,
+                meta: { server: entry.name, failures: entry.consecutiveFailures },
             });
             return;
         }
         (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "mcp.server_restart",
-            component: "repertoire",
-            message: `restarting crashed MCP server: ${name}`,
-            meta: { server: name, attempt: entry.consecutiveFailures },
+            level: "warn", event: "mcp.server_restart", component: "repertoire",
+            message: `restarting crashed MCP server: ${entry.name}`,
+            meta: { server: entry.name, attempt: entry.consecutiveFailures },
         });
-        /* v8 ignore start -- timer callback: covered by mcp-manager.test.ts via fake timers but v8 can't trace @preserve */
-        setTimeout(() => {
-            if (this.shuttingDown)
-                return;
-            if (this.servers.get(name)?.client !== crashedClient)
-                return;
-            this.restartServer(name, crashedClient).catch(() => {
-                // Error handling is inside restartServer
+        entry.restartTimer = setTimeout(() => {
+            this.enqueueBackground(async () => {
+                if (!this.isCurrentEntry(entry))
+                    return;
+                delete entry.restartTimer;
+                await this.restartServer(entry);
             });
         }, RESTART_DELAY_MS);
-        /* v8 ignore stop */
     }
-    /* v8 ignore start -- called from timer callback: covered by mcp-manager.test.ts via fake timers but v8 can't trace @preserve */
-    async restartServer(name, expectedClient) {
-        const entry = this.servers.get(name);
-        if (!entry)
-            return;
-        if (expectedClient && entry.client !== expectedClient)
-            return;
-        // Remove old entry and reconnect
-        this.servers.delete(name);
-        this.desiredGenerations.delete(name);
-        entry.client.shutdown();
-        await this.connectServer(name, entry.config, entry.pluginId, entry.ownerAgent);
-        // Preserve failure count
-        const newEntry = this.servers.get(name);
-        if (newEntry) {
-            newEntry.consecutiveFailures = entry.consecutiveFailures;
-        }
+    async restartServer(entry) {
+        this.removeEntry(entry);
+        await this.connectServer({
+            owner: entry.owner, name: entry.name, config: entry.config,
+            source: entry.source, pluginId: entry.pluginId,
+            configDigest: entry.configDigest, generation: entry.generation,
+            consecutiveFailures: entry.consecutiveFailures,
+        });
     }
-    /* v8 ignore stop */
-    async recoverStaleTransport(name, reason) {
+    async recoverStaleTransport(entry, reason) {
         (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "mcp.transport_recovery",
-            component: "repertoire",
-            message: `recovering stale MCP transport: ${name}`,
-            meta: { server: name, reason },
+            level: "warn", event: "mcp.transport_recovery", component: "repertoire",
+            message: `recovering stale MCP transport: ${entry.name}`, meta: { server: entry.name, reason },
         });
-        await this.restartServer(name);
+        await this.restartServer(entry);
     }
 }
 exports.McpManager = McpManager;
 let _sharedManager = null;
-let _sharedManagerPromise = null;
-/**
- * Get or create a shared McpManager instance from the agent's config.
- * Returns null if no mcpServers are configured.
- * Safe to call from multiple senses — will only create one instance.
- *
- * `options.runtimeServers` are the current turn's per-agent MCP overrides (e.g.
- * Workbench's `ouro_workbench`). They are PARAMETER data for this call only —
- * passed into the merge for both the initial `start()` and every subsequent
- * `reconcile()`, and never persisted as module state. A call that omits them
- * reconciles to a set WITHOUT them, tearing any prior runtime server down — the
- * no-leak invariant for the shared multi-agent daemon.
- */
+/** Every caller applies its own desired state and freezes its own view in the shared manager's lifecycle tail. */
 async function getSharedMcpManager(options) {
-    const runtimeServers = options?.runtimeServers;
-    // If manager exists, reconcile to pick up config changes (new/removed servers)
-    // AND this turn's runtime overrides. Passing runtimeServers per-call is what
-    // scopes the runtime MCP to the active agent's turn.
-    if (_sharedManager) {
-        const reconciled = await _sharedManager.reconcile(runtimeServers);
-        if (!reconciled) {
-            _sharedManager = null;
-            return null;
-        }
-        return _sharedManager;
+    if (!isOwner(options)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn", event: "mcp.owner_invalid", component: "repertoire",
+            message: "MCP requires an explicit owner", meta: { reason: "agent name and absolute root are required" },
+        });
+        return null;
     }
-    /* v8 ignore next -- race guard: deduplicates concurrent initialization calls @preserve */
-    if (_sharedManagerPromise)
-        return _sharedManagerPromise;
-    // Always re-check config — agent may have added servers since last call
-    _sharedManagerPromise = (async () => {
-        try {
-            const { mergedServers, pluginOrigins } = buildMergedServerConfig(runtimeServers);
-            if (Object.keys(mergedServers).length === 0)
-                return null;
-            const manager = new McpManager();
-            await manager.start(mergedServers, pluginOrigins, (0, identity_1.getAgentName)());
-            _sharedManager = manager;
-            return manager;
-        }
-        catch (error) {
-            (0, runtime_1.emitNervesEvent)({
-                level: "error",
-                event: "mcp.manager_start",
-                component: "repertoire",
-                message: "failed to initialize shared MCP manager",
-                /* v8 ignore next -- both branches tested: Error in wiring test, non-Error is defensive @preserve */
-                meta: { reason: error instanceof Error ? error.message : String(error) },
-            });
-            return null;
-        }
-        finally {
-            _sharedManagerPromise = null;
-        }
-    })();
-    return _sharedManagerPromise;
+    const manager = _sharedManager ??= new McpManager();
+    return manager.reconcile(options, options.runtimeServers);
 }
-async function releaseRuntimeMcpServers() {
-    if (!_sharedManager)
-        return;
-    if (!await _sharedManager.reconcile()) {
-        _sharedManager = null;
-    }
+async function releaseRuntimeMcpServers(owner) {
+    if (_sharedManager)
+        await _sharedManager.reconcile(owner);
 }
-/**
- * Shut down the shared MCP manager and clear the singleton.
- * Called during daemon/agent shutdown.
- */
-function shutdownSharedMcpManager() {
-    if (_sharedManager) {
-        _sharedManager.shutdown();
+async function shutdownSharedMcpManager() {
+    const manager = _sharedManager;
+    if (!manager)
+        return;
+    await manager.shutdown();
+    if (_sharedManager === manager)
         _sharedManager = null;
-    }
 }
-/** Reset for testing only */
-function resetSharedMcpManager() {
-    _sharedManager = null;
-    _sharedManagerPromise = null;
+/** Reset for testing only. */
+async function resetSharedMcpManager() {
+    await shutdownSharedMcpManager();
 }