weir-harness 1.2.1 → 1.2.3

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/intent-gate/matcher.js

@@ -20,6 +20,7 @@ export function stripQuotedRegions(text) {
  * @property {string} id
  * @property {RegExp[]} patterns - compiled matchers
  * @property {boolean} oncePerSession
+ * @property {string} [summary] - one-line catalog description for the semantic classifier
  * @property {{ kind: 'skill-pointer', skill: string }
  *   | { kind: 'message', text: string }
  *   | { kind: 'effort', reasoningEffort: string }} injection
@@ -76,6 +77,7 @@ export function compileIntentTable(raw) {
       id: entry.id,
       patterns,
       oncePerSession: entry.oncePerSession !== false,
+      ...(typeof entry.summary === 'string' && entry.summary.length > 0 ? { summary: entry.summary } : {}),
       injection,
     }
   })
@@ -91,6 +93,16 @@ export function matchIntents(stripped, intents) {
   return intents.filter((intent) => intent.patterns.some((pattern) => pattern.test(stripped)))
 }
 
+/** Verbatim directive injected on every writing intent hit. */
+export const WRITING_DIRECTIVE = `<intent-gate id="writing">
+Write the deliverable as the finished product, not as a record of producing it.
+- Keep the agent's thinking, implementation rationale, design reasoning, debugging narrative, and next-step plans out of the deliverable.
+- Do not write explanatory UI copy — "I will", "we can", "this page shows", "here you'll find", "used to illustrate", "implemented" — unless it is genuine product help text or empty-state copy.
+- Put implementation approach, verification method, limitations, and trade-offs only in the chat reply, code comments, the PR/MR description, docs, or plan files.
+- Exception: include design notes, methodology, implementation walkthrough, or a work log in the deliverable only when the user explicitly asks for them.
+- Unless there is a real need, a change leaves no trace: no comments, notes, markers, or any "why this changed" evidence. Code should look like it was always that way. The best change looks like no change was made — present the result, not the change itself.
+</intent-gate>`
+
 /** The default intent table (English templates; runtime content follows the session language). */
 export const DEFAULT_INTENTS = [
   {
@@ -113,6 +125,21 @@ export const DEFAULT_INTENTS = [
     matchers: ['\\bdebug\\b', '\\bdebugging\\b', '调试', '排查'],
     injection: { kind: 'skill-pointer', skill: 'debugging' },
   },
+  {
+    id: 'writing',
+    matchers: [
+      '\\bwrite (?:a |an |the |some )?(?:[a-z][\\w-]* )?(?:doc|docs|document|documents|documentation|readme|guide|manual|report|spec)\\b',
+      '\\b(?:draft|compose|author|produce|prepare|rewrite|revise|update|polish) (?:a |an |the |some )?(?:[a-z][\\w-]* )?(?:doc|docs|document|documentation|readme|guide|manual|report)\\b',
+      '\\bwrite[- ]?up\\b',
+      '\\bdocument (?:the|this|these|a|an)\\b',
+      '(?:写|撰写|编写|起草|整理成|写成|润色|补全|更新)[^\\n]{0,8}(?:文档|说明|报告|指南|手册|教程|文案)',
+      '(?:写|撰写|编写|起草|润色|补全|更新)[^\\n]{0,8}readme',
+      '文档(?:撰写|编写|写作|润色|补全|更新)',
+    ],
+    oncePerSession: false,
+    summary: 'author a documentation-style deliverable (docs, README, guide, report) as the finished result',
+    injection: { kind: 'message', text: WRITING_DIRECTIVE },
+  },
   {
     id: 'think',
     matchers: ['\\bthink hard\\b', '\\bultrathink\\b', '深思熟虑'],