create-pmos 0.8.0 → 0.9.0

package/README.md

@@ -333,6 +333,30 @@ 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.9.0
+
+**The Terminal Workspace now tells you whose turn it is.** The optional GUI got this release's real
+work: it reads each session's transcript and shows, per session, whether the agent is still working
+or **waiting on you** — so a wall of terminals becomes a queue you can triage at a glance instead of
+a grid you have to click through.
+
+- **Whose-turn, read from the actual transcript.** Each session row and tab carries its state —
+  agent-working vs waiting-on-you — derived from the real conversation, not a guess. The sessions
+  that need a decision surface; the ones still running recede.
+- **A real design system, not a dev-tool skin.** The workspace was reskinned on a proper palette
+  with its own typography, and the fonts ship *inside* the package — nothing is fetched at runtime,
+  so it looks the same offline and behind a proxy.
+- **Your git branch is in the frame.** Each session shows the branch it is on and lets you switch,
+  so `initiative/<id>` work and its worktree are visible where you are working, not a `git status`
+  away.
+- **The router now makes you write the answers down.** `pmos-router` gained a step: the intake
+  answers (does this need its own instance? has this been rejected before?) get recorded on the
+  initiative, so a routing decision is enforceable later instead of evaporating the moment it's made.
+
+All of this rides in `npx create-pmos@latest workspace`. The file-mode kit itself is unchanged and
+still dependency-free; `npx create-pmos@latest --update` brings the router change into an existing
+kit and never touches your `state/`, `planning/`, or `okf/product/` records.
+
 ## What's new in 0.8.0
 
 **The document review is gone. There is a document editor instead.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.8.0",
+  "version": "0.9.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@f56d5eb
+kernel-source: pmos@bb26298
 assembled: 2026-07-28
 mode: vendor

package/payload/skills/pmos-router.skill

@@ -68,6 +68,28 @@ router is the bug (fix it via the weekly harness scan).
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
 [working-in-pmos](/okf/core/playbooks/working-in-pmos.md).
 
+## Step 5 — WRITE THE ANSWERS DOWN (this is what makes any of it enforceable)
+
+Steps 0.3 and 0.4 used to be asked aloud and then discarded, and the cost was exactly what you would
+predict: nothing could check that a *needs-an-instance* answer was followed by a prototype, or that
+an *existing surface* was explained before it was specified. An unrecorded answer is an
+unenforceable one. So both land on the initiative record, as a **leading token plus your reasoning**:
+
+```yaml
+specimen_test: "needs-instance — no description settles whether …"       # or "description-judgeable — …"
+predecessor: <prototype-initiative-id>       # required when the answer is needs-instance
+surface_check: "existing — the Initiative Gate"                          # or "greenfield — …"
+explainer_path: planning/explainers/<surface>-explainer.md               # required when it is existing
+```
+
+The gate ([`scripts/workflow-state.js`](/scripts/workflow-state.js)) reads the **token** and the
+**ordering of the paths it implies** — the prose is for the PM. It fails a PR whose PRD first
+appeared before its prototype brief (**O3**) or before its surface explainer (**O4**). It does not
+judge whether the answer was *right*: no deterministic check can decide that, and over-firing the
+specimen test twice running stays a D41 tripwire on the test's wording, not a gate condition.
+
+Check your position at any time with `node scripts/workflow-state.js <id>`.
+
 ## Edge rules
 
 - **Two shapes at once** (an idea that is also a bet): sharpness first, then the brief-offer, then

package/payload/skills-native/pmos-router/SKILL.md

@@ -70,6 +70,28 @@ router is the bug (fix it via the weekly harness scan).
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
 [working-in-pmos](/okf/core/playbooks/working-in-pmos.md).
 
+## Step 5 — WRITE THE ANSWERS DOWN (this is what makes any of it enforceable)
+
+Steps 0.3 and 0.4 used to be asked aloud and then discarded, and the cost was exactly what you would
+predict: nothing could check that a *needs-an-instance* answer was followed by a prototype, or that
+an *existing surface* was explained before it was specified. An unrecorded answer is an
+unenforceable one. So both land on the initiative record, as a **leading token plus your reasoning**:
+
+```yaml
+specimen_test: "needs-instance — no description settles whether …"       # or "description-judgeable — …"
+predecessor: <prototype-initiative-id>       # required when the answer is needs-instance
+surface_check: "existing — the Initiative Gate"                          # or "greenfield — …"
+explainer_path: planning/explainers/<surface>-explainer.md               # required when it is existing
+```
+
+The gate ([`scripts/workflow-state.js`](/scripts/workflow-state.js)) reads the **token** and the
+**ordering of the paths it implies** — the prose is for the PM. It fails a PR whose PRD first
+appeared before its prototype brief (**O3**) or before its surface explainer (**O4**). It does not
+judge whether the answer was *right*: no deterministic check can decide that, and over-firing the
+specimen test twice running stays a D41 tripwire on the test's wording, not a gate condition.
+
+Check your position at any time with `node scripts/workflow-state.js <id>`.
+
 ## Edge rules
 
 - **Two shapes at once** (an idea that is also a bet): sharpness first, then the brief-offer, then

package/workspace/README.md

@@ -94,6 +94,34 @@ tokens, JWTs, `Authorization:` values, api keys): scrollback holds whatever the
 so D08's never-log-headers discipline applies to what this hands back. Matching runs against
 the *scrubbed* text, so the endpoint cannot be used to grep a secret out.
 
+## Branches: a new one doesn't move the others
+
+Starting a session, the branch control is **optional** — the default is "stay on current" and it
+performs no git operation at all. When you do pick one:
+
+- **`+ new branch…`** can give that branch its **own working tree**, at
+  `../<repo>-worktrees/<branch>` (a sibling of the repo — nothing appears inside it, nothing for
+  `.gitignore` to chase), registered as its own workspace. Every session already running stays
+  exactly where it was. The folder is named in the form before you commit to it, and again in the
+  footer once it exists.
+- **That's the default only when there are sessions to protect.** Alone in a workspace a plain
+  checkout disturbs nobody, so no folder is made. The checkbox is yours to flip either way.
+- **Unchecking "give it its own folder"** is the shared-tree checkout: this repo moves, and so does
+  every session in it. The hint counts them, and only warns when something really would move.
+- A branch can live in **one** working tree at a time. One already open elsewhere is labelled with
+  its location in the picker, rather than failing later.
+
+**⑂ worktrees** in the sidebar lists every working tree the repo has, and removes the ones that are
+safe to remove. A removal is refused — with the reason — when the tree has sessions running in it,
+uncommitted changes, or commits that no other branch, remote or tag holds. Removing one reclaims
+the folder and **keeps the branch**; nothing is ever removed automatically. Git history is shared
+between worktrees, so what a folder costs is a checkout of tracked files, not a second copy of the
+repo.
+
+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.
+
 ## Boundaries (honest v1 seams)
 - **Server binds 127.0.0.1** — the D62 hosted-PTY-bridge rejection stands; a tailnet/phone client
   attaches to the same local server, never a public endpoint.

package/workspace/lib/console-state.js

@@ -114,4 +114,59 @@ function radar({ stateDir, snapshotDir }) {
   } };
 }
 
-module.exports = { metrics, radar, computeMetricsFromRuns, loadJson, loadJsonl };
+/*
+ * ── workflow: where each initiative is, what is next, what is blocking ────────────────────────
+ *
+ * The one surface that answers "where am I in the loop" without the PM reconstructing it from
+ * files. It renders the SAME ladder the CLI and the Initiative Gate print, from the same engine —
+ * `scripts/workflow-state.js` — so the panel can never disagree with what CI is about to say.
+ *
+ * The engine is the one BUNDLED WITH THE WORKSPACE, pointed at the opened repo via its `root`
+ * option. It is deliberately not `require`d out of the opened directory: the engine only reads
+ * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
+ * executed. An install that does not carry the engine gets an honest error, never a blank panel.
+ */
+function workflow({ root }) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
+  let engine;
+  try { engine = require(path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js')); }
+  catch {
+    return { ok: false, error: 'the workflow engine (scripts/workflow-state.js) is not present in this install — the ladder cannot be derived here' };
+  }
+  let ids;
+  try { ids = engine.listInitiatives(root); }
+  catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
+  if (!ids.length) return { ok: true, empty: true, source: 'file-mode' };
+
+  // One commit range for the whole board — resolving it per initiative would re-shell git for each.
+  const range = engine.commitRange(root);
+  const rows = ids.map((id) => {
+    try { return engine.computeWorkflow(id, { root, range }); }
+    catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
+  });
+  // Same `inFlight` the CLI and the gate use — the panel must not invent its own idea of what is
+  // open. Filtering by `legacy` here was a real bug: on main every record is legacy, so the panel
+  // read "0 in flight" against 93 initiatives, blank at exactly the moment someone opens it.
+  const { shown, hidden, total } = engine.inFlight(rows);
+  const shape = (r) => (r.ok ? {
+    id: r.id, title: r.title, lane: r.lane, stage: r.stage, legacy: r.legacy,
+    in_change: r.in_change, anchor: r.anchor,
+    record: r.record, blockers: r.blockers, next: r.next,
+    steps: r.steps.map((s) => ({ key: s.key, status: s.status, evidence: s.evidence, next: s.next, blocking: s.blocking, rule: s.rule })),
+  } : { id: r.id, error: r.error });
+  return {
+    ok: true, empty: false, source: 'file-mode',
+    data: {
+      live: shown.map(shape),
+      hidden,                       // reported on the client — a silent cap reads as "that is all"
+      total,
+      accepted: rows.filter((r) => r.ok && r.accepted).length,
+      unreadable: rows.filter((r) => !r.ok).map(shape),
+      blocked: shown.filter((r) => r.ok && r.blockers.length).length,
+      degraded: range.ok ? null : range.reason,
+      enforced_from: engine.ENFORCED_FROM,
+    },
+  };
+}
+
+module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl };

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/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 };
+});