create-pmos 0.16.1 → 0.18.0

package/README.md

@@ -333,6 +333,66 @@ 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
+version bump means an existing install auto-upgrades.
+
+- **An initiative's status is now read from what happened, not from what someone typed.** The
+  workspace took each initiative's state from a `status:` line written by hand into a PRD and
+  matched it against a list of words. In the repo this was built in, that one field held 23
+  different values, 33 initiatives had none at all, and several were cut off mid-sentence by a
+  stray comma. The plainest value of the lot — `build complete, PR #138` — matched the word
+  "build" first and displayed as *in progress*. Status is now derived from your acceptance
+  records, your logged runs, your open items, and your repository's own merge history, and each
+  row states which of those it was read from. Nothing you type can move it.
+- **`delivered` and `accepted` are no longer the same thing.** Work that merged and work you
+  actually signed off are now separate states. That gap is usually the interesting number: in the
+  repo this was built in, 62 of 63 delivered initiatives had no acceptance recorded — invisible
+  while both wore one label.
+- **The board reads your whole project history, not just the branch you are standing on.** It
+  shared a commit range with the CI gate, and that range is *empty* when your branch is level with
+  `main` — so every initiative reported "no implementation commits" and fell back to its earliest
+  stage. Work finished weeks ago looked identical to work never begun. The gate still reads only
+  the pull request, which is correct for judging whether a spec came before its build.
+- **A history it cannot read is now said out loud.** In a shallow clone (some CI checkouts) the
+  delivery history genuinely is not there. The board reports that, with the reason, instead of
+  quietly showing everything as unstarted — which would look exactly like a project where nothing
+  has happened.
+
+Unchanged where it matters: **no database, no network at runtime, no telemetry.** The server still
+binds `127.0.0.1` only. The file-mode kit itself is unchanged and still dependency-free.
+
 ## What's new in 0.16.1
 
 **Two fixes on the Terminal Workspace's entry path — how a repository reaches a running workspace.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.16.1",
+  "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@011b77e
+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/engine/workflow-state.js

@@ -164,25 +164,88 @@ function git(root, args) {
  * evaluated has not been satisfied, and saying so is the whole point of the honesty rule above.
  */
 function commitRange(root) {
+  return buildRange(root, { spec: null });
+}
+
+/*
+ * The BOARD's range: the whole trunk, not the pull request.
+ *
+ * These are two different questions and they were sharing an answer. The gate asks "inside this
+ * diff, did the spec precede the build?" — only decidable within the PR. The board asks "where does
+ * this initiative stand?", which the PR range cannot answer at all: on a branch level with `main`
+ * the range is EMPTY, so every initiative reported `no implementation commits in this range` and
+ * collapsed to stage `spec`. A delivered initiative rendered identically to one never started.
+ *
+ * Splitting them means a rule can read `done` on the board and still be evaluated inside the gate.
+ * That is intended and is stated in the board's own footer, so it never reads as a discrepancy.
+ */
+function historyRange(root) {
+  const trunk = ['origin/main', 'main', 'origin/master', 'master']
+    .find((c) => git(root, ['rev-parse', '--verify', '--quiet', c]));
+  return buildRange(root, { spec: trunk || 'HEAD', whole: true });
+}
+
+/*
+ * ONE pass over the range, not one git call per question.
+ *
+ * Two `git log` invocations build every index the ladder needs: which paths each commit CHANGED
+ * (for buildCommits) and where each path was ADDED (for firstAppearance). Previously firstAppearance
+ * shelled out once per path per initiative and buildCommits ran `git show` once per commit per
+ * initiative — 330+ processes for the board on an empty range (23 s), and O(commits × initiatives)
+ * on a full one, which is what made full history look impossible rather than merely unimplemented.
+ */
+function buildRange(root, { spec, whole }) {
   if ((git(root, ['rev-parse', '--is-shallow-repository']) || '').trim() === 'true') {
     return { ok: false, reason: 'shallow clone — no history to order commits by (CI needs fetch-depth: 0)' };
   }
-  const candidates = [];
-  if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
-  candidates.push('origin/main', 'main', 'origin/master', 'master');
   let base = null;
-  for (const c of candidates) {
-    if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
-    const mb = git(root, ['merge-base', c, 'HEAD']);
-    if (mb && mb.trim()) { base = mb.trim(); break; }
+  let range = spec;
+  if (!range) {
+    const candidates = [];
+    if (process.env.GITHUB_BASE_REF) candidates.push(`origin/${process.env.GITHUB_BASE_REF}`);
+    candidates.push('origin/main', 'main', 'origin/master', 'master');
+    for (const c of candidates) {
+      if (!git(root, ['rev-parse', '--verify', '--quiet', c])) continue;
+      const mb = git(root, ['merge-base', c, 'HEAD']);
+      if (mb && mb.trim()) { base = mb.trim(); break; }
+    }
+    range = base ? `${base}..HEAD` : 'HEAD';
   }
-  const spec = base ? `${base}..HEAD` : 'HEAD';
-  const log = git(root, ['log', '--reverse', '--format=%H', spec]);
+  const log = git(root, ['log', '--reverse', '--format=%x1e%H %ct', '--name-only', range]);
   if (log == null) return { ok: false, reason: 'git history unreadable' };
-  const shas = log.split('\n').map((s) => s.trim()).filter(Boolean);
+
+  const shas = [];
+  const changed = [];                 // index -> string[] of paths touched
+  const dates = [];                   // index -> commit unix seconds (what `legacy` is decided by)
+  for (const chunk of log.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const lines = chunk.split('\n');
+    const head = (lines.shift() || '').trim();
+    const [sha, ct] = head.split(/\s+/);
+    if (!sha) continue;
+    shas.push(sha);
+    dates.push(Number.isFinite(parseInt(ct, 10)) ? parseInt(ct, 10) : null);
+    changed.push(lines.map((s) => s.trim()).filter(Boolean));
+  }
   const index = new Map();
   shas.forEach((sha, i) => index.set(sha, i));
-  return { ok: true, base, index, shas, wholeHistory: !base };
+
+  // Where each path was ADDED, as an index into the same range. `--diff-filter=A` in one pass.
+  const added = new Map();
+  const addLog = git(root, ['log', '--reverse', '--format=%x1e%H', '--diff-filter=A', '--name-only', range]);
+  if (addLog != null) {
+    for (const chunk of addLog.split('\x1e')) {
+      if (!chunk.trim()) continue;
+      const lines = chunk.split('\n');
+      const sha = (lines.shift() || '').trim();
+      const at = index.has(sha) ? index.get(sha) : null;
+      if (at == null) continue;
+      for (const f of lines.map((s) => s.trim()).filter(Boolean)) {
+        if (!added.has(f)) added.set(f, at);
+      }
+    }
+  }
+  return { ok: true, base, index, shas, changed, dates, added, wholeHistory: whole ? true : !base };
 }
 
 /*
@@ -200,6 +263,10 @@ function commitRange(root) {
 function firstAppearance(root, range, rel) {
   const onDisk = fs.existsSync(path.join(root, rel));
   if (!range.ok) return onDisk ? undefined : null;
+  // The single-pass index answers first, and over the whole trunk it answers everything that has
+  // ever been committed — so the fallback below only runs for a PR range, where "added before the
+  // range" and "never committed" are genuinely different answers and only git can tell them apart.
+  if (range.added && range.added.has(rel)) return range.added.get(rel);
   const log = git(root, ['log', '--diff-filter=A', '--reverse', '--format=%H', '--', rel]);
   const sha = log ? log.split('\n').map((s) => s.trim()).filter(Boolean)[0] : null;
   if (!sha) return onDisk ? Infinity : null;
@@ -213,9 +280,10 @@ function buildCommits(root, range, lane) {
   if (!range.ok) return { unknown: true };
   let first = null; let count = 0; let sample = null;
   for (let i = 0; i < range.shas.length; i++) {
-    const files = git(root, ['show', '--name-only', '--format=', range.shas[i]]);
-    if (!files) continue;
-    const hit = files.split('\n').map((s) => s.trim()).filter(Boolean).find((f) => isBuildPath(f, lane));
+    // range.changed came from the range's own single pass; the per-commit `git show` this replaced
+    // ran once per commit PER INITIATIVE, which is why the board took 23 s before it read anything.
+    const files = (range.changed && range.changed[i]) || [];
+    const hit = files.find((f) => isBuildPath(f, lane));
     if (!hit) continue;
     count++;
     if (first === null) { first = i; sample = hit; }
@@ -290,10 +358,29 @@ function computeWorkflow(id, opts) {
   const effLane = knownLane ? lane : 'feature';           // unknown lane = strictest, as the bash gate does
   const range = (opts && opts.range) || commitRange(root);
   // See ENFORCED_FROM: git decides, the frontmatter only breaks a tie git cannot see.
+  //
+  // `recIdx === -1` — "the record predates this range" — is the right test for a PR range and a
+  // MEANINGLESS one over the whole trunk, where nothing predates the range and every legacy record
+  // would suddenly be enforced. So the commit DATE decides whenever the range can supply it, and
+  // -1 keeps its meaning for the gate's range. Same question, asked of evidence that survives both.
   const recIdx = firstAppearance(root, range, recRel);
-  const legacy = (recIdx === undefined || recIdx === null)
-    ? String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM   // fallback only — see ENFORCED_FROM
-    : recIdx === -1;
+  const recAt = (range.dates && typeof recIdx === 'number' && recIdx >= 0) ? range.dates[recIdx] : null;
+  /*
+   * `reconstructed_from` — the merge date of work whose record was written afterwards.
+   *
+   * A record backfilled today for a PR that merged in June has TODAY's commit date, so the date
+   * test would enforce today's rules on work that predates them and report a violation nobody
+   * could ever have avoided. The declared merge date decides instead.
+   *
+   * This is not an escape hatch: it must name a date, that date is checkable against the merge it
+   * claims, and declaring one AFTER `ENFORCED_FROM` makes the record non-legacy — so work that
+   * genuinely skipped the loop still reports blocked, which is the point of writing it down.
+   */
+  const recon = String(fm.reconstructed_from || '').trim().slice(0, 10);
+  const legacy = recIdx === -1 ? true
+    : /^\d{4}-\d{2}-\d{2}$/.test(recon) ? recon < ENFORCED_FROM
+      : recAt ? new Date(recAt * 1000).toISOString().slice(0, 10) < ENFORCED_FROM
+        : String(fm.timestamp || '').slice(0, 10) < ENFORCED_FROM;   // fallback — see ENFORCED_FROM
   /*
    * `legacy` answers the ENFORCEMENT question — should this PR fail? It is NOT the visibility
    * question. Filtering the board by it was a real bug: on `main`, every record is legacy, so the
@@ -304,7 +391,12 @@ function computeWorkflow(id, opts) {
    * `lastActivity` is the honest fallback for everything else, because "when was this last worked
    * on" is a fact the repo already holds and nobody has to maintain.
    */
-  const inChange = recIdx !== -1 && recIdx !== null && recIdx !== undefined;
+  // `● in this change` must keep meaning "the diff under review touches this". Over the whole trunk
+  // that is true of everything, which makes the marker noise — so the board passes the GATE's range
+  // separately and the marker is answered from that, or dropped when there is no such range.
+  const changeRange = (opts && opts.changeRange) || (range.wholeHistory ? null : range);
+  const chgIdx = changeRange ? firstAppearance(root, changeRange, recRel) : null;
+  const inChange = !!changeRange && chgIdx !== -1 && chgIdx !== null && chgIdx !== undefined;
   const lastActivity = (() => {
     const paths = [recRel, fm.prd_path, fm.rubric_path].filter(Boolean);
     const out = git(root, ['log', '-1', '--format=%ct', '--', ...paths]);
@@ -522,10 +614,14 @@ function computeWorkflow(id, opts) {
         steps.push(step('spec', 'spec', 'done', `${specNames} — first-appeared at or before the first build commit`));
       } else {
         const late = rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? rubric : prd;
-        steps.push(step('spec', 'spec', 'blocked',
+        // `legacy` applies here exactly as it does to O4. It always should have — the rule simply
+        // never fired for a legacy record while the board shared the gate's PR range, because an
+        // empty range has no build commit to be out of order with. Reading the trunk exposed it:
+        // 81 records that predate enforcement were suddenly failing a rule written after them.
+        steps.push(step('spec', 'spec', legacy ? 'unknown' : 'blocked',
           `ORDER VIOLATION — implementation (${build.sample}) was committed BEFORE ${late} first appeared`,
           'the rubric is the spec (D13). Land the spec artifacts in an earlier commit than the build, or split this PR so the spec lands first',
-          { blocking: true, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
+          { blocking: !legacy, rule: rubricIdx !== null && rubricIdx > build.first && prdIdx <= build.first ? 'O2' : 'O1' }));
       }
     }
   }
@@ -776,6 +872,10 @@ function renderBoard(rows, opts) {
   out.push('');
   // Never a silent cap — a truncated list that does not say so reads as "that is everything".
   if (hidden) out.push(`  ${c(33, `+ ${hidden} more without a recorded acceptance, not shown`)} ${c(90, `— node ${opts.self} --all`)}`);
+  // The two ranges, said out loud. The board reads the whole trunk so a delivered initiative does
+  // not render as unstarted; the gate reads the PR so "spec before build" stays decidable. A rule
+  // can therefore read done here and still be evaluated on the PR — intended, and not a discrepancy.
+  out.push(`  ${c(90, 'derived from the whole trunk history; the CI gate evaluates order within the PR only')}`);
   out.push(`  ${c(90, `one initiative in detail:  node ${opts.self} <id>`)}`);
   out.push('');
   return out.join('\n');
@@ -871,8 +971,12 @@ function main(argv) {
     return 0;
   }
 
-  const range = commitRange(root);
-  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range }));
+  // R-7: the BOARD reads the trunk, not the pull request. The gate path above keeps commitRange().
+  // The PR range is still computed and passed alongside — it is what `● in this change` means, and
+  // it is the one thing the trunk range genuinely cannot answer.
+  const range = historyRange(root);
+  const changeRange = commitRange(root);
+  const rows = listInitiatives(root).map((i) => computeWorkflow(i, { root, range, changeRange }));
   if (json) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
   if (!rows.length) { process.stdout.write('\n  no initiative records found — is this a PMOS repo?\n\n'); return 1; }
   process.stdout.write(renderBoard(rows, { self, all }));
@@ -882,6 +986,9 @@ function main(argv) {
 module.exports = {
   computeWorkflow, renderLadder, renderBoard, listInitiatives, layout, inFlight, BOARD_CAP,
   parseLeadingFrontmatter, specimenRoute, surfaceRoute, priorsCitation, isBuildPath, commitRange,
+  // the board's trunk range, exported so the suite can assert the split: the same record is legacy
+  // under BOTH ranges, and `in this change` is false under the trunk one.
+  historyRange,
   ENFORCED_FROM,
 };
 

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.16.1",
+  "version": "0.18.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.16.1",
+      "version": "0.18.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

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);
@@ -523,6 +583,10 @@ const ROLE_BY_DIR = {
   prd: 'PRD', evals: 'eval', design: 'design', research: 'research', briefs: 'brief',
   okrs: 'OKR', radar: 'radar', gtm: 'gtm', 'out-of-scope': 'rejected', 'harness-refine': 'harness',
   'design-export': 'design', explainers: 'explainer', fixtures: 'fixture',
+  // The initiative RECORD (planning/initiatives/<id>.md) is the canonical anchor+lane carrier and
+  // the only artifact that exists for work backfilled from a merge. Before it was a role, a record
+  // with no sibling PRD landed in `ungrouped` and the initiative was invisible here.
+  initiatives: 'record',
 };
 // ── D60 specimens: prototype/<id>/, deliberately OUTSIDE planning/ ───────────────────────────
 // The planning walk cannot reach them (planningRoots only finds `planning`), so a prototype leg was
@@ -575,17 +639,23 @@ function parseHead(full) {
     head = buf.slice(0, n).toString('utf8');
   } catch { return {}; }
   const id = head.match(/^\s*[-*]?\s*initiative_id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
+  // An initiative RECORD names itself with `id:`, not `initiative_id:`. Only the record role reads
+  // this (see docMeta) — a bare `id:` on any other document must not invent an initiative.
+  const rid = head.match(/^\s*id\s*:\s*["']?([A-Za-z0-9][\w.-]*)["']?\s*$/m);
   const h1 = head.match(/^#\s+(.+)$/m);
-  // status/stage/anchor ride the PRD's identity block — the only initiative signal that lives on
-  // disk today. RICE/effort/milestones/progress do NOT (net-new state) and are never invented.
+  // The anchor and the lane are DECLARED state and are read as such — they say what the work is
+  // pointed at, never how far along it is. `status:`/`stage:` are deliberately NOT read: they were
+  // hand-typed free text (23 distinct values in this repo, 33 absent, several truncated mid-YAML)
+  // funnelled through a regex, so `build complete, PR #138` rendered as `building`. Position is
+  // derived from evidence in deliveryIndex/deriveState instead — see the surface explainer.
   const clean = (m) => m ? m[1].replace(/\*\*/g, '').split(/\s+[—–-]\s|\(/)[0].trim().slice(0, 48) : null;
-  const status = head.match(/^\s*[-*]?\s*status\s*:\s*(.+?)\s*$/mi);
-  const stage = head.match(/^\s*[-*]?\s*stage\s*:\s*(.+?)\s*$/mi);
   const kr = head.match(/^\s*[-*]?\s*parent[_-]?kr\s*:\s*(.+?)\s*$/mi);
+  const lane = head.match(/^\s*[-*]?\s*lane\s*:\s*(.+?)\s*$/mi);
   return {
     initiative: id ? id[1] : null,
+    recordId: rid ? rid[1] : null,
     title: h1 ? h1[1].replace(/^(PRD|Eval Rubric|Design Brief)\s*:\s*/i, '').trim() : null,
-    status: clean(status), stage: clean(stage), kr: clean(kr),
+    kr: clean(kr), lane: clean(lane),
   };
 }
 function roleAndStem(rel, base) {
@@ -608,8 +678,9 @@ function docMeta(root, full) {
   const meta = {
     mtimeMs: st.mtimeMs, path: rel, name: base, role,
     // frontmatter wins; the filename convention is the fallback, never the override
-    initiative: head.initiative || null, stem, title: head.title || null,
-    status: head.status || null, stage: head.stage || null, kr: head.kr || null,
+    initiative: head.initiative || (role === 'record' ? head.recordId : null) || null,
+    stem, title: head.title || null,
+    kr: head.kr || null, lane: head.lane || null,
   };
   metaCache.set(full, meta);
   return meta;
@@ -650,17 +721,17 @@ function initiativeIndex(root) {
     const k = keyFor(m);
     const art = { name: m.name, path: m.path, role: m.role, title: m.title };
     if (!k) { ungrouped.push(art); continue; }
-    if (!groups.has(k)) groups.set(k, { id: k, title: null, status: null, stage: null, kr: null, artifacts: [] });
+    if (!groups.has(k)) groups.set(k, { id: k, title: null, kr: null, lane: null, artifacts: [] });
     const g = groups.get(k);
     g.artifacts.push(art);
     if (m.role === 'PRD' && m.title) g.title = m.title;      // the PRD names the initiative
     else if (!g.title && m.title) g.title = m.title;
-    // status/stage/anchor: the PRD is authoritative; any artifact fills a gap, never overrides it
-    if (m.status && (m.role === 'PRD' || !g.status)) g.status = m.status;
-    if (m.stage && (m.role === 'PRD' || !g.stage)) g.stage = m.stage;
-    if (m.kr && (m.role === 'PRD' || !g.kr)) g.kr = m.kr;
+    // The anchor and lane are the RECORD's to declare (D56/D59 — it is what the gates read); the
+    // PRD fills a gap for legacy initiatives that predate repo-native records, never overrides it.
+    if (m.kr && (m.role === 'record' || !g.kr)) g.kr = m.kr;
+    if (m.lane && (m.role === 'record' || !g.lane)) g.lane = m.lane;
   }
-  const ROLE_ORDER = ['PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
+  const ROLE_ORDER = ['record', 'PRD', 'rubric', 'eval', 'design brief', 'design', 'reconcile', 'dogfood'];
   const initiatives = [...groups.values()].map((g) => {
     g.artifacts.sort((a, b) => {
       const ia = ROLE_ORDER.indexOf(a.role), ib = ROLE_ORDER.indexOf(b.role);
@@ -695,57 +766,207 @@ function library(root) {
 // client renders it; a surface that can't be produced returns ok:false and the client shows an
 // honest can't-produce state. RICE/effort/milestones/progress are NET-NEW state → emitted as null
 // ("— not tracked"), never invented (D14/D40 honesty).
-const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', landed: 'report' };
-function statusKey(raw) {
-  const s = String(raw || '').toLowerCase();
-  if (/block/.test(s)) return 'blocked';
-  if (/ship|merg|accept|closed|done|live/.test(s)) return 'landed';
-  if (/build|progress|in build|dogfood/.test(s)) return 'building';
-  if (/intake|spec|plan|draft|propos/.test(s)) return 'planning';
+const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', delivered: 'report', accepted: 'report', unknown: 'plan' };
+
+// ── Delivery evidence (board-delivery-truth R-2/R-3). ──────────────────────────────────────────
+// "Has this shipped?" answered from the trunk's own history rather than from anything anyone typed.
+//
+// ONE `git log` per trunk head, memoised on that sha — ~0.3s and ~800 KB on this repo's 1,214
+// commits, paid once and reused by every surface until the trunk moves. Local only: git reads the
+// object store on disk, so the suite's "no network" guarantee (K. Surfaces) is untouched.
+//
+// TWO signals, because one is not enough. The branch convention (`initiative/<id>`) is precise but
+// incomplete: 31% of this repo's merged PRs shipped on `claude/*` branches, which match no id. So a
+// commit that MENTIONS the id and TOUCHES a build path counts too. The build-path requirement is
+// what keeps the mention signal honest — `feat(planning): add <id> PRD` mentions the id while
+// delivering nothing, and without the path test every specified initiative would read as shipped.
+const BUILD_EXCLUDE = /^(planning|okf|prototype)\//;
+function isDeliveryPath(f) {
+  if (!f) return false;
+  if (BUILD_EXCLUDE.test(f)) return false;
+  return !/^[^/]+\.md$/.test(f);      // root governance prose (DECISIONS.md, CLAUDE.md…) is not a build
+}
+const deliveryCache = new Map();      // root -> { head, index }
+function trunkRef(root) {
+  for (const c of ['origin/main', 'main', 'origin/master', 'master']) {
+    const r = gitCap(root, ['rev-parse', '--verify', '--quiet', c]);
+    if (r.ok && r.out.trim()) return { ref: c, head: r.out.trim() };
+  }
   return null;
 }
-function statusFrom(g) {
-  return statusKey(g.status) || statusKey(g.stage) || 'planning';
+function gitCap(root, args) {
+  try {
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || r.status !== 0) return { ok: false, out: '', err: (r.stderr || (r.error && r.error.message) || '').trim() };
+    return { ok: true, out: r.stdout || '' };
+  } catch (e) { return { ok: false, out: '', err: String((e && e.message) || e) }; }
+}
+/**
+ * → { ok, reason?, byBranch:Set<id>, byMention:Set<id> }
+ * `ok:false` is a REAL answer and never degrades into "nothing was delivered" — the caller renders
+ * it red and marks every initiative's delivery `unknown` (R-3). A board that cannot read the
+ * history must say so; silently reporting `planning` for 110 shipped initiatives is the failure
+ * this whole initiative exists to remove.
+ */
+function deliveryIndex(root, ids) {
+  const t = trunkRef(root);
+  if (!t) return { ok: false, reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived', byBranch: new Set(), byMention: new Set() };
+  const hit = deliveryCache.get(root);
+  if (hit && hit.head === t.head) return hit.index;
+
+  // %x1e separates commits, %x1f separates the message from --name-only's file list.
+  const r = gitCap(root, ['log', '--format=%x1e%s %b%x1f', '--name-only', t.head]);
+  if (!r.ok) {
+    return { ok: false, reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`, byBranch: new Set(), byMention: new Set() };
+  }
+  const byBranch = new Set(), byMention = new Set();
+  const known = Array.isArray(ids) ? ids : [...ids];
+  for (const chunk of r.out.split('\x1e')) {
+    if (!chunk.trim()) continue;
+    const cut = chunk.indexOf('\x1f');
+    const msg = cut < 0 ? chunk : chunk.slice(0, cut);
+    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
+    for (const m of msg.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) byBranch.add(m[1]);
+    if (!files.some(isDeliveryPath)) continue;
+    for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
+  }
+  const index = { ok: true, byBranch, byMention };
+  deliveryCache.set(root, { head: t.head, index });
+  return index;
+}
+/**
+ * The five states, in precedence order. Every one of them names the artifact it was read from, so
+ * the surface can show its own evidence instead of asking to be trusted.
+ *
+ * `blocked` deliberately outranks `delivered`: work the PM RETURNED is work that needs them, and
+ * hiding that behind a delivery glyph would reproduce, in a new place, the exact failure of a board
+ * that reports green over a red underneath. (The PRD's R-1 table lists delivered first; this is the
+ * one ordering departure, made because the alternative buries a returned initiative.)
+ */
+function deriveState(ev) {
+  if (ev.accepted) return { state: 'accepted', why: `accepted by the PM${ev.acceptedAt ? ` on ${String(ev.acceptedAt).slice(0, 10)}` : ''}` };
+  if (ev.returned) return { state: 'blocked', why: 'the PM returned this at the Acceptance Gate' };
+  if (ev.needs) return { state: 'blocked', why: `${ev.needs} open item${ev.needs > 1 ? 's' : ''} in needs.json` };
+  // Not `planning`. An unreadable history means the evidence for the delivery states is missing,
+  // and `planning` is itself a claim ("nothing has happened") that the missing evidence cannot
+  // support. `unknown` is the only honest answer, and it is visibly not a resting state.
+  if (ev.delivery === 'unknown') return { state: 'unknown', why: 'the trunk history could not be read — delivery cannot be derived here' };
+  if (ev.deliveredBy) return { state: 'delivered', why: ev.deliveredBy === 'branch' ? 'an initiative/<id> branch merged to the trunk' : 'a commit on the trunk names this initiative and changes build files' };
+  if (ev.runs) return { state: 'building', why: `${ev.runs} run${ev.runs > 1 ? 's' : ''} logged, nothing merged yet` };
+  return { state: 'planning', why: 'no run, no merge, no acceptance — nothing has happened yet' };
+}
+// BOTH acceptance ledgers, oldest-wins-never: the workspace writes to its state dir, while the
+// ladder and every hand-recorded acceptance in pmos-self live in planning/runs/. Reading only the
+// state dir is why this surface reported 0 accepted against 23 real acceptance rows — the same
+// "one field, several readers, none agreeing" defect the anchor resolver was built to end.
+function acceptanceFilesFor(w) {
+  const out = [];
+  const d = stateDirFor(w);
+  if (d) out.push(path.join(d, 'acceptances.jsonl'));
+  if (w && w.root) out.push(path.join(w.root, 'planning', 'runs', 'acceptances.jsonl'));
+  return out;
 }
 function readAcceptances(w) {
-  const acc = new Map();   // initiative_id -> last action (accept | approve | return)
-  const f = acceptancesFileFor(w);
-  if (!f) return acc;
-  try {
-    for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+  const acc = new Map();   // initiative_id -> { action, at }
+  for (const f of acceptanceFilesFor(w)) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
       if (!line.trim()) continue;
       // Tolerate both shapes: this server's {action} and the kit's {accepted} (D54 adapter).
+      // THE BOOLEAN OUTRANKS THE LABEL. `action` is an open vocabulary describing what the PM did
+      // — this corpus holds accept, merge, publish, return — while `accepted` is the D12 verdict
+      // itself. Reading `action` first (the previous behaviour) meant every row labelled `merge` or
+      // `publish` carried `accepted: true` and was still not counted: 7 of 16 real acceptances went
+      // missing, and the surface reported those initiatives as merely `building`.
       try {
         const r = JSON.parse(line);
         if (!r.initiative_id) continue;
-        acc.set(r.initiative_id, r.action || (r.accepted === true ? 'accept' : r.accepted === false ? 'return' : null));
+        const label = String(r.action || '').toLowerCase();
+        const action = r.accepted === true ? 'accept'
+          : r.accepted === false ? 'return'
+            : label === 'return' ? 'return'
+              : ['accept', 'approve', 'merge', 'publish'].includes(label) ? 'accept'
+                : null;
+        const at = r.at || r.date || null;
+        // Last write wins, but a row with no timestamp never displaces a dated one.
+        const prev = acc.get(r.initiative_id);
+        if (prev && prev.at && !at) continue;
+        acc.set(r.initiative_id, { action, at });
       } catch {}
     }
-  } catch {}
+  }
   return acc;
 }
+// How many runs each initiative has logged — evidence that work STARTED, which is the only thing
+// separating `building` from `planning`. The file is the same one the ladder reads.
+function readRunCounts(w) {
+  const counts = new Map();
+  const d = stateDirFor(w);
+  const files = [];
+  if (d) files.push(path.join(d, 'agent-runs.jsonl'));
+  if (w && w.root) files.push(path.join(w.root, 'planning', 'runs', 'agent-runs.jsonl'));
+  for (const f of files) {
+    let text = '';
+    try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const r = JSON.parse(line);
+        if (r && r.initiative_id) counts.set(r.initiative_id, (counts.get(r.initiative_id) || 0) + 1);
+      } catch {}
+    }
+  }
+  return counts;
+}
 function surfaceInitiatives(root, w) {
   const { initiatives } = initiativeIndex(root);
   const acc = readAcceptances(w);
+  const runs = readRunCounts(w);
+  const needsRaw = readNeeds(w) || [];
+  const needsBy = new Map();
+  for (const n of needsRaw) if (n && n.initiative_id) needsBy.set(n.initiative_id, (needsBy.get(n.initiative_id) || 0) + 1);
+
+  const del = deliveryIndex(root, initiatives.map((g) => g.id));
   const items = initiatives.map((g) => {
-    const sk = statusFrom(g);
+    const a = acc.get(g.id) || {};
+    const deliveredBy = !del.ok ? null : del.byBranch.has(g.id) ? 'branch' : del.byMention.has(g.id) ? 'mention' : null;
+    const { state, why } = deriveState({
+      accepted: a.action === 'accept' || a.action === 'approve', acceptedAt: a.at,
+      returned: a.action === 'return',
+      needs: needsBy.get(g.id) || 0,
+      delivery: del.ok ? 'known' : 'unknown',
+      deliveredBy,
+      runs: runs.get(g.id) || 0,
+    });
     return {
       id: g.id, title: g.title || null,
-      status: sk, statusText: g.status || g.stage || sk, phase: PHASE_OF[sk] || 'plan',
-      stage: g.stage || null, kr: g.kr || null,
-      accepted: acc.get(g.id) === 'accept',
-      artifacts: g.artifacts.map((a) => ({ role: a.role, name: a.name, path: a.path })),
+      status: state, statusText: why, phase: PHASE_OF[state] || 'plan',
+      // `stage` was the declared field this surface used to trust. It is gone, not renamed —
+      // the client renders `statusText`, which always names the artifact the state was read from.
+      stage: null, kr: g.kr || null, lane: g.lane || null,
+      accepted: state === 'accepted',
+      delivered: state === 'accepted' || state === 'delivered',
+      delivery_evidence: deliveredBy,
+      artifacts: g.artifacts.map((a2) => ({ role: a2.role, name: a2.name, path: a2.path })),
       // NET-NEW state — not on disk yet, so null (the surface renders "— not tracked", never a guess)
       rice: null, effort: null, milestones: null, progress: null, tracked: false,
     };
   });
   const by = (k) => items.filter((i) => i.status === k).length;
-  const needs = (readNeeds(w) || []).map((n) => ({
+  const needs = needsRaw.map((n) => ({
     t: n.question || '(unstated)', kind: n.kind || 'question', initiative_id: n.initiative_id || null,
   }));
   return {
     initiatives: items,
-    pulse: { total: items.length, planning: by('planning'), building: by('building'), blocked: by('blocked'), landed: by('landed') },
+    pulse: {
+      total: items.length, planning: by('planning'), building: by('building'),
+      blocked: by('blocked'), delivered: by('delivered'), accepted: by('accepted'),
+      unknown: by('unknown'),
+    },
+    // R-3: a failed read is reported, never absorbed. The client renders this RED above the list
+    // rather than letting 110 shipped initiatives quietly read `planning`.
+    delivery_read: del.ok ? null : (del.reason || 'the trunk history could not be read'),
     needs,
   };
 }
@@ -755,7 +976,7 @@ function surfaceRoadmap(root, w) {
     label, dates_tracked: false,
     items: items.filter((i) => keys.includes(i.status)).map((i) => ({ id: i.id, status: i.status, phase: i.phase, progress: i.progress })),
   });
-  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['landed'])]
+  const groups = [bucket('In flight', ['building', 'blocked']), bucket('Planned', ['planning']), bucket('Landed', ['delivered', 'accepted'])]
     .filter((g) => g.items.length);
   return { groups, note: 'dates are net-new state — grouped by status until a timeline is tracked' };
 }
@@ -932,12 +1153,16 @@ function surfaceReport(root, w) {
   const s = surfaceInitiatives(root, w);
   const line = (i) => `${i.id}${i.title ? ' — ' + i.title : ''}`;
   const inflight = s.initiatives.filter((i) => i.status === 'building' || i.status === 'blocked');
-  const landed = s.initiatives.filter((i) => i.status === 'landed');
+  // Delivered and accepted are reported SEPARATELY, not summed into one "landed" heading. The gap
+  // between them is the D12 Acceptance Gate's backlog — the number this report exists to surface.
+  const delivered = s.initiatives.filter((i) => i.status === 'delivered');
+  const accepted = s.initiatives.filter((i) => i.status === 'accepted');
   const sections = [
     { heading: 'In flight', items: inflight.map(line) },
-    { heading: 'Landed', items: landed.map(line) },
+    { heading: 'Delivered — acceptance not recorded', items: delivered.map(line) },
+    { heading: 'Accepted', items: accepted.map(line) },
     { heading: 'Needs you', items: s.needs.map((n) => n.t) },
-    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.landed} landed`] },
+    { heading: 'Metrics pulse', items: [`${s.pulse.total} initiatives · ${s.pulse.building} building · ${s.pulse.blocked} blocked · ${s.pulse.delivered} delivered · ${s.pulse.accepted} accepted`] },
   ];
   return { cadence: 'weekly', sections };
 }
@@ -1307,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);
@@ -1339,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
@@ -1757,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;
@@ -1775,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 }));
@@ -1852,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 ──────────────
@@ -1868,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);
@@ -1972,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;
 }
@@ -2782,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
@@ -3228,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).
@@ -3608,10 +3913,27 @@ async function handleRequest(req, res) {
       'and useful answer.',
     ].filter((l) => l !== '').join('\n');
 
+    // NOT typed blind into the PTY. An agent CLI opening a folder it has never seen shows a
+    // trust prompt first — and a fresh tenant repo is by definition such a folder, so the case this
+    // feature exists for is the exact case where blind input is swallowed by a security dialog and
+    // the drafting silently never happens. Found by installing the published kit and watching a real
+    // session sit at "Is this a project you trust?" with the prompt already gone.
+    //
+    // Auto-answering that dialog is not on the table: it is the PM's decision, not ours. So the
+    // prompt is PERSISTED and STAGED instead — it cannot be lost, and the PM sends it once the agent
+    // is actually at its input.
+    const promptFile = path.join(adir, 'prompt-' + Date.now() + '.md');
+    try { fs.writeFileSync(promptFile, prompt + '\n'); }
+    catch (e) { warnWriteFail('alignment prompt', e); return json(res, { ok: false, error: 'could not stage the drafting prompt' }, 500); }
+
     const s = spawnSession({ name: 'align: ' + path.basename(rel), agent: 'claude', ws: w.id,
-      origin: 'align:' + rel, initialInput: prompt + '\r' });
+      origin: 'align:' + rel });
     const started = !!(s && s.pty);
+    let staged = false;
+    if (started) { try { writeScratchpad(w, s.id, prompt); staged = true; } catch {} }
     return json(res, { ok: started, sessionId: s && s.id, targets, sink: adir,
+      prompt_file: promptFile, staged,
+      next: started ? 'the drafting prompt is staged in this session\'s scratchpad — answer any trust prompt the agent shows, then send it' : undefined,
       error: started ? undefined : ((s && s.note) || 'could not start the session') });
   }
   if (p === '/api/align/drafts') {
@@ -3626,8 +3948,19 @@ async function handleRequest(req, res) {
     let doc;
     try { doc = JSON.parse(fs.readFileSync(path.join(adir, pick), 'utf8')); }
     catch { return json(res, { ok: false, error: `the draft file '${pick}' is unreadable or not valid JSON` }, 500); }
-    const drafts = Array.isArray(doc.drafts) ? doc.drafts.filter((d) => d && typeof d.file === 'string') : [];
-    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts });
+    // A malformed draft is REFUSED at read, not half-rendered (contract crit 4). Silently dropping a
+    // bad draft would let the agent's mistake reach the PM as a shorter, unexplained list — the same
+    // "looks fine, is wrong" failure the anchored write guard exists to stop. An empty `drafts` array
+    // is valid and calm (crit 3): the agent looked and found nothing to realign.
+    if (!Array.isArray(doc.drafts)) {
+      return json(res, { ok: false, error: `the draft file '${pick}' has no drafts array — the agent did not produce the documented shape` }, 422);
+    }
+    for (const d of doc.drafts) {
+      if (!d || typeof d.file !== 'string' || typeof d.after !== 'string' || (d.before != null && typeof d.before !== 'string')) {
+        return json(res, { ok: false, error: `a draft in '${pick}' is missing a file or an after — refusing to render a partial set (crit 4)` }, 422);
+      }
+    }
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts: doc.drafts });
   }
   if (p === '/api/align/apply' && req.method === 'POST') {
     // Apply ONE drafted realignment. Same anchored guard as everything else that writes here: the
@@ -3954,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,
@@ -3969,4 +4306,9 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   // where the anchor resolver is looked for — exported so the suite can assert the INSTALL
   // location is in the list. A dev checkout satisfies entry 1 and would hide the loss of entry 2
   // exactly as it hid the workflow engine's absence for four releases (PKG4).
-  ANCHOR_LIB_PATHS };
+  ANCHOR_LIB_PATHS,
+  // the delivery derivation (board-delivery-truth), exported so the suite can assert the three
+  // things that matter independently of a rendered page: that no declared field reaches a status,
+  // that an unreadable history reports rather than degrades, and that a planning-only commit does
+  // not count as delivery.
+  surfaceInitiatives, deliveryIndex, deriveState, isDeliveryPath };