@myagentroam/agent 0.10.60 → 0.10.62

package/dist/agent-core/subagent/session-controller.js

@@ -4,12 +4,28 @@ import { randomUUID } from 'node:crypto';
 import { MarAgentError, describeMarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
 import { parseAgentWaitTargets, waitForAgentCondition } from './wait.js';
+const RECENT_TERMINAL_RESOURCE_LIMIT = 16;
+const DETAIL_FIELDS = [
+    'latestMessage',
+    'latestActivity',
+    'summary',
+    'changedFiles',
+    'verification',
+    'evidence',
+    'permissionStop',
+    'errorMessage'
+];
 export class SubagentSessionController {
     parentSessionId;
     rootSessionId;
     backend;
     limits;
     #agents = new Map();
+    // Discovery order is independent of the order in which history is requested.
+    #discovered = new Map();
+    #loading = new Map();
+    #readers = new Map();
+    #allReaders = 0;
     #queue = [];
     #completionWaiters = new Set();
     #activityWaiters = new Set();
@@ -35,7 +51,7 @@ export class SubagentSessionController {
     #retainedExecution = new AsyncLocalStorage();
     #execution;
     #pendingDeliveries = new Set();
-    constructor(parentSessionId, rootSessionId, backend, limits = { maxTasks: 8, maxConcurrent: 4 }) {
+    constructor(parentSessionId, rootSessionId, backend, limits = { maxTasks: 16, maxConcurrent: 16 }) {
         this.parentSessionId = parentSessionId;
         this.rootSessionId = rootSessionId;
         this.backend = backend;
@@ -43,11 +59,12 @@ export class SubagentSessionController {
     }
     static async open(input) {
         const controller = new SubagentSessionController(input.parentSessionId, input.rootSessionId, input.backend, input.limits);
-        const sessions = [...(await input.backend.listChildren(input.parentSessionId))].sort((a, b) => a.lastActivityAt.localeCompare(b.lastActivityAt));
-        for (const session of sessions) {
-            const state = restoreAgentState(session);
-            state.resourceRevision = ++controller.#resourceRevision;
-            controller.#agents.set(session.id, state);
+        const sessions = await input.backend.listChildren(input.parentSessionId);
+        // Map insertion order is creation order; values independently rank activity.
+        for (const session of sessions)
+            controller.#discovered.set(session.id, 0);
+        for (const session of [...sessions].sort((a, b) => a.lastActivityAt.localeCompare(b.lastActivityAt))) {
+            controller.#discovered.set(session.id, ++controller.#resourceRevision);
         }
         return controller;
     }
@@ -58,6 +75,7 @@ export class SubagentSessionController {
         this.#creationBudget = { count: 0 };
         for (const state of this.#agents.values())
             await this.#publishTerminal(state);
+        this.#releaseOldDetails();
     }
     /** A retained cell must not borrow a later model Execution's identity or task budget. */
     captureExecution(executionId) {
@@ -93,12 +111,63 @@ export class SubagentSessionController {
         return this.#retainedExecution.run({ execution: operation, budget: { count: 0 }, native: true }, run);
     }
     async inspect(agentId) {
-        return this.#snapshot(await this.#find(agentId), { full: true });
+        return this.#using([agentId], async () => {
+            return this.#snapshot(await this.#find(agentId), { full: true });
+        });
     }
     inspectAll() {
         if (this.#disposed)
             throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-        return [...this.#agents.values()].map((state) => this.#snapshot(state, { full: true }));
+        return this.#orderedStates().map((state) => this.#snapshot(state, { full: true }));
+    }
+    async list(signal) {
+        return this.#using(undefined, async () => {
+            await this.prepareAll(signal);
+            return this.inspectAll();
+        });
+    }
+    /** Full listing is explicit; ordinary opens and executions never require it. */
+    async prepareAll(signal) {
+        for (const id of this.#discovered.keys()) {
+            signal?.throwIfAborted();
+            await this.#restoreDiscovered(id);
+        }
+        signal?.throwIfAborted();
+    }
+    async prepareSessionResources(signal) {
+        const candidates = [...this.#discovered]
+            .filter(([id]) => {
+            const state = this.#agents.get(id);
+            return !state || isTerminalState(state);
+        })
+            .sort(([a, ar], [b, br]) => (this.#agents.get(b)?.resourceRevision ?? br) -
+            (this.#agents.get(a)?.resourceRevision ?? ar));
+        let prepared = 0;
+        for (const [id] of candidates) {
+            signal?.throwIfAborted();
+            const state = await this.#restoreDiscovered(id);
+            if (state && isTerminalState(state) && ++prepared === RECENT_TERMINAL_RESOURCE_LIMIT)
+                break;
+        }
+        signal?.throwIfAborted();
+        this.#releaseOldDetails();
+    }
+    async #restoreDiscovered(agentId) {
+        try {
+            return await this.#find(agentId);
+        }
+        catch (error) {
+            if (!(error instanceof MarAgentError) || error.code !== 'MAR_AGENT_SUBAGENT_NOT_FOUND')
+                throw error;
+            this.#discovered.delete(agentId);
+            return undefined;
+        }
+    }
+    #orderedStates() {
+        return [...this.#discovered.keys()].flatMap((id) => {
+            const state = this.#agents.get(id);
+            return state ? [state] : [];
+        });
     }
     collectModelUpdates() {
         return [...this.#agents.values()]
@@ -203,173 +272,125 @@ export class SubagentSessionController {
         catch (error) {
             await this.#deleteUnstartedSession(created.id, error);
         }
-        const state = {
-            agentId: created.id,
-            description: source.description,
-            role: input.role,
-            ...(source.ownerInstanceId === undefined ? {} : { ownerInstanceId: source.ownerInstanceId }),
-            ...(source.extensionId === undefined ? {} : { extensionId: source.extensionId }),
-            status: 'queued',
-            messageRevision: 0,
-            observedMessageRevision: 0,
-            latestMessageActivityRevision: 0,
-            changedFiles: [],
-            verification: [],
-            evidence: [],
-            terminalPending: false,
-            observedTerminalRevision: -1,
-            resourceRevision: ++this.#resourceRevision
-        };
-        if (!native)
-            (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
-        this.#agents.set(state.agentId, state);
-        const knownModel = execution.models.get(input.modelId ?? execution.modelId);
-        if (knownModel) {
-            state.modelId = knownModel.id;
-            state.modelName = knownModel.name;
-        }
-        try {
-            const selected = resolveModel(execution, input);
-            state.modelId = selected.id;
-            state.modelName = selected.name;
-            state.reasoningEffort = selected.reasoningEffort;
-        }
-        catch (error) {
-            this.#setFailure(state, error);
-        }
-        try {
-            await options.onCreated?.(this.#receiptSnapshot(state));
-            if (this.#disposed)
-                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-        }
-        catch (error) {
-            await this.#deleteUnstartedSession(state.agentId, error);
-        }
-        if (state.status === 'failed') {
-            await this.#publishTerminal(state);
-            this.#observeTerminal(state);
-            return this.#snapshot(state);
-        }
-        this.#queueTurn(state, input.prompt, execution, [], undefined, undefined, options.signal, options.turnSignal);
-        if (options.waitFor === 'start' || (options.waitFor === undefined && input.background))
-            return this.#receiptSnapshot(state);
-        await waitForPromise(state.turn.completion, options.signal);
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = this.#observeTerminal(state);
-        this.#observeLatestMessage(state);
-        return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
-    }
-    async output(agentId, options = {}) {
-        options.signal?.throwIfAborted();
-        const state = await this.#find(agentId);
-        options.signal?.throwIfAborted();
-        validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
-        if (options.untilSettled) {
-            if (state.turn)
-                await waitForPromise(state.turn.completion, options.signal);
-            options.signal?.throwIfAborted();
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = this.#observeTerminal(state);
-            this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
-            };
-        }
-        if (options.waitMs === undefined || options.waitMs === 0)
-            return {
-                ...this.#snapshot(state, {
-                    includeLatestMessage: false,
-                    includeTerminalDetails: false
-                }),
-                waitOutcome: 'snapshot'
+        return this.#using([created.id], async () => {
+            const state = {
+                agentId: created.id,
+                description: source.description,
+                role: input.role,
+                ...(source.ownerInstanceId === undefined
+                    ? {}
+                    : { ownerInstanceId: source.ownerInstanceId }),
+                ...(source.extensionId === undefined ? {} : { extensionId: source.extensionId }),
+                status: 'queued',
+                messageRevision: 0,
+                observedMessageRevision: 0,
+                latestMessageActivityRevision: 0,
+                changedFiles: [],
+                verification: [],
+                evidence: [],
+                terminalPending: false,
+                observedTerminalRevision: -1,
+                resourceRevision: ++this.#resourceRevision
             };
-        if (isTerminalState(state)) {
+            if (!native)
+                (this.#retainedExecution.getStore()?.budget ?? this.#creationBudget).count++;
+            this.#agents.set(state.agentId, state);
+            this.#discovered.set(state.agentId, state.resourceRevision);
+            const knownModel = execution.models.get(input.modelId ?? execution.modelId);
+            if (knownModel) {
+                state.modelId = knownModel.id;
+                state.modelName = knownModel.name;
+            }
+            try {
+                const selected = resolveModel(execution, input);
+                state.modelId = selected.id;
+                state.modelName = selected.name;
+                state.reasoningEffort = selected.reasoningEffort;
+            }
+            catch (error) {
+                this.#setFailure(state, error);
+            }
+            try {
+                await options.onCreated?.(this.#receiptSnapshot(state));
+                if (this.#disposed)
+                    throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+            }
+            catch (error) {
+                await this.#deleteUnstartedSession(state.agentId, error);
+            }
+            if (state.status === 'failed') {
+                await this.#publishTerminal(state);
+                this.#observeTerminal(state);
+                return this.#snapshot(state);
+            }
+            this.#queueTurn(state, input.prompt, execution, [], undefined, undefined, options.signal, options.turnSignal);
+            if (options.waitFor === 'start' || (options.waitFor === undefined && input.background))
+                return this.#receiptSnapshot(state);
+            await waitForPromise(state.turn.completion, options.signal);
             const includeLatestMessage = this.#hasUnreadMessage(state);
             const includeTerminalDetails = this.#observeTerminal(state);
             this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
-            };
-        }
-        const waitFor = options.waitFor ?? 'completion';
-        if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
-            this.#observeLatestMessage(state);
-            return { ...this.#snapshot(state), waitOutcome: 'message' };
-        }
-        const waitMs = this.#retainedExecution.getStore()?.native
-            ? options.waitMs
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitFor === 'completion') {
-            const completed = await this.#waitForCompletion(state, waitMs, options.signal, options.waitInterrupt);
+            return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        });
+    }
+    async output(agentId, options = {}) {
+        return this.#using([agentId], async () => {
             options.signal?.throwIfAborted();
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
-            if (includeLatestMessage)
+            const state = await this.#find(agentId);
+            options.signal?.throwIfAborted();
+            validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
+            if (options.untilSettled) {
+                if (state.turn)
+                    await waitForPromise(state.turn.completion, options.signal);
+                options.signal?.throwIfAborted();
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
                 this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
-            };
-        }
-        const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal, options.waitInterrupt);
-        options.signal?.throwIfAborted();
-        const includeLatestMessage = activity?.kind === 'message' ||
-            (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
-        const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
-        if (activity)
-            this.#observeLatestMessage(activity.state);
-        return {
-            ...this.#snapshot(activity?.state ?? state, {
-                includeLatestMessage,
-                includeTerminalDetails
-            }),
-            ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
-        };
-    }
-    async outputAny(options = {}) {
-        options.signal?.throwIfAborted();
-        if (options.untilSettled)
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires an agent id.');
-        validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
-        const states = [...this.#agents.values()];
-        if (states.length === 0)
-            throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
-        const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
-        if (options.waitMs === undefined || options.waitMs === 0)
-            return {
-                ...this.#snapshot(live.at(-1) ?? states.at(-1), {
-                    includeLatestMessage: false,
-                    includeTerminalDetails: false
-                }),
-                waitOutcome: 'snapshot'
-            };
-        if (live.length === 0) {
-            const state = states.at(-1);
-            const includeLatestMessage = this.#hasUnreadMessage(state);
-            const includeTerminalDetails = this.#observeTerminal(state);
-            this.#observeLatestMessage(state);
-            return {
-                ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: 'completion'
-            };
-        }
-        const waitFor = options.waitFor ?? 'completion';
-        if (waitFor === 'message') {
-            const pending = this.#oldestUnreadMessage(live);
-            if (pending) {
-                this.#observeLatestMessage(pending);
-                return { ...this.#snapshot(pending), waitOutcome: 'message' };
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
             }
-        }
-        const waitMs = this.#retainedExecution.getStore()?.native
-            ? options.waitMs
-            : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-        if (waitFor === 'message') {
-            const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal, options.waitInterrupt);
+            if (options.waitMs === undefined || options.waitMs === 0)
+                return {
+                    ...this.#snapshot(state, {
+                        includeLatestMessage: false,
+                        includeTerminalDetails: false
+                    }),
+                    waitOutcome: 'snapshot'
+                };
+            if (isTerminalState(state)) {
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
+                this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
+            }
+            const waitFor = options.waitFor ?? 'completion';
+            if (waitFor === 'message' && this.#hasUnreadMessage(state)) {
+                this.#observeLatestMessage(state);
+                return { ...this.#snapshot(state), waitOutcome: 'message' };
+            }
+            const waitMs = this.#retainedExecution.getStore()?.native
+                ? options.waitMs
+                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+            if (waitFor === 'completion') {
+                const completed = await this.#waitForCompletion(state, waitMs, options.signal, options.waitInterrupt);
+                options.signal?.throwIfAborted();
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
+                if (includeLatestMessage)
+                    this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
+                };
+            }
+            const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal, options.waitInterrupt);
             options.signal?.throwIfAborted();
             const includeLatestMessage = activity?.kind === 'message' ||
                 (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
@@ -377,27 +398,93 @@ export class SubagentSessionController {
             if (activity)
                 this.#observeLatestMessage(activity.state);
             return {
-                ...this.#snapshot(activity?.state ?? live.at(-1), {
+                ...this.#snapshot(activity?.state ?? state, {
                     includeLatestMessage,
                     includeTerminalDetails
                 }),
                 ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
             };
-        }
-        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal, options.waitInterrupt);
-        options.signal?.throwIfAborted();
-        const state = completed ?? this.#oldestUnreadMessage(live) ?? live.at(-1);
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
-        if (includeLatestMessage)
-            this.#observeLatestMessage(state);
-        return {
-            ...this.#snapshot(state, {
-                includeLatestMessage,
-                includeTerminalDetails
-            }),
-            ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
-        };
+        });
+    }
+    async outputAny(options = {}) {
+        return this.#using(undefined, async () => {
+            options.signal?.throwIfAborted();
+            if (options.untilSettled)
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'An unbounded wait requires an agent id.');
+            validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
+            const hasLive = [...this.#agents.values()].some((state) => !isTerminalState(state));
+            if (!hasLive) {
+                for (const id of [...this.#discovered.keys()].reverse()) {
+                    options.signal?.throwIfAborted();
+                    if (await this.#restoreDiscovered(id))
+                        break;
+                }
+            }
+            options.signal?.throwIfAborted();
+            const states = this.#orderedStates();
+            if (states.length === 0)
+                throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
+            const live = states.filter((state) => state.status === 'queued' || state.status === 'running');
+            if (options.waitMs === undefined || options.waitMs === 0)
+                return {
+                    ...this.#snapshot(live.at(-1) ?? states.at(-1), {
+                        includeLatestMessage: false,
+                        includeTerminalDetails: false
+                    }),
+                    waitOutcome: 'snapshot'
+                };
+            if (live.length === 0) {
+                const state = states.at(-1);
+                const includeLatestMessage = this.#hasUnreadMessage(state);
+                const includeTerminalDetails = this.#observeTerminal(state);
+                this.#observeLatestMessage(state);
+                return {
+                    ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
+                    waitOutcome: 'completion'
+                };
+            }
+            const waitFor = options.waitFor ?? 'completion';
+            if (waitFor === 'message') {
+                const pending = this.#oldestUnreadMessage(live);
+                if (pending) {
+                    this.#observeLatestMessage(pending);
+                    return { ...this.#snapshot(pending), waitOutcome: 'message' };
+                }
+            }
+            const waitMs = this.#retainedExecution.getStore()?.native
+                ? options.waitMs
+                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+            if (waitFor === 'message') {
+                const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal, options.waitInterrupt);
+                options.signal?.throwIfAborted();
+                const includeLatestMessage = activity?.kind === 'message' ||
+                    (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
+                const includeTerminalDetails = activity?.kind === 'completion' ? this.#observeTerminal(activity.state) : false;
+                if (activity)
+                    this.#observeLatestMessage(activity.state);
+                return {
+                    ...this.#snapshot(activity?.state ?? live.at(-1), {
+                        includeLatestMessage,
+                        includeTerminalDetails
+                    }),
+                    ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
+                };
+            }
+            const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal, options.waitInterrupt);
+            options.signal?.throwIfAborted();
+            const state = completed ?? this.#oldestUnreadMessage(live) ?? live.at(-1);
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
+            if (includeLatestMessage)
+                this.#observeLatestMessage(state);
+            return {
+                ...this.#snapshot(state, {
+                    includeLatestMessage,
+                    includeTerminalDetails
+                }),
+                ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
+            };
+        });
     }
     async outputMany(agentIds, options = {}) {
         options.signal?.throwIfAborted();
@@ -407,187 +494,198 @@ export class SubagentSessionController {
         validateOutputOptions(options, this.#retainedExecution.getStore()?.native === true);
         if (!ids || 'untilSettled' in options)
             throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Group waits require a bounded deadline.');
-        const states = await Promise.all(ids.map((id) => this.#find(id)));
-        options.signal?.throwIfAborted();
-        const waitFor = options.waitFor ?? 'completion';
-        const targets = states.map((state) => ({
-            state,
-            turn: state.turn,
-            view: copyWaitState(state),
-            observation: this.#nativeObservation(state)
-        }));
-        const refresh = () => {
-            for (const target of targets) {
-                if (!isTerminalState(target.view) &&
-                    (target.state.turn === target.turn ||
-                        (target.state.turn === undefined && isTerminalState(target.state))))
-                    target.view = copyWaitState(target.state);
+        return this.#using(ids, async () => {
+            const states = await Promise.all(ids.map((id) => this.#find(id)));
+            options.signal?.throwIfAborted();
+            const waitFor = options.waitFor ?? 'completion';
+            const targets = states.map((state) => ({
+                state,
+                turn: state.turn,
+                view: copyWaitState(state),
+                observation: this.#nativeObservation(state)
+            }));
+            const refresh = () => {
+                for (const target of targets) {
+                    if (!isTerminalState(target.view) &&
+                        (target.state.turn === target.turn ||
+                            (target.state.turn === undefined && isTerminalState(target.state))))
+                        target.view = copyWaitState(target.state);
+                }
+            };
+            const unread = (target) => target.view.messageRevision >
+                (target.observation?.messageRevision ?? target.state.observedMessageRevision);
+            const ready = (target) => isTerminalState(target.view) || (waitFor === 'message' && unread(target));
+            const snapshot = options.waitMs === undefined || options.waitMs === 0;
+            let satisfied = false;
+            if (!snapshot) {
+                const waitMs = this.#retainedExecution.getStore()?.native
+                    ? options.waitMs
+                    : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
+                satisfied = await waitForAgentCondition({
+                    waitMs,
+                    signal: options.signal,
+                    interrupt: options.waitInterrupt,
+                    ready: () => {
+                        refresh();
+                        return mode === 'all' ? targets.every(ready) : targets.some(ready);
+                    },
+                    subscribe: (notify) => {
+                        const listener = () => notify();
+                        this.#activityWaiters.add(listener);
+                        return () => this.#activityWaiters.delete(listener);
+                    }
+                });
+                options.signal?.throwIfAborted();
             }
-        };
-        const unread = (target) => target.view.messageRevision >
-            (target.observation?.messageRevision ?? target.state.observedMessageRevision);
-        const ready = (target) => isTerminalState(target.view) || (waitFor === 'message' && unread(target));
-        const snapshot = options.waitMs === undefined || options.waitMs === 0;
-        let satisfied = false;
-        if (!snapshot) {
-            const waitMs = this.#retainedExecution.getStore()?.native
-                ? options.waitMs
-                : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
-            satisfied = await waitForAgentCondition({
-                waitMs,
-                signal: options.signal,
-                interrupt: options.waitInterrupt,
-                ready: () => {
-                    refresh();
-                    return mode === 'all' ? targets.every(ready) : targets.some(ready);
-                },
-                subscribe: (notify) => {
-                    const listener = () => notify();
-                    this.#activityWaiters.add(listener);
-                    return () => this.#activityWaiters.delete(listener);
+            refresh();
+            if (!snapshot)
+                satisfied = mode === 'all' ? targets.every(ready) : targets.some(ready);
+            const pendingAgentIds = targets
+                .filter((target) => !ready(target))
+                .map((target) => target.state.agentId);
+            const agents = targets.map((target) => {
+                const { state, view, observation } = target;
+                const terminal = isTerminalState(view);
+                const outcome = snapshot
+                    ? 'snapshot'
+                    : terminal
+                        ? 'completion'
+                        : ready(target)
+                            ? 'message'
+                            : satisfied
+                                ? 'snapshot'
+                                : options.waitInterrupt?.pending()
+                                    ? 'interrupted'
+                                    : 'timeout';
+                const includeLatestMessage = outcome !== 'snapshot' && unread(target);
+                const includeTerminalDetails = outcome === 'completion' &&
+                    (observation
+                        ? observation.terminalRevision < view.resourceRevision
+                        : state.observedTerminalRevision < view.resourceRevision);
+                const result = {
+                    ...this.#snapshot(view, { includeLatestMessage, includeTerminalDetails }),
+                    ...(target.turn === undefined ? {} : { turnId: target.turn.turnId }),
+                    ...waitMetadata(outcome)
+                };
+                if (includeLatestMessage) {
+                    if (observation)
+                        observation.messageRevision = Math.max(observation.messageRevision, view.messageRevision);
+                    else
+                        state.observedMessageRevision = Math.max(state.observedMessageRevision, view.messageRevision);
+                }
+                if (includeTerminalDetails) {
+                    if (observation)
+                        observation.terminalRevision = Math.max(observation.terminalRevision, view.resourceRevision);
+                    else
+                        state.observedTerminalRevision = Math.max(state.observedTerminalRevision, view.resourceRevision);
                 }
+                return result;
             });
-            options.signal?.throwIfAborted();
-        }
-        refresh();
-        if (!snapshot)
-            satisfied = mode === 'all' ? targets.every(ready) : targets.some(ready);
-        const pendingAgentIds = targets
-            .filter((target) => !ready(target))
-            .map((target) => target.state.agentId);
-        const agents = targets.map((target) => {
-            const { state, view, observation } = target;
-            const terminal = isTerminalState(view);
-            const outcome = snapshot
-                ? 'snapshot'
-                : terminal
-                    ? 'completion'
-                    : ready(target)
-                        ? 'message'
-                        : satisfied
-                            ? 'snapshot'
-                            : options.waitInterrupt?.pending()
-                                ? 'interrupted'
-                                : 'timeout';
-            const includeLatestMessage = outcome !== 'snapshot' && unread(target);
-            const includeTerminalDetails = outcome === 'completion' &&
-                (observation
-                    ? observation.terminalRevision < view.resourceRevision
-                    : state.observedTerminalRevision < view.resourceRevision);
-            const result = {
-                ...this.#snapshot(view, { includeLatestMessage, includeTerminalDetails }),
-                ...(target.turn === undefined ? {} : { turnId: target.turn.turnId }),
-                ...waitMetadata(outcome)
+            return {
+                mode,
+                waitFor,
+                agents,
+                pendingAgentIds,
+                ...waitMetadata(snapshot
+                    ? 'snapshot'
+                    : !satisfied
+                        ? options.waitInterrupt?.pending()
+                            ? 'interrupted'
+                            : 'timeout'
+                        : agents.some((agent) => agent.waitOutcome === 'message')
+                            ? 'message'
+                            : 'completion')
             };
-            if (includeLatestMessage) {
-                if (observation)
-                    observation.messageRevision = Math.max(observation.messageRevision, view.messageRevision);
-                else
-                    state.observedMessageRevision = Math.max(state.observedMessageRevision, view.messageRevision);
-            }
-            if (includeTerminalDetails) {
-                if (observation)
-                    observation.terminalRevision = Math.max(observation.terminalRevision, view.resourceRevision);
-                else
-                    state.observedTerminalRevision = Math.max(state.observedTerminalRevision, view.resourceRevision);
-            }
-            return result;
         });
-        return {
-            mode,
-            waitFor,
-            agents,
-            pendingAgentIds,
-            ...waitMetadata(snapshot
-                ? 'snapshot'
-                : !satisfied
-                    ? options.waitInterrupt?.pending()
-                        ? 'interrupted'
-                        : 'timeout'
-                    : agents.some((agent) => agent.waitOutcome === 'message')
-                        ? 'message'
-                        : 'completion')
-        };
     }
     async message(agentId, message, options = {}) {
-        const execution = this.#requireExecution();
-        if (typeof message !== 'string' ||
-            message.trim().length === 0 ||
-            (this.#retainedExecution.getStore()?.native !== true &&
-                Buffer.byteLength(message) > TOOL_EXECUTION_LIMITS.subagentMessageMaxBytes) ||
-            (options.delivery !== undefined &&
-                options.delivery !== 'append' &&
-                options.delivery !== 'replace'))
-            throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent message input is invalid.');
-        const state = await this.#find(agentId);
-        return this.#control(state, async () => {
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-            // Resolve before cancelling so an unavailable model does not stop valid work.
-            const selected = resolveExistingModel(execution, state);
-            if (options.delivery === 'replace')
-                await this.#cancelState(state);
-            this.#requireExecution();
-            options.signal?.throwIfAborted();
-            const turnId = state.turn?.turnId ?? randomUUID();
-            const receipt = { messageId: randomUUID(), turnId, deliveryStatus: 'accepted' };
-            const mutableReceipt = receipt;
-            const delivery = this.#createDelivery(state, execution, mutableReceipt, options.signal);
-            try {
-                if (state.status === 'running' && state.turn) {
-                    const turn = state.turn;
-                    if (!turn.handle)
-                        await turn.handleReady;
-                    this.#requireExecution();
-                    options.signal?.throwIfAborted();
-                    delivery.signal?.throwIfAborted();
-                    if (state.status === 'running' &&
-                        state.turn === turn &&
-                        turn.handle?.enqueueMessage(message, delivery)) {
+        return this.#using([agentId], async () => {
+            const execution = this.#requireExecution();
+            if (typeof message !== 'string' ||
+                message.trim().length === 0 ||
+                (this.#retainedExecution.getStore()?.native !== true &&
+                    Buffer.byteLength(message) > TOOL_EXECUTION_LIMITS.subagentMessageMaxBytes) ||
+                (options.delivery !== undefined &&
+                    options.delivery !== 'append' &&
+                    options.delivery !== 'replace'))
+                throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent message input is invalid.');
+            const state = await this.#find(agentId);
+            return this.#control(state, async () => {
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+                // Resolve before cancelling so an unavailable model does not stop valid work.
+                const selected = resolveExistingModel(execution, state);
+                if (options.delivery === 'replace')
+                    await this.#cancelState(state);
+                this.#requireExecution();
+                options.signal?.throwIfAborted();
+                const turnId = state.turn?.turnId ?? randomUUID();
+                const receipt = { messageId: randomUUID(), turnId, deliveryStatus: 'accepted' };
+                const mutableReceipt = receipt;
+                const delivery = this.#createDelivery(state, execution, mutableReceipt, options.signal);
+                try {
+                    if (state.status === 'running' && state.turn) {
+                        const turn = state.turn;
+                        if (!turn.handle)
+                            await turn.handleReady;
+                        this.#requireExecution();
+                        options.signal?.throwIfAborted();
+                        delivery.signal?.throwIfAborted();
+                        if (state.status === 'running' &&
+                            state.turn === turn &&
+                            turn.handle?.enqueueMessage(message, delivery)) {
+                            delivery.accepted();
+                            state.receipt = mutableReceipt;
+                            return this.#messageReceiptSnapshot(state);
+                        }
+                        await turn.completion;
+                    }
+                    else if (state.status === 'queued' && state.turn) {
                         delivery.accepted();
+                        state.turn.pendingMessages.push({ text: message, delivery });
                         state.receipt = mutableReceipt;
                         return this.#messageReceiptSnapshot(state);
                     }
-                    await turn.completion;
-                }
-                else if (state.status === 'queued' && state.turn) {
+                    this.#requireExecution();
+                    options.signal?.throwIfAborted();
+                    delivery.signal?.throwIfAborted();
+                    state.modelId = selected.id;
+                    state.modelName = selected.name;
+                    state.reasoningEffort = selected.reasoningEffort;
+                    // A closing turn may have rejected append; reserve a fresh identity for its successor.
+                    mutableReceipt.turnId = randomUUID();
                     delivery.accepted();
-                    state.turn.pendingMessages.push({ text: message, delivery });
                     state.receipt = mutableReceipt;
+                    this.#queueTurn(state, message, execution, [], mutableReceipt.turnId, delivery, options.signal);
                     return this.#messageReceiptSnapshot(state);
                 }
-                this.#requireExecution();
-                options.signal?.throwIfAborted();
-                delivery.signal?.throwIfAborted();
-                state.modelId = selected.id;
-                state.modelName = selected.name;
-                state.reasoningEffort = selected.reasoningEffort;
-                // A closing turn may have rejected append; reserve a fresh identity for its successor.
-                mutableReceipt.turnId = randomUUID();
-                delivery.accepted();
-                state.receipt = mutableReceipt;
-                this.#queueTurn(state, message, execution, [], mutableReceipt.turnId, delivery, options.signal);
-                return this.#messageReceiptSnapshot(state);
-            }
-            catch (error) {
-                delivery.settled?.(options.signal?.aborted || ('signal' in execution && execution.signal.aborted)
-                    ? 'cancelled'
-                    : 'failed');
-                throw error;
-            }
+                catch (error) {
+                    delivery.settled?.(options.signal?.aborted || ('signal' in execution && execution.signal.aborted)
+                        ? 'cancelled'
+                        : 'failed');
+                    throw error;
+                }
+            });
         });
     }
     async cancel(agentId) {
-        const state = await this.#find(agentId);
-        await this.#control(state, () => this.#cancelState(state));
-        const includeLatestMessage = this.#hasUnreadMessage(state);
-        const includeTerminalDetails = this.#observeTerminal(state);
-        this.#observeLatestMessage(state);
-        return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        return this.#using([agentId], async () => {
+            const state = await this.#find(agentId);
+            await this.#control(state, () => this.#cancelState(state));
+            const includeLatestMessage = this.#hasUnreadMessage(state);
+            const includeTerminalDetails = this.#observeTerminal(state);
+            this.#observeLatestMessage(state);
+            return this.#snapshot(state, { includeLatestMessage, includeTerminalDetails });
+        });
     }
     #control(state, operation) {
         const result = (state.controlTail ?? Promise.resolve()).then(operation);
-        state.controlTail = result.catch(() => undefined);
+        const tail = result.then(() => undefined, () => undefined);
+        state.controlTail = tail;
+        void tail.then(() => {
+            if (state.controlTail === tail)
+                delete state.controlTail;
+        });
         return result;
     }
     async #cancelState(state) {
@@ -625,7 +723,7 @@ export class SubagentSessionController {
         const terminal = states
             .filter((state) => state.status !== 'queued' && state.status !== 'running')
             .sort((left, right) => right.resourceRevision - left.resourceRevision)
-            .slice(0, 8);
+            .slice(0, RECENT_TERMINAL_RESOURCE_LIMIT);
         return [...active, ...terminal].map((state) => ({
             agentId: state.agentId,
             status: state.status,
@@ -673,6 +771,7 @@ export class SubagentSessionController {
                     ? native.signal
                     : AbortSignal.any([native.signal, signal]));
         state.status = 'queued';
+        state.restorable = false;
         this.#touchResource(state);
         delete state.summary;
         delete state.permissionStop;
@@ -750,9 +849,18 @@ export class SubagentSessionController {
         await this.#consumeTurn(state, turn);
     }
     async #consumeTurn(state, turn) {
+        const previousActivity = state.latestActivity;
+        const previousMessageRevision = state.messageRevision;
+        let terminal;
         try {
             const consume = (async () => {
                 for await (const event of turn.handle) {
+                    if (event.type === 'execution.completed')
+                        terminal = 'completed';
+                    else if (event.type === 'execution.failed')
+                        terminal = 'failed';
+                    else if (event.type === 'execution.cancelled')
+                        terminal = 'cancelled';
                     if (!observeAgentEvent(state, event))
                         continue;
                     state.messageRevision++;
@@ -778,6 +886,14 @@ export class SubagentSessionController {
                 state.errorCode = result.errorCode ?? 'MAR_AGENT_SUBAGENT_FAILED';
                 state.errorMessage = result.errorMessage ?? 'Subagent execution failed.';
             }
+            state.restorable =
+                turn.handle.persistedEvents === true &&
+                    terminal === state.status &&
+                    (previousActivity === undefined || state.latestActivity !== previousActivity) &&
+                    (state.latestMessage === undefined || state.messageRevision > previousMessageRevision) &&
+                    (state.status !== 'completed' ||
+                        (state.latestMessage?.phase === 'final_answer' &&
+                            state.summary === state.latestMessage.text));
             state.terminalPending = true;
             this.#touchResource(state, true);
             this.#closeReceipt(state);
@@ -812,6 +928,7 @@ export class SubagentSessionController {
     #setFailure(state, error) {
         const diagnostic = describeMarAgentError(error, 'MAR_AGENT_SUBAGENT_FAILED');
         state.status = 'failed';
+        state.restorable = false;
         state.errorCode = diagnostic.code;
         state.errorMessage = diagnostic.message;
         state.terminalPending = true;
@@ -946,6 +1063,7 @@ export class SubagentSessionController {
     }
     async #deleteUnstartedSession(agentId, error) {
         this.#agents.delete(agentId);
+        this.#discovered.delete(agentId);
         try {
             await this.backend.deleteSession(agentId);
         }
@@ -956,16 +1074,105 @@ export class SubagentSessionController {
         }
         throw error;
     }
+    async #using(ids, operation) {
+        if (ids === undefined)
+            this.#allReaders++;
+        else
+            for (const id of ids)
+                this.#readers.set(id, (this.#readers.get(id) ?? 0) + 1);
+        try {
+            return await operation();
+        }
+        finally {
+            if (ids === undefined)
+                this.#allReaders--;
+            else
+                for (const id of ids) {
+                    const count = this.#readers.get(id) - 1;
+                    if (count)
+                        this.#readers.set(id, count);
+                    else
+                        this.#readers.delete(id);
+                }
+        }
+    }
+    #releaseOldDetails() {
+        if (this.#allReaders)
+            return;
+        const terminal = [...this.#agents.values()]
+            .filter(isTerminalState)
+            .sort((a, b) => b.resourceRevision - a.resourceRevision);
+        for (const state of terminal.slice(RECENT_TERMINAL_RESOURCE_LIMIT)) {
+            if (state.detailsEvicted ||
+                !state.restorable ||
+                state.turn ||
+                state.controlTail ||
+                this.#readers.has(state.agentId) ||
+                this.#loading.has(state.agentId) ||
+                state.terminalPending ||
+                state.messageRevision > state.observedMessageRevision ||
+                (state.terminalRevision !== undefined &&
+                    state.terminalRevision > state.observedTerminalRevision) ||
+                [...this.#pendingDeliveries].some((pending) => pending.state === state))
+                continue;
+            // Keep identity and cursors for old acknowledgements; only the disk-backed body unloads.
+            for (const key of DETAIL_FIELDS)
+                delete state[key];
+            state.changedFiles = [];
+            state.verification = [];
+            state.evidence = [];
+            state.detailsEvicted = true;
+        }
+    }
     async #find(agentId) {
+        if (this.#disposed)
+            throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
         const known = this.#agents.get(agentId);
-        if (known)
+        if (known && !known.detailsEvicted)
             return known;
-        const persisted = await this.backend.loadChild(this.parentSessionId, agentId);
-        if (!persisted)
-            throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
-        const restored = restoreAgentState(persisted);
-        this.#agents.set(agentId, restored);
-        return restored;
+        const pending = this.#loading.get(agentId);
+        if (pending)
+            return pending;
+        const load = (async () => {
+            const persisted = await this.backend.loadChild(this.parentSessionId, agentId);
+            if (this.#disposed)
+                throw new MarAgentError('MAR_AGENT_DISPOSED', 'Subagent controller is disposed.');
+            if (!persisted) {
+                this.#agents.delete(agentId);
+                this.#discovered.delete(agentId);
+                throw new MarAgentError('MAR_AGENT_SUBAGENT_NOT_FOUND', 'Subagent was not found.');
+            }
+            const existing = this.#agents.get(agentId);
+            if (existing && !existing.detailsEvicted)
+                return existing;
+            const restored = restoreAgentState(persisted);
+            if (existing) {
+                for (const key of DETAIL_FIELDS) {
+                    if (key in restored)
+                        Object.assign(existing, { [key]: restored[key] });
+                    else
+                        delete existing[key];
+                }
+                delete existing.detailsEvicted;
+                return existing;
+            }
+            let revision = this.#discovered.get(agentId);
+            if (revision === undefined) {
+                revision = ++this.#resourceRevision;
+                this.#discovered.set(agentId, revision);
+            }
+            restored.resourceRevision = revision;
+            this.#agents.set(agentId, restored);
+            return restored;
+        })();
+        this.#loading.set(agentId, load);
+        try {
+            return await load;
+        }
+        finally {
+            if (this.#loading.get(agentId) === load)
+                this.#loading.delete(agentId);
+        }
     }
     #requireExecution() {
         if (this.#disposed)
@@ -1139,6 +1346,7 @@ function restoreAgentState(session) {
     const terminal = currentRecords.findLast((record) => ['execution.completed', 'execution.failed', 'execution.cancelled'].includes(eventType(record) ?? ''));
     const terminalType = eventType(terminal);
     const state = {
+        restorable: true,
         agentId: session.id,
         description: session.source.description,
         role: session.source.role,