weir-harness 2.0.0 → 2.1.1

package/src/capabilities/lifecycle-preload.js

@@ -1,11 +1,19 @@
-// Task 6.1 preload (design D6): at plugin apply, load the accepted
-// selections of KNOWN sessions into the lifecycle memory snapshot, so the
-// agent/created listener's synchronous read hits memory instead of disk.
-// This module is the async boundary — it runs at mount time, NEVER inside
-// the agent/created listener. A slow or failed preload costs one blocking
-// synchronous disk read per agent creation (the listener's miss path),
-// never correctness. Records that do not decode are pre-marked BLOCKED, so
-// the fail-closed state is ready before the first agent is created.
+// Task 6.1 preload (design D6): at plugin apply, load the EFFECTIVE selections
+// of KNOWN sessions into the lifecycle memory snapshot, so the agent/created
+// listener's synchronous read hits memory instead of disk. This module is the
+// async boundary — it runs at mount time, NEVER inside the agent/created
+// listener. A slow or failed preload costs one blocking synchronous disk read
+// per agent creation (the listener's miss path), never correctness. Records
+// that do not decode are pre-marked BLOCKED, so the fail-closed state is ready
+// before the first agent is created.
+//
+// "Effective" is the same priority the synchronous read path applies: the
+// accepted selection when one exists, otherwise the durable inherited snapshot
+// (a fork of a fork, or a fork whose source only resolved an initial set). Both
+// are loaded here, because a cold session read (Badge/manager receipt, MCP
+// gate, Skill catalog) must report the inherited set rather than an empty one
+// until the fork's agent is recreated. A corrupt record of EITHER unit blocks
+// the session — never a fall-through to the other one.
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { isSegment } from './store/paths.js'
@@ -14,10 +22,17 @@ import { openCapabilityStore } from './store/store.js'
 /** @param {unknown} error */
 const message = error => (error instanceof Error ? error.message : String(error))
 
+/** @param {unknown} payload @returns {number} capturedAt used by the inherited restore */
+const capturedAtOf = payload => {
+  const value = /** @type {Record<string, unknown>} */ (payload ?? {}).capturedAt
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
 /**
  * @param {{
  *   lifecycle: {
- *     publish(sessionId: string, next: { revision: number, skills?: unknown[], mcpServers?: string[] }): unknown,
+ *     publish(sessionId: string, next: { revision: number, skills?: unknown[], mcpServers?: string[],
+ *       captured?: { parentSessionId: string, parentRevision: number | null, capturedAt: number } | null }): unknown,
  *     markBlocked(sessionId: string, reason: 'corrupt'|'unknown-schema'|'torn'|'unreadable'): unknown,
  *     peek(sessionId: string): unknown,
  *   },
@@ -45,20 +60,63 @@ export async function preloadLifecycleSnapshots({ lifecycle, profileContext, pla
     if (!isSegment(name)) continue
     // A fresher in-memory publication (e.g. an Apply accepted while this
     // preload was in flight) always wins over the disk record it came from.
-    if (lifecycle.peek(name)) continue
+    // Capture the exact observed object so EVERY post-await publication or
+    // blocked marker can be gated on the same freshness proof.
+    const observed = lifecycle.peek(name) ?? null
+    if (observed) continue
     try {
       const record = await active.read({ kind: 'selection', sessionId: name })
+      // The first await may have allowed an accepted Apply (or another
+      // publisher) to replace the memory snapshot. Never publish/mark stale.
+      if (lifecycle.peek(name) !== observed) continue
       if (record.kind === 'ok') {
         const payload = record.payload ?? {}
         lifecycle.publish(name, {
           revision: record.revision,
           skills: Array.isArray(payload.skills) ? payload.skills : [],
           mcpServers: Array.isArray(payload.mcpServers) ? payload.mcpServers : [],
+          mcpIncarnations: payload.mcpIncarnations,
         })
         loaded++
-      } else if (record.kind === 'corrupt' || record.kind === 'unknown-schema' || record.kind === 'torn') {
+        continue
+      }
+      if (record.kind !== 'absent') {
         lifecycle.markBlocked(name, record.kind)
         blocked++
+        continue
+      }
+      // No accepted record: the effective set may be the durable inherited
+      // snapshot. Same fail-closed treatment for a record that exists but does
+      // not decode — the session must not look uninitialized (and be handed a
+      // fresh initial baseline) merely because its inheritance is damaged.
+      const inherited = await active.read({ kind: 'inherited', sessionId: name })
+      // A second independent read creates another interleaving window: an
+      // accepted Apply here MUST outrank the older inherited unit.
+      if (lifecycle.peek(name) !== observed) continue
+      if (inherited.kind === 'ok') {
+        const payload = /** @type {Record<string, unknown>} */ (inherited.payload ?? {})
+        const parent = payload.parent && typeof payload.parent === 'object'
+          ? /** @type {Record<string, unknown>} */ (payload.parent)
+          : null
+        lifecycle.publish(name, {
+          revision: inherited.revision,
+          skills: Array.isArray(payload.skills) ? payload.skills : [],
+          mcpServers: Array.isArray(payload.mcpServers) ? payload.mcpServers : [],
+          mcpIncarnations: 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: capturedAtOf(payload),
+            }
+            : null,
+        })
+        loaded++
+        continue
+      }
+      if (inherited.kind !== 'absent') {
+        lifecycle.markBlocked(name, inherited.kind)
+        blocked++
       }
     } catch (error) {
       warn(`lifecycle snapshot preload skipped session "${name}": ${message(error)}`)

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' })
         }