weir-harness 2.1.1 → 2.1.2

package/src/capabilities/mcp-mount.js

@@ -3,8 +3,16 @@
 import { randomUUID } from 'node:crypto'
 import { isSegment } from './store/paths.js'
 import { McpLifecycleError, mcpDiagnostic } from './mcp-diagnostics.js'
+import {
+  MCP_GROUP_PREFIX,
+  createMcpMountOwnership,
+  isMcpResidueId,
+  isSuffixedMcpGroupId,
+  resolveMcpGroupIdentity,
+} from './mcp-mount-ownership.js'
+
+export { MCP_GROUP_PREFIX, isMcpResidueId } from './mcp-mount-ownership.js'
 
-export const MCP_GROUP_PREFIX = 'weir-mcp-'
 const DEFAULT_STARTUP_TIMEOUT = 15_000
 const DEFAULT_CLEANUP_TIMEOUT = 15_000
 const message = error => (error instanceof Error ? error.message : String(error))
@@ -29,9 +37,10 @@ export function detectMcpNameAmbiguity(entries) {
   return conflicts.length === 0 ? { kind: 'ok' } : { kind: 'conflict', conflicts }
 }
 
-export function mcpGroupOptions({ identity, generation, client }) {
+export function mcpGroupOptions({ identity, generation, client, groupId = null }) {
   if (!isSegment(identity)) throw new TypeError(`invalid MCP server identity: ${JSON.stringify(identity)}`)
-  const group = `${MCP_GROUP_PREFIX}${identity}`
+  const group = groupId ?? `${MCP_GROUP_PREFIX}${identity}`
+  if (!isMcpResidueId(group)) throw new TypeError(`invalid actual MCP groupId: ${JSON.stringify(group)}`)
   return {
     id: group,
     name: 'cordis:group',
@@ -44,31 +53,44 @@ export function mcpGroupOptions({ identity, generation, client }) {
   }
 }
 
-export const isMcpResidueId = id => typeof id === 'string' && id.startsWith(MCP_GROUP_PREFIX) && !id.endsWith('-facade') && !id.endsWith('-client')
-
-/**
- * The stock EntryTree methods write through their tree. Its root EntryGroup
- * methods only mutate the runtime store, which is the non-profile-writing seam
- * used for materialized secrets. Any other shape is unsupported, never a
- * fallback to the write-through tree.
- */
-export function resolveEphemeralMcpTree(loader) {
-  const root = loader?.root
-  const tree = root?.tree
-  if (tree?.root !== root || typeof root?.create !== 'function' || typeof root?.remove !== 'function'
-    || typeof tree?.await !== 'function' || typeof tree?.resolve !== 'function') {
+function nonWritingTree(tree, { scoped = false } = {}) {
+  const root = tree?.root
+  if (tree?.root?.tree !== tree || typeof root?.create !== 'function' || typeof root?.remove !== 'function'
+    || typeof tree?.await !== 'function' || typeof tree?.resolve !== 'function'
+    || typeof tree?.entries !== 'function' || !tree?.store || typeof tree.store !== 'object') {
     return { kind: 'unsupported', reason: 'ephemeral-loader-unavailable' }
   }
   return {
     kind: 'ok',
     tree: {
       ephemeral: true,
+      scoped,
+      source: tree,
+      store: tree.store,
       create: options => root.create(options),
       remove: id => root.remove(id),
+      entries: () => [...tree.entries()],
+      resolve: id => tree.resolve(id),
+      await: () => tree.await(),
     },
   }
 }
 
+/** The exact retained-revision seam proven by the real scoped-tree canary. */
+export function resolveScopedMcpTree(tree) {
+  return nonWritingTree(tree, { scoped: true })
+}
+
+/**
+ * The stock EntryTree methods write through their tree. Its root EntryGroup
+ * methods only mutate the runtime store, which is the non-profile-writing seam
+ * used for materialized secrets. Any other shape is unsupported, never a
+ * fallback to the write-through tree.
+ */
+export function resolveEphemeralMcpTree(loader) {
+  return nonWritingTree(loader?.root?.tree)
+}
+
 export function strictMcpClientConfig(client, { probe = false } = {}) {
   const reconnect = probe
     ? { enabled: false, initialDelayMs: 1, maxDelayMs: 1, maxAttempts: 1 }
@@ -88,38 +110,134 @@ async function bounded(promise, timeoutMs, code, label) {
   }
 }
 
-export function createMcpMount({ loader, onError = () => {}, startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT, cleanupTimeoutMs = DEFAULT_CLEANUP_TIMEOUT, ephemeralTree } = {}) {
+export function createMcpMount({
+  loader,
+  onError = () => {},
+  startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT,
+  cleanupTimeoutMs = DEFAULT_CLEANUP_TIMEOUT,
+  ephemeralTree,
+  ownership = createMcpMountOwnership(),
+} = {}) {
   /** @type {Map<string, { groupId: string, generation: number, state?: string }>} */
   const mounted = new Map()
+  const holder = {}
+  const scopedTrees = new Set()
 
-  const treeFor = secretBearing => {
-    const resolved = ephemeralTree === undefined ? resolveEphemeralMcpTree(loader) : ephemeralTree
-    if (resolved?.kind === 'ok' && resolved.tree) return resolved.tree
-    if (secretBearing) throw new McpLifecycleError('unsupported', new Error('secret-bearing MCP mount requires a proven non-profile-writing Loader root group'), { status: 'unsupported', action: 'use-secret-free-config' })
+  const legacyTree = () => {
     if (typeof loader?.create !== 'function' || typeof loader?.remove !== 'function') {
       throw new McpLifecycleError('unsupported', new Error('MCP Loader lifecycle is unavailable'), { status: 'unsupported' })
     }
-    // Compatibility for secret-free legacy records only. New secret-bearing
-    // paths can never reach this write-through branch.
-    return { ephemeral: false, create: options => loader.create(options), remove: id => loader.remove(id) }
+    return {
+      ephemeral: false,
+      scoped: false,
+      source: loader,
+      store: loader.store,
+      create: options => loader.create(options),
+      remove: id => loader.remove(id),
+      entries: typeof loader.entries === 'function' ? () => [...loader.entries()] : null,
+      resolve: typeof loader.resolve === 'function' ? id => loader.resolve(id) : null,
+      await: typeof loader.await === 'function' ? () => loader.await() : async () => {},
+    }
+  }
+
+  const hostTree = () => {
+    const resolved = resolveEphemeralMcpTree(loader)
+    return resolved.kind === 'ok' ? resolved.tree : legacyTree()
   }
 
-  function entriesFor(groupId) {
-    if (typeof loader?.entries === 'function') {
-      return [...loader.entries()].filter(entry => entry?.id === groupId || String(entry?.id ?? '').startsWith(`${groupId}:`))
+  const treeFor = secretBearing => {
+    // An explicitly retained/revision-scoped tree is mandatory. If its proven
+    // non-writing shape is unavailable, fail closed rather than silently
+    // reintroducing a shared-root same-identity collision.
+    if (ephemeralTree !== undefined && ephemeralTree?.kind !== 'ok') {
+      throw new McpLifecycleError('unsupported', new Error('revision-scoped MCP mount requires its proven non-profile-writing PresetTree'), { status: 'unsupported', action: 'recover-residue' })
     }
-    if (loader?.store && typeof loader.store === 'object') {
-      return Object.values(loader.store).filter(entry => entry?.id === groupId || entry?.options?.id === groupId || String(entry?.options?.id ?? '').startsWith(`${groupId}-`))
+    const resolved = ephemeralTree === undefined ? resolveEphemeralMcpTree(loader) : ephemeralTree
+    if (resolved?.kind === 'ok' && resolved.tree) {
+      if (resolved.tree.scoped) scopedTrees.add(resolved.tree)
+      return resolved.tree
+    }
+    if (secretBearing) throw new McpLifecycleError('unsupported', new Error('secret-bearing MCP mount requires a proven non-profile-writing Loader root group'), { status: 'unsupported', action: 'use-secret-free-config' })
+    // Compatibility for secret-free legacy records only.
+    return legacyTree()
+  }
+
+  function entriesWithTree(tree, groupId) {
+    const localId = entry => entry?.options?.id ?? entry?.id
+    if (typeof tree?.entries === 'function') {
+      return [...tree.entries()].filter(entry => {
+        const id = localId(entry)
+        return id === groupId || String(id ?? '').startsWith(`${groupId}:`)
+          || id === `${groupId}-facade` || id === `${groupId}-client`
+      })
+    }
+    if (tree?.store && typeof tree.store === 'object') {
+      return Object.values(tree.store).filter(entry => {
+        const id = localId(entry)
+        return id === groupId || id === `${groupId}-facade` || id === `${groupId}-client`
+      })
     }
     return null
   }
 
+  function treeForGroup(groupId) {
+    return ownership.forGroup(groupId)?.tree ?? null
+  }
+
+  function residueTree(groupId) {
+    const owned = treeForGroup(groupId)
+    if (owned) return owned
+    if (!loader) return treeFor(false)
+    const host = hostTree()
+    const hostEntries = entriesWithTree(host, groupId)
+    if (hostEntries?.some(entry => (entry?.options?.id ?? entry?.id) === groupId)) return host
+    return treeFor(false)
+  }
+
+  function entriesFor(groupId, tree = null) {
+    return entriesWithTree(tree ?? residueTree(groupId), groupId)
+  }
+
   function forgetGroup(groupId, generation) {
     for (const [identity, entry] of mounted) {
       if (entry.groupId === groupId && (!generation || entry.generation === generation)) mounted.delete(identity)
     }
   }
 
+  function track(record, promise) {
+    const pending = Promise.resolve(promise)
+    if (!record) return pending
+    record.pending.add(pending)
+    pending.then(() => record.pending.delete(pending), () => record.pending.delete(pending))
+    return pending
+  }
+
+  function failedCleanup(groupId, status, cause, record = null) {
+    if (record) ownership.transition(record, status)
+    return {
+      status, removed: false, groupId,
+      diagnostic: mcpDiagnostic(cause, { code: status, action: 'recover-residue' }),
+    }
+  }
+
+  async function finishCleaned(groupId, context, record, removed) {
+    forgetGroup(groupId, context.generation)
+    try {
+      if (typeof context.afterCleanup === 'function') {
+        await context.afterCleanup({
+          groupId, identity: context.identity, generation: context.generation,
+          probe: context.probe === true, owner: record?.owner,
+        })
+      }
+    } catch (cause) {
+      return failedCleanup(groupId, 'cleanup-failed', cause, record)
+    }
+    if (record && !ownership.release(record, { provenAbsent: true })) {
+      return failedCleanup(groupId, 'cleanup-unknown', new Error('MCP mount ownership still has unresolved create/disposal work'), record)
+    }
+    return { status: 'cleaned', removed, groupId }
+  }
+
   /**
    * Capture and settle group/client/descendant fibers BEFORE removing rows.
    * remove() is not the barrier: its return does not await async plugin
@@ -127,19 +245,34 @@ export function createMcpMount({ loader, onError = () => {}, startupTimeoutMs =
    * replacement and leaves enough state for residue recovery.
    */
   async function disposeGroup(groupId, context = {}) {
-    const tree = context.tree ?? treeFor(Boolean(context.secretBearing))
-    const captured = entriesFor(groupId)
+    const record = ownership.forGroup(groupId)
+    if (record && record.holder !== holder) {
+      return failedCleanup(groupId, 'cleanup-unknown', new Error('cannot dispose a foreign active MCP mount owner'))
+    }
+    const tree = context.tree ?? record?.tree ?? residueTree(groupId)
+    if (record?.pending.size) {
+      try {
+        await bounded(Promise.allSettled([...record.pending]), cleanupTimeoutMs, 'cleanup-timeout', `MCP pending create/disposal ${groupId}`)
+      } catch (cause) {
+        return failedCleanup(groupId, 'cleanup-unknown', cause, record)
+      }
+      if (record.pending.size > 0) return failedCleanup(groupId, 'cleanup-unknown', new Error('MCP create/disposal has not settled'), record)
+    }
+    const captured = entriesWithTree(tree, groupId)
     if (captured?.length === 0) {
-      forgetGroup(groupId, context.generation)
-      return { status: 'cleaned', removed: false, groupId }
+      if (context.requireCapture === true && context.createTimedOut === true && record?.pending.size) {
+        return failedCleanup(groupId, 'cleanup-unknown', new Error('MCP create settlement is not proven'), record)
+      }
+      return finishCleaned(groupId, context, record, false)
     }
-    if (captured === null && context.requireCapture === true) {
-      return { status: 'cleanup-unknown', removed: false, groupId, diagnostic: mcpDiagnostic(new Error('cannot capture Loader fibers for disposal'), { code: 'cleanup-unknown', action: 'recover-residue' }) }
+    if (captured === null && (context.requireCapture === true || context.createTimedOut === true)) {
+      return failedCleanup(groupId, 'cleanup-unknown', new Error('cannot capture Loader fibers for disposal'), record)
     }
     const fibers = (captured ?? []).map(entry => entry?.fiber).filter(Boolean)
     const disposals = fibers.map((fiber, index) => {
       try {
-        return bounded(fiber.dispose?.(), cleanupTimeoutMs, 'cleanup-timeout', `MCP disposal ${groupId}[${index}]`)
+        const disposal = track(record, fiber.dispose?.())
+        return bounded(disposal, cleanupTimeoutMs, 'cleanup-timeout', `MCP disposal ${groupId}[${index}]`)
       } catch (cause) {
         return Promise.reject(cause)
       }
@@ -147,105 +280,208 @@ export function createMcpMount({ loader, onError = () => {}, startupTimeoutMs =
     const settled = await Promise.allSettled(disposals)
     const rejected = settled.find(result => result.status === 'rejected')
     if (rejected) {
-      return { status: rejected.reason?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed', removed: false, groupId, diagnostic: mcpDiagnostic(rejected.reason, { code: rejected.reason?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed', action: 'recover-residue' }) }
+      const status = rejected.reason?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed'
+      return failedCleanup(groupId, status, rejected.reason, record)
     }
     try {
-      await bounded(tree.remove(groupId), cleanupTimeoutMs, 'cleanup-timeout', `MCP Loader remove ${groupId}`)
+      const removing = track(record, tree.remove(groupId))
+      await bounded(removing, cleanupTimeoutMs, 'cleanup-timeout', `MCP Loader remove ${groupId}`)
     } catch (cause) {
-      return { status: cause?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed', removed: false, groupId, diagnostic: mcpDiagnostic(cause, { code: cause?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed', action: 'recover-residue' }) }
+      const status = cause?.code === 'cleanup-timeout' ? 'cleanup-unknown' : 'cleanup-failed'
+      return failedCleanup(groupId, status, cause, record)
     }
-    const remaining = entriesFor(groupId)
+    const remaining = entriesWithTree(tree, groupId)
     let closeConfirmed = remaining === null ? true : remaining.length === 0
     if (typeof context.confirmClosed === 'function') {
       try {
         closeConfirmed = closeConfirmed && await bounded(context.confirmClosed({ groupId, entries: captured, fibers }), cleanupTimeoutMs, 'cleanup-timeout', `MCP close confirmation ${groupId}`) === true
       } catch (cause) {
-        return { status: 'cleanup-unknown', removed: false, groupId, diagnostic: mcpDiagnostic(cause, { code: 'cleanup-unknown', action: 'recover-residue' }) }
+        return failedCleanup(groupId, 'cleanup-unknown', cause, record)
       }
     } else if (captured !== null) {
       closeConfirmed = closeConfirmed && fibers.every(fiber => fiber.uid === null || fiber.state === 4 || fiber.state === 5)
     }
     if (!closeConfirmed || remaining === null && context.requireCapture === true) {
-      return { status: 'cleanup-unknown', removed: false, groupId, diagnostic: mcpDiagnostic(new Error('MCP transport closure or Loader row removal could not be confirmed'), { code: 'cleanup-unknown', action: 'recover-residue' }) }
+      return failedCleanup(groupId, 'cleanup-unknown', new Error('MCP transport closure or Loader row removal could not be confirmed'), record)
     }
-    forgetGroup(groupId, context.generation)
-    return { status: 'cleaned', removed: true, groupId }
+    return finishCleaned(groupId, context, record, true)
   }
 
-  async function sweepResidue(candidateIds) {
-    const removed = []
+  function identityForGroup(groupId) {
+    const entries = entriesFor(groupId)
+    const exact = entries?.find(entry => (entry?.options?.id ?? entry?.id) === groupId)
+    // The manager's own plugin ID is residue-shaped but is not a Loader group.
+    // Never claim/dispose a standalone row merely because its ID has the prefix.
+    if (exact && exact.options?.group !== true) return null
+    const row = exact ?? { id: groupId }
+    return resolveMcpGroupIdentity({ groupId, mounted, ownership, row })
+  }
+
+  async function sweepResidueDetailed(candidateIds, context = {}) {
+    const swept = []
+    const blocked = []
+    const foreign = []
+    const unresolved = []
     for (const id of candidateIds.filter(isMcpResidueId)) {
-      const cleanup = await disposeGroup(id, { tree: treeFor(false), identity: id.slice(MCP_GROUP_PREFIX.length) })
-      if (cleanup.status === 'cleaned') removed.push(id)
-      else onError(`residue-sweep-${cleanup.status}:${id}`, cleanup.diagnostic)
+      let record = ownership.forGroup(id)
+      if (record && record.holder !== holder) {
+        foreign.push(id)
+        continue
+      }
+      const resolved = identityForGroup(id)
+      if (!resolved) {
+        unresolved.push(id)
+        continue
+      }
+      const tree = record?.tree ?? residueTree(id)
+      if (!record) {
+        const captured = entriesWithTree(tree, id)
+        const activeUnknown = captured?.some(entry => {
+          const entryId = entry?.options?.id ?? entry?.id
+          if (entryId === id) return false // the container may be active while every child is disabled residue
+          const fiber = entry?.fiber
+          return fiber && fiber.uid !== null && fiber.state !== 4 && fiber.state !== 5
+        })
+        // A facade/config row without a module-realm owner may belong to another
+        // loaded bundle instance. Active cross-module ownership is unprovable:
+        // retain it instead of sweeping a foreign live client.
+        if (activeUnknown) {
+          foreign.push(id)
+          continue
+        }
+        record = ownership.claimResidue({ identity: resolved.identity, groupId: id, holder, tree })
+      }
+      if (!record) {
+        foreign.push(id)
+        continue
+      }
+      const cleanup = await disposeGroup(id, {
+        tree, identity: resolved.identity, secretBearing: false,
+        afterCleanup: context.afterCleanup,
+        requireCapture: isSuffixedMcpGroupId(id) || tree.scoped === true,
+      })
+      if (cleanup.status === 'cleaned') swept.push(id)
+      else {
+        blocked.push(id)
+        onError(`residue-sweep-${cleanup.status}:${id}`, cleanup.diagnostic)
+      }
     }
-    return removed
+    return { swept, blocked, foreign, unresolved }
+  }
+
+  async function sweepResidue(candidateIds, context = {}) {
+    return (await sweepResidueDetailed(candidateIds, context)).swept
   }
 
   async function mountOne(input) {
     const { identity, generation, fiberOf, probe = false, secretBearing = false } = input
+    if (!isSegment(identity)) throw new TypeError(`invalid MCP server identity: ${JSON.stringify(identity)}`)
     const previous = mounted.get(identity)
     if (!probe && (previous?.state === 'cleanup-failed' || previous?.state === 'cleanup-unknown')) {
       throw new McpLifecycleError(previous.state, new Error(`same-name MCP replacement is blocked while ${identity} is ${previous.state}`), { status: previous.state, action: 'recover-residue' })
     }
-    const options = mcpGroupOptions({ identity, generation, client: strictMcpClientConfig(input.client, { probe }) })
     const tree = treeFor(secretBearing)
+    let record = null
+    let options = null
     let bridgeReady = false
+    let createStarted = false
     let cleanup = null
     let succeeded = false
     try {
-      if (typeof input.beforeCreate === 'function') await input.beforeCreate({ groupId: options.id, identity, generation, probe, ephemeral: tree.ephemeral === true })
+      record = ownership.claim(identity, {
+        holder, tree,
+        available: groupId => {
+          const existing = entriesWithTree(tree, groupId)
+          if (existing?.length) return false
+          if (tree.scoped && loader) {
+            const hostEntries = entriesWithTree(hostTree(), groupId)
+            if (hostEntries?.length) return false
+          }
+          return true
+        },
+      })
+      options = mcpGroupOptions({ identity, generation, groupId: record.groupId, client: strictMcpClientConfig(input.client, { probe }) })
+      const attempt = () => ({ groupId: options.id, identity, generation, probe, ephemeral: tree.ephemeral === true, owner: record.owner })
+      if (typeof input.beforeCreate === 'function') await input.beforeCreate(attempt())
       bridgeReady = true
-      await bounded(tree.create(options), startupTimeoutMs, 'startup-timeout', `MCP Loader create ${identity}`)
-      await bounded(loader.await(), startupTimeoutMs, 'startup-timeout', `MCP Loader await ${identity}`)
+      // A foreign module realm may have claimed the group while an async
+      // beforeCreate callback yielded. Never dispose that row as our residue.
+      const collision = entriesWithTree(tree, options.id)
+      if (collision?.length) throw Object.assign(new Error(`MCP Loader group ${options.id} was claimed by another owner`), { code: 'duplicate-mcp-group-owner' })
+      createStarted = true
+      // The claim above occupies the actual ID synchronously before this call;
+      // its original promise remains tracked even if the bounded wait times out.
+      const creating = track(record, tree.create(options))
+      await bounded(creating, startupTimeoutMs, 'startup-timeout', `MCP Loader create ${identity}`)
+      await bounded(tree.await(), startupTimeoutMs, 'startup-timeout', `MCP Loader await ${identity}`)
       const fiber = typeof fiberOf === 'function'
-        ? await bounded(fiberOf(options.id), startupTimeoutMs, 'startup-timeout', `MCP client readiness ${identity}`)
+        ? await bounded(fiberOf(options.id, { tree, owner: record.owner }), startupTimeoutMs, 'startup-timeout', `MCP client readiness ${identity}`)
         : { state: 'running' }
       if (fiber === null || fiber === undefined) throw new Error('mcp-mount-error: client entry has no fiber after loader.await()')
       if (fiber.state !== undefined && !['running', 'active', 2].includes(fiber.state)) throw new Error(`mcp-mount-error: client fiber is not ready (state ${String(fiber.state)})`)
-      const clientEntry = loader?.store?.[`${options.id}-client`]
+      const clientEntry = tree.store?.[`${options.id}-client`]
       if (clientEntry?.error) throw clientEntry.error
-      if (typeof input.readback === 'function') await input.readback({ groupId: options.id, identity, generation, probe })
-      const discovery = typeof input.discovery === 'function' ? await input.discovery({ groupId: options.id, identity, generation, probe }) : { toolCount: null, toolNamesPreview: [], truncated: false }
+      if (typeof input.readback === 'function') await input.readback(attempt())
+      const discovery = typeof input.discovery === 'function' ? await input.discovery(attempt()) : { toolCount: null, toolNamesPreview: [], truncated: false }
       const result = { status: 'mounted', groupId: options.id, identity, generation, probe, discovery, execution: input.execution ?? null }
       if (!probe) mounted.set(identity, { groupId: options.id, generation, state: 'mounted' })
+      ownership.transition(record, 'mounted')
       succeeded = true
       return result
     } catch (cause) {
-      cleanup = await disposeGroup(options.id, { tree, identity, generation, secretBearing, confirmClosed: input.confirmClosed })
-      if (!probe && cleanup.status !== 'cleaned') mounted.set(identity, { groupId: options.id, generation, state: cleanup.status })
-      const diagnostic = mcpDiagnostic(cause, { secrets: input.secrets, action: cleanup.status === 'cleaned' ? 'retry' : 'recover-residue' })
-      throw new McpLifecycleError(cleanup.status === 'cleaned' ? diagnostic.code : cleanup.status, cause, {
-        status: cleanup.status === 'cleaned' ? (probe ? 'probe-failed' : 'mount-failed') : cleanup.status,
+      if (!createStarted && record) {
+        cleanup = await finishCleaned(options.id, {
+          identity, generation, probe,
+          afterCleanup: bridgeReady ? input.afterCleanup : null,
+        }, record, false)
+      } else if (options) {
+        cleanup = await disposeGroup(options.id, {
+          tree, identity, generation, probe, secretBearing,
+          confirmClosed: input.confirmClosed,
+          createTimedOut: cause?.code === 'startup-timeout' && createStarted,
+          requireCapture: cause?.code === 'startup-timeout' && createStarted,
+          afterCleanup: bridgeReady ? input.afterCleanup : null,
+        })
+      }
+      if (!probe && cleanup && cleanup.status !== 'cleaned') mounted.set(identity, { groupId: options.id, generation, state: cleanup.status })
+      const diagnostic = mcpDiagnostic(cause, { secrets: input.secrets, action: cleanup?.status === 'cleaned' ? 'retry' : 'recover-residue' })
+      throw new McpLifecycleError(cleanup?.status === 'cleaned' ? diagnostic.code : cleanup?.status ?? 'mount-failed', cause, {
+        status: cleanup?.status === 'cleaned' ? (probe ? 'probe-failed' : 'mount-failed') : cleanup?.status ?? 'mount-failed',
         secrets: input.secrets,
         cleanup,
-        action: cleanup.status === 'cleaned' ? 'retry' : 'recover-residue',
+        action: cleanup?.status === 'cleaned' ? 'retry' : 'recover-residue',
       })
     } finally {
-      if (!succeeded && bridgeReady && cleanup?.status === 'cleaned' && typeof input.afterCleanup === 'function') await input.afterCleanup({ groupId: options.id, identity, generation, probe })
-      if (succeeded && probe && typeof input.afterProbeReady === 'function') await input.afterProbeReady({ groupId: options.id, identity, generation })
+      if (succeeded && probe && typeof input.afterProbeReady === 'function') await input.afterProbeReady({ groupId: options.id, identity, generation, owner: record.owner })
     }
   }
 
   async function unmountOne(identity, guards = {}, context = {}) {
     const entry = mounted.get(identity)
-    if (!entry && context.required === true) return { status: 'cleanup-unknown', removed: false, reason: 'mount-record-missing' }
-    const groupId = entry?.groupId ?? `${MCP_GROUP_PREFIX}${identity}`
-    const cleanup = await disposeGroup(groupId, { ...context, identity, generation: entry?.generation, tree: context.tree ?? treeFor(Boolean(context.secretBearing)) })
+    if (!entry) {
+      if (context.required === true) return { status: 'cleanup-unknown', removed: false, reason: 'mount-record-missing' }
+      // Ordinary cleanup is not residue recovery: without our exact mount record
+      // there is no authority to infer and delete a possibly reused legacy ID.
+      return { status: 'cleaned', removed: false, groupId: null }
+    }
+    const groupId = entry.groupId
+    const cleanup = await disposeGroup(groupId, {
+      ...context, identity, generation: entry.generation,
+      tree: context.tree ?? treeForGroup(groupId) ?? treeFor(Boolean(context.secretBearing)),
+    })
     if (cleanup.status !== 'cleaned') {
-      if (entry) entry.state = cleanup.status
+      entry.state = cleanup.status
       return cleanup
     }
     if (typeof guards.alive === 'function' && typeof guards.remount === 'function') {
-      for (const [other] of mounted) {
-        const siblingGroup = `${MCP_GROUP_PREFIX}${other}`
-        if (!guards.alive().includes(siblingGroup)) {
+      for (const [other, sibling] of mounted) {
+        if (!guards.alive().includes(sibling.groupId)) {
           onError(`sibling-vanished-after-unmount:${other}`)
           await guards.remount(other)
         }
       }
     }
-    return { status: 'cleaned', removed: Boolean(entry) || cleanup.removed, groupId }
+    return { status: 'cleaned', removed: true, groupId }
   }
 
   async function probe(input) {
@@ -260,14 +496,27 @@ export function createMcpMount({ loader, onError = () => {}, startupTimeoutMs =
       if (cause instanceof McpLifecycleError) throw cause
       throw new McpLifecycleError('probe-failed', cause, { status: 'probe-failed', secrets: input.secrets })
     }
-    try {
-      const cleanup = await disposeGroup(ready.groupId, { tree: treeFor(Boolean(input.secretBearing)), identity, generation: ready.generation, secretBearing: Boolean(input.secretBearing), confirmClosed: input.confirmClosed, requireCapture: true })
-      if (cleanup.status !== 'cleaned') return { status: cleanup.status, identity, generation: ready.generation, cleanup, diagnostic: cleanup.diagnostic }
-      if (typeof input.afterCleanup === 'function') await input.afterCleanup({ groupId: ready.groupId, identity, generation: ready.generation, probe: true, cleanup })
-      return { ...ready, status: 'mounted', cleanup }
-    } catch (cause) {
-      throw new McpLifecycleError('cleanup-failed', cause, { status: 'cleanup-failed', secrets: input.secrets, action: 'recover-residue' })
+    const record = ownership.forGroup(ready.groupId)
+    const cleanup = await disposeGroup(ready.groupId, {
+      tree: record?.tree ?? treeFor(Boolean(input.secretBearing)), identity, generation: ready.generation,
+      probe: true, secretBearing: Boolean(input.secretBearing), confirmClosed: input.confirmClosed,
+      requireCapture: true, afterCleanup: input.afterCleanup,
+    })
+    if (cleanup.status !== 'cleaned') return { status: cleanup.status, identity, generation: ready.generation, cleanup, diagnostic: cleanup.diagnostic }
+    return { ...ready, status: 'mounted', cleanup }
+  }
+
+  function listRows() {
+    const rows = []
+    for (const tree of scopedTrees) {
+      for (const entry of tree.entries()) {
+        const options = entry?.options ?? {}
+        const id = options.id ?? entry?.id
+        if (!isMcpResidueId(id) || options.group !== true) continue
+        rows.push({ id, name: options.name ?? null, config: options.config ?? {} })
+      }
     }
+    return rows
   }
 
   const queues = new Map()
@@ -282,5 +531,8 @@ export function createMcpMount({ loader, onError = () => {}, startupTimeoutMs =
   const mount = input => input?.probe ? mountOne(input) : serialize(input.identity, () => mountOne(input))
   const unmount = (identity, guards = {}, context = {}) => serialize(identity, () => unmountOne(identity, guards, context))
 
-  return { mount, unmount, probe, sweepResidue, disposeGroup, mounted, entriesFor, message }
+  return {
+    mount, unmount, probe, sweepResidue, sweepResidueDetailed, disposeGroup,
+    mounted, entriesFor, identityForGroup, listRows, treeForGroup, ownership, message,
+  }
 }

package/src/capabilities/mcp-operation-coordinator.js

@@ -0,0 +1,76 @@
+// One manager-owned Operation Coordination module. The per-identity FIFO,
+// runtime fence/token and admission-drain transitions are inseparable here;
+// mount/probe/registry/CAS work remains in their existing modules.
+// The independent createMcpMount Disposal Barrier deliberately stays inner.
+
+/**
+ * Per-identity FIFO for operations that open a runtime fence. A rejected task
+ * does not poison its identity, and identities have independent tails. The
+ * queue is not reentrant: a caller already in a slot passes its fence token to
+ * the inner manager operation instead of serializing the same identity again.
+ */
+export function createMcpIdentityLock() {
+  const tails = new Map()
+  return function serialize(identity, task) {
+    const previous = tails.get(identity) ?? Promise.resolve()
+    const run = previous.then(() => task())
+    const tail = run.then(() => {}, () => {})
+    tails.set(identity, tail)
+    void tail.then(() => { if (tails.get(identity) === tail) tails.delete(identity) })
+    return run
+  }
+}
+
+const fallbackLocks = new WeakMap()
+/**
+ * Resolve the manager's own queue. The WeakMap fallback only supports legacy
+ * test/older faces without serialize; a real manager always exposes its one
+ * coordinator queue so this adapter cannot silently fork production ordering.
+ */
+export function mcpIdentityLockFor(manager) {
+  if (typeof manager?.serialize === 'function') return (identity, task) => manager.serialize(identity, task)
+  if (!manager || (typeof manager !== 'object' && typeof manager !== 'function')) return createMcpIdentityLock()
+  let lock = fallbackLocks.get(manager)
+  if (!lock) { lock = createMcpIdentityLock(); fallbackLocks.set(manager, lock) }
+  return lock
+}
+
+/**
+ * @param {{
+ *   runtime: ReturnType<typeof import('./mcp-runtime.js').createMcpRuntime>,
+ *   drain: { closeAll: (identity: string) => void, reopenAll: (identity: string) => void },
+ *   transition?: <T>(identity: string, change: () => T) => T,
+ * }} options
+ */
+export function createMcpOperationCoordinator({ runtime, drain, transition = (_identity, change) => change() }) {
+  const serialize = createMcpIdentityLock()
+
+  function beginOperation(identity, phase = 'replacing', details = {}) {
+    return transition(identity, () => {
+      // Both transitions are synchronous and precede every async operation
+      // step. No registry, credential or probe await can precede this fence.
+      const token = runtime.begin(identity, { phase, ...details })
+      drain.closeAll(identity)
+      return token
+    })
+  }
+
+  function finishOperation(token, phase, details = {}) {
+    const finished = transition(token.identity, () => runtime.finish(token, phase, details))
+    // A stale finish cannot report mounted through runtime.finish and must not
+    // reopen admission for whichever operation now owns the identity.
+    if (finished && phase === 'mounted') drain.reopenAll(token.identity)
+    return finished
+  }
+
+  function abortOperation(token) {
+    const previousPhase = token.previous?.phase
+    return transition(token.identity, () => {
+      const restored = runtime.restore(token)
+      if (restored && previousPhase === 'mounted') drain.reopenAll(token.identity)
+      return restored
+    })
+  }
+
+  return { serialize, beginOperation, finishOperation, abortOperation }
+}