@junctionpanel/server 0.1.61 → 0.1.63

package/dist/server/server/session.js

@@ -29,7 +29,7 @@ import { expandTilde } from '../utils/path.js';
 import { searchHomeDirectories, searchWorkspaceEntries, searchWorkspaceEntriesAtGitRef, searchGitRepositories, checkIsGitRepo, } from '../utils/directory-suggestions.js';
 import { cloneRepository } from '../utils/git-clone.js';
 import { initRepository } from '../utils/git-init.js';
-import { resolveClientMessageId } from './client-message-id.js';
+import { normalizeClientMessageId, resolveClientMessageId } from './client-message-id.js';
 import { deriveProjectGroupingKey, deriveProjectGroupingName } from '../shared/project-grouping.js';
 import { DEFAULT_DAEMON_PACKAGE_NAME, resolveDaemonPackageVersion, } from './daemon-package-context.js';
 import { runDaemonDoctor } from './daemon-doctor.js';
@@ -48,6 +48,8 @@ const READ_ONLY_GIT_ENV = {
 const DEFAULT_STORED_TIMELINE_FETCH_LIMIT = 200;
 const pendingAgentInitializations = new Map();
 const pendingAgentMessageExecutions = new Map();
+const CREATE_AGENT_REPLAY_WINDOW_MS = 30000;
+const pendingCreateAgentRequests = new Map();
 const sharedWorkspaceGitOperationStates = new Map();
 const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_IDS[0];
 const CHECKOUT_DIFF_WATCH_DEBOUNCE_MS = 150;
@@ -56,9 +58,36 @@ const WORKSPACE_STATUS_WATCH_DEBOUNCE_MS = 250;
 const WORKSPACE_STATUS_GIT_REFRESH_MS = 3000;
 const WORKSPACE_STATUS_PR_ACTIVE_REFRESH_MS = 15000;
 const WORKSPACE_STATUS_PR_PASSIVE_REFRESH_MS = 60000;
+const PROVIDER_CHILD_THREADS_REFRESH_DEBOUNCE_MS = 250;
+const PROVIDER_CHILD_THREADS_PERSISTED_LIST_INITIAL_LIMIT = 500;
+const PROVIDER_CHILD_THREADS_PERSISTED_LIST_MAX_LIMIT = 50000;
 const TERMINAL_STREAM_WINDOW_BYTES = 256 * 1024;
 const TERMINAL_STREAM_MAX_PENDING_BYTES = 2 * 1024 * 1024;
 const TERMINAL_STREAM_MAX_PENDING_CHUNKS = 2048;
+function buildCreateAgentReplayKey(clientId, clientMessageId) {
+    return JSON.stringify([clientId, clientMessageId]);
+}
+function deletePendingCreateAgentRequest(replayKey, expectedEntry) {
+    const existingEntry = pendingCreateAgentRequests.get(replayKey);
+    if (!existingEntry || (expectedEntry && existingEntry !== expectedEntry)) {
+        return;
+    }
+    clearTimeout(existingEntry.evictionTimer);
+    pendingCreateAgentRequests.delete(replayKey);
+}
+function storePendingCreateAgentRequest(replayKey, promise) {
+    const entry = {
+        promise,
+        evictionTimer: setTimeout(() => {
+            deletePendingCreateAgentRequest(replayKey, entry);
+        }, CREATE_AGENT_REPLAY_WINDOW_MS),
+    };
+    pendingCreateAgentRequests.set(replayKey, entry);
+    void promise.catch(() => {
+        deletePendingCreateAgentRequest(replayKey, entry);
+    });
+    return entry;
+}
 const DIRTY_WORKTREE_CONFIRMATION_REQUIRED = 'dirty_worktree_confirmation_required';
 class SessionRequestError extends Error {
     constructor(code, message) {
@@ -142,6 +171,12 @@ export class Session {
         this.checkoutDiffSubscriptions = new Map();
         this.checkoutDiffTargets = new Map();
         this.workspaceGitOperationStates = sharedWorkspaceGitOperationStates;
+        this.providerChildThreadEntries = [];
+        this.providerChildThreadEntriesFingerprint = null;
+        this.providerChildThreadEntriesHydrated = false;
+        this.providerChildThreadRefreshTimer = null;
+        this.providerChildThreadRefreshPromise = null;
+        this.providerChildThreadRefreshQueued = false;
         const { clientId, userId, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, junctionHome, agentManager, agentStorage, createAgentMcpTransport, terminalManager, agentProviderRuntimeSettings, connectionContext, } = options;
         this.clientId = clientId;
         this.userId = userId;
@@ -367,8 +402,14 @@ export class Session {
         this.unsubscribeAgentEvents = this.agentManager.subscribe((event) => {
             if (event.type === 'agent_state') {
                 void this.forwardAgentUpdate(event.agent);
+                if (event.agent.provider === 'codex') {
+                    this.scheduleProviderChildThreadRefresh();
+                }
                 return;
             }
+            if (this.shouldRefreshProviderChildThreadsForStreamEvent(event.event)) {
+                this.scheduleProviderChildThreadRefresh();
+            }
             // Reduce bandwidth/CPU on mobile: only forward high-frequency agent stream events
             // for the focused agent, with a short grace window while backgrounded.
             // History catch-up is handled via pull-based `fetch_agent_timeline_request`.
@@ -571,12 +612,16 @@ export class Session {
                 snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, {
                     ...extractTimestamps(record),
                     ...extractTimelineSnapshot(record),
+                    parentAgentId: record.parentAgentId ?? null,
                 });
                 this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent resumed from persistence');
             }
             else {
                 const config = buildSessionConfig(record);
-                snapshot = await this.agentManager.createAgent(config, agentId, { labels: record.labels });
+                snapshot = await this.agentManager.createAgent(config, agentId, {
+                    labels: record.labels,
+                    parentAgentId: record.parentAgentId ?? null,
+                });
                 this.sessionLogger.info({ agentId, provider: record.provider }, 'Agent created from stored config');
             }
             await this.agentManager.hydrateTimelineFromProvider(agentId);
@@ -762,6 +807,112 @@ export class Session {
             checkout,
         };
     }
+    shouldRefreshProviderChildThreadsForStreamEvent(event) {
+        if (event.provider !== 'codex') {
+            return false;
+        }
+        if (event.type === 'turn_completed') {
+            return true;
+        }
+        return (event.type === 'timeline' &&
+            event.item.type === 'tool_call' &&
+            event.item.name === 'spawn_agent' &&
+            event.item.detail.type === 'sub_agent');
+    }
+    serializeProviderChildThreadEntries(entries) {
+        return JSON.stringify(entries.map(({ thread, project }) => ({
+            id: thread.id,
+            threadId: thread.threadId,
+            parentThreadId: thread.parentThreadId ?? null,
+            rootThreadId: thread.rootThreadId ?? null,
+            parentAgentId: thread.parentAgentId,
+            cwd: thread.cwd,
+            title: thread.title,
+            status: thread.status,
+            model: thread.model ?? null,
+            createdAt: thread.createdAt,
+            updatedAt: thread.updatedAt,
+            persistence: {
+                provider: thread.persistence?.provider ?? null,
+                sessionId: thread.persistence?.sessionId ?? null,
+                nativeHandle: thread.persistence?.nativeHandle ?? null,
+            },
+            agentId: thread.agentId ?? null,
+            agentNickname: thread.agentNickname ?? null,
+            agentRole: thread.agentRole ?? null,
+            projectKey: project.projectKey,
+            projectName: project.projectName,
+            checkout: {
+                cwd: project.checkout.cwd,
+                isGit: project.checkout.isGit,
+                currentBranch: project.checkout.currentBranch,
+                remoteUrl: project.checkout.remoteUrl,
+                isJunctionOwnedWorktree: project.checkout.isJunctionOwnedWorktree,
+                mainRepoRoot: project.checkout.mainRepoRoot,
+            },
+        })));
+    }
+    emitProviderChildThreadsChanged(payload) {
+        this.emit({
+            type: 'provider_child_threads_changed',
+            payload,
+        });
+    }
+    setProviderChildThreadEntries(entries, options) {
+        const fingerprint = this.serializeProviderChildThreadEntries(entries);
+        this.providerChildThreadEntriesHydrated = true;
+        if (this.providerChildThreadEntriesFingerprint === fingerprint) {
+            return;
+        }
+        this.providerChildThreadEntries = entries;
+        this.providerChildThreadEntriesFingerprint = fingerprint;
+        if (options?.emit) {
+            this.emitProviderChildThreadsChanged({ entries });
+        }
+    }
+    async refreshProviderChildThreadEntries(options) {
+        if (this.providerChildThreadRefreshPromise) {
+            if (options?.emit) {
+                this.providerChildThreadRefreshQueued = true;
+            }
+            await this.providerChildThreadRefreshPromise;
+            return;
+        }
+        const refreshPromise = (async () => {
+            const entries = await this.listProviderChildThreadEntries();
+            this.setProviderChildThreadEntries(entries, { emit: options?.emit });
+        })();
+        this.providerChildThreadRefreshPromise = refreshPromise;
+        try {
+            await refreshPromise;
+        }
+        finally {
+            if (this.providerChildThreadRefreshPromise === refreshPromise) {
+                this.providerChildThreadRefreshPromise = null;
+            }
+            if (this.providerChildThreadRefreshQueued) {
+                this.providerChildThreadRefreshQueued = false;
+                await this.refreshProviderChildThreadEntries({ emit: true });
+            }
+        }
+    }
+    scheduleProviderChildThreadRefresh() {
+        if (this.providerChildThreadRefreshTimer) {
+            return;
+        }
+        this.providerChildThreadRefreshTimer = setTimeout(() => {
+            this.providerChildThreadRefreshTimer = null;
+            void this.refreshProviderChildThreadEntries({ emit: true }).catch((error) => {
+                this.sessionLogger.debug({ err: error }, 'Failed to refresh provider child thread cache');
+            });
+        }, PROVIDER_CHILD_THREADS_REFRESH_DEBOUNCE_MS);
+    }
+    async ensureProviderChildThreadEntriesHydrated() {
+        if (this.providerChildThreadEntriesHydrated) {
+            return;
+        }
+        await this.refreshProviderChildThreadEntries({ emit: false });
+    }
     async forwardAgentUpdate(agent) {
         try {
             const subscription = this.agentUpdatesSubscription;
@@ -794,6 +945,9 @@ export class Session {
     }
     async forwardStoredAgentRecordUpdate(record) {
         try {
+            if (record.provider === 'codex') {
+                this.scheduleProviderChildThreadRefresh();
+            }
             const subscription = this.agentUpdatesSubscription;
             if (!subscription || record.internal) {
                 return;
@@ -837,6 +991,12 @@ export class Session {
                 case 'fetch_agent_request':
                     await this.handleFetchAgent(msg.agentId, msg.requestId);
                     break;
+                case 'fetch_provider_child_threads_request':
+                    await this.handleFetchProviderChildThreads(msg);
+                    break;
+                case 'fetch_provider_thread_timeline_request':
+                    await this.handleFetchProviderThreadTimeline(msg);
+                    break;
                 case 'delete_agent_request':
                     await this.handleDeleteAgentRequest(msg.agentId, msg.requestId);
                     break;
@@ -1225,6 +1385,9 @@ export class Session {
     }
     async handleDeleteAgentRequest(agentId, requestId) {
         this.sessionLogger.info({ agentId }, `Deleting agent ${agentId} from registry`);
+        const storedRecord = await this.agentStorage.get(agentId);
+        const liveAgent = this.agentManager.getAgent(agentId);
+        const shouldRefreshProviderChildThreads = storedRecord?.provider === 'codex' || liveAgent?.provider === 'codex';
         // Prevent the persistence hook from re-creating the record while we close/delete.
         this.agentStorage.beginDelete(agentId);
         try {
@@ -1252,6 +1415,9 @@ export class Session {
                 agentId,
             });
         }
+        if (shouldRefreshProviderChildThreads) {
+            this.scheduleProviderChildThreadRefresh();
+        }
     }
     async handleArchiveAgentRequest(agentId, requestId, dirtyWorktreeBehavior) {
         this.sessionLogger.info({ agentId }, `Archiving agent ${agentId}`);
@@ -1290,6 +1456,9 @@ export class Session {
             archivedWorktree: await this.buildArchivedWorktreeState(archivedRecord.cwd, archivedAt),
         };
         await this.agentStorage.upsert(archivedRecord);
+        if (archivedRecord.provider === 'codex') {
+            this.scheduleProviderChildThreadRefresh();
+        }
         if (liveAgent) {
             this.agentManager.notifyAgentState(agentId);
         }
@@ -1557,7 +1726,7 @@ export class Session {
         const archivedAt = await this.getArchivedAt(agentId);
         if (archivedAt) {
             this.handleAgentRunError(agentId, new Error(`Agent ${agentId} is archived`), 'Refusing to send prompt to archived agent');
-            return;
+            return false;
         }
         try {
             await this.performAgentMessageSend({
@@ -1567,107 +1736,186 @@ export class Session {
                 images,
                 runOptions,
             });
+            return true;
         }
         catch (error) {
             this.handleAgentRunError(agentId, error, 'Failed to send prompt to agent');
+            return false;
         }
     }
     /**
      * Handle create agent request
      */
     async handleCreateAgentRequest(msg) {
-        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, initialRunOptions, git, bootstrapSetupOverride, generalPreferencesApplied, images, labels, } = msg;
+        const { config, worktreeName, requestId, initialPrompt, clientMessageId, outputSchema, initialRunOptions, git, bootstrapSetupOverride, generalPreferencesApplied, images, labels, parentAgentId, } = msg;
         this.sessionLogger.info({ cwd: config.cwd, provider: config.provider, worktreeName }, `Creating agent in ${config.cwd} (${config.provider})${worktreeName ? ` with worktree ${worktreeName}` : ''}`);
+        const trimmedPrompt = initialPrompt?.trim() ?? '';
+        const hasInitialMessage = trimmedPrompt.length > 0 || Boolean(images?.length);
+        const normalizedClientMessageId = hasInitialMessage ? normalizeClientMessageId(clientMessageId) : undefined;
+        const createReplayKey = normalizedClientMessageId
+            ? buildCreateAgentReplayKey(this.clientId, normalizedClientMessageId)
+            : null;
         try {
-            const { sessionConfig, worktreeConfig, autoWorkspaceName } = await this.buildAgentSessionConfig(config, git, worktreeName, labels);
-            const mergedLabels = autoWorkspaceName
-                ? { ...labels, 'junction:workspace': autoWorkspaceName }
-                : labels;
-            const snapshot = await this.agentManager.createAgent(sessionConfig, undefined, {
-                labels: applyNotificationRelayOwnerLabel(mergedLabels, this.userId),
-            });
-            await this.forwardAgentUpdate(snapshot);
-            if (requestId) {
-                const agentPayload = await this.getAgentPayloadById(snapshot.id);
-                if (!agentPayload) {
-                    throw new Error(`Agent ${snapshot.id} not found after creation`);
+            const createAgentLaunch = async (clearReplayEntryOnDeferredFailure) => {
+                const { sessionConfig, worktreeConfig, autoWorkspaceName } = await this.buildAgentSessionConfig(config, git, worktreeName, labels);
+                const mergedLabels = autoWorkspaceName
+                    ? { ...labels, 'junction:workspace': autoWorkspaceName }
+                    : labels;
+                const resumeHandle = toAgentPersistenceHandle(this.sessionLogger, initialRunOptions?.resumeFrom ?? null);
+                const agentLabels = applyNotificationRelayOwnerLabel(mergedLabels, this.userId);
+                const existingLiveAgent = resumeHandle
+                    ? this.findLiveAgentByPersistenceHandle({
+                        handle: resumeHandle,
+                        parentAgentId: parentAgentId ?? null,
+                    })
+                    : null;
+                let snapshot = existingLiveAgent
+                    ? existingLiveAgent
+                    : resumeHandle
+                        ? await this.agentManager.resumeAgentFromPersistence(resumeHandle, sessionConfig, undefined, {
+                            labels: agentLabels,
+                            parentAgentId: parentAgentId ?? null,
+                        })
+                        : await this.agentManager.createAgent(sessionConfig, undefined, {
+                            labels: agentLabels,
+                            parentAgentId: parentAgentId ?? null,
+                        });
+                if (resumeHandle) {
+                    if (existingLiveAgent && sessionConfig.title?.trim()) {
+                        await this.agentManager.setTitle(existingLiveAgent.id, sessionConfig.title.trim());
+                    }
+                    await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
+                    snapshot = this.agentManager.getAgent(snapshot.id) ?? snapshot;
                 }
-                this.emit({
-                    type: 'status',
-                    payload: {
-                        status: 'agent_created',
-                        agentId: snapshot.id,
-                        requestId,
-                        agent: agentPayload,
-                    },
-                });
-            }
-            const trimmedPrompt = initialPrompt?.trim() ?? '';
-            const hasInitialMessage = trimmedPrompt.length > 0 || Boolean(images?.length);
-            const runInitialPrompt = async () => {
-                if (!hasInitialMessage) {
-                    return;
+                await this.forwardAgentUpdate(snapshot);
+                if (snapshot.provider === 'codex') {
+                    this.scheduleProviderChildThreadRefresh();
+                }
+                const runInitialPrompt = async () => {
+                    if (!hasInitialMessage) {
+                        return;
+                    }
+                    if (trimmedPrompt.length > 0) {
+                        scheduleAgentMetadataGeneration({
+                            agentManager: this.agentManager,
+                            agentId: snapshot.id,
+                            cwd: snapshot.cwd,
+                            initialPrompt: trimmedPrompt,
+                            explicitTitle: snapshot.config.title,
+                            junctionHome: this.junctionHome,
+                            logger: this.sessionLogger,
+                        });
+                    }
+                    const sendSucceeded = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt, normalizedClientMessageId ?? resolveClientMessageId(clientMessageId), images, normalizeAgentRunOptions({
+                        ...(outputSchema ? { outputSchema } : {}),
+                        ...(initialRunOptions ?? {}),
+                    }));
+                    if (!sendSucceeded) {
+                        clearReplayEntryOnDeferredFailure?.();
+                    }
+                };
+                const handleInitialPromptError = (promptError) => {
+                    clearReplayEntryOnDeferredFailure?.();
+                    this.sessionLogger.error({ err: promptError, agentId: snapshot.id }, `Failed to run initial prompt for agent ${snapshot.id}`);
+                    this.emit({
+                        type: 'activity_log',
+                        payload: {
+                            id: uuidv4(),
+                            timestamp: new Date(),
+                            type: 'error',
+                            content: `Initial prompt failed: ${promptError?.message ?? promptError}`,
+                        },
+                    });
+                };
+                if (hasInitialMessage && !worktreeConfig) {
+                    void runInitialPrompt().catch(handleInitialPromptError);
                 }
-                if (trimmedPrompt.length > 0) {
-                    scheduleAgentMetadataGeneration({
-                        agentManager: this.agentManager,
+                if (worktreeConfig) {
+                    void runAsyncWorktreeBootstrap({
                         agentId: snapshot.id,
-                        cwd: snapshot.cwd,
-                        initialPrompt: trimmedPrompt,
-                        explicitTitle: snapshot.config.title,
-                        junctionHome: this.junctionHome,
+                        worktree: worktreeConfig,
+                        setupOverride: bootstrapSetupOverride,
+                        generalPreferencesApplied,
+                        terminalManager: this.terminalManager,
+                        appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
+                            agentManager: this.agentManager,
+                            agentId: snapshot.id,
+                            item,
+                        }),
+                        emitLiveTimelineItem: (item) => emitLiveTimelineItemIfAgentKnown({
+                            agentManager: this.agentManager,
+                            agentId: snapshot.id,
+                            item,
+                        }),
+                        onSetupSettled: async (result) => {
+                            if (!hasInitialMessage || result.setupStatus === 'failed') {
+                                if (hasInitialMessage && result.setupStatus === 'failed') {
+                                    clearReplayEntryOnDeferredFailure?.();
+                                }
+                                return;
+                            }
+                            await runInitialPrompt().catch(handleInitialPromptError);
+                        },
                         logger: this.sessionLogger,
+                    }).catch((bootstrapError) => {
+                        clearReplayEntryOnDeferredFailure?.();
+                        this.sessionLogger.error({ err: bootstrapError, agentId: snapshot.id }, `Failed to bootstrap worktree for agent ${snapshot.id}`);
                     });
                 }
-                await this.handleSendAgentMessage(snapshot.id, trimmedPrompt, resolveClientMessageId(clientMessageId), images, normalizeAgentRunOptions({
-                    ...(outputSchema ? { outputSchema } : {}),
-                    ...(initialRunOptions ?? {}),
-                }));
+                this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
+                return snapshot;
             };
-            const handleInitialPromptError = (promptError) => {
-                this.sessionLogger.error({ err: promptError, agentId: snapshot.id }, `Failed to run initial prompt for agent ${snapshot.id}`);
+            let reusedExisting = false;
+            let snapshot;
+            let agentPayload;
+            if (createReplayKey) {
+                const existingEntry = pendingCreateAgentRequests.get(createReplayKey);
+                if (existingEntry) {
+                    reusedExisting = true;
+                    snapshot = await existingEntry.promise;
+                }
+                else {
+                    reusedExisting = false;
+                    let clearReplayEntryOnDeferredFailure = () => { };
+                    const nextPromise = createAgentLaunch(() => {
+                        clearReplayEntryOnDeferredFailure();
+                    });
+                    const nextEntry = storePendingCreateAgentRequest(createReplayKey, nextPromise);
+                    clearReplayEntryOnDeferredFailure = () => {
+                        deletePendingCreateAgentRequest(createReplayKey, nextEntry);
+                    };
+                    try {
+                        snapshot = await nextPromise;
+                    }
+                    catch (error) {
+                        deletePendingCreateAgentRequest(createReplayKey, nextEntry);
+                        throw error;
+                    }
+                }
+                agentPayload = await this.getAgentPayloadById(snapshot.id);
+                if (!agentPayload) {
+                    agentPayload = await this.buildAgentPayload(snapshot);
+                }
+            }
+            else {
+                snapshot = await createAgentLaunch();
+                agentPayload = await this.getAgentPayloadById(snapshot.id);
+                if (!agentPayload) {
+                    throw new Error(`Agent ${snapshot.id} not found after creation`);
+                }
+            }
+            if (requestId) {
                 this.emit({
-                    type: 'activity_log',
+                    type: 'status',
                     payload: {
-                        id: uuidv4(),
-                        timestamp: new Date(),
-                        type: 'error',
-                        content: `Initial prompt failed: ${promptError?.message ?? promptError}`,
-                    },
-                });
-            };
-            if (hasInitialMessage && !worktreeConfig) {
-                void runInitialPrompt().catch(handleInitialPromptError);
-            }
-            if (worktreeConfig) {
-                void runAsyncWorktreeBootstrap({
-                    agentId: snapshot.id,
-                    worktree: worktreeConfig,
-                    setupOverride: bootstrapSetupOverride,
-                    generalPreferencesApplied,
-                    terminalManager: this.terminalManager,
-                    appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
-                        agentManager: this.agentManager,
-                        agentId: snapshot.id,
-                        item,
-                    }),
-                    emitLiveTimelineItem: (item) => emitLiveTimelineItemIfAgentKnown({
-                        agentManager: this.agentManager,
+                        status: 'agent_created',
+                        reusedExisting,
                         agentId: snapshot.id,
-                        item,
-                    }),
-                    onSetupSettled: async (result) => {
-                        if (!hasInitialMessage || result.setupStatus === 'failed') {
-                            return;
-                        }
-                        await runInitialPrompt().catch(handleInitialPromptError);
+                        requestId,
+                        agent: agentPayload,
                     },
-                    logger: this.sessionLogger,
-                }).catch((bootstrapError) => {
-                    this.sessionLogger.error({ err: bootstrapError, agentId: snapshot.id }, `Failed to bootstrap worktree for agent ${snapshot.id}`);
                 });
             }
-            this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
         catch (error) {
             this.sessionLogger.error({ err: error }, 'Failed to create agent');
@@ -1712,6 +1960,9 @@ export class Session {
             const snapshot = await this.agentManager.resumeAgentFromPersistence(handle, overrides);
             await this.agentManager.hydrateTimelineFromProvider(snapshot.id);
             await this.forwardAgentUpdate(snapshot);
+            if (snapshot.provider === 'codex') {
+                this.scheduleProviderChildThreadRefresh();
+            }
             const timelineSize = this.agentManager.getTimeline(snapshot.id).length;
             if (requestId) {
                 const agentPayload = await this.getAgentPayloadById(snapshot.id);
@@ -1770,10 +2021,14 @@ export class Session {
                 snapshot = await this.agentManager.resumeAgentFromPersistence(handle, buildConfigOverrides(record), agentId, {
                     ...extractTimestamps(record),
                     ...extractTimelineSnapshot(record),
+                    parentAgentId: record.parentAgentId ?? null,
                 });
             }
             await this.agentManager.hydrateTimelineFromProvider(agentId);
             await this.forwardAgentUpdate(snapshot);
+            if (snapshot.provider === 'codex') {
+                this.scheduleProviderChildThreadRefresh();
+            }
             const timelineSize = this.agentManager.getTimeline(agentId).length;
             if (requestId) {
                 this.emit({
@@ -5350,6 +5605,260 @@ export class Session {
             });
         }
     }
+    resolveAgentSessionId(agent) {
+        return agent.runtimeInfo?.sessionId ?? agent.persistence?.sessionId ?? null;
+    }
+    findLiveAgentByPersistenceHandle(input) {
+        const targetSessionId = input.handle.sessionId.trim();
+        if (!targetSessionId) {
+            return null;
+        }
+        for (const agent of this.agentManager.listAgents()) {
+            if (agent.provider !== input.handle.provider) {
+                continue;
+            }
+            if (input.parentAgentId !== undefined
+                && (agent.parentAgentId ?? null) !== (input.parentAgentId ?? null)) {
+                continue;
+            }
+            const agentSessionId = agent.persistence?.sessionId ?? agent.runtimeInfo?.sessionId ?? null;
+            if (agentSessionId === targetSessionId) {
+                return agent;
+            }
+        }
+        return null;
+    }
+    buildProviderChildThreadId(input) {
+        return `${input.provider}:thread:${input.threadId}`;
+    }
+    resolveProviderChildThreadStatus(input) {
+        return input.parentAgent.status === 'running' ? 'running' : 'idle';
+    }
+    buildProviderThreadTimelineEpoch(threadId) {
+        return `provider-thread:${threadId}`;
+    }
+    normalizeTimelineItemForInheritedPrefixComparison(item) {
+        if (item.type !== 'tool_call') {
+            return item;
+        }
+        if (item.name === 'spawn_agent' && item.detail.type === 'sub_agent') {
+            return {
+                type: item.type,
+                name: item.name,
+                detail: {
+                    type: item.detail.type,
+                    subAgentType: item.detail.subAgentType ?? null,
+                    description: item.detail.description ?? null,
+                },
+            };
+        }
+        return item;
+    }
+    serializeTimelineItemFingerprint(item) {
+        return JSON.stringify(this.normalizeTimelineItemForInheritedPrefixComparison(item));
+    }
+    countInheritedTimelinePrefix(parentTimeline, childTimeline) {
+        let index = 0;
+        while (index < parentTimeline.length && index < childTimeline.length) {
+            if (this.serializeTimelineItemFingerprint(parentTimeline[index])
+                !== this.serializeTimelineItemFingerprint(childTimeline[index])) {
+                break;
+            }
+            index += 1;
+        }
+        return index;
+    }
+    buildProviderThreadTimelineRows(input) {
+        const createdAtMs = input.createdAt.getTime();
+        return input.timeline.map((item, index) => ({
+            seq: index,
+            timestamp: new Date(createdAtMs + index).toISOString(),
+            item,
+        }));
+    }
+    async listPersistedProviderChildThreadCandidates() {
+        let limit = PROVIDER_CHILD_THREADS_PERSISTED_LIST_INITIAL_LIMIT;
+        let previousCount = -1;
+        while (true) {
+            const descriptors = await this.agentManager.listPersistedAgents({
+                provider: 'codex',
+                limit,
+                includeTimeline: false,
+            });
+            if (descriptors.length < limit) {
+                return descriptors;
+            }
+            if (descriptors.length === previousCount || limit >= PROVIDER_CHILD_THREADS_PERSISTED_LIST_MAX_LIMIT) {
+                return descriptors;
+            }
+            previousCount = descriptors.length;
+            limit = Math.min(limit * 2, PROVIDER_CHILD_THREADS_PERSISTED_LIST_MAX_LIMIT);
+        }
+    }
+    async listProviderChildThreadEntries() {
+        const agents = await this.listAgentPayloads();
+        const parentAgentBySessionId = new Map();
+        for (const agent of agents) {
+            const sessionId = this.resolveAgentSessionId(agent);
+            if (!sessionId) {
+                continue;
+            }
+            if (!parentAgentBySessionId.has(sessionId)) {
+                parentAgentBySessionId.set(sessionId, agent);
+            }
+        }
+        const placementByCwd = new Map();
+        const getPlacement = (cwd) => {
+            const existing = placementByCwd.get(cwd);
+            if (existing) {
+                return existing;
+            }
+            const next = this.buildProjectPlacement(cwd);
+            placementByCwd.set(cwd, next);
+            return next;
+        };
+        const persistedThreads = await this.listPersistedProviderChildThreadCandidates();
+        const entries = [];
+        const seenKeys = new Set();
+        const existingEntryByThreadId = new Map(this.providerChildThreadEntries.map((entry) => [entry.thread.threadId, entry]));
+        for (const descriptor of persistedThreads) {
+            const threadId = descriptor.sessionId.trim();
+            const parentSessionId = descriptor.parentSessionId?.trim() ?? '';
+            if (!threadId || !parentSessionId) {
+                continue;
+            }
+            const parentAgent = parentAgentBySessionId.get(parentSessionId);
+            if (!parentAgent) {
+                const existingEntry = existingEntryByThreadId.get(threadId);
+                if (existingEntry) {
+                    entries.push(existingEntry);
+                    seenKeys.add(`codex:${threadId}`);
+                }
+                continue;
+            }
+            const dedupeKey = `codex:${threadId}`;
+            if (seenKeys.has(dedupeKey)) {
+                continue;
+            }
+            seenKeys.add(dedupeKey);
+            entries.push({
+                thread: {
+                    id: this.buildProviderChildThreadId({
+                        provider: 'codex',
+                        threadId,
+                    }),
+                    provider: 'codex',
+                    threadId,
+                    parentThreadId: descriptor.parentSessionId ?? null,
+                    rootThreadId: descriptor.rootSessionId ?? null,
+                    parentAgentId: parentAgent.id,
+                    cwd: descriptor.cwd,
+                    title: descriptor.title,
+                    status: this.resolveProviderChildThreadStatus({ parentAgent }),
+                    model: descriptor.model ?? null,
+                    createdAt: descriptor.createdAt.toISOString(),
+                    updatedAt: descriptor.lastActivityAt.toISOString(),
+                    persistence: descriptor.persistence,
+                    agentId: descriptor.agentId ?? null,
+                    agentNickname: descriptor.agentNickname ?? null,
+                    agentRole: descriptor.agentRole ?? null,
+                },
+                project: await getPlacement(descriptor.cwd),
+            });
+        }
+        entries.sort((left, right) => new Date(right.thread.updatedAt).getTime() - new Date(left.thread.updatedAt).getTime());
+        return entries;
+    }
+    async handleFetchProviderThreadTimeline(request) {
+        const detailMode = request.detailMode ?? 'full';
+        try {
+            await this.ensureProviderChildThreadEntriesHydrated();
+            const isKnownChildThread = this.providerChildThreadEntries.some((entry) => entry.thread.provider === 'codex' && entry.thread.threadId === request.threadId);
+            if (!isKnownChildThread) {
+                throw new SessionRequestError('provider_thread_not_found', `Provider thread not found: ${request.threadId}`);
+            }
+            const descriptor = await this.agentManager.readPersistedAgent('codex', {
+                sessionId: request.threadId,
+                includeTimeline: true,
+            });
+            if (!descriptor) {
+                throw new SessionRequestError('provider_thread_not_found', `Provider thread not found: ${request.threadId}`);
+            }
+            let inheritedPrefixCount = 0;
+            if (descriptor.parentSessionId) {
+                const parentDescriptor = await this.agentManager.readPersistedAgent('codex', {
+                    sessionId: descriptor.parentSessionId,
+                    includeTimeline: true,
+                });
+                if (parentDescriptor) {
+                    inheritedPrefixCount = this.countInheritedTimelinePrefix(parentDescriptor.timeline, descriptor.timeline);
+                }
+            }
+            const timelineRows = this.buildProviderThreadTimelineRows({
+                timeline: descriptor.timeline.slice(inheritedPrefixCount),
+                createdAt: descriptor.createdAt,
+            });
+            const entries = projectTimelineRows(timelineRows, 'codex', 'projected').map((entry) => ({
+                ...entry,
+                item: sanitizeTimelineItemForTransport(entry.item, detailMode),
+            }));
+            this.emit({
+                type: 'fetch_provider_thread_timeline_response',
+                payload: {
+                    requestId: request.requestId,
+                    provider: 'codex',
+                    threadId: descriptor.sessionId,
+                    epoch: this.buildProviderThreadTimelineEpoch(descriptor.sessionId),
+                    inheritedPrefixCount,
+                    entries,
+                    error: null,
+                },
+            });
+        }
+        catch (error) {
+            this.sessionLogger.error({ err: error, threadId: request.threadId }, 'Failed to handle fetch_provider_thread_timeline_request');
+            this.emit({
+                type: 'fetch_provider_thread_timeline_response',
+                payload: {
+                    requestId: request.requestId,
+                    provider: request.provider,
+                    threadId: request.threadId,
+                    epoch: this.buildProviderThreadTimelineEpoch(request.threadId),
+                    inheritedPrefixCount: 0,
+                    entries: [],
+                    error: error instanceof Error ? error.message : 'Failed to fetch provider thread timeline',
+                },
+            });
+        }
+    }
+    async handleFetchProviderChildThreads(request) {
+        try {
+            await this.ensureProviderChildThreadEntriesHydrated();
+            this.emit({
+                type: 'fetch_provider_child_threads_response',
+                payload: {
+                    requestId: request.requestId,
+                    entries: this.providerChildThreadEntries,
+                },
+            });
+        }
+        catch (error) {
+            const code = error instanceof SessionRequestError
+                ? error.code
+                : 'fetch_provider_child_threads_failed';
+            const message = error instanceof Error ? error.message : 'Failed to fetch provider child threads';
+            this.sessionLogger.error({ err: error }, 'Failed to handle fetch_provider_child_threads_request');
+            this.emit({
+                type: 'rpc_error',
+                payload: {
+                    requestId: request.requestId,
+                    requestType: request.type,
+                    error: message,
+                    code,
+                },
+            });
+        }
+    }
     async handleFetchAgent(agentIdOrIdentifier, requestId) {
         const resolved = await this.resolveAgentIdentifier(agentIdOrIdentifier);
         if (!resolved.ok) {
@@ -5744,6 +6253,10 @@ export class Session {
             this.unsubscribeAgentEvents();
             this.unsubscribeAgentEvents = null;
         }
+        if (this.providerChildThreadRefreshTimer) {
+            clearTimeout(this.providerChildThreadRefreshTimer);
+            this.providerChildThreadRefreshTimer = null;
+        }
         // Abort any ongoing operations
         this.abortController.abort();
         // Close MCP clients