create-pmos 0.7.3 → 0.9.0

package/README.md

@@ -333,6 +333,74 @@ 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.**
+
+Minor, not patch: a feature that shipped in 0.7.0–0.7.3 has been **removed**, and what replaces it is
+a different thing with a different point. If you were using the review surface, it is not there any
+more — read on.
+
+### Why it went
+
+It answered a question nobody asked. An agent read your planning documents and told you what it
+thought was wrong with them, before you had touched anything. What was actually wanted was the
+opposite direction: **you** edit a document, and the tooling reacts to *your* change.
+
+**It also never fully worked.** The browser's Edit → Apply path depended on a script the server was
+never configured to serve, so it 404'd silently in every version that shipped it. The tests that
+covered it went straight to the endpoint and never exercised the path a person takes. If you tried to
+edit a proposal and apply it and nothing happened, that was why, and it was our bug.
+
+### What replaces it
+
+- **Edit any markdown document in the reader.** `edit` in the document header; `save`, `cancel` and
+  `history` while you are in it. ⌘S saves.
+- **The diff is beside you as you type** — the replaced lines struck through, the new ones marked,
+  with a running `+n −n` and the line the change starts at. Nothing to summon; it appears when the
+  document differs from what you opened.
+- **A save that refuses rather than clobbers.** If the file changed on disk since you opened it, the
+  save fails and says so, and **your text stays in the editor** so you can copy it out. It will not
+  merge over whoever changed it.
+- **Every save is logged, per repository.** What changed, where, and — if you write one — why. It
+  lands in your repo's own state directory, never in the installed app. `history` in the document
+  header shows that document's own log.
+
+The log records the changed region and your reason, **not a parallel history of your repository**.
+`git log` remains the record of what your files contain; this records what you changed and why, which
+git has no place to put.
+
+### Not built yet, and named so you are not waiting for it
+
+Two halves of the intended feature are **not** in this release: using a save to work out which *other*
+documents are now out of step and drafting the edits that would realign them, and feeding the
+accumulated change log to agents as context. The editor, the diff and the log are here; the
+propagation is not.
+
 ## What's new in 0.7.3
 
 **A fix — read this if you ran a document review on 0.7.1 or 0.7.2, and especially if you have more

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.7.3",
+  "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@56ab797
+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/apply-change.js

@@ -102,5 +102,55 @@
     return { ok: true, text: r.text, eol: r.eol };
   }
 
-  return { applyChange, changeStat, matchesRendered, detectEol };
+  /**
+   * Save a whole edited document (workspace-doc-editor R3).
+   *   current — the file on disk right now
+   *   base    — the text the editor loaded, i.e. what the PM's edit was made against
+   *   next    — what they wrote
+   * Refuses when `current` no longer matches `base`: the document moved under the PM, and writing
+   * `next` would silently discard whoever changed it. Same stance as applyChange's stale check —
+   * refuse loudly rather than merge — but for the case where the whole document is the unit.
+   */
+  function saveWhole(current, base, next) {
+    if (typeof current !== 'string' || typeof base !== 'string' || typeof next !== 'string') {
+      return { ok: false, reason: 'not-text' };
+    }
+    if (toLf(current) !== toLf(base)) {
+      return { ok: false, reason: 'stale', detail: 'this document changed on disk since you opened it' };
+    }
+    if (toLf(current) === toLf(next)) return { ok: false, reason: 'no-change' };
+    const eol = detectEol(current);
+    const out = toLf(next);
+    return { ok: true, text: eol === '\n' ? out : out.replace(/\n/g, eol), eol };
+  }
+
+  /**
+   * The changed REGION of an edit, for the change log (R4/R8).
+   *
+   * Common leading and trailing lines are trimmed away, leaving the part that actually differs. That
+   * is deliberately not a stored diff history — git holds the repository's content, and R4 says so.
+   * What this exists for is R8: an agent reading the log should see *what the PM tends to change and
+   * how*, which line counts alone cannot convey and whole documents would bury.
+   */
+  function changedRegion(base, next, maxLines = 40) {
+    const a = toLf(base == null ? '' : base).split('\n');
+    const b = toLf(next == null ? '' : next).split('\n');
+    let s = 0;
+    while (s < a.length && s < b.length && a[s] === b[s]) s++;
+    let e = 0;
+    while (e < a.length - s && e < b.length - s && a[a.length - 1 - e] === b[b.length - 1 - e]) e++;
+    const before = a.slice(s, a.length - e);
+    const after = b.slice(s, b.length - e);
+    const clip = (arr) => (arr.length > maxLines
+      ? arr.slice(0, maxLines).concat([`… ${arr.length - maxLines} more line(s)`]) : arr);
+    return {
+      at_line: s + 1,
+      removed: before.length,
+      added: after.length,
+      before: clip(before).join('\n'),
+      after: clip(after).join('\n'),
+    };
+  }
+
+  return { applyChange, changeStat, matchesRendered, detectEol, saveWhole, changedRegion };
 });

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 };