create-pmos 0.17.0 → 0.18.0

package/README.md

@@ -333,6 +333,36 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.18.0
+
+**Several sessions in one folder now say so.** Run `npx create-pmos@latest workspace`; the version
+bump means an existing install auto-upgrades.
+
+- **Starting a session where others are already running tells you what you are sharing.** Sessions
+  in one checkout share one branch, one index and one set of files — that was true before and
+  nothing said it. The new session's pane now names the sessions already there and points at the
+  alternative (a new branch in its own folder). It appears on the ordinary "＋ session" path too,
+  where no git operation runs at all: the server had already worked out that other sessions would
+  be disturbed, and was throwing the answer away unless you happened to pick a branch.
+- **It counts the right thing.** A repository registered at two paths — the project root and a
+  subdirectory of it, the ordinary shape when you add a product repo by path — is **one** checkout,
+  and its sessions are now told about each other; before, each was told it was alone. Two
+  *worktrees* of one repository are **two** checkouts and are deliberately not warned about, because
+  those are the sessions that isolation already made safe. A folder with no git says nothing, since
+  there is no index to collide over.
+- **One session is the declared writer; the rest read.** The first live session in a checkout holds
+  the claim, and you can hand it to another (`POST /api/tree/claim`); `GET /api/tree/peers` reports
+  who holds it and who else is there. It moves only when you move it — never on a timer or an exit —
+  and when its holder exits the checkout reads *vacant* rather than promoting somebody at random.
+- **Be clear about what that is: a declaration, not a lock.** The workspace hosts your agent's
+  terminal; it does not sit between the agent and the files, so nothing here prevents a write, a
+  checkout or a commit, and no session is ever refused because another one is there. It makes a
+  shared checkout visible. The discipline stays yours.
+- **A folder you are working in can no longer be reclaimed out from under you.** Removing a
+  worktree already refused when sessions were running in it — but it counted only sessions in the
+  workspace registered at that exact folder, so a session running in a subdirectory of it was
+  invisible. It is counted now, and named in the refusal.
+
 ## What's new in 0.17.0
 
 **Your board stops calling shipped work unstarted.** Run `npx create-pmos@latest workspace`; the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@4cb5198
+kernel-source: pmos@83f52ff
 assembled: 2026-07-31
 mode: vendor

package/workspace/README.md

@@ -155,6 +155,31 @@ the folder and **keeps the branch**; nothing is ever removed automatically. Git
 between worktrees, so what a folder costs is a checkout of tracked files, not a second copy of the
 repo.
 
+## Several sessions in one tree: you are told, never stopped
+
+Sessions in one working tree share **one branch, one index and one set of files**. Starting a
+session in a tree that already has live ones now says so in the pane — naming them, and naming the
+way out (⑂ a new branch in its own folder). It fires on the plain `＋ session` path too, where no
+git operation runs at all: the server already knew, and used to say nothing.
+
+**The tree is the unit, not the folder you registered.** A repo registered twice — say `~/repo` and
+`~/repo/packages/app`, the ordinary shape for a product repo added by path — is **one** tree, and
+its sessions are told about each other. Two *worktrees* of one repo are **two** trees, and are not
+warned about at all: those are the sessions isolation made safe. A folder with no git has no tree
+and says nothing, because there is no index to collide over.
+
+**The writer claim is a declaration, not a lock.** The first live session in a tree holds it; the
+others read. `GET /api/tree/peers?ws=…` reports the tree, its holder and every session on it;
+`POST /api/tree/claim {session}` hands it over. It moves **only** when you move it — never on a
+timer, never on an exit. When the holder exits the tree reads *vacant*, and no survivor is
+promoted, because which pane should be driving is your intention and not something to derive.
+
+Be clear about what this buys: **PMOS hosts your agent's terminal, it does not sit between it and
+the files.** Nothing here prevents a write, a checkout or a commit, and no spawn is ever refused
+because someone else is in the tree. It makes a shared tree visible; the discipline is still yours.
+(The role rides on `/api/sessions` rows as `tree` / `tree_role` / `tree_peers`; the tab-bar chip is
+not wired yet.)
+
 A workspace anywhere **inside** a repo knows its branch — a subdirectory (`repo/packages/app`)
 counts, which matters for a product repo added by path. A folder with **no git** simply says so and
 starts the session; nothing about git can block work in a repo that doesn't use it.

package/workspace/lib/tree-share.js

@@ -0,0 +1,129 @@
+'use strict';
+// Who shares a working tree with whom, and who is DECLARED to be driving it.
+//
+// The premise, stated once so nothing below has to hedge: PMOS hosts real PTYs and the agent CLI
+// inside one is untouched (D62). There is nothing between an agent and the filesystem, so this
+// module cannot prevent a write, a checkout or a commit — and never claims to. What it can do is
+// compute the right SET of sessions that would collide, and carry one declaration about which of
+// them the PM says is driving. Advisory, and every sentence it produces says so.
+//
+// The one idea worth holding: **three keys look like "which repo is this" and only one of them is
+// the collision unit.**
+//   • the workspace id  — a registered DIRECTORY. Too narrow: one repo can be registered twice
+//     (`~/repo` and `~/repo/packages/app`, the ordinary shape for a tenant repo added by path),
+//     and those two ids share one HEAD, one index, one set of files.
+//   • `repo_key`        — the repository, i.e. its MAIN worktree. Too wide: it deliberately groups
+//     a repo's linked worktrees, which are exactly the sessions that are SAFELY isolated. Warning
+//     on those is how a warning gets trained away.
+//   • the working-tree top (`git rev-parse --show-toplevel`) — one HEAD, one index, one
+//     `index.lock`. This is the one. A folder with no git has no tree key, and therefore no
+//     co-tenants: there is no index to corrupt, so there is nothing to say.
+//
+// Pure functions over plain rows, on purpose: the server owns the git shell-outs and the session
+// registry, and the rules are the part worth testing without either.
+
+/** Live = a session the PM could still be driving. `exited` is a corpse and collides with nobody. */
+function isLive(s) { return !!s && s.state !== 'exited'; }
+
+/**
+ * The live sessions sharing `tree`, excluding one id (normally the session asking).
+ * `treeOfWs` maps a workspace id → its working-tree top (null for a folder with no git).
+ * A null/empty `tree` matches nothing — "not in a repo" is never a group.
+ */
+function coTenants(sessions, treeOfWs, tree, exclude) {
+  if (!tree) return [];
+  const out = [];
+  for (const s of sessions || []) {
+    if (!isLive(s) || s.id === exclude) continue;
+    if (treeOfWs.get(s.ws) === tree) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * Who holds the writer claim on `tree` — or null when nobody does.
+ *
+ * The claim is stored, but it is only BELIEVED while its holder is live: a claim is a statement
+ * about a running session, and a dead session cannot be driving anything. Deriving the answer this
+ * way is what makes "the holder exited" read as **vacant** rather than as a stale name, without a
+ * cleanup pass having to be correct for the UI to be honest.
+ *
+ * Note what this deliberately does NOT do: promote the oldest survivor. Which pane should drive is
+ * the PM's intention, not an observable, and a derived answer must never impersonate a decision.
+ */
+function writerOf(claims, treeOfWs, sessions, tree) {
+  if (!tree) return null;
+  const held = claims.get(tree);
+  if (!held) return null;
+  const s = (sessions || []).find((x) => x && x.id === held);
+  if (!isLive(s) || treeOfWs.get(s.ws) !== tree) return null;
+  return held;
+}
+
+/** 'writer' | 'reader' for a session in a tree; null when it is not in one (no git → no role). */
+function roleOf(sessionId, tree, writerId) {
+  if (!tree) return null;
+  return sessionId === writerId ? 'writer' : 'reader';
+}
+
+/** Name a handful of panes without letting a 12-session tree produce a paragraph. */
+function nameList(rows, cap = 3) {
+  const names = (rows || []).map((s) => `“${s.name}”`);
+  if (names.length <= cap) return names.join(', ');
+  return `${names.slice(0, cap).join(', ')} and ${names.length - cap} more`;
+}
+
+/**
+ * The sentence a session gets when it starts in a tree somebody is already working in.
+ *
+ * It names the panes (a bare count tells the PM nothing they can act on), states the ONE fact that
+ * makes this matter — a shared branch, index and file set — and names the way out that already
+ * exists, because a warning with no alternative is just a nag. Returns null when there is nobody
+ * there, so the caller never has to test for emptiness.
+ */
+function coTenancyNotice(mates, opts) {
+  const rows = mates || [];
+  if (!rows.length) return null;
+  const n = rows.length;
+  const role = opts && opts.role === 'writer' ? 'writer' : 'reader';
+  const held = opts && opts.writerName;
+  const who = role === 'writer'
+    // Vacant tree: this session took the claim. Say so — the PM should know a declaration was made
+    // on their behalf, not discover it later in a list.
+    ? 'nobody had claimed it, so this session now holds the writer claim'
+    : held
+      ? `“${held}” holds the writer claim`
+      : 'no session holds the writer claim';
+  return `${n} session${n === 1 ? '' : 's'} already running in this working tree (${nameList(rows)}) — `
+    + `you share one branch, one index and one set of files with ${n === 1 ? 'it' : 'them'}. ${who}. `
+    + 'Claims are advisory: PMOS hosts your agent’s terminal, it does not sit between it and the '
+    + 'files. To work in parallel for real, start the session on a new branch with its own folder (⑂).';
+}
+
+/**
+ * The same fact, written into the pane's own scrollback at spawn.
+ *
+ * The notice frame is a transient line in whichever client was listening; this one is part of the
+ * session's record, so re-opening the tab tomorrow still shows what it was told. Dim, one line,
+ * and it never claims anything was prevented.
+ */
+function paneAdvisory(mates, opts) {
+  const line = coTenancyNotice(mates, opts);
+  if (!line) return null;
+  return `\x1b[38;5;244m⑂ ${line}\x1b[0m\r\n`;
+}
+
+/**
+ * Carry two non-fatal truths on a channel that has only ever carried one.
+ *
+ * `spawnWithBranch` returns a single `notice` string and, until now, at most one of its facts could
+ * be set at a time. A branch notice and a co-tenancy notice can both be true of the same spawn, and
+ * the second must not evict the first — dropping one would make the wire format quietly lossy in
+ * exactly the situation the PM most needs both.
+ */
+function joinNotices(...parts) {
+  const kept = parts.filter((p) => p != null && String(p).trim() !== '');
+  return kept.length ? kept.join(' · ') : null;
+}
+
+module.exports = { isLive, coTenants, writerOf, roleOf, coTenancyNotice, paneAdvisory, joinNotices, nameList };

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.17.0",
+      "version": "0.18.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/server.js

@@ -71,6 +71,7 @@ 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 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 +313,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 +341,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);
@@ -1472,7 +1532,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 +1573,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
@@ -1922,6 +2003,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 +2022,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 +2100,16 @@ 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) };
 }
 
 // ── Worktree housekeeping: the app that creates the folders shows and clears them ──────────────
@@ -2033,7 +2125,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 +2233,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;
 }
@@ -2947,6 +3047,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
@@ -3393,6 +3512,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).
@@ -4147,6 +4287,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,