create-pmos 0.6.4 → 0.7.0

package/workspace/server.js

@@ -70,6 +70,10 @@ const rateLimit = require('./lib/rate-limit');         // per-connection token b
 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
@@ -97,9 +101,11 @@ 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
@@ -133,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 });
 
@@ -586,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
@@ -703,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 —
@@ -716,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();
@@ -727,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';
@@ -785,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;
@@ -830,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);
@@ -918,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
@@ -938,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
@@ -1092,6 +1215,29 @@ function writeScratchpad(w, text) {
   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) {
@@ -1428,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'));
@@ -1531,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';
@@ -1609,6 +1763,25 @@ async function handleRequest(req, res) {
     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;
@@ -1705,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');
 }
 
@@ -1780,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; }
@@ -1889,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 };

package/workspace/skills/doc-review.skill

@@ -0,0 +1,114 @@
+---
+name: doc-review
+label: "Review documents"
+description: "Read the planning documents you name and report only defects the artifact cannot detect about itself — never lint. Each finding carries its evidence and, where one exists, a proposed change you dispose of."
+run: agent
+agent: claude
+output:
+  - Read
+  - Findings
+  - Withheld
+---
+
+You are running the "Review documents" skill in this PMOS workspace (local, file mode). Work only
+from this repository's own files, git, and CLIs — no network (D54).
+
+Goal: surface defects in the named documents that **the artifact cannot detect about itself**, and
+file them as a contract-checked review the PM disposes of one at a time.
+
+## What counts as a finding — and what does not
+
+The whole value of this review is that the PM keeps reading it. A review that reports what a linter
+already reports becomes a linter with manners, and gets ignored by Thursday.
+
+**Report only defects the document cannot detect about itself.** The four kinds that recur:
+
+- **A metric that does not measure its own claim** — a PRD bets on an outcome, then defines success as
+  a capability demo, so it can score full marks and move the outcome not at all.
+- **An anchor that cannot score wrong** — a rubric dimension whose anchors award credit for descoping,
+  or that cannot distinguish a correct implementation from an absent one.
+- **A gate that scripts away its own question** — a rubric prescribing the Acceptance Gate as the same
+  checklist it already scored, turning D12's strategic judgement into a second review pass.
+- **A constraint contradicted elsewhere** — a non-goal or design rule in one shipped document that
+  silently rules out what another document proposes.
+
+**NEVER report** — these belong to lint and the Frontmatter Gate, and emitting them fails the
+contract outright: frontmatter or schema validity · broken links or missing paths · string/regex
+matches · counting occurrences · spelling, typos, formatting.
+
+**Say nothing when there is nothing to say.** An empty findings list is a correct and valued outcome.
+Do not pad a review to look thorough — a false finding costs the PM more than a missed one, because
+they pay for it every time.
+
+## The withheld class — where you must NOT propose a fix
+
+Some defects are not defects. Before proposing any change, ask: **would applying this close a
+question the PM has parked, or overwrite a decision they recorded?** Check `pm-decisions.md`,
+`DECISIONS.md`, and the document's own history.
+
+If yes, the finding is **withheld**: `"withheld": true`, `"proposal": null`, and a
+`"withheld_reason"` saying why it is the PM's to settle. The client renders no Apply control for it —
+the absence of the button is the guard, so a withheld finding carrying a proposal is rejected by the
+contract, not merely discouraged.
+
+The recorded instance: `CLAUDE.md` points file-mode state at `pmos/state/*.jsonl`, which looks stale
+and is not — it is a measured open question (`pm-decisions.md` 491–503).
+
+## Procedure
+
+1. **Take the scope.** Read exactly the documents the PM named. Do not widen it.
+   *Done when:* every named path has been read in full, and you can list them.
+
+2. **Find, then cut.** For each document, ask the four questions above. Then remove every candidate
+   that a regex could have found, and every one you cannot evidence to a specific line.
+   *Done when:* each surviving finding names, in one sentence, what the artifact cannot see about
+   itself — the `self_undetectable` field. If you cannot write that sentence, drop the finding.
+
+3. **Propose, or withhold.** Where a change would genuinely fix it, write `proposal.before` as text
+   copied **verbatim** from the file and `proposal.after` as its replacement. `before` must appear in
+   the file **exactly once** — the apply path refuses a stale or ambiguous anchor rather than
+   guessing. Where the withheld test fires, propose nothing.
+   *Done when:* every finding either carries an exact-match proposal or is explicitly withheld.
+
+4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`), then write
+   `workspace/state/reviews/<run-id>.json` with exactly this shape:
+
+   ```json
+   {
+     "at": "<ISO 8601>",
+     "read": ["planning/prd/example-prd.md"],
+     "findings": [
+       {
+         "title": "One sentence, the defect stated plainly.",
+         "file": "planning/prd/example-prd.md",
+         "kind": "metric-claim-mismatch",
+         "argument": "Why this is a defect — the reasoning, not a restatement.",
+         "self_undetectable": "What this artifact cannot see about itself.",
+         "evidence": [{ "file": "planning/prd/example-prd.md", "line": 17 }],
+         "withheld": false,
+         "proposal": { "before": "<verbatim text from the file>", "after": "<replacement>" }
+       }
+     ]
+   }
+   ```
+
+   `withheld` is a required boolean on every finding and is never inferred. A withheld finding sets
+   `"proposal": null` and adds `"withheld_reason"`.
+   *Done when:* the file is valid JSON and `GET /api/review` returns `ok: true` for it. If it returns
+   `422`, the contract rejected a finding — fix it; do not file it anyway.
+
+5. **Tell the PM it is ready.** Read `workspace/state/needs.json` (a missing file is `[]`), append
+   exactly this object, and write the whole array back — it must stay a valid JSON array:
+
+   ```json
+   {"run_id":"<run-id>","kind":"review","initiative_id":"workspace-review-and-edit","question":"Document review — <n> findings"}
+   ```
+   *Done when:* `needs.json` is a valid array containing the new object.
+
+## Output contract — produce EXACTLY these sections
+
+- **Read** — the documents actually read, one per line.
+- **Findings** — one line per finding: the title and its `file:line`. `None this review.` if empty,
+  which is a good outcome, not a failed run.
+- **Withheld** — findings deliberately left for the PM, with the one-line reason. `None this review.`
+  if empty.