create-pmos 0.8.0 → 0.10.0

package/workspace/server.js

@@ -71,7 +71,9 @@ const consoleState = require('./lib/console-state');   // read-only console surf
 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 relatedDocs = require('./lib/related-docs');            // which documents a change puts out of step (R5/R6)
 const applyChange = require('./lib/apply-change');            // anchored + whole-document saves, refuse-on-stale
+const sessionState = require('./lib/session-state');   // the cadence×turn join — validated on BOTH sides
 // 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
@@ -301,6 +303,27 @@ function libraryTree(root) {
   if (loose.length) roots.push({ name: '(root)', path: '', dirs: [], docs: loose });
   return roots;
 }
+// Every markdown document under the root, as repo-relative paths. Used by alignment to decide which
+// documents a change might affect (R6) — it needs a flat list, and libraryTree returns a nested shape
+// for the library lens. Bounded: a repository is not an excuse to read forever.
+function markdownDocs(root, limit = 800) {
+  const out = [];
+  const walk = (dir, rel, depth) => {
+    if (out.length >= limit || depth > 8) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (out.length >= limit) return;
+      if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) walk(full, r, depth + 1);
+      else if (preview.previewKind(e.name) === 'markdown') out.push(r);
+    }
+  };
+  walk(root, '', 0);
+  return out;
+}
 // every top-level file (md + non-md), so the folder lens shows the real root, not a curated subset
 function looseFiles(root) {
   let ents = [];
@@ -738,7 +761,14 @@ function restorePersisted() {
   // 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; }
+  try { files = fs.readdirSync(SESS_DIR).filter((f) => f.endsWith('.json')); } catch { files = []; }
+  // Floor the counter on the FILENAMES first, before any parse. Doing it per-record meant a single
+  // unreadable file left `seq` low enough to re-issue an id another record already owned — and the
+  // next spawn would then overwrite that record's metadata and scrollback.
+  for (const f of files) {
+    const n = Number(f.replace(/\.json$/, '').split('-')[1]);
+    if (Number.isFinite(n) && n >= seq) seq = n + 1;
+  }
   for (const f of files) {
     try {
       const meta = JSON.parse(fs.readFileSync(path.join(SESS_DIR, f), 'utf8'));
@@ -765,6 +795,66 @@ function restorePersisted() {
       const n = Number(String(meta.id).split('-')[1]); if (Number.isFinite(n) && n >= seq) seq = n + 1;
     } catch {}
   }
+  adoptOrphanTmuxSessions();
+}
+
+// The registered workspace a directory belongs to — the LONGEST matching root, so a repo opened
+// inside another repo wins over its parent. Null when no registered workspace contains it.
+function workspaceForPath(dir) {
+  if (!dir) return null;
+  let best = null;
+  for (const w of workspaces.values()) {
+    if (!insideRoot(w.root, dir)) continue;
+    if (!best || w.root.length > best.root.length) best = w;
+  }
+  return best;
+}
+
+// A live pane on our socket that NO restored record claims is still the PM's running agent — the
+// server simply lost its note of it (state/sessions cleared or partly unreadable, a record written
+// by an older build, a metadata write that never landed). Before this, those panes were invisible:
+// the workspace came back apparently empty while the work was still running underneath, which is
+// the "my sessions did not come back" defect. Adopting them puts every live pane back on screen,
+// filed under the workspace its own directory belongs to — and it means an orphan is claimed
+// DELIBERATELY, by the pane it actually is, rather than by accident through an id collision.
+// What a recovered pane should call its agent. A shell (whatever the PM's login shell is) reads
+// `shell`, exactly as a spawned one does; anything else keeps its own command name so the row does
+// not claim to be a shell it is not. An unreadable start command falls back to `shell` — the
+// label that promises the least.
+function adoptedAgent(cmd) {
+  const base = path.basename(String(cmd || '').split(/\s+/)[0] || '');
+  if (!base) return 'shell';
+  if (base === path.basename(SHELL) || /^(sh|bash|zsh|fish|dash|powershell\.exe|cmd\.exe)$/i.test(base)) return 'shell';
+  return base;
+}
+function adoptOrphanTmuxSessions() {
+  if (!TMUX) return 0;
+  const claimed = new Set([...sessions.values()].map((s) => s.tmux).filter(Boolean));
+  let adopted = 0;
+  for (const t of tmuxList().sort((a, b) => a.created - b.created)) {
+    if (!t.name.startsWith('pmos-') || claimed.has(t.name)) continue;
+    const dir = t.dir && isDir(t.dir) ? path.resolve(t.dir) : null;
+    // Where it belongs: the workspace containing its pane directory; else — because a pane the PM
+    // can see must be a pane the PM can reach — that directory is registered as one, exactly as
+    // `pmos <path>` would. Only the home workspace is assumed when there is no readable directory.
+    const w = workspaceForPath(dir) || (dir && registerWorkspace(dir)) || homeWorkspace();
+    if (!w) continue;
+    const id = nextSessionId();
+    // The agent is the pane's own start command, not a guess: tmux spawned it directly (see
+    // createTmuxSession's `-- cmd`), so a `claude` pane comes back labelled `claude`.
+    const agent = adoptedAgent(t.cmd);
+    const s = {
+      id, ws: w.id, root: w.root, name: `recovered ${agent}`, agent,
+      origin: null, cwd: dir && insideRoot(w.root, dir) ? dir : w.root,
+      state: 'working', pty: null, tmux: t.name, note: '', buf: '',
+      cols: 80, rows: 24, clients: new Set(), created: nowISO(), recovered: true,
+    };
+    sessions.set(id, s);
+    attachPty(s, { seed: true });          // its history comes from tmux — ours was never written
+    persist(s);
+    adopted++;
+  }
+  return adopted;
 }
 
 // Broadcast to EVERY connected client exactly once (not per-session — a fresh client that
@@ -853,15 +943,22 @@ function sessionList() {
   return [...sessions.values()].map((s) => {
     const d = harness.deriveState(s.state, s.lastOutputAt, now);
     const h = harnessOf(s);
+    const hx = transcriptHarness(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,
+      // Derived presentation state, JOINED from both sources: the cadence clock above and the
+      // transcript's answer to whose turn it is (lib/session-state). working | quiet | exited |
+      // needs | blocked. `shell`-ness stays on `agent`, because it is orthogonal to state;
+      // `failed` does not exist (no observable for it). The client re-derives this from the SAME
+      // module — see /lib/session-state.js below — so the two can never hold different opinions.
+      shown: sessionState.presented(d.state, hx && hx.turn), quietMs: d.quietMs,
+      lastOutputAt: s.lastOutputAt || null,
       lastWords: h.lastWords,
-      // the harness proper — structured record, not rendered bytes
-      hx: transcriptHarness(s),
+      // the harness proper — structured record, not rendered bytes. Resolved ONCE above and
+      // reused: it also feeds the join, and calling it twice per session per broadcast would
+      // double the transcript work the TX_REREAD_MS floor exists to bound.
+      hx,
       missing: h.missing,
     };
   });
@@ -971,7 +1068,24 @@ 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
+// The name a session written BEFORE unique names carries. Kept only so those sessions still
+// re-attach after an upgrade; nothing new is ever named this way (see freshTmuxName).
 function tmuxName(id) { return 'pmos-' + id; }
+// A NEW session's tmux name must be unique on the socket for as long as any pane can outlive the
+// server that made it — and `pmos-sess-<n>` was not. The counter restarts with the process, so
+// once a generation's metadata went missing (state/sessions cleared, a partial restore) the next
+// server handed a fresh session the name of a pane still running from the last one, and
+// ensureTmuxSession's "already alive → leave it" ADOPTED that stranger's pane. The PM asked for a
+// session in one repo and got a live shell sitting in another — the wrong-directory defect. The
+// random suffix makes the name unforgeable by a later generation, so an orphan can only ever be
+// adopted deliberately (adoptOrphanTmuxSessions), never by an id collision.
+function freshTmuxName(id) {
+  for (let i = 0; i < 50; i++) {
+    const n = `pmos-${id}-${crypto.randomBytes(4).toString('hex')}`;
+    if (!tmuxHasSession(n)) return n;
+  }
+  return `pmos-${id}-${process.pid.toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
+}
 function writeTmuxConf() {
   if (!TMUX) return;
   const conf = [
@@ -992,12 +1106,38 @@ function writeTmuxConf() {
 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
+// Create the tmux session a FRESH spawn runs in. It REFUSES a name that already exists rather
+// than adopting it: this path only ever runs for a brand-new session, so an existing pane of that
+// name is someone else's process, in someone else's directory. Silently reusing it is how a new
+// session came up in the wrong repo. freshTmuxName makes the collision practically impossible;
+// this is the floor that keeps it impossible even if it were not.
+function createTmuxSession(name, cmd, workdir, cols, rows) {
+  if (tmuxHasSession(name)) return false;
   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;
 }
+// Every session alive on our private socket, with the directory its pane is actually sitting in.
+// Deliberately one lookup PER FIELD rather than one packed -F line: tmux rewrites whitespace
+// inside a format string (a tab separator came back as `_`), which silently glued the fields into
+// a single unusable name. One field per call has no separator to get wrong, and this runs only at
+// startup over the handful of sessions on our own socket. [] when tmux is absent or not running.
+function tmuxField(name, fmt) {
+  const r = tmuxCtl(['display-message', '-p', '-t', name, fmt]);
+  return r && r.status === 0 ? String(r.stdout || '').trim() : '';
+}
+function tmuxList() {
+  if (!TMUX) return [];
+  const r = tmuxCtl(['list-sessions', '-F', '#{session_name}']);
+  if (!r || r.status !== 0) return [];
+  return String(r.stdout || '').split('\n').map((line) => line.trim()).filter(Boolean)
+    .map((name) => ({
+      name,
+      dir: tmuxField(name, '#{pane_current_path}'),
+      created: Number(tmuxField(name, '#{session_created}')) || 0,
+      cmd: tmuxField(name, '#{pane_start_command}'),
+    }));
+}
 // 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) {
@@ -1030,7 +1170,11 @@ function seedFromPaneHistory(s, name) {
 // 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);
+  // The session's OWN recorded name, never one recomputed from its id — since freshTmuxName the
+  // two no longer coincide, and re-deriving would attach to whatever else happened to hold the
+  // id-shaped name. tmuxName() is the fallback for a session persisted before unique names.
+  const name = s.tmux || tmuxName(s.id);
+  s.tmux = name;
   const startedMs = Date.now();
   let p;
   try {
@@ -1132,8 +1276,26 @@ function exitedSession(base, workdir, why) {
   sessions.set(s.id, s); persist(s); pushSessions(); pushWorkspaces(); return s;
 }
 
+// Live (non-exited) sessions belonging to a workspace. Used to decide whether isolating a branch
+// would actually protect anyone, and to refuse removing a worktree somebody is working in.
+function liveSessionCount(wsIdent) {
+  let n = 0;
+  for (const s of sessions.values()) if (s.ws === wsIdent && s.state !== 'exited') n++;
+  return n;
+}
+
+// The next unused session id. `seq` is a per-process counter, so it can only be trusted once it
+// has been floored by what is already on disk and in memory (see restorePersisted) — this loop is
+// the last guard: a fresh session must never take an id another session's record already owns,
+// because persist() would then overwrite that record's scrollback.
+function nextSessionId() {
+  let id = 'sess-' + (seq++);
+  while (sessions.has(id)) id = 'sess-' + (seq++);
+  return id;
+}
+
 function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
-  const id = 'sess-' + (seq++);
+  const id = nextSessionId();
   const w = getWs(ws);
   const root = w ? w.root : SELF_ROOT;
   const isShell = agent === 'shell';
@@ -1156,11 +1318,11 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
 
   // ── the tmux path: the process outlives this server, and we re-attach to it live (R7) ──
   if (TMUX) {
-    const tname = tmuxName(id);
+    const tname = freshTmuxName(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)) {
+    if (!createTmuxSession(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`;
@@ -1202,36 +1364,143 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
   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 }) {
+// New session, optionally on a chosen/created branch. Three paths, and which one runs is the whole
+// point of this function:
+//
+//   isolate     — put the branch in its OWN worktree, register that directory as a workspace, and
+//                 start the session there. Every already-running session stays exactly where it
+//                 was. This is the default the UI offers for "+ new branch", because the shared
+//                 checkout moving every session was the single worst thing about this surface.
+//   checkout    — the shared-tree path: move THIS repo (and so every session in it) to the branch.
+//                 Still offered, still honest about its blast radius, no longer the only option.
+//   no git here — a workspace that is not a repo has no branch to be on. A stale picker or an old
+//                 client must not be able to BLOCK a session over it: we spawn, and return a
+//                 notice saying the branch was ignored. Never silently, never fatally.
+//
+// A FAILED git operation in a real repo 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
+// git-then-maybe-spawn contract is unit-testable without a WS client.
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate }) {
+  const w = getWs(ws);
+  if (!w) return { ok: false, error: 'no workspace' };
+  let targetWs = w.id;
+  let notice = null;
+  // Isolation exists to protect OTHER sessions. Alone in a workspace there are none to protect, so
+  // a plain checkout costs nothing and leaves no folder behind — which is the difference between
+  // "a worktree when it earns its keep" and a directory per branch forever. The client sends what
+  // the PM actually saw; this default only decides for a caller that expressed no preference (an
+  // older client, a scheduled run).
+  if (isolate === undefined || isolate === null) isolate = liveSessionCount(w.id) > 0;
+
   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
+    if (!gitInfo.isRepo(w.root)) {
+      notice = `“${w.name}” is not a git repository — the session started here, with no branch applied`;
+    } else if (isolate) {
+      const r = gitInfo.addWorktree(w.root, branch, { create: !!createBranch });
+      if (!r.ok) return { ok: false, error: r.error };
+      // A worktree is created at the REPO's top. If this workspace was a subdirectory of the repo
+      // (repo/packages/app — the ordinary shape for a tenant product repo added by path), the PM
+      // should land in the matching subdirectory of the new tree, not at a root they never chose.
+      const info = gitInfo.branchInfo(w.root);
+      const mirrored = info.ok && info.subdir ? path.join(r.dir, info.subdir) : r.dir;
+      const dir = isDir(mirrored) ? mirrored : r.dir;
+      const nw = registerWorkspace(dir, `${w.name} ⑂ ${branch}`);
+      if (!nw) return { ok: false, error: `worktree created at ${r.dir} but could not be registered as a workspace` };
+      targetWs = nw.id;
+      notice = r.reused
+        ? `reusing the existing worktree for “${branch}” at ${r.dir}`
+        : `“${branch}” checked out in its own folder — ${r.dir}. Sessions already running are untouched.`;
+      broadcast({ t: 'branch', ws: nw.id, ...gitInfo.branchInfo(nw.root) });
+    } else {
+      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 };
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs });
+  return { ok: true, session: s, notice };
+}
+
+// ── Worktree housekeeping: the app that creates the folders shows and clears them ──────────────
+// Isolation buys "your other sessions keep running" at the price of a directory per branch. That
+// price is only fair if the PM can see the folders and reclaim them without leaving the workspace
+// — and without a delete ever being a guess. Three hazards block a removal, and every one is
+// reported by name: live sessions (ours to know), uncommitted changes and commits held nowhere
+// else (git's to know, see gitInfo.worktreeSafety).
+function worktreeReport(w) {
+  const info = gitInfo.branchInfo(w.root);
+  if (!info.ok) return { ok: false, code: info.code, error: info.error };
+  const trees = info.worktrees || [];
+  const rows = trees.map((t, i) => {
+    const main = i === 0;
+    const owner = [...workspaces.values()].find((x) => path.resolve(x.root) === path.resolve(t.dir));
+    const live = owner ? liveSessionCount(owner.id) : 0;
+    // the main worktree is the repo itself — never removable from here, and saying so beats an
+    // absent button the PM has to reason about
+    const gone = !main && !isDir(t.dir);
+    const safety = main ? { removable: false, reasons: ['the repository’s own working tree'] }
+      // deleted by hand already: nothing left to protect, only git bookkeeping to clear. Asking
+      // `git status` about a folder that isn't there would fail and read as "unsafe".
+      : gone ? { removable: true, reasons: ['the folder is already gone — this clears git’s record of it'] }
+      : gitInfo.worktreeSafety(t.dir, t.branch);
+    const reasons = safety.reasons.slice();
+    if (!main && live > 0) reasons.unshift(`${live} session${live === 1 ? '' : 's'} still running here`);
+    return { dir: t.dir, branch: t.branch, main, missing: gone,
+      ws: owner ? owner.id : null, sessions: live,
+      removable: !main && live === 0 && safety.removable, reasons };
+  });
+  return { ok: true, repoRoot: info.repoRoot, worktrees: rows };
 }
 
-// ── 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.
+// ── Scratchpad: PER-SESSION staging text (R4). One file per terminal tab, because that is the
+// unit the PM stages against: the text is the next thing to type into THAT agent, and a single
+// per-workspace pad meant every tab showed — and overwrote — the same buffer. Local-only, keyed by
+// the workspace's hashed id and the server-issued session 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);
+// The pre-session file the workspace used to share. Still read, once: the first tab to open its
+// pad in that workspace CLAIMS it, so text staged before this change is not silently dropped.
+function legacyScratchpadPath(w) { return w ? path.join(SCRATCH_DIR, w.id + '.txt') : null; }
+// A session id is server-issued (`sess-<n>`), never echoed from the client — but this is the one
+// place a name reaches the filesystem, so it is checked rather than trusted.
+function scratchpadPath(w, sessionId) {
+  if (!w) return null;
+  if (!sessionId) return legacyScratchpadPath(w);
+  const sid = String(sessionId);
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(sid) || sid === '.' || sid === '..') return null;
+  return path.join(SCRATCH_DIR, w.id, sid + '.txt');
+}
+function readScratchpad(w, sessionId) {
+  const f = scratchpadPath(w, sessionId);
   if (!f) return '';
-  try { return fs.readFileSync(f, 'utf8'); } catch { return ''; }
+  try { return fs.readFileSync(f, 'utf8'); } catch {}
+  // Nothing staged for this tab yet — inherit the workspace's pre-session pad if one survives,
+  // by MOVING it, so exactly one tab gets it and it is never handed out twice.
+  if (sessionId) {
+    const legacy = legacyScratchpadPath(w);
+    try {
+      const text = fs.readFileSync(legacy, 'utf8');
+      fs.mkdirSync(path.dirname(f), { recursive: true });
+      fs.renameSync(legacy, f);
+      return text;
+    } catch {}
+  }
+  return '';
 }
-function writeScratchpad(w, text) {
-  const f = scratchpadPath(w);
-  if (!f) throw new Error('no workspace');
-  fs.mkdirSync(SCRATCH_DIR, { recursive: true });
+function writeScratchpad(w, sessionId, text) {
+  const f = scratchpadPath(w, sessionId);
+  if (!f) throw new Error('no scratchpad for that session');
+  fs.mkdirSync(path.dirname(f), { recursive: true });
   fs.writeFileSync(f, String(text == null ? '' : text).slice(0, SCRATCH_MAX));
 }
+// A tab that is gone takes its staging text with it — the pad belongs to the session, not to a
+// slot a later session could inherit by reusing its id.
+function forgetScratchpad(s) {
+  if (!s) return;
+  const w = workspaces.get(s.ws);
+  const f = scratchpadPath(w, s.id);
+  if (f) { try { fs.unlinkSync(f); } catch {} }
+}
 
 // ── 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
@@ -1262,6 +1531,7 @@ 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
+  forgetScratchpad(s);                   // the tab's staging text goes with the tab
   sessions.delete(id); unpersist(id); pushSessions(); pushWorkspaces();
   return true;
 }
@@ -1430,6 +1700,9 @@ function buildConsole(name, w, root) {
   if (name === 'needs') return needsResult(w);
   if (name === 'metrics') return consoleState.metrics({ stateDir, snapshotDir });
   if (name === 'radar') return consoleState.radar({ stateDir, snapshotDir });
+  // The workflow ladder reads the OPENED workspace's repo (records + git), not the state dir — an
+  // initiative's position is a property of the repo it lives in, snapshot or no snapshot.
+  if (name === 'workflow') return consoleState.workflow({ root: w ? w.root : root });
   return { ok: false, error: 'unknown console surface: ' + name };
 }
 
@@ -1593,17 +1866,25 @@ async function handleRequest(req, res) {
   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 === '/lib/session-state.js') return serveFile(res, path.join(__dirname, 'lib', 'session-state.js'));
   // The editor computes its live diff with the SAME module the server saves through, so what the PM
   // sees while typing and what gets written cannot disagree. NB: /lib/ is an explicit allowlist, not
   // a directory route — a <script src> for a file missing from this list 404s silently, and the
   // client feature that depends on it fails in a way no server-side test can see.
   if (p === '/lib/apply-change.js') return serveFile(res, path.join(__dirname, 'lib', 'apply-change.js'));
+  if (p === '/lib/related-docs.js') return serveFile(res, path.join(__dirname, 'lib', 'related-docs.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'));
+  // The design system's faces (D38) are VENDORED, not linked from a CDN: the workspace is a local
+  // companion app that has to render correctly with no network at all. Plex Mono ships 400 + 700
+  // because the terminal renders bold — with only the regular face the browser synthesises it.
+  if (p === '/vendor/space-grotesk-var.woff2') return serveFile(res, path.join(PUB, 'vendor', 'space-grotesk-var.woff2'));
+  if (p === '/vendor/ibm-plex-mono-400.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-400.woff2'));
+  if (p === '/vendor/ibm-plex-mono-700.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-700.woff2'));
 
   if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
   if (p === '/api/workspaces' && req.method === 'POST') {
@@ -1626,6 +1907,28 @@ async function handleRequest(req, res) {
     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/git/worktrees/remove' && req.method === 'POST') {
+    // Reclaim a worktree's folder. `dir` comes from a client, so it is checked against git's own
+    // list of THIS repo's linked worktrees before anything is removed — the main tree is
+    // unreachable by construction, and a tree with running sessions, uncommitted changes, or
+    // commits held nowhere else is refused with the reason, not silently kept.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); } catch {}
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const row = (worktreeReport(w).worktrees || [])
+      .find((t) => path.resolve(t.dir) === path.resolve(String(body.dir || '')));
+    if (!row) return json(res, { ok: false, error: 'not a linked worktree of this repository' }, 400);
+    if (row.sessions > 0) return json(res, { ok: false, error: `kept — ${row.reasons[0]}` }, 409);
+    const r = gitInfo.removeWorktree(w.root, row.dir);
+    if (!r.ok) return json(res, r, 409);
+    // the workspace entry goes with the folder; forgetWorkspace never touches a repo, and it
+    // refuses while sessions remain, so a race here fails closed rather than orphaning scrollback
+    const owner = [...workspaces.values()].find((x) => path.resolve(x.root) === path.resolve(row.dir));
+    if (owner) forgetWorkspace(owner.id);
+    broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });
+    return json(res, { ok: true, dir: r.dir, pruned: !!r.pruned });
+  }
   if (p === '/api/pick-folder' && req.method === 'POST') {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); } catch {}
@@ -1771,20 +2074,36 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' });
     return json(res, gitInfo.branchInfo(w.root));
   }
+  if (p === '/api/git/worktrees') {
+    // Every working tree attached to this workspace's repo, each with the reasons it can or cannot
+    // be removed. A worktree the workspace made is a folder the PM has to live with, so the app
+    // that creates them is the app that has to show them.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' });
+    return json(res, worktreeReport(w));
+  }
+  // The pad belongs to a SESSION when one is named — and the workspace then comes from that
+  // session, not from the caller, so a stale `ws` can never file one tab's text under another
+  // repo. `session` omitted still addresses the workspace pad (a window with no tabs yet).
   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);
+    const s = body.session ? sessions.get(String(body.session)) : null;
+    if (body.session && !s) return json(res, { ok: false, error: 'no such session' }, 404);
+    const w = s ? workspaces.get(s.ws) : getWs(body.ws);
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
-    try { writeScratchpad(w, body.text); }
+    try { writeScratchpad(w, s ? s.id : null, body.text); }
     catch (e) { warnWriteFail('scratchpad', e); return json(res, { ok: false, error: 'could not save scratchpad' }, 500); }
-    return json(res, { ok: true });
+    return json(res, { ok: true, session: s ? s.id : null });
   }
   if (p === '/api/scratchpad') {
-    const w = getWs(url.searchParams.get('ws'));
+    const sid = url.searchParams.get('session');
+    const s = sid ? sessions.get(sid) : null;
+    if (sid && !s) return json(res, { ok: false, error: 'no such session' }, 404);
+    const w = s ? workspaces.get(s.ws) : getWs(url.searchParams.get('ws'));
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
-    return json(res, { ok: true, text: readScratchpad(w) });
+    return json(res, { ok: true, session: s ? s.id : null, text: readScratchpad(w, s ? s.id : null) });
   }
   if (p === '/api/layouts' && req.method === 'POST') {
     let body = {};
@@ -1951,12 +2270,156 @@ async function handleRequest(req, res) {
       const sink = path.join(dir, 'doc-changes.jsonl');
       try { fs.mkdirSync(dir, { recursive: true }); fs.appendFileSync(sink, JSON.stringify(rec) + '\n'); logged = sink; }
       catch (e) { warnWriteFail('doc-changes.jsonl (the change log)', e); }
+      writeChangeContext(dir);                              // R8 — keep the agent-readable digest current
     }
     // The document IS saved at this point. A failed log is reported honestly rather than as success,
     // but it must not read as "your edit was lost".
     return json(res, { ok: true, saved: body.path, logged, change: { added: rec.added, removed: rec.removed, at_line: rec.at_line },
       warning: logged ? undefined : 'the document was saved but the change could not be logged' });
   }
+  if (p === '/api/align/candidates') {
+    // Which documents does the last change to THIS document put out of step? Scoped by the change
+    // (R6): a document qualifies only by a concrete tie — it links here, its frontmatter points
+    // here, it shares the initiative, or it quotes text the change altered. "Feels related" is not a
+    // rule, because that is how this becomes a review queue again.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(url.searchParams.get('path') || '');
+    const full = path.resolve(w.root, rel);
+    if (!rel || !insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+
+    const dir = stateDirFor(w);
+    let last = null;
+    try {
+      const sink = dir ? path.join(dir, 'doc-changes.jsonl') : null;
+      if (sink && fs.existsSync(sink)) {
+        const rows = fs.readFileSync(sink, 'utf8').split('\n').filter(Boolean)
+          .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+          .filter((r) => r && r.file === rel);
+        last = rows[rows.length - 1] || null;
+      }
+    } catch {}
+    if (!last) return json(res, { ok: true, empty: true, reason: 'no recorded change to this document yet' });
+
+    let changedText = '';
+    try { changedText = fs.readFileSync(full, 'utf8'); } catch {}
+    const docs = [];
+    for (const f of markdownDocs(w.root)) {
+      if (f === rel) continue;
+      const fp = path.resolve(w.root, f);
+      if (!insideRoot(w.root, fp)) continue;
+      try { docs.push({ path: f, text: fs.readFileSync(fp, 'utf8') }); } catch {}
+    }
+    const cands = relatedDocs.candidates({ changedPath: rel, changedText, removed: last.before, docs });
+    return json(res, { ok: true, change: last, candidates: cands.slice(0, 12), considered: docs.length, total: cands.length });
+  }
+  if (p === '/api/align/start' && req.method === 'POST') {
+    // Hand the change and its candidates to an agent, which DRAFTS the realigning edits (R5). The
+    // prompt is assembled here so the absolute paths are facts, not guesses — a tenant product repo
+    // has no workspace/ folder, and the agent must never invent one.
+    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);
+    const rel = String(body.path || '');
+    if (!rel || !insideRoot(w.root, path.resolve(w.root, rel))) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    const targets = (Array.isArray(body.targets) ? body.targets : []).filter((t) => typeof t === 'string').slice(0, 12);
+    if (!targets.length) return json(res, { ok: false, error: 'no documents named to align' }, 400);
+
+    const dir = stateDirFor(w, { create: true });
+    if (!dir) return json(res, { ok: false, error: 'this workspace has no state directory to file drafts into' }, 500);
+    const adir = path.join(dir, 'alignments');
+    try { fs.mkdirSync(adir, { recursive: true }); }
+    catch (e) { warnWriteFail('alignments directory', e); return json(res, { ok: false, error: 'could not create the alignments directory' }, 500); }
+
+    const c = body.change || {};
+    const prompt = [
+      'A document in this repository was just changed by the PM. Your job is to bring the documents',
+      'listed below back into line with that change — nothing else.',
+      '',
+      `CHANGED: ${rel} (from line ${c.at_line || '?'})`,
+      '',
+      'It used to say:', '```', String(c.before || '').slice(0, 4000), '```',
+      'It now says:', '```', String(c.after || '').slice(0, 4000), '```',
+      c.note ? `The PM's reason: ${c.note}` : '',
+      '',
+      'BRING THESE INTO LINE — read each, and only these:',
+      ...targets.map((t) => `  - ${t}`),
+      '',
+      'For each document that genuinely contradicts the change, produce the edit that fixes it.',
+      'A document that does not actually contradict it gets NO draft — say so and move on. Do not',
+      'improve, tidy, or critique anything: the only warrant you have is the change above.',
+      '',
+      `Write your drafts as JSON to: ${path.join(adir, 'draft-' + Date.now() + '.json')}`,
+      'Shape:',
+      '{"source":"' + rel + '","at":"<ISO 8601>","drafts":[',
+      '  {"file":"<path>","why":"<what in this document contradicts the change>",',
+      '   "before":"<verbatim text from that file, appearing EXACTLY once>","after":"<replacement>"}',
+      ']}',
+      '',
+      '`before` must be copied verbatim and must occur exactly once in its file — the apply path',
+      'refuses a stale or ambiguous anchor rather than guessing. An empty drafts array is a correct',
+      'and useful answer.',
+    ].filter((l) => l !== '').join('\n');
+
+    const s = spawnSession({ name: 'align: ' + path.basename(rel), agent: 'claude', ws: w.id,
+      origin: 'align:' + rel, initialInput: prompt + '\r' });
+    const started = !!(s && s.pty);
+    return json(res, { ok: started, sessionId: s && s.id, targets, sink: adir,
+      error: started ? undefined : ((s && s.note) || 'could not start the session') });
+  }
+  if (p === '/api/align/drafts') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const dir = stateDirFor(w);
+    const adir = dir ? path.join(dir, 'alignments') : null;
+    let files = [];
+    try { files = adir ? fs.readdirSync(adir).filter((f) => f.endsWith('.json')).sort() : []; } catch {}
+    if (!files.length) return json(res, { ok: true, empty: true });
+    const pick = files[files.length - 1];
+    let doc;
+    try { doc = JSON.parse(fs.readFileSync(path.join(adir, pick), 'utf8')); }
+    catch { return json(res, { ok: false, error: `the draft file '${pick}' is unreadable or not valid JSON` }, 500); }
+    const drafts = Array.isArray(doc.drafts) ? doc.drafts.filter((d) => d && typeof d.file === 'string') : [];
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts });
+  }
+  if (p === '/api/align/apply' && req.method === 'POST') {
+    // Apply ONE drafted realignment. Same anchored guard as everything else that writes here: the
+    // anchor must appear exactly once, or the write is refused rather than guessed at.
+    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);
+    const rel = String(body.file || '');
+    const full = path.resolve(w.root, rel);
+    if (!rel || !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); }
+
+    const r = applyChange.applyChange(current, { before: body.before, after: body.after });
+    if (!r.ok) return json(res, { ok: false, error: r.reason, detail: r.detail || null }, 409);
+    try { fs.writeFileSync(full, r.text); }
+    catch (e) { warnWriteFail('alignment apply (' + rel + ')', e); return json(res, { ok: false, error: 'could not write the document' }, 500); }
+
+    // An aligning edit is a change to that document too, and belongs in its log — attributed to the
+    // change that caused it, so the log reads as a chain rather than as unexplained edits.
+    const region = applyChange.changedRegion(body.before, body.after);
+    const dir = stateDirFor(w, { create: true });
+    if (dir) {
+      const rec = { file: rel, at: nowISO(), pm: body.pm || 'wawan',
+        note: 'aligned with ' + (body.source || 'an earlier change') + (body.why ? ' — ' + String(body.why).slice(0, 200) : ''),
+        at_line: region.at_line, added: region.added, removed: region.removed,
+        before: region.before, after: region.after, aligned_from: body.source || null };
+      try { fs.appendFileSync(path.join(dir, 'doc-changes.jsonl'), JSON.stringify(rec) + '\n'); }
+      catch (e) { warnWriteFail('doc-changes.jsonl (alignment)', e); }
+      writeChangeContext(dir);
+    }
+    return json(res, { ok: true, wrote: rel });
+  }
   if (p === '/api/doc/changes') {
     // The change log, read back (R8 — this is what an agent reads before working here).
     const w = getWs(url.searchParams.get('ws'));
@@ -1977,6 +2440,67 @@ async function handleRequest(req, res) {
   res.writeHead(404); res.end('not found');
 }
 
+// ── R8: the change log, written for an agent to read before it works here ──────────────────────
+// The jsonl is the record; this is the same material shaped so a coding agent picks it up without
+// being handed a parser. Regenerated on every save — cheap, and it means the file is never stale.
+// What makes it worth reading is the PM's own reasons: an agent that knows WHY a line kept getting
+// rewritten will stop writing the thing that provoked it.
+function writeChangeContext(dir) {
+  if (!dir) return null;
+  const sink = path.join(dir, 'doc-changes.jsonl');
+  let rows = [];
+  try {
+    if (!fs.existsSync(sink)) return null;
+    rows = fs.readFileSync(sink, 'utf8').split('\n').filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return null; }
+  if (!rows.length) return null;
+
+  const byFile = new Map();
+  for (const r of rows) byFile.set(r.file, (byFile.get(r.file) || 0) + 1);
+  const hot = [...byFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
+  const withReasons = rows.filter((r) => r.note).slice(-20).reverse();
+  const recent = rows.slice(-12).reverse();
+
+  const out = [
+    '---', 'type: Reference',
+    'title: "Change context — what the PM has been editing here, and why"',
+    'timestamp: ' + nowISO().slice(0, 10), '---', '',
+    '# Change context',
+    '',
+    '**Read this before writing documents in this repository.** It is generated from the PM\'s own',
+    'edits in the workspace — not a summary of the repo, and not a style guide someone wrote once.',
+    'If a line below shows the PM rewriting the same kind of thing repeatedly, that is a correction',
+    'you can avoid provoking again.',
+    '',
+    `Generated ${nowISO()} from ${rows.length} recorded change${rows.length === 1 ? '' : 's'}.`,
+    '',
+    '## Documents changed most often', '',
+    ...hot.map(([f, n]) => `- \`${f}\` — ${n} change${n === 1 ? '' : 's'}`),
+    '',
+  ];
+  if (withReasons.length) {
+    out.push('## Why the PM changed things, in their words', '');
+    for (const r of withReasons) {
+      out.push(`- **${r.file}** — ${r.note}`);
+      if (r.before && r.after) {
+        out.push('  ```', '  - ' + String(r.before).split('\n')[0].slice(0, 160),
+                 '  + ' + String(r.after).split('\n')[0].slice(0, 160), '  ```');
+      }
+    }
+    out.push('');
+  }
+  out.push('## Most recent changes', '');
+  for (const r of recent) {
+    out.push(`- \`${r.file}\` · +${r.added} −${r.removed} at line ${r.at_line} · ${String(r.at).slice(0, 16).replace('T', ' ')}` +
+             (r.aligned_from ? ` · aligned with a change to \`${r.aligned_from}\`` : ''));
+  }
+  out.push('');
+  const target = path.join(dir, 'change-context.md');
+  try { fs.writeFileSync(target, out.join('\n')); return target; }
+  catch { return null; }
+}
+
 // ── 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
@@ -2073,8 +2597,11 @@ 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 r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch });
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate });
       if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: 'branch: ' + r.error })); return; }
+      // a non-fatal truth about what just happened (a worktree's path, a branch ignored on a
+      // non-repo) — said out loud, never swallowed
+      if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
       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;