create-pmos 0.7.3 → 0.9.0

package/workspace/server.js

@@ -71,9 +71,8 @@ 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 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)
+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
@@ -600,18 +599,6 @@ 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.
-// PER WORKSPACE, like every other piece of state here. An earlier build put this in the SERVER's own
-// state/ — which meant two open repos shared one review pile, and a tenant repo (which has no
-// workspace/ folder at all) had the reviews written into the installed app instead of into the repo
-// being reviewed. Reviews name documents and quote their contents, so that was a cross-workspace leak,
-// not just untidy filing. stateDirFor() is the same resolver needs.json and acceptances.jsonl use.
-function reviewDirFor(w, opts) {
-  const d = stateDirFor(w, opts);
-  return d ? path.join(d, 'reviews') : null;
-}
 // 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
@@ -752,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'));
@@ -779,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
@@ -867,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,
     };
   });
@@ -985,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 = [
@@ -1006,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) {
@@ -1044,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 {
@@ -1146,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';
@@ -1170,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`;
@@ -1216,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
@@ -1276,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;
 }
@@ -1444,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 };
 }
 
@@ -1607,12 +1844,24 @@ 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 === '/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') {
@@ -1635,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 {}
@@ -1780,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 = {};
@@ -1910,201 +2197,78 @@ 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 = [];
-    const rdir = reviewDirFor(w);
-    try { files = rdir ? fs.readdirSync(rdir).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(rdir, 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 = {};
-    const records = [];
-    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) continue;
-          records.push(r);
-          if (r.finding_title) settled[r.finding_title] = r.disposition;
-        } catch {}
-      }
-    } catch {}
-    // The PRD's success signal is explicit that the counters are part of the build, not a follow-up:
-    // action rate must be derivable off the records with no manual counting. quiet-rate is NOT
-    // derivable here — it needs a corpus with a labelled CLEAN class, which does not exist — so it is
-    // reported as null and rendered as "not measured" rather than as a flattering zero.
-    const stats = { ...correctionRecord.summarise(records), quiet_rate: findingContract.quietRate(null, null) };
-    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, stats, reasons: [...correctionRecord.REASONS] });
-  }
-  if (p === '/api/review/start' && req.method === 'POST') {
-    // Review THIS document — the trigger that makes the scope implicit instead of typed. The PM is
-    // reading a document; the thing they want reviewed is the thing in front of them.
-    //
-    // The prompt is assembled HERE, not in the browser, for one reason that matters beyond tidiness:
-    // a tenant product repo has no workspace/ folder. Pointing the agent at
-    // `workspace/skills/doc-review.skill` works in PMOS-self and breaks everywhere else, and so does
-    // telling it to write to `workspace/state/reviews/`. The server knows the skill body and the
-    // resolved state directory for THIS workspace, so both travel in the prompt as absolute facts.
+  if (p === '/api/doc/save' && req.method === 'POST') {
+    // The editor's save (workspace-doc-editor R3/R4). The ONLY write path on this surface, and it is
+    // reached solely by the PM pressing save on a document they were editing. Nothing here consults
+    // an agent, and nothing an agent produced can reach it — the agent is downstream of this write,
+    // never upstream of it (rubric dim 1, the hard floor).
     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 || '').trim();
-    if (!rel) return json(res, { ok: false, error: 'no document named' }, 400);
-    const full = path.resolve(w.root, rel);
+
+    // Path guard, identical to every read on this surface (R10).
+    const full = path.resolve(w.root, String(body.path || ''));
     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 can be reviewed' }, 400);
-    }
-    if (!fs.existsSync(full)) return json(res, { ok: false, error: 'no such document' }, 404);
-
-    const task = loadTasks().find((t) => t.id === 'doc-review');
-    if (!task || !task.prompt) return json(res, { ok: false, error: 'the doc-review skill is not installed' }, 500);
-
-    const rdir = reviewDirFor(w, { create: true });
-    if (!rdir) return json(res, { ok: false, error: 'this workspace has no state directory to file a review into' }, 500);
-    try { fs.mkdirSync(rdir, { recursive: true }); }
-    catch (e) { warnWriteFail('reviews directory', e); return json(res, { ok: false, error: 'could not create the reviews directory' }, 500); }
-
-    // Scope first, so it is the last thing the agent reads before the procedure — and stated as
-    // paths, because "the documents the PM named" is only a rule if something names them.
-    const extra = Array.isArray(body.also) ? body.also.filter((x) => typeof x === 'string').slice(0, 9) : [];
-    const scope = [rel, ...extra];
-    const preamble = [
-      'Review these documents, and only these:',
-      ...scope.map((s) => `  - ${s}`),
-      '',
-      `File the review as JSON into: ${rdir}`,
-      `The needs-you queue for this workspace is: ${needsFileFor(w) || '(none — skip the needs step)'}`,
-      'Both paths are absolute and already exist. Use them exactly; do not guess a workspace/ path.',
-      '',
-      '--- the skill ---',
-      '',
-    ].join('\n');
-
-    const s = spawnSession({ name: 'review: ' + path.basename(rel), agent: task.agent || 'claude',
-      ws: w.id, origin: 'review:' + rel, initialInput: preamble + task.prompt + '\r' });
-    const started = !!(s && s.pty);
-    return json(res, { ok: started, sessionId: s && s.id, scope, sink: rdir,
-      error: started ? undefined : ((s && s.note) || 'could not start the session') });
-  }
-  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);
+      return json(res, { ok: false, error: 'only markdown documents are editable here' }, 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 current;
+    try { current = fs.readFileSync(full, 'utf8'); }
+    catch { return json(res, { ok: false, error: 'could not read the document' }, 404); }
+
+    // REFUSE ON STALE. `base` is what the editor loaded; if the file has moved since, writing would
+    // silently discard whoever changed it. Loud failure beats a merge nobody asked for.
+    const saved = applyChange.saveWhole(current, String(body.base == null ? '' : body.base), String(body.text == null ? '' : body.text));
+    if (!saved.ok) {
+      const code = saved.reason === 'stale' ? 409 : 400;
+      return json(res, { ok: false, error: saved.reason, detail: saved.detail || null }, code);
     }
 
-    // R8, and it must happen BEFORE the write. buildRecord depends on nothing the write produces, and
-    // validating it after would let a missing reason leave the document changed with no record behind
-    // it — a half-applied state whose whole point was to be impossible. Refuse first, touch the file
-    // second: every rejection below this line leaves the repository byte-identical.
-    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) {
-      return json(res, { ok: false, error: 'no correction record could be written, so nothing was changed', errors: built.errors }, 400);
+    try { fs.writeFileSync(full, saved.text); }
+    catch (e) {
+      warnWriteFail('document save (' + body.path + ')', e);
+      return json(res, { ok: false, error: 'could not write the document — nothing was changed' }, 500);
     }
 
-    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;
+    // R4/R9: append to THIS repository's own change log. stateDirFor() is the same resolver
+    // needs.json and acceptances.jsonl use — a tenant product repo has no workspace/ folder, and
+    // assuming one is exactly the defect shipped in 0.7.1/0.7.2.
+    const region = applyChange.changedRegion(body.base, body.text);
+    const rec = { file: String(body.path), at: nowISO(), pm: body.pm || 'wawan',
+      note: typeof body.note === 'string' && body.note.trim() ? body.note.trim().slice(0, 400) : null,
+      at_line: region.at_line, added: region.added, removed: region.removed,
+      before: region.before, after: region.after };
+    const dir = stateDirFor(w, { create: true });
+    let logged = null;
+    if (dir) {
+      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); }
     }
-
-    // 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');
+    // 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/doc/changes') {
+    // The change log, read back (R8 — this is what an agent reads before working here).
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const dir = stateDirFor(w);
+    const sink = dir ? path.join(dir, 'doc-changes.jsonl') : null;
+    const only = url.searchParams.get('path');
+    let rows = [];
     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 });
+      if (sink && fs.existsSync(sink)) {
+        rows = fs.readFileSync(sink, 'utf8').split('\n').filter(Boolean)
+          .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+      }
+    } catch (e) { return json(res, { ok: false, error: 'the change log is unreadable' }, 500); }
+    if (only) rows = rows.filter((r) => r.file === only);
+    return json(res, { ok: true, changes: rows.slice(-200).reverse(), total: rows.length });
   }
   res.writeHead(404); res.end('not found');
 }
@@ -2205,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;