create-pmos 0.6.3 → 0.7.0

package/workspace/server.js

@@ -69,6 +69,11 @@ const remoteAccess = require('./lib/remote-access');   // tailnet bind + token g
 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 gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
+const tmuxControl = require('./lib/tmux-control');     // tmux -CC protocol: the pane's raw stream, so xterm.js keeps its scrollback
+const findingContract = require('./lib/finding-contract');   // what a review finding is + the withheld guard (R3/R7)
+const applyChange = require('./lib/apply-change');            // pure change application, refuse-on-mismatch (R6/R9)
+const correctionRecord = require('./lib/correction-record');  // attribution never inferred (R8)
 // The "home" repo this server manages. In PMOS-self the app ships INSIDE its repo
 // (pmos/workspace) so the parent dir IS the repo. But a kit/tenant copy is installed standalone
 // — `npm i -g` puts it under node_modules/pmos-workspace, or it runs from an npx bundle — and
@@ -95,9 +100,12 @@ 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 SCRATCH_DIR = path.join(STATE, 'scratchpad');   // per-workspace staging text (D62; local-only, gitignored)
+const LAYOUT_DIR = path.join(STATE, 'layouts');       // per-workspace arrangements (R7; local-only, gitignored)
 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)
+const layoutModel = require('./lib/layout');           // the arrangement model — validated on BOTH sides
 // 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
@@ -131,6 +139,14 @@ function sessionEnv() {
   return env;
 }
 const SCROLLBACK = 200_000;                            // bytes of ring buffer per session
+// How often the server re-broadcasts the session list while anything is alive (see heartbeat()).
+// 2s is chosen against what it drives: the state dot and the quiet clock. QUIET_AFTER_MS is 30s, so
+// a 2s cadence puts the worst-case error in "quiet 31s" at one tick — under the rounding the UI
+// already does. Faster buys nothing a human reads; slower makes the dot feel laggy on the flip.
+const LIVENESS_MS = Number(process.env.PMOS_LIVENESS_MS || 2000);
+// The floor on re-parsing a session's transcript (see transcriptHarness). Deliberately looser than
+// the heartbeat: the harness is near-static within a run, while readHarness may parse up to 8 MB.
+const TX_REREAD_MS = Number(process.env.PMOS_TX_REREAD_MS || 3000);
 
 fs.mkdirSync(SESS_DIR, { recursive: true });
 
@@ -584,6 +600,10 @@ function buildSurface(name, root, w) {
 // 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');
+// Reviews the doc-review skill files (workspace-review-and-edit). One JSON per run, written by the
+// skill session, read back by /api/review. Runtime, not the record: the durable artifact of a review
+// is the correction records its dispositions produce, which live in planning/runs/ and are tracked.
+const REVIEW_DIR = path.join(STATE, 'reviews');
 // 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
@@ -701,6 +721,22 @@ function unpersist(id) {
     try { fs.unlinkSync(path.join(SESS_DIR, id + ext)); } catch {}
   }
 }
+// Scrollback written by the PRE-control-mode architecture carries the tmux CLIENT's own screen
+// setup, and that gets replayed verbatim into a fresh xterm.js on attach (public/app.js) — putting
+// the terminal straight back into the alternate buffer, where there is no scrollback. Strip it.
+//
+// The two signatures below are the client's, not an application's: the alt-screen switch IMMEDIATELY
+// followed by the window-title stack push/pop. Verified against every scrollback on disk — each
+// `?1049h` present was followed by exactly `\x1b[22;0;0t`. An inner full-screen app (vim, lazygit)
+// switches buffers without that adjacency, so its own alt-screen use is preserved and still replays
+// correctly — which is what a live TUI pane should do.
+const TMUX_CLIENT_SMCUP = /\x1b\[\?1049h\x1b\[22;0;0t/g;
+const TMUX_CLIENT_RMCUP = /\x1b\[\?1049l\x1b\[23;0;0t/g;
+function stripLegacyClientScreen(buf) {
+  if (!buf) return buf;
+  return buf.replace(TMUX_CLIENT_SMCUP, '').replace(TMUX_CLIENT_RMCUP, '');
+}
+
 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 —
@@ -714,7 +750,7 @@ function restorePersisted() {
       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 {}
+      try { buf = stripLegacyClientScreen(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();
@@ -725,7 +761,9 @@ function restorePersisted() {
       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
+        // seed: this server was DOWN, so output produced in the gap never reached our ring buffer.
+        // Control mode replays no history, so take tmux's — it is the superset (R7 + scrollback).
+        attachPty(s, { seed: true });       // 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';
@@ -783,7 +821,16 @@ function transcriptHarness(s) {
   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;
+  // A re-read FLOOR, separate from the stamp cache above. The stamp only suppresses a re-read when
+  // the transcript has not moved — but a working agent appends constantly, so under the liveness
+  // heartbeat the stamp changes on every tick and readHarness would re-parse up to MAX_BYTES (8 MB)
+  // per active session per push. The floor caps that at one parse per TX_REREAD_MS. The cost of the
+  // floor is that the drill-in's numbers can lag the terminal by up to that interval — acceptable,
+  // because the harness is near-static within a run (the leg-A finding that made it a drill-in and
+  // not a rail). The state dot and the quiet clock do NOT go through here and are never floored.
+  if (s.tx && (now - (s.txReadAt || 0)) < TX_REREAD_MS) return s.tx;
   const h = transcript.readHarness(found.file, scrub);
+  s.txReadAt = now;
   h.cliVersion = found.version || null;
   s.tx = h; s.txStamp = stamp;
   return h;
@@ -828,6 +875,29 @@ function sessionList() {
 function pushSessions() { broadcast({ t: 'sessions', sessions: sessionList() }); }
 function pushWorkspaces() { broadcast({ t: 'workspaces', workspaces: wsList() }); }
 
+// ── The liveness heartbeat. ───────────────────────────────────────────────────────────────────
+// Every other pushSessions() call site is a LIFECYCLE event — spawn, exit, close, rename, note.
+// None of them fires on output, so without this the client's copy of `lastOutputAt` was frozen at
+// the last lifecycle event and only ever aged: every row crossed QUIET_AFTER_MS ~30s after spawn
+// and read `quiet` forever, however hard the agent was working. The server always knew better
+// (appendBuf stamps every byte) — it simply never said so. This is the saying-so.
+//
+// The signals are unchanged. `quiet` still means EXACTLY "no bytes for >= QUIET_AFTER_MS" and
+// still never means "waiting on you" (PRD R1). Nothing new is derived here; an existing truth is
+// merely delivered on a cadence instead of on an accident.
+//
+// Two guards keep an idle machine idle: no connected client and no live session means no push.
+// A workspace left open overnight with everything exited costs one Map scan per tick. The decision
+// is a pure function so the guards are testable without standing up a server that has no clients.
+function shouldHeartbeat(clientCount, sessionStates) {
+  return clientCount > 0 && sessionStates.some((st) => st !== 'exited');
+}
+function heartbeat() {
+  if (!shouldHeartbeat(allClients.size, [...sessions.values()].map((s) => s.state))) return;
+  pushSessions();
+}
+try { const _hb = setInterval(heartbeat, LIVENESS_MS); if (_hb.unref) _hb.unref(); } catch {}
+
 function appendBuf(s, data) {
   s.buf += data;
   if (s.buf.length > SCROLLBACK) s.buf = s.buf.slice(s.buf.length - SCROLLBACK);
@@ -916,14 +986,43 @@ function ensureTmuxSession(name, cmd, workdir, cols, rows) {
     '-x', String(cols || 80), '-y', String(rows || 24), '-c', workdir, '--', cmd]);
   return r.status === 0;
 }
+// The pane id (%0, %1, …) the control client must address for input. One cheap lookup per attach;
+// cached on the session because a pane id is stable for the life of the tmux session.
+function tmuxPaneId(s, name) {
+  if (s.paneId) return s.paneId;
+  const r = tmuxCtl(['display-message', '-p', '-t', name, '#{pane_id}']);
+  const id = (r.stdout || '').trim();
+  if (/^%\d+$/.test(id)) s.paneId = id;
+  return s.paneId || null;
+}
+
+// tmux's OWN history is authoritative for what the pane has shown — and it is a superset of our
+// ring buffer, because output produced while this server was down never reached us at all. Control
+// mode reports only output produced AFTER attach (it is not a history replay), so on a REATTACH we
+// seed the buffer from tmux rather than leaving the pane showing a stale, truncated scrollback.
+function seedFromPaneHistory(s, name) {
+  const r = tmuxCtl(['capture-pane', '-p', '-e', '-J', '-t', name, '-S', '-5000']);
+  if (r.status !== 0 || !r.stdout) return false;
+  const text = r.stdout.replace(/\s+$/, '').replace(/\r?\n/g, '\r\n');
+  if (!text) return false;
+  s.buf = text + '\r\n';
+  s.parsed = null;
+  return true;
+}
+
 // 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) {
+//
+// The client runs in CONTROL MODE (-CC): it never paints a screen, so it never emits the `smcup`
+// that used to trap xterm.js in the alternate buffer with no scrollback. Instead tmux reports the
+// pane's raw bytes as %output, which we forward verbatim — the same stream shape the direct-PTY
+// fallback produces, so xterm.js keeps its own 5000-line scrollback. See lib/tmux-control.js.
+function attachPty(s, { seed = false } = {}) {
   const name = tmuxName(s.id);
   const startedMs = Date.now();
   let p;
   try {
-    p = pty.spawn(TMUX, ['-L', TMUX_SOCK, 'attach-session', '-t', name],
+    p = pty.spawn(TMUX, ['-L', TMUX_SOCK, '-CC', 'attach-session', '-t', name],
       { name: 'xterm-256color', cols: s.cols || 80, rows: s.rows || 24, cwd: s.cwd, env: sessionEnv() });
   } catch (e) {
     // A broken node-pty (e.g. a non-executable spawn-helper) throws synchronously here. This must
@@ -936,16 +1035,42 @@ function attachPty(s) {
     persist(s); pushSessions();
     return null;
   }
-  s.pty = p; s.tmux = name; s.state = 'working';
+  const paneId = tmuxPaneId(s, name);
+  // On a reattach, replace our (possibly stale, possibly truncated) buffer with tmux's own history
+  // BEFORE any live %output lands, so the two never interleave out of order.
+  if (seed) { try { seedFromPaneHistory(s, name); } catch {} }
+
+  // Everything outside this function treats s.pty as a PTY: .write() .resize() .kill() .pid, and
+  // truthiness meaning "live". Control mode changes HOW each is done, not the shape — so the ws
+  // handlers, the kill path and the liveness checks are all untouched.
+  const client = {
+    _client: p,
+    get pid() { return p.pid; },
+    write(data) {
+      if (!paneId) return;
+      for (const c of tmuxControl.sendKeysCommands(paneId, data)) p.write(c);
+    },
+    resize(cols, rows) { p.write(tmuxControl.resizeCommand(cols, rows)); },
+    kill() { try { p.kill(); } catch {} },
+  };
+  s.pty = client; 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 }));
+
+  const parser = tmuxControl.createParser({
+    onOutput: (pane, text) => {
+      if (paneId && pane !== paneId) return;              // only this session's pane
+      if (s._reattempts) s._reattempts = 0;               // a working attach clears the retry budget
+      appendBuf(s, text);
+      for (const c of s.clients) if (c.readyState === 1) c.send(JSON.stringify({ t: 'data', id: s.id, data: text }));
+    },
   });
+  p.onData((d) => parser.feed(d));
+  // The pane follows the control client's DECLARED size, so state it explicitly rather than relying
+  // on the client PTY's own window size.
+  client.resize(s.cols || 80, s.rows || 24);
   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
@@ -1058,6 +1183,61 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
   persist(s); pushSessions(); pushWorkspaces();
   return s;
 }
+
+// New session, optionally on a chosen/created branch. The working tree is SHARED across a repo's
+// sessions, so the checkout is repo-wide — the UI says so. A FAILED checkout must never spawn a
+// session on the wrong branch (rubric hard floor): we return {ok:false} and spawn nothing. Kept as
+// its own function so the checkout-then-maybe-spawn contract is unit-testable without a WS client.
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch }) {
+  if (branch) {
+    const w = getWs(ws);
+    const r = gitInfo.checkout(w.root, branch, { create: !!createBranch });
+    if (!r.ok) return { ok: false, error: r.error };
+    broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
+  }
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws });
+  return { ok: true, session: s };
+}
+
+// ── Scratchpad: per-workspace staging text (R4). Local-only, one file per workspace keyed by the
+// workspace's hashed id (never a caller-supplied path), capped so it can't be used as a blob store.
+const SCRATCH_MAX = 200_000;
+function scratchpadPath(w) { return w ? path.join(SCRATCH_DIR, w.id + '.txt') : null; }
+function readScratchpad(w) {
+  const f = scratchpadPath(w);
+  if (!f) return '';
+  try { return fs.readFileSync(f, 'utf8'); } catch { return ''; }
+}
+function writeScratchpad(w, text) {
+  const f = scratchpadPath(w);
+  if (!f) throw new Error('no workspace');
+  fs.mkdirSync(SCRATCH_DIR, { recursive: true });
+  fs.writeFileSync(f, String(text == null ? '' : text).slice(0, SCRATCH_MAX));
+}
+
+// ── Layouts: per-workspace arrangements (R7). Same shape as the scratchpad above — one file per
+// workspace keyed by the workspace's hashed id, never a caller-supplied path, capped so it can't
+// be used as a blob store. The arrangement belongs to the REPO you opened, so a second repo has
+// its own; it is machine-local and gitignored, not a repo artifact.
+const LAYOUT_MAX = 40_000;
+function layoutPath(w) { return w ? path.join(LAYOUT_DIR, w.id + '.json') : null; }
+// Always returns a usable document: an absent, empty, truncated or hand-mangled file yields the
+// four stock layouts rather than an error, because the alternative is a window the PM cannot use.
+function readLayouts(w) {
+  const f = layoutPath(w);
+  let raw = null;
+  if (f) { try { raw = fs.readFileSync(f, 'utf8'); } catch { raw = null; } }
+  return layoutModel.sanitize(raw);
+}
+function writeLayouts(w, doc) {
+  const f = layoutPath(w);
+  if (!f) throw new Error('no workspace');
+  const clean = layoutModel.sanitize(doc);              // never store what we would not accept back
+  fs.mkdirSync(LAYOUT_DIR, { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(clean).slice(0, LAYOUT_MAX));
+  return clean;
+}
+
 // 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) {
@@ -1394,6 +1574,7 @@ async function handleRequest(req, res) {
   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 === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.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'));
@@ -1497,9 +1678,16 @@ async function handleRequest(req, res) {
     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.`;
+      `"${built.description || built.label}". First read skills/core/SKILL-FORMAT.md (the skill spec) and ` +
+      `follow build-skills/skill-creator.skill (the authoring procedure). Keep the runtime frontmatter shape ` +
+      `unchanged (name, label, description, run: agent, agent: claude, and an output list = the sections it must ` +
+      `ALWAYS produce). Sharpen the BODY into a procedure-first, repeatable procedure grounded in THIS repository's ` +
+      `own files and tools only (no network): a Goal line, then numbered steps each ending on a checkable "Done when:" ` +
+      `condition. Keep the FILING CONTRACT the scaffold wrote — the run must write its deliverable to ` +
+      `workspace/state/deliverables/<run-id>.md and append the structured object to workspace/state/needs.json ` +
+      `(a valid JSON array), never a prose note. Then run the SKILL-FORMAT conformance checklist (items 6-9: ` +
+      `predictability, per-step completion criteria, pruning, leading words) over the body — put no self-check block ` +
+      `in the file itself. 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';
@@ -1553,6 +1741,47 @@ async function handleRequest(req, res) {
     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/git/branches') {
+    // Read-only branch awareness for a workspace. A non-repo returns {ok:false} (never a fake
+    // branch). Fixed git args, no caller input in the read path (R1).
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' });
+    return json(res, gitInfo.branchInfo(w.root));
+  }
+  if (p === '/api/scratchpad' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    try { writeScratchpad(w, body.text); }
+    catch (e) { warnWriteFail('scratchpad', e); return json(res, { ok: false, error: 'could not save scratchpad' }, 500); }
+    return json(res, { ok: true });
+  }
+  if (p === '/api/scratchpad') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    return json(res, { ok: true, text: readScratchpad(w) });
+  }
+  if (p === '/api/layouts' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    let saved;
+    try { saved = writeLayouts(w, body); }
+    catch (e) { warnWriteFail('layouts', e); return json(res, { ok: false, error: 'could not save the layout' }, 500); }
+    // echo what was STORED, not what was sent — the client's copy stays identical to disk even
+    // when sanitize() clamped a size or dropped a key it did not recognise
+    return json(res, { ok: true, layouts: saved.layouts, currentId: saved.currentId });
+  }
+  if (p === '/api/layouts') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const doc = readLayouts(w);
+    return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId });
+  }
   if (p === '/api/doc') {
     const w = getWs(url.searchParams.get('ws'));
     const doc = w ? readTextDoc(w.root, url.searchParams.get('path') || '') : null;
@@ -1649,6 +1878,135 @@ async function handleRequest(req, res) {
     } catch (e) { warnWriteFail('needs.json (clearing the accepted need)', e); }
     return json(res, { ok: true, recorded: rec, sink, fallback });
   }
+  if (p === '/api/review') {
+    // Read a filed review. Latest by default; ?id= for a specific one. Honest-by-construction like
+    // the console surfaces (D64 B2): a broken or contract-failing read returns {ok:false,error} so the
+    // client can render RED — never a calm empty over a review that exists but could not be parsed.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const want = url.searchParams.get('id');
+    let files = [];
+    try { files = fs.readdirSync(REVIEW_DIR).filter((f) => f.endsWith('.json')).sort(); } catch {}
+    if (want && !/^[A-Za-z0-9._-]+$/.test(want)) return json(res, { ok: false, error: 'bad review id' }, 400);
+    const pick = want ? `${want}.json` : files[files.length - 1];
+    if (!pick || !files.includes(pick)) return json(res, { ok: true, empty: true, reviews: files.length });
+
+    let review;
+    try { review = JSON.parse(fs.readFileSync(path.join(REVIEW_DIR, pick), 'utf8')); }
+    catch { return json(res, { ok: false, error: `review '${pick}' is unreadable or not valid JSON` }, 500); }
+
+    // The SAME contract the write path enforces (R3/R7). A review that fails it is surfaced as an
+    // error rather than half-rendered: a malformed finding must never reach the UI, because the UI's
+    // job is to decide whether an Apply control exists.
+    const v = findingContract.validateReview(review);
+    if (!v.ok) return json(res, { ok: false, error: 'this review failed the finding contract', errors: v.errors.slice(0, 12) }, 422);
+
+    // Merge in what the PM has already settled, so a disposed finding renders as settled rather than
+    // being offered twice. Read-only: dispositions live in the correction records, not in the review.
+    const settled = {};
+    try {
+      const txt = fs.readFileSync(path.join(w.root, 'planning', 'runs', 'correction-records.jsonl'), 'utf8');
+      for (const line of txt.split('\n')) {
+        if (!line.trim()) continue;
+        try { const r = JSON.parse(line); if (r && r.finding_title) settled[r.finding_title] = r.disposition; } catch {}
+      }
+    } catch {}
+    const findings = review.findings.map((f) => ({
+      ...f,
+      applyable: findingContract.isApplyable(f),      // the client asks the contract, never re-derives it
+      settled: settled[f.title] || null,
+    }));
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), read: review.read, at: review.at || null, findings, reviews: files.length });
+  }
+  if (p === '/api/review/dispose' && req.method === 'POST') {
+    // The ONLY write path this surface has (workspace-review-and-edit R6/R8/R11). The reader was
+    // designed around there being none, so every guard here is load-bearing rather than ceremony.
+    //
+    // Three dispositions, one endpoint: `apply` and `edit` write the file, `dismiss` writes only
+    // the correction record. Never automatic — reached solely by an explicit PM click, like /api/gate.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+
+    // The finding must satisfy the contract BEFORE anything else looks at it — a malformed
+    // finding never reaches a write, and never grows an Apply (fails closed by construction).
+    const f = body.finding;
+    const v = findingContract.validateFinding(f);
+    if (!v.ok) return json(res, { ok: false, error: 'finding failed the contract', errors: v.errors }, 400);
+
+    const disposition = body.disposition;
+    if (!correctionRecord.DISPOSITIONS.has(disposition)) {
+      return json(res, { ok: false, error: `disposition must be one of ${[...correctionRecord.DISPOSITIONS].join(' | ')}` }, 400);
+    }
+
+    // R7 CONTAINMENT, server side. The client renders no Apply for a withheld finding; this is the
+    // half that survives a tampered or stale client. A withheld finding can only ever be dismissed.
+    const writes = disposition === 'apply' || disposition === 'edit';
+    if (writes && !findingContract.isApplyable(f)) {
+      return json(res, { ok: false, error: 'this finding offers nothing to apply — it is context, and yours to settle' }, 400);
+    }
+
+    let wrote = null;
+    if (writes) {
+      // Path guard, identical to every read on this surface (R12): traversal and cross-workspace
+      // paths are refused before the file is opened, not after.
+      const full = path.resolve(w.root, f.file || '');
+      if (!insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+      if (preview.previewKind(path.basename(full)) !== 'markdown') {
+        return json(res, { ok: false, error: 'only markdown documents are editable here' }, 400);
+      }
+      let current;
+      try { current = fs.readFileSync(full, 'utf8'); }
+      catch { return json(res, { ok: false, error: 'could not read the document' }, 404); }
+
+      // On `edit` the PM's text replaces the agent's — the proposal applied is what the PM saw.
+      const proposal = disposition === 'edit'
+        ? { before: f.proposal.before, after: body.pm_text }
+        : f.proposal;
+
+      // REFUSE ON MISMATCH (sprint criterion 4). The client sends back the exact text it rendered
+      // and the server re-derives it; disagreement means the file moved, or the client is stale or
+      // tampered. Either way the PM would be applying something they never looked at.
+      const m = applyChange.matchesRendered(current, proposal, body.rendered_after);
+      if (!m.ok) return json(res, { ok: false, error: 'refused: ' + m.reason, detail: m.detail || null }, 409);
+
+      // FAIL LOUD (D64 Track A2, same stance as /api/gate): a swallowed write returning {ok:true}
+      // would tell the PM their edit landed when it did not. No header/secret content in the error (D08).
+      try { fs.writeFileSync(full, m.text); }
+      catch (e) {
+        warnWriteFail('document apply (' + f.file + ')', e);
+        return json(res, { ok: false, error: 'could not write the document — nothing was changed' }, 500);
+      }
+      wrote = f.file;
+    }
+
+    // R8: the record is built only where attribution is KNOWN. buildRecord refuses anything that
+    // would need inference, and a refusal here means no record is written at all — never a guess.
+    const built = correctionRecord.buildRecord({
+      run_id: body.run_id, initiative_id: body.initiative_id, finding: f, disposition,
+      pm_text: body.pm_text, reason: body.reason, reason_note: body.reason_note,
+      pm: body.pm || 'wawan', at: nowISO(),
+    });
+    if (!built.ok) {
+      // The document may already have been written — say so rather than imply a clean failure.
+      return json(res, { ok: false, error: 'no correction record written (attribution would have to be inferred)', errors: built.errors, wrote }, 400);
+    }
+
+    // Curated record, tracked and append-only — deliberately NOT stateDirFor()'s runtime directory
+    // (PRD open question 1; pm-decisions.md 491–503 keeps that boundary the PM's to settle).
+    const sink = path.join(w.root, 'planning', 'runs', 'correction-records.jsonl');
+    try {
+      fs.mkdirSync(path.dirname(sink), { recursive: true });
+      fs.appendFileSync(sink, JSON.stringify(built.record) + '\n');
+    } catch (e) {
+      warnWriteFail('correction-records.jsonl (the north-star numerator)', e);
+      return json(res, { ok: false, error: 'the document changed but the correction record could NOT be written', wrote }, 500);
+    }
+    return json(res, { ok: true, wrote, recorded: built.record, sink });
+  }
   res.writeHead(404); res.end('not found');
 }
 
@@ -1724,7 +2082,10 @@ wss.on('connection', (ws) => {
   // 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: HOME_ENABLED ? wsId(SELF_ROOT) : null, sessions: sessionList() }));
+  // quietAfterMs travels with hello so the client derives `quiet` from the SAME threshold the
+  // server does. It was a re-typed literal in app.js — two copies of a number that must agree.
+  ws.send(JSON.stringify({ t: 'hello', workspaces: wsList(), home: HOME_ENABLED ? wsId(SELF_ROOT) : null,
+    sessions: sessionList(), quietAfterMs: harness.QUIET_AFTER_MS }));
 
   ws.on('message', (raw) => {
     let m; try { m = JSON.parse(raw); } catch { return; }
@@ -1745,8 +2106,9 @@ wss.on('connection', (ws) => {
     } 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 }));
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch });
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: 'branch: ' + r.error })); return; }
+      ws.send(JSON.stringify({ t: 'created', id: r.session.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 });
@@ -1832,4 +2194,10 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   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 };
+  scrub, harnessOf,
+  // the legacy-scrollback migration, exported so the suite can assert BOTH halves: the tmux
+  // client's preamble is stripped, an inner TUI's own alt-screen use is not.
+  stripLegacyClientScreen,
+  // the liveness heartbeat's guard, exported pure so the "idle machine stays idle" half can be
+  // asserted without a server that has no clients (the suite always has both).
+  shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS };