@playcraft/cli 0.1.42 → 0.1.44-beta

package/dist/workspace-runtime/server/http.js

@@ -0,0 +1,1297 @@
+import { readObservedFile, withObservedFile } from '../workspaces/revisions.js';
+import { registerWorkspace, revisionScope, sessionWorkspaceRoot, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access as accessDirectory, stat } from 'node:fs/promises';
+import { workspaceRegistrationRequestSchema, workspaceFileSearchQuerySchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, isLostThreadError, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, isWorkspaceMutation, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, workspaceUiResultSchema, workspaceRemixReferenceImportRequestSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES, workspaceSessionRestoreRequestSchema, workspaceSessionRestoreResponseSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { controlTokenMatches, extractControlToken } from './auth.js';
+import { applyRuntimeEndpointPatch } from './endpoints.js';
+import { wakeSourceEventUploader } from './source-uploader.js';
+import { canExecuteKind, executeOperation } from './dispatch.js';
+import { InvalidWorkspacePathError, listWorkspaceFiles, } from '../workspaces/files.js';
+import { GitWorkspaceError, readWorkspaceGitDiff, readWorkspaceGitFile, readWorkspaceGitGraph, readWorkspaceGitStatus, } from '../workspaces/git.js';
+import { readWorkspaceParameters } from '../workspaces/parameters.js';
+import { readDependencies } from '../workspaces/dependencies.js';
+import { desktopHost, desktopRoute } from './desktop-host.js';
+import { ensureCliCredentials } from '../workspaces/cli-credentials.js';
+import { readAttachmentUpload, uploadWorkspaceAttachment, uploadWorkspaceVideoAttachment } from '../workspaces/attachments.js';
+import { serveWorkspaceAttachment } from '../workspaces/attachment-content.js';
+import { serveWorkspaceFileContent } from '../workspaces/file-content.js';
+import { importWorkspaceLibraryAttachment, listWorkspaceLibraryAttachments, listWorkspaceLibraryImportReceipts, readLibraryAttachmentUpload } from '../workspaces/library-attachments.js';
+import { beginWorkspaceDirectoryAttachment, uploadWorkspaceDirectoryFile, completeWorkspaceDirectoryAttachment, cancelWorkspaceDirectoryAttachment } from '../workspaces/directory-attachments.js';
+import { readWorkspaceSkills } from '../workspaces/skills.js';
+import { listWorkspaceRemixReferences, RemixReferenceError } from '../workspaces/remix-references.js';
+import { loadWorkspaceSkillArtifact } from '../workspaces/skill-artifact-loader.js';
+import { join } from 'node:path';
+import { terminalHost } from './terminal-host.js';
+import { productionCapability, productionDirectoryBusy, executeSandboxProduction, sandboxProductionReceipt } from '../production/controller.js';
+import { dispatchBatchRoute } from '../batch/routes.js';
+import { cleanupWorkspaceDirectories, syncWorkspaceDirectories } from '../workspaces/directory-maintenance.js';
+import { registerWorkspaceDirectory, restoreWorkspaceDirectory } from '../workspaces/directories.js';
+import { readWorkspaceDirectoryStats } from '../workspaces/directory-stats.js';
+import { probeRuntimeConnectivity } from './connectivity.js';
+import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
+import { WorkspaceArtifactStore } from '../workspaces/artifacts.js';
+import { workspaceArtifactContentQuerySchema } from '@playcraft/common/cloud-workspace/runtime';
+import { searchWorkspaceFiles } from '../workspaces/files-search.js';
+import { serveWorkspaceArchive } from '../workspaces/archive.js';
+import { handleWorkspaceTransfer } from './workspace-transfer.js';
+import { serveSessionImage } from '../workspaces/session-image.js';
+import { restoreNativeSession, SessionRestoreError } from './session-restore.js';
+export async function handleRuntimeRequest(state, request, response) {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const directoryName = url.searchParams.get('directoryName') ?? 'basic';
+    const access = authorizeRuntime(state, request);
+    if (!access) {
+        writeError(response, runtimeError('unauthenticated', 'control_token_required'));
+        return;
+    }
+    if (access === 'read' && !readSourcePath(request.method ?? 'GET', url.pathname)) {
+        writeJson(response, 403, { error: 'source_read_only' });
+        return;
+    }
+    try {
+        const batch = await dispatchBatchRoute(state, request, url);
+        if (batch) {
+            writeJson(response, batch.status, batch.body);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/production/capability') {
+            writeJson(response, 200, await productionCapability(state));
+            return;
+        }
+        if (request.method === 'POST' && ['/runtime/production/stages', '/runtime/production/stop', '/runtime/production/reconcile'].includes(url.pathname)) {
+            writeJson(response, 200, await executeSandboxProduction(state, await readJson(request)));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname.startsWith('/runtime/production/stages/')) {
+            writeJson(response, 200, await sandboxProductionReceipt(state, decodeURIComponent(url.pathname.slice('/runtime/production/stages/'.length)), {
+                workspaceId: url.searchParams.get('workspaceId') ?? '', directoryName, taskId: url.searchParams.get('taskId') ?? '',
+                attemptId: url.searchParams.get('attemptId') ?? '', owner: url.searchParams.get('owner') ?? '', fence: Number(url.searchParams.get('fence')),
+            }));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/health') {
+            writeJson(response, 200, { status: 'ok', handshake: handshake(state) });
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/connectivity') {
+            if (writeDestroyed(state, response))
+                return;
+            const parsed = runtimeConnectivityDocumentSchema.shape.workspaceId.safeParse(url.searchParams.get('workspaceId'));
+            if (!parsed.success) {
+                writeJson(response, 400, { error: 'invalid_workspace' });
+                return;
+            }
+            const workspaceId = parsed.data;
+            const root = await sessionWorkspaceRoot(state, workspaceId, directoryName);
+            const rootStat = await stat(root).catch(error => {
+                if (['ENOENT', 'ENOTDIR'].includes(error.code))
+                    throw new WorkspaceContextError('workspace_not_prepared', { cause: error });
+                throw error;
+            });
+            if (!rootStat.isDirectory())
+                throw new WorkspaceContextError('workspace_not_prepared');
+            await accessDirectory(root, constants.R_OK | constants.X_OK);
+            writeJson(response, 200, await probeRuntimeConnectivity(state, workspaceId));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/identity') {
+            const { runtimeId, userId, environment, generation } = state.config;
+            writeJson(response, 200, {
+                runtimeId,
+                userId,
+                environment,
+                generation,
+                runtimeEpoch: state.runtimeEpoch,
+                instanceToken: state.instanceToken,
+                permissionsVersion: 1,
+                composerContextVersion: 1,
+                remixReferencesVersion: 1,
+                ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
+                ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
+                ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),
+                sourceReadToken: state.journal.sourceReadToken(),
+                workspaceMode: state.config.workspaceMode,
+                executionGroup: {
+                    replaced: state.journal.executionGroup().replaced,
+                    stopConfirmed: state.journal.executionGroup().stopConfirmed,
+                    ...(state.journal.stoppedRuntimeEpochs().length ? { stoppedRuntimeEpochs: state.journal.stoppedRuntimeEpochs() } : {}),
+                },
+            });
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/approvals') {
+            writeJson(response, 200, { approvals: state.journal.listApprovals() });
+            return;
+        }
+        const restoreRoute = /^\/runtime\/sessions\/([^/]+)\/restore$/.exec(url.pathname);
+        if (request.method === 'POST' && restoreRoute) {
+            if (writeDestroyed(state, response))
+                return;
+            if (state.config.workspaceMode !== 'multi') {
+                writeJson(response, 409, { error: 'multi_workspace_unavailable' });
+                return;
+            }
+            const scope = workspaceSessionRestoreResponseSchema.pick({ sessionId: true, workspaceId: true, directoryName: true }).safeParse({
+                sessionId: decodeURIComponent(restoreRoute[1]), workspaceId: url.searchParams.get('workspaceId'), directoryName,
+            });
+            const parsed = workspaceSessionRestoreRequestSchema.safeParse(await readJson(request, 4096));
+            if (!scope.success || !parsed.success) {
+                writeJson(response, 400, { error: 'invalid_session_restore' });
+                return;
+            }
+            try {
+                const restored = await state.journal.exclusive(`directory:${scope.data.workspaceId}:${directoryName}`, async () => {
+                    if (await productionDirectoryBusy(state, scope.data.workspaceId, directoryName))
+                        throw new SessionRestoreError('batch_workspace_readonly');
+                    return state.journal.exclusive(`session:${scope.data.sessionId}`, () => state.journal.exclusive(`workspace:${revisionScope(state, scope.data.workspaceId, directoryName) ?? 'single'}`, () => restoreNativeSession(state, scope.data, parsed.data)));
+                });
+                writeJson(response, 200, workspaceSessionRestoreResponseSchema.parse({
+                    ...scope.data, threadId: restored.threadId, generation: parsed.data.generation,
+                    runtimeEpoch: parsed.data.runtimeEpoch, recoverability: 'native',
+                }));
+            }
+            catch (error) {
+                if (!(error instanceof SessionRestoreError))
+                    throw error;
+                writeJson(response, 409, { error: error.message });
+            }
+            return;
+        }
+        const uiResultRoute = /^\/runtime\/sessions\/([^/]+)\/ui-results$/.exec(url.pathname);
+        if (request.method === 'POST' && uiResultRoute) {
+            if (writeDestroyed(state, response))
+                return;
+            const sessionId = decodeURIComponent(uiResultRoute[1]);
+            const parsed = workspaceUiResultSchema.safeParse(await readJson(request));
+            if (!parsed.success) {
+                writeJson(response, 400, { error: 'invalid_ui_result' });
+                return;
+            }
+            const session = state.journal.getSession(sessionId);
+            if (!session || productionSessionAttemptId(sessionId) || session.workspaceId !== url.searchParams.get('workspaceId')
+                || (session.directoryName ?? 'basic') !== directoryName) {
+                writeJson(response, 404, { error: 'session_not_found' });
+                return;
+            }
+            if (!state.native?.workspaceUi || !state.native.respondUiTool) {
+                writeJson(response, 409, { error: 'ui_tools_unavailable' });
+                return;
+            }
+            const result = await state.native.respondUiTool({ sessionId, ...parsed.data });
+            writeJson(response, result.outcome === 'accepted' ? 200 : 409, result);
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/workspaces/register') {
+            if (writeDestroyed(state, response))
+                return;
+            const parsed = workspaceRegistrationRequestSchema.safeParse(await readJson(request));
+            if (!parsed.success || parsed.data.generation !== state.config.generation || parsed.data.runtimeEpoch !== state.runtimeEpoch) {
+                writeJson(response, 409, { error: 'invalid_workspace_registration' });
+                return;
+            }
+            const binding = await registerWorkspace(state, parsed.data.binding, parsed.data.leaseFence, parsed.data.preparation, parsed.data.cliCredentials === false, parsed.data.sourceSnapshot);
+            if (parsed.data.cliCredentials)
+                await ensureCliCredentials(state);
+            writeJson(response, 200, { workspaceId: binding.workspaceId, status: 'registered' });
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/workspaces/directories/register') {
+            if (writeDestroyed(state, response))
+                return;
+            const body = asRecord(await readJson(request));
+            if (body.generation !== state.config.generation || body.runtimeEpoch !== state.runtimeEpoch || !Number.isSafeInteger(body.leaseFence)) {
+                writeJson(response, 409, { error: 'invalid_workspace_registration' });
+                return;
+            }
+            writeJson(response, 200, await registerWorkspaceDirectory(state, body.directory, Number(body.leaseFence)));
+            return;
+        }
+        const maintenance = /^\/runtime\/workspaces\/([a-f0-9-]{36})\/directories\/(cleanup|sync|stats)$/.exec(url.pathname);
+        if ((request.method === 'GET' || request.method === 'POST') && maintenance?.[2] === 'stats') {
+            if (writeDestroyed(state, response))
+                return;
+            writeJson(response, 200, await readWorkspaceDirectoryStats(state, maintenance[1]));
+            return;
+        }
+        if (request.method === 'POST' && maintenance) {
+            if (writeDestroyed(state, response))
+                return;
+            const body = asRecord(await readJson(request));
+            const workspaceId = maintenance[1];
+            writeJson(response, 200, maintenance[2] === 'cleanup'
+                ? await cleanupWorkspaceDirectories(state, workspaceId, body.directoryNames)
+                : await syncWorkspaceDirectories(state, workspaceId, body.commitHash, body.targetDirectoryNames));
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/endpoints') {
+            try {
+                writeJson(response, 200, await applyRuntimeEndpointPatch(state, await readJson(request)));
+            }
+            catch {
+                writeError(response, runtimeError('invalid_config', 'endpoint_patch_rejected'));
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/handshake') {
+            writeJson(response, 200, handshake(state));
+            return;
+        }
+        const historyPath = sessionHistoryPath(url.pathname);
+        if (request.method === 'GET' && historyPath) {
+            await handleSessionHistory(state, response, historyPath.workspaceId, historyPath.sessionId);
+            return;
+        }
+        if (['GET', 'HEAD', 'POST'].includes(request.method ?? '') && url.pathname === '/runtime/session-image') {
+            let recordedPath;
+            if (request.method === 'POST') {
+                const body = asRecord(await readJson(request));
+                if (Object.keys(body).length !== 1 || typeof body.path !== 'string' || !body.path || body.path.length > 4096) {
+                    writeJson(response, 404, { error: 'image_not_found' });
+                    return;
+                }
+                recordedPath = body.path;
+            }
+            await serveSessionImage(state, request, response, url.searchParams, recordedPath);
+            return;
+        }
+        if (isUnimplementedWorkbenchPath(url.pathname)) {
+            if (writeDestroyed(state, response))
+                return;
+            writeError(response, runtimeError('capability_unavailable', 'capability_not_implemented'));
+            return;
+        }
+        if (url.pathname === '/runtime/events' || url.pathname.startsWith('/runtime/events/')) {
+            await handleSourceEvents(state, request, response, url);
+            return;
+        }
+        if (url.pathname === '/runtime/attachments/library' && ['GET', 'POST'].includes(request.method ?? '')) {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? '';
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            if (request.method === 'GET') {
+                const sessionId = url.searchParams.get('sessionId') ?? undefined;
+                writeJson(response, 200, { attachments: await listWorkspaceLibraryAttachments(root, sessionId),
+                    importReceipts: await listWorkspaceLibraryImportReceipts(root, sessionId) });
+            }
+            else {
+                if (await productionDirectoryBusy(state, workspaceId, directoryName)) {
+                    writeJson(response, 409, { error: 'batch_workspace_readonly' });
+                    return;
+                }
+                try {
+                    const attachment = await importWorkspaceLibraryAttachment(root, await readLibraryAttachmentUpload(request));
+                    await state.journal.allocateSourceEvent({
+                        runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+                        workspaceId, type: 'attachments.imported', occurredAt: new Date().toISOString(),
+                        payload: { workspaceId, directoryName, attachmentId: attachment.id },
+                    });
+                    writeJson(response, 200, attachment);
+                }
+                catch (error) {
+                    const code = error instanceof Error && ['library_asset_too_large', 'library_asset_changed', 'library_attachment_limit'].includes(error.message)
+                        ? error.message : 'invalid_library_attachment';
+                    writeJson(response, 400, { error: code });
+                }
+            }
+            return;
+        }
+        const directoryUpload = /^\/runtime\/attachments\/directory(?:\/([^/]+)(?:\/(file|complete))?)?$/.exec(url.pathname);
+        if (directoryUpload && ['POST', 'PUT', 'DELETE'].includes(request.method ?? '')) {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? '';
+            if (await productionDirectoryBusy(state, workspaceId, directoryName)) {
+                writeJson(response, 409, { error: 'batch_workspace_readonly' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const [, uploadId, action] = directoryUpload;
+            try {
+                if (!uploadId && request.method === 'POST')
+                    writeJson(response, 200, await beginWorkspaceDirectoryAttachment(root, await readAttachmentUpload(request)));
+                else if (uploadId && action === 'file' && request.method === 'PUT')
+                    writeJson(response, 200, await uploadWorkspaceDirectoryFile(root, uploadId, url.searchParams.get('path') ?? '', request));
+                else if (uploadId && action === 'complete' && request.method === 'POST') {
+                    const attachment = await completeWorkspaceDirectoryAttachment(root, uploadId);
+                    await state.journal.allocateSourceEvent({
+                        runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+                        workspaceId, type: 'attachments.imported', occurredAt: new Date().toISOString(),
+                        payload: { workspaceId, directoryName, attachmentId: attachment.id },
+                    });
+                    writeJson(response, 200, attachment);
+                }
+                else if (uploadId && !action && request.method === 'DELETE')
+                    writeJson(response, 200, await cancelWorkspaceDirectoryAttachment(root, uploadId));
+                else
+                    writeJson(response, 400, { error: 'invalid_attachment' });
+            }
+            catch (error) {
+                writeJson(response, 400, { error: error instanceof Error && error.message === 'video_probe_unavailable' ? 'video_probe_unavailable' : 'invalid_attachment' });
+            }
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/attachments/video') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? '';
+            if (await productionDirectoryBusy(state, workspaceId, directoryName)) {
+                writeJson(response, 409, { error: 'batch_workspace_readonly' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            try {
+                writeJson(response, 200, await uploadWorkspaceVideoAttachment(root, request, { name: url.searchParams.get('name') }));
+            }
+            catch (error) {
+                writeJson(response, 400, { error: error instanceof Error && error.message === 'video_probe_unavailable' ? 'video_probe_unavailable' : 'invalid_attachment' });
+            }
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/attachments') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? '';
+            if (await productionDirectoryBusy(state, workspaceId, directoryName)) {
+                writeJson(response, 409, { error: 'batch_workspace_readonly' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            try {
+                writeJson(response, 200, await uploadWorkspaceAttachment(root, await readAttachmentUpload(request)));
+            }
+            catch {
+                writeJson(response, 400, { error: 'invalid_attachment' });
+            }
+            return;
+        }
+        if (['GET', 'HEAD'].includes(request.method ?? '') && url.pathname === '/runtime/attachment-content') {
+            if (writeDestroyed(state, response))
+                return;
+            const root = await workspaceRoot(state, url.searchParams.get('workspaceId') ?? '', directoryName);
+            await serveWorkspaceAttachment(root, url.searchParams.get('attachmentId') ?? '', request, response, url.searchParams.get('filePath') ?? undefined);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/artifacts') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId');
+            if (!workspaceId) {
+                writeJson(response, 400, { error: 'invalid_workspace' });
+                return;
+            }
+            await workspaceRoot(state, workspaceId);
+            writeJson(response, 200, url.searchParams.get('refresh') === 'false'
+                ? await new WorkspaceArtifactStore(state.config.stateDir, workspaceId).list()
+                : await refreshWorkspaceArtifacts(state, workspaceId));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/artifact-content') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId');
+            if (!workspaceId) {
+                writeJson(response, 400, { error: 'invalid_workspace' });
+                return;
+            }
+            await workspaceRoot(state, workspaceId);
+            const parsed = workspaceArtifactContentQuerySchema.safeParse({
+                artifactId: url.searchParams.get('artifactId'), versionId: url.searchParams.get('versionId'),
+                ...(url.searchParams.has('path') ? { path: url.searchParams.get('path') } : {}),
+                ...(url.searchParams.has('offset') ? { offset: Number(url.searchParams.get('offset')) } : {}),
+                ...(url.searchParams.has('length') ? { length: Number(url.searchParams.get('length')) } : {}),
+            });
+            if (!parsed.success) {
+                writeJson(response, 400, { error: 'invalid_artifact_query' });
+                return;
+            }
+            try {
+                writeJson(response, 200, await new WorkspaceArtifactStore(state.config.stateDir, workspaceId).content(parsed.data));
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : 'artifact_unavailable';
+                writeJson(response, reason === 'artifact_not_found' ? 404 : reason === 'artifact_range_invalid' ? 416 : 409, { error: reason });
+            }
+            return;
+        }
+        if (['GET', 'POST'].includes(request.method ?? '') && url.pathname === '/runtime/git-bundle') {
+            if (writeDestroyed(state, response))
+                return;
+            await handleWorkspaceTransfer(state, request, response, url);
+            return;
+        }
+        if (['GET', 'HEAD'].includes(request.method ?? '') && url.pathname === '/runtime/archive') {
+            if (writeDestroyed(state, response))
+                return;
+            const root = await sessionWorkspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName);
+            await serveWorkspaceArchive(root, request, response, { excludedRoots: [state.config.stateDir] });
+            return;
+        }
+        if (['GET', 'HEAD'].includes(request.method ?? '') && url.pathname === '/runtime/file-content') {
+            if (writeDestroyed(state, response))
+                return;
+            const root = await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName);
+            await serveWorkspaceFileContent(root, url.searchParams.get('path') ?? '', request, response);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/files') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const listed = await listWorkspaceFiles(root, state.journal.fileRevisions(revisionScope(state, workspaceId, directoryName)));
+            console.log(`[workspace-files] GET /runtime/files workspaceId=${workspaceId ?? '-'} root=${root} files=${listed.files.length}`);
+            writeJson(response, 200, listed);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/files/search') {
+            if (writeDestroyed(state, response))
+                return;
+            if (directoryName === 'root') {
+                writeJson(response, 400, { error: 'invalid_workspace_search' });
+                return;
+            }
+            const parsed = workspaceFileSearchQuerySchema.safeParse({
+                query: url.searchParams.get('q') ?? '',
+                ...(url.searchParams.has('limit') ? { limit: Number(url.searchParams.get('limit')) } : {}),
+                ...(url.searchParams.has('cursor') ? { cursor: url.searchParams.get('cursor') } : {}),
+            });
+            if (!parsed.success) {
+                writeJson(response, 400, { error: 'invalid_workspace_search' });
+                return;
+            }
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            const closedRequest = () => { if (request.aborted || !request.complete)
+                abort(); };
+            request.once('aborted', abort);
+            request.once('close', closedRequest);
+            response.once('close', abort);
+            try {
+                const root = await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName);
+                const result = await searchWorkspaceFiles(root, parsed.data, { signal: controller.signal });
+                if (!controller.signal.aborted)
+                    writeJson(response, 200, result);
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'AbortError')
+                    return;
+                if (error instanceof Error && ['invalid_workspace_search', 'invalid_workspace_search_cursor'].includes(error.message))
+                    writeJson(response, 400, { error: error.message });
+                else
+                    throw error;
+            }
+            finally {
+                request.off('aborted', abort);
+                request.off('close', closedRequest);
+                response.off('close', abort);
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/file') {
+            if (writeDestroyed(state, response))
+                return;
+            const relativePath = url.searchParams.get('path') ?? '';
+            try {
+                writeJson(response, 200, await readObservedFile(state, url.searchParams.get('workspaceId') ?? undefined, relativePath, directoryName));
+            }
+            catch (error) {
+                if (error instanceof InvalidWorkspacePathError) {
+                    writeJson(response, 400, { error: 'invalid_workspace_path' });
+                    return;
+                }
+                if (error.code === 'ENOENT') {
+                    writeJson(response, 404, { error: 'file_not_found' });
+                    return;
+                }
+                throw error;
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/git/status') {
+            await writeGitRead(state, response, async () => readWorkspaceGitStatus(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/git/diff') {
+            await writeGitRead(state, response, async () => readWorkspaceGitDiff(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/git/file') {
+            const ref = gitFileRefSchema.safeParse(url.searchParams.get('ref'));
+            if (!ref.success) {
+                writeJson(response, 400, { error: 'invalid_git_ref' });
+                return;
+            }
+            await writeGitRead(state, response, async () => readWorkspaceGitFile(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName), url.searchParams.get('path') ?? '', ref.data));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/dependencies') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            await workspaceRoot(state, workspaceId, directoryName);
+            writeJson(response, 200, readDependencies(state, revisionScope(state, workspaceId, directoryName) ?? 'workspace'));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/remix-references') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            try {
+                const items = await state.journal.exclusive(`workspace:${revisionScope(state, workspaceId, directoryName) ?? 'single'}`, async () => listWorkspaceRemixReferences(await workspaceRoot(state, workspaceId, directoryName), directoryName));
+                writeJson(response, 200, { items });
+            }
+            catch (error) {
+                if (error instanceof WorkspaceContextError)
+                    throw error;
+                writeJson(response, 409, { error: error instanceof RemixReferenceError ? error.message : 'remix_reference_unavailable' });
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/skills') {
+            if (writeDestroyed(state, response))
+                return;
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            try {
+                const view = await state.journal.exclusive(`workspace:${revisionScope(state, workspaceId, directoryName) ?? 'single'}`, async () => readWorkspaceSkills(await workspaceRoot(state, workspaceId, directoryName), join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, workspaceId ?? 'workspace', entry, directoryName)));
+                writeJson(response, 200, view);
+            }
+            catch (error) {
+                if (error instanceof WorkspaceContextError)
+                    throw error;
+                writeJson(response, 409, { error: error instanceof Error && error.message.startsWith('workspace_skills_') ? error.message : 'workspace_skills_unavailable' });
+            }
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/git/graph') {
+            await writeGitRead(state, response, async () => readWorkspaceGitGraph(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/parameters') {
+            if (writeDestroyed(state, response))
+                return;
+            writeJson(response, 200, await readObservedParameters(state, url.searchParams.get('workspaceId') ?? undefined, directoryName));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/terminals') {
+            if (writeDestroyed(state, response))
+                return;
+            writeJson(response, 200, {
+                terminals: state.journal.listTerminals(url.searchParams.get('workspaceId') ?? undefined).filter(terminal => (terminal.directoryName ?? 'basic') === directoryName),
+            });
+            return;
+        }
+        if (url.pathname.startsWith('/runtime/terminals/')) {
+            await handleTerminalIdentity(state, request, response, url.pathname.slice('/runtime/terminals/'.length));
+            return;
+        }
+        if (desktopRoute(url.pathname)) {
+            await desktopHost(state).handleHttp(request, response, url);
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/runtime/operations') {
+            const kind = operationKindSchema.safeParse(url.searchParams.get('kind'));
+            const clientRequestId = url.searchParams.get('clientRequestId');
+            if (!kind.success || !clientRequestId) {
+                writeJson(response, 400, { error: 'invalid_operation_lookup' });
+                return;
+            }
+            const operation = state.journal.getOperation(operationScopeKey({
+                environment: state.config.environment,
+                userId: state.config.userId,
+                kind: kind.data,
+                clientRequestId,
+                workspaceId: url.searchParams.get('workspaceId') ?? undefined,
+                directoryName,
+                sessionId: url.searchParams.get('sessionId') ?? undefined,
+            }));
+            writeJson(response, operation ? 200 : 404, operation ?? { error: 'operation_not_found' });
+            return;
+        }
+        if (request.method === 'GET' && url.pathname.startsWith('/runtime/operations/')) {
+            const operationId = url.pathname.slice('/runtime/operations/'.length);
+            const operation = state.journal.getOperationById(operationId);
+            if (!operation) {
+                writeJson(response, 404, { error: 'operation_not_found' });
+                return;
+            }
+            writeJson(response, 200, operation);
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/operations') {
+            // Track creation before accepting it, so a new unconnected terminal is known not to have spawned.
+            terminalHost(state);
+            await acceptOperation(state, request, response);
+            return;
+        }
+        writeJson(response, 404, { error: 'not_found' });
+    }
+    catch (error) {
+        if (request.method === 'GET' && ['/runtime/connectivity', '/runtime/files'].includes(url.pathname)) {
+            const cause = error instanceof Error && error.cause ? error.cause : error;
+            if (['EACCES', 'EPERM'].includes(String(cause?.code))) {
+                writeJson(response, 409, { error: 'workspace_permission_denied' });
+                return;
+            }
+            if (url.pathname === '/runtime/connectivity' && error instanceof WorkspaceContextError && error.cause && !['ENOENT', 'ENOTDIR'].includes(String(cause?.code))) {
+                writeJson(response, 500, { error: 'workspace_access_failed' });
+                return;
+            }
+        }
+        if (error instanceof Error && error.message === 'request_body_too_large') {
+            writeJson(response, 413, { error: 'request_body_too_large' });
+            return;
+        }
+        if (error instanceof WorkspaceContextError) {
+            writeJson(response, 409, { error: error.message });
+            return;
+        }
+        writeJson(response, 500, {
+            error: 'internal_error',
+            reason: error instanceof Error ? error.message : 'unknown',
+        });
+    }
+}
+function handshake(state) {
+    const destroyed = state.journal.destroyed();
+    const conversationReady = Boolean(state.native?.ready()) && !destroyed;
+    const filesReady = !destroyed;
+    const gitReady = state.gitAvailable && !destroyed;
+    const capabilities = unavailableRuntimeCapabilities('adapter_not_started').map((item) => {
+        if (item.name === 'conversation') {
+            if (conversationReady)
+                return capability('conversation', true);
+            return capability('conversation', false, destroyed ? 'runtime_destroyed' : state.nativeError ?? 'adapter_not_started');
+        }
+        if (item.name === 'files') {
+            return filesReady
+                ? capability('files', true)
+                : capability('files', false, 'runtime_destroyed');
+        }
+        if (item.name === 'git') {
+            if (gitReady)
+                return capability('git', true);
+            if (destroyed)
+                return capability('git', false, 'runtime_destroyed');
+            if (!state.gitAvailable)
+                return capability('git', false, 'git_binary_missing');
+            return item;
+        }
+        if (item.name === 'terminal') {
+            return destroyed
+                ? capability('terminal', false, 'runtime_destroyed')
+                : capability('terminal', true);
+        }
+        if (item.name === 'desktop') {
+            if (destroyed)
+                return capability('desktop', false, 'runtime_destroyed');
+            const status = desktopHost(state).snapshot().status;
+            return status === 'ready' ? capability('desktop', true) : capability('desktop', false, status);
+        }
+        if (item.name === 'parameters') {
+            return destroyed
+                ? capability('parameters', false, 'runtime_destroyed')
+                : capability('parameters', true);
+        }
+        if (item.name === 'artifacts.singleFile') {
+            return destroyed
+                ? capability('artifacts.singleFile', false, 'runtime_destroyed')
+                : capability('artifacts.singleFile', true);
+        }
+        return item;
+    });
+    return buildHandshakeDocument({
+        protocolMajor: state.config.protocolMajor,
+        protocolMinor: state.config.protocolMinor,
+        cliVersion: state.config.cliVersion,
+        codexVersion: state.config.codexVersion,
+        imageDigest: state.config.imageDigest,
+        phase: destroyed ? 'unavailable' : conversationReady ? 'ready' : 'awaiting_native',
+        generations: {
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            leaseFence: state.acceptedLeaseFence,
+        },
+        capabilities,
+    });
+}
+async function acceptOperation(state, request, response) {
+    const body = await readJson(request, Math.max(WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES));
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        writeJson(response, 400, { error: 'invalid_operation' });
+        return;
+    }
+    // leaseFence 由 Runtime Server 派发，本控制面单独校验；其余代次/身份/根目录字段仍只来自引导配置。
+    const untrusted = findUntrustedRuntimeFields(body).filter((field) => field !== 'leaseFence');
+    if (untrusted.length > 0) {
+        writeError(response, runtimeError('untrusted_runtime_field', untrusted.join(',')));
+        return;
+    }
+    const incomingFence = Number(body.leaseFence ?? state.acceptedLeaseFence);
+    if (!Number.isInteger(incomingFence) || incomingFence < 0) {
+        writeJson(response, 400, { error: 'invalid_lease_fence' });
+        return;
+    }
+    if (assertLeaseFence(incomingFence, state.acceptedLeaseFence) !== 'ok') {
+        writeError(response, runtimeError('stale_lease', 'leaseFence is behind the accepted dispatcher'));
+        return;
+    }
+    const { leaseFence: _leaseFence, ...requestBody } = body;
+    const parsed = operationAcceptRequestSchema.safeParse(requestBody);
+    if (!parsed.success) {
+        writeJson(response, 400, { error: 'invalid_operation', issues: parsed.error.issues });
+        return;
+    }
+    if (parsed.data.kind === 'workspace.references.import') {
+        const source = workspaceRemixReferenceImportRequestSchema.safeParse(parsed.data.payload);
+        const snapshot = parsed.data.remixReferenceSnapshot;
+        if (!source.success || (snapshot && (snapshot.source.projectUuid !== source.data.source.projectUuid ||
+            snapshot.source.branchName !== source.data.source.branchName || snapshot.source.environment !== state.config.environment))) {
+            writeJson(response, 400, { error: 'invalid_remix_reference' });
+            return;
+        }
+    }
+    if (parsed.data.kind.startsWith('session.') && !parsed.data.sessionId) {
+        writeJson(response, 400, { error: 'invalid_operation', reason: 'sessionId_required' });
+        return;
+    }
+    if (parsed.data.directoryName === 'root' && !parsed.data.kind.startsWith('session.') && !['runtime.ensure', 'terminal.create'].includes(parsed.data.kind)) {
+        writeJson(response, 400, { error: 'invalid_workspace_directory' });
+        return;
+    }
+    if (state.config.workspaceMode === 'multi' && parsed.data.kind === 'runtime.ensure' && parsed.data.workspaceId)
+        await restoreWorkspaceDirectory(state, parsed.data.workspaceId, parsed.data.directoryName);
+    if (state.config.workspaceMode === 'multi')
+        await sessionWorkspaceRoot(state, parsed.data.workspaceId, parsed.data.directoryName);
+    const mutation = isWorkspaceMutation(parsed.data.kind);
+    const occupiesDirectory = mutation || parsed.data.kind === 'session.compact';
+    if (occupiesDirectory && await productionDirectoryBusy(state, parsed.data.workspaceId, parsed.data.directoryName)) {
+        writeJson(response, 409, { error: 'batch_workspace_readonly' });
+        return;
+    }
+    const payloadHash = hashOperationPayload(parsed.data.payload);
+    const scopeKey = operationScopeKey({
+        environment: state.config.environment,
+        userId: state.config.userId,
+        kind: parsed.data.kind,
+        clientRequestId: parsed.data.clientRequestId,
+        workspaceId: parsed.data.workspaceId,
+        directoryName: parsed.data.directoryName,
+        sessionId: parsed.data.sessionId,
+    });
+    const accept = () => state.journal.exclusive(scopeKey, async () => {
+        // Recheck after a concurrent dispatcher may have advanced the fence while this request waited.
+        if (assertLeaseFence(incomingFence, state.acceptedLeaseFence) !== 'ok') {
+            writeError(response, runtimeError('stale_lease', 'leaseFence is behind the accepted dispatcher'));
+            return;
+        }
+        const existing = state.journal.getOperation(scopeKey);
+        const decision = resolveIdempotentAccept(existing, payloadHash);
+        if (decision.action === 'conflict') {
+            writeError(response, runtimeError('idempotency_conflict', 'clientRequestId reused with a different payload', {
+                operationId: decision.operation.operationId,
+            }));
+            return;
+        }
+        // A turn refused for a lost thread never reached Codex. Sent again with the conversation, it
+        // runs afresh under the same request, so the message is shown and answered only once.
+        const retryWithRecovery = decision.action === 'reuse' && parsed.data.kind === 'session.turn'
+            && Boolean(parsed.data.sessionRecovery) && decision.operation.status === 'failed'
+            && isLostThreadError(decision.operation.error);
+        if (decision.action === 'reuse' && !retryWithRecovery) {
+            if (decision.operation.status === 'uncertain') {
+                writeError(response, runtimeError('uncertain_operation', decision.operation.error ?? 'native_receipt_lost', {
+                    operationId: decision.operation.operationId,
+                }));
+                return;
+            }
+            writeJson(response, 200, decision.operation);
+            return;
+        }
+        if (parsed.data.kind.startsWith('session.') && parsed.data.sessionId && productionSessionAttemptId(parsed.data.sessionId)) {
+            writeError(response, runtimeError('capability_unavailable', 'production_session_readonly'));
+            return;
+        }
+        if (parsed.data.kind === 'session.create') {
+            const creation = state.journal.findSessionCreation(parsed.data.sessionId);
+            const session = state.journal.getSession(parsed.data.sessionId);
+            if (creation || session) {
+                writeJson(response, 409, { error: 'session_already_bound' });
+                return;
+            }
+        }
+        else if (parsed.data.kind === 'terminal.create') {
+            const payload = asRecord(parsed.data.payload);
+            const terminalId = typeof payload.terminalId === 'string' ? payload.terminalId.trim() : '';
+            if (!terminalId) {
+                writeJson(response, 400, { error: 'invalid_operation', reason: 'terminalId_required' });
+                return;
+            }
+            const creation = state.journal.findTerminalCreation(terminalId);
+            const terminal = state.journal.getTerminal(terminalId);
+            if (creation && operationScopeKey(creation) !== scopeKey) {
+                writeJson(response, 409, { error: 'terminal_already_bound' });
+                return;
+            }
+            if (terminal && !creation) {
+                writeJson(response, 409, { error: 'terminal_already_bound' });
+                return;
+            }
+        }
+        else if (parsed.data.kind.startsWith('session.') && state.config.workspaceMode === 'multi') {
+            const session = state.journal.getSession(parsed.data.sessionId);
+            // A replaced sandbox has no binding yet; the recovering turn creates it.
+            const rebinding = !session && parsed.data.kind === 'session.turn' && parsed.data.sessionRecovery;
+            if (!rebinding && (!session || session.workspaceId !== parsed.data.workspaceId
+                || (session.directoryName ?? 'basic') !== (parsed.data.directoryName ?? 'basic'))) {
+                writeJson(response, 409, { error: 'session_workspace_mismatch' });
+                return;
+            }
+        }
+        if (parsed.data.kind === 'workspace.references.import' && !parsed.data.remixReferenceSnapshot) {
+            writeJson(response, 400, { error: 'remix_reference_snapshot_required' });
+            return;
+        }
+        if (parsed.data.kind === 'asset.library.import' && !parsed.data.libraryAssetImports) {
+            writeJson(response, 400, { error: 'library_asset_snapshot_required' });
+            return;
+        }
+        const now = new Date().toISOString();
+        const executable = canExecuteKind(state, parsed.data.kind);
+        const payloadRecord = asRecord(parsed.data.payload);
+        const operation = {
+            operationId: randomUUID(),
+            environment: state.config.environment,
+            userId: state.config.userId,
+            clientRequestId: parsed.data.clientRequestId,
+            kind: parsed.data.kind,
+            status: executable ? 'queued' : 'failed',
+            payloadHash,
+            workspaceId: parsed.data.workspaceId,
+            directoryName: parsed.data.directoryName,
+            sessionId: parsed.data.sessionId,
+            expectedRevision: parsed.data.expectedRevision,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            leaseFence: incomingFence,
+            terminalId: parsed.data.kind === 'terminal.create' && typeof payloadRecord.terminalId === 'string'
+                ? payloadRecord.terminalId.trim()
+                : undefined,
+            cwd: parsed.data.kind === 'terminal.create' && typeof payloadRecord.cwd === 'string'
+                ? payloadRecord.cwd
+                : undefined,
+            error: executable ? undefined : 'capability_unavailable',
+            createdAt: now,
+            updatedAt: now,
+        };
+        if (!executable) {
+            const saved = await state.journal.putOperation(scopeKey, operation);
+            writeError(response, runtimeError('capability_unavailable', unavailableReason(state, parsed.data.kind), {
+                operationId: saved.operationId,
+            }));
+            return;
+        }
+        state.acceptedLeaseFence = Math.max(state.acceptedLeaseFence, incomingFence);
+        await state.journal.setAcceptedLeaseFence(state.acceptedLeaseFence);
+        const queued = await state.journal.putOperation(scopeKey, operation);
+        const executionPayload = parsed.data.kind === 'workspace.references.import'
+            ? { snapshot: parsed.data.remixReferenceSnapshot } : parsed.data.kind === 'asset.library.import'
+            ? { selection: parsed.data.payload, snapshot: parsed.data.libraryAssetImports } : parsed.data.payload;
+        const executed = await executeOperation(state, scopeKey, queued, executionPayload, parsed.data.sessionRecovery);
+        if (executed.status === 'uncertain') {
+            writeError(response, runtimeError('uncertain_operation', executed.error ?? 'native_receipt_lost', {
+                operationId: executed.operationId,
+            }));
+            return;
+        }
+        writeJson(response, executed.status === 'failed' ? 409 : 202, executed);
+    });
+    const acceptBound = async () => {
+        if (occupiesDirectory && await productionDirectoryBusy(state, parsed.data.workspaceId, parsed.data.directoryName)) {
+            writeJson(response, 409, { error: 'batch_workspace_readonly' });
+            return;
+        }
+        if (state.config.workspaceMode === 'multi')
+            await sessionWorkspaceRoot(state, parsed.data.workspaceId, parsed.data.directoryName);
+        if (parsed.data.kind === 'session.create')
+            await state.journal.exclusive(`session:${parsed.data.sessionId}`, accept);
+        else if (parsed.data.kind === 'terminal.create') {
+            const terminalId = typeof asRecord(parsed.data.payload).terminalId === 'string'
+                ? String(asRecord(parsed.data.payload).terminalId).trim()
+                : '';
+            if (terminalId)
+                await state.journal.exclusive(`terminal:${terminalId}`, accept);
+            else
+                await accept();
+        }
+        else
+            await accept();
+    };
+    // Production admission and maintenance use this same lock before checking durable occupancy.
+    if (occupiesDirectory && state.config.workspaceMode === 'multi')
+        await state.journal.exclusive(`directory:${parsed.data.workspaceId}:${parsed.data.directoryName ?? 'basic'}`, acceptBound);
+    else
+        await acceptBound();
+}
+async function writeGitRead(state, response, read) {
+    if (writeDestroyed(state, response))
+        return;
+    if (!state.gitAvailable) {
+        writeError(response, runtimeError('capability_unavailable', 'git_binary_missing'));
+        return;
+    }
+    try {
+        writeJson(response, 200, await read());
+    }
+    catch (error) {
+        if (error instanceof GitWorkspaceError && error.code === 'invalid_workspace_path') {
+            writeJson(response, 400, { error: 'invalid_workspace_path' });
+            return;
+        }
+        const reason = error instanceof GitWorkspaceError ? error.code : 'git_command_failed';
+        writeError(response, runtimeError('capability_unavailable', reason));
+    }
+}
+async function readJson(request, maxBytes = Infinity) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > maxBytes)
+            throw new Error('request_body_too_large');
+        chunks.push(bytes);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeDestroyed(state, response) {
+    if (!state.journal.destroyed())
+        return false;
+    writeError(response, runtimeError('capability_unavailable', 'runtime_destroyed'));
+    return true;
+}
+async function handleTerminalIdentity(state, request, response, remainder) {
+    if (writeDestroyed(state, response))
+        return;
+    const [terminalId, action] = remainder.split('/');
+    if (!terminalId || action && action !== 'connect') {
+        writeJson(response, 404, { error: 'not_found' });
+        return;
+    }
+    const terminal = state.journal.getTerminal(terminalId);
+    if (!terminal) {
+        writeJson(response, 404, { error: 'terminal_not_found' });
+        return;
+    }
+    if (request.method === 'GET' && action === 'connect') {
+        if (terminal.status === 'destroyed') {
+            writeError(response, runtimeError('capability_unavailable', 'terminal_destroyed'));
+            return;
+        }
+        writeError(response, runtimeError('capability_unavailable', 'websocket_required'));
+        return;
+    }
+    if (request.method === 'GET' && !action) {
+        writeJson(response, 200, terminal);
+        return;
+    }
+    if (request.method === 'DELETE' && !action) {
+        try {
+            const destroyed = await terminalHost(state).destroy(terminalId);
+            writeJson(response, 200, { terminalId: destroyed.terminalId, status: destroyed.status });
+        }
+        catch {
+            writeError(response, runtimeError('capability_unavailable', 'terminal_stop_unconfirmed'));
+        }
+        return;
+    }
+    writeJson(response, 404, { error: 'not_found' });
+}
+function unavailableReason(state, kind) {
+    if (state.journal.destroyed())
+        return 'runtime_destroyed';
+    return state.nativeError ?? 'adapter_not_started';
+}
+function sessionHistoryPath(pathname) {
+    const match = pathname.match(/^\/runtime\/workspaces\/([^/]+)\/sessions\/([^/]+)\/history$/);
+    if (!match?.[1] || !match[2])
+        return undefined;
+    try {
+        return {
+            workspaceId: decodeURIComponent(match[1]),
+            sessionId: decodeURIComponent(match[2]),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isUnimplementedWorkbenchPath(pathname) {
+    const parts = pathname.split('/').filter(Boolean);
+    return parts[0] === 'runtime' && parts.includes('previews');
+}
+async function handleSessionHistory(state, response, workspaceId, sessionId) {
+    if (writeDestroyed(state, response))
+        return;
+    const session = state.journal.getSession(sessionId);
+    if (!session || (session.workspaceId && session.workspaceId !== workspaceId)) {
+        writeJson(response, 404, { error: 'session_not_found' });
+        return;
+    }
+    if (state.config.workspaceMode === 'multi' && session.workspaceId !== workspaceId) {
+        writeJson(response, 404, { error: 'session_not_found' });
+        return;
+    }
+    const readThread = state.native?.readThread;
+    if (!readThread) {
+        writeError(response, runtimeError('capability_unavailable', 'native_history_unavailable'));
+        return;
+    }
+    let read;
+    try {
+        read = await readThread({ threadId: session.threadId, sessionId });
+    }
+    catch {
+        writeError(response, runtimeError('capability_unavailable', 'native_history_unavailable'));
+        return;
+    }
+    if (!read || read.threadId !== session.threadId) {
+        writeError(response, runtimeError('capability_unavailable', 'native_history_unavailable'));
+        return;
+    }
+    const body = nativeHistoryReadSchema.safeParse({
+        source: 'native',
+        sessionId,
+        workspaceId,
+        threadId: read.threadId,
+        ...(read.threadName ? { threadName: read.threadName } : {}),
+        truncated: read.truncated,
+        items: read.items,
+    });
+    if (!body.success) {
+        writeError(response, runtimeError('capability_unavailable', 'native_history_unavailable'));
+        return;
+    }
+    writeJson(response, 200, body.data);
+}
+async function readObservedParameters(state, workspaceId, directoryName = 'basic') {
+    const root = await workspaceRoot(state, workspaceId, directoryName);
+    const scope = revisionScope(state, workspaceId, directoryName);
+    const first = await readWorkspaceParameters(root, state.journal.fileRevisions(scope));
+    for (const path of [first.schemaPath, first.dataPath]) {
+        if (path)
+            await withObservedFile(state, workspaceId, path, async () => undefined, directoryName);
+    }
+    return readWorkspaceParameters(root, state.journal.fileRevisions(scope));
+}
+function writeError(response, error) {
+    writeJson(response, HTTP_STATUS_BY_ERROR[error.code], error);
+}
+function writeJson(response, status, body) {
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(payload),
+    });
+    response.end(payload);
+}
+function authorizeRuntime(state, request) {
+    const presented = extractControlToken(request.headers);
+    if (controlTokenMatches(state.config.controlToken, presented))
+        return 'control';
+    const dedicated = headerValue(request.headers['x-playcraft-source-read-token']);
+    const candidate = dedicated || presented;
+    if (candidate && controlTokenMatches(state.journal.sourceReadToken(), candidate))
+        return 'read';
+    return null;
+}
+function readSourcePath(method, pathname) {
+    if (method === 'GET' && pathname === '/runtime/events')
+        return true;
+    if (method === 'POST' && pathname === '/runtime/events/replay-pins')
+        return true;
+    if (method === 'DELETE' && pathname.startsWith('/runtime/events/replay-pins/'))
+        return true;
+    return false;
+}
+async function handleSourceEvents(state, request, response, url) {
+    if (request.method === 'POST' && url.pathname === '/runtime/events/replay-pins') {
+        const pin = await state.journal.createReplayPin({
+            runtimeId: state.config.runtimeId,
+            generation: state.config.generation,
+            runtimeEpoch: state.runtimeEpoch,
+            ttlMs: Number(asRecord(await readJson(request)).ttlMs) || undefined,
+        });
+        writeJson(response, 201, pin);
+        return;
+    }
+    if (request.method === 'DELETE' && url.pathname.startsWith('/runtime/events/replay-pins/')) {
+        await state.journal.deleteReplayPin(decodeURIComponent(url.pathname.slice('/runtime/events/replay-pins/'.length)));
+        writeJson(response, 200, { deleted: true });
+        return;
+    }
+    if (request.method === 'POST' && url.pathname === '/runtime/events/ack') {
+        const parsed = sourceAckSchema.safeParse(await readJson(request));
+        if (!parsed.success) {
+            writeJson(response, 400, { error: 'invalid_source_ack' });
+            return;
+        }
+        try {
+            await state.journal.acknowledgeSource(parsed.data);
+            state.acceptedLeaseFence = Math.max(state.acceptedLeaseFence, state.journal.acceptedLeaseFence());
+            wakeSourceEventUploader(state);
+        }
+        catch (error) {
+            writeJson(response, 409, { code: error instanceof Error ? error.message : 'ack_rejected' });
+            return;
+        }
+        writeJson(response, 200, { ok: true, acceptedLeaseFence: state.journal.acceptedLeaseFence() });
+        return;
+    }
+    if (request.method === 'GET' && url.pathname === '/runtime/events') {
+        const after = Number(url.searchParams.get('after') ?? '0');
+        const safeAfter = Number.isInteger(after) && after >= 0 ? after : 0;
+        const epochQuery = url.searchParams.get('runtimeEpoch');
+        const runtimeEpoch = epochQuery === null ? state.runtimeEpoch : Number(epochQuery);
+        const runtimeId = url.searchParams.get('runtimeId') ?? state.config.runtimeId;
+        const generation = Number(url.searchParams.get('generation') ?? state.config.generation);
+        if (runtimeId !== state.config.runtimeId || generation !== state.config.generation || !Number.isInteger(runtimeEpoch) || runtimeEpoch < 0) {
+            writeJson(response, 403, { error: 'source_identity_mismatch' });
+            return;
+        }
+        const query = {
+            runtimeId,
+            generation,
+            runtimeEpoch,
+            after: safeAfter,
+        };
+        if (!state.journal.epochsSnapshot().some(epoch => epoch.runtime_id === runtimeId && epoch.generation === generation && epoch.runtime_epoch === runtimeEpoch)) {
+            writeJson(response, 409, { code: 'source_gap', retainedFrom: 1, highWater: 0, coveredThrough: safeAfter });
+            return;
+        }
+        if (String(request.headers.accept ?? '').includes('text/event-stream')) {
+            writeSourceStream(state, request, response, query);
+            return;
+        }
+        if (epochQuery === null && !url.searchParams.has('runtimeId') && !url.searchParams.has('generation')) {
+            const events = state.journal.listEvents(safeAfter);
+            const page = state.journal.readSourcePage({ ...query, limit: 1 });
+            writeJson(response, 200, {
+                events,
+                retainedFrom: page.ok ? page.retainedFrom : page.retainedFrom,
+                highWater: page.ok ? page.highWater : page.highWater,
+                nextAfter: events.at(-1)?.source.sourceSequence ?? safeAfter,
+                runtimeId: query.runtimeId,
+                generation: query.generation,
+                runtimeEpoch: query.runtimeEpoch,
+            });
+            return;
+        }
+        const page = state.journal.readSourcePage(query);
+        if (!page.ok) {
+            writeJson(response, 409, {
+                code: page.code,
+                retainedFrom: page.retainedFrom,
+                highWater: page.highWater,
+                coveredThrough: page.coveredThrough,
+            });
+            return;
+        }
+        writeJson(response, 200, {
+            events: page.events,
+            retainedFrom: page.retainedFrom,
+            highWater: page.highWater,
+            nextAfter: page.nextAfter,
+            runtimeId: page.runtimeId,
+            generation: page.generation,
+            runtimeEpoch: page.runtimeEpoch,
+        });
+        return;
+    }
+    writeJson(response, 404, { error: 'not_found' });
+}
+function writeSourceStream(state, request, response, query) {
+    let cursor = query.after;
+    const buffered = [];
+    const matches = (event) => event.source.runtimeId === query.runtimeId &&
+        event.source.generation === query.generation &&
+        event.source.runtimeEpoch === query.runtimeEpoch &&
+        event.source.sourceSequence > cursor;
+    const unsubscribe = state.journal.onSourceEvent((event) => {
+        if (matches(event))
+            buffered.push(event);
+    });
+    const page = state.journal.readSourcePage({ ...query, limit: 500 });
+    response.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+    });
+    const writeEvent = (name, data) => {
+        response.write(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    if (!page.ok) {
+        writeEvent('source.gap', {
+            code: page.code,
+            retainedFrom: page.retainedFrom,
+            highWater: page.highWater,
+            coveredThrough: page.coveredThrough,
+        });
+        response.end();
+        unsubscribe();
+        return;
+    }
+    writeEvent('source.ready', {
+        runtimeId: page.runtimeId,
+        generation: page.generation,
+        runtimeEpoch: page.runtimeEpoch,
+        retainedFrom: page.retainedFrom,
+        highWater: page.highWater,
+        nextAfter: page.nextAfter,
+    });
+    for (const event of page.events) {
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    }
+    for (const event of buffered) {
+        if (!matches(event))
+            continue;
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    }
+    unsubscribe();
+    const follow = state.journal.onSourceEvent((event) => {
+        if (!matches(event))
+            return;
+        writeEvent('source', event);
+        cursor = event.source.sourceSequence;
+    });
+    const heartbeat = setInterval(() => {
+        response.write(`: ping\n\n`);
+    }, 10_000);
+    heartbeat.unref?.();
+    const stop = () => {
+        clearInterval(heartbeat);
+        follow();
+    };
+    request.on('close', stop);
+    response.on('close', stop);
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}