weir-harness 1.2.3 → 2.1.0

package/src/capabilities/mcp-credentials.js

@@ -0,0 +1,180 @@
+// Attempt-scoped DSH credential allocation, materialization and conservative
+// compensation. Only random Weir-owned refs are ever unset; unknown registry
+// outcomes retain credentials and report indeterminate rather than guessing.
+import { createHash, randomUUID } from 'node:crypto'
+import { McpLifecycleError } from './mcp-diagnostics.js'
+import { validateCredentialRef } from './mcp-config.js'
+
+const hash = value => createHash('sha256').update(String(value)).digest('hex').slice(0, 12)
+const clone = value => value == null ? value : structuredClone(value)
+const kinds = ['env', 'headers', 'args']
+
+export function collectMcpCredentialRefs(entry) {
+  const refs = new Set()
+  for (const kind of kinds) for (const value of Object.values(entry?.secretRefs?.[kind] ?? {})) if (value?.ref) refs.add(value.ref)
+  if (entry?.secretRefs?.url?.ref) refs.add(entry.secretRefs.url.ref)
+  return [...refs]
+}
+
+function usedRefs(registryRecord) {
+  const used = new Set()
+  if (registryRecord?.kind !== 'ok') return used
+  for (const entry of Object.values(registryRecord.servers ?? {})) for (const ref of collectMcpCredentialRefs(entry)) used.add(ref)
+  return used
+}
+
+function credentialName(identity, generation, attemptId, field) {
+  return `WEIR_MCP_${hash(identity)}_G${generation}_${attemptId.replaceAll('-', '').slice(0, 16)}_${hash(field)}`
+}
+
+/** Allocate unique refs without writing them. A fresh attempt never shares a compensation target. */
+export function allocateMcpCredentialAttempt({ identity, generation, attemptId = randomUUID().replaceAll('-', '') }) {
+  if (!/^[a-f0-9-]{8,64}$/i.test(attemptId)) throw new TypeError('invalid MCP credential attempt id')
+  const ownedRefs = new Set()
+  return {
+    id: attemptId,
+    ownedRefs,
+    refFor(field) {
+      const ref = credentialName(identity, generation, attemptId, field)
+      ownedRefs.add(ref)
+      return ref
+    },
+  }
+}
+
+async function resolveValue(credentials, reference) {
+  if (!validateCredentialRef(reference)) throw new McpLifecycleError('credential-missing', new Error('invalid credential reference'), { status: 'validation-failed', action: 'configure-credential' })
+  let resolved
+  try { resolved = await credentials?.resolve?.(reference) } catch (cause) {
+    throw new McpLifecycleError('credential-missing', new Error(`credential ${reference} could not be resolved`, { cause }), { status: 'validation-failed', action: 'configure-credential' })
+  }
+  const value = typeof resolved === 'string' ? resolved : resolved?.value
+  if (typeof value !== 'string' || value.length === 0) throw new McpLifecycleError('credential-missing', new Error(`credential ${reference} is missing or empty`), { status: 'validation-failed', action: 'configure-credential' })
+  return value
+}
+
+/** Resolve refs on every probe/mount/restart; values remain in Host memory only. */
+export async function materializeMcpClientConfig(entry, credentials) {
+  const client = clone(entry?.client ?? {})
+  const resolvedSecrets = []
+  const resolve = async reference => {
+    const value = await resolveValue(credentials, reference)
+    resolvedSecrets.push(value)
+    return value
+  }
+  for (const [key, item] of Object.entries(entry?.secretRefs?.env ?? {})) {
+    client.env ??= {}
+    client.env[key] = `${item.prefix ?? ''}${await resolve(item.ref)}`
+  }
+  for (const [key, item] of Object.entries(entry?.secretRefs?.headers ?? {})) {
+    client.headers ??= {}
+    client.headers[key] = `${item.prefix ?? ''}${await resolve(item.ref)}`
+  }
+  for (const [key, item] of Object.entries(entry?.secretRefs?.args ?? {})) {
+    const index = Number(key)
+    if (!Number.isInteger(index) || index < 0 || index >= (client.args?.length ?? 0)) throw new McpLifecycleError('invalid-config', new Error(`secret argument ${key} is out of range`), { status: 'validation-failed' })
+    client.args[index] = `${item.prefix ?? ''}${await resolve(item.ref)}`
+  }
+  if (entry?.secretRefs?.url?.ref) client.url = await resolve(entry.secretRefs.url.ref)
+  client.failOnStartupError = true
+  delete client.secretRefs
+  return { client, resolvedSecrets }
+}
+
+/**
+ * Apply keep/replace/remove secret actions and stage newly allocated refs.
+ * The returned entry contains no transient values. On a partial set failure the
+ * function compensates only after a registry reread proves each ref unused.
+ */
+export async function stageMcpCredentials({ entry, secretValues = {}, credentials, registry, generation, attemptId }) {
+  const next = clone(entry)
+  next.secretRefs ??= {}
+  const attempt = allocateMcpCredentialAttempt({ identity: next.identity, generation, attemptId })
+  const writes = []
+  const ensureWritable = () => {
+    if (typeof credentials?.set !== 'function') throw new McpLifecycleError('unsupported', new Error('DSH credentials are unavailable for new secret values'), { status: 'unsupported', action: 'use-credential-refs' })
+  }
+  const actionsFor = (kind, key) => {
+    const value = secretValues?.[kind]?.[key]
+    return typeof value === 'string' ? (value === '' ? { action: 'keep' } : { action: 'replace', value }) : value
+  }
+  for (const kind of kinds) {
+    const keys = new Set([...Object.keys(secretValues?.[kind] ?? {})])
+    for (const key of keys) {
+      const action = actionsFor(kind, key)
+      if (!action || action.action === 'keep') continue
+      if (action.action === 'remove') {
+        delete next.secretRefs?.[kind]?.[key]
+        if (kind === 'env' && next.client?.env) delete next.client.env[key]
+        if (kind === 'headers' && next.client?.headers) delete next.client.headers[key]
+        if (kind === 'args' && next.client?.args?.[key] !== undefined) next.client.args[key] = ''
+        continue
+      }
+      if (action.action !== 'replace') throw new McpLifecycleError('invalid-config', new Error(`unknown secret action for ${kind}.${key}`), { status: 'validation-failed' })
+      ensureWritable()
+      const reference = attempt.refFor(`${kind}.${key}`)
+      const prefix = Object.hasOwn(action, 'prefix') ? action.prefix : next.secretRefs?.[kind]?.[key]?.prefix
+      next.secretRefs[kind] ??= {}
+      next.secretRefs[kind][key] = { ref: reference, ...(prefix ? { prefix } : {}) }
+      if (kind === 'env' && next.client?.env) delete next.client.env[key]
+      if (kind === 'headers' && next.client?.headers) delete next.client.headers[key]
+      if (kind === 'args' && next.client?.args?.[key] !== undefined) next.client.args[key] = ''
+      writes.push({ ref: reference, value: action.value })
+    }
+  }
+  const urlAction = typeof secretValues.url === 'string' ? { action: 'replace', value: secretValues.url } : secretValues.url
+  if (urlAction && urlAction.action !== 'keep') {
+    if (urlAction.action === 'remove') {
+      delete next.secretRefs.url
+      delete next.client.url
+    } else if (urlAction.action === 'replace') {
+      ensureWritable()
+      const reference = attempt.refFor('url')
+      next.secretRefs.url = { ref: reference }
+      delete next.client.url
+      writes.push({ ref: reference, value: urlAction.value })
+    } else throw new McpLifecycleError('invalid-config', new Error('unknown secret action for url'), { status: 'validation-failed' })
+  }
+  for (const kind of kinds) if (next.secretRefs?.[kind] && Object.keys(next.secretRefs[kind]).length === 0) delete next.secretRefs[kind]
+  if (next.secretRefs && Object.keys(next.secretRefs).length === 0) delete next.secretRefs
+  try {
+    for (const write of writes) await credentials.set(write.ref, write.value)
+    Object.defineProperty(attempt, 'secrets', { value: Object.freeze(writes.map(write => write.value)), enumerable: false })
+    return { status: 'staged', entry: next, attempt }
+  } catch (cause) {
+    const cleanup = await compensateMcpCredentialAttempt({ attempt, registry, credentials, provenUncommitted: true })
+    throw new McpLifecycleError(cleanup.status === 'cleaned' ? 'credential-write-failed' : cleanup.status, cause, {
+      status: cleanup.status === 'cleaned' ? 'validation-failed' : cleanup.status,
+      cleanup,
+      action: cleanup.status === 'cleaned' ? 'retry' : 'inspect-credentials',
+      secrets: writes.map(write => write.value),
+    })
+  }
+}
+
+/** Conservative compensation; never deletes user refs or performs orphan GC. */
+export async function compensateMcpCredentialAttempt({ attempt, registry, credentials, provenUncommitted }) {
+  if (!attempt || attempt.ownedRefs.size === 0) return { status: 'cleaned', unset: [] }
+  if (!provenUncommitted) return { status: 'indeterminate', retained: [...attempt.ownedRefs], reason: 'registry-outcome-unknown' }
+  let current
+  try { current = await registry.read() } catch (cause) {
+    return { status: 'indeterminate', retained: [...attempt.ownedRefs], reason: 'registry-reread-failed', diagnostic: String(cause?.message ?? cause) }
+  }
+  if (!['ok', 'absent'].includes(current?.kind)) return { status: 'indeterminate', retained: [...attempt.ownedRefs], reason: `registry-${current?.kind ?? 'unknown'}` }
+  const used = usedRefs(current)
+  const unset = []
+  const retained = []
+  const failures = []
+  for (const reference of attempt.ownedRefs) {
+    if (used.has(reference)) { retained.push(reference); continue }
+    try {
+      await credentials.unset(reference)
+      unset.push(reference)
+    } catch (cause) {
+      retained.push(reference)
+      failures.push({ ref: reference, message: String(cause?.message ?? cause).slice(0, 512) })
+    }
+  }
+  if (failures.length) return { status: 'cleanup-failed', unset, retained, failures }
+  return { status: 'cleaned', unset, retained }
+}

package/src/capabilities/mcp-diagnostics.js

@@ -0,0 +1,169 @@
+// Secret-free, bounded MCP diagnostics. Raw Error objects, stacks, URLs with
+// credentials, and arbitrary cause chains never cross the operation boundary.
+export const MCP_DIAGNOSTIC_LIMIT = 8192
+const CAUSE_LIMIT = 6
+
+const MESSAGE = value => value instanceof Error ? value.message : String(value ?? 'unknown error')
+
+/** Known-secret metadata is internal, inherited through wrapped causes, and never enumerated on the wire. */
+function errorSecrets(error, initial = []) {
+  const secrets = [...initial]
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    if (Array.isArray(current?.secrets)) secrets.push(...current.secrets)
+    current = current?.cause
+  }
+  return secrets
+}
+
+/** Replace known secrets, then reduce sensitive URL tails to scheme/host/path. */
+function redactKnownAndUrls(text, secrets) {
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Any sensitive URL component makes the whole userinfo/query/fragment tail
+  // sensitive. Preserve only scheme/host/path for actionable diagnostics.
+  return text.replace(/\b(?:https?|wss?):\/\/[^\s<>"']+/gi, candidate => {
+    const trailing = candidate.match(/[.,;:!?)]*$/)?.[0] ?? ''
+    const raw = trailing ? candidate.slice(0, -trailing.length) : candidate
+    try {
+      const url = new URL(raw)
+      if (!url.username && !url.password && !url.search && !url.hash) return candidate
+      return `${url.protocol}//${url.host}${url.pathname}[redacted-url]${trailing}`
+    } catch {
+      return '[redacted-url]'
+    }
+  })
+}
+
+/** Free text: replace every known secret before applying pattern-based redaction. */
+export function sanitizeMcpText(value, secrets = []) {
+  let text = String(value ?? '')
+  const known = [...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]
+    .sort((a, b) => b.length - a.length)
+  for (const secret of known) text = text.split(secret).join('[redacted]')
+  // Authorization lines and common secret-bearing key/value spellings.
+  text = text.replace(/\b(?:proxy-)?authorization\s*:\s*[^\r\n,;}]+/gi, match => `${match.split(':')[0]}: [redacted]`)
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+  text = text.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[redacted-jwt]')
+  text = text.replace(/\b(?:api[-_]?key|access[-_]?token|refresh[-_]?token|password|passwd|secret|client[-_]?secret)(\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}]+)/gi, (_match, key, separator) => `${key}${separator}[redacted]`)
+  // Shell/environment assignments. Values may be quoted; the key remains useful.
+  text = text.replace(/\b[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s]+)/g, assignment => `${assignment.slice(0, assignment.indexOf('='))}=[redacted]`)
+  return redactKnownAndUrls(text, [])
+}
+
+/**
+ * Structured MCP configuration fields (argv, command, cwd, label, refs) are
+ * exact values the user must be able to read, edit and approve. Secret-bearing
+ * positions are already replaced structurally (secretRefs-indexed args, env/
+ * header values, sensitive URLs); here only known secret values and sensitive
+ * URL tails are removed. The generic KEY=VALUE patterns are for free text only:
+ * applying them to argv turned `--port=8080` into `--port=[redacted]`.
+ */
+export function sanitizeMcpConfigText(value, secrets = []) {
+  return redactKnownAndUrls(String(value ?? ''), secrets)
+}
+
+// Config projections produced by redactMcpEntry. Membership is process-local and
+// lost on clone/serialization, which only falls back to the stricter free-text
+// sanitizer — never to less redaction.
+const CONFIG_PROJECTIONS = new WeakSet()
+export function markMcpConfigProjection(value) {
+  if (value && typeof value === 'object') CONFIG_PROJECTIONS.add(value)
+  return value
+}
+function sanitizeConfigProjection(value, secrets) {
+  if (typeof value === 'string') return sanitizeMcpConfigText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeConfigProjection(item, secrets))
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeConfigProjection(item, secrets)]))
+  return value
+}
+
+export function sanitizeMcpPayload(value, secrets = []) {
+  if (typeof value === 'string') return sanitizeMcpText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeMcpPayload(item, secrets))
+  if (value && typeof value === 'object') {
+    if (CONFIG_PROJECTIONS.has(value)) return markMcpConfigProjection(sanitizeConfigProjection(value, secrets))
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeMcpPayload(item, secrets)]))
+  }
+  return value
+}
+
+const RULES = [
+  ['credential-missing', /credential[- ]missing|credential.*(?:not configured|empty|missing)|missing.*credential/i, 'Configure a non-empty credential reference, then retry.'],
+  ['name-conflict', /serverName.*(?:already in use|conflict)|name[- ]conflict|namespace.*conflict/i, 'Choose a unique public server name or remove the conflicting registration.'],
+  ['executable-not-found', /\bENOENT\b|executable.*(?:not found|unavailable)|command.*not found|cannot find.*(?:command|executable)/i, 'Check the command and its GUI PATH resolution, then retry.'],
+  ['permission-denied', /\bEACCES\b|\bEPERM\b|permission denied|access denied/i, 'Check executable and credential/file permissions, then retry.'],
+  ['connection-refused', /ECONNREFUSED|connection refused/i, 'Check that the server is listening and the endpoint is correct, then retry.'],
+  ['http-unauthorized', /\bHTTP\s*40[13]\b|\b40[13]\b|unauthorized|forbidden/i, 'Check the HTTP credential reference and server authorization policy.'],
+  ['timeout', /timeout|timed out|deadline exceeded/i, 'Inspect server startup and connectivity, then retry with a healthy server.'],
+  ['invalid-config', /invalid config|validation|unsupported transport|unknown (?:option|field)|initialDelayMs|maxDelayMs/i, 'Correct the marked configuration field and preview again.'],
+  ['cleanup-unknown', /cleanup-unknown|closure could not be confirmed|unconfirmed (?:transport )?clos/i, 'Inspect residue before retrying; an immediate same-name replacement is blocked.'],
+  ['cleanup-failed', /cleanup-failed|dispose(?:d|al)?(?: rejection| failed)|remove rejection/i, 'Inspect the cleanup diagnostic and recover the remaining Loader entry before retrying.'],
+  ['unsupported', /unsupported|ephemeral.*unavailable/i, 'Use a secret-free configuration or a Host with the required ephemeral Loader support.'],
+  ['owner-changed', /owner-changed|preset.*changed|ownership.*changed/i, 'Return to the original session/preset and preview again.'],
+]
+
+export function classifyMcpError(error, secrets = []) {
+  secrets = errorSecrets(error, secrets)
+  const evidence = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    evidence.push(`${current?.code ?? ''} ${MESSAGE(current)}`)
+    current = current?.cause
+  }
+  const text = sanitizeMcpText(evidence.join('\n'), secrets)
+  const match = RULES.find(([, pattern]) => pattern.test(text))
+  if (!match) return { code: 'unknown-error', hint: 'Inspect the sanitized diagnostic and retry after correcting the cause.' }
+  return { code: match[0], hint: match[2] }
+}
+
+function boundedMessage(text, max = 4096) {
+  const clean = String(text)
+  return Buffer.byteLength(clean) <= max ? clean : Buffer.from(clean).subarray(0, max - 1).toString().replace(/\uFFFD+$/g, '') + '…'
+}
+
+/**
+ * Convert an Error/cause chain into one stable secret-free diagnostic. Both
+ * individual strings and the complete JSON projection are bounded to 8 KiB.
+ */
+export function mcpDiagnostic(error, options = {}) {
+  const secrets = errorSecrets(error, options.secrets ?? [])
+  const classified = options.code ? { code: options.code, hint: options.hint } : classifyMcpError(error, secrets)
+  const causes = []
+  let current = error
+  for (let depth = 0; current && depth < CAUSE_LIMIT; depth += 1) {
+    causes.push(boundedMessage(sanitizeMcpText(MESSAGE(current), secrets), 1024))
+    current = current?.cause
+  }
+  const first = causes[0] ?? boundedMessage(sanitizeMcpText(MESSAGE(error), secrets), 1024)
+  let diagnostic = {
+    code: classified.code ?? 'unknown-error',
+    message: boundedMessage(sanitizeMcpText(options.message ?? first, secrets)),
+    hint: boundedMessage(sanitizeMcpText(options.hint ?? classified.hint ?? 'Retry after correcting the cause.'), 1024),
+    recovery: { action: options.action ?? 'retry' },
+    causes,
+  }
+  while (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT && diagnostic.causes.length > 1) {
+    diagnostic.causes.pop()
+  }
+  if (Buffer.byteLength(JSON.stringify(diagnostic)) > MCP_DIAGNOSTIC_LIMIT) {
+    diagnostic.message = boundedMessage(diagnostic.message, 2048)
+    diagnostic.hint = boundedMessage(diagnostic.hint, 512)
+  }
+  return diagnostic
+}
+
+export class McpLifecycleError extends Error {
+  constructor(code, error, options = {}) {
+    const secrets = errorSecrets(error, options.secrets ?? [])
+    const diagnostic = mcpDiagnostic(error, { ...options, secrets, code, hint: options.hint })
+    super(diagnostic.message, options.cause === undefined && error instanceof Error ? { cause: error } : {})
+    this.name = 'McpLifecycleError'
+    this.code = code
+    this.status = options.status ?? code
+    this.diagnostic = diagnostic
+    Object.defineProperty(this, 'secrets', { value: Object.freeze([...new Set(secrets.filter(secret => typeof secret === 'string' && secret.length > 0))]), enumerable: false })
+    this.cleanup = options.cleanup === undefined ? undefined : sanitizeMcpPayload(options.cleanup, secrets)
+  }
+}

package/src/capabilities/mcp-drain.js

@@ -14,12 +14,13 @@
 export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
   /** @type {Map<string, { count: number, calls: Map<number, string>, closed: boolean }>} */
   const flights = new Map()
+  const closedServers = new Set()
   let sequence = 0
 
   const keyOf = (agentId, server) => `${agentId ?? 'unknown'}${server}`
   const stateOf = (agentId, server) => {
     const key = keyOf(agentId, server)
-    if (!flights.has(key)) flights.set(key, { count: 0, calls: new Map(), closed: false })
+    if (!flights.has(key)) flights.set(key, { server, count: 0, calls: new Map(), closed: false })
     return flights.get(key)
   }
 
@@ -30,7 +31,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
    */
   function enter(agentId, server, label = 'call') {
     const state = stateOf(agentId, server)
-    if (state.closed) return null
+    if (state.closed || closedServers.has(server)) return null
     sequence += 1
     state.count += 1
     state.calls.set(sequence, label)
@@ -68,7 +69,7 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
   }
 
   function isClosed(agentId, server) {
-    return stateOf(agentId, server).closed
+    return stateOf(agentId, server).closed || closedServers.has(server)
   }
 
   /** The Apply-time snapshot the response carries (sent at response time). */
@@ -77,7 +78,20 @@ export function createMcpDrain({ timeoutMs = 30_000, now = Date.now, sleep = ms
     return { server, state: state.count === 0 ? 'settled' : 'draining', inFlight: state.count }
   }
 
-  return { enter, exit, close, reopen, isClosed, drain, snapshot }
+  function closeAll(server) { closedServers.add(server) }
+  function reopenAll(server) { closedServers.delete(server) }
+  async function drainAll(server) {
+    const states = [...flights.values()].filter(state => state.server === server)
+    const started = now()
+    const totals = () => ({ count: states.reduce((sum, state) => sum + state.count, 0), calls: states.flatMap(state => [...state.calls.values()]) })
+    while (totals().count > 0 && now() - started < timeoutMs) await sleep(Math.min(50, timeoutMs))
+    const current = totals()
+    return current.count === 0
+      ? { drained: true, waitedMs: now() - started }
+      : { drained: false, inFlight: current.count, calls: current.calls, waitedMs: now() - started }
+  }
+
+  return { enter, exit, close, reopen, isClosed, drain, snapshot, closeAll, reopenAll, drainAll }
 }
 
 /**

package/src/capabilities/mcp-facade.js

@@ -32,8 +32,8 @@ const message = error => (error instanceof Error ? error.message : String(error)
  *   drain?: { enter(agentId: string, server: string, label?: string): number|null, exit(agentId: string, server: string, token: number|null): void },
  *   onError?: (reason: string, cause?: unknown) => void }} config
  */
-export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onError = () => {} }) {
-  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain })
+export function createMcpFacade({ host, identity, generation, admit, isEnabledFor, drain, onRegister, onError = () => {}, assertPermit }) {
+  const wrapper = createMcpToolWrapper({ identity, generation, admit, drain, assertPermit })
 
   const unknown = (service, method) => {
     const reason = `facade-unknown-method:${service}.${method}`
@@ -91,7 +91,7 @@ export function createMcpFacade({ host, identity, generation, admit, isEnabledFo
       const gated = typeof request === 'function'
         ? { ...provider, async request(args, exec) {
             const admitted = await admit(exec?.agent)
-            if (!admitted) {
+            if (!admitted || (assertPermit && !assertPermit(admitted))) {
               const error = new Error(`MCP server "${identity}" resources are not enabled for this agent`)
               throw Object.assign(error, { code: 'mcp-admission-refused' })
             }

package/src/capabilities/mcp-gate.js

@@ -1,23 +1,30 @@
-// Task 8.2/8.5 of the session-capability-manager change: the admission gate
-// service the facades consume. The verdict for "is this managed server
-// usable by this agent" combines, in order:
-//   1. the registry's configured identity + current generation (8.1) — a
-//      reconnect mounts a NEW generation and every old-generation handle is
-//      rejected; a same-named DIFFERENT identity inherits nothing (8.5);
-//   2. the session lifecycle snapshot: BLOCKED sessions refuse every managed
-//      call (6.4); a dispose/reload window without an initialized snapshot
-//      refuses too (8.5);
-//   3. the session's accepted managed-MCP set (the selection record's
-//      mcpServers): a server not in the set is not enabled for that agent.
-// Connections stay shared at the host plane — a session losing a server
-// never disposes anything (8.5).
+// Managed MCP admission combines runtime registration generation/incarnation,
+// the accepted lifecycle selection, and (when mounted) the per-identity runtime
+// phase. Legacy compatibility exists only when BOTH sides lack incarnations.
 
-/**
- * @param {{ registry: { read(): Promise<any> },
- *   lifecycle: { snapshotFor(sessionId: string): any },
- *   sessionMcpServers?: (sessionId: string) => string[] | null }} options
- */
-export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
+export function mcpIncarnationMatches(snapshot, identity, entry) {
+  if (!entry) return false
+  const mapping = snapshot?.mcpIncarnations
+  if (mapping && typeof mapping === 'object' && !Array.isArray(mapping)) {
+    if (!Object.hasOwn(mapping, identity)) return false
+    return mapping[identity] === (entry.incarnation ?? null)
+  }
+  // A legacy selection without a mapping remains valid only for a legacy entry.
+  return entry.incarnation == null
+}
+
+function acceptedSnapshot(lifecycle, agent, { parentFallback = false } = {}) {
+  const sessionId = agent?.session?.id
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+  let snapshot = lifecycle.snapshotFor(sessionId)
+  if (snapshot == null && parentFallback) {
+    const parentId = agent?.session?.header?.parentSession
+    if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+  }
+  return snapshot?.state === 'ready' ? snapshot : null
+}
+
+export function createMcpGate({ registry, lifecycle, sessionMcpServers, registrationFor, runtime }) {
   const acceptedOf = sessionId => {
     if (typeof sessionMcpServers === 'function') return sessionMcpServers(sessionId)
     const snapshot = lifecycle.snapshotFor(sessionId)
@@ -25,47 +32,39 @@ export function createMcpGate({ registry, lifecycle, sessionMcpServers }) {
     return snapshot.mcpServers
   }
 
-  /**
-   * The facade-side verdict for one call.
-   * @param {unknown} agent @param {string} identity @param {number} generation
-   * @returns {Promise<boolean>}
-   */
-  async function admit(agent, identity, generation) {
+  async function permit(agent, identity, generation) {
     const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    const snapshot = lifecycle.snapshotFor(sessionId)
-    // BLOCKED (6.4) or no initialized snapshot (dispose/reload window, 8.5):
-    // every managed call is refused, never an unrestricted pass.
-    if (snapshot?.state !== 'ready') return false
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return null
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return null
+    const snapshot = acceptedSnapshot(lifecycle, agent)
+    if (!snapshot) return null
     const accepted = acceptedOf(sessionId)
-    if (!Array.isArray(accepted) || !accepted.includes(identity)) return false
+    if (!Array.isArray(accepted) || !accepted.includes(identity)) return null
+    if (runtime?.beforeRead && runtime.beforeRead(identity) === false) return null
     const current = await registry.read()
-    if (current.kind !== 'ok') return false
+    if (current.kind !== 'ok') return null
     const entry = current.servers[identity]
-    return Boolean(entry && entry.generation === generation)
+    if (!entry || entry.generation !== generation || !mcpIncarnationMatches(snapshot, identity, entry)) return null
+    if (runtime?.afterRead && runtime.afterRead(identity) === false) return null
+    if (runtime?.permit) return runtime.permit(identity, { generation, incarnation: entry.incarnation ?? null })
+    return { identity, generation, incarnation: entry.incarnation ?? null, operationId: null }
+  }
+  async function admit(agent, identity, generation) {
+    return (await permit(agent, identity, generation)) !== null
   }
 
-  /**
-   * Instruction-section filtering (8.4): is the server in the session's
-   * accepted set? At a subagent's creation the inherited capture is what the
-   * child gets — the parent's accepted set VERBATIM at that moment — so when
-   * the child's own snapshot is not visible yet (the creation-time
-   * schema-hiding listener races the capture listener), the parent's
-   * snapshot stands in. Call admission (admit) never uses this fallback: a
-   * snapshot-less child is refused, never granted the parent's set.
-   */
   function enabledFor(agent, identity) {
-    const sessionId = agent?.session?.id
-    if (typeof sessionId !== 'string' || sessionId.length === 0) return false
-    let snapshot = lifecycle.snapshotFor(sessionId)
-    if (snapshot?.state !== 'ready') {
-      const parentId = agent?.session?.header?.parentSession
-      if (typeof parentId === 'string' && parentId.length > 0) snapshot = lifecycle.snapshotFor(parentId)
+    if (runtime?.enabledFor && runtime.enabledFor(identity) === false) return false
+    const snapshot = acceptedSnapshot(lifecycle, agent, { parentFallback: true })
+    if (!snapshot || !Array.isArray(snapshot.mcpServers) || !snapshot.mcpServers.includes(identity)) return false
+    if (typeof registrationFor !== 'function') {
+      // Pure legacy tests without a runtime registry still get mapping-shape
+      // enforcement; production always supplies registrationFor below.
+      const mapping = snapshot.mcpIncarnations
+      return !(mapping && typeof mapping === 'object' && !Array.isArray(mapping) && !Object.hasOwn(mapping, identity))
     }
-    if (snapshot?.state !== 'ready') return false
-    const accepted = snapshot.mcpServers
-    return Array.isArray(accepted) && accepted.includes(identity)
+    return mcpIncarnationMatches(snapshot, identity, registrationFor(identity))
   }
 
-  return { admit, enabledFor }
+  return { admit, permit, enabledFor, assertPermit: value => runtime?.assertPermit ? runtime.assertPermit(value) : Boolean(value) }
 }