weir-harness 1.2.1 → 1.2.2

package/cordis.patch.yml

@@ -104,7 +104,6 @@
                 You are the Orchestrator, the user's single point of collaboration, powered by the {{model}} model.
                 You understand intent, decompose work, delegate to specialist sub-agents, choose parallel fan-out
                 or sequenced waiting, verify evidence, and report results.
-              suffix: Your working directory is {{cwd}}.
           - id: weir-core
             name: 'weir-harness/core'
           - id: agent-instructions
@@ -294,7 +293,6 @@
                 You are the Orchestrator, the user's single point of collaboration, powered by the {{model}} model.
                 You understand intent, decompose work, delegate to specialist sub-agents, choose parallel fan-out
                 or sequenced waiting, verify evidence, and report results.
-              suffix: Your working directory is {{cwd}}.
           - id: weir-core
             name: 'weir-harness/core'
           # Creative-only: how to use the fused tooling (inspection order,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weir-harness",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "description": "Weir \u2014 orchestrator-centric DSH agent preset: intent gate, category delegation, todo driver, pull-based background jobs, auto-compaction, hashline edit.",
   "license": "MIT",
@@ -28,8 +28,11 @@
     "whitelist-defaults.json",
     "icon.svg"
   ],
+  "engines": {
+    "dsh": ">=0.2.1-rc.1 <0.3.0"
+  },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.2.0-rc.2 <0.3.0"
+    "@deepseek-ai/dsh": ">=0.2.1-rc.1 <0.3.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/capabilities/skill-office-adapter.js

@@ -30,7 +30,13 @@ export function createOfficeAdapter(skills, machineId) {
     const observation = Array.isArray(output) ? { candidates: output, complete: true } : output
     const candidates = []
     for (const raw of observation.candidates) {
-      if (!OFFICE_NAMES.includes(raw.name) || raw.provider !== 'dsh-office' || raw.source !== 'bundled' || typeof raw.locator !== 'string') {
+      // DSH 0.2.1's office provider lists MORE bundled siblings than the three
+      // Weir composes (`office`, `office-render`, `office-recalculate`,
+      // `office-export-pdf`). This adapter only owns OFFICE_NAMES: a foreign
+      // sibling is skipped, never an error — while a candidate that CLAIMS one
+      // of our names with an unexpected shape still fails closed below.
+      if (!OFFICE_NAMES.includes(raw.name)) continue
+      if (raw.provider !== 'dsh-office' || raw.source !== 'bundled' || typeof raw.locator !== 'string') {
         throw new Error('Unsupported Office provider candidate')
       }
       const path = await realpath(raw.locator)

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
+}

package/src/delegate/group-coordinator.js

@@ -47,18 +47,31 @@ export function createGroupRecord(name, { sealed = false, settled = false, membe
 }
 
 /**
- * Single exit for the untracked-catalog predicate: continuable catalog entries
- * the registry does not track. mode is normalized (undefined → 'continuable');
- * the row shape is { id, label, mode }. `isTracked(id)` is the caller's lookup.
+ * Single exit for the untracked-catalog predicate: catalog children the
+ * supervision registry does not track AND no one-shot/continuable spawn fact
+ * claims. The row shape is { id, label, mode } (mode is passed through
+ * verbatim: DSH 0.2.1 reports every local child as 'continuable' and may also
+ * report 'external', so the catalog mode no longer discriminates lanes — the
+ * durable spawn facts do).
+ * `isTracked(id)` is the caller's registry lookup. `spawnFactOf(id)` returns
+ * the durable delegate/spawn fact for a weir-spawned child (lane included):
+ * one-shot and plain-continuable children must never be resurrected as
+ * supervision orphans, while a supervised child normally IS tracked and a
+ * supervised child missing from the fact chain stays visible as an orphan
+ * (never hidden). Only a fact-less orphan (not spawned by this weir build)
+ * keeps the promoted/recovered semantics.
+ * @param {object[]} entries - DSH catalog children
+ * @param {(id: string) => boolean} isTracked
+ * @param {(id: string) => { lane?: string } | undefined} [spawnFactOf]
  */
-export function untrackedCatalogEntries(entries, isTracked) {
+export function untrackedCatalogEntries(entries, isTracked, spawnFactOf) {
   const untracked = []
   for (const entry of entries ?? []) {
     if (!entry || typeof entry !== 'object') continue
-    const mode = entry.mode === undefined ? 'continuable' : entry.mode
-    if (mode !== 'continuable') continue
     if (isTracked(entry.id)) continue
-    untracked.push({ id: entry.id, label: entry.label ?? '', mode })
+    const lane = spawnFactOf?.(entry.id)?.lane
+    if (lane === 'one-shot' || lane === 'continuable') continue
+    untracked.push({ id: entry.id, label: entry.label ?? '', mode: entry.mode })
   }
   return untracked
 }
@@ -73,7 +86,8 @@ export function untrackedCatalogEntries(entries, isTracked) {
  * @param {(delayMs: number, fn: () => void) => void} deps.schedule - delayed retry scheduler
  * @param {(reason: string) => void} [deps.onAudit]
   * @param {(fact: object) => void} [deps.onFact] - structured supervision facts (durability)
-  * @param {(text: string) => void} [deps.notifyParent] - deliver a parent-facing signal (timer-deferred followup)
+ * @param {(text: string) => void} [deps.notifyParent] - deliver a parent-facing signal (timer-deferred followup)
+ * @param {(childId: string) => { lane?: string } | undefined} [deps.spawnFactOf] - durable delegate/spawn fact for one child id (lane decides orphan resurrection; see untrackedCatalogEntries)
   */
 export function createGroupCoordinator(deps, config = {}) {
   const cfg = { ...DEFAULT_SUPERVISION, ...config }
@@ -174,9 +188,9 @@ export function createGroupCoordinator(deps, config = {}) {
     }
   }
 
-  /** Catalog cross-check: continuable catalog entries this registry does not track. */
+  /** Catalog cross-check: catalog children this registry does not track (spawn-fact aware). */
   function untrackedAgainstCatalog(entries) {
-    return untrackedCatalogEntries(entries, (id) => children.has(id))
+    return untrackedCatalogEntries(entries, (id) => children.has(id), deps.spawnFactOf)
   }
 
   function noteAssistantText(childId, text) {

package/src/delegate/index.js

@@ -18,6 +18,7 @@ import { createDelegateTool } from './tool.js'
 import { attachWorktreeModeGuard } from './worktree-mode.js'
 import { DOCTRINE_SECTION_ORDER } from '../core/doctrine.js'
 import { isDelegatedChild } from '../shared/child-scope.js'
+import { createChildComposition } from './child-composition.js'
 import {
   DELEGATE_TARGETS_SECTION_NAME,
   DELEGATE_TARGETS_SECTION_ORDER_OFFSET,
@@ -97,6 +98,20 @@ function apply(ctx, config = {}) {
     onAdaptersUpdated: (fn) => ctx.on('llm/adapters-updated', fn),
   })
 
+  // Creation-window child composition (DSH 0.2.1 removed the request-level
+  // persona/toolFilter): the shim applies the reserved spawn's composition in
+  // the child's agent/created window and replays it from the audit channel on
+  // cold resume. One instance per plugin context; dispose unregisters it.
+  const composition = createChildComposition({
+    ctx,
+    audit,
+    logger: ctx.logger,
+    restrictableNames: () => ctx.tools.view?.(undefined)?.restrictableNames,
+    // Feed the supervision catalog cross-check the same durable fact without a
+    // file re-read (spawn-fact lane decides orphan resurrection).
+    onSpawn: mount.noteSpawnFact,
+  })
+
   ctx.tools.register(
     createDelegateTool({
       resolveTarget: targetResolver.resolveTarget,
@@ -114,6 +129,7 @@ function apply(ctx, config = {}) {
       // names, so the child deny list names only tools this composition
       // actually registers (tools.restrict() rejects unknown deny names).
       restrictableNames: () => ctx.tools.view?.(undefined)?.restrictableNames,
+      composition,
     }),
   )
 
@@ -165,6 +181,7 @@ function apply(ctx, config = {}) {
   return () => {
     offModeGuard()
     mount.dispose()
+    composition.dispose()
   }
 }
 

package/src/delegate/rehydrate.js

@@ -9,21 +9,37 @@ import { parseTerminalStatus, isTerminalStatus } from '../shared/terminal-eviden
  * Rebuild supervision state by replaying structured audit facts and
  * cross-checking the DSH subagent catalog.
  *
+ * Two fact channels ride the same audit file: the supervision facts
+ * (`weir/supervision/<kind>`) and the child-composition spawn facts
+ * (`weir/delegate/spawn`, which carry the lane). The spawn facts decide which
+ * catalog children are supervision orphans — DSH 0.2.1 reports every local
+ * child as mode 'continuable', so the catalog mode can no longer tell a
+ * one-shot child from a supervised one.
+ *
  * @param {object} input
  * @param {string} input.parentId - the parent session id (record filter key)
  * @param {object[]} input.records - parsed audit JSONL records (already tail-read; may contain other sessions/types)
  * @param {object[]} input.catalogChildren - DSH catalog entries ({ id, label?, mode? }); best-effort
- * @returns {{ children: object[], groups: object[], untracked: object[], confidence: 'full'|'partial', factsSeen: number }}
+ * @returns {{ children: object[], groups: object[], untracked: object[], spawnFacts: object[], confidence: 'full'|'partial', factsSeen: number }}
  */
 export function rehydrateSupervision({ parentId, records, catalogChildren }) {
   const children = new Map()
   const groups = new Map()
+  /** @type {Map<string, { childId: string, lane?: string }>} */
+  const spawnFacts = new Map()
   let factsSeen = 0
 
   for (const record of records ?? []) {
     if (!record || typeof record !== 'object') continue
     if (record.session !== undefined && record.session !== null && record.session !== parentId) continue
     const type = typeof record.type === 'string' ? record.type : ''
+    if (type === 'weir/delegate/spawn') {
+      const fact = record.data
+      if (fact && typeof fact === 'object' && typeof fact.childId === 'string' && fact.childId.length > 0) {
+        spawnFacts.set(fact.childId, { childId: fact.childId, lane: typeof fact.lane === 'string' ? fact.lane : undefined })
+      }
+      continue
+    }
     if (!type.startsWith('weir/supervision/')) continue
     const fact = record.data
     if (!fact || typeof fact !== 'object' || typeof fact.kind !== 'string') continue
@@ -37,13 +53,16 @@ export function rehydrateSupervision({ parentId, records, catalogChildren }) {
     group.settled = group.sealed === true && group.memberIds.length > 0 && terminal
   }
 
-  // Catalog cross-check: continuable children the registry does not track.
-  const untracked = untrackedCatalogEntries(catalogChildren, (id) => children.has(id))
+  // Catalog cross-check: only fact-less orphans remain untracked (the spawn
+  // facts identify the one-shot/continuable children this registry must never
+  // resurrect, and keep a supervised child whose fact chain is broken visible).
+  const untracked = untrackedCatalogEntries(catalogChildren, (id) => children.has(id), (id) => spawnFacts.get(id))
 
   return {
     children: [...children.values()],
     groups: [...groups.values()],
     untracked,
+    spawnFacts: [...spawnFacts.values()],
     confidence: factsSeen > 0 ? 'full' : 'partial',
     factsSeen,
   }

package/src/delegate/spawn-adapter.js

@@ -1,15 +1,22 @@
 // Spawn adapter: the single site where a delegation becomes a started, guarded
-// child (design D1-D5). Request assembly, the maxDepth: 1 topology guarantee,
-// guard-attach order, and fail-closed teardown each live exactly once here;
-// the lanes differ only through the strategy knobs of the lane object
-// (start shape, toolFilter/persona transforms, guard handle path, teardown,
-// register ordering). Orchestration — escalation, job wrapping, group
-// two-phase/rollback/seal — stays in tool.js; this module only spawns.
+// child (design D1-D5). Activation assembly, the maxDepth: 1 topology
+// guarantee, guard-attach order, and fail-closed teardown each live exactly
+// once here; the lanes differ only through the strategy knobs of the lane
+// object (delivery policy, toolFilter/persona transforms, guard handle path,
+// teardown, register ordering). Orchestration — escalation, job wrapping,
+// group two-phase/rollback/seal — stays in tool.js; this module only spawns.
 //
-// Invariant: spawnGuardedChild returns only a started child whose read-only
-// guard is attached (or whose disabled-snapshot skip applies); a guard failure
-// always tears the child down and throws. Callers can never receive a
-// read-only child running unguarded.
+// DSH 0.2.1 single start entry: subagents.startActivation(spec) with
+// { provider, label, childId?, request, signal, delivery }. The request no
+// longer carries label/signal/persona/toolFilter: the caller reserves the
+// childId, and the persona + tool filter ride the creation-window composition
+// shim (child-composition.js) registered synchronously before the start.
+//
+// Invariant: spawnGuardedChild returns only a started child whose composition
+// was applied and whose read-only guard is attached (or whose disabled-snapshot
+// skip applies); a failure at either step always tears the child down and
+// throws. Callers can never receive an uncomposed or unguarded child.
+import { randomUUID } from 'node:crypto'
 import { SUPERVISION_CONTRACT } from './group-coordinator.js'
 import { attachReadOnlyBashGuard } from './robash-guard.js'
 import { attachLaneGuard } from '../worktree/guard.js'
@@ -28,45 +35,88 @@ import { CONTINUABLE_CONTRACT, WORKER_CONTRACT, childToolFilter } from '../share
 /**
  * Lane strategy: every genuine per-lane difference as an injected knob.
  * @typedef {object} SpawnLane
- * @property {(deps: object, request: object) => Promise<object>} start - provider start call (lane-native shape)
+ * @property {string} laneName - 'one-shot' | 'supervised' | 'continuable' (spawn fact + diagnostics)
+ * @property {'parent' | 'caller'} delivery - runtime settlement policy: 'parent' notifies the model, 'caller' only returns the result
  * @property {(toolFilter: object | undefined) => object | undefined} toolFilterFor - toolFilter transform
  * @property {(target: object) => string} personaFor - persona decoration
  * @property {(started: object, target: object) => void} [beforeGuardAttach] - runs before any guard code (supervised: registerMember)
  * @property {(started: object, deps: object) => object} guardHandleFor - live agent handle for the guard
- * @property {(error: unknown, started: object) => never} onGuardFailure - fail-closed teardown (lane-native mechanism)
+ * @property {(error: unknown, started: object) => never | Promise<never>} onGuardFailure - fail-closed teardown (lane-native mechanism)
+ * @property {boolean} [cancelOnAbort] - tear the published child down when the spawn signal aborts (one-shot lanes)
  */
 
 /**
- * Spawn one child and attach its read-only guard before returning.
+ * Spawn one child, apply its composition, and attach its read-only guard before
+ * returning.
  * @param {SpawnAssignment} assignment
  * @param {SpawnLane} lane
- * @param {object} deps - DelegateDeps subset { subagents, robash, agents, restrictableNames? }
- * @returns {Promise<object>} the lane-native started handle (one-shot →
- *   SubagentRun { id, localAgent, result, dispose }; supervised → { childId, messageId })
+ * @param {object} deps - DelegateDeps subset { subagents, robash, agents, restrictableNames?, composition?, reserveChildId? }
+ * @returns {Promise<{ id: string, childId: string, agent?: object, result: Promise<object>, dispose: () => Promise<void> | void, messageId?: string }>}
+ *   the normalized handle: `id` aliases the durable child id, `agent` is the
+ *   live child agent captured at spawn (0.2.1 resolves `result` only after
+ *   teardown, so the handle must be captured now).
  */
 export async function spawnGuardedChild(assignment, lane, deps) {
   const { target } = assignment
-  // Single request-assembly point (D3): the four near-verbatim literals of the
-  // pre-refactor lanes converge here; lane hooks absorb the per-lane
+  // Single activation-assembly point (D3): the four near-verbatim literals of
+  // the pre-refactor lanes converge here; lane hooks absorb the per-lane
   // transforms; maxDepth: 1 (children never delegate further) has this one site.
   // The child tool catalog restriction applies AFTER the lane transform:
   // allow-list filters (curated read-only targets) pass through unchanged;
   // every other filter gets CHILD_DENY_TOOLS merged in (intersected with the
   // composition's restrictable names — tools.restrict() rejects unknown deny
   // names), so no spawned child can see orchestrator-only tools.
+  const label = assignment.label ?? target.label
   const toolFilter = childToolFilter(lane.toolFilterFor(target.toolFilter), deps.restrictableNames?.())
-  const request = {
-    label: assignment.label ?? target.label,
-    prompt: assignment.prompt,
-    parent: assignment.parent,
-    signal: assignment.signal,
-    ...(target.agentOptions ? { agentOptions: target.agentOptions } : {}),
+  const persona = lane.personaFor(target)
+  // Every spawn reserves its child id (0.2.1 lets the caller do this): the
+  // composition registration is keyed by it, the continuable/supervised lanes
+  // get their messageId back through it, and handle normalization is exact.
+  const childId = deps.reserveChildId?.() ?? randomUUID()
+  // Register the pending composition BEFORE the start call: the child's
+  // creation window (agent/created) runs inside startActivation, so this entry
+  // is always present when the listener fires (no race).
+  const registration = deps.composition?.beginSpawn({
+    session: assignment.parent?.session ?? null,
+    childId,
+    lane: lane.laneName,
+    label,
+    persona,
     ...(toolFilter ? { toolFilter } : {}),
-    maxDepth: 1,
-    persona: lane.personaFor(target),
+  })
+  let raw
+  try {
+    raw = await deps.subagents.startActivation({
+      provider: 'spawn',
+      label,
+      childId,
+      request: {
+        prompt: assignment.prompt,
+        parent: assignment.parent,
+        ...(target.agentOptions ? { agentOptions: target.agentOptions } : {}),
+        maxDepth: 1,
+      },
+      signal: assignment.signal,
+      delivery: lane.delivery,
+    })
+  } catch (error) {
+    registration?.forget()
+    throw error
+  }
+  const started = normalizeStarted(raw, childId, deps)
+  // Fail-closed composition gate: a child whose persona/deny list did not land
+  // inside its creation window is torn down instead of running uncomposed or
+  // with the orchestrator-tool deny list missing.
+  const outcome = registration?.outcome()
+  if (outcome && !outcome.ok) {
+    registration.forget()
+    try {
+      await started.dispose?.()
+    } catch {
+      // best-effort teardown of the uncomposed child
+    }
+    throw outcome.error
   }
-  const started = await lane.start(deps, request)
-
   // Unified guard core (D5), in contract order: the lane's pre-guard hook runs
   // BEFORE any guard code (the supervised register-before-guard ordering, once
   // a comment-level contract, is now structural); the handle is resolved
@@ -75,79 +125,149 @@ export async function spawnGuardedChild(assignment, lane, deps) {
   // snapshot skips BOTH lanes silently (resolveTarget already withheld the
   // shell tool in that snapshot, so there is no shell surface left to guard).
   lane.beforeGuardAttach?.(started, target)
-  if (!target.readOnly && !assignment.laneGuard) return started
-  const handle = lane.guardHandleFor(started, deps)
-  if (target.readOnly) {
-    // deps.robash is a live resolver (the settings overlay can change between
-    // delegations), so resolve it once here: the enabled check and the lists
-    // handed to the guard must describe the same committed snapshot.
-    const robash = deps.robash?.()
-    // robash.lists carries both list sets ({ bash, pwsh }); the guard
-    // dispatches on execution.name.
-    if (robash?.enabled) {
+  if (target.readOnly || assignment.laneGuard) {
+    const handle = lane.guardHandleFor(started, deps)
+    if (target.readOnly) {
+      // deps.robash is a live resolver (the settings overlay can change between
+      // delegations), so resolve it once here: the enabled check and the lists
+      // handed to the guard must describe the same committed snapshot.
+      const robash = deps.robash?.()
+      // robash.lists carries both list sets ({ bash, pwsh }); the guard
+      // dispatches on execution.name.
+      if (robash?.enabled) {
+        try {
+          attachReadOnlyBashGuard(handle, robash.lists)
+        } catch (error) {
+          await lane.onGuardFailure(error, started)
+        }
+      }
+    }
+    // A lane-bound child additionally gets the lane guard (workdir, write
+    // paths/scope, branch-moving git) — same fail-closed teardown: a bound
+    // child never runs without it.
+    if (assignment.laneGuard) {
       try {
-        attachReadOnlyBashGuard(handle, robash.lists)
+        attachLaneGuard(handle, assignment.laneGuard)
       } catch (error) {
-        lane.onGuardFailure(error, started)
+        await lane.onGuardFailure(error, started)
       }
     }
   }
-  // A lane-bound child additionally gets the lane guard (workdir, write
-  // paths/scope, branch-moving git) — same fail-closed teardown: a bound
-  // child never runs without it.
-  if (assignment.laneGuard) {
+  // 0.2.1's activation signal is PRE-PUBLICATION cancellation only ("callers
+  // own later cancellation through dispose"); 0.2.0's in-process driver used
+  // to cancel a published child when its request signal aborted. The one-shot
+  // lanes keep that contract explicitly: aborting the tool call tears the
+  // child down (and its turn ends aborted, kind 'parent'), so a stopped
+  // parent never leaves a child running. Continuable/supervised lanes are
+  // deliberately NOT wired: their children outlive the call that started them.
+  // Wired last so a signal already aborted at spawn still leaves a fully
+  // guarded, fully composed child to tear down (never an unwired one).
+  if (lane.cancelOnAbort) wireAbortCancellation(assignment.signal, started)
+  return started
+}
+
+/**
+ * Cancel a published child when its spawn signal aborts (the 0.2.0 in-process
+ * driver contract, now caller-owned). `dispose()` is the 0.2.1 teardown that
+ * synchronously cancels the child agent (turn end: aborted, kind 'parent'), so
+ * a stopped parent never leaves a running child behind.
+ * @param {AbortSignal | undefined} signal
+ * @param {{ dispose?: () => Promise<void> | void }} started
+ */
+function wireAbortCancellation(signal, started) {
+  if (!signal || typeof started?.dispose !== 'function') return
+  let fired = false
+  const cancel = () => {
+    if (fired) return
+    fired = true
     try {
-      attachLaneGuard(handle, assignment.laneGuard)
-    } catch (error) {
-      lane.onGuardFailure(error, started)
+      void Promise.resolve(started.dispose()).catch(() => {})
+    } catch {
+      // best-effort teardown of the cancelled child
     }
   }
-  return started
+  if (signal.aborted) {
+    cancel()
+    return
+  }
+  signal.addEventListener('abort', cancel, { once: true })
 }
 
 /**
- * One-shot lane: subagents.start('spawn', request) with the caller's
- * toolFilter untouched (the child deny-list merge happens once in
- * spawnGuardedChild) and the persona extended by WORKER_CONTRACT. Serves the
- * foreground, background (inside the job wrapper), and escalation respawn
- * sites — identical spawn semantics, only the assignment fields
- * (parent/signal/label) differ.
+ * Normalize a SubagentActivation into the handle the lanes and tool.js use:
+ * `{ id, childId, agent, result, dispose }`. The live child agent must be
+ * captured here — 0.2.1 resolves `result` only after the activation is
+ * disposed, so no post-settlement lookup can reach it.
+ * @param {object} raw - SubagentActivation ({ childId, messageId?, result, dispose() })
+ * @param {string} reservedChildId - the caller-reserved child id
+ * @param {object} deps
+ */
+function normalizeStarted(raw, reservedChildId, deps) {
+  const childId = typeof raw?.childId === 'string' ? raw.childId : reservedChildId
+  let agent
+  try {
+    agent = deps.agents?.get?.(childId)
+  } catch {
+    agent = undefined
+  }
+  return {
+    id: childId,
+    childId,
+    agent: agent ?? raw?.agent,
+    result: raw?.result,
+    dispose: () => (typeof raw?.dispose === 'function' ? raw.dispose() : Promise.resolve()),
+    ...(raw?.messageId !== undefined ? { messageId: raw.messageId } : {}),
+  }
+}
+
+/**
+ * One-shot lane: startActivation with delivery 'caller' — the caller awaits
+ * the result itself and no runtime parent notice is sent (the jobs wrapper /
+ * the tool result is the report channel). The persona carries
+ * WORKER_CONTRACT. Serves the foreground, background (inside the job wrapper),
+ * and escalation respawn sites — identical spawn semantics, only the
+ * assignment fields (parent/signal/label) differ.
  * @returns {SpawnLane}
  */
 export function oneShotLane() {
   return {
-    start: (deps, request) => deps.subagents.start('spawn', request),
+    laneName: 'one-shot',
+    delivery: 'caller',
+    // Aborting the tool call tears the child down (0.2.0 driver contract, see
+    // wireAbortCancellation): only the one-shot lanes own the call window.
+    cancelOnAbort: true,
     toolFilterFor: (toolFilter) => toolFilter,
     personaFor: (target) => target.persona + WORKER_CONTRACT,
-    // S7 SubagentRun shape: the live agent handle rides the started run.
-    guardHandleFor: (started) => started.localAgent,
-    onGuardFailure(error, started) {
+    // The composition shim captures the live agent at spawn; no post-hoc lookup.
+    guardHandleFor: (started) => started.agent,
+    async onGuardFailure(error, started) {
       // A read-only child must never run unguarded: tear it down and fail loud.
-      started.dispose()
+      try {
+        await started.dispose?.()
+      } catch {
+        // best-effort teardown of the unguarded child
+      }
       throw new Error(`delegate: failed to attach the read-only bash guard — ${String(error?.message ?? error)}`)
     },
   }
 }
 
 /**
- * Supervised lane: startContinuable with the worker + status contracts
- * appended to the persona (SUPERVISION_CONTRACT stays last) and send_message
- * denied, plus register-before-guard ordering.
- * Teardown deliberately differs from the one-shot lane: continuable handles
- * have no dispose, so a guard failure rethrows as-is and the lane-level
- * rollback in tool.js terminates the member through the coordinator (which
- * keeps the registry bookkeeping in sync).
+ * Supervised lane: startActivation with delivery 'parent' (the built-in
+ * settlement notice is the supervising parent's report channel and the
+ * ordering-gate input), the worker + status contracts appended to the persona
+ * (SUPERVISION_CONTRACT stays last) and send_message denied, plus
+ * register-before-guard ordering.
+ * Teardown: a guard failure annotates the exact child id and rethrows, so the
+ * lane-level rollback in tool.js terminates the member through the coordinator
+ * (which keeps the registry bookkeeping in sync).
  * @param {{ coordinator: object, groupName: string, members: Array<object> }} group
  * @returns {SpawnLane}
  */
 export function supervisedLane({ coordinator, groupName, members }) {
   return {
-    // startContinuable takes label/signal beside the request, not inside it
-    // (provider API shape).
-    start: (deps, request) => {
-      const { label, signal, ...rest } = request
-      return deps.subagents.startContinuable({ provider: 'spawn', label, request: rest, signal })
-    },
+    laneName: 'supervised',
+    delivery: 'parent',
     toolFilterFor: supervisedToolFilter,
     personaFor: (target) => target.persona + WORKER_CONTRACT + SUPERVISION_CONTRACT,
     beforeGuardAttach(started, target) {
@@ -156,11 +276,10 @@ export function supervisedLane({ coordinator, groupName, members }) {
       const member = coordinator.registerMember({ id: started.childId, name: target.label, group: groupName })
       members.push({ id: started.childId, name: target.label, member })
     },
-    // startContinuable returns { childId, messageId } (no localAgent), so the
-    // read-only shell guard attaches through the live agent handle — same
-    // guard, same fail-closed semantics as the one-shot lane.
-    guardHandleFor(started, deps) {
-      const childAgent = deps.agents?.get(started.childId)
+    // The live agent captured at spawn is the guard handle (same guard, same
+    // fail-closed semantics as the one-shot lane).
+    guardHandleFor(started) {
+      const childAgent = started.agent
       if (!childAgent) throw new Error(`delegate: read-only supervised member spawned but no live agent handle is available for "${started.childId}"`)
       return childAgent
     },
@@ -172,38 +291,33 @@ export function supervisedLane({ coordinator, groupName, members }) {
 
 /**
  * Continuable lane (design D2/D3/D7): an opt-in `mode: 'continuable'` child
- * that starts via startContinuable and returns immediately; its results
- * arrive through the runtime's built-in settlement notices. The persona
- * carries WORKER_CONTRACT + CONTINUABLE_CONTRACT — NEVER SUPERVISION_CONTRACT:
- * no binary terminal-status contract, no coordinator registration, no
- * supervision bookkeeping (an untracked entry in supervised_status is the
- * normal state, not an anomaly). The child→parent channel stays closed the
- * same way as every lane: send_message is already in CHILD_DENY_TOOLS, which
- * the single assembly point merges, so toolFilterFor is the identity.
+ * that starts through startActivation (delivery 'parent') and returns
+ * immediately; its results arrive through the runtime's built-in settlement
+ * notices. The persona carries WORKER_CONTRACT + CONTINUABLE_CONTRACT — NEVER
+ * SUPERVISION_CONTRACT: no binary terminal-status contract, no coordinator
+ * registration, no supervision bookkeeping (an untracked entry in
+ * supervised_status is the normal state, not an anomaly). The child→parent
+ * channel stays closed the same way as every lane: send_message is already in
+ * CHILD_DENY_TOOLS, which the single assembly point merges, so toolFilterFor is
+ * the identity.
  *
- * Teardown matches the supervised lane: continuable handles have no dispose,
- * so a guard failure rethrows the original error with the child id attached;
- * the catch side in tool.js then best-effort interrupts the residual child
- * before propagating (the error names the child id, so the parent can
+ * Teardown: a guard failure rethrows the original error with the child id
+ * attached; the catch side in tool.js then best-effort interrupts the residual
+ * child before propagating (the error names the child id, so the parent can
  * dispose of it explicitly).
  * @returns {SpawnLane}
  */
 export function continuableLane() {
   return {
-    // startContinuable takes label/signal beside the request, not inside it
-    // (provider API shape) — same start shape as the supervised lane.
-    start: (deps, request) => {
-      const { label, signal, ...rest } = request
-      return deps.subagents.startContinuable({ provider: 'spawn', label, request: rest, signal })
-    },
+    laneName: 'continuable',
+    delivery: 'parent',
     toolFilterFor: (toolFilter) => toolFilter,
     personaFor: (target) => target.persona + WORKER_CONTRACT + CONTINUABLE_CONTRACT,
     // No beforeGuardAttach: nothing registers anywhere on this lane.
-    // startContinuable returns { childId, messageId } (no localAgent), so the
-    // read-only shell guard attaches through the live agent handle — same
-    // guard, same fail-closed semantics as the other lanes.
-    guardHandleFor(started, deps) {
-      const childAgent = deps.agents?.get(started.childId)
+    // The live agent captured at spawn is the guard handle (same guard, same
+    // fail-closed semantics as the other lanes).
+    guardHandleFor(started) {
+      const childAgent = started.agent
       if (!childAgent) {
         const error = new Error(`delegate: read-only continuable child spawned but no live agent handle is available for "${started.childId}"`)
         error.childId = started.childId

package/src/delegate/status-tool.js

@@ -19,7 +19,7 @@ export function digestReport(report, max = 200) {
 export function createStatusTool(deps) {
   return {
     name: 'supervised_status',
-    description: `Render the supervised-child registry of this session: per child the id, name, group, status (running/blocked/completed/terminated), retries, and a truncated report digest; per group the member count and sealed/settled state; plus continuable children in the DSH subagent catalog that this coordinator does not track (flagged untracked). Main agent only. Member report bodies live in the built-in settlement notices and the registry digest; respond to a blocked member with resume_agent or terminate_agent.`,
+    description: `Render the supervised-child registry of this session: per child the id, name, group, status (running/blocked/completed/terminated), retries, and a truncated report digest; per group the member count and sealed/settled state; plus delegated children in the DSH subagent catalog that this coordinator does not track and no spawn fact claims (flagged untracked; the catalog mode is reported verbatim and may be 'continuable' or 'external'). Main agent only. Member report bodies live in the built-in settlement notices and the registry digest; respond to a blocked member with resume_agent or terminate_agent.`,
     parameters: {
       type: 'object',
       properties: {},
@@ -66,8 +66,9 @@ export function collectStatus(coordinator) {
 }
 
 /**
- * Cross-check the DSH catalog: continuable children not tracked by the
- * coordinator are supervision orphans and must be surfaced, never hidden.
+ * Cross-check the DSH catalog: delegated children not tracked by the
+ * coordinator (and not claimed by a spawn fact) are supervision orphans and
+ * must be surfaced, never hidden.
  * @returns {Promise<object[] | null>} untracked rows, or null when the catalog is unavailable
  */
 export async function catalogUntracked(coordinator, parentId, listChildren) {
@@ -111,11 +112,13 @@ export function renderStatus(value) {
   if (value.untracked === null) {
     lines.push('Untracked-catalog cross-check unavailable (DSH catalog read failed).')
   } else if (value.untracked.length === 0) {
-    lines.push('No untracked continuable children in the DSH catalog.')
+    lines.push('No untracked delegated children in the DSH catalog.')
   } else {
-    lines.push('Untracked continuable children in the DSH catalog (not supervised by this registry):')
+    lines.push('Untracked delegated children in the DSH catalog (not supervised by this registry and not spawned by this session):')
     for (const entry of value.untracked) {
-      lines.push(`- ${entry.id} — label "${entry.label}" — mode ${entry.mode}`)
+      // The catalog mode is reported verbatim: DSH 0.2.1 reports every local
+      // child as 'continuable' and may also report 'external'.
+      lines.push(`- ${entry.id} — label "${entry.label}" — mode ${entry.mode ?? 'unknown'}`)
     }
   }
   return lines.join('\n')

package/src/delegate/supervision-mount.js

@@ -20,12 +20,34 @@ import { withSupervisedEditResume, settleDelegateEditLifecycle } from '../shared
  * @param {any} deps.settings - weirSettings service handle (absent = no commit push)
  * @param {() => object} deps.supervisionNow - overlay getter for supervision tuning
  * @param {(childId: string, parent: object) => void} [deps.onChildSettled] - a member reached a terminal fact (worktree lane settlement)
- * @returns {{ coordinatorFor: (parent: object) => Promise<object>, dispose: () => void }}
+ * @returns {{ coordinatorFor: (parent: object) => Promise<object>, noteSpawnFact: (fact: { session?: object | null, childId: string, lane?: string }) => void, dispose: () => void }}
  */
 export function mountSupervision({ ctx, audit, settings, supervisionNow, onChildSettled }) {
   // Supervised group coordinators, one per parent session.
   /** @type {Map<string, { coordinator: object, parent: object }>} */
   const coordinators = new Map()
+  // Durable delegate/spawn facts per parent session (childId → { lane }): the
+  // catalog cross-check consults them because DSH 0.2.1 reports every local
+  // child as mode 'continuable' (see untrackedCatalogEntries). Live spawns
+  // register through noteSpawnFact; a restart rebuild fills the same map from
+  // the rehydrated state.
+  /** @type {Map<string, Map<string, { childId: string, lane?: string }>>} */
+  const spawnFacts = new Map()
+  function spawnFactsFor(parentId) {
+    let facts = spawnFacts.get(parentId)
+    if (!facts) {
+      facts = new Map()
+      spawnFacts.set(parentId, facts)
+    }
+    return facts
+  }
+  /** Record one child-composition spawn fact (live spawn or rehydrated). */
+  function noteSpawnFact(fact) {
+    const parentId = fact?.session?.id
+    if (typeof parentId !== 'string' || parentId.length === 0) return
+    if (typeof fact.childId !== 'string' || fact.childId.length === 0) return
+    spawnFactsFor(parentId).set(fact.childId, { childId: fact.childId, lane: typeof fact.lane === 'string' ? fact.lane : undefined })
+  }
   // STATUS/turn-end is a bookkeeping fact, never proof the driver stopped.
   // This gate exists even when Edit Lock is disabled in the composition.
   const quiescence = new Map()
@@ -121,12 +143,18 @@ export function mountSupervision({ ctx, audit, settings, supervisionNow, onChild
             }
             deliver(1)
           },
+          // Lane decisions for the catalog cross-check come from the durable
+          // delegate/spawn facts (live-registered + rehydrated below).
+          spawnFactOf: (childId) => spawnFacts.get(parent.id)?.get(childId),
         },
         supervisionNow(),
       )
       // Restart rebuild: replay durable facts, cross-check the DSH catalog.
       const state = await rehydrateForParent(parent)
       coordinator.hydrate(state)
+      // Spawn facts ride the same tail: they decide which catalog children are
+      // orphans (one-shot/continuable children are never resurrected).
+      for (const fact of state.spawnFacts ?? []) noteSpawnFact({ session: parent.session, childId: fact.childId, lane: fact.lane })
       entry = { coordinator, parent }
       coordinators.set(parent.id, entry)
     }
@@ -209,5 +237,5 @@ export function mountSupervision({ ctx, audit, settings, supervisionNow, onChild
     offSettings?.()
   }
 
-  return { coordinatorFor, dispose }
+  return { coordinatorFor, noteSpawnFact, dispose }
 }

package/src/delegate/tool.js

@@ -48,6 +48,8 @@ Children cannot delegate further. Curated agents are read-only and never write f
  * @property {object | undefined} agents - ctx.agents (live agent lookup by child id)
  * @property {() => any} [lanes] - live getter for the weirWorktreeLanes service (absent = no lane support)
  * @property {() => Set<string> | undefined} [restrictableNames] - live resolver for the composition's restrictable tool names (ctx.tools.view); intersects CHILD_DENY_TOOLS at spawn because tools.restrict() rejects unknown deny names
+ * @property {{ beginSpawn: (composition: object) => { outcome: () => { ok: boolean, error?: Error }, forget: () => void } }} [composition] - the creation-window composition shim (child-composition.js): the reserved childId's persona/toolFilter are registered before startActivation and applied by the agent/created listener
+ * @property {() => string} [reserveChildId] - child-id minter override (tests); defaults to crypto.randomUUID
  */
 
 /**
@@ -321,7 +323,7 @@ async function settledResult(started, parent) {
   try { return await started.result } finally {
     // subagent/end is emit, not an awaited barrier. Explicitly join the
     // incarnation's standard edit disposition before result/escalation/handoff.
-    await settleDelegateEditLifecycle(parent, started.id, started.localAgent)
+    await settleDelegateEditLifecycle(parent, started.id, started.agent)
   }
 }
 /** Await one child, honoring the one-level ESCALATE contract. */

package/src/process/index.js

@@ -83,13 +83,22 @@ export function extraBinDirectories(env = process.env, platform = process.platfo
  * User-writable npm global prefix for panel installs: `npm --prefix <dir>
  * install -g …` lands servers here instead of a possibly root-owned global
  * prefix, and this directory is already part of the extended scan.
+ *
+ * `create` is a test seam: the win32 layout assertion must be runnable on any
+ * host WITHOUT materializing a literal `C:\Users\...` directory in the
+ * process CWD (the artifact that used to pollute the package directory after
+ * every unit run). Production callers keep the default (create the prefix).
+ * @param {Record<string, string | undefined>} [env]
+ * @param {string} [platform] - 'win32' | 'darwin' | 'linux' (process.platform values)
+ * @param {{ create?: boolean }} [options]
+ * @returns {string}
  */
-export function npmGlobalPrefix(env = process.env, platform = process.platform) {
+export function npmGlobalPrefix(env = process.env, platform = process.platform, options = {}) {
   const home = env.HOME ?? homedir()
   const prefix = platform === 'win32'
     ? join(env.APPDATA ?? join(home, 'AppData', 'Roaming'), 'npm')
     : join(home, '.npm-global')
-  mkdirSync(prefix, { recursive: true })
+  if (options.create !== false) mkdirSync(prefix, { recursive: true })
   return prefix
 }
 

package/src/shared/audit.js

@@ -44,6 +44,10 @@ export const AUDIT_TYPES = Object.freeze({
   // that had waiting subscribers; the emission lives in the blackboard plugin
   // and never touches a session log.
   blackboard: 'blackboard',
+  // Child-composition spawn facts (DSH 0.2.1 delegate shim): one record per
+  // spawn carrying the composition the child's creation window applies, so a
+  // host restart can replay it — the shim itself is runtime-only state.
+  delegate: 'delegate',
 })
 /**
  * Known dynamic sub-event kinds: `<type>/<kind>` events emitted beside a base
@@ -58,6 +62,9 @@ export const AUDIT_SUBTYPES = Object.freeze({
   // family, plus reconciliation reports.
   worktree: Object.freeze(['open', 'setup', 'bind', 'checked', 'check', 'invalidate', 'ask', 'decline', 'conflict', 'land', 'cleanup', 'abandon', 'reconcile', 'watch']),
   blackboard: Object.freeze(['released']),
+  // Child-composition spawn facts: one record per spawn, replayed on cold
+  // resume from this same channel (audit only — never a session log).
+  delegate: Object.freeze(['spawn']),
 })
 
 /**

package/src/shared/child-scope.js

@@ -59,7 +59,9 @@ export const CHILD_DENY_TOOLS = [
  * returned unchanged — allow semantics stay untouched. Deny-list or absent
  * filters get CHILD_DENY_TOOLS merged in, deduped. Same merge pattern as
  * supervisedToolFilter in src/delegate/spawn-adapter.js, applied AFTER the
- * lane transform at the single request-assembly point.
+ * lane transform at the single activation-assembly point, and re-applied by
+ * the DSH 0.2.1 creation-window shim (src/delegate/child-composition.js) with
+ * the CHILD scope's restrictable names before tools.restrict().
  *
  * DSH's tools.restrict() REJECTS deny names the composition never registered
  * (e.g. ask_user_question/present/edit_lock_* are absent from a headless