projectstore-claude 0.30.3 → 0.30.4

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.30.3",
+      "version": "0.30.4",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.30.3",
+  "version": "0.30.4",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/commands/agents.md

@@ -12,7 +12,10 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
 1. **Ask** via AskUserQuestion: "Register projectstore's agents in
    CLAUDE.md/AGENTS.md so every session routes to them (critic after
    authoring artifacts, planner before implementing, reviewer before commit)?
-   [Yes / No]". On No, stop.
+   [Yes / No]". On No, stop. When the block is already there marked newer
+   than this copy's template (doctor's info, or `status` showing
+   `ours-newer`), name both numbers in the question: registering writes this
+   copy's older block over the one marked vN.
 2. **Run the verb** and print its output verbatim:
    ```bash
    node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"
@@ -53,7 +56,7 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
 
 Run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" plan --json --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
 and report each item's `state` from `result.items[]` — the bin wraps the plan in its envelope (`ours-current`, `ours-stale` with its reason,
-`ours-absent`, or a refusal). Then:
+`ours-newer` — marked above this copy's template: install, upgrade and setup leave it, and a named run such as `register` writes this copy's over it — `ours-absent`, or a refusal). Then:
 
 - Block: present in which file, marker version vs the installed template, agent
   names vs the layout roster.

package/node_modules/projectstore/commands/doctor.md

@@ -42,6 +42,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
      the verb adds the import. For another harness the finding names its own
      `--harness`; relay that command. Never Edit or Write the block yourself —
      the verb is its only writer (install spec, contract 6).
+   - `agents-block` **info** that the block is "marked vN, newer than this
+     copy's vM" → **report only.** Install, upgrade and setup leave such a block as it is (install spec, contract 6 as amended
+     2026-10-14). Relay the finding and its command verbatim; run it only if
+     the user asks, because it writes this copy's older block over the one marked vN.
    - `statusline` issues → offer running `/projectstore:statusline on|off`,
      which installs or removes the entry and the launcher behind a preview
      (the SessionStart hook only refreshes an entry that already exists), and

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.3",
+  "version": "0.30.4",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/convergence.mjs

@@ -56,6 +56,7 @@ import {
   writeFileAtomic,
   envFlag,
   isEphemeralRoot,
+  COPY_UPDATE_STEPS,
 } from "./lib.mjs";
 import { loadHarness, loadHarnesses } from "./harness.mjs";
 import { analysePortableRegistration, portableRegistrationPaths } from "./portable-registration.mjs";
@@ -348,6 +349,34 @@ function runArgs({ harnesses = [], surfaces = null, register = true } = {}) {
   ].join(" ");
 }
 
+// The run a deferral sends to a terminal (the install spec, contract 6, as
+// amended 2026-10-14): the run's own verb for one harness, its --surface
+// selection, --global for a global removal, and setup's --channel npm when
+// that was the answer for the harness whose channel it is (setup's rule 13 —
+// a keep is never repeated). `plan` writes nothing, so it names install. One
+// builder for a deferred row's reason and setup's DONE, so the two agree.
+export function terminalRun({
+  verb = "install",
+  harness = null,
+  version = null,
+  surfaces = null,
+  globalRemoval = false,
+  channel = null,
+} = {}) {
+  const run = verb === "plan" ? "install" : verb;
+  const hostRegistration = Object.values(harness?.surfaces || {}).some(
+    (s) => s && typeof s === "object" && s.format === "host-plugin-registration",
+  );
+  const args = [
+    runArgs({ harnesses: harness ? [harness.id] : [], surfaces }),
+    globalRemoval ? "--global" : "",
+    run === "setup" && channel === "npm" && hostRegistration ? "--channel npm" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return coreCommand(run, { version, args });
+}
+
 // Stop when the registry's latest is at least a newer copy this project runs
 // — the newest such copy is named. A copy the latest does not reach, or no
 // answer, proceeds: the rows say which case it was (proceedCase). `read` is
@@ -577,9 +606,15 @@ export async function readKeepPlan(copy, { harness, projectDir, env, run, budget
     ...(Array.isArray(result.refusals) ? result.refusals : []),
     ...items.filter((i) => i.action === "refuse").map((i) => i.reason),
   ].filter((x) => typeof x === "string" && x);
+  // A deferred row's reason may carry its run on the lines after its prose
+  // (the install spec, contract 6, as amended 2026-10-14): only the prose is
+  // quoted inside our own sentence, never another copy's command.
   const deferred = items
     .filter((i) => i.deferred === true)
-    .map((i) => ({ surface: String(i.surface ?? ""), reason: typeof i.reason === "string" ? i.reason : null }));
+    .map((i) => ({
+      surface: String(i.surface ?? ""),
+      reason: typeof i.reason === "string" ? i.reason.split("\n")[0] : null,
+    }));
   return {
     argv,
     envelope: true,
@@ -603,6 +638,26 @@ export function ownUpgrade(copy, harness) {
   };
 }
 
+// Whether a kept copy is behind the running package (the install spec,
+// contract 21, rule 9, as amended 2026-10-14): semver precedence, rc
+// included. Never for a copy or a run with no semver version recorded — a
+// recorded "unknown" or a sha must not rank.
+export function copyBehind(copy, version) {
+  return isSemver(copy?.version) && isSemver(version) && cmpPrecedence(copy.version, version) < 0;
+}
+
+// What the keep says when its copy is behind: the project's surfaces are at
+// the running version until the copy updates, and the update in the copy's
+// channel. With a step, the copy's own upgrade runs after this run's agents
+// block, and a copy shipped before this rule plans the block back.
+export function behindAdvice(copy, version, { step = false } = {}) {
+  const head = `${copy.key} ${copy.version} is older than this package (${version})`;
+  const middle = step
+    ? `its own upgrade runs after this run's agents block and may plan the block back to its own version; until it updates, its doctor may call the block stale, and the next run may plan the block again`
+    : `until it updates, the agents block and anything else this run writes for the project are at ${version}, and its own doctor may call the block stale`;
+  return `${head}: ${middle}. Update it (${COPY_UPDATE_STEPS}).`;
+}
+
 // This checkout's npm registration enabled beside the kept copy: the keep
 // changes no registration, so it stays; its uninstall (rule 4) drops it.
 export function npmRowBeside({ harness, id, surface }) {

package/node_modules/projectstore/scripts/doctor.mjs

@@ -56,6 +56,8 @@ import {
   AGENTS_BLOCK_OPEN_SRC,
   AGENTS_BLOCK_CLOSE,
   agentsBlockVersion,
+  newerBlockWords,
+  isNewerBlock,
   findAgentsBlock,
   statusLineLauncherPath,
   LAUNCHER_HEADER,
@@ -369,7 +371,7 @@ export function checkStatusline(cfg, proj, home = homedir(), harness = speakingH
   // A harness without a status line hears nothing about one, whatever the
   // shared binding asks for (generation spec, contract 18).
   if (harness?.surfaces?.statusline?.supported === false) return out;
-  const local = hostSettingsPath(proj);
+  const local = hostSettingsPath(proj, process.env, harness);
   let cur = null;
   if (existsSync(local)) {
     try {
@@ -527,10 +529,10 @@ export function checkPendingUpgrade(proj, home = homedir(), root = pluginRoot(),
   // spec's 2026-10-03 amendment, case S1).
   let wired = null;
   try {
-    wired = JSON.parse(readFileSync(hostSettingsPath(proj), "utf8"))?.statusLine?.command || null;
+    wired = JSON.parse(readFileSync(hostSettingsPath(proj, process.env, harness), "utf8"))?.statusLine?.command || null;
   } catch {}
   if (!wired || !statusLineIsOurWiring(wired, proj, home, root)) return [];
-  const lp = pickExisting(statusLineLauncherPath(proj), legacyStatusLineLauncherPath(proj));
+  const lp = pickExisting(statusLineLauncherPath(proj, harness?.id), legacyStatusLineLauncherPath(proj));
   let text;
   try {
     text = readFileSync(lp, "utf8");
@@ -567,6 +569,7 @@ export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot()
   let unclosedFiles = 0;
   const perFile = {};
   const staleVersions = [];
+  const newerVersions = [];
   for (const name of ["CLAUDE.md", "AGENTS.md"]) {
     const p = join(proj, name);
     if (!existsSync(p)) continue;
@@ -610,7 +613,10 @@ export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot()
     }
     for (const m of text.matchAll(AGENT_BLOCK_MARKER)) {
       const v = parseInt(m[1], 10);
-      if (v !== AGENT_BLOCK_VERSION) staleVersions.push({ file: name, v });
+      // A marker above this copy's template is never stale: this copy writes
+      // no block down (the install spec, contract 6, as amended 2026-10-14).
+      if (isNewerBlock(v, AGENT_BLOCK_VERSION)) newerVersions.push({ file: name, v });
+      else if (v !== AGENT_BLOCK_VERSION) staleVersions.push({ file: name, v });
     }
   }
   if (blocks === 0) {
@@ -667,6 +673,22 @@ export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot()
     );
     out.push(refuses ? f : moveRepairs(f, fact));
   }
+  // A newer block: an info in the install report only — the startup line
+  // counts issues alone and offers none of this — and only for one
+  // well-formed block. Its way out is the running copy's own bin from a
+  // terminal, never the session's command, whose copy would write its own
+  // version. Not folded into the layout move, which leaves it as it is too.
+  if (blocks === 1 && !refuses)
+    for (const s of newerVersions)
+      out.push(
+        finding(
+          "install",
+          "info",
+          "agents-block",
+          `Agents block in ${s.file} is ${newerBlockWords(s.v, AGENT_BLOCK_VERSION)}: install, upgrade and setup leave it as it is. To write this copy's v${AGENT_BLOCK_VERSION} over it ${fromTerminalIn(proj)}:\nnode "${join(root, "bin", "projectstore.mjs")}" install --harness ${newerReader(proj, s.file, env)} --surface agents_block`,
+          s.file,
+        ),
+      );
   // Placement, held to the predicate install plans from (the install spec,
   // contract 6 as amended after the rc.3 tag): one well-formed block, seen by
   // every harness the project uses. rc.1 and rc.2 left a block in an
@@ -711,6 +733,19 @@ export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot()
   return out;
 }
 
+// The harness a newer block's way out names: the one this run identified,
+// else one the project uses whose files hold the block, else the source
+// harness — never Claude Code's by default in a Codex-only project, whose
+// install would create CLAUDE.md and overwrite nothing.
+function newerReader(proj, file, env) {
+  const identified = identifiedHarnessId(env);
+  if (identified) return identified;
+  const used = detectHarnesses(proj, { state: true }).map((d) => d.id);
+  return (
+    used.find((id) => (loadHarness(id)?.surfaces?.agents_block?.files || []).includes(file)) || sourceHarness()?.id
+  );
+}
+
 // While the layout move is pending, the findings the move itself repairs fold
 // into it instead of being counted beside it (the layout spec, contract 7 as
 // amended after the rc.3 tag; the upgrade story's O1): the stale block, which
@@ -1597,7 +1632,7 @@ function hostIgnoreLineMissing(proj, env) {
       .map((l) => l.trim());
   } catch {}
   if (lines.includes(".claude/") || lines.includes(".claude")) return [];
-  return [relative(proj, hostSettingsPath(proj, env))].filter((w) => !lines.includes(w));
+  return [relative(proj, hostSettingsPath(proj, env, sourceHarness()))].filter((w) => !lines.includes(w));
 }
 
 // Whether git ignores the host's machine-local settings file (the layout spec,
@@ -1611,7 +1646,7 @@ function hostIgnoreLineMissing(proj, env) {
 // line read. Full report only: a subprocess, like checkTrackedRuntime.
 export function checkHostIgnored(proj, { env = process.env } = {}) {
   if (!existsSync(join(proj, ".git"))) return [];
-  const file = relative(proj, hostSettingsPath(proj, env));
+  const file = relative(proj, hostSettingsPath(proj, env, sourceHarness()));
   const r = spawnSync("git", ["check-ignore", "-q", "--no-index", "--", file], { cwd: proj, env, timeout: 5000 });
   const missing = r.status === 0 ? [] : r.status === 1 ? [file] : hostIgnoreLineMissing(proj, env);
   if (!missing.length) return [];

package/node_modules/projectstore/scripts/harness.mjs

@@ -503,10 +503,12 @@ export function speakingHarness(env = process.env, dir = MANIFEST_DIR) {
 
 // ─── Runtime names and paths ───────────────────────────────────────────
 
-// The three branded names the active harness uses, so a caller can say which
-// variable it is talking about without spelling it.
-export function runtimeEnvNames(env = process.env) {
-  const r = activeHarness(env)?.runtime || {};
+// The three branded names a harness uses — the active one unless the caller
+// names it — so a caller can say which variable it is talking about without
+// spelling it. A surface rendered FOR a harness (the status-line launcher is
+// Claude Code's) names that harness, whichever process renders it.
+export function runtimeEnvNames(env = process.env, harness = activeHarness(env)) {
+  const r = harness?.runtime || {};
   return { projectDir: r.project_dir_env || null, pluginRoot: r.plugin_root_env || null, home: r.home_env || null };
 }
 
@@ -816,17 +818,20 @@ export function pickExisting(current, legacy) {
 
 // The per-project directory the HARNESS discovers (".claude" for the source
 // layout) — how a harness is detected in a project and where its own settings
-// live. Not where our config is: that is layoutPaths() (2026-09-06).
-export function projectConfigDir(env = process.env) {
-  return activeHarness(env)?.runtime?.harness_dir || ".claude";
+// live. Not where our config is: that is layoutPaths() (2026-09-06). A
+// caller reading ONE harness's settings names it: which harness launched the
+// process is not whose directory that is (the install spec, contract 6, as
+// amended 2026-10-14).
+export function projectConfigDir(env = process.env, harness = activeHarness(env)) {
+  return harness?.runtime?.harness_dir || ".claude";
 }
 
 // The host's own machine-local settings file in a project (the statusline
 // surface's file in the manifest — `.claude/settings.local.json` for Claude
 // Code). A harness surface, not ours: the one `.claude` path the core may
 // build, and it builds it from the manifest (2026-09-06).
-export function hostSettingsPath(projectDir, env = process.env) {
-  const h = activeHarness(env);
+export function hostSettingsPath(projectDir, env = process.env, harness = activeHarness(env)) {
+  const h = harness;
   const file = h?.surfaces?.statusline?.file || join(h?.runtime?.harness_dir || ".claude", "settings.local.json");
   return join(projectDir, file);
 }

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

@@ -193,6 +193,9 @@ import {
   npmRowBeside,
   pinFor,
   coreCommand,
+  terminalRun,
+  copyBehind,
+  behindAdvice,
   DEFAULT_REGISTRY,
   NOTICE_BUDGET_MS,
   READ_TIMEOUT_MS,
@@ -235,6 +238,7 @@ import {
   removeTreeUnder,
   projectDirRefusal,
   fromTerminalIn,
+  newerBlockWords,
   registrationProvenance,
   envFlag,
   selectCopy,
@@ -461,12 +465,27 @@ function planAgentsBlock(ctx, key, s) {
     return items;
   }
 
-  const entry = `projectstore:agents v${a.version}`;
   const current = a.current;
+  // A block marked above this copy's template is never rendered down (the
+  // install spec, contracts 4, 6 and 9, as amended 2026-10-14): a move, a
+  // migration or a dedupe carries its own bytes, stamped with its own marker.
+  const newer = a.newer || null;
+  const words = newer ? newerBlockWords(newer.block.v, a.version) : null;
+  const body = newer ? newer.block.block : a.desired;
+  const entry = `projectstore:agents v${newer ? newer.block.v : a.version}`;
   // Two files, one block each: resolve in favour of the preferred file —
   // register migrates, never duplicates (ADR-002 decision 3).
   for (const e of a.duplicates || [])
-    items.push(removal(e, { state: "ours-stale", reason: `duplicate of the block in ${current.file}` }));
+    items.push(
+      removal(e, {
+        state: "ours-stale",
+        reason:
+          newer === e
+            ? `carries v${e.block.v}, newer than this copy's v${a.version}; its text replaces the block in ${current.file}`
+            : `duplicate of the block in ${current.file}`,
+      }),
+    );
+  let newerInPlace = null;
 
   if (!current) {
     const target = preferred;
@@ -501,10 +520,43 @@ function planAgentsBlock(ctx, key, s) {
       entry,
       state: "ours-absent",
       action: preferred.present ? "add" : "create",
-      reason: ctx.readers && !current.own ? a.reason : `migrated from ${current.file}`,
+      reason:
+        ctx.readers && !current.own
+          ? a.reason
+          : `migrated from ${current.file}${newer ? ` with its own text (${words})` : ""}`,
       before: preferred.present ? preferred.text : null,
-      after: replaceAgentsBlock(preferred.present ? preferred.text : "", a.desired),
+      after: replaceAgentsBlock(preferred.present ? preferred.text : "", body),
+    });
+  } else if (newer && newer !== current) {
+    // The duplicate carries the higher marker: its text replaces the stayer's.
+    items.push({
+      surface: key,
+      kind: "shared",
+      path: current.path,
+      entry,
+      state: "ours-stale",
+      action: "replace-entry",
+      reason: `its text is replaced by ${newer.file}'s, which carries v${newer.block.v}, newer than this copy's v${a.version}`,
+      before: current.text,
+      after: replaceAgentsBlock(current.text, body),
     });
+  } else if (newer) {
+    // It stays as it is; a named run with nothing else to place overwrites it,
+    // decided once the imports are known (below).
+    newerInPlace = {
+      surface: key,
+      kind: "shared",
+      path: current.path,
+      entry,
+      state: "ours-newer",
+      action: "skip",
+      reason: `${words}: left as it is — ${
+        ctx.takesSurface === false
+          ? `to write this copy's v${a.version} over it: ${coreCommand("install", { args: `--harness ${ctx.harness.id} --surface ${key}` })}`
+          : `name --surface ${key} to write this copy's v${a.version} over it`
+      }`,
+    };
+    items.push(newerInPlace);
   } else if (current.block.v === a.version && current.block.block === a.desired) {
     items.push({
       surface: key,
@@ -590,6 +642,23 @@ function planAgentsBlock(ctx, key, s) {
         after,
       });
   }
+  // Naming the surface confirms the overwrite only when the run has nothing
+  // else to do for the block: it is the only block and every import it needs
+  // is in place. Doctor's placement remedies name the surface too, and they
+  // must never downgrade (contract 9 as amended 2026-10-14).
+  if (
+    newerInPlace &&
+    (ctx.surfaces || []).includes(key) &&
+    !(a.duplicates || []).length &&
+    !items.some((i) => i.surface === `${key}_import`)
+  )
+    Object.assign(newerInPlace, {
+      entry: `projectstore:agents v${a.version}`,
+      action: "replace-entry",
+      reason: `v${current.block.v} → v${a.version}: ${words}, and --surface ${key} names it`,
+      before: current.text,
+      after: replaceAgentsBlock(current.text, a.desired),
+    });
   return items;
 }
 
@@ -758,7 +827,7 @@ function planPortableRegistration(ctx, key, s) {
     // registration's removal decides them.
     if (registrationDeferred(env, harness)) {
       ctx.incomplete = true;
-      return [{ ...base, action: "skip", deferred: true, reason: deferralReason(harness, env) }];
+      return [{ ...base, action: "skip", deferred: true, ...deferredRun(ctx, deferralReason(harness, env)) }];
     }
     const steps = [];
     if (a.installed) steps.push(hostStep(a, s, "uninstall", fill, `explicit global removal forgets ${a.id}`));
@@ -827,7 +896,7 @@ function planPortableRegistration(ctx, key, s) {
         ...base,
         action: "skip",
         deferred: true,
-        reason: `${a.reason ? a.reason + "; " : ""}${deferralReason(harness, env)}`,
+        ...deferredRun(ctx, `${a.reason ? a.reason + "; " : ""}${deferralReason(harness, env)}`),
       },
     ];
   }
@@ -932,6 +1001,29 @@ function deferralReason(harness, env) {
   return `this runs inside a ${harness.display_name} session (${variable} is set), and the host's CLI would change the configuration that session runs on — run it from a terminal outside the session`;
 }
 
+// A deferral names its run (the install spec, contract 6, as amended
+// 2026-10-14): the prose as before, byte for byte, then where to run it and
+// the run's own command alone on its line — a way out, as the presentation
+// spec's contract 6 gives them, so `--json` carries it in `reason` and an
+// agent relaying the envelope relays the command.
+function deferredRun(ctx, prose) {
+  // The prose already says "outside the session"; the lead adds only where.
+  const where = fromTerminalIn(ctx.projectDir);
+  return advised(prose, [
+    {
+      lead: `${where.charAt(0).toUpperCase()}${where.slice(1)}:`,
+      command: terminalRun({
+        verb: ctx.verb,
+        harness: ctx.harness,
+        version: ctx.version,
+        surfaces: ctx.surfaces,
+        globalRemoval: ctx.globalRemoval,
+        channel: ctx.channel,
+      }),
+    },
+  ]);
+}
+
 function planRegistration(ctx, key, s) {
   const { projectDir, mode, root, home, env, harness } = ctx;
   const a = analyseRegistration(projectDir, s, { root, home, harness, env });
@@ -977,7 +1069,7 @@ function planRegistration(ctx, key, s) {
     }
     if (deferred) {
       ctx.incomplete = true;
-      return [{ ...base, action: "skip", reason: inSession }];
+      return [{ ...base, action: "skip", ...deferredRun(ctx, inSession) }];
     }
     const steps = [];
     if (a.installed)
@@ -1109,7 +1201,14 @@ function planRegistration(ctx, key, s) {
   }
   if (needsHost && deferred) {
     ctx.incomplete = true;
-    return [{ ...base, action: "skip", deferred: true, reason: `${a.reason ? a.reason + "; " : ""}${inSession}` }];
+    return [
+      {
+        ...base,
+        action: "skip",
+        deferred: true,
+        ...deferredRun(ctx, `${a.reason ? a.reason + "; " : ""}${inSession}`),
+      },
+    ];
   }
   // Our directory newer than this package and damaged (the converge story's
   // rule 6): never rewritten from the older package — this checkout and every
@@ -1392,6 +1491,11 @@ function keepTarget(projectDir, ids, { root, home, env }) {
 function keepEnv(env, { harness, projectDir, copyRoot, harnessHome }) {
   const out = childEnv(env);
   for (const m of loadHarnesses().values()) if (m.runtime?.plugin_root_env) delete out[m.runtime.plugin_root_env];
+  // An override this run inherited names THIS process's harness; in the copy
+  // it would turn the copy's own home and directory reads to another harness.
+  // The copy knows itself by the project-dir variable written below (the
+  // install spec, contract 21, as amended 2026-10-14).
+  delete out.PROJECTSTORE_HARNESS;
   const r = harness.runtime || {};
   if (r.plugin_root_env) out[r.plugin_root_env] = copyRoot;
   if (r.project_dir_env) out[r.project_dir_env] = projectDir;
@@ -1410,7 +1514,9 @@ const KEEP_SURFACE = "channel";
 // (keepArgv), its touches the writes the copy's own plan listed (`read`, made
 // by the prepare step) less the agents block's rows, which this run's one
 // block item writes before it (the story "One run plans the agents block
-// once…", rule 1). No write left: no item. The other rows it can be:
+// once…", rule 1). No write left: no item — unless the copy is behind the
+// running package, when a skip carries that line (contract 21, rule 9, as
+// amended 2026-10-14), as the update row does. The other rows it can be:
 // - a copy that cannot run the form (lib's capability read): skip, with the
 //   update in its channel — in the row's reason, since DONE never prints when
 //   nothing else writes, and as DONE's next line;
@@ -1547,11 +1653,29 @@ function planKeep(ctx, target, read) {
       }),
     ];
   }
-  if (!writes.length)
+  // A copy behind the running package says so (the install spec, contract
+  // 21, rule 9, as amended 2026-10-14): with no write left, a skip whose
+  // reason is that line — neither deferred nor incomplete, so a re-run stays
+  // zero-change; with writes, a line on the update row and in DONE.
+  const behind = copyBehind(copy, ctx.version);
+  if (!writes.length) {
+    if (behind) {
+      const line = behindAdvice(copy, ctx.version);
+      return [item({ action: "skip", ...advised(line, besides) }, [{ lead: line }])];
+    }
     return beside ? [item({ action: "skip", ...advised(`${named} has nothing to change here`, besides) })] : [];
+  }
+  const note = behind ? [{ lead: behindAdvice(copy, ctx.version, { step: true }) }] : [];
   if (insideHostSession(env, harness)) {
     ctx.incomplete = true;
-    return [item({ action: "skip", deferred: true, ...advised(`${kept}; ${inSessionReason(harness)}`, besides) })];
+    const prose = `${kept}; ${inSessionReason(harness)}`;
+    return [
+      item({
+        action: "skip",
+        deferred: true,
+        ...advised(prose, [...note, ...deferredRun(ctx, prose).advice.blocks, ...besides]),
+      }),
+    ];
   }
   const step = {
     kind: "host",
@@ -1560,7 +1684,7 @@ function planKeep(ctx, target, read) {
     why: `the kept copy's own upgrade, from its own bin without registering (the layout remedy's form), read back as JSON; it re-plans from the files as they stand then, after the agents block above`,
     touches: writes,
   };
-  return [item({ action: "update", ...advised(kept, besides), steps: [step] })];
+  return [item({ action: "update", ...advised(kept, [...note, ...besides]), steps: [step] }, note)];
 }
 
 // The mark (the converge story's rule 2), for the channel "npm" only: one
@@ -1889,7 +2013,7 @@ function planJsonEntry(ctx, key, s) {
       },
     ];
   }
-  const a = analyseJsonEntry(projectDir, s, { root, home, renderRoot });
+  const a = analyseJsonEntry(projectDir, s, { root, home, renderRoot, harness: ctx.harness });
   if (a.state === "unparseable")
     return [
       { surface: key, kind: "shared", path, entry: entryKey, state: "unparseable", action: "refuse", reason: a.reason },
@@ -2165,6 +2289,7 @@ export function plan(
     ensureState = false,
     recordKeep = false,
     takesSurface = true,
+    verb = null,
   } = {},
 ) {
   projectDir = resolve(projectDir);
@@ -2409,7 +2534,17 @@ export function plan(
           ? blockRun.map((m) => ({ display: m.display_name, files: agentsBlockRow(m)[1].files || [] }))
           : null;
       blockItems = planAgentsBlock(
-        { projectDir, mode, root, harness: owner, run: blockRun, readers, layout, surfaces: surfaces || [] },
+        {
+          projectDir,
+          mode,
+          root,
+          harness: owner,
+          run: blockRun,
+          readers,
+          layout,
+          surfaces: surfaces || [],
+          takesSurface,
+        },
         key,
         { ...s, files: commonBlockFiles(blockRun) },
       );
@@ -2469,6 +2604,9 @@ export function plan(
       channelFacts: null,
       refusals: [],
       takesSurface,
+      // The verb a deferral repeats (the install spec, contract 6, as amended
+      // 2026-10-14): the run's own — upgrade and setup plan in install mode.
+      verb: verb || mode,
     };
     // The keep (rule 5): the run's one block first — over the whole run set,
     // this harness included — then the keep's one item, and none of this
@@ -5258,6 +5396,7 @@ export async function runVerb(verb, projectDir, opts = {}) {
       plan(projectDir, {
         ...opts,
         mode,
+        verb,
         state: verb === "upgrade" || setup || (verb === "uninstall" && !opts.globalRemoval),
         version: prep.version,
         payloadRoots: prep.payloadRoots,

package/node_modules/projectstore/scripts/lib.mjs

@@ -30,6 +30,7 @@ import {
   projectRoot as harnessProjectRoot,
   pluginRoot as harnessPluginRoot,
   agentHome as harnessAgentHome,
+  harnessHome,
   configPath as harnessConfigPath,
   projectConfigDir as harnessProjectConfigDir,
   detectHarnessId,
@@ -545,12 +546,18 @@ export function pidAlive(pid) {
 
 // ─── Installed-plugin resolution ───────────────────────────────────────
 
-// The harness's config directory. Almost always ~/.claude, but the harness's
-// home variable relocates it — and a consumer that hardcodes the default
-// silently resolves nothing for those users instead of failing loudly. The
-// name is kept for its callers; the variable comes from the manifest.
+// Claude Code's config directory. Almost always ~/.claude, but its home
+// variable relocates it — and a consumer that hardcodes the default silently
+// resolves nothing for those users instead of failing loudly. The variable
+// comes from the source harness's manifest, never the active harness's: with
+// another harness's home variable exported (CODEX_HOME), detection makes that
+// harness active in a directory with no harness folder, and every Claude Code
+// path used to follow it into the other home (the install spec, contract 6,
+// as amended 2026-10-14). The host this process runs in is harnessAgentHome's
+// question, asked by its own callers; it stands in here only if a manifest
+// ever named no home at all.
 export function claudeHome(home = homedir()) {
-  return harnessAgentHome(process.env, home);
+  return harnessHome(sourceHarness(), { env: process.env, home }) || harnessAgentHome(process.env, home);
 }
 
 // The release triple only: 0.28.0-rc.2 and 0.28.0 compare equal. Right for
@@ -633,9 +640,11 @@ export function pluginEnabled(key, home = homedir(), projectDir = null) {
     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).
+    // host's own precedence (measured 2026-09-05, --scope local). Claude Code's
+    // project directory, whichever harness this process runs as.
+    const dir = harnessProjectConfigDir(process.env, sourceHarness());
     for (const f of ["settings.json", "settings.local.json"]) {
-      const proj = read(join(projectDir, harnessProjectConfigDir(), f));
+      const proj = read(join(projectDir, dir, f));
       if (proj && proj.enabledPlugins && Object.hasOwn(proj.enabledPlugins, key))
         enabled = proj.enabledPlugins[key] !== false;
     }
@@ -758,13 +767,17 @@ export function selectCopy(home = homedir(), projectDir, { harness = sourceHarne
   return { ...copy, bin, missing, channel: installChannel(copy.path, { home, harness }) };
 }
 
+// How a git-marketplace copy is updated, in its own channel: the one phrase
+// every advice about a kept or older copy quotes.
+export const COPY_UPDATE_STEPS = "in Claude Code: /plugin marketplace update, then /plugin update, then restart";
+
 // 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}`;
+  return `This project's projectstore plugin${v} ${cannot}: update it first (${COPY_UPDATE_STEPS}), ${then}`;
 }
 
 // The mark a channel switch leaves in this checkout's machine-local binding
@@ -1236,8 +1249,11 @@ export function statusLineIsOurWiring(cmd, projectDir, home = homedir(), root =
 // into state/<harness>/ made wrong; it is named instead, as plan() resolved
 // it — the same string the provenance line records, so an npx render and a
 // cache-install render stay byte-identical.
-export function renderStatusLineLauncher(tpl, root, projectDir = projectRoot(), env = process.env) {
-  const names = runtimeEnvNames(env);
+// `harness` is the one the launcher is FOR (the plan's harness), so a render
+// from a process another harness launched still bakes in Claude Code's names;
+// the SessionStart refresh passes none and renders for its own host.
+export function renderStatusLineLauncher(tpl, root, projectDir = projectRoot(), env = process.env, harness) {
+  const names = harness ? runtimeEnvNames(env, harness) : runtimeEnvNames(env);
   const subs = [
     ['"__PROJECTSTORE_ROOT__"', JSON.stringify(root)],
     ['"__PROJECTSTORE_HOME_ENV__"', JSON.stringify(names.home || "")],
@@ -1281,13 +1297,20 @@ export function writeStatusLineLauncher(projectDir, root) {
 // The command our entry should carry for this installation: the version-free
 // launcher for a marketplace-cache install, the plugin's own script for a dev
 // checkout (its path has no version to go stale). One resolver, shared by the
-// SessionStart refresh and the installer, so the two cannot disagree.
-export function desiredStatusLineCommand(projectDir, root = pluginRoot(), home = homedir()) {
+// SessionStart refresh and the installer, so the two cannot disagree. The
+// installer names the harness it plans (its launcher's state directory); the
+// refresh names none and means its own host.
+export function desiredStatusLineCommand(
+  projectDir,
+  root = pluginRoot(),
+  home = homedir(),
+  harnessId = activeHarnessId(),
+) {
   const launcher = isPluginCacheRoot(root, home);
   return {
     launcher,
     command: launcher
-      ? `node "${statusLineLauncherPath(projectDir)}"`
+      ? `node "${statusLineLauncherPath(projectDir, harnessId)}"`
       : `node "${join(root, "scripts", "statusline.mjs")}"`,
   };
 }
@@ -1416,6 +1439,19 @@ export function agentsBlockVersion(tmpl = null) {
   return m ? Number(m[1]) : null;
 }
 
+// A block whose marker is above this copy's template (the install spec,
+// contract 6, as amended 2026-10-14): the words every surface says it with.
+// Never "written by a newer projectstore" — a hand-edited marker reads the same.
+export function newerBlockWords(v, version) {
+  return `marked v${v}, newer than this copy's v${version}`;
+}
+
+// Whether a marker ranks above the template's. A template with no marker
+// (or a marker that is not a number) is never outranked.
+export function isNewerBlock(v, version) {
+  return Number.isInteger(v) && Number.isInteger(version) && v > version;
+}
+
 // The first block in `text`: its version, its span, whether it closes, and how
 // many open markers the file carries (more than one is a duplicate).
 export function findAgentsBlock(text) {
@@ -3871,7 +3907,7 @@ export function writeAnchorOffer(projectDir, sessionId, rec) {
 // within moments of each other both pass this check and both offer the same
 // name — the race is narrowed, not closed, and the ADR says so.
 export function liveSessionNames(selfSessionId, dir = null) {
-  const root = dir || join(claudeHome(), "sessions");
+  const root = dir || join(harnessAgentHome(process.env), "sessions");
   const out = [];
   let files;
   try {
@@ -3895,7 +3931,7 @@ export function liveSessionNames(selfSessionId, dir = null) {
 
 // What this session is currently called, if the harness has recorded a name.
 export function ownSessionName(selfSessionId, dir = null) {
-  const root = dir || join(claudeHome(), "sessions");
+  const root = dir || join(harnessAgentHome(process.env), "sessions");
   let files;
   try {
     files = readdirSync(root);

package/node_modules/projectstore/scripts/setup.mjs

@@ -64,7 +64,7 @@ import {
   languageNames,
 } from "./binding.mjs";
 import { analyseRegistration, analyseJsonEntry } from "./surfaces.mjs";
-import { runningCopies, coreCommand, channelChoices, pinFor } from "./convergence.mjs";
+import { runningCopies, coreCommand, channelChoices, pinFor, terminalRun } from "./convergence.mjs";
 import { runVerb, isInteractive, gateText, channelText, publicItem, planOptions } from "./install-harness.mjs";
 import { resolveBinding } from "./worktree.mjs";
 import * as term from "./term.mjs";
@@ -328,7 +328,9 @@ function factsOf(project, { env, home, root, version, interactive }) {
     sessionCopy = selectCopy(home, project, { harness: channelHarness });
   }
   const slotHarness = manifests.find((m) => statuslineOf(m)) || null;
-  const slot = slotHarness ? analyseJsonEntry(project, statuslineOf(slotHarness), { root, home }).state : null;
+  const slot = slotHarness
+    ? analyseJsonEntry(project, statuslineOf(slotHarness), { root, home, harness: slotHarness }).state
+    : null;
   // A worktree's main checkout (worktree.mjs): only where it can be offered —
   // at a terminal, unbound, in a linked worktree. Read for the project
   // answered, never from the git top, which --project leaves unread.
@@ -692,12 +694,12 @@ function doneLines(r, { project, runEnv, home, version, channel, vaultPlan, unde
     // Rule 13: `--channel npm` when that was the answer, and only for the
     // harness whose channel it is — setup refuses --channel in a run without
     // that harness (exit 2). A keep is not repeated: once recorded, it is the
-    // default already (rule 6).
-    const again = channel === "npm" && hostRegistrationOf(m) ? "--channel npm" : "";
+    // default already (rule 6). The deferred row's reason names the same
+    // command, from the same builder.
     if (left.length)
       blocks.push({
         lead: `Left for a terminal outside this ${m.display_name} session: ${left.join(", ")}. From a terminal in this project, run:`,
-        commands: [coreCommand("setup", { version, args: [`--harness ${id}`, again].filter(Boolean).join(" ") })],
+        commands: [terminalRun({ verb: "setup", harness: m, version, channel })],
         after: `then restart ${m.display_name}.`,
       });
   }

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -19,7 +19,8 @@
 //
 // Normative: the install spec — contract 0 (exclusive vs shared), 3–4 (the
 // four states and the ladder, rungs 1′ and 1″ included), 6 (per-entry states
-// for shared files: ours-current, ours-stale, ours-absent, unparseable),
+// for shared files: ours-current, ours-stale, ours-newer — 2026-10-14 —, ours-absent,
+// unparseable),
 // 12 (current, last written by), 14 (host-managed surfaces have no state to
 // derive), 16 (a harness is in use when detected or when it has files of
 // ours). Pure node, no external deps.
@@ -37,6 +38,8 @@ import {
   desiredStatusLineCommand,
   findAgentsBlock,
   agentsBlockVersion,
+  newerBlockWords,
+  isNewerBlock,
   agentsBlockTemplatePath,
   renderAgentsBlock,
   loadLayout,
@@ -185,6 +188,15 @@ export function analyseBlock(
   a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
   a.duplicates = withBlock.filter((e) => e !== a.current);
   if (!a.current) return { ...a, state: "ours-absent" };
+  // A marker above this copy's template is never rendered down (the install
+  // spec, contracts 4 and 6, as amended 2026-10-14). Placement still decides
+  // first (rungs B4–B6), and a block that moves, migrates or is deduplicated
+  // carries the newest block's own text; one that stays is `ours-newer`
+  // (B7), before the render is compared, so its roster is never re-rendered.
+  const newest = withBlock.reduce((n, e) => (e.block.v > n.block.v ? e : n), a.current);
+  a.newer = isNewerBlock(newest.block.v, a.version) ? newest : null;
+  const words = a.newer ? newerBlockWords(a.newer.block.v, a.version) : null;
+  const carried = a.newer ? ` with its own text (${words})` : "";
   // A block this harness CANNOT READ moves, and its target is created if it has
   // to be: that is the whole difference between a second harness arriving and a
   // preference. A block it can read moves only when the preferred file already
@@ -197,17 +209,25 @@ export function analyseBlock(
     return {
       ...a,
       state: "ours-stale",
-      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}`,
+      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}${carried}`,
     };
   }
   if (a.current.file !== preferred.file && preferred.present)
-    return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
+    return {
+      ...a,
+      state: "ours-stale",
+      reason: `in ${a.current.file}; install migrates it to ${preferred.file}${carried}`,
+    };
   if (a.duplicates.length)
     return {
       ...a,
       state: "ours-stale",
-      reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}`,
+      reason:
+        a.newer && a.newer !== a.current
+          ? `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}, and ${a.newer.file}'s carries v${a.newer.block.v}, newer than this copy's v${a.version}: its text replaces the block in ${a.current.file}`
+          : `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}${carried}`,
     };
+  if (a.newer) return { ...a, state: "ours-newer", reason: `${words}: left as it is` };
   if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
   return {
     ...a,
@@ -223,8 +243,15 @@ export function analyseBlock(
 
 // `renderRoot` (contract 4′, two phases): the root the surface is planned
 // AGAINST — the host's install path a registration produces — when it differs
-// from the root the templates are read from. Defaults to `root`.
-export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = homedir(), renderRoot = root } = {}) {
+// from the root the templates are read from. Defaults to `root`. `harness` is
+// the one the entry is FOR: its launcher lives under its own state directory,
+// whichever harness launched this process (the install spec, contract 6, as
+// amended 2026-10-14).
+export function analyseJsonEntry(
+  projectDir,
+  s,
+  { root = pluginRoot(), home = homedir(), renderRoot = root, harness = null } = {},
+) {
   const path = join(projectDir, s.file);
   const pointer = s.marker?.pointer || "statusLine.command";
   const entryKey = pointer.split(".")[0];
@@ -263,7 +290,7 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
   a.ours =
     statusLineIsOurWiring(a.curCmd, projectDir, home, root) ||
     statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
-  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home).command;
+  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home, harness?.id).command;
   if (!a.curEntry) return { ...a, state: "ours-absent" };
   if (!a.ours) return { ...a, state: "theirs", reason: "a status line we did not write owns the slot" };
   if (a.curCmd === a.desired) return { ...a, state: "ours-current" };
@@ -317,7 +344,7 @@ export function analyseStampedFile(
   const tpl = readText(src);
   if (!tpl.present || tpl.text === null)
     return { ...a, state: "unparseable", refusal: `the source ${s.source} is missing from the plugin at ${root}` };
-  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir);
+  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir, process.env, harness);
   if (rendered === null)
     return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
   const pkg = pluginVersionAt(root, harness) || "0.0.0";
@@ -791,7 +818,7 @@ export function surfaceStates(
     const hasOurs = states.some(
       (x) =>
         (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) ||
-        (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)),
+        (x.kind === "shared" && ["ours-current", "ours-stale", "ours-newer"].includes(x.state)),
     );
     if (detected.includes(m.id) || hasOurs) {
       out.used.push(m.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.3",
+  "version": "0.30.4",
   "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.30.3"
+    "projectstore": "=0.30.4"
   },
   "bundleDependencies": [
     "projectstore"