weir-harness 2.0.0 → 2.1.1

package/skills/mcp-server-setup/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: mcp-server-setup
+description: "Install, add, or configure a new MCP server with credential-safe preview, exact Host confirmation, strict discovery, and separate session Apply. Do not use for merely calling or discussing an existing MCP tool."
+metadata:
+  short-description: Credential-safe MCP server installation
+---
+
+# MCP Server Setup
+
+Use this workflow for genuine requests to install, add, or configure a new MCP
+server. It is not a tool-repair or general MCP discussion workflow.
+
+## Boundaries
+
+- Weir supports `stdio` and `streamable-http` only. Do not propose legacy SSE,
+  OAuth flows, a marketplace, or adoption of an unmanaged server.
+- Never ask the user to paste a token, password, private endpoint, or other
+  secret into chat. Use an existing DSH credential reference such as
+  `{ "ref": "GITHUB_TOKEN" }`. A reference may include a non-secret `prefix`.
+- Every environment or HTTP-header value on this tool surface is a credential
+  reference. Mark each sensitive stdio argument with a reference object instead
+  of placing its value in a plain argument string.
+- Any URL containing userinfo, a query, or a fragment is sensitive. Supply the
+  whole URL through a credential reference; do not put it in the plan.
+- Installation never selects the server, changes a default, or Applies a
+  capability set. Do not imply that a mounted server is already authorized.
+
+## 1. Establish the plan
+
+Read the server author's current documentation when it is available. Identify
+the transport, executable or endpoint, non-secret arguments, required credential
+references, working directory, and relevant timeout/reconnect options. Keep the
+plan within the `mcp_install` schema. Unknown fields and cross-transport fields
+are rejected.
+
+For stdio, `command` and non-secret `args` describe the process. For
+`streamable-http`, use `url` and credential-referenced `headers`; stdio fields
+are forbidden. `failOnStartupError` is not configurable: initial mounting is
+always strict. Discovering zero tools is still a valid result.
+
+Example stdio plan shape (references, not secrets):
+
+```json
+{
+  "action": "preview",
+  "plan": {
+    "identity": "github",
+    "label": "GitHub",
+    "transport": "stdio",
+    "command": "npx",
+    "args": ["-y", "@example/mcp-server", { "ref": "MCP_CLI_TOKEN" }],
+    "env": { "GITHUB_TOKEN": { "ref": "GITHUB_TOKEN" } }
+  }
+}
+```
+
+Example HTTP plan shape:
+
+```json
+{
+  "action": "preview",
+  "plan": {
+    "identity": "private-docs",
+    "transport": "streamable-http",
+    "url": { "ref": "PRIVATE_MCP_URL" },
+    "headers": {
+      "Authorization": { "ref": "PRIVATE_MCP_TOKEN", "prefix": "Bearer " }
+    }
+  }
+}
+```
+
+## 2. Preview before installation
+
+Call `mcp_install` with `action: "preview"` and the plan. Check the bounded
+redacted plan, digest, target conflicts, namespace conflicts, capabilities, and
+validation outcome. Preview does not start a process, contact the server, write
+credentials or configuration, or change selection. Correct the plan and preview
+again when necessary.
+
+`mcp_install` is single-server and fresh-identity only. Do not use it to edit,
+restart, remove, batch-import, or set a default. Use the management UI or the
+shared `/capabilities` MCP commands for those operations.
+
+## 3. Let the Host obtain approval
+
+After a clean preview, call `mcp_install` with `action: "install"` and the same
+plan. The Host displays the exact redacted plan, its digest, and process or
+network effects. Only the user can approve that card. There is no `confirmed`
+argument; chat text, custom answers, and extra selections are not approval.
+
+Cancellation, close, timeout, missing confirmation support, delegated callers,
+ownership changes, plan changes, registry changes, and namespace changes stop
+before probe or write. Report the outcome and request a fresh preview when
+required; never fabricate approval or retry an unchanged conflict in a loop.
+
+## 4. Interpret the actual outcome
+
+An approved install probes before registration. A failed probe does not create
+a registry entry. A mounted result reports the real identity, incarnation,
+generation, and bounded discovery summary.
+
+- `mounted`: registration and strict mount succeeded.
+- `saved-degraded`: configuration was saved (`saved: true`) but strict mounting
+  failed. This is not installation success; offer Edit, Test, or Restart.
+- `owner-changed` or `indeterminate`: inspect actual registry/mount facts. Never
+  claim rollback or zero effects.
+- `cleanup-failed` / `cleanup-unknown`: follow the recovery action; do not start
+  an immediate same-name replacement.
+
+Do not run an arbitrary discovered tool as an installation test. Discovery and
+the reported mount outcome are the evidence.
+
+## 5. Keep authorization separate
+
+After a mounted result, direct the user to the separate **Select for this
+session** action and explicit **Apply**. Installation and the optional
+new-session default are independent of the current draft and accepted sets.
+Editing or restarting preserves the registration incarnation; removing and
+re-adding the same identity creates a new one and requires reauthorization.
+
+Credential rotation takes effect on the next explicit probe or restart, not as
+a claimed live reconnect. Local credential storage avoids registry/profile and
+transcript disclosure; it is not an isolation boundary against a same-UID agent.

package/src/capabilities/apply-engine.js

@@ -203,7 +203,7 @@ export function digestApplyRequest(normalized) {
  */
 export function createApplyEngine(options) {
   const {
-    store, locateSession, inventory, provider,
+    store, locateSession, inventory, provider, mcpRegistry,
     fence = createAdmissionFence(),
     drain = createDrainCoordinator(),
     conditions = () => [],
@@ -365,6 +365,19 @@ export function createApplyEngine(options) {
     const missing = normalized.skills.filter(key => (byKey.get(key) ?? []).length !== 1)
     if (missing.length) return { status: 'rejected', reason: 'selected-identity-missing', step: 2, missing }
 
+    let mcpIncarnations
+    if (mcpRegistry) {
+      let current
+      try { current = await mcpRegistry.read() } catch (error) {
+        return { status: 'rejected', reason: `mcp-registry-unavailable:${message(error)}`, step: 2 }
+      }
+      if (current.kind !== 'ok' && current.kind !== 'absent') return { status: 'rejected', reason: `mcp-registry-unavailable:${current.kind}`, step: 2 }
+      const servers = current.kind === 'ok' ? current.servers : {}
+      const missingMcp = normalized.mcpServers.filter(identity => !servers[identity])
+      if (missingMcp.length) return { status: 'rejected', reason: 'unregistered-mcp', step: 2, missing: missingMcp }
+      mcpIncarnations = Object.fromEntries(normalized.mcpServers.map(identity => [identity, servers[identity].incarnation ?? null]))
+    }
+
     // Step 3: prepare a pure snapshot, filtered view and verified content
     // handles. Nothing is published, installed or notified here.
     let prepared
@@ -388,7 +401,7 @@ export function createApplyEngine(options) {
 
     const previousSets = record.kind === 'ok' ? safeSets(record.payload) : { skills: [], mcpServers: [] }
     const removedServers = previousSets.mcpServers.filter(server => !normalized.mcpServers.includes(server))
-    const payload = { skills: prepared.identities, mcpServers: normalized.mcpServers, origin: 'apply' }
+    const payload = { skills: prepared.identities, mcpServers: normalized.mcpServers, ...(mcpIncarnations ? { mcpIncarnations } : {}), origin: 'apply' }
     const requestDigest = digestApplyRequest(normalized)
 
     // Step 4: enter the admission fence, close removed-server gates, start draining.
@@ -496,7 +509,7 @@ export function createApplyEngine(options) {
         status: 'applied',
         revision: result.revision,
         receipt: result.receipt,
-        effective: { skills: structuredClone(prepared.identities), mcpServers: [...normalized.mcpServers] },
+        effective: { skills: structuredClone(prepared.identities), mcpServers: [...normalized.mcpServers], ...(mcpIncarnations ? { mcpIncarnations } : {}) },
         unresolvedWarnings: normalized.unresolved.map(entry => ({ ...entry })),
         ...(draining.length ? { draining } : {}),
         ...(warnings.length ? { warnings } : {}),
@@ -564,6 +577,7 @@ export function createApplyEngine(options) {
     return {
       skills: Array.isArray(value.skills) ? value.skills : [],
       mcpServers: Array.isArray(value.mcpServers) ? /** @type {string[]} */ (value.mcpServers) : [],
+      ...(value.mcpIncarnations && typeof value.mcpIncarnations === 'object' && !Array.isArray(value.mcpIncarnations) ? { mcpIncarnations: structuredClone(value.mcpIncarnations) } : {}),
     }
   }
 
@@ -613,7 +627,7 @@ export function createApplyEngine(options) {
     // just-committed record — reported, never fatal.
     try {
       const sets = safeSets(payload)
-      publishSnapshot?.(sessionId, { revision, skills: structuredClone(sets.skills), mcpServers: [...sets.mcpServers] })
+      publishSnapshot?.(sessionId, { revision, skills: structuredClone(sets.skills), mcpServers: [...sets.mcpServers], ...(sets.mcpIncarnations ? { mcpIncarnations: structuredClone(sets.mcpIncarnations) } : {}) })
     } catch (error) {
       degraded('snapshot-publication-degraded', error)
     }

package/src/capabilities/capability-remote.js

@@ -21,6 +21,7 @@ import { openCapabilityStore } from './store/store.js'
 import { buildReceiptPayload, buildListPayload, buildConditionsPayload, buildPresetsPayload, buildDefaultGetPayload } from './read-payloads.js'
 import { PRESET_SELECTED_EVENT } from './preset-invalidation.js'
 import { createAudit } from '../shared/audit.js'
+import { mcpDiagnostic, sanitizeMcpPayload } from './mcp-diagnostics.js'
 
 /** The host-root service key the typert gateway resolves (S27: ctx.get from the host root). */
 export const CAPABILITY_READ_SERVICE_KEY = 'weirCapabilityRead'
@@ -71,15 +72,74 @@ export function capabilityReadBridge(presetId) {
   return feeds?.size === 1 ? [...feeds][0].faces : null
 }
 
-function soleFeed(presetId) {
+/**
+ * The isolated `weirMcpManager` owned by the exact preset revision a live
+ * session's Agent retains, or undefined when that cannot be proven. The
+ * registry's `serviceFor(agent, name)` reads `agent.ctx`'s retained mount, so
+ * an old session keeps resolving its old revision after a config change or a
+ * bundle toggle remounted the preset next to it. Everything is read through
+ * caller-supplied ctx getters (never a static runtime import).
+ * @param {string} sessionId
+ * @param {{ agents?: () => any, agentPresets?: () => any }} [runtime]
+ */
+function sessionManager(sessionId, runtime) {
+  try {
+    const agent = runtime?.agents?.()?.get?.(sessionId)
+    // A cold or unknown session has no live Agent and hence no retained mount.
+    if (!agent?.ctx || agent.id !== sessionId) return undefined
+    const registry = runtime?.agentPresets?.()
+    if (typeof registry?.serviceFor !== 'function') return undefined
+    return registry.serviceFor(agent, 'weirMcpManager') ?? undefined
+  } catch { return undefined }
+}
+
+/**
+ * Resolve the feed owning ONE session's read/mutation.
+ *
+ * A single feed is the fast path (no agent lookup). Several feeds for one
+ * preset are legitimate — two retained revisions of the same preset stay
+ * mounted while old sessions still use the old one — so the owner is the
+ * unique feed whose `faces.mcpManager()` IS the manager the session's own
+ * revision provides. Every other outcome fails closed with `owner-ambiguous`:
+ * no runtime seam, a cold/unknown agent, a revision without a manager, no
+ * matching feed, or several feeds sharing that manager (overlapping
+ * generations of one revision). Never newest-wins.
+ * @param {string} presetId
+ * @param {string} sessionId
+ * @param {{ agents?: () => any, agentPresets?: () => any }} [runtime]
+ */
+function sessionFeed(presetId, sessionId, runtime) {
   const feeds = bridgeFeeds.get(presetId)
   if (!feeds?.size) throw new CapabilityReadError('bridge-absent', `capability read: no feed for preset ${presetId}`)
-  if (feeds.size !== 1) throw new CapabilityReadError('owner-ambiguous', `capability read: overlapping feeds for preset ${presetId}`)
-  return [...feeds][0]
+  if (feeds.size === 1) return [...feeds][0]
+  const ambiguous = reason => new CapabilityReadError('owner-ambiguous', `capability read: overlapping feeds for preset ${presetId}: ${reason}`)
+  const manager = sessionManager(sessionId, runtime)
+  if (manager === undefined) throw ambiguous(`session ${JSON.stringify(sessionId)} has no live agent with a preset-owned MCP manager`)
+  const matches = [...feeds].filter(feed => {
+    try { return feed.faces?.mcpManager?.() === manager } catch { return false }
+  })
+  if (matches.length === 0) throw ambiguous(`no feed belongs to the revision of session ${JSON.stringify(sessionId)}`)
+  if (matches.length > 1) throw ambiguous(`${matches.length} feeds share the manager of session ${JSON.stringify(sessionId)}`)
+  return matches[0]
+}
+
+/**
+ * Exact feed token used by mutation ownership snapshots and their rechecks.
+ * @param {string} presetId
+ * @param {string} sessionId
+ * @param {{ agents?: () => any, agentPresets?: () => any }} [runtime] ctx getters for the host `agents` and `agentPresets` services
+ */
+export function capabilityReadFeed(presetId, sessionId, runtime = undefined) { return sessionFeed(presetId, sessionId, runtime) }
+
+/** @param {{ bridge?: Function, agents?: () => any, agentPresets?: () => any }} dependencies */
+function feedResolver(dependencies) {
+  if (dependencies.bridge) return dependencies.bridge
+  const runtime = { agents: dependencies.agents, agentPresets: dependencies.agentPresets }
+  return (presetId, sessionId) => sessionFeed(presetId, sessionId, runtime)
 }
 
 /** Extract the current projected owner and its last committed selection generation. */
-function ownership(observation, sessionId) {
+export function capabilityOwnership(observation, sessionId) {
   if (!observation || observation.header?.id !== sessionId) {
     throw new CapabilityReadError('unknown-session', `capability read: unknown session ${JSON.stringify(sessionId)}`)
   }
@@ -95,7 +155,7 @@ function ownership(observation, sessionId) {
 
 /** Create the host read service. Observations are caller-owned leases, always disposed. */
 export function createCapabilityReadService(dependencies = {}) {
-  const bridgeFor = dependencies.bridge ?? soleFeed
+  const bridgeFor = feedResolver(dependencies)
   const storeFor = dependencies.store ?? (profileContext => openCapabilityStore({ profileContext }))
   const ensure = dependencies.ensureRegistered ?? (() => true)
   const onDegraded = dependencies.onDegraded ?? (() => {})
@@ -105,7 +165,7 @@ export function createCapabilityReadService(dependencies = {}) {
     try {
       lease = await observeSession(sessionId)
       if (!lease || typeof lease[Symbol.dispose] !== 'function') throw new CapabilityReadError('owner-unavailable', 'capability read: session observation is unavailable')
-      return { lease, owner: ownership(lease, sessionId) }
+      return { lease, owner: capabilityOwnership(lease, sessionId) }
     } catch (cause) {
       lease?.[Symbol.dispose]?.()
       if (cause instanceof CapabilityReadError) throw cause
@@ -117,7 +177,7 @@ export function createCapabilityReadService(dependencies = {}) {
     const first = await observe(sessionId)
     try {
       const { presetId, cwd, selectionSeq } = first.owner
-      const feed = bridgeFor(presetId)
+      const feed = bridgeFor(presetId, sessionId)
       if (!feed) throw new CapabilityReadError('bridge-absent', `capability read: no feed for preset ${presetId}`)
       const faces = feed.faces ?? feed
       const options = { cwd, scope: { session: { id: sessionId } } }
@@ -149,7 +209,7 @@ export function createCapabilityReadService(dependencies = {}) {
       }
       const second = await observe(sessionId)
       try {
-        if (second.owner.presetId !== presetId || second.owner.cwd !== cwd || second.owner.selectionSeq !== selectionSeq || bridgeFor(presetId) !== feed) {
+        if (second.owner.presetId !== presetId || second.owner.cwd !== cwd || second.owner.selectionSeq !== selectionSeq || bridgeFor(presetId, sessionId) !== feed) {
           throw new CapabilityReadError('owner-changed', 'capability read: owner or feed changed during read')
         }
         return payload
@@ -185,27 +245,143 @@ export function createCapabilityReadService(dependencies = {}) {
   }
 }
 
+export const CAPABILITY_MUTATION_SERVICE_KEY = 'weirCapabilityMutation'
+export const CAPABILITY_MUTATION_NAMESPACE = 'weirCapabilityMutations'
+export const CAPABILITY_MUTATION_METHODS = ['mutate', 'batch']
+
+export function sameMutationOwner(first, second) {
+  const profile = value => value ? `${value.home ?? ''}\0${value.name ?? ''}` : ''
+  return first.owner.presetId === second.owner.presetId
+    && first.owner.cwd === second.owner.cwd
+    && first.feed === second.feed
+    && profile(first.profile) === profile(second.profile)
+}
+
+/** Session-preset/profile/feed ownership for mutations; selectionSeq is not compared. */
+export function createCapabilityMutationService(dependencies = {}) {
+  const bridgeFor = feedResolver(dependencies)
+  const ensure = dependencies.ensureRegistered ?? (() => true)
+  const observeSession = dependencies.observeSession ?? (sessionId => dependencies.sessionQuery?.()?.observeSession(sessionId))
+  const observe = async sessionId => {
+    let lease
+    try {
+      lease = await observeSession(sessionId)
+      if (!lease || typeof lease[Symbol.dispose] !== 'function') throw new CapabilityReadError('owner-unavailable', 'capability mutation: session observation unavailable')
+      const owner = capabilityOwnership(lease, sessionId)
+      const feed = bridgeFor(owner.presetId, sessionId)
+      if (!feed) throw new CapabilityReadError('bridge-absent', `capability mutation: no feed for preset ${owner.presetId}`)
+      const faces = feed.faces ?? feed
+      return { lease, owner, feed, faces, profile: faces.profileContext?.() }
+    } catch (cause) {
+      lease?.[Symbol.dispose]?.()
+      if (cause instanceof CapabilityReadError) throw cause
+      throw new CapabilityReadError('unknown-session', `capability mutation: cannot observe session ${JSON.stringify(sessionId)}`, { cause })
+    }
+  }
+  async function mutate(sessionId, request, batch = false) {
+    if (!ensure()) throw new CapabilityReadError('channel-unavailable', 'capability mutation channel is not registered')
+    const first = await observe(sessionId)
+    try {
+      const assertOwner = async () => {
+        const current = await observe(sessionId)
+        try {
+          if (!sameMutationOwner(first, current)) throw new CapabilityReadError('owner-changed', 'capability mutation: session preset/profile/feed owner changed')
+        } finally { current.lease[Symbol.dispose]() }
+      }
+      if (typeof first.faces.mcpOperations !== 'function') throw new CapabilityReadError('bridge-absent', 'capability mutation: owning preset has no MCP operations')
+      const operations = first.faces.mcpOperations({ id: sessionId, header: { cwd: first.owner.cwd } }, { assertOwner })
+      let result
+      try {
+        result = batch ? await operations.executeBatch(request) : request?.action === 'preview' ? await operations.preview(request) : await operations.execute(request)
+      } catch (cause) {
+        result = { status: cause?.code === 'owner-changed' ? 'owner-changed' : 'validation-failed', saved: false, error: mcpDiagnostic(cause, { code: cause?.code ?? 'validation-failed' }) }
+      }
+      // A response may be stale by the time it is serialized. Never claim a
+      // rollback; return the operation's actual saved facts with owner-changed.
+      try {
+        await assertOwner()
+      } catch (cause) {
+        if (result.status !== 'owner-changed') {
+          return sanitizeMcpPayload({
+            ...result,
+            status: 'owner-changed',
+            ownerChanged: true,
+            actual: {
+              status: result.status,
+              saved: result.saved === true,
+              registryRevision: result.registryRevision ?? null,
+              generation: result.generation ?? null,
+              incarnation: result.incarnation ?? null,
+            },
+            error: mcpDiagnostic(cause, { code: 'owner-changed' }),
+          })
+        }
+      }
+      return sanitizeMcpPayload(result)
+    } finally {
+      first.lease[Symbol.dispose]()
+    }
+  }
+  return {
+    mutate: (sessionId, request) => mutate(sessionId, request, false),
+    batch: (sessionId, request) => mutate(sessionId, request, true),
+  }
+}
+
+/**
+ * Every endpoint the gateway resolves through this package's ONE host-face
+ * contribution, in contribution order. A live read says nothing about write
+ * availability, so liveness is always checked across this whole set.
+ */
+export const CAPABILITY_ENDPOINTS = [
+  ...CAPABILITY_READ_METHODS.map(method => `${CAPABILITY_READ_NAMESPACE}/${method}`),
+  ...CAPABILITY_MUTATION_METHODS.map(method => `${CAPABILITY_MUTATION_NAMESPACE}/${method}`),
+]
+
 /**
  * The hand-written typert contribution (S27: empty schemas/model, src-json
  * codecs, no zod, no generated artifacts). Parameters and results are plain
  * JSON; the envelope validates the argument name only.
+ *
+ * ALL five read and two mutation invocations live in ONE contribution, because
+ * the registry keys exactly one record per package+face and rejects any second
+ * registration while that record is live: two separate `weir-harness` host-face
+ * contributions could never overlap generations, and the face the mutation half
+ * used to declare (`host-mutations`) is not a face the registry accepts at all —
+ * register() threw and apply() swallowed it into a warning, so the write channel
+ * was silently dead. One atomic batch also means recovery restores every
+ * endpoint or none.
  */
-export function capabilityReadContribution() {
+export function capabilityContribution() {
   return {
-    // The registry's validatePackage requires both (missing = silently dead registration): it validates the package name and keys the package record by face.
+    // The registry's validatePackage requires both (missing = silently dead registration): it validates the package name, rejects any face except host/client, and keys the package record by face.
     package: 'weir-harness',
     face: 'host',
     schemas: [],
     model: { services: [], events: [], objects: [] },
-    invocations: CAPABILITY_READ_METHODS.map(method => ({
-      id: `weir-harness.${CAPABILITY_READ_NAMESPACE}.${method}`,
-      service: CAPABILITY_READ_SERVICE_KEY,
-      namespace: CAPABILITY_READ_NAMESPACE,
-      method,
-      invocation: { kind: 'direct' },
-      parameters: [{ name: 'sessionId', wire: 'sessionId', source: 'json', codec: { mode: 'src-json' } }],
-      result: { mode: 'src-json' },
-    })),
+    invocations: [
+      ...CAPABILITY_READ_METHODS.map(method => ({
+        id: `weir-harness.${CAPABILITY_READ_NAMESPACE}.${method}`,
+        service: CAPABILITY_READ_SERVICE_KEY,
+        namespace: CAPABILITY_READ_NAMESPACE,
+        method,
+        invocation: { kind: 'direct' },
+        parameters: [{ name: 'sessionId', wire: 'sessionId', source: 'json', codec: { mode: 'src-json' } }],
+        result: { mode: 'src-json' },
+      })),
+      ...CAPABILITY_MUTATION_METHODS.map(method => ({
+        id: `weir-harness.${CAPABILITY_MUTATION_NAMESPACE}.${method}`,
+        service: CAPABILITY_MUTATION_SERVICE_KEY,
+        namespace: CAPABILITY_MUTATION_NAMESPACE,
+        method,
+        invocation: { kind: 'direct' },
+        parameters: [
+          { name: 'sessionId', wire: 'sessionId', source: 'json', codec: { mode: 'src-json' } },
+          { name: 'request', wire: 'request', source: 'json', codec: { mode: 'src-json' } },
+        ],
+        result: { mode: 'src-json' },
+      })),
+    ],
   }
 }
 
@@ -222,6 +398,20 @@ export function capabilityReadContribution() {
  * gateway dispatch resolves through it as well, so the loader must order this
  * row after the typert provider — including a composition where a user-layer
  * patch injects typert after the bundle rows (S27).
+ *
+ * Registration lifecycle (S27.5, gateway/definition-unavailable): a fiber
+ * reload runs apply() again while the previous incarnation's effects are still
+ * unwinding, so BOTH the service provision and the contribution registration can
+ * lose that race, and the old incarnation then withdraws what the new one
+ * skipped. Because the gateway refuses a withdrawn strict definition before it
+ * ever reaches a service method (hasSeen + no live definition), the recovery
+ * must live in this plugin's own fiber: it subscribes to `typert.local` changes
+ * and re-attempts provision+registration on a coalesced microtask while the
+ * endpoints are incomplete. Every one of those facts is per-fiber state: a
+ * pending retry, the disposal latch and the warning latch belong to THIS
+ * generation, so an old generation can never consume the survivor's retry, and
+ * a disposed fiber cannot resurrect the endpoints (Cordis rejects its effect
+ * creation with INACTIVE_EFFECT — the final barrier, never a retry loop).
  */
 export function apply(ctx) {
   const warn = text => ctx.logger?.warn?.(text)
@@ -236,46 +426,107 @@ export function apply(ctx) {
     warn('weir capability remote: typert service is unavailable in this composition; capability reads stay unavailable on the client')
     return
   }
-  // Idempotent, self-healing registration. The registry rejects a duplicate
-  // package contribution, so a re-mount that races the previous fiber's
-  // disposal must not treat "already registered" as fatal when the endpoints
-  // are actually live — and a later withdrawal (that previous fiber finally
-  // disposing) must be repaired on the next read rather than left dead.
-  const endpointLive = () => {
-    try { return Boolean(typert.local?.get?.(`${CAPABILITY_READ_NAMESPACE}/receipt`)) } catch { return false }
+  // Per-fiber lifecycle state. NEVER module-global: the previous incarnation's
+  // listener and this one can both observe the same withdrawal.
+  let disposed = false
+  let retryQueued = false
+  let registrationWarned = false
+  const endpointLive = endpoint => {
+    try { return Boolean(typert.local?.get?.(endpoint)) } catch { return false }
   }
-  const ensureRegistered = () => {
-    if (endpointLive()) return true
+  const endpointsComplete = () => CAPABILITY_ENDPOINTS.every(endpointLive)
+  let readService
+  let mutationService
+  // Provide one service unless another incarnation still holds the host-root
+  // key. A host-root provide lives on the ROOT fiber (S27: the gateway resolves
+  // ctx.get from the host root), so the first incarnation's receiver survives
+  // every reload; replacing it is neither possible nor needed. A lost race is
+  // not fatal — the retry below keeps every endpoint self-healing.
+  const ensureService = (key, service) => {
     try {
-      typert.register(capabilityReadContribution())
+      const current = typeof ctx.get === 'function' ? ctx.get(key) : undefined
+      if (current === service) return true
+      if (current !== undefined) return false
+      ctx.root.reflect.provide(key, service)
       return true
+    } catch { return false }
+  }
+  const ensureServices = () => {
+    const read = ensureService(CAPABILITY_READ_SERVICE_KEY, readService)
+    const mutation = ensureService(CAPABILITY_MUTATION_SERVICE_KEY, mutationService)
+    return read && mutation
+  }
+  // Exactly ONE register attempt per call: the registry rejects the whole batch
+  // or commits all of it, so looping could only repeat the same rejection.
+  const ensureContribution = () => {
+    if (endpointsComplete()) return true
+    try {
+      typert.register(capabilityContribution())
     } catch (cause) {
-      // Duplicate-package race: a previous generation's registration still
-      // serves the endpoints — that is success, not a warning.
-      if (endpointLive()) return true
-      warn(`weir capability remote: registration failed (${cause instanceof Error ? cause.message : String(cause)}); capability reads stay unavailable on the client`)
-      return false
+      if (!endpointsComplete()) {
+        // A disposed fiber's rejection is terminal (the survivor owns the retry).
+        if (cause?.code === 'INACTIVE_EFFECT') {
+          disposed = true
+          return false
+        }
+        if (!registrationWarned) {
+          registrationWarned = true
+          warn(`weir capability remote: registration failed (${cause instanceof Error ? cause.message : String(cause)}); capability endpoints stay unavailable on the client`)
+        }
+        return false
+      }
     }
+    return endpointsComplete()
   }
+  const ensureRegistered = () => ensureContribution()
+  // Coalesce a burst of registry changes into one microtask. Waiting a turn also
+  // lets the disposing incarnation finish synchronously releasing its service
+  // keys, which a synchronous retry inside the change callback would still see.
+  const queueRetry = () => {
+    if (disposed || retryQueued) return
+    retryQueued = true
+    queueMicrotask(() => {
+      retryQueued = false
+      if (disposed || endpointsComplete()) return
+      ensureServices()
+      ensureContribution()
+    })
+  }
+  // Latch disposal as early as the fiber allows, before a queued retry can run
+  // against a fiber Cordis has already detached. A fiber that is already gone
+  // needs no latch: its next register() is rejected with INACTIVE_EFFECT.
+  try {
+    if (typeof ctx.effect === 'function') ctx.effect(() => () => { disposed = true })
+  } catch { /* detached fiber: the effect rejection is the barrier */ }
   try {
     const audit = createAudit(ctx)
     const onDegraded = facts => {
       warn(`weir capability read degraded: method=${facts.method} session=${facts.sessionId} preset=${facts.presetId} header=${facts.headerPreset} source=${facts.source} warnings=${facts.warnings.join(';')} provider=${facts.providerReason ?? '-'}: ${facts.providerError ?? '-'}`)
       audit({ id: facts.sessionId, header: { cwd: facts.cwd } }, 'capability-read', facts)
     }
-    const service = createCapabilityReadService({ ensureRegistered, sessionQuery: () => ctx.get?.('sessionQuery'), onDegraded })
-    // The exact frozen binding validateBinding requires (S27): { service,
-    // serviceKey, namespace } — built by hand, no protocol import.
-    service.typertRemote = Object.freeze({
-      service,
-      serviceKey: CAPABILITY_READ_SERVICE_KEY,
-      namespace: CAPABILITY_READ_NAMESPACE,
-    })
-    Object.freeze(service)
-    ctx.root.reflect.provide(CAPABILITY_READ_SERVICE_KEY, service)
-    ensureRegistered()
+    // Per-session owner resolution reads the host agents registry and the
+    // preset registry lazily (both host-root services; no mount-time inject).
+    const runtime = { agents: () => ctx.get?.('agents'), agentPresets: () => ctx.get?.('agentPresets') }
+    readService = createCapabilityReadService({ ensureRegistered, sessionQuery: () => ctx.get?.('sessionQuery'), onDegraded, ...runtime })
+    readService.typertRemote = Object.freeze({ service: readService, serviceKey: CAPABILITY_READ_SERVICE_KEY, namespace: CAPABILITY_READ_NAMESPACE })
+    Object.freeze(readService)
+    mutationService = createCapabilityMutationService({ ensureRegistered, sessionQuery: () => ctx.get?.('sessionQuery'), ...runtime })
+    mutationService.typertRemote = Object.freeze({ service: mutationService, serviceKey: CAPABILITY_MUTATION_SERVICE_KEY, namespace: CAPABILITY_MUTATION_NAMESPACE })
+    Object.freeze(mutationService)
   } catch (cause) {
     warn(`weir capability remote: setup failed (${cause instanceof Error ? cause.message : String(cause)}); capability reads stay unavailable on the client`)
+    return
+  }
+  // Provision BEFORE registering: the gateway resolves the service key of a
+  // live definition, so an endpoint must never outlive its receiver.
+  ensureServices()
+  ensureContribution()
+  // Independent per-fiber subscription: hosts without it keep the older
+  // self-heal-on-call behaviour (each service call still checks the endpoints).
+  try {
+    typert.local?.subscribe?.(() => { if (!endpointsComplete()) queueRetry() })
+  } catch (cause) {
+    warn(`weir capability remote: registration watch failed (${cause instanceof Error ? cause.message : String(cause)}); the capability channel only self-heals on the next call`)
   }
 }
 

package/src/capabilities/initial-selection.js

@@ -154,7 +154,7 @@ export function resolveSkillNamesForSave(names, candidates, appliedSkills) {
   return { identities, missing, ambiguous }
 }
 
-export function resolveInitialSelection({ defaultsRecord, builtinIdentities = [], enabledMcpIdentities = [] }) {
+export function resolveInitialSelection({ defaultsRecord, builtinIdentities = [], enabledMcpIdentities = [], mcpIncarnations }) {
   // A cleared marker is an explicit removal (9.4): it behaves as ABSENT —
   // clearing is never an explicit empty set, which stays a savable choice.
   const cleared = defaultsRecord && defaultsRecord.kind === 'ok'
@@ -169,13 +169,14 @@ export function resolveInitialSelection({ defaultsRecord, builtinIdentities = []
       selection: {
         skills: Array.isArray(payload.skills) ? structuredClone(payload.skills) : [],
         mcpServers: Array.isArray(payload.mcpServers) ? /** @type {string[]} */ (payload.mcpServers).slice() : [],
+        ...((mcpIncarnations ?? payload.mcpIncarnations) ? { mcpIncarnations: structuredClone(mcpIncarnations ?? payload.mcpIncarnations) } : {}),
       },
       missing: Array.isArray(payload.unresolvedRefs) ? payload.unresolvedRefs.slice() : [],
     }
   }
   return {
     source: 'builtin-baseline',
-    selection: { skills: builtinIdentities.slice(), mcpServers: enabledMcpIdentities.slice() },
+    selection: { skills: builtinIdentities.slice(), mcpServers: enabledMcpIdentities.slice(), ...(mcpIncarnations ? { mcpIncarnations: structuredClone(mcpIncarnations) } : {}) },
     missing: [],
   }
 }