projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/kanban.mjs

@@ -24,17 +24,16 @@ import {
   compareArtifactOrder, isMain,
   commandForm,
 } from "./lib.mjs";
+// The status table lives in stages.mjs, Node-free, so the band above the
+// prompt counts stories exactly as the board files them.
+import { NOT_ACTIONABLE, statusToColumn } from "./stages.mjs";
+export { NOT_ACTIONABLE, statusToColumn };
 
 function die(msg) {
   process.stderr.write(`projectstore/kanban: ${msg}\n`);
   process.exit(1);
 }
 
-// Statuses that describe work which is not on the board by definition: it was
-// replaced, postponed, or set aside. Putting them in a column would claim the
-// work is queued, which is the opposite of what the status says.
-const NOT_ACTIONABLE = new Set(["superseded", "deferred", "parked"]);
-
 export function findStories(vault, epicsPath) {
   const root = join(vault, epicsPath);
   const stories = [];
@@ -92,21 +91,6 @@ export function findStories(vault, epicsPath) {
   return { stories, skipped };
 }
 
-export function statusToColumn(status) {
-  const m = {
-    planned: "Backlog",
-    todo: "ToDo",
-    "to-do": "ToDo",
-    "in-progress": "In Progress",
-    in_progress: "In Progress",
-    "in progress": "In Progress",
-    review: "Review",
-    done: "Done",
-    closed: "Done",
-  };
-  return m[status] || "Backlog";
-}
-
 function renderItem(story) {
   const tags = [`#${story.priority}`];
   if (story.status === "done") tags.push("#done");

package/node_modules/projectstore/scripts/lib.mjs

@@ -8,6 +8,7 @@ import { join, dirname, basename, resolve, relative, isAbsolute } from "node:pat
 import { fileURLToPath } from "node:url";
 import { hostname, homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { parseFrontmatter } from "./stages.mjs";
 import {
   projectRoot as harnessProjectRoot,
   pluginRoot as harnessPluginRoot,
@@ -20,6 +21,7 @@ import {
   overlayId,
   hostSettingsPath,
   layoutPaths,
+  cachePaths,
   pickExisting,
   LAYOUT,
   RUNTIME_GITIGNORE_HEADER,
@@ -31,6 +33,7 @@ import {
   invocation,
   speakingHarness,
   packageCommand,
+  whichOnPath,
 } from "./harness.mjs";
 
 // ─── Paths ─────────────────────────────────────────────────────────────
@@ -103,10 +106,35 @@ 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 } = {}) {
+  const lines = findings.map((f) => `${f.level} ${f.check} ${f.message}${f.file ? ` — ${f.file}` : ""}`);
+  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
@@ -354,16 +382,18 @@ function sweepOrphanTemps(dir) {
     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
@@ -474,18 +504,104 @@ 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 {}
-    }
-  }
-  return null;
+// 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; }
+}
+// …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";
+export function channelMark(cfg) {
+  const m = cfg && typeof cfg === "object" && !Array.isArray(cfg) ? cfg[CHANNEL_SWITCH_KEY] : null;
+  return m && typeof m === "object" && !Array.isArray(m) && typeof m.by === "string" && typeof m.at === "string" ? m : null;
+}
+
+// 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
@@ -615,10 +731,13 @@ export function rollbackPortableMarketplace(dir, backup = null) {
   return dir;
 }
 
-export function removeTreeUnder(dir, homeBase) {
+// `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) {
@@ -714,7 +833,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,
@@ -751,21 +871,65 @@ 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
@@ -867,14 +1031,26 @@ 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
+    const desired = (launcher || namesLauncher) && onDisk
       ? `node "${onDisk}"`
       : `node "${join(root, "scripts", "statusline.mjs")}"`;
     if (curCmd !== desired) {
@@ -1065,14 +1241,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 +1295,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;
 
@@ -2373,13 +2570,25 @@ 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`));
@@ -2462,16 +2671,21 @@ export const SOURCE_IGNORE = [
 
 // 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$/,
+  new RegExp(`^${LAYOUT.root.replace(".", "\\.")}\\/\\.gitignore$`),
 ];
 
 export function isSourcePath(absPath, projectDir, vaultPath) {
@@ -3138,21 +3352,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 };

package/node_modules/projectstore/scripts/portable-registration.mjs

@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { whichOnPath } from "./lib.mjs";
+import { whichOnPath, cmpPrecedence } from "./lib.mjs";
 
 const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
 const samePath = (a, b) => {
@@ -114,13 +114,35 @@ function pluginIds(sections) {
   return ids;
 }
 
+// The manifests a portable plugin root may carry, in the order they are read:
+// an Agent Plugins plugin.json at the root, then the legacy one Codex
+// validates — from 0.28.2 the shell's one manifest, since Codex picks a root
+// one first and loads no hooks from it (openai/codex#37027). The one place
+// either is spelled; the shell fetch's verification names them by kind.
+const PAYLOAD_MANIFESTS = { root: ["plugin.json"], legacy: [".codex-plugin", "plugin.json"] };
+export function payloadManifestPaths(root) {
+  return Object.values(PAYLOAD_MANIFESTS).map((parts) => join(root, ...parts));
+}
+export function payloadManifestPath(root, kind) {
+  return join(root, ...PAYLOAD_MANIFESTS[kind]);
+}
+// Is `root` a portable plugin root: does it carry either manifest?
+export function isPortablePluginRoot(root) {
+  return Boolean(root) && payloadManifestPaths(root).some((p) => existsSync(p));
+}
+// The first manifest that parses, or null — or, with `kind`, that one only.
+export function payloadManifest(root, { kind = null } = {}) {
+  for (const p of kind ? [payloadManifestPath(root, kind)] : payloadManifestPaths(root)) { const m = readJson(p); if (m) return m; }
+  return null;
+}
+
 function cacheEntries(paths, s) {
   const base = join(paths.cacheDir, s.marketplace_name, s.plugin_name);
   let names;
   try { names = readdirSync(base); } catch { return []; }
   return names.map((name) => {
     const path = join(base, name);
-    const manifest = readJson(join(path, "plugin.json")) || readJson(join(path, ".codex-plugin", "plugin.json"));
+    const manifest = payloadManifest(path);
     let at = 0; try { at = statSync(path).mtimeMs; } catch {}
     if (!manifest || typeof manifest.version !== "string") return null;
     let digest = null;
@@ -139,18 +161,33 @@ function cacheEntries(paths, s) {
 // the harness's directory (S2 of the 2026-10-03 review in "The Codex shell's
 // plugin root: .codex-plugin, the rendered surfaces, and the first Codex
 // install").
-export function portablePayloadRoot(s, { root, env = process.env } = {}) {
+//
+// `fetched` is the root a core run fetched for this harness (the shell fetch
+// of install and upgrade). The variable wins: a set one is used as is, a root
+// or not, and the fetched root is consulted only when it is unset — a shell
+// that names its own root is never second-guessed by a fetch.
+export function portablePayloadRoot(s, { root, env = process.env, fetched = null } = {}) {
   const named = env.PROJECTSTORE_DISTRIBUTION_ROOT || null;
   if (s.condition !== "distribution_root") return named || root;
-  if (!named) return null;
-  return existsSync(join(named, "plugin.json")) || existsSync(join(named, ".codex-plugin", "plugin.json")) ? named : null;
+  const candidate = named || fetched || null;
+  return candidate && isPortablePluginRoot(candidate) ? candidate : null;
 }
 
-export function analysePortableRegistration(projectDir, s, { root, payloadRoot: explicitPayloadRoot = null, home = homedir(), harness, env = process.env, ignoreJournal = false } = {}) {
+// Two modes. With a payload, every rung is decided, the published digest
+// against the recorded one included. With a `version` and no payload — plan's
+// dry run, both uninstalls, a run whose fetch was skipped, and the recheck of
+// an item planned that way — every rung that reads host facts is decided, and
+// the one comparison that needs the payload's bytes is not: its digest, so
+// `contentDiffers` and the same-version, different-content conflict. That is
+// the one rung a local-tarball install at an unchanged version trips, and it
+// is decided after a real fetch. `unavailable` for want of a payload fires
+// only when there is neither. Doctor passes neither and reads as before.
+export function analysePortableRegistration(projectDir, s, { root, payloadRoot: explicitPayloadRoot = null, version = null, fetched = null, home = homedir(), harness, env = process.env, ignoreJournal = false } = {}) {
   const paths = portableRegistrationPaths(s, { home, projectDir, harness, env });
-  const payloadRoot = explicitPayloadRoot || portablePayloadRoot(s, { root, env });
-  const desiredManifest = payloadRoot ? (readJson(join(payloadRoot, "plugin.json")) || readJson(join(payloadRoot, ".codex-plugin", "plugin.json"))) : null;
-  const desiredVersion = desiredManifest?.version || null;
+  const payloadRoot = explicitPayloadRoot || portablePayloadRoot(s, { root, env, fetched });
+  const desiredManifest = payloadRoot ? payloadManifest(payloadRoot) : null;
+  const versionOnly = !payloadRoot && typeof version === "string" && version !== "";
+  const desiredVersion = desiredManifest?.version || (versionOnly ? version : null);
   const id = `${s.plugin_name}@${s.marketplace_name}`;
   const bin = whichOnPath(s.cli.bin, env);
   const ownership = readJson(paths.ownership)?.[s.provenance_key] || null;
@@ -168,15 +205,21 @@ export function analysePortableRegistration(projectDir, s, { root, payloadRoot:
       const g = global.get(pluginTable(other)) || null, p = project.get(pluginTable(other)) || null;
       return { id: other, enabled: typeof p?.enabled === "boolean" ? p.enabled : g?.enabled === true };
     });
+  // A registration newer than what this run offers (the converge story's rule
+  // 6): set before the ladder, so a damaged one keeps it beside its real
+  // reason, and the cache is then read at the version the host registered —
+  // keyed on the desired version, a newer registration's integrity rungs
+  // checked the wrong cache directory.
+  const newer = typeof ownership?.version === "string" && typeof desiredVersion === "string" && cmpPrecedence(ownership.version, desiredVersion) > 0;
   const caches = cacheEntries(paths, s);
-  const installed = caches.find((e) => e.version === desiredVersion) || caches[0] || null;
-  const out = { id, paths, path: paths.dir, payloadRoot, desiredVersion, bin, ownership, journal, catalog, market, globalPlugin, projectPlugin, enabled, others, caches, installed, installPath: installed?.path || null, installedVersion: installed?.version || null, state: "absent", reason: null, produced: Boolean(desiredManifest), contentDiffers: null };
+  const installed = caches.find((e) => e.version === (newer ? ownership.version : desiredVersion)) || caches[0] || null;
+  const out = { id, paths, path: paths.dir, payloadRoot, desiredVersion, versionOnly, bin, ownership, journal, catalog, market, globalPlugin, projectPlugin, enabled, others, caches, installed, installPath: installed?.path || null, installedVersion: installed?.version || null, state: "absent", reason: null, produced: Boolean(desiredManifest), contentDiffers: null, newer };
   const enabledOther = others.find((other) => other.enabled);
   const nothing = !existsSync(paths.dir) && !market && !globalPlugin && !installed && !enabledOther;
-  if (!desiredManifest) return { ...out, state: "unavailable", reason: payloadRoot ? `${payloadRoot} is not a portable plugin root` : `nothing to register from this run: ${harness?.display_name || "this harness"}'s plugin is registered from its distribution shell, not from the core` };
+  if (!desiredManifest && !versionOnly) return { ...out, state: "unavailable", reason: payloadRoot ? `${payloadRoot} is not a portable plugin root` : `nothing to register from this run: ${harness?.display_name || "this harness"}'s plugin is registered from its distribution shell, not from the core` };
   if (!bin && nothing) return { ...out, state: "unavailable", reason: `\`${s.cli.bin}\` is not on PATH — the registration needs the host CLI` };
   let desiredDigest = null;
-  try { desiredDigest = payloadDigest(payloadRoot); } catch (e) { return { ...out, state: "unavailable", reason: e.message }; }
+  if (!versionOnly) { try { desiredDigest = payloadDigest(payloadRoot); } catch (e) { return { ...out, state: "unavailable", reason: e.message }; } }
   out.desiredDigest = desiredDigest;
   if (enabledOther) return { ...out, state: "conflict", refusal: `${enabledOther.id} is already enabled; two ProjectStore plugins would load the same skills and hooks. Disable or remove that registration explicitly, then retry` };
   // A journal the rollback could not prove names the run that left it, when,
@@ -191,13 +234,17 @@ export function analysePortableRegistration(projectDir, s, { root, payloadRoot:
   let sourceDigest = null;
   try { if (existsSync(paths.payload)) sourceDigest = payloadDigest(paths.payload); } catch {}
   out.sourceDigest = sourceDigest;
-  out.contentDiffers = Boolean(ownership?.digest) && (ownership.digest.sha256 !== desiredDigest.sha256 || ownership.digest.count !== desiredDigest.count);
+  out.contentDiffers = versionOnly ? null : Boolean(ownership?.digest) && (ownership.digest.sha256 !== desiredDigest.sha256 || ownership.digest.count !== desiredDigest.count);
   if (!ownership || !catalog) return { ...out, state: "stale", reason: "the owned marketplace source is incomplete" };
-  if (ownership.version === desiredVersion && out.contentDiffers) return { ...out, state: "conflict", refusal: `release ${desiredVersion} already owns this marketplace with a different payload digest` };
+  if (!versionOnly && ownership.version === desiredVersion && out.contentDiffers) return { ...out, state: "conflict", refusal: `release ${desiredVersion} already owns this marketplace with a different payload digest` };
   if (!sourceDigest || sourceDigest.sha256 !== ownership.digest?.sha256 || sourceDigest.count !== ownership.digest?.count) return { ...out, state: "stale", reason: "the stable source does not match its recorded digest" };
   if (!market) return { ...out, state: "stale", reason: "the host does not know the marketplace" };
   if (!installed || installed.version !== ownership.version) return { ...out, state: "stale", reason: "the host cache does not contain the registered payload version" };
   if (!installed.digest || installed.digest.sha256 !== ownership.digest?.sha256 || installed.digest.count !== ownership.digest?.count) return { ...out, state: "stale", reason: "the materialised host cache does not match the registered payload digest" };
+  // The newer rung, after the integrity rungs: a sound registration newer
+  // than this run is current and never staged over (rule 6). A damaged one
+  // stayed stale above, with its real reason; the planner skips it.
+  if (newer) return { ...out, state: "current", reason: `the registration is at ${ownership.version}, newer than this package (${desiredVersion}) — not downgraded` };
   if (ownership.version !== desiredVersion) return { ...out, state: "stale", reason: `installed ${ownership.version}; package offers ${desiredVersion}` };
   return { ...out, state: "current", reason: enabled ? null : "installed globally but disabled by effective configuration" };
 }