create-pmos 0.17.0 → 0.18.1

package/workspace/server.js

@@ -71,6 +71,8 @@ const consoleState = require('./lib/console-state');   // read-only console surf
 const boardCache = require('./lib/board-cache');   // the workflow board, cached + derived off the event loop (R4)
 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 startPolicy = require('./lib/start-policy');     // ONE stated rule for where a session starts (repo-first R1/R3)
+const treeShare = require('./lib/tree-share');         // who shares a working tree, and who is DECLARED to be driving it
 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
@@ -312,11 +314,18 @@ function repoIdentity(root) {
   const now = Date.now();
   if (hit && now - hit.at < REPO_KEY_TTL_MS) return hit;
   let key = root, name = path.basename(root), branch = null, branchError = null, branchCode = null;
-  let remote = null;
+  let remote = null, tree = null;
   try {
     const trees = gitInfo.worktrees(root);
     if (trees.length && trees[0].dir) { key = path.resolve(trees[0].dir); name = path.basename(key); }
   } catch { /* not a repo, or git absent — the tree is its own group, which is the truth */ }
+  // The THIRD key, and the only one that answers "would these two sessions collide": the working
+  // tree this workspace sits in — one HEAD, one index, one set of files. `key` above is the
+  // REPOSITORY (its main worktree), which deliberately groups a repo's linked worktrees; those are
+  // exactly the sessions that are safely isolated, so it is the wrong key for collisions. Null for
+  // a folder with no git, and null is meaningful: no index, nothing to collide over. Memoised in
+  // this same entry because `wsList()` runs on every workspace push and this is a third shell-out.
+  try { tree = gitInfo.repoRoot(root); } catch { tree = null; }
   // Where this tree came FROM. Memoised with the rest of the identity (same 15s TTL) because it is
   // another `git` shell-out on a call that runs for every workspace on every push. A failure is not
   // a fault: a folder registered by path legitimately has no origin, and null is the honest answer.
@@ -333,10 +342,62 @@ function repoIdentity(root) {
     // one drifts.
     else { branchError = bi.error || 'branch could not be read'; branchCode = bi.code || 'git-error'; }
   } catch { branchError = 'branch could not be read'; branchCode = 'git-error'; }
-  const val = { at: now, key, name, branch, branchError, branchCode, remote };
+  const val = { at: now, key, name, branch, branchError, branchCode, remote, tree };
   repoKeyCache.set(root, val);
   return val;
 }
+
+// ── Shared-tree co-tenancy (workspace-session-concurrency) ────────────────────────────────────
+// The rules live in lib/tree-share.js, pure and unit-tested; what lives here is the two things the
+// server owns — the git answer (via the memoised identity above) and the session registry.
+//
+// Held claims, tree top → session id. Only ever BELIEVED while its holder is live (treeShare.
+// writerOf re-checks), so an exited writer leaves the tree vacant rather than leaving a stale name
+// on it. Nothing is promoted automatically: which pane drives is the PM's intention, not ours.
+const treeClaims = new Map();
+/** workspace id → its working-tree top (null when the folder is not in a repo). */
+function treeOfWsMap() {
+  const m = new Map();
+  for (const w of workspaces.values()) m.set(w.id, repoIdentity(w.root).tree || null);
+  return m;
+}
+function treeForWs(wsIdent) {
+  const w = wsIdent && workspaces.get(wsIdent);
+  return w ? (repoIdentity(w.root).tree || null) : null;
+}
+/** Live sessions sharing a tree, excluding one id. Rows are the registry's own objects. */
+function treeTenants(tree, excludeId) {
+  return treeShare.coTenants([...sessions.values()], treeOfWsMap(), tree, excludeId);
+}
+function treeWriter(tree) {
+  return treeShare.writerOf(treeClaims, treeOfWsMap(), [...sessions.values()], tree);
+}
+/**
+ * A freshly-live session meets its tree: take the claim if nobody holds one, and write what it
+ * found into its own scrollback. The pane line is deliberately part of the session's record rather
+ * than only a transient notice frame — re-open the tab tomorrow and it still says what it was told.
+ * Returns the co-tenants so the caller can put the same fact on the wire.
+ */
+function announceTree(s) {
+  const tree = treeForWs(s.ws);
+  s.tree = tree || null;
+  if (!tree) return [];
+  const mates = treeTenants(tree, s.id);
+  const holder = treeWriter(tree);
+  if (!holder) treeClaims.set(tree, s.id);           // vacant → this session declares itself
+  if (!mates.length) return [];                      // alone in the tree: nothing to say
+  const held = holder ? (sessions.get(holder) || {}).name : null;
+  const line = treeShare.paneAdvisory(mates, { role: holder ? 'reader' : 'writer', writerName: held });
+  if (line) appendBuf(s, line);
+  return mates;
+}
+/** The sentence for the spawn's notice frame — same facts as the pane line, same source. */
+function treeNoticeFor(s, mates) {
+  if (!mates || !mates.length) return null;
+  const holder = treeWriter(s.tree);
+  const held = holder && holder !== s.id ? (sessions.get(holder) || {}).name : null;
+  return treeShare.coTenancyNotice(mates, { role: holder === s.id ? 'writer' : 'reader', writerName: held });
+}
 function wsList() {
   return [...workspaces.values()].map((w) => {
     const rid = repoIdentity(w.root);
@@ -1246,6 +1307,10 @@ function persist(s) {
   try {
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
+    // What is on disk now matches `s.buf`. The periodic writer reads this to skip a session whose
+    // buffer has not moved — see the interval below. Cleared only on a write that SUCCEEDED, so a
+    // disk blip leaves the session dirty and it is retried on the next tick.
+    s.bufDirty = false;
   } catch { /* best-effort; never crash a live session on a disk blip */ }
 }
 function unpersist(id) {
@@ -1472,7 +1537,16 @@ function sessionList() {
   // failure to avoid claiming "no profiles are configured on this machine" when PMOS never looked.
   const pread = readProfilesNow();
   const byId = new Map((pread.profiles || []).map((p) => [p.id, p]));
-  return [...sessions.values()].map((s) => {
+  // ONE tree map and ONE writer lookup per broadcast, for the same reason profiles are read once:
+  // the heartbeat runs every 2s and a per-row `git rev-parse` would be a shell-out per pane per
+  // tick. `repoIdentity` is memoised, but the map is still built once and reused.
+  const rowsAll = [...sessions.values()];
+  const treeOfWs = treeOfWsMap();
+  const writerByTree = new Map();
+  for (const t of new Set([...treeOfWs.values()].filter(Boolean))) {
+    writerByTree.set(t, treeShare.writerOf(treeClaims, treeOfWs, rowsAll, t));
+  }
+  return rowsAll.map((s) => {
     const d = harness.deriveState(s.state, s.lastOutputAt, now);
     const h = harnessOf(s);
     const hx = transcriptHarness(s);
@@ -1504,6 +1578,18 @@ function sessionList() {
       // BARE ID — the module rejects a bare string on purpose ("the recorded value is not a
       // profile descriptor"), which is the honest answer. Resolving it to `null` instead would
       // print "none was chosen" over a session that did choose one (R9).
+      // ── the shared working tree, and the DECLARED writer on it ──
+      // `tree` is the collision unit (one HEAD, one index) — null for a folder with no git, and
+      // null is the honest answer there rather than a group of one. `tree_role` is 'writer' for the
+      // one session that holds the claim, 'reader' for every other session in that tree, and null
+      // where there is no tree. `tree_peers` counts the OTHER live sessions sharing it. All three
+      // are advisory: PMOS hosts the terminal, it does not sit between the agent and the files.
+      tree: treeOfWs.get(s.ws) || null,
+      // an exited pane holds no role: a corpse is neither writing nor waiting to.
+      tree_role: treeShare.isLive(s)
+        ? treeShare.roleOf(s.id, treeOfWs.get(s.ws) || null, writerByTree.get(treeOfWs.get(s.ws)))
+        : null,
+      tree_peers: treeShare.coTenants(rowsAll, treeOfWs, treeOfWs.get(s.ws) || null, s.id).length,
       profile_id: 'profile' in s ? (s.profile == null ? null : s.profile) : null,
       profile_line: profilesLib.profileLine(
         !('profile' in s) ? undefined
@@ -1560,6 +1646,7 @@ function trimBuf(buf, limit) {
 function appendBuf(s, data) {
   s.buf += data;
   if (s.buf.length > SCROLLBACK) s.buf = trimBuf(s.buf, SCROLLBACK);
+  s.bufDirty = true;                    // the periodic writer skips a session that is not dirty
   // Parser 2's whole input: the moment output last arrived. `quiet` is derived from this, never
   // from reading the bytes — which is why it is the only one of the five that cannot misread.
   s.lastOutputAt = Date.now();
@@ -1727,6 +1814,7 @@ function seedFromPaneHistory(s, name) {
   if (!text) return false;
   s.buf = trimBuf(text + '\r\n', SCROLLBACK);          // 5000 lines of history can overrun the ring
   s.parsed = null;
+  s.bufDirty = true;                                   // the ring moved; the file on disk is stale
   return true;
 }
 
@@ -1922,6 +2010,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
       s.buf = `\x1b[38;5;203m✗ ${why}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`;
       persist(s); pushSessions(); pushWorkspaces(); return s;
     }
+    announceTree(s);   // before attach, so the advisory is the first line of the pane's record
     attachPty(s);
     feed(s);
     persist(s); pushSessions(); pushWorkspaces(); return s;
@@ -1940,6 +2029,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
     pty: p, tmux: null, note: '', buf: '', cols: 80, rows: 24, clients: new Set(), created: nowISO(),
     lastOutputAt: Date.now() };
   sessions.set(id, s);
+  announceTree(s);   // registered first: a session's co-tenancy question includes itself in the map
   p.onData((d) => {
     appendBuf(s, d);
     for (const c of s.clients) if (c.readyState === 1) c.send(JSON.stringify({ t: 'data', id, data: d }));
@@ -2017,7 +2107,96 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate,
     }
   }
   const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id });
-  return { ok: true, session: s, notice };
+  // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
+  // block above. The isolate default already computes that other sessions would be disturbed — and
+  // then the whole git block is skipped when no branch was picked, which is the common path and the
+  // one the PM has been living in. It said nothing. Now it says what it already knew.
+  //
+  // Both facts travel: `notice` is a single string on the wire and a branch notice and a co-tenancy
+  // notice can both be true of one spawn. joinNotices keeps them both rather than letting the
+  // second evict the first exactly when the PM most needs both.
+  const shared = treeNoticeFor(s, treeTenants(s.tree, s.id));
+  return { ok: true, session: s, notice: treeShare.joinNotices(notice, shared) };
+}
+
+/* ── workspace-repo-first · start work in one click (PRD R1 · R3) ───────────────────────────────
+ * The composer asked six questions to open a terminal, and the one question the PM actually has —
+ * "which initiative am I working on?" — was not among them. It asked for a BRANCH instead, plus an
+ * isolation checkbox whose default came from liveSessionCount(). These three functions replace that
+ * with: pick a repository, optionally pick an initiative, press one control.
+ *
+ * The policy itself is lib/start-policy.js — pure, so the git-touching paths are testable without
+ * a repository. This layer only supplies it with facts and carries out what it decides.
+ *
+ * R3 is why `agent` appears NOWHERE below except as a value passed through to the spawn: the
+ * destination is derived from the repository and the initiative, so `shell` and `claude` cannot
+ * land in different directories for the same selection. Previously both resolved through
+ * `state.wsId` — whichever folder the client happened to have selected — which is exactly how they
+ * came apart.
+ */
+function treesOfRepo(repoKey) {
+  const out = [];
+  for (const w of workspaces.values()) {
+    const ident = repoIdentity(w.root);
+    if (String(ident.key) !== String(repoKey)) continue;
+    out.push({ id: w.id, root: w.root, name: w.name, repo_key: ident.key, branch: ident.branch });
+  }
+  return out;
+}
+// The repo key for a request that named a workspace rather than a repository. The client sends
+// whichever it has; a stale ws id must not silently retarget another repo, so an unknown id is an
+// error rather than a fallback to "some repository".
+function repoKeyFor({ repoKey, ws }) {
+  if (repoKey) return String(repoKey);
+  const w = ws && workspaces.get(ws);
+  return w ? String(repoIdentity(w.root).key) : null;
+}
+// What the PM is about to get, BEFORE they press anything (R1: the destination is named first).
+// Read-only: it reads git and resolves the policy, and starts nothing.
+function startPreview({ initiative, repoKey, ws }) {
+  const key = repoKeyFor({ repoKey, ws });
+  if (!key) return { ok: false, error: 'no repository selected' };
+  const trees = treesOfRepo(key);
+  const main = startPolicy.mainTreeOf(trees);
+  // branchInfo is shelled per call and only when an initiative is named — the no-initiative plan
+  // needs no branch list, and this runs on every selection change.
+  let branches = null;
+  if (initiative && main) {
+    try { const bi = gitInfo.branchInfo(main.root); if (bi.ok) branches = bi.branches; } catch {}
+  }
+  const plan = startPolicy.resolveStart({ initiative, trees, branches });
+  if (!plan.ok) return plan;
+  // The literal directory, so the sentence in the UI is checkable rather than a promise.
+  let dir = null;
+  if (plan.plan === 'new-worktree' && main) { try { dir = gitInfo.worktreePath(main.root, plan.branch); } catch {} }
+  else { const t = trees.find((x) => x.id === plan.wsId); dir = t ? t.root : null; }
+  return { ok: true, plan: plan.plan, why: plan.why, dir, branch: plan.branch, wsId: plan.wsId };
+}
+// One click. Resolves the policy, then hands the SAME seam spawnWithBranch already exposes the
+// branch/isolate decision it made — so the inherited hard floor (a failed git operation spawns
+// nothing) is enforced in exactly one place and is not re-implemented here.
+function startWork({ initiative, repoKey, ws, agent, name, profile }) {
+  const key = repoKeyFor({ repoKey, ws });
+  if (!key) return { ok: false, error: 'no repository selected' };
+  const trees = treesOfRepo(key);
+  const main = startPolicy.mainTreeOf(trees);
+  let branches = null;
+  if (initiative && main) {
+    try { const bi = gitInfo.branchInfo(main.root); if (bi.ok) branches = bi.branches; } catch {}
+  }
+  const plan = startPolicy.resolveStart({ initiative, trees, branches });
+  if (!plan.ok) return plan;
+  const r = spawnWithBranch({
+    name: name || initiative || agent || 'shell',
+    agent: agent || 'shell',
+    ws: plan.wsId,
+    branch: plan.branch,
+    createBranch: plan.createBranch,
+    isolate: plan.isolate,
+    profile,
+  });
+  if (!r.ok) return r;
+  return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
 }
 
 // ── Worktree housekeeping: the app that creates the folders shows and clears them ──────────────
@@ -2033,7 +2212,11 @@ function worktreeReport(w) {
   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;
+    // Counted by TREE, not by workspace id. A session running in a workspace registered at a
+    // SUBDIRECTORY of this tree (`repo/packages/app` — the ordinary tenant-repo shape) is a session
+    // whose files this removal would pull out from under it, and the old workspace-id count could
+    // not see it: two ids, one checkout. `owner` is still the row's workspace for the client.
+    const live = treeTenants(path.resolve(t.dir), null).length;
     // 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);
@@ -2137,6 +2320,10 @@ function removeSession(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
+  // Drop a claim this session held. Correctness does not depend on this — treeShare.writerOf only
+  // believes a claim whose holder is still live, so a stale entry already reads as vacant — but a
+  // map that only grows is a leak waiting to be found by someone else.
+  if (s.tree && treeClaims.get(s.tree) === id) treeClaims.delete(s.tree);
   sessions.delete(id); unpersist(id); pushSessions(); pushWorkspaces();
   return true;
 }
@@ -2155,8 +2342,17 @@ function renameSession(id, name) {
   return true;
 }
 
-// periodic scrollback persistence so a crash loses at most a few seconds of history
-setInterval(() => { for (const s of sessions.values()) if (s.pty) persist(s); }, 5000).unref?.();
+// Periodic scrollback persistence so a crash loses at most a few seconds of history — but ONLY for
+// sessions whose buffer actually moved. `persist()` is two SYNCHRONOUS writes, the second of them
+// the whole ring buffer (up to 200 KB), and this ran unconditionally for every live session every
+// five seconds. A workspace with six idle panes open was therefore doing over a megabyte of blocking
+// disk I/O, on a timer, forever — rewriting bytes identical to the ones already on disk, on the same
+// thread that carries every keystroke to a PTY and every byte back to the browser. That is a stall
+// the PM feels as the terminal going unresponsive for no reason they can see.
+//
+// `bufDirty` is set by appendBuf (the only writer of `s.buf`) and cleared by persist(), so an idle
+// session now costs one map lookup per tick and a busy one is written exactly as often as before.
+setInterval(() => { for (const s of sessions.values()) if (s.pty && s.bufDirty) persist(s); }, 5000).unref?.();
 
 // ── File-mode state, per workspace. ───────────────────────────────────────────────────
 // A repo that carries PMOS state OWNS its records. The kit (D54) keeps them under `pmos/state/`
@@ -2947,6 +3143,25 @@ async function handleRequest(req, res) {
     return serveFile(res, file, null, true);
   }
 
+  if (p === '/api/tree/claim' && req.method === 'POST') {
+    // Hand the writer claim to a named session. The ONLY way a claim moves: never on a timer, never
+    // on an exit, never on a heuristic. Which pane should be driving is the PM's intention, and a
+    // derived answer must not impersonate a decision — so an exited holder leaves the tree vacant
+    // and this endpoint is how it stops being vacant.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const s = body.session && sessions.get(String(body.session));
+    if (!s) return json(res, { ok: false, error: 'no such session' }, 400);
+    if (!treeShare.isLive(s)) return json(res, { ok: false, error: 'that session has exited — an exited pane cannot hold a claim' }, 400);
+    const tree = treeForWs(s.ws);
+    if (!tree) return json(res, { ok: false, error: 'that session is not in a git working tree — there is nothing to claim' }, 400);
+    const prev = treeWriter(tree);
+    treeClaims.set(tree, s.id);
+    pushSessions();
+    return json(res, { ok: true, tree, writer: s.id, previous: prev || null, advisory: true,
+      note: 'a declaration, not a guarantee — nothing about either process changed' });
+  }
   if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
   if (p === '/api/workspaces' && req.method === 'POST') {
     // How `pmos` in another repo becomes another workspace (R1). Local-only, like every
@@ -3385,6 +3600,16 @@ 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/start/preview') {
+    // repo-first R1 — what one click will do, said BEFORE the click. Read-only: it resolves the
+    // policy and names the literal destination directory, and starts nothing. This exists so the
+    // rule is checkable by the PM rather than inferred after a folder appears.
+    return json(res, startPreview({
+      initiative: url.searchParams.get('initiative') || '',
+      repoKey: url.searchParams.get('repo') || '',
+      ws: url.searchParams.get('ws') || '',
+    }));
+  }
   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
@@ -3393,6 +3618,27 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' });
     return json(res, worktreeReport(w));
   }
+  if (p === '/api/tree/peers') {
+    // Who this workspace's sessions actually share mutable git state with, and who is declared to
+    // be driving. `advisory` is a FIELD, not a footnote: a caller that renders this must not be
+    // able to read it as enforcement without having read the word.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' });
+    const tree = repoIdentity(w.root).tree || null;
+    if (!tree) {
+      return json(res, { ok: true, tree: null, writer: null, sessions: [], advisory: true,
+        note: 'this workspace is not inside a git working tree — there is no shared index to collide over' });
+    }
+    const writer = treeWriter(tree);
+    const rows = treeTenants(tree, null).map((s) => ({
+      id: s.id, name: s.name, ws: s.ws, agent: s.agent, state: s.state,
+      role: treeShare.roleOf(s.id, tree, writer),
+    }));
+    return json(res, { ok: true, tree, writer, sessions: rows, advisory: true,
+      note: writer
+        ? 'the writer claim is a declaration, not a guarantee — PMOS hosts the terminal, it does not sit between the agent and the files'
+        : 'no session holds the writer claim on this tree' });
+  }
   // 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).
@@ -4019,7 +4265,7 @@ wss.on('connection', (ws) => {
   ws.on('message', (raw) => {
     let m; try { m = JSON.parse(raw); } catch { return; }
     // Gate the shell-spawning / PTY-feeding messages through the buckets before they do any work.
-    if ((m.t === 'new' || m.t === 'respawn') && !rateLimit.take(ws._rlSpawn)) {
+    if ((m.t === 'new' || m.t === 'start' || m.t === 'respawn') && !rateLimit.take(ws._rlSpawn)) {
       ws.send(JSON.stringify({ t: 'error', error: 'rate limited: too many session spawns — slow down' }));
       return;
     }
@@ -4043,6 +4289,15 @@ wss.on('connection', (ws) => {
       // 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 === 'start') {
+      // repo-first R1 — the one-click path. It carries an INITIATIVE (or none) and a repository,
+      // never a branch and never an isolate flag: those are the policy's to decide, and a client
+      // that could still send them would be a second place the rule lives.
+      const r = startWork({ initiative: m.initiative, repoKey: m.repoKey, ws: m.ws,
+        agent: m.agent, name: m.name, profile: m.profile });
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'start: ') + r.error })); return; }
+      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;
       // `respawn` is UNCHANGED on the wire (profiles R9): the profile is read off the record the
@@ -4147,6 +4402,10 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // non-repo folder from a real git fault, and the whole legibility defect was that distinction
   // being dropped one layer above it.
   repoIdentity, wsList,
+  // the shared-tree co-tenancy layer — exported so the suite can assert the KEY in both directions
+  // (one repo registered twice is one tree; two worktrees of one repo are two) without driving
+  // every case through a spawn.
+  treeForWs, treeTenants, treeWriter, treeClaims,
   // exported so the suite can assert the D08 invariant end-to-end: the harness parsers consume
   // scrubbed text, so a secret printed into scrollback must not survive into a rendered value.
   scrub, harnessOf,