@venturewild/workspace 0.1.0 → 0.1.1

package/server/src/index.mjs

@@ -1,635 +1,1099 @@
-// wild-workspace server bootstrap.
-// Three processes per AR-17:
-//   - this Node server (Hono): REST + WebSocket + frontend bundle
-//   - AI agent subprocess: spawned per chat session via agent.mjs
-//   - bmo-sync daemon (v1.x — out of scope for this scaffold)
-
-import { Hono } from 'hono';
-import { serveStatic } from '@hono/node-server/serve-static';
-import { serve } from '@hono/node-server';
-import { WebSocketServer } from 'ws';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import url from 'node:url';
-import {
-  buildConfig,
-  ROLES,
-  ROLE_CAPABILITIES,
-  APP_VERSION,
-  DEFAULT_AGENTS,
-  assertSecureBinding,
-} from './config.mjs';
-import { detectAgents, AgentSession, pickDefaultAgent } from './agent.mjs';
-import { mintShareToken, verifyShareToken, buildShareUrl, TokenRegistry } from './share.mjs';
-import { listDir, readFile, fullTree, workspaceSummary, safeResolve } from './fs.mjs';
-import { InboxWatcher } from './inbox.mjs';
-import { ActivityBus } from './activity.mjs';
-import { DaemonBridge } from './daemon.mjs';
-import { SyncControl } from './sync.mjs';
-import { detectPreviewPorts, checkPort } from './preview.mjs';
-import { nanoid } from 'nanoid';
-
-const __filename = url.fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-export async function createServer(overrides = {}) {
-  const config = buildConfig(overrides);
-  // Refuse to start on a public bind with a forgeable default secret. (C1/C2)
-  assertSecureBinding(config);
-  if (!existsSync(config.dataDir)) mkdirSync(config.dataDir, { recursive: true });
-
-  const activityBus = new ActivityBus();
-  const tokenRegistry = new TokenRegistry();
-  const inboxWatcher = new InboxWatcher(config.workspaceDir).start();
-  inboxWatcher.on('change', (payload) => {
-    activityBus.publish({ type: 'inbox-change', snapshot: payload.snapshot });
-  });
-
-  // Bridge the bmo-sync daemon's event feed into the ActivityBus. The daemon
-  // is a separate process and may be absent — the bridge retries quietly.
-  // `overrides.daemonBridge: false` disables it (used by tests).
-  const daemonBridge =
-    overrides.daemonBridge === false
-      ? null
-      : new DaemonBridge(activityBus, { url: config.daemonUrl }).start();
-
-  // Control plane for bmo-sync folder sharing (pair / detach / invite).
-  // `overrides.syncControl` is a test seam.
-  const syncControl =
-    overrides.syncControl ||
-    new SyncControl({
-      daemonHttpUrl: config.daemonHttpUrl,
-      bmoSyncServerUrl: config.bmoSyncServerUrl,
-      adminKey: config.bmoSyncAdminKey,
-    });
-
-  // `overrides.agents` / `overrides.activeAgent` are a test/embedding seam:
-  // a caller can inject agent definitions instead of probing PATH.
-  const detectedAgents = overrides.agents || (await detectAgents());
-  let activeAgent = overrides.activeAgent || pickDefaultAgent(detectedAgents);
-
-  const app = new Hono();
-
-  // --- auth + role resolution ---
-  async function resolveRole(c) {
-    const auth = c.req.header('authorization');
-    if (auth?.startsWith('Bearer ')) {
-      const token = auth.slice('Bearer '.length).trim();
-      if (token === config.partnerToken) {
-        return { role: ROLES.PARTNER, sub: 'partner', source: 'partner-token' };
-      }
-      const payload = await verifyShareToken(token, config.shareSecret);
-      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
-        return {
-          role: payload.role,
-          sub: payload.sub,
-          workspaceId: payload.workspaceId,
-          source: 'share-jwt',
-          exp: payload.exp,
-        };
-      }
-    }
-    const queryToken = c.req.query('t');
-    if (queryToken) {
-      // A browser opening the workspace URL can only carry a token in the
-      // query string, not an Authorization header — so the partner token is
-      // accepted here too, mirroring the WebSocket upgrade handler.
-      if (queryToken === config.partnerToken) {
-        return { role: ROLES.PARTNER, sub: 'partner', source: 'partner-token-query' };
-      }
-      const payload = await verifyShareToken(queryToken, config.shareSecret);
-      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
-        return {
-          role: payload.role,
-          sub: payload.sub,
-          workspaceId: payload.workspaceId,
-          source: 'share-jwt-query',
-          exp: payload.exp,
-        };
-      }
-    }
-    // Default for local partner UX — same machine, no token expected.
-    if (!config.publicMode) {
-      return { role: ROLES.PARTNER, sub: 'local-partner', source: 'localhost' };
-    }
-    // Public mode with no valid token: deny. No anonymous viewer access —
-    // a share JWT or the partner token is required. (Concern C1.)
-    return { role: null, sub: 'anon', source: 'unauth', denied: true };
-  }
-
-  function require(c, capability) {
-    const cap = ROLE_CAPABILITIES[c.get('role')];
-    if (!cap || !cap[capability]) {
-      return c.json({ error: 'forbidden', capability, role: c.get('role') }, 403);
-    }
-    return null;
-  }
-
-  app.use('*', async (c, next) => {
-    const session = await resolveRole(c);
-    c.set('role', session.role);
-    c.set('session', session);
-    // Block the API for denied (non-localhost, unauthenticated) requests, but
-    // let static assets and the health check through so the SPA can still
-    // load and prompt for a token. (Concern C1.)
-    if (session.denied && c.req.path.startsWith('/api/') && c.req.path !== '/api/health') {
-      return c.json({ error: 'unauthorized' }, 401);
-    }
-    await next();
-  });
-
-  // --- meta ---
-  app.get('/api/health', (c) =>
-    c.json({ status: 'ok', version: APP_VERSION, ts: Date.now() }),
-  );
-
-  app.get('/api/session', (c) => {
-    const session = c.get('session');
-    const role = c.get('role');
-    return c.json({
-      version: APP_VERSION,
-      role,
-      capabilities: ROLE_CAPABILITIES[role],
-      workspace: workspaceSummary(config.workspaceDir),
-      workspaceId: config.workspaceId,
-      session,
-      agent: activeAgent
-        ? { id: activeAgent.id, label: activeAgent.label, available: activeAgent.available }
-        : null,
-    });
-  });
-
-  app.get('/api/agents', (c) =>
-    c.json({
-      available: detectedAgents.map(({ id, label, description, available, resolvedPath }) => ({
-        id,
-        label,
-        description,
-        available,
-        resolvedPath,
-      })),
-      active: activeAgent?.id,
-    }),
-  );
-
-  app.post('/api/agents/select', async (c) => {
-    const forbidden = require(c, 'chatWrite');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const next = detectedAgents.find((a) => a.id === body.id);
-    if (!next) return c.json({ error: 'unknown-agent', id: body.id }, 400);
-    activeAgent = next;
-    activityBus.publish({ type: 'agent-changed', agentId: next.id });
-    return c.json({ ok: true, active: activeAgent.id });
-  });
-
-  // --- workspace files ---
-  app.get('/api/workspace/tree', async (c) => {
-    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
-      return c.json({ error: 'forbidden' }, 403);
-    }
-    try {
-      const tree = await fullTree(config.workspaceDir, 3);
-      return c.json({ root: config.workspaceDir, entries: tree });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 500);
-    }
-  });
-
-  app.get('/api/workspace/list', async (c) => {
-    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
-      return c.json({ error: 'forbidden' }, 403);
-    }
-    const p = c.req.query('path') || '';
-    try {
-      const items = await listDir(config.workspaceDir, p);
-      if (items == null) return c.json({ error: 'not-a-directory' }, 400);
-      return c.json({ path: p, items });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  app.get('/api/workspace/file', async (c) => {
-    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
-      return c.json({ error: 'forbidden' }, 403);
-    }
-    const p = c.req.query('path');
-    if (!p) return c.json({ error: 'path-required' }, 400);
-    try {
-      const result = await readFile(config.workspaceDir, p);
-      return c.json({ path: p, ...result });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  // --- component inbox ---
-  app.get('/api/inbox', async (c) => {
-    const snapshot = await inboxWatcher.snapshot();
-    return c.json(snapshot);
-  });
-
-  // --- live preview port detection ---
-  app.get('/api/preview/ports', async (c) => {
-    const ports = await detectPreviewPorts();
-    return c.json({ ports });
-  });
-
-  app.get('/api/preview/check', async (c) => {
-    const port = Number(c.req.query('port'));
-    if (!port) return c.json({ error: 'port-required' }, 400);
-    const host = c.req.query('host') || '127.0.0.1';
-    return c.json({ port, host, listening: await checkPort(port, host) });
-  });
-
-  // --- activity stream snapshot (WebSocket carries live updates) ---
-  app.get('/api/activity', (c) => c.json(activityBus.snapshot()));
-
-  // --- share-by-URL (AR-20) ---
-  app.post('/api/share', async (c) => {
-    const forbidden = require(c, 'share');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const role = body.role === 'client' ? 'client' : 'viewer';
-    const ttlSeconds = Number(body.ttlSeconds) || 60 * 60 * 24;
-    const label = body.label || (role === 'client' ? 'Client portal' : 'Viewer');
-    try {
-      const minted = await mintShareToken({
-        secret: config.shareSecret,
-        workspaceId: config.workspaceId,
-        role,
-        ttlSeconds,
-      });
-      tokenRegistry.add({
-        ...minted,
-        label,
-        createdAt: Date.now(),
-      });
-      const shareUrl = buildShareUrl({
-        shareBaseUrl: config.shareBaseUrl,
-        workspaceId: config.workspaceId,
-        token: minted.token,
-      });
-      activityBus.publish({
-        type: 'share-issued',
-        role,
-        sub: minted.sub,
-        exp: minted.exp,
-        label,
-      });
-      return c.json({ ...minted, shareUrl, label });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  app.get('/api/share', (c) => {
-    const forbidden = require(c, 'share');
-    if (forbidden) return forbidden;
-    return c.json({ tokens: tokenRegistry.list() });
-  });
-
-  app.delete('/api/share/:sub', (c) => {
-    const forbidden = require(c, 'share');
-    if (forbidden) return forbidden;
-    const sub = c.req.param('sub');
-    tokenRegistry.revoke(sub);
-    activityBus.publish({ type: 'share-revoked', sub });
-    return c.json({ ok: true, sub });
-  });
-
-  // --- bmo-sync folder sharing ---
-  // Pairing / detaching a folder and minting invites all run through the
-  // bmo-sync daemon (and, for invites, the central server). Partner-only.
-  app.get('/api/sync/status', async (c) => {
-    const forbidden = require(c, 'sync');
-    if (forbidden) return forbidden;
-    const status = await syncControl.status();
-    return c.json({
-      ...status,
-      workspaceDir: config.workspaceDir,
-      workspaceName: path.basename(config.workspaceDir),
-    });
-  });
-
-  app.post('/api/sync/pair', async (c) => {
-    const forbidden = require(c, 'sync');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    try {
-      const workspace = await syncControl.pair(body.inviteCode, config.workspaceDir);
-      activityBus.publish({
-        type: 'sync-paired',
-        workspaceId: workspace.workspaceId,
-        projectName: workspace.projectName,
-      });
-      return c.json({ ok: true, workspace });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  app.post('/api/sync/detach', async (c) => {
-    const forbidden = require(c, 'sync');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    try {
-      const result = await syncControl.detach(body.workspaceId);
-      activityBus.publish({ type: 'sync-detached', workspaceId: body.workspaceId });
-      return c.json({ ok: true, ...result });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  app.post('/api/sync/invite', async (c) => {
-    const forbidden = require(c, 'sync');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    try {
-      const invite = await syncControl.createInvite({
-        projectCode: body.projectCode,
-        displayName: body.displayName,
-        expiresHours: body.expiresHours,
-      });
-      return c.json({ ok: true, invite });
-    } catch (e) {
-      return c.json({ error: String(e.message || e) }, 400);
-    }
-  });
-
-  // --- chat REST fallback (for clients that can't WebSocket) ---
-  app.post('/api/chat', async (c) => {
-    const forbidden = require(c, 'chatWrite');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const prompt = (body.prompt || '').trim();
-    if (!prompt) return c.json({ error: 'prompt-required' }, 400);
-    const session = new AgentSession(activeAgent);
-    return new Promise((resolve) => {
-      const chunks = [];
-      session.on('chunk', (chunk) => chunks.push(chunk));
-      session.on('end', ({ code }) => {
-        resolve(c.json({ ok: true, exitCode: code, chunks }));
-      });
-      session.on('error', (err) => {
-        resolve(c.json({ ok: false, error: String(err.message || err) }, 500));
-      });
-      session.send(prompt, { cwd: config.workspaceDir, mode: body.mode });
-    });
-  });
-
-  // --- request-changes (client role) ---
-  const changeRequests = [];
-  app.post('/api/request-changes', async (c) => {
-    const forbidden = require(c, 'requestChanges');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const text = (body.text || '').trim();
-    if (!text) return c.json({ error: 'text-required' }, 400);
-    const session = c.get('session');
-    const entry = {
-      id: nanoid(12),
-      text,
-      from: session.sub || 'client',
-      ts: Date.now(),
-    };
-    changeRequests.push(entry);
-    activityBus.publish({ type: 'request-changes', entry });
-    return c.json({ ok: true, entry });
-  });
-
-  app.get('/api/request-changes', (c) => c.json({ requests: changeRequests }));
-
-  // --- frontend bundle (built by `npm run build:web`) ---
-  if (existsSync(config.webDir)) {
-    app.use(
-      '/*',
-      serveStatic({
-        root: path.relative(process.cwd(), config.webDir),
-      }),
-    );
-    // SPA fallback
-    app.notFound((c) => {
-      const indexHtmlPath = path.join(config.webDir, 'index.html');
-      if (existsSync(indexHtmlPath)) {
-        return new Response(readFileSync(indexHtmlPath), {
-          headers: { 'content-type': 'text/html' },
-        });
-      }
-      return c.text('wild-workspace: frontend not built; run `npm run build`', 200);
-    });
-  } else {
-    app.notFound((c) =>
-      c.text(
-        'wild-workspace API ready. Frontend bundle missing — run `npm run build` first.',
-        200,
-      ),
-    );
-  }
-
-  const httpServer = serve({
-    fetch: app.fetch,
-    port: config.port,
-    hostname: config.host,
-  });
-  // wait until the server is actually listening before continuing
-  await new Promise((resolve, reject) => {
-    if (httpServer.listening) return resolve();
-    httpServer.once('listening', resolve);
-    httpServer.once('error', reject);
-  });
-
-  // --- websocket bridge ---
-  const wss = new WebSocketServer({ noServer: true });
-  httpServer.on('upgrade', async (req, socket, head) => {
-    const reqUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
-    const supported = ['/ws/chat', '/ws/activity'];
-    if (!supported.includes(reqUrl.pathname)) {
-      socket.destroy();
-      return;
-    }
-    const tokenFromQuery = reqUrl.searchParams.get('t');
-    let role = null;
-    let sub = 'anon';
-    if (tokenFromQuery === config.partnerToken) {
-      role = ROLES.PARTNER;
-      sub = 'partner';
-    } else if (tokenFromQuery) {
-      const payload = await verifyShareToken(tokenFromQuery, config.shareSecret);
-      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
-        role = payload.role;
-        sub = payload.sub;
-      }
-    } else if (!config.publicMode) {
-      role = ROLES.PARTNER;
-      sub = 'local-partner';
-    }
-    // Deny: public mode with no token, or any invalid/revoked token. An
-    // invalid token must NOT silently fall back to partner. (Concern C1.)
-    if (!role) {
-      socket.destroy();
-      return;
-    }
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      ws._wsRole = role;
-      ws._wsSub = sub;
-      wss.emit('connection', ws, req, reqUrl.pathname);
-    });
-  });
-
-  wss.on('connection', (ws, req, route) => {
-    if (route === '/ws/activity') return wireActivityWs(ws);
-    if (route === '/ws/chat') return wireChatWs(ws);
-  });
-
-  function wireActivityWs(ws) {
-    const presence = activityBus.joinPresence({
-      sessionId: nanoid(10),
-      role: ws._wsRole,
-      label: ws._wsRole,
-    });
-    ws.send(
-      JSON.stringify({
-        type: 'snapshot',
-        snapshot: activityBus.snapshot(),
-        you: presence,
-      }),
-    );
-    const onEvent = (evt) => {
-      if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(evt));
-    };
-    activityBus.on('event', onEvent);
-    ws.on('message', (raw) => {
-      try {
-        const msg = JSON.parse(raw.toString());
-        if (msg.type === 'focus') {
-          activityBus.updateFocus(presence.sessionId, msg.focus || null);
-        }
-      } catch {}
-    });
-    ws.on('close', () => {
-      activityBus.off('event', onEvent);
-      activityBus.leavePresence(presence.sessionId);
-    });
-  }
-
-  function wireChatWs(ws) {
-    const cap = ROLE_CAPABILITIES[ws._wsRole];
-    let activeSession = null;
-    ws.send(JSON.stringify({ type: 'hello', role: ws._wsRole, agent: activeAgent?.id }));
-    ws.on('message', (raw) => {
-      let msg;
-      try {
-        msg = JSON.parse(raw.toString());
-      } catch {
-        ws.send(JSON.stringify({ type: 'error', message: 'invalid json' }));
-        return;
-      }
-      if (msg.type === 'send') {
-        if (!cap.chatWrite) {
-          ws.send(
-            JSON.stringify({ type: 'error', message: 'role not permitted to send' }),
-          );
-          return;
-        }
-        if (activeSession) activeSession.close();
-        const messageId = msg.messageId || nanoid(8);
-        activityBus.publish({
-          type: 'chat-user',
-          messageId,
-          role: ws._wsRole,
-          text: msg.text,
-        });
-        activeSession = new AgentSession(activeAgent);
-        activeSession.on('chunk', (chunk) => {
-          ws.send(JSON.stringify({ type: 'chunk', messageId, chunk }));
-          activityBus.publish({ type: 'chat-stream', messageId, chunk });
-          // Surface the turn's token/cost totals so the activity bar can show
-          // running usage — the ActivityBus accumulates events typed 'usage'.
-          if (chunk.type === 'usage' && chunk.usage) {
-            activityBus.publish({ type: 'usage', usage: chunk.usage });
-          }
-        });
-        activeSession.on('stderr', (text) => {
-          ws.send(JSON.stringify({ type: 'stderr', messageId, text }));
-        });
-        activeSession.on('end', ({ code }) => {
-          ws.send(JSON.stringify({ type: 'end', messageId, code }));
-          activityBus.publish({ type: 'chat-end', messageId, code });
-          activeSession = null;
-        });
-        activeSession.on('error', (err) => {
-          ws.send(
-            JSON.stringify({
-              type: 'error',
-              messageId,
-              message: String(err.message || err),
-            }),
-          );
-          activeSession = null;
-        });
-        activeSession.send(msg.text, {
-          cwd: config.workspaceDir,
-          mode: msg.mode,
-        });
-      } else if (msg.type === 'cancel') {
-        if (activeSession) activeSession.close();
-        activeSession = null;
-      }
-    });
-    ws.on('close', () => {
-      if (activeSession) activeSession.close();
-    });
-  }
-
-  return {
-    config,
-    app,
-    httpServer,
-    wss,
-    activityBus,
-    inboxWatcher,
-    tokenRegistry,
-    daemonBridge,
-    syncControl,
-    detectedAgents,
-    getActiveAgent: () => activeAgent,
-    async stop() {
-      try { inboxWatcher.stop(); } catch {}
-      try { daemonBridge?.stop(); } catch {}
-      try { wss.close(); } catch {}
-      await new Promise((resolve) => httpServer.close(resolve));
-    },
-  };
-}
-
-// Standalone entry — runs when executed directly (node server/src/index.mjs).
-const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === __filename;
-if (isDirectRun) {
-  createServer().then(async (s) => {
-    const { config } = s;
-    console.log(`\n  wild-workspace v${APP_VERSION}`);
-    console.log(`  workspace : ${config.workspaceDir}`);
-    console.log(`  url       : http://${config.host}:${config.port}`);
-    console.log(`  agent     : ${s.getActiveAgent()?.label || '(none detected)'}`);
-    if (config.publicMode) {
-      // Public mode: no anonymous access. Partner must authenticate.
-      console.log(`  mode      : PUBLIC — anonymous requests denied`);
-      console.log(`  partner   : append ?t=${config.partnerToken} to the URL`);
-    }
-    console.log('');
-    if (config.openBrowser) {
-      try {
-        const open = (await import('open')).default;
-        open(`http://${config.host}:${config.port}`);
-      } catch (e) {
-        // browser is best-effort; not having one isn't fatal
-      }
-    }
-  }).catch((err) => {
-    console.error('wild-workspace failed to start:', err);
-    process.exit(1);
-  });
-}
+// wild-workspace server bootstrap.
+// Three processes per AR-17:
+//   - this Node server (Hono): REST + WebSocket + frontend bundle
+//   - AI agent subprocess: spawned per chat session via agent.mjs
+//   - bmo-sync daemon (v1.x — out of scope for this scaffold)
+
+import { Hono } from 'hono';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { serve } from '@hono/node-server';
+import { WebSocketServer } from 'ws';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import {
+  buildConfig,
+  ROLES,
+  ROLE_CAPABILITIES,
+  APP_VERSION,
+  DEFAULT_AGENTS,
+  assertSecureBinding,
+} from './config.mjs';
+import { detectAgents, AgentSession, pickDefaultAgent } from './agent.mjs';
+import { mintShareToken, verifyShareToken, buildShareUrl, TokenRegistry } from './share.mjs';
+import { listDir, readFile, fullTree, workspaceSummary, safeResolve } from './fs.mjs';
+import { InboxWatcher } from './inbox.mjs';
+import { ActivityBus } from './activity.mjs';
+import { loadIdentity, saveIdentity, markOnboarded, TONES } from './agent-identity.mjs';
+import { ErrorReporter } from './error-reporter.mjs';
+import { DaemonBridge } from './daemon.mjs';
+import { DaemonSupervisor } from './daemon-supervisor.mjs';
+import { SyncControl } from './sync.mjs';
+import { detectPreviewPorts, checkPort } from './preview.mjs';
+import { nanoid } from 'nanoid';
+
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// --- structured logging ---------------------------------------------------
+// Single helper used everywhere so log lines are uniformly tagged + timestamped.
+// Goes to stdout; the launcher redirects stdout/stderr to a file. Categories:
+// [http], [ws], [chat], [onboarding], [identity], [auth].
+function log(tag, ...args) {
+  const ts = new Date().toISOString();
+  const line = args
+    .map((a) =>
+      typeof a === 'string'
+        ? a
+        : a instanceof Error
+          ? a.stack || String(a)
+          : JSON.stringify(a),
+    )
+    .join(' ');
+  process.stdout.write(`${ts} ${tag} ${line}\n`);
+}
+
+// --- chat session persistence ---------------------------------------------
+// The conversation's claude session id, stored in the workspace's gitignored
+// .wild-workspace/ dir. Persisting it means a browser reload — or a server
+// restart — doesn't wipe the agent's memory of the conversation.
+function chatSessionPath(dataDir) {
+  return path.join(dataDir, 'chat-session.json');
+}
+function loadChatSessionId(dataDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(chatSessionPath(dataDir), 'utf8'));
+    return typeof parsed.sessionId === 'string' ? parsed.sessionId : null;
+  } catch {
+    return null;
+  }
+}
+function saveChatSessionId(dataDir, sessionId) {
+  try {
+    writeFileSync(
+      chatSessionPath(dataDir),
+      JSON.stringify({ sessionId: sessionId || null }, null, 2),
+    );
+  } catch {
+    /* read-only fs — continuity degrades to in-memory for this run */
+  }
+}
+
+// Directory names already under .wild/imports/ — the auto-wake baseline.
+function scanImports(workspaceDir) {
+  try {
+    return readdirSync(path.join(workspaceDir, '.wild', 'imports'), {
+      withFileTypes: true,
+    })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export async function createServer(overrides = {}) {
+  const config = buildConfig(overrides);
+  // Refuse to start on a public bind with a forgeable default secret. (C1/C2)
+  assertSecureBinding(config);
+  if (!existsSync(config.dataDir)) mkdirSync(config.dataDir, { recursive: true });
+
+  const activityBus = new ActivityBus();
+  const tokenRegistry = new TokenRegistry();
+  const inboxWatcher = new InboxWatcher(config.workspaceDir).start();
+  inboxWatcher.on('change', (payload) => {
+    activityBus.publish({ type: 'inbox-change', snapshot: payload.snapshot });
+  });
+
+  // Bridge the bmo-sync daemon's event feed into the ActivityBus. The daemon
+  // is a separate process and may be absent — the bridge retries quietly.
+  // `overrides.daemonBridge: false` disables it (used by tests).
+  const daemonBridge =
+    overrides.daemonBridge === false
+      ? null
+      : new DaemonBridge(activityBus, { url: config.daemonUrl }).start();
+
+  // Owns the bmo-sync daemon's lifecycle: starts it (detached + window-hidden)
+  // if it isn't already running, so sync just works whenever wild-workspace is
+  // used. The daemon outlives the server by design — not stopped in stop().
+  // `overrides.daemonSupervisor: false` disables it; an object injects test
+  // seams. Autostart is gated by config.daemonAutostart (off under tests).
+  const daemonSupervisor =
+    overrides.daemonSupervisor === false
+      ? null
+      : new DaemonSupervisor({
+          httpBase: config.daemonHttpUrl,
+          // b-ii: hand the daemon the account token + relay so it opens the
+          // proxy link (lights up <slug>.venturewild.llc). Null when logged out.
+          accountToken: config.accountToken,
+          serverUrl: config.bmoSyncServerUrl,
+          ...(typeof overrides.daemonSupervisor === 'object'
+            ? overrides.daemonSupervisor
+            : {}),
+        });
+  const daemonReady =
+    daemonSupervisor && config.daemonAutostart
+      ? daemonSupervisor
+          .ensureRunning()
+          .catch((e) => ({ started: false, error: String(e?.message || e) }))
+      : Promise.resolve({ started: false, skipped: true });
+
+  // Control plane for bmo-sync folder sharing (pair / detach / invite).
+  // `overrides.syncControl` is a test seam.
+  const syncControl =
+    overrides.syncControl ||
+    new SyncControl({
+      daemonHttpUrl: config.daemonHttpUrl,
+      bmoSyncServerUrl: config.bmoSyncServerUrl,
+      adminKey: config.bmoSyncAdminKey,
+    });
+
+  // `overrides.agents` / `overrides.activeAgent` are a test/embedding seam:
+  // a caller can inject agent definitions instead of probing PATH.
+  const detectedAgents = overrides.agents || (await detectAgents());
+  let activeAgent = overrides.activeAgent || pickDefaultAgent(detectedAgents);
+
+  // Error telemetry — forwards agent crashes etc. to bmo-sync-server so
+  // support can diagnose client-machine issues. Off via
+  // WILD_WORKSPACE_NO_TELEMETRY=1 or overrides.errorReporter = false.
+  const errorReporter =
+    overrides.errorReporter === false
+      ? { report: () => {} }
+      : overrides.errorReporter ||
+        new ErrorReporter({
+          bmoSyncUrl: config.bmoSyncServerUrl,
+          workspaceId: config.workspaceId,
+          enabled: process.env.WILD_WORKSPACE_NO_TELEMETRY !== '1',
+        });
+
+  // --- chat turn orchestration ----------------------------------------------
+  // One conversation per workspace in v1 (single-user, single tab — PRD §5.5).
+  // Both user sends and auto-wake turns thread through one turn-runner so they
+  // share the agent's memory and never run two claude processes at once.
+  let chatSessionId = loadChatSessionId(config.dataDir);
+  const chatClients = new Set(); // every connected /ws/chat socket
+  let currentTurn = null; //       { session, messageId } — at most one at a time
+
+  function broadcastChat(obj) {
+    const data = JSON.stringify(obj);
+    for (const ws of chatClients) {
+      if (ws.readyState === ws.OPEN) ws.send(data);
+    }
+  }
+
+  /**
+   * Run one chat turn: spawn the agent, stream every chunk to every chat
+   * client, and persist the resulting session id so the next turn resumes it.
+   *   - `userText` / `note`: optional lines shown before the agent reply (a
+   *     user bubble, or an auto-wake system note).
+   *   - `auto`: an automated (auto-wake) turn — never interrupts a live turn,
+   *     and retries once if the run fails (PRD §13 A8).
+   * Returns false if the turn could not start (an auto turn while busy).
+   */
+  function runChatTurn({ prompt, mode, messageId, userText, note, auto = false }) {
+    if (currentTurn) {
+      if (auto) return false; //          auto-wake yields to a live turn
+      currentTurn.session.close(); //     a user send supersedes what's running
+      currentTurn = null;
+    }
+    const id = messageId || nanoid(8);
+    broadcastChat({ type: 'turn-begin', messageId: id, userText, note });
+    activityBus.publish({
+      type: 'chat-user',
+      messageId: id,
+      text: userText || note || prompt,
+    });
+
+    let retried = false;
+    const startTurn = () => {
+      const startedAt = Date.now();
+      log('[chat]', `turn-begin id=${id} auto=${auto} mode=${mode || 'build'} promptChars=${(prompt || '').length}`);
+      const session = new AgentSession(activeAgent);
+      currentTurn = { session, messageId: id };
+      let sawError = false;
+      session.on('chunk', (chunk) => {
+        if (chunk.type === 'error') sawError = true;
+        broadcastChat({ type: 'chunk', messageId: id, chunk });
+        activityBus.publish({ type: 'chat-stream', messageId: id, chunk });
+        // Surface the turn's token/cost totals so the activity bar can show
+        // running usage — the ActivityBus accumulates events typed 'usage'.
+        if (chunk.type === 'usage' && chunk.usage) {
+          activityBus.publish({ type: 'usage', usage: chunk.usage });
+        }
+      });
+      session.on('stderr', (text) => {
+        const trimmed = String(text || '').trim();
+        if (trimmed) log('[chat]', `stderr id=${id}: ${trimmed.slice(0, 240)}`);
+        broadcastChat({ type: 'stderr', messageId: id, text });
+      });
+      session.on('error', (err) => {
+        sawError = true;
+        const msg = String(err?.message || err);
+        log('[chat]', `error id=${id}: ${msg}`);
+        errorReporter.report({
+          category: 'agent',
+          message: msg,
+          stack: err?.stack,
+          agentLabel: activeAgent?.label,
+        });
+        broadcastChat({
+          type: 'error',
+          messageId: id,
+          message: msg,
+        });
+        currentTurn = null;
+      });
+      session.on('end', ({ code }) => {
+        currentTurn = null;
+        const elapsed = Date.now() - startedAt;
+        log('[chat]', `turn-end id=${id} code=${code} ms=${elapsed} closed=${session.closed} sawError=${sawError}`);
+        // Silent agent crash → telemetry. A non-zero exit (or signal-kill =
+        // code null) that wasn't user-cancelled is exactly the failure mode
+        // we want to see in the central log. Skip the user-cancelled and
+        // clean-exit cases.
+        if (!session.closed && (code !== 0 || sawError)) {
+          errorReporter.report({
+            category: 'agent',
+            message:
+              code === null
+                ? `agent subprocess killed by signal after ${elapsed}ms (no chunks)`
+                : `agent exited code=${code} after ${elapsed}ms sawError=${sawError}`,
+            agentLabel: activeAgent?.label,
+          });
+        }
+        // A turn closed on purpose — cancelled by the user, or superseded by
+        // the next turn — never reached a clean finish: it must not retry and
+        // must not persist its session id (that would clobber a reset, or
+        // resurrect a turn the user just stopped).
+        if (!session.closed) {
+          // An automated turn retries once on a failed run — `claude -p`
+          // spawned non-interactively hits transient API resets (PRD §13 A8).
+          if (auto && !retried && (sawError || code !== 0)) {
+            retried = true;
+            setTimeout(startTurn, 700);
+            return;
+          }
+          if (session.sessionId) {
+            chatSessionId = session.sessionId;
+            saveChatSessionId(config.dataDir, chatSessionId);
+          }
+        }
+        broadcastChat({ type: 'end', messageId: id, code });
+        activityBus.publish({ type: 'chat-end', messageId: id, code });
+      });
+      session.send(prompt, {
+        cwd: config.workspaceDir,
+        mode,
+        resumeSessionId: chatSessionId,
+      });
+    };
+    startTurn();
+    return true;
+  }
+
+  function resetChat() {
+    if (currentTurn) {
+      currentTurn.session.close();
+      currentTurn = null;
+    }
+    chatSessionId = null;
+    saveChatSessionId(config.dataDir, null);
+    broadcastChat({ type: 'reset' });
+  }
+
+  // --- auto-wake on import (AR-23) ------------------------------------------
+  // When `wild add` (or a bmo-sync delivery) drops a new component into
+  // .wild/imports/, wake the agent in PLAN mode to PROPOSE the integration.
+  // Plan mode is the consent boundary — it cannot edit files, so auto-wake
+  // only ever proposes; the user's reply applies it in Build mode.
+  const autoWakeMs = overrides.autoWakeDebounceMs ?? 1500;
+  const autoWakeEnabled = overrides.autoWake !== false;
+  let knownImports = new Set(scanImports(config.workspaceDir)); // startup baseline
+  let pendingWake = new Set();
+  let autoWakeTimer = null;
+
+  if (autoWakeEnabled) {
+    inboxWatcher.on('change', ({ snapshot }) => {
+      const current = new Set(snapshot.imports || []);
+      for (const name of current) {
+        if (!knownImports.has(name)) pendingWake.add(name);
+      }
+      knownImports = current;
+      if (pendingWake.size === 0) return;
+      // Debounce: `wild add` writes several files; collapse the burst.
+      clearTimeout(autoWakeTimer);
+      autoWakeTimer = setTimeout(fireAutoWake, autoWakeMs);
+    });
+  }
+
+  function fireAutoWake() {
+    const names = [...pendingWake];
+    if (names.length === 0) return;
+    pendingWake = new Set();
+    const list = names.join(', ');
+    const note = `📦 Imported ${list} — proposing an integration plan…`;
+    const prompt =
+      `A new wild component was just imported into this workspace: ` +
+      `${names.map((n) => `.wild/imports/${n}/`).join(', ')}. ` +
+      `You are in Plan mode, so you cannot modify files — only propose. ` +
+      `Read each component's README.md, look at the existing workspace, then ` +
+      `lay out how to integrate it: where the files should go, whether to ` +
+      `merge / overwrite / namespace, and any risks. Then stop so I can choose.`;
+    const started = runChatTurn({ prompt, mode: 'plan', note, auto: true });
+    if (!started) {
+      // The chat was busy — re-queue so the import isn't silently dropped.
+      for (const n of names) pendingWake.add(n);
+      clearTimeout(autoWakeTimer);
+      autoWakeTimer = setTimeout(fireAutoWake, 3000);
+    }
+  }
+
+  const app = new Hono();
+
+  // --- auth + role resolution ---
+  async function resolveRole(c) {
+    const auth = c.req.header('authorization');
+    if (auth?.startsWith('Bearer ')) {
+      const token = auth.slice('Bearer '.length).trim();
+      if (token === config.partnerToken) {
+        return { role: ROLES.PARTNER, sub: 'partner', source: 'partner-token' };
+      }
+      const payload = await verifyShareToken(token, config.shareSecret);
+      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
+        return {
+          role: payload.role,
+          sub: payload.sub,
+          workspaceId: payload.workspaceId,
+          source: 'share-jwt',
+          exp: payload.exp,
+        };
+      }
+    }
+    const queryToken = c.req.query('t');
+    if (queryToken) {
+      // A browser opening the workspace URL can only carry a token in the
+      // query string, not an Authorization header — so the partner token is
+      // accepted here too, mirroring the WebSocket upgrade handler.
+      if (queryToken === config.partnerToken) {
+        return { role: ROLES.PARTNER, sub: 'partner', source: 'partner-token-query' };
+      }
+      const payload = await verifyShareToken(queryToken, config.shareSecret);
+      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
+        return {
+          role: payload.role,
+          sub: payload.sub,
+          workspaceId: payload.workspaceId,
+          source: 'share-jwt-query',
+          exp: payload.exp,
+        };
+      }
+    }
+    // Default for local partner UX — same machine, no token expected.
+    if (!config.publicMode) {
+      return { role: ROLES.PARTNER, sub: 'local-partner', source: 'localhost' };
+    }
+    // Public mode with no valid token: deny. No anonymous viewer access —
+    // a share JWT or the partner token is required. (Concern C1.)
+    return { role: null, sub: 'anon', source: 'unauth', denied: true };
+  }
+
+  function require(c, capability) {
+    const cap = ROLE_CAPABILITIES[c.get('role')];
+    if (!cap || !cap[capability]) {
+      return c.json({ error: 'forbidden', capability, role: c.get('role') }, 403);
+    }
+    return null;
+  }
+
+  app.use('*', async (c, next) => {
+    const session = await resolveRole(c);
+    c.set('role', session.role);
+    c.set('session', session);
+    // Block the API for denied (non-localhost, unauthenticated) requests, but
+    // let static assets and the health check through so the SPA can still
+    // load and prompt for a token. (Concern C1.)
+    if (session.denied && c.req.path.startsWith('/api/') && c.req.path !== '/api/health') {
+      log('[auth]', `denied ${c.req.method} ${c.req.path} src=${session.source}`);
+      return c.json({ error: 'unauthorized' }, 401);
+    }
+    await next();
+  });
+
+  // Lightweight HTTP request log — every /api/* call, with status + duration.
+  // Static asset traffic is noisy and uninteresting, so we skip it.
+  app.use('/api/*', async (c, next) => {
+    const t0 = Date.now();
+    await next();
+    const ms = Date.now() - t0;
+    const role = c.get('role') || 'anon';
+    log('[http]', `${c.req.method} ${c.req.path} ${c.res.status} ${ms}ms role=${role}`);
+  });
+
+  // --- meta ---
+  app.get('/api/health', (c) =>
+    c.json({ status: 'ok', version: APP_VERSION, ts: Date.now() }),
+  );
+
+  app.get('/api/session', (c) => {
+    const session = c.get('session');
+    const role = c.get('role');
+    const identity = loadIdentity(config.dataDir);
+    return c.json({
+      version: APP_VERSION,
+      role,
+      capabilities: ROLE_CAPABILITIES[role],
+      workspace: workspaceSummary(config.workspaceDir),
+      workspaceId: config.workspaceId,
+      session,
+      agent: activeAgent
+        ? { id: activeAgent.id, label: activeAgent.label, available: activeAgent.available }
+        : null,
+      identity,
+      onboarded: Boolean(identity?.onboardedAt),
+      shareBaseUrl: config.shareBaseUrl,
+      // `account` is set after the user runs `wild-workspace login`. The UI
+      // uses it to show "you are <slug>" and to seed step 4 of onboarding
+      // with the actual <slug>.venturewild.llc URL. accountToken is NOT
+      // exposed — it stays in server-side config only.
+      account: config.account,
+    });
+  });
+
+  // --- agent identity (onboarding) ---
+  // Persisted to <dataDir>/agent-identity.json. Absence of this file is the
+  // signal the UI uses to launch the 5-step onboarding flow.
+  app.get('/api/agent/identity', (c) => {
+    const identity = loadIdentity(config.dataDir);
+    return c.json({ identity, tones: TONES });
+  });
+
+  app.post('/api/agent/identity', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const saved = saveIdentity(config.dataDir, {
+        name: body.name,
+        tone: body.tone,
+        color: body.color,
+        connectedServices: body.connectedServices,
+      });
+      log('[identity]', `saved name=${saved.name} tone=${saved.tone} color=${saved.color}`);
+      activityBus.publish({ type: 'identity-changed', name: saved.name, tone: saved.tone });
+      return c.json({ identity: saved });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.post('/api/agent/onboarded', (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    try {
+      const saved = markOnboarded(config.dataDir);
+      log('[onboarding]', `complete name=${saved.name}`);
+      activityBus.publish({ type: 'onboarded', at: saved.onboardedAt });
+      return c.json({ identity: saved });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  // --- onboarding step 2: agent peeks at a folder ---
+  // The browser sends a small sample of the chosen folder's contents — file
+  // names + a short head of each text file — and we ask the agent to react
+  // in one or two sentences. Runs through the normal turn-runner; the browser
+  // supplies the messageId so the onboarding overlay can subscribe to /ws/chat
+  // and stream the reaction back into a bubble next to the dropzone — the
+  // "agent reacts in ~2s" beat the locked plan calls the highest-converting moment.
+  app.post('/api/onboarding/peek', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const files = Array.isArray(body.files) ? body.files.slice(0, 80) : [];
+    const folderName = (body.folderName || 'this folder').slice(0, 80);
+    if (files.length === 0) return c.json({ error: 'no-files' }, 400);
+    const sample = files
+      .map((f) => {
+        const head = typeof f.head === 'string' ? f.head.slice(0, 600) : '';
+        return head
+          ? `--- ${f.path}\n${head}`
+          : `--- ${f.path}`;
+      })
+      .join('\n');
+    const identity = loadIdentity(config.dataDir);
+    const youAre = identity?.name
+      ? `You are ${identity.name}, a ${identity.tone || 'concise'} AI assistant just meeting your human for the first time.`
+      : `You are an AI assistant just meeting your human for the first time.`;
+    const prompt =
+      `${youAre} They just showed you a folder called "${folderName}" with ` +
+      `${files.length} file${files.length === 1 ? '' : 's'}. Below is a quick ` +
+      `sample of what's inside. In ONE or TWO short sentences, react: name ` +
+      `what you see, then propose ONE specific, concrete thing you could do ` +
+      `with it that would be useful. Be specific — reference real filenames ` +
+      `or content. Don't ask permission, don't list options, don't introduce ` +
+      `yourself. Just react like a smart friend who just glanced at the desk.\n\n` +
+      sample;
+    const messageId =
+      typeof body.messageId === 'string' && body.messageId.trim()
+        ? body.messageId.trim().slice(0, 64)
+        : undefined;
+    log('[onboarding]', `peek folder=${folderName} files=${files.length} sampleBytes=${sample.length} mid=${messageId || '(auto)'}`);
+    const started = runChatTurn({
+      prompt,
+      mode: 'plan',
+      messageId,
+      note: `👀 ${identity?.name || 'Your agent'} is looking at ${folderName}…`,
+      auto: true,
+    });
+    return c.json({ ok: true, sampled: files.length, started: started !== false });
+  });
+
+  // --- onboarding step 5: kick off the user's first real job ---
+  // The browser picks one of three known job kinds; the server builds the
+  // matching prompt incorporating the agent's tone + the optional peek context
+  // so the long instruction shape stays server-side (the user sees a clean
+  // "Started: …" note, not the raw prompt). Same WS streaming contract as
+  // peek — the browser supplies the messageId.
+  app.post('/api/onboarding/start-job', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const kind = typeof body.kind === 'string' ? body.kind : '';
+    const messageId =
+      typeof body.messageId === 'string' && body.messageId.trim()
+        ? body.messageId.trim().slice(0, 64)
+        : undefined;
+    const peekFolder =
+      typeof body.peekFolderName === 'string'
+        ? body.peekFolderName.slice(0, 80)
+        : null;
+    const identity = loadIdentity(config.dataDir);
+    const tone = identity?.tone || 'concise';
+    const name = identity?.name || 'your agent';
+    const youAre = `You are ${name}, a ${tone} AI assistant. Your human just finished a 5-step onboarding and picked their first job. Stay in character.`;
+    let prompt;
+    let note;
+    if (kind === 'survey') {
+      prompt =
+        `${youAre} Look at the wild-workspace folder this server runs in — ` +
+        `read CLAUDE.md, README.md, and any package.json or top-level docs ` +
+        `you find. In ONE short paragraph, summarize what this project is ` +
+        `and what's notable about it. Be ${tone}. Don't ask permission ` +
+        `first — just go. Finish with a single concrete next-step question.`;
+      note = `🔎 First job — ${name} is reading your workspace…`;
+    } else if (kind === 'startup') {
+      const folderHint = peekFolder
+        ? ` They showed you a folder called "${peekFolder}" earlier — feel free to reference it.`
+        : '';
+      prompt =
+        `${youAre} Your human wants to start a new project but hasn't said ` +
+        `what yet.${folderHint} In ONE or TWO sentences, ask the single ` +
+        `most useful question that will help you understand what they want ` +
+        `to build today. Be ${tone}, warm, and concrete — no list of options.`;
+      note = `🚀 First job — ${name} is figuring out what to build with you…`;
+    } else if (kind === 'chat') {
+      prompt =
+        `${youAre} Your human picked the "just chat" option — they want to ` +
+        `get to know you, no agenda yet. Say a brief hello, then ask ONE ` +
+        `short question that will help you find a job for them today. Be ` +
+        `${tone}. Don't introduce yourself by name (they already named you).`;
+      note = `💬 First job — ${name} is settling in…`;
+    } else {
+      return c.json({ error: 'unknown-job-kind' }, 400);
+    }
+    log('[onboarding]', `start-job kind=${kind} mid=${messageId || '(auto)'} peek=${peekFolder || '-'}`);
+    const started = runChatTurn({
+      prompt,
+      mode: 'build',
+      messageId,
+      note,
+      auto: true,
+    });
+    return c.json({ ok: true, started: started !== false });
+  });
+
+  app.get('/api/agents', (c) =>
+    c.json({
+      available: detectedAgents.map(({ id, label, description, available, resolvedPath }) => ({
+        id,
+        label,
+        description,
+        available,
+        resolvedPath,
+      })),
+      active: activeAgent?.id,
+    }),
+  );
+
+  app.post('/api/agents/select', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const next = detectedAgents.find((a) => a.id === body.id);
+    if (!next) return c.json({ error: 'unknown-agent', id: body.id }, 400);
+    activeAgent = next;
+    activityBus.publish({ type: 'agent-changed', agentId: next.id });
+    return c.json({ ok: true, active: activeAgent.id });
+  });
+
+  // --- workspace files ---
+  app.get('/api/workspace/tree', async (c) => {
+    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
+      return c.json({ error: 'forbidden' }, 403);
+    }
+    try {
+      const tree = await fullTree(config.workspaceDir, 3);
+      return c.json({ root: config.workspaceDir, entries: tree });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 500);
+    }
+  });
+
+  app.get('/api/workspace/list', async (c) => {
+    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
+      return c.json({ error: 'forbidden' }, 403);
+    }
+    const p = c.req.query('path') || '';
+    try {
+      const items = await listDir(config.workspaceDir, p);
+      if (items == null) return c.json({ error: 'not-a-directory' }, 400);
+      return c.json({ path: p, items });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.get('/api/workspace/file', async (c) => {
+    if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
+      return c.json({ error: 'forbidden' }, 403);
+    }
+    const p = c.req.query('path');
+    if (!p) return c.json({ error: 'path-required' }, 400);
+    try {
+      const result = await readFile(config.workspaceDir, p);
+      return c.json({ path: p, ...result });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  // --- component inbox ---
+  app.get('/api/inbox', async (c) => {
+    const snapshot = await inboxWatcher.snapshot();
+    return c.json(snapshot);
+  });
+
+  // --- live preview port detection ---
+  app.get('/api/preview/ports', async (c) => {
+    const ports = await detectPreviewPorts();
+    return c.json({ ports });
+  });
+
+  app.get('/api/preview/check', async (c) => {
+    const port = Number(c.req.query('port'));
+    if (!port) return c.json({ error: 'port-required' }, 400);
+    const host = c.req.query('host') || '127.0.0.1';
+    return c.json({ port, host, listening: await checkPort(port, host) });
+  });
+
+  // --- activity stream snapshot (WebSocket carries live updates) ---
+  app.get('/api/activity', (c) => c.json(activityBus.snapshot()));
+
+  // --- share-by-URL (AR-20) ---
+  app.post('/api/share', async (c) => {
+    const forbidden = require(c, 'share');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const role = body.role === 'client' ? 'client' : 'viewer';
+    const ttlSeconds = Number(body.ttlSeconds) || 60 * 60 * 24;
+    const label = body.label || (role === 'client' ? 'Client portal' : 'Viewer');
+    try {
+      const minted = await mintShareToken({
+        secret: config.shareSecret,
+        workspaceId: config.workspaceId,
+        role,
+        ttlSeconds,
+      });
+      tokenRegistry.add({
+        ...minted,
+        label,
+        createdAt: Date.now(),
+      });
+      const shareUrl = buildShareUrl({
+        shareBaseUrl: config.shareBaseUrl,
+        workspaceId: config.workspaceId,
+        token: minted.token,
+      });
+      activityBus.publish({
+        type: 'share-issued',
+        role,
+        sub: minted.sub,
+        exp: minted.exp,
+        label,
+      });
+      return c.json({ ...minted, shareUrl, label });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.get('/api/share', (c) => {
+    const forbidden = require(c, 'share');
+    if (forbidden) return forbidden;
+    return c.json({ tokens: tokenRegistry.list() });
+  });
+
+  app.delete('/api/share/:sub', (c) => {
+    const forbidden = require(c, 'share');
+    if (forbidden) return forbidden;
+    const sub = c.req.param('sub');
+    tokenRegistry.revoke(sub);
+    activityBus.publish({ type: 'share-revoked', sub });
+    return c.json({ ok: true, sub });
+  });
+
+  // --- bmo-sync folder sharing ---
+  // Pairing / detaching a folder and minting invites all run through the
+  // bmo-sync daemon (and, for invites, the central server). Partner-only.
+  app.get('/api/sync/status', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const status = await syncControl.status();
+    return c.json({
+      ...status,
+      workspaceDir: config.workspaceDir,
+      workspaceName: path.basename(config.workspaceDir),
+    });
+  });
+
+  app.post('/api/sync/pair', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const workspace = await syncControl.pair(body.inviteCode, config.workspaceDir);
+      activityBus.publish({
+        type: 'sync-paired',
+        workspaceId: workspace.workspaceId,
+        projectName: workspace.projectName,
+      });
+      return c.json({ ok: true, workspace });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.post('/api/sync/detach', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const result = await syncControl.detach(body.workspaceId);
+      activityBus.publish({ type: 'sync-detached', workspaceId: body.workspaceId });
+      return c.json({ ok: true, ...result });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.post('/api/sync/invite', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      const invite = await syncControl.createInvite({
+        projectCode: body.projectCode,
+        displayName: body.displayName,
+        expiresHours: body.expiresHours,
+      });
+      return c.json({ ok: true, invite });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  // --- C12-e conflict surface ---
+  // The daemon detects local-vs-peer divergence and stores both versions
+  // in its back-office. The agent (and the human-fallback badge) drives
+  // resolution through these routes.
+  app.get('/api/conflicts', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const conflicts = await syncControl.listConflicts();
+    return c.json({ conflicts });
+  });
+
+  app.get('/api/conflicts/view', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const workspaceId = c.req.query('workspaceId');
+    const filePath = c.req.query('path');
+    if (!workspaceId || !filePath) {
+      return c.json({ error: 'workspaceId and path are required' }, 400);
+    }
+    try {
+      const view = await syncControl.viewConflict(workspaceId, filePath);
+      if (!view) return c.json({ error: 'not found' }, 404);
+      return c.json(view);
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  app.post('/api/conflicts/resolve', async (c) => {
+    const forbidden = require(c, 'sync');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    try {
+      await syncControl.resolveConflict(body.workspaceId, body.path, body.action);
+      activityBus.publish({
+        type: 'sync-conflict-resolved',
+        workspaceId: body.workspaceId,
+        path: body.path,
+        action: body.action,
+      });
+      return c.json({ ok: true });
+    } catch (e) {
+      return c.json({ error: String(e.message || e) }, 400);
+    }
+  });
+
+  // --- request-changes (client role) ---
+  const changeRequests = [];
+  app.post('/api/request-changes', async (c) => {
+    const forbidden = require(c, 'requestChanges');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const text = (body.text || '').trim();
+    if (!text) return c.json({ error: 'text-required' }, 400);
+    const session = c.get('session');
+    const entry = {
+      id: nanoid(12),
+      text,
+      from: session.sub || 'client',
+      ts: Date.now(),
+    };
+    changeRequests.push(entry);
+    activityBus.publish({ type: 'request-changes', entry });
+    return c.json({ ok: true, entry });
+  });
+
+  app.get('/api/request-changes', (c) => c.json({ requests: changeRequests }));
+
+  // --- frontend bundle (built by `npm run build:web`) ---
+  if (existsSync(config.webDir)) {
+    app.use(
+      '/*',
+      serveStatic({
+        root: path.relative(process.cwd(), config.webDir),
+      }),
+    );
+    // SPA fallback
+    app.notFound((c) => {
+      const indexHtmlPath = path.join(config.webDir, 'index.html');
+      if (existsSync(indexHtmlPath)) {
+        return new Response(readFileSync(indexHtmlPath), {
+          headers: { 'content-type': 'text/html' },
+        });
+      }
+      return c.text('wild-workspace: frontend not built; run `npm run build`', 200);
+    });
+  } else {
+    app.notFound((c) =>
+      c.text(
+        'wild-workspace API ready. Frontend bundle missing — run `npm run build` first.',
+        200,
+      ),
+    );
+  }
+
+  const httpServer = serve({
+    fetch: app.fetch,
+    port: config.port,
+    hostname: config.host,
+  });
+  // wait until the server is actually listening before continuing
+  await new Promise((resolve, reject) => {
+    if (httpServer.listening) return resolve();
+    httpServer.once('listening', resolve);
+    httpServer.once('error', reject);
+  });
+
+  // --- websocket bridge ---
+  const wss = new WebSocketServer({ noServer: true });
+  httpServer.on('upgrade', async (req, socket, head) => {
+    const reqUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const supported = ['/ws/chat', '/ws/activity'];
+    if (!supported.includes(reqUrl.pathname)) {
+      socket.destroy();
+      return;
+    }
+    const tokenFromQuery = reqUrl.searchParams.get('t');
+    let role = null;
+    let sub = 'anon';
+    if (tokenFromQuery === config.partnerToken) {
+      role = ROLES.PARTNER;
+      sub = 'partner';
+    } else if (tokenFromQuery) {
+      const payload = await verifyShareToken(tokenFromQuery, config.shareSecret);
+      if (payload && !tokenRegistry.isRevoked(payload.sub)) {
+        role = payload.role;
+        sub = payload.sub;
+      }
+    } else if (!config.publicMode) {
+      role = ROLES.PARTNER;
+      sub = 'local-partner';
+    }
+    // Deny: public mode with no token, or any invalid/revoked token. An
+    // invalid token must NOT silently fall back to partner. (Concern C1.)
+    if (!role) {
+      log('[ws]', `denied ${reqUrl.pathname} (no valid token)`);
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      ws._wsRole = role;
+      ws._wsSub = sub;
+      log('[ws]', `open ${reqUrl.pathname} role=${role} sub=${sub}`);
+      wss.emit('connection', ws, req, reqUrl.pathname);
+    });
+  });
+
+  wss.on('connection', (ws, req, route) => {
+    if (route === '/ws/activity') return wireActivityWs(ws);
+    if (route === '/ws/chat') return wireChatWs(ws);
+  });
+
+  function wireActivityWs(ws) {
+    const presence = activityBus.joinPresence({
+      sessionId: nanoid(10),
+      role: ws._wsRole,
+      label: ws._wsRole,
+    });
+    ws.send(
+      JSON.stringify({
+        type: 'snapshot',
+        snapshot: activityBus.snapshot(),
+        you: presence,
+      }),
+    );
+    const onEvent = (evt) => {
+      if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(evt));
+    };
+    activityBus.on('event', onEvent);
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'focus') {
+          activityBus.updateFocus(presence.sessionId, msg.focus || null);
+        }
+      } catch {}
+    });
+    ws.on('close', () => {
+      activityBus.off('event', onEvent);
+      activityBus.leavePresence(presence.sessionId);
+    });
+  }
+
+  function wireChatWs(ws) {
+    const cap = ROLE_CAPABILITIES[ws._wsRole];
+    chatClients.add(ws);
+    ws.send(JSON.stringify({ type: 'hello', role: ws._wsRole, agent: activeAgent?.id }));
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        ws.send(JSON.stringify({ type: 'error', message: 'invalid json' }));
+        return;
+      }
+      if (msg.type === 'send') {
+        if (!cap.chatWrite) {
+          ws.send(
+            JSON.stringify({ type: 'error', message: 'role not permitted to send' }),
+          );
+          return;
+        }
+        // The turn-runner is server-level: it streams to every chat client and
+        // resumes the persisted claude session, so the agent keeps its memory.
+        runChatTurn({
+          prompt: msg.text,
+          mode: msg.mode,
+          messageId: msg.messageId,
+          userText: msg.text,
+        });
+      } else if (msg.type === 'cancel') {
+        if (currentTurn) {
+          currentTurn.session.close();
+          currentTurn = null;
+        }
+      } else if (msg.type === 'reset') {
+        // "New chat" — drop the resumed session so the next turn starts fresh.
+        if (cap.chatWrite) resetChat();
+      }
+    });
+    ws.on('close', () => {
+      chatClients.delete(ws);
+      log('[ws]', `close /ws/chat sub=${ws._wsSub} remaining=${chatClients.size}`);
+      // The turn itself keeps running — it may have other watchers, and it
+      // still needs to finish to persist the session id.
+    });
+  }
+
+  return {
+    config,
+    app,
+    httpServer,
+    wss,
+    activityBus,
+    inboxWatcher,
+    tokenRegistry,
+    daemonBridge,
+    daemonSupervisor,
+    daemonReady,
+    syncControl,
+    detectedAgents,
+    getActiveAgent: () => activeAgent,
+    async stop() {
+      try { clearTimeout(autoWakeTimer); } catch {}
+      try { currentTurn?.session.close(); } catch {}
+      try { inboxWatcher.stop(); } catch {}
+      try { daemonBridge?.stop(); } catch {}
+      // The daemon is deliberately NOT stopped here — it is detached so sync
+      // keeps running after wild-workspace closes. `wild-workspace daemon
+      // stop` is the explicit off-switch.
+      try { wss.close(); } catch {}
+      await new Promise((resolve) => httpServer.close(resolve));
+    },
+  };
+}
+
+// Standalone entry — runs when executed directly (node server/src/index.mjs).
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (isDirectRun) {
+  createServer().then(async (s) => {
+    const { config } = s;
+    console.log(`\n  wild-workspace v${APP_VERSION}`);
+    console.log(`  workspace : ${config.workspaceDir}`);
+    console.log(`  url       : http://${config.host}:${config.port}`);
+    console.log(`  agent     : ${s.getActiveAgent()?.label || '(none detected)'}`);
+    if (config.publicMode) {
+      // Public mode: no anonymous access. Partner must authenticate.
+      console.log(`  mode      : PUBLIC — anonymous requests denied`);
+      console.log(`  partner   : append ?t=${config.partnerToken} to the URL`);
+    }
+    console.log('');
+    if (config.openBrowser) {
+      try {
+        const open = (await import('open')).default;
+        open(`http://${config.host}:${config.port}`);
+      } catch (e) {
+        // browser is best-effort; not having one isn't fatal
+      }
+    }
+  }).catch((err) => {
+    console.error('wild-workspace failed to start:', err);
+    process.exit(1);
+  });
+}