create-pmos 0.5.0 → 0.6.0

package/workspace/server.js

@@ -0,0 +1,1753 @@
+#!/usr/bin/env node
+/*
+ * PMOS Terminal Workspace — session server (D62 as ratified/amended).
+ *
+ * A persistent, LOCAL, headless server that owns real PTYs for the PM's agent CLIs.
+ * Clients (the GUI, later a native TUI, a phone) ATTACH over WebSocket; close a client
+ * and the sessions keep running — re-attach replays scrollback and resumes live (R7).
+ * Binds localhost only: the D62 hosted-PTY-bridge rejection stands — never public.
+ *
+ * The server hosts MANY workspaces (repo roots), not one: `pmos` in any repository
+ * registers that repository and the client switches to it. Sessions, the library and
+ * every path guard are scoped to the workspace they belong to — workspace A can never
+ * read workspace B's files (workspace-multi-repo-library R1/R3).
+ *
+ * The agent harness runs UNTOUCHED inside the PTY (Claude Code / Codex / a shell): this
+ * server is the terminal on the other end, not a wrapper. Subscription login, slash
+ * commands, keybindings — all the CLI's own.
+ *
+ * No dependency on the hosted backend. Gate actions write the file-mode PMOS vocabulary
+ * under state/ (the reconcile seam). Request headers are never logged (D08).
+ */
+'use strict';
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile, spawnSync } = require('child_process');
+const { WebSocketServer } = require('ws');
+
+// node-pty is a NATIVE module; a broken/mismatched build is the #1 field failure
+// (posix_spawnp failed on macOS = wrong-arch binary). Fail with the fix, not a stack.
+let pty;
+try {
+  pty = require('node-pty');
+} catch (e) {
+  console.error('✗ node-pty failed to load — the native module is missing or built for the wrong platform.');
+  console.error(`  ${e.message.split('\n')[0]}`);
+  console.error('  Fix:  npm run doctor        (diagnoses arch/toolchain)');
+  console.error('        npm rebuild node-pty --build-from-source');
+  process.exit(1);
+}
+
+const { checkSurface } = require('./lib/surface-contract');
+const scheduleLogic = require('./lib/schedule-logic');
+const harness = require('./lib/harness-parse');
+const transcript = require('./lib/transcript-read');
+const skillStore = require('./lib/skill-store');
+const remoteAccess = require('./lib/remote-access');   // tailnet bind + token guard (D62) + origin/host allowlist (D64)
+const rateLimit = require('./lib/rate-limit');         // per-connection token bucket for spawn/input (D64 A3)
+const consoleState = require('./lib/console-state');   // read-only console surfaces over file-mode state (D64 B)
+const fmParse = require('./lib/file-mode-parse');      // canonical file-mode parsers, shared with metrics.py (D64 D)
+const SELF_ROOT = path.resolve(__dirname, '..');       // the repo the workspace ships inside
+const PUB = path.join(__dirname, 'public');
+const XROOT = path.join(__dirname, 'node_modules', '@xterm');
+const STATE = path.join(__dirname, 'state');
+const SESS_DIR = path.join(STATE, 'sessions');
+const WS_FILE = path.join(STATE, 'workspaces.json');
+const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
+const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
+// Bind + token policy (D62). DEFAULT = loopback only, no token (unchanged). The opt-in remote flag
+// (PMOS_REMOTE=tailnet / PMOS_BIND_TAILNET=1) adds the machine's OWN tailnet IPv4 (100.64.0.0/10)
+// and requires a bearer token on every non-loopback peer. Any non-loopback, non-tailnet bind is
+// REFUSED (BIND.refused) so the server exits — there is no code path to a public interface.
+const BIND = remoteAccess.resolveBinds({ env: process.env });
+const TOKEN = BIND.token || null;                     // non-loopback peers must present it; never logged (D08)
+// Per-OS default shell. On Windows there is no `bash` — use ComSpec/PowerShell.
+function defaultShell() {
+  if (process.platform === 'win32') return process.env.COMSPEC || 'powershell.exe';
+  return process.env.SHELL || 'bash';
+}
+const SHELL = defaultShell();
+
+// The environment a spawned SESSION gets. The workspace server is long-lived and independent;
+// a `claude` (or `codex`, or shell) started inside it is a fresh TOP-LEVEL session, not a child
+// of whatever launched the server. But the server inherits its launcher's environment — and if
+// that launcher was itself a Claude Code session (e.g. `pmos` was run from inside one), the
+// CLAUDE_CODE_* markers leak through into every session we spawn, so the agent CLI sees a
+// "child session" marker and disables its own transcript saving. Strip those markers here: the
+// harness inside the PTY must run as though the PM launched it directly. Login/subscription do
+// NOT live in these vars (they're in the CLI's own config/keychain), so this never affects auth.
+const INHERITED_SESSION_MARKERS = [
+  'CLAUDECODE', 'CLAUDE_CODE_CHILD_SESSION', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_EXECPATH', 'CLAUDE_PID', 'AI_AGENT', 'CLAUDE_EFFORT',
+];
+function sessionEnv() {
+  const env = { ...process.env };
+  for (const k of INHERITED_SESSION_MARKERS) delete env[k];
+  // also drop any other CLAUDE_CODE_* the CLI adds to mark a nested run
+  for (const k of Object.keys(env)) if (/^CLAUDE_CODE_/.test(k)) delete env[k];
+  return env;
+}
+const SCROLLBACK = 200_000;                            // bytes of ring buffer per session
+
+fs.mkdirSync(SESS_DIR, { recursive: true });
+
+function nowISO() { return new Date(Date.now()).toISOString(); }
+
+// D64 (Track A2): record-of-truth writes must FAIL LOUDLY, never swallow. This surfaces a visible
+// server error (no header/secret content, D08) rather than a silent `catch {}` that lets a green
+// click sit over an empty record. The Acceptance-Gate append at /api/gate goes further and returns
+// an HTTP 500 to the caller; these secondary writes at least never fail in silence.
+function warnWriteFail(what, e) {
+  const msg = String((e && e.message) || e || 'unknown error').split('\n')[0].slice(0, 160);
+  try { console.error(`✗ file-mode write failed: ${what} — ${msg}`); } catch {}
+}
+
+// ── Workspaces: the registry of repo roots this server hosts. ─────────────────────────
+// One server, many repos. The id is derived from the absolute path, so registering the
+// same directory twice is idempotent — `pmos` can be run in a repo any number of times.
+/** @type {Map<string,{id,name,root,addedAt}>} */
+const workspaces = new Map();
+
+function wsId(root) { return crypto.createHash('sha1').update(path.resolve(root)).digest('hex').slice(0, 10); }
+function saveWorkspaces() {
+  try { fs.writeFileSync(WS_FILE, JSON.stringify([...workspaces.values()], null, 2)); }
+  catch (e) { warnWriteFail('workspaces.json (the workspace registry)', e); }
+}
+function loadWorkspaces() {
+  let list = [];
+  try { list = JSON.parse(fs.readFileSync(WS_FILE, 'utf8')); } catch {}
+  if (Array.isArray(list)) {
+    for (const w of list) {
+      if (!w || !w.root) continue;
+      const root = path.resolve(w.root);
+      if (!isDir(root)) continue;                       // a moved/deleted repo drops out quietly
+      workspaces.set(wsId(root), { id: wsId(root), name: w.name || path.basename(root), root, addedAt: w.addedAt || nowISO() });
+    }
+  }
+}
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+function registerWorkspace(root, name) {
+  if (!root) return null;
+  const abs = path.resolve(root);
+  if (!isDir(abs)) return null;
+  const id = wsId(abs);
+  const existing = workspaces.get(id);
+  if (existing) {
+    if (name && name !== existing.name) { existing.name = name; saveWorkspaces(); pushWorkspaces(); }
+    return existing;
+  }
+  const w = { id, name: name || path.basename(abs) || abs, root: abs, addedAt: nowISO() };
+  workspaces.set(id, w);
+  saveWorkspaces(); pushWorkspaces();
+  return w;
+}
+// Forgetting a workspace never touches the repo — it only stops hosting it here. Blocked
+// while it still owns sessions, so scrollback is never orphaned by a click.
+function forgetWorkspace(id) {
+  const w = workspaces.get(id);
+  if (!w || w.root === SELF_ROOT) return false;
+  if ([...sessions.values()].some((s) => s.ws === id)) return false;
+  workspaces.delete(id); saveWorkspaces(); pushWorkspaces();
+  return true;
+}
+function homeWorkspace() { return workspaces.get(wsId(SELF_ROOT)); }
+function getWs(id) { return (id && workspaces.get(id)) || homeWorkspace(); }
+function wsList() {
+  return [...workspaces.values()].map((w) => ({
+    id: w.id, name: w.name, root: w.root, home: w.root === SELF_ROOT,
+    shape: wsShape(w.root), addedAt: w.addedAt,
+    sessions: [...sessions.values()].filter((s) => s.ws === w.id).length,
+  }));
+}
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'vendor', 'target', 'coverage', '.git', 'tmp', 'out']);
+const PLAIN_MAX_DEPTH = 3;      // the curated (knowledge) view stays shallow
+const TREE_MAX_DEPTH = 6;       // the folder lens is a real explorer, but bounded on huge/slow repos
+const TREE_MAX_NODES = 4000;    // …and node-budgeted so a giant repo (or Google Drive) never hangs
+const BUNDLE_MAX_DEPTH = 2;     // find a planning/okf/skills bundle at the root OR one level nested
+const LIB_FILES = ['DECISIONS.md', 'AGENTS.md', 'PRINCIPLES.md', 'CLAUDE.md', 'discoveries.md', 'README.md'];
+
+function insideRoot(root, p) {
+  const r = path.resolve(p);
+  return r === root || r.startsWith(root + path.sep);
+}
+// Find sub-directories with a given basename, at any depth up to maxDepth (skipping junk dirs).
+// This is how a PMOS bundle is located whether it sits at the repo root OR nested — e.g. IDPF
+// keeps its whole bundle under `pmos/`, so `pmos/planning/prd/*` are real initiatives too.
+function findDirsNamed(root, name, maxDepth) {
+  const found = [];
+  (function walk(dir, depth) {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.name === name) found.push(full);
+      if (depth < maxDepth) walk(full, depth + 1);
+    }
+  })(root, 1);
+  return found;
+}
+function planningRoots(root) { return findDirsNamed(root, 'planning', BUNDLE_MAX_DEPTH); }
+// A repo with a planning/ bundle (at any shallow depth) or a DECISIONS.md gets the initiative lens
+// + curated knowledge; anything else is a plain document tree. Detection is nested-aware so a repo
+// that vendors a PMOS bundle under a sub-folder still shows its initiatives (the reported defect).
+function wsShape(root) {
+  return planningRoots(root).length || fs.existsSync(path.join(root, 'DECISIONS.md')) ? 'pmos' : 'plain';
+}
+
+// ── Library: the file tree the sidebar browses. ───────────────────────────────────────
+// One hierarchical node: {name, path, dirs:[…], docs:[…]}. opts.all → a COMPLETE explorer:
+// every sub-directory (even empty) and every file (each flagged {md}). Otherwise the curated
+// view: .md only, empty branches pruned (used by the initiative lens's knowledge section).
+// DOC READS are workspace-guarded (readTextDoc): markdown/text/html preview; images stream via
+// /api/asset; a truly non-previewable binary is shown but never served.
+function tree(root, dir, opts = {}, depth = 0, budget = { n: TREE_MAX_NODES }) {
+  const rel = path.relative(root, dir);
+  const out = { name: path.basename(dir) || rel || path.basename(root), path: rel, dirs: [], docs: [] };
+  let ents = [];
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  const maxDepth = opts.all ? TREE_MAX_DEPTH : PLAIN_MAX_DEPTH;
+  for (const e of ents.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+    if (budget.n <= 0) break;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (depth < maxDepth) { budget.n--; out.dirs.push(tree(root, full, opts, depth + 1, budget)); }
+    } else if (e.isFile()) {
+      const kind = preview.previewKind(e.name);
+      const isMd = kind === 'markdown';                 // markdown incl. .skill — opens in the reader
+      if (opts.all || isMd) { budget.n--; out.docs.push({ name: e.name, path: path.relative(root, full), md: isMd, kind }); }
+    }
+  }
+  if (!opts.all) out.dirs = out.dirs.filter((d) => d.dirs.length || d.docs.length);   // curated: prune empty
+  return out;
+}
+// The folder lens is a COMPLETE map of the repo — every top-level folder and file, at any shape,
+// browsed the same way whether or not the repo has ever seen PMOS. Curated roots no longer gate it:
+// the reported defect was that it showed "only selected" folders and a new folder never appeared.
+function libraryTree(root) {
+  const roots = [];
+  const budget = { n: TREE_MAX_NODES };
+  let ents = [];
+  try { ents = fs.readdirSync(root, { withFileTypes: true }); } catch {}
+  for (const e of ents.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+    roots.push(tree(root, path.join(root, e.name), { all: true }, 1, budget));
+  }
+  const loose = looseFiles(root);
+  if (loose.length) roots.push({ name: '(root)', path: '', dirs: [], docs: loose });
+  return roots;
+}
+// every top-level file (md + non-md), so the folder lens shows the real root, not a curated subset
+function looseFiles(root) {
+  let ents = [];
+  try { ents = fs.readdirSync(root, { withFileTypes: true }); } catch {}
+  return ents.filter((e) => e.isFile() && !e.name.startsWith('.'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((e) => { const kind = preview.previewKind(e.name); return { name: e.name, path: e.name, md: kind === 'markdown', kind }; });
+}
+// top-level .md files: the curated governance set first, then anything else at the root
+function looseDocs(root) {
+  const seen = new Set();
+  const out = [];
+  for (const f of LIB_FILES) {
+    if (fs.existsSync(path.join(root, f))) { out.push({ name: f, path: f }); seen.add(f); }
+  }
+  let ents = [];
+  try { ents = fs.readdirSync(root, { withFileTypes: true }); } catch {}
+  for (const e of ents.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.isFile() && e.name.endsWith('.md') && !seen.has(e.name)) out.push({ name: e.name, path: e.name });
+  }
+  return out;
+}
+// Serve a TEXTUAL document — markdown (incl. .skill), plain-text/config source, or HTML source —
+// per-workspace-guarded. Images are NOT served here (they stream through /api/asset); anything
+// non-textual returns null so the reader shows it inert. A NUL byte ⇒ binary masquerading as text
+// ⇒ refused. Returns { kind, text } or null. The traversal + cross-workspace guard is unchanged
+// (insideRoot); what widened is the file KIND, never the reachable path set.
+function readTextDoc(root, rel) {
+  const full = path.resolve(root, rel || '');
+  if (!insideRoot(root, full)) return null;                     // per-workspace guard (traversal + cross-ws)
+  const kind = preview.previewKind(path.basename(full));
+  if (kind !== 'markdown' && kind !== 'text' && kind !== 'html') return null;
+  let text;
+  try { text = fs.readFileSync(full, 'utf8'); } catch { return null; }
+  if (text.indexOf(String.fromCharCode(0)) !== -1) return null;   // NUL byte => binary masquerading as text
+  return { kind, text };
+}
+
+// ── The initiative lens: the library grouped the way the PM thinks. ───────────────────
+// planning/ splits one initiative across prd/ evals/ design/ research/ — correct for the
+// filesystem, useless for "show me everything for pmos-jira-sync". This projection joins
+// them on the initiative_id the artifacts already declare in their own identity block,
+// falling back to the filename convention when an artifact declares nothing.
+const ROLE_SUFFIXES = [
+  ['-eval-rubric', 'rubric'], ['-design-brief', 'design brief'], ['-design-reference', 'design'],
+  ['-dogfood', 'dogfood'], ['-reconcile', 'reconcile'], ['-findings', 'findings'],
+  ['-scoping', 'scoping'], ['-intake', 'intake'], ['-brief', 'brief'], ['-prd', 'PRD'],
+];
+const ROLE_BY_DIR = {
+  prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
+  okrs: 'OKR', radar: 'radar', gtm: 'gtm', 'out-of-scope': 'rejected', 'harness-refine': 'harness',
+  'design-export': 'design', explainers: 'explainer', fixtures: 'fixture',
+};
+/** full path -> {mtimeMs, initiative, role, title} — re-read only what actually changed */
+const metaCache = new Map();
+
+function parseHead(full) {
+  // first 4 KB is enough for the identity block + the H1 every PMOS artifact opens with
+  let head = '';
+  try {
+    const fd = fs.openSync(full, 'r');
+    const buf = Buffer.alloc(4096);
+    const n = fs.readSync(fd, buf, 0, 4096, 0);
+    fs.closeSync(fd);
+    head = buf.slice(0, n).toString('utf8');
+  } catch { return {}; }
+  const id = head.match(/^\s*[-*]?\s*initiative_id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
+  const h1 = head.match(/^#\s+(.+)$/m);
+  // status/stage/anchor ride the PRD's identity block — the only initiative signal that lives on
+  // disk today. RICE/effort/milestones/progress do NOT (net-new state) and are never invented.
+  const clean = (m) => m ? m[1].replace(/\*\*/g, '').split(/\s+[—–-]\s|\(/)[0].trim().slice(0, 48) : null;
+  const status = head.match(/^\s*[-*]?\s*status\s*:\s*(.+?)\s*$/mi);
+  const stage = head.match(/^\s*[-*]?\s*stage\s*:\s*(.+?)\s*$/mi);
+  const kr = head.match(/^\s*[-*]?\s*parent[_-]?kr\s*:\s*(.+?)\s*$/mi);
+  return {
+    initiative: id ? id[1] : null,
+    title: h1 ? h1[1].replace(/^(PRD|Eval Rubric|Design Brief)\s*:\s*/i, '').trim() : null,
+    status: clean(status), stage: clean(stage), kr: clean(kr),
+  };
+}
+function roleAndStem(rel, base) {
+  const stem = base.replace(/\.md$/, '');
+  for (const [suf, role] of ROLE_SUFFIXES) {
+    if (stem.endsWith(suf)) return { role, stem: stem.slice(0, -suf.length) };
+  }
+  const dir = path.dirname(rel).split(path.sep).pop();
+  return { role: ROLE_BY_DIR[dir] || 'doc', stem };
+}
+function docMeta(root, full) {
+  let st;
+  try { st = fs.statSync(full); } catch { return null; }
+  const hit = metaCache.get(full);
+  if (hit && hit.mtimeMs === st.mtimeMs) return hit;
+  const rel = path.relative(root, full);
+  const base = path.basename(full);
+  const { role, stem } = roleAndStem(rel, base);
+  const head = parseHead(full);
+  const meta = {
+    mtimeMs: st.mtimeMs, path: rel, name: base, role,
+    // frontmatter wins; the filename convention is the fallback, never the override
+    initiative: head.initiative || null, stem, title: head.title || null,
+    status: head.status || null, stage: head.stage || null, kr: head.kr || null,
+  };
+  metaCache.set(full, meta);
+  return meta;
+}
+function walkMd(dir, acc) {
+  let ents = [];
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const e of ents) {
+    if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walkMd(full, acc);
+    else if (e.isFile() && e.name.endsWith('.md')) acc.push(full);
+  }
+  return acc;
+}
+function initiativeIndex(root) {
+  const proots = planningRoots(root);          // planning/ at the root OR nested (e.g. IDPF/pmos/planning)
+  if (!proots.length) return { initiatives: [], ungrouped: [] };
+  const metas = proots.flatMap((p) => walkMd(p, [])).map((f) => docMeta(root, f)).filter(Boolean);
+  // Pass 1: every id an artifact explicitly declares. Only these are real initiatives —
+  // a filename stem is promoted to a group only when it matches a declared id or when
+  // several artifacts share it, so a lone research note never invents an initiative.
+  const declared = new Set(metas.map((m) => m.initiative).filter(Boolean));
+  const byStem = new Map();
+  for (const m of metas) if (!m.initiative) byStem.set(m.stem, (byStem.get(m.stem) || 0) + 1);
+  const groups = new Map();
+  const ungrouped = [];
+  const keyFor = (m) => {
+    if (m.initiative) return m.initiative;
+    if (declared.has(m.stem)) return m.stem;
+    // the convention join: `jira-sync-prd.md` + `jira-sync-eval-rubric.md` are one unit
+    if ((byStem.get(m.stem) || 0) > 1) return m.stem;
+    return null;
+  };
+  for (const m of metas) {
+    const k = keyFor(m);
+    const art = { name: m.name, path: m.path, role: m.role, title: m.title };
+    if (!k) { ungrouped.push(art); continue; }
+    if (!groups.has(k)) groups.set(k, { id: k, title: null, status: null, stage: null, kr: null, artifacts: [] });
+    const g = groups.get(k);
+    g.artifacts.push(art);
+    if (m.role === 'PRD' && m.title) g.title = m.title;      // the PRD names the initiative
+    else if (!g.title && m.title) g.title = m.title;
+    // status/stage/anchor: the PRD is authoritative; any artifact fills a gap, never overrides it
+    if (m.status && (m.role === 'PRD' || !g.status)) g.status = m.status;
+    if (m.stage && (m.role === 'PRD' || !g.stage)) g.stage = m.stage;
+    if (m.kr && (m.role === 'PRD' || !g.kr)) g.kr = m.kr;
+  }
+  const ROLE_ORDER = ['PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
+  const initiatives = [...groups.values()].map((g) => {
+    g.artifacts.sort((a, b) => {
+      const ia = ROLE_ORDER.indexOf(a.role), ib = ROLE_ORDER.indexOf(b.role);
+      return (ia < 0 ? 99 : ia) - (ib < 0 ? 99 : ib) || a.name.localeCompare(b.name);
+    });
+    return g;
+  }).sort((a, b) => a.id.localeCompare(b.id));
+  ungrouped.sort((a, b) => a.path.localeCompare(b.path));
+  return { initiatives, ungrouped };
+}
+// The folder lens (`roots`) is the complete repo map. The initiative lens is a PROJECTION: it
+// groups planning/ into initiatives and carries the PMOS knowledge (okf/skills/build-skills,
+// wherever they live) + governance. Its guarantee is that it never DROPS a planning document —
+// not that it mirrors every file in the repo (the folder lens is for that).
+function library(root) {
+  const shape = wsShape(root);
+  const roots = libraryTree(root);
+  const { initiatives, ungrouped } = shape === 'pmos' ? initiativeIndex(root) : { initiatives: [], ungrouped: [] };
+  const knowledge = shape === 'pmos'
+    ? ['okf', 'skills', 'build-skills'].flatMap((d) => findDirsNamed(root, d, BUNDLE_MAX_DEPTH))
+      .map((d) => tree(root, d, {}, 0, { n: TREE_MAX_NODES }))
+      .filter((t) => t.dirs.length || t.docs.length)
+    : [];
+  return { shape, roots, initiatives, ungrouped, knowledge, governance: looseDocs(root) };
+}
+
+// ── On-demand surfaces (D60 / the workspace-ondemand-surfaces PRD). ────────────────────────────
+// Plan/Deliver/Measure/Report OUTPUTS, produced when the PM asks — never a resident dashboard.
+// Every surface derives ONLY through local files (the D54 state adapter: planning/ frontmatter,
+// state/needs.json, state/acceptances.jsonl) — no Supabase, no network — so it runs identically in
+// pmos-self and a create-pmos file-mode repo. `surface-contract.js` validates the shape before the
+// client renders it; a surface that can't be produced returns ok:false and the client shows an
+// honest can't-produce state. RICE/effort/milestones/progress are NET-NEW state → emitted as null
+// ("— not tracked"), never invented (D14/D40 honesty).
+const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', landed: 'report' };
+function statusKey(raw) {
+  const s = String(raw || '').toLowerCase();
+  if (/block/.test(s)) return 'blocked';
+  if (/ship|merg|accept|closed|done|live/.test(s)) return 'landed';
+  if (/build|progress|in build|dogfood/.test(s)) return 'building';
+  if (/intake|spec|plan|draft|propos/.test(s)) return 'planning';
+  return null;
+}
+function statusFrom(g) {
+  return statusKey(g.status) || statusKey(g.stage) || 'planning';
+}
+function readAcceptances(w) {
+  const acc = new Map();   // initiative_id -> last action (accept | approve | return)
+  const f = acceptancesFileFor(w);
+  if (!f) return acc;
+  try {
+    for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      // Tolerate both shapes: this server's {action} and the kit's {accepted} (D54 adapter).
+      try {
+        const r = JSON.parse(line);
+        if (!r.initiative_id) continue;
+        acc.set(r.initiative_id, r.action || (r.accepted === true ? 'accept' : r.accepted === false ? 'return' : null));
+      } catch {}
+    }
+  } catch {}
+  return acc;
+}
+function surfaceInitiatives(root, w) {
+  const { initiatives } = initiativeIndex(root);
+  const acc = readAcceptances(w);
+  const items = initiatives.map((g) => {
+    const sk = statusFrom(g);
+    return {
+      id: g.id, title: g.title || null,
+      status: sk, statusText: g.status || g.stage || sk, phase: PHASE_OF[sk] || 'plan',
+      stage: g.stage || null, kr: g.kr || null,
+      accepted: acc.get(g.id) === 'accept',
+      artifacts: g.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path })),
+      // NET-NEW state — not on disk yet, so null (the surface renders "— not tracked", never a guess)
+      rice: null, effort: null, milestones: null, progress: null, tracked: false,
+    };
+  });
+  const by = (k) => items.filter((i) => i.status === k).length;
+  const needs = (readNeeds(w) || []).map((n) => ({
+    t: n.question || '(unstated)', kind: n.kind || 'question', initiative_id: n.initiative_id || null,
+  }));
+  return {
+    initiatives: items,
+    pulse: { total: items.length, planning: by('planning'), building: by('building'), blocked: by('blocked'), landed: by('landed') },
+    needs,
+  };
+}
+function surfaceRoadmap(root, w) {
+  const items = surfaceInitiatives(root, w).initiatives;
+  const bucket = (label, keys) => ({
+    label, dates_tracked: false,
+    items: items.filter((i) => keys.includes(i.status)).map((i) => ({ id: i.id, status: i.status, phase: i.phase, progress: i.progress })),
+  });
+  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['landed'])]
+    .filter((g) => g.items.length);
+  return { groups, note: 'dates are net-new state — grouped by status until a timeline is tracked' };
+}
+function surfaceOkr(root) {
+  const objectives = [];
+  for (const dir of findDirsNamed(root, 'okrs', BUNDLE_MAX_DEPTH)) {
+    for (const f of walkMd(dir, [])) {
+      let text = '';
+      try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+      let cur = null;
+      for (const line of text.split('\n')) {
+        const o = line.match(/^#{1,3}\s+(O\d+)\s*[—–:-]?\s*(.+)$/);
+        if (o) { cur = { id: o[1], name: o[2].replace(/\*\*/g, '').trim().slice(0, 120), krs: [] }; objectives.push(cur); continue; }
+        const k = line.match(/^\s*[-*]\s*\*\*\s*(KR\d+)\s*[—–:-]?\s*(.+?)\*\*/);
+        if (k && cur) cur.krs.push({ id: k[1], name: k[2].trim().slice(0, 140), current: null, target: null, levers: null });
+      }
+    }
+  }
+  return { objectives, note: 'KR current/target and the lever tree are net-new state — shown as "— not tracked"' };
+}
+function surfaceReport(root, w) {
+  const s = surfaceInitiatives(root, w);
+  const line = (i) => `${i.id}${i.title ? ' — ' + i.title : ''}`;
+  const inflight = s.initiatives.filter((i) => i.status === 'building' || i.status === 'blocked');
+  const landed = s.initiatives.filter((i) => i.status === 'landed');
+  const sections = [
+    { heading: 'In flight', items: inflight.map(line) },
+    { heading: 'Landed', items: landed.map(line) },
+    { heading: 'Needs you', items: s.needs.map((n) => n.t) },
+    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.landed} landed`] },
+  ];
+  return { cadence: 'weekly', sections };
+}
+function buildSurface(name, root, w) {
+  switch (name) {
+    case 'initiatives': return surfaceInitiatives(root, w);
+    case 'roadmap': return surfaceRoadmap(root, w);
+    case 'okr': return surfaceOkr(root);
+    case 'report': return surfaceReport(root, w);
+    default: return null;
+  }
+}
+
+// ── Scheduled tasks (workspace-scheduled-tasks PRD). ────────────────────────────────────────────
+// A local scheduler: schedules live in state/schedules.json; a tick fires due ones; each fire runs
+// a SKILL-backed task and produces a contract-checked deliverable, filed to needs-you. Backend-free
+// (D62). v1 tasks are DETERMINISTIC (generated from a surface + the contract = maximally consistent,
+// no agent needed); agent-backed tasks (reasoning work) that spawn a PTY session are the documented
+// extension, not v1. Cadence math is the pure shared module — the tick and the pane's next-run agree.
+const SCHED_FILE = path.join(STATE, 'schedules.json');
+const DELIV_DIR = path.join(STATE, 'deliverables');
+// Skills are file-driven (workspace-skill-authoring): built-ins ship committed under workspace/skills/,
+// user-authored ones are scaffolded into state/skills/ by the New Skill flow. There is ONE user-facing
+// concept — a skill — so the picker never exposes the internal `run`/`kind`; how a skill runs (server
+// derives it instantly, or a claude PTY session reasons through it) is decided by the file, not the PM.
+const BUILTIN_SKILLS_DIR = path.join(__dirname, 'skills');
+const USER_SKILLS_DIR = path.join(STATE, 'skills');
+// Read the skill files fresh each call so a just-created user skill appears with no restart. User dirs
+// load FIRST and built-ins LAST, so a built-in's load-bearing deterministic fast-path can't be shadowed.
+function loadTasks() {
+  return skillStore.loadSkills([
+    { dir: USER_SKILLS_DIR, source: 'user' },
+    { dir: BUILTIN_SKILLS_DIR, source: 'builtin' },
+  ]).map(toTask);
+}
+// Map a loaded skill to the internal task shape fireSchedule/the picker use. `kind` is derived from the
+// file's `run` and stays INTERNAL — it is never a field the PM selects.
+function toTask(s) {
+  const t = { id: s.id, label: s.label, skill: s.id, kind: s.run, source: s.source,
+    description: s.description, output: s.output };
+  if (s.run === 'deterministic') t.surface = s.surface;
+  else { t.agent = s.agent || 'claude'; t.prompt = s.body || null; }
+  return t;
+}
+function taskById(id) { return loadTasks().find((t) => t.id === id || t.skill === id) || null; }
+function readSchedules() {
+  try { const a = JSON.parse(fs.readFileSync(SCHED_FILE, 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
+}
+function writeSchedules(list) {
+  try { fs.writeFileSync(SCHED_FILE, JSON.stringify(list)); }
+  catch (e) { warnWriteFail('schedules.json (scheduled tasks)', e); }
+}
+
+function reportToMarkdown(surface) {
+  const out = ['# Weekly report', '', `_${surface.cadence || 'weekly'} · generated ${nowISO()}_`, ''];
+  for (const sec of (surface.sections || [])) {
+    out.push(`## ${sec.heading}`, '');
+    for (const it of (sec.items && sec.items.length ? sec.items : ['—'])) out.push(`- ${it}`);
+    out.push('');
+  }
+  return out.join('\n');
+}
+// Fire one schedule: run its skill → contract → deliverable → stamp → file to needs-you. Same path
+// for a scheduled tick and for run-now (R7). Pure of PTYs in v1 (deterministic report skill).
+function fireSchedule(sched) {
+  const w = workspaces.get(sched.ws) || homeWorkspace();
+  const root = w ? w.root : SELF_ROOT;
+  const task = taskById(sched.task) || taskById(sched.skill);
+  // AGENT task — fire as a real PTY session running its skill (async; the skill files its own
+  // deliverable). The workspace starts it + stamps 'started'; run-now and the tick share this path.
+  if (task && task.kind === 'agent') {
+    const s = spawnSession({ name: sched.name, agent: task.agent || 'claude', ws: sched.ws,
+      origin: 'schedule:' + sched.id, initialInput: task.prompt ? task.prompt + '\r' : null });
+    const list = readSchedules(); const cur = list.find((x) => x.id === sched.id);
+    const started = s.state !== 'exited';
+    if (cur) { cur.lastRun = nowISO(); cur.lastStatus = started ? 'started' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); writeSchedules(list); }
+    return { ok: started, kind: 'agent', sessionId: s.id, reason: started ? '' : (s.note || 'could not start the session') };
+  }
+  const runId = `sched-${sched.id}-${Date.now()}`;
+  let ok = false, deliverable = null, reason = '';
+  try {
+    if (task && task.kind === 'deterministic') {
+      const surface = buildSurface(task.surface, root, w);
+      const contract = checkSurface(task.surface, surface || {});
+      if (contract.pass) {
+        try { fs.mkdirSync(DELIV_DIR, { recursive: true }); } catch {}
+        fs.writeFileSync(path.join(DELIV_DIR, runId + '.md'), reportToMarkdown(surface));
+        deliverable = runId; ok = true;
+      } else { reason = 'contract: missing ' + (contract.missing || []).join(', '); }
+    } else { reason = 'no skill-backed task'; }
+  } catch (e) { reason = 'error: ' + String(e && e.message || 'failed').slice(0, 120); }
+  // stamp lastRun/lastStatus/nextRun via the pure module
+  const list = readSchedules();
+  const cur = list.find((s) => s.id === sched.id);
+  if (cur) { cur.lastRun = nowISO(); cur.lastStatus = ok ? 'ok' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); writeSchedules(list); }
+  // surface it — the finished run reaches the PM through needs-you (R5), honest on failure
+  try {
+    const nf = needsFileFor(w);
+    if (nf) {
+      let needs = []; try { needs = JSON.parse(fs.readFileSync(nf, 'utf8')); } catch {}
+      needs.push(ok
+        ? { run_id: runId, kind: 'report', initiative_id: sched.name, question: `${sched.name} — report ready`, deliverable }
+        : { run_id: runId, kind: 'report', initiative_id: sched.name, question: `${sched.name} could not produce its report — ${reason}` });
+      fs.writeFileSync(nf, JSON.stringify(needs));
+    }
+  } catch (e) { warnWriteFail('needs.json (needs-you queue, schedule fire)', e); }
+  return { ok, runId, deliverable, reason };
+}
+function checkDueSchedules() {
+  let fired = 0;
+  for (const s of readSchedules()) { try { if (scheduleLogic.isDue(s)) { fireSchedule(s); fired++; } } catch {} }
+  return fired;
+}
+// the tick — the persistent server checks on an interval; unref'd so it never blocks exit
+try { const _tick = setInterval(checkDueSchedules, 60000); if (_tick.unref) _tick.unref(); } catch {}
+
+// ── Sessions: real PTYs, owned by the server, with disk-backed scrollback + metadata. ──
+/** @type {Map<string, {id,ws,name,agent,cwd,state,note,created,pty,buf,cols,rows,clients:Set}>} */
+const sessions = new Map();
+/** every connected ws — broadcasts must reach clients that haven't attached to anything yet */
+const allClients = new Set();
+let seq = 0;
+
+function persist(s) {
+  // note IS persisted — a restored session must still say why it exited. `root` is persisted
+  // so a session survives even if the workspace registry is lost (it re-registers its root).
+  const meta = { id: s.id, ws: s.ws, root: s.root, name: s.name, agent: s.agent, cwd: s.cwd,
+    state: s.state, note: s.note || '', created: s.created, tmux: s.tmux || null, origin: s.origin || null };
+  try {
+    fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
+    fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
+  } catch { /* best-effort; never crash a live session on a disk blip */ }
+}
+function unpersist(id) {
+  for (const ext of ['.json', '.scrollback']) {
+    try { fs.unlinkSync(path.join(SESS_DIR, id + ext)); } catch {}
+  }
+}
+function restorePersisted() {
+  // On server start, load prior sessions' metadata + scrollback. A tmux-backed session whose
+  // process is STILL ALIVE (it outlived this server via the tmux daemon) is RE-ATTACHED live —
+  // the PM's `claude` keeps its in-flight state across `pmos stop`/relaunch, no respawn (R7).
+  // A session whose process is truly gone (tmux absent, or the daemon/process ended) loads as
+  // 'exited' with replayable scrollback and a one-click respawn — honest, never a fake-live pane.
+  let files = [];
+  try { files = fs.readdirSync(SESS_DIR).filter((f) => f.endsWith('.json')); } catch { return; }
+  for (const f of files) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(SESS_DIR, f), 'utf8'));
+      if (!meta.id || sessions.has(meta.id)) continue;
+      let buf = '';
+      try { buf = fs.readFileSync(path.join(SESS_DIR, meta.id + '.scrollback'), 'utf8'); } catch {}
+      // re-home the session: its workspace must exist for it to be reachable in the UI
+      const root = meta.root || SELF_ROOT;
+      const w = workspaces.get(meta.ws) || registerWorkspace(root) || homeWorkspace();
+      const s = {
+        ...meta, ws: w ? w.id : wsId(SELF_ROOT), root: w ? w.root : SELF_ROOT,
+        pty: null, buf, tmux: meta.tmux || null, cols: 80, rows: 24, clients: new Set(),
+      };
+      sessions.set(meta.id, s);
+      if (TMUX && meta.tmux && tmuxHasSession(meta.tmux)) {
+        s.state = 'working'; s.note = '';
+        attachPty(s);                       // the process is alive — reconnect to it, live
+      } else {
+        s.state = 'exited';
+        s.note = meta.note || 'restored after server restart — scrollback preserved; ↻ respawn to start a new process';
+      }
+      const n = Number(String(meta.id).split('-')[1]); if (Number.isFinite(n) && n >= seq) seq = n + 1;
+    } catch {}
+  }
+}
+
+// Broadcast to EVERY connected client exactly once (not per-session — a fresh client that
+// hasn't attached must still see session-list updates; an N-session client must not get N copies).
+function broadcast(obj) {
+  const msg = JSON.stringify(obj);
+  for (const c of allClients) if (c.readyState === 1) c.send(msg);
+}
+// The agent process behind a session. tmux spawns the command directly (see ensureTmuxSession's
+// `-- cmd`, no shell), so pane_pid IS the agent — one hop, no guessing. Cached because a pid
+// cannot change for the life of a session.
+function agentPid(s) {
+  if (s.agentPid !== undefined) return s.agentPid;
+  let pid = null;
+  if (s.tmux && TMUX) {
+    const r = tmuxCtl(['display-message', '-p', '-t', s.tmux, '#{pane_pid}']);
+    const n = r && r.status === 0 ? parseInt(String(r.stdout).trim(), 10) : NaN;
+    if (Number.isFinite(n) && n > 0) pid = n;
+  } else if (s.pty && s.pty.pid) {
+    pid = s.pty.pid;
+  }
+  s.agentPid = pid;
+  return pid;
+}
+
+// The harness itself comes from the CLI's own STRUCTURED transcript, not from rendered bytes:
+// the CLI never PRINTS its model, effort, token usage or skill set to the terminal, so parsing
+// scrollback for them returned four empty rows. Scrollback still owns the one thing it is
+// actually the source of — the agent's last words. Re-read on transcript mtime/size change.
+function transcriptHarness(s) {
+  if (s.state === 'exited') return { missing: { all: 'the session has exited' } };
+  // A `shell` session is included: the PM launches `claude` INSIDE the default shell pane, so the
+  // agent is a descendant of the pane pid — findTranscript's child-walk resolves it. A non-claude,
+  // non-shell agent (e.g. codex) publishes no claude transcript, so it keeps the honest message.
+  if (s.agent !== 'claude' && s.agent !== 'shell') {
+    return { missing: { all: 'only claude sessions publish a transcript' } };
+  }
+  // findTranscript may shell out to `ps` for the child-walk; throttle so a broadcast storm cannot
+  // spawn a ps per session per push. Re-resolving every ~2s also picks up a claude the PM restarts
+  // inside the same shell (a new child pid) without a stale cache pinning the old transcript.
+  const now = Date.now();
+  if (!s.txFound || (now - (s.txFoundAt || 0)) > 2000) {
+    s.txFound = transcript.findTranscript(agentPid(s), s.root);
+    s.txFoundAt = now;
+  }
+  const found = s.txFound;
+  if (found.missing) return { missing: { all: found.missing } };
+  let stamp = null;
+  try { const st = fs.statSync(found.file); stamp = `${st.size}:${st.mtimeMs}`; } catch {}
+  if (s.tx && s.txStamp === stamp) return s.tx;
+  const h = transcript.readHarness(found.file, scrub);
+  h.cliVersion = found.version || null;
+  s.tx = h; s.txStamp = stamp;
+  return h;
+}
+
+// Parse lazily and cache per buffer length: sessionList() runs on every broadcast, and
+// re-reading a 32 KB tail per session per push would be waste. `appendBuf` invalidates.
+function harnessOf(s) {
+  if (s.parsed && s.parsedAt === s.buf.length) return s.parsed;
+  let out;
+  try {
+    // scrub() FIRST, always (D08): the tail holds whatever the agent printed, so an unscrubbed
+    // "last words" line could put a credential in the sidebar. Reuses the session-search path.
+    out = harness.parseHarness(scrub(s.buf || ''), s.agent);
+  } catch (e) {
+    // A throwing parser must still say it could not read — never fall through to a blank row.
+    const why = 'the parser failed on this output';
+    out = { lastWords: null, tools: null, model: null, context: null,
+      missing: { lastWords: `can't read its last words — ${why}`, tools: why, model: why, context: why } };
+  }
+  s.parsed = out; s.parsedAt = s.buf.length;
+  return out;
+}
+function sessionList() {
+  const now = Date.now();
+  return [...sessions.values()].map((s) => {
+    const d = harness.deriveState(s.state, s.lastOutputAt, now);
+    const h = harnessOf(s);
+    return {
+      id: s.id, ws: s.ws, name: s.name, agent: s.agent, state: s.state, created: s.created,
+      cwd: path.relative(s.root, s.cwd) || '.', note: s.note || '', origin: s.origin || null,
+      // derived presentation state: working | quiet | exited. `shell`-ness stays on `agent`,
+      // because it is orthogonal to state; `failed` does not exist (no observable for it).
+      shown: d.state, quietMs: d.quietMs, lastOutputAt: s.lastOutputAt || null,
+      lastWords: h.lastWords,
+      // the harness proper — structured record, not rendered bytes
+      hx: transcriptHarness(s),
+      missing: h.missing,
+    };
+  });
+}
+function pushSessions() { broadcast({ t: 'sessions', sessions: sessionList() }); }
+function pushWorkspaces() { broadcast({ t: 'workspaces', workspaces: wsList() }); }
+
+function appendBuf(s, data) {
+  s.buf += data;
+  if (s.buf.length > SCROLLBACK) s.buf = s.buf.slice(s.buf.length - SCROLLBACK);
+  // Parser 2's whole input: the moment output last arrived. `quiet` is derived from this, never
+  // from reading the bytes — which is why it is the only one of the five that cannot misread.
+  s.lastOutputAt = Date.now();
+  s.parsed = null;                      // buffer moved; the cached parse is stale
+}
+
+// Platform-correct guidance when a spawn fails. `posix_spawnp failed` almost always means the
+// node-pty NATIVE BINARY is broken/wrong-arch (e.g. x64 Node on Apple Silicon) — a shell change
+// won't fix that; a rebuild will.
+function spawnFailureAdvice(err, cmd, isShell) {
+  const msg = String(err && err.message || err);
+  if (/posix_spawnp|EFAULT|ENOEXEC|wrong architecture|not valid/i.test(msg)) {
+    return `could not spawn '${cmd}' (${msg}). This is usually a broken node-pty native build ` +
+      `(arch mismatch). Fix: stop the server, run \`npm run doctor\` in workspace/, ` +
+      `then \`npm rebuild node-pty --build-from-source\`.`;
+  }
+  if (process.platform === 'win32') {
+    return `could not start '${cmd}': ${msg}. Native Windows needs WSL for a real PTY shell — ` +
+      `run the workspace inside WSL.`;
+  }
+  return isShell
+    ? `could not start a shell ('${cmd}'): ${msg}. Set SHELL to a valid shell (e.g. /bin/zsh) and restart.`
+    : `could not launch '${cmd}': ${msg} — is it installed and on PATH?`;
+}
+
+// Does `cmd` exist as an executable? (On Linux node-pty does NOT throw for a missing
+// command — the exec fails inside the fork — so a pre-spawn PATH check is the only way
+// to give a deterministic "not installed" answer on every platform.)
+function commandExists(cmd) {
+  const X = fs.constants.X_OK;
+  try {
+    if (cmd.includes('/') || cmd.includes('\\')) { fs.accessSync(cmd, X); return true; }
+    const exts = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+      if (!dir) continue;
+      for (const ext of exts) {
+        try { fs.accessSync(path.join(dir, cmd + ext), X); return true; } catch {}
+      }
+    }
+  } catch {}
+  return false;
+}
+
+// ── tmux-backed sessions: real persistence across a SERVER restart (R7). ───────────────
+// Each session's process runs inside a DETACHED tmux session on a private socket, so stopping
+// or restarting THIS server (`pmos stop`, a crash, a code deploy) leaves the process alive in
+// the tmux daemon; on relaunch we re-attach to the LIVE process — no respawn, no lost agent
+// state (the reported defect). tmux is wrapped TRANSPARENTLY — prefix disabled, no status bar,
+// no key/mouse bindings, RGB passed through — so the harness inside still runs untouched (D62).
+// Where tmux is absent, spawnSession falls back to a direct PTY (today's behavior): honest,
+// just not restart-proof.
+const TMUX = commandExists('tmux') ? 'tmux' : null;
+const TMUX_SOCK = process.env.PMOS_TMUX_SOCK || 'pmos';   // private socket; never the user's own
+const TMUX_CONF = path.join(STATE, 'tmux.conf');
+let shuttingDown = false;                                 // set on SIGTERM/SIGINT — suppress reattach
+function tmuxName(id) { return 'pmos-' + id; }
+function writeTmuxConf() {
+  if (!TMUX) return;
+  const conf = [
+    // Full transparency: no prefix, no bindings, no status line, no mouse capture — every
+    // keystroke and mouse event reaches the app inside, unaltered (the harness runs untouched).
+    'set -g prefix None', 'set -g prefix2 None', 'unbind -a',
+    'set -g status off', 'set -g mouse off', 'set -g escape-time 0',
+    'set -g history-limit 100000', 'set -g destroy-unattached off',
+    'set -g window-size latest', 'setw -g aggressive-resize on',
+    // a (re)attaching client must not push a stale or CLAUDE_CODE-marked env into new panes
+    'set -g update-environment ""',
+    'set -g default-terminal "screen-256color"', 'set -as terminal-features ",*:RGB"',
+  ].join('\n') + '\n';
+  try { fs.writeFileSync(TMUX_CONF, conf); } catch {}
+}
+// A tmux CONTROL command (not the attach PTY). Uses the CLEANED session env so that the cold
+// start this may trigger seeds the tmux server's own environment marker-free (D62 / sessionEnv).
+function tmuxCtl(args) { return spawnSync(TMUX, ['-L', TMUX_SOCK, ...args], { env: sessionEnv(), encoding: 'utf8' }); }
+function tmuxHasSession(name) { return !!TMUX && tmuxCtl(['has-session', '-t', name]).status === 0; }
+function tmuxKillSession(name) { if (TMUX && name) tmuxCtl(['kill-session', '-t', name]); }
+function ensureTmuxSession(name, cmd, workdir, cols, rows) {
+  if (tmuxHasSession(name)) return true;                  // already alive (a reattach) — leave it
+  const r = tmuxCtl(['-f', TMUX_CONF, 'new-session', '-d', '-s', name,
+    '-x', String(cols || 80), '-y', String(rows || 24), '-c', workdir, '--', cmd]);
+  return r.status === 0;
+}
+// Spawn the server-side PTY that is a tmux client attached to session s's LIVE tmux session,
+// wiring streaming + exit. Reused by spawnSession (fresh) and restorePersisted (reattach).
+function attachPty(s) {
+  const name = tmuxName(s.id);
+  const startedMs = Date.now();
+  const p = pty.spawn(TMUX, ['-L', TMUX_SOCK, 'attach-session', '-t', name],
+    { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
+  s.pty = p; s.tmux = name; s.state = 'working';
+  // Start the quiet clock at ATTACH, not at first byte: a session that spawns and immediately
+  // hangs should go quiet on schedule rather than read 'working' forever. On a restore this
+  // means "no output since we re-attached", which is the only thing we can honestly claim.
+  s.lastOutputAt = Date.now(); s.parsed = null;
+  p.onData((d) => {
+    if (s._reattempts) s._reattempts = 0;                 // a working attach clears the retry budget
+    appendBuf(s, d);
+    for (const c of s.clients) if (c.readyState === 1) c.send(JSON.stringify({ t: 'data', id: s.id, data: d }));
+  });
+  p.onExit(({ exitCode }) => {
+    s.pty = null;
+    // Our PTY is the tmux CLIENT: it exits when the pane process ends AND on a mere detach. If
+    // the tmux session is still alive, the process lives on — reconnect (bounded, to never spin).
+    // If it's gone, the process truly exited.
+    if (!shuttingDown && tmuxHasSession(name)) {
+      s._reattempts = (s._reattempts || 0) + 1;
+      if (s._reattempts <= 5) {
+        setTimeout(() => { if (!s.pty && !shuttingDown && tmuxHasSession(name)) attachPty(s); }, 200);
+        return;
+      }
+      tmuxKillSession(name);                               // give up cleanly rather than loop
+    }
+    s.state = 'exited';
+    const fast = Date.now() - startedMs < 800;
+    s.note = fast
+      ? `'${s.agent}' exited immediately. If this repeats, run \`npm run doctor\` — usually a broken node-pty build or a shell rc that exits.`
+      : `exited (code ${exitCode})`;
+    appendBuf(s, `\r\n\x1b[38;5;244m[${s.note}]\x1b[0m\r\n`);
+    persist(s); pushSessions();
+  });
+  return p;
+}
+
+// Try a command, falling back to `sh` on posix if the preferred shell can't spawn.
+function spawnPty(cmd, workdir) {
+  const opts = { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: sessionEnv() };
+  const chain = process.platform === 'win32' ? [cmd] : [...new Set([cmd, 'sh', '/bin/sh'])];
+  let lastErr;
+  for (const c of chain) {
+    try { return { pty: pty.spawn(c, [], opts), cmd: c }; } catch (e) { lastErr = e; }
+  }
+  throw lastErr;
+}
+
+// An honest exited pane: say WHY in the pane and the session note. Never a fake-live pane.
+function exitedSession(base, workdir, why) {
+  const s = { ...base, cwd: workdir, state: 'exited', pty: null, tmux: null, note: why,
+    buf: `\x1b[38;5;203m✗ ${why}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`,
+    cols: 80, rows: 24, clients: new Set(), created: nowISO() };
+  sessions.set(s.id, s); persist(s); pushSessions(); pushWorkspaces(); return s;
+}
+
+function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
+  const id = 'sess-' + (seq++);
+  const w = getWs(ws);
+  const root = w ? w.root : SELF_ROOT;
+  const isShell = agent === 'shell';
+  // a scheduled run tags the session with its origin, and feeds the skill invocation as first input
+  const tag = origin || null;
+  const feed = (s) => { if (initialInput && s && s.pty) { try { setTimeout(() => { try { s.pty.write(initialInput); } catch {} }, 700); } catch {} } };
+  // shell gets a real fallback to `sh`; agent CLIs run as-is (harness untouched), NO fallback —
+  // falling back from `claude` to `sh` would be a lie.
+  const cmd = isShell ? (commandExists(SHELL) ? SHELL : 'sh') : agent;
+  // a session's working directory is confined to its OWN workspace root (R3)
+  const workdir = cwd && insideRoot(root, path.resolve(root, cwd)) ? path.resolve(root, cwd) : root;
+  const base = { id, ws: w ? w.id : wsId(SELF_ROOT), root, name: (name && String(name).trim()) || agent, agent, origin: tag };
+
+  // A missing agent CLI is detected BEFORE any spawn (on Linux the exec-in-fork failure is
+  // otherwise silent) — the same honest exited pane on both the tmux and the direct path.
+  if (!isShell && !commandExists(agent)) {
+    return exitedSession(base, workdir,
+      spawnFailureAdvice(Object.assign(new Error(`'${agent}' not found on PATH`), { code: 'ENOENT' }), agent, false));
+  }
+
+  // ── the tmux path: the process outlives this server, and we re-attach to it live (R7) ──
+  if (TMUX) {
+    const tname = tmuxName(id);
+    const s = { ...base, cwd: workdir, state: 'working', pty: null, tmux: tname,
+      note: '', buf: '', cols: 80, rows: 24, clients: new Set(), created: nowISO() };
+    sessions.set(id, s);
+    if (!ensureTmuxSession(tname, cmd, workdir, 80, 24)) {
+      const why = `could not start a tmux session for '${cmd}'. Run \`npm run doctor\` in workspace/.`;
+      s.state = 'exited'; s.tmux = null; s.note = why;
+      s.buf = `\x1b[38;5;203m✗ ${why}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`;
+      persist(s); pushSessions(); pushWorkspaces(); return s;
+    }
+    attachPty(s);
+    feed(s);
+    persist(s); pushSessions(); pushWorkspaces(); return s;
+  }
+
+  // ── fallback: a direct PTY (no tmux on this machine) — honest, just not restart-proof ──
+  const startedMs = Date.now();
+  let p, usedCmd = cmd;
+  try {
+    if (isShell) { const r = spawnPty(cmd, workdir); p = r.pty; usedCmd = r.cmd; }
+    else p = pty.spawn(cmd, [], { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: sessionEnv() });
+  } catch (e) {
+    return exitedSession(base, workdir, spawnFailureAdvice(e, cmd, isShell));
+  }
+  const s = { ...base, cwd: workdir, state: 'working',
+    pty: p, tmux: null, note: '', buf: '', cols: 80, rows: 24, clients: new Set(), created: nowISO(),
+    lastOutputAt: Date.now() };
+  sessions.set(id, s);
+  p.onData((d) => {
+    appendBuf(s, d);
+    for (const c of s.clients) if (c.readyState === 1) c.send(JSON.stringify({ t: 'data', id, data: d }));
+  });
+  p.onExit(({ exitCode }) => {
+    s.state = 'exited'; s.pty = null;
+    const fast = Date.now() - startedMs < 800;   // exited almost immediately → surface a hint
+    s.note = fast
+      ? `'${usedCmd}' exited immediately (code ${exitCode}). If this repeats, run \`npm run doctor\` — usually a broken node-pty build or a shell rc that exits.`
+      : `exited (code ${exitCode})`;
+    appendBuf(s, `\r\n\x1b[38;5;244m[${s.note}]\x1b[0m\r\n`);
+    persist(s); pushSessions();
+  });
+  feed(s);
+  persist(s); pushSessions(); pushWorkspaces();
+  return s;
+}
+// Remove a session from the registry + disk. Only non-live sessions can be removed;
+// a live one must be killed first (its onExit flips it to exited).
+function removeSession(id) {
+  const s = sessions.get(id);
+  if (!s || s.pty) return false;
+  if (s.tmux) tmuxKillSession(s.tmux);   // best-effort: never orphan a detached tmux session
+  sessions.delete(id); unpersist(id); pushSessions(); pushWorkspaces();
+  return true;
+}
+
+// Rename a session. A name chosen at creation is a guess — the PM learns what the run actually
+// is minutes later, so renaming must work at ANY point, live or exited (R11). The name is the
+// only thing that makes a list of sessions readable, so it is persisted like the rest of the meta.
+const NAME_MAX = 60;
+function renameSession(id, name) {
+  const s = sessions.get(id);
+  if (!s) return false;
+  const next = String(name == null ? '' : name).replace(/[\r\n\t]/g, ' ').trim().slice(0, NAME_MAX);
+  if (!next || next === s.name) return false;   // empty is a cancel, not a rename
+  s.name = next;
+  persist(s); pushSessions();
+  return true;
+}
+
+// periodic scrollback persistence so a crash loses at most a few seconds of history
+setInterval(() => { for (const s of sessions.values()) if (s.pty) persist(s); }, 5000).unref?.();
+
+// ── File-mode state, per workspace. ───────────────────────────────────────────────────
+// A repo that carries PMOS state OWNS its records. The kit (D54) keeps them under `pmos/state/`
+// and `scripts/metrics.py` reads exactly that path for the north star and κ. Reads and writes
+// MUST resolve through this one function: a queue read per-repo but recorded into the server's
+// own state/ is how a tenant's acceptance disappears from the repo that earned it — the click
+// goes green and the record it was supposed to leave never exists.
+function stateDirFor(w, { create = false } = {}) {
+  if (!w) return null;
+  for (const rel of [['pmos', 'state'], ['state'], ['.pmos']]) {
+    const d = path.join(w.root, ...rel);
+    if (isDir(d)) return d;
+  }
+  if (w.root === SELF_ROOT) return STATE;   // pmos-self: the server's own state/ IS its file-mode mirror
+  // A PMOS-shaped repo with no state dir yet gets the kit's own layout on first write. Never
+  // invented for a plain repo — there we fall back and SAY SO rather than write somewhere wrong.
+  if (create && wsShape(w.root) === 'pmos') {
+    const d = path.join(w.root, 'pmos', 'state');
+    try { fs.mkdirSync(d, { recursive: true }); return d; } catch {}
+  }
+  return null;
+}
+function acceptancesFileFor(w, opts) {
+  const d = stateDirFor(w, opts);
+  return d ? path.join(d, 'acceptances.jsonl') : null;
+}
+// needs-you: an explicit queue file the harness writes wins; otherwise the workspace's state dir.
+function needsFileFor(w) {
+  if (!w) return null;
+  const local = path.join(w.root, '.pmos', 'needs.json');
+  if (fs.existsSync(local)) return local;
+  const d = stateDirFor(w);
+  return d ? path.join(d, 'needs.json') : null;
+}
+function readJsonl(dir, name) {
+  const out = [];
+  try {
+    for (const line of fs.readFileSync(path.join(dir, name), 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch {}
+    }
+  } catch {}
+  return out;
+}
+// The LEADING frontmatter block only — body text must never be able to fake a declaration.
+// The implementation now lives in lib/file-mode-parse.js and is MIRRORED by kit/scripts/metrics.py,
+// with kit/fixtures/test_parsers.py enforcing that the JS and Python parsers agree (D64 Track D1).
+function leadingFrontmatter(file) { return fmParse.leadingFrontmatter(file); }
+// ── Derived needs-you: what the PM owes a decision on, computed from the repo's own
+// append-only state rather than waiting for something to seed a queue file. Two sources, both
+// decisions only the human can close:
+//   1. an eval with no acceptance for its run_id → the Acceptance Gate is open (D12)
+//   2. a declared outcome past its horizon, never disposed → the D57 check is due
+// The outcome rule mirrors kit/scripts/metrics.py EXACTLY, including "a missing horizon counts
+// as due" — a bet with no judgment date can never come due by itself (horizon-gaming-by-omission).
+// Derivation only ever reports; it never disposes anything (D57).
+function deriveNeeds(w) {
+  const dir = stateDirFor(w);
+  if (!dir) return [];
+  const needs = [];
+  const settled = new Set();
+  for (const a of readJsonl(dir, 'acceptances.jsonl')) if (a.run_id) settled.add(a.run_id);
+  for (const e of readJsonl(dir, 'evals.jsonl')) {
+    if (!e.run_id || settled.has(e.run_id)) continue;
+    const verdict = e.verdict ? String(e.verdict) : 'no verdict';
+    needs.push({
+      run_id: e.run_id, initiative_id: e.initiative_id || null, kind: 'accept', derived: true,
+      question: `Acceptance Gate open — evaluator says ${verdict}${e.score != null ? ` (${e.score})` : ''}`,
+      doc: e.rubric_path || null,
+    });
+  }
+  const disposed = new Set();
+  for (const c of readJsonl(dir, 'outcome_checks.jsonl')) if (c.initiative_id) disposed.add(c.initiative_id);
+  const today = nowISO().slice(0, 10);
+  let files = [];
+  try { files = fs.readdirSync(path.join(dir, 'initiatives')).filter((f) => f.endsWith('.md')).sort(); } catch {}
+  for (const f of files) {
+    const fm = leadingFrontmatter(path.join(dir, 'initiatives', f));
+    if (!fm.id || !fm.outcome_metric || disposed.has(fm.id)) continue;
+    if (String(fm.outcome_horizon || '0000-00-00') >= today) continue;
+    needs.push({
+      run_id: `outcome:${fm.id}`, initiative_id: fm.id, kind: 'outcome', derived: true,
+      question: `Outcome check due — "${fm.outcome_metric}" (horizon ${fm.outcome_horizon || 'none declared'})`,
+      doc: null,
+    });
+  }
+  return needs;
+}
+// The queue the harness writes is authoritative for the entries it names; everything the repo's
+// own state implies is added beneath it. A repo nobody has seeded still shows its real work.
+function readNeeds(w) {
+  const f = needsFileFor(w);
+  let queued = [];
+  if (f) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(f, 'utf8'));
+      if (Array.isArray(parsed)) queued = parsed;
+    } catch {}
+  }
+  const seen = new Set(queued.map((n) => n && n.run_id).filter(Boolean));
+  return queued.concat(deriveNeeds(w).filter((n) => !seen.has(n.run_id)));
+}
+
+// ── Read-only console surfaces over file-mode state (D64 Track B). ──────────────────────
+// The committed hosted snapshot is the seed/demo source when no LIVE file-mode state exists; the
+// readers in lib/console-state.js always prefer live state. pmos-self reads its own snapshot; a
+// tenant workspace only ever reads ITS OWN snapshot (never pmos-self's), so a tenant with no data
+// gets an honest "no source" error rather than someone else's numbers.
+function latestSnapshotDir(root) {
+  const base = path.join(root, 'planning', 'data-export');
+  let ents = [];
+  try { ents = fs.readdirSync(base, { withFileTypes: true }); } catch { return null; }
+  const dirs = ents.filter((e) => e.isDirectory() && /hosted-snapshot/.test(e.name)).map((e) => e.name).sort();
+  return dirs.length ? path.join(base, dirs[dirs.length - 1]) : null;   // dates sort → newest last
+}
+// The needs-you console read, honest by construction: a corrupt/unreadable queue file is an ERROR
+// (red on the client), NEVER a green "nothing awaits". A successfully-computed empty queue is empty.
+function needsResult(w) {
+  if (!w) return { ok: false, error: 'no workspace resolved for the needs-you queue' };
+  const f = needsFileFor(w);
+  let queued = [];
+  if (f && fs.existsSync(f)) {
+    let text;
+    try { text = fs.readFileSync(f, 'utf8'); } catch { return { ok: false, error: 'the needs-you queue file is unreadable — file-mode state error, not empty' }; }
+    try {
+      const parsed = JSON.parse(text);
+      if (!Array.isArray(parsed)) return { ok: false, error: 'the needs-you queue file is not a JSON array — corrupt state, not empty' };
+      queued = parsed;
+    } catch { return { ok: false, error: 'the needs-you queue file is not valid JSON — corrupt state, not empty' }; }
+  }
+  let derived = [];
+  try { derived = deriveNeeds(w); } catch { return { ok: false, error: 'could not derive needs from file-mode state' }; }
+  const seen = new Set(queued.map((n) => n && n.run_id).filter(Boolean));
+  const all = queued.concat(derived.filter((n) => !seen.has(n.run_id)));
+  const items = all.map((n) => ({
+    run_id: n.run_id || null, kind: n.kind || 'question', initiative_id: n.initiative_id || null,
+    question: n.question || n.t || '(unstated)', derived: !!n.derived, doc: n.doc || null,
+    deliverable: n.deliverable || null,
+  }));
+  if (!items.length) return { ok: true, empty: true };
+  return { ok: true, empty: false, data: { items } };
+}
+function buildConsole(name, w, root) {
+  const stateDir = stateDirFor(w);
+  const snapshotDir = latestSnapshotDir(root);
+  if (name === 'needs') return needsResult(w);
+  if (name === 'metrics') return consoleState.metrics({ stateDir, snapshotDir });
+  if (name === 'radar') return consoleState.radar({ stateDir, snapshotDir });
+  return { ok: false, error: 'unknown console surface: ' + name };
+}
+
+// ── Session search: episodic recall over this workspace's own scrollback. ─────────────
+// Every session's scrollback is already mirrored to disk (a 200 KB ring per session), which
+// makes it a searchable record of what past runs actually did — the gap `get_agent_runs`
+// leaves open, since it returns structured rows and no run text. An agent that cannot recall
+// what it tried repeats it, and repeated corrections are exactly the north star (D10).
+//
+// Two invariants:
+//  - Scoped to ONE workspace by root. Workspace A never reads workspace B's history (R1/R3).
+//  - Secrets are scrubbed from every emitted line. Scrollback holds whatever the agent printed,
+//    so D08's never-log-headers discipline applies to what this surface hands back. Matching
+//    runs against the SCRUBBED text, so this endpoint cannot be used to grep a token out.
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|[\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+const SECRETS = [
+  [/\b(authorization|x-api-key|api-key|cookie|set-cookie)(\s*:\s*)\S+/gi, '$1$2«redacted»'],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi, 'Bearer «redacted»'],
+  [/\beyJ[A-Za-z0-9._-]{20,}/g, '«redacted-jwt»'],
+  [/\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, '«redacted-key»'],
+  [/\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{16,}/g, '«redacted-token»'],
+  [/\bservice_role[A-Za-z0-9_-]*\s*[:=]\s*\S+/gi, 'service_role «redacted»'],
+];
+function scrub(line) {
+  let out = String(line).replace(ANSI, '');
+  for (const [re, to] of SECRETS) out = out.replace(re, to);
+  return out;
+}
+const SEARCH_MAX = 40;
+function searchSessions(w, q, limit = SEARCH_MAX) {
+  const needle = String(q || '').toLowerCase();
+  if (!w || needle.length < 2) return [];
+  let files = [];
+  try { files = fs.readdirSync(SESS_DIR).filter((f) => f.endsWith('.json')); } catch {}
+  const metas = [];
+  for (const f of files) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(SESS_DIR, f), 'utf8'));
+      if (!meta || !meta.id || meta.root !== w.root) continue;   // isolation: this workspace only
+      let mtime = 0;
+      try { mtime = fs.statSync(path.join(SESS_DIR, meta.id + '.scrollback')).mtimeMs; } catch {}
+      metas.push({ meta, mtime });
+    } catch {}
+  }
+  metas.sort((a, b) => b.mtime - a.mtime);               // most recent run first
+  const hits = [];
+  for (const { meta, mtime } of metas) {
+    if (hits.length >= limit) break;
+    let text = '';
+    try { text = fs.readFileSync(path.join(SESS_DIR, meta.id + '.scrollback'), 'utf8'); } catch { continue; }
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length && hits.length < limit; i++) {
+      const clean = scrub(lines[i]);
+      if (!clean.toLowerCase().includes(needle)) continue;
+      hits.push({
+        session_id: meta.id, session: meta.name, agent: meta.agent, state: meta.state,
+        at: mtime ? new Date(mtime).toISOString() : null,
+        before: lines[i - 1] ? scrub(lines[i - 1]).trim().slice(0, 200) : '',
+        line: clean.trim().slice(0, 400),
+        after: lines[i + 1] ? scrub(lines[i + 1]).trim().slice(0, 200) : '',
+      });
+    }
+  }
+  return hits;
+}
+
+// ── Choosing a folder. ────────────────────────────────────────────────────────────────
+// A browser cannot hand back an absolute path (its own directory picker yields a name and a
+// handle, never a path), so "add a repository" would otherwise stay a typed-path field. The
+// server — which runs on the PM's own machine, bound to 127.0.0.1 (D62) — opens the machine's
+// native folder chooser instead and returns only the chosen path. It registers nothing on its
+// own: the client posts the result back through /api/workspaces so every registration keeps
+// going through registerWorkspace's guards.
+let pickerBusy = false;                 // one dialog at a time — a second click must not stack
+const PICK_TIMEOUT = 120_000;
+function runPicker(cmd, args) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: PICK_TIMEOUT, maxBuffer: 1 << 20 }, (err, stdout) => {
+      const out = String(stdout || '').trim();
+      if (err && !out) return resolve({ cancelled: true });   // cancel exits non-zero on every OS
+      resolve({ path: out });
+    });
+  });
+}
+async function pickFolder(startDir) {
+  const start = isDir(startDir || '') ? path.resolve(startDir) : os.homedir();
+  if (process.platform === 'darwin') {
+    if (!commandExists('osascript')) return { unsupported: true };
+    const script = `set d to choose folder with prompt "Choose a repository to open as a workspace" default location POSIX file ${JSON.stringify(start)}\nPOSIX path of d`;
+    return runPicker('osascript', ['-e', script]);
+  }
+  if (process.platform === 'win32') {
+    const ps = commandExists('powershell.exe') ? 'powershell.exe' : (commandExists('pwsh') ? 'pwsh' : null);
+    if (!ps) return { unsupported: true };
+    const script = 'Add-Type -AssemblyName System.Windows.Forms;' +
+      '$d = New-Object System.Windows.Forms.FolderBrowserDialog;' +
+      `$d.SelectedPath = ${JSON.stringify(start)};` +
+      'if ($d.ShowDialog() -eq "OK") { Write-Output $d.SelectedPath }';
+    return runPicker(ps, ['-NoProfile', '-STA', '-Command', script]);
+  }
+  if (commandExists('zenity')) {
+    return runPicker('zenity', ['--file-selection', '--directory', `--filename=${start}${path.sep}`,
+      '--title=Choose a repository to open as a workspace']);
+  }
+  if (commandExists('kdialog')) return runPicker('kdialog', ['--getexistingdirectory', start]);
+  return { unsupported: true };         // headless Linux: the in-app browser stands in
+}
+
+// The in-app folder browser's data source, used when there is no native chooser (and by anyone
+// who prefers it). It widens what the server DISCLOSES beyond the registered workspace roots —
+// consciously: it returns the NAMES of directories only, never file contents, never file names,
+// and the server binds 127.0.0.1 only (D62). readTextDoc's per-workspace guard is untouched;
+// nothing here can read a byte of anything.
+const FS_LIST_MAX = 400;
+function fsList(dir) {
+  const abs = path.resolve(dir && String(dir).trim() ? dir : os.homedir());
+  if (!isDir(abs)) return null;
+  const parent = path.dirname(abs);
+  const entries = [];
+  let ents = [];
+  try { ents = fs.readdirSync(abs, { withFileTypes: true }); }
+  catch { return { path: abs, parent: parent === abs ? null : parent, home: os.homedir(), entries: [], denied: true }; }
+  for (const e of ents.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+    const full = path.join(abs, e.name);
+    entries.push({ name: e.name, path: full, isRepo: fs.existsSync(path.join(full, '.git')) });
+    if (entries.length >= FS_LIST_MAX) break;
+  }
+  return { path: abs, parent: parent === abs ? null : parent, home: os.homedir(), entries, denied: false };
+}
+
+// ── HTTP: static assets + the file/gate APIs. Headers never logged (D08). ─────────────
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.map': 'application/json',
+  '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
+function serveFile(res, file, type, noCache) {
+  fs.readFile(file, (err, buf) => {
+    if (err) { res.writeHead(404); res.end('not found'); return; }
+    const headers = { 'Content-Type': type || TYPES[path.extname(file)] || 'application/octet-stream' };
+    // The app SHELL (index.html + app.js) must revalidate every load: without this a tab left open
+    // across a `git merge` + server restart keeps running the pre-merge JS, so a fix that IS being
+    // served never reaches the screen. `no-cache` = "always revalidate", not "never store".
+    if (noCache) headers['Cache-Control'] = 'no-cache';
+    res.writeHead(200, headers);
+    res.end(buf);
+  });
+}
+function readBody(req) {
+  return new Promise((resolve) => { let b = ''; req.on('data', (c) => (b += c)); req.on('end', () => resolve(b)); });
+}
+function json(res, obj, code = 200) {
+  res.writeHead(code, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(obj));
+}
+
+async function handleRequest(req, res) {
+  const url = new URL(req.url, 'http://localhost');
+  const p = url.pathname;
+
+  if (p === '/' || p === '/index.html') return serveFile(res, path.join(PUB, 'index.html'), null, true);
+  if (p === '/app.js') return serveFile(res, path.join(PUB, 'app.js'), null, true);
+  if (p === '/lib/preview-kind.js') return serveFile(res, path.join(__dirname, 'lib', 'preview-kind.js'));
+  if (p === '/styles.css') return serveFile(res, path.join(PUB, 'styles.css'));
+  // xterm assets straight from node_modules (offline; no CDN)
+  if (p === '/vendor/xterm.js') return serveFile(res, path.join(XROOT, 'xterm', 'lib', 'xterm.js'));
+  if (p === '/vendor/xterm.css') return serveFile(res, path.join(XROOT, 'xterm', 'css', 'xterm.css'));
+  if (p === '/vendor/addon-fit.js') return serveFile(res, path.join(XROOT, 'addon-fit', 'lib', 'addon-fit.js'));
+  if (p === '/vendor/addon-web-links.js') return serveFile(res, path.join(XROOT, 'addon-web-links', 'lib', 'addon-web-links.js'));
+
+  if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
+  if (p === '/api/workspaces' && req.method === 'POST') {
+    // How `pmos` in another repo becomes another workspace (R1). Local-only, like every
+    // route here — the server binds 127.0.0.1 and this only records a path.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    if (!body.root) return json(res, { ok: false, error: 'root is required' }, 400);
+    const w = registerWorkspace(body.root, body.name);
+    if (!w) return json(res, { ok: false, error: `not a directory: ${body.root}` }, 400);
+    // tell any open client to switch — otherwise the browser refocuses the old tab and the
+    // PM sees the previous repo, which is precisely the reported defect
+    if (body.focus !== false) broadcast({ t: 'focus', ws: w.id });
+    return json(res, { ok: true, workspace: { ...w, home: w.root === SELF_ROOT, shape: wsShape(w.root) } });
+  }
+  if (p === '/api/workspaces/forget' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); } catch {}
+    const ok = forgetWorkspace(body.id);
+    return json(res, { ok, error: ok ? undefined : 'unknown workspace, the home workspace, or it still owns sessions' }, ok ? 200 : 409);
+  }
+  if (p === '/api/pick-folder' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); } catch {}
+    if (pickerBusy) return json(res, { ok: false, busy: true, error: 'a folder chooser is already open' }, 409);
+    pickerBusy = true;
+    let r;
+    try { r = await pickFolder(body.start); } catch { r = { unsupported: true }; }
+    finally { pickerBusy = false; }
+    if (r.unsupported) return json(res, { ok: false, unsupported: true, error: 'no native folder chooser on this system' });
+    if (r.cancelled || !r.path) return json(res, { ok: false, cancelled: true });
+    const root = path.resolve(r.path);
+    if (!isDir(root)) return json(res, { ok: false, error: `not a directory: ${root}` }, 400);
+    return json(res, { ok: true, root });
+  }
+  if (p === '/api/fs/list') {
+    const listing = fsList(url.searchParams.get('path'));
+    if (!listing) return json(res, { ok: false, error: 'not a directory' }, 404);
+    return json(res, { ok: true, ...listing });
+  }
+  if (p === '/api/tree') {
+    const w = getWs(url.searchParams.get('ws'));
+    return json(res, { ws: w ? w.id : null, roots: w ? libraryTree(w.root) : [] });
+  }
+  if (p === '/api/library') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ws: null, shape: 'plain', roots: [], initiatives: [], ungrouped: [], knowledge: [], governance: [] });
+    return json(res, { ws: w.id, ...library(w.root) });
+  }
+  if (p === '/api/surface') {
+    // On-demand P/D/M/R surface, derived through the local state adapter only (no network).
+    // Always 200: ok=false + the contract's missing[] is how the client renders can't-produce.
+    const name = url.searchParams.get('name') || 'initiatives';
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    let surface = null;
+    try { surface = buildSurface(name, root, w); } catch { surface = null; }
+    const contract = checkSurface(name, surface || {});
+    return json(res, { ok: contract.pass, name, surface: contract.pass ? surface : null, contract });
+  }
+  // ── scheduled tasks ──
+  // The picker's source: file-driven skills. `kind` is carried for internal/back-compat consumers,
+  // but the New Skill flow + the scheduled lens never render it — one concept, no user-facing kind.
+  if (p === '/api/tasks') return json(res, { tasks: loadTasks().map((t) => ({ id: t.id, label: t.label, skill: t.skill, kind: t.kind })) });
+  // ── skills (workspace-skill-authoring): the ONE-concept surface + the New Skill flow ──
+  // GET lists every skill with NO kind field — from the user's view there is just a skill.
+  if (p === '/api/skills' && req.method === 'GET') {
+    const skills = loadTasks().map((t) => ({ id: t.id, label: t.label, skill: t.skill,
+      description: t.description || '', output: t.output || [], source: t.source || 'builtin' }));
+    return json(res, { skills });
+  }
+  // POST scaffolds a well-formed .skill file from name + "what it should do" + the output shape.
+  // A GUI replaces editing server code; user skills default to running as a claude PTY session.
+  if (p === '/api/skills' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const built = skillStore.scaffoldSkill(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    if (loadTasks().some((t) => t.id === built.slug)) return json(res, { ok: false, error: `a skill named "${built.slug}" already exists` }, 409);
+    try { fs.mkdirSync(USER_SKILLS_DIR, { recursive: true }); fs.writeFileSync(path.join(USER_SKILLS_DIR, built.slug + '.skill'), built.content); }
+    catch (e) { return json(res, { ok: false, error: 'could not write the skill file' }, 500); }
+    return json(res, { ok: true, skill: { id: built.slug, label: built.label, skill: built.slug,
+      description: built.description, output: built.output, source: 'user' } });
+  }
+  // POST /draft — the POWER-UP: scaffold the file, then spawn a LOCAL claude session (on the PM's
+  // subscription, D54) that refines the skill file in place, grounded in the description + local data.
+  // Always leaves a valid file even where claude is absent; the session is honest about not starting.
+  if (p === '/api/skills/draft' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const built = skillStore.scaffoldSkill(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    if (loadTasks().some((t) => t.id === built.slug)) return json(res, { ok: false, error: `a skill named "${built.slug}" already exists` }, 409);
+    try { fs.mkdirSync(USER_SKILLS_DIR, { recursive: true }); fs.writeFileSync(path.join(USER_SKILLS_DIR, built.slug + '.skill'), built.content); }
+    catch { return json(res, { ok: false, error: 'could not write the skill file' }, 500); }
+    const w = getWs(body.ws);
+    const rel = path.relative(w ? w.root : SELF_ROOT, path.join(USER_SKILLS_DIR, built.slug + '.skill'));
+    const prompt = `Refine the PMOS workspace skill file at ${rel}. It was scaffolded from this ask: ` +
+      `"${built.description || built.label}". Keep the frontmatter shape (name, label, description, run: agent, ` +
+      `agent: claude, and an output list = the sections it must ALWAYS produce). Sharpen the body into a concrete, ` +
+      `repeatable procedure grounded in THIS repository's local files and tools only (no network). Then stop.`;
+    const s = spawnSession({ name: 'draft: ' + built.slug, agent: 'claude', ws: body.ws,
+      origin: 'skill-draft:' + built.slug, initialInput: prompt + '\r' });
+    const started = s.state !== 'exited';
+    return json(res, { ok: true, started, sessionId: s.id,
+      reason: started ? '' : (s.note || 'could not start a claude session'),
+      skill: { id: built.slug, label: built.label, skill: built.slug,
+        description: built.description, output: built.output, source: 'user' } });
+  }
+  if (p === '/api/schedules' && req.method === 'GET') {
+    const wsFilter = getWs(url.searchParams.get('ws'));
+    const id = wsFilter ? wsFilter.id : null;
+    const list = readSchedules().filter((s) => !id || s.ws === id).map((s) => ({ ...s, next: scheduleLogic.nextRun(s) }));
+    return json(res, { schedules: list, now: nowISO() });
+  }
+  if (p === '/api/schedules' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    if (!taskById(body.task || body.skill)) return json(res, { ok: false, error: 'that task has no backing skill' }, 400);
+    const norm = scheduleLogic.normalizeSchedule(body);
+    if (!norm.ok) return json(res, { ok: false, error: norm.error }, 400);
+    const w = getWs(body.ws);
+    const sched = { id: 'sc-' + Date.now().toString(36), ws: w ? w.id : wsId(SELF_ROOT), ...norm.schedule, lastRun: null, lastStatus: null };
+    sched.nextRun = scheduleLogic.nextRun(sched);
+    const list = readSchedules(); list.unshift(sched); writeSchedules(list);
+    return json(res, { ok: true, schedule: sched });
+  }
+  if (p === '/api/schedules/update' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const list = readSchedules(); const s = list.find((x) => x.id === body.id);
+    if (!s) return json(res, { ok: false, error: 'no such schedule' }, 404);
+    if (typeof body.enabled === 'boolean') s.enabled = body.enabled;
+    for (const k of ['name', 'cadence', 'day', 'dayOfMonth', 'time', 'task', 'skill']) if (body[k] != null) s[k] = body[k];
+    s.nextRun = scheduleLogic.nextRun(s); writeSchedules(list);
+    return json(res, { ok: true, schedule: s });
+  }
+  if (p === '/api/schedules/delete' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    writeSchedules(readSchedules().filter((s) => s.id !== body.id));
+    return json(res, { ok: true });
+  }
+  if (p === '/api/schedules/run' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const s = readSchedules().find((x) => x.id === body.id);
+    if (!s) return json(res, { ok: false, error: 'no such schedule' }, 404);
+    return json(res, { ok: true, result: fireSchedule(s) });   // run-now = the exact fire path
+  }
+  if (p === '/api/schedules/check' && req.method === 'POST') return json(res, { ok: true, fired: checkDueSchedules() });
+  if (p === '/api/deliverable') {
+    const id = String(url.searchParams.get('id') || '');
+    if (!/^[\w.-]+$/.test(id) || id.includes('..')) { res.writeHead(400); return res.end('bad id'); }
+    let md; try { md = fs.readFileSync(path.join(DELIV_DIR, id + '.md'), 'utf8'); } catch { res.writeHead(404); return res.end('not found'); }
+    res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' }); return res.end(md);
+  }
+  if (p === '/api/sessions') return json(res, { sessions: sessionList() });
+  if (p === '/api/doc') {
+    const w = getWs(url.searchParams.get('ws'));
+    const doc = w ? readTextDoc(w.root, url.searchParams.get('path') || '') : null;
+    if (doc == null) { res.writeHead(404); return res.end('not a readable text document in this workspace'); }
+    // HTML is served as text/plain — the client renders it sandboxed on demand, never as live markup.
+    const ctype = doc.kind === 'markdown' ? 'text/markdown; charset=utf-8' : 'text/plain; charset=utf-8';
+    res.writeHead(200, { 'Content-Type': ctype, 'X-Doc-Kind': doc.kind }); return res.end(doc.text);
+  }
+  if (p === '/api/asset') {
+    // Stream a repo-relative IMAGE from the workspace, guarded (R3). Image MIME allowlist only — no
+    // arbitrary file leaves through here; traversal / cross-workspace paths 404 (insideRoot). nosniff +
+    // a script-blocking CSP neutralise a scripted SVG opened directly. This endpoint is the ONLY way an
+    // image reaches the reader, and it never touches a remote URL — the no-beacon invariant (R4).
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) { res.writeHead(404); return res.end('no workspace'); }
+    const full = path.resolve(w.root, url.searchParams.get('path') || '');
+    if (!insideRoot(w.root, full)) { res.writeHead(404); return res.end('outside workspace'); }
+    const mime = preview.imageMime(path.basename(full));
+    if (!mime) { res.writeHead(404); return res.end('not a servable asset'); }
+    return fs.readFile(full, (err, buf) => {
+      if (err) { res.writeHead(404); return res.end('not found'); }
+      res.writeHead(200, {
+        'Content-Type': mime,
+        'X-Content-Type-Options': 'nosniff',
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+      });
+      res.end(buf);
+    });
+  }
+  if (p === '/api/needs') return json(res, { needs: readNeeds(getWs(url.searchParams.get('ws'))) });
+  if (p === '/api/console') {
+    // Read-only console surfaces (needs-you · radar · metrics) over file-mode state (D64 Track B).
+    // Discriminated result: {ok:true,empty} genuinely nothing · {ok:false,error} a broken read the
+    // client MUST render red — never a green empty on a failed read (honesty by construction).
+    const name = url.searchParams.get('name') || 'radar';
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    let out;
+    try { out = buildConsole(name, w, root); }
+    catch (e) { out = { ok: false, error: 'console read failed: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+    return json(res, { name, ...out });
+  }
+  if (p === '/api/search') {
+    // Episodic recall over this workspace's own past sessions. Localhost only, like everything
+    // else here — an agent running in a pane can curl it to check what an earlier run tried.
+    // An unknown ws resolves to the home workspace, like every other endpoint here — so an
+    // unrecognised id can only ever see LESS history, never another repo's.
+    const w = getWs(url.searchParams.get('ws'));
+    const q = String(url.searchParams.get('q') || '').trim();
+    if (q.length < 2) return json(res, { ok: false, error: 'a query of at least 2 characters is required', hits: [] }, 400);
+    const hits = searchSessions(w, q);
+    return json(res, { ok: true, q, workspace: w.name, hits, truncated: hits.length >= SEARCH_MAX });
+  }
+  if (p === '/api/gate' && req.method === 'POST') {
+    // The PMOS Acceptance/Review vocabulary in file mode (R5). NEVER automatic — this is
+    // only reached by an explicit PM click, and it just records the decision.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    if (!body.action || !body.run_id) return json(res, { ok: false, error: 'action and run_id are required' }, 400);
+    const w = getWs(body.ws);
+    const rec = { at: nowISO(), date: nowISO().slice(0, 10),
+      action: body.action, run_id: body.run_id, initiative_id: body.initiative_id,
+      // `accepted` is the kit's field (D54) — what metrics.py counts for the north star and
+      // throughput. Only the explicit Acceptance action sets it; `approve` is a Review-gate
+      // disposition and leaves it unset. `pm_label` is deliberately NOT derived here: κ labels
+      // are the PM's own word (D40 — never manufacture calibration data from a UI click).
+      accepted: body.action === 'accept' ? true : body.action === 'return' ? false : undefined,
+      note: body.note || '', workspace: w ? w.name : null, root: w ? w.root : null, pm: true };
+    // Record into the workspace's OWN state, creating the kit layout for a PMOS-shaped repo.
+    // If it can't be resolved, still record — but in the server's state/, and say so in the
+    // response so the client can be honest about where the decision landed.
+    let sink = acceptancesFileFor(w, { create: true });
+    const fallback = !sink;
+    if (fallback) sink = path.join(STATE, 'acceptances.jsonl');
+    // FAIL LOUD (D64 Track A2): under D64 the file-mode acceptances log is the SYSTEM OF RECORD.
+    // A swallowed append + {ok:true} would light the gate green over a record that never landed —
+    // exactly the false-green class D64 exists to delete. On write failure return HTTP 500 and
+    // {ok:false}, and do NOT report success. The error text carries no header/secret content (D08).
+    try {
+      fs.appendFileSync(sink, JSON.stringify(rec) + '\n');
+    } catch (e) {
+      warnWriteFail('acceptances.jsonl (Acceptance Gate — system of record)', e);
+      return json(res, { ok: false, error: 'could not record the acceptance — the file-mode system of record is unwritable; the decision was NOT saved', sink, fallback }, 500);
+    }
+    // clear the matching needs entry from the file it actually came from (secondary — best effort,
+    // but never silent: a failure here is surfaced as a visible server error).
+    try {
+      const nf = needsFileFor(w);
+      if (nf && fs.existsSync(nf)) {
+        const needs = JSON.parse(fs.readFileSync(nf, 'utf8'));
+        fs.writeFileSync(nf, JSON.stringify(needs.filter((n) => n.run_id !== body.run_id)));
+      }
+    } catch (e) { warnWriteFail('needs.json (clearing the accepted need)', e); }
+    return json(res, { ok: true, recorded: rec, sink, fallback });
+  }
+  res.writeHead(404); res.end('not found');
+}
+
+// ── Access guard (D62): loopback is token-free; every non-loopback peer needs the bearer token. ──
+// Peer-based: what matters is where the request came FROM, not which listener accepted it. With the
+// remote flag off there is no non-loopback listener, so this is transparent for local dev. Headers
+// and the token are never logged (D08).
+function httpGuard(req, res) {
+  // Origin/Host allowlist FIRST (D64 A1): reject a cross-site / DNS-rebinding request before the
+  // token exemption for loopback can be reached. Header values are never logged (D08).
+  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds })) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: 'forbidden origin/host' }));
+    return;
+  }
+  if (!remoteAccess.authorize({ remoteAddress: req.socket.remoteAddress,
+      presentedToken: remoteAccess.extractHttpToken(req.headers), expectedToken: TOKEN })) {
+    res.writeHead(401, { 'Content-Type': 'application/json', 'WWW-Authenticate': 'Bearer' });
+    res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+    return;
+  }
+  return handleRequest(req, res);
+}
+const server = http.createServer(httpGuard);
+
+// ── WebSocket: the attach protocol. ───────────────────────────────────────────────────
+// noServer mode so the SAME peer-based token guard runs on the upgrade handshake BEFORE the socket
+// is accepted, and so a second (tailnet) listener can share this exact WS handling.
+const wss = new WebSocketServer({ noServer: true });
+function handleUpgrade(req, socket, head) {
+  // Same origin/host allowlist on the WS upgrade handshake (D64 A1): a cross-origin page must not be
+  // able to open ws://127.0.0.1:<port> and spawn/type into a shell. Rejected BEFORE the socket is
+  // accepted, and before loopback's token exemption applies. Header values never logged (D08).
+  if (!remoteAccess.checkHostOrigin({ origin: req.headers.origin, host: req.headers.host, binds: BIND.binds })) {
+    socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+    return;
+  }
+  if (!remoteAccess.authorize({ remoteAddress: socket.remoteAddress,
+      presentedToken: remoteAccess.extractWsToken(req), expectedToken: TOKEN })) {
+    socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+    socket.destroy();     // reject the upgrade; nothing about the request is logged (D08)
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+}
+server.on('upgrade', handleUpgrade);
+wss.on('connection', (ws) => {
+  ws.attached = new Set();
+  allClients.add(ws);
+  // Per-connection rate limits (D64 A3) to bound abuse if this socket is ever reached by something
+  // hostile. Sized to be invisible to a human at an interactive terminal: SPAWN allows a burst of 8
+  // then ~1 every 2s; INPUT allows a big burst (pastes) then a high steady rate. Excess input is
+  // dropped silently; excess spawns get an honest error rather than piling up shells.
+  ws._rlSpawn = rateLimit.createBucket(8, 0.5);
+  ws._rlInput = rateLimit.createBucket(400, 200);
+  ws.send(JSON.stringify({ t: 'hello', workspaces: wsList(), home: wsId(SELF_ROOT), sessions: sessionList() }));
+
+  ws.on('message', (raw) => {
+    let m; try { m = JSON.parse(raw); } catch { return; }
+    // Gate the shell-spawning / PTY-feeding messages through the buckets before they do any work.
+    if ((m.t === 'new' || m.t === 'respawn') && !rateLimit.take(ws._rlSpawn)) {
+      ws.send(JSON.stringify({ t: 'error', error: 'rate limited: too many session spawns — slow down' }));
+      return;
+    }
+    if (m.t === 'input' && !rateLimit.take(ws._rlInput)) return;   // drop excess input quietly
+    if (m.t === 'attach') {
+      const s = sessions.get(m.id); if (!s) return;
+      s.clients.add(ws); ws.attached.add(s.id);
+      ws.send(JSON.stringify({ t: 'attached', id: s.id, buf: s.buf, state: s.state, cols: s.cols, rows: s.rows }));
+    } else if (m.t === 'detach') {
+      const s = sessions.get(m.id); if (s) s.clients.delete(ws); ws.attached.delete(m.id);
+    } else if (m.t === 'input') {
+      const s = sessions.get(m.id); if (s && s.pty) s.pty.write(m.data);
+    } else if (m.t === 'resize') {
+      const s = sessions.get(m.id); if (s && s.pty) { try { s.pty.resize(m.cols, m.rows); s.cols = m.cols; s.rows = m.rows; } catch {} }
+    } else if (m.t === 'new') {
+      const s = spawnSession({ name: m.name, agent: m.agent || 'shell', cwd: m.cwd, ws: m.ws });
+      ws.send(JSON.stringify({ t: 'created', id: s.id }));
+    } else if (m.t === 'respawn') {
+      const old = sessions.get(m.id); if (!old || old.pty) return;
+      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws });
+      removeSession(old.id);   // the corpse doesn't linger — respawn replaces, not accumulates
+      ws.send(JSON.stringify({ t: 'created', id: s.id }));
+    } else if (m.t === 'kill') {
+      const s = sessions.get(m.id); if (!s) return;
+      if (s.pty) {
+        // A tmux client's .kill() only DETACHES — the process would live on and we'd reattach.
+        // To actually end a live session, kill the tmux session itself (onExit then flips state).
+        if (s.tmux) tmuxKillSession(s.tmux);
+        try { s.pty.kill(); } catch {}                // live → terminate (onExit flips state)
+      } else removeSession(m.id);                      // exited → remove from registry + disk
+    } else if (m.t === 'rename') {
+      renameSession(m.id, m.name);
+    } else if (m.t === 'remove') {
+      removeSession(m.id);
+    }
+  });
+  ws.on('close', () => {
+    allClients.delete(ws);
+    for (const id of ws.attached) { const s = sessions.get(id); if (s) s.clients.delete(ws); }
+  });
+});
+
+loadWorkspaces();
+registerWorkspace(SELF_ROOT);      // the home workspace is always hosted
+writeTmuxConf();                   // must exist before restore may reattach or spawn creates
+restorePersisted();
+
+// A first shell so the workspace is never empty on first run (honest real PTY).
+if ([...sessions.values()].filter((s) => s.pty).length === 0) {
+  spawnSession({ name: 'shell', agent: 'shell' });
+}
+
+if (require.main === module) {
+  // Refuse-to-start is the D62 spine: if the requested remote bind isn't loopback or a tailnet
+  // address, resolveBinds returned {refused} and we exit rather than expose a PTY server publicly.
+  if (BIND.refused) { console.error('✗ ' + BIND.refused); process.exit(1); }
+
+  // First bind is always loopback (the exported `server`); any extra bind is the tailnet address,
+  // served by an additional listener sharing the EXACT same guarded handler + WS upgrade guard.
+  const extraListeners = BIND.binds.slice(1).map(() => {
+    const s = http.createServer(httpGuard); s.on('upgrade', handleUpgrade); return s;
+  });
+  const listeners = [server, ...extraListeners];
+
+  // On `pmos stop` (SIGTERM) or Ctrl-C, flush scrollback and exit cleanly. The tmux sessions
+  // are a SEPARATE daemon and keep running — that is the whole point: relaunch re-attaches live.
+  const shutdown = () => {
+    if (shuttingDown) return; shuttingDown = true;
+    for (const s of sessions.values()) if (s.pty) { try { persist(s); } catch {} }
+    for (const l of listeners) { try { l.close(); } catch {} }
+    process.exit(0);
+  };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  const onError = (e) => {
+    if (e.code === 'EADDRINUSE') {
+      console.error(`✗ port ${PORT} is already in use (another workspace server running?).`);
+      console.error(`  Stop it, or start on another port:  PMOS_WS_PORT=7500 npm start`);
+      process.exit(1);
+    }
+    if (e.code === 'EADDRNOTAVAIL') {
+      console.error(`✗ cannot bind ${e.address || 'the tailnet address'}:${PORT} — that address is not present on this machine. Is Tailscale up?`);
+      process.exit(1);
+    }
+    throw e;
+  };
+  let up = 0;
+  BIND.binds.forEach((addr, i) => {
+    const l = listeners[i];
+    l.on('error', onError);
+    l.listen(PORT, addr, () => {
+      // stdout only — no request/header logging (D08). Banner (incl. any generated token) printed once.
+      if (++up === BIND.binds.length) for (const line of remoteAccess.startupLines(BIND, PORT)) console.log(line);
+    });
+  });
+}
+module.exports = { server, spawnSession, removeSession, renameSession, sessions, libraryTree, readTextDoc,
+  registerWorkspace, forgetWorkspace, workspaces, library, initiativeIndex, fsList,
+  // exported so the suite can assert the D08 invariant end-to-end: the harness parsers consume
+  // scrubbed text, so a secret printed into scrollback must not survive into a rendered value.
+  scrub, harnessOf };