create-pmos 0.8.0 → 0.9.0

package/workspace/server.js

@@ -72,6 +72,7 @@ const fmParse = require('./lib/file-mode-parse');      // canonical file-mode pa
 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 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
@@ -738,7 +739,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 +773,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 +921,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 +1046,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 +1084,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 +1148,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 +1254,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 +1296,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 +1342,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 +1509,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 +1678,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,6 +1844,7 @@ 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
@@ -1604,6 +1856,12 @@ async function handleRequest(req, res) {
   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 +1884,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 +2051,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 = {};
@@ -2073,8 +2369,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;