factory-factory 0.4.4 → 0.4.6

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

@@ -1,9 +1,19 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AcpBrowseSessionUnavailableError } from '../../../../../backend/services/session/service/acp/acp-runtime-manager.js';
+import { SessionDomainService } from '../../../../../backend/services/session/service/session-domain.service.js';
+import { sessionEventBus } from '../../../../../backend/services/session/service/session-event-bus.js';
 import { userSettingsService } from '../../../../../backend/services/settings/index.js';
-import { workspaceNotificationService } from '../../../../../backend/services/workspace/index.js';
+import { workspaceDataService, workspaceNotificationService } from '../../../../../backend/services/workspace/index.js';
 import { SessionStatus } from '../../../../../shared/core/index.js';
 import { unsafeCoerce } from '../../../../../test-utils/unsafe-coerce.js';
 import { SessionLifecycleService } from './session.lifecycle.service.js';
+import { SessionLifecycleEventService } from './session-lifecycle-event.service.js';
+vi.mock('./closed-session-persistence.service', () => ({
+    closedSessionPersistenceService: {
+        persistClosedSession: vi.fn(async () => undefined),
+    },
+}));
+import { closedSessionPersistenceService } from './closed-session-persistence.service.js';
 vi.mock('@/backend/services/logger.service', () => ({
     createLogger: () => ({
         debug: vi.fn(),
@@ -11,6 +21,7 @@ vi.mock('@/backend/services/logger.service', () => ({
         warn: vi.fn(),
         error: vi.fn(),
     }),
+    getCurrentProcessEnv: () => ({ ...process.env }),
 }));
 vi.mock('@/backend/services/workspace', () => ({
     workspaceDataService: { findById: vi.fn() },
@@ -49,6 +60,7 @@ function createLifecycleService(options) {
         promptTurnCompletionService: {},
         retryService: {},
         sendSessionMessage: vi.fn(async () => undefined),
+        lifecycleEventService: { hydrate: vi.fn(async () => undefined) },
     });
     service.configure({
         workspace: {
@@ -64,16 +76,31 @@ function createLifecycleService(options) {
 async function deliverPendingChildNotifications(service, sessionId = 'session-1', workspaceId = 'workspace-1') {
     return await service.deliverPendingChildNotifications(sessionId, workspaceId);
 }
+function getStopGenerations(service) {
+    return service.stopGenerations;
+}
+function createDeferred() {
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    return { promise, resolve: resolvePromise, reject: rejectPromise };
+}
 function createStoppableLifecycleService() {
     const repository = {
         getSessionsByWorkspaceId: vi.fn(async () => [
             { id: 'session-running', status: SessionStatus.RUNNING },
             { id: 'session-runtime-only', status: SessionStatus.COMPLETED },
+            { id: 'session-browse-only', status: SessionStatus.IDLE },
             { id: 'session-idle', status: SessionStatus.IDLE },
         ]),
     };
     const runtimeManager = {
         isSessionRunning: vi.fn((sessionId) => sessionId === 'session-runtime-only'),
+        getBrowseClient: vi.fn(() => undefined),
+        isBrowseOnlySession: vi.fn((sessionId) => sessionId === 'session-browse-only'),
     };
     const service = new SessionLifecycleService({
         repository: repository,
@@ -86,11 +113,78 @@ function createStoppableLifecycleService() {
         promptTurnCompletionService: {},
         retryService: {},
         sendSessionMessage: vi.fn(async () => undefined),
+        lifecycleEventService: { hydrate: vi.fn(async () => undefined) },
     });
-    const stopSession = vi.fn((_sessionId) => Promise.resolve());
+    const stopSession = vi.fn((_sessionId, _options) => Promise.resolve());
     service.stopSession = stopSession;
     return { service, repository, runtimeManager, stopSession };
 }
+function createStopReasonLifecycleService(options) {
+    const session = {
+        id: 'session-1',
+        workspaceId: 'workspace-1',
+        workflow: 'code',
+        providerProcessPid: options?.providerProcessPid ?? 4242,
+    };
+    const repository = {
+        getSessionById: vi.fn(async () => session),
+        updateSessionIfStatus: vi.fn(async () => session),
+        updateSession: vi.fn(async () => session),
+    };
+    const runtimeManager = {
+        isStopInProgress: vi.fn(() => false),
+        isSessionRunning: vi.fn(() => false),
+        isBrowseOnlySession: vi.fn(() => false),
+        isSessionWorking: vi.fn(() => false),
+        getClient: vi.fn(() => undefined),
+        stopClient: vi.fn(async () => undefined),
+    };
+    const lifecycleEventService = {
+        record: vi.fn(async (_input) => null),
+        hydrate: vi.fn(),
+    };
+    const service = new SessionLifecycleService(unsafeCoerce({
+        repository,
+        promptBuilder: {},
+        runtimeManager,
+        sessionDomainService: {
+            clearQueuedWork: vi.fn(),
+            getRuntimeSnapshot: vi.fn(() => ({
+                phase: 'idle',
+                processState: 'stopped',
+                activity: 'IDLE',
+                updatedAt: '2026-07-30T00:00:00.000Z',
+            })),
+            setRuntimeSnapshot: vi.fn(),
+            markProcessExit: vi.fn(),
+            clearSession: vi.fn(),
+        },
+        sessionPermissionService: { cancelPendingRequests: vi.fn() },
+        sessionConfigService: {},
+        acpEventProcessor: {
+            createRuntimeEventHandler: vi.fn(() => ({})),
+            clearStreamingState: vi.fn(),
+            clearReplaySuppression: vi.fn(),
+            clearSessionContext: vi.fn(),
+            clearSessionState: vi.fn(),
+            finalizeOrphanedToolCalls: vi.fn(),
+        },
+        promptTurnCompletionService: { clearSession: vi.fn() },
+        retryService: { run: vi.fn(async (operation) => await operation()) },
+        lifecycleEventService,
+        sendSessionMessage: vi.fn(),
+    }));
+    const createRuntimeHandlers = () => service;
+    const runtimeHandlers = createRuntimeHandlers().setupAcpEventHandler('session-1');
+    return {
+        service,
+        repository,
+        lifecycleEventService,
+        runtimeManager,
+        runtimeHandlers,
+        createRuntimeHandlers: () => createRuntimeHandlers().setupAcpEventHandler('session-1'),
+    };
+}
 describe('SessionLifecycleService stopWorkspaceSessions', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -101,8 +195,12 @@ describe('SessionLifecycleService stopWorkspaceSessions', () => {
         expect(repository.getSessionsByWorkspaceId).toHaveBeenCalledWith('workspace-1');
         expect(runtimeManager.isSessionRunning).toHaveBeenCalledWith('session-runtime-only');
         expect(runtimeManager.isSessionRunning).toHaveBeenCalledWith('session-idle');
-        expect(stopSession).toHaveBeenCalledWith('session-running');
-        expect(stopSession).toHaveBeenCalledWith('session-runtime-only');
+        expect(stopSession).toHaveBeenCalledWith('session-running', { reason: 'SYSTEM_STOP' });
+        expect(stopSession).toHaveBeenCalledWith('session-runtime-only', { reason: 'SYSTEM_STOP' });
+        expect(stopSession).toHaveBeenCalledWith('session-browse-only', {
+            reason: 'SYSTEM_STOP',
+            recordLifecycleEvent: false,
+        });
         expect(stopSession).not.toHaveBeenCalledWith('session-idle');
     });
     it('attempts every running session and throws when any stop fails', async () => {
@@ -114,8 +212,266 @@ describe('SessionLifecycleService stopWorkspaceSessions', () => {
             return Promise.resolve();
         });
         await expect(service.stopWorkspaceSessions('workspace-1')).rejects.toThrow('Failed to stop 1 workspace session');
-        expect(stopSession).toHaveBeenCalledWith('session-running');
-        expect(stopSession).toHaveBeenCalledWith('session-runtime-only');
+        expect(stopSession).toHaveBeenCalledWith('session-running', { reason: 'SYSTEM_STOP' });
+        expect(stopSession).toHaveBeenCalledWith('session-runtime-only', { reason: 'SYSTEM_STOP' });
+    });
+});
+describe('SessionLifecycleService stop causes', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it.each([
+        ['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.'],
+    ])('records %s before stopping the runtime', async (reason, message) => {
+        const { service, lifecycleEventService, runtimeManager } = createStopReasonLifecycleService();
+        await service.stopSession('session-1', { reason });
+        expect(lifecycleEventService.record).toHaveBeenCalledWith(expect.objectContaining({
+            workspaceId: 'workspace-1',
+            sessionId: 'session-1',
+            kind: 'SESSION_STOPPED',
+            reason,
+            message,
+            dedupeKey: expect.stringMatching(/^session-stop:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/),
+        }));
+        expect(lifecycleEventService.record.mock.invocationCallOrder[0]).toBeLessThan(runtimeManager.stopClient.mock.invocationCallOrder[0]);
+    });
+    it('uses a new durable stop identity after lifecycle-service reconstruction', async () => {
+        const first = createStopReasonLifecycleService();
+        const reconstructed = createStopReasonLifecycleService();
+        await first.service.stopSession('session-1', { reason: 'USER_STOP' });
+        await reconstructed.service.stopSession('session-1', { reason: 'USER_STOP' });
+        const firstKey = first.lifecycleEventService.record.mock.calls[0]?.[0]?.dedupeKey;
+        const reconstructedKey = reconstructed.lifecycleEventService.record.mock.calls[0]?.[0]?.dedupeKey;
+        expect(firstKey).toMatch(/^session-stop:/);
+        expect(reconstructedKey).toMatch(/^session-stop:/);
+        expect(reconstructedKey).not.toBe(firstKey);
+    });
+    it('records an unexpected process exit once with its runtime incarnation and exit code', async () => {
+        const { lifecycleEventService, runtimeHandlers } = createStopReasonLifecycleService();
+        await runtimeHandlers.onExit?.('session-1', 1);
+        expect(lifecycleEventService.record).toHaveBeenCalledWith(expect.objectContaining({
+            kind: 'SESSION_STOPPED',
+            reason: 'UNEXPECTED_EXIT',
+            message: 'Session stopped: agent process exited unexpectedly (code 1).',
+            dedupeKey: expect.stringMatching(/^process-exit:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}:1$/),
+        }));
+    });
+    it('records an unexpected process exit when the status update fails', async () => {
+        const { lifecycleEventService, repository, runtimeHandlers } = createStopReasonLifecycleService();
+        repository.updateSession.mockRejectedValueOnce(new Error('database write failed'));
+        await runtimeHandlers.onExit?.('session-1', 1);
+        expect(lifecycleEventService.record).toHaveBeenCalledWith(expect.objectContaining({
+            reason: 'UNEXPECTED_EXIT',
+            dedupeKey: expect.stringMatching(/^process-exit:.+:1$/),
+        }));
+    });
+    it('does not collapse repeated null-PID exits from separate runtime incarnations', async () => {
+        const { lifecycleEventService, createRuntimeHandlers } = createStopReasonLifecycleService({
+            providerProcessPid: null,
+        });
+        await createRuntimeHandlers().onExit?.('session-1', 1);
+        await createRuntimeHandlers().onExit?.('session-1', 1);
+        const dedupeKeys = lifecycleEventService.record.mock.calls.map(([recordInput]) => recordInput.dedupeKey);
+        expect(dedupeKeys).toHaveLength(2);
+        expect(new Set(dedupeKeys).size).toBe(2);
+        expect(dedupeKeys).toEqual([
+            expect.stringMatching(/^process-exit:.+:1$/),
+            expect.stringMatching(/^process-exit:.+:1$/),
+        ]);
+    });
+    it('does not label a deliberate stop as an unexpected exit', async () => {
+        const { lifecycleEventService, runtimeManager, runtimeHandlers } = createStopReasonLifecycleService();
+        runtimeManager.isStopInProgress.mockReturnValue(true);
+        await runtimeHandlers.onExit?.('session-1', 0);
+        expect(lifecycleEventService.record).not.toHaveBeenCalledWith(expect.objectContaining({ reason: 'UNEXPECTED_EXIT' }));
+    });
+    it('can clean up a failed startup without recording a stop event', async () => {
+        const { service, lifecycleEventService, runtimeManager } = createStopReasonLifecycleService();
+        await service.stopSession('session-1', { recordLifecycleEvent: false });
+        expect(lifecycleEventService.record).not.toHaveBeenCalled();
+        expect(runtimeManager.stopClient).toHaveBeenCalledWith('session-1');
+    });
+});
+describe('SessionLifecycleService closed transcript persistence', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('hydrates durable lifecycle rows before persisting a closed transcript', async () => {
+        const domain = new SessionDomainService();
+        const hydrateProviderHistory = vi.fn(() => {
+            domain.replaceTranscript('session-1', [
+                {
+                    id: 'provider-user-1',
+                    source: 'user',
+                    text: 'Original provider conversation',
+                    timestamp: '2026-07-30T12:00:00.000Z',
+                    order: 0,
+                },
+            ]);
+            return Promise.resolve();
+        });
+        const lifecycleEventService = new SessionLifecycleEventService({
+            store: {
+                upsert: vi.fn(),
+                findBySessionId: vi.fn(async () => [
+                    {
+                        id: 'event-1',
+                        workspaceId: 'workspace-1',
+                        sessionId: 'session-1',
+                        kind: 'TURN_INTERRUPTED',
+                        reason: 'PROMPT_TIMEOUT',
+                        message: 'Turn stopped: reached the 4-hour limit.',
+                        dedupeKey: 'prompt-timeout',
+                        createdAt: new Date('2026-07-30T12:22:23.353Z'),
+                    },
+                ]),
+            },
+            sessionDomainService: domain,
+        });
+        const hydrateLifecycleEvents = vi.spyOn(lifecycleEventService, 'hydrate');
+        domain.clearSession('session-1');
+        const repository = {
+            getSessionById: vi.fn(async () => ({
+                id: 'session-1',
+                workspaceId: 'workspace-1',
+                name: 'Chat',
+                workflow: 'user',
+                provider: 'CLAUDE',
+                model: 'claude-sonnet',
+                createdAt: new Date('2026-07-30T12:00:00.000Z'),
+            })),
+        };
+        vi.mocked(workspaceDataService.findById).mockResolvedValue({
+            id: 'workspace-1',
+            worktreePath: '/tmp/worktree',
+        });
+        const service = new SessionLifecycleService(unsafeCoerce({
+            repository,
+            promptBuilder: {},
+            runtimeManager: {},
+            sessionDomainService: domain,
+            sessionPermissionService: {},
+            sessionConfigService: {},
+            acpEventProcessor: {},
+            promptTurnCompletionService: {},
+            retryService: {},
+            sendSessionMessage: vi.fn(),
+            lifecycleEventService,
+            hydrateProviderHistory,
+        }));
+        await service.persistClosedSession('session-1');
+        expect(closedSessionPersistenceService.persistClosedSession).toHaveBeenCalledWith(expect.objectContaining({
+            sessionId: 'session-1',
+            messages: expect.arrayContaining([
+                expect.objectContaining({ id: 'provider-user-1' }),
+                expect.objectContaining({ id: 'session-lifecycle:event-1' }),
+            ]),
+        }));
+        expect(hydrateProviderHistory).toHaveBeenCalledWith('session-1', expect.objectContaining({ provider: 'CLAUDE' }));
+        expect(hydrateProviderHistory.mock.invocationCallOrder[0]).toBeLessThan(hydrateLifecycleEvents.mock.invocationCallOrder[0]);
+    });
+});
+describe('SessionLifecycleService graceful shutdown', () => {
+    it('records SYSTEM_STOP for active and pending runtimes before bounded shutdown', async () => {
+        const runtimeManager = {
+            beginShutdown: vi.fn(() => ['session-active', 'session-pending', 'session-browse-only']),
+            stopAllClients: vi.fn(async () => undefined),
+            isStopInProgress: vi.fn(() => false),
+            isBrowseOnlySession: vi.fn((sessionId) => sessionId === 'session-browse-only'),
+        };
+        const repository = {
+            getSessionById: vi.fn(async (sessionId) => ({
+                id: sessionId,
+                workspaceId: 'workspace-1',
+                workflow: 'code',
+            })),
+        };
+        const lifecycleEventService = {
+            record: vi.fn(async () => null),
+            hydrate: vi.fn(async () => undefined),
+        };
+        const promptTurnCompletionService = {
+            clearAll: vi.fn(),
+        };
+        const service = new SessionLifecycleService(unsafeCoerce({
+            repository,
+            promptBuilder: {},
+            runtimeManager,
+            sessionDomainService: {},
+            sessionPermissionService: {},
+            sessionConfigService: {},
+            acpEventProcessor: { getWorkspaceId: vi.fn() },
+            promptTurnCompletionService,
+            retryService: {
+                run: vi.fn(async (operation) => await operation()),
+            },
+            lifecycleEventService,
+            hydrateProviderHistory: vi.fn(),
+            sendSessionMessage: vi.fn(),
+        }));
+        await service.stopAllClients(4321);
+        expect(runtimeManager.beginShutdown).toHaveBeenCalledOnce();
+        expect(lifecycleEventService.record).toHaveBeenCalledTimes(2);
+        expect(lifecycleEventService.record).toHaveBeenCalledWith(expect.objectContaining({
+            sessionId: 'session-active',
+            reason: 'SYSTEM_STOP',
+        }));
+        expect(lifecycleEventService.record).not.toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'session-browse-only' }));
+        expect(lifecycleEventService.record).toHaveBeenCalledWith(expect.objectContaining({
+            sessionId: 'session-pending',
+            reason: 'SYSTEM_STOP',
+        }));
+        expect(runtimeManager.beginShutdown.mock.invocationCallOrder[0]).toBeLessThan(lifecycleEventService.record.mock.invocationCallOrder[0]);
+        expect(lifecycleEventService.record.mock.invocationCallOrder.at(-1)).toBeLessThan(runtimeManager.stopAllClients.mock.invocationCallOrder[0]);
+        expect(runtimeManager.stopAllClients).toHaveBeenCalledWith(4321);
+    });
+    it('continues runtime shutdown when lifecycle recording stalls', async () => {
+        vi.useFakeTimers();
+        try {
+            const runtimeManager = {
+                beginShutdown: vi.fn(() => ['session-active']),
+                stopAllClients: vi.fn(async () => undefined),
+                isStopInProgress: vi.fn(() => false),
+                isBrowseOnlySession: vi.fn(() => false),
+            };
+            const service = new SessionLifecycleService(unsafeCoerce({
+                repository: {
+                    getSessionById: vi.fn(async () => ({
+                        id: 'session-active',
+                        workspaceId: 'workspace-1',
+                        workflow: 'code',
+                    })),
+                },
+                promptBuilder: {},
+                runtimeManager,
+                sessionDomainService: {},
+                sessionPermissionService: {},
+                sessionConfigService: {},
+                acpEventProcessor: { getWorkspaceId: vi.fn() },
+                promptTurnCompletionService: { clearAll: vi.fn() },
+                retryService: {
+                    run: vi.fn(async (operation) => await operation()),
+                },
+                lifecycleEventService: {
+                    record: vi.fn(() => new Promise(() => undefined)),
+                    hydrate: vi.fn(async () => undefined),
+                },
+                hydrateProviderHistory: vi.fn(),
+                sendSessionMessage: vi.fn(),
+            }));
+            const shutdown = service.stopAllClients(4321);
+            await vi.advanceTimersByTimeAsync(999);
+            expect(runtimeManager.stopAllClients).not.toHaveBeenCalled();
+            await vi.advanceTimersByTimeAsync(1);
+            await shutdown;
+            expect(runtimeManager.stopAllClients).toHaveBeenCalledWith(4321);
+        }
+        finally {
+            vi.useRealTimers();
+        }
     });
 });
 describe('SessionLifecycleService pending workspace notifications', () => {
@@ -196,7 +552,7 @@ describe('SessionLifecycleService pending workspace notifications', () => {
         await vi.waitFor(() => {
             expect(workspaceNotificationService.listPendingForDelivery).toHaveBeenCalledWith('workspace-1');
         });
-        service.stopGenerations.set('session-1', 1);
+        getStopGenerations(service).set('session-1', service.getStopGeneration('session-1') + 1);
         resolvePending([
             {
                 id: 'notif-parent',
@@ -624,8 +980,8 @@ function createStartableLifecycleService(options) {
         id: 'session-1',
         workspaceId: 'workspace-1',
         workflow: 'code',
-        provider: 'CLAUDE',
-        providerSessionId: null,
+        provider: options?.provider ?? 'CLAUDE',
+        providerSessionId: options?.providerSessionId ?? null,
         providerMetadata: null,
         model: 'claude-sonnet',
     };
@@ -634,7 +990,7 @@ function createStartableLifecycleService(options) {
         name: 'Workspace',
         description: null,
         projectId: 'project-1',
-        worktreePath: '/tmp/workspace',
+        worktreePath: options?.worktreePath === undefined ? '/tmp/workspace' : options.worktreePath,
         branchName: 'feature/test',
         isAutoGeneratedBranch: false,
         hasHadSessions: false,
@@ -643,17 +999,23 @@ function createStartableLifecycleService(options) {
         creationMetadata: null,
     };
     const handle = {
-        provider: 'CLAUDE',
-        providerSessionId: 'provider-session-1',
+        provider: options?.provider ?? 'CLAUDE',
+        providerSessionId: options?.providerSessionId ?? 'provider-session-1',
         configOptions: [],
         isPromptInFlight: false,
+        getSubagentBrowseCapability: vi.fn(() => ({
+            version: 1,
+            list: true,
+            read: true,
+            notifications: true,
+        })),
     };
     const repository = {
         getSessionById: vi.fn(async () => session),
         getWorkspaceById: vi.fn(async () => workspace),
         getProjectById: vi.fn(),
         markWorkspaceHasHadSessions: vi.fn(async () => undefined),
-        updateSession: vi.fn(async () => undefined),
+        updateSession: vi.fn(async () => session),
         updateSessionIfStatus: vi.fn(async () => null),
     };
     const promptBuilder = {
@@ -667,8 +1029,12 @@ function createStartableLifecycleService(options) {
     const runtimeManager = {
         isStopInProgress: vi.fn(() => false),
         isSessionRunning: vi.fn(() => false),
+        isBrowseOnlySession: vi.fn(() => false),
         getClient: vi.fn(() => undefined),
-        getOrCreateClient: vi.fn(async () => handle),
+        getBrowseClient: vi.fn(() => undefined),
+        getPendingClient: vi.fn(() => undefined),
+        getSubagentBrowseCapability: vi.fn(() => null),
+        getOrCreateClient: vi.fn(async (_sessionId, _options) => handle),
         stopClient: vi.fn(async () => undefined),
         isSessionWorking: vi.fn(() => false),
     };
@@ -685,6 +1051,7 @@ function createStartableLifecycleService(options) {
         })),
         clearQueuedWork: vi.fn(),
         clearSession: vi.fn(),
+        markProcessExit: vi.fn(),
     };
     const sessionConfigService = {
         applyConfiguredReasoningEffort: vi.fn(async () => undefined),
@@ -718,6 +1085,7 @@ function createStartableLifecycleService(options) {
             run: vi.fn(async (operation) => await operation()),
         },
         sendSessionMessage,
+        lifecycleEventService: { hydrate: vi.fn(async () => undefined), record: vi.fn() },
     });
     service.configure({
         workspace: {
@@ -728,19 +1096,267 @@ function createStartableLifecycleService(options) {
         },
         messageQueue: { tryDispatchNextMessage },
     });
-    service.deliverPendingChildNotifications = vi.fn(async () => options?.pendingNotificationCount ?? 0);
+    const deliverPendingChildNotifications = vi.fn(async () => options?.pendingNotificationCount ?? 0);
+    service.deliverPendingChildNotifications = deliverPendingChildNotifications;
     return {
         service,
+        session,
+        handle,
+        repository,
         sendSessionMessage,
         tryDispatchNextMessage,
         sessionConfigService,
         runtimeManager,
+        sessionDomainService,
+        acpEventProcessor,
+        deliverPendingChildNotifications,
     };
 }
 describe('SessionLifecycleService startSession pending workspace notifications', () => {
     beforeEach(() => {
         vi.clearAllMocks();
     });
+    it('restores a stopped Codex session for browsing without activating it', async () => {
+        const { service, repository, runtimeManager, handle, sessionDomainService, deliverPendingChildNotifications, } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+            pendingNotificationCount: 2,
+        });
+        runtimeManager.getOrCreateClient.mockImplementationOnce((_id, options) => {
+            expect(options).toMatchObject({
+                purpose: 'browse',
+                resumeProviderSessionId: 'provider-session-existing',
+            });
+            runtimeManager.getSubagentBrowseCapability.mockReturnValue({
+                version: 1,
+                list: true,
+                read: true,
+                notifications: true,
+            });
+            return Promise.resolve(handle);
+        });
+        await expect(service.ensureSubagentBrowseSession('session-1')).resolves.toBe(true);
+        expect(repository.markWorkspaceHasHadSessions).not.toHaveBeenCalled();
+        expect(repository.updateSession).not.toHaveBeenCalledWith('session-1', expect.objectContaining({ status: SessionStatus.RUNNING }));
+        expect(deliverPendingChildNotifications).not.toHaveBeenCalled();
+        expect(sessionDomainService.setRuntimeSnapshot).not.toHaveBeenCalled();
+    });
+    it('does not spawn a browse client without a stored provider session', async () => {
+        const { service, runtimeManager } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: null,
+        });
+        await expect(service.ensureSubagentBrowseSession('session-1')).resolves.toBe(false);
+        expect(runtimeManager.getOrCreateClient).not.toHaveBeenCalled();
+    });
+    it('returns unsupported when the stopped session has no usable worktree', async () => {
+        const { service, runtimeManager } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+            worktreePath: null,
+        });
+        await expect(service.ensureSubagentBrowseSession('session-1')).resolves.toBe(false);
+        expect(runtimeManager.getOrCreateClient).not.toHaveBeenCalled();
+    });
+    it('returns unsupported when the provider cannot restore the stored session', async () => {
+        const { service, runtimeManager } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        runtimeManager.getOrCreateClient.mockRejectedValueOnce(new AcpBrowseSessionUnavailableError('loadSession unsupported'));
+        await expect(service.ensureSubagentBrowseSession('session-1')).resolves.toBe(false);
+    });
+    it('stops a browse-only client when the provider lacks sub-agent browsing', async () => {
+        const { service, runtimeManager, acpEventProcessor } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        runtimeManager.isBrowseOnlySession.mockReturnValue(true);
+        await expect(service.ensureSubagentBrowseSession('session-1')).resolves.toBe(false);
+        expect(runtimeManager.stopClient).toHaveBeenCalledWith('session-1');
+        expect(acpEventProcessor.clearSessionState).toHaveBeenCalledWith('session-1');
+    });
+    it('cancels an active startup that began before unsupported browse cleanup', async () => {
+        const { service, session, repository, runtimeManager } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        const activeSessionLookup = createDeferred();
+        const browseStop = createDeferred();
+        repository.getSessionById.mockReturnValueOnce(activeSessionLookup.promise);
+        runtimeManager.isBrowseOnlySession.mockReturnValue(true);
+        runtimeManager.stopClient.mockReturnValueOnce(browseStop.promise);
+        const activeStartup = service.getOrCreateSessionClient('session-1');
+        await vi.waitFor(() => {
+            expect(repository.getSessionById).toHaveBeenCalledTimes(1);
+        });
+        const browseResult = service.ensureSubagentBrowseSession('session-1');
+        await vi.waitFor(() => {
+            expect(runtimeManager.stopClient).toHaveBeenCalledWith('session-1');
+        });
+        activeSessionLookup.resolve(session);
+        await expect(activeStartup).rejects.toThrow();
+        browseStop.resolve(undefined);
+        await expect(browseResult).resolves.toBe(false);
+        expect(runtimeManager.getOrCreateClient).toHaveBeenCalledTimes(1);
+    });
+    it('returns unsupported when concurrent browse cleanup invalidates its startup', async () => {
+        const { service, session, repository, runtimeManager } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        const firstSessionLookup = createDeferred();
+        const secondSessionLookup = createDeferred();
+        const browseStop = createDeferred();
+        repository.getSessionById
+            .mockReturnValueOnce(firstSessionLookup.promise)
+            .mockReturnValueOnce(secondSessionLookup.promise);
+        runtimeManager.isBrowseOnlySession.mockReturnValue(true);
+        runtimeManager.stopClient.mockReturnValueOnce(browseStop.promise);
+        const firstBrowse = service.ensureSubagentBrowseSession('session-1');
+        const secondBrowse = service.ensureSubagentBrowseSession('session-1');
+        await vi.waitFor(() => {
+            expect(repository.getSessionById).toHaveBeenCalledTimes(2);
+        });
+        firstSessionLookup.resolve(session);
+        await vi.waitFor(() => {
+            expect(runtimeManager.stopClient).toHaveBeenCalledWith('session-1');
+        });
+        secondSessionLookup.resolve(session);
+        await expect(secondBrowse).resolves.toBe(false);
+        browseStop.resolve(undefined);
+        await expect(firstBrowse).resolves.toBe(false);
+        expect(runtimeManager.getOrCreateClient).toHaveBeenCalledTimes(1);
+    });
+    it('does not let a failed browse creation clear a concurrent active startup context', async () => {
+        const { service, handle, runtimeManager, acpEventProcessor } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        const browseCreation = createDeferred();
+        const activeCreation = createDeferred();
+        runtimeManager.getOrCreateClient
+            .mockReturnValueOnce(browseCreation.promise)
+            .mockReturnValueOnce(activeCreation.promise);
+        const browseResult = service
+            .ensureSubagentBrowseSession('session-1')
+            .catch((error) => error);
+        await vi.waitFor(() => {
+            expect(runtimeManager.getOrCreateClient).toHaveBeenCalledTimes(1);
+        });
+        const activeResult = service.getOrCreateSessionClient('session-1');
+        await vi.waitFor(() => {
+            expect(runtimeManager.getOrCreateClient).toHaveBeenCalledTimes(2);
+        });
+        browseCreation.reject(new Error('browse restore failed'));
+        await expect(browseResult).resolves.toEqual(expect.objectContaining({ message: 'browse restore failed' }));
+        expect(acpEventProcessor.clearSessionState).not.toHaveBeenCalled();
+        activeCreation.resolve(handle);
+        await expect(activeResult).resolves.toBe(handle);
+    });
+    it('omits provider-session persistence from browse-only runtime handlers', () => {
+        const { service } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+        });
+        const handlers = service.setupAcpEventHandler('session-1', { persistProviderSessionId: false });
+        expect(handlers.onSessionId).toBeUndefined();
+    });
+    it('promotes a restored browse client through the normal active startup path', async () => {
+        const { service, repository, runtimeManager, handle, deliverPendingChildNotifications, sessionConfigService, } = createStartableLifecycleService({
+            provider: 'CODEX',
+            providerSessionId: 'provider-session-existing',
+            pendingNotificationCount: 1,
+        });
+        runtimeManager.getOrCreateClient.mockImplementation((_id, options) => {
+            if (options.purpose === 'browse') {
+                runtimeManager.getSubagentBrowseCapability.mockReturnValue({
+                    version: 1,
+                    list: true,
+                    read: true,
+                    notifications: true,
+                });
+            }
+            return Promise.resolve(handle);
+        });
+        await service.ensureSubagentBrowseSession('session-1');
+        await expect(service.getOrCreateSessionClient('session-1')).resolves.toBe(handle);
+        expect(runtimeManager.getOrCreateClient).toHaveBeenCalledTimes(2);
+        expect(runtimeManager.getOrCreateClient.mock.calls[0]?.[1]).toMatchObject({
+            purpose: 'browse',
+        });
+        expect(runtimeManager.getOrCreateClient.mock.calls[1]?.[1].purpose).toBeUndefined();
+        expect(repository.updateSession).toHaveBeenCalledWith('session-1', {
+            status: SessionStatus.RUNNING,
+        });
+        expect(sessionConfigService.applyConfiguredPermissionPreset).toHaveBeenCalledTimes(1);
+        expect(deliverPendingChildNotifications).toHaveBeenCalledTimes(1);
+    });
+    it('does not retain a stop generation for a missing session', async () => {
+        const { service, repository } = createStartableLifecycleService();
+        repository.getSessionById.mockResolvedValueOnce(null);
+        await expect(service.startSession('missing-session')).rejects.toThrow('Session not found: missing-session');
+        expect(getStopGenerations(service).has('missing-session')).toBe(false);
+    });
+    it('does not create a client when stop completes during the initial session lookup', async () => {
+        const { service, session, repository, runtimeManager } = createStartableLifecycleService();
+        let resolveSession;
+        repository.getSessionById.mockReturnValueOnce(new Promise((resolve) => {
+            resolveSession = resolve;
+        }));
+        const startResult = service.startSession('session-1').catch((error) => error);
+        await vi.waitFor(() => {
+            expect(repository.getSessionById).toHaveBeenCalledWith('session-1');
+        });
+        await service.stopSession('session-1');
+        resolveSession(session);
+        await expect(startResult).resolves.toEqual(expect.objectContaining({ message: 'Session is currently being stopped' }));
+        expect(runtimeManager.getOrCreateClient).not.toHaveBeenCalled();
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('releases the stop generation when startup fails before creating a runtime', async () => {
+        const { service, runtimeManager } = createStartableLifecycleService();
+        runtimeManager.getOrCreateClient.mockRejectedValueOnce(new Error('spawn failed'));
+        await expect(service.startSession('session-1')).rejects.toThrow('spawn failed');
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('does not retain a stop generation when client lookup cannot find the session', async () => {
+        const { service, repository } = createStartableLifecycleService();
+        repository.getSessionById.mockResolvedValueOnce(null);
+        await expect(service.getOrCreateSessionClient('missing-session')).rejects.toThrow('Session not found: missing-session');
+        expect(getStopGenerations(service).has('missing-session')).toBe(false);
+    });
+    it('releases the stop generation when record-based client creation fails', async () => {
+        const { service, session, runtimeManager } = createStartableLifecycleService();
+        runtimeManager.getOrCreateClient.mockRejectedValueOnce(new Error('spawn failed'));
+        await expect(service.getOrCreateSessionClientFromRecord(session)).rejects.toThrow('spawn failed');
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('does not release a stop generation still owned by a concurrent startup', async () => {
+        let resolveFirstSettings;
+        const firstSettings = new Promise((resolve) => {
+            resolveFirstSettings = resolve;
+        });
+        vi.mocked(userSettingsService.get)
+            .mockReturnValueOnce(firstSettings)
+            .mockResolvedValueOnce(unsafeCoerce({
+            defaultWorkspacePermissions: 'STRICT',
+            ratchetPermissions: 'YOLO',
+        }));
+        const { service, runtimeManager } = createStartableLifecycleService();
+        const firstStart = service.startSession('session-1');
+        await vi.waitFor(() => {
+            expect(userSettingsService.get).toHaveBeenCalledTimes(1);
+        });
+        runtimeManager.getOrCreateClient.mockRejectedValueOnce(new Error('second spawn failed'));
+        await expect(service.startSession('session-1')).rejects.toThrow('second spawn failed');
+        resolveFirstSettings(unsafeCoerce({
+            defaultWorkspacePermissions: 'STRICT',
+            ratchetPermissions: 'YOLO',
+        }));
+        await expect(firstStart).resolves.toBeUndefined();
+        expect(getStopGenerations(service).has('session-1')).toBe(true);
+    });
     it('dispatches queued notifications after startup presets and skips the default continue prompt', async () => {
         const { service, sendSessionMessage, tryDispatchNextMessage, sessionConfigService } = createStartableLifecycleService({ pendingNotificationCount: 2 });
         await service.startSession('session-1');
@@ -768,6 +1384,22 @@ describe('SessionLifecycleService startSession pending workspace notifications',
         expect(sendOrder).toBeDefined();
         expect(dispatchOrder).toBeLessThan(sendOrder);
     });
+    it('does not complete startup when stop finishes during the initial prompt', async () => {
+        let resolvePrompt;
+        const pendingPrompt = new Promise((resolve) => {
+            resolvePrompt = resolve;
+        });
+        const { service, sendSessionMessage } = createStartableLifecycleService();
+        sendSessionMessage.mockReturnValueOnce(pendingPrompt);
+        const startResult = service.startSession('session-1').catch((error) => error);
+        await vi.waitFor(() => {
+            expect(sendSessionMessage).toHaveBeenCalledWith('session-1', 'Continue with the task.');
+        });
+        await service.stopSession('session-1');
+        resolvePrompt(undefined);
+        await expect(startResult).resolves.toEqual(expect.objectContaining({ message: 'Session is currently being stopped' }));
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
     it('does not create a client after stop completes during permission resolution', async () => {
         let resolveSettings;
         const pendingSettings = new Promise((resolve) => {
@@ -780,6 +1412,7 @@ describe('SessionLifecycleService startSession pending workspace notifications',
             expect(userSettingsService.get).toHaveBeenCalled();
         });
         await service.stopSession('session-1');
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
         resolveSettings(unsafeCoerce({
             defaultWorkspacePermissions: 'STRICT',
             ratchetPermissions: 'YOLO',
@@ -787,6 +1420,42 @@ describe('SessionLifecycleService startSession pending workspace notifications',
         await expect(startResult).resolves.toEqual(expect.objectContaining({ message: 'Session is currently being stopped' }));
         expect(runtimeManager.getOrCreateClient).not.toHaveBeenCalled();
         expect(sendSessionMessage).not.toHaveBeenCalled();
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('releases the stop generation after a session stops', async () => {
+        const { service } = createStartableLifecycleService();
+        await service.stopSession('session-1');
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('releases the stop generation when viewers retain inactive session state', async () => {
+        const { service, sessionDomainService } = createStartableLifecycleService();
+        sessionEventBus.registerViewerCountProvider((sessionId) => (sessionId === 'session-1' ? 1 : 0));
+        try {
+            await service.stopSession('session-1');
+        }
+        finally {
+            sessionEventBus.registerViewerCountProvider(null);
+        }
+        expect(sessionDomainService.clearSession).not.toHaveBeenCalled();
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+    });
+    it('does not clear a restarted generation when an old runtime exit finishes', async () => {
+        const { service, session, repository } = createStartableLifecycleService();
+        let resolveUpdate;
+        repository.updateSession.mockReturnValueOnce(new Promise((resolve) => {
+            resolveUpdate = resolve;
+        }));
+        const oldGeneration = service.getStopGeneration('session-1');
+        const handlers = service.setupAcpEventHandler('session-1');
+        const exitPromise = handlers.onExit('session-1', 0);
+        expect(getStopGenerations(service).has('session-1')).toBe(false);
+        await service.startSession('session-1');
+        const restartedGeneration = service.getStopGeneration('session-1');
+        expect(restartedGeneration).not.toBe(oldGeneration);
+        resolveUpdate(session);
+        await exitPromise;
+        expect(service.isStopGenerationCurrent('session-1', restartedGeneration)).toBe(true);
+        expect(service.isStopGenerationCurrent('session-1', oldGeneration)).toBe(false);
     });
     it('waits for a registered client creation and stops the resulting runtime', async () => {
         const { service, sendSessionMessage, runtimeManager } = createStartableLifecycleService();