@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/src/api.ts

@@ -0,0 +1,1716 @@
+// api.ts — local HTTP API the host-side client (@cordfuse/crosstalk)
+// connects to. Binds 127.0.0.1 only; never exposes to the network.
+//
+// Design choices (see conversation 2026-06-12):
+//   - No auth. Localhost dev tool, same model as ollama / postgres-on-
+//     localhost / jupyter-without-token. If you're on the host, you're
+//     trusted. The actual security boundary is the bind address.
+//   - Bind hardcoded to 127.0.0.1. Operators can't accidentally expose
+//     to the network even by misconfiguring docker-compose port mapping.
+//   - Plain Node `http` module, no Express/Fastify dep. v7 ships with
+//     two runtime deps (tsx + yaml); HTTP framework would break that.
+//   - JSON in, JSON out. Error responses carry { error: <message> }.
+//
+// Endpoint surface (v7.0.0-alpha.1):
+//   GET  /healthz                       — liveness probe (no body needed)
+//   GET  /version                       — engine version + alias
+//   GET  /status                        — status summary
+//   GET  /channels                      — channel listing (name → uuid)
+//   POST /channels                      — create a channel
+//   POST /messages                      — write primitive or workflow marker
+//   GET  /messages/:relPath/replies     — reply status for given relPath(s)
+//
+// Deferred to follow-up: SSE streaming endpoint for `replies --watch`,
+// /transport/template (export template tarball for `crosstalk transport init`),
+// /shutdown (graceful engine stop).
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'http';
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { hostname, homedir } from 'os';
+import { join } from 'path';
+import { now, messageFilename } from './filenames.js';
+import { parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
+import {
+  discoverChannels,
+  gitCommitAndPush,
+  listChannelMessages,
+} from './transport.js';
+import { sendWakeSignal, readHeartbeat, readCursor, countErrors } from './state.js';
+import { reList } from './activation.js';
+import { isOnPath, type ModelEntry, type ModelsRegistry } from './models.js';
+import { resolveToField } from './resolve.js';
+import { dashboardPage } from './web/dashboard.js';
+import { channelListPage, channelViewPage, agentsPage, type BusMessage } from './web/channels.js';
+import { workflowsListPage, workflowDetailPage, type WorkflowSummary } from './web/workflows.js';
+import { setupPage as authSetupPage, loginPage as authLoginPage } from './web/auth-pages.js';
+import { chatPage } from './web/chat-page.js';
+import { mountChatPty } from './web/chat-pty.js';
+import { accountPage, usersPage, tokensPage, logsPage, settingsPage, aboutPage } from './web/stubs.js';
+import { logBuffer, type LogEntry } from './log-buffer.js';
+import { findOpenWorkflows, validatePlan, COMPILE_PROMPT, extractPlanFromOutput, type WorkflowPlan } from './workflow.js';
+import { invokeModelCli } from './invoke.js';
+import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
+import { FileUserStore, type UserStore } from './auth/users.js';
+import { FileTokenStore, type TokenStore } from './auth/tokens.js';
+import { SetupState, handleSetupSubmit, setupGate } from './auth/setup.js';
+import {
+  authenticateRequest, sessionCookieFor, clearSessionCookie,
+  type AuthSuccess,
+} from './auth/middleware.js';
+import { handleLogin, handleLogout } from './auth/handlers.js';
+
+export interface ApiContext {
+  transportRoot: string;
+  alias: string;
+  version: string;
+  registry: ModelsRegistry;
+  claimed: Map<string, ModelEntry>;  // shorthand for registry.claimed
+  /** Auth stores; v8-native. Optional — engine still runs without auth
+   *  if the operator doesn't want it (just the web UI gating turns off). */
+  userStore?: UserStore;
+  tokenStore?: TokenStore;
+  setupState?: SetupState;
+}
+
+interface JsonRes {
+  status: number;
+  body: unknown;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolveBody, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(Buffer.from(c)));
+    req.on('end', () => resolveBody(Buffer.concat(chunks).toString('utf-8')));
+    req.on('error', reject);
+  });
+}
+
+async function readJson<T = unknown>(req: IncomingMessage): Promise<T> {
+  const raw = await readBody(req);
+  if (raw.length === 0) return {} as T;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    throw new HttpError(400, 'invalid JSON body');
+  }
+}
+
+class HttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown, engineVersion?: string): void {
+  const json = JSON.stringify(body);
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(json).toString(),
+  };
+  // Advertise our version on every response so the client can detect
+  // version skew passively — no extra round-trip needed. Client writes
+  // a one-shot warning when its own version doesn't match.
+  if (engineVersion) headers['X-Crosstalk-Engine-Version'] = engineVersion;
+  res.writeHead(status, headers);
+  res.end(json);
+}
+
+function writeHtml(res: ServerResponse, status: number, html: string, engineVersion?: string): void {
+  const headers: Record<string, string> = {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Content-Length': Buffer.byteLength(html, 'utf-8').toString(),
+    // HTML pages always reflect server-side state (channels, workflows,
+    // tokens, etc.) — never serve a stale cached copy. Defeats both
+    // intermediary proxy caches and Chrome's bfcache restoring a list
+    // page that still shows a just-deleted entity.
+    'Cache-Control': 'no-store, no-cache, must-revalidate',
+    'Pragma': 'no-cache',
+  };
+  if (engineVersion) headers['X-Crosstalk-Engine-Version'] = engineVersion;
+  res.writeHead(status, headers);
+  res.end(html);
+}
+
+function writeRedirect(res: ServerResponse, to: string): void {
+  res.writeHead(302, { 'Location': to });
+  res.end();
+}
+
+// ── channel discovery helpers ────────────────────────────────────────
+
+interface ChannelMeta {
+  uuid: string;
+  name: string | null;
+  parent: string | null;
+}
+
+function readChannelMeta(transportRoot: string, uuid: string): ChannelMeta {
+  const chPath = join(transportRoot, 'data', 'channels', uuid, 'CHANNEL.md');
+  if (!existsSync(chPath)) return { uuid, name: null, parent: null };
+  const raw = readFileSync(chPath, 'utf-8');
+  const { data } = parseFrontmatter<{ name?: unknown; parent?: unknown }>(raw);
+  return {
+    uuid,
+    name: typeof data.name === 'string' ? data.name : null,
+    parent: typeof data.parent === 'string' ? data.parent : null,
+  };
+}
+
+function allChannelMeta(transportRoot: string): ChannelMeta[] {
+  return discoverChannels(transportRoot).map((u) => readChannelMeta(transportRoot, u));
+}
+
+function resolveChannelHandle(transportRoot: string, handle: string): ChannelMeta | null {
+  if (UUID_RE.test(handle)) {
+    const path = join(transportRoot, 'data', 'channels', handle);
+    if (!existsSync(path)) return null;
+    return readChannelMeta(transportRoot, handle);
+  }
+  // Prefer CHANNEL.md name match.
+  for (const meta of allChannelMeta(transportRoot)) {
+    if (meta.name === handle) return meta;
+  }
+  // Fallback: bare directory name. Handles legacy / orphan channels
+  // whose dir name is not a UUID AND whose CHANNEL.md has no name —
+  // they'd be otherwise unreachable via the API. Caught 2026-06-22
+  // when an old "mctest" dir couldn't be deleted from the web UI.
+  const directPath = join(transportRoot, 'data', 'channels', handle);
+  if (existsSync(directPath)) return readChannelMeta(transportRoot, handle);
+  return null;
+}
+
+// ── route handlers ───────────────────────────────────────────────────
+
+function handleHealthz(ctx: ApiContext): JsonRes {
+  return { status: 200, body: { ok: true, alias: ctx.alias, version: ctx.version } };
+}
+
+function handleVersion(ctx: ApiContext): JsonRes {
+  return {
+    status: 200,
+    body: { engine: 'crosstalk', version: ctx.version, alias: ctx.alias },
+  };
+}
+
+function handleStatus(ctx: ApiContext): JsonRes {
+  const { transportRoot } = ctx;
+  const hb = readHeartbeat(transportRoot);
+  const cursor = readCursor(transportRoot);
+  const channels = allChannelMeta(transportRoot);
+  return {
+    status: 200,
+    body: {
+      transport_root: transportRoot,
+      alias: ctx.alias,
+      version: ctx.version,
+      claimed_models: [...ctx.claimed.keys()],
+      heartbeat: hb
+        ? { ts: hb.ts, pid: hb.pid, version: hb.version, alias: hb.alias }
+        : null,
+      cursor: cursor ?? null,
+      channels: channels.map((c) => ({ uuid: c.uuid, name: c.name, parent: c.parent })),
+      errors_logged: countErrors(transportRoot),
+    },
+  };
+}
+
+function handleListChannels(ctx: ApiContext): JsonRes {
+  return {
+    status: 200,
+    body: { channels: allChannelMeta(ctx.transportRoot) },
+  };
+}
+
+// Canonical agent CLI binaries crosstalk supports. The set the host
+// client's `chat` command knows how to PTY-wrap. The engine checks PATH
+// inside the container for each — what's actually installed.
+//
+// This is distinct from `claimed_models` on /status: that lists
+// data/crosstalk.yaml entries whose CLI is on PATH (e.g. "sonnet", "haiku"
+// — model names). /agents/installed lists raw CLI binaries (e.g.
+// "claude" — the interactive entry point operators talk to).
+const KNOWN_AGENT_BINARIES = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
+
+function handleAgentsInstalled(ctx: ApiContext): JsonRes {
+  const installed = KNOWN_AGENT_BINARIES.filter((bin) => isOnPath(bin));
+  // The set of CLI binaries referenced by entries in data/crosstalk.yaml
+  // (whether their CLI is currently claimed or not). Lets the client
+  // differentiate "yaml has them but they're not claimed → restart" from
+  // "yaml has no entry referencing them → add one". M2 fix (alpha.10):
+  // alpha.9 status hint conflated those two cases.
+  const yamlReferenced = [...new Set(
+    [...ctx.registry.all.values()].map((entry) => entry.cli),
+  )];
+  // The set of CLI binaries with at least one currently-claimed model.
+  // Distinct from yaml_referenced: yaml may reference `claude` but the
+  // dispatcher may not yet have claimed it (CLI installed post-startup,
+  // PATH change, etc.). N1 (alpha.11): lets the client surface the
+  // "needs restart" hint in mixed states where some models ARE claimed.
+  const claimedClis = [...new Set(
+    [...ctx.claimed.values()].map((entry) => entry.cli),
+  )];
+  return {
+    status: 200,
+    body: {
+      installed,
+      known: KNOWN_AGENT_BINARIES,
+      yaml_referenced: yamlReferenced,
+      claimed: claimedClis,
+    },
+  };
+}
+
+interface CreateChannelReq { name: string }
+
+function handleCreateChannel(ctx: ApiContext, body: CreateChannelReq): JsonRes {
+  const { transportRoot } = ctx;
+  if (typeof body.name !== 'string' || body.name.length === 0) {
+    throw new HttpError(400, 'channel name is required');
+  }
+  if (UUID_RE.test(body.name)) {
+    throw new HttpError(400, 'channel name cannot be UUID-shaped');
+  }
+  if (allChannelMeta(transportRoot).some((c) => c.name === body.name)) {
+    throw new HttpError(409, `a channel named '${body.name}' already exists`);
+  }
+  const uuid = randomUUID();
+  const dir = join(transportRoot, 'data', 'channels', uuid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'CHANNEL.md'), serializeFrontmatter({ name: body.name }, ''));
+  const push = gitCommitAndPush(transportRoot, `channel(create): ${body.name} (${uuid.slice(0, 8)})`);
+  if (!push.committed && push.error) {
+    // Commit itself failed (e.g. file system / git config issue).
+    throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
+  }
+  // push.committed=true but push.pushed=false → local commit landed,
+  // remote push failed (missing ssh key, no internet, conflicting
+  // origin). Don't fail the operation — operators on single-machine
+  // setups should be able to use crosstalk locally without git
+  // credentials. The engine log records the push error for visibility.
+  return { status: 201, body: { uuid, name: body.name } };
+}
+
+interface RenameChannelReq { name: string }
+
+function handleRenameChannel(ctx: ApiContext, handle: string, body: RenameChannelReq): JsonRes {
+  const { transportRoot } = ctx;
+  if (typeof body.name !== 'string' || body.name.length === 0) {
+    throw new HttpError(400, 'new name is required');
+  }
+  if (UUID_RE.test(body.name)) {
+    throw new HttpError(400, 'channel name cannot be UUID-shaped');
+  }
+  const meta = resolveChannelHandle(transportRoot, handle);
+  if (!meta) throw new HttpError(404, `channel '${handle}' not found`);
+  if (meta.name === body.name) {
+    return { status: 200, body: { uuid: meta.uuid, name: meta.name, noop: true } };
+  }
+  if (allChannelMeta(transportRoot).some((c) => c.name === body.name)) {
+    throw new HttpError(409, `a channel named '${body.name}' already exists`);
+  }
+  const chPath = join(transportRoot, 'data', 'channels', meta.uuid, 'CHANNEL.md');
+  const fm: Record<string, unknown> = { name: body.name };
+  if (meta.parent) fm['parent'] = meta.parent;
+  writeFileSync(chPath, serializeFrontmatter(fm, ''));
+  const push = gitCommitAndPush(
+    transportRoot,
+    `channel(rename): ${meta.name ?? '(unnamed)'} -> ${body.name} (${meta.uuid.slice(0, 8)})`,
+  );
+  if (!push.committed && push.error) {
+    // Commit itself failed (e.g. file system / git config issue).
+    throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
+  }
+  // push.committed=true but push.pushed=false → local commit landed,
+  // remote push failed (missing ssh key, no internet, conflicting
+  // origin). Don't fail the operation — operators on single-machine
+  // setups should be able to use crosstalk locally without git
+  // credentials. The engine log records the push error for visibility.
+  return { status: 200, body: { uuid: meta.uuid, name: body.name } };
+}
+
+function handleDeleteChannel(ctx: ApiContext, handle: string, confirm: string | null): JsonRes {
+  const { transportRoot } = ctx;
+  const meta = resolveChannelHandle(transportRoot, handle);
+  if (!meta) throw new HttpError(404, `channel '${handle}' not found`);
+  // The confirmation string must match the channel's name (or UUID if
+  // unnamed). Prevents accidental deletes — operator + client both
+  // typed the same name out, gives a moment for second thoughts.
+  const expected = meta.name ?? meta.uuid;
+  if (confirm !== expected) {
+    throw new HttpError(
+      400,
+      `confirmation mismatch — pass ?confirm=${expected} to delete this channel`,
+    );
+  }
+  const dir = join(transportRoot, 'data', 'channels', meta.uuid);
+  rmSync(dir, { recursive: true, force: true });
+  const push = gitCommitAndPush(
+    transportRoot,
+    `channel(delete): ${meta.name ?? '(unnamed)'} (${meta.uuid.slice(0, 8)})`,
+  );
+  if (!push.committed && push.error) {
+    // Commit itself failed (e.g. file system / git config issue).
+    throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
+  }
+  // push.committed=true but push.pushed=false → local commit landed,
+  // remote push failed (missing ssh key, no internet, conflicting
+  // origin). Don't fail the operation — operators on single-machine
+  // setups should be able to use crosstalk locally without git
+  // credentials. The engine log records the push error for visibility.
+  return { status: 200, body: { uuid: meta.uuid, name: meta.name, deleted: true } };
+}
+
+interface PostMessageReq {
+  type: 'primitive' | 'workflow';
+  channel?: string;        // name or UUID; defaults to single channel if exactly one exists
+  from?: string;
+  to?: string;             // required for primitive
+  as?: string;             // optional persona for primitive
+  fanout?: number;         // optional, default 1
+  body: string;
+  re?: string[];           // optional explicit re: targets
+}
+
+function resolveChannelUuid(transportRoot: string, handle?: string): string {
+  if (handle) {
+    const meta = resolveChannelHandle(transportRoot, handle);
+    if (!meta) throw new HttpError(404, `channel '${handle}' not found`);
+    return meta.uuid;
+  }
+  const all = discoverChannels(transportRoot);
+  if (all.length === 1) return all[0]!;
+  if (all.length === 0) {
+    throw new HttpError(409, "no channels exist — create one via POST /channels first");
+  }
+  throw new HttpError(409, 'multiple channels exist — specify "channel" in request body');
+}
+
+function writeMessageFile(opts: {
+  transportRoot: string;
+  channelUuid: string;
+  from: string;
+  to: string;
+  as?: string;
+  body: string;
+  re: string[];
+  extraFrontmatter?: Record<string, unknown>;
+  workflow?: boolean;
+}): string {
+  const ts = now();
+  const dir = join(opts.transportRoot, 'data', 'channels', opts.channelUuid, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+  const fm: Record<string, unknown> = {
+    from: opts.from,
+    to: opts.to,
+    timestamp: ts.iso,
+  };
+  if (opts.as) fm['as'] = opts.as;
+  if (opts.workflow) fm['type'] = 'workflow';
+  if (opts.re.length === 1) fm['re'] = opts.re[0];
+  else if (opts.re.length > 1) fm['re'] = opts.re;
+  if (opts.extraFrontmatter) Object.assign(fm, opts.extraFrontmatter);
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(fm, opts.body));
+  return join(ts.pathDate, filename);
+}
+
+function handlePostMessage(ctx: ApiContext, body: PostMessageReq): JsonRes {
+  const { transportRoot } = ctx;
+  if (typeof body.body !== 'string') {
+    throw new HttpError(400, 'message body (`body` field) is required and must be a string');
+  }
+  const re = Array.isArray(body.re) ? body.re.filter((s) => typeof s === 'string') : [];
+  const from = typeof body.from === 'string' && body.from.length > 0 ? body.from : 'operator';
+
+  if (body.type === 'primitive') {
+    if (typeof body.to !== 'string' || body.to.length === 0) {
+      throw new HttpError(400, 'primitive requires `to` (model name)');
+    }
+    // Normalize `to:` to qualified `<provider>/<model>[@host]` via the
+    // addressing layer. Bare names auto-disambig against the claimed
+    // registry; unknown/ambiguous fails fast with a pick-list 400.
+    const resolved = resolveToField(body.to, ctx.registry);
+    if (resolved.kind !== 'ok' && resolved.kind !== 'reserved') {
+      throw new HttpError(400, resolved.error!);
+    }
+    const toQualified = resolved.qualified!;
+    const channelUuid = resolveChannelUuid(transportRoot, body.channel);
+    const fanout = Math.max(1, Math.min(50, body.fanout ?? 1));
+    const relPaths: string[] = [];
+    for (let i = 0; i < fanout; i++) {
+      relPaths.push(
+        writeMessageFile({
+          transportRoot,
+          channelUuid,
+          from,
+          to: toQualified,
+          as: body.as,
+          body: body.body,
+          re,
+        }),
+      );
+    }
+    const commitMsg =
+      fanout === 1
+        ? `run: ${from} -> ${toQualified} in ${channelUuid.slice(0, 8)}`
+        : `run: ${from} -> ${toQualified} x${fanout} in ${channelUuid.slice(0, 8)}`;
+    const push = gitCommitAndPush(transportRoot, commitMsg);
+    sendWakeSignal(transportRoot);
+    if (!push.committed && push.error) {
+      throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
+    }
+    // push.committed=true with push.pushed=false → local-only, OK.
+    return { status: 201, body: { relPaths, channel: channelUuid, type: 'primitive' } };
+  }
+
+  if (body.type === 'workflow') {
+    const parsed = parseFrontmatter<Record<string, unknown>>(body.body);
+    if (parsed.data['type'] !== 'workflow') {
+      throw new HttpError(400, "workflow body must declare 'type: workflow' in frontmatter");
+    }
+    const parentUuid = resolveChannelUuid(transportRoot, body.channel);
+    const childUuid = randomUUID();
+    const childDir = join(transportRoot, 'data', 'channels', childUuid);
+    mkdirSync(childDir, { recursive: true });
+    writeFileSync(
+      join(childDir, 'CHANNEL.md'),
+      serializeFrontmatter({ name: `workflow-${Date.now()}`, parent: parentUuid }, ''),
+    );
+    const heartbeat = readHeartbeat(transportRoot);
+    const dispatchHost = heartbeat?.alias;
+    const extraFrontmatter: Record<string, unknown> = { child_channel: childUuid };
+    if (dispatchHost) extraFrontmatter['dispatch_host'] = dispatchHost;
+    const relPath = writeMessageFile({
+      transportRoot,
+      channelUuid: parentUuid,
+      from,
+      to: 'workflow',
+      body: parsed.body,
+      re,
+      extraFrontmatter,
+      workflow: true,
+    });
+    const push = gitCommitAndPush(
+      transportRoot,
+      `run(workflow): ${from} child ${childUuid.slice(0, 8)}`,
+    );
+    sendWakeSignal(transportRoot);
+    if (!push.committed && push.error) {
+      throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
+    }
+    // push.committed=true with push.pushed=false → local-only, OK.
+    return {
+      status: 201,
+      body: { relPath, channel: parentUuid, childChannel: childUuid, type: 'workflow' },
+    };
+  }
+
+  throw new HttpError(400, "`type` must be 'primitive' or 'workflow'");
+}
+
+function handleReplies(ctx: ApiContext, relPathQuery: string): JsonRes {
+  const targets = relPathQuery.split(',').map((s) => s.trim()).filter(Boolean);
+  if (targets.length === 0) {
+    throw new HttpError(400, 'at least one relPath query argument required');
+  }
+  const found = new Map<string, { from: string; relPath: string; failed: boolean }>();
+  for (const channel of discoverChannels(ctx.transportRoot)) {
+    for (const msg of listChannelMessages(ctx.transportRoot, channel)) {
+      for (const entry of reList(msg.data['re'])) {
+        if (targets.includes(entry) && !found.has(entry)) {
+          found.set(entry, {
+            from: String(msg.data['from']),
+            relPath: msg.relPath,
+            failed: msg.data['failed'] === true,
+          });
+        }
+      }
+    }
+  }
+  const results = targets.map((t) => {
+    const reply = found.get(t);
+    if (!reply) return { target: t, status: 'PENDING' };
+    return {
+      target: t,
+      status: reply.failed ? 'FAILED' : 'REPLIED',
+      from: reply.from,
+      replyRelPath: reply.relPath,
+    };
+  });
+  return { status: 200, body: { replies: results } };
+}
+
+// ── HTML page rendering ──────────────────────────────────────────────
+//
+// The web UI lives at separate paths from the JSON API to avoid Accept-
+// header ambiguity and to keep the JSON surface untouched. Paths:
+//   GET  /                         → dashboard
+//   GET  /c                        → channel list
+//   GET  /c/<handle>               → threaded message view (handle =
+//                                    channel name or uuid)
+//   GET  /c/<handle>/messages.json → poll endpoint for the threaded view
+//   GET  /agents                   → installed/yaml-referenced/claimed agents
+//
+// All HTML routes are synchronous reads of the transport state — no
+// auth (engine binds 127.0.0.1; tailscale-serve front handles tailnet
+// exposure if the operator wants it).
+
+function hostString(): string {
+  try { return hostname() || 'localhost'; } catch { return 'localhost'; }
+}
+
+/**
+ * v8 auth gate. Web pages (HTML routes) AND auth-API routes (POST
+ * /api/setup, POST /api/auth/login, POST /api/auth/logout) are gated by
+ * the user/token stores. JSON API routes (everything else under /api/*)
+ * stay open on 127.0.0.1 — the engine binds loopback only, so the
+ * security boundary is the bind address, not app-level auth. This
+ * matches the v7 model + only adds gating for browser/web access.
+ *
+ * Returns: 'allow' = caller may proceed; 'handled' = setup/login flow
+ * was served (HTML or JSON); 'redirect' = unauthed; caller wrote 302.
+ */
+async function tryWebAuthFlow(ctx: ApiContext, req: IncomingMessage, res: ServerResponse): Promise<'handled' | 'allow' | 'redirect'> {
+  if (!ctx.userStore || !ctx.tokenStore || !ctx.setupState) return 'allow';
+  const { method = 'GET', url = '/' } = req;
+  const u = new URL(url, 'http://localhost');
+  const path = u.pathname;
+
+  // POST /api/setup — open during first-run only.
+  if (method === 'POST' && path === '/api/setup') {
+    const body = JSON.parse(await readBody(req) || '{}') as { setupToken?: string; name?: string; username?: string; passphrase?: string };
+    const r = await handleSetupSubmit({
+      setupToken: body.setupToken ?? '',
+      name: body.name ?? '',
+      username: body.username ?? '',
+      passphrase: body.passphrase ?? '',
+    }, ctx.userStore, ctx.tokenStore, ctx.setupState);
+    if (r.ok && r.bootstrapToken) {
+      // Set the session cookie alongside the JSON body so the operator
+      // is auto-signed-in after setup completes.
+      const json = JSON.stringify(r);
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(json).toString(),
+        'X-Crosstalk-Engine-Version': ctx.version,
+        'Set-Cookie': sessionCookieFor(r.bootstrapToken.plaintextSecret),
+      });
+      res.end(json);
+    } else {
+      writeJson(res, r.ok ? 200 : 400, r, ctx.version);
+    }
+    return 'handled';
+  }
+
+  // POST /api/auth/login — open. Returns wire token + sets session cookie.
+  if (method === 'POST' && path === '/api/auth/login') {
+    const body = JSON.parse(await readBody(req) || '{}');
+    const r = await handleLogin(body, ctx.userStore, ctx.tokenStore);
+    if (r.status === 200 && 'token' in r.body) {
+      const json = JSON.stringify(r.body);
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(json).toString(),
+        'X-Crosstalk-Engine-Version': ctx.version,
+        'Set-Cookie': sessionCookieFor(r.body.token),
+      });
+      res.end(json);
+    } else {
+      writeJson(res, r.status, r.body, ctx.version);
+    }
+    return 'handled';
+  }
+
+  // POST /api/auth/logout — requires v2 cookie; clears session.
+  if (method === 'POST' && path === '/api/auth/logout') {
+    const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+    if (!auth.ok) { writeJson(res, auth.status, auth.body, ctx.version); return 'handled'; }
+    const r = await handleLogout(auth.token, ctx.tokenStore);
+    const json = JSON.stringify(r.body);
+    res.writeHead(r.status, {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(json).toString(),
+      'X-Crosstalk-Engine-Version': ctx.version,
+      'Set-Cookie': clearSessionCookie(),
+    });
+    res.end(json);
+    return 'handled';
+  }
+
+  // GET /setup — render the wizard. Only honored when no users exist;
+  // post-setup it 302s to /.
+  if (method === 'GET' && path === '/setup') {
+    if (!(await ctx.userStore.isEmpty())) { writeRedirect(res, '/'); return 'handled'; }
+    const token = u.searchParams.get('token') ?? '';
+    writeHtml(res, 200, authSetupPage({ setupToken: token, host: hostString(), alias: ctx.alias }), ctx.version);
+    return 'handled';
+  }
+
+  // GET /login — render the form. Already-authed users redirect to /.
+  if (method === 'GET' && path === '/login') {
+    const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+    if (auth.ok) { writeRedirect(res, '/'); return 'handled'; }
+    const returnTo = u.searchParams.get('returnTo') ?? '/';
+    writeHtml(res, 200, authLoginPage({ host: hostString(), alias: ctx.alias, returnTo }), ctx.version);
+    return 'handled';
+  }
+
+  // Setup gate first-run: when no users exist AND the request isn't a
+  // setup/api-setup path, redirect to /setup so the first browser visit
+  // bootstraps the admin account.
+  const HTML_GATED_PATHS = new Set([
+    '/', '/agents', '/chat',
+    '/tokens', '/logs', '/settings', '/account', '/users', '/about',
+  ]);
+  if (method === 'GET' && (HTML_GATED_PATHS.has(path) || path.startsWith('/c') || path.startsWith('/w'))) {
+    const gate = await setupGate(ctx.userStore, path);
+    if (!gate.allow) {
+      // Mint a setup token if none active; either way, include it in
+      // the redirect URL so the operator doesn't have to fish it out
+      // of the daemon log.
+      const token = ctx.setupState.currentToken
+        ?? ctx.setupState.mint().token;
+      writeRedirect(res, `/setup?token=${encodeURIComponent(token)}`);
+      return 'redirect';
+    }
+    // Users exist — require a valid v2 cookie/bearer for HTML routes.
+    const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+    if (!auth.ok) {
+      writeRedirect(res, `/login?returnTo=${encodeURIComponent(u.pathname + u.search)}`);
+      return 'redirect';
+    }
+  }
+
+  return 'allow';
+}
+
+/**
+ * Auth-aware JSON API routes for the web UI:
+ *   POST   /api/tokens                  — mint a token for current user
+ *   DELETE /api/tokens/:tokenId         — revoke a token (must own it)
+ *   PATCH  /api/tokens/:tokenId         — rename a token (must own it)
+ *   POST   /api/account/passphrase      — change own passphrase
+ *   POST   /api/users                   — admin: create user
+ *   DELETE /api/users/:username         — admin: delete user (not self)
+ *   PATCH  /api/users/:username         — admin: toggle admin (not self)
+ *
+ * All return JSON. Auth required on every endpoint; admin endpoints
+ * additionally check the caller's admin flag. Returns true if the
+ * request was handled (response written), false to fall through.
+ */
+async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (!ctx.userStore || !ctx.tokenStore) return false;
+  const { method = 'GET', url = '/' } = req;
+  const u = new URL(url, 'http://localhost');
+  const path = u.pathname;
+
+  const isApiPath =
+    path === '/api/tokens' || path.startsWith('/api/tokens/') ||
+    path === '/api/account' || path === '/api/account/passphrase' ||
+    path === '/api/users' || path.startsWith('/api/users/') ||
+    path === '/api/workflows' || path.startsWith('/api/workflows/') ||
+    path === '/api/logs' || path === '/api/logs/stream' ||
+    path === '/api/settings';
+  if (!isApiPath) return false;
+
+  const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+  if (!auth.ok) { writeJson(res, auth.status, auth.body, ctx.version); return true; }
+  const me = auth.user;
+
+  // ── Account read ─────────────────────────────────────────────────
+  // GET /api/account → who am I (used by `crosstalk auth whoami` + UI).
+  if (method === 'GET' && path === '/api/account') {
+    // Don't leak passphraseHash.
+    const { passphraseHash: _ph, ...safe } = me;
+    void _ph;
+    writeJson(res, 200, safe, ctx.version);
+    return true;
+  }
+
+  // ── Tokens ────────────────────────────────────────────────────────
+  // GET /api/tokens → list current user's tokens (CLI + UI).
+  if (method === 'GET' && path === '/api/tokens') {
+    const tokens = await ctx.tokenStore.list(me.username);
+    writeJson(res, 200, { tokens }, ctx.version);
+    return true;
+  }
+  if (method === 'POST' && path === '/api/tokens') {
+    const body = await readJson<{ name?: string }>(req);
+    if (typeof body.name !== 'string' || body.name.trim().length === 0) {
+      writeJson(res, 400, { error: 'token name required' }, ctx.version);
+      return true;
+    }
+    const r = await ctx.tokenStore.mint({ username: me.username, name: body.name.trim() });
+    writeJson(res, 201, { tokenId: r.token.tokenId, plaintextSecret: r.plaintextSecret, createdAt: r.token.createdAt }, ctx.version);
+    return true;
+  }
+  {
+    const m = path.match(/^\/api\/tokens\/([^/]+)$/);
+    if (m && method === 'DELETE') {
+      const tokenId = decodeURIComponent(m[1]!);
+      // Operators can only revoke tokens they own. Admin override
+      // isn't necessary here — admin can use the CLI / edit the json
+      // if they really need to nuke another user's token.
+      const tok = await ctx.tokenStore.get(tokenId);
+      if (!tok) { writeJson(res, 404, { error: 'token not found' }, ctx.version); return true; }
+      if (tok.username !== me.username) {
+        writeJson(res, 403, { error: 'cannot revoke a token you do not own' }, ctx.version);
+        return true;
+      }
+      await ctx.tokenStore.revoke(tokenId);
+      writeJson(res, 200, { ok: true }, ctx.version);
+      return true;
+    }
+    if (m && method === 'PATCH') {
+      const tokenId = decodeURIComponent(m[1]!);
+      const tok = await ctx.tokenStore.get(tokenId);
+      if (!tok) { writeJson(res, 404, { error: 'token not found' }, ctx.version); return true; }
+      if (tok.username !== me.username) {
+        writeJson(res, 403, { error: 'cannot rename a token you do not own' }, ctx.version);
+        return true;
+      }
+      const body = await readJson<{ name?: string }>(req);
+      if (typeof body.name !== 'string' || body.name.trim().length === 0) {
+        writeJson(res, 400, { error: 'token name required' }, ctx.version);
+        return true;
+      }
+      const updated = await ctx.tokenStore.rename(tokenId, body.name.trim());
+      writeJson(res, 200, { token: updated }, ctx.version);
+      return true;
+    }
+  }
+
+  // ── Account: change passphrase ───────────────────────────────────
+  if (method === 'POST' && path === '/api/account/passphrase') {
+    const body = await readJson<{ oldPassphrase?: string; newPassphrase?: string }>(req);
+    if (!body.oldPassphrase || !body.newPassphrase) {
+      writeJson(res, 400, { error: 'oldPassphrase + newPassphrase required' }, ctx.version);
+      return true;
+    }
+    const ok = await ctx.userStore.verifyPassphrase(me.username, body.oldPassphrase);
+    if (!ok) { writeJson(res, 401, { error: 'current passphrase incorrect' }, ctx.version); return true; }
+    try {
+      await ctx.userStore.setPassphrase(me.username, body.newPassphrase);
+      writeJson(res, 200, { ok: true }, ctx.version);
+    } catch (err) {
+      writeJson(res, 400, { error: (err as Error).message }, ctx.version);
+    }
+    return true;
+  }
+
+  // ── Users: admin-gated ────────────────────────────────────────────
+  if (path.startsWith('/api/users')) {
+    if (!me.admin) { writeJson(res, 403, { error: 'admin only' }, ctx.version); return true; }
+
+    if (method === 'POST' && path === '/api/users') {
+      const body = await readJson<{ username?: string; name?: string; passphrase?: string; admin?: boolean }>(req);
+      if (!body.username || !body.name || !body.passphrase) {
+        writeJson(res, 400, { error: 'username + name + passphrase required' }, ctx.version);
+        return true;
+      }
+      try {
+        const created = await ctx.userStore.createUser({
+          username: body.username, name: body.name, passphrase: body.passphrase, admin: body.admin === true,
+        });
+        // Don't echo the passphrase hash back.
+        const { passphraseHash: _ph, ...safe } = created;
+        void _ph;
+        writeJson(res, 201, safe, ctx.version);
+      } catch (err) {
+        writeJson(res, 400, { error: (err as Error).message }, ctx.version);
+      }
+      return true;
+    }
+
+    const m = path.match(/^\/api\/users\/([^/]+)$/);
+    if (m) {
+      const targetUsername = decodeURIComponent(m[1]!);
+      // Self-protection: admins can't delete or demote themselves —
+      // prevents the "last admin" footgun where deleting yourself
+      // locks the operator pool down with no path back without
+      // editing users.json by hand.
+      if (targetUsername === me.username) {
+        writeJson(res, 400, { error: 'cannot modify your own admin record via this endpoint' }, ctx.version);
+        return true;
+      }
+      if (method === 'DELETE') {
+        try {
+          await ctx.userStore.deleteUser(targetUsername);
+          // Revoke all tokens for the deleted user.
+          await ctx.tokenStore.revokeAllForUser(targetUsername);
+          writeJson(res, 200, { ok: true }, ctx.version);
+        } catch (err) {
+          writeJson(res, 404, { error: (err as Error).message }, ctx.version);
+        }
+        return true;
+      }
+      if (method === 'PATCH') {
+        const body = await readJson<{ admin?: boolean }>(req);
+        if (typeof body.admin !== 'boolean') {
+          writeJson(res, 400, { error: 'admin (boolean) required' }, ctx.version);
+          return true;
+        }
+        try {
+          await ctx.userStore.setAdmin(targetUsername, body.admin);
+          writeJson(res, 200, { ok: true }, ctx.version);
+        } catch (err) {
+          writeJson(res, 404, { error: (err as Error).message }, ctx.version);
+        }
+        return true;
+      }
+    }
+  }
+
+  // ── Settings snapshot (JSON, for CLI `settings show`) ───────────
+  if (method === 'GET' && path === '/api/settings') {
+    const apiPort = Number(process.env['CROSSTALK_API_PORT']) || DEFAULT_API_PORT;
+    writeJson(res, 200, {
+      alias: ctx.alias,
+      version: ctx.version,
+      transportRoot: ctx.transportRoot,
+      claimedModels: [...ctx.claimed.keys()],
+      pollSeconds: null,
+      apiPort,
+    }, ctx.version);
+    return true;
+  }
+
+  // ── Workflow list / detail (JSON, for CLI `workflow status`) ────
+  if (method === 'GET' && path === '/api/workflows') {
+    writeJson(res, 200, {
+      workflows: collectWorkflowSummaries(ctx.transportRoot),
+    }, ctx.version);
+    return true;
+  }
+  {
+    const m = path.match(/^\/api\/workflows\/([^/]+)$/);
+    // The compose / submit endpoints use the same prefix but with
+    // literal verbs (compose, submit). Detail lookups use a UUID-shaped
+    // child channel id; reject the literal-verb cases so we fall
+    // through to the POST handlers below.
+    if (m && method === 'GET' && m[1] !== 'compose' && m[1] !== 'submit') {
+      const childUuid = decodeURIComponent(m[1]!);
+      const detail = collectWorkflowDetail(ctx.transportRoot, childUuid);
+      if (!detail) {
+        writeJson(res, 404, { error: 'workflow not found' }, ctx.version);
+        return true;
+      }
+      writeJson(res, 200, detail, ctx.version);
+      return true;
+    }
+  }
+
+  // ── Workflow compose ─────────────────────────────────────────────
+  //
+  // Operator types a plain-language prompt; engine invokes the compiler
+  // agent (defaults to first claimed model) with COMPILE_PROMPT + the
+  // prompt as the document. Compiler returns JSON matching WorkflowPlan;
+  // we YAML-stringify it for the preview UI. Operator reviews + edits
+  // the YAML, then submits it back to /api/workflows/submit which
+  // creates the workflow message + writes PLAN.json pre-compiled so the
+  // dispatcher skips its own compile step.
+  if (method === 'POST' && path === '/api/workflows/compose') {
+    const body = await readJson<{ prompt?: string; compilerAgent?: string }>(req);
+    if (typeof body.prompt !== 'string' || body.prompt.trim().length === 0) {
+      writeJson(res, 400, { error: 'prompt required' }, ctx.version);
+      return true;
+    }
+    // Resolve compiler agent. body.compilerAgent is the qualified model
+    // name (<provider>/<model>) as it appears in the claimed map.
+    let compiler: ModelEntry | undefined;
+    if (body.compilerAgent && ctx.claimed.has(body.compilerAgent)) {
+      compiler = ctx.claimed.get(body.compilerAgent);
+    } else {
+      compiler = ctx.claimed.values().next().value as ModelEntry | undefined;
+    }
+    if (!compiler) {
+      writeJson(res, 409, { error: 'no claimed model available to compile — check /agents' }, ctx.version);
+      return true;
+    }
+    const result = await invokeModelCli(compiler, COMPILE_PROMPT, body.prompt, {});
+    if (result.status !== 0) {
+      writeJson(res, 502, {
+        error: `compiler exit ${result.status}: ${result.stderr.slice(0, 500)}`,
+        stdout: result.stdout.slice(0, 800),
+      }, ctx.version);
+      return true;
+    }
+    const plan = extractPlanFromOutput(result.stdout);
+    if (!plan) {
+      writeJson(res, 422, {
+        error: 'compiler output did not parse as a workflow plan',
+        rawOutput: result.stdout.slice(0, 1500),
+      }, ctx.version);
+      return true;
+    }
+    const yaml = yamlStringify(plan, { indent: 2 });
+    writeJson(res, 200, { plan, yaml, compiler: compiler.name }, ctx.version);
+    return true;
+  }
+  if (method === 'POST' && path === '/api/workflows/submit') {
+    const body = await readJson<{ yaml?: string; channel?: string; prompt?: string }>(req);
+    if (typeof body.yaml !== 'string' || body.yaml.length === 0) {
+      writeJson(res, 400, { error: 'yaml required' }, ctx.version);
+      return true;
+    }
+    let parsed: unknown;
+    try {
+      parsed = yamlParse(body.yaml);
+    } catch (err) {
+      writeJson(res, 400, { error: `yaml parse error: ${(err as Error).message}` }, ctx.version);
+      return true;
+    }
+    if (!validatePlan(parsed)) {
+      writeJson(res, 400, { error: 'yaml does not match workflow plan schema (fanout.to/count/body + synthesize.to/body)' }, ctx.version);
+      return true;
+    }
+    const plan = parsed as WorkflowPlan;
+    let parentUuid: string;
+    try {
+      parentUuid = resolveChannelUuid(ctx.transportRoot, body.channel);
+    } catch (err) {
+      writeJson(res, (err as HttpError).status ?? 400, { error: (err as Error).message }, ctx.version);
+      return true;
+    }
+    // Create child channel + pre-write PLAN.json so the dispatcher skips
+    // its own compile (loadPlan returns non-null).
+    const childUuid = randomUUID();
+    const childDir = join(ctx.transportRoot, 'data', 'channels', childUuid);
+    mkdirSync(childDir, { recursive: true });
+    writeFileSync(
+      join(childDir, 'CHANNEL.md'),
+      serializeFrontmatter({ name: `workflow-${Date.now()}`, parent: parentUuid }, ''),
+    );
+    writeFileSync(
+      join(childDir, 'PLAN.json'),
+      JSON.stringify(plan, null, 2) + '\n',
+    );
+    // Marker message body = operator's original prompt (for traceability).
+    const markerBody = typeof body.prompt === 'string' && body.prompt.length > 0
+      ? body.prompt
+      : '(composed via web UI)';
+    const heartbeat = readHeartbeat(ctx.transportRoot);
+    const dispatchHost = heartbeat?.alias;
+    const extraFrontmatter: Record<string, unknown> = { child_channel: childUuid };
+    if (dispatchHost) extraFrontmatter['dispatch_host'] = dispatchHost;
+    const relPath = writeMessageFile({
+      transportRoot: ctx.transportRoot,
+      channelUuid: parentUuid,
+      from: me.username,
+      to: 'workflow',
+      body: markerBody,
+      re: [],
+      extraFrontmatter,
+      workflow: true,
+    });
+    const push = gitCommitAndPush(
+      ctx.transportRoot,
+      `run(workflow): ${me.username} child ${childUuid.slice(0, 8)} (composed)`,
+    );
+    sendWakeSignal(ctx.transportRoot);
+    if (!push.committed && push.error) {
+      // Commit itself failed — must surface as 500 to caller.
+      writeJson(res, 500, { error: `commit failed: ${push.error.slice(0, 300)}` }, ctx.version);
+      return true;
+    }
+    // Push failed but commit landed locally — proceed; commits sync
+    // up the next time the remote becomes reachable.
+    writeJson(res, 201, { childUuid, parentUuid, relPath, plan }, ctx.version);
+    return true;
+  }
+
+  // ── Logs ─────────────────────────────────────────────────────────
+  //
+  // GET /api/logs?since=<seq>  → JSON snapshot of entries with seq > since
+  // GET /api/logs/stream       → SSE stream of new entries as they happen
+  //
+  // Both auth-gated like the rest of /api/*. Engine emits structured
+  // events via dispatch.ts's log() function which tees into the
+  // in-memory ring buffer (log-buffer.ts).
+  if (method === 'GET' && path === '/api/logs') {
+    const since = Number(u.searchParams.get('since') ?? 0);
+    const entries = logBuffer.recent(Number.isFinite(since) ? since : 0);
+    writeJson(res, 200, { entries, currentSeq: logBuffer.currentSeq }, ctx.version);
+    return true;
+  }
+  if (method === 'GET' && path === '/api/logs/stream') {
+    // SSE: keep the connection open + push every new log entry as a
+    // `data: <json>\n\n` frame. Cache-Control: no-cache is critical —
+    // intermediaries that buffer text/event-stream would coalesce
+    // frames and break live tail.
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Crosstalk-Engine-Version': ctx.version,
+    });
+    // Initial snapshot so the browser has context immediately. The
+    // since= query param replays only newer entries (used when the
+    // client reconnects after a transient disconnect).
+    const sinceParam = Number(u.searchParams.get('since') ?? 0);
+    const since = Number.isFinite(sinceParam) ? sinceParam : 0;
+    for (const entry of logBuffer.recent(since)) {
+      try { res.write(`data: ${JSON.stringify(entry)}\n\n`); } catch { /* socket dead */ }
+    }
+    const writeEntry = (entry: LogEntry): void => {
+      try { res.write(`data: ${JSON.stringify(entry)}\n\n`); }
+      catch { /* socket closing */ }
+    };
+    const unsubscribe = logBuffer.subscribe(writeEntry);
+    // Idle keep-alive every 15s so proxies don't reap the connection.
+    const keepAlive = setInterval(() => {
+      try { res.write(`: keep-alive\n\n`); } catch { /* closed */ }
+    }, 15_000);
+    req.on('close', () => { unsubscribe(); clearInterval(keepAlive); });
+    return true;
+  }
+
+  // Path matched the prefix but no method handler — 405.
+  writeJson(res, 405, { error: `method ${method} not allowed on ${path}` }, ctx.version);
+  return true;
+}
+
+/** Try to handle the request as an HTML route. Returns true if handled. */
+async function tryHtmlRoute(ctx: ApiContext, req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  const { method = 'GET', url = '/' } = req;
+  if (method !== 'GET') return false;
+  const u = new URL(url, 'http://localhost');
+  const path = u.pathname;
+  const host = hostString();
+
+  if (path === '/') {
+    const hb = readHeartbeat(ctx.transportRoot);
+    const cursor = readCursor(ctx.transportRoot);
+    const channels = allChannelMeta(ctx.transportRoot);
+    writeHtml(res, 200, dashboardPage({
+      host, alias: ctx.alias, version: ctx.version, transportRoot: ctx.transportRoot,
+      heartbeat: hb ? { ts: hb.ts, pid: hb.pid, version: hb.version, alias: hb.alias } : null,
+      cursor: cursor ?? null,
+      claimedModels: [...ctx.claimed.keys()],
+      channels: channels.map(c => ({ uuid: c.uuid, name: c.name, parent: c.parent })),
+      errorsLogged: countErrors(ctx.transportRoot),
+      pendingWork: collectPendingWork(ctx.transportRoot, ctx.claimed),
+    }), ctx.version);
+    return true;
+  }
+
+  if (path === '/c') {
+    const channels = allChannelMeta(ctx.transportRoot);
+    writeHtml(res, 200, channelListPage({
+      host, alias: ctx.alias,
+      channels: channels.map(c => ({ uuid: c.uuid, name: c.name, parent: c.parent })),
+    }), ctx.version);
+    return true;
+  }
+
+  const channelMatch = path.match(/^\/c\/([^/]+)(?:\/(.+))?$/);
+  if (channelMatch) {
+    const handle = decodeURIComponent(channelMatch[1]!);
+    const sub = channelMatch[2];
+    const meta = resolveChannelHandle(ctx.transportRoot, handle);
+    if (!meta) {
+      writeHtml(res, 404, channelListPage({
+        host, alias: ctx.alias,
+        channels: allChannelMeta(ctx.transportRoot).map(c => ({ uuid: c.uuid, name: c.name, parent: c.parent })),
+      }), ctx.version);
+      return true;
+    }
+    if (sub === 'messages.json') {
+      const messages = collectBusMessages(ctx.transportRoot, meta.uuid);
+      writeJson(res, 200, { messages }, ctx.version);
+      return true;
+    }
+    if (sub === undefined) {
+      const messages = collectBusMessages(ctx.transportRoot, meta.uuid);
+      writeHtml(res, 200, channelViewPage({
+        host, alias: ctx.alias,
+        channelHandle: handle, channelUuid: meta.uuid, channelName: meta.name, messages,
+      }), ctx.version);
+      return true;
+    }
+  }
+
+  if (path === '/events') {
+    // Server-Sent Events stream: emits status snapshots whenever the
+    // dispatcher cursor or heartbeat changes. Dashboard subscribes
+    // instead of polling every 5s. Headers per SSE spec; we keep the
+    // connection open and write `data: <json>\n\n` frames.
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Crosstalk-Engine-Version': ctx.version,
+    });
+    let lastCursor: string | null = readCursor(ctx.transportRoot) ?? null;
+    let lastHb: string | null = readHeartbeat(ctx.transportRoot)?.ts ?? null;
+    const emit = (event: string, data: unknown): void => {
+      try { res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); }
+      catch { /* socket closed */ }
+    };
+    // Initial snapshot so the client has state immediately.
+    emit('snapshot', {
+      cursor: lastCursor,
+      heartbeat: readHeartbeat(ctx.transportRoot),
+      channels: allChannelMeta(ctx.transportRoot).length,
+      errors: countErrors(ctx.transportRoot),
+      claimedModels: [...ctx.claimed.keys()],
+    });
+    const tick = setInterval(() => {
+      const hb = readHeartbeat(ctx.transportRoot);
+      const cur = readCursor(ctx.transportRoot) ?? null;
+      const hbTs = hb?.ts ?? null;
+      if (cur !== lastCursor || hbTs !== lastHb) {
+        lastCursor = cur; lastHb = hbTs;
+        emit('update', {
+          cursor: cur,
+          heartbeat: hb,
+          channels: allChannelMeta(ctx.transportRoot).length,
+          errors: countErrors(ctx.transportRoot),
+          claimedModels: [...ctx.claimed.keys()],
+        });
+      } else {
+        // Keep-alive comment frame every tick when idle (the spec allows
+        // \`:\` lines; intermediate proxies that buffer SSE will release
+        // them, holding the connection open across long idle windows).
+        try { res.write(`: keep-alive\n\n`); } catch { /* closed */ }
+      }
+    }, 2000);
+    req.on('close', () => { clearInterval(tick); });
+    return true;
+  }
+
+  if (path === '/w') {
+    const channels = allChannelMeta(ctx.transportRoot)
+      .map((c) => ({ uuid: c.uuid, name: c.name }));
+    writeHtml(res, 200, workflowsListPage({
+      host, alias: ctx.alias,
+      workflows: collectWorkflowSummaries(ctx.transportRoot),
+      claimedModels: [...ctx.claimed.keys()],
+      channels,
+    }), ctx.version);
+    return true;
+  }
+  const wMatch = path.match(/^\/w\/([^/]+)$/);
+  if (wMatch) {
+    const childUuid = decodeURIComponent(wMatch[1]!);
+    const detail = collectWorkflowDetail(ctx.transportRoot, childUuid);
+    if (!detail) {
+      writeHtml(res, 404, workflowsListPage({
+        host, alias: ctx.alias,
+        workflows: collectWorkflowSummaries(ctx.transportRoot),
+        claimedModels: [...ctx.claimed.keys()],
+        channels: allChannelMeta(ctx.transportRoot).map((c) => ({ uuid: c.uuid, name: c.name })),
+      }), ctx.version);
+      return true;
+    }
+    writeHtml(res, 200, workflowDetailPage({ host, alias: ctx.alias, ...detail }), ctx.version);
+    return true;
+  }
+
+  if (path === '/agents') {
+    const installed = KNOWN_AGENT_BINARIES.filter((bin) => isOnPath(bin));
+    const yamlReferenced = [...new Set([...ctx.registry.all.values()].map((e) => e.cli))];
+    const claimed = [...new Set([...ctx.claimed.values()].map((e) => e.cli))];
+    writeHtml(res, 200, agentsPage({
+      host, alias: ctx.alias, installed, known: KNOWN_AGENT_BINARIES, yamlReferenced, claimed,
+    }), ctx.version);
+    return true;
+  }
+
+  if (path === '/chat') {
+    const installed = KNOWN_AGENT_BINARIES.filter((bin) => isOnPath(bin));
+    writeHtml(res, 200, chatPage({
+      host, alias: ctx.alias, installedAgents: installed, version: ctx.version,
+      home: homedir(),
+    }), ctx.version);
+    return true;
+  }
+
+  // Auth-aware stub pages. authenticateRequest is a no-op (returns
+  // notOk) when the stores aren't configured — the gate above already
+  // short-circuited unauthed access, so by the time we get here we
+  // know the user is authed in normal operation.
+  if (path === '/account') {
+    let user = null;
+    if (ctx.userStore && ctx.tokenStore) {
+      const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+      if (auth.ok) user = auth.user;
+    }
+    writeHtml(res, 200, accountPage({ host, alias: ctx.alias, user }), ctx.version);
+    return true;
+  }
+  if (path === '/users') {
+    let users: import('./auth/users.js').User[] = [];
+    let isAdmin = false;
+    let viewerUsername: string | null = null;
+    if (ctx.userStore && ctx.tokenStore) {
+      const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+      if (auth.ok) { isAdmin = auth.user.admin; viewerUsername = auth.user.username; }
+      if (isAdmin) users = await ctx.userStore.listUsers();
+    }
+    writeHtml(res, 200, usersPage({ host, alias: ctx.alias, users, viewerIsAdmin: isAdmin, viewerUsername }), ctx.version);
+    return true;
+  }
+  if (path === '/tokens') {
+    let tokens: import('./auth/tokens.js').IdentityToken[] = [];
+    let viewerUsername: string | null = null;
+    if (ctx.userStore && ctx.tokenStore) {
+      const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+      if (auth.ok) {
+        viewerUsername = auth.user.username;
+        tokens = await ctx.tokenStore.list(auth.user.username);
+      }
+    }
+    writeHtml(res, 200, tokensPage({ host, alias: ctx.alias, tokens, viewerUsername }), ctx.version);
+    return true;
+  }
+  if (path === '/logs') {
+    writeHtml(res, 200, logsPage({
+      host, alias: ctx.alias, errorsLogged: countErrors(ctx.transportRoot),
+      transportRoot: ctx.transportRoot,
+    }), ctx.version);
+    return true;
+  }
+  if (path === '/settings') {
+    const port = Number(process.env['CROSSTALK_API_PORT']) || DEFAULT_API_PORT;
+    writeHtml(res, 200, settingsPage({
+      host, alias: ctx.alias, version: ctx.version, transportRoot: ctx.transportRoot,
+      claimedModels: [...ctx.claimed.keys()],
+      pollSeconds: null, // dispatcher cadence isn't on ctx yet; nullable so the UI shows '—'
+      apiPort: port,
+    }), ctx.version);
+    return true;
+  }
+  if (path === '/about') {
+    writeHtml(res, 200, aboutPage({
+      host, alias: ctx.alias, version: ctx.version, transportRoot: ctx.transportRoot,
+    }), ctx.version);
+    return true;
+  }
+
+  return false;
+}
+
+/** Build a summary row for every workflow marker (open or complete) on the bus. */
+function collectWorkflowSummaries(transportRoot: string): WorkflowSummary[] {
+  const channels = discoverChannels(transportRoot);
+  const out: WorkflowSummary[] = [];
+  for (const parentUuid of channels) {
+    const parentMeta = readChannelMeta(transportRoot, parentUuid);
+    const parentMessages = listChannelMessages(transportRoot, parentUuid);
+    for (const m of parentMessages) {
+      if (m.data['type'] !== 'workflow') continue;
+      const childUuid = m.data['child_channel'];
+      if (typeof childUuid !== 'string') continue;
+      out.push(buildWorkflowSummary(transportRoot, parentMeta, childUuid, m));
+    }
+  }
+  // Newest workflow markers first.
+  out.sort((a, b) => (b.markerTimestamp || '').localeCompare(a.markerTimestamp || ''));
+  return out;
+}
+
+function buildWorkflowSummary(
+  transportRoot: string,
+  parentMeta: ChannelMeta,
+  childUuid: string,
+  marker: { data: Record<string, unknown>; relPath: string; body: string },
+): WorkflowSummary {
+  const completeFile = join(transportRoot, 'data', 'channels', childUuid, 'COMPLETE');
+  const planFile = join(transportRoot, 'data', 'channels', childUuid, 'PLAN.json');
+  const isComplete = existsSync(completeFile);
+  const childMessages = existsSync(join(transportRoot, 'data', 'channels', childUuid))
+    ? listChannelMessages(transportRoot, childUuid)
+    : [];
+
+  // Count fanout dispatches + their replies.
+  const fanoutDispatches = childMessages.filter((m) => m.data['workflow_phase'] === 'fanout');
+  const fanoutDispatchPaths = new Set(fanoutDispatches.map((m) => m.relPath));
+  const fanoutReplies = childMessages.filter((m) => {
+    const re = m.data['re'];
+    const list = Array.isArray(re) ? re : (typeof re === 'string' ? [re] : []);
+    return list.some((p) => fanoutDispatchPaths.has(p));
+  });
+
+  // Failed: any fanout or synthesis reply with failed:true, OR no plan after long enough.
+  const anyFailedReply = childMessages.some((m) => m.data['failed'] === true);
+
+  let phase: WorkflowSummary['phase'];
+  if (isComplete) phase = 'complete';
+  else if (anyFailedReply) phase = 'failed';
+  else if (!existsSync(planFile)) phase = 'pending_compile';
+  else {
+    // Plan exists. Check if synthesis phase has started.
+    const synth = childMessages.find((m) => m.data['workflow_phase'] === 'synthesize');
+    phase = synth ? 'synthesize' : 'fanout';
+  }
+
+  const dispatchHost = typeof marker.data['dispatch_host'] === 'string'
+    ? (marker.data['dispatch_host'] as string)
+    : null;
+
+  return {
+    childChannelUuid: childUuid,
+    parentChannelUuid: parentMeta.uuid,
+    parentChannelName: parentMeta.name,
+    markerFrom: String(marker.data['from'] ?? 'unknown'),
+    markerTimestamp: String(marker.data['timestamp'] ?? ''),
+    phase,
+    fanoutTotal: fanoutDispatches.length,
+    fanoutReplied: fanoutReplies.length,
+    dispatchHost,
+  };
+}
+
+/** Full detail for one workflow. Returns null if no matching marker found. */
+function collectWorkflowDetail(transportRoot: string, childUuid: string):
+  Omit<Parameters<typeof workflowDetailPage>[0], 'host' | 'alias'> | null {
+  const channels = discoverChannels(transportRoot);
+  // Find the parent — the channel that contains the workflow marker
+  // pointing at this child uuid.
+  let markerData: Record<string, unknown> | null = null;
+  let markerBody = '';
+  let markerRelPath = '';
+  let parentMeta: ChannelMeta | null = null;
+  for (const parentUuid of channels) {
+    const parentMessages = listChannelMessages(transportRoot, parentUuid);
+    for (const m of parentMessages) {
+      if (m.data['type'] === 'workflow' && m.data['child_channel'] === childUuid) {
+        markerData = m.data;
+        markerBody = m.body;
+        markerRelPath = m.relPath;
+        parentMeta = readChannelMeta(transportRoot, parentUuid);
+        break;
+      }
+    }
+    if (markerData) break;
+  }
+  if (!markerData || !parentMeta) return null;
+
+  const planFile = join(transportRoot, 'data', 'channels', childUuid, 'PLAN.json');
+  let plan: unknown = null;
+  if (existsSync(planFile)) {
+    try {
+      const parsed = JSON.parse(readFileSync(planFile, 'utf-8')) as unknown;
+      plan = validatePlan(parsed) ? parsed : { invalid: true, raw: parsed };
+    } catch { plan = null; }
+  }
+
+  const childMessages = existsSync(join(transportRoot, 'data', 'channels', childUuid))
+    ? listChannelMessages(transportRoot, childUuid)
+    : [];
+
+  const fanoutDispatches = childMessages
+    .filter((m) => m.data['workflow_phase'] === 'fanout')
+    .map((m) => ({
+      relPath: m.relPath,
+      to: Array.isArray(m.data['to']) ? (m.data['to'] as string[]).join(',') : String(m.data['to'] ?? ''),
+      body: m.body,
+    }));
+  const fanoutDispatchPaths = new Set(fanoutDispatches.map((d) => d.relPath));
+  const fanoutReplies = childMessages
+    .filter((m) => {
+      const re = m.data['re'];
+      const list = Array.isArray(re) ? re : (typeof re === 'string' ? [re] : []);
+      return list.some((p) => fanoutDispatchPaths.has(p));
+    })
+    .map((m) => ({
+      relPath: m.relPath,
+      from: String(m.data['from'] ?? 'unknown'),
+      re: (m.data['re'] as string | string[]) ?? '',
+      body: m.body,
+      failed: m.data['failed'] === true,
+    }));
+
+  const synthDispatchMsg = childMessages.find((m) => m.data['workflow_phase'] === 'synthesize');
+  const synthesisDispatch = synthDispatchMsg
+    ? {
+        relPath: synthDispatchMsg.relPath,
+        to: Array.isArray(synthDispatchMsg.data['to']) ? (synthDispatchMsg.data['to'] as string[]).join(',') : String(synthDispatchMsg.data['to'] ?? ''),
+        body: synthDispatchMsg.body,
+      }
+    : null;
+  const synthesisReplyMsg = synthDispatchMsg
+    ? childMessages.find((m) => {
+        const re = m.data['re'];
+        const list = Array.isArray(re) ? re : (typeof re === 'string' ? [re] : []);
+        return list.includes(synthDispatchMsg.relPath);
+      })
+    : undefined;
+  const synthesisReply = synthesisReplyMsg
+    ? {
+        relPath: synthesisReplyMsg.relPath,
+        from: String(synthesisReplyMsg.data['from'] ?? 'unknown'),
+        body: synthesisReplyMsg.body,
+        failed: synthesisReplyMsg.data['failed'] === true,
+      }
+    : null;
+
+  const completeFile = join(transportRoot, 'data', 'channels', childUuid, 'COMPLETE');
+  const isComplete = existsSync(completeFile);
+  const anyFailed = childMessages.some((m) => m.data['failed'] === true);
+  let phase: WorkflowSummary['phase'];
+  if (isComplete) phase = 'complete';
+  else if (anyFailed) phase = 'failed';
+  else if (!existsSync(planFile)) phase = 'pending_compile';
+  else if (synthDispatchMsg) phase = 'synthesize';
+  else phase = 'fanout';
+
+  // Reference markerRelPath so unused-var checks pass; also useful for
+  // future "open the marker message" deep-links from the detail page.
+  void markerRelPath;
+
+  return {
+    childUuid,
+    parentChannelUuid: parentMeta.uuid,
+    parentChannelName: parentMeta.name,
+    markerFrom: String(markerData['from'] ?? 'unknown'),
+    markerTimestamp: String(markerData['timestamp'] ?? ''),
+    markerBody,
+    plan,
+    phase,
+    fanoutDispatches,
+    fanoutReplies,
+    synthesisDispatch,
+    synthesisReply,
+    dispatchHost: typeof markerData['dispatch_host'] === 'string' ? (markerData['dispatch_host'] as string) : null,
+  };
+}
+
+/**
+ * Walk every channel and count messages with no reply pointing at
+ * them, grouped by recipient. Powers the dashboard's "pending work"
+ * card — gives operators an at-a-glance view of what the dispatcher
+ * will be picking up on its next tick(s).
+ *
+ * O(N) over all messages on the bus; cheap for the typical capstone-
+ * scale transport, would need indexing if we ever push past ~10k.
+ */
+function collectPendingWork(
+  transportRoot: string,
+  claimed: Map<string, ModelEntry>,
+): { to: string; count: number; channelLabels: string[] }[] {
+  const channels = discoverChannels(transportRoot);
+  const acc = new Map<string, { count: number; channels: Set<string> }>();
+  // A recipient is dispatcher-actionable if some claimed model name
+  // matches the actor portion (before '@'). Anything else (humans,
+  // unclaimed models, agents on other hosts) won't be picked up by
+  // this dispatcher's next tick, so it shouldn't count as pending.
+  const claimedActors = new Set([...claimed.keys()]);
+  function isClaimable(recipient: string): boolean {
+    if (recipient === 'all') return true;
+    const at = recipient.indexOf('@');
+    const actor = at === -1 ? recipient : recipient.slice(0, at);
+    return claimedActors.has(actor);
+  }
+  for (const channelUuid of channels) {
+    const meta = readChannelMeta(transportRoot, channelUuid);
+    const label = meta.name ?? channelUuid.slice(0, 8) + '…';
+    const messages = listChannelMessages(transportRoot, channelUuid);
+    const replied = new Set<string>();
+    for (const m of messages) {
+      const re = m.data['re'];
+      const list = Array.isArray(re) ? re : (typeof re === 'string' ? [re] : []);
+      for (const t of list) replied.add(t as string);
+    }
+    for (const m of messages) {
+      // Skip workflow markers — they live in the Workflows surface.
+      if (m.data['type'] === 'workflow') continue;
+      // Skip messages internal to a workflow run. Once a fanout
+      // dispatch is sent, its reply is consumed by the workflow
+      // runtime advancing phase — not by another message being
+      // posted in reply. Counting them as pending overstates the
+      // dispatcher's actual queue.
+      if (typeof m.data['workflow_phase'] === 'string') continue;
+      // Skip messages SENT BY the workflow runtime (workflow@<alias>)
+      // — same reason; runtime-managed, not bus-pending.
+      const from = String(m.data['from'] ?? '');
+      if (from.startsWith('workflow@')) continue;
+      if (replied.has(m.relPath)) continue;
+      const to = m.data['to'];
+      const recipients = Array.isArray(to) ? to : (typeof to === 'string' ? [to] : []);
+      for (const r of recipients) {
+        const recipient = String(r);
+        // Skip recipients this dispatcher can't service. Humans
+        // (named users), unclaimed models, or models claimed on a
+        // different host — none of these will be picked up.
+        if (!isClaimable(recipient)) continue;
+        if (!acc.has(recipient)) acc.set(recipient, { count: 0, channels: new Set() });
+        const e = acc.get(recipient)!;
+        e.count++;
+        e.channels.add(label);
+      }
+    }
+  }
+  return Array.from(acc.entries())
+    .map(([to, e]) => ({ to, count: e.count, channelLabels: Array.from(e.channels) }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/** Pull all bus messages for a channel into the shape the web UI consumes. */
+function collectBusMessages(transportRoot: string, channelUuid: string): BusMessage[] {
+  const raw = listChannelMessages(transportRoot, channelUuid);
+  return raw.map((m) => ({
+    relPath: m.relPath,
+    from: String(m.data['from'] ?? ''),
+    to: (m.data['to'] as string | string[]) ?? '',
+    re: (m.data['re'] as string | string[] | null) ?? null,
+    body: m.body,
+    timestamp: String(m.data['timestamp'] ?? ''),
+    failed: m.data['failed'] === true,
+  }));
+}
+
+// ── router ───────────────────────────────────────────────────────────
+
+async function route(ctx: ApiContext, req: IncomingMessage): Promise<JsonRes> {
+  const { method = 'GET', url = '/' } = req;
+  const u = new URL(url, 'http://localhost');
+  const path = u.pathname;
+
+  if (method === 'GET' && path === '/healthz') return handleHealthz(ctx);
+  if (method === 'GET' && path === '/version') return handleVersion(ctx);
+  if (method === 'GET' && path === '/status') return handleStatus(ctx);
+  if (method === 'GET' && path === '/agents/installed') return handleAgentsInstalled(ctx);
+  if (method === 'GET' && path === '/channels') return handleListChannels(ctx);
+  if (method === 'POST' && path === '/channels') {
+    const body = await readJson<CreateChannelReq>(req);
+    return handleCreateChannel(ctx, body);
+  }
+  // PATCH /channels/<handle>  — rename
+  // DELETE /channels/<handle>?confirm=<typed-name>  — delete
+  {
+    const m = path.match(/^\/channels\/([^/]+)$/);
+    if (m) {
+      const handle = decodeURIComponent(m[1]!);
+      if (method === 'PATCH') {
+        const body = await readJson<RenameChannelReq>(req);
+        return handleRenameChannel(ctx, handle, body);
+      }
+      if (method === 'DELETE') {
+        return handleDeleteChannel(ctx, handle, u.searchParams.get('confirm'));
+      }
+    }
+  }
+  if (method === 'POST' && path === '/messages') {
+    const body = await readJson<PostMessageReq>(req);
+    return handlePostMessage(ctx, body);
+  }
+  if (method === 'GET' && path === '/replies') {
+    const targets = u.searchParams.get('relPaths') ?? '';
+    return handleReplies(ctx, targets);
+  }
+  return { status: 404, body: { error: `no route for ${method} ${path}` } };
+}
+
+// ── server lifecycle ─────────────────────────────────────────────────
+
+export const DEFAULT_API_PORT = 7000;
+
+export interface StartApiOptions {
+  port?: number;
+  log: (event: string, fields?: Record<string, unknown>) => void;
+}
+
+export function startApi(ctx: ApiContext, opts: StartApiOptions): Server {
+  const port = opts.port ?? (Number(process.env['CROSSTALK_API_PORT']) || DEFAULT_API_PORT);
+  // Bind address resolution:
+  //   - Native (default):  127.0.0.1 — engine running as a host process
+  //     should not expose the API to the network. Localhost only.
+  //   - Container:         0.0.0.0 (set via ENV CROSSTALK_API_BIND in
+  //     the Dockerfile) — Docker's bridge networking means "127.0.0.1
+  //     inside the container" can't be reached via the daemon's port
+  //     forwarder. The actual security boundary moves up to compose's
+  //     port mapping (`127.0.0.1:HOST:CONTAINER`), which restricts
+  //     reachability to host loopback only.
+  //
+  // The engine bind address is therefore env-controlled, BUT operators
+  // never need to set it manually — the container image does it.
+  const bind = process.env['CROSSTALK_API_BIND'] ?? '127.0.0.1';
+  const server = createServer(async (req, res) => {
+    try {
+      // v8 auth gate for web routes. Either handles the request fully
+      // (setup wizard, login, logout, redirect to /setup or /login),
+      // or returns 'allow' to continue to the HTML / JSON routers.
+      const authOutcome = await tryWebAuthFlow(ctx, req, res);
+      if (authOutcome === 'handled' || authOutcome === 'redirect') return;
+
+      // Web-side JSON API (token mgmt, account passphrase, user
+      // admin). Runs before tryHtmlRoute since paths start with /api.
+      if (await tryWebApiRoute(ctx, req, res)) return;
+
+      // Try HTML routes first (/, /c, /c/<handle>, /agents). The HTML
+      // surface is GET-only and lives at paths distinct from the JSON
+      // API, so no conflicts. If no HTML route matches, fall through to
+      // the JSON router (which handles the existing API surface).
+      if (await tryHtmlRoute(ctx, req, res)) return;
+
+      // v8 operational-API auth gate. The historical "if you're on the
+      // host you're trusted" model is replaced by uniform bearer-token
+      // auth — CLI commands authenticate the same way the web UI does.
+      // /healthz and /version stay open as monitoring probes (standard
+      // pattern — kubelet/loadbalancer needs to ping them).
+      if (ctx.userStore && ctx.tokenStore) {
+        const u = new URL(req.url ?? '/', 'http://localhost');
+        const path = u.pathname;
+        const isExempt = path === '/healthz' || path === '/version';
+        if (!isExempt) {
+          // If setup hasn't run yet, return a clear "setup needed"
+          // response with the URL — operators see this immediately
+          // when their first CLI call fails after engine boot.
+          const setup = await setupGate(ctx.userStore, path);
+          if (!setup.allow) {
+            writeJson(res, setup.status ?? 503, setup.body ?? { error: 'setup needed' }, ctx.version);
+            return;
+          }
+          const auth = await authenticateRequest(req, { tokenStore: ctx.tokenStore, userStore: ctx.userStore });
+          if (!auth.ok) {
+            // Body includes a hint operators can act on: run
+            // 'crosstalk auth login' to bootstrap a token.
+            writeJson(res, auth.status, {
+              ...(auth.body as Record<string, unknown>),
+              hint: "run 'crosstalk auth login' to obtain a token",
+            }, ctx.version);
+            return;
+          }
+        }
+      }
+
+      const result = await route(ctx, req);
+      writeJson(res, result.status, result.body, ctx.version);
+    } catch (err) {
+      if (err instanceof HttpError) {
+        writeJson(res, err.status, { error: err.message }, ctx.version);
+      } else {
+        const msg = (err as Error).message;
+        opts.log('api_handler_crash', { error: msg.slice(0, 300) });
+        writeJson(res, 500, { error: `internal error: ${msg.slice(0, 200)}` }, ctx.version);
+      }
+    }
+  });
+  // Mount the chat pty WS bridge. Same auth model as the HTML routes —
+  // if user/token stores are configured, the WS upgrade is gated by a
+  // valid crosstalk_session cookie (or bearer token). Without auth
+  // stores (legacy/loopback-only mode), the WS is open since the bind
+  // address is the security boundary.
+  mountChatPty(server, {
+    authorize: ctx.userStore && ctx.tokenStore
+      ? async (req) => {
+          const auth = await authenticateRequest(req, {
+            tokenStore: ctx.tokenStore!,
+            userStore: ctx.userStore!,
+          });
+          return auth.ok;
+        }
+      : undefined,
+  });
+
+  server.listen(port, bind, () => {
+    opts.log('api_listening', { host: bind, port });
+  });
+  return server;
+}