projectstore-claude 0.30.2 → 0.30.4

package/node_modules/projectstore/scripts/doctor.mjs

@@ -56,10 +56,13 @@ import {
   AGENTS_BLOCK_OPEN_SRC,
   AGENTS_BLOCK_CLOSE,
   agentsBlockVersion,
+  newerBlockWords,
+  isNewerBlock,
   findAgentsBlock,
   statusLineLauncherPath,
   LAUNCHER_HEADER,
   installedPluginEntries,
+  projectCopies,
   selectCopy,
   takesNoRegister,
   copyUpdateAdvice,
@@ -98,7 +101,9 @@ import {
   configPath as harnessConfigPath,
   packageCommand,
   invocation,
+  harnessForOverlay,
 } from "./harness.mjs";
+import { effortSpec } from "./models.mjs";
 
 // A remedy used to interpolate the surface's harness variable here. It cannot:
 // measured 2026-09-06, NO harness gives its Bash tool that variable, and a
@@ -366,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 {
@@ -524,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");
@@ -564,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;
@@ -607,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) {
@@ -664,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
@@ -708,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
@@ -891,7 +929,7 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
         "install",
         "issue",
         "overlay-forbidden-key",
-        `${where} carries \`${k}\`, which an overlay may not: only agents.default.model and agents.per_agent.<name>.model are read; the key is ignored.`,
+        `${where} carries \`${k}\`, which an overlay may not: only agents.default.model, agents.default.effort, agents.per_agent.<name>.model and agents.per_agent.<name>.effort are read; the key is ignored.`,
         where,
       ),
     );
@@ -953,19 +991,42 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
       }
     }
   }
-  // A configured name no roster agent carries runs nothing: the model never
-  // applies. A warn, not an issue — a newer package's agent is a legitimate
-  // reason for a committed overlay to name one this copy does not ship.
+  // A configured name no roster agent carries runs nothing: what it
+  // configures never applies. A warn, not an issue — a newer package's agent
+  // is a legitimate reason for a committed overlay to name one this copy does
+  // not ship.
+  // An effort the harness's levels lack fails at spawn on a harness whose
+  // spawn takes those levels only, and is the harness's to judge elsewhere:
+  // a warn names it either way (the effort ADR, decision 7). Read against the
+  // manifest's floor alone: doctor reads no model catalog.
+  const levels = effortSpec(harnessForOverlay(o.id))?.levels?.map((l) => l.id) || null;
+  if (levels) {
+    const set = [
+      ...(o.efforts.default ? [["agents.default.effort", o.efforts.default]] : []),
+      ...Object.entries(o.efforts.per_agent).map(([n, v]) => [`agents.per_agent.${n}.effort`, v]),
+    ];
+    for (const [k, v] of set)
+      if (!levels.includes(v))
+        out.push(
+          finding(
+            "install",
+            "warn",
+            "overlay-unknown-effort",
+            `${where} sets \`${k}\` to ${v}, which is not one of ${harnessForOverlay(o.id)?.display_name || o.id}'s effort levels (${levels.join(", ")}) — a spawn may refuse it.`,
+            where,
+          ),
+        );
+  }
   const roster = layoutRoster(cfg);
   if (roster) {
-    for (const n of Object.keys(o.agents.per_agent)) {
+    for (const n of new Set([...Object.keys(o.agents.per_agent), ...Object.keys(o.efforts.per_agent)])) {
       if (!roster.includes(n))
         out.push(
           finding(
             "install",
             "warn",
             "overlay-unknown-agent",
-            `${where} configures \`${n}\`, which is not in the ${cfg.layout} roster (${roster.join(", ")}) — no agent by that name runs, so the model never applies. A typo, or an agent this package does not ship yet.`,
+            `${where} configures \`${n}\`, which is not in the ${cfg.layout} roster (${roster.join(", ")}) — no agent by that name runs, so what it configures never applies. A typo, or an agent this package does not ship yet.`,
             where,
           ),
         );
@@ -1148,7 +1209,16 @@ export function checkVersionDrift(home = homedir(), states = [], proj = null, {
   const seen = [];
   // The registry read here is the source harness's own.
   const registryOf = sourceHarness()?.id || null;
-  for (const e of installedPluginEntries(home, proj)) {
+  // The copies the host loads for this project (contract 17, amended
+  // 2026-10-14): this checkout's own row or a user-scope row, never another
+  // project's — the registry keeps every project's local rows, and another
+  // checkout's old copy is not a drift here. Every row, not one per key: this
+  // project's own row against a user-scope row is the drift contract 17 names.
+  // Without a project, the user-scope rows alone.
+  const rows = proj
+    ? projectCopies(home, proj)
+    : installedPluginEntries(home).filter((e) => e.present && e.enabled !== false && !e.projectPath);
+  for (const e of rows) {
     // A disabled registration is not a copy anyone runs (contract 17, amended 2026-09-05).
     if (e.version && e.present && e.enabled !== false)
       seen.push({
@@ -1284,24 +1354,32 @@ export function checkOverrideCopies(proj, home = homedir(), harness = speakingHa
   return out;
 }
 
-// ADR-008 made `effort` unconfigurable per project, which promotes this env var
-// from a curiosity to the ONLY thing that can move our agents off `effort: max`.
-// It beats frontmatter, so a value set for cost or latency silently drops all
-// five agents below the quality floor the plugin advertises — exactly the class
-// of silent downgrade doctor exists to name.
+// The variable outranks every effort projectstore passes at spawn and the
+// bundled agents' frontmatter effort: with it set, the spawn offers no effort
+// parameter at all (the effort ADR, decision 7). So a value set for cost or
+// latency silently replaces the efforts the overlay configures — exactly the
+// class of "the value configured is not the value that runs" doctor names.
 // The variable names come from the manifest (runtime.agent_overrides); the
-// wording is projectstore's, because the claim — ADR-008's quality floor — is.
-export function checkEnvEffort() {
+// overlay is read only when one is set, so a clean startup reads nothing.
+export function checkEnvEffort(proj = null) {
   return agentOverrides()
     .filter((o) => o.kind === "effort")
-    .map((o) =>
-      finding(
+    .map((o) => {
+      const ov = proj ? readOverlayAt(proj) : null;
+      const set = ov
+        ? [
+            ...(ov.efforts.default ? ["agents.default.effort"] : []),
+            ...Object.keys(ov.efforts.per_agent).map((n) => `agents.per_agent.${n}.effort`),
+          ]
+        : [];
+      const where = set.length ? ` (${relative(proj, ov.path) || ov.path} sets ${set.join(", ")})` : "";
+      return finding(
         "install",
         "warn",
         "env-effort",
-        `${o.env}=${o.value} is set — it overrides the bundled agents' "effort: max" frontmatter, so every projectstore agent runs at "${o.value}". Effort is not configurable per project (ADR-008); unset the variable to restore the quality floor.`,
-      ),
-    );
+        `${o.env}=${o.value} is set — it outranks every effort projectstore passes at spawn${where} and the bundled agents' frontmatter, so every projectstore agent runs at "${o.value}". Unset it for the configured efforts to run.`,
+      );
+    });
 }
 
 export function checkEnvModel() {
@@ -1538,28 +1616,48 @@ export function checkGitignore(proj) {
       }
     }
   }
-  if (!existsSync(join(proj, ".git"))) return out;
+  // The host's settings file is checkHostIgnored's (the layout spec, contract 9
+  // as amended 2026-10-14): only git knows every rule that ignores it, and this
+  // function runs in the SessionStart subset, whose budget forbids a subprocess.
+  return out;
+}
+
+// The line read the host-file check used before it asked git, and still uses
+// when git cannot answer: the project's own .gitignore, exact lines only.
+function hostIgnoreLineMissing(proj, env) {
   let lines = [];
   try {
     lines = readFileSync(join(proj, ".gitignore"), "utf8")
       .split("\n")
       .map((l) => l.trim());
   } catch {}
-  const coveredAll = lines.includes(".claude/") || lines.includes(".claude");
-  if (coveredAll) return out;
-  // Our own files are self-ignored inside .projectstore/; what is left is the host's.
-  const wanted = [relative(proj, hostSettingsPath(proj))];
-  const missing = wanted.filter((w) => !lines.includes(w));
-  if (!missing.length) return out;
-  out.push(
+  if (lines.includes(".claude/") || lines.includes(".claude")) return [];
+  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,
+// contract 9 as amended 2026-10-14). Our own files are self-ignored inside
+// .projectstore/; what is left is the host's. Git's answer covers every rule
+// it applies — nested .gitignore files, .git/info/exclude, core.excludesFile
+// and its XDG default — where the line read saw only the project's exact
+// lines. --no-index keeps this about rules: a tracked file with a matching rule
+// is quiet here (tracking is checkTrackedRuntime's). Exit 0 is ignored, 1 is
+// not; anything else — no git on PATH, an error, a timeout — falls back to the
+// 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, 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 [];
+  return [
     finding(
       "install",
       "warn",
       "gitignore",
       `Machine-specific files not gitignored: ${missing.join(", ")} (or ignore ".claude/" wholesale).`,
     ),
-  );
-  return out;
+  ];
 }
 
 // An ignore line never untracks a file already in the index, so the project
@@ -2956,8 +3054,9 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
     ...checkAgentsBlock(proj, { env: opts.env, root: opts.root }),
     ...checkOverrideCopies(proj),
     ...checkEnvModel(),
-    ...checkEnvEffort(),
+    ...checkEnvEffort(proj),
     ...checkGitignore(proj),
+    ...checkHostIgnored(proj, { env: opts.env }),
     ...checkTrackedRuntime(proj),
     ...checkVaultGit(cfg),
     ...checkAutoUpdate(),
@@ -3042,7 +3141,7 @@ export function runStartupChecks(cfg, proj, budgetMs = 150) {
         restamp: findings.some((f) => f.level === "info" && f.check === "upgrade"),
       }),
     () => checkEnvModel(),
-    () => checkEnvEffort(),
+    () => checkEnvEffort(proj),
   ];
   for (const step of steps) {
     if (Date.now() - started > budgetMs) return { skipped: true, count: 0, findings: foldIntoMove(findings) };

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);
 }