factory-factory 0.3.21 → 0.4.1

package/dist/src/backend/server.upgrade.test.js

@@ -1,77 +1,45 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer as createNetServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import request from 'supertest';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { prisma } from '../backend/db.js';
-import { startInterceptors, stopInterceptors } from '../backend/interceptors/index.js';
-import { configureDomainBridges } from '../backend/orchestration/domain-bridges.orchestrator.js';
-import { configureEventCollector, stopEventCollector, } from '../backend/orchestration/event-collector.orchestrator.js';
-import { configureSnapshotReconciliation, snapshotReconciliationService, } from '../backend/orchestration/snapshot-reconciliation.orchestrator.js';
-import { recoverStaleArchivingWorkspaces } from '../backend/orchestration/workspace-archive.orchestrator.js';
-import { reconciliationService } from '../backend/services/ratchet/index.js';
-import { runScriptStateMachine } from '../backend/services/run-script/index.js';
+import { WebSocket } from 'ws';
 import { unsafeCoerce } from '../test-utils/unsafe-coerce.js';
-const handlers = vi.hoisted(() => ({
-    chat: vi.fn(),
-    terminal: vi.fn(),
-    setupTerminal: vi.fn(),
-    devLogs: vi.fn(),
-    postRunLogs: vi.fn(),
-    snapshots: vi.fn(),
-}));
-vi.mock('@/backend/routers/websocket', () => ({
-    createChatUpgradeHandler: vi.fn(() => handlers.chat),
-    createTerminalUpgradeHandler: vi.fn(() => handlers.terminal),
-    createSetupTerminalUpgradeHandler: vi.fn(() => handlers.setupTerminal),
-    createDevLogsUpgradeHandler: vi.fn(() => handlers.devLogs),
-    createPostRunLogsUpgradeHandler: vi.fn(() => handlers.postRunLogs),
-    createSnapshotsUpgradeHandler: vi.fn(() => handlers.snapshots),
-}));
-vi.mock('@/backend/orchestration/domain-bridges.orchestrator', () => ({
-    configureDomainBridges: vi.fn(),
-}));
-vi.mock('@/backend/orchestration/event-collector.orchestrator', () => ({
-    configureEventCollector: vi.fn(),
-    stopEventCollector: vi.fn(),
-}));
-vi.mock('@/backend/orchestration/snapshot-reconciliation.orchestrator', () => ({
-    configureSnapshotReconciliation: vi.fn(),
-    snapshotReconciliationService: {
-        stop: vi.fn(async () => undefined),
-    },
-}));
-vi.mock('@/backend/orchestration/workspace-archive.orchestrator', () => ({
-    recoverStaleArchivingWorkspaces: vi.fn(async () => ({ archived: [], failed: [] })),
-}));
-vi.mock('@/backend/services/ratchet', async (importOriginal) => {
-    const actual = await importOriginal();
-    return {
-        ...actual,
-        reconciliationService: {
-            cleanupOrphans: vi.fn(async () => undefined),
-            reconcile: vi.fn(async () => undefined),
-            startPeriodicCleanup: vi.fn(),
-            stopPeriodicCleanup: vi.fn(async () => undefined),
-        },
+const { handlers, handlerFactories, transportDisposers } = vi.hoisted(() => {
+    const upgradeHandlers = {
+        chat: vi.fn(),
+        terminal: vi.fn(),
+        setupTerminal: vi.fn(),
+        devLogs: vi.fn(),
+        postRunLogs: vi.fn(),
+        snapshots: vi.fn(),
     };
-});
-vi.mock('@/backend/services/run-script', async (importOriginal) => {
-    const actual = await importOriginal();
     return {
-        ...actual,
-        runScriptStateMachine: {
-            ...actual.runScriptStateMachine,
-            removeAllListeners: vi.fn(),
-            on: vi.fn(),
-            recoverStaleStates: vi.fn(async () => undefined),
+        handlers: upgradeHandlers,
+        handlerFactories: {
+            chat: vi.fn(() => upgradeHandlers.chat),
+            terminal: vi.fn(() => upgradeHandlers.terminal),
+            setupTerminal: vi.fn(() => upgradeHandlers.setupTerminal),
+            devLogs: vi.fn(() => upgradeHandlers.devLogs),
+            postRunLogs: vi.fn(() => upgradeHandlers.postRunLogs),
+            snapshots: vi.fn(() => upgradeHandlers.snapshots),
+        },
+        transportDisposers: {
+            chat: vi.fn(),
+            snapshots: vi.fn(),
         },
     };
 });
-vi.mock('@/backend/interceptors', () => ({
-    registerInterceptors: vi.fn(),
-    startInterceptors: vi.fn(async () => undefined),
-    stopInterceptors: vi.fn(async () => undefined),
+vi.mock('@/backend/routers/websocket', () => ({
+    createChatUpgradeHandler: handlerFactories.chat,
+    createTerminalUpgradeHandler: handlerFactories.terminal,
+    createSetupTerminalUpgradeHandler: handlerFactories.setupTerminal,
+    createDevLogsUpgradeHandler: handlerFactories.devLogs,
+    createPostRunLogsUpgradeHandler: handlerFactories.postRunLogs,
+    createSnapshotsUpgradeHandler: handlerFactories.snapshots,
+    disposeChatTransportForApplication: transportDisposers.chat,
+    disposeSnapshotsHandlerState: transportDisposers.snapshots,
 }));
 vi.mock('@/backend/trpc/index', () => ({
     appRouter: {},
@@ -80,11 +48,6 @@ vi.mock('@/backend/trpc/index', () => ({
 vi.mock('@trpc/server/adapters/express', () => ({
     createExpressMiddleware: vi.fn(() => (_req, _res, next) => next()),
 }));
-vi.mock('@/backend/db', () => ({
-    prisma: {
-        $disconnect: vi.fn(async () => undefined),
-    },
-}));
 import { createServer } from './server.js';
 function createTestHarness(options = {}) {
     const logger = {
@@ -93,7 +56,6 @@ function createTestHarness(options = {}) {
         info: vi.fn(),
         warn: vi.fn(),
     };
-    const requestedPortResult = options.requestedPortResult ?? 0;
     const services = {
         configService: {
             getBackendPort: () => 0,
@@ -108,7 +70,7 @@ function createTestHarness(options = {}) {
             getDatabasePathFromEnv: () => undefined,
         },
         createLogger: () => logger,
-        findAvailablePort: vi.fn(async () => requestedPortResult),
+        findAvailablePort: vi.fn(async (startPort) => startPort),
         ratchetService: {
             start: vi.fn(),
             stop: vi.fn(async () => undefined),
@@ -125,6 +87,19 @@ function createTestHarness(options = {}) {
             start: vi.fn(),
             stop: vi.fn(async () => undefined),
         },
+        periodicTaskService: {
+            start: vi.fn(),
+            stop: vi.fn(async () => undefined),
+        },
+        reconciliationService: {
+            cleanupOrphans: vi.fn(async () => undefined),
+            reconcile: vi.fn(async () => undefined),
+            startPeriodicCleanup: vi.fn(),
+            stopPeriodicCleanup: vi.fn(async () => undefined),
+        },
+        runScriptStateMachine: {
+            recoverStaleStates: vi.fn(async () => undefined),
+        },
         acpTraceLogger: {
             cleanup: vi.fn(),
             cleanupOldLogs: vi.fn(),
@@ -140,21 +115,111 @@ function createTestHarness(options = {}) {
         terminalService: {
             cleanup: vi.fn(),
         },
+        workspaceAccessor: {
+            resetStaleAutoIterationStatuses: vi.fn(async () => []),
+        },
+        workspaceGitStateService: {
+            stop: vi.fn(),
+        },
+    };
+    const lifecycle = {
+        database: {
+            $disconnect: vi.fn(async () => undefined),
+        },
+        interceptors: {
+            register: vi.fn(),
+            start: vi.fn(async () => undefined),
+            stop: vi.fn(async () => undefined),
+        },
+        wireDomainBridges: vi.fn(),
+        eventCollector: {
+            configure: vi.fn(),
+            stop: vi.fn(),
+        },
+        snapshotReconciliation: {
+            configure: vi.fn(),
+            start: vi.fn(),
+            stop: vi.fn(async () => undefined),
+        },
+        recoverStaleArchivingWorkspaces: vi.fn(async () => ({ archived: [], failed: [] })),
     };
+    const application = unsafeCoerce({ services, lifecycle, config: {} });
     return {
-        context: unsafeCoerce({ services }),
+        application,
+        lifecycle,
         logger,
         services,
     };
 }
-function createTestAppContext(options = {}) {
-    return createTestHarness(options).context;
+function createTestApplication(options = {}) {
+    return createTestHarness(options).application;
+}
+async function occupyPort(port = 0) {
+    const server = createNetServer();
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        throw new Error('Expected occupied TCP server to have a numeric port');
+    }
+    return { port: address.port, server };
+}
+async function closeNetServer(server) {
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+async function waitForHttpServerToListen(server) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        if (server.getHttpServer().listening) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error('Expected HTTP server to start listening');
+}
+async function occupyConsecutivePorts(count) {
+    for (let attempt = 0; attempt < 50; attempt++) {
+        const servers = [];
+        try {
+            const first = await occupyPort();
+            const startPort = first.port;
+            servers.push(first.server);
+            if (startPort + count - 1 > 65_535) {
+                await Promise.allSettled(servers.map(closeNetServer));
+                continue;
+            }
+            for (let offset = 1; offset < count; offset++) {
+                const occupied = await occupyPort(startPort + offset);
+                servers.push(occupied.server);
+            }
+            return { startPort, servers };
+        }
+        catch (error) {
+            await Promise.allSettled(servers.map(closeNetServer));
+            if (attempt === 49) {
+                throw error;
+            }
+        }
+    }
+    throw new Error('Could not occupy a consecutive TCP port range');
 }
 describe('server websocket upgrade routing', () => {
     const servers = [];
     const tempDirs = [];
-    const createTestServer = (appContext = createTestAppContext(), requestedPort) => {
-        const server = createServer(requestedPort, appContext);
+    const createTestServer = (application = createTestApplication(), requestedPort) => {
+        const server = createServer(application, requestedPort);
         servers.push(server);
         return server;
     };
@@ -194,6 +259,16 @@ describe('server websocket upgrade routing', () => {
         expect(handlers.devLogs).not.toHaveBeenCalled();
         expect(handlers.snapshots).not.toHaveBeenCalled();
     });
+    it('supplies the exact application graph to every upgrade handler factory', () => {
+        const application = createTestApplication();
+        createTestServer(application);
+        expect(handlerFactories.chat).toHaveBeenCalledWith(application);
+        expect(handlerFactories.terminal).toHaveBeenCalledWith(application);
+        expect(handlerFactories.setupTerminal).toHaveBeenCalledWith(application);
+        expect(handlerFactories.devLogs).toHaveBeenCalledWith(application);
+        expect(handlerFactories.postRunLogs).toHaveBeenCalledWith(application);
+        expect(handlerFactories.snapshots).toHaveBeenCalledWith(application);
+    });
     it('routes /terminal upgrades to terminal handler', () => {
         const server = createTestServer();
         const request = {
@@ -285,60 +360,61 @@ describe('server websocket upgrade routing', () => {
         expect(handlers.devLogs).not.toHaveBeenCalled();
         expect(handlers.snapshots).not.toHaveBeenCalled();
     });
-    it('starts server and wires startup services', async () => {
-        const harness = createTestHarness({
-            requestedPortResult: 0,
-        });
-        const server = createTestServer(harness.context, 47_891);
+    it('starts an already-composed application without rewiring dependencies', async () => {
+        const { application, lifecycle } = createTestHarness();
+        const server = createTestServer(application, 0);
         const endpoint = await server.start();
         expect(endpoint).toBe('http://localhost:0');
         expect(server.getPort()).toBe(0);
-        expect(harness.services.findAvailablePort).toHaveBeenCalledWith(47_891);
-        expect(harness.logger.warn).toHaveBeenCalledOnce();
-        expect(configureDomainBridges).toHaveBeenCalledWith(harness.context.services);
-        expect(configureEventCollector).toHaveBeenCalledWith(harness.context.services);
-        expect(configureSnapshotReconciliation).toHaveBeenCalledWith(harness.context.services);
-        expect(reconciliationService.cleanupOrphans).toHaveBeenCalledOnce();
-        expect(harness.services.sessionService.recoverStaleSessionStates).toHaveBeenCalledOnce();
-        expect(reconciliationService.reconcile).toHaveBeenCalledOnce();
-        expect(runScriptStateMachine.recoverStaleStates).toHaveBeenCalledOnce();
-        expect(recoverStaleArchivingWorkspaces).toHaveBeenCalledWith(harness.context.services);
-        const runScriptRecoveryOrder = vi.mocked(runScriptStateMachine.recoverStaleStates).mock
-            .invocationCallOrder[0];
-        const archiveRecoveryOrder = vi.mocked(recoverStaleArchivingWorkspaces).mock
-            .invocationCallOrder[0];
-        const snapshotReconciliationOrder = vi.mocked(configureSnapshotReconciliation).mock
-            .invocationCallOrder[0];
-        expect(runScriptRecoveryOrder).toBeDefined();
-        expect(archiveRecoveryOrder).toBeDefined();
-        expect(snapshotReconciliationOrder).toBeDefined();
-        expect(runScriptRecoveryOrder ?? 0).toBeLessThan(archiveRecoveryOrder ?? 0);
-        expect(archiveRecoveryOrder ?? 0).toBeLessThan(snapshotReconciliationOrder ?? 0);
-        expect(startInterceptors).toHaveBeenCalledOnce();
-        expect(reconciliationService.startPeriodicCleanup).toHaveBeenCalledOnce();
-        expect(harness.services.rateLimiter.start).toHaveBeenCalledOnce();
-        expect(harness.services.schedulerService.start).toHaveBeenCalledOnce();
-        expect(harness.services.ratchetService.start).toHaveBeenCalledOnce();
+        expect(lifecycle.wireDomainBridges).not.toHaveBeenCalled();
+        expect(lifecycle.eventCollector.configure).not.toHaveBeenCalled();
+        expect(lifecycle.snapshotReconciliation.configure).not.toHaveBeenCalled();
+        expect(lifecycle.snapshotReconciliation.start).toHaveBeenCalledOnce();
+    });
+    it('rejects concurrent start calls without running startup cleanup', async () => {
+        const harness = createTestHarness();
+        let reconciliationStarted;
+        let continueReconciliation;
+        const reconciliationStartedPromise = new Promise((resolve) => {
+            reconciliationStarted = resolve;
+        });
+        const continueReconciliationPromise = new Promise((resolve) => {
+            continueReconciliation = resolve;
+        });
+        vi.mocked(harness.services.reconciliationService.cleanupOrphans).mockImplementationOnce(async () => {
+            reconciliationStarted();
+            await continueReconciliationPromise;
+        });
+        const server = createTestServer(harness.application, 0);
+        const startPromise = server.start();
+        await reconciliationStartedPromise;
+        await expect(server.start()).rejects.toThrow('Server startup has already been initiated');
+        expect(harness.lifecycle.interceptors.stop).not.toHaveBeenCalled();
+        expect(harness.services.sessionService.stopAllClients).not.toHaveBeenCalled();
+        expect(harness.services.schedulerService.stop).not.toHaveBeenCalled();
+        expect(harness.lifecycle.database.$disconnect).not.toHaveBeenCalled();
+        continueReconciliation();
+        await expect(startPromise).resolves.toBe('http://localhost:0');
+        expect(server.getHttpServer().listening).toBe(true);
     });
     it('writes backend port to stdout when run script proxy mode is enabled', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         const harness = createTestHarness({
             isRunScriptProxyEnabled: true,
-            requestedPortResult: 0,
         });
-        const server = createTestServer(harness.context, 0);
+        const server = createTestServer(harness.application, 0);
         await server.start();
         expect(writeSpy).toHaveBeenCalledWith('BACKEND_PORT:0\n');
         writeSpy.mockRestore();
     });
     it('logs startup reconciliation failures and continues starting', async () => {
-        const harness = createTestHarness({ requestedPortResult: 0 });
-        vi.mocked(reconciliationService.cleanupOrphans).mockRejectedValueOnce(new Error('cleanup failed'));
+        const harness = createTestHarness();
+        vi.mocked(harness.services.reconciliationService.cleanupOrphans).mockRejectedValueOnce(new Error('cleanup failed'));
         vi.mocked(harness.services.sessionService.recoverStaleSessionStates).mockRejectedValueOnce(new Error('session recovery failed'));
-        vi.mocked(reconciliationService.reconcile).mockRejectedValueOnce(new Error('reconcile failed'));
-        vi.mocked(runScriptStateMachine.recoverStaleStates).mockRejectedValueOnce(new Error('run script recovery failed'));
-        vi.mocked(recoverStaleArchivingWorkspaces).mockRejectedValueOnce(new Error('archive recovery failed'));
-        const server = createTestServer(harness.context, 0);
+        vi.mocked(harness.services.reconciliationService.reconcile).mockRejectedValueOnce(new Error('reconcile failed'));
+        vi.mocked(harness.services.runScriptStateMachine.recoverStaleStates).mockRejectedValueOnce(new Error('run script recovery failed'));
+        vi.mocked(harness.lifecycle.recoverStaleArchivingWorkspaces).mockRejectedValueOnce(new Error('archive recovery failed'));
+        const server = createTestServer(harness.application, 0);
         await expect(server.start()).resolves.toBe('http://localhost:0');
         expect(harness.logger.error).toHaveBeenCalledWith('Failed to cleanup orphan sessions on startup', expect.any(Object));
         expect(harness.logger.error).toHaveBeenCalledWith('Failed to recover stale agent sessions on startup', expect.any(Object));
@@ -346,38 +422,195 @@ describe('server websocket upgrade routing', () => {
         expect(harness.logger.error).toHaveBeenCalledWith('Failed to recover stale run script states on startup', expect.any(Object));
         expect(harness.logger.error).toHaveBeenCalledWith('Failed to recover stale archiving workspaces on startup', expect.any(Object));
     });
+    it('gates HTTP requests and websocket upgrades while startup reconciliation is pending', async () => {
+        const harness = createTestHarness();
+        let reconciliationStarted;
+        let continueReconciliation;
+        const reconciliationStartedPromise = new Promise((resolve) => {
+            reconciliationStarted = resolve;
+        });
+        const continueReconciliationPromise = new Promise((resolve) => {
+            continueReconciliation = resolve;
+        });
+        vi.mocked(harness.services.reconciliationService.cleanupOrphans).mockImplementationOnce(async () => {
+            reconciliationStarted();
+            await continueReconciliationPromise;
+        });
+        const server = createTestServer(harness.application, 0);
+        const startPromise = server.start();
+        await reconciliationStartedPromise;
+        await waitForHttpServerToListen(server);
+        const response = await request(server.getHttpServer()).get('/health');
+        const socket = {
+            destroy: vi.fn(),
+            write: vi.fn(),
+        };
+        const upgradeRequest = {
+            headers: { host: 'localhost:3001' },
+            url: '/chat?sessionId=s1',
+        };
+        server.getHttpServer().emit('upgrade', upgradeRequest, socket, Buffer.alloc(0));
+        expect(response.status).toBe(503);
+        expect(response.body).toMatchObject({ error: 'Service starting' });
+        expect(socket.write).toHaveBeenCalledWith(expect.stringContaining('503 Service Unavailable'));
+        expect(socket.destroy).toHaveBeenCalledOnce();
+        expect(handlers.chat).not.toHaveBeenCalled();
+        continueReconciliation();
+        await expect(startPromise).resolves.toBe('http://localhost:0');
+        const readyResponse = await request(server.getHttpServer()).get('/health');
+        expect(readyResponse.status).toBe(200);
+    });
+    it('retries the next port when the requested port is already bound', async () => {
+        const { startPort, servers: occupiedServers } = await occupyConsecutivePorts(2);
+        const requestedPortReservation = occupiedServers[0];
+        const nextPortReservation = occupiedServers[1];
+        if (!(requestedPortReservation && nextPortReservation)) {
+            throw new Error('Expected two occupied TCP port reservations');
+        }
+        await closeNetServer(nextPortReservation);
+        try {
+            const harness = createTestHarness({ backendHost: '127.0.0.1' });
+            const server = createTestServer(harness.application, startPort);
+            await expect(server.start()).resolves.toBe(`http://127.0.0.1:${startPort + 1}`);
+            expect(server.getPort()).toBe(startPort + 1);
+            expect(harness.services.findAvailablePort).not.toHaveBeenCalled();
+            expect(harness.logger.warn).toHaveBeenCalledWith('Requested port in use, using alternative', {
+                requestedPort: startPort,
+                actualPort: startPort + 1,
+            });
+            expect(harness.services.reconciliationService.cleanupOrphans).toHaveBeenCalledOnce();
+            expect(harness.lifecycle.interceptors.start).toHaveBeenCalledOnce();
+        }
+        finally {
+            await closeNetServer(requestedPortReservation);
+        }
+    });
+    it('rejects startup after all bind fallback ports are already bound', async () => {
+        const { startPort, servers: occupiedServers } = await occupyConsecutivePorts(10);
+        try {
+            const harness = createTestHarness({ backendHost: '127.0.0.1' });
+            const server = createTestServer(harness.application, startPort);
+            await expect(server.start()).rejects.toThrow(`Could not bind server to an available port starting from ${startPort}`);
+            expect(harness.services.findAvailablePort).not.toHaveBeenCalled();
+            expect(harness.lifecycle.snapshotReconciliation.start).not.toHaveBeenCalled();
+            expect(harness.lifecycle.interceptors.start).not.toHaveBeenCalled();
+        }
+        finally {
+            await Promise.all(occupiedServers.map(closeNetServer));
+        }
+    });
     it('rejects start when http server emits an error', async () => {
-        const harness = createTestHarness({ requestedPortResult: 0 });
-        const server = createTestServer(harness.context, 0);
+        const harness = createTestHarness();
+        const server = createTestServer(harness.application, 0);
         const httpServer = server.getHttpServer();
         vi.spyOn(httpServer, 'listen').mockImplementation(() => httpServer);
         const startPromise = server.start();
         await Promise.resolve();
         httpServer.emit('error', new Error('listen failed'));
         await expect(startPromise).rejects.toThrow('listen failed');
-        expect(configureSnapshotReconciliation).not.toHaveBeenCalled();
+        expect(harness.lifecycle.snapshotReconciliation.start).not.toHaveBeenCalled();
+    });
+    it('runs normal cleanup when startup fails after the server is bound', async () => {
+        const harness = createTestHarness();
+        vi.mocked(harness.services.schedulerService.start).mockImplementationOnce(() => {
+            throw new Error('scheduler failed');
+        });
+        const server = createTestServer(harness.application, 0);
+        await expect(server.start()).rejects.toThrow('scheduler failed');
+        expect(server.getHttpServer().listening).toBe(false);
+        expect(harness.lifecycle.interceptors.stop).toHaveBeenCalledOnce();
+        expect(harness.services.sessionService.stopAllClients).toHaveBeenCalledWith(5000);
+        expect(harness.services.terminalService.cleanup).toHaveBeenCalledOnce();
+        expect(harness.services.sessionFileLogger.cleanup).toHaveBeenCalledOnce();
+        expect(harness.services.acpTraceLogger.cleanup).toHaveBeenCalledOnce();
+        expect(harness.services.rateLimiter.stop).toHaveBeenCalledOnce();
+        expect(harness.services.schedulerService.stop).toHaveBeenCalledOnce();
+        expect(harness.services.periodicTaskService.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.eventCollector.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.snapshotReconciliation.stop).toHaveBeenCalledOnce();
+        expect(harness.services.workspaceGitStateService.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.snapshotReconciliation.stop.mock.invocationCallOrder[0] ?? 0).toBeLessThan(harness.services.workspaceGitStateService.stop.mock.invocationCallOrder[0] ?? 0);
+        expect(harness.services.ratchetService.stop).toHaveBeenCalledOnce();
+        expect(harness.services.reconciliationService.stopPeriodicCleanup).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.database.$disconnect).toHaveBeenCalledOnce();
+    });
+    it('does not allow retrying start after startup failure cleanup', async () => {
+        const harness = createTestHarness();
+        vi.mocked(harness.services.schedulerService.start).mockImplementationOnce(() => {
+            throw new Error('scheduler failed');
+        });
+        const server = createTestServer(harness.application, 0);
+        await expect(server.start()).rejects.toThrow('scheduler failed');
+        expect(server.getHttpServer().listening).toBe(false);
+        await expect(server.start()).rejects.toThrow('Server has already been stopped');
+        await server.stop();
+        expect(harness.lifecycle.interceptors.stop).toHaveBeenCalledOnce();
+        expect(harness.services.sessionService.stopAllClients).toHaveBeenCalledOnce();
+        expect(harness.services.schedulerService.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.database.$disconnect).toHaveBeenCalledOnce();
     });
     it('runs cleanup fan-out when server stops', async () => {
         const harness = createTestHarness();
-        const server = createTestServer(harness.context);
+        const server = createTestServer(harness.application);
         await server.stop();
-        expect(stopInterceptors).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.interceptors.stop).toHaveBeenCalledOnce();
         expect(harness.services.sessionService.stopAllClients).toHaveBeenCalledWith(5000);
         expect(harness.services.terminalService.cleanup).toHaveBeenCalledOnce();
         expect(harness.services.sessionFileLogger.cleanup).toHaveBeenCalledOnce();
         expect(harness.services.acpTraceLogger.cleanup).toHaveBeenCalledOnce();
         expect(harness.services.rateLimiter.stop).toHaveBeenCalledOnce();
         expect(harness.services.schedulerService.stop).toHaveBeenCalledOnce();
-        expect(stopEventCollector).toHaveBeenCalledOnce();
-        expect(snapshotReconciliationService.stop).toHaveBeenCalledOnce();
+        expect(harness.services.periodicTaskService.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.eventCollector.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.snapshotReconciliation.stop).toHaveBeenCalledOnce();
+        expect(harness.services.workspaceGitStateService.stop).toHaveBeenCalledOnce();
         expect(harness.services.ratchetService.stop).toHaveBeenCalledOnce();
-        expect(reconciliationService.stopPeriodicCleanup).toHaveBeenCalledOnce();
-        expect(prisma.$disconnect).toHaveBeenCalledOnce();
+        expect(harness.services.reconciliationService.stopPeriodicCleanup).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.database.$disconnect).toHaveBeenCalledOnce();
+        expect(transportDisposers.chat).toHaveBeenCalledWith(harness.application);
+        expect(transportDisposers.snapshots).toHaveBeenCalledWith(harness.application);
+    });
+    it('closes active WebSocket clients before completing server cleanup', async () => {
+        handlers.chat.mockImplementationOnce((request, socket, head, _url, wss) => {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                wss.emit('connection', ws, request);
+            });
+        });
+        const harness = createTestHarness({ backendHost: '127.0.0.1' });
+        const server = createTestServer(harness.application, 0);
+        await server.start();
+        const address = server.getHttpServer().address();
+        if (address === null || typeof address === 'string') {
+            throw new Error('Expected the server to listen on a TCP port');
+        }
+        const client = new WebSocket(`ws://127.0.0.1:${address.port}/chat`, {
+            headers: { Origin: 'http://localhost:3000' },
+        });
+        await new Promise((resolve, reject) => {
+            client.once('open', resolve);
+            client.once('error', reject);
+        });
+        const closed = new Promise((resolve) => client.once('close', () => resolve()));
+        await server.stop();
+        await closed;
+        expect(client.readyState).toBe(WebSocket.CLOSED);
+    });
+    it('starts and idempotently stops only the supplied application graph', async () => {
+        const harness = createTestHarness();
+        const server = createTestServer(harness.application, 0);
+        await server.start();
+        await Promise.all([server.stop(), server.stop()]);
+        expect(harness.lifecycle.interceptors.start).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.interceptors.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.eventCollector.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.snapshotReconciliation.start).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.snapshotReconciliation.stop).toHaveBeenCalledOnce();
+        expect(harness.lifecycle.database.$disconnect).toHaveBeenCalledOnce();
     });
     it('serves static index fallback with no-cache headers and bypasses API routes', async () => {
         const frontendStaticPath = createStaticFrontendDir({ withIndex: true });
         const harness = createTestHarness({ frontendStaticPath });
-        const server = createTestServer(harness.context);
+        const server = createTestServer(harness.application);
         const fallbackResponse = await request(server.getHttpServer()).get('/workspace/abc');
         const deepFallbackResponse = await request(server.getHttpServer()).get('/workspace/abc/session/def');
         const apiResponse = await request(server.getHttpServer()).get('/api/unknown');
@@ -393,7 +626,7 @@ describe('server websocket upgrade routing', () => {
     });
     it('sets no-cache headers when index.html is requested directly', async () => {
         const frontendStaticPath = createStaticFrontendDir({ withIndex: true });
-        const server = createTestServer(createTestAppContext({ frontendStaticPath }));
+        const server = createTestServer(createTestApplication({ frontendStaticPath }));
         const response = await request(server.getHttpServer()).get('/index.html');
         expect(response.status).toBe(200);
         expect(response.headers['cache-control']).toBe('no-cache, no-store, must-revalidate');
@@ -403,7 +636,7 @@ describe('server websocket upgrade routing', () => {
     it('returns 503 when static fallback index.html is missing', async () => {
         const frontendStaticPath = createStaticFrontendDir({ withIndex: false });
         const harness = createTestHarness({ frontendStaticPath });
-        const server = createTestServer(harness.context);
+        const server = createTestServer(harness.application);
         const response = await request(server.getHttpServer()).get('/workspace/xyz');
         expect(response.status).toBe(503);
         expect(response.text).toContain('Service temporarily unavailable');