@mrpatronz/nexusflow 2.8.1 → 2.10.0

package/dist/server.js

@@ -6,19 +6,19 @@ import { Hono } from 'hono';
 import { serve } from '@hono/node-server';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { cors } from 'hono/cors';
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
 import { streamSSE } from 'hono/streaming';
 import { createNodeWebSocket } from '@hono/node-ws';
 import * as fs from 'node:fs/promises';
-import { createWriteStream, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execa } from 'execa';
 import * as os from 'node:os';
 import { createHash } from 'node:crypto';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { spawn } from 'node:child_process';
 import { loadConfig, saveConfig, getConfigDir } from './core/config.js';
+import { saveChatThread, loadChatThread, clearChatThread } from './storage/db.js';
+import { PRIMARY_LOGS_DIR, LEGACY_LOGS_DIR, WORKROOM_BOOTSTRAP_HEADERS, WORKROOM_BOOTSTRAP_COOKIES, ENGINE_ID, LEGACY_ENGINE_ID, ENGINE_NPM_PACKAGE, LEGACY_ENGINE_NPM_PACKAGE, resolveWorkspaceChatLedger, readWorkspaceChatMessages, } from './core/constants.js';
 import { configPatchSchema } from './core/config-schema.js';
 import { listStorageProviders } from './core/adapters/registry.js';
 import { scanForRepos } from './core/scanner.js';
@@ -35,9 +35,10 @@ import { detectEditors } from './utils/detect-editors.js';
 import { buildWorkspaceLaunchPrompt, detectWorkspaceLaunchTargets, launchTargetIdForEditorCommand, launchWorkspaceTarget, } from './utils/workspace-launch.js';
 import { isBinaryOnPath, launchWorkspaceTerminal, SUPPORTED_ASSISTANTS } from './utils/terminal-launch.js';
 import { openInEditor } from './utils/open-editor.js';
-import { canOpenCodexSessionInWorkspace, canTransferClaudeSessionInWorkspace, findSessions, getSessionTranscript, } from './utils/session-finder.js';
+import { canOpenCodexSessionInWorkspace, canTransferClaudeSessionInWorkspace, findActiveAssistants, findSessions, getSessionTranscript, } from './utils/session-finder.js';
 import { ProviderRegistry } from './agent/adapters.js';
 import { isValidSessionUuid } from './agent/session.js';
+import { defaultTurnSessionManager, AgentTurnGate, dispatchAgentInput } from './agent/TurnSessionManager.js';
 import { getRepoStatus } from './utils/multi-git.js';
 import { syncWorkspace } from './core/sync.js';
 import { commitWorkspace } from './core/commit.js';
@@ -54,6 +55,12 @@ import { deleteAgent, getAllAgents, importAgentToml, saveAgent, } from './resour
 import { ResourceConflictError } from './resources/materializer.js';
 import { ResourceSelectionError, validateResourceSelections, withResourceAdministrationLock, } from './resources/service.js';
 import { suggestWorkflow } from './utils/workflow-advisor.js';
+import { WorkroomAuthorizationError, WorkroomRevisionError, WorkroomValidationError, documentNameSchema, workflowStepSchema, } from './workrooms/contracts.js';
+import { listWorkroomNetworkInterfaces } from './workrooms/host.js';
+import * as workroomManagerModule from './workrooms/manager.js';
+const { workroomManager } = workroomManagerModule;
+import { buildPortableWorkroomPreview, digestPortableWorkroomContext } from './workrooms/portable.js';
+import { randomToken, tokenDigest } from './workrooms/crypto.js';
 // Resolve static files directory
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -73,34 +80,7 @@ function hasTrustedLocalOrigin(origin) {
         return false;
     }
 }
-/** Validate and dispatch one renderer turn without letting malformed authority reach a harness. */
-export function dispatchAgentInput(agent, provider, payload) {
-    if (typeof payload.input !== 'string' || !payload.input.trim()) {
-        return 'A non-empty input message is required.';
-    }
-    const executionProfile = ProviderRegistry.resolveExecutionProfile(provider, payload.executionProfile);
-    if (executionProfile === null) {
-        return 'Select a supported execution profile before sending this turn.';
-    }
-    void agent.send(payload.input, executionProfile);
-    return null;
-}
-/** Per-socket admission guard so a second prompt is rejected, never dropped. */
-export class AgentTurnGate {
-    active = false;
-    tryBegin() {
-        if (this.active)
-            return false;
-        this.active = true;
-        return true;
-    }
-    settle() {
-        this.active = false;
-    }
-    isActive() {
-        return this.active;
-    }
-}
+export { dispatchAgentInput, AgentTurnGate };
 app.get('/ws', async (c, next) => {
     // Prevent Cross-Site WebSocket Hijacking (CSWSH)
     const origin = c.req.header('origin');
@@ -123,11 +103,11 @@ app.get('/ws', async (c, next) => {
     //                     | {type:'rejected', reason:'busy', message, turnId?}
     //                     | {type:'close', code} | {type:'pong'}
     return upgradeWebSocket((c) => {
-        let agent = null;
-        let activeProvider = null;
-        const turnGate = new AgentTurnGate();
+        let currentCwd = null;
+        let currentWs = null;
         return {
             async onMessage(event, ws) {
+                currentWs = ws;
                 if (typeof event.data === 'string') {
                     if (event.data === 'ping') {
                         ws.send(JSON.stringify({ type: 'pong' }));
@@ -139,35 +119,24 @@ app.get('/ws', async (c, next) => {
                             ws.send(JSON.stringify({ type: 'pong' }));
                         }
                         else if (payload.type === 'start') {
-                            turnGate.settle();
-                            if (agent) {
-                                const previousAgent = agent;
-                                agent = null;
-                                activeProvider = null;
-                                previousAgent.stop();
+                            const command = payload.command;
+                            const cwd = payload.cwd;
+                            if (typeof cwd !== 'string' || !cwd.trim()) {
+                                ws.send(JSON.stringify({ type: 'error', message: 'Workspace directory cwd is required.' }));
+                                return;
                             }
-                            const provider = ProviderRegistry.getProvider(payload.command);
+                            const provider = ProviderRegistry.getProvider(command);
                             if (!provider) {
-                                ws.send(JSON.stringify({ type: 'error', message: `No provider found for ${payload.command}. Please create a dedicated adapter.` }));
+                                ws.send(JSON.stringify({ type: 'error', message: `No provider found for ${command}. Please create a dedicated adapter.` }));
                                 return;
                             }
                             const config = await loadConfig();
-                            if (typeof payload.cwd !== 'string' || !payload.cwd.trim()) {
-                                ws.send(JSON.stringify({ type: 'error', message: 'Workspace directory cwd is required.' }));
-                                return;
-                            }
-                            const safeCwd = await resolveExactLaunchWorkspace(config.workspacesDir, payload.cwd);
+                            const safeCwd = await resolveExactLaunchWorkspace(config.workspacesDir, cwd);
                             if (!safeCwd) {
                                 ws.send(JSON.stringify({ type: 'error', message: 'Invalid or uncontained workspace directory.' }));
                                 return;
                             }
-                            const freshness = await checkGenerationLock(safeCwd, { markDocuments: true });
-                            if (!freshness.fresh) {
-                                ws.send(JSON.stringify({
-                                    type: 'system',
-                                    message: `⚠ NexusFlow generated context is stale or drifted. ${freshness.drift.map((item) => item.message).join(' ')}`,
-                                }));
-                            }
+                            currentCwd = safeCwd;
                             let session;
                             const model = ProviderRegistry.resolveModel(provider, payload.model);
                             if (model === null) {
@@ -177,120 +146,95 @@ app.get('/ws', async (c, next) => {
                                 }));
                                 return;
                             }
+                            const effort = typeof payload.effort === 'string' && payload.effort.trim() ? payload.effort.trim() : undefined;
                             if (payload.sessionId !== undefined && payload.sessionId !== null) {
                                 if (!isValidSessionUuid(payload.sessionId)) {
                                     ws.send(JSON.stringify({ type: 'error', message: 'Invalid session id.' }));
                                     return;
                                 }
-                                session = { id: payload.sessionId, resume: Boolean(payload.resume), model };
+                                session = { id: payload.sessionId, resume: Boolean(payload.resume), model, effort };
                             }
-                            else if (model) {
-                                session = { id: crypto.randomUUID(), resume: false, model };
+                            else if (model || effort) {
+                                session = { id: crypto.randomUUID(), resume: false, model, effort };
                             }
-                            const startedAgent = provider.createInstance();
-                            agent = startedAgent;
-                            activeProvider = provider;
-                            const isCurrentAgent = () => agent === startedAgent;
-                            startedAgent.on('data', (text) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                ws.send(JSON.stringify({ type: 'stream', text }));
+                            await defaultTurnSessionManager.startSession({
+                                workspaceCwd: safeCwd,
+                                command,
+                                client: ws,
+                                provider,
+                                session,
                             });
-                            startedAgent.on('system', (message) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                ws.send(JSON.stringify({ type: 'system', message }));
-                            });
-                            startedAgent.on('session', (id) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                // Provider output is still boundary input. Only inert UUIDs
-                                // may be persisted by the renderer and sent back in argv.
-                                if (isValidSessionUuid(id)) {
-                                    ws.send(JSON.stringify({ type: 'session', id }));
-                                }
-                            });
-                            startedAgent.on('idle', () => {
-                                if (!isCurrentAgent())
-                                    return;
-                                turnGate.settle();
-                                ws.send(JSON.stringify({ type: 'status', state: 'idle' }));
-                            });
-                            startedAgent.on('close', (code) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                turnGate.settle();
-                                ws.send(JSON.stringify({ type: 'close', code }));
-                            });
-                            startedAgent.on('usage', (usage) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                ws.send(JSON.stringify({ type: 'usage', usage }));
-                            });
-                            startedAgent.on('error', (error) => {
-                                if (!isCurrentAgent())
-                                    return;
-                                ws.send(JSON.stringify({ type: 'error', message: error?.message ?? String(error) }));
-                            });
-                            startedAgent.start(safeCwd, session);
                         }
                         else if (payload.type === 'input') {
-                            if (agent && activeProvider) {
-                                if (!turnGate.tryBegin()) {
-                                    const turnId = isValidSessionUuid(payload.turnId) ? payload.turnId : undefined;
-                                    ws.send(JSON.stringify({
-                                        type: 'rejected',
-                                        reason: 'busy',
-                                        message: 'The agent is still processing the current turn.',
-                                        ...(turnId ? { turnId } : {}),
-                                    }));
-                                    return;
-                                }
-                                const error = dispatchAgentInput(agent, activeProvider, payload);
-                                if (error) {
-                                    turnGate.settle();
-                                    ws.send(JSON.stringify({ type: 'error', message: error }));
+                            const cwd = typeof payload.cwd === 'string' ? payload.cwd : currentCwd;
+                            if (!cwd) {
+                                ws.send(JSON.stringify({
+                                    type: 'error',
+                                    message: 'No active agent session. Please start or reconnect the agent.',
+                                }));
+                                return;
+                            }
+                            const config = await loadConfig();
+                            const safeCwd = await resolveExactLaunchWorkspace(config.workspacesDir, cwd);
+                            if (!safeCwd) {
+                                ws.send(JSON.stringify({ type: 'error', message: 'Invalid workspace directory.' }));
+                                return;
+                            }
+                            currentCwd = safeCwd;
+                            const existingSession = defaultTurnSessionManager.getSession(safeCwd);
+                            if (!existingSession) {
+                                const command = typeof payload.command === 'string' ? payload.command : 'antigravity-cli';
+                                const provider = ProviderRegistry.getProvider(command);
+                                if (!provider) {
+                                    ws.send(JSON.stringify({ type: 'error', message: `No provider found for ${command}.` }));
                                     return;
                                 }
-                                // Some harness validation failures emit error + idle
-                                // synchronously from send(); do not overwrite that settled
-                                // state with a late busy frame.
-                                if (turnGate.isActive()) {
-                                    const turnId = isValidSessionUuid(payload.turnId) ? payload.turnId : undefined;
-                                    ws.send(JSON.stringify({
-                                        type: 'accepted',
-                                        ...(turnId ? { turnId } : {}),
-                                    }));
-                                    ws.send(JSON.stringify({ type: 'status', state: 'busy' }));
-                                }
+                                await defaultTurnSessionManager.startSession({
+                                    workspaceCwd: safeCwd,
+                                    command,
+                                    client: ws,
+                                    provider,
+                                });
+                            }
+                            const result = defaultTurnSessionManager.dispatchInput(safeCwd, payload);
+                            if (result.error) {
+                                ws.send(JSON.stringify({ type: 'error', message: result.error }));
+                            }
+                            else if (result.rejected) {
+                                const turnId = isValidSessionUuid(payload.turnId) ? payload.turnId : undefined;
+                                ws.send(JSON.stringify({
+                                    type: 'rejected',
+                                    reason: 'busy',
+                                    message: 'The agent is still processing the current turn.',
+                                    ...(turnId ? { turnId } : {}),
+                                }));
+                            }
+                        }
+                        else if (payload.type === 'approval_response') {
+                            if (currentCwd) {
+                                const requestId = typeof payload.requestId === 'string' ? payload.requestId : '';
+                                const decision = payload.decision === 'allow' ? 'allow' : 'deny';
+                                const message = typeof payload.message === 'string' ? payload.message : undefined;
+                                defaultTurnSessionManager.respondToApproval(currentCwd, requestId, decision, message);
                             }
                         }
                         else if (payload.type === 'stop') {
-                            turnGate.settle();
-                            if (agent) {
-                                const stoppedAgent = agent;
-                                agent = null;
-                                activeProvider = null;
-                                stoppedAgent.stop();
+                            if (currentCwd) {
+                                defaultTurnSessionManager.stopSession(currentCwd);
                             }
                         }
                     }
                     catch (err) {
-                        console.error('[WS] Failed to parse message', err);
+                        console.error('Error handling WebSocket message:', err);
                     }
                 }
             },
-            onOpen(_event, _ws) {
-                console.log('[WS] Client connected');
+            onOpen(_event, ws) {
+                currentWs = ws;
             },
-            onClose(_event, _ws) {
-                console.log('[WS] Client disconnected');
-                turnGate.settle();
-                if (agent) {
-                    const disconnectedAgent = agent;
-                    agent = null;
-                    activeProvider = null;
-                    disconnectedAgent.stop();
+            onClose(_event, ws) {
+                if (currentCwd && ws) {
+                    defaultTurnSessionManager.unregisterClient(currentCwd, ws);
                 }
             },
         };
@@ -401,6 +345,19 @@ function errorResponse(c, error) {
             missingAgents: error.missingAgents,
         }, 400);
     }
+    if (error instanceof WorkroomAuthorizationError) {
+        return c.json({ error: error.message }, 401);
+    }
+    if (error instanceof WorkroomRevisionError) {
+        return c.json({
+            error: error.message,
+            expectedRevision: error.expected,
+            actualRevision: error.actual,
+        }, 409);
+    }
+    if (error instanceof WorkroomValidationError) {
+        return c.json({ error: error.message }, 400);
+    }
     const msg = error instanceof Error ? error.message : String(error);
     return c.json({ error: msg }, 500);
 }
@@ -431,35 +388,18 @@ async function findResourceAssignments(workspacesDir, resourceId, kind) {
     }
     return assignments;
 }
-/**
- * Restrict the self-update download to GitHub release hosts over HTTPS so a
- * cross-origin caller cannot make the server fetch and later execute an
- * arbitrary binary.
- */
-export function isAllowedUpdateUrl(candidate) {
-    try {
-        const url = new URL(candidate);
-        if (url.protocol !== 'https:')
-            return false;
-        const host = url.hostname.toLowerCase();
-        if (host === 'github.com') {
-            return url.pathname.includes('/releases/download/');
-        }
-        return (host === 'objects.githubusercontent.com' ||
-            host === 'github-releases.githubusercontent.com');
-    }
-    catch {
-        return false;
-    }
-}
 // Enable CORS for the local GUI only. This server can spawn processes, run
 // package installs and delete worktrees, so a wildcard origin would let any
 // web page the developer has open drive it cross-origin.
 app.use('/api/*', cors({
-    origin: (origin) => {
+    credentials: true,
+    origin: (origin, c) => {
         // No Origin header → same-origin or a non-browser client (CLI/desktop).
         if (!origin)
             return origin;
+        if (c.req.path.startsWith('/api/workrooms/')) {
+            return hasExactDashboardOrigin(origin, c.req.url) ? origin : null;
+        }
         try {
             const { hostname } = new URL(origin);
             const isLocal = hostname === 'localhost' ||
@@ -493,10 +433,18 @@ app.use('*', async (c, next) => {
 // cross-site request forgery and browser form posts from untrusted web pages.
 app.use('/api/*', async (c, next) => {
     if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(c.req.method)) {
+        const secFetchSite = c.req.header('sec-fetch-site');
+        if (secFetchSite === 'cross-site') {
+            return c.json({ error: 'Forbidden cross-site request.' }, 403);
+        }
         const origin = c.req.header('origin');
         if (origin && !hasTrustedLocalOrigin(origin)) {
             return c.json({ error: 'Forbidden cross-origin request.' }, 403);
         }
+        const referer = c.req.header('referer');
+        if (referer && !hasTrustedLocalOrigin(referer)) {
+            return c.json({ error: 'Forbidden cross-origin referer.' }, 403);
+        }
     }
     await next();
 });
@@ -525,6 +473,116 @@ app.post('/api/adapters/status/refresh', async (c) => {
     }
     return c.json(ProviderRegistry.getAllStatus({ refreshProviderId: providerId }));
 });
+app.post('/api/chat/upload-attachment', async (c) => {
+    if (!hasTrustedLocalOrigin(c.req.header('origin'))) {
+        return c.json({ error: 'A local browser origin is required.' }, 403);
+    }
+    try {
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body.dataUrl !== 'string' || !body.dataUrl.startsWith('data:image/')) {
+            return c.json({ error: 'A valid image dataUrl is required.' }, 400);
+        }
+        const matches = body.dataUrl.match(/^data:image\/([a-zA-Z0-9+.-]+);base64,(.+)$/);
+        if (!matches) {
+            return c.json({ error: 'Malformed image dataUrl format.' }, 400);
+        }
+        const MAX_ATTACHMENT_BASE64_CHARS = Math.ceil((20 * 1024 * 1024 * 4) / 3);
+        if (matches[2].length > MAX_ATTACHMENT_BASE64_CHARS) {
+            return c.json({ error: 'Image attachment exceeds maximum allowed size of 20MB.' }, 413);
+        }
+        const rawExt = matches[1].toLowerCase();
+        const ext = rawExt === 'jpeg' ? 'jpg' : rawExt.replace(/[^a-zA-Z0-9]/g, '') || 'png';
+        const buffer = Buffer.from(matches[2], 'base64');
+        const imageId = crypto.randomUUID();
+        const config = await loadConfig();
+        const workspaceDir = typeof body.workspacePath === 'string'
+            ? await resolveExactLaunchWorkspace(config.workspacesDir, body.workspacePath)
+            : null;
+        const targetDir = workspaceDir
+            ? path.join(workspaceDir, '.nexusflow', 'attachments')
+            : path.join(getConfigDir(), 'attachments');
+        await fs.mkdir(targetDir, { recursive: true });
+        const targetFile = path.join(targetDir, `${imageId}.${ext}`);
+        await fs.writeFile(targetFile, buffer);
+        return c.json({
+            id: imageId,
+            filename: typeof body.filename === 'string' ? body.filename : `image-${imageId}.${ext}`,
+            path: targetFile,
+            size: buffer.length,
+        });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/chat/thread/:workspaceId', async (c) => {
+    const workspaceId = c.req.param('workspaceId');
+    if (!workspaceId) {
+        return c.json({ error: 'workspaceId is required' }, 400);
+    }
+    try {
+        const thread = loadChatThread(workspaceId);
+        const config = await loadConfig().catch(() => null);
+        let isBusy = false;
+        if (config) {
+            try {
+                const workspacePath = resolveWorkspacePath(config.workspacesDir, workspaceId);
+                isBusy = defaultTurnSessionManager.hasActiveTurn(workspacePath);
+            }
+            catch {
+                // Workspace not found on disk or invalid
+            }
+        }
+        return c.json({ thread, isBusy });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/chat/thread/:workspaceId', async (c) => {
+    if (!hasTrustedLocalOrigin(c.req.header('origin'))) {
+        return c.json({ error: 'A local browser origin is required.' }, 403);
+    }
+    const workspaceId = c.req.param('workspaceId');
+    if (!workspaceId) {
+        return c.json({ error: 'workspaceId is required' }, 400);
+    }
+    try {
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body !== 'object') {
+            return c.json({ error: 'Valid chat thread payload is required.' }, 400);
+        }
+        saveChatThread({
+            workspaceId,
+            providerId: typeof body.providerId === 'string' ? body.providerId : null,
+            sessions: typeof body.sessions === 'object' && body.sessions !== null ? body.sessions : {},
+            profilesByProvider: typeof body.profilesByProvider === 'object' && body.profilesByProvider !== null ? body.profilesByProvider : {},
+            modelsByProvider: typeof body.modelsByProvider === 'object' && body.modelsByProvider !== null ? body.modelsByProvider : {},
+            effortsByProvider: typeof body.effortsByProvider === 'object' && body.effortsByProvider !== null ? body.effortsByProvider : {},
+            messages: Array.isArray(body.messages) ? body.messages : [],
+        });
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.delete('/api/chat/thread/:workspaceId', async (c) => {
+    if (!hasTrustedLocalOrigin(c.req.header('origin'))) {
+        return c.json({ error: 'A local browser origin is required.' }, 403);
+    }
+    const workspaceId = c.req.param('workspaceId');
+    if (!workspaceId) {
+        return c.json({ error: 'workspaceId is required' }, 400);
+    }
+    try {
+        clearChatThread(workspaceId);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
 // 1. Get current configuration
 app.get('/api/config', async (c) => {
     try {
@@ -736,6 +794,7 @@ app.get('/api/workspaces/status', async (c) => {
                 runningServices: 0,
                 syncStatus: 'unknown',
                 pendingValidation: false,
+                activeAssistants: [],
             };
             try {
                 // Uncommitted changes across the workspace's repos: worktrees inside
@@ -758,6 +817,8 @@ app.get('/api/workspaces/status', async (c) => {
                 const repoStates = Object.values(wsState.repos);
                 status.syncStatus = worstSyncStatus(repoStates);
                 status.pendingValidation = repoStates.some((r) => r.pendingValidation);
+                // Active AI assistant sessions
+                status.activeAssistants = await findActiveAssistants(workspacePath, ws.repos);
             }
             catch {
                 // Leave defaults on any per-workspace failure so one bad repo doesn't
@@ -1126,7 +1187,6 @@ app.post('/api/workspace/:id/isolate', async (c) => {
 app.post('/api/workspace/suggest-workflow', async (c) => {
     try {
         const { description, repos } = await c.req.json();
-        const config = await loadConfig();
         const suggestion = await suggestWorkflow(description, repos);
         return c.json({
             success: true,
@@ -1332,6 +1392,15 @@ app.get('/api/workspace/:id/services', async (c) => {
         return errorResponse(c, error);
     }
 });
+function getWorkspaceLogDir(workspacePath) {
+    const primary = path.join(workspacePath, PRIMARY_LOGS_DIR);
+    const legacy = path.join(workspacePath, LEGACY_LOGS_DIR);
+    if (existsSync(primary))
+        return primary;
+    if (existsSync(legacy))
+        return legacy;
+    return primary;
+}
 // 10. Start services in workspace. Configs are re-detected server-side —
 // the client only says "start", never what to execute.
 app.post('/api/workspace/:id/services/start', async (c) => {
@@ -1339,7 +1408,7 @@ app.post('/api/workspace/:id/services/start', async (c) => {
         const id = c.req.param('id');
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const logDir = path.join(workspacePath, '.nexusflow-logs');
+        const logDir = getWorkspaceLogDir(workspacePath);
         const services = await detectAllServices(workspacePath);
         await startServices(services, workspacePath, logDir);
         return c.json({ success: true });
@@ -1370,7 +1439,7 @@ app.post('/api/workspace/:id/services/:serviceName/:action{start|stop|restart}',
         const action = c.req.param('action');
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const logDir = path.join(workspacePath, '.nexusflow-logs');
+        const logDir = getWorkspaceLogDir(workspacePath);
         if (action === 'stop') {
             const stopped = await stopService(workspacePath, serviceName);
             return c.json({ success: true, stopped });
@@ -1391,7 +1460,7 @@ app.post('/api/workspace/:id/services/:serviceName/:action{start|stop|restart}',
 });
 /** Resolve + contain a service log path; names may contain '/' (repo/sub). */
 function resolveServiceLogFile(workspacePath, serviceName) {
-    const logDir = path.join(workspacePath, '.nexusflow-logs');
+    const logDir = getWorkspaceLogDir(workspacePath);
     return assertWithin(logDir, path.join(logDir, `${serviceName}.log`));
 }
 // 12. Get service logs (backfill). Returns the trailing 50KB and the byte
@@ -1406,14 +1475,18 @@ app.get('/api/workspace/:id/services/logs/:serviceName', async (c) => {
         let content = '';
         let size = 0;
         try {
-            const stats = await fs.stat(logFile);
-            size = stats.size;
-            const start = Math.max(0, size - 50000);
             const fd = await fs.open(logFile, 'r');
-            const buffer = Buffer.alloc(size - start);
-            await fd.read(buffer, 0, buffer.length, start);
-            await fd.close();
-            content = buffer.toString('utf-8');
+            try {
+                const stats = await fd.stat();
+                size = stats.size;
+                const start = Math.max(0, size - 50000);
+                const buffer = Buffer.alloc(size - start);
+                await fd.read(buffer, 0, buffer.length, start);
+                content = buffer.toString('utf-8');
+            }
+            finally {
+                await fd.close();
+            }
         }
         catch {
             content = 'No logs available yet.';
@@ -1482,7 +1555,7 @@ app.post('/api/workspace/:id/orchestrators/:action{start|stop}', async (c) => {
         }
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const logDir = path.join(workspacePath, '.nexusflow-logs');
+        const logDir = getWorkspaceLogDir(workspacePath);
         const tools = await detectOrchestrationTools(workspacePath);
         const detection = tools.find((t) => t.id === body.id);
         if (!detection) {
@@ -1641,6 +1714,214 @@ app.get('/api/workspace/:id/changes/diff', async (c) => {
         return errorResponse(c, error);
     }
 });
+// 13b. Revert changes to specific files in workspace sub-repositories
+app.post('/api/workspace/:id/changes/revert', async (c) => {
+    if (!hasTrustedLocalOrigin(c.req.header('origin'))) {
+        return c.json({ error: 'A local browser origin is required.' }, 403);
+    }
+    try {
+        const id = c.req.param('id');
+        const body = await c.req.json().catch(() => null);
+        const files = Array.isArray(body?.files) ? body.files.filter((f) => typeof f === 'string' && f.trim().length > 0) : [];
+        if (files.length === 0) {
+            return c.json({ error: 'Missing files array in request body.' }, 400);
+        }
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        const feature = await loadFeatureConfig(workspacePath);
+        const repoName = typeof body?.repo === 'string' && body.repo ? body.repo : (feature?.repos[0] ? path.basename(feature.repos[0]) : null);
+        let worktreePath;
+        if (feature && isInPlace(feature)) {
+            const matches = repoName ? feature.repos.filter((r) => path.basename(r) === repoName) : feature.repos;
+            if (matches.length === 0) {
+                return c.json({ error: `Unknown repo in this workspace.` }, 404);
+            }
+            if (matches.length > 1) {
+                return c.json({ error: `Ambiguous repository '${repoName}' in this workspace. Multiple repositories match this name.` }, 400);
+            }
+            worktreePath = matches[0];
+        }
+        else {
+            worktreePath = repoName ? resolveRepoPath(workspacePath, repoName) : workspacePath;
+        }
+        // Snapshot git index so staged changes can be restored with 100% fidelity on rollback
+        let indexPath = null;
+        let originalIndexBuf = null;
+        try {
+            const { stdout: gitPathOut } = await execa('git', ['rev-parse', '--git-path', 'index'], { cwd: worktreePath });
+            const relIndexPath = gitPathOut.trim();
+            if (relIndexPath) {
+                indexPath = path.resolve(worktreePath, relIndexPath);
+                try {
+                    originalIndexBuf = await fs.readFile(indexPath);
+                }
+                catch (readErr) {
+                    if (readErr?.code !== 'ENOENT') {
+                        return c.json({
+                            error: `Failed to snapshot Git index before revert: ${readErr?.message ?? String(readErr)}`,
+                        }, 500);
+                    }
+                    originalIndexBuf = null;
+                }
+            }
+        }
+        catch (gitErr) {
+            return c.json({
+                error: `Failed to resolve Git index path before revert: ${gitErr?.message ?? String(gitErr)}`,
+            }, 500);
+        }
+        const preflightItems = [];
+        for (const file of files) {
+            const resolvedFile = assertWithin(worktreePath, path.join(worktreePath, file));
+            const relFile = path.relative(worktreePath, resolvedFile);
+            const { stdout: statusOut } = await execa('git', ['status', '--porcelain', '--', relFile], { cwd: worktreePath });
+            const statusLine = statusOut.trim();
+            if (!statusLine) {
+                continue;
+            }
+            // Preflight unsupported statuses: conflicts (U, AA, DD), submodules (S), typechanges (T)
+            const code = statusLine.slice(0, 2);
+            if (code.includes('U') || code === 'AA' || code === 'DD') {
+                return c.json({
+                    error: `Cannot revert '${relFile}': file has unmerged git conflicts ('${statusLine}'). Resolve conflicts first.`,
+                }, 400);
+            }
+            if (code.includes('S') || code.includes('T')) {
+                return c.json({
+                    error: `Cannot revert '${relFile}': file has unsupported git status ('${statusLine}').`,
+                }, 400);
+            }
+            const isUntracked = statusLine.startsWith('??');
+            let exists = false;
+            let originalContent;
+            let originalMode;
+            try {
+                let handle = null;
+                try {
+                    if (typeof fs.open === 'function') {
+                        handle = await fs.open(resolvedFile, 'r');
+                    }
+                    if (handle && typeof handle.readFile === 'function') {
+                        const [content, stat] = await Promise.all([
+                            handle.readFile(),
+                            typeof handle.stat === 'function' ? handle.stat() : Promise.resolve(undefined),
+                        ]);
+                        originalContent = content;
+                        originalMode = stat?.mode;
+                        exists = true;
+                    }
+                    else {
+                        originalContent = await fs.readFile(resolvedFile);
+                        exists = true;
+                    }
+                }
+                finally {
+                    if (handle && typeof handle.close === 'function') {
+                        await handle.close();
+                    }
+                }
+            }
+            catch (err) {
+                if (err?.code !== 'ENOENT') {
+                    throw err;
+                }
+                exists = false;
+            }
+            preflightItems.push({
+                resolvedFile,
+                relFile,
+                isUntracked,
+                exists,
+                originalContent,
+                originalMode,
+            });
+        }
+        // Execution with rollback protection: if any operation fails, restore previous state
+        const executedReverts = [];
+        try {
+            for (const item of preflightItems) {
+                if (item.isUntracked) {
+                    if (item.exists) {
+                        await fs.unlink(item.resolvedFile);
+                    }
+                }
+                else {
+                    await execa('git', ['checkout', 'HEAD', '--', item.relFile], { cwd: worktreePath });
+                }
+                executedReverts.push(item);
+            }
+        }
+        catch (revertErr) {
+            const rollbackErrors = [];
+            // 1. Restore the Git index first if it was snapshotted
+            if (indexPath && originalIndexBuf) {
+                try {
+                    await fs.writeFile(indexPath, originalIndexBuf);
+                }
+                catch (indexErr) {
+                    rollbackErrors.push(`Failed to restore git index: ${indexErr?.message ?? String(indexErr)}`);
+                }
+            }
+            // 2. Restore modified working tree files and metadata
+            for (const item of executedReverts) {
+                try {
+                    if (item.isUntracked) {
+                        if (item.exists && item.originalContent) {
+                            await fs.writeFile(item.resolvedFile, item.originalContent);
+                            if (item.originalMode !== undefined && typeof fs.chmod === 'function') {
+                                try {
+                                    await fs.chmod(item.resolvedFile, item.originalMode);
+                                }
+                                catch (chmodErr) {
+                                    rollbackErrors.push(`Failed to restore mode on ${item.relFile}: ${chmodErr?.message ?? String(chmodErr)}`);
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        if (item.exists && item.originalContent) {
+                            await fs.writeFile(item.resolvedFile, item.originalContent);
+                            if (item.originalMode !== undefined && typeof fs.chmod === 'function') {
+                                try {
+                                    await fs.chmod(item.resolvedFile, item.originalMode);
+                                }
+                                catch (chmodErr) {
+                                    rollbackErrors.push(`Failed to restore mode on ${item.relFile}: ${chmodErr?.message ?? String(chmodErr)}`);
+                                }
+                            }
+                        }
+                        else if (!item.exists) {
+                            try {
+                                await fs.unlink(item.resolvedFile);
+                            }
+                            catch (unlinkErr) {
+                                if (unlinkErr?.code !== 'ENOENT') {
+                                    rollbackErrors.push(`Failed to remove checked-out file ${item.relFile}: ${unlinkErr?.message ?? String(unlinkErr)}`);
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (restoreErr) {
+                    rollbackErrors.push(`Failed to restore ${item.relFile}: ${restoreErr?.message ?? String(restoreErr)}`);
+                }
+            }
+            if (rollbackErrors.length > 0) {
+                return c.json({
+                    error: `Failed to revert files: ${revertErr?.message ?? String(revertErr)}. Warning: Rollback could not fully restore state: ${rollbackErrors.join('; ')}`,
+                }, 500);
+            }
+            return c.json({
+                error: `Failed to revert files: ${revertErr?.message ?? String(revertErr)}. Any modified files were rolled back.`,
+            }, 500);
+        }
+        const reverted = preflightItems.map((item) => item.relFile);
+        return c.json({ success: true, reverted });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
 // 13a. Get workspace knowledge (nexusflow-knowledge.md)
 // Routed through the active storage adapter so the GUI edits the same file the
 // generators write, whichever backend is active.
@@ -1665,7 +1946,14 @@ app.put('/api/workspace/:id/knowledge', async (c) => {
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const feature = await loadFeatureConfig(workspacePath);
         const featureId = feature?.id ?? path.basename(workspacePath);
-        await writeWorkspaceFile(workspacePath, featureId, 'nexusflow-knowledge.md', content);
+        const { PRIMARY_KNOWLEDGE_FILE, LEGACY_KNOWLEDGE_FILE } = await import('./core/constants.js');
+        const { workspaceFileExists } = await import('./core/storage.js');
+        const filename = (await workspaceFileExists(workspacePath, featureId, PRIMARY_KNOWLEDGE_FILE))
+            ? PRIMARY_KNOWLEDGE_FILE
+            : (await workspaceFileExists(workspacePath, featureId, LEGACY_KNOWLEDGE_FILE))
+                ? LEGACY_KNOWLEDGE_FILE
+                : PRIMARY_KNOWLEDGE_FILE;
+        await writeWorkspaceFile(workspacePath, featureId, filename, content);
         return c.json({ success: true });
     }
     catch (error) {
@@ -1706,16 +1994,17 @@ app.post('/api/workspace/:id/knowledge/entry', async (c) => {
         return errorResponse(c, error);
     }
 });
-// 13c. Get workspace plan (nexusflow-plan.md)
+// 13c. Get workspace plan (contextspace-plan.md / nexusflow-plan.md)
 app.get('/api/workspace/:id/plan', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const planFile = path.join(workspacePath, 'nexusflow-plan.md');
+        const { resolveWorkspaceFilePath } = await import('./core/brand-config.js');
+        const resolved = await resolveWorkspaceFilePath(workspacePath, 'plan');
         let content = '';
         try {
-            content = await fs.readFile(planFile, 'utf-8');
+            content = await fs.readFile(resolved.path, 'utf-8');
         }
         catch {
             content = '# Workspace Plan\n\nNo implementation plan file yet.';
@@ -1726,70 +2015,206 @@ app.get('/api/workspace/:id/plan', async (c) => {
         return errorResponse(c, error);
     }
 });
-// 13d. Sync all repositories in workspace
-app.post('/api/workspace/:id/sync', async (c) => {
+// 13c-2. Check workspace migration status (legacy NexusFlow files detected)
+app.get('/api/workspace/:id/migration-status', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const report = await syncWorkspace(workspacePath);
-        const results = report.repos.map((repo) => ({
-            repoName: repo.name,
-            success: repo.status !== 'conflict' && repo.status !== 'error',
-            status: repo.status,
-            message: repo.message,
-            conflict: repo.conflict,
-        }));
-        return c.json({
-            results,
-            syncedCount: report.syncedCount,
-            conflictCount: report.conflictCount,
-            errorCount: report.errorCount,
-        });
+        const { isLegacyWorkspace } = await import('./core/migrate.js');
+        const isLegacy = await isLegacyWorkspace(workspacePath);
+        return c.json({ isLegacy });
     }
     catch (error) {
         return errorResponse(c, error);
     }
 });
-// 13e. Commit changes in all repositories in workspace
-app.post('/api/workspace/:id/commit', async (c) => {
+// 13c-3. Migrate legacy workspace to native ContextSpace
+app.post('/api/workspace/:id/migrate', async (c) => {
     try {
         const id = c.req.param('id');
-        const { message } = await c.req.json();
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        const report = await commitWorkspace(workspacePath, message);
-        const results = report.repos.map((repo) => ({
-            repoName: repo.name,
-            success: repo.success,
-            commitHash: repo.commitHash,
-            filesChanged: repo.filesChanged,
-            message: repo.message,
-        }));
-        return c.json({ results });
+        const { migrateWorkspace } = await import('./core/migrate.js');
+        const report = await migrateWorkspace(workspacePath, { dryRun: false, refresh: true });
+        return c.json(report);
     }
     catch (error) {
         return errorResponse(c, error);
     }
 });
-// 14. Resume session in workspace (copies CLI resume command and opens editor)
-app.post('/api/workspace/:id/resume', async (c) => {
-    const origin = c.req.header('origin');
-    if (origin && !hasTrustedLocalOrigin(origin)) {
-        return c.json({ error: 'Forbidden cross-origin request.' }, 403);
-    }
+// 13c-4. Get workspace collaboration stream (.nexusflow/chat.jsonl or .contextspace/chat.jsonl)
+app.get('/api/workspace/:id/stream', async (c) => {
     try {
-        const id = decodeURIComponent(c.req.param('id'));
+        const id = c.req.param('id');
         const config = await loadConfig();
         const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
-        // Load feature config to get repo paths
-        const feature = await loadFeatureConfig(workspacePath);
-        if (!feature) {
-            return c.json({ error: 'Workspace configuration not found.' }, 404);
+        const { messages, ledgerInfo } = await readWorkspaceChatMessages(workspacePath);
+        let isRemoteActive = false;
+        let remoteStatus = null;
+        let workflowProgress = null;
+        try {
+            const client = await workroomManagerModule.loadPinnedWorkroomClientForWorkspace(id);
+            const snapshot = await client.snapshot();
+            isRemoteActive = true;
+            workflowProgress = snapshot.workflowProgress ?? null;
+            remoteStatus = {
+                roomId: snapshot.roomId,
+                name: snapshot.name,
+            };
         }
-        const body = await c.req.json().catch(() => ({}));
-        const targetSessionId = typeof body.sessionId === 'string' && isValidSessionUuid(body.sessionId) ? body.sessionId : undefined;
-        if (body.sessionId !== undefined && targetSessionId === undefined) {
+        catch {
+            // Fallback to in-process workroomManager
+            try {
+                if (workroomManagerModule.workroomManager.hasActiveRoom()) {
+                    const status = await workroomManagerModule.workroomManager.status();
+                    if ((status.mode === 'host' || status.mode === 'guest') && status.localWorkspaceId === id) {
+                        isRemoteActive = true;
+                        workflowProgress = status.snapshot?.workflowProgress ?? null;
+                        remoteStatus = {
+                            roomId: status.roomId,
+                            url: status.url,
+                            name: status.name,
+                        };
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        // Reconcile messages with live authoritative workflow progress by stepId
+        const stepMap = new Map();
+        if (workflowProgress?.steps) {
+            for (const step of workflowProgress.steps) {
+                stepMap.set(step.stepId, step);
+            }
+        }
+        const reconciledMessages = messages.map((msg) => {
+            if (!msg.stepId)
+                return msg;
+            const liveStep = stepMap.get(msg.stepId);
+            if (!liveStep)
+                return msg;
+            return {
+                ...msg,
+                stepProposal: liveStep,
+            };
+        });
+        const relLedgerPath = ledgerInfo.isLegacy ? '.nexusflow/chat.jsonl' : '.contextspace/chat.jsonl';
+        return c.json({
+            workspaceId: id,
+            messages: reconciledMessages,
+            workflowProgress,
+            isRemoteActive,
+            remoteStatus,
+            isLegacy: ledgerInfo.isLegacy,
+            ledgerPath: relLedgerPath,
+        });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+// 13c-5. Post a message to workspace collaboration stream
+app.post('/api/workspace/:id/stream', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const body = (await c.req.json());
+        const message = String(body.message ?? '').trim();
+        if (!message) {
+            return c.json({ error: 'Message cannot be empty.' }, 400);
+        }
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        const ledger = await resolveWorkspaceChatLedger(workspacePath);
+        await fs.mkdir(ledger.chatDir, { recursive: true });
+        const chatFile = ledger.chatPath;
+        const isHuman = body.author === 'human' || body.harness === 'developer' || body.harness === 'human';
+        const status = body.status ? String(body.status).trim() : (body.stepId ? 'proposed' : undefined);
+        const effectiveStatus = (!isHuman && status === 'completed') ? 'proposed' : status;
+        const entry = {
+            id: createHash('sha256').update(Date.now() + message).digest('hex').slice(0, 12),
+            timestamp: new Date().toISOString(),
+            harness: body.harness || (isHuman ? 'developer' : 'agent'),
+            author: isHuman ? 'human' : 'agent',
+            status: effectiveStatus,
+            message,
+            ...(body.stepId ? { stepId: body.stepId } : {}),
+            ...(body.evidence ? { evidence: body.evidence } : {}),
+            ...(isHuman && effectiveStatus === 'completed' ? { confirmedBy: 'human', confirmedAt: new Date().toISOString() } : {}),
+        };
+        await fs.appendFile(chatFile, JSON.stringify(entry) + '\n', 'utf-8');
+        return c.json({ success: true, entry });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+// 13d. Sync all repositories in workspace
+app.post('/api/workspace/:id/sync', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        const report = await syncWorkspace(workspacePath);
+        const results = report.repos.map((repo) => ({
+            repoName: repo.name,
+            success: repo.status !== 'conflict' && repo.status !== 'error',
+            status: repo.status,
+            message: repo.message,
+            conflict: repo.conflict,
+        }));
+        return c.json({
+            results,
+            syncedCount: report.syncedCount,
+            conflictCount: report.conflictCount,
+            errorCount: report.errorCount,
+        });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+// 13e. Commit changes in all repositories in workspace
+app.post('/api/workspace/:id/commit', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const { message } = await c.req.json();
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        const report = await commitWorkspace(workspacePath, message);
+        const results = report.repos.map((repo) => ({
+            repoName: repo.name,
+            success: repo.success,
+            commitHash: repo.commitHash,
+            filesChanged: repo.filesChanged,
+            message: repo.message,
+        }));
+        return c.json({ results });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+// 14. Resume session in workspace (copies CLI resume command and opens editor)
+app.post('/api/workspace/:id/resume', async (c) => {
+    const origin = c.req.header('origin');
+    if (origin && !hasTrustedLocalOrigin(origin)) {
+        return c.json({ error: 'Forbidden cross-origin request.' }, 403);
+    }
+    try {
+        const id = decodeURIComponent(c.req.param('id'));
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        // Load feature config to get repo paths
+        const feature = await loadFeatureConfig(workspacePath);
+        if (!feature) {
+            return c.json({ error: 'Workspace configuration not found.' }, 404);
+        }
+        const body = await c.req.json().catch(() => ({}));
+        const targetSessionId = typeof body.sessionId === 'string' && isValidSessionUuid(body.sessionId) ? body.sessionId : undefined;
+        if (body.sessionId !== undefined && targetSessionId === undefined) {
             return c.json({ error: 'Invalid session UUID format.' }, 400);
         }
         if (body.command !== undefined && (typeof body.command !== 'string' || !ALLOWED_EDITORS.has(body.command))) {
@@ -1981,7 +2406,8 @@ app.post('/api/updates/install', async (c) => {
     try {
         const { toolId } = await c.req.json();
         const tools = [
-            { id: 'nexusflow', cmd: 'npm', args: ['install', '-g', '@mrpatronz/nexusflow'] },
+            { id: ENGINE_ID, cmd: 'npm', args: ['install', '-g', ENGINE_NPM_PACKAGE] },
+            { id: LEGACY_ENGINE_ID, cmd: 'npm', args: ['install', '-g', LEGACY_ENGINE_NPM_PACKAGE] },
             { id: 'antigravity', cmd: 'agy', args: ['update'] },
             { id: 'claude', cmd: 'npm', args: ['install', '-g', '@anthropic-ai/claude-code'] },
         ];
@@ -2004,96 +2430,6 @@ app.post('/api/updates/install', async (c) => {
         return errorResponse(c, error);
     }
 });
-let downloadedInstallerPath = null;
-// 17.7. Download matching GitHub Release installer to temporary folder
-app.post('/api/updates/download', async (c) => {
-    try {
-        const { downloadUrl } = await c.req.json();
-        if (!downloadUrl) {
-            return c.json({ error: 'Download URL is required' }, 400);
-        }
-        if (!isAllowedUpdateUrl(downloadUrl)) {
-            return c.json({ error: 'Download URL is not an allowed update host' }, 400);
-        }
-        const tempDir = os.tmpdir();
-        const fileName = 'NexusFlowSetup_Update.exe';
-        const targetPath = path.join(tempDir, fileName);
-        const response = await fetch(downloadUrl);
-        if (!response.ok) {
-            throw new Error(`HTTP error ${response.status}`);
-        }
-        // Node fetch body stream download and SHA-256 computation
-        const hash = createHash('sha256');
-        const fileStream = createWriteStream(targetPath);
-        if (!response.body) {
-            throw new Error('Response body is null');
-        }
-        const nodeStream = Readable.fromWeb(response.body);
-        nodeStream.on('data', (chunk) => hash.update(chunk));
-        await pipeline(nodeStream, fileStream);
-        const computedHash = hash.digest('hex').toLowerCase();
-        // Verify SHA-256 against release checksum file if published
-        try {
-            const shaUrl = `${downloadUrl}.sha256`;
-            if (isAllowedUpdateUrl(shaUrl)) {
-                const shaRes = await fetch(shaUrl);
-                if (shaRes.ok) {
-                    const shaText = await shaRes.text();
-                    const expectedHash = shaText.trim().split(/\s+/)[0]?.toLowerCase();
-                    if (expectedHash && expectedHash.length === 64 && expectedHash !== computedHash) {
-                        await fs.unlink(targetPath).catch(() => { });
-                        throw new Error(`SHA-256 checksum mismatch (expected ${expectedHash}, got ${computedHash})`);
-                    }
-                }
-            }
-        }
-        catch (shaErr) {
-            if (shaErr instanceof Error && shaErr.message.includes('SHA-256 checksum mismatch')) {
-                throw shaErr;
-            }
-            // Non-fatal if sha256 sidecar does not exist on older releases
-        }
-        downloadedInstallerPath = targetPath;
-        return c.json({ success: true, path: targetPath, sha256: computedHash });
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: `Download failed: ${msg}` }, 500);
-    }
-});
-// 17.8. Launch the silent installer detached and exit server
-app.post('/api/updates/apply', async (c) => {
-    if (!downloadedInstallerPath || !existsSync(downloadedInstallerPath)) {
-        return c.json({ error: 'No downloaded installer found on disk' }, 400);
-    }
-    try {
-        const isWin = process.platform === 'win32';
-        if (isWin) {
-            // The desktop app ships an electron-builder NSIS installer (build target
-            // 'nsis'), whose silent-install switch is `/S` — NOT Inno Setup's
-            // /VERYSILENT. With the wrong flags the one-click installer waits for UI
-            // that a detached (stdio: 'ignore') process can never provide, so the
-            // update silently fails to apply. `/S` runs it unattended and relaunches
-            // the app on finish (electron-builder default).
-            console.log(`Applying update: Spawning detached installer at: ${downloadedInstallerPath}`);
-            const child = spawn(downloadedInstallerPath, ['/S'], {
-                detached: true,
-                stdio: 'ignore',
-            });
-            child.unref();
-        }
-        // Gracefully exit server process in 1 second to release file locks
-        setTimeout(() => {
-            console.log('Update installer successfully spawned. Exiting Hono server process...');
-            process.exit(0);
-        }, 1000);
-        return c.json({ success: true, message: 'Installer spawned, app shutting down...' });
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: `Failed to execute update: ${msg}` }, 500);
-    }
-});
 // 17.9. Get available workflow templates
 app.get('/api/workflows/templates', async (c) => {
     try {
@@ -2399,6 +2735,505 @@ app.post('/api/skills/workspace/:id/assign', async (c) => {
         return errorResponse(c, error);
     }
 });
+// ─── Workrooms: opt-in LAN/VPN collaboration ─────────────────────────────
+const WORKROOM_HUMAN_SESSION_COOKIES = [
+    'contextspace_workroom_human',
+    'nexusflow_workroom_human',
+];
+const WORKROOM_BOOTSTRAP_TOKEN = randomToken();
+function establishWorkroomBootstrap(c) {
+    for (const cookieName of WORKROOM_BOOTSTRAP_COOKIES) {
+        setCookie(c, cookieName, WORKROOM_BOOTSTRAP_TOKEN, {
+            httpOnly: true,
+            sameSite: 'Strict',
+            path: '/api/workrooms',
+        });
+    }
+}
+function hasValidWorkroomBootstrap(c) {
+    const cookieToken = WORKROOM_BOOTSTRAP_COOKIES
+        .map((name) => getCookie(c, name))
+        .find((val) => typeof val === 'string' && val);
+    const headerToken = WORKROOM_BOOTSTRAP_HEADERS
+        .map((header) => c.req.header(header))
+        .find((val) => typeof val === 'string' && val);
+    return Boolean(cookieToken && headerToken
+        && tokenDigest(cookieToken) === tokenDigest(WORKROOM_BOOTSTRAP_TOKEN)
+        && tokenDigest(headerToken) === tokenDigest(WORKROOM_BOOTSTRAP_TOKEN));
+}
+function establishWorkroomHumanSession(c, token = workroomManager.beginHumanSession()) {
+    for (const cookieName of WORKROOM_HUMAN_SESSION_COOKIES) {
+        setCookie(c, cookieName, token, {
+            httpOnly: true,
+            sameSite: 'Strict',
+            path: '/api/workrooms',
+        });
+    }
+}
+function getWorkroomHumanSessionToken(c) {
+    return WORKROOM_HUMAN_SESSION_COOKIES
+        .map((name) => getCookie(c, name))
+        .find((val) => typeof val === 'string' && val);
+}
+function clearWorkroomHumanSession(c) {
+    for (const cookieName of WORKROOM_HUMAN_SESSION_COOKIES) {
+        deleteCookie(c, cookieName, { path: '/api/workrooms' });
+    }
+}
+function hasExactDashboardOrigin(origin, requestUrl) {
+    if (!origin)
+        return false;
+    try {
+        const normalizedOrigin = new URL(origin).origin;
+        const requestOrigin = new URL(requestUrl).origin;
+        const devOrigin = process.env.CONTEXTSPACE_DASHBOARD_ORIGIN || process.env.NEXUSFLOW_DASHBOARD_ORIGIN;
+        const configuredDevelopmentOrigin = devOrigin ? new URL(devOrigin).origin : undefined;
+        return normalizedOrigin === requestOrigin || normalizedOrigin === configuredDevelopmentOrigin;
+    }
+    catch {
+        return false;
+    }
+}
+function hasExactWorkroomBrowserBoundary(c) {
+    const origin = c.req.header('origin');
+    if (origin)
+        return hasExactDashboardOrigin(origin, c.req.url);
+    const referer = c.req.header('referer');
+    if (referer)
+        return hasExactDashboardOrigin(referer, c.req.url);
+    return c.req.header('sec-fetch-site') === 'same-origin';
+}
+app.use('/api/workrooms/*', async (c, next) => {
+    const pathname = new URL(c.req.url).pathname;
+    c.header('Cache-Control', 'no-store');
+    if (!hasExactWorkroomBrowserBoundary(c)) {
+        return c.json({ error: 'Workroom access requires the local browser dashboard.' }, 403);
+    }
+    if (pathname === '/api/workrooms/bootstrap')
+        return next();
+    if (!hasValidWorkroomBootstrap(c)) {
+        return c.json({ error: 'Workroom access requires a same-origin dashboard bootstrap.' }, 403);
+    }
+    if (pathname === '/api/workrooms/session' || pathname === '/api/workrooms/session/reclaim'
+        || pathname === '/api/workrooms/session/abandon')
+        return next();
+    const isMutation = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(c.req.method);
+    const needsHumanReadSession = c.req.method === 'GET' && (pathname === '/api/workrooms/snapshot'
+        || pathname === '/api/workrooms/local-resources'
+        || (pathname === '/api/workrooms/status' && workroomManager.hasActiveRoom()));
+    if (!isMutation && !needsHumanReadSession)
+        return next();
+    const doesNotRequireExistingHumanSession = pathname === '/api/workrooms/start'
+        || pathname === '/api/workrooms/join'
+        || pathname === '/api/workrooms/import'
+        || /^\/api\/workrooms\/quarantined\/room-[a-f0-9]{32}\/discard$/.test(pathname)
+        || /^\/api\/workrooms\/room-[a-f0-9]{32}\/resume$/.test(pathname);
+    if (needsHumanReadSession || (isMutation && !doesNotRequireExistingHumanSession)) {
+        try {
+            const authority = workroomManager.assertHumanSession(getWorkroomHumanSessionToken(c));
+            if (pathname === '/api/workrooms/stop')
+                return next();
+            await workroomManager.runWithHumanAuthority(authority, () => next());
+            return;
+        }
+        catch (error) {
+            return errorResponse(c, error);
+        }
+    }
+    await next();
+});
+app.post('/api/workrooms/bootstrap', (c) => {
+    establishWorkroomBootstrap(c);
+    return c.json({ token: WORKROOM_BOOTSTRAP_TOKEN });
+});
+app.get('/api/workrooms/session', (c) => {
+    const active = workroomManager.hasActiveRoom();
+    if (!active)
+        return c.json({ active: false, locked: false });
+    const roomType = workroomManager.activeRoomType();
+    if (!roomType)
+        return c.json({ active: false, locked: false });
+    try {
+        workroomManager.assertHumanSession(getWorkroomHumanSessionToken(c));
+        return c.json({ active: true, locked: false, roomType });
+    }
+    catch {
+        return c.json({ active: true, locked: true, roomType });
+    }
+});
+app.post('/api/workrooms/session/reclaim', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (!workroomManager.hasActiveRoom())
+            return c.json({ error: 'No active Workroom can be reconnected.' }, 409);
+        const token = await workroomManager.reclaimHostHumanSession(String(body.password ?? ''));
+        establishWorkroomHumanSession(c, token);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/session/abandon', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (body.confirm !== true)
+            return c.json({ error: 'Confirm leaving this locked guest connection.' }, 400);
+        await workroomManager.abandonLockedGuest();
+        clearWorkroomHumanSession(c);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/interfaces', (c) => {
+    return c.json({ interfaces: listWorkroomNetworkInterfaces() });
+});
+app.get('/api/workrooms/status', async (c) => {
+    try {
+        const status = await workroomManager.status();
+        if (status.mode !== 'idle') {
+            workroomManager.assertHumanSession(getWorkroomHumanSessionToken(c));
+        }
+        return c.json({ status });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/paused', async (c) => {
+    try {
+        return c.json({ rooms: await workroomManager.listPaused() });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/quarantined', async (c) => {
+    try {
+        return c.json({ rooms: await workroomManager.listQuarantined() });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/quarantined/:roomId/discard', async (c) => {
+    try {
+        const roomId = c.req.param('roomId');
+        const body = await c.req.json();
+        if (body.confirmRoomId !== roomId) {
+            return c.json({ error: 'Confirm the exact quarantined Workroom ID before discarding it.' }, 400);
+        }
+        await workroomManager.discardQuarantined(roomId);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/:roomId/resume', async (c) => {
+    try {
+        const body = await c.req.json();
+        const status = await workroomManager.resumeHost(c.req.param('roomId'), String(body.password ?? ''));
+        establishWorkroomHumanSession(c);
+        return c.json({ status });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/preview/:workspaceId', async (c) => {
+    try {
+        const workspaceId = decodeURIComponent(c.req.param('workspaceId'));
+        const config = await loadConfig();
+        const workspacePath = await resolveExactWorkspaceById(config.workspacesDir, workspaceId);
+        if (!workspacePath)
+            return c.json({ error: 'Workspace not found.' }, 404);
+        return c.json({ preview: await buildPortableWorkroomPreview(workspacePath) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/start', async (c) => {
+    try {
+        const body = await c.req.json();
+        const workspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : '';
+        const config = await loadConfig();
+        const workspacePath = await resolveExactWorkspaceById(config.workspacesDir, workspaceId);
+        if (!workspacePath)
+            return c.json({ error: 'Workspace not found.' }, 404);
+        const preview = await buildPortableWorkroomPreview(workspacePath);
+        if (body.contextConfirmed !== true) {
+            return c.json({ error: 'Review the exact shared context and confirm it before starting the Workroom.' }, 400);
+        }
+        const documentOverrides = typeof body.documents === 'object' && body.documents !== null
+            ? body.documents
+            : {};
+        const documents = { plan: '', decisions: '', handoff: '' };
+        for (const name of ['plan', 'decisions', 'handoff']) {
+            if (typeof documentOverrides[name] === 'string')
+                documents[name] = documentOverrides[name];
+        }
+        if (body.contextDigest !== digestPortableWorkroomContext(preview.bundle, documents)) {
+            return c.json({ error: 'The exact selected context changed after review. Refresh the sharing preview and confirm it again.' }, 409);
+        }
+        const status = await workroomManager.startHost({
+            ...preview,
+            documents,
+            name: String(body.name ?? '').trim() || `${preview.bundle.feature.id} workroom`,
+            address: String(body.address ?? ''),
+            port: Number(body.port ?? 4242),
+            password: String(body.password ?? ''),
+            hostDisplayName: String(body.hostDisplayName ?? '').trim() || os.userInfo().username || 'Host',
+        });
+        establishWorkroomHumanSession(c);
+        return c.json({ status }, 201);
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/stop', async (c) => {
+    try {
+        const authority = workroomManager.assertHumanSession(getWorkroomHumanSessionToken(c));
+        await workroomManager.stopOrLeave(authority);
+        clearWorkroomHumanSession(c);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/invites', async (c) => {
+    try {
+        return c.json(await workroomManager.createInvite(), 201);
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/join', async (c) => {
+    try {
+        const body = await c.req.json();
+        let localWorkspaceId;
+        if (typeof body.workspaceId === 'string' && body.workspaceId) {
+            const config = await loadConfig();
+            const workspacePath = await resolveExactWorkspaceById(config.workspacesDir, body.workspaceId);
+            if (!workspacePath)
+                return c.json({ error: 'Select an existing local workspace for the Workroom mapping.' }, 404);
+            localWorkspaceId = body.workspaceId;
+        }
+        const status = await workroomManager.join(String(body.invite ?? ''), String(body.password ?? ''), String(body.displayName ?? '').trim() || os.userInfo().username || 'Developer', localWorkspaceId);
+        establishWorkroomHumanSession(c);
+        return c.json({ status }, 202);
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/join/poll', async (c) => {
+    try {
+        return c.json({ status: await workroomManager.pollJoin() });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/snapshot', async (c) => {
+    try {
+        return c.json({ snapshot: await workroomManager.snapshot() });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.put('/api/workrooms/documents/:name', async (c) => {
+    try {
+        const name = documentNameSchema.parse(c.req.param('name'));
+        const body = await c.req.json();
+        if (typeof body.content !== 'string' || !Number.isInteger(body.expectedRevision)) {
+            return c.json({ error: 'content and an integer expectedRevision are required.' }, 400);
+        }
+        return c.json({ document: await workroomManager.updateDocument(name, body.content, body.expectedRevision) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/handoff', async (c) => {
+    try {
+        const body = await c.req.json();
+        const workspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : '';
+        const config = await loadConfig();
+        const workspacePath = await resolveExactWorkspaceById(config.workspacesDir, workspaceId);
+        if (!workspacePath)
+            return c.json({ error: 'Select a local workspace before publishing a handoff.' }, 404);
+        return c.json({ document: await workroomManager.publishHandoff(workspacePath) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/members/:requestId/decision', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (typeof body.accept !== 'boolean')
+            return c.json({ error: 'accept must be a boolean.' }, 400);
+        await workroomManager.decideJoin(c.req.param('requestId'), body.accept);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.put('/api/workrooms/members/:memberId/role', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (body.role !== 'publisher' && body.role !== 'member')
+            return c.json({ error: 'role must be publisher or member.' }, 400);
+        await workroomManager.setRole(c.req.param('memberId'), body.role);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.delete('/api/workrooms/members/:memberId', async (c) => {
+    try {
+        await workroomManager.revokeMember(c.req.param('memberId'));
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/password/rotate', async (c) => {
+    try {
+        const body = await c.req.json();
+        await workroomManager.rotatePassword(String(body.password ?? ''), body.revokeDevices !== false);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.get('/api/workrooms/local-resources', async (c) => {
+    try {
+        return c.json({ resources: await workroomManager.listLocalResources() });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/resources/publish', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (!['skill', 'agent', 'workflow'].includes(body.kind) || typeof body.id !== 'string' || typeof body.version !== 'string') {
+            return c.json({ error: 'kind, id, and semantic version are required.' }, 400);
+        }
+        return c.json({ package: await workroomManager.publishLocalResource(body.kind, body.id, body.version) }, 201);
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/resources/:digest/download', async (c) => {
+    try {
+        return c.json(await workroomManager.downloadResource(c.req.param('digest')));
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/resources/:digest/apply', async (c) => {
+    try {
+        const body = await c.req.json();
+        return c.json({ applied: await workroomManager.applyResource(c.req.param('digest'), String(body.approvedDigest ?? ''), String(body.approvedLocalDigest ?? '')) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/resources/:digest/quarantine', async (c) => {
+    try {
+        await workroomManager.quarantineResource(c.req.param('digest'));
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/resources/:digest/purge', async (c) => {
+    try {
+        const body = await c.req.json();
+        if (body.confirmDigest !== c.req.param('digest')) {
+            return c.json({ error: 'Confirm the exact quarantined resource digest before purging it.' }, 400);
+        }
+        await workroomManager.purgeResource(c.req.param('digest'));
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/workflow/select', async (c) => {
+    try {
+        const body = await c.req.json();
+        const steps = Array.isArray(body.steps)
+            ? body.steps.map((step) => workflowStepSchema.parse(step))
+            : undefined;
+        if (typeof body.workflowId !== 'string' || typeof body.version !== 'string' || !steps
+            || !Number.isInteger(body.expectedRevision) || body.expectedRevision < 0) {
+            return c.json({ error: 'workflowId, version, steps, and a nonnegative integer expectedRevision are required.' }, 400);
+        }
+        await workroomManager.selectLocalWorkflow(body.workflowId, body.version, steps, body.expectedRevision);
+        return c.json({ success: true });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/workflow/steps/:stepId/transition', async (c) => {
+    try {
+        const body = await c.req.json();
+        const allowed = ['pending', 'in_progress', 'completion_proposed', 'completed', 'skipped'];
+        if (!allowed.includes(body.status) || !Number.isInteger(body.expectedRevision)) {
+            return c.json({ error: 'A valid status and integer expectedRevision are required.' }, 400);
+        }
+        return c.json({ step: await workroomManager.transitionWorkflowStep(c.req.param('stepId'), body.status, body.expectedRevision, typeof body.evidence === 'string' ? body.evidence : undefined) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/export', async (c) => {
+    try {
+        const body = await c.req.json();
+        return c.json({ export: await workroomManager.exportRoom(String(body.passphrase ?? '')) });
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
+app.post('/api/workrooms/import', async (c) => {
+    try {
+        const body = await c.req.json();
+        const status = await workroomManager.importRoom(body.export, String(body.exportPassphrase ?? ''), {
+            name: typeof body.name === 'string' ? body.name : undefined,
+            address: String(body.address ?? ''),
+            port: Number(body.port ?? 4242),
+            password: String(body.password ?? ''),
+            hostDisplayName: String(body.hostDisplayName ?? '').trim() || os.userInfo().username || 'Host',
+        });
+        establishWorkroomHumanSession(c);
+        return c.json({ status }, 201);
+    }
+    catch (error) {
+        return errorResponse(c, error);
+    }
+});
 // ─── Schedules: recurring workspace jobs (sync/refresh) ─────────────────
 // List all scheduled jobs (with computed next-due time)
 app.get('/api/schedules', async (c) => {
@@ -2500,6 +3335,11 @@ export function startServer(port = 3000, opts = {}) {
             resolve({ port: info.port, server });
         });
         injectWebSocket(server);
+        server.on('close', () => {
+            void workroomManager.stopOrLeave().catch((error) => {
+                console.error('[workroom] failed to stop with the dashboard:', error instanceof Error ? error.message : String(error));
+            });
+        });
         server.on('error', (e) => {
             if (e.code === 'EADDRINUSE') {
                 // Callers that own their backend (desktop/extension) pass strictPort so