projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -27,7 +27,7 @@
 import { readFileSync, existsSync, realpathSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { loadHarnesses, loadHarness, harnessIds, detectHarnesses, sourceHarness, MANIFEST_DIR } from "./harness.mjs";
+import { loadHarnesses, harnessIds, detectHarnesses, sourceHarness, MANIFEST_DIR } from "./harness.mjs";
 import { stamp, deriveState, parseProvenance, sourceHash, STALE, STALE_TEXT, FOREIGN_TEXT } from "./provenance.mjs";
 import {
   pluginRoot,
@@ -44,6 +44,7 @@ import {
   claudeHome,
   whichOnPath,
   installedPluginEntries,
+  projectCopiesByKey,
   pluginEnabled,
   treeDigest,
   packageDigest,
@@ -52,11 +53,17 @@ import {
   RUNTIME_GITIGNORE_HEADER,
   LAUNCHER_HEADER,
   commandForm,
+  registrationProvenance,
 } from "./lib.mjs";
-import { analysePortableRegistration, portableRegistrationPaths, portablePayloadRoot } from "./portable-registration.mjs";
+import {
+  analysePortableRegistration,
+  portableRegistrationPaths,
+  portablePayloadRoot,
+} from "./portable-registration.mjs";
 
 export const GENERATOR = "scripts/install-harness.mjs";
-export const INSTALLED_REMEDY = "projectstore doctor reports this file when it is stale; run install again to refresh it.";
+export const INSTALLED_REMEDY =
+  "projectstore doctor reports this file when it is stale; run install again to refresh it.";
 // The line every launcher has carried since the template was written; the
 // recogniser for a pre-provenance launcher (contract 4, rung 1″). A substring
 // of the template's own header, so a reworded comment cannot turn every
@@ -89,39 +96,90 @@ export function isOurFile(text) {
 
 // ─── markdown-block: the ADR-002 block ─────────────────────────────────
 
-export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir = MANIFEST_DIR } = {}) {
+// `layout` names the roster the run leaves (a layout name; the binding's when
+// null). `readers` is a run's harnesses as [{ display, files }], passed when a
+// run names more than one: the migration reason then names the one whose
+// files lack the block's file, rather than the harness whose surface `s` is
+// (the story "One run plans the agents block once…", rules 1 and 3).
+export function analyseBlock(
+  projectDir,
+  s,
+  { root = pluginRoot(), manifestDir = MANIFEST_DIR, layout = null, readers = null } = {},
+) {
   const files = s.files || ["AGENTS.md", "CLAUDE.md"];
-  const PREFERRED = files[0], FALLBACK = files[files.length - 1];
+  const PREFERRED = files[0],
+    FALLBACK = files[files.length - 1];
   // LOOK across every file any manifest names; WRITE to one this harness can
   // read. The two are different questions and conflating them is what let the
   // block be created twice: a harness that scanned only its own list could not
   // see the copy another harness had already written, so it created a second.
   // Scanning is free and static — the union is manifest data, not project
   // state — while the write target stays this manifest's own preference.
-  const scan = [...files, ...[...loadHarnesses(manifestDir).values()]
-    .flatMap((m) => m.surfaces?.agents_block?.files || [])
-    .filter((f) => !files.includes(f))];
-  const found = scan.map((f) => ({ file: f, path: join(projectDir, f), ...readText(join(projectDir, f)) }))
+  const scan = [
+    ...files,
+    ...[...loadHarnesses(manifestDir).values()]
+      .flatMap((m) => m.surfaces?.agents_block?.files || [])
+      .filter((f) => !files.includes(f)),
+  ];
+  const found = scan
+    .map((f) => ({ file: f, path: join(projectDir, f), ...readText(join(projectDir, f)) }))
     .map((e) => ({ ...e, block: e.text !== null ? findAgentsBlock(e.text) : null, own: files.includes(e.file) }));
   const withBlock = found.filter((e) => e.block);
   const preferred = found.find((e) => e.file === PREFERRED && e.present) || found.find((e) => e.file === FALLBACK);
   const claude = found.find((e) => e.file === FALLBACK);
   const importLine = `@${PREFERRED}`;
-  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 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 ${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` };
+  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` };
+  if (twice)
+    return { ...a, state: "unparseable", refusal: `${twice.file} carries the block more than once — keep exactly one` };
 
   const tmpl = readText(agentsBlockTemplatePath(root));
-  if (!tmpl.present || tmpl.text === null) return { ...a, state: "unparseable", refusal: `the block's source is missing from the plugin at ${agentsBlockTemplatePath(root)}` };
+  if (!tmpl.present || tmpl.text === null)
+    return {
+      ...a,
+      state: "unparseable",
+      refusal: `the block's source is missing from the plugin at ${agentsBlockTemplatePath(root)}`,
+    };
   a.version = agentsBlockVersion(tmpl.text);
   const cfg = readConfigAt(projectDir);
   let roster = null;
-  if (cfg && typeof cfg.layout === "string") {
-    try { roster = loadLayout(cfg.layout, root).agents || null; } catch { roster = null; }
+  const name = layout ?? cfg?.layout;
+  if (typeof name === "string") {
+    try {
+      roster = loadLayout(name, root).agents || null;
+    } catch {
+      roster = null;
+    }
   }
   a.desired = renderAgentsBlock(tmpl.text, roster);
   a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
@@ -134,11 +192,31 @@ export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir =
   // never acquires an AGENTS.md it did not ask for, while installing Codex into
   // that same project moves the substance to the file Codex can read and leaves
   // CLAUDE.md importing it.
-  if (!a.current.own) return { ...a, state: "ours-stale", reason: `in ${a.current.file}, which ${s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}` };
-  if (a.current.file !== preferred.file && preferred.present) return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
-  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}` };
+  if (!a.current.own) {
+    const reader = readers?.find((r) => !(r.files || []).includes(a.current.file))?.display;
+    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}`,
+    };
+  }
+  if (a.current.file !== preferred.file && preferred.present)
+    return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
+  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}`,
+    };
   if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
-  return { ...a, state: "ours-stale", reason: a.current.block.v !== a.version ? `v${a.current.block.v} → v${a.version}` : "content differs from the current source" };
+  return {
+    ...a,
+    state: "ours-stale",
+    reason:
+      a.current.block.v !== a.version
+        ? `v${a.current.block.v} → v${a.version}`
+        : "content differs from the current source",
+  };
 }
 
 // ─── json-entry: one entry in a JSON file the user co-owns ─────────────
@@ -151,18 +229,40 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
   const pointer = s.marker?.pointer || "statusLine.command";
   const entryKey = pointer.split(".")[0];
   const cur = readText(path);
-  const a = { path, entryKey, cur, settings: {}, curEntry: null, curCmd: null, ours: false, desired: null, state: "ours-absent", reason: null };
+  const a = {
+    path,
+    entryKey,
+    cur,
+    settings: {},
+    curEntry: null,
+    curCmd: null,
+    ours: false,
+    desired: null,
+    state: "ours-absent",
+    reason: null,
+  };
   if (cur.present) {
     if (cur.text === null) return { ...a, state: "unparseable", reason: "the file cannot be read" };
-    try { a.settings = JSON.parse(cur.text); } catch { return { ...a, state: "unparseable", reason: "the file is not valid JSON — nothing outside a marked entry is touched, so nothing is written" }; }
-    if (!a.settings || typeof a.settings !== "object" || Array.isArray(a.settings)) return { ...a, state: "unparseable", reason: "the file is not a JSON object" };
+    try {
+      a.settings = JSON.parse(cur.text);
+    } catch {
+      return {
+        ...a,
+        state: "unparseable",
+        reason: "the file is not valid JSON — nothing outside a marked entry is touched, so nothing is written",
+      };
+    }
+    if (!a.settings || typeof a.settings !== "object" || Array.isArray(a.settings))
+      return { ...a, state: "unparseable", reason: "the file is not a JSON object" };
   }
   a.curEntry = a.settings[entryKey] ?? null;
   a.curCmd = a.curEntry && typeof a.curEntry.command === "string" ? a.curEntry.command : null;
   // "Did we write this?" is asked of the EXISTING entry, written by whatever
   // root was current then: a dev checkout's direct wiring stays ours when the
   // plan now renders against a registration's install path (reviewer, 2026-09-05).
-  a.ours = statusLineIsOurWiring(a.curCmd, projectDir, home, root) || statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
+  a.ours =
+    statusLineIsOurWiring(a.curCmd, projectDir, home, root) ||
+    statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
   a.desired = desiredStatusLineCommand(projectDir, renderRoot, home).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" };
@@ -172,7 +272,11 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
 
 // ─── mjs: an exclusive, provenance-stamped file ────────────────────────
 
-export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home = homedir(), harness = null, renderRoot = root } = {}) {
+export function analyseStampedFile(
+  projectDir,
+  s,
+  { root = pluginRoot(), home = homedir(), harness = null, renderRoot = root } = {},
+) {
   const path = join(projectDir, s.file);
   let file = readText(path);
   // The manifest may name where an earlier release wrote this file
@@ -181,28 +285,74 @@ export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home =
   const legacyPath = s.legacy_file ? join(projectDir, s.legacy_file) : null;
   const atLegacy = !file.present && legacyPath && existsSync(legacyPath);
   if (atLegacy) file = readText(legacyPath);
-  const a = { path, file, produced: true, ours: null, refusal: null, stamped: null, state: "absent", reason: null, writtenBy: null, sameProject: false, legacy: false, renderRoot, legacyPath: atLegacy ? legacyPath : null };
+  const a = {
+    path,
+    file,
+    produced: true,
+    ours: null,
+    refusal: null,
+    stamped: null,
+    state: "absent",
+    reason: null,
+    writtenBy: null,
+    sameProject: false,
+    legacy: false,
+    renderRoot,
+    legacyPath: atLegacy ? legacyPath : null,
+  };
   if (s.condition === "plugin_cache_install" && !isPluginCacheRoot(renderRoot, home)) {
     // Not produced for this installation (a dev checkout is wired directly).
     a.produced = false;
     if (!file.present) return { ...a, state: "absent" };
     a.ours = isOurFile(file.text);
-    return { ...a, state: a.ours ? "stale" : "foreign", reason: a.ours ? "not produced for this installation (a dev checkout is wired directly) — left in place; a prune of a launcher this root did not write needs the root that wrote it, or uninstall" : null };
+    return {
+      ...a,
+      state: a.ours ? "stale" : "foreign",
+      reason: a.ours
+        ? "not produced for this installation (a dev checkout is wired directly) — left in place; a prune of a launcher this root did not write needs the root that wrote it, or uninstall"
+        : null,
+    };
   }
   const src = join(root, s.source);
   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}` };
+  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);
-  if (rendered === null) return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
+  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";
   a.pkg = pkg;
-  a.stamped = stamp(rendered, { format: s.format, src: s.source, srcHash: sourceHash(tpl.text), pkg, project: projectDir, harness: harness?.id || sourceHarness()?.id || "harness", generator: GENERATOR, remedy: INSTALLED_REMEDY });
-  let st = deriveState({ file, sourceHash: sourceHash(tpl.text), pkg, renderNowHash: a.stamped.render, project: projectDir });
+  a.stamped = stamp(rendered, {
+    format: s.format,
+    src: s.source,
+    srcHash: sourceHash(tpl.text),
+    pkg,
+    project: projectDir,
+    harness: harness?.id || sourceHarness()?.id || "harness",
+    generator: GENERATOR,
+    remedy: INSTALLED_REMEDY,
+  });
+  let st = deriveState({
+    file,
+    sourceHash: sourceHash(tpl.text),
+    pkg,
+    renderNowHash: a.stamped.render,
+    project: projectDir,
+  });
   // Contract 4, rung 1″: a launcher written before provenance existed carries
   // no line but the template's own header. It is ours, stale, replaceable.
-  if (st.state === "foreign" && typeof file.text === "string" && file.text.includes(LAUNCHER_HEADER)) { st = { ...st, state: "stale", reason: STALE.PLUGIN }; a.legacy = true; }
+  if (st.state === "foreign" && typeof file.text === "string" && file.text.includes(LAUNCHER_HEADER)) {
+    st = { ...st, state: "stale", reason: STALE.PLUGIN };
+    a.legacy = true;
+  }
   a.installedPkg = st.provenance?.pkg || null;
-  return { ...a, state: st.state, reason: st.reason ? STALE_TEXT[st.reason] + (a.legacy ? " (pre-provenance file)" : "") : null, writtenBy: st.writtenBy, sameProject: st.sameProject };
+  return {
+    ...a,
+    state: st.state,
+    reason: st.reason ? STALE_TEXT[st.reason] + (a.legacy ? " (pre-provenance file)" : "") : null,
+    writtenBy: st.writtenBy,
+    sameProject: st.sameProject,
+  };
 }
 
 // ─── host-plugin-registration: our marketplace directory + the host's registry ──
@@ -214,12 +364,22 @@ export function analyseStampedFile(projectDir, s, { root = pluginRoot(), home =
 // located, never run.
 
 function samePath(a, b) {
-  const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
   return Boolean(a && b) && real(a) === real(b);
 }
 
 function readJson(p) {
-  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
 }
 
 export function registrationPaths(s, { home = homedir(), projectDir = null, harness = null } = {}) {
@@ -239,35 +399,68 @@ export function registrationPaths(s, { home = homedir(), projectDir = null, harn
   };
 }
 
-export function analyseRegistration(projectDir, s, { root = pluginRoot(), home = homedir(), harness = null, env = process.env } = {}) {
+export function analyseRegistration(
+  projectDir,
+  s,
+  { root = pluginRoot(), home = homedir(), harness = null, env = process.env } = {},
+) {
   const id = `${s.plugin_name}@${s.marketplace_name}`;
   const paths = registrationPaths(s, { home, projectDir, harness });
   const pkg = pluginVersionAt(root, harness) || "0.0.0";
-  const a = { id, paths, path: paths.dir, entryKey: id, pkg, bin: whichOnPath(s.cli?.bin || "claude", env), produced: !(s.condition === "npm_package_root" && isPluginCacheRoot(root, home)),
-    dir: { present: existsSync(paths.dir), manifest: null, prov: null, pkg: null, disabled: [], digestOk: null }, known: null, registeredHere: null, installed: null, installedVersion: null, installPath: null,
-    enabled: null, others: [], otherProjects: 0, writtenBy: null, newer: false, state: "absent", reason: null, refusal: null };
+  const a = {
+    id,
+    paths,
+    path: paths.dir,
+    entryKey: id,
+    pkg,
+    bin: whichOnPath(s.cli?.bin || "claude", env),
+    produced: !(s.condition === "npm_package_root" && isPluginCacheRoot(root, home)),
+    dir: { present: existsSync(paths.dir), manifest: null, prov: null, pkg: null, disabled: [], digestOk: null },
+    known: null,
+    registeredHere: null,
+    installed: null,
+    installedVersion: null,
+    installPath: null,
+    enabled: null,
+    others: [],
+    otherProjects: 0,
+    writtenBy: null,
+    newer: false,
+    state: "absent",
+    reason: null,
+    refusal: null,
+  };
 
   // Machine-global facts: our directory, the host's marketplace registry, every row of ours.
   if (a.dir.present) {
     a.dir.manifest = readJson(paths.manifest);
-    const prov = a.dir.manifest && a.dir.manifest[s.provenance_key];
-    if (prov && typeof prov === "object" && typeof prov.pkg === "string") {
-      a.dir.prov = prov; a.dir.pkg = prov.pkg;
+    const prov = registrationProvenance(a.dir.manifest, s);
+    if (prov) {
+      a.dir.prov = prov;
+      a.dir.pkg = prov.pkg;
       a.dir.disabled = Array.isArray(prov.disabled) ? prov.disabled.filter((x) => typeof x === "string") : [];
       if (typeof prov.project === "string" && !samePath(prov.project, projectDir)) a.writtenBy = prov.project;
       // The payload digest: a copy that did not finish, or a hand edit, is not current.
       if (prov.digest && typeof prov.digest.sha256 === "string") {
-        try { const d = treeDigest(paths.payload); a.dir.digestOk = d.count === prov.digest.count && d.sha256 === prov.digest.sha256; } catch { a.dir.digestOk = false; }
+        try {
+          const d = treeDigest(paths.payload);
+          a.dir.digestOk = d.count === prov.digest.count && d.sha256 === prov.digest.sha256;
+        } catch {
+          a.dir.digestOk = false;
+        }
       } else a.dir.digestOk = null; // no digest recorded: nothing to compare
     }
   }
   const known = readJson(paths.marketplaces);
   const mp = known && known[s.marketplace_name];
-  a.known = mp ? { path: (mp.installLocation || mp.source?.path || null), source: mp.source?.source || null } : null;
+  a.known = mp ? { path: mp.installLocation || mp.source?.path || null, source: mp.source?.source || null } : null;
   const all = installedPluginEntries(home, projectDir).filter((e) => e.key === id);
   // Per-project facts: the checkout's own settings file and the registry row carrying its path.
   const local = readJson(paths.projectSettings);
-  const here = local && local[s.registry?.known_pointer || "extraKnownMarketplaces"] && local[s.registry?.known_pointer || "extraKnownMarketplaces"][s.marketplace_name];
+  const here =
+    local &&
+    local[s.registry?.known_pointer || "extraKnownMarketplaces"] &&
+    local[s.registry?.known_pointer || "extraKnownMarketplaces"][s.marketplace_name];
   a.registeredHere = here ? { path: here.source?.path || null } : null;
   const enabledHere = (local && local[s.registry?.enabled_pointer || "enabledPlugins"]) || {};
   a.disabledHere = Object.keys(enabledHere).filter((k) => enabledHere[k] === false);
@@ -278,19 +471,25 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   a.installPath = row ? row.path : null;
   a.installedVersion = row ? row.version : null;
   a.enabled = pluginEnabled(id, home, projectDir);
-  // Competing registrations of the same plugin, enabled for this project.
-  const seen = new Set();
-  for (const e of installedPluginEntries(home, projectDir)) {
-    if (e.key === id || seen.has(e.key) || !e.present || e.enabled === false) continue;
-    if (e.projectPath && !samePath(e.projectPath, projectDir)) continue;
-    seen.add(e.key); a.others.push({ key: e.key, path: e.path, version: e.version });
+  // Competing registrations of the same plugin, enabled for this project:
+  // contract 12's selection, one row per key — the row the host loads here,
+  // this checkout's own before a user-scope one. The convergence story's rule
+  // 6 reads the same rows (lib's projectCopiesByKey), so the deferral of a
+  // newer copy and the stop never disagree about its version.
+  for (const e of projectCopiesByKey(home, projectDir)) {
+    if (e.key !== id) a.others.push({ key: e.key, path: e.path, version: e.version });
   }
   a.newer = Boolean(a.dir.pkg) && cmpPrecedence(a.dir.pkg, pkg) > 0;
   // Same version, different payload: the directory's recorded digest against
   // this package's — contract 4's rung 3 (source changed) for a directory.
   a.contentDiffers = null;
   if (a.dir.prov && a.dir.pkg === pkg && a.dir.prov.digest && typeof a.dir.prov.digest.sha256 === "string") {
-    try { const d = packageDigest(root); a.contentDiffers = d.sha256 !== a.dir.prov.digest.sha256 || d.count !== a.dir.prov.digest.count; } catch { a.contentDiffers = null; }
+    try {
+      const d = packageDigest(root);
+      a.contentDiffers = d.sha256 !== a.dir.prov.digest.sha256 || d.count !== a.dir.prov.digest.count;
+    } catch {
+      a.contentDiffers = null;
+    }
   }
   // The version the host would install from the directory as it will stand after this run.
   a.targetPkg = a.newer ? a.dir.pkg : pkg;
@@ -300,22 +499,100 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   const bin = s.cli?.bin || "claude";
 
   // The ladder (contract 4′).
-  if (!a.bin && nothingOfOurs) return { ...a, state: "unavailable", reason: `\`${bin}\` is not on PATH — the registration needs the host's CLI; the other surfaces still install` };
-  if (a.dir.present && !a.dir.prov) return { ...a, state: "foreign", refusal: `${paths.dir} exists and its ${s.manifest} carries no \`${s.provenance_key}\` field of ours — a directory we did not write sits at our path; move it if it is yours, or delete it to let install take the name` };
-  if (a.known && a.known.path && !samePath(a.known.path, paths.dir)) return { ...a, state: "foreign", refusal: `the host's registry names marketplace \`${s.marketplace_name}\` at ${a.known.path}, not at ${paths.dir} — a registration we did not make holds our name; \`${bin} plugin marketplace remove ${s.marketplace_name}\` lets install take it` };
-  if (a.registeredHere && a.registeredHere.path && !samePath(a.registeredHere.path, paths.dir)) return { ...a, state: "foreign", refusal: `${paths.projectSettings} declares marketplace \`${s.marketplace_name}\` at ${a.registeredHere.path}, not at ${paths.dir} — remove that entry to let install take the name` };
+  if (!a.bin && nothingOfOurs)
+    return {
+      ...a,
+      state: "unavailable",
+      reason: `\`${bin}\` is not on PATH — the registration needs the host's CLI; the other surfaces still install`,
+    };
+  if (a.dir.present && !a.dir.prov)
+    return {
+      ...a,
+      state: "foreign",
+      refusal: `${paths.dir} exists and its ${s.manifest} carries no \`${s.provenance_key}\` field of ours — a directory we did not write sits at our path; move it if it is yours, or delete it to let install take the name`,
+    };
+  if (a.known && a.known.path && !samePath(a.known.path, paths.dir))
+    return {
+      ...a,
+      state: "foreign",
+      refusal: `the host's registry names marketplace \`${s.marketplace_name}\` at ${a.known.path}, not at ${paths.dir} — a registration we did not make holds our name; \`${bin} plugin marketplace remove ${s.marketplace_name}\` lets install take it`,
+    };
+  if (a.registeredHere && a.registeredHere.path && !samePath(a.registeredHere.path, paths.dir))
+    return {
+      ...a,
+      state: "foreign",
+      refusal: `${paths.projectSettings} declares marketplace \`${s.marketplace_name}\` at ${a.registeredHere.path}, not at ${paths.dir} — remove that entry to let install take the name`,
+    };
   if (nothingOfOurs) return { ...a, state: "absent" };
   // The directory is shared by every checkout on the machine; a project that never registered is absent, whatever the directory holds.
-  if (nothingOfOursHere) return { ...a, state: "absent", reason: a.dir.present ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered` : null };
+  if (nothingOfOursHere)
+    return {
+      ...a,
+      state: "absent",
+      reason: a.dir.present
+        ? `the marketplace directory is present${a.writtenBy ? ` (written from ${a.writtenBy})` : ""}; this checkout is not registered`
+        : null,
+    };
   if (!a.dir.present) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + " (the directory is gone)" };
-  if (cmpPrecedence(a.dir.pkg, pkg) < 0) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})` };
-  if (a.dir.digestOk === false) return { ...a, state: "stale", reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)" };
-  if (a.contentDiffers === true) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (same version ${pkg}, different content — the directory's digest is not this package's)` };
-  if (!a.known || !a.registeredHere) return { ...a, state: "stale", reason: STALE_TEXT[STALE.CONFIG] + (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)") };
-  if (!a.installed || !a.installed.present) return { ...a, state: "stale", reason: "not installed" + (a.installed ? " (the host's install path is gone)" : " (registered, not installed for this checkout)") };
-  if (a.installedVersion !== a.dir.pkg) return { ...a, state: "stale", reason: STALE_TEXT[STALE.PLUGIN] + ` (installed ${a.installedVersion}, directory ${a.dir.pkg})` };
+  if (cmpPrecedence(a.dir.pkg, pkg) < 0)
+    return {
+      ...a,
+      state: "stale",
+      reason: STALE_TEXT[STALE.PLUGIN] + ` (directory at ${a.dir.pkg}, package at ${pkg})`,
+    };
+  if (a.dir.digestOk === false)
+    return {
+      ...a,
+      state: "stale",
+      reason: "edited by hand or half-written (the payload does not match the digest its manifest carries)",
+    };
+  if (a.contentDiffers === true)
+    return {
+      ...a,
+      state: "stale",
+      reason:
+        STALE_TEXT[STALE.PLUGIN] +
+        ` (same version ${pkg}, different content — the directory's digest is not this package's)`,
+    };
+  if (!a.known || !a.registeredHere)
+    return {
+      ...a,
+      state: "stale",
+      reason:
+        STALE_TEXT[STALE.CONFIG] +
+        (a.known ? " (this checkout does not declare the marketplace)" : " (the host does not know the marketplace)"),
+    };
+  if (!a.installed || !a.installed.present)
+    return {
+      ...a,
+      state: "stale",
+      reason:
+        "not installed" +
+        (a.installed ? " (the host's install path is gone)" : " (registered, not installed for this checkout)"),
+    };
+  if (a.installedVersion !== a.dir.pkg)
+    return {
+      ...a,
+      state: "stale",
+      reason: STALE_TEXT[STALE.PLUGIN] + ` (installed ${a.installedVersion}, directory ${a.dir.pkg})`,
+    };
   if (!a.enabled) return { ...a, state: "stale", reason: "disabled for this checkout" };
-  return { ...a, state: "current", reason: a.newer ? `the directory is at ${a.dir.pkg}, newer than this package (${pkg})${a.writtenBy ? `, written from ${a.writtenBy}` : ""} — not downgraded` : null };
+  return {
+    ...a,
+    state: "current",
+    reason: a.newer
+      ? `the directory is at ${a.dir.pkg}, newer than this package (${pkg})${a.writtenBy ? `, written from ${a.writtenBy}` : ""} — not downgraded`
+      : null,
+  };
+}
+
+// The root a registration renders the project's dependent surfaces against,
+// read-only (contract 4′, two phases): the host's install path of this
+// checkout's row, when that copy is on disk and enabled; else null. One rule
+// for plan() (a run that leaves the registration out) and surfaceStates
+// (doctor), so the two cannot disagree about which root a launcher is for.
+export function registrationRenderRoot(a) {
+  return a && a.installed && (a.installed.present ?? true) && a.enabled ? a.installPath : null;
 }
 
 // ─── the project-level layout: legacy / new / both (the layout ADR) ─────
@@ -329,13 +606,27 @@ export function analyseLayout(projectDir, { harness = null } = {}) {
   const has = (f) => existsSync(f);
   const legacy = {
     dir: p.legacy.dir,
-    binding: has(p.legacy.binding), runtime: has(p.legacy.runtime), state: has(p.legacy.state), launcher: has(p.legacy.launcher),
-    entryLog: has(p.legacy.entryLog), welcomed: has(p.legacy.welcomed), sessionId: has(p.legacy.sessionId),
-    runtimeOurs: false, stateFiles: [],
+    binding: has(p.legacy.binding),
+    runtime: has(p.legacy.runtime),
+    state: has(p.legacy.state),
+    launcher: has(p.legacy.launcher),
+    entryLog: has(p.legacy.entryLog),
+    welcomed: has(p.legacy.welcomed),
+    sessionId: has(p.legacy.sessionId),
+    runtimeOurs: false,
+    stateFiles: [],
   };
   if (legacy.runtime) {
-    try { legacy.runtimeOurs = readFileSync(p.legacy.gitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER); } catch { legacy.runtimeOurs = false; }
-    if (legacy.state) { try { legacy.stateFiles = readdirSync(p.legacy.state).filter((n) => n !== ".gitignore"); } catch {} }
+    try {
+      legacy.runtimeOurs = readFileSync(p.legacy.gitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER);
+    } catch {
+      legacy.runtimeOurs = false;
+    }
+    if (legacy.state) {
+      try {
+        legacy.stateFiles = readdirSync(p.legacy.state).filter((n) => n !== ".gitignore");
+      } catch {}
+    }
   }
   const current = { root: has(p.root), binding: has(p.binding) };
   const any = legacy.binding || legacy.runtime || legacy.welcomed || legacy.sessionId;
@@ -344,28 +635,77 @@ export function analyseLayout(projectDir, { harness = null } = {}) {
   let resumable = false;
   if (legacy.binding && current.binding) {
     try {
-      const { agents, ...oldRest } = JSON.parse(readFileSync(p.legacy.binding, "utf8"));
+      const { agents: _agents, ...oldRest } = JSON.parse(readFileSync(p.legacy.binding, "utf8"));
       const cur = JSON.parse(readFileSync(p.binding, "utf8"));
       resumable = JSON.stringify(oldRest) === JSON.stringify(cur);
-    } catch { resumable = false; }
+    } catch {
+      resumable = false;
+    }
   }
   return {
-    paths: p, legacy, current, resumable,
+    paths: p,
+    legacy,
+    current,
+    resumable,
     twoConfigs: legacy.binding && current.binding,
     pending: any,
-    state: !any ? "current" : (legacy.binding && current.binding) ? "both" : legacy.binding ? "legacy" : "partial",
+    state: !any ? "current" : legacy.binding && current.binding ? "both" : legacy.binding ? "legacy" : "partial",
   };
 }
 
+// ─── a harness's state directory: the welcome marker (contract 13) ──────
+//
+// What a project uninstall may take from .projectstore/state/<id>/: the
+// welcome marker, and the directory once it is empty. Without that the
+// directory outlives the uninstall and the next bare upgrade selects the
+// removed harness again (layout spec contract 5). The marker carries no
+// provenance line, so it is recognised three ways at once — the third
+// recogniser contract 13 accepts beside the provenance line and rung 1″: its
+// path, layoutPaths(p).welcomed(id); the state directory's .gitignore carrying
+// RUNTIME_GITIGNORE_HEADER; and its content, one ISO timestamp line, exactly
+// as the SessionStart hook writes it. Anything else in the directory — a
+// launcher, a file of the user's — is named in `others` and never ours to
+// take here: a launcher is its surface item's. Read-only, like everything in
+// this module.
+const WELCOME_STAMP = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z\n?$/;
+export function analyseHarnessState(projectDir, id) {
+  const p = layoutPaths(projectDir);
+  const dir = p.harnessState(id);
+  let names;
+  try {
+    names = readdirSync(dir).sort();
+  } catch {
+    return { dir, present: false, names: [], headed: false, marker: null, others: [] };
+  }
+  let headed = false;
+  try {
+    headed = readFileSync(p.stateGitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER);
+  } catch {}
+  const markerPath = p.welcomed(id);
+  const markerName = markerPath.slice(dir.length + 1);
+  const t = names.includes(markerName) ? readText(markerPath) : { present: false, text: null };
+  const marker = headed && t.present && typeof t.text === "string" && WELCOME_STAMP.test(t.text) ? markerPath : null;
+  return { dir, present: true, names, headed, marker, others: names.filter((n) => !(marker && n === markerName)) };
+}
+
 // ─── every surface, for doctor ─────────────────────────────────────────
 
 export { analysePortableRegistration, portableRegistrationPaths };
-const ANALYSERS = { "markdown-block": analyseBlock, "json-entry": analyseJsonEntry, "mjs": analyseStampedFile, "host-plugin-registration": analyseRegistration, "portable-plugin-registration": analysePortableRegistration };
+const ANALYSERS = {
+  "markdown-block": analyseBlock,
+  "json-entry": analyseJsonEntry,
+  mjs: analyseStampedFile,
+  "host-plugin-registration": analyseRegistration,
+  "portable-plugin-registration": analysePortableRegistration,
+};
 
 // The states of every non-host, supported surface of every harness this
 // project uses — detected by directory, or carrying a file of ours (contract
 // 16). Host-managed rows have nothing to derive (contract 14).
-export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(), manifestDir = MANIFEST_DIR, harnesses = null, env = process.env } = {}) {
+export function surfaceStates(
+  projectDir,
+  { home = homedir(), root = pluginRoot(), manifestDir = MANIFEST_DIR, harnesses = null, env = process.env } = {},
+) {
   projectDir = resolve(projectDir);
   const detected = detectHarnesses(projectDir, { dir: manifestDir }).map((d) => d.id);
   const out = { projectDir, detected, used: [], installable: harnessIds(manifestDir), states: [] };
@@ -376,37 +716,83 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
     // and so does this (S2, the 2026-10-03 review): reporting it from the
     // core printed "<core> is not a portable plugin root" into every project
     // that merely contained the harness's directory.
-    const rows = Object.entries(m.surfaces || {}).filter(([k, s]) => !k.startsWith("_") && s.kind !== "host" && s.supported !== false && ANALYSERS[s.format]
-      && !(s.condition === "distribution_root" && !portablePayloadRoot(s, { root, env })));
+    const rows = Object.entries(m.surfaces || {}).filter(
+      ([k, s]) =>
+        !k.startsWith("_") &&
+        s.kind !== "host" &&
+        s.supported !== false &&
+        ANALYSERS[s.format] &&
+        !(s.condition === "distribution_root" && !portablePayloadRoot(s, { root, env })),
+    );
+    // The render root, as plan() takes it (contract 0 as amended 2026-10-10):
+    // an enabled, produced registration's install path. The launcher and the
+    // status-line entry are analysed against it — from the marketplace
+    // directory the host loads an npm registration from, or from a package
+    // root, the running root alone read the launcher as "not produced here".
+    // Read once, before the rows (the registration sorts last in the
+    // manifest); its own row reuses the result, since the analysis digests
+    // the payload.
+    const reg = rows.find(([, s]) => s.kind === "registration");
+    const regA = reg ? ANALYSERS[reg[1].format](projectDir, reg[1], { root, home, harness: m, env }) : null;
+    const renderRoot = (regA && regA.produced !== false && registrationRenderRoot(regA)) || root;
     const states = [];
     for (const [key, s] of rows) {
-      const a = ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env });
-      const entry = s.kind === "shared" ? (a.entryKey || s.marker?.pointer || null) : null;
-      const path = a.legacyPath || a.path || (a.current ? a.current.path : (a.preferred ? a.preferred.path : join(projectDir, s.file || "")));
-      const row = { harness: m.id, surface: key, kind: s.kind, path, entry, state: a.state, reason: a.reason || a.refusal || null, writtenBy: a.writtenBy || null, sameProject: Boolean(a.sameProject), produced: a.produced !== false, legacy: Boolean(a.legacy), installedPkg: a.installedPkg || null, present: a.file ? a.file.present : (a.current ? true : (a.curEntry ? true : false)) };
-      if (s.kind === "registration") Object.assign(row, {
-        entry: a.id,
-        present: Boolean(a.dir?.present || a.ownership || a.known || a.market || a.installed),
-        produced: a.produced,
-        pkg: a.pkg || a.desiredVersion || null,
-        dirPkg: a.dir?.pkg || a.ownership?.version || null,
-        installedVersion: a.installedVersion,
-        installPath: a.installPath,
-        enabled: a.enabled,
-        others: a.others || [],
-        otherProjects: a.otherProjects || 0,
+      const dependent = renderRoot !== root && ["json-entry", "mjs"].includes(s.format);
+      const a =
+        reg && s === reg[1]
+          ? regA
+          : ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env, ...(dependent ? { renderRoot } : {}) });
+      const entry = s.kind === "shared" ? a.entryKey || s.marker?.pointer || null : null;
+      const path =
+        a.legacyPath ||
+        a.path ||
+        (a.current ? a.current.path : a.preferred ? a.preferred.path : join(projectDir, s.file || ""));
+      const row = {
+        harness: m.id,
+        surface: key,
+        kind: s.kind,
+        path,
+        entry,
+        state: a.state,
+        reason: a.reason || a.refusal || null,
         writtenBy: a.writtenBy || null,
-        newer: Boolean(a.newer),
-        bin: a.bin,
-        // What this registration silenced for the checkout and the checkout
-        // still holds off: exactly the set uninstall re-enables (contract 13).
-        silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
-      });
+        sameProject: Boolean(a.sameProject),
+        produced: a.produced !== false,
+        legacy: Boolean(a.legacy),
+        installedPkg: a.installedPkg || null,
+        present: a.file ? a.file.present : a.current ? true : a.curEntry ? true : false,
+      };
+      if (s.kind === "registration")
+        Object.assign(row, {
+          entry: a.id,
+          present: Boolean(a.dir?.present || a.ownership || a.known || a.market || a.installed),
+          produced: a.produced,
+          pkg: a.pkg || a.desiredVersion || null,
+          dirPkg: a.dir?.pkg || a.ownership?.version || null,
+          installedVersion: a.installedVersion,
+          installPath: a.installPath,
+          // The plugin's root inside our directory (registrationPaths' payload):
+          // what a host that loads the registration in place runs from.
+          payload: a.paths?.payload || null,
+          enabled: a.enabled,
+          others: a.others || [],
+          otherProjects: a.otherProjects || 0,
+          writtenBy: a.writtenBy || null,
+          newer: Boolean(a.newer),
+          bin: a.bin,
+          // What this registration silenced for the checkout and the checkout
+          // still holds off: exactly the set uninstall re-enables (contract 13).
+          silenced: (a.dir?.disabled || []).filter((k) => (a.disabledHere || []).includes(k)),
+        });
       states.push(row);
     }
     // A registration is the host's to load and never counts as a file of ours
     // (contract 16): it decides nothing about whether the harness is in use.
-    const hasOurs = states.some((x) => (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) || (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)));
+    const hasOurs = states.some(
+      (x) =>
+        (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) ||
+        (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)),
+    );
     if (detected.includes(m.id) || hasOurs) {
       out.used.push(m.id);
       // The agents block is deliberately shared across harnesses. Its presence