projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/fetch-shell.mjs

@@ -0,0 +1,283 @@
+// projectstore — fetch-shell.mjs: the shell fetch of install and upgrade.
+//
+// A harness whose plugin root ships only in its distribution shell (Codex:
+// its registration surface carries `condition: "distribution_root"`) cannot
+// be registered from the core alone. So a core run that stages fetches that
+// shell, at the core's own version, into a scratch directory under the
+// user-level cache, verifies it, and plans the harness from it in the same
+// plan() as every other harness — one PLAN, one question, one APPLY (the
+// ADR "One front door: projectstore setup installs every harness it finds;
+// shells are release artifacts, not user commands", decision 3; the story
+// "Install and upgrade fetch a shell-rooted harness at the bin's own version,
+// once per run; plan and uninstall never fetch", rules 1–4 and 9).
+//
+//   rootVersion(root)                 → <root>/package.json's version, or null
+//   fetchDecision({…})                → { fetch, why } — rule 1, pure
+//   fetchArgv({ prefix, registry, … }) → rule 2's npm argv, plan's and the run's
+//   npmRegistry(projectDir, { env })  → the registry npx would see there, or null
+//   npmUserRegistry({ home, env })    → the user's own registry, read from home, or null
+//   fetchShell(job, { dir, registry }) → { ok, root, ms } or { ok: false, code, refusal }
+//   verifyFetched(root, { … })        → null, or the refusal naming file and values
+//   fetchRefusal(code, ctx)           → rule 4's texts
+//   sweepFetchRuns(fetchDir)          → the leftovers of dead runs, removed
+//   fetchRunId()                      → <pid>-<epoch ms>
+//
+// Nothing here decides a registration's rows: the analyser and the installer
+// do, from the fetched root this module hands them. Only install-harness.mjs
+// imports this file; hooks, doctor, surfaces and lib never do (the
+// portability suite asserts it). Pure node, no external deps.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { registrationDeferred } from "./harness.mjs";
+import { removeTreeUnder, pidAlive, whichOnPath } from "./lib.mjs";
+import { isPortablePluginRoot, payloadManifest, payloadManifestPath, payloadManifestPaths } from "./portable-registration.mjs";
+import { runHost, startFailure, HOST_BUDGET_MS } from "./run-host.mjs";
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+
+// The version a shell-rooted harness is fetched at has one source: the
+// package.json of the root the plan runs from — never `latest`, never a range.
+export function rootVersion(root) {
+  const v = readJson(join(String(root || ""), "package.json"))?.version;
+  return typeof v === "string" && v ? v : null;
+}
+
+// The core's own package name, which the fetched shell bundles under its
+// node_modules (the shells ADR: the shell pins the core exactly).
+export function rootName(root) {
+  const n = readJson(join(String(root || ""), "package.json"))?.name;
+  return typeof n === "string" && n ? n : null;
+}
+
+const STAGING_VERBS = ["install", "upgrade", "setup"];
+
+// Rule 1, as one pure decision per harness. A run fetches a harness's shell
+// only when every condition holds; the first that fails is `why`, which the
+// tests read and nothing prints (the row a skipped fetch shows is the
+// installer's, rule 1's table).
+//   verb         — the run stages: install or upgrade (and setup, when it lands)
+//   harness, s   — the manifest and its registration surface
+//   excluded     — --no-register, or a --surface that does not name it
+//   named        — a harness was named: the confirmation without a terminal
+//   interactive  — a person at a terminal will be asked (isInteractive, or `ask`)
+//   analysis     — a version-only analysis of the registration
+//   ownShell     — the run is this harness's own shell's core (rule 8)
+//   env          — the run's: a named distribution root, a session marker or a
+//                  registration_defer_env variable
+export function fetchDecision({ verb, harness, s, excluded = false, named = false, interactive = false, analysis = null, ownShell = false, env = process.env } = {}) {
+  if (!STAGING_VERBS.includes(verb)) return { fetch: false, why: "verb" };
+  if (s?.condition !== "distribution_root" || !harness?.install?.shell) return { fetch: false, why: "not-shell-rooted" };
+  if (excluded) return { fetch: false, why: "excluded" };
+  // A set root is used as is — a root or not — and nothing is fetched.
+  if (env && env.PROJECTSTORE_DISTRIBUTION_ROOT) return { fetch: false, why: "root-named" };
+  // A bare run that cannot be asked refuses at the gate; its preview is the dry run.
+  if (!named && !interactive) return { fetch: false, why: "not-interactive" };
+  // The registration defers in the harness's own session (decision 2) — by
+  // its session marker or its registration_defer_env (the setup story, rule
+  // 15) — and the fetch is skipped for a registration that will defer.
+  if (registrationDeferred(env, harness)) return { fetch: false, why: "in-session" };
+  // The host's facts alone decide these rows; a payload would change none.
+  if (["unavailable", "foreign", "conflict"].includes(analysis?.state)) return { fetch: false, why: analysis.state };
+  // A registration newer than the running version is never staged over (the
+  // converge story's rule 6): its row is the newer rung's, sound or damaged,
+  // decided from the version and the host's facts alone.
+  if (analysis?.newer) return { fetch: false, why: "newer" };
+  // No host CLI: the row defers whatever of ours exists, so a fetch — which
+  // may fail offline — must not turn a deferral into a refusal (the ADR: the
+  // fetch is skipped for a harness whose registration will defer).
+  if (!analysis?.bin) return { fetch: false, why: "no-host-cli" };
+  if (ownShell) return { fetch: false, why: "own-shell" };
+  return { fetch: true, why: null };
+}
+
+// Rule 2's argv, after `npm`. One builder for plan's dry-run step (literal
+// <run-id> and <registry>) and the run's own fetch. --prefix hides a
+// project's .npmrc, so only the registry is forwarded; with none resolved,
+// npm resolves it from user config. The four --fetch-… flags bound one
+// request to about 96 s and a refused connection to about 6 s (npm 11.19's
+// defaults wait 10 s, then 60 s: 70.3 s measured); the run's own budget is the
+// outer bound. --ignore-scripts: no install-time code from a registry runs.
+export function fetchArgv({ prefix, registry = null, shell, version }) {
+  return [
+    "install", "--prefix", prefix, "--no-save", "--ignore-scripts", "--no-audit", "--no-fund", "--no-update-notifier", "--json",
+    ...(registry ? ["--registry", registry] : []),
+    "--fetch-timeout=30000", "--fetch-retries=2", "--fetch-retry-mintimeout=1000", "--fetch-retry-maxtimeout=5000",
+    `${shell}@${version}`,
+  ];
+}
+
+// Node runs a .cmd only through a shell, and a shell splits on spaces, so on
+// win32 the bin and every argument are quoted. Unverified, as the install
+// spec already says of Windows.
+const WIN = process.platform === "win32";
+const winQuote = (a) => `"${String(a).replace(/"/g, '""')}"`;
+function npmCall(argv, env) {
+  const resolved = whichOnPath("npm", env);
+  const bin = resolved || (WIN ? "npm.cmd" : "npm");
+  return { resolved, bin: WIN ? winQuote(bin) : bin, argv: WIN ? argv.map(winQuote) : argv, shell: WIN };
+}
+
+// The registry `npx` run in this project would see: one `npm config get
+// registry` with the project as its working directory, so a registry its
+// .npmrc names counts (npm walks up to the nearest package.json or
+// node_modules), and an outer npx's npm_config_registry outranks it as npm
+// ranks the environment above a file (measured). Null when the read fails or
+// runs past its own short budget — a local read that hangs must not add a
+// second 120 s to the fetch's — and the fetch then passes no --registry.
+// --no-update-notifier: npm otherwise asks the registry about itself here too.
+// Exported for the update notice.
+export const REGISTRY_BUDGET_MS = 10000;
+export async function npmRegistry(projectDir, { env = process.env, spawn, budget = REGISTRY_BUDGET_MS } = {}) {
+  const call = npmCall(["config", "get", "registry", "--no-update-notifier"], env);
+  const r = await runHost(call.bin, call.argv, { env, cwd: projectDir, budget, spawn, shell: call.shell });
+  if (r.error || r.status !== 0) return null;
+  const value = String(r.stdout || "").trim().split(/\r?\n/).pop()?.trim() || "";
+  return value && !/\s/.test(value) && value !== "undefined" ? value : null;
+}
+
+// The registry the user's npm resolves outside any project (the converge
+// story's rule 8, as amended 2026-10-09): `npm config get registry` run from
+// the home directory, with every lowercase npm_config_* variable removed from
+// its environment — what an outer npx injects into its child, and a user's
+// own lowercase variable too. Only the uppercase NPM_CONFIG_* survive, with
+// ~/.npmrc and the global npmrc. What chooses code before the question reads
+// this one: the update notice and rule 6's read. Only the previewed shell
+// fetch keeps the project's registry (npmRegistry, above). Null when the read
+// fails; the caller then uses the public registry.
+export async function npmUserRegistry({ home = null, env = process.env, spawn, budget = REGISTRY_BUDGET_MS } = {}) {
+  const clean = {};
+  for (const [k, v] of Object.entries(env || {})) if (!k.startsWith("npm_config_")) clean[k] = v;
+  return npmRegistry(home || process.cwd(), { env: clean, spawn, budget });
+}
+
+// npm's --json error, which it prints on stdout: { error: { code, summary,
+// detail } }. stderr is the fallback, read for its `npm error code X` line
+// only — npm's raw stderr, log path included, is never shown.
+export function npmError(stdout, stderr) {
+  try {
+    const e = JSON.parse(String(stdout || ""))?.error;
+    if (e && typeof e === "object") return { code: String(e.code || "") || null, summary: String(e.summary || "").trim(), detail: String(e.detail || "").trim() };
+  } catch {}
+  const code = String(stderr || "").match(/npm (?:error|ERR!) code (\S+)/)?.[1] || null;
+  const summary = String(stderr || "").split(/\r?\n/).map((l) => l.replace(/^npm (?:error|ERR!) ?/, "").trim()).find((l) => l && !/^code \S+$/.test(l) && !/complete log of this run/i.test(l)) || "";
+  return { code, summary, detail: "" };
+}
+
+const seconds = (ms) => `${Number((ms / 1000).toFixed(ms % 1000 ? 1 : 0))} s`;
+
+// Rule 4's refusals, by npm's code or ours. `ctx`: pkg ("<shell>@<v>"),
+// shell, registry (null: npm's own), display (the harness's display name),
+// budget, summary (npm's), cause (a start failure's), path/from/variable (the
+// cache). Every way out is a terminal command or a variable; none names a
+// version but the one this run is at.
+export function fetchRefusal(code, ctx = {}) {
+  const { pkg = "the shell", shell = "the shell", registry = null, display = "this harness", budget = HOST_BUDGET_MS, summary = "", cause = "", path = null, from = null, variable = null } = ctx;
+  const where = registry || "the registry npm resolves";
+  const without = `name --harness without ${display}`;
+  switch (code) {
+    case "ETARGET":
+    case "E404":
+      return `${pkg} is not on ${where} (npm ${code}); ${display} is registered from that shell at this exact version, and no other version is tried. Just released? The shell is published after the core, so retry in a few minutes. From a checkout at an unpublished version, point PROJECTSTORE_DISTRIBUTION_ROOT at the output of \`npm run shells:build -- --dev\` (dist/build/${shell}). Or ${without}.`;
+    // Our budget, not npm's: npm's own ETIMEDOUT (a socket) is any other code.
+    case "EBUDGET":
+      return `fetching ${pkg} from ${where} took longer than ${seconds(budget)} and was stopped. Retry, or ${without}.`;
+    case "FETCH_TIMEOUT":
+      return `npm gave up on ${ctx.url || where} (network timeout) while fetching ${pkg}. Retry, or ${without}.`;
+    case "E401":
+    case "E403":
+      return `${where} refused the credentials for ${pkg} (npm ${code}). A project .npmrc's token does not reach this fetch — only its registry does — so the registry's token must be in user config: ~/.npmrc, or an NPM_CONFIG_… variable. Or point PROJECTSTORE_DISTRIBUTION_ROOT at a ${shell} root obtained another way.`;
+    case "ESTART":
+      return `${cause}; ${display} is registered from its shell, which npm fetches. Put npm on PATH, or ${without}.`;
+    case "ENOCACHE":
+      return `the shell fetch has no cache directory: ${variable} is not an absolute path and the home directory is unknown. Set ${variable} to a writable directory, then run this again.`;
+    case "ECACHE":
+      return `the cache directory ${path} cannot be written (${ctx.errno || "error"}); it comes from ${from}. Set ${variable} to a writable directory, then run this again.`;
+    default:
+      return `npm could not fetch ${pkg} from ${where}: ${code || "an unknown error"}${summary ? ` — ${summary.split(/\r?\n/)[0]}` : ""}. ${display} is registered from its shell, which needs the network: retry once the registry is reachable, or ${without}.`;
+  }
+}
+
+// Rule 3: the fetched tree is what this run plans, before it is planned —
+// the shell's name and version, a plugin root by the analyser's own predicate,
+// its plugin manifest's name and version, and the bundled core at the same
+// version (the pairing the shells ADR promises: the core Codex runs is the
+// core this release rendered). Null when it holds; otherwise the refusal,
+// naming the file and both values. Nothing is staged either way.
+export function verifyFetched(root, { shell, version, pluginName, coreName }) {
+  const pkg = `${shell}@${version}`;
+  const mismatch = (file, what, got, want) => `the fetched ${pkg} is not what this run plans: ${file} has ${what} ${JSON.stringify(got ?? null)}, expected ${JSON.stringify(want)} — nothing is staged`;
+  const pkgFile = join(root, "package.json");
+  const shellPkg = readJson(pkgFile);
+  if (shellPkg?.name !== shell) return mismatch(pkgFile, "name", shellPkg?.name, shell);
+  if (shellPkg?.version !== version) return mismatch(pkgFile, "version", shellPkg?.version, version);
+  if (!isPortablePluginRoot(root)) return `the fetched ${pkg} is not a plugin root: neither ${payloadManifestPaths(root).join(" nor ")} exists — nothing is staged`;
+  // Exactly the shell's one manifest, the one the host validates: a root
+  // manifest would be read first and load no hooks, so it never passes.
+  const manifestFile = payloadManifestPath(root, "legacy");
+  const rootFile = payloadManifestPath(root, "root");
+  if (existsSync(rootFile)) return `the fetched ${pkg} carries ${rootFile}, which the host reads before ${manifestFile} and loads no hooks from — nothing is staged`;
+  const manifest = payloadManifest(root, { kind: "legacy" });
+  if (!manifest) return `the fetched ${pkg} has no readable plugin manifest at ${manifestFile} — nothing is staged`;
+  if (manifest.name !== pluginName) return mismatch(manifestFile, "name", manifest.name, pluginName);
+  if (manifest.version !== version) return mismatch(manifestFile, "version", manifest.version, version);
+  const coreFile = join(root, "node_modules", coreName, "package.json");
+  const core = readJson(coreFile);
+  if (core?.version !== version) return mismatch(coreFile, "version", core?.version, version);
+  return null;
+}
+
+// The fetch itself: npm, asynchronously, in `dir` (made by the caller), with
+// the run's environment. The payload root is computed, never read from npm's
+// output: npm's --json result printed it with one UUID-like segment redacted
+// as *** (measured). A failure is a refusal before the plan, never a fallback.
+export async function fetchShell({ harness, s, version, coreName }, { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS } = {}) {
+  const shell = harness.install.shell;
+  const pkg = `${shell}@${version}`;
+  const ctx = { pkg, shell, registry, display: harness.display_name, budget };
+  const call = npmCall(fetchArgv({ prefix: dir, registry, shell, version }), env);
+  const t0 = Date.now();
+  const r = await runHost(call.bin, call.argv, { env, cwd: dir, budget, spawn, shell: call.shell });
+  const ms = Date.now() - t0;
+  if (r.error) {
+    if (r.error.code === "ETIMEDOUT") return { ok: false, ms, code: "ETIMEDOUT", refusal: fetchRefusal("EBUDGET", ctx) };
+    return { ok: false, ms, code: r.error.code || "ESTART", refusal: fetchRefusal("ESTART", { ...ctx, cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }) }) };
+  }
+  if (r.status !== 0) {
+    const e = npmError(r.stdout, r.stderr);
+    // npm reports a request it gave up on as FETCH_ERROR, "network timeout
+    // at: <url>" (measured in review, 2026-10-08), not as ETIMEDOUT.
+    const timeout = e.code === "FETCH_ERROR" && /network timeout at:\s*(\S+)/.exec(e.summary);
+    if (timeout) return { ok: false, ms, code: e.code, refusal: fetchRefusal("FETCH_TIMEOUT", { ...ctx, url: timeout[1] }) };
+    return { ok: false, ms, code: e.code || `exit ${r.status}`, refusal: fetchRefusal(e.code, { ...ctx, summary: e.summary }) };
+  }
+  const root = join(dir, "node_modules", shell);
+  const wrong = verifyFetched(root, { shell, version, pluginName: s.plugin_name, coreName });
+  if (wrong) return { ok: false, ms, code: "EVERIFY", refusal: wrong };
+  return { ok: true, ms, root };
+}
+
+// <pid>-<epoch ms>: the run that owns a scratch directory, by its name.
+export function fetchRunId() {
+  return `${process.pid}-${Date.now()}`;
+}
+
+// Rule 9's sweep, run by the next fetching run: every <fetch>/<pid>-<ms>
+// whose pid is dead goes. A live pid — ours or not (EPERM) — keeps its
+// directory, which may be a run waiting at its question for days, and any
+// other name stays. No age rule: a reused pid keeps a leftover until a later
+// sweep, which costs about 1.4 MB, never data. An npm still writing into a
+// dead run's directory is caught by a later sweep: it converges.
+export function sweepFetchRuns(fetchDir) {
+  let names;
+  try { names = readdirSync(fetchDir); } catch { return []; }
+  const removed = [];
+  for (const n of names) {
+    const m = /^(\d+)-\d+$/.exec(n);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (!pid || pid === process.pid || pidAlive(pid)) continue;
+    try { removeTreeUnder(join(fetchDir, n), fetchDir, { maxRetries: 3 }); removed.push(n); } catch {}
+  }
+  return removed;
+}

package/node_modules/projectstore/scripts/harness.mjs

@@ -24,8 +24,8 @@
 //
 // Pure node, no external deps — same constraint as lib.mjs. Read-only.
 
-import { readFileSync, existsSync, readdirSync, realpathSync } from "node:fs";
-import { join, dirname, resolve, sep } from "node:path";
+import { readFileSync, existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, dirname, resolve, sep, relative, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
@@ -226,25 +226,141 @@ export function resetDetection() {
 // process" from branded environment variables, and using it here would
 // conjure .claude/ for a Codex user. Not memoised: it is per directory, and a
 // test builds a project per case.
-export function detectHarnesses(projectDir, { dir = MANIFEST_DIR } = {}) {
+//
+// `state` adds the second signal `upgrade` reads: a harness whose state
+// directory of ours exists (layoutPaths(p).harnessState(id), layout spec
+// contract 5). A Codex session wrote its welcome marker there, so Codex is
+// used here even with no .codex/ (measured in this repository, 2026-10-08).
+// Never a machine-global registration: one exists for every project on the
+// machine and would select its harness everywhere. One entry per manifest,
+// the directory first, in manifest order as before.
+export function detectHarnesses(projectDir, { dir = MANIFEST_DIR, state = false } = {}) {
   const out = [];
+  const p = state ? layoutPaths(projectDir, { dir }) : null;
   for (const m of loadHarnesses(dir).values()) {
     const d = m.runtime?.harness_dir;
-    if (d && existsSync(join(projectDir, d))) out.push({ id: m.id, why: "directory", evidence: d });
+    if (d && existsSync(join(projectDir, d))) { out.push({ id: m.id, why: "directory", evidence: d }); continue; }
+    if (!p) continue;
+    const at = p.harnessState(m.id);
+    let isDir = false;
+    try { isDir = statSync(at).isDirectory(); } catch {}
+    if (isDir) out.push({ id: m.id, why: "state", evidence: relative(projectDir, at) });
   }
   return out;
 }
 
+// A pure PATH walk for a host binary — a read, not a subprocess: the analysers
+// run on every doctor call. Returns the absolute path or null. It lives here,
+// beside hostPresence, which needs it; lib.mjs re-exports it under the name
+// it already published.
+export function whichOnPath(name, env = process.env) {
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const dir of String(env.PATH || "").split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const p = join(dir, name + ext);
+      try { const st = statSync(p); if (st.isFile() && (process.platform === "win32" || (st.mode & 0o111))) return p; } catch {}
+    }
+  }
+  return null;
+}
+
+// Whether a harness's host is on this MACHINE (the story "projectstore setup
+// asks, shows one plan and installs every harness it finds, with the vault",
+// rule 5): its registration surface's CLI found on PATH, and its home
+// directory present — the manifest's home variable when set, else
+// <home>/<home_default>. Not detectHarnesses, which answers for a PROJECT, and
+// not detectHarnessId, which names the harness running this process. Setup's
+// pre-tick is the one place machine presence counts; install keeps contract 8.
+// Every name comes from the manifest. Read-only: a stat per PATH entry and one
+// for the home.
+//   → { cli, home, bin, homeDir }: `cli` is the absolute path found, or null;
+//     `home` the directory when it exists, or null. `bin` and `homeDir` are
+//     what was looked for (null when the manifest names none), so a reason can
+//     name them when either is missing.
+export function hostPresence(manifest, { env = process.env, home = homedir() } = {}) {
+  const s = Object.entries(manifest?.surfaces || {}).find(([k, x]) => !k.startsWith("_") && x?.kind === "registration" && x.supported !== false && typeof x.cli?.bin === "string" && x.cli.bin)?.[1] || null;
+  const bin = s ? s.cli.bin : null;
+  const r = manifest?.runtime || {};
+  const fromEnv = r.home_env && env ? env[r.home_env] : null;
+  const homeDir = fromEnv || (home && r.home_default ? join(home, r.home_default) : null);
+  let present = false;
+  if (homeDir) { try { present = statSync(homeDir).isDirectory(); } catch {} }
+  return { cli: bin ? whichOnPath(bin, env || {}) : null, home: present ? homeDir : null, bin, homeDir };
+}
+
+// The agents block of a RUN (the story "One run plans the agents block once,
+// and a bare uninstall selects every harness the project uses", rules 1–2):
+// the files every manifest of the run names for it, in the FIRST manifest's
+// order. The block is written to the first of them, so it lands where every
+// harness of the run can read it, natively or through the import the run
+// creates. One manifest gives its own list unchanged, which is what keeps a
+// single-harness plan as it was.
+export function commonBlockFiles(manifests) {
+  const lists = manifests.map((m) => agentsBlockRow(m)?.[1].files || []);
+  if (!lists.length) return [];
+  return lists[0].filter((f) => lists.every((l) => l.includes(f)));
+}
+
+// A manifest's agents-block row as [key, surface], or null: found by its
+// format, as the installer's handlers are keyed, never by the key's name.
+export function agentsBlockRow(manifest) {
+  return Object.entries(manifest?.surfaces || {}).find(([k, s]) => !k.startsWith("_") && s?.format === "markdown-block") || null;
+}
+
+// Rule 2, for the schema test: the manifests' lists share a file, or a run of
+// all of them has nowhere to write the block. Null when they do; otherwise
+// the problem, naming each manifest's list.
+export function blockTargetProblem(manifests) {
+  const withBlock = manifests.filter((m) => agentsBlockRow(m));
+  if (commonBlockFiles(withBlock).length) return null;
+  return `the agents-block files lists share no file, so a run of every harness has no file to write the block to: ${withBlock.map((m) => `${m.id} ${JSON.stringify(agentsBlockRow(m)[1].files || [])}`).join(", ")}`;
+}
+
 // The refusal when nothing is detected and nothing is named — built from the
-// manifests, so a new harness appears in it without an edit here.
-export function harnessRefusal(projectDir, dir = MANIFEST_DIR) {
+// manifests, so a new harness appears in it without an edit here. With
+// `state` (upgrade's set) it names both signals the selection read.
+export function harnessRefusal(projectDir, { dir = MANIFEST_DIR, state = false } = {}) {
   const lines = [`No harness detected in ${projectDir}, and none named. Name one:`];
+  const p = state ? layoutPaths(projectDir, { dir }) : null;
   for (const m of loadHarnesses(dir).values()) {
-    lines.push(`  --harness ${m.id}    (${m.display_name}; detected by its project directory: ${m.runtime?.harness_dir || "?"})`);
+    const by = `detected by its project directory: ${m.runtime?.harness_dir || "?"}`;
+    lines.push(`  --harness ${m.id}    (${m.display_name}; ${p ? `${by}, or by its state directory: ${relative(projectDir, p.harnessState(m.id))}` : by})`);
   }
   return lines.join("\n");
 }
 
+// Inside a live session of the host, its CLI and the session both rewrite the
+// same settings files on their own schedules; the registration is planned
+// only from a terminal outside one. The host marks its sessions in the
+// environment (manifest runtime.session_env). It lives here, beside
+// detection, so the installer and the shell fetch read one predicate without
+// an import cycle.
+export function insideHostSession(env, harness) {
+  // runtime.session_env, not detect_env: a Bash tool inside a session carries
+  // the session marker, not the plugin-root variables a hook receives
+  // (measured 2026-09-05; the critic's third pass caught the first draft
+  // keying on detect_env, which never fired in a session).
+  return (harness?.runtime?.session_env || []).some((k) => env && env[k]);
+}
+
+// Whether a harness's registration — and the shell fetch that would feed it —
+// defers in this environment (the setup story, rule 15: the front-door ADR's
+// first open question, answered by the maintainer on 2026-10-08). It defers
+// inside the harness's own session (insideHostSession, runtime.session_env),
+// or while one of its runtime.registration_defer_env variables is set. That
+// second list defers the registration and the fetch and nothing else:
+// isInteractive, the layout move and session identity read session_env alone.
+// Codex's exec tool sets CODEX_THREAD_ID in every command (measured
+// 2026-10-05), while its session_env stays empty so the doctor skill's
+// `upgrade --json` still moves the layout there. Keyed on the PLANNED
+// harness's manifest: inside one host's session another host's registration
+// does not defer.
+export function registrationDeferred(env, harness) {
+  if (insideHostSession(env, harness)) return true;
+  return (harness?.runtime?.registration_defer_env || []).some((k) => env && env[k]);
+}
+
 export function activeHarness(env = process.env, dir = MANIFEST_DIR) {
   return loadHarness(detectHarnessId(env, dir), dir) || sourceHarness(dir);
 }
@@ -516,6 +632,34 @@ export function layoutPaths(projectDir, { harnessDir = null, dir = MANIFEST_DIR
   };
 }
 
+// ─── The user-level cache (layout spec contract 0, the user-level class) ─
+//
+// What is ours on the machine but belongs to no project and no harness home:
+// the shell fetch's scratch (<root>/fetch/<pid>-<ms>/, removed when its run
+// ends) and the registry answer the update notice caches for a day
+// (<root>/registry.json, named now and read by no one yet). The XDG Base
+// Directory spec puts a cache at $XDG_CACHE_HOME when that is an absolute
+// path and ignores a relative one; an empty one is ignored too. Otherwise it
+// is <home>/.cache. With neither, `root` is null and the fetch refuses. This
+// is the one place either name is spelled (contract 0's grep): `from` and
+// `variable` carry them into a refusal's text. env and home are always
+// parameters.
+export function cachePaths({ env = process.env, home = homedir() } = {}) {
+  const variable = "XDG_CACHE_HOME";
+  const xdg = env ? env[variable] : null;
+  const fromEnv = typeof xdg === "string" && xdg !== "" && isAbsolute(xdg);
+  const base = fromEnv ? xdg : (home ? join(home, ".cache") : null);
+  const root = base ? join(base, "projectstore") : null;
+  return {
+    root,
+    fetch: root ? join(root, "fetch") : null,
+    fetchRun: (id) => (root ? join(root, "fetch", id) : null),
+    registry: root ? join(root, "registry.json") : null,
+    from: fromEnv ? variable : "the home directory",
+    variable,
+  };
+}
+
 // The command a user types from a terminal for this harness (the layout ADR
 // decision 6; layout spec contract 12): the harness's distribution shell when
 // the manifest names one — `npx projectstore-claude install --project "…"`,
@@ -531,6 +675,17 @@ export function packageCommand(harness, verb, { version = null, args = "" } = {}
   return `npx ${pkg} ${verb}${fixed}${args ? ` ${args}` : ""}`;
 }
 
+// The package this run was invoked as, for a command it prints to be typed
+// next: the shell it came through (the shell's bin sets PROJECTSTORE_SHELL,
+// and fixes the harness, so a verb that takes --harness needs none), else the
+// core. packageCommand() above is the install family's, per harness; this one
+// is for the verbs that name no harness (bind, status, scaffold, reconcile),
+// which every shell passes through. `npx` runs it with no bin on PATH.
+export function invokedAs(env = process.env) {
+  const shell = env.PROJECTSTORE_SHELL || null;
+  return { shell, cmd: shell ? `npx ${shell}` : "npx projectstore" };
+}
+
 // 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.
@@ -552,6 +707,22 @@ export function harnessForOverlay(key, dir = MANIFEST_DIR) {
   return all.find((m) => m.runtime?.overlay === key) || all.find((m) => m.id === key) || null;
 }
 
+// Whether a harness draws the band above the prompt (the band spec, contract
+// 1): the one predicate for "a harness without a band", read by the generator
+// (which keeps the module out of such a harness's tree) and by `band status`.
+export function hasBand(manifest) {
+  return manifest?.surfaces?.band?.supported === true;
+}
+
+// The session id the host hands a tool process, by the manifest's name for
+// it (runtime.session_id_env), or null where the harness names none or the
+// process got none.
+export function hostSessionId(env = process.env, harness = activeHarness(env)) {
+  const k = harness?.runtime?.session_id_env;
+  const v = k && env ? env[k] : null;
+  return typeof v === "string" && v ? v : null;
+}
+
 // A reader's fallback: the new path when it exists, else the legacy one when
 // THAT exists, else the new path (a writer's target) — at most two existsSync
 // calls, never a directory scan (contract 1; the SessionStart budget).