weir-harness 1.2.0 → 1.2.2

package/src/capabilities/store/checked-contract.d.ts

@@ -8,6 +8,7 @@ declare module 'node:fs' {
   export function renameSync(from: string, to: string): void;
   export function unlinkSync(path: string): void;
   export function fsyncSync(fd: number): void;
+  export function linkSync(existingPath: string, newPath: string): void;
 }
 declare module 'node:fs/promises' {
   export function link(existingPath: string, newPath: string): Promise<void>;
@@ -23,10 +24,14 @@ declare module 'node:child_process' {
 }
 declare module 'node:os' {
   export function hostname(): string;
+  export function homedir(): string;
 }
 declare var process: {
   pid: number;
   platform: string;
+  execPath: string;
+  cwd(): string;
+  env: Record<string, string | undefined>;
   kill(pid: number, signal?: number): void;
 };
 

package/src/capabilities/store/fs-adapter.js

@@ -106,3 +106,55 @@ export function instrumentFs(inner, hook) {
   }
   return /** @type {StoreFs} */ (wrapped)
 }
+
+// ---- Synchronous counterpart (capabilities-deepening D4) ---------------------
+// The lifecycle listener may not yield the event loop (G4b), so the store's
+// sync commit/read path needs blocking I/O with the SAME durability
+// discipline as the async Adapter above: full-content write, file fsync,
+// link/rename publication, directory fsync (POSIX-only — the same platform
+// stance as fsyncDir). One seam, so a test can wrap these calls exactly like
+// instrumentFs wraps the async ones.
+
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+
+/**
+ * @typedef {{
+ *   readTextSync(path: string): string,
+ *   writeFullSync(path: string, text: string): void,
+ *   fsyncFileSync(path: string): void,
+ *   linkSync(from: string, to: string): void,
+ *   renameSync(from: string, to: string): void,
+ *   unlinkSync(path: string): void,
+ *   mkdirpSync(path: string): void,
+ *   fsyncDirSync(path: string): void,
+ * }} StoreSyncFs
+ */
+
+/** @returns {StoreSyncFs} */
+export function createNodeSyncFs() {
+  return {
+    readTextSync: path => readFileSync(path, 'utf8'),
+    writeFullSync(path, text) { writeFileSync(path, text, { mode: 0o600 }) },
+    fsyncFileSync(path) {
+      const fd = openSync(path, 'r+')
+      try {
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+    },
+    linkSync: (from, to) => linkSync(from, to),
+    renameSync: (from, to) => renameSync(from, to),
+    unlinkSync: path => unlinkSync(path),
+    mkdirpSync(path) { mkdirSync(path, { recursive: true, mode: 0o700 }) },
+    fsyncDirSync(path) {
+      if (!DIR_SYNC_SUPPORTED) return
+      const fd = openSync(path, 'r')
+      try {
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+    },
+  }
+}

package/src/capabilities/store/lock.js

@@ -264,3 +264,89 @@ export function createLockProtocol(options) {
 
   return { acquire, release, cleanup, inspect, clear }
 }
+
+// ---- Synchronous nominal-lease variant (capabilities-deepening D4) -----------
+// For callers that may not yield the event loop (the agent/created lifecycle
+// listener): the SAME publication convention as the async protocol above —
+// private candidate + fsync + link (EEXIST = contention), the same OwnerDoc
+// schema, remove-only-if-ours release — but with NO backoff and NO
+// reclamation: contention fails closed, and a crashed holder's leftover lock
+// becomes reclaimable to the async protocol after the nominal lease expires
+// ('sync-capture' marks an owner whose start identity was never probed, so a
+// same-process leftover reads as dead once the lease lapses).
+
+import { hostname } from 'node:os'
+import { createNodeSyncFs } from './fs-adapter.js'
+
+/** Nominal lease of a synchronously acquired lock (acquired, used, released in one segment). */
+export const SYNC_LOCK_LEASE_MS = 10_000
+
+/**
+ * @param {{ fs?: import('./fs-adapter.js').StoreSyncFs, now?: () => number, token?: () => string }} [options]
+ */
+export function createSyncLock(options = {}) {
+  const fs = options.fs ?? createNodeSyncFs()
+  const now = options.now ?? Date.now
+  const token = options.token ?? (() => randomBytes(12).toString('hex'))
+
+  /**
+   * Acquire `<dir>/<name>.lock` synchronously or fail closed. Never writes
+   * the unit record. Contention (EEXIST) is a 'locked' refusal, not a wait.
+   * @param {string} dir @param {string} name
+   * @returns {{ ok: true, token: string } | { ok: false, reason: 'locked' }}
+   */
+  function acquire(dir, name) {
+    const ownerToken = token()
+    const lockFile = join(dir, `${name}.lock`)
+    const candidate = `${lockFile}.${ownerToken}.cand`
+    const at = now()
+    /** @type {OwnerDoc} */
+    const doc = {
+      schemaVersion: LOCK_SCHEMA_VERSION,
+      ownerToken,
+      pid: process.pid,
+      host: hostname(),
+      startIdentity: { osStart: null, bootNonce: 'sync-capture' },
+      acquiredAt: at,
+      leaseUntil: at + SYNC_LOCK_LEASE_MS,
+    }
+    try {
+      fs.writeFullSync(candidate, JSON.stringify(doc))
+      fs.fsyncFileSync(candidate)
+      fs.linkSync(candidate, lockFile)
+    } catch (error) {
+      try { fs.unlinkSync(candidate) } catch { /* the candidate may never have landed */ }
+      // EEXIST = the lock is held; ENOENT = the holder's orphan sweep removed
+      // our candidate mid-race (the async publish() convention) — both mean
+      // this round is lost, and the caller fails closed or retries.
+      if (hasCode(error, 'EEXIST', 'ENOENT')) return { ok: false, reason: /** @type {const} */ ('locked') }
+      throw error
+    }
+    // Candidate cleanup is best-effort (the async publish() convention): a
+    // leftover candidate is swept by the next async acquire's cleanup.
+    try { fs.unlinkSync(candidate) } catch { /* best effort */ }
+    return { ok: true, token: ownerToken }
+  }
+
+  /** Remove `<dir>/<name>.lock` only while it still names our token. @param {string} dir @param {string} name @param {string} ownerToken */
+  function release(dir, name, ownerToken) {
+    const lockFile = join(dir, `${name}.lock`)
+    let text
+    try {
+      text = fs.readTextSync(lockFile)
+    } catch (error) {
+      if (hasCode(error, 'ENOENT')) return false
+      throw error
+    }
+    const doc = parseOwnerDoc(text)
+    if (doc.kind === 'ok' && doc.value.ownerToken !== ownerToken) return false
+    try {
+      fs.unlinkSync(lockFile)
+    } catch (error) {
+      if (!hasCode(error, 'ENOENT')) throw error
+    }
+    return true
+  }
+
+  return { acquire, release }
+}

package/src/capabilities/store/paths.js

@@ -33,6 +33,7 @@ export function resolveStoreRoot(profileContext) {
  * @typedef {{ kind: 'selection', sessionId: string }
  *   | { kind: 'content', sessionId: string }
  *   | { kind: 'inherited', sessionId: string }
+ *   | { kind: 'notice', sessionId: string }
  *   | { kind: 'defaults', workspaceKey: string }
  *   | { kind: 'preset', scope: 'global', presetId: string }
  *   | { kind: 'preset', scope: 'workspace', workspaceKey: string, presetId: string }
@@ -55,6 +56,10 @@ export function unitLayout(unit) {
     case 'selection':
     case 'content':
     case 'inherited':
+    // The pending model-facing notice (durable-pending-notice D1): its own
+    // unit, so the accepted selection record's revision — the client's CAS
+    // token — is never touched by delivery bookkeeping. Absent = nothing owed.
+    case 'notice':
       need(u.sessionId)
       return layout(['sessions', /** @type {string} */ (u.sessionId)], u.kind)
     case 'defaults':

package/src/capabilities/store/store.js

@@ -2,10 +2,14 @@
 // read(unit), commit(unit, expectedRevision, mutate) and publishPointer(scope,
 // next). Locking, stale-lock reclamation, temp cleanup, schema checks and the
 // platform gate stay inside; the filesystem Adapter is the only seam.
+// A committed result also reports the payload its CAS replaced (`committedOver`,
+// read under the same per-unit lock that performed the write): the store is the
+// only component that can prove a write's "before" state without a race, so no
+// caller may re-derive it from an unlocked read.
 import { join } from 'node:path'
-import { createNodeFs } from './fs-adapter.js'
+import { createNodeFs, createNodeSyncFs } from './fs-adapter.js'
 import { createLiveness } from './liveness.js'
-import { createLockProtocol } from './lock.js'
+import { createLockProtocol, createSyncLock } from './lock.js'
 import { validPresetPayload } from './enumerate.js'
 import { isFileSegment, isSegment, resolveStoreRoot, unitLayout } from './paths.js'
 import { decodeRecord, digestOf, encodeRecord } from './record.js'
@@ -23,7 +27,7 @@ export const SUPPORTED_PLATFORMS = Object.freeze(['darwin', 'win32'])
  * @typedef {import('./record.js').Receipt} Receipt
  * @typedef {import('./record.js').RecordRead} RecordRead
  * @typedef {{ requestId?: string, requestDigest?: string }} RequestRef
- * @typedef {{ status: 'committed', revision: number, payload: unknown, receipt: Receipt|null }
+ * @typedef {{ status: 'committed', revision: number, payload: unknown, receipt: Receipt|null, committedOver: unknown }
  *   | { status: 'duplicate', revision: number, receipt: Receipt }
  *   | { status: 'revision-conflict', revision: number }
  *   | { status: 'request-conflict', receipt: Receipt }
@@ -61,6 +65,11 @@ export function openCapabilityStore(options) {
     ? { supported: false, reason: `platform-unsupported:${platform}` }
     : /** @type {any} */ (located)
   const lock = createLockProtocol({ fs, liveness, leaseMs: options.leaseMs, deadlineMs: options.deadlineMs, now, token: options.token })
+  // The synchronous path (capabilities-deepening D4): same root/layout/record
+  // schema, the sync fs counterpart and the nominal-lease sync lock — acquired,
+  // used and released in one blocking segment, contention fails closed.
+  const syncFs = options.syncFs ?? createNodeSyncFs()
+  const syncLock = createSyncLock({ fs: syncFs, now, token: options.token })
   /** @type {Map<string, Promise<unknown>>} */
   const queues = new Map()
 
@@ -243,7 +252,9 @@ export function openCapabilityStore(options) {
           const settled = await readRecord(record).catch(() => null)
           if (settled?.kind !== 'ok' || settled.digest !== next.digest) return { status: 'write-failed', error }
         }
-        return { status: 'committed', revision, payload, receipt }
+        // The payload the CAS replaced, read under this same lock — the only
+        // provable "before" authority of this write (undefined: no record).
+        return { status: 'committed', revision, payload, receipt, committedOver: current.kind === 'ok' ? current.payload : undefined }
       } finally {
         await lock.release(dir, layout.name, acquired.token).catch(() => {})
       }
@@ -302,5 +313,94 @@ export function openCapabilityStore(options) {
     return serialize(layout.key, () => lock.clear(dir, layout.name, which, ownerToken))
   }
 
-  return { support, read, commit, publishPointer, inspect, clear, withPresetNamespace, withSelectionSnapshot }
+  /** Synchronous record read — the same decode/fail-closed semantics as
+   * readRecord, blocking. @param {string} path @returns {RecordRead} */
+  function readRecordSync(path) {
+    let text
+    try {
+      text = syncFs.readTextSync(path)
+    } catch (error) {
+      if (hasCode(error, 'ENOENT')) return { kind: 'absent', revision: 0 }
+      throw error
+    }
+    return decodeRecord(text)
+  }
+
+  /**
+   * Synchronous read (capabilities-deepening D4): the listener path may not
+   * yield the event loop. Same unit layout, same record schema, same
+   * fail-closed kinds as the async read.
+   * @param {Unit} unit
+   * @returns {RecordRead | { kind: 'unsupported', reason: string }}
+   */
+  function readSync(unit) {
+    const { record } = locate(unit)
+    if (!support.supported) return { kind: 'unsupported', reason: support.reason }
+    return readRecordSync(record)
+  }
+
+  /**
+   * Synchronous CAS commit (capabilities-deepening D4), mirroring transact's
+   * step order: lock → dedup the request receipt → CAS the revision → mutate
+   * → temp+fsync → rename → directory fsync. The sync lock is the nominal-
+   * lease convention (acquired, used, released in one blocking segment):
+   * contention fails closed as 'locked' — never a backoff, never a second
+   * reclamation protocol. `mutate` must be synchronous.
+   * @param {Unit} unit
+   * @param {number} expectedRevision
+   * @param {(payload: unknown, info: { revision: number }) => unknown} mutate
+   * @param {RequestRef} [request]
+   * @returns {CommitResult}
+   */
+  function commitSync(unit, expectedRevision, mutate, request = {}) {
+    const { layout, dir, record } = locate(unit)
+    if (!support.supported) return { status: 'unsupported', reason: support.reason }
+    const { requestId, requestDigest } = request
+    if (requestId !== undefined && (typeof requestId !== 'string' || requestId.length === 0 || typeof requestDigest !== 'string')) {
+      throw new TypeError('requestId requires a non-empty id and a requestDigest')
+    }
+    syncFs.mkdirpSync(dir)
+    const acquired = syncLock.acquire(dir, layout.name)
+    if (!acquired.ok) return { status: 'locked', reason: acquired.reason }
+    try {
+      const current = readRecordSync(record)
+      if (current.kind !== 'ok' && current.kind !== 'absent') return { status: 'unreadable', kind: current.kind }
+      const receipts = current.kind === 'ok' ? current.receipts : []
+      if (requestId !== undefined) {
+        const prior = receipts.find(r => r.requestId === requestId)
+        if (prior) return prior.requestDigest === requestDigest ? { status: 'duplicate', revision: prior.revision, receipt: prior } : { status: 'request-conflict', receipt: prior }
+      }
+      if (current.revision !== expectedRevision) return { status: 'revision-conflict', revision: current.revision }
+      const revision = current.revision + 1
+      const payload = mutate(current.kind === 'ok' ? current.payload : undefined, { revision: current.revision })
+      /** @type {Receipt|null} */
+      const receipt = requestId === undefined ? null : { requestId, requestDigest: /** @type {string} */ (requestDigest), revision, acceptedAt: now() }
+      const next = encodeRecord(revision, payload, receipt ? [...receipts, receipt] : receipts)
+      const temp = join(dir, `${layout.name}.${acquired.token}.tmp`)
+      try {
+        syncFs.writeFullSync(temp, JSON.stringify(next))
+        syncFs.fsyncFileSync(temp)
+      } catch (error) {
+        try { syncFs.unlinkSync(temp) } catch { /* the temp may never have landed */ }
+        return { status: 'write-failed', error }
+      }
+      try {
+        syncFs.renameSync(temp, record)
+        syncFs.fsyncDirSync(dir)
+      } catch (error) {
+        try { syncFs.unlinkSync(temp) } catch { /* the temp may never have landed */ }
+        if (hasCode(error, 'EXDEV')) return { status: 'unsupported', reason: 'cross-device' }
+        // Same indeterminate settle-check as the async path: the rename may or
+        // may not have landed — only a digest match proves it did.
+        let settled
+        try { settled = readRecordSync(record) } catch { settled = null }
+        if (settled?.kind !== 'ok' || settled.digest !== next.digest) return { status: 'write-failed', error }
+      }
+      // Same committed-over authority as the async path (one typedef, both writes).
+      return { status: 'committed', revision, payload, receipt, committedOver: current.kind === 'ok' ? current.payload : undefined }
+    } finally {
+      try { syncLock.release(dir, layout.name, acquired.token) } catch { /* release is best-effort */ }
+    }
+  }
+  return { support, read, commit, commitSync, readSync, publishPointer, inspect, clear, withPresetNamespace, withSelectionSnapshot }
 }

package/src/creative-guide/guide.js

@@ -20,7 +20,7 @@ Call \`cordis_inspect_list\` first to enumerate the Host and Client Inspect Prov
 
 ## Manage plugins deliberately
 
-\`plugin_manager\` lists, installs, enables, disables, and removes profile bundles and plugins. List first to obtain exact identifiers. Changes affect every session in the profile and apply immediately in a live profile. To re-apply a changed bundle, disable then enable it (\`set_bundle\`) — repeating \`install_bundle\` for an already-installed bundle is rejected as ambiguous. A version exemption risks crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.
+\`plugin_manager\` lists, installs, enables, disables, and removes profile bundles and plugins. List first to obtain exact identifiers. Changes affect every session in the profile and apply immediately in a live profile. To re-apply a changed bundle, disable then enable it (\`set_bundle\`) — repeating \`install_bundle\` for a known, already-installed bundle is refused up front as \`already-installed\`. A version exemption risks crashes and data loss: warn the user and obtain explicit permission for the exact plugin and runtime versions before granting one.
 
 ## Load the development skills
 

package/src/delegate/child-composition.js

@@ -0,0 +1,258 @@
+// Child composition shim: the creation-window replacement for the
+// request-level `persona`/`toolFilter` fields DSH 0.2.1 removed from
+// `subagents.startActivation`. The delegate module reserves the childId before
+// spawning, registers the composition here, and the `agent/created` listener
+// applies it inside the child's creation window — before the subagent runtime
+// delivers the initial prompt (startLocal → materialize → agents.create →
+// setup → announce → submitMaterialized, verified against 0.2.1).
+//
+// Timing is race-free by construction and fail-closed: a fresh spawn waits for
+// the recorded verdict and tears the child down when the composition did not
+// land, so no child ever runs with the orchestrator-tool deny list missing.
+//
+// Cold resume: the applied sections/restrictions are runtime state of one
+// agent incarnation, so a host restart loses them. Every spawn therefore also
+// writes a `delegate/spawn` fact on the shared audit channel (the cold-safe
+// channel — never a custom session event type, S13) and this listener replays
+// the composition for a resumed child whose fact is still in the audit tail.
+// Missing fact: persona/allow-lists degrade fail-open (same posture as the
+// supervision rebuild), while the orchestrator-tool deny floor is still applied
+// whenever the child is attributable to a weir-managed parent session.
+import { AUDIT_TYPES, AUDIT_SUBTYPES } from '../shared/audit.js'
+import { auditFilePathOf, readAuditTail } from '../shared/terminal-evidence.js'
+import { CHILD_DENY_TOOLS, childToolFilter } from '../shared/child-scope.js'
+
+/**
+ * The spawn-fact audit type AS PASSED TO the audit sink: UNPREFIXED, because
+ * createAudit prepends `weir/` itself (see src/shared/audit.js). Mirrors the
+ * AUDIT_TYPES/AUDIT_SUBTYPES registry; passing a pre-prefixed value here is
+ * what produced `weir/weir/delegate/spawn` records in the wild.
+ */
+export const SPAWN_FACT_TYPE = `${AUDIT_TYPES.delegate}/${AUDIT_SUBTYPES.delegate[0]}`
+
+/**
+ * The spawn-fact type AS STORED in the audit channel (JSONL record + cordis
+ * event name): the sink's single `weir/` prefix is part of the record, so every
+ * comparison against a stored `record.type` must use THIS constant.
+ */
+export const SPAWN_FACT_RECORD_TYPE = `weir/${SPAWN_FACT_TYPE}`
+
+/** Deployment persona prefix section (dsh-system-prompt / dsh-persona contract). */
+const PERSONA_PREFIX_SECTION = 'deployment:persona-prefix'
+const PERSONA_PREFIX_ORDER = 'DEPLOYMENT_PERSONA_PREFIX'
+
+/**
+ * @typedef {object} SpawnComposition
+ * @property {string} [childId]
+ * @property {string} [lane] - one of 'one-shot' | 'continuable' | 'supervised'
+ * @property {string} [label]
+ * @property {string} persona - full persona text applied as the child's prefix section
+ * @property {{ allow?: string[], deny?: string[] }} [toolFilter] - requested child tool filter
+ */
+
+/**
+ * Mount the composition listener on one plugin ctx.
+ * @param {object} deps
+ * @param {any} deps.ctx - plugin context (on / tools)
+ * @param {(session: object | null, type: string, data?: unknown) => void} deps.audit - createAudit sink
+ * @param {{ warn?: (message: string) => void }} [deps.logger]
+ * @param {() => Set<string> | undefined} [deps.restrictableNames] - fallback composition view
+ * @param {(fact: { session?: object | null, childId: string, lane?: string }) => void} [deps.onSpawn] - live spawn-fact sink (supervision catalog cross-check)
+ * @returns {{ beginSpawn: (composition: SpawnComposition & { session?: object | null }) => { outcome: () => { ok: boolean, error?: Error }, forget: () => void }, dispose: () => void }}
+ */
+export function createChildComposition({ ctx, audit, logger, restrictableNames, onSpawn }) {
+  /** @type {Map<string, { session: object | null, childId: string, lane: string, label: string, persona: string, toolFilter?: object, applied: boolean, error?: Error }>} */
+  const pending = new Map()
+
+  /**
+   * Reserve one composition and write its cold-safe spawn fact. Called
+   * synchronously BEFORE startActivation: the child's creation window runs
+   * inside that call, so the entry is always present when the listener fires.
+   * @param {SpawnComposition & { session?: object | null }} composition
+   */
+  function beginSpawn(composition) {
+    const entry = {
+      session: composition.session ?? null,
+      childId: composition.childId,
+      lane: composition.lane ?? 'one-shot',
+      label: composition.label ?? '',
+      persona: composition.persona ?? '',
+      toolFilter: composition.toolFilter,
+      applied: false,
+      error: undefined,
+    }
+    pending.set(entry.childId, entry)
+    // Audit mirrors the fact to <cwd>/.weir/audit.jsonl (cold-safe replay) and
+    // emits it in-process. Never throws.
+    const fact = {
+      childId: entry.childId,
+      lane: entry.lane,
+      label: entry.label,
+      persona: entry.persona,
+      ...(entry.toolFilter ? { toolFilter: entry.toolFilter } : {}),
+    }
+    audit(entry.session, SPAWN_FACT_TYPE, fact)
+    // Live consumers (the supervision catalog cross-check) see the same fact
+    // without re-reading the file.
+    try {
+      onSpawn?.({ session: entry.session, childId: entry.childId, lane: entry.lane })
+    } catch {
+      // a live sink failure must never break the spawn
+    }
+    return {
+      outcome: () => (entry.applied
+        ? { ok: true }
+        : {
+            ok: false,
+            error: entry.error ?? new Error(`child "${entry.childId}": the composition was not applied inside the creation window`),
+          }),
+      forget: () => {
+        if (pending.get(entry.childId) === entry) pending.delete(entry.childId)
+      },
+    }
+  }
+
+  /** Apply a composition to one live child agent (throws on any failure). */
+  function apply(agent, composition) {
+    const systemPrompt = agent?.ctx?.systemPrompt
+    const tools = agent?.ctx?.tools
+    if (typeof composition.persona === 'string' && composition.persona.length > 0) {
+      if (typeof systemPrompt?.section !== 'function') {
+        throw new Error('the child agent exposes no systemPrompt service')
+      }
+      // Same section name the deployment/preset persona uses, so the child's
+      // own layer shadows it instead of duplicating a prompt paragraph.
+      systemPrompt.section({
+        name: PERSONA_PREFIX_SECTION,
+        order: systemPrompt.getSectionOrder(PERSONA_PREFIX_ORDER),
+        text: composition.persona,
+      })
+    }
+    const filter = composition.toolFilter
+    if (!filter) return
+    if (typeof tools?.restrict !== 'function') {
+      // An allow filter with no restriction channel would silently widen the
+      // child surface; the deny list is the safety floor. Fail closed.
+      throw new Error('the child agent exposes no tools service')
+    }
+    // tools.restrict() rejects unknown deny/allow names, so the deny list is
+    // merged against the CHILD scope's restrictable set (the composition's own
+    // view is only a fallback). childToolFilter keeps the existing merge
+    // semantics: allow-list filters pass through, every other filter gets
+    // CHILD_DENY_TOOLS intersected in, so the orchestrator-tool deny never
+    // degrades with the requested filter. The final deny list is then
+    // intersected with that same child set: a name the child scope never
+    // registered needs no deny (it is absent either way) and naming it would
+    // make restrict() throw.
+    const known = restrictableNamesOf(agent) ?? restrictableNames?.()
+    const merged = childToolFilter(filter, known)
+    const deny = Array.isArray(merged.deny) && known ? merged.deny.filter((name) => known.has(name)) : merged.deny
+    const effective = deny === merged.deny ? merged : { ...merged, deny }
+    const hasAllow = effective.allow !== undefined
+    const hasDeny = Array.isArray(effective.deny) && effective.deny.length > 0
+    if (!hasAllow && !hasDeny) return
+    tools.restrict(effective)
+  }
+
+  /** Resolve the child scope's restrictable tool names (undefined when unavailable). */
+  function restrictableNamesOf(agent) {
+    try {
+      const view = agent?.ctx?.tools?.view?.(agent)
+      if (view?.restrictableNames instanceof Set) return view.restrictableNames
+    } catch {
+      // view() failures fall back to the composition view
+    }
+    return undefined
+  }
+
+  /**
+   * Replay the composition of a cold-resumed child from the audit tail.
+   * @param {any} agent
+   * @param {object} header - the child session header
+   */
+  function replayFromAudit(agent, header) {
+    const file = auditFilePathOf(agent.session)
+    const records = readAuditTail(file)
+    if (records.length === 0) return
+    let fact
+    let parentManaged = false
+    for (const record of records) {
+      if (!record || typeof record !== 'object') continue
+      if (record.session !== header.parentSession) continue
+      if (typeof record.type !== 'string' || !record.type.startsWith('weir/')) continue
+      parentManaged = true
+      if (record.type === SPAWN_FACT_RECORD_TYPE && record.data?.childId === agent.id) fact = record.data
+    }
+    if (!parentManaged) return // not a weir-managed parent session: not our child
+    if (!fact) {
+      // Degraded: the spawn fact aged out of the tail (or the audit channel was
+      // unavailable). Persona and allow-lists stay unapplied, but the
+      // orchestrator-tool deny floor never does.
+      logger?.warn?.(`weir-delegate: child "${agent.id}" has no delegate/spawn fact in the audit tail — replaying the static orchestrator-tool deny floor only`)
+      applyDenyFloor(agent)
+      return
+    }
+    try {
+      apply(agent, fact)
+    } catch (error) {
+      logger?.warn?.(`weir-delegate: child "${agent.id}" composition replay failed (fail-open): ${String(error?.message ?? error)}`)
+      applyDenyFloor(agent)
+    }
+  }
+
+  /** Apply only the static orchestrator-tool deny floor (best-effort, warns). */
+  function applyDenyFloor(agent) {
+    try {
+      const known = restrictableNamesOf(agent) ?? restrictableNames?.()
+      const deny = known ? CHILD_DENY_TOOLS.filter((name) => known.has(name)) : [...CHILD_DENY_TOOLS]
+      if (deny.length === 0) return
+      agent.ctx.tools.restrict({ deny })
+    } catch (error) {
+      logger?.warn?.(`weir-delegate: child "${agent.id}" deny-floor application failed: ${String(error?.message ?? error)}`)
+    }
+  }
+
+  /**
+   * `agent/created` listener. A failure on the fresh-spawn path is thrown so
+   * the spawn call itself rejects (the runtime disposes the unpublished child
+   * after a rejected creation announcement); the recorded verdict lets the
+   * spawn's own fail-closed branch also catch a listener that never ran.
+   */
+  function onAgentCreated(payload) {
+    const agent = payload?.agent
+    const header = agent?.session?.header
+    if (!header) return
+    if ((header.delegationDepth ?? 0) < 1) return
+    const childId = agent.id
+    const entry = pending.get(childId)
+    if (entry) {
+      pending.delete(childId)
+      try {
+        apply(agent, entry)
+        entry.applied = true
+      } catch (error) {
+        entry.error = compositionError(childId, error)
+        throw entry.error
+      }
+      return
+    }
+    replayFromAudit(agent, header)
+  }
+
+  const off = ctx.on('agent/created', onAgentCreated)
+
+  return {
+    beginSpawn,
+    dispose: () => {
+      pending.clear()
+      off?.()
+    },
+  }
+}
+
+/** Wrap one composition failure with the delegate-facing cause. */
+function compositionError(childId, error) {
+  const wrapped = new Error(`delegate: failed to apply the child composition for "${childId}" — ${String(error?.message ?? error)}`)
+  wrapped.cause = error
+  return wrapped
+}