create-pmos 0.8.0 → 0.10.0

package/workspace/lib/git-info.js

@@ -1,25 +1,51 @@
 'use strict';
 // Read-mostly git helpers for the workspace (branch awareness + select/create at session start).
 // Everything here shells `git` via spawnSync with an ARGS ARRAY — never a shell string — so no
-// caller input is ever interpolated into a command line. A workspace's working tree is SHARED by
-// every session in it (D62), so a branch is a property of the REPO, not a session: switching moves
-// every session in that repo. Callers surface that truth; this module never pretends otherwise.
+// caller input is ever interpolated into a command line.
+//
+// Two truths this module exists to keep straight:
+//   1. A workspace's working tree is SHARED by every session in it (D62), so `checkout` is a
+//      property of the REPO, not a session: switching moves every session in that repo — and every
+//      OTHER workspace registered under the same repo too. Callers surface that; we never pretend.
+//   2. The way OUT of that shared-tree constraint is a linked worktree: `addWorktree` gives a
+//      branch its own directory, so a new session can start on a new branch while every running
+//      session stays exactly where it was. That is the isolated path, and it is the default the
+//      UI offers for "+ new branch".
+//
+// "Is this a repo?" is answered by `git rev-parse`, NOT by looking for a `.git` entry: a workspace
+// registered at a SUBDIRECTORY of a repo (common for a tenant product repo added by path) is
+// inside git, and reporting "not a git repository" there was a lie that cost the PM real time.
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
 const GIT_TIMEOUT = 5000;   // never let a slow/hung repo (huge tree, network remote) block the server
 
-function isRepo(root) {
-  // a normal repo has a `.git` dir; a linked worktree has a `.git` FILE — both count.
-  try { return !!root && fs.existsSync(path.join(root, '.git')); } catch { return false; }
-}
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
 
 function git(root, args) {
   const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT });
   return { code: r.status, out: (r.stdout || '').trim(), err: (r.stderr || '').trim(), failed: !!r.error };
 }
 
+// The repo's top-level directory, or null when `root` is not inside a repo. Works from any depth,
+// which is the whole point: a workspace at repo/packages/app is still in git.
+function repoRoot(root) {
+  if (!root || !isDir(root)) return null;
+  const r = git(root, ['rev-parse', '--show-toplevel']);
+  if (r.failed || r.code !== 0 || !r.out) return null;
+  const top = r.out.split('\n')[0].trim();
+  return top ? path.resolve(top) : null;
+}
+
+function isRepo(root) {
+  if (!root) return false;
+  if (repoRoot(root)) return true;
+  // git absent from PATH: fall back to the on-disk marker so we don't call a real repo "not a
+  // repo". A normal repo has a `.git` dir; a linked worktree has a `.git` FILE — both count.
+  try { return fs.existsSync(path.join(root, '.git')); } catch { return false; }
+}
+
 // git check-ref-format for a BRANCH name, re-implemented defensively so nothing dubious ever
 // reaches `git` (defense in depth — `git` itself is the final authority and rejects the rest).
 // Rejects: empty, whitespace/control, the special chars ~ ^ : ? * [ \ , the sequences .. and @{,
@@ -38,25 +64,42 @@ function validBranchName(name) {
   return true;
 }
 
-// { ok, current, branches[], detached, dirty }. A non-repo or a failed git returns ok:false with a
-// reason — NEVER a fabricated branch (a wrong branch chip is worse than none; anti-drift).
-function branchInfo(root) {
-  if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
-  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
-  if (head.failed) return { ok: false, error: 'git not available' };
-  if (head.code !== 0) return { ok: false, error: head.err || 'could not read HEAD' };
-  const detached = head.out === 'HEAD';
-  const current = detached ? null : head.out;
-  const refs = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
-  const branches = refs.code === 0 && refs.out ? refs.out.split('\n').filter(Boolean) : [];
-  const status = git(root, ['status', '--porcelain']);
-  const dirty = status.code === 0 ? status.out.length > 0 : false;
-  return { ok: true, current, branches, detached, dirty };
+// Every working tree attached to this repo: [{ dir, branch|null }]. Used for two honest answers —
+// "this branch is already open over there" (git will refuse a second checkout of it, so the picker
+// says so instead of letting the PM hit a raw git error) and "here is where an isolated session
+// would land".
+function worktrees(root) {
+  const top = repoRoot(root);
+  return top ? worktreesAt(top) : [];
+}
+// same, for a caller that already resolved the top (saves a `git rev-parse` per call)
+function worktreesAt(top) {
+  const r = git(top, ['worktree', 'list', '--porcelain']);
+  if (r.failed || r.code !== 0 || !r.out) return [];
+  const out = [];
+  let cur = null;
+  for (const line of r.out.split('\n')) {
+    if (line.startsWith('worktree ')) { cur = { dir: line.slice(9).trim(), branch: null }; out.push(cur); }
+    else if (cur && line.startsWith('branch ')) cur.branch = line.slice(7).trim().replace(/^refs\/heads\//, '');
+  }
+  return out;
 }
 
-// Check out an existing branch, or create one with -b. Confined to `root` by cwd; the name is
-// validated first so nothing malformed reaches git. On any failure returns { ok:false, error } and
-// leaves the caller to NOT spawn a session on the wrong branch (a failed checkout must never spawn).
+// Where an isolated worktree lands: a sibling of the repo, gathered under one `<repo>-worktrees/`
+// folder. Deliberately OUTSIDE the repo — nothing new appears inside the tree, so no `git status`
+// noise and nothing for .gitignore to chase. The path is derived from a name already passed
+// through validBranchName (charset A–Za–z0–9._/-, no `..`, no leading `.`), so the only
+// transformation needed is '/' → '-' to keep it one directory segment.
+function worktreePath(root, branch) {
+  const top = repoRoot(root);
+  if (!top || !validBranchName(branch)) return null;
+  return path.join(path.dirname(top), path.basename(top) + '-worktrees', branch.replace(/\//g, '-'));
+}
+
+// Check out an existing branch, or create one with -b. THIS MOVES THE WHOLE REPO — every session
+// in every workspace under it. Confined to `root` by cwd; the name is validated first so nothing
+// malformed reaches git. On any failure returns { ok:false, error } and leaves the caller to NOT
+// spawn a session on the wrong branch (a failed checkout must never spawn).
 function checkout(root, branch, { create = false } = {}) {
   if (!isRepo(root)) return { ok: false, error: 'not a git repository' };
   if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
@@ -68,4 +111,133 @@ function checkout(root, branch, { create = false } = {}) {
   return { ok: true, current: info.ok ? info.current : branch };
 }
 
-module.exports = { isRepo, validBranchName, branchInfo, checkout };
+// Put `branch` in its OWN working tree, so a session can start on it while every already-running
+// session stays untouched. `create` makes the branch (`-b`); otherwise the branch must exist and
+// must not already be checked out somewhere else (git refuses — we return that plainly).
+// Returns { ok, dir, branch, reused } or { ok:false, error }.
+function addWorktree(root, branch, { create = false } = {}) {
+  const top = repoRoot(root);
+  if (!top) return { ok: false, error: 'not a git repository' };
+  if (!validBranchName(branch)) return { ok: false, error: 'invalid branch name' };
+
+  // Already checked out somewhere? Say where, rather than letting git's message be the first the
+  // PM sees — and if it is exactly the worktree we would have made, reuse it instead of failing.
+  const dir = worktreePath(top, branch);
+  const existing = worktreesAt(top).find((w) => w.branch === branch);
+  if (existing) {
+    if (create) return { ok: false, error: `branch '${branch}' already exists (checked out at ${existing.dir})` };
+    if (path.resolve(existing.dir) === path.resolve(dir)) return { ok: true, dir, branch, reused: true };
+    return { ok: false, error: `branch '${branch}' is already checked out at ${existing.dir} — git allows one working tree per branch` };
+  }
+  if (fs.existsSync(dir)) return { ok: false, error: `${dir} already exists — move or remove it, or pick another branch name` };
+
+  try { fs.mkdirSync(path.dirname(dir), { recursive: true }); }
+  catch (e) { return { ok: false, error: `cannot create ${path.dirname(dir)}: ${e.code || e.message}` }; }
+
+  const args = create ? ['worktree', 'add', '-b', branch, dir] : ['worktree', 'add', dir, branch];
+  const r = git(top, args);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) {
+    // never leave a half-made directory behind to block the next attempt
+    try { if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir); } catch {}
+    return { ok: false, error: (r.err || r.out || 'worktree add failed').split('\n').filter(Boolean).pop().slice(0, 200) };
+  }
+  return { ok: true, dir, branch, reused: false };
+}
+
+// Everything needed to decide whether a worktree can be removed WITHOUT losing work. Two hazards
+// live in git itself, and each is reported BY NAME so the UI can say why rather than just greying
+// out a button:
+//   dirty          — uncommitted or untracked files sitting in the tree
+//   unique commits — commits on this branch that no other branch, remote or tag holds, so removing
+//                    the tree is the last thing standing between them and `git gc`
+// Anything unreadable counts as unsafe: this gates a delete, so "I could not check" must never
+// read as "fine". (The caller adds the two hazards git cannot see: live sessions in the tree, and
+// "this is the repo's main worktree".)
+function worktreeSafety(dir, branch) {
+  const reasons = [];
+  const st = git(dir, ['status', '--porcelain']);
+  const dirty = st.failed || st.code !== 0 ? true : st.out.length > 0;
+  if (dirty) reasons.push(st.code === 0 ? 'uncommitted changes' : 'its state could not be read');
+
+  let unique = 0;
+  if (!branch) {
+    unique = -1;
+    reasons.push('detached HEAD — no branch names its commits');
+  } else {
+    // "commits reachable from this branch and from nothing else". --exclude applies to the NEXT
+    // ref-listing option only, so --branches drops this branch while --remotes and --tags still
+    // count: a copy on a remote means the commits survive the removal.
+    const rl = git(dir, ['rev-list', '--count', 'refs/heads/' + branch,
+      '--not', '--exclude=' + branch, '--branches', '--remotes', '--tags']);
+    unique = rl.code === 0 && /^\d+$/.test(rl.out) ? parseInt(rl.out, 10) : -1;
+    if (unique > 0) reasons.push(`${unique} commit${unique === 1 ? '' : 's'} not on any other branch or remote`);
+    if (unique < 0) reasons.push('could not verify its commits exist elsewhere');
+  }
+  return { removable: reasons.length === 0, reasons, dirty, unique };
+}
+
+// Remove a linked worktree, refusing anything that would lose work. `dir` arrives from a client, so
+// it is never passed through as given: it must match one of THIS repo's linked worktrees (git's own
+// list is the allowlist), and the main worktree is unreachable by construction. The BRANCH is left
+// alone — a branch is a cheap pointer, and deleting one is a different decision than reclaiming a
+// directory.
+function removeWorktree(root, dir) {
+  const top = repoRoot(root);
+  if (!top) return { ok: false, error: 'not a git repository' };
+  const trees = worktreesAt(top);
+  // index 0 is always the main worktree — sliced off, so it can never be the target
+  const target = trees.slice(1).find((w) => path.resolve(w.dir) === path.resolve(String(dir || '')));
+  if (!target) return { ok: false, error: 'not a linked worktree of this repository' };
+
+  // Gone from disk already (the PM deleted it by hand): there is nothing to protect, just stale
+  // bookkeeping to clear.
+  if (!isDir(target.dir)) {
+    const p = git(top, ['worktree', 'prune']);
+    if (p.code !== 0) return { ok: false, error: (p.err || 'prune failed').split('\n')[0].slice(0, 200) };
+    return { ok: true, dir: target.dir, pruned: true };
+  }
+
+  const safety = worktreeSafety(target.dir, target.branch);
+  if (!safety.removable) return { ok: false, error: 'kept — ' + safety.reasons.join('; '), safety };
+  const r = git(top, ['worktree', 'remove', target.dir]);
+  if (r.failed) return { ok: false, error: 'git not available' };
+  if (r.code !== 0) return { ok: false, error: (r.err || r.out || 'worktree remove failed').split('\n').filter(Boolean).pop().slice(0, 200) };
+  return { ok: true, dir: target.dir, branch: target.branch, pruned: false };
+}
+
+// { ok, current, branches[], detached, dirty, repoRoot, subdir, linked, worktrees[] }. A non-repo
+// or a failed git returns ok:false with a reason — NEVER a fabricated branch (a wrong branch chip
+// is worse than none; anti-drift). `subdir` is the workspace's path INSIDE the repo ('' at the
+// top): non-empty means a checkout here moves a tree larger than this workspace, which the UI says
+// out loud.
+function branchInfo(root) {
+  // `code` lets a caller tell the two failures apart without matching on prose: `no-git` is a
+  // perfectly normal folder (a tenant product repo with no git at all) and deserves no alarm;
+  // `git-error` is something the PM may want to look at.
+  const top = repoRoot(root);
+  if (!top) {
+    if (!isRepo(root)) return { ok: false, code: 'no-git', error: 'not a git repository' };
+    return { ok: false, code: 'git-error', error: 'git not available' };
+  }
+  const head = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head.failed) return { ok: false, code: 'git-error', error: 'git not available' };
+  if (head.code !== 0) return { ok: false, code: 'git-error', error: head.err || 'could not read HEAD' };
+  const detached = head.out === 'HEAD';
+  const current = detached ? null : head.out;
+  const refs = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']);
+  const branches = refs.code === 0 && refs.out ? refs.out.split('\n').filter(Boolean) : [];
+  const status = git(root, ['status', '--porcelain']);
+  const dirty = status.code === 0 ? status.out.length > 0 : false;
+  const rel = path.relative(top, path.resolve(root));
+  const trees = worktreesAt(top);
+  const linked = path.resolve(top) !== path.resolve(trees[0] ? trees[0].dir : top);
+  return {
+    ok: true, current, branches, detached, dirty,
+    repoRoot: top, subdir: rel === '' || rel === '.' ? '' : rel, linked,
+    worktrees: trees.map((w) => ({ dir: w.dir, branch: w.branch })),
+  };
+}
+
+module.exports = { isRepo, repoRoot, validBranchName, branchInfo, checkout, worktrees, worktreePath,
+  addWorktree, worktreeSafety, removeWorktree };

package/workspace/lib/related-docs.js

@@ -0,0 +1,107 @@
+/* related-docs — which OTHER documents does this change put out of step?
+ * (workspace-doc-editor · R5/R6)
+ *
+ * Pure: takes the changed file, what changed in it, and a list of {path, text} for the repository's
+ * other documents. Returns candidates with a stated reason. No filesystem, no network, so the
+ * scoring rules are unit-testable directly and the endpoint stays a thin caller.
+ *
+ * R6 is the constraint that shapes everything here: **alignment is scoped by the change, not by the
+ * repository.** A pass that re-reads everything is a review by another name — the exact feature this
+ * one replaced, arriving through the back door. So a document only becomes a candidate if it has a
+ * concrete tie to the thing that changed:
+ *
+ *   - it LINKS to the changed file, or names it in frontmatter (prd_path, rubric_path, …)
+ *   - it shares the changed file's initiative_id
+ *   - it QUOTES text the change removed or altered
+ *
+ * "Feels related" is deliberately not a rule. Semantic similarity would widen this to everything and
+ * put the PM back in front of a queue of an agent's opinions, which is what they said they did not
+ * want. If references miss something, that is a known and accepted cost, recorded in the PRD.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.RelatedDocs = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  /** `key: value` from a leading frontmatter block. Tolerates a missing block. */
+  function frontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---/.exec(String(text || ''));
+    if (!m) return {};
+    const out = {};
+    for (const line of m[1].split('\n')) {
+      const i = line.indexOf(':');
+      if (i < 1) continue;
+      out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+  }
+
+  /* Phrases worth searching other documents for. Short or generic lines match everything and would
+   * turn precision into noise, so a line must be substantial to qualify — and only a few are used,
+   * because each one costs a scan of every document. */
+  function phrasesFrom(removedText, min = 24, max = 4) {
+    return String(removedText || '')
+      .split('\n')
+      .map((l) => l.replace(/^[\s>#*\-+\d.]+/, '').trim())
+      .filter((l) => l.length >= min && /[a-z]{4}/i.test(l))
+      .sort((a, b) => b.length - a.length)
+      .slice(0, max);
+  }
+
+  /**
+   * candidates({ changedPath, changedText, removed, docs })
+   *   changedPath — repo-relative path of the document just saved
+   *   changedText — its full text after the save (for its own frontmatter)
+   *   removed     — the text the save removed or replaced (drives the quote rule)
+   *   docs        — [{ path, text }] for the repository's other markdown documents
+   * → [{ path, reasons: [string], strength }] sorted strongest first. Never throws.
+   */
+  function candidates({ changedPath, changedText, removed, docs } = {}) {
+    const target = String(changedPath || '');
+    if (!target || !Array.isArray(docs)) return [];
+    const base = target.split('/').pop();
+    const mine = frontmatter(changedText);
+    const initiative = mine.initiative_id || mine.id || null;
+    const phrases = phrasesFrom(removed);
+    const out = [];
+
+    for (const d of docs) {
+      if (!d || typeof d.path !== 'string' || d.path === target) continue;
+      const text = String(d.text || '');
+      const reasons = [];
+
+      // 1. links to the changed file — by full repo path or by filename
+      if (text.includes(target) || new RegExp('\\(([^)]*/)?' + esc(base) + '\\)').test(text)) {
+        reasons.push('links to this document');
+      }
+      // 2. frontmatter points at it (prd_path, rubric_path, and anything else path-shaped)
+      const fm = frontmatter(text);
+      for (const [k, v] of Object.entries(fm)) {
+        if (typeof v === 'string' && v && (v === target || v.endsWith('/' + base))) {
+          reasons.push(`its ${k} is this document`);
+        }
+      }
+      // 3. same initiative — the artifacts of one piece of work move together
+      if (initiative && (fm.initiative_id === initiative || fm.id === initiative)) {
+        reasons.push(`same initiative (${initiative})`);
+      }
+      // 4. quotes text this change removed or altered — the strongest signal there is, because the
+      //    other document is now asserting something the source no longer says
+      for (const ph of phrases) {
+        if (text.includes(ph)) { reasons.push(`quotes text this change altered: "${ph.slice(0, 60)}…"`); break; }
+      }
+
+      if (reasons.length) {
+        const quotes = reasons.some((r) => r.startsWith('quotes text'));
+        out.push({ path: d.path, reasons, strength: reasons.length + (quotes ? 2 : 0) });
+      }
+    }
+    return out.sort((a, b) => b.strength - a.strength || a.path.localeCompare(b.path));
+  }
+
+  return { candidates, frontmatter, phrasesFrom };
+});

package/workspace/lib/session-state.js

@@ -0,0 +1,139 @@
+/* session-state — the presented state of a session, joined from the workspace's TWO sources.
+ * (workspace-waiting-on-you R2/R3/R4/R5/R6.)
+ *
+ * One source of truth for "what word goes beside this session", used on BOTH sides:
+ *   - server.js requires it (sessionList publishes the joined state)
+ *   - the browser loads it as /lib/session-state.js before app.js (window.PMOSSessionState)
+ * so the sidebar and the server can never hold different opinions about one session. That is not
+ * hypothetical tidiness: QUIET_AFTER_MS was once re-typed as a literal in app.js, two copies of one
+ * number free to drift, and the fix was to ship it from one place. A duplicated TABLE fails the
+ * same way with more surface area.
+ *
+ * ── THE TWO SOURCES, AND WHY NEITHER IS ENOUGH ALONE ────────────────────────────────────────
+ *   CADENCE   (harness-parse.deriveState ← lastOutputAt)  answers  "is anything happening?"
+ *   STRUCTURE (transcript-read.turn      ← the JSONL)     answers  "whose turn is it?"
+ *
+ * Cadence alone cannot tell a finished turn from a crash from a slow tool — which is why
+ * workspace-harness-tower's R1 forbade upgrading `quiet` to "waiting on you", and why that rule is
+ * SATISFIED here rather than repealed: the stronger words are built from BOTH, and every cell
+ * without corroboration still says exactly what it said before.
+ *
+ * The two contributions are NOT symmetric, and pretending otherwise would be the first step toward
+ * over-claiming:
+ *   - for `needs`   the transcript is load-bearing and the quiet clock is only a SETTLE-TIMER
+ *                   (the terminal is still painting the final block for a moment after a turn ends)
+ *   - for `blocked` the transcript only says a call is open; the quiet clock does the real
+ *                   discriminating, because a running tool emits bytes and a permission prompt does not
+ *
+ * ── THE PROPERTY THIS FILE EXISTS TO GUARANTEE (R4) ─────────────────────────────────────────
+ * `needs` is reachable ONLY from turn === 'user', and transcript-read sets 'user' only when NO
+ * tool_use is unresolved. A crashed session's dangling call is a permanent phantom (2/25 real
+ * transcripts) and a phantom IS an unresolved call — so a phantom can only ever reach `tool`, and
+ * `needs` is UNCONSTRUCTABLE for it.
+ *
+ * There is deliberately NO `if (!phantom)` anywhere here. A check is a thing a later change can
+ * forget to call; a state that cannot be built needs no discipline to stay honest. This is the same
+ * discipline as the shipped "age without liveness is refused" — and if you are editing this file,
+ * the test that matters is `needs you` over the join's WHOLE domain, not one example of it.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSSessionState = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  // The cadence clock's three values (harness-parse.deriveState) — this module's first input.
+  const CADENCE = ['working', 'quiet', 'exited'];
+  // The transcript's answer to whose turn it is — this module's second input. `null` = no answer,
+  // which is the NORMAL case for a shell/codex session and for any claude session whose transcript
+  // cannot be resolved. It is not an error and draws no apology.
+  const TURN = ['user', 'agent', 'tool', null];
+  // What can end up on screen. The first three are pre-existing and unchanged; the last two are
+  // this feature. `failed` is absent by design — it has no observable (harness-tower).
+  const PRESENTED = ['working', 'quiet', 'exited', 'needs', 'blocked'];
+
+  // The word beside the glyph. Deliberately separate from the key: `blocked`'s word names its own
+  // uncertainty, because its evidence cannot distinguish a permission prompt from a hung tool from
+  // a corpse. The surface may not launder that into confidence.
+  const WORD = {
+    working: 'working',
+    quiet: 'quiet',
+    exited: 'exited',
+    needs: 'needs you',
+    blocked: 'maybe blocked',
+  };
+
+  // Filled = corroborated by both sources, hollow = suspected from one. `needs` takes ◆, which has
+  // sat declared-but-dead in the client's GLYPH map since the harness tower; this makes it live.
+  const GLYPH = { working: '●', quiet: '◼', exited: '○', needs: '◆', blocked: '◇' };
+
+  // Which presented states may carry the open call's verb + age. Unchanged for `working` (shipped
+  // behaviour); extended to `blocked`, where the age is the most informative part of a weak claim —
+  // "a call has been open 6m and nothing is moving" is the whole signal.
+  const CARRIES_CALL_AGE = { working: true, blocked: true };
+
+  /**
+   * THE JOIN (R2). Total over CADENCE × TURN: every one of the twelve cells is defined here, and
+   * `presentedStates()` below exists so a test can walk the domain rather than sample it.
+   *
+   * Pure: no clock read, no I/O, no DOM. The caller supplies the already-derived cadence state, so
+   * this function cannot disagree with `deriveState` about the threshold — it never sees one.
+   *
+   *   turn ↓ / cadence →   working    quiet          exited
+   *   'user'               working    NEEDS          exited
+   *   'tool'               working    BLOCKED        exited
+   *   'agent'              working    quiet          exited
+   *   null                 working    quiet          exited
+   *
+   * Three cells change from pre-feature behaviour. The other nine are byte-identical, and that is
+   * asserted rather than assumed.
+   */
+  function presented(cadence, turn) {
+    // `exited` is the server's own lifecycle fact and outranks anything the transcript says: a
+    // transcript is a file that outlives its process, so a dead session's last record would
+    // otherwise keep claiming a turn forever.
+    if (cadence === 'exited') return 'exited';
+    // Bytes are arriving. Whatever the transcript says, something IS happening, so no stronger
+    // claim is available or needed — and this is what stops `needs` firing during the moment the
+    // terminal is still painting the turn it just finished.
+    if (cadence === 'working') return 'working';
+    if (cadence !== 'quiet') return 'working';   // unknown cadence ⇒ the weakest live word, never a claim
+    // Quiet. Only here can the transcript raise the claim above `quiet`.
+    if (turn === 'user') return 'needs';         // turn ended AND nothing moving ⇒ the human is up
+    if (turn === 'tool') return 'blocked';       // a call is open AND nothing moving ⇒ suspect
+    return 'quiet';                              // 'agent' (model call in flight) or null (no source)
+  }
+
+  /** Every (cadence, turn, presented) triple. The domain is small — walk it, don't sample it. */
+  function presentedStates() {
+    const out = [];
+    for (const cadence of CADENCE) {
+      for (const turn of TURN) out.push({ cadence, turn, presented: presented(cadence, turn) });
+    }
+    return out;
+  }
+
+  /** Does this presented state make the strong "this session wants you" claim? */
+  function isNeedsClaim(p) { return p === 'needs'; }
+
+  /**
+   * The full label for a row or tab: the word, plus the quiet clock's age on `quiet`, plus the open
+   * call's verb and age where the state carries it. `fmtDur` is injected (the client and the server
+   * format durations for different audiences) and the ages are computed by the CALLER, because this
+   * module reads no clock.
+   */
+  function label(p, { quietMs = null, call = null, fmtDur = null } = {}) {
+    const w = WORD[p] || p;
+    const d = (ms) => (fmtDur && ms != null ? fmtDur(ms) : null);
+    if (p === 'quiet') { const s = d(quietMs); return s ? `${w} ${s}` : w; }
+    if (CARRIES_CALL_AGE[p] && call && call.verb) {
+      const s = d(call.ageMs);
+      return s ? `${w} · ${call.verb} ${s}` : `${w} · ${call.verb}`;
+    }
+    return w;
+  }
+
+  return { CADENCE, TURN, PRESENTED, WORD, GLYPH, CARRIES_CALL_AGE,
+    presented, presentedStates, isNeedsClaim, label };
+});

package/workspace/lib/transcript-read.js

@@ -168,7 +168,7 @@ function prettyTool(name) {
  */
 function readHarness(file, clean = (x) => x) {
   const out = { model: null, effort: null, turns: 0, tokens: null, tools: null, skills: null,
-    title: null, openCall: null, missing: {} };
+    title: null, openCall: null, turn: null, missing: {} };
   let raw;
   try {
     const st = fs.statSync(file);
@@ -199,6 +199,11 @@ function readHarness(file, clean = (x) => x) {
   // report the raw fact {verb, sinceTs}; we never claim it is live.
   const openUse = new Map();       // tool_use_id → { verb, ts }  (insertion order = chronological)
   const resolved = new Set();      // tool_use_ids that got a tool_result
+  // WHOSE TURN IS IT (workspace-waiting-on-you R1). The last TURN-TAKING record's role — nothing
+  // more. `ai-title` and `attachment` records are CLI bookkeeping and are deliberately not
+  // turn-taking, and neither is a SYNTHETIC assistant record: counting one as "the assistant
+  // finished speaking" is exactly how a false `needs you` would be manufactured.
+  let lastRole = null;             // 'assistant' | 'user' | null
 
   for (const line of raw.split('\n')) {
     if (!line) continue;
@@ -217,6 +222,7 @@ function readHarness(file, clean = (x) => x) {
       for (const c of (Array.isArray(um.content) ? um.content : [])) {
         if (c && c.type === 'tool_result' && c.tool_use_id) resolved.add(c.tool_use_id);
       }
+      lastRole = 'user';           // a prompt was submitted, or a tool result landed
       continue;
     }
     if (r.type === 'attachment') {
@@ -234,6 +240,7 @@ function readHarness(file, clean = (x) => x) {
     if (m.model && m.model !== SYNTHETIC) {
       out.model = clean(m.model);
       out.turns++;                                  // only real model turns count
+      lastRole = 'assistant';                       // ...and only a real turn takes the turn
       if (r.effort) out.effort = clean(String(r.effort));
     }
     const u = m.usage || {};
@@ -260,6 +267,19 @@ function readHarness(file, clean = (x) => x) {
     if (!resolved.has(id)) out.openCall = { verb: info.verb, sinceTs: info.ts };
   }
 
+  // ── Whose turn (R1). Derived here, from what the pass already collected — no second walk. ──
+  // The ORDER of these three branches is the honesty property the whole feature rests on (R4).
+  // `tool` is tested FIRST, so any unresolved call claims the turn. A crashed session's dangling
+  // tool_use is a PERMANENT phantom (2/25 real transcripts), and a phantom is by definition an
+  // unresolved call — so a phantom always lands on `tool`, and `user` (the only turn from which
+  // the strong `needs you` claim can be built) is UNREACHABLE for it. Not a guard that rejects
+  // the phantom: a value it cannot construct. Reordering these branches silently converts a
+  // corpse into "waiting on you", which is the one lie this surface must not tell.
+  if (out.openCall) out.turn = 'tool';              // awaiting a tool — OR the PM's approval of one
+  else if (lastRole === 'assistant') out.turn = 'user';   // the model stopped; the human is up
+  else if (lastRole === 'user') out.turn = 'agent';       // a prompt/result landed; the model is up
+  // else: null — nothing turn-taking was parseable, so no claim is made.
+
   if (!out.model) out.missing.model = 'the transcript names no model yet';
   if (!out.effort) out.missing.effort = 'the transcript records no effort level';
   if (toolTotal) out.tools = { counts: toolCounts, total: toolTotal };
@@ -271,11 +291,13 @@ function readHarness(file, clean = (x) => x) {
   else out.missing.tokens = 'the transcript records no token usage yet';
   if (!out.skills) out.missing.skills = 'the CLI listed no skills for this session';
   if (!out.turns) out.missing.turns = 'no model turns in the transcript yet';
-  // NOTE: `title` and `openCall` deliberately get NO `missing` entry. This map carries reasons the
-  // UI RENDERS in place of a value; both of these instead fall back to a real shipped rendering
-  // (agent · cwd for an untitled session; the plain `working`/`quiet` word when no call is open).
-  // Putting them here would break the map's contract — "empty missing == everything was readable" —
-  // and put a reason on screen where a perfectly good value already goes.
+  // NOTE: `title`, `openCall` and `turn` deliberately get NO `missing` entry. This map carries
+  // reasons the UI RENDERS in place of a value; all three instead fall back to a real shipped
+  // rendering (agent · cwd for an untitled session; the plain `working`/`quiet` word when no call
+  // is open and when the turn is unknown). Putting them here would break the map's contract —
+  // "empty missing == everything was readable" — and put a reason on screen where a perfectly good
+  // value already goes. For `turn` that fallback IS the feature's refusal rule (R5): no second
+  // source, no claim, and the row reads exactly as it did before this existed.
 
   return out;
 }

package/workspace/package.json

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