projectstore-claude 0.30.3 → 0.30.5

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,
@@ -100,6 +102,7 @@ import {
   packageCommand,
   invocation,
   harnessForOverlay,
+  activeHarness,
 } from "./harness.mjs";
 import { effortSpec } from "./models.mjs";
 
@@ -369,7 +372,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 +530,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 +570,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 +614,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 +674,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 +734,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
@@ -908,17 +944,22 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
     // 2026-10-03 amendment, finding 7).
     const remedy = layoutRemedy(proj, { root, home });
     // The block and its move are the source harness's — a pre-0.28 binding
-    // and that harness's command — so its fact under any other listener.
+    // and that harness's command — so its fact under any other listener. The
+    // move writes the source harness's overlay, whoever listens: since the
+    // overlay follows the shell that bundles the core (layout spec, contract 2,
+    // as amended 2026-10-15), the listener's `where` would name another file.
+    const src = sourceHarness();
+    const dest = relative(proj, layoutPaths(proj).overlay(src?.runtime?.overlay || src?.id));
     out.push(
       aboutHarness(
         finding(
           "install",
           "warn",
           "agents-in-binding",
-          `${b} still carries an agents block — since 0.28 the models live in ${where} (the layout ADR); nothing reads it there. ${remedyWords(remedy, proj, "Move it")}`,
+          `${b} still carries an agents block — since 0.28 the models live in ${dest} (the layout ADR); nothing reads it there. ${remedyWords(remedy, proj, "Move it")}`,
           b,
         ),
-        sourceHarness(),
+        src,
         speaker,
       ),
     );
@@ -1327,10 +1368,15 @@ export function checkOverrideCopies(proj, home = homedir(), harness = speakingHa
 // The variable names come from the manifest (runtime.agent_overrides); the
 // overlay is read only when one is set, so a clean startup reads nothing.
 export function checkEnvEffort(proj = null) {
+  // The variable is the active harness's (agentOverrides keys on detection), so
+  // the overlay it outranks is that harness's too — not the listener's, which
+  // in a shell's tree can be another harness (layout spec, contract 2, as
+  // amended 2026-10-15).
+  const h = activeHarness();
   return agentOverrides()
     .filter((o) => o.kind === "effort")
     .map((o) => {
-      const ov = proj ? readOverlayAt(proj) : null;
+      const ov = proj ? readOverlayAt(proj, h?.runtime?.overlay || h?.id) : null;
       const set = ov
         ? [
             ...(ov.efforts.default ? ["agents.default.effort"] : []),
@@ -1597,7 +1643,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 +1657,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

@@ -411,6 +411,46 @@ export function activeHarness(env = process.env, dir = MANIFEST_DIR) {
   return loadHarness(detectHarnessId(env, dir), dir) || sourceHarness(dir);
 }
 
+// ─── The Stop carrier (generation spec, contract 17; entry spec, contract 14,
+// as amended 2026-10-15) ────────────────────────────────────────────────
+//
+// The shape the entry reminder's Stop carrier prints, from the manifest of the
+// harness that IDENTIFIES itself — a forced harness, a parent's decision, a
+// strong signal or a session marker. Never detection's cwd folder, weak ranking or source
+// fallback: a wrong answer here is a hook the host refuses (Codex's Stop schema
+// denies hookSpecificOutput, measured 2026-10-15), and a refused print would
+// still spend the session's reminder. Nothing identified, or no carrier
+// measured, is null: the hook stays silent.
+export const STOP_CARRIERS = Object.freeze(["additionalContext", "block"]);
+export function stopCarrier(env = process.env, dir = MANIFEST_DIR) {
+  const id = identifiedHarnessId(env, dir);
+  const carrier = id ? loadHarness(id, dir)?.output_channels?.Stop?.carrier : null;
+  return STOP_CARRIERS.includes(carrier) ? carrier : null;
+}
+
+// What is wrong with a manifest's Stop row, or null. The carrier is our choice
+// and must be one its row supports: context needs `additionalContext` among the
+// honoured fields, a block needs the block decision, and a carrier is only
+// ever chosen from a measured row. Shared by the manifest check and its
+// planted fixtures.
+export function stopCarrierProblem(manifest) {
+  const row = manifest?.output_channels?.Stop;
+  if (row === null || row === undefined) return null;
+  if (typeof row !== "object") return "output_channels.Stop is not an object";
+  if (!("carrier" in row)) return "output_channels.Stop has no carrier (null when none is measured)";
+  if (![...STOP_CARRIERS, null].includes(row.carrier))
+    return `output_channels.Stop.carrier ${JSON.stringify(row.carrier)} is not one of ${STOP_CARRIERS.join(", ")} or null`;
+  if (![null, "block"].includes(row.decision))
+    return `output_channels.Stop.decision ${JSON.stringify(row.decision)} is not null or "block"`;
+  if (row.carrier === null) return null;
+  if (row.evidence !== "measured") return "output_channels.Stop.carrier is set on a row that is not measured";
+  if (row.carrier === "additionalContext" && !(row.fields || []).includes("additionalContext"))
+    return "output_channels.Stop.carrier is additionalContext, but its fields do not honour it";
+  if (row.carrier === "block" && row.decision !== "block")
+    return 'output_channels.Stop.carrier is block, but its decision is not "block"';
+  return null;
+}
+
 // ─── 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
@@ -503,10 +543,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 };
 }
 
@@ -763,9 +805,20 @@ export function shellHarnessId(env = process.env, dir = MANIFEST_DIR) {
 
 // The overlay a harness reads: <project>/.projectstore/harness/<overlay>.json —
 // the manifest's runtime.overlay, the harness id by convention (the layout ADR,
-// decision 3). Null only when no manifest at all can be found.
-export function overlayId(env = process.env, dir = MANIFEST_DIR) {
-  const h = activeHarness(env, dir);
+// decision 3). Whose (layout spec, contract 2, as amended 2026-10-15): the
+// harness that identifies itself; else the shell that bundles this core; else
+// the shell the environment names; else detectHarnessId's answer (the cwd's
+// harness folder, the weak ranking, the source harness). Contract 18's middle
+// rungs with detection's tail: a rendered skill's exec tool carries no variable
+// of its harness, and the cwd's folder would answer for it. --harness stays the
+// caller's (cli.mjs runAgents). Null only when no manifest at all can be found.
+export function overlayId(env = process.env, dir = MANIFEST_DIR, { core } = {}) {
+  const id =
+    identifiedHarnessId(env, dir) ||
+    bundlingShellHarnessId({ core, dir }) ||
+    shellHarnessId(env, dir) ||
+    detectHarnessId(env, dir);
+  const h = loadHarness(id, dir) || sourceHarness(dir);
   return h?.runtime?.overlay || h?.id || null;
 }
 
@@ -816,17 +869,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,