projectstore-claude 0.29.3 → 0.29.4

package/node_modules/projectstore/hooks/session-start.mjs

@@ -13,7 +13,7 @@
 //    open. Bounded and O(1) in vault size by construction.
 
 import { existsSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { dirname } from "node:path";
 import {
   readConfig,
   gatherVaultFacts,
@@ -30,6 +30,7 @@ import {
   ensureStateRoot,
   syncStatusLine,
   cleanupStaleSessionState,
+  refreshStoryPointer,
   armReminder,
   truncEnd,
   truncFront,
@@ -64,9 +65,10 @@ function welcomedMarkerWritePath(proj) {
 // the one instruction it carries branches on the binding; everything else is
 // the same message.
 function buildWelcome(cfg = null) {
-  const start = cfg && cfg.vault_path
-    ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation, and you approve every write. If the vault has no folders yet, \`${commandForm("scaffold")}\` lays them out.`
-    : `**To start using it**: run \`${commandForm("bind", { args: "<vault-path>" })}\` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation; you only approve the writes.`;
+  const start =
+    cfg && cfg.vault_path
+      ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation, and you approve every write. If the vault has no folders yet, \`${commandForm("scaffold")}\` lays them out.`
+      : `**To start using it**: run \`${commandForm("bind", { args: "<vault-path>" })}\` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation; you only approve the writes.`;
   return [
     "# 👋 projectstore is loaded for the first time in this project",
     "",
@@ -178,15 +180,25 @@ async function main() {
   // an unbound one that is not a worktree pays a single ~10 ms probe.
   let binding = null;
   if (!cfg) {
-    try { binding = resolveBinding(proj); } catch {}
+    try {
+      binding = resolveBinding(proj);
+    } catch {}
   }
   const welcome = showWelcomeOnce(proj, cfg);
   // The person's channel carries one instruction, and it has to be the right
-  // one: a bound project is told what it is bound to, not to bind again.
+  // one: a bound project is told what it is bound to, not to bind again. A
+  // command stands alone on its line, the update hint on lines of its own
+  // after it (the story "User-facing text says where to run…", rules 4 and 5).
   const welcomeSystemMessage = welcome
-    ? (cfg && cfg.vault_path
+    ? cfg && cfg.vault_path
       ? `👋 projectstore: first-run welcome shown. Bound to ${cfg.vault_path}. ${updateHint().line}`
-      : `👋 projectstore: first-run welcome shown. Start with ${commandForm("bind", { args: "<vault-path>" })}. ${updateHint().line}`)
+      : [
+          "👋 projectstore: first-run welcome shown. Start with:",
+          commandForm("bind", { args: "<vault-path>" }),
+          updateHint().line,
+        ]
+          .filter(Boolean)
+          .join("\n")
     : null;
 
   if (!cfg) {
@@ -196,8 +208,10 @@ async function main() {
     // whose parent is already bound. Ordering is the cheap fix; the small
     // redundancy is accepted rather than papered over with copy that will rot.
     const offer = binding && binding.state === "inheritable" ? bindingOfferText(binding) : "";
+    // What binding does first, then the command alone on its line: an
+    // in-session form that can carry the parent's vault path (rule 4).
     const offerSystemMessage = offer
-      ? `projectstore: this worktree is unbound — ${inheritForm(binding.vaultPath, { layout: binding.layout, language: binding.language })} ${bindInherits() ? "adopts the binding of" : "binds it to the vault, layout and language of"} the checkout it was forked from.`
+      ? `projectstore: this worktree is unbound. ${bindInherits() ? "Adopt the binding of" : "Bind it to the vault, layout and language of"} the checkout it was forked from, in the session:\n${inheritForm(binding.vaultPath, { layout: binding.layout, language: binding.language })}`
       : null;
     const body = offer + (welcome || "");
     if (body) {
@@ -213,10 +227,23 @@ async function main() {
   // Opt-in status line: keep settings.local.json pointed at this plugin
   // version's statusline.mjs (self-heals on update). Best-effort; a settings
   // write must never break session-context injection.
-  try { syncStatusLine(cfg, proj); } catch {}
+  try {
+    syncStatusLine(cfg, proj);
+  } catch {}
   // Statusline-feature housekeeping, like syncStatusLine — must run even when
   // auto_inject=false (touch-session writes pointers regardless of it).
-  try { cleanupStaleSessionState(proj); } catch {}
+  try {
+    cleanupStaleSessionState(proj);
+  } catch {}
+  // This session's story fields from the story file, once (ADR-006, amended
+  // 2026-10-12): a pointer written before a close, or a story closed elsewhere
+  // since, stops naming finished work. A bounded read; a lost race writes
+  // nothing.
+  if (sid) {
+    try {
+      await refreshStoryPointer(proj, cfg.vault_path, sid);
+    } catch {}
+  }
 
   // Arm BEFORE the auto_inject gate. The entry reminder's markers must be
   // re-armed after a compaction whether or not this session injects context —
@@ -231,7 +258,9 @@ async function main() {
   // context while its marker persists on disk. Arming lets it fire once more;
   // the cap of two is enforced by the election, not here.
   if (sid && (input?.source === "compact" || input?.source === "clear")) {
-    try { armReminder(proj, sid); } catch {}
+    try {
+      armReminder(proj, sid);
+    } catch {}
   }
 
   if (cfg.auto_inject === false) {
@@ -272,23 +301,26 @@ async function main() {
     }
   }
 
-  // Cheap install-only doctor subset (ADR-005): one line, only when N > 0;
-  // aborted past its budget rather than reporting a false "clean".
+  // Cheap install-only doctor subset (ADR-005): one part, only when N > 0;
+  // aborted past its budget rather than reporting a false "clean". Its doctor
+  // form stands alone on its line, as every command of this line does.
   let doctorMsg = null;
   let offers = [];
   try {
     const r = runStartupChecks(cfg, proj);
     if (r.skipped) {
-      doctorMsg = `projectstore doctor: startup checks skipped — run ${commandForm("doctor")}`;
+      doctorMsg = `projectstore doctor: startup checks skipped. Run them in the session:\n${commandForm("doctor")}`;
     } else if (r.count > 0) {
-      doctorMsg = `projectstore doctor: ${r.count} install issue(s) — run ${commandForm("doctor")}`;
+      doctorMsg = `projectstore doctor: ${r.count} install issue(s). See them in the session:\n${commandForm("doctor")}`;
     }
     // Offers (doctor's OFFER_CHECKS): one-time steps a user should see once,
     // e.g. the re-stamp after a plugin update — not issues, not silent.
     offers = (r.offers || []).map((m) => `projectstore: ${m}`);
   } catch {}
-  const systemMessage =
-    [welcomeSystemMessage, doctorMsg, ...offers].filter(Boolean).join(" · ") || null;
+  // Each part on lines of its own: an offer ends with its command alone on
+  // its line, and a part joined after it with ` · ` would put text after the
+  // command (the story "User-facing text says where to run…", rule 4).
+  const systemMessage = [welcomeSystemMessage, doctorMsg, ...offers].filter(Boolean).join("\n") || null;
 
   if (gatherError) {
     emit(

package/node_modules/projectstore/hooks/session-stop.mjs

@@ -71,12 +71,14 @@ async function main() {
 
   if (!electEmitter(proj, sid)) return;
   appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score, via: "Stop" });
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "Stop",
-      additionalContext: entryReminderText(score),
-    },
-  }) + "\n");
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext: entryReminderText(score),
+      },
+    }) + "\n",
+  );
 }
 
 main().catch(() => {

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.29.3",
+  "version": "0.29.4",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",
@@ -66,6 +66,15 @@
     "shells": "node packaging/shells.mjs --write",
     "shells:check": "node packaging/shells.mjs --check",
     "shells:build": "node packaging/shells.mjs --build --out dist",
-    "release:check": "npm run adapters:check && npm run guard && npm run shells:check && npm test && npm pack --dry-run"
+    "release:check": "npm run adapters:check && npm run guard && npm run shells:check && npm run lint && npm run format:check && npm test && npm pack --dry-run",
+    "lint": "eslint --max-warnings 0 bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs",
+    "format": "prettier --write bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs",
+    "format:check": "prettier --check bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "eslint": "10.12.0",
+    "eslint-plugin-n": "18.4.1",
+    "prettier": "3.9.10"
   }
 }

package/node_modules/projectstore/scripts/band-shared.mjs

@@ -11,6 +11,8 @@
 // Spec: the band above the prompt — rows, heartbeat, command and the status
 // line's yield (the contract numbers below are that spec's).
 
+import { stageOf } from "./stages.mjs";
+
 // ─── The heartbeat (contracts 10, 11) ──────────────────────────────────
 // While a session's band draws, the module keeps a small file fresh in the
 // session-state directory; the status line yields its own line only while
@@ -25,7 +27,7 @@ export const HEARTBEAT_WINDOW_MS = 30_000;
 // as one. Null for an id that cannot name a file.
 export function heartbeatFile(sessionId) {
   if (typeof sessionId !== "string" || !sessionId) return null;
-  if (/[\/\\\0]/.test(sessionId) || sessionId === "." || sessionId === "..") return null;
+  if (/[/\\\0]/.test(sessionId) || sessionId === "." || sessionId === "..") return null;
   return `.band-${sessionId}.json`;
 }
 
@@ -63,13 +65,34 @@ export function heartbeatNext(lastRender, wasDrawing, now) {
 // templates/<lang>/strings.json, the English file the fallback per key.
 
 export const BAND_STRING_KEYS = Object.freeze([
-  "band_this_session", "band_pinned", "band_goal", "band_story", "band_agent",
-  "band_done", "band_in_work", "band_backlog", "band_stories", "band_no_stories",
-  "band_more", "band_hint", "band_ended_done", "band_ended_stopped",
-  "band_verb_critic", "band_verb_reviewer", "band_verb_planner", "band_verb_clerk",
-  "band_verb_librarian", "band_verb_archaeologist", "band_verb_other",
-  "band_step_reads", "band_step_writes", "band_step_edits", "band_step_searches",
-  "band_step_runs", "band_step_web", "band_step_vault",
+  "band_this_session",
+  "band_pinned",
+  "band_goal",
+  "band_story",
+  "band_agent",
+  "band_done",
+  "band_in_work",
+  "band_backlog",
+  "band_stories",
+  "band_no_stories",
+  "band_more",
+  "band_hint",
+  "band_ended_done",
+  "band_ended_stopped",
+  "band_verb_critic",
+  "band_verb_reviewer",
+  "band_verb_planner",
+  "band_verb_clerk",
+  "band_verb_librarian",
+  "band_verb_archaeologist",
+  "band_verb_other",
+  "band_step_reads",
+  "band_step_writes",
+  "band_step_edits",
+  "band_step_searches",
+  "band_step_runs",
+  "band_step_web",
+  "band_step_vault",
 ]);
 
 // The band's words for a language: the English file's, each overlaid by the
@@ -140,20 +163,54 @@ const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 export async function storyFiles(fs, epicDir) {
   const out = [];
   const stories = `${epicDir}/stories`;
-  let entries = [];
-  try { entries = await fs.list(stories); } catch { entries = []; }
+  let entries;
+  try {
+    entries = await fs.list(stories);
+  } catch {
+    entries = [];
+  }
   for (const e of [...entries].sort(byName)) {
     if (e.kind === "file" && e.name.endsWith(".md")) out.push(`${stories}/${e.name}`);
-    else if (e.kind === "dir" && (await fs.exists(`${stories}/${e.name}/README.md`))) out.push(`${stories}/${e.name}/README.md`);
+    else if (e.kind === "dir" && (await fs.exists(`${stories}/${e.name}/README.md`)))
+      out.push(`${stories}/${e.name}/README.md`);
+  }
+  let beside;
+  try {
+    beside = await fs.list(epicDir);
+  } catch {
+    beside = [];
   }
-  let beside = [];
-  try { beside = await fs.list(epicDir); } catch { beside = []; }
   for (const e of [...beside].sort(byName)) {
     if (e.kind === "file" && e.name.startsWith("story-") && e.name.endsWith(".md")) out.push(`${epicDir}/${e.name}`);
   }
   return out;
 }
 
+// ─── This session's story (contract 8) ─────────────────────────────────
+// The session pointer names its story by a key; the band finds that key among
+// the epic's story files. One function for both, so a folder story and a
+// story beside epic.md are named the way they are found.
+
+// The key of a story file from its path below the epic folder:
+// `stories/<x>.md` and `stories/<x>/README.md` are `<x>`, `story-<x>.md`
+// beside epic.md is `story-<x>`; anything else is not a story (null).
+export function storyKeyOf(relToEpic) {
+  const rel = String(relToEpic || "");
+  let m = rel.match(/^stories\/([^/]+)\.md$/);
+  if (m) return m[1];
+  m = rel.match(/^stories\/([^/]+)\/README\.md$/);
+  if (m) return m[1];
+  m = rel.match(/^(story-[^/]+)\.md$/);
+  return m ? m[1] : null;
+}
+
+// Whether a story with this status is work the session is moving: in work or
+// backlog. Done, closed, parked, superseded, deferred or no status — not.
+export function storyIsCurrent(status) {
+  const stage = stageOf(status);
+  return stage === "active" || stage === "backlog";
+}
+
 // An epic id the band may put in a path: one segment the board would list
 // (not hidden, not a `_templates`-style folder).
 export function isEpicName(id) {
@@ -165,12 +222,26 @@ export function isEpicName(id) {
 // marks and variation selectors none.
 
 const WIDE = [
-  [0x1100, 0x115f], [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf],
-  [0x4e00, 0x9fff], [0xa000, 0xa4cf], [0xac00, 0xd7a3], [0xf900, 0xfaff],
-  [0xfe30, 0xfe4f], [0xff00, 0xff60], [0xffe0, 0xffe6], [0x1f300, 0x1f64f],
-  [0x1f900, 0x1f9ff], [0x20000, 0x3fffd],
+  [0x1100, 0x115f],
+  [0x2e80, 0x303e],
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe30, 0xfe4f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f300, 0x1f64f],
+  [0x1f900, 0x1f9ff],
+  [0x20000, 0x3fffd],
+];
+const ZERO = [
+  [0x0300, 0x036f],
+  [0x200b, 0x200f],
+  [0xfe00, 0xfe0f],
 ];
-const ZERO = [[0x0300, 0x036f], [0x200b, 0x200f], [0xfe00, 0xfe0f]];
 const within = (cp, ranges) => ranges.some(([a, b]) => cp >= a && cp <= b);
 
 export function cellWidth(text) {
@@ -228,6 +299,38 @@ export function progressLayout(counts, hint, bodyColumns) {
   return { bar: room >= BAR_MIN ? Math.min(BAR_MAX, room) : 0, hint: false };
 }
 
+// The first characters of `text` that fit `cells`, with `…` when it was cut.
+export function cutCells(text, cells) {
+  const s = String(text);
+  if (cellWidth(s) <= cells) return s;
+  let out = "";
+  let w = 0;
+  for (const ch of s) {
+    const cw = cellWidth(ch);
+    if (w + cw > cells - 1) break;
+    out += ch;
+    w += cw;
+  }
+  return `${out}…`;
+}
+
+// ` · <status>`, `_` and `-` shown as spaces; "" with no status.
+export function storyTail(status) {
+  return status ? ` · ${String(status).replace(/[_-]/g, " ")}` : "";
+}
+
+// The story row: `   <label> <title> · <status>`, at most bodyColumns − 3
+// cells — the room the progress row's formula leaves (the box's padding, then
+// the strict fit). The status is never cut: when the row is longer, the title
+// is cut with `…` (to `…` alone at worst).
+export function storyLayout(label, title, status, bodyColumns) {
+  const tail = storyTail(status);
+  // No width from the host: draw the title whole and let the host truncate.
+  if (!Number.isFinite(bodyColumns)) return { title: String(title), tail };
+  const room = bodyColumns - 2 - 3 - cellWidth(`${label} `) - cellWidth(tail) - 1;
+  return { title: cutCells(title, Math.max(1, room)), tail };
+}
+
 // ─── The agent row (contract 12) ───────────────────────────────────────
 
 export const AGENT_PREFIX = "projectstore:";
@@ -249,7 +352,8 @@ export function subjectPath(prompt, vault, kindFolders) {
   const text = String(prompt || "");
   const found = [];
   if (vault) {
-    for (const m of text.matchAll(new RegExp(`${escRe(vault)}/([^\\s\`'")\\]]+?\\.md)`, "g"))) found.push({ at: m.index, rel: m[1] });
+    for (const m of text.matchAll(new RegExp(`${escRe(vault)}/([^\\s\`'")\\]]+?\\.md)`, "g")))
+      found.push({ at: m.index, rel: m[1] });
   }
   const kinds = (kindFolders || []).filter(Boolean).map(escRe);
   if (kinds.length) {
@@ -283,9 +387,14 @@ const vaultRel = (vault, p) => (vault && p.startsWith(`${vault}/`) ? p.slice(vau
 
 // `node /x/reconcile.mjs --a` reads `reconcile`, `git diff --stat` reads `git diff`.
 export function commandWord(command) {
-  const words = String(command).replace(/^(\s*cd\s+("[^"]*"|'[^']*'|\S+)\s*&&\s*)+/, "").trim().split(/\s+/).filter((x) => !/^\w+=/.test(x));
+  const words = String(command)
+    .replace(/^(\s*cd\s+("[^"]*"|'[^']*'|\S+)\s*&&\s*)+/, "")
+    .trim()
+    .split(/\s+/)
+    .filter((x) => !/^\w+=/.test(x));
   const [cmd = "", arg = ""] = words.map((x) => x.replace(/^["']|["']$/g, ""));
-  if (/^(node|python3?|bash|sh|npx|bun|deno|tsx)$/.test(lastSegment(cmd)) && arg && !arg.startsWith("-")) return lastSegment(arg).replace(/\.(m?js|cjs|py|sh|ts)$/, "");
+  if (/^(node|python3?|bash|sh|npx|bun|deno|tsx)$/.test(lastSegment(cmd)) && arg && !arg.startsWith("-"))
+    return lastSegment(arg).replace(/\.(m?js|cjs|py|sh|ts)$/, "");
   return /^[a-z][\w:-]*$/.test(arg) ? `${lastSegment(cmd)} ${arg}` : lastSegment(cmd);
 }
 
@@ -295,10 +404,16 @@ const QUIET = /^(echo|printf|true|sleep|:)(\s|$)/;
 // nothing worth a row (an echo, a tool the band does not name).
 export function stepOf(call, vault, w) {
   const tool = typeof call.tool === "string" ? call.tool : "";
-  const path = typeof call.file_path === "string" ? call.file_path : typeof call.notebook_path === "string" ? call.notebook_path : null;
+  const path =
+    typeof call.file_path === "string"
+      ? call.file_path
+      : typeof call.notebook_path === "string"
+        ? call.notebook_path
+        : null;
   if (tool === "Read" && path) return `${w.band_step_reads} ${vaultRel(vault, path)}`;
   if (tool === "Write" && path) return `${w.band_step_writes} ${vaultRel(vault, path)}`;
-  if ((tool === "Edit" || tool === "MultiEdit" || tool === "NotebookEdit") && path) return `${w.band_step_edits} ${vaultRel(vault, path)}`;
+  if ((tool === "Edit" || tool === "MultiEdit" || tool === "NotebookEdit") && path)
+    return `${w.band_step_edits} ${vaultRel(vault, path)}`;
   if (tool === "Grep" || tool === "Glob") {
     if (typeof call.pattern !== "string") return w.band_step_searches;
     return `${w.band_step_searches} ${call.pattern.length > 32 ? call.pattern.slice(0, 31) + "…" : call.pattern}`;
@@ -323,7 +438,9 @@ export function leadAgent(agents, now) {
   const order = new Map(live.map((a, i) => [a, i]));
   const later = (a, b) => order.get(b) - order.get(a);
   const running = live.filter((a) => a.status === "running").sort((a, b) => b.startedAt - a.startedAt || later(a, b));
-  const ended = live.filter((a) => a.status !== "running").sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0) || later(a, b));
+  const ended = live
+    .filter((a) => a.status !== "running")
+    .sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0) || later(a, b));
   const lead = running[0] || ended[0] || null;
   return { lead, others: lead ? live.length - 1 : 0, live };
 }

package/node_modules/projectstore/scripts/band.mjs

@@ -31,20 +31,38 @@ export function bandKeys(cfg) {
 export function epicIds(cfg, root) {
   if (!cfg || !cfg.vault_path) return [];
   let folder;
-  try { folder = folderByKind(loadLayout(cfg.layout || "engineering", root), "epic"); } catch { folder = null; }
+  try {
+    folder = folderByKind(loadLayout(cfg.layout || "engineering", root), "epic");
+  } catch {
+    folder = null;
+  }
   if (!folder) return [];
   const dir = join(cfg.vault_path, folder.path);
-  let names = [];
-  try { names = readdirSync(dir); } catch { return []; }
-  return names.filter((n) => {
-    if (!isEpicName(n)) return false;
-    try { return statSync(join(dir, n)).isDirectory(); } catch { return false; }
-  }).sort();
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => {
+      if (!isEpicName(n)) return false;
+      try {
+        return statSync(join(dir, n)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort();
 }
 
 function readBinding(path) {
   if (!existsSync(path)) return { raw: null, corrupt: false };
-  try { return { raw: JSON.parse(readFileSync(path, "utf8")), corrupt: false }; } catch { return { raw: null, corrupt: true }; }
+  try {
+    return { raw: JSON.parse(readFileSync(path, "utf8")), corrupt: false };
+  } catch {
+    return { raw: null, corrupt: true };
+  }
 }
 
 // What a write would do: the binding's path, its band keys before and after,
@@ -53,9 +71,20 @@ function readBinding(path) {
 export function planBand(projectDir, sub, arg, { env = process.env, root } = {}) {
   const path = harnessConfigPath(projectDir, env);
   const { raw, corrupt } = readBinding(path);
-  if (corrupt) return { path, refusal: { code: "UNREADABLE", message: `${path} is not valid JSON — fix or remove it first; nothing is written` } };
+  if (corrupt)
+    return {
+      path,
+      refusal: {
+        code: "UNREADABLE",
+        message: `${path} is not valid JSON — fix or remove it first; nothing is written`,
+      },
+    };
   // A bare `{ band: {} }` file would read as a binding: never create one.
-  if (!raw) return { path, refusal: { code: "UNBOUND", message: `${projectDir} is not bound to a vault; there is no band to switch` } };
+  if (!raw)
+    return {
+      path,
+      refusal: { code: "UNBOUND", message: `${projectDir} is not bound to a vault; there is no band to switch` },
+    };
   const before = bandKeys(raw);
   const next = { ...(raw.band && typeof raw.band === "object" ? raw.band : {}) };
   if (sub === "on") next.enabled = true;
@@ -63,7 +92,14 @@ export function planBand(projectDir, sub, arg, { env = process.env, root } = {})
   else if (sub === "epic" && arg) {
     const ids = epicIds(raw, root);
     const hit = ids.find((id) => id.toLowerCase() === String(arg).toLowerCase());
-    if (!hit) return { path, refusal: { code: "UNKNOWN_EPIC", message: `no epic ${arg}${ids.length ? ` — epics: ${ids.join(", ")}` : " — the vault has no epics"}` } };
+    if (!hit)
+      return {
+        path,
+        refusal: {
+          code: "UNKNOWN_EPIC",
+          message: `no epic ${arg}${ids.length ? ` — epics: ${ids.join(", ")}` : " — the vault has no epics"}`,
+        },
+      };
     next.epic = hit;
   } else if (sub === "epic") delete next.epic;
   else return { path, refusal: { code: "USAGE", message: `band takes ${SUBCOMMANDS.join(", ")}` } };
@@ -83,10 +119,12 @@ export function applyBand(plan) {
 const REASONS = Object.freeze({
   harness: "this harness has no band",
   off: "switched off (projectstore band on)",
-  session_unknown: "this session is unknown here (no session id from the host), so neither its epic nor its heartbeat can be read",
+  session_unknown:
+    "this session is unknown here (no session id from the host), so neither its epic nor its heartbeat can be read",
   pin_missing: "the pinned epic no longer exists",
   no_epic: "this session has no epic, and none is pinned",
-  not_drawing: "the module is not drawing (modules switched off by the host, an older Claude Code, or a crashed module)",
+  not_drawing:
+    "the module is not drawing (modules switched off by the host, an older Claude Code, or a crashed module)",
 });
 
 // Why the band is or is not drawing in this session, read-only. The session
@@ -105,7 +143,11 @@ export function bandStatus(projectDir, cfg, { env = process.env, now = Date.now(
     } catch {}
     const name = heartbeatFile(sessionId);
     if (name) {
-      try { heartbeat = heartbeatState(JSON.parse(readFileSync(join(stateDir(projectDir), name), "utf8")), now); } catch { heartbeat = "none"; }
+      try {
+        heartbeat = heartbeatState(JSON.parse(readFileSync(join(stateDir(projectDir), name), "utf8")), now);
+      } catch {
+        heartbeat = "none";
+      }
     }
   }
   const ids = epicIds(cfg, root);
@@ -146,11 +188,20 @@ export function renderBandStatus(s) {
 }
 
 export function renderBandPlan(plan, sub, arg) {
-  const what = sub === "on" ? "switch the band on" : sub === "off" ? "switch the band off" : arg ? `pin the band to ${plan.after.epic}` : "release the pinned epic";
-  return [
-    `band ${sub}${arg ? ` ${arg}` : ""} — ${plan.path}`,
-    `  ${what}`,
-    `  enabled: ${plan.before.enabled ? "on" : "off"} → ${plan.after.enabled ? "on" : "off"}`,
-    `  pinned: ${plan.before.epic || "—"} → ${plan.after.epic || "—"}`,
-  ].join("\n") + "\n";
+  const what =
+    sub === "on"
+      ? "switch the band on"
+      : sub === "off"
+        ? "switch the band off"
+        : arg
+          ? `pin the band to ${plan.after.epic}`
+          : "release the pinned epic";
+  return (
+    [
+      `band ${sub}${arg ? ` ${arg}` : ""} — ${plan.path}`,
+      `  ${what}`,
+      `  enabled: ${plan.before.enabled ? "on" : "off"} → ${plan.after.enabled ? "on" : "off"}`,
+      `  pinned: ${plan.before.epic || "—"} → ${plan.after.epic || "—"}`,
+    ].join("\n") + "\n"
+  );
 }