projectstore-claude 0.29.0 → 0.29.2

package/node_modules/projectstore/scripts/harness.mjs

@@ -217,6 +217,8 @@ function ranked(env, dir) {
 // process.env to impersonate a harness needs the next call to look again.
 export function resetDetection() {
   _detected = null;
+  _speaking = null;
+  _bundling = undefined;
 }
 
 // Which harnesses this PROJECT uses — by directory (install spec, contract
@@ -247,6 +249,93 @@ export function activeHarness(env = process.env, dir = MANIFEST_DIR) {
   return loadHarness(detectHarnessId(env, dir), dir) || sourceHarness(dir);
 }
 
+// ─── Who a message is for (generation spec, contract 18) ───────────────
+//
+// The core prints for ONE harness at a time, and a command it names must be
+// one that harness can run: `/projectstore:doctor` in Claude Code,
+// `$projectstore-doctor` in Codex, where commands arrive as rendered skills.
+// The form is manifest data; these functions only fill it in.
+
+// How a harness calls one of our commands (kind "commands") or roles (kind
+// "agents"): the surface's own `invocation` template, or — for a surface the
+// generator renders as skills — its `rendered_name` filled into the skills'
+// template. `*` names the family ("/projectstore:*"). Filled by split/join, so
+// a `$` in a template is never read as a replacement pattern.
+export function invocation(manifest, name, { kind = "commands", args = "" } = {}) {
+  // No manifest (a partial tarball): the bare name, never a throw in a hook.
+  const surfaces = manifest?.surfaces || {};
+  const s = surfaces[kind] || {};
+  let template = s.invocation || null;
+  if (!template && s.rendered_as === "skill" && s.rendered_name && surfaces.skills?.invocation) {
+    template = surfaces.skills.invocation.split("<name>").join(s.rendered_name);
+  }
+  const form = template ? template.split("<name>").join(name) : name;
+  return args ? `${form} ${args}` : form;
+}
+
+// The UI words a manifest declares (ui_vocabulary), as patterns. A word glued
+// to a longer name or to a path is not the word: `/plugin-x` is not `/plugin`,
+// and neither is the one in `.claude-plugin/plugin.json`; a full stop after it
+// still ends a sentence. The generator's leak check and the vocabulary lint
+// read these same patterns.
+export function uiWordPatterns(manifest) {
+  const esc = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return (manifest?.ui_vocabulary || []).map((word) => ({ word, re: new RegExp(`(?<![\\w.-])${esc(word)}(?![\\w-]|\\.\\w)`, "g") }));
+}
+
+// The harness whose distribution shell bundles this core, by the shell's
+// package name: a shell installs the core at <shell>/node_modules/projectstore,
+// and its package.json names it as a manifest's install.shell. A hook, a
+// rendered skill's command and an npx run inside that tree all belong to that
+// harness by construction — nothing to export, nothing a model can forget.
+// A source checkout or a host's own cache of the core answers null.
+let _bundling;
+export function bundlingShellHarnessId({ core = REPO_ROOT, dir = MANIFEST_DIR } = {}) {
+  const memo = core === REPO_ROOT && dir === MANIFEST_DIR;
+  if (memo && _bundling !== undefined) return _bundling;
+  let id = null;
+  try {
+    const real = realOr(core);
+    const parent = dirname(real);
+    if (parent.split(sep).pop() === "node_modules") {
+      const name = JSON.parse(readFileSync(join(dirname(parent), "package.json"), "utf8")).name;
+      id = [...loadHarnesses(dir).values()].find((m) => m.install?.shell && m.install.shell === name)?.id ?? null;
+    }
+  } catch { id = null; }
+  if (memo) _bundling = id;
+  return id;
+}
+
+// The harness a message is FOR: forced (PROJECTSTORE_HARNESS); else the one
+// that identifies itself — a strong signal or its session marker; else the
+// shell that bundles this core; else the shell the environment names
+// (PROJECTSTORE_SHELL, which only the shells set); else the source harness.
+// `--harness <id>` names an install target and plays no part in this.
+let _speaking = null;
+export function speakingHarnessId(env = process.env, dir = MANIFEST_DIR) {
+  const memo = env === process.env && dir === MANIFEST_DIR;
+  if (memo && _speaking) return _speaking;
+  const id = speaker(env, dir);
+  if (memo) _speaking = id;
+  return id;
+}
+
+function speaker(env, dir) {
+  const identified = identifiedHarnessId(env, dir);
+  if (identified) return identified;
+  const bundled = bundlingShellHarnessId({ dir });
+  if (bundled) return bundled;
+  if (env.PROJECTSTORE_SHELL) {
+    const named = [...loadHarnesses(dir).values()].find((m) => m.install?.shell === env.PROJECTSTORE_SHELL);
+    if (named) return named.id;
+  }
+  return sourceHarness(dir)?.id ?? null;
+}
+
+export function speakingHarness(env = process.env, dir = MANIFEST_DIR) {
+  return loadHarness(speakingHarnessId(env, dir), dir) || sourceHarness(dir);
+}
+
 // ─── Runtime names and paths ───────────────────────────────────────────
 
 // The three branded names the active harness uses, so a caller can say which

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -69,7 +69,7 @@ import { loadHarness, loadHarnesses, harnessIds, sourceHarness, detectHarnesses,
 import { FOREIGN_TEXT, GRAMMAR_VERSION } from "./provenance.mjs";
 import { analyseBlock, analyseJsonEntry, analyseStampedFile, analyseRegistration, analysePortableRegistration, analyseLayout, isOurFile, readText } from "./surfaces.mjs";
 import { payloadFiles, renderPortableCatalog } from "./portable-registration.mjs";
-import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpPrecedence, importsLine, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder } from "./lib.mjs";
+import { pluginRoot, writeFileAtomic, writeExclusiveMetadata, ensureStateDir, ensureRuntimeDir, removeAgentsBlock, replaceAgentsBlock, readConfigAt, isPluginCacheRoot, isEphemeralRoot, statusLineIsOurWiring, claudeHome, packageDigest, writeOwnTree, removeOwnTree, cmpPrecedence, importsLine, whichOnPath as whichOnPathFromLib, moveStateDir, mergeEntryLog, movePath, removeInside, statusLineScriptPath, layoutPaths, stagePortableMarketplace, finishPortableMarketplace, rollbackPortableMarketplace, removeTreeUnder, projectDirRefusal } from "./lib.mjs";
 
 import { GENERATOR } from "./surfaces.mjs";
 export { GENERATOR };
@@ -373,6 +373,15 @@ function planPortableRegistration(ctx, key, s) {
   if (!a.market) steps.push(hostStep(a, s, "marketplace_add", fill, "register the stable local marketplace source globally"));
   if (!a.installed || a.installedVersion !== a.desiredVersion || mustWrite) steps.push(hostStep(a, s, "install", fill, `materialise and enable ${a.id} from the staged source`));
   steps.push(hostStep(a, s, "list", fill, "read back host-reported installation and effective enablement"));
+  // Asked first, before anything changes: the command the registration's own
+  // verification needs. A host too old to answer it stops the run with nothing
+  // staged, journaled or registered (issue #28: a codex without `plugin list
+  // --json` failed only at verification, after it had added the marketplace
+  // and the plugin; the install spec's 2026-09-29 amendment, as amended
+  // 2026-10-05).
+  if (steps.some((x) => x.kind === "portable-write" || (x.kind === "host" && x.name !== "list"))) {
+    steps.unshift({ ...hostStep(a, s, "list", fill, "check that the host can report what it installs, before anything changes"), name: "preflight" });
+  }
   return [{ ...base, action: a.state === "absent" ? "create" : "update", steps, verify: { version: a.desiredVersion, digest }, reason: a.reason }];
 }
 
@@ -590,6 +599,16 @@ export function plan(projectDir, { harnesses = [], mode = "install", env = proce
     out.ok = false;
     return out;
   }
+  // A project that does not exist is refused before contract 8's detection
+  // could stand in for it ("no harness detected"), and before anything is
+  // written, staged, locked or spawned (contract 19).
+  const missing = projectDirRefusal(projectDir);
+  if (missing) {
+    out.harnesses = named;
+    out.refusals.push(missing);
+    out.ok = false;
+    return out;
+  }
   if (!ids.length) {
     out.refusals.push(harnessRefusal(projectDir));
     out.ok = false;
@@ -1118,7 +1137,7 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
     const r = spawn(bin || s.cli.bin, argv, { env: childEnv, cwd: p.projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
     const rows = !r.error && r.status === 0 ? portableListFacts(r.stdout) : null;
     out.steps.push({ kind: "portable-recovery-list", argv: [s.cli.bin, ...argv], status: r.status ?? null, ok: Boolean(rows) });
-    return { rows, stderr: String((r.stderr || "") + (r.error ? r.error.message : "")).trim() };
+    return { rows, stderr: r.error ? startFailure(r.error, { bin: s.cli.bin, resolved: bin, cwd: p.projectDir }) : String(r.stderr || "").trim() };
   };
   const observedPortable = (a) => ({
     dir_exists: existsSync(a.paths.dir),
@@ -1142,7 +1161,7 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
   };
   const verifyPrevious = (previous) => {
     const listed = readHostList();
-    if (!listed.rows) return { ok: false, why: listed.stderr || "Codex plugin list did not return JSON" };
+    if (!listed.rows) return { ok: false, unanswered: true, why: listed.stderr || "Codex plugin list did not return JSON" };
     const row = listed.rows.find((entry) => entry?.pluginId === i.entry) || null;
     if (!previous) {
       const a = analysePortableRegistration(p.projectDir, s, { root: p.root, home, harness, env: childEnv, ignoreJournal: true });
@@ -1171,10 +1190,21 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
     const ok = a.state === "current" && a.installedVersion === previous.version && a.enabled === previous.enabled && sourceOk && cacheOk && hostOk;
     return ok ? { ok: true } : { ok: false, why: `restored source/cache/enablement could not be proven (state=${a.state}, version=${a.installedVersion || "?"}, enabled=${String(a.enabled)})` };
   };
+  // A journal keeps its history (issue #28): the first failure's error and
+  // time stay as written; a later run that re-checks and still cannot prove
+  // the previous state adds its own reason and time beside them. The message
+  // says the error is a previous run's, where the journal is, and what lifts it.
   const requireRecovery = (journal, why) => {
-    writeFileAtomic(journalPath, JSON.stringify({ ...journal, phase: "recovery-required", error: why }, null, 2) + "\n", { sweep: false });
+    const now = new Date().toISOString();
+    const again = journal.phase === "recovery-required";
+    const record = again
+      ? { ...journal, rechecked_at: now, recheck_error: why }
+      : { ...journal, phase: "recovery-required", error: why, failed_at: now };
+    writeFileAtomic(journalPath, JSON.stringify(record, null, 2) + "\n", { sweep: false });
     releaseLock();
-    out.failed = { step: "recovery-required", status: null, stderr: `${why}; ${journalPath} was retained and blocks automatic mutation` };
+    out.failed = { step: "recovery-required", status: null, stderr: again
+      ? `a previous run (${journal.failed_at || "time not recorded"}) could not prove its restore: ${String(journal.error || "no error recorded").split("\n")[0]}. This run re-checked the previous state and could not prove it either: ${why}. ${journalPath} is kept: a later run lifts it once the previous state proves, or inspect the registration and remove the journal to start over`
+      : `${why}; ${journalPath} was retained and blocks automatic mutation until a later run proves the previous state` };
     return out;
   };
   if (portable) {
@@ -1219,22 +1249,43 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
         releaseLock(); out.failed = { step: "recovery", status: null, stderr: `${journalPath} does not describe this owned marketplace; inspect it before retrying` }; return out;
       }
       try {
-        if (journal.phase === "recovery-required") return requireRecovery(journal, journal.error || "a prior registration could not prove restoration");
-        if (journal.phase === "verified") finishPortableMarketplace(journal.target, journal.backup || null);
+        // A recovery the rollback could not prove is re-proved here, under the
+        // lock, with the rollback's own checks: it lifts when they hold, and is
+        // refused with its history kept when they do not (the install spec's
+        // 2026-09-29 amendment, as amended 2026-10-05).
+        let lifted = null;
+        if (journal.phase === "recovery-required") {
+          const proven = verifyPrevious(journal.previous || null);
+          // A host that cannot answer the proof's read-back is the case issue
+          // #28 met with a journal still in place: say what to do about it.
+          if (!proven.ok) return requireRecovery(journal, proven.unanswered
+            ? `${proven.why}\nThe re-check could not ask ${harness.display_name || s.cli.bin} (\`${[s.cli.bin, ...(s.cli.commands.list || [])].join(" ")}\`); if it is too old to answer, upgrade it, then run this again.`
+            : proven.why);
+          lifted = journal;
+        } else if (journal.phase === "verified") finishPortableMarketplace(journal.target, journal.backup || null);
         else if (journal.phase === "swapped" || (journal.phase === "prepare" && journal.backup && existsSync(journal.backup))) rollbackPortableMarketplace(journal.target, journal.backup || null);
         else if (journal.phase === "prepare" && !journal.previous && existsSync(journal.target)) {
           if (!ownedTargetMatches(journal.target, journal.next)) return requireRecovery(journal, `first-install recovery found an unrecognised target at ${journal.target}`);
           rollbackPortableMarketplace(journal.target, null);
         }
-        if (existsSync(journal.stage)) removeTreeUnder(journal.stage, i.home);
-        if (journal.phase !== "verified") {
+        if (existsSync(journal.stage) && resolve(journal.stage) !== resolve(i.path)) removeTreeUnder(journal.stage, i.home);
+        if (journal.phase !== "verified" && !lifted) {
           const restored = verifyPrevious(journal.previous || null);
           if (!restored.ok) return requireRecovery(journal, restored.why);
         }
         unlinkSync(journalPath);
-        out.steps.push({ kind: "portable-recover", phase: journal.phase || "unknown", ok: true });
+        out.steps.push({ kind: "portable-recover", phase: journal.phase || "unknown", ok: true, ...(lifted ? { lifted: lifted.error || null, failed_at: lifted.failed_at || null } : {}) });
+        // Only a lifted recovery prints a line of its own: the other phases'
+        // APPLY reads as it did. After the proof, whose host list has its line.
+        if (lifted && onStep) {
+          const st = { kind: "recover", path: journalPath, lifted: lifted.error || "" };
+          onStep(st, "start");
+          onStep(st, "end", { ok: true });
+        }
       } catch (e) {
-        releaseLock(); out.failed = { step: "recovery", status: null, stderr: e && e.message ? e.message : String(e) }; return out;
+        releaseLock();
+        out.failed = { step: "recovery", status: null, stderr: `${e && e.message ? e.message : String(e)}; ${journalPath} is kept: a later run retries it, or inspect the registration and remove the journal to start over` };
+        return out;
       }
     }
     const current = analysePortableRegistration(p.projectDir, s, { root: p.root, home, harness, env: childEnv, ignoreJournal: true });
@@ -1281,7 +1332,8 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
           const args = template.map((t) => t.replace(/\{(\w+)\}/g, (_, k) => fill[k] ?? `{${k}}`));
           const bin = whichOnPathFromLib(s.cli.bin, env);
           const r = spawn(bin || s.cli.bin, args, { env: childEnv, cwd: p.projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
-          out.steps.push({ kind: "portable-compensate", name, argv: [s.cli.bin, ...args], status: r.status ?? null, ok: !r.error && r.status === 0 });
+          const ok = !r.error && r.status === 0;
+          out.steps.push({ kind: "portable-compensate", name, argv: [s.cli.bin, ...args], status: r.status ?? null, ok, ...(ok ? {} : { stderr: r.error ? startFailure(r.error, { bin: s.cli.bin, resolved: bin, cwd: p.projectDir }) : String((r.stderr || "") + (r.stdout || "")).trim() }) });
         }
       }
       try {
@@ -1351,10 +1403,27 @@ function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
     } else if (st.kind === "host") {
       const bin = whichOnPathFromLib(st.bin, env);
       const r = spawn(bin || st.bin, st.argv, { env: childEnv, cwd: p.projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
-      const ok = !r.error && r.status === 0;
-      const said = String((r.stderr || "") + (ok ? "" : r.stdout || "") + (r.error ? r.error.message : "")).trim();
-      out.steps.push({ kind: "host", argv: [st.bin, ...st.argv], status: r.status ?? null, ok, ...(ok ? {} : { stderr: said }) });
-      if (!ok) return fail(st.name, r.status ?? null, said, [st.bin, ...st.argv]);
+      const ran = !r.error && r.status === 0;
+      // A preflight that ran must also answer in the shape verification reads:
+      // a host that exits 0 with text would pass on its status alone.
+      const unreadable = ran && portable && st.name === "preflight" && portableListFacts(r.stdout) === null;
+      const ok = ran && !unreadable;
+      // A command that did not start says why (contract 19); one that ran and
+      // failed says what it said. A preflight the host ran and could not
+      // answer adds what that means; one that never started does not, since
+      // upgrading the host would not help.
+      const said = r.error
+        ? startFailure(r.error, { bin: st.bin, resolved: bin, cwd: p.projectDir })
+        : unreadable
+          ? `${[st.bin, ...st.argv].join(" ")} answered, but not with the JSON the registration reads`
+          : String((r.stderr || "") + (ok ? "" : r.stdout || "")).trim();
+      const told = !ok && st.name === "preflight" && !r.error
+        ? `${said}\nThe registration needs \`${[st.bin, ...st.argv].join(" ")}\` to verify what it installs, so it changed nothing. Upgrade ${harness.display_name || st.bin}, then run this again.`
+        : said;
+      out.steps.push({ kind: "host", argv: [st.bin, ...st.argv], status: r.status ?? null, ok, ...(ok ? {} : { stderr: told }) });
+      // An unreadable answer exited 0; STOPPED names it by what it said, as
+      // the final list's own failure does, not by an "exited 0".
+      if (!ok) return fail(st.name, unreadable ? null : r.status ?? null, told, [st.bin, ...st.argv]);
       if (portable && st.name === "list") {
         hostList = portableListFact(r.stdout, i.entry);
         if (!hostList) return fail("list", null, `${st.bin} ${st.argv.join(" ")} did not report ${i.entry} in JSON output`, [st.bin, ...st.argv]);
@@ -1403,6 +1472,19 @@ function homeEnvName(harnessId) {
   try { return loadHarness(harnessId).runtime.home_env; } catch { return sourceHarness().runtime.home_env; }
 }
 
+// What Node cannot say: spawnSync reports a working directory that does not
+// exist and a binary not on PATH with the same `spawnSync <bin> ENOENT`
+// (measured 2026-10-05). The filesystem tells them apart, in this order (the
+// install spec, contract 19); any other error passes through as Node wrote it.
+function startFailure(err, { bin, resolved, cwd }) {
+  let dir = false;
+  try { dir = statSync(cwd).isDirectory(); } catch {}
+  if (!dir) return `${bin} could not start: the working directory ${JSON.stringify(String(cwd))} is not an existing directory`;
+  if (!resolved) return `${bin} could not start: it was not found on PATH`;
+  if (["ENOENT", "EACCES", "ENOEXEC"].includes(err?.code)) return `${bin} could not start: ${resolved} exists but could not be run (${err.code})`;
+  return String(err?.message || err);
+}
+
 // rmdirSync refuses a non-empty directory — that refusal IS the guarantee
 // (contract 13): we prune only a directory we emptied. The runtime dir's own
 // .gitignore does not count as content.
@@ -1499,6 +1581,7 @@ function stepLabel(p, st) {
   const r = (x) => tilde(rel(p.projectDir, x));
   switch (st.kind) {
     case "portable-write": return `stage ${r(st.path)}`;
+    case "recover": return `lift ${r(st.path)} — the previous state proved${st.lifted ? `; it held: ${String(st.lifted).split("\n")[0]}` : ""}`;
     case "write": return `write ${r(st.path)}`;
     case "unregister": return `edit ${r(st.path)} [${st.pointer}.${st.name}]`;
     case "ensure": return `ensure ${r(st.path)}/`;

package/node_modules/projectstore/scripts/kanban.mjs

@@ -21,7 +21,8 @@ import {
   listEpicStories,
   slugIdentity,
   displayNumberOf,
-  compareArtifactOrder, isMain
+  compareArtifactOrder, isMain,
+  commandForm,
 } from "./lib.mjs";
 
 function die(msg) {
@@ -117,7 +118,7 @@ function renderItem(story) {
 
 function main() {
   const cfg = readConfig();
-  if (!cfg) die("No projectstore config. Run /projectstore:bind first.");
+  if (!cfg) die(`No projectstore config. Run ${commandForm("bind")} first.`);
   const layout = loadLayout(cfg.layout);
   if (!layout.kanban) die(`Layout ${cfg.layout} does not declare a kanban config.`);
 

package/node_modules/projectstore/scripts/lib.mjs

@@ -28,6 +28,9 @@ import {
   isWriteTool as harnessIsWriteTool,
   toolPaths as harnessToolPaths,
   sourceHarness,
+  invocation,
+  speakingHarness,
+  packageCommand,
 } from "./harness.mjs";
 
 // ─── Paths ─────────────────────────────────────────────────────────────
@@ -47,10 +50,63 @@ export function configPath() {
   return harnessConfigPath(projectRoot(), process.env);
 }
 
+// ─── What a message names (generation spec, contract 18) ───────────────
+//
+// Every command, role and update path a message names, in the form the
+// harness it is printed for can use: `/projectstore:doctor` in Claude Code,
+// `$projectstore-doctor` in Codex. A name passed here must be a string literal
+// — tests/portability.test.mjs resolves each one on every harness, so a
+// command renamed on one harness fails where another would name it.
+export function commandForm(name, { args = "", env = process.env } = {}) {
+  return invocation(speakingHarness(env), name, { kind: "commands", args });
+}
+export function roleForm(name, { env = process.env } = {}) {
+  return invocation(speakingHarness(env), name, { kind: "agents" });
+}
+// The form the shared AGENTS.md block uses: the source harness's, until the
+// block is rendered per harness.
+export function sharedRoleForm(name) {
+  return invocation(sourceHarness(), name, { kind: "agents" });
+}
+// What a welcome says about updates, and the product name a message uses.
+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"' }) : "";
+  const fill = (t) => String(t).split("{upgrade}").join(upgrade);
+  return { line: fill(hint.line || ""), welcome: (hint.welcome || []).map(fill) };
+}
+// How an unbound worktree adopts its parent's binding: `bind --inherit` where
+// the harness's bind can inherit, else bind with the parent's vault named.
+// Whether the listening harness's bind can adopt a parent checkout's binding
+// whole (capabilities.bind_inherit). Where it cannot, a message says what its
+// bind does instead: the same vault, layout and language, not the binding.
+export function bindInherits({ env = process.env } = {}) {
+  return Boolean(speakingHarness(env)?.capabilities?.bind_inherit);
+}
+
+// Where it cannot inherit, the parent's vault, layout and language travel in
+// the form, so the new binding has those three of the parent's; every other
+// key is bind's default. The flags are the core verb's (`--layout`,
+// `--language`): a harness whose bind cannot inherit renders a bind skill that
+// hands them to the verb, and lint layer 2 holds that skill to naming each
+// one. A value that is not a plain name is left out, never pasted raw.
+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(" ");
+  return commandForm("bind", { args, env });
+}
+export function speakingDisplayName({ env = process.env } = {}) {
+  return speakingHarness(env)?.display_name || "another";
+}
+
 // 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 };
+export { layoutPaths, pickExisting, LAYOUT, RUNTIME_GITIGNORE_HEADER, hostSettingsPath, overlayId, speakingHarness };
 
 // 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
@@ -633,6 +689,18 @@ export function installChannel(root, { home = homedir(), harness = sourceHarness
   return own && marketplace === own.marketplace_name ? "registration" : "marketplace";
 }
 
+// A write verb works in a project that exists (the install spec, contract 19):
+// install, upgrade, uninstall and plan, and agents configure, refuse a path
+// that is not an existing directory before anything is written, staged or
+// spawned. The path is quoted, so a trailing comma, space or newline shows: a
+// `--project "$PWD",` pasted from a chat once created `ProjectStore,/` and
+// 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 {}
+  return `no such project directory: ${JSON.stringify(String(dir))} — nothing is written`;
+}
+
 // ─── Status line wiring (SessionStart-managed) ─────────────────────────
 //
 // The Claude Code statusLine slot is single and NOT plugin-declarable, so
@@ -1997,7 +2065,7 @@ export function renderVaultSkeleton(facts) {
     if (cont.status === "timeout") {
       L.push("## Where this session left off");
       L.push("");
-      L.push("- recent activity not resolved within budget — run `/projectstore:status`");
+      L.push(`- recent activity not resolved within budget — run \`${commandForm("status")}\``);
       L.push("");
     } else if (cont.paths && cont.paths.length > 0) {
       L.push("## Where this session left off");
@@ -2006,7 +2074,7 @@ export function renderVaultSkeleton(facts) {
       L.push("");
       for (const p of cont.paths.slice(0, INFLIGHT_CAP)) L.push(`- ${pathCell(p)}`);
       const more = (cont.total ?? cont.paths.length) - Math.min(cont.paths.length, INFLIGHT_CAP);
-      if (more > 0) L.push(`- …and ${more} more; see \`/projectstore:status\``);
+      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` +
@@ -2692,8 +2760,8 @@ export function entryReminderText(n) {
   return [
     `**projectstore**: this session has written to ${n} source files and no story`,
     "is in progress. If this is feature-sized work, open it in the vault before",
-    'going further — `/projectstore:story <EPIC> "<title>"`, or',
-    "`/projectstore:epic` if it needs a new one. If it is a one-off fix, carry",
+    `going further — \`${commandForm("story", { args: '<EPIC> "<title>"' })}\`, or`,
+    `\`${commandForm("epic")}\` if it needs a new one. If it is a one-off fix, carry`,
     "on — this fires once.",
   ].join("\n");
 }
@@ -3056,11 +3124,16 @@ export function sessionNameOffer(name, { peers = [], current = null, declined =
   return null;
 }
 
-export function sessionNameOfferText(offer) {
+// The command comes from the speaking harness's manifest (runtime.
+// session_rename); a harness without one is offered nothing.
+export function sessionNameOfferText(offer, { env = process.env } = {}) {
   if (!offer || !offer.name) return null;
+  const rename = speakingHarness(env)?.capabilities?.session_rename;
+  if (!rename) return null;
+  const run = rename.split("<name>").join(offer.name);
   return offer.qualified
-    ? `projectstore: this session looks like "${offer.name}" (a peer holds the unqualified name) — /rename ${offer.name}`
-    : `projectstore: this session looks like "${offer.name}" — /rename ${offer.name}`;
+    ? `projectstore: this session looks like "${offer.name}" (a peer holds the unqualified name) — ${run}`
+    : `projectstore: this session looks like "${offer.name}" — ${run}`;
 }
 
 // ─── Frontmatter parsing (minimal) ─────────────────────────────────────

package/node_modules/projectstore/scripts/mcp.mjs

@@ -65,7 +65,7 @@ function spawnBin(argv, { env, cwd, timeoutMs = DOCTOR_TIMEOUT_MS, onChild = nul
     child.on("close", (code) => { clearTimeout(timer); done({ code: code === null ? 2 : code, out, err }); });
   });
 }
-import { readConfigAt, isInsideVault } from "./lib.mjs";
+import { readConfigAt, isInsideVault, commandForm } from "./lib.mjs";
 
 // Two revisions, not four: 2025-03-26 has JSON-RPC batching (removed again in
 // 2025-06-18), which this server answers with -32600 — advertising that
@@ -247,7 +247,7 @@ export function createServer({ project, env = process.env, cwd = project, versio
     // answer the bind instruction inside the envelope.
     const rowRequiresBinding = (VERBS.find((v) => v.verb === t.verb) || {}).requiresBinding !== false;
     if (rowRequiresBinding && !cfgOf()) {
-      return { content: [{ type: "text", text: JSON.stringify(envelope(t.verb, project, false, { error: `${project} is not bound to a vault — run /projectstore:bind <vault> in a session, or projectstore bind <vault> --project ${project}` })) }], isError: true };
+      return { content: [{ type: "text", text: JSON.stringify(envelope(t.verb, project, false, { error: `${project} is not bound to a vault — run ${commandForm("bind", { args: "<vault>", env })} in a session, or projectstore bind <vault> --project ${project}` })) }], isError: true };
     }
     const { opts, positionals } = t.argv(a);
     const argv = [t.verb, ...opts, "--json", "--project", project, ...(positionals.length ? ["--", ...positionals] : [])];

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

@@ -179,7 +179,12 @@ export function analysePortableRegistration(projectDir, s, { root, payloadRoot:
   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` };
-  if (journal && !ignoreJournal) return { ...out, state: "stale", reason: "an interrupted registration has a recovery journal; the next confirmed run recovers it before applying this plan" };
+  // A journal the rollback could not prove names the run that left it, when,
+  // and its error, so the reader of the plan is not told recovery is assured
+  // (issue #28). Every other phase reads as before.
+  if (journal && !ignoreJournal) return { ...out, state: "stale", reason: journal.phase === "recovery-required"
+    ? `a previous run${journal.failed_at ? ` (${journal.failed_at})` : ""} could not prove its restore: ${String(journal.error || "no error recorded").split("\n")[0]}; this run re-proves the previous state before applying this plan, and refuses if it cannot (${paths.journal})`
+    : "an interrupted registration has a recovery journal; the next confirmed run recovers it before applying this plan" };
   if (existsSync(paths.dir) && !ownership) return { ...out, state: "foreign", refusal: `${paths.dir} exists without ${s.ownership_manifest}; a source this installer does not own holds the stable marketplace path` };
   if (market?.source && !samePath(market.source, paths.dir)) return { ...out, state: "foreign", refusal: `${paths.globalConfig} points marketplace ${s.marketplace_name} at ${market.source}, not ${paths.dir}` };
   if (nothing) return out;

package/node_modules/projectstore/scripts/query.mjs

@@ -49,6 +49,7 @@ import {
   listOf,
   sectionOf,
   isInsideVault,
+  commandForm,
 } from "./lib.mjs";
 import { walkVaultFiles } from "./doctor.mjs";
 import { buildGraph } from "./graph.mjs";
@@ -202,7 +203,7 @@ export function status(cfg, { project = null } = {}) {
 }
 
 export function renderStatus(r) {
-  if (!r.bound) return `Not bound${r.project ? ` — ${r.project}` : ""}. Run /projectstore:bind <vault> in a session.\n`;
+  if (!r.bound) return `Not bound${r.project ? ` — ${r.project}` : ""}. Run ${commandForm("bind", { args: "<vault>" })} in a session.\n`;
   const lines = [`Vault: ${r.vault_path}${r.vault_exists ? "" : "  (missing)"}`, `Layout: ${r.layout} · language: ${r.language} · auto_inject: ${r.auto_inject} · approval_mode: ${r.approval_mode} · spec_policy: ${r.spec_policy} · lifecycle_gates: ${r.lifecycle_gates}`];
   if (r.stories && r.stories.status !== "ok") lines.push(`Stories: not counted — ${r.stories.error}`);
   else if (r.stories) {

package/node_modules/projectstore/scripts/reconcile.mjs

@@ -40,7 +40,8 @@ import {
   slugIdentity,
   displayNumberOf,
   compareArtifactOrder,
-  writeFileAtomic, isMain
+  writeFileAtomic, isMain,
+  commandForm,
 } from "./lib.mjs";
 import { childEnv } from "./harness.mjs";
 
@@ -145,7 +146,7 @@ const SKIP = {
       : null,
   "graph.mjs": (g, onDisk) =>
     onDisk === null
-      ? "graph.md does not exist yet — create it explicitly (--only graph or /projectstore:graph)"
+      ? `graph.md does not exist yet — create it explicitly (--only graph or ${commandForm("graph")})`
       : null,
 };
 
@@ -306,7 +307,7 @@ export function runReconcile({ write = false, only = null, projectDir = null, en
   _projectDir = projectDir;
   _env = env;
   const cfg = projectDir ? readConfigAt(projectDir) : readConfig();
-  if (!cfg) { const e = new Error("No projectstore config. Run /projectstore:bind first."); e.code = "UNBOUND"; throw e; }
+  if (!cfg) { const e = new Error(`No projectstore config. Run ${commandForm("bind")} first.`); e.code = "UNBOUND"; throw e; }
   const layout = loadLayout(cfg.layout);
   const sel = resolveSelection(layout, only);
   if (sel.error) throw new Error(sel.error);

package/node_modules/projectstore/scripts/story-section.mjs

@@ -34,6 +34,7 @@ import {
   footerDateRe,
   nowIso,
   today,
+  commandForm,
 } from "./lib.mjs";
 
 function die(msg) {
@@ -116,7 +117,7 @@ function main() {
     die("usage: story-section.mjs <plan|close> <story-path> [--check <baseline-file>]");
   }
   const cfg = readConfig();
-  if (!cfg) die("No projectstore config. Run /projectstore:bind first.");
+  if (!cfg) die(`No projectstore config. Run ${commandForm("bind")} first.`);
   const lang = cfg.language || "en";
   const abs = resolve(storyPath);
   if (!existsSync(abs)) die(`story not found: ${abs}`);

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -51,6 +51,7 @@ import {
   layoutPaths,
   RUNTIME_GITIGNORE_HEADER,
   LAUNCHER_HEADER,
+  commandForm,
 } from "./lib.mjs";
 import { analysePortableRegistration, portableRegistrationPaths, portablePayloadRoot } from "./portable-registration.mjs";
 
@@ -109,7 +110,7 @@ export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir =
   const a = { files: found, own: files, withBlock, preferred, claude, importLine, PREFERRED, FALLBACK, entryKey: "projectstore:agents", version: null, desired: null, current: null, state: "ours-absent", reason: null, refusal: null };
 
   const unclosed = withBlock.find((e) => e.block.unclosed);
-  if (unclosed && unclosed.block.wrapped) return { ...a, state: "unparseable", refusal: `${unclosed.file}:${unclosed.block.line}: the projectstore:agents open marker does not close on its own line — the parser reads one line. Put \`-->\` back on the marker's line, then run /projectstore:agents register` };
+  if (unclosed && unclosed.block.wrapped) return { ...a, state: "unparseable", refusal: `${unclosed.file}:${unclosed.block.line}: the projectstore:agents open marker does not close on its own line — the parser reads one line. Put \`-->\` back on the marker's line, then run ${commandForm("agents", { args: "register" })}` };
   if (unclosed) return { ...a, state: "unparseable", refusal: `${unclosed.file}: the block opens and never closes — restore the closing marker or remove the block by hand` };
   const twice = withBlock.find((e) => e.block.count > 1);
   if (twice) return { ...a, state: "unparseable", refusal: `${twice.file} carries the block more than once — keep exactly one` };

package/node_modules/projectstore/scripts/term.mjs

@@ -141,7 +141,9 @@ export async function askLine(question, input, output) {
   return await new Promise((settle) => {
     let done = false;
     const finish = (answer) => { if (done) return; done = true; settle(answer); rl.close(); };
-    rl.on("close", () => finish(null));
+    // End of input echoes no newline: end the question's line, so whatever is
+    // printed next ("Nothing written.") starts on a line of its own.
+    rl.on("close", () => { if (!done) output.write("\n"); finish(null); });
     rl.question(question).then((a) => finish(a), () => finish(null));
   });
 }

package/node_modules/projectstore/scripts/touch-session.mjs

@@ -71,6 +71,8 @@ import {
   sessionNameOffer,
   sessionNameOfferText,
   toolPaths,
+  commandForm,
+  speakingHarness,
 } from "./lib.mjs";
 
 const NUDGE_INTERVAL_MS = 10 * 60 * 1000;
@@ -96,6 +98,9 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
   // this session id and cannot accept a name — must not vote on one.
   if (!isWriteTool(toolName || "")) return null;
   if (isSubagent) return null;
+  // A harness with no way to rename a session gets no offer, and so keeps no
+  // tally and logs nothing for one (generation spec, contract 18).
+  if (!speakingHarness()?.capabilities?.session_rename) return null;
 
   const rel = filePath.slice(cfg.vault_path.length + 1);
   let hit = null;
@@ -191,7 +196,7 @@ function updatePointerAndNudge(cfg, proj, sid, filePath, toolName) {
     const last = st && st.nudged_at ? Date.parse(st.nudged_at) : 0;
     if (Date.now() - last > NUDGE_INTERVAL_MS) {
       nudge =
-        "projectstore: vault file edited directly — if this bypassed a /projectstore:* command, run /projectstore:reconcile (or doctor) afterwards so the board/indexes stay in sync.";
+        `projectstore: vault file edited directly — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} (or doctor) afterwards so the board/indexes stay in sync.`;
       patch = { ...(patch || {}), nudged_at: new Date().toISOString() };
     }
   }