factory-factory 0.4.4 → 0.4.6

package/dist/src/backend/services/session/service/lifecycle/session.lifecycle.service.js

@@ -1,11 +1,13 @@
+import { randomUUID } from 'node:crypto';
 import { configService } from '../../../../../backend/services/config.service.js';
 import { createLogger } from '../../../../../backend/services/logger.service.js';
+import { AcpBrowseSessionUnavailableError } from '../../../../../backend/services/session/service/acp/acp-runtime-manager.js';
 import { getChildWorkspaceMcpServerConfig } from '../../../../../backend/services/session/service/acp/child-workspace-mcp-server.js';
 import { acpTraceLogger } from '../../../../../backend/services/session/service/logging/acp-trace-logger.service.js';
 import { sessionEventBus } from '../../../../../backend/services/session/service/session-event-bus.js';
 import { userSettingsService } from '../../../../../backend/services/settings/index.js';
 import { workspaceDataService, workspaceNotificationService } from '../../../../../backend/services/workspace/index.js';
-import { SessionStatus } from '../../../../../shared/core/index.js';
+import { SessionLifecycleEventKind, SessionLifecycleEventReason, SessionStatus, } from '../../../../../shared/core/index.js';
 import { createInitialSessionRuntimeState, } from '../../../../../shared/session-runtime.js';
 import { buildWorkspaceNotificationMessageText, WORKSPACE_NOTIFICATION_MESSAGE_ID_PREFIX, workspaceNotificationMessageId, } from '../../../../../shared/workspace-notifications.js';
 import { closedSessionPersistenceService } from './closed-session-persistence.service.js';
@@ -13,9 +15,22 @@ import { toErrorMessage } from './session.error-message.js';
 import { maybeDiscoverPROnSessionEnd as maybeDiscoverPROnSessionEndHelper } from './session-pr-discovery.service.js';
 import { isStaleLoadingRuntime } from './session-runtime-state.helpers.js';
 const logger = createLogger('session');
+class SessionStartupCancelledError extends Error {
+    constructor() {
+        super('Session is currently being stopped');
+        this.name = 'SessionStartupCancelledError';
+    }
+}
 function getPersistedStatusForExitCode(exitCode) {
     return exitCode === 0 ? SessionStatus.COMPLETED : SessionStatus.FAILED;
 }
+const SESSION_STOP_MESSAGES = {
+    USER_STOP: 'Session stopped by you.',
+    SESSION_CLOSED: 'Session closed by you.',
+    WORKSPACE_ARCHIVED: 'Session stopped because the workspace was archived.',
+    SYSTEM_STOP: 'Session stopped by the system.',
+};
+const SHUTDOWN_LIFECYCLE_RECORD_TIMEOUT_MS = 1000;
 export class SessionLifecycleService {
     repository;
     promptBuilder;
@@ -26,11 +41,16 @@ export class SessionLifecycleService {
     acpEventProcessor;
     promptTurnCompletionService;
     retryService;
+    lifecycleEventService;
+    hydrateProviderHistory;
     sendSessionMessage;
     onBeforeStopSession;
     onSessionExit;
     stoppingSessions = new Set();
+    shutdownSessions = new Set();
+    stopGenerationCounter = 0;
     stopGenerations = new Map();
+    startupGenerationReferences = new Map();
     clientCreationOperations = new Map();
     workspaceBridge = null;
     messageQueueBridge = null;
@@ -45,6 +65,9 @@ export class SessionLifecycleService {
         this.acpEventProcessor = options.acpEventProcessor;
         this.promptTurnCompletionService = options.promptTurnCompletionService;
         this.retryService = options.retryService;
+        this.lifecycleEventService = options.lifecycleEventService;
+        this.hydrateProviderHistory =
+            options.hydrateProviderHistory ?? (async () => undefined);
         this.sendSessionMessage = options.sendSessionMessage;
         this.onBeforeStopSession = options.onBeforeStopSession;
         this.onSessionExit = options.onSessionExit;
@@ -55,32 +78,34 @@ export class SessionLifecycleService {
         this.autoIterationExitBridge = bridges.autoIterationExit ?? null;
     }
     async startSession(sessionId, options) {
-        const stopGeneration = this.getStopGeneration(sessionId);
-        const session = await this.repository.getSessionById(sessionId);
-        if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
-        }
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        const existingClient = this.runtimeManager.getClient(sessionId);
-        if (existingClient) {
-            throw new Error('Session is already running');
-        }
-        const startupModePreset = options?.startupModePreset;
-        const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(sessionId, {}, session, stopGeneration);
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        await this.applyStartupModePreset(sessionId, handle, startupModePreset, session.workflow);
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        await this.applyConfiguredPermissionPreset(sessionId, session, handle, resolvedPreset);
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        await this.dispatchQueuedNotificationsIfNeeded(sessionId, dispatchableNotificationCount);
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        const initialPrompt = options?.initialPrompt ?? 'Continue with the task.';
-        const shouldSendInitialPrompt = dispatchableNotificationCount === 0 ||
-            (typeof options?.initialPrompt === 'string' && !options.initialPromptIsDefault);
-        if (shouldSendInitialPrompt && initialPrompt) {
-            await this.sendSessionMessage(sessionId, initialPrompt);
-        }
-        logger.info('Session started', { sessionId, provider: session.provider });
+        await this.runStartupOperation(sessionId, async (stopGeneration) => {
+            const session = await this.repository.getSessionById(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            const existingClient = this.runtimeManager.getClient(sessionId);
+            if (existingClient) {
+                throw new Error('Session is already running');
+            }
+            const startupModePreset = options?.startupModePreset;
+            const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(sessionId, {}, session, stopGeneration);
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            await this.applyStartupModePreset(sessionId, handle, startupModePreset, session.workflow);
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            await this.applyConfiguredPermissionPreset(sessionId, session, handle, resolvedPreset);
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            await this.dispatchQueuedNotificationsIfNeeded(sessionId, dispatchableNotificationCount);
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            const initialPrompt = options?.initialPrompt ?? 'Continue with the task.';
+            const shouldSendInitialPrompt = dispatchableNotificationCount === 0 ||
+                (typeof options?.initialPrompt === 'string' && !options.initialPromptIsDefault);
+            if (shouldSendInitialPrompt && initialPrompt) {
+                await this.sendSessionMessage(sessionId, initialPrompt);
+            }
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            logger.info('Session started', { sessionId, provider: session.provider });
+        });
     }
     async restartSession(sessionId, options) {
         const isRunning = this.runtimeManager.isSessionRunning(sessionId);
@@ -110,24 +135,33 @@ export class SessionLifecycleService {
             logger.debug('Session stop already in progress', { sessionId });
             return;
         }
-        this.stopGenerations.set(sessionId, this.getStopGeneration(sessionId) + 1);
+        this.advanceStopGeneration(sessionId);
         this.stoppingSessions.add(sessionId);
+        const stopInvocationId = randomUUID();
         try {
-            await this.stopSessionWithBarrier(sessionId, options);
+            await this.stopSessionWithBarrier(sessionId, stopInvocationId, options);
         }
         finally {
             this.stoppingSessions.delete(sessionId);
+            this.stopGenerations.delete(sessionId);
         }
     }
-    async stopSessionWithBarrier(sessionId, options) {
+    async stopSessionWithBarrier(sessionId, stopInvocationId, options) {
         this.promptTurnCompletionService.clearSession(sessionId);
         this.onBeforeStopSession?.(sessionId);
         this.sessionDomainService.clearQueuedWork(sessionId, { emitSnapshot: true });
         const session = await this.loadSessionForStop(sessionId);
         const workspaceId = session?.workspaceId ?? this.acpEventProcessor.getWorkspaceId(sessionId);
-        if (this.runtimeManager.isStopInProgress(sessionId)) {
-            logger.debug('Session stop already in progress', { sessionId });
-            return;
+        const reason = options?.reason ?? 'SYSTEM_STOP';
+        if (workspaceId && options?.recordLifecycleEvent !== false) {
+            await this.lifecycleEventService.record({
+                workspaceId,
+                sessionId,
+                kind: SessionLifecycleEventKind.SESSION_STOPPED,
+                reason,
+                message: SESSION_STOP_MESSAGES[reason],
+                dedupeKey: `session-stop:${stopInvocationId}`,
+            });
         }
         const current = this.getRuntimeSnapshot(sessionId);
         this.sessionDomainService.setRuntimeSnapshot(sessionId, {
@@ -160,7 +194,7 @@ export class SessionLifecycleService {
                 updatedAt: new Date().toISOString(),
             });
             this.markWorkspaceSessionIdleOnStop(workspaceId, sessionId);
-            this.acpEventProcessor.clearSessionContext(sessionId);
+            this.acpEventProcessor.clearSessionState(sessionId);
             if (!stopClientFailed) {
                 const shouldCleanupTransientRatchetSession = options?.cleanupTransientRatchetSession ?? true;
                 await this.cleanupTransientRatchetOnStop(session, sessionId, shouldCleanupTransientRatchetSession);
@@ -178,35 +212,32 @@ export class SessionLifecycleService {
         }
     }
     async stopRuntimeAndPendingCreation(sessionId) {
-        if (!this.runtimeManager.isStopInProgress(sessionId)) {
-            await this.runtimeManager.stopClient(sessionId);
-        }
+        await this.runtimeManager.stopClient(sessionId);
         const pendingCreations = this.clientCreationOperations.get(sessionId);
         if (!pendingCreations || pendingCreations.size === 0) {
             return;
         }
         await Promise.allSettled([...pendingCreations]);
-        if (!this.runtimeManager.isStopInProgress(sessionId)) {
-            await this.runtimeManager.stopClient(sessionId);
-        }
+        await this.runtimeManager.stopClient(sessionId);
     }
-    async stopWorkspaceSessions(workspaceId) {
+    async stopWorkspaceSessions(workspaceId, options) {
         const sessions = await this.repository.getSessionsByWorkspaceId(workspaceId);
         const stopErrors = [];
         for (const session of sessions) {
-            if (session.status === SessionStatus.RUNNING ||
-                this.runtimeManager.isSessionRunning(session.id)) {
-                try {
-                    await this.stopSession(session.id);
-                }
-                catch (error) {
-                    logger.error('Failed to stop workspace session', {
-                        sessionId: session.id,
-                        workspaceId,
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                    stopErrors.push(error);
-                }
+            const stopOptions = this.getWorkspaceSessionStopOptions(session, options?.reason ?? 'SYSTEM_STOP');
+            if (!stopOptions) {
+                continue;
+            }
+            try {
+                await this.stopSession(session.id, stopOptions);
+            }
+            catch (error) {
+                logger.error('Failed to stop workspace session', {
+                    sessionId: session.id,
+                    workspaceId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                stopErrors.push(error);
             }
         }
         if (stopErrors.length > 0) {
@@ -214,37 +245,113 @@ export class SessionLifecycleService {
         }
         logger.info('Stopped all workspace sessions', { workspaceId, count: sessions.length });
     }
-    async getOrCreateSessionClient(sessionId, options) {
-        const stopGeneration = this.getStopGeneration(sessionId);
-        const session = await this.repository.getSessionById(sessionId);
-        if (!session) {
-            throw new Error(`Session not found: ${sessionId}`);
+    getWorkspaceSessionStopOptions(session, reason) {
+        const browseOnlyClient = this.runtimeManager.isBrowseOnlySession(session.id);
+        const activeClient = this.runtimeManager.isSessionRunning(session.id);
+        if (!(session.status === SessionStatus.RUNNING || activeClient || browseOnlyClient)) {
+            return null;
         }
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        const hadClient = !!this.runtimeManager.getClient(sessionId);
-        const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(sessionId, options ?? {}, session, stopGeneration);
-        this.assertStartupAllowed(sessionId, stopGeneration);
-        if (!hadClient) {
-            await this.applyConfiguredPermissionPreset(sessionId, session, handle, resolvedPreset);
+        return {
+            reason,
+            ...(browseOnlyClient && !activeClient ? { recordLifecycleEvent: false } : {}),
+        };
+    }
+    async getOrCreateSessionClient(sessionId, options) {
+        return await this.runStartupOperation(sessionId, async (stopGeneration) => {
+            const session = await this.repository.getSessionById(sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
             this.assertStartupAllowed(sessionId, stopGeneration);
-            await this.dispatchQueuedNotificationsIfNeeded(sessionId, dispatchableNotificationCount);
+            const hadClient = !!this.runtimeManager.getClient(sessionId);
+            const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(sessionId, options ?? {}, session, stopGeneration);
             this.assertStartupAllowed(sessionId, stopGeneration);
-        }
-        return handle;
+            if (!hadClient) {
+                await this.applyConfiguredPermissionPreset(sessionId, session, handle, resolvedPreset);
+                this.assertStartupAllowed(sessionId, stopGeneration);
+                await this.dispatchQueuedNotificationsIfNeeded(sessionId, dispatchableNotificationCount);
+                this.assertStartupAllowed(sessionId, stopGeneration);
+            }
+            return handle;
+        });
     }
     async getOrCreateSessionClientFromRecord(session, options) {
-        const stopGeneration = this.getStopGeneration(session.id);
-        this.assertStartupAllowed(session.id, stopGeneration);
-        const hadClient = !!this.runtimeManager.getClient(session.id);
-        const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(session.id, options ?? {}, session, stopGeneration);
-        this.assertStartupAllowed(session.id, stopGeneration);
-        if (!hadClient) {
-            await this.applyConfiguredPermissionPreset(session.id, session, handle, resolvedPreset);
+        return await this.runStartupOperation(session.id, async (stopGeneration) => {
             this.assertStartupAllowed(session.id, stopGeneration);
-            await this.dispatchQueuedNotificationsIfNeeded(session.id, dispatchableNotificationCount);
+            const hadClient = !!this.runtimeManager.getClient(session.id);
+            const { handle, resolvedPreset, dispatchableNotificationCount } = await this.getOrCreateAcpSessionClient(session.id, options ?? {}, session, stopGeneration);
             this.assertStartupAllowed(session.id, stopGeneration);
+            if (!hadClient) {
+                await this.applyConfiguredPermissionPreset(session.id, session, handle, resolvedPreset);
+                this.assertStartupAllowed(session.id, stopGeneration);
+                await this.dispatchQueuedNotificationsIfNeeded(session.id, dispatchableNotificationCount);
+                this.assertStartupAllowed(session.id, stopGeneration);
+            }
+            return handle;
+        });
+    }
+    async ensureSubagentBrowseSession(sessionId) {
+        if (this.runtimeManager.getSubagentBrowseCapability(sessionId)) {
+            return true;
         }
-        return handle;
+        const pendingClient = this.runtimeManager.getPendingClient(sessionId);
+        if (pendingClient) {
+            try {
+                await pendingClient;
+            }
+            catch (error) {
+                if (error instanceof AcpBrowseSessionUnavailableError) {
+                    return false;
+                }
+                throw error;
+            }
+            return await this.resolveSubagentBrowseSupport(sessionId);
+        }
+        return await this.runStartupOperation(sessionId, async (stopGeneration) => {
+            const session = await this.repository.getSessionById(sessionId);
+            if (!(session?.provider === 'CODEX' && session.providerSessionId)) {
+                return false;
+            }
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            const workspace = await this.repository.getWorkspaceById(session.workspaceId);
+            if (!workspace?.worktreePath ||
+                workspace.status === 'ARCHIVING' ||
+                workspace.status === 'ARCHIVED') {
+                return false;
+            }
+            this.assertStartupAllowed(sessionId, stopGeneration);
+            try {
+                await this.createAcpClient(sessionId, { purpose: 'browse' }, session, undefined, stopGeneration);
+            }
+            catch (error) {
+                if (error instanceof AcpBrowseSessionUnavailableError) {
+                    return false;
+                }
+                throw error;
+            }
+            return await this.resolveSubagentBrowseSupport(sessionId);
+        }).catch((error) => {
+            if (error instanceof SessionStartupCancelledError) {
+                return false;
+            }
+            throw error;
+        });
+    }
+    async resolveSubagentBrowseSupport(sessionId) {
+        if (this.runtimeManager.getSubagentBrowseCapability(sessionId) !== null) {
+            return true;
+        }
+        if (!this.runtimeManager.isBrowseOnlySession(sessionId)) {
+            return false;
+        }
+        this.advanceStopGeneration(sessionId);
+        try {
+            await this.runtimeManager.stopClient(sessionId);
+        }
+        finally {
+            this.acpEventProcessor.clearSessionState(sessionId);
+        }
+        return false;
     }
     getSessionClient(sessionId) {
         return this.runtimeManager.getClient(sessionId);
@@ -285,11 +392,50 @@ export class SessionLifecycleService {
         return this.stoppingSessions.has(sessionId) || this.runtimeManager.isStopInProgress(sessionId);
     }
     getStopGeneration(sessionId) {
-        return this.stopGenerations.get(sessionId) ?? 0;
+        return this.stopGenerations.get(sessionId) ?? this.advanceStopGeneration(sessionId);
+    }
+    async runStartupOperation(sessionId, operation) {
+        const stopGeneration = this.getStopGeneration(sessionId);
+        this.startupGenerationReferences.set(stopGeneration, (this.startupGenerationReferences.get(stopGeneration) ?? 0) + 1);
+        let succeeded = false;
+        try {
+            const result = await operation(stopGeneration);
+            succeeded = true;
+            return result;
+        }
+        finally {
+            this.releaseStartupGeneration(sessionId, stopGeneration, succeeded);
+        }
+    }
+    releaseStartupGeneration(sessionId, stopGeneration, succeeded) {
+        const referenceCount = this.startupGenerationReferences.get(stopGeneration);
+        if (referenceCount === undefined) {
+            return;
+        }
+        if (referenceCount > 1) {
+            this.startupGenerationReferences.set(stopGeneration, referenceCount - 1);
+            return;
+        }
+        this.startupGenerationReferences.delete(stopGeneration);
+        if (!(succeeded ||
+            this.isSessionStopping(sessionId) ||
+            this.runtimeManager.getClient(sessionId)) &&
+            this.isStopGenerationCurrent(sessionId, stopGeneration)) {
+            this.stopGenerations.delete(sessionId);
+        }
+    }
+    isStopGenerationCurrent(sessionId, stopGeneration) {
+        return this.stopGenerations.get(sessionId) === stopGeneration;
+    }
+    advanceStopGeneration(sessionId) {
+        this.stopGenerationCounter += 1;
+        this.stopGenerations.set(sessionId, this.stopGenerationCounter);
+        return this.stopGenerationCounter;
     }
     assertStartupAllowed(sessionId, stopGeneration) {
-        if (this.isSessionStopping(sessionId) || this.getStopGeneration(sessionId) !== stopGeneration) {
-            throw new Error('Session is currently being stopped');
+        if (this.isSessionStopping(sessionId) ||
+            !this.isStopGenerationCurrent(sessionId, stopGeneration)) {
+            throw new SessionStartupCancelledError();
         }
     }
     async getSessionOptions(sessionId) {
@@ -307,6 +453,12 @@ export class SessionLifecycleService {
     }
     async stopAllClients(timeoutMs = 5000) {
         this.promptTurnCompletionService.clearAll();
+        const shutdownSessionIds = this.runtimeManager.beginShutdown();
+        const activeShutdownSessionIds = shutdownSessionIds.filter((sessionId) => !this.runtimeManager.isBrowseOnlySession(sessionId));
+        for (const sessionId of activeShutdownSessionIds) {
+            this.shutdownSessions.add(sessionId);
+        }
+        await this.recordShutdownLifecycleEvents(activeShutdownSessionIds);
         try {
             await this.runtimeManager.stopAllClients(timeoutMs);
         }
@@ -317,83 +469,100 @@ export class SessionLifecycleService {
             throw error;
         }
     }
-    setupAcpEventHandler(sessionId) {
+    async recordShutdownLifecycleEvent(sessionId) {
+        const session = await this.loadSessionForStop(sessionId);
+        const workspaceId = session?.workspaceId ?? this.acpEventProcessor.getWorkspaceId(sessionId);
+        if (!workspaceId) {
+            logger.warn('Skipped shutdown lifecycle event without workspace owner', { sessionId });
+            return;
+        }
+        await this.lifecycleEventService.record({
+            workspaceId,
+            sessionId,
+            kind: SessionLifecycleEventKind.SESSION_STOPPED,
+            reason: SessionLifecycleEventReason.SYSTEM_STOP,
+            message: SESSION_STOP_MESSAGES.SYSTEM_STOP,
+            dedupeKey: `session-stop:${randomUUID()}`,
+        });
+    }
+    async recordShutdownLifecycleEvents(sessionIds) {
+        const resultsPromise = Promise.allSettled(sessionIds.map((sessionId) => this.recordShutdownLifecycleEvent(sessionId)));
+        let timeout;
+        const results = await Promise.race([
+            resultsPromise,
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve(null), SHUTDOWN_LIFECYCLE_RECORD_TIMEOUT_MS);
+            }),
+        ]);
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        if (results === null) {
+            logger.warn('Timed out recording shutdown lifecycle events; continuing shutdown', {
+                timeoutMs: SHUTDOWN_LIFECYCLE_RECORD_TIMEOUT_MS,
+            });
+            return;
+        }
+        for (const [index, result] of results.entries()) {
+            if (result.status === 'rejected') {
+                logger.warn('Failed recording shutdown lifecycle event; continuing shutdown', {
+                    sessionId: sessionIds[index],
+                    error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                });
+            }
+        }
+    }
+    setupAcpEventHandler(sessionId, options) {
         const runtimeEventHandler = this.acpEventProcessor.createRuntimeEventHandler(sessionId);
-        return {
-            ...runtimeEventHandler,
-            onSessionId: async (sid, providerSessionId) => {
-                try {
-                    await this.repository.updateSession(sid, { providerSessionId });
-                    acpTraceLogger.log(sid, 'runtime_metadata', {
-                        type: 'provider_session_id',
-                        providerSessionId,
-                    });
-                    logger.debug('Updated session with ACP providerSessionId', {
-                        sessionId: sid,
-                        providerSessionId,
-                    });
-                }
-                catch (error) {
-                    logger.warn('Failed to update session with ACP providerSessionId', {
-                        sessionId: sid,
-                        providerSessionId,
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
-            },
-            onExit: async (sid, exitCode) => {
-                this.promptTurnCompletionService.clearSession(sid);
-                this.onSessionExit?.(sid);
-                this.finalizeOrphanedToolCalls(sid, 'runtime_exit');
-                this.acpEventProcessor.clearSessionState(sid);
-                this.sessionPermissionService.cancelPendingRequests(sid);
-                acpTraceLogger.log(sid, 'runtime_exit', { exitCode });
-                try {
-                    this.sessionDomainService.markProcessExit(sid, exitCode);
-                    const persistedStatus = getPersistedStatusForExitCode(exitCode);
-                    const session = await this.repository.updateSession(sid, {
-                        status: persistedStatus,
-                    });
-                    logger.debug('Updated ACP session status on exit', {
-                        sessionId: sid,
-                        exitCode,
-                        status: persistedStatus,
-                    });
-                    await this.recordRatchetSessionEndOnExit(session.workspaceId, sid, exitCode);
-                    void this.maybeDiscoverPROnSessionEnd(session.workspaceId);
-                    if (session.workflow === 'ratchet') {
-                        await this.persistRatchetTranscript(sid, session);
-                        await this.repository.deleteSession(sid);
-                        this.sessionDomainService.clearSession(sid);
-                        logger.debug('Deleted transient ratchet ACP session', { sessionId: sid });
-                    }
-                    if (session.workflow === 'auto-iteration' && this.autoIterationExitBridge) {
-                        if (!this.runtimeManager.isStopInProgress(sid)) {
-                            this.autoIterationExitBridge.onAutoIterationSessionExit(session.workspaceId, sid);
-                        }
-                    }
-                }
-                catch (error) {
-                    logger.warn('Failed to update ACP session status on exit', {
-                        sessionId: sid,
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
-                finally {
+        const runtimeIncarnationId = randomUUID();
+        const providerSessionIdHandler = options?.persistProviderSessionId === false
+            ? {}
+            : {
+                onSessionId: async (sid, providerSessionId) => {
                     try {
-                        this.clearSessionStoreIfInactive(sid, 'runtime_exit');
+                        await this.repository.updateSession(sid, { providerSessionId });
+                        acpTraceLogger.log(sid, 'runtime_metadata', {
+                            type: 'provider_session_id',
+                            providerSessionId,
+                        });
+                        logger.debug('Updated session with ACP providerSessionId', {
+                            sessionId: sid,
+                            providerSessionId,
+                        });
                     }
-                    finally {
-                        acpTraceLogger.closeSession(sid);
+                    catch (error) {
+                        logger.warn('Failed to update session with ACP providerSessionId', {
+                            sessionId: sid,
+                            providerSessionId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
                     }
+                },
+            };
+        return {
+            ...runtimeEventHandler,
+            ...providerSessionIdHandler,
+            onExit: async (sid, exitCode) => {
+                this.stopGenerations.delete(sid);
+                if (this.runtimeManager.isBrowseOnlySession(sid)) {
+                    this.acpEventProcessor.clearSessionState(sid);
+                    acpTraceLogger.closeSession(sid);
+                    return;
                 }
+                const wasDeliberateStop = this.stoppingSessions.has(sid) ||
+                    this.shutdownSessions.has(sid) ||
+                    this.runtimeManager.isStopInProgress(sid);
+                this.prepareAcpRuntimeExit(sid, exitCode);
+                await this.handleAcpRuntimeExit(sid, exitCode, wasDeliberateStop, runtimeIncarnationId);
             },
             onError: (sid, error) => {
                 acpTraceLogger.log(sid, 'runtime_error', {
                     message: error.message,
                     stack: error.stack,
                 });
-                this.sessionDomainService.markError(sid, error.message);
+                if (!this.runtimeManager.isBrowseOnlySession(sid)) {
+                    this.sessionDomainService.markError(sid, error.message);
+                }
                 logger.error('ACP client error', {
                     sessionId: sid,
                     error: error.message,
@@ -405,20 +574,104 @@ export class SessionLifecycleService {
             },
         };
     }
+    prepareAcpRuntimeExit(sessionId, exitCode) {
+        this.promptTurnCompletionService.clearSession(sessionId);
+        this.onSessionExit?.(sessionId);
+        this.finalizeOrphanedToolCalls(sessionId, 'runtime_exit');
+        this.acpEventProcessor.clearSessionState(sessionId);
+        this.sessionPermissionService.cancelPendingRequests(sessionId);
+        acpTraceLogger.log(sessionId, 'runtime_exit', { exitCode });
+    }
+    async handleAcpRuntimeExit(sessionId, exitCode, wasDeliberateStop, runtimeIncarnationId) {
+        try {
+            this.sessionDomainService.markProcessExit(sessionId, exitCode);
+            const session = await this.repository.getSessionById(sessionId);
+            if (!session) {
+                logger.warn('Failed to find ACP session on exit', { sessionId });
+                return;
+            }
+            const persistedStatus = getPersistedStatusForExitCode(exitCode);
+            try {
+                await this.repository.updateSession(sessionId, { status: persistedStatus });
+                logger.debug('Updated ACP session status on exit', {
+                    sessionId,
+                    exitCode,
+                    status: persistedStatus,
+                });
+            }
+            catch (error) {
+                logger.warn('Failed to update ACP session status on exit', {
+                    sessionId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            await this.recordUnexpectedExitIfNeeded(session, sessionId, exitCode, wasDeliberateStop, runtimeIncarnationId);
+            await this.recordRatchetSessionEndOnExit(session.workspaceId, sessionId, exitCode);
+            void this.maybeDiscoverPROnSessionEnd(session.workspaceId);
+            await this.cleanupExitedWorkflow(session, sessionId, wasDeliberateStop);
+        }
+        catch (error) {
+            logger.warn('Failed to process ACP session exit', {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            try {
+                this.clearSessionStoreIfInactive(sessionId, 'runtime_exit');
+            }
+            finally {
+                acpTraceLogger.closeSession(sessionId);
+            }
+        }
+    }
+    async recordUnexpectedExitIfNeeded(session, sessionId, exitCode, wasDeliberateStop, runtimeIncarnationId) {
+        if (wasDeliberateStop) {
+            return;
+        }
+        await this.lifecycleEventService.record({
+            workspaceId: session.workspaceId,
+            sessionId,
+            kind: SessionLifecycleEventKind.SESSION_STOPPED,
+            reason: SessionLifecycleEventReason.UNEXPECTED_EXIT,
+            message: exitCode === null
+                ? 'Session stopped: agent process exited unexpectedly.'
+                : `Session stopped: agent process exited unexpectedly (code ${exitCode}).`,
+            dedupeKey: `process-exit:${runtimeIncarnationId}:${exitCode ?? 'signal'}`,
+        });
+    }
+    async cleanupExitedWorkflow(session, sessionId, wasDeliberateStop) {
+        if (session.workflow === 'ratchet') {
+            await this.persistRatchetTranscript(sessionId);
+            await this.repository.deleteSession(sessionId);
+            this.sessionDomainService.clearSession(sessionId);
+            logger.debug('Deleted transient ratchet ACP session', { sessionId });
+        }
+        if (session.workflow === 'auto-iteration' &&
+            this.autoIterationExitBridge &&
+            !wasDeliberateStop) {
+            this.autoIterationExitBridge.onAutoIterationSessionExit(session.workspaceId, sessionId);
+        }
+    }
     async createAcpClient(sessionId, options, session, permissionPreset, stopGeneration = this.getStopGeneration(sessionId)) {
         const sessionContext = await this.loadSessionContext(sessionId, session);
         if (!sessionContext) {
             throw new Error(`Session context not ready: ${sessionId}`);
         }
         this.assertStartupAllowed(sessionId, stopGeneration);
-        await this.repository.markWorkspaceHasHadSessions(sessionContext.workspaceId);
-        this.assertStartupAllowed(sessionId, stopGeneration);
+        const browseOnly = options?.purpose === 'browse';
+        if (!browseOnly) {
+            await this.repository.markWorkspaceHasHadSessions(sessionContext.workspaceId);
+            this.assertStartupAllowed(sessionId, stopGeneration);
+        }
         this.acpEventProcessor.registerSessionContext(sessionId, {
             workspaceId: sessionContext.workspaceId,
             workingDir: sessionContext.workingDir,
             provider: session?.provider ?? 'CLAUDE',
         });
-        const handlers = this.setupAcpEventHandler(sessionId);
+        const handlers = this.setupAcpEventHandler(sessionId, {
+            persistProviderSessionId: !browseOnly,
+        });
         const shouldSuppressReplay = this.shouldSuppressReplayDuringAcpResume(sessionId, session);
         this.acpEventProcessor.setReplaySuppression(sessionId, shouldSuppressReplay);
         const apiPort = String(configService.getBackendPort());
@@ -429,6 +682,7 @@ export class SessionLifecycleService {
         });
         const clientOptions = {
             provider: session?.provider ?? 'CLAUDE',
+            purpose: options?.purpose,
             workingDir: sessionContext.workingDir,
             model: options?.model ?? sessionContext.model,
             systemPrompt: sessionContext.systemPrompt,
@@ -449,13 +703,16 @@ export class SessionLifecycleService {
         try {
             handle = await creationPromise;
             this.assertStartupAllowed(sessionId, stopGeneration);
+            if (browseOnly) {
+                return { handle, dispatchableNotificationCount: 0 };
+            }
             await this.sessionConfigService.applyConfiguredReasoningEffort(sessionId, handle, {
                 persistSnapshot: false,
                 emitUpdates: false,
             });
         }
         catch (error) {
-            this.acpEventProcessor.clearSessionState(sessionId);
+            this.clearAcpSessionStateAfterFailedCreation(sessionId, sessionCreations);
             throw error;
         }
         finally {
@@ -485,6 +742,11 @@ export class SessionLifecycleService {
         const dispatchableNotificationCount = await this.deliverPendingChildNotifications(sessionId, sessionContext.workspaceId, stopGeneration);
         return { handle, dispatchableNotificationCount };
     }
+    clearAcpSessionStateAfterFailedCreation(sessionId, sessionCreations) {
+        if (sessionCreations.size === 1) {
+            this.acpEventProcessor.clearSessionState(sessionId);
+        }
+    }
     shouldSuppressReplayDuringAcpResume(sessionId, session) {
         if (!session?.providerSessionId) {
             return false;
@@ -581,7 +843,7 @@ export class SessionLifecycleService {
             return;
         }
         try {
-            await this.persistRatchetTranscript(sessionId, session);
+            await this.persistRatchetTranscript(sessionId);
             await this.repository.deleteSession(sessionId);
             this.sessionDomainService.clearSession(sessionId);
             logger.debug('Deleted transient ratchet session after stop', { sessionId });
@@ -617,20 +879,26 @@ export class SessionLifecycleService {
         this.sessionDomainService.clearSession(sessionId, { preserveRejections: true });
         logger.debug('Cleared inactive in-memory session state', { sessionId, reason });
     }
-    async persistRatchetTranscript(sessionId, session) {
-        if (!this.workspaceBridge) {
-            logger.warn('Cannot persist ratchet transcript: no workspace bridge', { sessionId });
+    async persistClosedSession(sessionId) {
+        const session = await this.repository.getSessionById(sessionId);
+        if (!session) {
+            logger.warn('Cannot persist closed session: session not found', { sessionId });
             return;
         }
-        const transcript = this.sessionDomainService.getTranscriptSnapshot(sessionId);
         const workspace = await workspaceDataService.findById(session.workspaceId);
         if (!workspace?.worktreePath) {
-            logger.warn('Cannot persist ratchet transcript: no worktree path', {
+            logger.warn('Cannot persist closed session: no worktree path', {
                 sessionId,
                 workspaceId: session.workspaceId,
             });
             return;
         }
+        await this.hydrateProviderHistory(sessionId, {
+            ...session,
+            workspace: { worktreePath: workspace.worktreePath },
+        });
+        await this.lifecycleEventService.hydrate(sessionId);
+        const transcript = this.sessionDomainService.getTranscriptSnapshot(sessionId);
         await closedSessionPersistenceService.persistClosedSession({
             sessionId,
             workspaceId: session.workspaceId,
@@ -643,6 +911,9 @@ export class SessionLifecycleService {
             messages: transcript,
         });
     }
+    async persistRatchetTranscript(sessionId) {
+        await this.persistClosedSession(sessionId);
+    }
     async getOrCreateAcpSessionClient(sessionId, options, session, stopGeneration) {
         this.assertStartupAllowed(sessionId, stopGeneration);
         const existingAcp = this.runtimeManager.getClient(sessionId);