@venturewild/workspace 0.1.2 → 0.1.4

package/server/src/index.mjs

@@ -1,1330 +1,1330 @@
-// 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 { probeAgentReadiness } from './agent-readiness.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 { loadAccount } from './account.mjs';
-import { runDoctor } from './doctor.mjs';
-import { appendLine, tailFile, logFile, TAILABLE, globalDir } from './logpaths.mjs';
-import { SessionReporter } from './session-reporter.mjs';
-import { TranscriptRecorder } from './transcript.mjs';
-import { loadObservabilityConsent, setObservabilityConsent } from './observability.mjs';
-import { spawn } from 'node:child_process';
-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',
-        });
-
-  // Proactive, consented session + install observability (session-reporter.mjs).
-  // Default-on with a clear disclosure at onboarding; off via the consent toggle
-  // or the WILD_WORKSPACE_NO_TELEMETRY kill switch. Inert in tests and without an
-  // account token. Carries WHAT happened + install health, never the words —
-  // conversation content is the separate transcript channel.
-  let observability = loadObservabilityConsent(config.dataDir);
-  const sessionEnabled = () =>
-    observability.enabled &&
-    process.env.WILD_WORKSPACE_NO_TELEMETRY !== '1' &&
-    !process.env.VITEST &&
-    config.nodeEnv !== 'test';
-  const sessionReporter =
-    overrides.sessionReporter === false
-      ? { ingest() {}, flush() {}, start() {}, stop() {}, setEnabled() {} }
-      : overrides.sessionReporter ||
-        new SessionReporter({
-          bmoSyncUrl: config.bmoSyncServerUrl,
-          accountToken: config.accountToken,
-          slug: config.account?.slug || null,
-          workspaceId: config.workspaceId,
-          sessionId: overrides.sessionId || nanoid(12),
-          enabled: sessionEnabled(),
-        });
-  // Conversation *content* channel (transcript.mjs) — separate from the feed.
-  // Appends markdown to ~/.wild-workspace/transcripts/<workspaceId>/ (OUTSIDE the
-  // synced repo); forwarding to us is consent-gated. Noop under the test runner so
-  // it never writes into a real home dir.
-  const transcriptForward = ({ markdown, date }) => {
-    if (!sessionEnabled() || !config.accountToken) return;
-    const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
-    const ctrl = new AbortController();
-    const t = setTimeout(() => ctrl.abort(), 5000);
-    Promise.resolve()
-      .then(() =>
-        fetch(url, {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({
-            account_token: config.accountToken,
-            slug: config.account?.slug || null,
-            workspace_id: config.workspaceId,
-            kind: 'transcript',
-            date,
-            markdown,
-            sent_at: Math.floor(Date.now() / 1000),
-          }),
-          signal: ctrl.signal,
-        }),
-      )
-      .catch(() => {})
-      .finally(() => clearTimeout(t));
-  };
-  const transcriptRecorder =
-    overrides.transcriptRecorder === false || process.env.VITEST || config.nodeEnv === 'test'
-      ? { ingest() {}, flush() {}, stop() {} }
-      : new TranscriptRecorder({
-          dir: path.join(globalDir(), 'transcripts', config.workspaceId),
-          agentName: loadIdentity(config.dataDir)?.name || activeAgent?.label || 'Agent',
-          forwardImpl: transcriptForward,
-        });
-
-  activityBus.on('event', (e) => {
-    try { sessionReporter.ingest(e); } catch { /* never let telemetry break the bus */ }
-    try { transcriptRecorder.ingest(e); } catch { /* nor the transcript */ }
-  });
-  sessionReporter.start();
-
-  // --- 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' };
-      }
-      // The operator (support) token — header-only, and only when the channel is
-      // explicitly enabled (a token exists). Never accepted via `?t=` (below),
-      // so it can't leak through URLs/logs/referrer (SECURITY.md S1).
-      if (config.operatorToken && token === config.operatorToken) {
-        return { role: ROLES.OPERATOR, sub: 'operator', source: 'operator-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,
-      // Consent state for the proactive observability feed, so settings/onboarding
-      // can show + toggle it. The disclosure copy lives in the UI.
-      observability: { enabled: observability.enabled, version: observability.version },
-    });
-  });
-
-  // --- 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 });
-  });
-
-  // --- agent readiness (the agent-login gate) ---
-  // "Is the wrapped agent installed AND signed in?" detectAgents() only proves
-  // the binary is on PATH; this proves a turn will actually work. Onboarding
-  // calls this before its folder-peek wow beat so a not-signed-in user gets a
-  // calm "sign in to Claude" step instead of a broken error bubble (the §3.2
-  // open question in docs/user-experience.md). See agent-readiness.mjs.
-  //
-  // Cached briefly: a 'ready' verdict rarely flips, and the probe spawns a
-  // subprocess. `?fresh=1` forces a re-probe (the gate's "I've signed in" button
-  // sends it so the user isn't stuck behind a stale 'login' verdict).
-  let _readinessCache = null; // { at, verdict }
-  const READINESS_TTL_MS = 30_000;
-  const agentTag = (a) => (a ? { id: a.id, label: a.label } : null);
-  app.get('/api/agent/readiness', async (c) => {
-    const forbidden = require(c, 'chat');
-    if (forbidden) return forbidden;
-    const fresh = c.req.query('fresh') === '1';
-    const now = Date.now();
-    if (!fresh && _readinessCache && now - _readinessCache.at < READINESS_TTL_MS) {
-      return c.json({ agent: agentTag(activeAgent), ...(_readinessCache.verdict) });
-    }
-    const verdict = await probeAgentReadiness(activeAgent);
-    _readinessCache = { at: now, verdict };
-    log('[onboarding]', `readiness agent=${activeAgent?.id || '-'} status=${verdict.status}${verdict.email ? ` email=${verdict.email}` : ''}`);
-    return c.json({ agent: agentTag(activeAgent), ...verdict });
-  });
-
-  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);
-    }
-  });
-
-  // Consent toggle for the proactive observability feed (default-on — see
-  // observability.mjs). Owner-only; applied live to the reporter, no restart.
-  app.post('/api/observability/consent', async (c) => {
-    const forbidden = require(c, 'chatWrite');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const enabled = body.enabled !== false;
-    observability = setObservabilityConsent(config.dataDir, enabled);
-    sessionReporter.setEnabled(sessionEnabled());
-    activityBus.publish({ type: 'observability-consent', enabled });
-    log('[observability]', `consent set enabled=${enabled}`);
-    return c.json({ observability: { enabled: observability.enabled, version: observability.version } });
-  });
-
-  // --- 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 });
-  });
-
-  // --- operator channel (consented support; OFF unless a token is set) -------
-  // The dedicated operator token (operator.mjs) maps to the `operator` role in
-  // resolveRole; every route here gates on the `operate` capability. When the
-  // channel is disabled (no token) the routes 404 so the surface is invisible.
-  // Each call is audit-logged to operator.log AND surfaced in the activity feed
-  // (CLAUDE.md principle #5 — both peers see what happened). The actions are a
-  // CURATED ALLOWLIST — never arbitrary shell (docs/SECURITY.md).
-  const operatorDeps = {
-    runDoctor: (o) => runDoctor(o),
-    detectAgents,
-    loadAccount,
-    spawn,
-    ...(overrides.operatorDeps || {}),
-  };
-  const operatorEnabled = () => Boolean(config.operatorToken);
-  function auditOperator(c, action, detail) {
-    const s = c.get('session') || {};
-    appendLine('operator', `${action} by=${s.sub || 'operator'} src=${s.source || '-'} ${detail || ''}`.trim());
-    activityBus.publish({ type: 'operator-action', action, detail: detail || null, at: Date.now() });
-  }
-
-  // Curated remediation actions. Each reuses an existing seam; none runs an
-  // arbitrary command. (`restart-server` is intentionally absent — exiting the
-  // process would sever the very tunnel we reach the user through on a machine
-  // without the always-on supervisor; deferred — see SECURITY.md.)
-  const OPERATOR_ACTIONS = {
-    'run-doctor': async () => operatorDeps.runDoctor({ config }),
-    'restart-daemon': async () => {
-      if (!daemonSupervisor) return { restarted: false, reason: 'daemon-supervisor-disabled' };
-      await daemonSupervisor.stop().catch(() => {});
-      return daemonSupervisor.ensureRunning();
-    },
-    'relink-account': async () => {
-      const account = operatorDeps.loadAccount(config.dataDir);
-      if (daemonSupervisor) {
-        await daemonSupervisor.stop().catch(() => {});
-        await daemonSupervisor.ensureRunning().catch(() => {});
-      }
-      return { relinked: Boolean(account?.slug), slug: account?.slug || null, email: account?.email || null };
-    },
-    'redetect-agent': async () => {
-      const agents = (await operatorDeps.detectAgents()) || [];
-      const next = pickDefaultAgent(agents) || null;
-      activeAgent = next;
-      _readinessCache = null; // force a fresh readiness probe next time
-      activityBus.publish({ type: 'agent-changed', agentId: next?.id || null });
-      return {
-        active: next?.id || null,
-        available: Boolean(next?.available),
-        agents: agents.map((a) => ({ id: a.id, available: a.available })),
-      };
-    },
-    'reinstall-daemon': async () => {
-      const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-      const child = operatorDeps.spawn(cmd, ['i', '-g', '@venturewild/workspace'], { windowsHide: true });
-      appendLine('operator', `reinstall-daemon spawned pid=${child?.pid}`);
-      child?.stdout?.on?.('data', (d) => appendLine('operator', `[npm] ${String(d).trim()}`));
-      child?.stderr?.on?.('data', (d) => appendLine('operator', `[npm:err] ${String(d).trim()}`));
-      child?.on?.('exit', (code) => appendLine('operator', `reinstall-daemon exited code=${code}`));
-      return { started: true, pid: child?.pid || null, command: `${cmd} i -g @venturewild/workspace` };
-    },
-  };
-
-  app.get('/api/operator/diag', async (c) => {
-    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
-    const forbidden = require(c, 'operate');
-    if (forbidden) return forbidden;
-    const report = await operatorDeps.runDoctor({ config });
-    auditOperator(c, 'diag', `fail=${report.summary?.fail} warn=${report.summary?.warn}`);
-    return c.json(report);
-  });
-
-  app.get('/api/operator/logs', (c) => {
-    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
-    const forbidden = require(c, 'operate');
-    if (forbidden) return forbidden;
-    const name = c.req.query('name') || 'cli';
-    if (!TAILABLE.includes(name)) return c.json({ error: 'unknown-log', name, allowed: TAILABLE }, 400);
-    const tail = Math.min(Number(c.req.query('tail')) || 200, 2000);
-    const file = logFile(name);
-    auditOperator(c, 'logs', `name=${name} tail=${tail}`);
-    return c.json({ name, file, tail, body: tailFile(file, tail) });
-  });
-
-  app.post('/api/operator/action', async (c) => {
-    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
-    const forbidden = require(c, 'operate');
-    if (forbidden) return forbidden;
-    const body = await c.req.json().catch(() => ({}));
-    const action = String(body.action || '');
-    if (!OPERATOR_ACTIONS[action]) {
-      return c.json({ error: 'unknown-action', action, allowed: Object.keys(OPERATOR_ACTIONS) }, 400);
-    }
-    auditOperator(c, 'action', `action=${action}`);
-    try {
-      const result = await OPERATOR_ACTIONS[action]();
-      return c.json({ ok: true, action, result });
-    } catch (e) {
-      appendLine('operator', `action=${action} FAILED ${e?.stack || e}`);
-      return c.json({ ok: false, action, error: String(e?.message || e) }, 500);
-    }
-  });
-
-  // --- 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,
-    sessionReporter,
-    detectedAgents,
-    getActiveAgent: () => activeAgent,
-    async stop() {
-      try { clearTimeout(autoWakeTimer); } catch {}
-      try { currentTurn?.session.close(); } catch {}
-      try { sessionReporter.stop(); } catch {}
-      try { transcriptRecorder.stop(); } 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);
-  });
-}
+// 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 { probeAgentReadiness } from './agent-readiness.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 { loadAccount } from './account.mjs';
+import { runDoctor } from './doctor.mjs';
+import { appendLine, tailFile, logFile, TAILABLE, globalDir } from './logpaths.mjs';
+import { SessionReporter } from './session-reporter.mjs';
+import { TranscriptRecorder } from './transcript.mjs';
+import { loadObservabilityConsent, setObservabilityConsent } from './observability.mjs';
+import { spawn } from 'node:child_process';
+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',
+        });
+
+  // Proactive, consented session + install observability (session-reporter.mjs).
+  // Default-on with a clear disclosure at onboarding; off via the consent toggle
+  // or the WILD_WORKSPACE_NO_TELEMETRY kill switch. Inert in tests and without an
+  // account token. Carries WHAT happened + install health, never the words —
+  // conversation content is the separate transcript channel.
+  let observability = loadObservabilityConsent(config.dataDir);
+  const sessionEnabled = () =>
+    observability.enabled &&
+    process.env.WILD_WORKSPACE_NO_TELEMETRY !== '1' &&
+    !process.env.VITEST &&
+    config.nodeEnv !== 'test';
+  const sessionReporter =
+    overrides.sessionReporter === false
+      ? { ingest() {}, flush() {}, start() {}, stop() {}, setEnabled() {} }
+      : overrides.sessionReporter ||
+        new SessionReporter({
+          bmoSyncUrl: config.bmoSyncServerUrl,
+          accountToken: config.accountToken,
+          slug: config.account?.slug || null,
+          workspaceId: config.workspaceId,
+          sessionId: overrides.sessionId || nanoid(12),
+          enabled: sessionEnabled(),
+        });
+  // Conversation *content* channel (transcript.mjs) — separate from the feed.
+  // Appends markdown to ~/.wild-workspace/transcripts/<workspaceId>/ (OUTSIDE the
+  // synced repo); forwarding to us is consent-gated. Noop under the test runner so
+  // it never writes into a real home dir.
+  const transcriptForward = ({ markdown, date }) => {
+    if (!sessionEnabled() || !config.accountToken) return;
+    const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 5000);
+    Promise.resolve()
+      .then(() =>
+        fetch(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            account_token: config.accountToken,
+            slug: config.account?.slug || null,
+            workspace_id: config.workspaceId,
+            kind: 'transcript',
+            date,
+            markdown,
+            sent_at: Math.floor(Date.now() / 1000),
+          }),
+          signal: ctrl.signal,
+        }),
+      )
+      .catch(() => {})
+      .finally(() => clearTimeout(t));
+  };
+  const transcriptRecorder =
+    overrides.transcriptRecorder === false || process.env.VITEST || config.nodeEnv === 'test'
+      ? { ingest() {}, flush() {}, stop() {} }
+      : new TranscriptRecorder({
+          dir: path.join(globalDir(), 'transcripts', config.workspaceId),
+          agentName: loadIdentity(config.dataDir)?.name || activeAgent?.label || 'Agent',
+          forwardImpl: transcriptForward,
+        });
+
+  activityBus.on('event', (e) => {
+    try { sessionReporter.ingest(e); } catch { /* never let telemetry break the bus */ }
+    try { transcriptRecorder.ingest(e); } catch { /* nor the transcript */ }
+  });
+  sessionReporter.start();
+
+  // --- 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' };
+      }
+      // The operator (support) token — header-only, and only when the channel is
+      // explicitly enabled (a token exists). Never accepted via `?t=` (below),
+      // so it can't leak through URLs/logs/referrer (SECURITY.md S1).
+      if (config.operatorToken && token === config.operatorToken) {
+        return { role: ROLES.OPERATOR, sub: 'operator', source: 'operator-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,
+      // Consent state for the proactive observability feed, so settings/onboarding
+      // can show + toggle it. The disclosure copy lives in the UI.
+      observability: { enabled: observability.enabled, version: observability.version },
+    });
+  });
+
+  // --- 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 });
+  });
+
+  // --- agent readiness (the agent-login gate) ---
+  // "Is the wrapped agent installed AND signed in?" detectAgents() only proves
+  // the binary is on PATH; this proves a turn will actually work. Onboarding
+  // calls this before its folder-peek wow beat so a not-signed-in user gets a
+  // calm "sign in to Claude" step instead of a broken error bubble (the §3.2
+  // open question in docs/user-experience.md). See agent-readiness.mjs.
+  //
+  // Cached briefly: a 'ready' verdict rarely flips, and the probe spawns a
+  // subprocess. `?fresh=1` forces a re-probe (the gate's "I've signed in" button
+  // sends it so the user isn't stuck behind a stale 'login' verdict).
+  let _readinessCache = null; // { at, verdict }
+  const READINESS_TTL_MS = 30_000;
+  const agentTag = (a) => (a ? { id: a.id, label: a.label } : null);
+  app.get('/api/agent/readiness', async (c) => {
+    const forbidden = require(c, 'chat');
+    if (forbidden) return forbidden;
+    const fresh = c.req.query('fresh') === '1';
+    const now = Date.now();
+    if (!fresh && _readinessCache && now - _readinessCache.at < READINESS_TTL_MS) {
+      return c.json({ agent: agentTag(activeAgent), ...(_readinessCache.verdict) });
+    }
+    const verdict = await probeAgentReadiness(activeAgent);
+    _readinessCache = { at: now, verdict };
+    log('[onboarding]', `readiness agent=${activeAgent?.id || '-'} status=${verdict.status}${verdict.email ? ` email=${verdict.email}` : ''}`);
+    return c.json({ agent: agentTag(activeAgent), ...verdict });
+  });
+
+  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);
+    }
+  });
+
+  // Consent toggle for the proactive observability feed (default-on — see
+  // observability.mjs). Owner-only; applied live to the reporter, no restart.
+  app.post('/api/observability/consent', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const enabled = body.enabled !== false;
+    observability = setObservabilityConsent(config.dataDir, enabled);
+    sessionReporter.setEnabled(sessionEnabled());
+    activityBus.publish({ type: 'observability-consent', enabled });
+    log('[observability]', `consent set enabled=${enabled}`);
+    return c.json({ observability: { enabled: observability.enabled, version: observability.version } });
+  });
+
+  // --- 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 });
+  });
+
+  // --- operator channel (consented support; OFF unless a token is set) -------
+  // The dedicated operator token (operator.mjs) maps to the `operator` role in
+  // resolveRole; every route here gates on the `operate` capability. When the
+  // channel is disabled (no token) the routes 404 so the surface is invisible.
+  // Each call is audit-logged to operator.log AND surfaced in the activity feed
+  // (CLAUDE.md principle #5 — both peers see what happened). The actions are a
+  // CURATED ALLOWLIST — never arbitrary shell (docs/SECURITY.md).
+  const operatorDeps = {
+    runDoctor: (o) => runDoctor(o),
+    detectAgents,
+    loadAccount,
+    spawn,
+    ...(overrides.operatorDeps || {}),
+  };
+  const operatorEnabled = () => Boolean(config.operatorToken);
+  function auditOperator(c, action, detail) {
+    const s = c.get('session') || {};
+    appendLine('operator', `${action} by=${s.sub || 'operator'} src=${s.source || '-'} ${detail || ''}`.trim());
+    activityBus.publish({ type: 'operator-action', action, detail: detail || null, at: Date.now() });
+  }
+
+  // Curated remediation actions. Each reuses an existing seam; none runs an
+  // arbitrary command. (`restart-server` is intentionally absent — exiting the
+  // process would sever the very tunnel we reach the user through on a machine
+  // without the always-on supervisor; deferred — see SECURITY.md.)
+  const OPERATOR_ACTIONS = {
+    'run-doctor': async () => operatorDeps.runDoctor({ config }),
+    'restart-daemon': async () => {
+      if (!daemonSupervisor) return { restarted: false, reason: 'daemon-supervisor-disabled' };
+      await daemonSupervisor.stop().catch(() => {});
+      return daemonSupervisor.ensureRunning();
+    },
+    'relink-account': async () => {
+      const account = operatorDeps.loadAccount(config.dataDir);
+      if (daemonSupervisor) {
+        await daemonSupervisor.stop().catch(() => {});
+        await daemonSupervisor.ensureRunning().catch(() => {});
+      }
+      return { relinked: Boolean(account?.slug), slug: account?.slug || null, email: account?.email || null };
+    },
+    'redetect-agent': async () => {
+      const agents = (await operatorDeps.detectAgents()) || [];
+      const next = pickDefaultAgent(agents) || null;
+      activeAgent = next;
+      _readinessCache = null; // force a fresh readiness probe next time
+      activityBus.publish({ type: 'agent-changed', agentId: next?.id || null });
+      return {
+        active: next?.id || null,
+        available: Boolean(next?.available),
+        agents: agents.map((a) => ({ id: a.id, available: a.available })),
+      };
+    },
+    'reinstall-daemon': async () => {
+      const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+      const child = operatorDeps.spawn(cmd, ['i', '-g', '@venturewild/workspace'], { windowsHide: true });
+      appendLine('operator', `reinstall-daemon spawned pid=${child?.pid}`);
+      child?.stdout?.on?.('data', (d) => appendLine('operator', `[npm] ${String(d).trim()}`));
+      child?.stderr?.on?.('data', (d) => appendLine('operator', `[npm:err] ${String(d).trim()}`));
+      child?.on?.('exit', (code) => appendLine('operator', `reinstall-daemon exited code=${code}`));
+      return { started: true, pid: child?.pid || null, command: `${cmd} i -g @venturewild/workspace` };
+    },
+  };
+
+  app.get('/api/operator/diag', async (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const report = await operatorDeps.runDoctor({ config });
+    auditOperator(c, 'diag', `fail=${report.summary?.fail} warn=${report.summary?.warn}`);
+    return c.json(report);
+  });
+
+  app.get('/api/operator/logs', (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const name = c.req.query('name') || 'cli';
+    if (!TAILABLE.includes(name)) return c.json({ error: 'unknown-log', name, allowed: TAILABLE }, 400);
+    const tail = Math.min(Number(c.req.query('tail')) || 200, 2000);
+    const file = logFile(name);
+    auditOperator(c, 'logs', `name=${name} tail=${tail}`);
+    return c.json({ name, file, tail, body: tailFile(file, tail) });
+  });
+
+  app.post('/api/operator/action', async (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const action = String(body.action || '');
+    if (!OPERATOR_ACTIONS[action]) {
+      return c.json({ error: 'unknown-action', action, allowed: Object.keys(OPERATOR_ACTIONS) }, 400);
+    }
+    auditOperator(c, 'action', `action=${action}`);
+    try {
+      const result = await OPERATOR_ACTIONS[action]();
+      return c.json({ ok: true, action, result });
+    } catch (e) {
+      appendLine('operator', `action=${action} FAILED ${e?.stack || e}`);
+      return c.json({ ok: false, action, error: String(e?.message || e) }, 500);
+    }
+  });
+
+  // --- 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,
+    sessionReporter,
+    detectedAgents,
+    getActiveAgent: () => activeAgent,
+    async stop() {
+      try { clearTimeout(autoWakeTimer); } catch {}
+      try { currentTurn?.session.close(); } catch {}
+      try { sessionReporter.stop(); } catch {}
+      try { transcriptRecorder.stop(); } 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);
+  });
+}