projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/query.mjs

@@ -54,6 +54,11 @@ import {
 import { walkVaultFiles } from "./doctor.mjs";
 import { buildGraph } from "./graph.mjs";
 import { findStories, statusToColumn } from "./kanban.mjs";
+// status's text screen is drawn with the presentation primitives; term.mjs
+// has no side effect at import, so the MCP server's graph gains nothing it
+// could trip on (cli.mjs imports it already).
+import { PLAIN, painter, icon, heading, kv, rows, wrap, commandBlock } from "./term.mjs";
+import { invokedAs } from "./harness.mjs";
 
 export const SEARCH_DEFAULT_LIMIT = 20;
 export const SEARCH_HARD_CAP = 100;
@@ -202,19 +207,85 @@ export function status(cfg, { project = null } = {}) {
   return out;
 }
 
-export function renderStatus(r) {
-  if (!r.bound) return `Not bound${r.project ? ` — ${r.project}` : ""}. Run ${commandForm("bind", { args: "<vault>" })} in a session.\n`;
-  const lines = [`Vault: ${r.vault_path}${r.vault_exists ? "" : "  (missing)"}`, `Layout: ${r.layout} · language: ${r.language} · auto_inject: ${r.auto_inject} · approval_mode: ${r.approval_mode} · spec_policy: ${r.spec_policy} · lifecycle_gates: ${r.lifecycle_gates}`];
-  if (r.stories && r.stories.status !== "ok") lines.push(`Stories: not counted — ${r.stories.error}`);
-  else if (r.stories) {
-    lines.push(`Stories: ${r.stories.total} on the board — ${Object.entries(r.stories.by_status).map(([k, v]) => `${k} ${v}`).join(", ") || "none"}${r.stories.off_board_total ? `; ${r.stories.off_board_total} off it (${Object.entries(r.stories.off_board).map(([k, v]) => `${k} ${v}`).join(", ")})` : ""}`);
-    if (r.stories.in_progress_total) {
-      lines.push(`In progress (${r.stories.in_progress_total}):`);
-      for (const s of r.stories.in_progress) lines.push(`  ${s.epic}: ${s.title}  — ${s.path}${s.started_at ? `  (since ${s.started_at})` : ""}`);
-    } else lines.push("In progress: nothing");
+// Stands in for a space wrap() must not break at; given back after it.
+const GLUE = "";
+
+// A story's start as a date: a date stays as written; a timestamp is read in
+// the reader's own zone. Anything else prints as it is.
+export function startDate(at) {
+  const s = String(at);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return s;
+  const d = /^\d{4}-\d{2}-\d{2}T/.test(s) ? new Date(s) : null;
+  if (!d || Number.isNaN(d.getTime())) return s;
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+// status's screen (presentation spec contract 12), from status()'s result as
+// it is — the envelope is untouched. The binding as key–value lines; the
+// board's counts on one line; the stories in progress grouped by epic, each a
+// row of its start, its title and its path, the list ending with `+N more —
+// see <the kanban view's path>` when status() listed fewer than it counted;
+// then the views' freshness and the sessions. No badge: that is the install
+// family's and doctor's. `caps` is the stream's (term.mjs; plain by default):
+// prose wraps, a long title wraps under itself and a row's note moves on a
+// live terminal only, so a pipe gets one line per row. `env` names the
+// commands when nothing is bound: the session's form for the listening
+// harness, and the terminal's as this run was invoked (a shell's own name).
+export function renderStatus(r, { caps: c = PLAIN, env = process.env } = {}) {
+  const paint = painter(c);
+  const dash = icon(c, "dash"), dot = icon(c, "dot");
+  const prose = (text, indent = "") => indent + wrap(text, c.live ? c.width : 0, indent + "  ");
+  // A heading whose counts wrap only between them, after the dot: a count is
+  // never parted from its word. Each part's spaces are glued for wrap() and
+  // given back after it.
+  const counted = (title, parts) => {
+    const glued = parts.map((x) => (Array.isArray(x) ? [x[0].split(" ").join(GLUE), x[1]] : String(x).split(" ").join(GLUE)));
+    return prose(heading(c, title, glued).split(` ${dot} `).join(`${GLUE}${dot} `)).split(GLUE).join(" ");
+  };
+  if (!r.bound) {
+    return [
+      prose(`Not bound${r.project ? ` ${dash} ${r.project}` : ""}`),
+      "",
+      prose("Next: bind it to a vault, in a session or from a terminal:"),
+      ...commandBlock(c, [commandForm("bind", { args: "<vault>", env }), `${invokedAs(env).cmd} bind <vault>`]),
+    ].join("\n") + "\n";
+  }
+  const missing = r.vault_exists ? "" : `  ${paint("attention", `${icon(c, "warning")} missing`)}`;
+  const binding = [["vault_path", `${r.vault_path}${missing}`], ["layout", r.layout], ["language", r.language], ["auto_inject", r.auto_inject], ["approval_mode", r.approval_mode], ["spec_policy", r.spec_policy], ["lifecycle_gates", r.lifecycle_gates]];
+  const lines = [heading(c, "Binding"), ...kv(c, binding.filter(([, v]) => v !== null && v !== undefined))];
+  const s = r.stories;
+  if (s && s.status !== "ok") lines.push("", prose(heading(c, "Stories", [[`not counted ${dash} ${s.error}`, "attention"]])));
+  else if (s) {
+    const counts = [`${s.total} on the board`, ...Object.entries(s.by_status).map(([k, n]) => `${n} ${k}`)];
+    if (s.off_board_total) counts.push([`${s.off_board_total} off the board (${Object.entries(s.off_board).map(([k, n]) => `${k} ${n}`).join(", ")})`, "explanation"]);
+    lines.push("", counted("Stories", counts));
+    const listed = s.in_progress || [];
+    lines.push("", heading(c, "In progress", [s.in_progress_total ? String(s.in_progress_total) : ["nothing", "explanation"]]));
+    const byEpic = new Map();
+    for (const x of listed) {
+      const epic = x.epic || "";
+      if (!byEpic.has(epic)) byEpic.set(epic, []);
+      byEpic.get(epic).push(x);
+    }
+    for (const [epic, xs] of byEpic) {
+      if (epic) lines.push(`  ${paint("emphasis", epic)}`);
+      // A row per story (contract 5): the dot, the day it started, its title
+      // and its path. On a live terminal a title wider than the row wraps at
+      // its spaces, under itself, and a path that does not fit moves beneath
+      // it, at the same column. A story with no title is its path, never
+      // wrapped.
+      lines.push(...rows(c, xs.map((x) => ({ glyph: "dot", role: "explanation", action: x.started_at ? startDate(x.started_at) : "", target: x.title || x.path, prose: Boolean(x.title), note: x.title ? x.path : "" })), { indent: 4 }));
+    }
+    const more = (s.in_progress_total || 0) - listed.length;
+    const kanban = r.views && r.views.kanban ? r.views.kanban.path : null;
+    if (more > 0) lines.push(`  ${paint("explanation", `+${more} more${kanban ? ` ${dash} see ${kanban}` : ""}`)}`);
+  }
+  if (r.views) {
+    // A view that is stale or missing wants a reconcile: both in the attention role.
+    const state = (v) => (!v.exists ? ["missing", "attention"] : v.stale === null ? ["unknown", "explanation"] : v.stale ? ["stale", "attention"] : ["fresh", "done"]);
+    lines.push("", counted("Views", Object.values(r.views).map((v) => { const [word, role] = state(v); return `${v.path} ${paint(role, word)}`; })));
   }
-  if (r.views) lines.push(`Views: ${Object.entries(r.views).map(([k, v]) => `${k} ${!v.exists ? "missing" : v.stale === null ? "unknown" : v.stale ? "stale" : "fresh"}`).join(" · ")}`);
-  if (r.sessions) lines.push(`Sessions active: ${r.sessions.active}`);
+  if (r.sessions) lines.push(heading(c, "Sessions", [`${r.sessions.active} active`]));
   return lines.join("\n") + "\n";
 }
 

package/node_modules/projectstore/scripts/run-host.mjs

@@ -0,0 +1,94 @@
+// projectstore — run-host.mjs: one asynchronous runner for a host command.
+//
+// The install verbs ran every child through spawnSync, which blocks the event
+// loop: nothing can animate while it waits. The shell fetch of install and
+// upgrade (the story "Install and upgrade fetch a shell-rooted harness at the
+// bin's own version, once per run; plan and uninstall never fetch") is the
+// first child a person watches for seconds, so it gets a runner that yields:
+// a spawn with stdin ignored and both outputs piped, resolved with spawnSync's
+// own result shape so a caller written for one reads the other. APPLY's host
+// commands move onto it in a later story (the APPLY story adds `signal`).
+//
+//   runHost(bin, argv, { env, cwd, budget, spawn, shell })
+//     → Promise<{ status, signal, stdout, stderr, error }>
+//   startFailure(err, { bin, resolved, cwd }) → what Node could not say
+//   HOST_BUDGET_MS                            → the outer bound, 120 s
+//
+// Leaf module: node built-ins only. Only install-harness.mjs and
+// fetch-shell.mjs import it; hooks, doctor, surfaces and lib never do (the
+// portability suite asserts it), so the SessionStart graph never loads it.
+
+import { spawn as nodeSpawn } from "node:child_process";
+import { statSync } from "node:fs";
+
+// The bound every host command gets, ours, outside whatever the child sets
+// for itself (npm's per-request timeouts, retried, can outlast it).
+export const HOST_BUDGET_MS = 120000;
+
+// How long the pipes may drain after the child exits. A grandchild that keeps
+// a pipe open must not hold the run: `close` waited 3 s for one where `exit`
+// came at 99 ms (measured 2026-10-09).
+const DRAIN_MS = 200;
+
+// spawnSync's shape, asynchronously: `status` is the exit code, or null when
+// the child never started or was stopped; `error` carries the start failure
+// (never close's -2), or ETIMEDOUT when the budget ran out. Output is decoded
+// as UTF-8 by the streams themselves, so a character split across two writes
+// stays whole (measured). The budget's SIGTERM settles at once: a child that
+// ignores it, or a grandchild still writing, is left to the OS — its pipes are
+// destroyed and its handle unref'd, so nothing of it keeps this process open.
+// `shell` exists for win32, where npm is npm.cmd and runs only through a
+// shell; that path is unverified, as the install spec says of Windows.
+export function runHost(bin, argv, { env = process.env, cwd = process.cwd(), budget = HOST_BUDGET_MS, spawn = nodeSpawn, shell = false } = {}) {
+  return new Promise((settle) => {
+    const out = [], err = [];
+    let child = null, done = false, timer = null, drain = null, exited = null;
+    const release = () => {
+      for (const s of [child?.stdout, child?.stderr]) { try { s?.destroy(); } catch {} }
+      try { child?.unref?.(); } catch {}
+    };
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      clearTimeout(drain);
+      settle({ status: null, signal: null, stdout: out.join(""), stderr: err.join(""), error: undefined, ...r });
+    };
+    try { child = spawn(bin, argv, { env, cwd, stdio: ["ignore", "pipe", "pipe"], shell }); }
+    catch (e) { finish({ error: e }); return; }
+    for (const [s, sink] of [[child.stdout, out], [child.stderr, err]]) {
+      if (!s) continue;
+      s.setEncoding("utf8");
+      s.on("data", (d) => sink.push(d));
+      // A stream that ends after the exit may be the last one the drain waits on.
+      s.on("end", () => { if (exited && drained()) finish(exited); });
+      s.on("error", () => {});
+    }
+    const drained = () => [child.stdout, child.stderr].every((s) => !s || s.readableEnded || s.destroyed);
+    child.on("error", (e) => { finish({ error: e, status: null }); release(); });
+    child.on("exit", (code, signal) => {
+      exited = { status: code, signal };
+      if (drained()) { finish(exited); return; }
+      drain = setTimeout(() => { finish(exited); release(); }, DRAIN_MS);
+    });
+    timer = setTimeout(() => {
+      try { child.kill("SIGTERM"); } catch {}
+      finish({ status: null, signal: "SIGTERM", error: Object.assign(new Error(`${bin} ran past its ${budget} ms budget and was stopped`), { code: "ETIMEDOUT" }) });
+      release();
+    }, budget);
+  });
+}
+
+// What Node cannot say: spawnSync reports a working directory that does not
+// exist and a binary not on PATH with the same `spawnSync <bin> ENOENT`
+// (measured 2026-10-05), and spawn the same `spawn <bin> ENOENT`. The
+// filesystem tells them apart, in this order (the install spec, contract 19);
+// any other error passes through as Node wrote it.
+export function startFailure(err, { bin, resolved, cwd }) {
+  let dir = false;
+  try { dir = statSync(cwd).isDirectory(); } catch {}
+  if (!dir) return `${bin} could not start: the working directory ${JSON.stringify(String(cwd))} is not an existing directory`;
+  if (!resolved) return `${bin} could not start: it was not found on PATH`;
+  if (["ENOENT", "EACCES", "ENOEXEC"].includes(err?.code)) return `${bin} could not start: ${resolved} exists but could not be run (${err.code})`;
+  return String(err?.message || err);
+}

package/node_modules/projectstore/scripts/scaffold.mjs

@@ -0,0 +1,183 @@
+// projectstore — scaffold.mjs
+//
+// A vault's skeleton — the layout's folders, their README indexes and the
+// vault's own README — as a plan and an apply: the one place it is written,
+// for the CLI's `scaffold` verb, for `init` (binding.mjs) and, through the
+// bin, for the session command and the Codex skill. So a vault made in a
+// session, by `init` and by `setup` is the same bytes (the front-door ADR's
+// decision 7). Before this module a session wrote the READMEs itself, picking
+// each folder's name and description "based on the folder kind": two sessions
+// wrote two vaults, and the SessionStart skeleton's Purpose column, which
+// reads a folder's README prose, repeated whatever words the model chose.
+// The names and descriptions are data now: templates/<lang>/strings.json →
+// folders.<kind>, in the binding's language, with no English fallback.
+//
+// The shape is binding.mjs's. planScaffold() is pure over the filesystem: one
+// row per folder, per folder README and for the vault README, each `create`
+// or `exists`, and the reasons it refuses before anything is written.
+// applyScaffold() writes the `create` rows and nothing else. A file that
+// exists is never rewritten, whatever its content: the index rows inside a
+// README are reconcile's, and a README edited by hand is the person's. "The
+// layout's folders are missing" means the plan has a `create` row — a folder
+// that is there without its README counts, because reconcile drops an index
+// it cannot find without a word (the locale spec, contract 5).
+//
+// A leaf: lib.mjs and node built-ins only. binding.mjs imports this module,
+// so the reverse import would be a cycle. Normative: the story "Scaffold is a
+// core verb, and init creates a whole vault…" (PS-CORE).
+
+import { existsSync, statSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { pluginRoot, loadLayout, loadTemplate, loadStrings, renderTemplate, writeFileAtomic, commandForm } from "./lib.mjs";
+
+const README = "README.md";
+
+const kindsOf = (layout) => [...new Set((layout.folders || []).map((f) => f.kind))];
+const usable = (v) => typeof v === "string" && v.trim() !== "";
+const pathKind = (p) => { try { return statSync(p).isDirectory() ? "dir" : "file"; } catch { return null; } };
+
+// What a layout needs from a language before anything is written: the vault
+// README's template, the folder README's when a folder asks for one, and a
+// name and a description for every kind the layout's folders declare —
+// `diagram` included, though no command creates one. planScaffold refuses on
+// exactly this list and doctor's checkLayoutTemplates warns on it, so the two
+// cannot disagree about what a language lacks.
+export function missingScaffoldRequirements(layout, lang, root = pluginRoot()) {
+  const missing = [];
+  const templates = ["vault-readme", ...((layout.folders || []).some((f) => f.readme) ? ["folder-readme"] : [])];
+  for (const name of templates) {
+    if (!existsSync(join(root, "templates", String(lang), `${name}.md.tmpl`))) {
+      missing.push({ what: "template", name, message: `language "${lang}" has no ${name} template (templates/${lang}/${name}.md.tmpl)` });
+    }
+  }
+  const strings = loadStrings(lang, root);
+  for (const kind of kindsOf(layout)) {
+    const s = strings && strings.folders && strings.folders[kind];
+    if (!s || !usable(s.name) || !usable(s.description)) {
+      missing.push({ what: "string", name: kind, message: `language "${lang}" has no name and description for the folder kind "${kind}" (templates/${lang}/strings.json → folders.${kind})` });
+    }
+  }
+  return missing;
+}
+
+// The vault README's folder table: a row per layout folder, its name linked
+// to the folder's README (to the folder, when the layout asks for none) and
+// its description — the same strings the folder READMEs carry, so the two
+// never call one folder by two names.
+function folderRows(layout, strings) {
+  return layout.folders.map((f) => {
+    const s = strings.folders[f.kind];
+    return `| [${s.name}](${f.path}/${f.readme ? README : ""}) | ${s.description} |`;
+  }).join("\n");
+}
+
+// What `scaffold` would write into `vault`. A vault that does not exist yet
+// is planned as all `create` — what `init` plans before its mkdir. Refusal
+// codes: LAYOUT, TEMPLATE, STRINGS, NOT_A_DIRECTORY, FOLDER_IS_FILE; every
+// one is exit 1 upstream, and any one means nothing is written. A `create`
+// row carries the bytes it would write; an `exists` row carries none.
+export function planScaffold(vault, { layout, language, root = pluginRoot() } = {}) {
+  const refusals = [];
+  const rows = [];
+  const plan = { vault, layout, language, rows, creates: 0, refusals, ok: false };
+  let spec;
+  try {
+    spec = loadLayout(layout, root);
+    if (!spec || !Array.isArray(spec.folders)) throw new Error("it declares no folders");
+  } catch (e) {
+    refusals.push({ code: "LAYOUT", message: `the layout "${layout}" does not load: ${e.message}` });
+    return plan;
+  }
+  for (const m of missingScaffoldRequirements(spec, language, root)) refusals.push({ code: m.what === "template" ? "TEMPLATE" : "STRINGS", message: m.message });
+  if (pathKind(vault) === "file") refusals.push({ code: "NOT_A_DIRECTORY", message: `${vault} is a file, not a vault directory` });
+  if (refusals.length) return plan;
+  const strings = loadStrings(language, root);
+  const folderTemplate = spec.folders.some((f) => f.readme) ? loadTemplate(language, "folder-readme", root) : null;
+  const row = (type, rel, render = null) => {
+    const abs = join(vault, rel);
+    const action = existsSync(abs) ? "exists" : "create";
+    rows.push({ type, rel, abs, action, ...(render && action === "create" ? { content: render() } : {}) });
+  };
+  for (const f of spec.folders) {
+    if (pathKind(join(vault, f.path)) === "file") refusals.push({ code: "FOLDER_IS_FILE", message: `${f.path} exists in ${vault} as a file — the layout's ${f.kind} folder cannot be created there` });
+    row("folder", f.path);
+    if (f.readme) {
+      const s = strings.folders[f.kind];
+      row("readme", `${f.path}/${README}`, () => renderTemplate(folderTemplate, { folder_name: s.name, folder_description: s.description }));
+    }
+  }
+  // Last, and from the basename alone: nothing path-dependent beyond the
+  // directory's name, so a vault made here and one made by `init` elsewhere
+  // under the same name are byte-identical.
+  row("vault-readme", README, () => renderTemplate(loadTemplate(language, "vault-readme", root), { vault_name: basename(vault), folder_rows: folderRows(spec, strings) }));
+  plan.creates = rows.filter((r) => r.action === "create").length;
+  plan.ok = refusals.length === 0;
+  return plan;
+}
+
+// Writes the plan's `create` rows and nothing else: every folder first —
+// writeFileAtomic never mkdirs — then each README, its absence checked again
+// at the moment of writing, so a file that appeared after the plan (another
+// session, a hand) is reported as there and never rewritten. The vault root is
+// the caller's to make: `init` makes it, and a binding whose vault vanished is
+// refused upstream, never recreated here behind the person's back.
+export function applyScaffold(plan) {
+  if (!plan.ok) throw Object.assign(new Error(plan.refusals.map((r) => r.message).join("; ")), { code: plan.refusals[0] ? plan.refusals[0].code : "REFUSED" });
+  if (pathKind(plan.vault) !== "dir") throw Object.assign(new Error(`${plan.vault} does not exist — scaffold never creates the vault itself`), { code: "MISSING" });
+  const made = new Set();
+  for (const r of plan.rows) {
+    if (r.type !== "folder" || r.action !== "create" || existsSync(r.abs)) continue;
+    mkdirSync(r.abs, { recursive: true });
+    made.add(r.rel);
+  }
+  for (const r of plan.rows) {
+    if (r.type === "folder" || r.action !== "create" || existsSync(r.abs)) continue;
+    writeFileAtomic(r.abs, r.content);
+    made.add(r.rel);
+  }
+  return {
+    created: plan.rows.filter((r) => made.has(r.rel)).map((r) => r.rel),
+    exists: plan.rows.filter((r) => !made.has(r.rel)).map((r) => r.rel),
+  };
+}
+
+// The result a front-end reports: the rows and what became of them, never a
+// file body. `path` is vault-relative.
+export function scaffoldResult(plan, done = null) {
+  return {
+    vault_path: plan.vault, layout: plan.layout, language: plan.language,
+    rows: plan.rows.map((r) => ({ type: r.type, path: r.rel, action: r.action })),
+    creates: plan.creates, wrote: Boolean(done),
+    created: done ? done.created : [],
+    exists: done ? done.exists : plan.rows.filter((r) => r.action === "exists").map((r) => r.rel),
+    refusals: plan.refusals,
+  };
+}
+
+const shown = (r) => (r.type === "folder" ? `${r.rel}/` : r.rel);
+
+// The plan as text. A bare plan ends with the command that writes it, in both
+// forms — the session's and the bin's, since a git-marketplace install has no
+// bin on PATH — and with `--write`, because at a terminal that form shows this
+// plan again and asks. `asking`: the question follows on the same stream, so
+// the closing line is left out. After an apply, what was created and what was
+// already there.
+export function renderScaffoldPlan(plan, done = null, { env = process.env, asking = false } = {}) {
+  if (!plan.ok) return [...plan.refusals.map((r) => r.message), "Nothing written."].join("\n") + "\n";
+  const where = `${plan.vault} (layout ${plan.layout}, language ${plan.language})`;
+  if (done) {
+    const lines = [`Scaffolded ${where}`, ...plan.rows.filter((r) => done.created.includes(r.rel)).map((r) => `  created  ${shown(r)}`)];
+    lines.push(done.exists.length
+      ? `Created ${done.created.length}; ${done.exists.length} already there, left as ${done.exists.length === 1 ? "it was" : "they were"}.`
+      : `Created ${done.created.length}.`);
+    return lines.join("\n") + "\n";
+  }
+  const lines = [`Scaffold ${where}`, ...plan.rows.map((r) => `  ${r.action}  ${shown(r)}`), ""];
+  const there = plan.rows.length - plan.creates;
+  if (!plan.creates) lines.push("Nothing to create: every folder and README the layout declares is there.");
+  else {
+    lines.push(`${plan.creates} to create${there ? `; ${there} already there, never rewritten` : ""}.`);
+    if (!asking) lines.push(`To write them: ${commandForm("scaffold", { env })} in a session, or \`projectstore scaffold --write\`.`);
+  }
+  return lines.join("\n") + "\n";
+}

package/node_modules/projectstore/scripts/stages.mjs

@@ -0,0 +1,80 @@
+// projectstore — stages.mjs: how a story's status reads on the board.
+//
+// One table for two readers: the kanban board (scripts/kanban.mjs) and the
+// band above the prompt (hooks/band.tsx), which counts an epic's stories by
+// the same rule so the band and kanban.md never disagree. The band is a Claude
+// Code hooks module and runs with no Node, so this file imports nothing at
+// all — keep it that way.
+
+// Statuses that describe work which is not on the board by definition: it was
+// replaced, postponed, or set aside. Putting them in a column would claim the
+// work is queued, which is the opposite of what the status says.
+export const NOT_ACTIONABLE = new Set(["superseded", "deferred", "parked"]);
+
+// A lower-cased status to its board column. Exact match; anything the table
+// does not name is Backlog.
+export function statusToColumn(status) {
+  const m = {
+    planned: "Backlog",
+    todo: "ToDo",
+    "to-do": "ToDo",
+    "in-progress": "In Progress",
+    in_progress: "In Progress",
+    "in progress": "In Progress",
+    review: "Review",
+    done: "Done",
+    closed: "Done",
+  };
+  return m[status] || "Backlog";
+}
+
+// The band's three stages, folded from the board's columns.
+export const COLUMN_STAGE = Object.freeze({
+  Done: "done",
+  "In Progress": "active",
+  Review: "active",
+  ToDo: "backlog",
+  Backlog: "backlog",
+});
+
+// A story's stage from its raw frontmatter status, as the board reads it:
+// lower-cased; no status, or a status the board leaves off, counts nowhere
+// (null).
+export function stageOf(raw) {
+  if (raw === null || raw === undefined || raw === "") return null;
+  const status = String(raw).toLowerCase();
+  if (NOT_ACTIONABLE.has(status)) return null;
+  return COLUMN_STAGE[statusToColumn(status)] || "backlog";
+}
+
+// Raw statuses → { done, active, backlog }.
+export function foldStages(statuses) {
+  const out = { done: 0, active: 0, backlog: 0 };
+  for (const raw of statuses) {
+    const stage = stageOf(raw);
+    if (stage) out[stage]++;
+  }
+  return out;
+}
+
+// Line-based frontmatter: `key: value` scalars between the opening `---` and
+// the next one. Quoted values are JSON-decoded (titles that hold quotes),
+// `null` is null; block sequences are invisible to it.
+export function parseFrontmatter(md) {
+  const m = md.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return { data: {}, body: md };
+  const data = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^(\w+):\s*(.*)$/);
+    if (!kv) continue;
+    let v = kv[2].trim();
+    if (v === "null") v = null;
+    else if (v.startsWith('"') && v.endsWith('"')) {
+      // JSON.parse round-trips escaped scalars from renderTemplate's _json
+      // form (titles containing quotes); fall back to the bare strip.
+      try { v = JSON.parse(v); } catch { v = v.slice(1, -1); }
+    }
+    data[kv[1]] = v;
+  }
+  return { data, body: md.slice(m[0].length) };
+}

package/node_modules/projectstore/scripts/statusline.mjs

@@ -25,6 +25,13 @@
 //      cold-start line. The renderer drops a .last-render.json breadcrumb so
 //      doctor can detect session_id divergence between hook and statusLine.
 //
+// While this session's band above the prompt is drawing (hooks/band.tsx keeps
+// a heartbeat fresh in the session-state directory), our line gives way to it:
+// composed, the base HUD prints alone; standalone, the badge and the 📚
+// segment drop. A missing, unreadable or stale heartbeat changes nothing, so
+// a band that cannot draw always gives the line back (the band ADR, decision
+// 5; spec contract 11).
+//
 // Everything is best-effort; on any error emit what we have and exit 0.
 
 import { readFileSync, existsSync } from "node:fs";
@@ -41,6 +48,7 @@ import {
   claudeHome,
   writeFileAtomic,
 } from "./lib.mjs";
+import { heartbeatFile, heartbeatYields } from "./band-shared.mjs";
 
 const SELF = fileURLToPath(import.meta.url);
 const SEP = " · ";
@@ -153,6 +161,19 @@ function bookSegment(cfg, proj, input, strings) {
   return seg;
 }
 
+// Whether this session's band is drawing now. Read after bookSegment has
+// written the breadcrumb, so doctor keeps its evidence while the band is up;
+// any failure reads as "no band" and the line stays.
+function bandYields(proj, sid) {
+  try {
+    const name = heartbeatFile(sid);
+    if (!name) return false;
+    return heartbeatYields(JSON.parse(readFileSync(join(stateDir(proj), name), "utf8")), Date.now());
+  } catch {
+    return false;
+  }
+}
+
 // The base statusLine command we compose with — highest-precedence entry BELOW
 // our own local one: project settings.json, else user settings.json.
 function discoverBaseCommand(projectDir) {
@@ -210,8 +231,10 @@ function main() {
   let book = null;
   try { book = cfg && cfg.vault_path ? bookSegment(cfg, projectDir, input, strings) : null; } catch { book = null; }
 
+  const yielded = Boolean(cfg && cfg.vault_path && bandYields(projectDir, input.session_id));
+
   const showVersion = !(cfg && cfg.statusline && cfg.statusline.show_version === false);
-  const ver = showVersion ? pluginVersion() : null;
+  const ver = showVersion && !yielded ? pluginVersion() : null;
   const badge = ver ? `[PS#${ver}] ` : "";
 
   const baseCmd = discoverBaseCommand(projectDir);
@@ -220,7 +243,7 @@ function main() {
   // "Never blank" must be total: even if the resolver threw (book === null on a
   // bound project), fall back to the cold-start line rather than vanishing.
   const bookOut =
-    cfg && cfg.vault_path ? book || BOOK + strings.statusline_no_work : null;
+    cfg && cfg.vault_path && !yielded ? book || BOOK + strings.statusline_no_work : null;
 
   const lines = [];
   if (baseOut) {