comisai 1.0.42 → 1.0.45

package/node_modules/@comis/agent/dist/spawn/sub-agent-runner.js

@@ -10,11 +10,14 @@
  * Extracted from daemon.ts inline session.spawn handler for testability.
  * @module
  */
-import { formatSessionKey, parseFormattedSessionKey, runWithContext, } from "@comis/core";
+import { formatSessionKey, parseFormattedSessionKey, runWithContext, SUB_AGENT_TOOL_DENYLIST, toolReachableGroups, RequiredToolsUnreachableError, } from "@comis/core";
 import { suppressError } from "@comis/shared";
+import { createCoordinatorProgressFork, } from "./coordinator-progress-fork.js";
 import { sanitizeAssistantResponse } from "../provider/response/sanitize-pipeline.js";
 import { randomUUID } from "node:crypto";
 import { classifyAbortReason, buildAnnouncementMessage, deliverAnnouncement, deliverFailureNotification, validateOutputs, sweepResultFiles, persistFailureRecord, } from "./sub-agent-result-processor.js";
+import { comparePosture, SandboxDowngradeError } from "./sandbox-posture.js";
+import { steerRun as steerRunHelper } from "./steer-run.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -23,31 +26,68 @@ import { classifyAbortReason, buildAnnouncementMessage, deliverAnnouncement, del
  *  in response to announcements. 30s caused premature fallback + duplicate delivery. */
 export const ANNOUNCE_PARENT_TIMEOUT_MS = 300_000;
 /**
- * Build the composite-key triple from a SubAgentRun for resolver lookups
- * (R3, B37). Sub-agent runs only carry a formatted `sessionKey` string +
- * `agentId` + optional announce-channel context, so:
+ * Build the composite-key triple from a SubAgentRun for resolver lookups.
+ * MUST compose (via BackgroundSessionResolver.formatComposite) to the EXACT key
+ * the executor registers the live handle under (pi-executor.ts:1152-1156):
+ *
+ *   formatSessionKey({ tenantId: agentId ?? "default",
+ *                      channelId: `${originChannelType}:${msg.channelId}`,
+ *                      userId: msg.channelId })
+ *
+ * where for a sub-agent run `originChannelType = deliveryOrigin?.channelType ??
+ * channelType ?? "gateway"` and `msg.channelId = subSessionKey.channelId` (the
+ * executor ALWAYS receives subSessionKey -- line 1289). So:
  *   - agentId    -> run.agentId
- *   - channelType-> run.announceChannelType ?? "sub-agent"
- *   - channelId  -> run.announceChannelId
- *                   ?? parseFormattedSessionKey(run.sessionKey)?.channelId
- *                   ?? run.sessionKey  (last-resort: the formatted key
- *                                       itself; never empty so the
- *                                       resolver's empty-field guard
- *                                       does not trip)
+ *   - channelType-> run.announceChannelType ?? "gateway"  (announce runs
+ *                   propagate announceChannelType into ALS as deliveryOrigin
+ *                   -- line 1267/1286; no-announce runs default to "gateway")
+ *   - channelId  -> parseFormattedSessionKey(run.sessionKey)?.channelId
+ *                   ?? run.sessionKey  (the PARSED sub-session channelId, NOT
+ *                   run.announceChannelId -- the executor keys on
+ *                   subSessionKey.channelId, never the announce channelId; the
+ *                   last-resort raw key keeps the resolver's empty-field guard
+ *                   from tripping)
  *
- * The "sub-agent" channelType fallback acknowledges that production
- * SubAgentRun does not carry the original inbound channelType -- the
- * abort path is best-effort regardless (the SDK session may already be
- * in cleanup), so a no-op when the resolver does not find a handle is
- * acceptable. There is a runtime semantic gap (deviation: composite-key
- * triple vs registered formatted-key shape).
+ * WR-01 (175-REVIEW.md): the prior formula used "sub-agent" for channelType and
+ * `run.announceChannelId ?? parsed?.channelId` for channelId, which DIVERGED
+ * from the registration key. For steer (steer-run.ts) that miss was FATAL
+ * (the inject's whole purpose is to reach the live handle); for the kill /
+ * ghost-sweep / watchdog aborts below it was a silent best-effort no-op
+ * (latent). Aligning the formula fixes steer AND makes those aborts actually
+ * reach the handle. Keep this BYTE-IDENTICAL to steer-run.ts:deriveCompositeForRun
+ * -- the 175-00 spike fails loudly on drift.
  */
 function deriveCompositeForRun(run) {
     const parsed = parseFormattedSessionKey(run.sessionKey);
     return {
         agentId: run.agentId,
-        channelType: run.announceChannelType ?? "sub-agent",
-        channelId: run.announceChannelId ?? parsed?.channelId ?? run.sessionKey,
+        channelType: run.announceChannelType ?? "gateway",
+        channelId: parsed?.channelId ?? run.sessionKey,
+    };
+}
+// ---------------------------------------------------------------------------
+// Spawn-time required_tools gate helpers
+// ---------------------------------------------------------------------------
+/**
+ * Classify a single required tool as "outside_profile" or "denylist".
+ * Uses toolReachableGroups from @comis/core — no @comis/skills import needed.
+ */
+function classifyRequiredTool(toolName, activeGroups) {
+    if (SUB_AGENT_TOOL_DENYLIST.has(toolName)) {
+        return {
+            toolName,
+            reason: "denylist",
+            hint: `Tool '${toolName}' is denied to ALL sub-agents — the parent must perform this step.`,
+        };
+    }
+    const broader = toolReachableGroups(toolName).filter((p) => !activeGroups.includes(p));
+    // When no profile contains the tool, suggest only 'full' — 'supervisor' does not
+    // contain generic tools like web_fetch/browser/sessions_spawn, so it would fail again.
+    const suggestion = broader.length > 0 ? broader.join("' | '") : "full";
+    return {
+        toolName,
+        reason: "outside_profile",
+        hint: `Tool '${toolName}' is outside this sub-agent's profile. Re-spawn with tool_groups:['${suggestion}'].`,
     };
 }
 // ---------------------------------------------------------------------------
@@ -57,6 +97,206 @@ export function createSubAgentRunner(deps) {
     const { clock, timers } = deps;
     const runs = new Map();
     const activePromises = new Set();
+    // -------------------------------------------------------------------------
+    // Phase 216 (DUR-01 / HB-01): durable checkpoint + keep-alive heartbeat.
+    // Inert when `deps.durableRuns` is absent (the default install). The
+    // heartbeat timer is tracked per runId so the terminal `finally` clears it
+    // (no leaked interval). Store calls are best-effort — a write error is
+    // WARN-logged but NEVER crashes the live run (durability is a recovery aid).
+    // -------------------------------------------------------------------------
+    const heartbeatTimers = new Map();
+    const DURABLE_KEEPALIVE_MS = deps.durability?.keepAliveMs ?? 30_000;
+    /**
+     * Derive the MED-4 `cronOrigin` from the REAL cron signal threaded onto the
+     * spawn params (`isCronAgentTurn` + `jobId`/`jobName`). A cron-fired turn's
+     * sub-agent records the firing job's id; a non-cron spawn records null. There
+     * is NO `cronOrigin` string at HEAD — this IS the derivation.
+     */
+    function deriveCronOrigin(params) {
+        return params.isCronAgentTurn === true ? (params.jobId ?? params.jobName ?? "cron") : null;
+    }
+    /**
+     * Write the initial durable checkpoint at the SPAWN BOUNDARY (DUR-01) and start
+     * the keep-alive heartbeat (HB-01). `stepIndex` starts at -1 (the never-sent
+     * sentinel — the outward counter is owned by allocateOutwardStep, NOT here).
+     * Inert when no store is wired. Never throws.
+     */
+    function startDurableCheckpoint(run, params) {
+        const store = deps.durableRuns;
+        if (!store)
+            return;
+        const rootRunId = run.rootRunId;
+        const facts = deps.durableRunFacts?.(rootRunId, params.agentId);
+        // Caps: explicit spawn param wins (the lease's minted caps), else the
+        // injected facts resolver, else an empty set (a safe degrade — a resume
+        // re-mints the persisted caps VERBATIM, so empty is zero-authority, never
+        // an over-grant).
+        const caps = params.caps ?? facts?.caps ?? [];
+        const leaseIds = facts?.leaseIds ?? (params.parentLeaseId ? [params.parentLeaseId] : []);
+        const budgetConsumed = facts?.budgetConsumed ?? 0;
+        const cronOrigin = deriveCronOrigin(params);
+        void store
+            .upsertCheckpoint({
+            rootRunId,
+            spawnTree: [rootRunId],
+            // Copy into mutable arrays — DurableRunRecord's caps/leaseIds are mutable
+            // (the Zod-inferred shape); the deps/params surfaces are readonly.
+            caps: [...caps],
+            leaseIds: [...leaseIds],
+            budgetConsumed,
+            cronOrigin,
+            stepIndex: -1,
+            status: "running",
+            lastHeartbeatAt: clock.now(),
+        })
+            .then((r) => {
+            if (!r.ok) {
+                deps.logger?.warn({ rootRunId, err: r.error, hint: "durable checkpoint upsert failed — the run still proceeds; it will not be resumable after a crash", errorKind: "internal" }, "Durable checkpoint: upsert failed (run continues)");
+            }
+        })
+            .catch((err) => {
+            deps.logger?.warn({ rootRunId, err, hint: "durable checkpoint upsert threw — the run still proceeds", errorKind: "internal" }, "Durable checkpoint: upsert threw (run continues)");
+        });
+        // HB-01: a keep-alive that fires INDEPENDENT of step/spawn completion so a
+        // long-running child never trips the watchdog's stale threshold (Pitfall 4).
+        // One interval per run, cleared on terminal settle (no leaked timer).
+        if (!heartbeatTimers.has(run.runId)) {
+            const handle = timers.setInterval(() => {
+                suppressError(store
+                    .touchHeartbeat(rootRunId, clock.now())
+                    .then((r) => {
+                    if (!r.ok) {
+                        deps.logger?.debug({ rootRunId, err: r.error, hint: "durable heartbeat touch failed; the watchdog may orphan-sweep this run if it persists", errorKind: "internal" }, "Durable heartbeat: touch failed");
+                    }
+                }), "durable heartbeat touch (best-effort)");
+            }, DURABLE_KEEPALIVE_MS);
+            handle.unref();
+            heartbeatTimers.set(run.runId, handle);
+        }
+    }
+    /**
+     * Terminal seam (DUR-01): mark the run completed + clear its keep-alive
+     * heartbeat. Fires on EVERY terminal settle of a started run (completion,
+     * failure, kill/ghost/watchdog — the underlying executeAgent promise still
+     * settles), so the interval is reclaimed and the durable record stops being
+     * resumable. Inert + idempotent when no store / no timer. Never throws.
+     */
+    function finishDurableCheckpoint(run) {
+        const handle = heartbeatTimers.get(run.runId);
+        if (handle) {
+            handle.cancel();
+            heartbeatTimers.delete(run.runId);
+        }
+        const store = deps.durableRuns;
+        if (!store)
+            return;
+        suppressError(store
+            .markCompleted(run.rootRunId)
+            .then((r) => {
+            if (!r.ok) {
+                deps.logger?.warn({ rootRunId: run.rootRunId, err: r.error, hint: "durable markCompleted failed — the watchdog will eventually orphan-sweep the stale record (no live impact)", errorKind: "internal" }, "Durable checkpoint: markCompleted failed");
+            }
+        }), "durable terminal markCompleted (best-effort)");
+    }
+    // -------------------------------------------------------------------------
+    // COORD-03: the ~30s read-only progress fork (coordinator-progress-fork.ts).
+    // One fork per running child, tracked by runId so the terminal `finally`
+    // stops it (no leaked timer — the fork's interval is .unref()'d). The fork is
+    // a READ-ONLY summary of the in-flight child's advance — it never re-executes,
+    // calls a tool, or spawns. It runs INDEPENDENT of the durable store (a long
+    // child should surface progress even when durability is off), so it is started
+    // at the spawn boundary alongside — but not inside — startDurableCheckpoint.
+    // -------------------------------------------------------------------------
+    const progressForks = new Map();
+    /**
+     * Start the read-only progress fork for a just-started child run. `getStepState`
+     * is a thin read of the run's live step counter — `run.result` is only
+     * populated on completion (by which point the fork is already stopped), so an
+     * in-flight tick reports `stepsExecuted: 0` and the elapsed wall-clock is the
+     * advance signal (RESEARCH: a count-only advance is still NOT a re-execution).
+     * Idempotent per runId. No model call, no tool, no spawn.
+     */
+    function startProgressFork(run, params) {
+        if (progressForks.has(run.runId))
+            return;
+        const fork = createCoordinatorProgressFork({
+            eventBus: deps.eventBus,
+            clock,
+            timers,
+            runId: run.runId,
+            agentId: params.agentId,
+            // Thin read of the existing run handle — no new run-state plumbing.
+            getStepState: () => ({ stepsExecuted: run.result?.stepsExecuted ?? 0 }),
+        });
+        fork.start();
+        progressForks.set(run.runId, fork);
+    }
+    /**
+     * Stop + reclaim a child's progress fork on its terminal settle. Idempotent +
+     * inert when none was started (e.g. a queued run that never ran). Mirrors
+     * finishDurableCheckpoint's terminal-seam discipline — the fork never outlives
+     * the child (T-218-15).
+     */
+    function stopProgressFork(run) {
+        const fork = progressForks.get(run.runId);
+        if (!fork)
+            return;
+        fork.stop();
+        progressForks.delete(run.runId);
+    }
+    // WR-02: make the fail-OPEN observable. The sandbox no-downgrade gate (below)
+    // silently no-ops when `resolvePosture` is absent — a P0 security control that
+    // does nothing. Production composition (setup-cross-session-runtime.ts) ALWAYS
+    // injects the resolver (a daemon-wiring test pins this), but a future second
+    // construction path could omit it and ship an inert gate. Emit a one-time
+    // construction WARN so the fail-open surfaces in the logs rather than silently.
+    if (deps.config.sandboxNoDowngrade !== false && !deps.resolvePosture) {
+        deps.logger?.warn({
+            hint: "sandboxNoDowngrade is on but no posture resolver was injected — the no-downgrade gate is INERT; " +
+                "wire resolvePosture into createSubAgentRunner (see setup-cross-session-runtime.ts) or set security.agentToAgent.sandboxNoDowngrade:false",
+            errorKind: "config",
+        }, "Sandbox no-downgrade gate is INERT: no posture resolver injected");
+    }
+    // ---------------------------------------------------------------------
+    // In-flight spawn dedup:
+    //   Maps `(callerSessionKey + agentId + task)` triples to in-flight runIds.
+    //   Populated when a non-graph session-spawn starts (running OR queued)
+    //   and removed at terminal status transitions. A spawn() call whose
+    //   dedup key already maps to an in-flight run short-circuits and returns
+    //   the existing runId AND records `lastDedupHit` for the calling RPC
+    //   handler to surface `deduped: true, existingRunId, ageMs` to the LLM.
+    // Skipped for:
+    //   - top-level spawns (no callerSessionKey) — scoped dedup requires a
+    //     known caller identity, otherwise CLI/scheduler spawns would collide.
+    //   - graph-marked spawns (callerType === "graph") — graph coordinator
+    //     owns its own dedup via `runIdToNode`; matching by task would break
+    //     graph parallelism when two nodes coincidentally share task wording.
+    // ---------------------------------------------------------------------
+    const inFlightByDedupKey = new Map();
+    let lastDedupHit;
+    function computeDedupKey(callerSessionKey, task, agentId) {
+        // NUL byte separator: cannot appear in JSON-source session keys or
+        // agent IDs and is vanishingly unlikely in task prose. The map is
+        // in-process only and never serialized — collisions are not
+        // attacker-controlled.
+        return `${callerSessionKey}\x00${agentId}\x00${task}`;
+    }
+    function isDedupEligible(params) {
+        return params.callerSessionKey !== undefined && params.callerType !== "graph";
+    }
+    function removeDedupEntry(run) {
+        if (!run.callerSessionKey)
+            return;
+        // Graph-marked runs were never registered.
+        if (run.graphId !== undefined)
+            return;
+        const dedupKey = computeDedupKey(run.callerSessionKey, run.task, run.agentId);
+        // Only delete if the slot still points at THIS runId — defensive against
+        // a re-spawn that already won the slot after our terminal transition.
+        if (inFlightByDedupKey.get(dedupKey) === run.runId) {
+            inFlightByDedupKey.delete(dedupKey);
+        }
+    }
     // Late-binding ref for graph coordinator (created after sub-agent runner in daemon.ts)
     let graphCoordinatorRef;
     /** FIFO queue per caller session key. */
@@ -79,6 +319,21 @@ export function createSubAgentRunner(deps) {
     // -------------------------------------------------------------------------
     // Proxy typing stop helper (avoids repeating guard+emit in 5 paths)
     // -------------------------------------------------------------------------
+    /**
+     * Release a run's reserved tree-wide ceiling slot EXACTLY ONCE (Phase 213
+     * CR-02). Pairs 1:1 with the `checkSpawnCeiling` acquire recorded on the run.
+     * Clearing `ceilingSlotAcquired` first makes this idempotent across the several
+     * terminal paths a single run can traverse (kill marks failed, then the
+     * underlying executeAgent promise later settles and fires `execPromise.finally`
+     * — both must not double-release, which would steal a sibling slot under a
+     * shared root since `releaseSpawn` floors at 0 but cannot tell whose slot it is).
+     */
+    function releaseCeilingSlotOnce(run) {
+        if (!run.ceilingSlotAcquired)
+            return;
+        run.ceilingSlotAcquired = false;
+        deps.releaseSpawnCeiling?.(run.rootRunId);
+    }
     function emitProxyStop(run, runId, reason) {
         if (!run.announceChannelType || !run.announceChannelId)
             return;
@@ -96,6 +351,14 @@ export function createSubAgentRunner(deps) {
     // -------------------------------------------------------------------------
     const SWEEP_INTERVAL_MS = 300_000;
     const MAX_RUNS = 1000;
+    // WR-01: DLQ recovery sink — when a dead-lettered announcement is finally
+    // re-delivered on drain(), record its idempotency key in the shared
+    // deliveredKeys set so a later failure sweep (deliverFailureNotification)
+    // does not double-notify the same run. No-op when no shared dedup is wired.
+    const markRecoveredDelivered = (idempotencyKey) => {
+        deps.deliveryDedup?.mark(idempotencyKey);
+        deps.batcher?.markDelivered(idempotencyKey);
+    };
     const sweepInterval = timers.setInterval(() => {
         const now = clock.now();
         const retentionMs = deps.config.subAgentRetentionMs;
@@ -120,6 +383,9 @@ export function createSubAgentRunner(deps) {
                     timestamp: now,
                 });
                 deps.logger?.debug({ runId, ageMs: now - run.completedAt }, "Sub-agent run auto-archived");
+                // Belt-and-suspenders: terminal-transition sites already remove the
+                // dedup entry, but archive is the last chance to evict if those missed.
+                removeDedupEntry(run);
                 runs.delete(runId);
             }
         }
@@ -130,7 +396,9 @@ export function createSubAgentRunner(deps) {
                 .sort((a, b) => (a[1].completedAt ?? 0) - (b[1].completedAt ?? 0));
             const toRemove = runs.size - MAX_RUNS;
             for (let i = 0; i < toRemove && i < completedRuns.length; i++) {
-                runs.delete(completedRuns[i][0]);
+                const [pruneRunId, pruneRun] = completedRuns[i];
+                removeDedupEntry(pruneRun);
+                runs.delete(pruneRunId);
             }
         }
         // Queue timeout sweep -- fail queued spawns that exceeded queueTimeoutMs
@@ -147,6 +415,7 @@ export function createSubAgentRunner(deps) {
                         run.status = "failed";
                         run.error = `Queue timeout: waited ${queueTimeoutMs}ms for an execution slot`;
                         run.completedAt = now;
+                        removeDedupEntry(run);
                         deps.eventBus.emit("session:sub_agent_spawn_rejected", {
                             parentSessionKey: callerKey,
                             agentId: run.agentId,
@@ -196,6 +465,7 @@ export function createSubAgentRunner(deps) {
             run.status = "failed";
             run.completedAt = now;
             run.error = `Ghost run: stuck in 'running' for ${(runningDurationMs / 1000).toFixed(0)}s (grace: ${(ghostGraceMs / 1000).toFixed(0)}s)`;
+            removeDedupEntry(run);
             // Persist failure record
             if (deps.dataDir) {
                 suppressError(persistFailureRecord({
@@ -208,7 +478,7 @@ export function createSubAgentRunner(deps) {
                     runtimeMs: runningDurationMs,
                 }, deps.logger), "ghost-sweep-failure-record");
             }
-            // Abort SDK session (best-effort, R3 / B37 -- composite-key resolver)
+            // Abort SDK session (best-effort, composite-key resolver)
             if (deps.sessionResolver) {
                 const handle = deps.sessionResolver.resolveActiveSession(deriveCompositeForRun(run));
                 if (handle) {
@@ -231,6 +501,7 @@ export function createSubAgentRunner(deps) {
                     task: run.task,
                     runtimeMs: runningDurationMs,
                     runId,
+                    callerSessionKey: run.callerSessionKey, // DELIVERY-03: shared dedup key
                     // eslint-disable-next-line no-restricted-syntax -- intentional fire-and-forget
                 }, deps).catch(() => { });
             }
@@ -256,24 +527,34 @@ export function createSubAgentRunner(deps) {
         }
         // Dead-letter queue periodic drain
         if (deps.deadLetterQueue) {
-            suppressError(deps.deadLetterQueue.drain(deps.sendToChannel), "dead-letter-sweep-drain");
+            suppressError(deps.deadLetterQueue.drain(deps.sendToChannel, markRecoveredDelivered), "dead-letter-sweep-drain");
         }
     }, SWEEP_INTERVAL_MS);
     sweepInterval.unref();
     // Event-driven DLQ drain on provider recovery
     if (deps.deadLetterQueue) {
         deps.eventBus.on("provider:recovered", () => {
-            suppressError(deps.deadLetterQueue.drain(deps.sendToChannel), "dead-letter-recovery-drain");
+            suppressError(deps.deadLetterQueue.drain(deps.sendToChannel, markRecoveredDelivered), "dead-letter-recovery-drain");
         });
     }
     // -------------------------------------------------------------------------
     // Public API
     // -------------------------------------------------------------------------
     function spawn(params) {
+        // Reset dedup signal at the start of every call so a non-deduped spawn
+        // does not see a stale hit from the previous invocation.
+        lastDedupHit = undefined;
         // 0. Resolve depth and config values for limit enforcement
         const currentDepth = params.depth ?? 0;
         const maxDepth = params.maxDepth ?? deps.config.subagentContext?.maxSpawnDepth ?? 3;
         const isGraphSpawn = params.callerType === "graph";
+        // Establish the tree-stable rootRunId (CEIL-01/REVOKE-03 foundation). The root
+        // (the first caller with no rootRunId) mints one; every descendant MUST pass its
+        // parent's id down via params.rootRunId. We mint whenever it is absent — regardless
+        // of depth — so a missing id never silently splits a tree into per-spawn ids that
+        // each escape the parent's ceiling (RESEARCH Pitfall 1). Uses the injected
+        // ClockPort (never the wall-clock global — the globals.test.ts arch-gate).
+        const rootRunId = params.rootRunId ?? `root-${params.agentId}-${clock.now().toString(36)}`;
         // Depth check (applies to ALL spawns including graph)
         if (currentDepth >= maxDepth) {
             deps.eventBus.emit("session:sub_agent_spawn_rejected", {
@@ -299,6 +580,135 @@ export function createSubAgentRunner(deps) {
             // @allow-throw: spawn() consumed exclusively by daemon RPC handlers (subagent-handlers, session-handlers, graph-*); these handlers are @allow-throw boundaries — rpc-dispatch.ts wraps and converts to JSON-RPC error response.
             throw new Error(`Spawn rejected: depth limit exceeded (current: ${currentDepth}, max: ${maxDepth}). This sub-agent cannot spawn further children at this nesting level.`);
         }
+        // In-flight dedup check. A duplicate same-caller-same-task spawn
+        // returns the existing runId rather than starting a parallel run. Placed
+        // AFTER the depth throw (depth violations must always reject) but BEFORE
+        // the children-limit / queue / allowlist logic — a deduped spawn does NOT
+        // consume a child slot or create a new run; the existing run was already
+        // validated by these gates when it was first started.
+        if (isDedupEligible(params)) {
+            const dedupKey = computeDedupKey(params.callerSessionKey, params.task, params.agentId);
+            const existingRunId = inFlightByDedupKey.get(dedupKey);
+            if (existingRunId !== undefined) {
+                const existing = runs.get(existingRunId);
+                if (existing && (existing.status === "running" || existing.status === "queued")) {
+                    const startRef = existing.startedAt || existing.queuedAt || clock.now();
+                    const ageMs = clock.now() - startRef;
+                    lastDedupHit = { existingRunId, ageMs };
+                    deps.logger?.debug({
+                        runId: existingRunId,
+                        existingRunId,
+                        taskLength: params.task.length,
+                        callerSessionKey: params.callerSessionKey,
+                        ageMs,
+                        hint: "Duplicate spawn deduped against in-flight run",
+                    }, "Sub-agent spawn deduped");
+                    return existingRunId;
+                }
+                // Stale entry — the prior run reached terminal status without cleanup.
+                // Drop it so we don't keep returning a dead runId.
+                inFlightByDedupKey.delete(dedupKey);
+            }
+        }
+        // Spawn-time required_tools gate.
+        // Validates that each declared required tool is reachable by the sub-agent
+        // BEFORE creating a runId or session — fires on BOTH the immediate and queued paths.
+        //
+        // Uses the daemon-provided reachableToolNames set (params.reachableToolNames), which the
+        // daemon's session-mutate.ts computes via computeReachableToolNames() after applying the
+        // config default tool groups and expanding both TOOL_PROFILES and TOOL_GROUPS. This gives
+        // TRUE parity with the runtime ceiling (setup-tools.ts:588-607).
+        //
+        // When reachableToolNames is absent (older callers), the gate fails-open so the runtime
+        // denylist+ceiling enforcement still applies. The daemon path MUST provide this field.
+        if (params.requiredTools && params.requiredTools.length > 0) {
+            const reachableSet = params.reachableToolNames;
+            const effectiveGroups = params.toolGroups ?? [];
+            const unreachable = [];
+            for (const tool of params.requiredTools) {
+                // Denylisted tools are unreachable regardless of profile or reachableToolNames (check first)
+                if (SUB_AGENT_TOOL_DENYLIST.has(tool)) {
+                    unreachable.push(classifyRequiredTool(tool, effectiveGroups));
+                }
+                else if (reachableSet !== undefined && !reachableSet.has(tool)) {
+                    // reachableSet is provided → use it for membership check (profile/group parity)
+                    unreachable.push(classifyRequiredTool(tool, effectiveGroups));
+                    // reachableSet is undefined → fail-open (runtime boundary still enforces)
+                }
+            }
+            if (unreachable.length > 0) {
+                deps.logger?.warn({
+                    agentId: params.agentId,
+                    requiredTools: params.requiredTools,
+                    toolGroups: params.toolGroups,
+                    unreachableTools: unreachable.map((e) => ({ toolName: e.toolName, reason: e.reason })),
+                    hint: "Spawn rejected: required_tools unreachable in sub-agent profile; see unreachableTools for re-spawn guidance",
+                    errorKind: "validation",
+                }, "Sub-agent spawn rejected: required tools unreachable");
+                // @allow-throw: spawn() consumed exclusively by daemon RPC handlers.
+                throw new RequiredToolsUnreachableError(unreachable);
+            }
+        }
+        // Sandbox no-downgrade gate (SANDBOX-02). The single fail-closed posture
+        // check at the spawn chokepoint: a spawned child may never be LESS confined
+        // than its spawner. Placed AFTER the required_tools gate and BEFORE the
+        // children/queue branch, so ONE check fires before any `runs.set` / runId /
+        // session on BOTH the immediate (line ~1019) and queued (line ~949) paths —
+        // satisfying "refuse before any child run/session is created".
+        //
+        // Gated by the typed `config.sandboxNoDowngrade` field (default true;
+        // `undefined !== false` ⇒ active, so an explicit `false` is the ONLY off
+        // state). Inert when `resolvePosture` is absent (older test wiring) or for a
+        // top-level spawn (no parent posture to compare against). Posture is resolved
+        // via the INJECTED `deps.resolvePosture` dep — the runner never reaches
+        // `config.agents[...]` (D-RESOLVEDEP).
+        //
+        // ORDERING (IN-02, intentional): this fail-closed gate runs BEFORE the
+        // children/queue branch and the allowlist check (line ~1051). A spawn that is
+        // BOTH a downgrade AND not-allowlisted is therefore attributed to the
+        // downgrade refusal. We keep this order on purpose: both branches refuse the
+        // spawn (no security difference — only the reason/event differs), and moving
+        // the allowlist earlier would hoist it above the queue SIDE-EFFECT branch
+        // too, perturbing the load-bearing "refuse before any run/session/queue"
+        // placement that the queued-path gate test pins. Security placement wins over
+        // reason attribution.
+        const sandboxNoDowngrade = deps.config.sandboxNoDowngrade;
+        if (sandboxNoDowngrade !== false && deps.resolvePosture && params.callerAgentId) {
+            const parentPosture = deps.resolvePosture(params.callerAgentId);
+            const childPosture = deps.resolvePosture(params.agentId, params.callerAgentId);
+            const cmp = comparePosture(parentPosture, childPosture);
+            if (cmp.isDowngrade) {
+                const violated = cmp.violatedDimensions.join(", ");
+                deps.logger?.warn({
+                    agentId: params.agentId,
+                    parentAgentId: params.callerAgentId,
+                    childAgentId: params.agentId,
+                    // Enum labels only — never posture values/paths/hosts (§2.7).
+                    violatedDimensions: cmp.violatedDimensions,
+                    hint: `Spawn refused: child sandbox posture is less confined than its spawner on ${violated}; ` +
+                        "align the child's skills sandbox config or set security.agentToAgent.sandboxNoDowngrade:false to disable",
+                    errorKind: "precondition",
+                }, "Sub-agent spawn refused: sandbox downgrade");
+                // Typed refusal event (SANDBOX-03): both postures as enum TUPLES + the
+                // violated dimension labels + the two agent ids — labels only, NO
+                // paths/hosts/uid-numbers/credential values (§2.7 / T-172-01f). Fires
+                // here, before the throw, at the exact point a run/session would
+                // otherwise be created. comparePosture's violatedDimensions feeds it.
+                deps.eventBus.emit("security:sandbox_downgrade_refused", {
+                    timestamp: clock.now(),
+                    parentAgentId: params.callerAgentId,
+                    childAgentId: params.agentId,
+                    violatedDimensions: cmp.violatedDimensions,
+                    parentPosture,
+                    childPosture,
+                });
+                // @allow-throw: spawn() consumed exclusively by daemon RPC handlers; @allow-throw boundary.
+                // Typed (OBS-RPC-REFUSAL-CLASS): classifyRpcError maps SandboxDowngradeError to
+                // precondition/warn — this fail-closed SECURITY refusal must NOT read as an
+                // internal/error handler fault in an operator's ERROR-level health sweep.
+                throw new SandboxDowngradeError(`Spawn refused: child "${params.agentId}" sandbox posture is less confined than parent "${params.callerAgentId}" on: ${violated}.`, cmp.violatedDimensions);
+            }
+        }
         // Children check (bypassed for graph spawns)
         if (!isGraphSpawn && params.callerSessionKey) {
             const maxChildren = deps.config.subagentContext?.maxChildrenPerAgent ?? 5;
@@ -371,6 +781,8 @@ export function createSubAgentRunner(deps) {
                     queuedAt: now,
                     requesterOrigin: params.requesterOrigin,
                     depth: currentDepth,
+                    rootRunId,
+                    ...(params.parentLeaseId !== undefined ? { parentLeaseId: params.parentLeaseId } : {}),
                     callerSessionKey: params.callerSessionKey,
                     announceChannelType: params.announceChannelType,
                     announceChannelId: params.announceChannelId,
@@ -381,6 +793,12 @@ export function createSubAgentRunner(deps) {
                         : params.callerSessionKey,
                 };
                 runs.set(queuedRunId, queuedRun);
+                // Register dedup entry for the queued run so a second same-caller-same-task
+                // spawn at children-limit returns the queued runId rather than starting another.
+                if (isDedupEligible(params)) {
+                    const dedupKey = computeDedupKey(params.callerSessionKey, params.task, params.agentId);
+                    inFlightByDedupKey.set(dedupKey, queuedRunId);
+                }
                 const callerQueue = spawnQueue.get(params.callerSessionKey) ?? [];
                 callerQueue.push({ runId: queuedRunId, params, queuedAt: now });
                 spawnQueue.set(params.callerSessionKey, callerQueue);
@@ -405,18 +823,80 @@ export function createSubAgentRunner(deps) {
                 return queuedRunId;
             }
         }
-        // 1. Allowlist check
+        // 1. Allowlist check.
+        // WR-03 (213-REVIEW): hoisted ABOVE the ceiling acquire below. The allowlist
+        // check has NO side effects and can throw; if it ran AFTER the ceiling
+        // reserve (the prior order), a not-allowlisted spawn would reserve a slot and
+        // then throw with no run ever created — so no completion `finally` would ever
+        // release it (a slot leak the instant CR-02's release landed). Refusing here,
+        // before any reserve, keeps the acquire the LAST gate before run creation so
+        // every successful acquire is paired 1:1 with a run that will release it.
         if (deps.config.allowAgents.length > 0 &&
             !deps.config.allowAgents.includes(params.agentId)) {
             // `callerAgentId` is `string | undefined` -- a top-level spawn call
             // (no parent agent in flight) omits it. Use the same "unknown" sentinel
-            // as the success-path log line at the bottom of this function (around
-            // line 889) so failure records and observability payloads don't grep
-            // for the literal string "undefined".
+            // as the success-path log line at the bottom of this function so failure
+            // records and observability payloads don't grep for the literal "undefined".
             const callerLabel = params.callerAgentId ?? "unknown";
             // @allow-throw: spawn() consumed exclusively by daemon RPC handlers.
             throw new Error(`Agent "${callerLabel}" is not allowed to spawn "${params.agentId}". Allowed: ${deps.config.allowAgents.join(", ")}`);
         }
+        // Tree-wide spawn ceiling (CEIL-01). The SINGLE consult both session.spawn
+        // AND graph.* AND the in-process agent loop hit (they all reach here via
+        // runner.spawn), keyed on the tree-stable rootRunId — so a for(;;) spawn()
+        // is bounded across the whole tree, not just one caller. Placed AFTER the
+        // per-caller depth/children/queue gates AND the allowlist (WR-03) and BEFORE
+        // any runId/session is created, so it rejects with the SAME shape as the
+        // depth/children gates (event + WARN + no run/session) and is the LAST gate
+        // before run creation (every acquire pairs 1:1 with a releasing run). The
+        // fanout arg is the caller's active children (0 for a top-level / graph spawn
+        // with no callerSessionKey). Inert when the callback is absent (older/non-
+        // daemon wiring).
+        let ceilingSlotAcquired = false;
+        if (deps.checkSpawnCeiling) {
+            const ceilingFanout = countActiveChildren(params.callerSessionKey);
+            const ceiling = deps.checkSpawnCeiling(rootRunId, currentDepth, ceilingFanout);
+            if (ceiling.ok) {
+                // The consult RESERVED a slot (tryAcquireSpawn increments on ok). Record
+                // it so the run's terminal transition releases it 1:1 (CR-02). This is the
+                // last gate before run creation, so a successful acquire is always paired
+                // with a run that will release.
+                ceilingSlotAcquired = true;
+            }
+            if (!ceiling.ok) {
+                // Map the ceiling's reason (concurrency/depth/fanout) to the closed
+                // event union's tree-wide `ceiling_*` member; an unknown reason folds to
+                // ceiling_concurrency (the catch-all bound). Keeps the event distinct
+                // from the per-caller depth_exceeded/children_exceeded gates.
+                const eventReason = ceiling.reason === "depth"
+                    ? "ceiling_depth"
+                    : ceiling.reason === "fanout"
+                        ? "ceiling_fanout"
+                        : "ceiling_concurrency";
+                deps.eventBus.emit("session:sub_agent_spawn_rejected", {
+                    parentSessionKey: params.callerSessionKey ?? "unknown",
+                    agentId: params.agentId,
+                    task: params.task,
+                    reason: eventReason,
+                    currentDepth,
+                    maxDepth,
+                    currentChildren: ceilingFanout,
+                    maxChildren: deps.config.subagentContext?.maxChildrenPerAgent ?? 5,
+                    timestamp: clock.now(),
+                });
+                deps.logger?.warn({
+                    agentId: params.agentId,
+                    parentSessionKey: params.callerSessionKey ?? "unknown",
+                    reason: ceiling.reason,
+                    rootRunId,
+                    currentDepth,
+                    hint: "Spawn rejected: tree-wide autonomy ceiling reached; the spawn tree hit its concurrency/depth/fanout bound (autonomy.spawn.*). Wait for sibling sub-agents to finish or raise the bound.",
+                    errorKind: "resource",
+                }, "Subagent spawn rejected");
+                // @allow-throw: spawn() consumed exclusively by daemon RPC handlers; @allow-throw boundary — rpc-dispatch.ts converts to a JSON-RPC error.
+                throw new Error(`Spawn rejected: tree-wide spawn ceiling reached (reason: ${ceiling.reason}). This spawn tree is at its concurrency/depth/fanout bound.`);
+            }
+        }
         // Normal (non-queued) path: create run and start execution
         const runId = randomUUID();
         const run = {
@@ -424,6 +904,8 @@ export function createSubAgentRunner(deps) {
             task: params.task, sessionKey: "", startedAt: clock.now(),
             requesterOrigin: params.requesterOrigin,
             depth: currentDepth,
+            rootRunId,
+            ...(params.parentLeaseId !== undefined ? { parentLeaseId: params.parentLeaseId } : {}),
             callerSessionKey: params.callerSessionKey,
             announceChannelType: params.announceChannelType,
             announceChannelId: params.announceChannelId,
@@ -432,8 +914,15 @@ export function createSubAgentRunner(deps) {
             abortGroup: params.callerType === "graph" && params.graphId
                 ? `graph:${params.graphId}`
                 : params.callerSessionKey,
+            ...(ceilingSlotAcquired ? { ceilingSlotAcquired: true } : {}),
         };
         runs.set(runId, run);
+        // Register dedup entry for the just-started run so duplicate spawns
+        // arriving while it is in flight short-circuit to this runId.
+        if (isDedupEligible(params)) {
+            const dedupKey = computeDedupKey(params.callerSessionKey, params.task, params.agentId);
+            inFlightByDedupKey.set(dedupKey, runId);
+        }
         startExecution(runId, run, params, currentDepth, maxDepth);
         // 6. Return runId immediately (non-blocking)
         return runId;
@@ -466,6 +955,7 @@ export function createSubAgentRunner(deps) {
                     maxSpawnDepth: maxDepth,
                     artifactRefs: params.artifactRefs ?? [],
                     objective: params.objective ?? "",
+                    language: params.resolvedLanguage,
                     domainKnowledge: params.domainKnowledge ?? [],
                     toolGroups: params.toolGroups ?? [],
                     includeParentHistory: params.includeParentHistory ?? "none",
@@ -498,6 +988,7 @@ export function createSubAgentRunner(deps) {
                 maxSpawnDepth: maxDepth,
                 artifactRefs: params.artifactRefs ?? [],
                 objective: params.objective ?? "",
+                language: params.resolvedLanguage,
                 domainKnowledge: params.domainKnowledge ?? [],
                 toolGroups: params.toolGroups ?? [],
                 includeParentHistory: params.includeParentHistory ?? "none",
@@ -506,12 +997,27 @@ export function createSubAgentRunner(deps) {
                 graphToolNames: params.graphToolNames ?? [],
                 graphNodeDepth: params.graphNodeDepth,
                 isLeafNode: params.isLeafNode ?? false,
+                // WT-01: carry the worktree request onto the child session metadata so
+                // executeSubAgent (the only place that holds the GitExec seam + the
+                // workspace resolver) can run the child in an isolated git worktree.
+                // Defaults to false so the no-worktree path stays byte-identical.
+                worktree: params.worktree ?? false,
             });
         }
         // Update run with session info and running status
         run.sessionKey = formattedKey;
         run.status = "running";
         run.startedAt = clock.now();
+        // Phase 216 (DUR-01 / HB-01): the SPAWN BOUNDARY — the run is now registered
+        // + running, so write the initial durable checkpoint (stepIndex -1) + start
+        // the keep-alive heartbeat. Inert when no durable store is wired. The keep-
+        // alive is cleared + the record marked completed in the terminal `finally`.
+        startDurableCheckpoint(run, params);
+        // COORD-03: start the ~30s read-only progress fork so a long-running child
+        // surfaces its advance (a content-free session:sub_agent_progress) WITHOUT
+        // completing. Stopped in the terminal `finally` (no leaked timer). Runs
+        // independent of the durable store.
+        startProgressFork(run, params);
         deps.logger?.info({
             runId, agentId: params.agentId,
             callerAgentId: params.callerAgentId ?? "unknown",
@@ -583,7 +1089,7 @@ export function createSubAgentRunner(deps) {
                     ? { graphId: params.graphId, nodeId: params.nodeId, reuseSessionKey: params.reuseSessionKey, graphNodeDepth: params.graphNodeDepth }
                     : params.reuseSessionKey
                         ? { reuseSessionKey: params.reuseSessionKey }
-                        : undefined));
+                        : undefined, params.tokenBudget));
                 // Guard: if already killed, skip completion logic
                 if (run.status === "failed")
                     return;
@@ -591,6 +1097,7 @@ export function createSubAgentRunner(deps) {
                 run.status = "completed";
                 run.completedAt = completedAt;
                 run.result = result;
+                removeDedupEntry(run);
                 // Populate run.error for non-successful completions so graph coordinator
                 // and downstream consumers see a meaningful error instead of "Unknown error".
                 if (result.finishReason !== "stop" && result.finishReason !== "end_turn") {
@@ -670,6 +1177,49 @@ export function createSubAgentRunner(deps) {
                         }, "ResultCondenser failed");
                     }
                 }
+                // Phase 218 (SUMREF-02): materialize the child's FULL output to its OWN
+                // jailed workspace as a structured ResultRef, so the lead's announcement
+                // grows by a bounded summary + a HANDLE, never the megabyte body (the
+                // longevity invariant). The condenser (SUMREF-01 summary) and the store
+                // (SUMREF-02 handle) are complementary — both run. The drill-in line that
+                // follows the summary defaults to the condenser's diskPath: the genuine
+                // "no store wired / no handle produced" path (no store to materialize
+                // through, so the on-disk condensed result IS the handle — NOT a shim).
+                let fullResultLine = condensedResult ? `\n\nFull result: ${condensedResult.diskPath}` : "";
+                // The successful handle (when produced) — threaded into the NarrativeCaster
+                // path too, so the production-default tagged announcement also carries the
+                // handle, not the diskPath (SUMREF-02 longevity invariant on every path).
+                let materializedRef;
+                if (condensedResult && deps.materializeFullOutput) {
+                    const materialized = await deps.materializeFullOutput(result.response, { runId, nowMs: clock.now(), agentId: params.agentId });
+                    if (materialized && "ref" in materialized && typeof materialized.ref === "string") {
+                        // Success: the lead drills into the handle on demand (read/grep/jq).
+                        materializedRef = materialized;
+                        fullResultLine = `\n\nFull result (drill in with read/grep/jq): ${materialized.ref} (${materialized.bytes}B, ${materialized.kind})`;
+                        deps.logger?.debug({
+                            runId, step: "child-result-materialize",
+                            bytes: materialized.bytes, kind: materialized.kind,
+                        }, "Child output materialized to ResultRef");
+                    }
+                    else if (materialized && "error" in materialized && typeof materialized.error === "string") {
+                        // Refused (over per-file cap / path-traversal); the store wrote
+                        // nothing. Degrade to the summary + diskPath and surface a WARN — the
+                        // `.error` is a content-free CODE string, safe to echo in the hint.
+                        deps.logger?.warn({
+                            runId, step: "child-result-materialize",
+                            errorKind: "resource",
+                            hint: `Child output materialize refused (${materialized.error}); the lead falls back to the condensed summary + diskPath.`,
+                        }, "Child output materialize refused");
+                    }
+                    else {
+                        // undefined: the contained write itself failed (the store already
+                        // logged it). Degrade to the summary + diskPath WITHOUT a WARN — no
+                        // double-report; a DEBUG of the no-handle degrade is sufficient.
+                        deps.logger?.debug({
+                            runId, step: "child-result-materialize",
+                        }, "Child output materialize produced no handle; using condensed summary + diskPath");
+                    }
+                }
                 // Emit completion event
                 const isSuccess = result.finishReason === "stop" || result.finishReason === "end_turn";
                 deps.eventBus.emit("session:sub_agent_completed", {
@@ -807,6 +1357,7 @@ export function createSubAgentRunner(deps) {
                             task: params.task,
                             runtimeMs,
                             runId,
+                            callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
                         }, deps);
                     }
                 }
@@ -827,6 +1378,9 @@ export function createSubAgentRunner(deps) {
                                 tokensUsed: result.tokensUsed.total,
                                 cost: result.cost.total,
                                 sessionKey: formattedKey,
+                                // SUMREF-02: the materialized handle (when produced) so the tagged
+                                // announcement carries the drill-in handle, not the diskPath.
+                                resultRef: materializedRef,
                             });
                         }
                         else {
@@ -835,7 +1389,7 @@ export function createSubAgentRunner(deps) {
                                 task: params.task,
                                 status: "completed",
                                 response: condensedResult
-                                    ? `${condensedResult.result.summary}\n\nFull result: ${condensedResult.diskPath}`
+                                    ? `${condensedResult.result.summary}${fullResultLine}`
                                     : sanitizeAssistantResponse(result.response),
                                 runtimeMs,
                                 stepsExecuted: result.stepsExecuted,
@@ -900,6 +1454,7 @@ export function createSubAgentRunner(deps) {
                 const completedAt = clock.now();
                 run.status = "failed";
                 run.completedAt = completedAt;
+                removeDedupEntry(run);
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 run.error = errorMessage;
                 const runtimeMs = completedAt - run.startedAt;
@@ -969,6 +1524,7 @@ export function createSubAgentRunner(deps) {
                         task: params.task,
                         runtimeMs,
                         runId,
+                        callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
                     }, deps);
                 }
                 else {
@@ -1019,6 +1575,7 @@ export function createSubAgentRunner(deps) {
             run.status = "failed";
             run.completedAt = completedAt;
             run.error = `Execution timeout: exceeded ${runTimeoutMs}ms wall-clock limit`;
+            removeDedupEntry(run);
             deps.logger?.error({
                 runId, agentId: run.agentId,
                 runtimeMs, timeoutMs: runTimeoutMs,
@@ -1037,7 +1594,7 @@ export function createSubAgentRunner(deps) {
                     runtimeMs,
                 }, deps.logger), "watchdog-failure-record");
             }
-            // Abort SDK session via composite-key resolver (R3 / B37). The
+            // Abort SDK session via composite-key resolver. The
             // previous lookup keyed on the formatted sessionKey only; the
             // resolver makes the `(agentId, channelType, channelId)` triple
             // explicit so multi-agent collisions are distinguishable.
@@ -1064,6 +1621,7 @@ export function createSubAgentRunner(deps) {
                     task: params.task,
                     runtimeMs,
                     runId,
+                    callerSessionKey: params.callerSessionKey, // DELIVERY-03: shared dedup key
                     // eslint-disable-next-line no-restricted-syntax -- intentional fire-and-forget
                 }, deps).catch(() => { });
             }
@@ -1092,6 +1650,20 @@ export function createSubAgentRunner(deps) {
         activePromises.add(execPromise);
         execPromise.finally(() => {
             activePromises.delete(execPromise);
+            // CR-02: release the tree-wide ceiling slot this run reserved (idempotent;
+            // a no-op for promoted queued runs, which never acquired). This fires for
+            // EVERY started run on its terminal settle — completion, failure, AND a
+            // kill/ghost/watchdog (those mark the run failed but the underlying
+            // executeAgent promise still settles here), so a long-running tree's slots
+            // are reclaimed rather than monotonically leaking.
+            releaseCeilingSlotOnce(run);
+            // Phase 216 (DUR-01 / HB-01): the SAME universal terminal seam — mark the
+            // durable record completed + clear its keep-alive heartbeat (no leaked
+            // interval). Inert + idempotent when no durable store is wired.
+            finishDurableCheckpoint(run);
+            // COORD-03: stop the read-only progress fork on the same universal terminal
+            // seam so it never outlives the child (no leaked timer; T-218-15).
+            stopProgressFork(run);
             // Drain queue when a slot opens (use abortGroup for graph-scoped draining)
             const drainKey = run.abortGroup ?? run.callerSessionKey;
             if (drainKey) {
@@ -1128,6 +1700,32 @@ export function createSubAgentRunner(deps) {
     function getRunStatus(runId) {
         return runs.get(runId);
     }
+    /**
+     * Resolve the running/queued sub-agent run whose child session key equals
+     * `sessionKey` (Phase 213 CR-01). When a sub-agent itself calls
+     * `sessions_spawn`, the dispatcher injects ITS session key as the spawn's
+     * `_callerSessionKey`; that key is exactly the spawning run's `run.sessionKey`.
+     * The daemon spawn handler uses this to make a descendant INHERIT its parent
+     * run's tree-stable `rootRunId`/`parentLeaseId` instead of minting a fresh root
+     * (the fork-bomb-defeating defect). Returns the most-recently-started match
+     * among live runs; `undefined` for a top-level (operator) caller whose session
+     * is not a sub-agent run. Terminal runs are ignored (a finished parent cannot
+     * own a new child).
+     */
+    function getRunBySessionKey(sessionKey) {
+        if (!sessionKey)
+            return undefined;
+        let best;
+        for (const run of runs.values()) {
+            if (run.sessionKey !== sessionKey)
+                continue;
+            if (run.status !== "running" && run.status !== "queued")
+                continue;
+            if (!best || run.startedAt > best.startedAt)
+                best = run;
+        }
+        return best;
+    }
     /**
      * List tracked sub-agent runs, optionally filtered by recency.
      * @param recentMinutes - Only include runs started within the last N minutes.
@@ -1160,6 +1758,7 @@ export function createSubAgentRunner(deps) {
         }
         run.status = "failed";
         run.completedAt = clock.now();
+        removeDedupEntry(run);
         run.error = "Killed by parent agent";
         // Persist failure record for killed runs (fire-and-forget, belt-defense)
         if (deps.dataDir) {
@@ -1174,7 +1773,7 @@ export function createSubAgentRunner(deps) {
             }, deps.logger), "kill-failure-record");
         }
         // Abort the in-flight SDK session via composite-key resolver
-        // (R3 / B37, best-effort).
+        // (best-effort).
         if (deps.sessionResolver) {
             const handle = deps.sessionResolver.resolveActiveSession(deriveCompositeForRun(run));
             if (handle) {
@@ -1230,6 +1829,60 @@ export function createSubAgentRunner(deps) {
         }
         return { killed: true };
     }
+    /**
+     * REVOKE-03: hard-stop a whole spawn tree. Fans the per-run {@link killRun}
+     * (which marks the run failed and aborts its in-flight SDK session) over every
+     * running/queued run sharing `rootRunId`, and returns the count killed.
+     *
+     * Filters STRICTLY on `run.rootRunId === rootRunId` (threat T-213-01-02 — a
+     * different tree must be untouched) and on the same status guard killRun uses,
+     * so already-terminal runs are skipped. An unknown root is a clean no-op
+     * (`{ killed: 0 }`), never a throw — the count return is the contract the
+     * daemon-side `run.kill` RPC handler (the @allow-throw boundary, Plan 06)
+     * drives; this helper itself raises nothing (the raw-throw.test.ts gate).
+     */
+    function killByRootRun(rootRunId) {
+        let killed = 0;
+        for (const run of runs.values()) {
+            if (run.rootRunId === rootRunId &&
+                (run.status === "running" || run.status === "queued")) {
+                if (killRun(run.runId).killed)
+                    killed++;
+            }
+        }
+        return { killed };
+    }
+    /**
+     * STEER-01: inject a steer message into a RUNNING child's live SDK session
+     * (mid-flight steering), distinct from killRun. Delegates to the steer-run.ts
+     * helper to keep the mechanism OUT of this (already large) file.
+     *
+     * L2 — widen the resolver/registry surface at the delegation boundary: this
+     * runner's `deps.sessionResolver`/`deps.activeRunRegistry` are typed to the
+     * narrowed `{ abort(): Promise<void> }` (the kill path only needs abort, and
+     * the narrow type avoids a daemon→agent import cycle in those Deps). steerRun
+     * needs the FULL RunHandle (steer/followUp/isStreaming/isCompacting). The
+     * RUNTIME handle is complete — pi-executor.ts:1161 builds all five and
+     * registers it under the SAME key the resolver composes (175-00 spike). So
+     * we re-type the lookups to the full RunHandle at this boundary; this is a
+     * pure TS surface widening over an object that already has the methods, not
+     * a behavior change.
+     */
+    async function steerRun(runId, message) {
+        const steerDeps = {
+            // SubAgentRun structurally satisfies SteerableRun (the minimal slice the
+            // helper reads); Map is invariant in its value type, so cast at the
+            // boundary. steerRun READS only — it never `set`s into the map.
+            runs: runs,
+            // Runtime handle is complete (pi-executor.ts:1161); the narrowed {abort()}
+            // Deps type omits steer/followUp/isStreaming/isCompacting that the runtime
+            // object carries — re-type to the full RunHandle for the inject delegation.
+            sessionResolver: deps.sessionResolver,
+            activeRunRegistry: deps.activeRunRegistry,
+            logger: deps.logger,
+        };
+        return steerRunHelper(steerDeps, runId, message);
+    }
     async function shutdown() {
         sweepInterval.cancel();
         // Flush any batched announcements before draining active runs
@@ -1239,7 +1892,7 @@ export function createSubAgentRunner(deps) {
         // Drain dead-letter queue before shutdown
         if (deps.deadLetterQueue) {
             try {
-                await deps.deadLetterQueue.drain(deps.sendToChannel);
+                await deps.deadLetterQueue.drain(deps.sendToChannel, markRecoveredDelivered);
             }
             catch {
                 // Best-effort drain on shutdown
@@ -1261,5 +1914,16 @@ export function createSubAgentRunner(deps) {
     function setGraphCoordinator(gc) {
         graphCoordinatorRef = gc;
     }
-    return { spawn, getRunStatus, listRuns, killRun, shutdown, setGraphCoordinator };
+    /**
+     * Return the most recent dedup hit observed by `spawn()`. Cleared at the
+     * start of every `spawn()` call so each invocation surfaces a fresh signal.
+     * Used by `session.spawn` RPC handler to set `deduped: true, existingRunId,
+     * dedupAgeMs` on the response when an LLM duplicate-spawned the same task.
+     */
+    function lastSpawnDedupInfo() {
+        if (!lastDedupHit)
+            return undefined;
+        return { deduped: true, existingRunId: lastDedupHit.existingRunId, ageMs: lastDedupHit.ageMs };
+    }
+    return { spawn, getRunStatus, getRunBySessionKey, listRuns, killRun, killByRootRun, steerRun, shutdown, setGraphCoordinator, lastSpawnDedupInfo };
 }