sonorance 0.1.0-beta.4.1

package/src/server/index.mjs

@@ -0,0 +1,993 @@
+/**
+ * server/index.mjs — the local Deliberate workbench daemon.
+ *
+ * A small `node:http` server (no external deps) that serves the web app and a
+ * handful of file-backed endpoints over the current project's vault. It is a
+ * *workbench*, not the pipeline: it reads and edits the case records on disk and
+ * reports git status — running the funnel is the skill/CLI's job, in-harness.
+ *
+ * Endpoints (all JSON unless noted):
+ *   GET  /api/state          → { project, cases:[…attention], isGit }
+ *   GET  /api/record?id=<id> → { id,num,title,file,exists,text,idea,isGit }
+ *   POST /api/record         → { ok, updated }         (body: { id, text })
+ *   POST /api/create         → { ok, path }             (body: { path } — create a new .md file)
+ *   POST /api/mkdir          → { ok, path }             (body: { path } — create a new folder)
+ *   POST /api/move           → { ok, from, path }       (body: { src, dest } — move file/folder into dest folder; dest:'' = root)
+ *   POST /api/rename        → { ok, from, path }        (body: { path, name } — rename a file/folder in place)
+ *   POST /api/config        → { ok }                    (body: { patch } — merge project config keys)
+ *   DELETE /api/file         → { ok, path }             (body: { path } — remove a file or folder)
+ *   GET  /api/diff?id=<id>   → { isGit, tracked, diff, base, work } (analysis.md vs HEAD)
+ *   POST /api/comment       → { ok, commentId, file }        (reader selection + comment on a file)
+ *   GET  /api/address        → { comments:[…], count }       (agent drains open comments, each w/ file)
+ *   POST /api/resolve        → { ok }                         (agent marks a comment resolved by id)
+ *   GET  /api/comments?file=<path>→ { comments }              (a file's comments)
+ *   GET  /api/comments-summary → { counts:{rel:n}, total }    (per-file OPEN comment counts, read-only)
+ *   DELETE /api/comment      → { ok }                         (reader deletes their comment by id)
+ *   GET  /api/events         → SSE stream (comment / resolve / delete / addressing push)
+ *   GET  /api/asset?path=<p> → a vault image (binary, typed; for Markdown `![](…)` images)
+ *   GET  /api/browse?path=<d> → { path, parent, home, entries:[{name,path}] } (folder picker: dirs only)
+ *   GET  /icon.png           → the app icon (favicon / PWA)
+ *   GET  /manifest.webmanifest → PWA manifest
+ *   GET  *                   → the web app (src/ui/index.html)
+ */
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, extname, resolve, relative, sep, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { readFileSync, readdirSync, rmSync, writeFileSync, mkdirSync, existsSync, statSync, watch, renameSync } from 'node:fs';
+import { ensureGitignore } from '../gitignore.mjs';
+import { configureTelemetry, refreshTelemetry, emit, flushTelemetry, submitTelemetryBatch, shutdownTelemetry, telemetryMode } from '../telemetry.mjs';
+import { submitFeedback } from '../feedback.mjs';
+import { getConsent, setConsent, ensureInstallId } from '../identity.mjs';
+
+// The app is a GENERIC markdown editor: it imports no product engine. The host (e.g. the
+// `deliberate` package) injects an `engine` object into startServer with the vault store
+// factory (openVault), project resolvers (currentProject / setCurrentProject /
+// resolveProject), the declarative document-kind registry (KINDS), and a logger
+// (info / error / installCrashHandlers). Everything product-specific arrives through it; the
+// app knows only these injected capabilities. `E` is set once per process by startServer,
+// before any route runs; `info`/`error` are rebound from it.
+let E = null;
+let info = () => {}, error = () => {};
+
+const here = dirname(fileURLToPath(import.meta.url));
+// Image types the daemon serves for Markdown images (GET /api/asset). Extension-gated so the
+// asset endpoint can never be used to read arbitrary (e.g. `.md`, `.json`, `.env`) files.
+const IMG_TYPES = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.avif': 'image/avif', '.bmp': 'image/bmp', '.ico': 'image/x-icon',
+};
+// The app version + a capability flag. `GET /api/state` returns these so the UI
+// (always read fresh from disk) can detect it's being served by a STALE `serve` process
+// that predates the current routes — the "new UI + old in-memory routes" version skew.
+// An out-of-date server omits `bridge`/returns an older `version`, and the UI warns.
+const PKG = (() => { try { return JSON.parse(readFileSync(join(here, '../../package.json'), 'utf8')); } catch { return {}; } })();
+const APP_VERSION = String(PKG.version || '0');
+// The app's own, stable identity. Branch A: the app is ALWAYS Sonorance across every vault — a
+// plugin (e.g. Deliberate) surfaces per-project via kinds/inbox, it never renames the app. So
+// identity + the canonical command hints are app-owned here, not read from the (per-vault) engine.
+const SONORANCE = { name: 'Sonorance', serve: 'sonorance serve', address: '/sonorance address' };
+const ex = promisify(execFile);
+// Editor state (open tabs / active tab / Explorer) lives in `.sonorance/local/state.json`.
+const readState = (store, pid) => store.getState(pid) || {};
+const writeState = (store, pid, key, value) => store.setState(pid, key, value);
+const writeStateMany = (store, pid, patch) => store.setStateMany(pid, patch);
+const json = (res, code, body) => { res.writeHead(code, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); };
+// Read + parse a JSON request body defensively: malformed JSON yields `{}` (routes then return
+// their own validation error, never a 500), and the body is capped so a runaway/oversized POST
+// can't buffer unbounded memory.
+const MAX_BODY = 16 * 1024 * 1024;
+const readBody = (req) => new Promise(r => {
+  let b = '', size = 0, tooBig = false;
+  req.on('data', c => { size += c.length; if (size > MAX_BODY){ tooBig = true; req.destroy(); return; } b += c; });
+  req.on('end', () => { if (tooBig) return r({}); try { r(b ? JSON.parse(b) : {}); } catch { r({}); } });
+  req.on('error', () => r({}));
+});
+
+// ---- git (read-only) ----------------------------------------------------------
+// The vault may or may not be a git repo (in-repo projects ride the user's git;
+// standalone folders don't). Every git call is best-effort and never throws.
+async function git(root, args) {
+  try { const { stdout } = await ex('git', ['-C', root, ...args], { maxBuffer: 16 * 1024 * 1024 }); return { ok: true, out: stdout }; }
+  catch (e) { return { ok: false, out: e.stdout || '', err: e.stderr || e.message, code: e.code }; }
+}
+async function isGitRepo(root) {
+  if (!root) return false;
+  const r = await git(root, ['rev-parse', '--is-inside-work-tree']);
+  return r.ok && r.out.trim() === 'true';
+}
+// The working-tree diff of one file vs. the last commit. Tracked files use plain
+// `git diff`; an untracked-but-present record is diffed against /dev/null so the
+// whole new file reads as an addition. Empty string = no changes.
+async function fileDiff(root, file) {
+  const tracked = (await git(root, ['ls-files', '--error-unmatch', '--', file])).ok;
+  if (tracked) return { tracked: true, diff: (await git(root, ['diff', '--no-color', '--', file])).out };
+  const r = await git(root, ['diff', '--no-color', '--no-index', '--', '/dev/null', file]); // exits 1 when differing
+  return { tracked: false, diff: r.out };
+}
+// The committed (HEAD) and current working-tree contents of one file, for the workbench's
+// rendered unified diff (which reconstructs the change as marked-up Markdown, not a raw patch).
+// `base` is the last-committed text ('' for an untracked/new file); `work` is what's on disk now
+// ('' for a file deleted since the last commit). `file` may be repo-relative (plain files) OR an
+// absolute path (a plugin's record store returns absolute case paths) — both are normalised to a
+// repo-relative, forward-slashed spec so `git show HEAD:<rel>` and the disk read resolve. Both
+// best-effort — never throw.
+async function fileContents(root, file) {
+  const abs = resolve(root, file);
+  const rel = relative(root, abs).split(sep).join('/');
+  const head = await git(root, ['show', `HEAD:${rel}`]);
+  const base = head.ok ? head.out : '';
+  let work = '';
+  try { work = readFileSync(abs, 'utf8'); } catch { work = ''; }
+  return { base, work };
+}
+// The current branch name (or a short SHA when the HEAD is detached / on a fresh repo).
+async function gitBranch(root) {
+  const r = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const name = r.ok ? r.out.trim() : '';
+  if (name && name !== 'HEAD') return name;
+  const sha = await git(root, ['rev-parse', '--short', 'HEAD']);
+  return sha.ok && sha.out.trim() ? `detached @ ${sha.out.trim()}` : (name || 'no branch');
+}
+// Every path with uncommitted changes (staged + working-tree + untracked), project-root
+// relative (matching the Explorer's tree paths). `status` is the porcelain XY code, trimmed
+// (M/A/D/??/…). Confined to the repo the vault rides; empty on a clean tree or non-repo.
+// `--untracked-files=all` lists every new file individually — without it git collapses a
+// brand-new directory to just its name (e.g. a fresh case folder), so newly added records
+// never surface in the Explorer's diff mode.
+async function gitChanged(root) {
+  const r = await git(root, ['status', '--porcelain', '--no-renames', '--untracked-files=all', '-z']);
+  if (!r.ok) return [];
+  const out = [];
+  for (const entry of r.out.split('\0')) {
+    if (!entry) continue;
+    const status = entry.slice(0, 2).trim() || '?';
+    const path = entry.slice(3);
+    if (path) out.push({ path, status });
+  }
+  return out;
+}
+// Discard ALL uncommitted changes in one file (destructive): a tracked file is restored
+// from HEAD (staged + working tree); an untracked new file is deleted. `rel` is confined to
+// the vault by the caller. Returns { ok } — never throws.
+async function discardFile(root, rel) {
+  const tracked = (await git(root, ['ls-files', '--error-unmatch', '--', rel])).ok;
+  if (tracked) {
+    let r = await git(root, ['restore', '--staged', '--worktree', '--source=HEAD', '--', rel]);
+    if (!r.ok) r = await git(root, ['checkout', 'HEAD', '--', rel]);   // older git without `restore`
+    return { ok: r.ok, err: r.err };
+  }
+  try { rmSync(join(root, rel), { force: true }); return { ok: true }; }   // untracked → remove the new file
+  catch (e) { return { ok: false, err: e.message }; }
+}
+// The first `# ` heading text of a markdown file (its title) — read cheaply from the head
+// of the file. Used to make the Explorer search match a record's H1, not just its filename.
+// A tiny mtime-keyed read cache: recompute a per-file value (its H1, its `type:`) only when
+// the file actually changed on disk. Tree builds + comment batches hit the same files
+// repeatedly (every poll / FS event), so this turns "read every file every time" into a cheap
+// stat. Self-bounds by clearing when it grows large (a vault has few files; belt-and-suspenders).
+function cachedByMtime(cache, abs, compute) {
+  let mtimeMs;
+  try { mtimeMs = statSync(abs).mtimeMs; } catch { return compute(); }   // unstatable → best-effort compute
+  const hit = cache.get(abs);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.value;
+  const value = compute();
+  if (cache.size > 5000) cache.clear();
+  cache.set(abs, { mtimeMs, value });
+  return value;
+}
+const _h1Cache = new Map();
+const _typeCache = new Map();
+function fileH1(abs) {
+  return cachedByMtime(_h1Cache, abs, () => {
+    try {
+      const head = readFileSync(abs, 'utf8').slice(0, 4000);
+      const body = head.replace(/^---\n[\s\S]*?\n---\n?/, '');   // skip YAML frontmatter
+      const m = body.match(/^#\s+(.+?)\s*$/m);
+      return m ? m[1].trim() : '';
+    } catch { return ''; }
+  });
+}
+
+// ---- the comment bridge: in-record annotations + agent resolution ------------
+//
+// The workbench reader selects any span of ANY file in the project (a case's analysis.md,
+// a brief's brief.md, or any file) and leaves a comment — a question or a change request,
+// GitHub-PR-review style. Comments are persisted as durable OPEN entries in ONE
+// project-level file (`deliberate/comments.jsonl`), each carrying the annotated file's
+// path. The user then runs `/deliberate address` in their agent, which fetches the open
+// comments (batch, via `GET /api/address`), answers them in its own interface / edits the
+// referenced file, and resolves each (`POST /api/resolve`). Resolutions/deletions are
+// pushed to the browser over SSE (`GET /api/events`) so comments update live. All state is
+// the durable comments.jsonl the vault writes plus the live SSE set — no database.
+function makeBridge() {
+  return { sse: new Set(), treeCache: null, treeDirty: true, watcher: null, watchFails: 0, rewatch: null };
+}
+function sseBroadcast(bridge, obj) {
+  const line = `data: ${JSON.stringify(obj)}\n\n`;
+  for (const res of bridge.sse) { try { res.write(line); } catch { /* dropped client */ } }
+}
+// The frontmatter `type:` of a markdown file (cheap head read) — used to attach a kind's
+// per-type `addressing` guidance to its comments. Empty when absent/unreadable.
+function fileType(abs) {
+  return cachedByMtime(_typeCache, abs, () => {
+    try {
+      const head = readFileSync(abs, 'utf8').slice(0, 2000);
+      const fm = head.match(/^---\n([\s\S]*?)\n---/);
+      if (!fm) return '';
+      const m = fm[1].match(/^type:\s*(.+?)\s*$/m);
+      return m ? m[1].replace(/^["']|["']$/g, '').trim() : '';
+    } catch { return ''; }
+  });
+}
+// Every OPEN comment in the project, oldest first — the batch an agent drains when the user
+// runs the address skill. Each carries the `file` to edit and, when the file is a registered
+// document `type`, that kind's optional `addressing` guidance (host special treatment — e.g.
+// "keep the sibling one-pager consistent"). Generic files get none.
+function openComments(store, project) {
+  const pid = project.id;
+  const byType = new Map((E.KINDS || []).filter(k => k.addressing).map(k => [k.type, k.addressing]));
+  const noteFor = (rel) => {
+    if (!byType.size || !rel) return undefined;
+    const t = fileType(join(project.dir, rel));
+    return t ? byType.get(t) : undefined;
+  };
+  return store.allComments(pid)
+    .filter(c => c.status === 'open')
+    .map(c => { const o = { id: c.id, file: c.file, anchor: c.anchor, body: c.body, ts: c.ts }; const g = noteFor(c.file); if (g) o.addressing = g; return o; })
+    .sort((a, b) => (a.ts || 0) - (b.ts || 0));
+}
+
+// Accept the internal hash id (what the app passes) OR a per-project #num, so the
+// endpoints are also usable by hand (`?id=3`) and from tests.
+function resolveCaseId(store, pid, ref) {
+  if (ref == null) return null;
+  if (store.getCase(ref)) return String(ref);
+  const s = store.listCases(pid).find(x => String(x.num) === String(ref));
+  return s ? s.id : String(ref);
+}
+// Same, for briefs (project-scoped landscape reports): a hash id or a per-project #num.
+function resolveBriefId(store, pid, ref) {
+  if (ref == null) return null;
+  if (store.getBrief(ref)) return String(ref);
+  const b = store.listBriefs(pid).find(x => String(x.num) === String(ref));
+  return b ? b.id : String(ref);
+}
+// Same, for date-keyed product readouts.
+function resolveReadoutId(store, pid, ref) {
+  if (ref == null) return null;
+  if (store.getReadout(ref)) return String(ref);
+  return String(ref);
+}
+// Same, for matchups (single-competitor head-to-heads): a hash id or the competitor slug
+// (the folder name — a natural human handle, since matchups are keyed by rival, not date).
+function resolveMatchupId(store, pid, ref) {
+  if (ref == null) return null;
+  if (store.getMatchup(ref)) return String(ref);
+  const m = store.listMatchups(pid).find(x => String(x.slug) === String(ref));
+  return m ? m.id : String(ref);
+}
+
+// ---- the vault's markdown file tree (the sidebar's Explorer) ------------------
+// Walk the project's `deliberate/` folder into a tree of ONLY markdown files (and the
+// folders that contain them, transitively). Case records (`analysis.md`) and briefs
+// (`brief.md`) are tagged with their kind + id so the client routes a click to the
+// right tab and labels the leaf by metadata (case title / brief period) rather than the
+// bare filename; every other `.md` is a plain `file` the client opens read-only. Hidden
+// dirs (`.config`) are skipped. Paths are project-root-relative POSIX, matching the
+// comment store's `relFile` key.
+// The content root the tree walks. The host may confine it to a subfolder (Deliberate walks
+// `<repo>/deliberate`); a standalone/generic host serves the whole folder. `base` is the
+// relative prefix the paths start with (must match the store's relFile output). Default:
+// the project folder itself, with no prefix — a plain folder of Markdown.
+// Directories never shown in the Explorer tree: git internals and dependency trees. Hidden
+// CONTENT dirs (dot-dirs like `.github`, and the committed `.sonorance/` — which holds the
+// project's hand-editable `sources.md`) ARE shown, so machine state that carries user-facing
+// Markdown surfaces normally. (The FS watcher ignores a WIDER set — see WATCH_SKIP.)
+const TREE_SKIP = new Set(['.git', 'node_modules']);
+// Directories the FS watcher ignores. Broader than TREE_SKIP: `.sonorance/` churns constantly
+// (config + comments + editor state rewrites), and an unfiltered watch on it caused a
+// self-sustaining refresh loop that froze the UI — so it's shown in the tree but never watched.
+const WATCH_SKIP = new Set(['.git', '.sonorance', 'node_modules']);
+function contentRoot(project) {
+  const c = E.contentDir ? E.contentDir(project) : null;
+  return c && c.dir ? { dir: c.dir, base: c.base || '' } : { dir: project.dir, base: '' };
+}
+function buildTree(store, project) {
+  const pid = project.id;
+  const { dir: root, base } = contentRoot(project);
+  const caseByRel = new Map(), briefByRel = new Map(), readoutByRel = new Map(), matchupByRel = new Map();
+  for (const s of store.listCases(pid)) { const f = store.recordFile(s.id); const rel = f && store.relFile(pid, f); if (rel) caseByRel.set(rel, s.id); }
+  for (const b of store.listBriefs(pid)) { const f = store.briefFilePath(b.id); const rel = f && store.relFile(pid, f); if (rel) briefByRel.set(rel, b.id); }
+  for (const r of store.listReadouts(pid)) { const f = store.readoutFilePath(r.id); const rel = f && store.relFile(pid, f); if (rel) readoutByRel.set(rel, r.id); }
+  for (const m of store.listMatchups(pid)) { const f = store.matchupFilePath(m.id); const rel = f && store.relFile(pid, f); if (rel) matchupByRel.set(rel, m.id); }
+  const walk = (absDir, relDir) => {
+    let entries = [];
+    try { entries = readdirSync(absDir, { withFileTypes: true }); } catch { return []; }
+    const nodes = [];
+    for (const e of entries) {
+      // Hidden CONTENT folders (dot-dirs like `.github`, and the committed `.sonorance/` that
+      // holds `sources.md`) ARE shown; only git internals and dependency trees are skipped.
+      if (TREE_SKIP.has(e.name)) continue;
+      const abs = join(absDir, e.name);
+      const rel = relDir ? `${relDir}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        // A folder is shown ONLY if it lies on a path from the root to a Markdown file — i.e. it
+        // has at least one `.md` descendant. Fileless folders are pruned (they'd be dead ends in a
+        // Markdown workspace). Because `.md` leaves are the only files added and fileless dirs are
+        // dropped recursively, a non-empty `children` guarantees a Markdown descendant, so the
+        // presence check is just `children.length`.
+        const children = walk(abs, rel);
+        if (children.length) nodes.push({ name: e.name, path: rel, type: 'dir', children });
+      } else if (e.isFile() && /\.md$/i.test(e.name)) {
+        const kind = caseByRel.has(rel) ? 'case' : briefByRel.has(rel) ? 'brief' : readoutByRel.has(rel) ? 'readout' : matchupByRel.has(rel) ? 'matchup' : 'file';
+        const id = kind === 'case' ? caseByRel.get(rel) : kind === 'brief' ? briefByRel.get(rel) : kind === 'readout' ? readoutByRel.get(rel) : kind === 'matchup' ? matchupByRel.get(rel) : null;
+        // Carry the file's H1 (its title) so the Explorer search matches content, not just
+        // the filename/path (a record's analysis.md filename is never meaningful).
+        nodes.push({ name: e.name, path: rel, type: 'file', kind, id, h1: fileH1(abs) });
+      }
+    }
+    // Folders first, then files; each alphabetical.
+    nodes.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1));
+    return nodes;
+  };
+  return walk(root, base);
+}
+
+
+function buildRoutes(store, bridge) {
+  // Per-request project resolution: an explicit `?project=<slug>` (the URL's /p/<slug>) wins,
+  // so multiple projects can be open in separate browser tabs at once; absent/unknown falls
+  // back to the last-active project (the registry's `current`).
+  const cur = (b) => b?.project ? E.resolveProject(store, b.project) : E.currentProject(store);
+  // Mark a project last-active (so `/` and a fresh boot default there). Only WRITE actions call
+  // this — reads/polls must not, or two open tabs would fight over the pointer.
+  const touch = (p) => { try { if (p && p.id) E.setCurrentProject(store, p.id); } catch { /* best-effort */ } };
+  const moveTelemetryTo = (p) => {
+    // Drain with the OLD resource before changing vault identity/policy. Do not requeue a failed
+    // old-vault send into the new context; the local audit remains the durable record.
+    flushTelemetry({ requeue: false }).catch(() => {});
+    configureTelemetry({
+      surface: 'ui',
+      product: (E.KINDS && E.KINDS.length) ? 'deliberate' : 'sonorance',
+      version: APP_VERSION,
+      vaultDir: p?.dir || null,
+    });
+  };
+  return {
+    'GET /api/state': async (b) => {
+      const p = cur(b);
+      const isGit = await isGitRepo(p?.dir);
+      const cases = p ? store.listCases(p.id).map(s => ({
+        id: s.id, title: s.title, state: s.state, score: s.score,
+        updated_at: s.updated_at, last_stage_at: s.last_stage_at,
+      })) : [];
+      // Editor state (open tabs / active tab / Explorer) lives in `.sonorance/local/state.json` — the
+      // `readState` helper; `getConfig` is a fallback for an older host that predates the split.
+      const st = p ? readState(store, p.id) : {};
+      const briefs = p ? store.listBriefs(p.id).map(b => ({
+        id: b.id, period_start: b.period_start, period_end: b.period_end,
+        created_at: b.created_at, updated_at: b.updated_at,
+      })) : [];
+      const readouts = p ? store.listReadouts(p.id).map(r => ({
+        id: r.id, period_start: r.period_start, period_end: r.period_end,
+        created_at: r.created_at, updated_at: r.updated_at,
+      })) : [];
+      const matchups = p ? store.listMatchups(p.id).map(m => ({
+        id: m.id, competitor: m.competitor, slug: m.slug, as_of: m.as_of,
+        created_at: m.created_at, updated_at: m.updated_at,
+      })) : [];
+      return {
+        project: p ? { id: p.id, name: p.name, dir: p.dir } : null,
+        projects: store.listProjects().map(x => ({ id: x.id, name: x.name, dir: x.dir, exists: x.exists !== false })),
+        cases, briefs, readouts, matchups, isGit,
+        kinds: E.KINDS,                                  // the declarative document-kind registry (drives the inbox)
+        brand: SONORANCE,                                // app-owned identity + canonical hints (never per-vault)
+        version: APP_VERSION,                           // for the UI's stale-server (version-skew) check
+        telemetry: { enabled: telemetryMode() !== 'off' }, // drives the Settings privacy toggle
+        bridge: true,                                   // capability flag: this server has the comment bridge
+        tabs: Array.isArray(st.tabs) ? st.tabs : [],   // persisted open tabs (in state.json)
+        activeTab: st.activeTab || null,                 // persisted active tab {kind,id} — restored per project on switch
+        explorer: st.explorer || null,                   // persisted Explorer collapse/expand state {mode, ex[]}
+      };
+    },
+    // Switch which registered project the workbench is serving (project selector).
+    'POST /api/switch': (b) => {
+      const target = E.resolveProject(store, b.id);
+      if (target) {
+        E.setCurrentProject(store, target.id);
+        bridge.treeDirty = true; bridge.treeCache = null;        // new project → rebuild + re-arm the watcher
+        const np = E.currentProject(store);
+        if (np && bridge.rewatch) { try { bridge.rewatch(contentRoot(np).dir); } catch { /* polling covers it */ } }
+        moveTelemetryTo(np);
+        emit('vault.switched', {});
+      }
+      return { ok: !!target };
+    },
+    // Open a folder as a vault and switch to it. `dir` must be an existing folder; opening registers
+    // it (creating
+    // its `.sonorance/` marker) and makes it current. Only supported when the host engine
+    // exposes a registry (`openVaultFolder`); the single-project hosts return `unsupported`.
+    'POST /api/open': (b) => {
+      const dir = b && b.dir ? String(b.dir).trim() : '';
+      if (!dir) return { error: 'no folder given' };
+      if (typeof E.openVaultFolder !== 'function') return { error: 'unsupported' };
+      if (!existsSync(dir)) return { error: 'not found' };
+      let p; try { p = E.openVaultFolder(store, dir); } catch (e) { return { error: e.message }; }
+      if (!p) return { error: 'could not open folder' };
+      bridge.treeDirty = true; bridge.treeCache = null;
+      if (bridge.rewatch) { try { bridge.rewatch(contentRoot(p).dir); } catch { /* polling covers it */ } }
+      moveTelemetryTo(p);
+      emit('vault.switched', {});
+      return { ok: true, project: { id: p.id, name: p.name, dir: p.dir } };
+    },
+    // Browse the local filesystem for a folder to open as a vault — powers the "Open folder…"
+    // picker (a browser can't return an absolute path from a native dialog, so the local daemon
+    // lists directories and the UI drills in). Read-only, directories only (never file contents);
+    // hidden dot-folders are skipped. `path` defaults to the home directory. Symlinked folders
+    // are followed (statSync). This is a local daemon the user runs, with expected FS access.
+    'GET /api/browse': (b) => {
+      let dir;
+      try { dir = resolve(b && b.path ? String(b.path) : homedir()); } catch { dir = homedir(); }
+      let st; try { st = statSync(dir); } catch { return { error: 'not found' }; }
+      if (!st.isDirectory()) return { error: 'not a folder' };
+      let entries = [];
+      try {
+        entries = readdirSync(dir)
+          .filter(n => !n.startsWith('.'))
+          .map(n => join(dir, n))
+          .filter(p => { try { return statSync(p).isDirectory(); } catch { return false; } })   // follows symlinked dirs; skips unreadable
+          .map(p => ({ name: basename(p), path: p }))
+          .sort((a, c) => a.name.localeCompare(c.name, undefined, { numeric: true, sensitivity: 'base' }));
+      } catch { return { error: 'unreadable', path: dir }; }
+      const parent = dirname(dir);
+      return { path: dir, parent: parent !== dir ? parent : null, name: basename(dir) || dir, home: homedir(), entries };
+    },
+    // Forget a registered vault (the switcher's Remove for a missing folder). Never deletes the
+    // folder or its `.sonorance/` — only drops it from the registry. Host without a registry → no-op ok.
+    'POST /api/remove': (b) => {
+      if (typeof E.removeProject !== 'function') return { ok: false };
+      E.removeProject(store, b.id);
+      bridge.treeDirty = true; bridge.treeCache = null;
+      return { ok: true };
+    },
+    // Persist the set of open tabs (and which one is active) for the current project.
+    // Editor state lives in `.sonorance/local/state.json` (regenerable; not needed to open a vault),
+    // so switching projects restores that project's own tab set and last-active tab.
+    'POST /api/tabs': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      writeState(store, p.id, 'tabs', Array.isArray(b.tabs) ? b.tabs : []);
+      if ('active' in b) writeState(store, p.id, 'activeTab', b.active || null);
+      return { ok: true };
+    },
+    // Generic editor-state write: merge a `patch` object of key→value into the project's
+    // `.sonorance/local/state.json`. The client buffers rapid changes (e.g. Explorer collapse/expand)
+    // in memory and flushes them here periodically, so high-frequency UI state is persisted
+    // without a disk write per interaction. Each key is stored as-is.
+    'POST /api/config': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const patch = (b && b.patch && typeof b.patch === 'object' && !Array.isArray(b.patch)) ? b.patch : null;
+      if (!patch) return { error: 'no patch' };
+      writeStateMany(store, p.id, patch);
+      return { ok: true };
+    },
+    'GET /api/record': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const id = resolveCaseId(store, p.id, b.id);
+      const rec = store.readRecord(id);
+      if (!rec) return { error: 'unknown case' };
+      const pr = store.prototypeRef(id);
+      const proto = pr ? { exists: !!pr.exists, external: !!pr.external, url: pr.external ? pr.url : null } : null;
+      // Hand the client the project-root-relative file — the same key the comment store uses.
+      return { ...rec, file: store.relFile(p.id, rec.file) || rec.file, isGit: await isGitRepo(p.dir), proto };
+    },
+    'POST /api/record': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const ok = store.writeRecord(resolveCaseId(store, p.id, b.id), String(b.text ?? ''));
+      if (ok) touch(p);
+      return ok ? { ok: true, updated: Date.now() } : { error: 'unknown case' };
+    },
+    // A brief's raw record (read-only in the workbench). Briefs are project-scoped
+    // landscape reports, viewed like a case record but not edited through stages.
+    'GET /api/brief': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const id = resolveBriefId(store, p.id, b.id);
+      const rec = store.readBriefRecord(id);
+      if (!rec) return { error: 'unknown brief' };
+      return { ...rec, file: store.relFile(p.id, rec.file) || rec.file, isGit: await isGitRepo(p.dir) };
+    },
+    // A product readout's raw, read-only record.
+    'GET /api/readout': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const id = resolveReadoutId(store, p.id, b.id);
+      const rec = store.readReadoutRecord(id);
+      if (!rec) return { error: 'unknown readout' };
+      return { ...rec, file: store.relFile(p.id, rec.file) || rec.file, isGit: await isGitRepo(p.dir) };
+    },
+    // A matchup's raw record (read-only in the workbench). Matchups are project-scoped
+    // single-competitor head-to-heads, viewed like a brief but keyed by rival (refresh-in-place).
+    'GET /api/matchup': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const id = resolveMatchupId(store, p.id, b.id);
+      const rec = store.readMatchupRecord(id);
+      if (!rec) return { error: 'unknown matchup' };
+      return { ...rec, file: store.relFile(p.id, rec.file) || rec.file, isGit: await isGitRepo(p.dir) };
+    },
+    // The vault's markdown file tree — the sidebar Explorer's data source (full-tree view).
+    // `base` is the content root's project-relative prefix (empty for the generic app; e.g.
+    // `deliberate` for a host that confines content to a subfolder), so the UI's "New file"
+    // at the root creates inside the content root, not outside where the tree can't show it.
+    // Cached per project: rebuilt only when the FS watcher (or a structural write) marks it
+    // dirty, so the client's periodic poll is a cheap cache hit when nothing changed.
+    'GET /api/tree': (b) => {
+      const p = cur(b); if (!p) return { tree: [], base: '', inventory: { cases: 0, briefs: 0, readouts: 0, matchups: 0 } };
+      const c = bridge.treeCache;
+      if (c && c.pid === p.id && !bridge.treeDirty) return c.resp;
+      const resp = {
+        tree: buildTree(store, p),
+        base: contentRoot(p).base || '',
+        inventory: {
+          cases: store.listCases(p.id).length,
+          briefs: store.listBriefs(p.id).length,
+          readouts: store.listReadouts(p.id).length,
+          matchups: store.listMatchups(p.id).length,
+        },
+      };
+      bridge.treeCache = { pid: p.id, resp }; bridge.treeDirty = false;
+      return resp;
+    },
+    // Read a markdown file by its project-relative path. The path is normalized + confined
+    // to the folder via relFile; only `.md` is served. The generic app edits any markdown
+    // file this way; Deliberate opens context files (e.g. product.md) with it too.
+    'GET /api/file': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel || !/\.md$/i.test(rel)) return { error: 'bad path' };
+      let text = '';
+      try { text = readFileSync(join(p.dir, rel), 'utf8'); } catch { return { error: 'not found' }; }
+      return { path: rel, text, isGit: await isGitRepo(p.dir) };
+    },
+    // Write a markdown file by its project-relative path (the generic editor's save). Confined
+    // to the folder via relFile; only `.md` is writable. Autosaved from the live editor.
+    'POST /api/file': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel || !/\.md$/i.test(rel)) return { error: 'bad path' };
+      try { writeFileSync(join(p.dir, rel), String(b.text ?? '')); touch(p); return { ok: true, updated: Date.now() }; }
+      catch (e) { return { error: e.message }; }
+    },
+    // Create a NEW markdown file at a project-relative path (Explorer "New file"). Confined to
+    // the folder via relFile; only `.md`. Parent folders are created as needed. Never clobbers
+    // an existing file (`wx`) — creating over one returns `exists` so the UI can warn.
+    'POST /api/create': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel || !/\.md$/i.test(rel)) return { error: 'bad path' };
+      const abs = join(p.dir, rel);
+      if (existsSync(abs)) return { error: 'exists' };
+      try { mkdirSync(dirname(abs), { recursive: true }); writeFileSync(abs, String(b.text ?? ''), { flag: 'wx' }); }
+      catch (e) { return e.code === 'EEXIST' ? { error: 'exists' } : { error: e.message }; }
+      bridge.treeDirty = true;                                  // structural change → next /api/tree rebuilds now
+      touch(p);
+      info(`create: ${rel}`);
+      return { ok: true, path: rel };
+    },
+    // Remove a file OR a folder (recursively) from the Explorer — destructive (the UI confirms
+    // first). `path` is the project-relative file/folder; confined to the vault via relFile.
+    // Guarded so it can never target the vault root or the hidden `.sonorance/` state dir.
+    'DELETE /api/file': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel || rel === '.' || /(^|\/)\.[^/]/.test(rel)) return { error: 'bad path' };
+      const abs = join(p.dir, rel);
+      try {
+        if (!existsSync(abs)) return { error: 'not found' };
+        rmSync(abs, { recursive: statSync(abs).isDirectory(), force: true });
+      } catch (e) { return { error: e.message }; }
+      bridge.treeDirty = true;                                  // structural change → rebuild the tree next fetch
+      touch(p);
+      info(`delete: ${rel}`);
+      return { ok: true, path: rel };
+    },
+    // Create a new (empty) folder at a project-relative path (Explorer "New folder"). Confined to
+    // the vault via relFile; can't target the root or a hidden machine dir. `recursive` so nested
+    // paths work; never clobbers an existing entry.
+    'POST /api/mkdir': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel || rel === '.' || /(^|\/)\.[^/]/.test(rel)) return { error: 'bad path' };
+      const abs = join(p.dir, rel);
+      if (existsSync(abs)) return { error: 'exists' };
+      try { mkdirSync(abs, { recursive: true }); } catch (e) { return { error: e.message }; }
+      bridge.treeDirty = true; touch(p);
+      info(`mkdir: ${rel}`);
+      return { ok: true, path: rel };
+    },
+    // Move a file OR a folder (with its whole subtree) into another folder — or the vault root
+    // (`dest: ''`). Both ends are confined to the vault via relFile. Guards: can't move a folder
+    // into itself or its own subtree, can't clobber an existing entry, no hidden machine dirs.
+    // Returns the new project-relative path so the UI can re-point open tabs.
+    'POST /api/move': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const srcRel = store.relFile(p.id, b.src || '');
+      if (!srcRel || srcRel === '.' || /(^|\/)\.[^/]/.test(srcRel)) return { error: 'bad path' };
+      const destDirRel = (b.dest == null || b.dest === '') ? '' : store.relFile(p.id, b.dest);
+      if (destDirRel == null || /(^|\/)\.[^/]/.test(destDirRel)) return { error: 'bad path' };
+      const baseName = srcRel.split('/').pop();
+      const targetRel = destDirRel ? `${destDirRel}/${baseName}` : baseName;
+      if (targetRel === srcRel) return { ok: true, path: srcRel };            // already there → no-op
+      if (targetRel === srcRel || targetRel.startsWith(srcRel + '/')) return { error: 'into-self' };
+      const srcAbs = join(p.dir, srcRel), destAbs = join(p.dir, targetRel);
+      if (!existsSync(srcAbs)) return { error: 'not found' };
+      if (existsSync(destAbs)) return { error: 'exists' };
+      try { mkdirSync(dirname(destAbs), { recursive: true }); renameSync(srcAbs, destAbs); }
+      catch (e) { return { error: e.message }; }
+      bridge.treeDirty = true; touch(p);
+      info(`move: ${srcRel} → ${targetRel}`);
+      return { ok: true, from: srcRel, path: targetRel };
+    },
+    // Rename a file or folder in place (same parent dir, new basename) — the Explorer's "Rename…".
+    // `name` is a bare basename (no slashes): renaming never moves the entry between folders. A
+    // file keeps its extension when the new name omits one (so `notes.md` → `ideas` stays `.md`
+    // and doesn't vanish from the markdown tree); folders take the name verbatim.
+    'POST /api/rename': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const srcRel = store.relFile(p.id, b.path || '');
+      if (!srcRel || srcRel === '.' || /(^|\/)\.[^/]/.test(srcRel)) return { error: 'bad path' };
+      let name = String(b.name || '').trim();
+      if (!name || name === '.' || name === '..' || /[/\\]/.test(name) || name.startsWith('.')) return { error: 'bad name' };
+      const srcAbs = join(p.dir, srcRel);
+      if (!existsSync(srcAbs)) return { error: 'not found' };
+      if (!statSync(srcAbs).isDirectory()) { const ext = extname(srcRel); if (ext && !extname(name)) name += ext; }
+      const parent = srcRel.includes('/') ? srcRel.slice(0, srcRel.lastIndexOf('/')) : '';
+      const targetRel = parent ? `${parent}/${name}` : name;
+      if (targetRel === srcRel) return { ok: true, from: srcRel, path: srcRel };            // unchanged → no-op
+      const destAbs = join(p.dir, targetRel);
+      if (existsSync(destAbs)) return { error: 'exists' };
+      try { renameSync(srcAbs, destAbs); }
+      catch (e) { return { error: e.message }; }
+      bridge.treeDirty = true; touch(p);
+      info(`rename: ${srcRel} → ${targetRel}`);
+      return { ok: true, from: srcRel, path: targetRel };
+    },
+    'GET /api/diff': async (b) => {
+      const p = cur(b); if (!p) return { isGit: false, diff: '' };
+      const isGit = await isGitRepo(p.dir);
+      if (!isGit) return { isGit: false, diff: '' };
+      // Diff any file by its project-relative path (Explorer diff mode), else a case's record by id.
+      const file = b.path ? store.relFile(p.id, b.path) : store.recordFile(resolveCaseId(store, p.id, b.id));
+      if (!file) return { isGit, tracked: false, diff: '' };
+      return { isGit, ...(await fileDiff(p.dir, file)), ...(await fileContents(p.dir, file)) };
+    },
+    // Git status for the Explorer's diff mode: the current branch + every path with
+    // uncommitted changes (staged/working/untracked), project-root relative.
+    'GET /api/git': async (b) => {
+      const p = cur(b); if (!p) return { isGit: false, branch: '', changed: [] };
+      const isGit = await isGitRepo(p.dir);
+      if (!isGit) return { isGit: false, branch: '', changed: [] };
+      return { isGit, branch: await gitBranch(p.dir), changed: await gitChanged(p.dir) };
+    },
+    // Discard ALL uncommitted changes in one file (destructive — the UI confirms first):
+    // a tracked file is restored from HEAD, an untracked new file is deleted. `path` is the
+    // project-relative file; it's confined to the vault via relFile before touching disk.
+    'POST /api/discard': async (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      if (!(await isGitRepo(p.dir))) return { error: 'not a git repo' };
+      const rel = store.relFile(p.id, b.path || '');
+      if (!rel) return { error: 'bad path' };
+      const r = await discardFile(p.dir, rel);
+      if (!r.ok) return { error: r.err || 'discard failed' };
+      bridge.treeDirty = true;                                  // a discard can add/remove a file → refresh the tree
+      touch(p);
+      info(`discard: ${rel}`);
+      return { ok: true, path: rel };
+    },
+
+    // ---- the comment bridge (in-record annotations) ----------------------------
+    // The reader's selection + comment on a file. Persist a durable OPEN comment (the
+    // source of truth) and push it to any open browsers over SSE. `file` is the annotated
+    // file's path (the UI passes the record's file); it's stored project-root-relative.
+    'POST /api/comment': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const file = String(b.file ?? '');
+      if (!file) return { error: 'no file' };
+      const anchor = { quote: String(b.quote ?? b.anchor?.quote ?? '').slice(0, 2000), heading: String(b.heading ?? b.anchor?.heading ?? '') };
+      const line = Number(b.line ?? b.anchor?.line);
+      const endLine = Number(b.endLine ?? b.anchor?.endLine);
+      // Source-LINE-RANGE anchor (robust to duplicate headings / edited-away quote text). The quote
+      // is kept only as a secondary hint for precise inline highlighting.
+      if (Number.isInteger(line) && line >= 0){ anchor.line = line; anchor.endLine = Number.isInteger(endLine) && endLine >= line ? endLine : line; }
+      const body = String(b.body ?? b.message ?? '').slice(0, 4000);
+      if (!body.trim()) return { error: 'empty comment' };
+      const comment = store.addComment(p.id, file, { anchor, body, author: 'user' });
+      if (!comment) return { error: 'invalid file' };    // escaped the project, or unresolvable
+      sseBroadcast(bridge, { type: 'comment', file: comment.file, comment });
+      info(`comment: ${comment.file} comment ${comment.id}`);
+      emit('comment.created', {});
+      return { ok: true, commentId: comment.id, file: comment.file };
+    },
+    // Every OPEN comment across the project — the batch the agent drains on
+    // `/deliberate address`. Announces to browsers that an agent is working (a transient
+    // "addressing" indicator) so the user sees their comments are being acted on.
+    'GET /api/address': (b) => {
+      const p = cur(b); if (!p) return { comments: [], count: 0 };
+      const comments = openComments(store, p);
+      // Announce the agent is working — but at most once per 10s, so repeated drains/polls don't
+      // spam the browser's transient "addressing" toast.
+      if (comments.length) {
+        const now = Date.now();
+        if (now - (bridge.lastAddressing || 0) > 10_000) { bridge.lastAddressing = now; sseBroadcast(bridge, { type: 'addressing' }); emit('address.drained', { count: comments.length }); }
+      }
+      return { comments, count: comments.length };
+    },
+    // The agent marks a comment resolved (optionally noting what it did / that it edited
+    // the file). Persist it and push the resolution so the browser drops the comment.
+    'POST /api/resolve': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const commentId = String(b.commentId ?? b.id ?? '');
+      const patch = { status: 'resolved', revised: !!b.revised, session: b.session || 'agent', resolved_at: Date.now() };
+      if (b.note != null) patch.note = String(b.note).slice(0, 4000);
+      const hit = store.resolveComment(p.id, commentId, patch);
+      if (!hit) return { error: 'unknown comment' };
+      sseBroadcast(bridge, { type: 'resolve', file: hit.file, commentId, revised: patch.revised });
+      emit('comment.resolved', { revised: patch.revised });
+      return { ok: true };
+    },
+    // Every persisted comment for a file (the browser loads these when a record opens
+    // and renders the OPEN ones inline).
+    'GET /api/comments': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      return { comments: store.comments(p.id, String(b.file ?? '')) };
+    },
+    // Per-file OPEN comment counts across the whole project (read-only; NO addressing
+    // side-effect, unlike /api/address). Drives the Explorer's comment filter + the per-file
+    // and per-folder comment markers. `file` keys are project-root-relative (match the tree).
+    'GET /api/comments-summary': (b) => {
+      const p = cur(b); if (!p) return { counts: {}, total: 0 };
+      const counts = {};
+      for (const c of store.allComments(p.id)) { if (c.status === 'open' && c.file) counts[c.file] = (counts[c.file] || 0) + 1; }
+      return { counts, total: Object.values(counts).reduce((a, n) => a + n, 0) };
+    },
+    // The reader edits their own comment's text (a patch that keeps status/anchor). Broadcasts a
+    // `comment` update so open browsers reflect the new body.
+    'POST /api/comment-edit': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const commentId = String(b.commentId ?? b.id ?? '');
+      const body = String(b.body ?? '').slice(0, 4000);
+      if (!body.trim()) return { error: 'empty comment' };
+      const hit = store.resolveComment(p.id, commentId, { body });   // generic patch (body only — status/anchor unchanged)
+      if (!hit) return { error: 'unknown comment' };
+      sseBroadcast(bridge, { type: 'comment', file: hit.file, comment: hit });
+      return { ok: true, comment: hit };
+    },
+    // The reader deletes their own comment (distinct from the agent resolving it): remove
+    // it from the record and push the deletion so it drops from every open browser.
+    'DELETE /api/comment': (b) => {
+      const p = cur(b); if (!p) return { error: 'no project' };
+      const commentId = String(b.commentId ?? b.comment ?? '');
+      const hit = store.deleteComment(p.id, commentId);
+      if (!hit) return { error: 'unknown comment' };
+      sseBroadcast(bridge, { type: 'delete', file: hit.file, commentId });
+      return { ok: true };
+    },
+
+    // ---- telemetry + feedback (content-free product analytics; OTLP under the hood) ------------
+    // The UI's telemetry sink. The browser can't reach the OTLP endpoint (no direct network, no
+    // secrets), so it batches its content-free events + aggregate rollups and POSTs them here; the
+    // server re-emits each already-bounded browser batch through an isolated client scoped to the
+    // request's vault, so concurrent project tabs cannot share identity, policy, or retry state.
+    'POST /api/telemetry': async (b) => {
+      const p = cur(b);
+      await submitTelemetryBatch({
+        events: Array.isArray(b.events) ? b.events.slice(0, 100) : [],
+        counters: (b.counters && typeof b.counters === 'object') ? b.counters : {},
+        gauges: (b.gauges && typeof b.gauges === 'object') ? b.gauges : {},
+        histograms: (b.histograms && typeof b.histograms === 'object') ? b.histograms : {},
+      }, {
+        surface: 'ui',
+        product: (E.KINDS && E.KINDS.length) ? 'deliberate' : 'sonorance',
+        version: APP_VERSION,
+        vaultDir: p?.dir || null,
+      });
+      return { ok: true };
+    },
+    // Explicit, user-authored feedback from the UI panel. Always accepted (independent of the
+    // telemetry switch): it is a deliberate submission, mirrored locally first, then sent as an
+    // OTLP log record carrying only the fields the user typed (bug diagnostics are scrubbed).
+    'POST /api/feedback': async (b) => {
+      const product = (E.KINDS && E.KINDS.length) ? 'deliberate' : 'sonorance';
+      const p = cur(b);
+      try {
+        const r = await submitFeedback(b || {}, { surface: 'ui', product, version: APP_VERSION, vaultDir: p?.dir });
+        return { ok: true, id: r.id, needs_framing: r.needs_framing };
+      } catch (e) { return { error: e.message }; }
+    },
+    // The UI Settings toggle writes the opt-out choice here, so the CLI
+    // and UI resolve the SAME ~/.sonorance consent. Re-resolves the running client immediately.
+    'POST /api/consent': (b) => {
+      const enabled = !!(b && (b.enabled === true || b.enabled === 'true' || b.enabled === 1 || b.enabled === '1'));
+      const was = telemetryMode() !== 'off';
+      if (enabled && !was) { setConsent(true); refreshTelemetry(); emit('telemetry.enabled', {}); }
+      else if (!enabled && was) { emit('telemetry.disabled', {}); setConsent(false); refreshTelemetry(); }
+      else setConsent(enabled);
+      return { ok: true, enabled: telemetryMode() !== 'off' };
+    },
+  };
+}
+
+const manifestJson = () => {
+  const name = SONORANCE.name;
+  return JSON.stringify({
+    name, short_name: name, display: 'standalone',
+    background_color: '#0d0b09', theme_color: '#0d0b09', start_url: '/',
+    icons: [{ src: '/icon.png', sizes: '512x512', type: 'image/png' }],
+  });
+};
+
+/**
+ * startServer — boot the local app daemon.
+ * @param {object}  o
+ * @param {object}  o.engine  REQUIRED host injection: { openVault, currentProject,
+ *   setCurrentProject, resolveProject, KINDS,
+ *   info, error, installCrashHandlers } — the app imports no product engine itself.
+ * @param {number}  [o.port]  TCP port; 0 lets the OS pick a free one. Env: DELIBERATE_PORT.
+ * @param {boolean} [o.unref] detach the socket from the event loop (tests).
+ * @returns {Promise<{ server, port, store }>}
+ */
+export async function startServer({ engine, port = process.env.DELIBERATE_PORT || 7777, unref } = {}) {
+  if (!engine || typeof engine.openVault !== 'function')
+    throw new Error('app startServer: an `engine` must be injected by the host (e.g. the deliberate package).');
+  E = engine;
+  if (typeof E.info === 'function') info = E.info;
+  if (typeof E.error === 'function') error = E.error;
+  E.installCrashHandlers?.();
+  const store = E.openVault();
+  const bridge = makeBridge();
+  const routes = buildRoutes(store, bridge);
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://x');
+    const base = '/' + url.pathname.split('/').filter(Boolean).slice(0, 2).join('/');
+    const route = routes[`${req.method} ${base}`];
+    if (route) {
+      try { const body = { ...(await readBody(req)), ...Object.fromEntries(url.searchParams) }; return json(res, 200, await route(body) || {}); }
+      catch (e) { error(`${req.method} ${url.pathname}`, e); return json(res, 500, { error: e.message }); }
+    }
+    // SSE: server→browser push for the comment bridge (comment created, comment
+    // resolved, agent addressing). Kept open; a comment heartbeat prevents idle drops.
+    if (req.method === 'GET' && url.pathname === '/api/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive', 'x-accel-buffering': 'no' });
+      res.write(': ok\n\n');
+      bridge.sse.add(res);
+      const hb = setInterval(() => { try { res.write(': hb\n\n'); } catch { /* ignore */ } }, 30_000); hb.unref?.();
+      req.on('close', () => { clearInterval(hb); bridge.sse.delete(res); });
+      return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/proto') {
+      const ps = url.searchParams.get('project');
+      const p = (ps && E.resolveProject(store, ps)) || E.currentProject(store);
+      const id = p ? resolveCaseId(store, p.id, url.searchParams.get('id')) : null;
+      // Optional surface (a primary-surface slug) selects `prototype/<surface>/index.html`;
+      // sanitized to a slug so it can never escape the case's prototype folder.
+      const surface = (url.searchParams.get('surface') || '').toLowerCase().replace(/[^a-z0-9-]/g, '');
+      const pr = id ? store.prototypeRef(id, surface) : null;
+      if (pr && pr.external) { res.writeHead(302, { location: pr.url }); return res.end(); }
+      if (!pr || !pr.exists) { res.writeHead(404, { 'content-type': 'text/plain' }); return res.end('No prototype for this case yet.'); }
+      try { const html = await readFile(pr.path); res.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' }); return res.end(html); }
+      catch { res.writeHead(404); return res.end('no prototype'); }
+    }
+    if (req.method === 'GET' && url.pathname === '/api/asset') {
+      // Serve a Markdown image referenced from a record/file. `path` is project-relative and
+      // confined to the vault via relFile (no `..` escape); only known image types are served,
+      // read straight off disk so images work offline with no external fetch.
+      const ps = url.searchParams.get('project');
+      const p = (ps && E.resolveProject(store, ps)) || E.currentProject(store);
+      const rel = p ? store.relFile(p.id, url.searchParams.get('path') || '') : null;
+      if (!p || !rel) { res.writeHead(404, { 'content-type': 'text/plain' }); return res.end('no asset'); }
+      const type = IMG_TYPES[extname(rel).toLowerCase()];
+      if (!type) { res.writeHead(415, { 'content-type': 'text/plain' }); return res.end('unsupported asset type'); }
+      try { const buf = await readFile(join(p.dir, rel)); res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' }); return res.end(buf); }
+      catch { res.writeHead(404, { 'content-type': 'text/plain' }); return res.end('not found'); }
+    }
+    if (req.method === 'GET' && url.pathname === '/manifest.webmanifest') { res.writeHead(200, { 'content-type': 'application/manifest+json' }); return res.end(manifestJson()); }
+    if (req.method === 'GET' && url.pathname === '/icon.png') {
+      try { const png = await readFile(join(here, '../../build/icon.png')); res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'max-age=86400' }); return res.end(png); }
+      catch { res.writeHead(404); return res.end('no icon'); }
+    }
+    if (req.method === 'GET' && !url.pathname.startsWith('/api')) { res.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' }); return res.end(await readFile(join(here, '../ui/index.html'))); }
+    res.writeHead(404); res.end('not found');
+  });
+  const boundPort = await new Promise((resolve) => server.listen(port, () => resolve(server.address().port)));
+  if (unref || process.env.DELIBERATE_TEST) server.unref();
+  // Serving a folder initiates the project there (it creates `.sonorance/`), so keep that
+  // machine state out of git the moment we boot — same as `init` does. Only touches an existing
+  // .gitignore; idempotent. Entries are host-supplied (generic: `.sonorance/`; Deliberate adds
+  // any hidden `deliberate/` subfolder).
+  const project = E.currentProject(store) || store.getProject?.();
+  try { if (project?.dir) ensureGitignore(project.dir, E.gitignoreEntries?.(project) ?? []); } catch { /* non-fatal */ }
+  // Telemetry: the server IS the `ui` surface. Configure the shared client with this vault (so the
+  // committed team kill-switch + project_key resolve) and the product flavor (deliberate when the
+  // injected engine ships document kinds; the generic editor is plain sonorance). Content-free;
+  // never blocks a request. Emitting is a no-op when the user has opted out (mode 'off').
+  try {
+    const product = (E.KINDS && E.KINDS.length) ? 'deliberate' : 'sonorance';
+    const freshInstall = ensureInstallId().fresh;          // capture BEFORE configure (which mints the id)
+    configureTelemetry({ surface: 'ui', product, version: APP_VERSION, vaultDir: project?.dir || null });
+    if (freshInstall) emit('install.created', {});
+    emit('session.start', {});
+    emit('serve.started', {});
+  } catch { /* telemetry must never break serve */ }
+  // Watch the vault's content root and push an `fs` event to open browsers whenever files
+  // appear/disappear/change on disk, so the Explorer's file tree + git diff mode auto-refresh
+  // (a new case folder shows up; a deleted file drops out) without a manual reload, and mark the
+  // server-side tree cache dirty. The watcher FOLLOWS the current project (re-armed on switch),
+  // SELF-HEALS on error (bounded retries), and is best-effort — an unsupported platform simply
+  // falls back to the client's polling. Coalesced (250ms) so a burst of writes is one refresh;
+  // unref'd so it never keeps the process (or a test) alive.
+  const watchRoot = (root) => {
+    try { bridge.watcher?.close(); } catch { /* ignore */ }
+    bridge.watcher = null;
+    if (!root || !existsSync(root)) return;
+    let fsTimer = null;
+    const onChange = (_evt, filename) => {
+      // Ignore VCS/app-state churn (`.git/` index refreshes, the app's own `.sonorance/`
+      // config+comments, `node_modules/`) — the WATCH_SKIP set (wider than TREE_SKIP: `.sonorance/`
+      // is shown in the tree but never watched). These are not content, and watching them caused a
+      // self-sustaining refresh loop: the client's periodic refresh runs `git status`, which
+      // rewrites `.git/index`; an unfiltered watcher fired `fs` → the client refetched tree + ran
+      // `git status` again → … ~2.5×/s forever, which froze the UI.
+      if (filename && String(filename).split(/[\\/]/).some(seg => WATCH_SKIP.has(seg))) return;
+      bridge.watchFails = 0;                                   // a live event → the watcher is healthy
+      if (fsTimer) return;
+      fsTimer = setTimeout(() => { fsTimer = null; bridge.treeDirty = true; sseBroadcast(bridge, { type: 'fs' }); }, 250);
+      fsTimer.unref?.();
+    };
+    try {
+      const w = watch(root, { recursive: true }, onChange);
+      w.unref?.();
+      w.on('error', () => {
+        try { w.close(); } catch { /* ignore */ }
+        // Only the CURRENT watcher re-arms. An already-replaced (orphaned) watcher that emits a
+        // late error must NOT schedule a rewatch — that would tear down the healthy live watcher
+        // and spawn another, and repeated orphan errors could thrash/accumulate watchers.
+        if (bridge.watcher !== w) return;
+        bridge.watcher = null;
+        if ((bridge.watchFails = (bridge.watchFails || 0) + 1) <= 5) { const t = setTimeout(() => watchRoot(root), 1000); t.unref?.(); }
+      });
+      bridge.watcher = w;
+    } catch { /* unsupported → client polling covers it */ }
+  };
+  bridge.rewatch = watchRoot;                                  // /api/switch re-arms it for the new project
+  bridge.treeDirty = true;                                     // force a fresh build on the first /api/tree
+  try { watchRoot(contentRoot(project).dir); } catch { /* non-fatal: client polling is the fallback */ }
+  // Record where we're listening so the CLI's `address`/`resolve` clients reach THIS server
+  // (via the engine-provided discovery path). Cleared best-effort on exit.
+  const info_path = E.serveInfoPath?.(project);
+  if (info_path) {
+    try {
+      mkdirSync(dirname(info_path), { recursive: true });
+      writeFileSync(info_path, JSON.stringify({ port: boundPort, pid: process.pid, ts: Date.now() }));
+      const cleanup = () => { try { const cur = JSON.parse(readFileSync(info_path, 'utf8')); if (cur.pid === process.pid) rmSync(info_path, { force: true }); } catch { /* ignore */ } };
+      process.on('exit', cleanup);
+      bridge.cleanup = cleanup;
+    } catch { /* non-fatal */ }
+  }
+  // One place to tear down on a signal: drop the serve pointer AND flush telemetry (a final,
+  // time-boxed OTLP send of the session's remaining events/rollups) before exiting. Best-effort;
+  // the local JSONL is the durable record if the flush can't complete in time.
+  const onSignal = async () => {
+    try { bridge.cleanup?.(); } catch { /* ignore */ }
+    try { await shutdownTelemetry(); } catch { /* ignore */ }
+    process.exit(0);
+  };
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  info(`${SONORANCE.name} → http://localhost:${boundPort}`);
+  return { server, port: boundPort, store };
+}
+
+// This is a LIBRARY: the host (the `deliberate` package) imports `startServer` and injects
+// its engine. There is no run-directly path — `node src/server/index.mjs` has no engine to
+// inject, so it intentionally does nothing.