projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/scripts/lib.mjs

@@ -2,12 +2,30 @@
 // Pure node, no external deps. Keep this single-file & dependency-free
 // so plugin install does not require npm install.
 
-import { readFileSync, writeFileSync, writeSync, appendFileSync, existsSync, readdirSync, statSync, lstatSync, mkdirSync, utimesSync, unlinkSync, renameSync, rmSync, realpathSync, cpSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  writeSync,
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  statSync,
+  lstatSync,
+  mkdirSync,
+  utimesSync,
+  unlinkSync,
+  renameSync,
+  rmSync,
+  realpathSync,
+  copyFileSync,
+} from "node:fs";
 import { readFile as readFileAsync } from "node:fs/promises";
 import { join, dirname, basename, resolve, relative, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import { hostname, homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { parseFrontmatter } from "./stages.mjs";
+import { storyKeyOf } from "./band-shared.mjs";
 import {
   projectRoot as harnessProjectRoot,
   pluginRoot as harnessPluginRoot,
@@ -20,6 +38,7 @@ import {
   overlayId,
   hostSettingsPath,
   layoutPaths,
+  cachePaths,
   pickExisting,
   LAYOUT,
   RUNTIME_GITIGNORE_HEADER,
@@ -31,6 +50,8 @@ import {
   invocation,
   speakingHarness,
   packageCommand,
+  whichOnPath,
+  hostSessionId,
 } from "./harness.mjs";
 
 // ─── Paths ─────────────────────────────────────────────────────────────
@@ -73,8 +94,11 @@ export function updateHint({ env = process.env } = {}) {
   const m = speakingHarness(env) || {};
   // A harness that declares no hint gets none — never another harness's advice.
   const hint = m.update_hint || { line: "", welcome: [] };
-  // `{upgrade}` is the harness's own shell command, pinned to latest so it runs as printed.
-  const upgrade = m.install?.shell ? packageCommand(m, "upgrade", { version: "latest", args: '--project "$PWD"' }) : "";
+  // `{upgrade}` is the core's upgrade for this harness, pinned to latest so it
+  // runs as printed, with no --project: the hint says where to run it (the
+  // story "User-facing text says where to run…", rule 2). Any hint that holds
+  // the placeholder gets it; one that holds none prints as written.
+  const upgrade = m.id ? packageCommand(m, "upgrade", { version: "latest" }) : "";
   const fill = (t) => String(t).split("{upgrade}").join(upgrade);
   return { line: fill(hint.line || ""), welcome: (hint.welcome || []).map(fill) };
 }
@@ -96,17 +120,65 @@ export function bindInherits({ env = process.env } = {}) {
 export function inheritForm(vaultPath, { layout = null, language = null, env = process.env } = {}) {
   if (speakingHarness(env)?.capabilities?.bind_inherit) return commandForm("bind", { args: "--inherit", env });
   const plain = (v) => typeof v === "string" && /^[a-z0-9-]+$/.test(v);
-  const args = [JSON.stringify(String(vaultPath)), plain(layout) ? `--layout ${layout}` : "", plain(language) ? `--language ${language}` : ""].filter(Boolean).join(" ");
+  const args = [
+    JSON.stringify(String(vaultPath)),
+    plain(layout) ? `--layout ${layout}` : "",
+    plain(language) ? `--language ${language}` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
   return commandForm("bind", { args, env });
 }
 export function speakingDisplayName({ env = process.env } = {}) {
   return speakingHarness(env)?.display_name || "another";
 }
 
+// ─── doctor's last line (presentation spec, contract 11) ───────────────
+//
+// The Summary line ends every text report of doctor's, verbatim from its
+// 0.29.2 report: the write ceremony captures it as the pre-state and compares
+// it after (commands/story.md step 5a, agents/clerk.md), so its bytes are a
+// contract. It lives here, beside commandForm, because every printer of the
+// report needs it — doctor-report.mjs, and the fallback of each caller when
+// that renderer cannot be loaded or throws — and this is the one module all
+// of them already import. `env` decides the command forms.
+export function doctorSummaryLine(findings, { env = process.env } = {}) {
+  const issues = findings.filter((f) => f.level === "issue").length;
+  const warns = findings.filter((f) => f.level === "warn").length;
+  return `Summary: ${issues} issue(s), ${warns} warning(s). ${issues ? `Repairs: ${commandForm("doctor", { args: "--fix", env })} (install), ${commandForm("kanban", { env })} / reconcile (vault).` : "Vault and wiring look healthy."}`;
+}
+
+// What a reader gets when the renderer cannot draw the findings: each one
+// per line, `level check message — file`, then the Summary line, still last.
+export function doctorFallbackText(findings, { env = process.env } = {}) {
+  // A message's first line is prose; each further line is a lead ending with
+  // `:` or a command (the story "User-facing text says where to run…", rule 4
+  // as amended): the file stays with the first line's words, and every
+  // further line keeps a line of its own, as the message has it.
+  const lines = findings.map((f) => {
+    const [said, ...commands] = String(f.message).split("\n");
+    return [`${f.level} ${f.check} ${said}${f.file ? ` — ${f.file}` : ""}`, ...commands].join("\n");
+  });
+  return [...lines, ...(lines.length ? [""] : []), doctorSummaryLine(findings, { env })].join("\n") + "\n";
+}
+
 // The layout resolver and its constants, re-exported so hooks and scripts
 // import one module (the layout ADR, 2026-09-06). The active harness's id,
-// for the paths keyed by it (state/<id>/…).
-export { layoutPaths, pickExisting, LAYOUT, RUNTIME_GITIGNORE_HEADER, hostSettingsPath, overlayId, speakingHarness };
+// for the paths keyed by it (state/<id>/…). cachePaths is the user-level
+// class beside it (layout spec contract 0): the shell fetch's scratch.
+// whichOnPath, the PATH walk for a host binary, moved to harness.mjs beside
+// hostPresence (the setup story, rule 5); its importers keep this name.
+export {
+  layoutPaths,
+  cachePaths,
+  pickExisting,
+  LAYOUT,
+  RUNTIME_GITIGNORE_HEADER,
+  hostSettingsPath,
+  overlayId,
+  speakingHarness,
+  whichOnPath,
+};
 
 // A hook's payload carries the `cwd` of the session that fired it, and on a
 // harness that exports no project-dir variable it is the only answer better
@@ -126,16 +198,35 @@ export function readOverlayAt(projectDir, id = overlayId()) {
   // No id (no manifest at all): nothing is read, and the writer below refuses
   // the same id rather than inventing a file name for it.
   const path = id ? layoutPaths(projectDir).overlay(id) : null;
-  const out = { id: id || null, path, present: Boolean(path) && existsSync(path), unparseable: false, agents: { default: null, per_agent: {} }, rejected: [], raw: null };
+  const out = {
+    id: id || null,
+    path,
+    present: Boolean(path) && existsSync(path),
+    unparseable: false,
+    agents: { default: null, per_agent: {} },
+    rejected: [],
+    raw: null,
+  };
   if (!out.present) return out;
   let raw;
-  try { raw = JSON.parse(readFileSync(path, "utf8")); } catch { out.unparseable = true; return out; }
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) { out.unparseable = true; return out; }
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    out.unparseable = true;
+    return out;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    out.unparseable = true;
+    return out;
+  }
   out.raw = raw;
   for (const k of Object.keys(raw)) if (k !== "agents") out.rejected.push(k);
   const a = raw.agents;
   if (a === undefined) return out;
-  if (!a || typeof a !== "object" || Array.isArray(a)) { out.rejected.push("agents"); return out; }
+  if (!a || typeof a !== "object" || Array.isArray(a)) {
+    out.rejected.push("agents");
+    return out;
+  }
   for (const k of Object.keys(a)) if (k !== "default" && k !== "per_agent") out.rejected.push(`agents.${k}`);
   if (a.default !== undefined) {
     if (a.default && typeof a.default === "object") {
@@ -146,7 +237,10 @@ export function readOverlayAt(projectDir, id = overlayId()) {
   if (a.per_agent !== undefined) {
     if (a.per_agent && typeof a.per_agent === "object" && !Array.isArray(a.per_agent)) {
       for (const [name, v] of Object.entries(a.per_agent)) {
-        if (!v || typeof v !== "object") { out.rejected.push(`agents.per_agent.${name}`); continue; }
+        if (!v || typeof v !== "object") {
+          out.rejected.push(`agents.per_agent.${name}`);
+          continue;
+        }
         for (const k of Object.keys(v)) if (k !== "model") out.rejected.push(`agents.per_agent.${name}.${k}`);
         if (typeof v.model === "string" && v.model) out.agents.per_agent[name] = v.model;
       }
@@ -171,14 +265,17 @@ export function writeOverlayAt(projectDir, id, agents) {
   if (!id) throw new Error("writeOverlayAt: the overlay's harness id is required");
   const path = layoutPaths(projectDir).overlay(id);
   let raw = {};
-  try { raw = JSON.parse(readFileSync(path, "utf8")); } catch {}
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch {}
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) raw = {};
   const block = {};
   if (agents.default) block.default = { model: agents.default };
   const names = Object.keys(agents.per_agent || {}).sort();
   if (names.length) block.per_agent = Object.fromEntries(names.map((n) => [n, { model: agents.per_agent[n] }]));
   const next = { ...raw };
-  if (Object.keys(block).length) next.agents = block; else delete next.agents;
+  if (Object.keys(block).length) next.agents = block;
+  else delete next.agents;
   ensureRuntimeDir(projectDir);
   mkdirSync(dirname(path), { recursive: true });
   writeFileAtomic(path, JSON.stringify(next, null, 2) + "\n", { sweep: false });
@@ -194,11 +291,13 @@ export function activeHarnessId() {
 export function ensureGitignoreLines(file, lines, header = null) {
   mkdirSync(dirname(file), { recursive: true });
   let cur = "";
-  try { cur = readFileSync(file, "utf8"); } catch {}
+  try {
+    cur = readFileSync(file, "utf8");
+  } catch {}
   const have = new Set(cur.split(/\r?\n/).map((l) => l.trim()));
   const add = lines.filter((l) => !have.has(l));
   if (!add.length) return false;
-  const prefix = cur ? (cur.endsWith("\n") ? cur : cur + "\n") : (header ? `# ${header}\n` : "");
+  const prefix = cur ? (cur.endsWith("\n") ? cur : cur + "\n") : header ? `# ${header}\n` : "";
   writeFileSync(file, prefix + add.join("\n") + "\n", "utf8");
   return true;
 }
@@ -217,14 +316,37 @@ export function moveStateDir(from, to, within) {
   mkdirSync(to, { recursive: true });
   for (const name of readdirSync(from)) {
     if (name === ".gitignore") continue;
-    const src = join(from, name), dst = join(to, name);
-    let st; try { st = lstatSync(src); } catch { continue; }
-    if (st.isSymbolicLink()) { out.dropped.push(name); continue; }
-    if (!existsSync(dst)) { movePath(src, dst, within); out.moved.push(name); continue; }
-    if (st.isDirectory() || name.startsWith(".")) { rmSync(src, { recursive: true, force: true }); out.kept.push(name); continue; }
+    const src = join(from, name),
+      dst = join(to, name);
+    let st;
+    try {
+      st = lstatSync(src);
+    } catch {
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      out.dropped.push(name);
+      continue;
+    }
+    if (!existsSync(dst)) {
+      movePath(src, dst, within);
+      out.moved.push(name);
+      continue;
+    }
+    if (st.isDirectory() || name.startsWith(".")) {
+      rmSync(src, { recursive: true, force: true });
+      out.kept.push(name);
+      continue;
+    }
     const newer = st.mtimeMs > statSync(dst).mtimeMs;
-    if (newer) { rmSync(dst, { force: true }); movePath(src, dst, within); out.replaced.push(name); }
-    else { rmSync(src, { force: true }); out.kept.push(name); }
+    if (newer) {
+      rmSync(dst, { force: true });
+      movePath(src, dst, within);
+      out.replaced.push(name);
+    } else {
+      rmSync(src, { force: true });
+      out.kept.push(name);
+    }
   }
   return out;
 }
@@ -233,10 +355,16 @@ export function moveStateDir(from, to, within) {
 // the legacy file is removed; an absent side is fine.
 export function mergeEntryLog(from, to, within) {
   if (!existsSync(from)) return "absent";
-  const inside = (p) => { const r = relative(resolve(within), resolve(p)); return r !== "" && !r.startsWith("..") && !isAbsolute(r); };
+  const inside = (p) => {
+    const r = relative(resolve(within), resolve(p));
+    return r !== "" && !r.startsWith("..") && !isAbsolute(r);
+  };
   if (!inside(from) || !inside(to)) throw new Error(`mergeEntryLog: ${from} → ${to} leaves ${within}`);
   const old = readFileSync(from, "utf8");
-  let cur = ""; try { cur = readFileSync(to, "utf8"); } catch {}
+  let cur = "";
+  try {
+    cur = readFileSync(to, "utf8");
+  } catch {}
   mkdirSync(dirname(to), { recursive: true });
   const glue = old && !old.endsWith("\n") ? "\n" : "";
   writeFileAtomic(to, old + glue + cur, { sweep: false });
@@ -256,7 +384,10 @@ export function removeInside(path, within, { recursive = false } = {}) {
 }
 
 export function movePath(from, to, within) {
-  const inside = (p) => { const r = relative(resolve(within), resolve(p)); return r !== "" && !r.startsWith("..") && !isAbsolute(r); };
+  const inside = (p) => {
+    const r = relative(resolve(within), resolve(p));
+    return r !== "" && !r.startsWith("..") && !isAbsolute(r);
+  };
   if (!inside(from) || !inside(to)) throw new Error(`movePath: ${from} → ${to} leaves ${within}`);
   if (!existsSync(from)) return "absent";
   if (existsSync(to)) return "target-exists";
@@ -276,7 +407,7 @@ export function readConfigAt(projectDir) {
   if (!existsSync(p)) return null;
   try {
     return JSON.parse(readFileSync(p, "utf8"));
-  } catch (e) {
+  } catch {
     return null;
   }
 }
@@ -298,7 +429,11 @@ export function isMain(metaUrl) {
   if (!argv1) return false;
   const here = fileURLToPath(metaUrl);
   if (resolve(argv1) === here) return true;
-  try { return realpathSync(argv1) === here; } catch { return false; }
+  try {
+    return realpathSync(argv1) === here;
+  } catch {
+    return false;
+  }
 }
 
 // ─── Atomic file writes (spec: atomic-regeneration-of-derived-views) ──
@@ -323,7 +458,9 @@ export function writeFileAtomic(p, content, { sweep = true } = {}) {
     writeFileSync(tmp, content, "utf8");
     renameSync(tmp, p);
   } catch (e) {
-    try { unlinkSync(tmp); } catch {}
+    try {
+      unlinkSync(tmp);
+    } catch {}
     throw e;
   }
 }
@@ -348,22 +485,36 @@ export function writeExclusiveMetadata(fd, value) {
 // numeric pid, `.tmp`) can never match `.gitignore` and friends.
 function sweepOrphanTemps(dir) {
   let names;
-  try { names = readdirSync(dir); } catch { return; }
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
   for (const n of names) {
     const m = n.match(/^\..+\.(\d+)\.tmp$/);
     if (!m) continue;
     const pid = parseInt(m[1], 10);
     if (!pid || pid === process.pid) continue;
-    try {
-      process.kill(pid, 0); // returns ⇒ alive; EPERM ⇒ alive, not ours
-    } catch (e) {
-      if (e.code === "ESRCH") {
-        try { unlinkSync(join(dir, n)); } catch {}
-      }
+    if (!pidAlive(pid)) {
+      try {
+        unlinkSync(join(dir, n));
+      } catch {}
     }
   }
 }
 
+// The sweeps' one liveness rule: signal 0 returns ⇒ alive; EPERM ⇒ alive but
+// not ours; only ESRCH is dead. Shared by the temp sweep above and the shell
+// fetch's scratch sweep (fetch-shell.mjs), so the two cannot drift.
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code !== "ESRCH";
+  }
+}
+
 // ─── Installed-plugin resolution ───────────────────────────────────────
 
 // The harness's config directory. Almost always ~/.claude, but the harness's
@@ -378,8 +529,12 @@ export function claudeHome(home = homedir()) {
 // "which release line" (the layout window's sunset); wrong for "which build is
 // newer" — that is cmpPrecedence.
 export function cmpVersion(a, b) {
-  const A = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
-  const B = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const A = String(a || "0")
+    .split(".")
+    .map((n) => parseInt(n, 10) || 0);
+  const B = String(b || "0")
+    .split(".")
+    .map((n) => parseInt(n, 10) || 0);
   for (let i = 0; i < 3; i++) if ((A[i] || 0) !== (B[i] || 0)) return (A[i] || 0) - (B[i] || 0);
   return 0;
 }
@@ -392,18 +547,27 @@ export function cmpPrecedence(a, b) {
   const parse = (v) => {
     const s = String(v || "0").split("+")[0];
     const dash = s.indexOf("-");
-    return { core: (dash < 0 ? s : s.slice(0, dash)).split(".").map((n) => parseInt(n, 10) || 0), pre: dash < 0 ? [] : s.slice(dash + 1).split(".") };
+    return {
+      core: (dash < 0 ? s : s.slice(0, dash)).split(".").map((n) => parseInt(n, 10) || 0),
+      pre: dash < 0 ? [] : s.slice(dash + 1).split("."),
+    };
   };
-  const A = parse(a), B = parse(b);
+  const A = parse(a),
+    B = parse(b);
   for (let i = 0; i < 3; i++) if ((A.core[i] || 0) !== (B.core[i] || 0)) return (A.core[i] || 0) - (B.core[i] || 0);
   // A release outranks every candidate for it.
   if (!A.pre.length || !B.pre.length) return B.pre.length - A.pre.length;
   for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
     if (i >= A.pre.length) return -1;
     if (i >= B.pre.length) return 1;
-    const x = A.pre[i], y = B.pre[i];
-    const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
-    if (nx && ny) { if (Number(x) !== Number(y)) return Number(x) - Number(y); continue; }
+    const x = A.pre[i],
+      y = B.pre[i];
+    const nx = /^\d+$/.test(x),
+      ny = /^\d+$/.test(y);
+    if (nx && ny) {
+      if (Number(x) !== Number(y)) return Number(x) - Number(y);
+      continue;
+    }
     // A numeric identifier ranks below an alphanumeric one.
     if (nx !== ny) return nx ? -1 : 1;
     if (x !== y) return x < y ? -1 : 1;
@@ -428,16 +592,24 @@ export function cmpPrecedence(a, b) {
 // The host's enablement of a plugin, user settings first and the project's
 // settings over it (a project may silence a user-scope plugin). Absent → true.
 export function pluginEnabled(key, home = homedir(), projectDir = null) {
-  const read = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+  const read = (p) => {
+    try {
+      return JSON.parse(readFileSync(p, "utf8"));
+    } catch {
+      return null;
+    }
+  };
   let enabled = true;
   const user = read(join(claudeHome(home), "settings.json"));
-  if (user && user.enabledPlugins && Object.hasOwn(user.enabledPlugins, key)) enabled = user.enabledPlugins[key] !== false;
+  if (user && user.enabledPlugins && Object.hasOwn(user.enabledPlugins, key))
+    enabled = user.enabledPlugins[key] !== false;
   if (projectDir) {
     // The committed project file, then the checkout's local one over it — the
     // host's own precedence (measured 2026-09-05, --scope local).
     for (const f of ["settings.json", "settings.local.json"]) {
       const proj = read(join(projectDir, harnessProjectConfigDir(), f));
-      if (proj && proj.enabledPlugins && Object.hasOwn(proj.enabledPlugins, key)) enabled = proj.enabledPlugins[key] !== false;
+      if (proj && proj.enabledPlugins && Object.hasOwn(proj.enabledPlugins, key))
+        enabled = proj.enabledPlugins[key] !== false;
     }
   }
   return enabled;
@@ -474,18 +646,135 @@ export function installedPluginEntries(home = homedir(), projectDir = null) {
   return out;
 }
 
-// A pure PATH walk for a host binary — a read, not a subprocess: the analysers
-// run on every doctor call. Returns the absolute path or null.
-export function whichOnPath(name, env = process.env) {
-  const sep = process.platform === "win32" ? ";" : ":";
-  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
-  for (const dir of String(env.PATH || "").split(sep).filter(Boolean)) {
-    for (const ext of exts) {
-      const p = join(dir, name + ext);
-      try { const st = statSync(p); if (st.isFile() && (process.platform === "win32" || (st.mode & 0o111))) return p; } catch {}
+// Contract 12's selection (the layout spec, as amended 2026-10-03): the copies
+// of ours the host loads for this project — present, enabled for it, and this
+// checkout's own row or a row with no project (user scope), never another
+// checkout's. This checkout's row first, then the most recently updated. Real
+// paths: the host records the project's cwd as one, and /var against
+// /private/var would otherwise drop the project's own row. One filter for
+// doctor's layout remedy and the convergence story's running copies (the
+// converge story's rule 6), so the two cannot disagree about what a project
+// runs. `own` marks this checkout's row.
+export function projectCopies(home = homedir(), projectDir) {
+  const real = (x) => {
+    try {
+      return realpathSync.native(x);
+    } catch {
+      return resolve(x);
     }
+  };
+  const here = real(projectDir);
+  const mine = (e) => Boolean(e.projectPath) && real(e.projectPath) === here;
+  return installedPluginEntries(home, projectDir)
+    .filter((e) => e.present && e.enabled && (!e.projectPath || mine(e)))
+    .map((e) => ({ ...e, own: mine(e) }))
+    .sort((a, b) => Number(b.own) - Number(a.own) || b.at - a.at);
+}
+
+// The same selection, one row per plugin key: the row the host loads for this
+// project — this checkout's own row over a user-scope row of the same key,
+// else the most recent. What "a copy enabled for this project" means for the
+// competing copies the registration silences (surfaces.mjs, contract 13) and
+// for the copies the convergence story's rule 6 compares, so the stop and the
+// deferral of a newer copy always see the same (key, version) pairs.
+export function projectCopiesByKey(home = homedir(), projectDir) {
+  const seen = new Set();
+  return projectCopies(home, projectDir).filter((e) => !seen.has(e.key) && seen.add(e.key));
+}
+
+// Whether a registry copy can run the command named for it. `--no-register`
+// arrived in 0.28.0-rc.3, and rc.1 and rc.2 parse strictly, so the command
+// exits 2 on the flag and writes nothing (the layout spec, contract 12 as
+// amended after the rc.3 tag). Read from the copy's own parse table, never
+// from its version: a never-published 0.28.0 build ranks above rc.3 and lacks
+// the flag, while a copy labelled rc.2 taken from main at 418448e has it. A
+// file read, because this runs in the SessionStart subset: never an import()
+// of the copy, never a spawn. Add files to the read, never drop cli.mjs:
+// released copies keep their parse there. Moved here from doctor.mjs (the
+// converge story's rule 5), which re-exports it: doctor's layout remedy and
+// the installer's keep read one function.
+export function takesNoRegister(copy) {
+  try {
+    return readFileSync(join(copy, "scripts", "cli.mjs"), "utf8").includes('"no-register"');
+  } catch {
+    return false;
   }
-  return null;
+}
+// …and whether its CLI takes --verbose, the same way: the flag arrived in
+// 0.29.0, after --no-register, and a copy between them (rc.3 to 0.28.x)
+// parses strictly, so a command naming it would exit 2. Read before DONE names
+// a kept copy's own `plan --verbose`.
+export function takesVerbose(copy) {
+  try {
+    return /\bverbose\b/.test(readFileSync(join(copy, "scripts", "cli.mjs"), "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+// Contract 12's selection with its capability read (the layout spec, contract
+// 12 as amended 2026-10-03; the converge story's rule 5): the first of
+// projectCopies — this checkout's own row, then user-scope rows by recency,
+// never another checkout's — and whether its own bin can run the remedy form
+// (`missing`: "bin" for a copy with no bin/projectstore.mjs, 0.27.x;
+// "no-register" for one whose CLI predates the flag, rc.1 and rc.2; null when
+// it can). `only` limits the rows to one install channel before the first is
+// taken: the keep takes "marketplace", so the npm registration's copy is never
+// the kept one. Doctor's layout remedy and the installer's keep call this one
+// function, so the two never disagree about which copy a project runs.
+export function selectCopy(home = homedir(), projectDir, { harness = sourceHarness(), only = null } = {}) {
+  const copy = projectCopies(home, projectDir).find((e) => !only || installChannel(e.path, { home, harness }) === only);
+  if (!copy) return null;
+  const bin = join(copy.path, "bin", "projectstore.mjs");
+  const missing = !existsSync(bin) ? "bin" : !takesNoRegister(copy.path) ? "no-register" : null;
+  return { ...copy, bin, missing, channel: installChannel(copy.path, { home, harness }) };
+}
+
+// The advice for a marketplace copy that cannot run what is named for it, in
+// that copy's own channel: the host's update, then a restart. `cannot` says
+// what it cannot do, `then` what follows the update. One text for doctor's
+// layout remedy and the keep's skip row and DONE line.
+export function copyUpdateAdvice(copy, { cannot, then }) {
+  const v = copy?.version ? ` (${copy.version})` : "";
+  return `This project's projectstore plugin${v} ${cannot}: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), ${then}`;
+}
+
+// The mark a channel switch leaves in this checkout's machine-local binding
+// (the converge story's rules 2–4): `channel_switch: { by, at }`, two strings.
+// It says this checkout chose the npm install; it lists no copies — the
+// silenced set lives in our manifest and the checkout's local settings.
+// Doctor drops contract 13's "if moving to npm was meant, ignore this" info
+// for a marked checkout, the installer plans no second mark, and uninstall
+// removes the key with the registration. `bind --inherit` never copies it.
+export const CHANNEL_SWITCH_KEY = "channel_switch";
+const stampAt = (cfg, key) => {
+  const m = cfg && typeof cfg === "object" && !Array.isArray(cfg) ? cfg[key] : null;
+  return m && typeof m === "object" && !Array.isArray(m) && typeof m.by === "string" && typeof m.at === "string"
+    ? m
+    : null;
+};
+export function channelMark(cfg) {
+  return stampAt(cfg, CHANNEL_SWITCH_KEY);
+}
+
+// Its counterpart for the other answer (the setup story, rule 6): the keep of
+// the git marketplace, `channel_keep: { by, at }`, recorded when setup's
+// channel question was answered keep. Setup's question then defaults to keep,
+// and a run without a terminal reads it as `--channel git`. Per checkout, as
+// the mark is: `bind --inherit` never copies it. The latest answer wins: a
+// later switch removes it, and recording it removes the mark, so the two
+// never both stay after a run.
+export const CHANNEL_KEEP_KEY = "channel_keep";
+export function channelKeep(cfg) {
+  return stampAt(cfg, CHANNEL_KEEP_KEY);
+}
+
+// A switch read from the environment the way contract 9 reads CI: set, and
+// not empty, "0" or "false" (any case). One reading for CI and for
+// PROJECTSTORE_NO_UPDATE_CHECK (the converge story's rule 8).
+export function envFlag(env, name) {
+  const v = env ? env[name] : undefined;
+  return v !== undefined && v !== null && v !== "" && !["0", "false"].includes(String(v).toLowerCase());
 }
 
 // The files a package ships, as the release gate defines them — package.json
@@ -494,15 +783,26 @@ export function whichOnPath(name, env = process.env) {
 // path outside the tree). Returns the relative paths copied, sorted.
 export function packageFiles(root) {
   let pkg;
-  try { pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); } catch { return []; }
+  try {
+    pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  } catch {
+    return [];
+  }
   const out = new Set(["package.json"]);
   for (const n of readdirSync(root)) if (/^(README|LICEN[CS]E)(\.|$)/i.test(n)) out.add(n);
   const walk = (rel) => {
     const abs = join(root, rel);
-    let st; try { st = lstatSync(abs); } catch { return; }
+    let st;
+    try {
+      st = lstatSync(abs);
+    } catch {
+      return;
+    }
     if (st.isSymbolicLink()) return;
-    if (st.isDirectory()) { for (const n of readdirSync(abs)) if (n !== "node_modules" && !n.startsWith(".DS_Store")) walk(rel ? `${rel}/${n}` : n); }
-    else out.add(rel);
+    if (st.isDirectory()) {
+      for (const n of readdirSync(abs))
+        if (n !== "node_modules" && !n.startsWith(".DS_Store")) walk(rel ? `${rel}/${n}` : n);
+    } else out.add(rel);
   };
   for (const f of pkg.files || []) walk(f.replace(/\/+$/, ""));
   return [...out].sort();
@@ -512,8 +812,12 @@ export function packageFiles(root) {
 // ours (install spec contract 13, amended 2026-09-05). The caller has already
 // proven the manifest is ours; this refuses anything outside the harness home.
 export function removeOwnTree(dir, home = homedir()) {
-  const norm = (s) => String(s || "").replace(/\\/g, "/").replace(/\/+$/, "");
-  if (!norm(dir).startsWith(norm(claudeHome(home)) + "/")) throw new Error(`removeOwnTree: ${dir} is not under the harness home`);
+  const norm = (s) =>
+    String(s || "")
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
+  if (!norm(dir).startsWith(norm(claudeHome(home)) + "/"))
+    throw new Error(`removeOwnTree: ${dir} is not under the harness home`);
   rmSync(dir, { recursive: true, force: true });
 }
 
@@ -522,7 +826,7 @@ export function copyPackageTree(from, to) {
   for (const rel of files) {
     const dst = join(to, rel);
     mkdirSync(dirname(dst), { recursive: true });
-    cpSync(join(from, rel), dst);
+    copyFileSync(join(from, rel), dst);
   }
   return files;
 }
@@ -532,10 +836,17 @@ export function treeFiles(dir) {
   const out = [];
   const walk = (rel) => {
     const abs = rel ? join(dir, rel) : dir;
-    let st; try { st = lstatSync(abs); } catch { return; }
+    let st;
+    try {
+      st = lstatSync(abs);
+    } catch {
+      return;
+    }
     if (st.isSymbolicLink()) return;
-    if (st.isDirectory()) { for (const n of readdirSync(abs)) if (n !== "node_modules" && !n.startsWith(".DS_Store")) walk(rel ? `${rel}/${n}` : n); }
-    else out.push(rel);
+    if (st.isDirectory()) {
+      for (const n of readdirSync(abs))
+        if (n !== "node_modules" && !n.startsWith(".DS_Store")) walk(rel ? `${rel}/${n}` : n);
+    } else out.push(rel);
   };
   walk("");
   return out.sort();
@@ -549,7 +860,11 @@ export function filesDigest(root, files) {
   const h = createHash("sha256");
   for (const rel of files) {
     h.update(rel + "\n");
-    h.update(createHash("sha256").update(readFileSync(join(root, rel))).digest("hex") + "\n");
+    h.update(
+      createHash("sha256")
+        .update(readFileSync(join(root, rel)))
+        .digest("hex") + "\n",
+    );
   }
   return { count: files.length, sha256: h.digest("hex") };
 }
@@ -562,8 +877,12 @@ export const treeDigest = (dir) => filesDigest(dir, treeFiles(dir));
 // contract 4′). An existing directory is removed only after the stage is
 // complete — and only by the caller's proof that it is ours.
 export function writeOwnTree(dir, { from, subdir, manifestRel, manifest, home = homedir() }) {
-  const norm = (s) => String(s || "").replace(/\\/g, "/").replace(/\/+$/, "");
-  if (!norm(dir).startsWith(norm(claudeHome(home)) + "/")) throw new Error(`writeOwnTree: ${dir} is not under the harness home`);
+  const norm = (s) =>
+    String(s || "")
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
+  if (!norm(dir).startsWith(norm(claudeHome(home)) + "/"))
+    throw new Error(`writeOwnTree: ${dir} is not under the harness home`);
   const stage = dir + ".staging";
   rmSync(stage, { recursive: true, force: true });
   mkdirSync(join(stage, subdir), { recursive: true });
@@ -580,27 +899,49 @@ export function writeOwnTree(dir, { from, subdir, manifestRel, manifest, home =
 // entry is re-checked as a regular file at apply time, so a symlink swap cannot
 // escape the source root. The previous directory is retained until the caller
 // verifies the host cache and returns the backup path for commit/rollback.
-export function stagePortableMarketplace(dir, { from, files, subdir, catalogRel, catalog, ownershipRel, ownership, homeBase, token = `${process.pid}-${randomUUID()}` }) {
-  const norm = (s) => String(s || "").replace(/\\/g, "/").replace(/\/+$/, "");
-  if (!norm(dir).startsWith(norm(homeBase) + "/")) throw new Error(`stagePortableMarketplace: ${dir} is not under ${homeBase}`);
+export function stagePortableMarketplace(
+  dir,
+  {
+    from,
+    files,
+    subdir,
+    catalogRel,
+    catalog,
+    ownershipRel,
+    ownership,
+    homeBase,
+    token = `${process.pid}-${randomUUID()}`,
+  },
+) {
+  const norm = (s) =>
+    String(s || "")
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
+  if (!norm(dir).startsWith(norm(homeBase) + "/"))
+    throw new Error(`stagePortableMarketplace: ${dir} is not under ${homeBase}`);
   const stage = `${dir}.staging-${token}`;
   const backup = existsSync(dir) ? `${dir}.previous-${token}` : null;
   rmSync(stage, { recursive: true, force: true });
   for (const rel of files) {
     const src = join(from, rel);
     const st = lstatSync(src);
-    if (!st.isFile() || st.isSymbolicLink()) throw new Error(`portable payload changed under the plan: ${rel} is not a regular file`);
+    if (!st.isFile() || st.isSymbolicLink())
+      throw new Error(`portable payload changed under the plan: ${rel} is not a regular file`);
     const dst = join(stage, subdir, rel);
     mkdirSync(dirname(dst), { recursive: true });
-    cpSync(src, dst);
+    copyFileSync(src, dst);
   }
   mkdirSync(dirname(join(stage, catalogRel)), { recursive: true });
   mkdirSync(dirname(join(stage, ownershipRel)), { recursive: true });
   writeFileAtomic(join(stage, catalogRel), JSON.stringify(catalog, null, 2) + "\n", { sweep: false });
   writeFileAtomic(join(stage, ownershipRel), JSON.stringify(ownership, null, 2) + "\n", { sweep: false });
   if (backup) renameSync(dir, backup);
-  try { renameSync(stage, dir); }
-  catch (e) { if (backup && !existsSync(dir)) renameSync(backup, dir); throw e; }
+  try {
+    renameSync(stage, dir);
+  } catch (e) {
+    if (backup && !existsSync(dir)) renameSync(backup, dir);
+    throw e;
+  }
   return { stage, backup };
 }
 
@@ -615,17 +956,28 @@ export function rollbackPortableMarketplace(dir, backup = null) {
   return dir;
 }
 
-export function removeTreeUnder(dir, homeBase) {
-  const norm = (s) => String(s || "").replace(/\\/g, "/").replace(/\/+$/, "");
+// `maxRetries` is rmSync's own: a tree another process may still be writing
+// into (an npm the fetch budget stopped) can fail with ENOTEMPTY or EBUSY
+// once and succeed on the next pass. The path guard holds whatever it is.
+export function removeTreeUnder(dir, homeBase, { maxRetries = 0 } = {}) {
+  const norm = (s) =>
+    String(s || "")
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
   if (!norm(dir).startsWith(norm(homeBase) + "/")) throw new Error(`removeTreeUnder: ${dir} is not under ${homeBase}`);
-  rmSync(dir, { recursive: true, force: true });
+  rmSync(dir, { recursive: true, force: true, maxRetries });
 }
 
 export function installedPluginRoot(home = homedir(), preferFamily = null) {
   try {
     const found = installedPluginEntries(home)
       .filter((e) => e.present && e.enabled !== false)
-      .map((e) => ({ path: e.path, version: e.version, same: preferFamily && dirname(e.path) === preferFamily ? 1 : 0, at: e.at }));
+      .map((e) => ({
+        path: e.path,
+        version: e.version,
+        same: preferFamily && dirname(e.path) === preferFamily ? 1 : 0,
+        at: e.at,
+      }));
     // Family is a filter, not a tiebreak: when the caller came from a known
     // marketplace, an install from a DIFFERENT one is not a newer copy of the
     // same plugin — it is someone else's fork, and we do not execute it.
@@ -646,13 +998,27 @@ export function installedPluginRoot(home = homedir(), preferFamily = null) {
 // took its own copy for a checkout and planned the package's registration
 // (measured 2026-10-03, the critic of the layout spec's contract 12 amendment).
 function underPluginCache(root, home = homedir()) {
-  const norm = (s) => String(s || "").replace(/\\/g, "/").replace(/\/+$/, "");
+  const norm = (s) =>
+    String(s || "")
+      .replace(/\\/g, "/")
+      .replace(/\/+$/, "");
   const cache = join(claudeHome(home), "plugins", "cache");
-  const below = (r, c) => { const a = norm(r), b = norm(c); return a.startsWith(b + "/") ? a.slice(b.length + 1) : null; };
+  const below = (r, c) => {
+    const a = norm(r),
+      b = norm(c);
+    return a.startsWith(b + "/") ? a.slice(b.length + 1) : null;
+  };
   const direct = below(root, cache);
   if (direct !== null || !root) return direct;
-  const real = (x) => { try { return realpathSync(x); } catch { return null; } };
-  const rr = real(root), rc = real(cache);
+  const real = (x) => {
+    try {
+      return realpathSync(x);
+    } catch {
+      return null;
+    }
+  };
+  const rr = real(root),
+    rc = real(cache);
   return rr && rc ? below(rr, rc) : null;
 }
 
@@ -668,10 +1034,13 @@ export function isEphemeralRoot(root) {
 }
 
 // Which channel the copy at `root` came through. A remedy that re-runs the
-// installer has to ask this first, because the package's shell registers the
-// plugin through its OWN channel: run for a git-marketplace user, it adds a
-// second copy and turns the installed one off for the checkout (the layout
-// spec, contract 12 as amended 2026-10-03). The answers:
+// installer has to ask this first, because the npm package's upgrade
+// registers the plugin through the npm channel: run for a git-marketplace
+// user without --no-register, it adds a second copy and turns the installed
+// one off for the checkout (the layout spec, contract 12 as amended
+// 2026-10-03). So the remedy names the copy's own bin for a host copy of
+// another channel, and the core's form only for the npm registration's. The
+// answers:
 // - "registration": the host's cache copy of the registration marketplace the
 //   manifest names, i.e. the package's own channel;
 // - "marketplace": any other host cache copy (the git marketplace, a fork);
@@ -697,10 +1066,20 @@ export function installChannel(root, { home = homedir(), harness = sourceHarness
 // wrote an AGENTS.md into it (2026-10-05). bind refuses the same way
 // (NO_PROJECT, binding.mjs).
 export function projectDirRefusal(dir) {
-  try { if (statSync(dir).isDirectory()) return null; } catch {}
+  try {
+    if (statSync(dir).isDirectory()) return null;
+  } catch {}
   return `no such project directory: ${JSON.stringify(String(dir))} — nothing is written`;
 }
 
+// Where a printed command runs, named in prose (the story "User-facing text
+// says where to run and names no project path and no shell", rule 1): the
+// command carries no --project, so a run's own output names the directory,
+// quoted as the refusal above quotes it — a trailing comma or space shows.
+export function fromTerminalIn(dir) {
+  return `from a terminal in ${JSON.stringify(String(dir))}`;
+}
+
 // ─── Status line wiring (SessionStart-managed) ─────────────────────────
 //
 // The Claude Code statusLine slot is single and NOT plugin-declarable, so
@@ -714,7 +1093,8 @@ export function projectDirRefusal(dir) {
 // PREVIOUS session start, one restart behind every update. The launcher path
 // never changes, and it resolves the installed plugin at render time, so
 // `/plugin update` + `/reload-plugins` show up immediately. Dev checkouts and
-// --plugin-dir roots carry no version, so those stay wired directly.
+// --plugin-dir roots carry no version, so install wires those directly; a
+// session run from one keeps whatever launcher entry install wrote.
 //
 // Idempotent (writes only when the value changes); never clobbers a foreign
 // statusLine; bails on an unparseable settings file. Returns a status string,
@@ -731,7 +1111,9 @@ export function legacyStatusLineLauncherPath(projectDir) {
 }
 // Both launcher shapes — the new state/<harness>/ one and the legacy one —
 // in one place; the recognisers below and doctor read it.
-export const LAUNCHER_PATH_RE = new RegExp(`${LAYOUT.root.replace(".", "\\.")}/(${LAYOUT.state}/[^/]+/)?${LAYOUT.launcher.replace(".", "\\.")}$`);
+export const LAUNCHER_PATH_RE = new RegExp(
+  `${LAYOUT.root.replace(".", "\\.")}/(${LAYOUT.state}/[^/]+/)?${LAYOUT.launcher.replace(".", "\\.")}$`,
+);
 export function isLauncherPath(p) {
   return LAUNCHER_PATH_RE.test(String(p || "").replace(/\\/g, "/"));
 }
@@ -751,21 +1133,69 @@ export function statusLineScriptPath(cmd) {
   return m ? m[1].replace(/\\/g, "/") : null;
 }
 
+// Is `p` a launcher path of ours in this project: any harness's launcher in
+// its state directory, or the legacy one? A path test — nothing is read. The
+// ownership check below and the SessionStart refresh both ask it.
+function ourLauncherPath(p, projectDir) {
+  if (!p) return false;
+  const norm = (s) => String(s).replace(/\\/g, "/");
+  const q = norm(p);
+  const lp = layoutPaths(projectDir);
+  return (q.startsWith(norm(lp.state) + "/") && isLauncherPath(q)) || q === norm(lp.legacy.launcher);
+}
+
+// The provenance field of a registration directory's manifest, or null — the
+// install spec's contract 2 for a JSON directory: emitted by one function
+// (registrationManifest, the installer) and read by this one. The registration
+// analysis (surfaces.mjs) and statusLineIsOurWiring both call it; the key is
+// the surface's provenance_key.
+export function registrationProvenance(manifest, s) {
+  const prov = manifest && s && s.provenance_key ? manifest[s.provenance_key] : null;
+  return prov && typeof prov === "object" && typeof prov.pkg === "string" ? prov : null;
+}
+
+// Is `p` the npm registration's own payload script —
+// <registration dir>/<plugin_subdir>/scripts/statusline.mjs, whose directory's
+// manifest carries our provenance field? The host loads that registration in
+// place from its marketplace directory, so a session refreshed the entry to
+// that script and a package root then read it as someone else's (the story
+// "The SessionStart hook and install agree on the status line of an npm
+// registration loaded from its marketplace directory"). A string test first;
+// the manifest is read only when the path has the payload's shape. Every name
+// comes from the source manifest's registration surface, and the directory
+// from `p` itself — never a path built from the home.
+function isRegistrationPayloadScript(p, harness = sourceHarness()) {
+  const s = Object.values(harness?.surfaces || {}).find(
+    (x) => x && x.kind === "registration" && x.format === "host-plugin-registration" && x.plugin_subdir && x.manifest,
+  );
+  if (!s) return false;
+  const tail = `/${s.plugin_subdir}/scripts/statusline.mjs`;
+  if (!p.endsWith(tail)) return false;
+  try {
+    return Boolean(
+      registrationProvenance(JSON.parse(readFileSync(join(p.slice(0, -tail.length), s.manifest), "utf8")), s),
+    );
+  } catch {
+    return false;
+  }
+}
+
 // Strict test — "did WE write this?". Required wherever we would overwrite or
 // delete the entry: the loose shape above also matches a user's own
 // ~/.claude/scripts/statusline.mjs, and clobbering that would take their HUD.
 // Ours means one of: this project's launcher, the running plugin's own script
-// (dev checkouts included), or any versioned install under the plugin cache.
+// (dev checkouts included), any versioned install under the plugin cache, or
+// the npm registration's payload script — the one rung that reads a file, so
+// it runs last, after every cheaper test has failed.
 export function statusLineIsOurWiring(cmd, projectDir, home = homedir(), root = pluginRoot()) {
   const p = statusLineScriptPath(cmd);
   if (!p) return false;
   const norm = (s) => String(s).replace(/\\/g, "/");
   // Ours if it is any harness's launcher in this project's state, or the legacy launcher.
-  const lp = layoutPaths(projectDir);
-  if (p.startsWith(norm(lp.state) + "/") && isLauncherPath(p)) return true;
-  if (p === norm(lp.legacy.launcher)) return true;
+  if (ourLauncherPath(p, projectDir)) return true;
   if (p === norm(join(root, "scripts", "statusline.mjs"))) return true;
-  return isPluginCacheRoot(dirname(dirname(p)), home);
+  if (isPluginCacheRoot(dirname(dirname(p)), home)) return true;
+  return isRegistrationPayloadScript(p);
 }
 
 // The launcher template runs standalone, before it knows which plugin root to
@@ -805,7 +1235,9 @@ export function writeStatusLineLauncher(projectDir, root) {
     if (src === null) return null;
     const p = statusLineLauncherPath(projectDir);
     let cur = null;
-    try { cur = readFileSync(p, "utf8"); } catch {}
+    try {
+      cur = readFileSync(p, "utf8");
+    } catch {}
     if (cur !== src) {
       ensureStateDir(projectDir); // carries the nested .gitignore: this path is machine-specific
       mkdirSync(dirname(p), { recursive: true });
@@ -826,7 +1258,9 @@ export function desiredStatusLineCommand(projectDir, root = pluginRoot(), home =
   const launcher = isPluginCacheRoot(root, home);
   return {
     launcher,
-    command: launcher ? `node "${statusLineLauncherPath(projectDir)}"` : `node "${join(root, "scripts", "statusline.mjs")}"`,
+    command: launcher
+      ? `node "${statusLineLauncherPath(projectDir)}"`
+      : `node "${join(root, "scripts", "statusline.mjs")}"`,
   };
 }
 
@@ -867,16 +1301,29 @@ export function syncStatusLine(cfg, projectDir, home = homedir()) {
     // nothing into the project, since we are not wiring anything here.
     if (cur && !isOurs) return "foreign-present";
     if (!cur) return "needs-install";
-    // Refresh: the launcher when it is on disk, else the plugin's own script,
-    // so an entry always names a renderer that exists. A missing launcher is
-    // install's to create (stamped), never this path's.
+    // Install alone decides the entry's shape; this hook never demotes a
+    // launcher. An entry naming a launcher of ours that is on disk is left
+    // byte-identical, whatever root runs the hook: the host loads an npm
+    // registration in place from its marketplace directory, which is not the
+    // cache path the launcher was planned against, and re-pointing the entry
+    // at that root's script undid every install (the install spec, contract 0
+    // as amended 2026-10-10). Recognised by path and existsSync only — the
+    // launcher is not read here.
+    const named = statusLineScriptPath(curCmd);
+    const namesLauncher = ourLauncherPath(named, projectDir);
+    if (namesLauncher && existsSync(named)) return "unchanged";
+    // Refresh: a launcher of ours on disk when this root is a cache install or
+    // the entry named a launcher, else the plugin's own script, so an entry
+    // always names a renderer that exists. A missing launcher is install's to
+    // create (stamped), never this path's.
     const { launcher } = desiredStatusLineCommand(projectDir, root, home);
     // A launcher on disk at either path — the new one, or the legacy one an
     // earlier release wrote (the layout ADR) — is kept; moving it is install's.
-    const onDisk = [statusLineLauncherPath(projectDir), legacyStatusLineLauncherPath(projectDir)].find((f) => existsSync(f));
-    const desired = launcher && onDisk
-      ? `node "${onDisk}"`
-      : `node "${join(root, "scripts", "statusline.mjs")}"`;
+    const onDisk = [statusLineLauncherPath(projectDir), legacyStatusLineLauncherPath(projectDir)].find((f) =>
+      existsSync(f),
+    );
+    const desired =
+      (launcher || namesLauncher) && onDisk ? `node "${onDisk}"` : `node "${join(root, "scripts", "statusline.mjs")}"`;
     if (curCmd !== desired) {
       // Keep any sibling keys the platform supports on this object
       // (refreshInterval and friends) — we own the command, not the entry.
@@ -953,19 +1400,40 @@ export function findAgentsBlock(text) {
     const loose = new RegExp(AGENTS_BLOCK_OPEN_LOOSE_SRC).exec(text);
     if (!loose) return null;
     const line = text.slice(0, loose.index).split("\n").length;
-    return { present: true, v: Number(loose[1]), start: loose.index, end: null, unclosed: true, wrapped: true, line, count, block: null };
+    return {
+      present: true,
+      v: Number(loose[1]),
+      start: loose.index,
+      end: null,
+      unclosed: true,
+      wrapped: true,
+      line,
+      count,
+      block: null,
+    };
   }
   const closeAt = text.indexOf(AGENTS_BLOCK_CLOSE, m.index + m[0].length);
-  if (closeAt === -1) return { present: true, v: Number(m[1]), start: m.index, end: null, unclosed: true, count, block: null };
+  if (closeAt === -1)
+    return { present: true, v: Number(m[1]), start: m.index, end: null, unclosed: true, count, block: null };
   const end = closeAt + AGENTS_BLOCK_CLOSE.length;
-  return { present: true, v: Number(m[1]), start: m.index, end, unclosed: false, count, block: text.slice(m.index, end) };
+  return {
+    present: true,
+    v: Number(m[1]),
+    start: m.index,
+    end,
+    unclosed: false,
+    count,
+    block: text.slice(m.index, end),
+  };
 }
 
 // Whether `text` holds `line` as a line of its own, trimmed and exact — the
 // installer's match for the `@<file>` import, so `@./AGENTS.md` reads as
 // absent to install and doctor alike.
 export function importsLine(text, line) {
-  return String(text ?? "").split("\n").some((l) => l.trim() === line);
+  return String(text ?? "")
+    .split("\n")
+    .some((l) => l.trim() === line);
 }
 
 // Whether a harness sees the one agents block where it stands — the predicate
@@ -1025,14 +1493,24 @@ export function renderAgentsBlock(tmpl, roster = null) {
   const AGENT_LINE = /^- [^:]*?:\s+(?:run|consult) (?:the )?`projectstore:([a-z]+)`/;
   const flush = () => {
     if (!bullet) return;
-    const m = AGENT_LINE.exec(bullet.map((l) => l.trim()).join(" ").replace(/^- /, "- "));
+    const m = AGENT_LINE.exec(
+      bullet
+        .map((l) => l.trim())
+        .join(" ")
+        .replace(/^- /, "- "),
+    );
     if (!names || !m || names.has(m[1])) out.push(...bullet);
     bullet = null;
   };
   for (const l of lines) {
-    if (/^- /.test(l)) { flush(); bullet = [l]; }
-    else if (bullet && /^\s+\S/.test(l)) bullet.push(l);
-    else { flush(); out.push(l); }
+    if (/^- /.test(l)) {
+      flush();
+      bullet = [l];
+    } else if (bullet && /^\s+\S/.test(l)) bullet.push(l);
+    else {
+      flush();
+      out.push(l);
+    }
   }
   flush();
   return out.join("\n");
@@ -1056,7 +1534,9 @@ export function layoutRoster(cfg, root = pluginRoot()) {
   try {
     const r = loadLayout(cfg.layout, root).agents;
     return Array.isArray(r) && r.length ? r : null;
-  } catch { return null; }
+  } catch {
+    return null;
+  }
 }
 
 export function folderByKind(layout, kind) {
@@ -1065,14 +1545,33 @@ export function folderByKind(layout, kind) {
 
 // ─── Templates ─────────────────────────────────────────────────────────
 
-export function loadTemplate(lang, name) {
-  const p = join(pluginRoot(), "templates", lang, `${name}.md.tmpl`);
+// `root` is the plugin root to read from — the bin passes its own package's,
+// as it does for layouts, so a scaffold plans against the copy that runs.
+export function loadTemplate(lang, name, root = pluginRoot()) {
+  const p = join(root, "templates", lang, `${name}.md.tmpl`);
   if (!existsSync(p)) {
     throw new Error(`Template not found: templates/${lang}/${name}.md.tmpl`);
   }
   return readFileSync(p, "utf8");
 }
 
+// templates/<lang>/strings.json, parsed — or null when the language has none
+// or it does not parse. No English fallback, unlike the status line's own
+// reader: the folder names and descriptions are written into a vault's
+// READMEs, and an English description in a Russian vault would read as the
+// vault's own prose forever after (the skeleton's Purpose column takes it
+// from there). A missing string is the caller's refusal to name.
+export function loadStrings(lang, root = pluginRoot()) {
+  const p = join(root, "templates", String(lang), "strings.json");
+  if (!existsSync(p)) return null;
+  try {
+    const s = JSON.parse(readFileSync(p, "utf8"));
+    return s && typeof s === "object" && !Array.isArray(s) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
 // {{x}} substitutes raw; {{x_json}} substitutes JSON.stringify(String(x)) — a
 // valid YAML double-quoted scalar. Frontmatter lines in templates use the
 // _json form so titles containing `"` or `:` cannot corrupt the YAML.
@@ -1100,7 +1599,9 @@ export function renderTemplate(template, vars) {
 // language is the canonical form used when WRITING. Matching always accepts
 // every registered form of every language — a ru-headed file in an en-bound
 // vault must still lint. This is deliberately separate from
-// templates/<lang>/strings.json, which is a render-only map for the statusline.
+// templates/<lang>/strings.json, a render-only map: the status line's strings
+// and the folder names and descriptions scaffold writes into READMEs, which
+// nothing ever matches against.
 
 let _headingsCache = null;
 
@@ -1110,7 +1611,7 @@ export function loadHeadingsRegistry() {
   try {
     _headingsCache = JSON.parse(readFileSync(p, "utf8"));
   } catch (e) {
-    throw new Error(`heading registry missing or unreadable (${p}): ${e.message}`);
+    throw new Error(`heading registry missing or unreadable (${p}): ${e.message}`, { cause: e });
   }
   return _headingsCache;
 }
@@ -1192,10 +1693,10 @@ export function footerDateRe() {
 // so the loss had no detector at all. Anchored, both halves behave as
 // documented: reconcile reports the index unusable and doctor warns.
 export function indexHeaderRe() {
-  const cols = ["file", "title", "status", "date"].map((c) =>
-    allForms("index_columns", c).map(escapeRe).join("|"));
+  const cols = ["file", "title", "status", "date"].map((c) => allForms("index_columns", c).map(escapeRe).join("|"));
   return new RegExp(
-    `^\\|\\s*(?:${cols[0]})\\s*\\|\\s*(?:${cols[1]})\\s*\\|\\s*(?:${cols[2]})\\s*\\|\\s*(?:${cols[3]})\\s*\\|\\s*$`);
+    `^\\|\\s*(?:${cols[0]})\\s*\\|\\s*(?:${cols[1]})\\s*\\|\\s*(?:${cols[2]})\\s*\\|\\s*(?:${cols[3]})\\s*\\|\\s*$`,
+  );
 }
 
 // ─── Frontmatter list fields (code_refs / specs / stories / adr) ───────
@@ -1261,10 +1762,39 @@ export function isLegacyStory(fm, since) {
 // Cyrillic → Latin so ru titles produce portable ASCII filenames; every other
 // Unicode letter/digit survives via \p{L}\p{N}. Never returns an empty slug.
 const CYRILLIC = {
-  а: "a", б: "b", в: "v", г: "g", д: "d", е: "e", ё: "e", ж: "zh", з: "z",
-  и: "i", й: "y", к: "k", л: "l", м: "m", н: "n", о: "o", п: "p", р: "r",
-  с: "s", т: "t", у: "u", ф: "f", х: "h", ц: "ts", ч: "ch", ш: "sh",
-  щ: "shch", ъ: "", ы: "y", ь: "", э: "e", ю: "yu", я: "ya",
+  а: "a",
+  б: "b",
+  в: "v",
+  г: "g",
+  д: "d",
+  е: "e",
+  ё: "e",
+  ж: "zh",
+  з: "z",
+  и: "i",
+  й: "y",
+  к: "k",
+  л: "l",
+  м: "m",
+  н: "n",
+  о: "o",
+  п: "p",
+  р: "r",
+  с: "s",
+  т: "t",
+  у: "u",
+  ф: "f",
+  х: "h",
+  ц: "ts",
+  ч: "ch",
+  ш: "sh",
+  щ: "shch",
+  ъ: "",
+  ы: "y",
+  ь: "",
+  э: "e",
+  ю: "yu",
+  я: "ya",
 };
 
 export function slugify(s) {
@@ -1460,7 +1990,11 @@ export function listStoryFiles(storiesDir) {
   for (const entry of readdirSync(storiesDir).sort()) {
     const full = join(storiesDir, entry);
     let st;
-    try { st = statSync(full); } catch { continue; }
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
     if (st.isFile() && entry.endsWith(".md")) {
       out.push({ abs: full, rel: entry, slug: entry.replace(/\.md$/, "") });
       continue;
@@ -1486,14 +2020,22 @@ export function listStoryFiles(storiesDir) {
 export function listEpicStories(epicDir) {
   const out = [];
   // epics/ holds loose files too (README, notes) — only folders are epics.
-  try { if (!statSync(epicDir).isDirectory()) return out; } catch { return out; }
+  try {
+    if (!statSync(epicDir).isDirectory()) return out;
+  } catch {
+    return out;
+  }
   for (const s of listStoryFiles(join(epicDir, "stories"))) {
     out.push({ abs: s.abs, rel: `stories/${s.rel}`, slug: s.slug });
   }
   for (const entry of readdirSync(epicDir).sort()) {
     if (!entry.startsWith("story-") || !entry.endsWith(".md")) continue;
     const full = join(epicDir, entry);
-    try { if (!statSync(full).isFile()) continue; } catch { continue; }
+    try {
+      if (!statSync(full).isFile()) continue;
+    } catch {
+      continue;
+    }
     out.push({ abs: full, rel: entry, slug: entry.replace(/\.md$/, "") });
   }
   return out;
@@ -1574,14 +2116,16 @@ export function buildNodeIndex(cfg, layout) {
   const nodes = [];
   const push = (abs, rel, type, { prefix = null, story = false } = {}) => {
     let md;
-    try { md = readFileSync(abs, "utf8"); } catch { return; }
+    try {
+      md = readFileSync(abs, "utf8");
+    } catch {
+      return;
+    }
     const fm = parseFrontmatter(md).data;
     const name = basename(rel);
     // A folder-shape story is identified by its folder name, like doctor's
     // storyStemOf; every other node by its filename stem.
-    const stem = name === "README.md"
-      ? basename(dirname(rel))
-      : name.replace(/\.md$/i, "");
+    const stem = name === "README.md" ? basename(dirname(rel)) : name.replace(/\.md$/i, "");
     const idField = fm.id ?? fm.slug; // research/concept/runbook/meeting templates carry slug:, not id:
     nodes.push({
       path: rel,
@@ -1706,10 +2250,13 @@ export function resolveLinkTarget(rawTarget, linkType, ctx) {
   const tiers = [
     () => (index.byIdentity.get(key) || []).filter(eligible),
     () => (index.byStem.get(key) || []).filter(eligible),
-    () => index.nodes.filter((n) =>
-      eligible(n)
-      && isLegacyNumberedId(target, n.story ? { story: true } : { prefix: n.prefix })
-      && n.stem.toLowerCase().startsWith(`${key}-`)),
+    () =>
+      index.nodes.filter(
+        (n) =>
+          eligible(n) &&
+          isLegacyNumberedId(target, n.story ? { story: true } : { prefix: n.prefix }) &&
+          n.stem.toLowerCase().startsWith(`${key}-`),
+      ),
   ];
   for (const tier of tiers) {
     const hits = [...new Set(tier())];
@@ -1734,11 +2281,11 @@ export function resolveLinkTarget(rawTarget, linkType, ctx) {
 // split is what makes the bounds unit-testable without a slow filesystem, and
 // what stops a second convenience being paid for out of the same budget later.
 
-export const PURPOSE_CELL = 160;   // contract 1
-export const TITLE_CELL = 80;      // contract 1
-export const PATH_CELL = 200;      // contracts 1, 19 — measured: longest path here is 123
-export const INFLIGHT_CAP = 5;     // contracts 1, 19
-export const ERROR_CELL = 500;     // contract 3
+export const PURPOSE_CELL = 160; // contract 1
+export const TITLE_CELL = 80; // contract 1
+export const PATH_CELL = 200; // contracts 1, 19 — measured: longest path here is 123
+export const INFLIGHT_CAP = 5; // contracts 1, 19
+export const ERROR_CELL = 500; // contract 3
 
 // A truncation marks itself, and the mark counts toward the budget (contract 1).
 export function truncEnd(s, max) {
@@ -2077,8 +2624,10 @@ export function renderVaultSkeleton(facts) {
       if (more > 0) L.push(`- …and ${more} more; see \`${commandForm("status")}\``);
       if (cont.artifact) {
         L.push("");
-        L.push(`**In flight**: ${pathCell(cont.artifact)} was the newest structured write before` +
-          " compaction. If we were drafting it, continue from there.");
+        L.push(
+          `**In flight**: ${pathCell(cont.artifact)} was the newest structured write before` +
+            " compaction. If we were drafting it, continue from there.",
+        );
       }
       L.push("");
     }
@@ -2142,7 +2691,11 @@ export function ensureSessionsDir(vault) {
   // vault lives. The .gitignore inside <vault>/.projectstore/ is merged by
   // line (2026-09-06: a vault that is also a project shares the directory
   // with the project layout, whose committed harness/ a "*" would hide).
-  ensureGitignoreLines(join(vault, LAYOUT.root, ".gitignore"), [`${LAYOUT.vaultSessions}/`], "projectstore — runtime data, do not commit");
+  ensureGitignoreLines(
+    join(vault, LAYOUT.root, ".gitignore"),
+    [`${LAYOUT.vaultSessions}/`],
+    "projectstore — runtime data, do not commit",
+  );
   return dir;
 }
 
@@ -2154,7 +2707,9 @@ export function writeSession(vault, sessionId, projectRoot) {
   const path = sessionFilePath(vault, sessionId);
   let existing = null;
   if (existsSync(path)) {
-    try { existing = JSON.parse(readFileSync(path, "utf8")); } catch {}
+    try {
+      existing = JSON.parse(readFileSync(path, "utf8"));
+    } catch {}
   }
   const data = {
     id: sessionId,
@@ -2189,10 +2744,18 @@ export function readActiveSessions(vault, currentSessionId, maxAgeMinutes = 30)
     if (!name.endsWith(".json")) continue;
     const path = join(dir, name);
     let stat;
-    try { stat = statSync(path); } catch { continue; }
+    try {
+      stat = statSync(path);
+    } catch {
+      continue;
+    }
     if (stat.mtimeMs < cutoff) continue;
     let data;
-    try { data = JSON.parse(readFileSync(path, "utf8")); } catch { continue; }
+    try {
+      data = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      continue;
+    }
     if (data.id === currentSessionId) continue;
     out.push({ ...data, last_active: stat.mtime });
   }
@@ -2236,7 +2799,6 @@ export function cleanupStaleSessions(vault, maxAgeHours = 24, currentSessionId =
 // behind by v0.3 – v0.5 (file-based per-project session id). Safe to call
 // on every session start; no-op if the file is absent. Kept until v0.7.
 
-
 // ─── Session activity log ──────────────────────────────────────────────
 //
 // Each session file may carry a `recent_activity` array, populated by
@@ -2348,7 +2910,7 @@ export function isInsideVault(filePath, vaultPath) {
 // so per-session ids/titles never reach the user's git history.
 
 // The WRITER's view: <project>/.projectstore/state/sessions. Readers fall back
-// to the legacy .claude/.projectstore/state through 0.29 (readSessionState).
+// to the legacy .claude/.projectstore/state through 0.30 (readSessionState).
 export function stateDir(projectDir) {
   return layoutPaths(projectDir).sessions;
 }
@@ -2365,7 +2927,11 @@ export function sessionStatePath(projectDir, sessionId) {
 export function ensureRuntimeDir(projectDir) {
   const p = layoutPaths(projectDir);
   mkdirSync(p.root, { recursive: true });
-  ensureGitignoreLines(p.gitignore, [...LAYOUT.gitignore], "projectstore — the binding and the state are machine-local; harness/ is committed");
+  ensureGitignoreLines(
+    p.gitignore,
+    [...LAYOUT.gitignore],
+    "projectstore — the binding and the state are machine-local; harness/ is committed",
+  );
   return p.root;
 }
 
@@ -2373,16 +2939,32 @@ export function ensureRuntimeDir(projectDir) {
 // harness inside; its own ignore file so nothing in here can reach git,
 // whichever writer gets there first.
 export function ensureStateDir(projectDir) {
-  ensureRuntimeDir(projectDir);
+  ensureStateRoot(projectDir);
   const p = layoutPaths(projectDir);
   mkdirSync(p.sessions, { recursive: true });
-  if (!existsSync(p.stateGitignore)) writeFileSync(p.stateGitignore, `# ${RUNTIME_GITIGNORE_HEADER}, do not commit\n*\n`, "utf8");
   return p.sessions;
 }
 
+// state/ and its .gitignore, header included, without sessions/: what the
+// welcome marker's writer needs in a project that is not bound, where no
+// session state may appear. The header is how a project uninstall
+// recognises the marker as ours (install spec contract 13, as amended by the
+// shell-fetch story).
+export function ensureStateRoot(projectDir) {
+  ensureRuntimeDir(projectDir);
+  const p = layoutPaths(projectDir);
+  mkdirSync(p.state, { recursive: true });
+  if (!existsSync(p.stateGitignore))
+    writeFileSync(p.stateGitignore, `# ${RUNTIME_GITIGNORE_HEADER}, do not commit\n*\n`, "utf8");
+  return p.state;
+}
+
 export function readSessionState(projectDir, sessionId) {
   try {
-    const p = pickExisting(sessionStatePath(projectDir, sessionId), join(legacyStateDir(projectDir), `${sessionId}.json`));
+    const p = pickExisting(
+      sessionStatePath(projectDir, sessionId),
+      join(legacyStateDir(projectDir), `${sessionId}.json`),
+    );
     return JSON.parse(readFileSync(p, "utf8"));
   } catch {
     return null;
@@ -2401,13 +2983,137 @@ export function writeSessionState(projectDir, sessionId, patch) {
   // readSessionState answers null, so the next write keeps only its own patch
   // and the rest of the pointer is gone for good. The rename also hides the
   // empty instant after the truncate. The
-  // default sweep stays on: this writer runs only on vault-file tool calls, so
+  // default sweep stays on: this writer runs only on vault-file tool calls,
+  // story-close refreshes and once at SessionStart, so
   // it can afford the readdir that reaps orphan temps here (the status line's
   // breadcrumb, written beside it, opts out because it renders every refresh).
   writeFileAtomic(sessionStatePath(projectDir, sessionId), JSON.stringify(next, null, 2));
   return next;
 }
 
+// ─── The pointer's epic and story (ADR-006 decision 1, amended 2026-10-12) ──
+// What touching one vault file says about this session's work: the epic it
+// sits under and, for a story, the story's key, title and status as the file
+// says them NOW — callers run after a write, never before it. The merge in
+// writeSessionState cannot delete a key, so a story field with no value is
+// written as null (every reader treats it as absent): a touch of another
+// epic clears the previous epic's story, and an unreadable story names no
+// stale title. Null when the file is not under an epic.
+export function pointerPatchFor(vaultPath, filePath, cur, read = (p) => readFileSync(p, "utf8")) {
+  const m = filePath.slice(vaultPath.length + 1).match(/^epics\/([^/]+)\/(.+)$/);
+  if (!m) return null;
+  const [, epicId, inEpic] = m;
+  const patch = { active_epic: epicId };
+  try {
+    const { data } = parseFrontmatter(read(join(vaultPath, "epics", epicId, "epic.md")));
+    if (data.title) patch.epic_title = String(data.title);
+  } catch {}
+  const key = storyKeyOf(inEpic);
+  if (key) {
+    let data = null;
+    try {
+      data = parseFrontmatter(read(filePath)).data;
+    } catch {}
+    patch.active_story = key;
+    patch.story_title = data && data.title ? String(data.title) : null;
+    patch.story_status = data && data.status ? String(data.status) : null;
+  } else if (!cur || cur.active_epic !== epicId) {
+    Object.assign(patch, { active_story: null, story_title: null, story_status: null });
+  }
+  return patch;
+}
+
+// The file a pointer's story key names, by the three shapes the board lists
+// (storyKeyOf); null when none exists. existsSync is a stat, which does not
+// download an evicted iCloud file.
+export function storyFileFor(vaultPath, epicId, key) {
+  if (!epicId || !key || /[/\\\0]/.test(epicId) || /[/\\\0]/.test(key)) return null;
+  const epicDir = join(vaultPath, "epics", epicId);
+  const candidates = [join(epicDir, "stories", `${key}.md`), join(epicDir, "stories", key, "README.md")];
+  if (key.startsWith("story-")) candidates.push(join(epicDir, `${key}.md`));
+  return candidates.find((p) => existsSync(p)) || null;
+}
+
+// `projectstore session refresh <path>` — ADR-006 decision 1's "projectstore
+// commands on approved epic/story writes". The close ceremony copies the
+// story through Bash, which no hook sees, so the story command calls this
+// after the copy: this session's pointer is patched from the file as it is
+// now, as a touch of that file would be. The session is the host's
+// (session_id_env); a harness that names none gets nothing written and no
+// failure, so a close there is never broken by it. `path` is vault-relative
+// or absolute inside the vault.
+export function refreshSessionPointer(projectDir, cfg, path, { env = process.env } = {}) {
+  const vault = cfg.vault_path;
+  const abs = isAbsolute(path) ? resolve(path) : join(vault, path);
+  const rel = abs.startsWith(`${vault}/`) ? abs.slice(vault.length + 1) : null;
+  if (!rel) return { refusal: { code: "NOT_IN_VAULT", message: `${path} is not inside the bound vault (${vault})` } };
+  if (!existsSync(abs)) return { refusal: { code: "NOT_FOUND", message: `${rel} does not exist in the vault` } };
+  const sessionId = hostSessionId(env);
+  const cur = sessionId ? readSessionState(projectDir, sessionId) : null;
+  const patch = pointerPatchFor(vault, abs, cur);
+  if (!patch || !patch.active_story)
+    return { refusal: { code: "NOT_A_STORY", message: `${rel} is not a story file under an epic` } };
+  if (!sessionId) return { session: null, refreshed: false, reason: "no-session", path: rel };
+  const next = writeSessionState(projectDir, sessionId, patch);
+  return {
+    session: sessionId,
+    refreshed: true,
+    path: rel,
+    pointer: {
+      active_epic: next.active_epic ?? null,
+      active_story: next.active_story ?? null,
+      story_title: next.story_title ?? null,
+      story_status: next.story_status ?? null,
+    },
+  };
+}
+
+// SessionStart's refresh of this session's story fields from the story file:
+// a pointer written before a close (0.29.3 patched it before the write, and
+// never on the close ceremony's copy), or a story closed in another session
+// or by hand since. The read races a budget, as resolveOpenStory's does — an
+// evicted file blocks — and a lost race writes nothing. A story the epic no
+// longer has clears the fields; a vault or epic folder that is not there (an
+// unmounted drive) proves nothing and writes nothing.
+// "refreshed" | "unchanged" | "unknown".
+export async function refreshStoryPointer(projectDir, vaultPath, sessionId, opts = {}) {
+  const cur = readSessionState(projectDir, sessionId);
+  if (!cur || !cur.active_epic || !cur.active_story) return "unchanged";
+  const file = storyFileFor(vaultPath, cur.active_epic, cur.active_story);
+  if (!file && !existsSync(join(vaultPath, "epics", cur.active_epic, "epic.md"))) return "unknown";
+  let title = null;
+  let status = null;
+  if (file) {
+    const readFile = opts.readFile || ((p) => readFileAsync(p, "utf8"));
+    let timer = null;
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), opts.budgetMs ?? 200);
+    });
+    let text;
+    try {
+      text = await Promise.race([
+        Promise.resolve()
+          .then(() => readFile(file))
+          .then(String, () => null),
+        deadline,
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    if (text === null) return "unknown";
+    const { data } = parseFrontmatter(text);
+    title = data.title ? String(data.title) : null;
+    status = data.status ? String(data.status) : null;
+  }
+  const patch = file
+    ? { story_title: title, story_status: status }
+    : { active_story: null, story_title: null, story_status: null };
+  const same = Object.entries(patch).every(([k, v]) => (cur[k] ?? null) === v);
+  if (same) return "unchanged";
+  writeSessionState(projectDir, sessionId, patch);
+  return "refreshed";
+}
+
 export function cleanupStaleSessionState(projectDir, maxAgeHours = 24) {
   const dir = stateDir(projectDir);
   if (!existsSync(dir)) return 0;
@@ -2455,23 +3161,36 @@ export function cleanupStaleSessionState(projectDir, maxAgeHours = 24) {
 // consumer. Lifted out of diff-refs.mjs so the hook, doctor and diff-refs
 // cannot drift apart (contract 1).
 export const SOURCE_IGNORE = [
-  /(^|\/)package-lock\.json$/, /(^|\/)yarn\.lock$/, /(^|\/)pnpm-lock\.yaml$/,
-  /(^|\/)Cargo\.lock$/, /(^|\/)node_modules\//, /(^|\/)dist\//, /(^|\/)build\//,
-  /(^|\/)\.claude\//, /\.min\.(js|css)$/,
+  /(^|\/)package-lock\.json$/,
+  /(^|\/)yarn\.lock$/,
+  /(^|\/)pnpm-lock\.yaml$/,
+  /(^|\/)Cargo\.lock$/,
+  /(^|\/)node_modules\//,
+  /(^|\/)dist\//,
+  /(^|\/)build\//,
+  /(^|\/)\.claude\//,
+  /\.min\.(js|css)$/,
 ];
 
 // The entry-rule counter ignores strictly more than the base set, and the
 // difference is deliberate rather than an oversight of one or the other.
-// /projectstore:bind writes these three itself, in a session that by
+// /projectstore:bind writes these itself, in a session that by
 // construction has no story open — counting them makes the plugin nag about its
 // own setup. They must NOT join SOURCE_IGNORE: an edit to AGENTS.md is a real
 // code reference (the PS-AGENTS epic already lists it), and folding these into
 // the shared set would silently drop it from every proposed code_refs.
 // Root-anchored, unlike the patterns above: a monorepo's nested AGENTS.md is
-// ordinary source and must still count.
+// ordinary source and must still count. The fourth is the binding's own
+// ignore file, which `bind` and `init` write through ensureRuntimeDir: the
+// layout move added it and this list missed it, so a fresh `init` on a clean
+// project read as one uncommitted source file (measured 2026-10-08 on 0.29.2).
+// Built from LAYOUT.root, which the resolver alone spells (layout contract 0).
 export const ENTRY_IGNORE = [
   ...SOURCE_IGNORE,
-  /^AGENTS\.md$/, /^CLAUDE\.md$/, /^\.gitignore$/,
+  /^AGENTS\.md$/,
+  /^CLAUDE\.md$/,
+  /^\.gitignore$/,
+  new RegExp(`^${LAYOUT.root.replace(".", "\\.")}\\/\\.gitignore$`),
 ];
 
 export function isSourcePath(absPath, projectDir, vaultPath) {
@@ -2545,7 +3264,11 @@ export function listVaultStoryFiles(vaultPath) {
   const out = [];
   const epicsDir = join(vaultPath, "epics");
   let entries;
-  try { entries = readdirSync(epicsDir).sort(); } catch { return out; }
+  try {
+    entries = readdirSync(epicsDir).sort();
+  } catch {
+    return out;
+  }
   for (const e of entries) {
     for (const s of listEpicStories(join(epicsDir, e))) out.push(s.abs);
   }
@@ -2575,7 +3298,11 @@ export async function resolveOpenStory(vaultPath, opts = {}) {
   const scan = (async () => {
     for (const f of files) {
       let text;
-      try { text = await readFile(f); } catch { continue; }
+      try {
+        text = await readFile(f);
+      } catch {
+        continue;
+      }
       // String(): the injected reader is a seam, and a caller that forgets an
       // encoding hands back a Buffer. Coercing here keeps that a non-event.
       if (openStoryFrom([parseFrontmatter(String(text)).data])) return true;
@@ -2598,7 +3325,11 @@ export function lastVaultActivityMs(vaultPath) {
   let newest = 0;
   const walk = (dir) => {
     let entries;
-    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
     for (const e of entries) {
       if (e.name.startsWith(".")) continue; // .projectstore/, .obsidian/, .git/
       const p = join(dir, e.name);
@@ -2657,8 +3388,7 @@ export function writeOpenStoryCache(projectDir, sessionId, value) {
 
 export function firedCount(projectDir, sessionId) {
   try {
-    return readdirSync(markerDir(projectDir, sessionId))
-      .filter((n) => /^fired-\d+$/.test(n)).length;
+    return readdirSync(markerDir(projectDir, sessionId)).filter((n) => /^fired-\d+$/.test(n)).length;
   } catch {
     return 0;
   }
@@ -2773,7 +3503,11 @@ export function electEmitter(projectDir, sessionId) {
   if (n === 0) target = "fired-1";
   else if (n === 1 && isArmed(projectDir, sessionId)) target = "fired-2";
   if (!target) return false;
-  try { mkdirSync(dir, { recursive: true }); } catch { return false; }
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return false;
+  }
 
   // In the ARMED state the arming is the scarce thing, so consuming it must be
   // the atomic act. Creating fired-2 first and unlinking `armed` afterwards
@@ -2783,7 +3517,11 @@ export function electEmitter(projectDir, sessionId) {
   // both win). unlink() succeeding is what elects here, exactly as create()
   // does in the unarmed state.
   if (target === "fired-2") {
-    try { unlinkSync(join(dir, "armed")); } catch { return false; }
+    try {
+      unlinkSync(join(dir, "armed"));
+    } catch {
+      return false;
+    }
   }
   try {
     writeFileSync(join(dir, target), "", { flag: "wx" });
@@ -2821,17 +3559,16 @@ export function electEmitter(projectDir, sessionId) {
 // did; without the second, parallel subagents (which share one session id)
 // vote on a name none of them can accept.
 
-export const ANCHOR_SETTLE = 5;   // tally at which a key becomes offerable
-export const ANCHOR_MARGIN = 10;  // lead a challenger needs to take over
-const ANCHOR_NAME_CELL = 48;      // a name is typed by hand; keep it typeable
+export const ANCHOR_SETTLE = 5; // tally at which a key becomes offerable
+export const ANCHOR_MARGIN = 10; // lead a challenger needs to take over
+const ANCHOR_NAME_CELL = 48; // a name is typed by hand; keep it typeable
 
 // Which cluster an artifact belongs to: its epic, or the document itself.
 // Folders come from the layout, never from a hard-coded set — a vault that
 // renames `research/` must not silently stop being nameable.
 export function anchorKeyOf(rel, layout) {
   if (typeof rel !== "string" || !rel) return null;
-  const folders = (layout && Array.isArray(layout.folders) ? layout.folders : [])
-    .filter((f) => f && f.path);
+  const folders = (layout && Array.isArray(layout.folders) ? layout.folders : []).filter((f) => f && f.path);
   const epic = folders.find((f) => f.kind === "epic");
   if (epic && rel.startsWith(epic.path + "/")) {
     // String ops, never an interpolated RegExp: a layout path is user data, and
@@ -2845,7 +3582,7 @@ export function anchorKeyOf(rel, layout) {
     if (f.kind === "epic") continue;
     if (rel.startsWith(f.path + "/") && rel.endsWith(".md")) {
       const base = rel.slice(f.path.length + 1);
-      if (base.includes("/")) continue;      // only files directly in the folder
+      if (base.includes("/")) continue; // only files directly in the folder
       // A folder's generated index is not a document: `adr/README.md` would
       // otherwise settle an anchor and compose the name "readme".
       if (f.readme && base.toLowerCase() === "readme.md") continue;
@@ -2883,9 +3620,7 @@ export function foldAnchor(state, hit) {
   let offer = null;
   const top = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
   if (top && top[1] >= ANCHOR_SETTLE) {
-    const take = incumbent === null
-      ? true
-      : top[0] !== incumbent && top[1] >= (counts[incumbent] || 0) + ANCHOR_MARGIN;
+    const take = incumbent === null ? true : top[0] !== incumbent && top[1] >= (counts[incumbent] || 0) + ANCHOR_MARGIN;
     if (take && top[0] !== incumbent) {
       incumbent = top[0];
       // A moved anchor is not automatically a new NAME. Two documents can share
@@ -2960,7 +3695,10 @@ export function anchorDir(projectDir, sessionId) {
 }
 
 function anchorSlot(key, leaf) {
-  const h = createHash("sha1").update(leaf ? `${key}\u0000${leaf}` : key).digest("hex").slice(0, 16);
+  const h = createHash("sha1")
+    .update(leaf ? `${key}\u0000${leaf}` : key)
+    .digest("hex")
+    .slice(0, 16);
   return leaf ? `l${h}` : `k${h}`;
 }
 
@@ -3007,14 +3745,17 @@ export function readAnchorState(projectDir, sessionId) {
     try {
       raw = readFileSync(join(dir, f), "utf8");
       n = statSync(join(dir, slot)).size;
-    } catch { continue; }
+    } catch {
+      continue;
+    }
     if (!raw || !n) continue;
     if (slot.startsWith("k")) {
       st.counts[raw] = n;
     } else {
       const nl = raw.indexOf("\n");
       if (nl < 0) continue;
-      const key = raw.slice(0, nl), leaf = raw.slice(nl + 1);
+      const key = raw.slice(0, nl),
+        leaf = raw.slice(nl + 1);
       st.leaves[key] = { ...(st.leaves[key] || {}), [leaf]: n };
     }
   }
@@ -3074,7 +3815,11 @@ export function liveSessionNames(selfSessionId, dir = null) {
   const root = dir || join(claudeHome(), "sessions");
   const out = [];
   let files;
-  try { files = readdirSync(root); } catch { return out; }
+  try {
+    files = readdirSync(root);
+  } catch {
+    return out;
+  }
   for (const f of files) {
     if (!f.endsWith(".json")) continue;
     try {
@@ -3093,7 +3838,11 @@ export function liveSessionNames(selfSessionId, dir = null) {
 export function ownSessionName(selfSessionId, dir = null) {
   const root = dir || join(claudeHome(), "sessions");
   let files;
-  try { files = readdirSync(root); } catch { return null; }
+  try {
+    files = readdirSync(root);
+  } catch {
+    return null;
+  }
   for (const f of files) {
     if (!f.endsWith(".json")) continue;
     try {
@@ -3111,7 +3860,7 @@ export function sessionNameOffer(name, { peers = [], current = null, declined =
   // Never talk over a name the person chose. `declined` carries names we have
   // seen the session wear that we did not compose.
   if (current && current !== name && declined.includes(current)) return null;
-  if (current === name) return null;                       // already wearing it
+  if (current === name) return null; // already wearing it
   const taken = new Set(peers.map((p) => p && p.name).filter(Boolean));
   if (!taken.has(name)) return { name, qualified: false };
   // Taken. Qualify rather than skip: the anchor is still the honest answer, and
@@ -3138,21 +3887,6 @@ export function sessionNameOfferText(offer, { env = process.env } = {}) {
 
 // ─── Frontmatter parsing (minimal) ─────────────────────────────────────
 
-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) };
-}
+// Moved to stages.mjs (Node-free) so the band module parses frontmatter by
+// the same rule; re-exported here for every existing caller.
+export { parseFrontmatter };