@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/agents/subagent-registry.js

@@ -5,7 +5,11 @@ import { defaultRuntime } from "../runtime.js";
 import { normalizeDeliveryContext } from "../utils/delivery-context.js";
 import { resetAnnounceQueuesForTests } from "./subagent-announce-queue.js";
 import { runSubagentAnnounceFlow } from "./subagent-announce.js";
-import { loadSubagentRegistryFromDisk, saveSubagentRegistryToDisk, } from "./subagent-registry.store.js";
+import { SUBAGENT_ENDED_OUTCOME_KILLED, SUBAGENT_ENDED_REASON_COMPLETE, SUBAGENT_ENDED_REASON_ERROR, SUBAGENT_ENDED_REASON_KILLED, } from "./subagent-lifecycle-events.js";
+import { resolveCleanupCompletionReason, resolveDeferredCleanupDecision, } from "./subagent-registry-cleanup.js";
+import { emitSubagentEndedHookOnce, resolveLifecycleOutcomeFromRunOutcome, runOutcomesEqual, } from "./subagent-registry-completion.js";
+import { countActiveDescendantRunsFromRuns, countActiveRunsForSessionFromRuns, findRunIdsByChildSessionKeyFromRuns, listDescendantRunsForRequesterFromRuns, listRunsForRequesterFromRuns, resolveRequesterForChildSessionFromRuns, } from "./subagent-registry-queries.js";
+import { getSubagentRunsSnapshotForRead, persistSubagentRunsToDisk, restoreSubagentRunsFromDisk, } from "./subagent-registry-state.js";
 import { resolveAgentTimeoutMs } from "./timeout.js";
 const subagentRuns = new Map();
 let sweeper = null;
@@ -41,17 +45,85 @@ function logAnnounceGiveUp(entry, reason) {
     defaultRuntime.log(`[warn] Subagent announce give up (${reason}) run=${entry.runId} child=${entry.childSessionKey} requester=${entry.requesterSessionKey} retries=${retryCount} endedAgo=${endedAgoLabel}`);
 }
 function persistSubagentRuns() {
-    try {
-        saveSubagentRegistryToDisk(subagentRuns);
-    }
-    catch {
-        // ignore persistence failures
-    }
+    persistSubagentRunsToDisk(subagentRuns);
 }
 const resumedRuns = new Set();
+const endedHookInFlightRunIds = new Set();
 function suppressAnnounceForSteerRestart(entry) {
     return entry?.suppressAnnounceReason === "steer-restart";
 }
+function shouldKeepThreadBindingAfterRun(params) {
+    if (params.reason === SUBAGENT_ENDED_REASON_KILLED) {
+        return false;
+    }
+    return params.entry.spawnMode === "session";
+}
+function shouldEmitEndedHookForRun(params) {
+    return !shouldKeepThreadBindingAfterRun(params);
+}
+async function emitSubagentEndedHookForRun(params) {
+    const reason = params.reason ?? params.entry.endedReason ?? SUBAGENT_ENDED_REASON_COMPLETE;
+    const outcome = resolveLifecycleOutcomeFromRunOutcome(params.entry.outcome);
+    const error = params.entry.outcome?.status === "error" ? params.entry.outcome.error : undefined;
+    await emitSubagentEndedHookOnce({
+        entry: params.entry,
+        reason,
+        sendFarewell: params.sendFarewell,
+        accountId: params.accountId ?? params.entry.requesterOrigin?.accountId,
+        outcome,
+        error,
+        inFlightRunIds: endedHookInFlightRunIds,
+        persist: persistSubagentRuns,
+    });
+}
+async function completeSubagentRun(params) {
+    const entry = subagentRuns.get(params.runId);
+    if (!entry) {
+        return;
+    }
+    let mutated = false;
+    const endedAt = typeof params.endedAt === "number" ? params.endedAt : Date.now();
+    if (entry.endedAt !== endedAt) {
+        entry.endedAt = endedAt;
+        mutated = true;
+    }
+    if (!runOutcomesEqual(entry.outcome, params.outcome)) {
+        entry.outcome = params.outcome;
+        mutated = true;
+    }
+    if (entry.endedReason !== params.reason) {
+        entry.endedReason = params.reason;
+        mutated = true;
+    }
+    if (mutated) {
+        persistSubagentRuns();
+    }
+    const suppressedForSteerRestart = suppressAnnounceForSteerRestart(entry);
+    const shouldEmitEndedHook = !suppressedForSteerRestart &&
+        shouldEmitEndedHookForRun({
+            entry,
+            reason: params.reason,
+        });
+    const shouldDeferEndedHook = shouldEmitEndedHook &&
+        params.triggerCleanup &&
+        entry.expectsCompletionMessage === true &&
+        !suppressedForSteerRestart;
+    if (!shouldDeferEndedHook && shouldEmitEndedHook) {
+        await emitSubagentEndedHookForRun({
+            entry,
+            reason: params.reason,
+            sendFarewell: params.sendFarewell,
+            accountId: params.accountId,
+        });
+    }
+    if (!params.triggerCleanup) {
+        return;
+    }
+    if (suppressedForSteerRestart) {
+        return;
+    }
+    startSubagentAnnounceCleanupFlow(params.runId, entry);
+}
 function startSubagentAnnounceCleanupFlow(runId, entry) {
     if (!beginSubagentCleanup(runId)) {
         return false;
@@ -64,7 +136,6 @@ function startSubagentAnnounceCleanupFlow(runId, entry) {
         requesterOrigin,
         requesterDisplayKey: entry.requesterDisplayKey,
         task: entry.task,
-        expectsCompletionMessage: entry.expectsCompletionMessage,
         timeoutMs: SUBAGENT_ANNOUNCE_TIMEOUT_MS,
         cleanup: entry.cleanup,
         waitForCompletion: false,
@@ -72,8 +143,10 @@ function startSubagentAnnounceCleanupFlow(runId, entry) {
         endedAt: entry.endedAt,
         label: entry.label,
         outcome: entry.outcome,
+        spawnMode: entry.spawnMode,
+        expectsCompletionMessage: entry.expectsCompletionMessage,
     }).then((didAnnounce) => {
-        finalizeSubagentCleanup(runId, entry.cleanup, didAnnounce);
+        void finalizeSubagentCleanup(runId, entry.cleanup, didAnnounce);
     });
     return true;
 }
@@ -137,19 +210,13 @@ function restoreSubagentRunsOnce() {
     }
     restoreAttempted = true;
     try {
-        const restored = loadSubagentRegistryFromDisk();
-        if (restored.size === 0) {
+        const restoredCount = restoreSubagentRunsFromDisk({
+            runs: subagentRuns,
+            mergeOnly: true,
+        });
+        if (restoredCount === 0) {
             return;
         }
-        for (const [runId, entry] of restored.entries()) {
-            if (!runId || !entry) {
-                continue;
-            }
-            // Keep any newer in-memory entries.
-            if (!subagentRuns.has(runId)) {
-                subagentRuns.set(runId, entry);
-            }
-        }
         // Resume pending work.
         ensureListener();
         if ([...subagentRuns.values()].some((entry) => entry.archiveAtMs)) {
@@ -202,7 +269,11 @@ async function sweepSubagentRuns() {
         try {
             await callGateway({
                 method: "sessions.delete",
-                params: { key: entry.childSessionKey, deleteTranscript: true },
+                params: {
+                    key: entry.childSessionKey,
+                    deleteTranscript: true,
+                    emitLifecycleHooks: false,
+                },
                 timeoutMs: 10_000,
             });
         }
@@ -223,87 +294,131 @@ function ensureListener() {
     }
     listenerStarted = true;
     listenerStop = onAgentEvent((evt) => {
-        if (!evt || evt.stream !== "lifecycle") {
-            return;
-        }
-        const entry = subagentRuns.get(evt.runId);
-        if (!entry) {
-            return;
-        }
-        const phase = evt.data?.phase;
-        if (phase === "start") {
-            const startedAt = typeof evt.data?.startedAt === "number" ? evt.data.startedAt : undefined;
-            if (startedAt) {
-                entry.startedAt = startedAt;
-                persistSubagentRuns();
+        void (async () => {
+            if (!evt || evt.stream !== "lifecycle") {
+                return;
             }
-            return;
-        }
-        if (phase !== "end" && phase !== "error") {
-            return;
-        }
-        const endedAt = typeof evt.data?.endedAt === "number" ? evt.data.endedAt : Date.now();
-        entry.endedAt = endedAt;
-        if (phase === "error") {
+            const entry = subagentRuns.get(evt.runId);
+            if (!entry) {
+                return;
+            }
+            const phase = evt.data?.phase;
+            if (phase === "start") {
+                const startedAt = typeof evt.data?.startedAt === "number" ? evt.data.startedAt : undefined;
+                if (startedAt) {
+                    entry.startedAt = startedAt;
+                    persistSubagentRuns();
+                }
+                return;
+            }
+            if (phase !== "end" && phase !== "error") {
+                return;
+            }
+            const endedAt = typeof evt.data?.endedAt === "number" ? evt.data.endedAt : Date.now();
             const error = typeof evt.data?.error === "string" ? evt.data.error : undefined;
-            entry.outcome = { status: "error", error };
-        }
-        else if (evt.data?.aborted) {
-            entry.outcome = { status: "timeout" };
-        }
-        else {
-            entry.outcome = { status: "ok" };
-        }
-        persistSubagentRuns();
-        if (suppressAnnounceForSteerRestart(entry)) {
-            return;
-        }
-        if (!startSubagentAnnounceCleanupFlow(evt.runId, entry)) {
-            return;
-        }
+            const outcome = phase === "error"
+                ? { status: "error", error }
+                : evt.data?.aborted
+                    ? { status: "timeout" }
+                    : { status: "ok" };
+            await completeSubagentRun({
+                runId: evt.runId,
+                endedAt,
+                outcome,
+                reason: phase === "error" ? SUBAGENT_ENDED_REASON_ERROR : SUBAGENT_ENDED_REASON_COMPLETE,
+                sendFarewell: true,
+                accountId: entry.requesterOrigin?.accountId,
+                triggerCleanup: true,
+            });
+        })();
     });
 }
-function finalizeSubagentCleanup(runId, cleanup, didAnnounce) {
+async function finalizeSubagentCleanup(runId, cleanup, didAnnounce) {
     const entry = subagentRuns.get(runId);
     if (!entry) {
         return;
     }
-    if (!didAnnounce) {
-        const now = Date.now();
-        const retryCount = (entry.announceRetryCount ?? 0) + 1;
-        entry.announceRetryCount = retryCount;
+    if (didAnnounce) {
+        const completionReason = resolveCleanupCompletionReason(entry);
+        await emitCompletionEndedHookIfNeeded(entry, completionReason);
+        completeCleanupBookkeeping({
+            runId,
+            entry,
+            cleanup,
+            completedAt: Date.now(),
+        });
+        return;
+    }
+    const now = Date.now();
+    const deferredDecision = resolveDeferredCleanupDecision({
+        entry,
+        now,
+        activeDescendantRuns: Math.max(0, countActiveDescendantRuns(entry.childSessionKey)),
+        announceExpiryMs: ANNOUNCE_EXPIRY_MS,
+        maxAnnounceRetryCount: MAX_ANNOUNCE_RETRY_COUNT,
+        deferDescendantDelayMs: MIN_ANNOUNCE_RETRY_DELAY_MS,
+        resolveAnnounceRetryDelayMs,
+    });
+    if (deferredDecision.kind === "defer-descendants") {
         entry.lastAnnounceRetryAt = now;
-        // Check if the announce has exceeded retry limits or expired (#18264).
-        const endedAgo = typeof entry.endedAt === "number" ? now - entry.endedAt : 0;
-        if (retryCount >= MAX_ANNOUNCE_RETRY_COUNT || endedAgo > ANNOUNCE_EXPIRY_MS) {
-            // Give up: mark as completed to break the infinite retry loop.
-            logAnnounceGiveUp(entry, retryCount >= MAX_ANNOUNCE_RETRY_COUNT ? "retry-limit" : "expiry");
-            entry.cleanupCompletedAt = now;
-            persistSubagentRuns();
-            retryDeferredCompletedAnnounces(runId);
-            return;
-        }
-        // Allow retry on the next wake if announce was deferred or failed.
         entry.cleanupHandled = false;
         resumedRuns.delete(runId);
         persistSubagentRuns();
-        if (entry.expectsCompletionMessage !== true) {
-            return;
-        }
         setTimeout(() => {
             resumeSubagentRun(runId);
-        }, resolveAnnounceRetryDelayMs(entry.announceRetryCount ?? 0)).unref?.();
+        }, deferredDecision.delayMs).unref?.();
         return;
     }
-    if (cleanup === "delete") {
-        subagentRuns.delete(runId);
+    if (deferredDecision.retryCount != null) {
+        entry.announceRetryCount = deferredDecision.retryCount;
+        entry.lastAnnounceRetryAt = now;
+    }
+    if (deferredDecision.kind === "give-up") {
+        const completionReason = resolveCleanupCompletionReason(entry);
+        await emitCompletionEndedHookIfNeeded(entry, completionReason);
+        logAnnounceGiveUp(entry, deferredDecision.reason);
+        completeCleanupBookkeeping({
+            runId,
+            entry,
+            cleanup: "keep",
+            completedAt: now,
+        });
+        return;
+    }
+    // Allow retry on the next wake if announce was deferred or failed.
+    entry.cleanupHandled = false;
+    resumedRuns.delete(runId);
+    persistSubagentRuns();
+    if (deferredDecision.resumeDelayMs == null) {
+        return;
+    }
+    setTimeout(() => {
+        resumeSubagentRun(runId);
+    }, deferredDecision.resumeDelayMs).unref?.();
+}
+async function emitCompletionEndedHookIfNeeded(entry, reason) {
+    if (entry.expectsCompletionMessage === true &&
+        shouldEmitEndedHookForRun({
+            entry,
+            reason,
+        })) {
+        await emitSubagentEndedHookForRun({
+            entry,
+            reason,
+            sendFarewell: true,
+        });
+    }
+}
+function completeCleanupBookkeeping(params) {
+    if (params.cleanup === "delete") {
+        subagentRuns.delete(params.runId);
         persistSubagentRuns();
-        retryDeferredCompletedAnnounces(runId);
+        retryDeferredCompletedAnnounces(params.runId);
         return;
     }
-    entry.cleanupCompletedAt = Date.now();
+    params.entry.cleanupCompletedAt = params.completedAt;
     persistSubagentRuns();
-    retryDeferredCompletedAnnounces(runId);
+    retryDeferredCompletedAnnounces(params.runId);
 }
 function retryDeferredCompletedAnnounces(excludeRunId) {
     const now = Date.now();
@@ -403,7 +518,8 @@ export function replaceSubagentRunAfterSteer(params) {
     const now = Date.now();
     const cfg = loadConfig();
     const archiveAfterMs = resolveArchiveAfterMs(cfg);
-    const archiveAtMs = archiveAfterMs ? now + archiveAfterMs : undefined;
+    const spawnMode = source.spawnMode === "session" ? "session" : "run";
+    const archiveAtMs = spawnMode === "session" ? undefined : archiveAfterMs ? now + archiveAfterMs : undefined;
     const runTimeoutSeconds = params.runTimeoutSeconds ?? source.runTimeoutSeconds ?? 0;
     const waitTimeoutMs = resolveSubagentWaitTimeoutMs(cfg, runTimeoutSeconds);
     const next = {
@@ -411,12 +527,15 @@ export function replaceSubagentRunAfterSteer(params) {
         runId: nextRunId,
         startedAt: now,
         endedAt: undefined,
+        endedReason: undefined,
+        endedHookEmittedAt: undefined,
         outcome: undefined,
         cleanupCompletedAt: undefined,
         cleanupHandled: false,
         suppressAnnounceReason: undefined,
         announceRetryCount: undefined,
         lastAnnounceRetryAt: undefined,
+        spawnMode,
         archiveAtMs,
         runTimeoutSeconds,
     };
@@ -433,7 +552,8 @@ export function registerSubagentRun(params) {
     const now = Date.now();
     const cfg = loadConfig();
     const archiveAfterMs = resolveArchiveAfterMs(cfg);
-    const archiveAtMs = archiveAfterMs ? now + archiveAfterMs : undefined;
+    const spawnMode = params.spawnMode === "session" ? "session" : "run";
+    const archiveAtMs = spawnMode === "session" ? undefined : archiveAfterMs ? now + archiveAfterMs : undefined;
     const runTimeoutSeconds = params.runTimeoutSeconds ?? 0;
     const waitTimeoutMs = resolveSubagentWaitTimeoutMs(cfg, runTimeoutSeconds);
     const requesterOrigin = normalizeDeliveryContext(params.requesterOrigin);
@@ -446,6 +566,7 @@ export function registerSubagentRun(params) {
         task: params.task,
         cleanup: params.cleanup,
         expectsCompletionMessage: params.expectsCompletionMessage,
+        spawnMode,
         label: params.label,
         model: params.model,
         runTimeoutSeconds,
@@ -456,7 +577,7 @@ export function registerSubagentRun(params) {
     });
     ensureListener();
     persistSubagentRuns();
-    if (archiveAfterMs) {
+    if (archiveAtMs) {
         startSweeper();
     }
     // Wait for subagent completion via gateway RPC (cross-process).
@@ -495,22 +616,27 @@ async function waitForSubagentCompletion(runId, waitTimeoutMs) {
             mutated = true;
         }
         const waitError = typeof wait.error === "string" ? wait.error : undefined;
-        entry.outcome =
-            wait.status === "error"
-                ? { status: "error", error: waitError }
-                : wait.status === "timeout"
-                    ? { status: "timeout" }
-                    : { status: "ok" };
-        mutated = true;
+        const outcome = wait.status === "error"
+            ? { status: "error", error: waitError }
+            : wait.status === "timeout"
+                ? { status: "timeout" }
+                : { status: "ok" };
+        if (!runOutcomesEqual(entry.outcome, outcome)) {
+            entry.outcome = outcome;
+            mutated = true;
+        }
         if (mutated) {
             persistSubagentRuns();
         }
-        if (suppressAnnounceForSteerRestart(entry)) {
-            return;
-        }
-        if (!startSubagentAnnounceCleanupFlow(runId, entry)) {
-            return;
-        }
+        await completeSubagentRun({
+            runId,
+            endedAt: entry.endedAt,
+            outcome,
+            reason: wait.status === "error" ? SUBAGENT_ENDED_REASON_ERROR : SUBAGENT_ENDED_REASON_COMPLETE,
+            sendFarewell: true,
+            accountId: entry.requesterOrigin?.accountId,
+            triggerCleanup: true,
+        });
     }
     catch {
         // ignore
@@ -519,6 +645,7 @@ async function waitForSubagentCompletion(runId, waitTimeoutMs) {
 export function resetSubagentRegistryForTests(opts) {
     subagentRuns.clear();
     resumedRuns.clear();
+    endedHookInFlightRunIds.clear();
     resetAnnounceQueuesForTests();
     stopSweeper();
     restoreAttempted = false;
@@ -544,58 +671,16 @@ export function releaseSubagentRun(runId) {
     }
 }
 function findRunIdsByChildSessionKey(childSessionKey) {
-    const key = childSessionKey.trim();
-    if (!key) {
-        return [];
-    }
-    const runIds = [];
-    for (const [runId, entry] of subagentRuns.entries()) {
-        if (entry.childSessionKey === key) {
-            runIds.push(runId);
-        }
-    }
-    return runIds;
-}
-function getRunsSnapshotForRead() {
-    const merged = new Map();
-    const shouldReadDisk = !(process.env.VITEST || process.env.NODE_ENV === "test");
-    if (shouldReadDisk) {
-        try {
-            // Registry state is persisted to disk so other worker processes (for
-            // example cron runners) can observe active children spawned elsewhere.
-            for (const [runId, entry] of loadSubagentRegistryFromDisk().entries()) {
-                merged.set(runId, entry);
-            }
-        }
-        catch {
-            // Ignore disk read failures and fall back to local memory state.
-        }
-    }
-    for (const [runId, entry] of subagentRuns.entries()) {
-        merged.set(runId, entry);
-    }
-    return merged;
+    return findRunIdsByChildSessionKeyFromRuns(subagentRuns, childSessionKey);
 }
 export function resolveRequesterForChildSession(childSessionKey) {
-    const key = childSessionKey.trim();
-    if (!key) {
-        return null;
-    }
-    let best;
-    for (const entry of getRunsSnapshotForRead().values()) {
-        if (entry.childSessionKey !== key) {
-            continue;
-        }
-        if (!best || entry.createdAt > best.createdAt) {
-            best = entry;
-        }
-    }
-    if (!best) {
+    const resolved = resolveRequesterForChildSessionFromRuns(getSubagentRunsSnapshotForRead(subagentRuns), childSessionKey);
+    if (!resolved) {
         return null;
     }
     return {
-        requesterSessionKey: best.requesterSessionKey,
-        requesterOrigin: normalizeDeliveryContext(best.requesterOrigin),
+        requesterSessionKey: resolved.requesterSessionKey,
+        requesterOrigin: normalizeDeliveryContext(resolved.requesterOrigin),
     };
 }
 export function isSubagentSessionRunActive(childSessionKey) {
@@ -627,6 +712,7 @@ export function markSubagentRunTerminated(params) {
     const now = Date.now();
     const reason = params.reason?.trim() || "killed";
     let updated = 0;
+    const entriesByChildSessionKey = new Map();
     for (const runId of runIds) {
         const entry = subagentRuns.get(runId);
         if (!entry) {
@@ -637,99 +723,44 @@ export function markSubagentRunTerminated(params) {
         }
         entry.endedAt = now;
         entry.outcome = { status: "error", error: reason };
+        entry.endedReason = SUBAGENT_ENDED_REASON_KILLED;
         entry.cleanupHandled = true;
         entry.cleanupCompletedAt = now;
         entry.suppressAnnounceReason = "killed";
+        if (!entriesByChildSessionKey.has(entry.childSessionKey)) {
+            entriesByChildSessionKey.set(entry.childSessionKey, entry);
+        }
         updated += 1;
     }
     if (updated > 0) {
         persistSubagentRuns();
+        for (const entry of entriesByChildSessionKey.values()) {
+            void emitSubagentEndedHookOnce({
+                entry,
+                reason: SUBAGENT_ENDED_REASON_KILLED,
+                sendFarewell: true,
+                outcome: SUBAGENT_ENDED_OUTCOME_KILLED,
+                error: reason,
+                inFlightRunIds: endedHookInFlightRunIds,
+                persist: persistSubagentRuns,
+            }).catch(() => {
+                // Hook failures should not break termination flow.
+            });
+        }
     }
     return updated;
 }
 export function listSubagentRunsForRequester(requesterSessionKey) {
-    const key = requesterSessionKey.trim();
-    if (!key) {
-        return [];
-    }
-    return [...subagentRuns.values()].filter((entry) => entry.requesterSessionKey === key);
+    return listRunsForRequesterFromRuns(subagentRuns, requesterSessionKey);
 }
 export function countActiveRunsForSession(requesterSessionKey) {
-    const key = requesterSessionKey.trim();
-    if (!key) {
-        return 0;
-    }
-    let count = 0;
-    for (const entry of getRunsSnapshotForRead().values()) {
-        if (entry.requesterSessionKey !== key) {
-            continue;
-        }
-        if (typeof entry.endedAt === "number") {
-            continue;
-        }
-        count += 1;
-    }
-    return count;
+    return countActiveRunsForSessionFromRuns(getSubagentRunsSnapshotForRead(subagentRuns), requesterSessionKey);
 }
 export function countActiveDescendantRuns(rootSessionKey) {
-    const root = rootSessionKey.trim();
-    if (!root) {
-        return 0;
-    }
-    const runs = getRunsSnapshotForRead();
-    const pending = [root];
-    const visited = new Set([root]);
-    let count = 0;
-    while (pending.length > 0) {
-        const requester = pending.shift();
-        if (!requester) {
-            continue;
-        }
-        for (const entry of runs.values()) {
-            if (entry.requesterSessionKey !== requester) {
-                continue;
-            }
-            if (typeof entry.endedAt !== "number") {
-                count += 1;
-            }
-            const childKey = entry.childSessionKey.trim();
-            if (!childKey || visited.has(childKey)) {
-                continue;
-            }
-            visited.add(childKey);
-            pending.push(childKey);
-        }
-    }
-    return count;
+    return countActiveDescendantRunsFromRuns(getSubagentRunsSnapshotForRead(subagentRuns), rootSessionKey);
 }
 export function listDescendantRunsForRequester(rootSessionKey) {
-    const root = rootSessionKey.trim();
-    if (!root) {
-        return [];
-    }
-    const runs = getRunsSnapshotForRead();
-    const pending = [root];
-    const visited = new Set([root]);
-    const descendants = [];
-    while (pending.length > 0) {
-        const requester = pending.shift();
-        if (!requester) {
-            continue;
-        }
-        for (const entry of runs.values()) {
-            if (entry.requesterSessionKey !== requester) {
-                continue;
-            }
-            descendants.push(entry);
-            const childKey = entry.childSessionKey.trim();
-            if (!childKey || visited.has(childKey)) {
-                continue;
-            }
-            visited.add(childKey);
-            pending.push(childKey);
-        }
-    }
-    return descendants;
+    return listDescendantRunsForRequesterFromRuns(getSubagentRunsSnapshotForRead(subagentRuns), rootSessionKey);
 }
 export function initSubagentRegistry() {
     restoreSubagentRunsOnce();

package/dist/agents/subagent-registry.mocks.shared.js

@@ -0,0 +1,12 @@
+import { vi } from "vitest";
+const noop = () => { };
+vi.mock("../gateway/call.js", () => ({
+    callGateway: vi.fn(async () => ({
+        status: "ok",
+        startedAt: 111,
+        endedAt: 222,
+    })),
+}));
+vi.mock("../infra/agent-events.js", () => ({
+    onAgentEvent: vi.fn(() => noop),
+}));

package/dist/agents/subagent-registry.store.js

@@ -45,6 +45,7 @@ export function loadSubagentRegistryFromDisk() {
             requesterOrigin,
             cleanupCompletedAt,
             cleanupHandled,
+            spawnMode: typed.spawnMode === "session" ? "session" : "run",
         });
         if (isLegacy)
             migrated = true;

package/dist/agents/subagent-registry.types.js

@@ -0,0 +1 @@
+export {};