weir-harness 1.2.3 → 2.1.0

package/src/capabilities/lifecycle-snapshot.js

@@ -9,13 +9,15 @@
 // never yields: no promise chains, no async helpers, only blocking
 // synchronous file I/O where durability is required.
 //
-// 6.1 — in-memory snapshot: accepted selections are loaded into memory at
-// plugin apply (lifecycle-preload.js) and after every Apply acceptance (the
-// apply-engine publishSnapshot hook, invoked inside the same non-async
-// segment as the internal snapshot swap). The listener reads the memory
-// snapshot synchronously (measured ≈0.2 ms in G4b); on a memory miss it
-// falls back to ONE blocking synchronous read of the session record (never
-// the host storageDomain — a promise interface, unusable here, CITED).
+// 6.1 — in-memory snapshot: the session's EFFECTIVE capability set is loaded
+// into memory at plugin apply (lifecycle-preload.js) and after every Apply
+// acceptance (the apply-engine publishSnapshot hook, invoked inside the same
+// non-async segment as the internal snapshot swap). The listener reads the
+// memory snapshot synchronously (measured ≈0.2 ms in G4b); on a memory miss it
+// falls back to blocking synchronous reads of the session records — the
+// accepted selection FIRST, then the durable inherited snapshot when no
+// accepted record exists (a fork of a fork, a resumed incarnation), never the
+// host storageDomain (a promise interface, unusable here, CITED).
 //
 // 6.2 — synchronous durable capture: a subagent's inherited snapshot is
 // written inside the listener through the capability store's SYNC commit path
@@ -39,19 +41,29 @@
 //   decoded does NOT throw — the session is created/resumed as usual and
 //   the memory snapshot becomes BLOCKED (empty Skill view, all managed MCP
 //   calls refused, recovery entry visible). Never a full-discovery
-//   fallback; the original file is never rewritten.
+//   fallback; the original file is never rewritten. An inherited record is
+//   consulted ONLY when no accepted record exists, and an existing record
+//   that cannot be decoded blocks just as hard — a corrupt higher-priority
+//   record is never skipped in favour of a lower-priority one or of the
+//   initial baseline.
 // - resume/fork incarnation (depth 0 yet a parentSession header): the named
-//   parent's accepted snapshot is captured best-effort under the SAME root
-//   rule — a failed capture never throws and never rejects the session; the
-//   session runs BLOCKED like an unreadable root record, with the manager
-//   naming an explicit Apply as the recovery gesture.
-// - subagent (one-shot / background / supervised member / escalation /
-//   fork child): a parent snapshot that cannot be read, or a capture that
-//   cannot be written, makes the listener THROW. The host dispatches
-//   agent/created serially and a listener failure rejects the creation, so
-//   throwing is the INTENTIONAL bail that refuses the subagent while the
-//   parent session continues and learns the reason through the delegation
-//   result. Never an unrestricted pass.
+//   parent's EFFECTIVE snapshot (accepted, inherited, or the already-resolved
+//   initial one) is captured best-effort under the SAME root rule — a failed
+//   capture never throws and never rejects the session; the session runs
+//   BLOCKED like an unreadable root record, with the manager naming an
+//   explicit Apply as the recovery gesture. A parent with NO effective
+//   snapshot at all (proven absent on supported storage) is not an empty
+//   set: the capture is skipped and the fork resolves the ordinary root
+//   initialization policy for itself.
+// - subagent (one-shot / background / supervised member / escalation; a
+//   depth-0 fork child is handled by the incarnation rule above): a parent
+//   snapshot that cannot be read, or a capture that cannot be written, makes
+//   the listener THROW. The host dispatches agent/created serially and a
+//   listener failure rejects the creation, so throwing is the INTENTIONAL
+//   bail that refuses the subagent while the parent session continues and
+//   learns the reason through the delegation result. Never an unrestricted
+//   pass, and never the root-initialization fallback (that is a depth-0 fork
+//   affordance only).
 import { isSegment } from './store/paths.js'
 import { openCapabilityStore } from './store/store.js'
 import { skillIdentityKey } from './skill-identity.js'
@@ -60,17 +72,28 @@ import { skillIdentityKey } from './skill-identity.js'
 export const INHERITED_ORIGIN = 'inherited'
 
 /**
- * @typedef {{ state: 'ready', sessionId: string, revision: number, skills: unknown[], mcpServers: string[],
+ * @typedef {{ state: 'ready', sessionId: string, revision: number, skills: unknown[], mcpServers: string[], mcpIncarnations?: Record<string, string|null>,
  *   captured: { parentSessionId: string, parentRevision: number | null, capturedAt: number } | null }} ReadySnapshot
  * @typedef {{ state: 'blocked', sessionId: string, reason: 'corrupt'|'unknown-schema'|'torn'|'unreadable' }} BlockedSnapshot
  * @typedef {ReadySnapshot | BlockedSnapshot} LifecycleSnapshot
- * @typedef {{ revision: number, skills?: unknown[], mcpServers?: string[],
+ * @typedef {{ revision: number, skills?: unknown[], mcpServers?: string[], mcpIncarnations?: Record<string, string|null>,
  *   captured?: { parentSessionId: string, parentRevision: number | null, capturedAt: number } | null }} SnapshotInput
  */
 
 /** @param {unknown} error */
 const message = error => (error instanceof Error ? error.message : String(error))
 
+export function normalizeMcpIncarnations(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  return Object.fromEntries(Object.entries(value).filter(([, incarnation]) => incarnation === null || typeof incarnation === 'string'))
+}
+
+export function mcpIncarnationsFor(servers, mapping) {
+  const normalized = normalizeMcpIncarnations(mapping)
+  if (!normalized) return undefined
+  return Object.fromEntries(servers.filter(identity => Object.hasOwn(normalized, identity)).map(identity => [identity, normalized[identity]]))
+}
+
 /**
  * In-memory lifecycle snapshots plus the synchronous read/capture paths.
  * All durable I/O delegates to the capability store's sync path: the same
@@ -118,6 +141,7 @@ export function createLifecycleSnapshots(options = {}) {
       revision: next.revision,
       skills: Object.freeze(structuredClone(Array.isArray(next.skills) ? next.skills : [])),
       mcpServers: Object.freeze((Array.isArray(next.mcpServers) ? next.mcpServers : []).slice()),
+      ...(normalizeMcpIncarnations(next.mcpIncarnations) ? { mcpIncarnations: Object.freeze(normalizeMcpIncarnations(next.mcpIncarnations)) } : {}),
       captured: next.captured ? Object.freeze({ ...next.captured }) : null,
     })
     snapshots.set(sessionId, snapshot)
@@ -146,11 +170,14 @@ export function createLifecycleSnapshots(options = {}) {
 
   /**
    * THE synchronous read path (6.1): memory hit returns immediately; a
-   * miss performs ONE blocking synchronous read of the durable record —
-   * the store's sync read, never a promise, never a yield. An absent record
-   * returns null (no accepted selection; initialization priority for
-   * brand-new root sessions is task 6.5). An undecodable record becomes
-   * BLOCKED.
+   * miss performs blocking synchronous reads of the durable records — the
+   * store's sync read, never a promise, never a yield. The effective snapshot
+   * is the accepted selection when one exists, otherwise the durable inherited
+   * snapshot (a fork whose source only ever resolved an initial set, or a fork
+   * of a fork). An absent pair returns null (no effective snapshot; the fork's
+   * own root initialization is layered above this mechanism). Any record that
+   * exists and does not decode becomes BLOCKED — a corrupt higher-priority
+   * record never falls through to a lower-priority one.
    * @param {string} sessionId
    * @returns {LifecycleSnapshot | null}
    */
@@ -166,19 +193,62 @@ export function createLifecycleSnapshots(options = {}) {
       // closed BLOCKED (6.4), never a guessed full authorization.
       return markBlocked(sessionId, 'unreadable')
     }
-    // No accepted record yet — a legitimate cold state, not a failure.
-    if (record.kind === 'absent') return null
     if (record.kind === 'ok') {
       const payload = /** @type {Record<string, unknown>} */ (record.payload ?? {})
       return publish(sessionId, {
         revision: record.revision,
         skills: Array.isArray(payload.skills) ? payload.skills : [],
         mcpServers: Array.isArray(payload.mcpServers) ? /** @type {string[]} */ (payload.mcpServers) : [],
+        mcpIncarnations: normalizeMcpIncarnations(payload.mcpIncarnations),
       })
     }
     // corrupt / unknown-schema / torn / unsupported: fail closed BLOCKED
     // (6.4 root rule). The original file is never rewritten from this path.
-    return markBlocked(sessionId, /** @type {BlockedSnapshot['reason']} */ (record.kind))
+    if (record.kind !== 'absent') return markBlocked(sessionId, /** @type {BlockedSnapshot['reason']} */ (record.kind))
+    // No accepted record — a legitimate cold state. The EFFECTIVE set may still
+    // be the durable inherited snapshot this session was created with.
+    return snapshotFromInherited(sessionId)
+  }
+
+  /**
+   * The inherited fallback of {@link snapshotFor}: no accepted record exists,
+   * so the effective set is whatever durable inheritance the session was given
+   * at creation. The snapshot keeps the inherited revision and restores the
+   * parent/captured metadata — it is NEVER reported as an accepted revision
+   * (the receipt's CAS token stays accepted-only, 0 when absent). A record
+   * that exists but does not decode blocks exactly like a corrupt selection
+   * record: no fall-through to the initial baseline.
+   * @param {string} sessionId
+   * @returns {LifecycleSnapshot | null}
+   */
+  function snapshotFromInherited(sessionId) {
+    let inherited
+    try {
+      inherited = store.readSync({ kind: 'inherited', sessionId })
+    } catch {
+      return markBlocked(sessionId, 'unreadable')
+    }
+    if (inherited.kind !== 'ok') {
+      if (inherited.kind === 'absent') return null
+      return markBlocked(sessionId, /** @type {BlockedSnapshot['reason']} */ (inherited.kind))
+    }
+    const payload = /** @type {Record<string, unknown>} */ (inherited.payload ?? {})
+    const parent = /** @type {Record<string, unknown> | null} */ (
+      payload.parent && typeof payload.parent === 'object' ? payload.parent : null)
+    const capturedAt = typeof payload.capturedAt === 'number' && Number.isFinite(payload.capturedAt) ? payload.capturedAt : 0
+    return publish(sessionId, {
+      revision: inherited.revision,
+      skills: Array.isArray(payload.skills) ? payload.skills : [],
+      mcpServers: Array.isArray(payload.mcpServers) ? /** @type {string[]} */ (payload.mcpServers) : [],
+      mcpIncarnations: normalizeMcpIncarnations(payload.mcpIncarnations),
+      captured: parent && typeof parent.sessionId === 'string' && parent.sessionId.length > 0
+        ? {
+          parentSessionId: parent.sessionId,
+          parentRevision: Number.isSafeInteger(parent.revision) ? /** @type {number} */ (parent.revision) : null,
+          capturedAt,
+        }
+        : null,
+    })
   }
 
   /**
@@ -219,13 +289,15 @@ export function createLifecycleSnapshots(options = {}) {
   }
 
   /**
-   * Durably capture a subagent's inherited snapshot (6.2), synchronously.
+   * Durably capture a session's inherited snapshot (6.2), synchronously.
    * The inherited sets follow creation-time inheritance (6.3): verbatim
    * parent at creation, child-previous ∩ current-parent on an explicit
    * resume/escalation, narrowed by delegation constraints — never widened.
-   * A parent without any accepted record yields
-   * an empty inherited set (the no-policy initialization priority of task
-   * 6.5 is a root-session concern layered above this mechanism).
+   * The parent's EFFECTIVE set is its accepted selection when one exists,
+   * otherwise its own inherited snapshot (a fork of a fork). A parent with NO
+   * effective snapshot at all is not an empty inheritance: the depth-0 fork
+   * caller skips this capture entirely (see `agentCreated`) and lets that fork
+   * run the ordinary root initialization instead.
    *
    * NOT ATOMIC with the host's session publication (see the module header):
    * a crash between the two durable acts leaves a child session without a
@@ -270,9 +342,11 @@ export function createLifecycleSnapshots(options = {}) {
       : null
     let mcpServers = previousMcp == null ? parentMcp.slice() : intersectStrings(previousMcp, parentMcp)
     if (Array.isArray(constraints.allowMcpServers)) mcpServers = intersectStrings(mcpServers, constraints.allowMcpServers)
+    const mcpIncarnations = mcpIncarnationsFor(mcpServers, parent?.mcpIncarnations)
     const payload = {
       skills: structuredClone(skills),
       mcpServers,
+      ...(mcpIncarnations ? { mcpIncarnations } : {}),
       origin: INHERITED_ORIGIN,
       parent: { sessionId: parentSessionId, revision: parent ? parent.revision : null },
       capturedAt,
@@ -290,6 +364,7 @@ export function createLifecycleSnapshots(options = {}) {
       revision: result.revision,
       skills: payload.skills,
       mcpServers: payload.mcpServers,
+      mcpIncarnations: normalizeMcpIncarnations(payload.mcpIncarnations),
       captured: { parentSessionId, parentRevision: payload.parent.revision, capturedAt },
     })
   }
@@ -320,7 +395,7 @@ export function createLifecycleSnapshots(options = {}) {
         // record becomes BLOCKED inside snapshotFor — this path NEVER throws.
         const own = snapshotFor(sessionId)
         // Resume/fork incarnation (D1): depth zero yet a parentSession
-        // header. The read side demands an inherited snapshot for such a
+        // header. The read side demands an effective snapshot for such a
         // session exactly when it carries NO accepted record of its own, so
         // the capture side aligns with that gate: an incarnation WITH its
         // own accepted record keeps it verbatim (an explicit user Apply is
@@ -331,12 +406,25 @@ export function createLifecycleSnapshots(options = {}) {
         // parentSession equal to the session id is no parent (defensive).
         const parentSessionId = session.header?.parentSession
         if (own === null && typeof parentSessionId === 'string' && parentSessionId.length > 0 && parentSessionId !== sessionId) {
-          try {
-            captureInherited(sessionId, parentSessionId)
-          } catch (captureError) {
-            warn(`resume incarnation capture failed for session "${sessionId}": ${message(captureError)}`)
-            markBlocked(sessionId, 'unreadable')
+          // The fork inherits the source's EFFECTIVE set: accepted, else
+          // inherited, else the already-resolved initial snapshot. Only a
+          // parent snapshot PROVEN absent (null on supported storage) is not a
+          // set to copy — an unsupported store proves nothing, so that case
+          // keeps the old attempt-and-block shape instead of silently
+          // initializing the fork.
+          const parent = snapshotFor(parentSessionId)
+          const provenAbsent = parent === null && support.supported
+          if (!provenAbsent) {
+            try {
+              captureInherited(sessionId, parentSessionId)
+            } catch (captureError) {
+              warn(`resume incarnation capture failed for session "${sessionId}": ${message(captureError)}`)
+              markBlocked(sessionId, 'unreadable')
+            }
           }
+          // provenAbsent: no capture and no empty inherited record. The first
+          // readSelection then runs the ordinary root initialization for this
+          // depth-0 fork and publishes its own revision-0 snapshot.
         }
         return undefined
       }

package/src/capabilities/mcp-admission.js

@@ -13,7 +13,7 @@
  *   admit: (agent: unknown) => Promise<boolean>,
  *   drain?: { enter(agentId: string, server: string, label?: string): number|null, exit(agentId: string, server: string, token: number|null): void } }} config
  */
-export function createMcpToolWrapper({ identity, generation, admit, drain }) {
+export function createMcpToolWrapper({ identity, generation, admit, drain, assertPermit }) {
   /**
    * Wrap one tool definition with the last-moment check.
    * @param {{ name?: unknown, execute?: unknown, [key: string]: unknown }} definition
@@ -33,7 +33,7 @@ export function createMcpToolWrapper({ identity, generation, admit, drain }) {
        */
       async execute(args, exec) {
         const admitted = await admit(exec?.agent)
-        if (!admitted) {
+        if (!admitted || (assertPermit && !assertPermit(admitted))) {
           const error = new Error(`MCP server "${identity}" is not enabled for this agent (admission refused at generation ${generation})`)
           throw Object.assign(error, { code: 'mcp-admission-refused' })
         }

package/src/capabilities/mcp-config.js

@@ -0,0 +1,344 @@
+// One MCP configuration parser/projection for forms, JSON paste, commands, AI,
+// registry previews and stock-client materialization. Unknown fields fail before
+// any operation side effect; secret values never appear in the returned plan.
+import { createHash } from 'node:crypto'
+import { isSegment } from './store/paths.js'
+import { sanitizeMcpConfigText, markMcpConfigProjection } from './mcp-diagnostics.js'
+
+export const MCP_LIMITS = Object.freeze({
+  documentBytes: 1024 * 1024,
+  batchEntries: 32,
+  args: 128,
+  env: 64,
+  headers: 64,
+  planBytes: 256 * 1024,
+  toolNamesPreview: 20,
+  diagnosticBytes: 8192,
+})
+const SERVER_NAME = /^[A-Za-z0-9_-]{1,32}$/
+const CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/
+const COMMON = new Set(['transport', 'type', 'serverName', 'toolCallTimeoutMs', 'maxInstructionBytes', 'reconnect', 'failOnStartupError'])
+const ROOT = new Set(['identity', 'label', 'owner', 'incarnation', 'generation', 'configuredAt', 'client', 'transport', 'secretRefs', 'secretValues', ...COMMON, 'command', 'args', 'env', 'cwd', 'url', 'headers', 'secretArgs'])
+const RECONNECT = new Set(['enabled', 'initialDelayMs', 'maxDelayMs', 'maxAttempts'])
+const clone = value => value == null ? value : structuredClone(value)
+const object = value => value && typeof value === 'object' && !Array.isArray(value)
+
+export class McpConfigError extends TypeError {
+  constructor(field, message) {
+    super(`${field}: ${message}`)
+    this.name = 'McpConfigError'
+    this.code = 'invalid-config'
+    this.field = field
+  }
+}
+const fail = (field, message) => { throw new McpConfigError(field, message) }
+const known = (value, allowed, path) => {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) fail(`${path}.${key}`, 'unknown field')
+}
+const positive = (value, field, integer = false) => {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || (integer && !Number.isSafeInteger(value))) fail(field, 'must be a positive finite number')
+  return value
+}
+const ref = (value, field) => {
+  if (!object(value) || typeof value.ref !== 'string' || !CREDENTIAL_REF.test(value.ref)) fail(field, 'must be a POSIX credential reference')
+  known(value, new Set(['ref', 'prefix']), field)
+  if (value.prefix !== undefined && typeof value.prefix !== 'string') fail(`${field}.prefix`, 'must be a string')
+  return { ref: value.ref, ...(value.prefix ? { prefix: value.prefix } : {}) }
+}
+const sensitiveUrl = value => {
+  try {
+    const url = new URL(value)
+    return Boolean(url.username || url.password || url.search || url.hash)
+  } catch { return true }
+}
+const safeHttpUrl = (value, field) => {
+  let url
+  try { url = new URL(value) } catch { fail(field, 'must be an absolute URL') }
+  if (!['http:', 'https:'].includes(url.protocol)) fail(field, 'only http/https URLs are supported')
+  return url
+}
+
+function reconnectOf(value) {
+  if (value === undefined) return undefined
+  if (!object(value)) fail('reconnect', 'must be an object')
+  known(value, RECONNECT, 'reconnect')
+  const out = {}
+  if (value.enabled !== undefined) {
+    if (typeof value.enabled !== 'boolean') fail('reconnect.enabled', 'must be boolean')
+    out.enabled = value.enabled
+  }
+  for (const key of ['initialDelayMs', 'maxDelayMs']) if (value[key] !== undefined) out[key] = positive(value[key], `reconnect.${key}`)
+  if (value.maxAttempts !== undefined) out.maxAttempts = positive(value.maxAttempts, 'reconnect.maxAttempts', true)
+  if ((out.initialDelayMs ?? 500) > (out.maxDelayMs ?? 30000)) fail('reconnect.initialDelayMs', 'must not exceed maxDelayMs')
+  return out
+}
+
+function secretInput(value, field, surface) {
+  if (!object(value)) {
+    if (value === '') return { action: 'keep' }
+    if (surface !== 'ui') fail(field, 'literal secrets are accepted only by the Host mutation channel; use a credential reference')
+    if (typeof value !== 'string') fail(field, 'secret values must be strings')
+    return { action: 'replace', value }
+  }
+  known(value, new Set(['action', 'value', 'prefix']), field)
+  const action = value.action ?? 'replace'
+  if (value.prefix !== undefined && typeof value.prefix !== 'string') fail(`${field}.prefix`, 'must be a string')
+  if (!['keep', 'replace', 'remove'].includes(action)) fail(`${field}.action`, 'must be keep, replace or remove')
+  if (action === 'replace') {
+    if (surface !== 'ui') fail(field, 'literal secrets are accepted only by the Host mutation channel; use a credential reference')
+    if (typeof value.value !== 'string' || value.value.length === 0) fail(`${field}.value`, 'replacement secrets must be non-empty strings; blank means keep')
+  }
+  return { action, ...(action === 'replace' ? { value: value.value, ...(value.prefix !== undefined ? { prefix: value.prefix } : {}) } : {}) }
+}
+
+function secretMap(input, field, limit, surface) {
+  if (input === undefined) return { refs: {}, values: {}, literals: {}, legacy: {} }
+  if (!object(input)) fail(field, 'must be an object')
+  const entries = Object.entries(input)
+  if (entries.length > limit) fail(field, `exceeds the ${limit}-entry limit`)
+  const refs = {}, values = {}, literals = {}, legacy = {}
+  for (const [key, value] of entries) {
+    if (!key || Buffer.byteLength(key) > 256) fail(field, 'contains an invalid key')
+    if (typeof value === 'string') {
+      // New UI/JSON literal env/header values are staged credentials. The
+      // registry adapter may explicitly preserve a legacy record instead.
+      if (surface === 'legacy') legacy[key] = value
+      else if (surface === 'refs' && value !== '') fail(`${field}.${key}`, 'literal secrets are not accepted; use a credential reference')
+      else values[key] = value === '' ? { action: 'keep' } : { action: 'replace', value }
+    } else if (object(value) && typeof value.ref === 'string') refs[key] = ref(value, `${field}.${key}`)
+    else values[key] = secretInput(value, `${field}.${key}`, surface)
+  }
+  return { refs, values, literals, legacy }
+}
+
+function refsOf(input, field) {
+  if (!object(input)) return {}
+  known(input, new Set(['env', 'headers', 'args', 'url']), field)
+  const out = {}
+  for (const kind of ['env', 'headers', 'args']) {
+    if (input[kind] === undefined) continue
+    if (!object(input[kind])) fail(`${field}.${kind}`, 'must be an object')
+    out[kind] = {}
+    for (const [key, value] of Object.entries(input[kind])) out[kind][key] = ref(value, `${field}.${kind}.${key}`)
+  }
+  if (input.url !== undefined) out.url = ref(input.url, `${field}.url`)
+  return out
+}
+
+function normalizeTransport(input, client) {
+  const kind = client.transport ?? client.type ?? input.transport?.kind ?? (typeof client.command === 'string' ? 'stdio' : typeof client.url === 'string' || object(client.url) ? 'streamable-http' : undefined)
+  if (kind === 'http') return 'streamable-http'
+  if (kind !== 'stdio' && kind !== 'streamable-http') fail('transport', 'must be stdio or streamable-http')
+  return kind
+}
+
+/** Normalize one server. surface=ui permits transient secretValues; refs-only surfaces never do. */
+export function normalizeMcpServer(raw, options = {}) {
+  if (!object(raw)) fail('server', 'must be an object')
+  known(raw, ROOT, 'server')
+  const surface = options.surface ?? 'ui'
+  if (!['ui', 'refs', 'legacy'].includes(surface)) fail('surface', 'unknown input surface')
+  const clientInput = raw.client ?? raw
+  if (!object(clientInput)) fail('client', 'must be an object')
+  const kind = normalizeTransport(raw, clientInput)
+  const allowed = new Set(kind === 'stdio' ? ['command', 'args', 'env', 'cwd', 'secretArgs'] : ['url', 'headers'])
+  known(clientInput, new Set([...COMMON, ...allowed, 'identity', 'label', 'owner', 'incarnation', 'generation', 'configuredAt', 'client', 'secretRefs', 'secretValues']), 'client')
+  const identity = options.identity ?? raw.identity
+  if (!isSegment(identity)) fail('identity', 'must be a stable identity segment')
+  const label = raw.label ?? identity
+  if (typeof label !== 'string' || !label.trim() || Buffer.byteLength(label) > 512) fail('label', 'must be a non-empty bounded string')
+  const serverName = clientInput.serverName ?? identity
+  if (typeof serverName !== 'string' || !SERVER_NAME.test(serverName)) fail('serverName', 'must match [A-Za-z0-9_-]{1,32}')
+  const client = { transport: kind, serverName, failOnStartupError: true }
+  for (const key of ['toolCallTimeoutMs', 'maxInstructionBytes']) if (clientInput[key] !== undefined) client[key] = positive(clientInput[key], key, key === 'maxInstructionBytes')
+  const reconnect = reconnectOf(clientInput.reconnect)
+  if (reconnect) client.reconnect = reconnect
+  const secretRefs = { env: {}, headers: {}, args: {} }
+  const secretValues = { env: {}, headers: {}, args: {} }
+  const legacy = { env: {}, headers: {} }
+  const existingRefs = refsOf(raw.secretRefs, 'secretRefs')
+  Object.assign(secretRefs.env, existingRefs.env ?? {})
+  Object.assign(secretRefs.headers, existingRefs.headers ?? {})
+  Object.assign(secretRefs.args, existingRefs.args ?? {})
+  if (existingRefs.url) secretRefs.url = existingRefs.url
+
+  if (kind === 'stdio') {
+    if (clientInput.url !== undefined || clientInput.headers !== undefined) fail('client', 'HTTP fields cannot be combined with stdio')
+    if (typeof clientInput.command !== 'string' || !clientInput.command.trim()) fail('command', 'is required')
+    client.command = clientInput.command
+    const args = clientInput.args ?? []
+    if (!Array.isArray(args) || args.length > MCP_LIMITS.args) fail('args', `must be an array of at most ${MCP_LIMITS.args} entries`)
+    client.args = args.map((value, index) => {
+      if (typeof value === 'string') return value
+      if (object(value) && typeof value.ref === 'string') {
+        secretRefs.args[index] = ref(value, `args.${index}`)
+        return ''
+      }
+      fail(`args.${index}`, 'must be a string or credential reference')
+    })
+    if (clientInput.secretArgs !== undefined) {
+      if (!object(clientInput.secretArgs)) fail('secretArgs', 'must be an object keyed by argument index')
+      for (const [key, value] of Object.entries(clientInput.secretArgs)) {
+        const index = Number(key)
+        if (!Number.isInteger(index) || index < 0 || index >= client.args.length) fail(`secretArgs.${key}`, 'argument index is out of range')
+        if (object(value) && typeof value.ref === 'string') secretRefs.args[index] = ref(value, `secretArgs.${key}`)
+        else secretValues.args[index] = secretInput(value, `secretArgs.${key}`, surface)
+      }
+    }
+    const env = secretMap(clientInput.env, 'env', MCP_LIMITS.env, surface)
+    Object.assign(secretRefs.env, env.refs)
+    Object.assign(secretValues.env, env.values)
+    Object.assign(legacy.env, env.legacy)
+    if (clientInput.cwd !== undefined) {
+      if (typeof clientInput.cwd !== 'string') fail('cwd', 'must be a string')
+      client.cwd = clientInput.cwd
+    }
+  } else {
+    if (clientInput.command !== undefined || clientInput.args !== undefined || clientInput.env !== undefined || clientInput.cwd !== undefined || clientInput.secretArgs !== undefined) fail('client', 'stdio fields cannot be combined with streamable-http')
+    if (object(clientInput.url) && typeof clientInput.url.ref === 'string') secretRefs.url = ref(clientInput.url, 'url')
+    else if (typeof clientInput.url === 'string') {
+      const url = safeHttpUrl(clientInput.url, 'url')
+      if (sensitiveUrl(clientInput.url)) {
+        if (surface !== 'ui') fail('url', 'sensitive URLs require a credential reference')
+        secretValues.url = { action: 'replace', value: clientInput.url }
+      } else client.url = url.toString()
+    } else if (clientInput.url !== undefined) secretValues.url = secretInput(clientInput.url, 'url', surface)
+    else if (!secretRefs.url) fail('url', 'is required')
+    const headers = secretMap(clientInput.headers, 'headers', MCP_LIMITS.headers, surface)
+    Object.assign(secretRefs.headers, headers.refs)
+    Object.assign(secretValues.headers, headers.values)
+    Object.assign(legacy.headers, headers.legacy)
+  }
+  if (raw.secretValues !== undefined) {
+    if (!object(raw.secretValues)) fail('secretValues', 'must be an object')
+    known(raw.secretValues, new Set(['env', 'headers', 'args', 'url']), 'secretValues')
+    for (const [field, limit] of [['env', MCP_LIMITS.env], ['headers', MCP_LIMITS.headers], ['args', MCP_LIMITS.args]]) {
+      const values = raw.secretValues[field]
+      if (values === undefined) continue
+      if (!object(values)) fail(`secretValues.${field}`, 'must be an object')
+      if (Object.keys(values).length > limit) fail(`secretValues.${field}`, `exceeds the ${limit}-entry limit`)
+      for (const [key, value] of Object.entries(values)) secretValues[field][key] = secretInput(value, `secretValues.${field}.${key}`, surface)
+    }
+    if (raw.secretValues.url !== undefined) secretValues.url = secretInput(raw.secretValues.url, 'secretValues.url', surface)
+  }
+  const hasRefs = Object.values(secretRefs).some(value => object(value) && Object.keys(value).length > 0)
+  const hasLegacy = Object.keys(legacy.env).length > 0 || Object.keys(legacy.headers).length > 0
+  const entry = {
+    identity,
+    label,
+    owner: clone(raw.owner ?? options.owner ?? { kind: 'global', key: 'installation' }),
+    ...(raw.incarnation !== undefined ? { incarnation: raw.incarnation } : {}),
+    generation: raw.generation ?? 0,
+    configuredAt: raw.configuredAt ?? 0,
+    transport: { kind, ref: kind === 'stdio' ? `cmd:${client.command}` : client.url ? `http:${client.url}` : 'http:credential-ref' },
+    client: { ...client, ...(kind === 'stdio' ? { env: legacy.env } : { headers: legacy.headers }) },
+    secretRefs,
+  }
+  if (Object.keys(secretRefs.env).length === 0) delete entry.secretRefs.env
+  if (Object.keys(secretRefs.headers).length === 0) delete entry.secretRefs.headers
+  if (Object.keys(secretRefs.args).length === 0) delete entry.secretRefs.args
+  if (Object.keys(entry.secretRefs).length === 0) delete entry.secretRefs
+  const transient = Object.keys(secretValues.env).length || Object.keys(secretValues.headers).length || Object.keys(secretValues.args).length || secretValues.url
+  return {
+    entry,
+    secretValues: transient ? secretValues : {},
+    hasSecrets: Boolean(hasRefs || hasLegacy || transient),
+    legacyLiteralSecrets: hasLegacy,
+  }
+}
+
+export function parseMcpDocument(input, options = {}) {
+  let document = input
+  if (typeof input === 'string') {
+    if (Buffer.byteLength(input) > MCP_LIMITS.documentBytes) fail('document', `exceeds the ${MCP_LIMITS.documentBytes}-byte limit`)
+    try { document = JSON.parse(input) } catch { fail('document', 'must be valid JSON') }
+  }
+  if (!object(document)) fail('document', 'must be an object')
+  const batch = Object.hasOwn(document, 'mcpServers')
+  if (batch) {
+    known(document, new Set(['mcpServers']), 'document')
+    if (!object(document.mcpServers)) fail('mcpServers', 'must be an object')
+  }
+  const entries = batch ? Object.entries(document.mcpServers) : [[undefined, document]]
+  if (entries.length < 1 || entries.length > MCP_LIMITS.batchEntries) fail('mcpServers', `must contain between 1 and ${MCP_LIMITS.batchEntries} servers`)
+  const identities = new Set()
+  const normalized = entries.map(([key, value], index) => {
+    const identity = key ?? value?.identity
+    if (identities.has(identity)) fail(`mcpServers.${identity}`, 'duplicate identity')
+    identities.add(identity)
+    try {
+      return normalizeMcpServer(value, { ...options, identity: identity ?? options.identity })
+    } catch (error) {
+      if (error instanceof McpConfigError) throw new McpConfigError(batch ? `mcpServers.${key ?? index}.${error.field}` : error.field, error.message.slice(error.message.indexOf(': ') + 2))
+      throw error
+    }
+  })
+  const plan = normalized.map((item, index) => ({ index, identity: item.entry.identity, entry: redactMcpEntry(item.entry), fingerprint: fingerprintMcpEntry(item.entry) }))
+  assertMcpPlanSize(plan)
+  const result = { plan, digest: createHash('sha256').update(JSON.stringify(plan)).digest('hex') }
+  // Execution-only normalized entries (including transient secretValues) stay
+  // reachable to Host operations but can never leak into a serialized preview.
+  Object.defineProperty(result, 'entries', { value: normalized, enumerable: false })
+  return result
+}
+
+/**
+ * Display/edit projection of a stored entry. Only structurally secret positions
+ * are replaced: env/header values, secretRefs-indexed args and sensitive URLs.
+ * Every other string keeps its exact value apart from known secrets and
+ * sensitive URL tails, so plain argv such as `--port=8080` or `FOO=bar` survives
+ * an edit round-trip and an approval card byte-identical.
+ */
+export function redactMcpEntry(entry, secrets = []) {
+  const out = clone(entry)
+  if (out?.client?.env) for (const key of Object.keys(out.client.env)) out.client.env[key] = MCP_REDACTED
+  if (out?.client?.headers) for (const key of Object.keys(out.client.headers)) out.client.headers[key] = MCP_REDACTED
+  for (const index of Object.keys(out?.secretRefs?.args ?? {})) if (out.client?.args?.[index] !== undefined) out.client.args[index] = MCP_REDACTED
+  if (out?.client?.url && sensitiveUrl(out.client.url)) out.client.url = '[redacted-url]'
+  delete out.secretValues
+  return markMcpConfigProjection(sanitizeMcpConfigProjection(out, secrets))
+}
+function sanitizeMcpConfigProjection(value, secrets) {
+  if (typeof value === 'string') return sanitizeMcpConfigText(value, secrets)
+  if (Array.isArray(value)) return value.map(item => sanitizeMcpConfigProjection(item, secrets))
+  if (object(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeMcpConfigProjection(item, secrets)]))
+  return value
+}
+export const MCP_REDACTED = '[redacted]'
+const PLACEHOLDER = /\[redacted(?:-[a-z]+)?\]/
+
+/**
+ * Edit input for stdio args is resolved against the stored record: an element
+ * equal to the redaction projection at the same index means "unchanged" and
+ * takes the stored value back (secret slots stay '' with their refs). Any other
+ * placeholder is a redacted value round-tripped as literal input and is refused
+ * instead of being saved.
+ */
+export function resolveMcpEditArgs(existing, incoming) {
+  if (!Array.isArray(incoming)) return incoming
+  const stored = existing?.client?.args ?? []
+  const projected = redactMcpEntry(existing)?.client?.args ?? []
+  return incoming.map((value, index) => {
+    if (typeof value !== 'string') return value
+    if (index < stored.length && value === projected[index]) return stored[index]
+    if (PLACEHOLDER.test(value)) fail(`args.${index}`, 'contains a redaction placeholder; omit args to keep the stored arguments or enter the real value')
+    return value
+  })
+}
+
+/** Hash the full record (including legacy literals) without returning those literals. */
+export function fingerprintMcpEntry(entry) {
+  return createHash('sha256').update(JSON.stringify(entry ?? null)).digest('hex')
+}
+export function assertMcpPlanSize(plan) {
+  const bytes = Buffer.byteLength(JSON.stringify(plan))
+  if (bytes > MCP_LIMITS.planBytes) fail('plan', `exceeds the ${MCP_LIMITS.planBytes}-byte limit`)
+  return bytes
+}
+export function hasMcpSecrets(entry) {
+  if (entry?.secretRefs && Object.keys(entry.secretRefs).length > 0) return true
+  if (Object.keys(entry?.client?.env ?? {}).length > 0 || Object.keys(entry?.client?.headers ?? {}).length > 0) return true
+  return typeof entry?.client?.url === 'string' && sensitiveUrl(entry.client.url)
+}
+export function isSensitiveMcpUrl(value) { return sensitiveUrl(value) }
+export function validateCredentialRef(value) { return typeof value === 'string' && CREDENTIAL_REF.test(value) }