heyspex 0.2.2 → 0.2.3

package/scripts/lib/customer-kit.mjs

@@ -410,8 +410,16 @@ const LAUNCHER_TEMPLATE = [
   '//   4. node_modules/heyspex up from $__ENV__, $CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR, cwd',
   '//   5. <npm root -g>/heyspex                    a global install, last resort',
   '// Nothing found -> one stderr line and exit 0 (fail-open, like the shim itself).',
+  '//',
+  '// The same resolution starts the package\'s other entrypoints, so no committed',
+  '// file names node_modules/heyspex directly and a repo with no node_modules of',
+  '// its own still works off a global install:',
+  '//   --mcp         the stdio MCP server          (.mcp.json, .cursor/mcp.json)',
+  '//   --statusline  the Claude Code status line   (statusLine.command)',
+  '//   --resolve     print the package root, exit 0; exit 1 when none (hs doctor)',
   "import { spawnSync } from 'node:child_process';",
-  "import { existsSync } from 'node:fs';",
+  "import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';",
+  "import { homedir } from 'node:os';",
   "import { dirname, resolve } from 'node:path';",
   "import { fileURLToPath, pathToFileURL } from 'node:url';",
   '',
@@ -421,6 +429,7 @@ const LAUNCHER_TEMPLATE = [
   'const text = (v) => (typeof v === \'string\' && v.trim() ? v.trim() : null);',
   'const hasShim = (root) => Boolean(root) && existsSync(resolve(root, ...SHIM));',
   '',
+  '__YIELD__',
   'function packageUpFrom(start) {',
   '  let dir = resolve(start);',
   '  for (;;) {',
@@ -455,39 +464,146 @@ const LAUNCHER_TEMPLATE = [
   '  if (hasShim(global)) root = global;',
   '}',
   '',
+  'const ENTRYPOINTS = {',
+  "  '--mcp': 'vendor/heyspex-mcp/cli.mjs',",
+  "  '--statusline': 'scripts/claude-statusline/statusline-command.mjs',",
+  '};',
+  'const mode = process.argv[2];',
+  'const entry = Object.hasOwn(ENTRYPOINTS, mode) ? ENTRYPOINTS[mode] : null;',
+  '',
   'if (!root) {',
+  "  const what = entry || mode === '--resolve' ? mode : 'hook ' + (mode ?? '?');",
   '  process.stderr.write(',
-  "    '[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: no heyspex package found ' +",
-  "      '(run \"npm install heyspex\" in this repo, or set HEYSPEX_PLATFORM_ROOT). Looked for __SHIM__ under ' +",
-  "      'HEYSPEX_PLATFORM_ROOT, HEYSPEX_MCP_ENTRY, node_modules/heyspex up from ' + starts.join(', ') + ', and npm root -g.\\n',",
+  "    '[heyspex] ' + what + ' skipped: no heyspex package found ' +",
+  "      '(run \"npm install heyspex\" or \"npm link heyspex\" in this repo, install it globally, or set HEYSPEX_PLATFORM_ROOT). ' +",
+  "      'Looked for __SHIM__ under HEYSPEX_PLATFORM_ROOT, HEYSPEX_MCP_ENTRY, node_modules/heyspex up from ' + starts.join(', ') + ', and npm root -g.\\n',",
   '  );',
+  '  // Hooks and the status line fail open; the MCP server and --resolve fail',
+  '  // loudly, so the client and hs doctor both see it.',
+  "  process.exit(mode === '--mcp' || mode === '--resolve' ? 1 : 0);",
+  '}',
+  "if (mode === '--resolve') {",
+  "  process.stdout.write(root + '\\n');",
   '  process.exit(0);',
   '}',
   '',
   '// argv is already [node, <this file>, <hook>, ...args] -- the shape the shim',
-  '// reads; the shim path replaces this file so a shim guarded by "am I main?"',
-  '// (the Cursor one) runs exactly as if Cursor had invoked it directly.',
-  'const shim = resolve(root, ...SHIM);',
-  'process.argv[1] = shim;',
+  '// reads; the target replaces this file so a script guarded by "am I main?"',
+  '// runs exactly as if it had been invoked directly. Real path, so that guard',
+  '// still matches when node_modules/heyspex is an npm link or a junction (node',
+  '// realpaths import.meta.url but leaves argv[1] alone).',
+  'let target = resolve(root, ...(entry ? entry.split(\'/\') : SHIM));',
+  'try {',
+  '  target = realpathSync(target);',
+  '} catch {',
+  '  // keep the resolved path',
+  '}',
+  'if (entry) process.argv.splice(2, 1);',
+  'process.argv[1] = target;',
   'try {',
-  '  await import(pathToFileURL(shim).href);',
+  '  await import(pathToFileURL(target).href);',
   '} catch (err) {',
-  "  process.stderr.write('[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  "  process.stderr.write('[heyspex] ' + (entry ? mode : 'hook ' + (process.argv[2] ?? '?')) + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  '  // Hooks and the status line fail open; the MCP server fails loudly.',
+  "  if (mode === '--mcp') process.exit(1);",
   '  process.exit(0);',
   '}',
   '',
 ].join('\n');
 
+/**
+ * Version marker the Claude launcher carries once it yields to the plugin.
+ * Bumping the version changes the rendered text, so
+ * {@link planCustomerLauncherWrite} rewrites every older launcher exactly
+ * once and is idempotent after that; {@link detectDoubleFire} reads it to
+ * tell a yielding launcher from a pre-yield one.
+ */
+export const LAUNCHER_YIELD_MARKER = '// yields-to-plugin: v1';
+const LAUNCHER_YIELD_MARKER_RE = /^\/\/ yields-to-plugin: v\d+/m;
+
+/** Whether a launcher's text (any version) yields to an enabled heyspex plugin. */
+export function launcherYieldsToPlugin(text) {
+  return typeof text === 'string' && LAUNCHER_YIELD_MARKER_RE.test(text.replace(/\r\n/g, '\n'));
+}
+
+// THE YIELD (Claude surface only; Cursor has no heyspex plugin). The design rule is ONE source of
+// hooks per repo (plugins/heyspex/README.md "One source of hooks: plugin OR repo hooks, never
+// both"), but `hs install` commits the repo rows for every teammate while the plugin is a
+// per-MACHINE choice (`hs setup copilot`, `/plugin install`), so the committed file cannot decide
+// per machine at install time -- it decides at run time instead: when the plugin is enabled here,
+// the plugin's own launcher (plugins/heyspex/bin/run-hook.mjs, which resolves the platform shim
+// itself and never imports this file -- no recursion) already runs the hook, and this row exits 0
+// silently BEFORE resolving the package. Plugin evidence mirrors {@link detectDoubleFire}; an
+// explicit `enabledPlugins["heyspex@..."] === false` (user or project Claude settings) means the
+// plugin is off for this harness and the repo row runs; HEYSPEX_REPO_HOOKS=1 never yields.
+// Dependency-free and sync (a handful of small reads) so the cost per hook event stays negligible.
+const LAUNCHER_YIELD_BLOCK = [
+  LAUNCHER_YIELD_MARKER + ' -- one source of hooks: when the heyspex plugin is enabled on this machine',
+  '// its own launcher (plugins/heyspex/bin/run-hook.mjs, which never calls this file) already runs every',
+  '// hook, so this committed row exits 0 silently before resolving anything and each hook fires ONCE.',
+  '//   HEYSPEX_REPO_HOOKS=1                      never yield (the repo rows are the chosen source);',
+  '//   enabledPlugins["heyspex@..."] === false    in ~/.claude/settings.json or this repo\'s .claude/',
+  '//                                             settings[.local].json: plugin off here, the row runs;',
+  '//   plugin evidence (what `hs doctor` hook-double-fire reads): a heyspex@... key in',
+  '//     ~/.claude/plugins/installed_plugins.json, enabledPlugins naming heyspex with a non-false',
+  '//     value, or a heyspex directory under ~/.copilot/installed-plugins | ~/.copilot/plugins.',
+  'function readJson(file) {',
+  "  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return undefined; }",
+  '}',
+  'function listDir(dir) {',
+  '  try { return readdirSync(dir); } catch { return []; }',
+  '}',
+  'function pluginTakesThisHook() {',
+  '  const flag = text(env.HEYSPEX_REPO_HOOKS);',
+  "  if (flag && flag !== '0' && flag.toLowerCase() !== 'false') return false;",
+  '  const home = homedir();',
+  "  const repo = resolve(here, '..', '..');",
+  '  const isHeyspex = (k) => /^heyspex(@|$)/i.test(k);',
+  '  let enabled = false;',
+  "  for (const f of [resolve(home, '.claude', 'settings.json'), resolve(repo, '.claude', 'settings.json'), resolve(repo, '.claude', 'settings.local.json')]) {",
+  '    const settings = readJson(f);',
+  "    const ep = settings && typeof settings === 'object' ? settings.enabledPlugins : null;",
+  "    if (!ep || typeof ep !== 'object') continue;",
+  '    for (const [k, v] of Object.entries(ep)) {',
+  '      if (!isHeyspex(k)) continue;',
+  '      if (v === false) return false;',
+  '      enabled = true;',
+  '    }',
+  '  }',
+  '  if (enabled) return true;',
+  "  const installed = readJson(resolve(home, '.claude', 'plugins', 'installed_plugins.json'));",
+  "  if (installed && typeof installed === 'object' && Object.keys(installed.plugins && typeof installed.plugins === 'object' ? installed.plugins : installed).some(isHeyspex)) return true;",
+  "  for (const sub of ['installed-plugins', 'plugins']) {",
+  "    const dir = resolve(home, '.copilot', sub);",
+  '    const names = listDir(dir);',
+  '    if (names.some((n) => /heyspex/i.test(n))) return true;',
+  '    if (names.some((n) => listDir(resolve(dir, n)).some((m) => /heyspex/i.test(m)))) return true;',
+  '  }',
+  '  return false;',
+  '}',
+  '// Only a HOOK EVENT yields: --mcp / --statusline / --resolve and an agent-run',
+  '// `<script> --directive <key>` fetch are not hook events the plugin could run in',
+  '// our place, so they always go on to the package below.',
+  "const yieldMode = process.argv[2];",
+  "const notAHookEvent = ['--mcp', '--statusline', '--resolve'].includes(yieldMode) || process.argv.includes('--directive');",
+  'if (!notAHookEvent && pluginTakesThisHook()) process.exit(0);',
+  '',
+  '',
+].join('\n');
+
 /**
  * The launcher file `hs install` / `hs connect` write into a customer repo
  * (`.claude/heyspex/run-hook.mjs`; the Cursor copy at
  * `.cursor/heyspex/run-hook.mjs`). Pure: a string, no machine path in it.
+ * The Claude copy yields to an enabled heyspex plugin ({@link LAUNCHER_YIELD_MARKER}).
  * @param {'claude' | 'cursor'} [surface]
  */
 export function renderCustomerLauncher(surface = 'claude') {
   const l = CUSTOMER_LAUNCHERS[surface];
-  return LAUNCHER_TEMPLATE.replace(/__(REGISTRY|ENV|LAUNCHER|SHIM)__/g, (_m, token) =>
-    token === 'REGISTRY' ? l.registry : token === 'ENV' ? l.projectDirEnv : token === 'LAUNCHER' ? l.rel.join('/') : l.shim,
+  return LAUNCHER_TEMPLATE.replace('__YIELD__\n', surface === 'claude' ? LAUNCHER_YIELD_BLOCK : '').replace(
+    /__(REGISTRY|ENV|LAUNCHER|SHIM)__/g,
+    (_m, token) =>
+      token === 'REGISTRY' ? l.registry : token === 'ENV' ? l.projectDirEnv : token === 'LAUNCHER' ? l.rel.join('/') : l.shim,
   );
 }
 
@@ -798,18 +914,31 @@ const readJsonFile = (deps, file) => {
   }
 };
 
-/** @param {unknown} settings */
+/** A command routed through the committed customer launcher (`.claude/heyspex/run-hook.mjs`). */
+const CUSTOMER_LAUNCHER_COMMAND_RE = /\.claude\/heyspex\/run-hook\.mjs/;
+
+/**
+ * HeySpex rows in a parsed hooks document: how many, and how many of them go
+ * through the committed customer launcher (the rows that can yield).
+ * @param {unknown} settings
+ * @returns {{ n: number, viaLauncher: number }}
+ */
 function countOurRows(settings) {
   let n = 0;
+  let viaLauncher = 0;
   const hooks = settings && typeof settings === 'object' && settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
   for (const groups of Object.values(hooks)) {
     for (const g of Array.isArray(groups) ? groups : []) {
       // Claude shape: { matcher, hooks: [{ command }] }; Copilot .github/hooks shape: { bash } / { command }.
       const cmds = Array.isArray(g?.hooks) ? g.hooks.map((h) => h?.command) : [g?.command, g?.bash];
-      for (const c of cmds) if (typeof c === 'string' && (ourHookTail(c) !== null || /claude-hooks\/_run\.mjs/.test(c))) n++;
+      for (const c of cmds) {
+        if (typeof c !== 'string' || (ourHookTail(c) === null && !/claude-hooks\/_run\.mjs/.test(c))) continue;
+        n++;
+        if (CUSTOMER_LAUNCHER_COMMAND_RE.test(c.replace(/\\/g, '/'))) viaLauncher++;
+      }
     }
   }
-  return n;
+  return { n, viaLauncher };
 }
 
 /**
@@ -824,22 +953,26 @@ function countOurRows(settings) {
  * @param {{ targetRoot: string, home?: string, deps?: { readFile: (p: string) => string | null, listDir?: (p: string) => string[] } }} opts
  * @returns {{ status: 'ok' | 'warn' | 'unknown', detail: string, repoHooks: number, plugin: boolean | null, evidence: string[] }}
  */
-export function detectDoubleFire({ targetRoot, home = os.homedir(), deps = fsDeps }) {
+export function detectDoubleFire({ targetRoot, home = os.homedir(), copilotHome = path.join(home, '.copilot'), deps = fsDeps }) {
   const evidence = [];
   const repoFiles = ['.claude/settings.json', '.claude/settings.local.json'].map((f) => path.join(targetRoot, f));
   let repoHooks = 0;
+  let launcherRows = 0; // rows in .claude/settings*.json that go through the committed launcher
   for (const f of repoFiles) {
-    const n = countOurRows(readJsonFile(deps, f));
-    if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in ${f}`); }
+    const { n, viaLauncher } = countOurRows(readJsonFile(deps, f));
+    if (n) { repoHooks += n; launcherRows += viaLauncher; evidence.push(`${n} HeySpex hook row(s) in ${f}`); }
   }
   const ghDir = path.join(targetRoot, '.github', 'hooks');
   for (const name of (deps.listDir ? deps.listDir(ghDir) : []).filter((x) => x.endsWith('.json'))) {
-    const n = countOurRows(readJsonFile(deps, path.join(ghDir, name)));
+    const { n } = countOurRows(readJsonFile(deps, path.join(ghDir, name)));
     if (n) { repoHooks += n; evidence.push(`${n} HeySpex hook row(s) in .github/hooks/${name}`); }
   }
 
   let readable = 0;
   let plugin = false;
+  /** `enabledPlugins["heyspex@..."] === false` somewhere: the plugin is switched off for this harness. */
+  let disabledIn = null;
+  let copilotPlugin = false;
   const installed = readJsonFile(deps, path.join(home, '.claude', 'plugins', 'installed_plugins.json'));
   if (installed !== undefined) {
     readable++;
@@ -852,24 +985,29 @@ export function detectDoubleFire({ targetRoot, home = os.homedir(), deps = fsDep
     if (st === undefined) continue;
     if (f === userSettings) readable++; // a project file proves nothing about what is installed elsewhere
     const ep = st?.enabledPlugins;
-    if (ep && typeof ep === 'object' && Object.entries(ep).some(([k, v]) => /^heyspex(@|$)/i.test(k) && v !== false)) {
+    if (!ep || typeof ep !== 'object') continue;
+    const ours = Object.entries(ep).filter(([k]) => /^heyspex(@|$)/i.test(k));
+    if (ours.some(([, v]) => v !== false)) {
       plugin = true;
       evidence.push(`heyspex in enabledPlugins of ${f}`);
     }
+    if (ours.some(([, v]) => v === false)) disabledIn ??= f;
   }
   if (deps.listDir) {
     for (const sub of ['installed-plugins', 'plugins']) {
-      const dir = path.join(home, '.copilot', sub);
+      const dir = path.join(copilotHome, sub);
       const names = deps.listDir(dir);
       if (names.length) readable++;
       if (names.some((n) => /heyspex/i.test(n))) {
         plugin = true;
+        copilotPlugin = true;
         evidence.push(`heyspex under ${dir}`);
       } else {
         // one level deeper: <marketplace>/<plugin> layouts
         for (const n of names) {
           if (deps.listDir(path.join(dir, n)).some((m) => /heyspex/i.test(m))) {
             plugin = true;
+            copilotPlugin = true;
             evidence.push(`heyspex under ${path.join(dir, n)}`);
           }
         }
@@ -879,6 +1017,28 @@ export function detectDoubleFire({ targetRoot, home = os.homedir(), deps = fsDep
 
   if (repoHooks === 0) return { status: 'ok', detail: 'no repo-level HeySpex hooks to double up with a plugin', repoHooks, plugin: plugin || null, evidence };
   if (plugin) {
+    // The committed Claude launcher yields at run time when the plugin is enabled on this machine
+    // ({@link LAUNCHER_YIELD_MARKER}): every .claude/settings*.json row that goes through it fires once.
+    // Rows in .github/hooks/*.json never use the launcher, so any of those keeps the warning.
+    const launcher = deps.readFile(path.join(targetRoot, ...CUSTOMER_LAUNCHERS.claude.rel));
+    if (launcherRows === repoHooks && launcherYieldsToPlugin(launcher)) {
+      return {
+        status: 'ok',
+        detail: `repo launcher yields to the heyspex plugin on this machine — hooks fire once (${evidence.join('; ')})`,
+        repoHooks,
+        plugin: true,
+        evidence,
+      };
+    }
+    if (disabledIn && !copilotPlugin) {
+      return {
+        status: 'ok',
+        detail: `heyspex plugin installed but switched off (enabledPlugins false in ${disabledIn}) — the repo hooks are the one source`,
+        repoHooks,
+        plugin: true,
+        evidence,
+      };
+    }
     return {
       status: 'warn',
       detail: `HeySpex hooks are registered in the repo AND the heyspex plugin is installed, so every hook fires twice (${evidence.join('; ')})`,
@@ -990,14 +1150,30 @@ function shortHash(text) {
   return createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 16);
 }
 
+/**
+ * LINE ENDINGS. Every comparison and hash here is over LF text: a Windows
+ * clone with `core.autocrlf=true` checks the committed copy out with CRLF,
+ * and the canonical source itself may sit on such a checkout. The write
+ * layer (`spex-console/src/lib/cli/generated-file-eol.ts`) picks the EOL a
+ * file is written with; nothing in this module may let `\r\n` reach a hash
+ * or an equality test, or a CRLF file reads as "customized"/"stale" forever
+ * (the 0.2.2 kit did exactly that: `hs install` left 14 untouched commands
+ * alone as "customized" while `hs connect --check` reported them stale).
+ * @param {string | null | undefined} text
+ */
+export function normalizeEol(text) {
+  return text === null || text === undefined ? text : String(text).replace(/\r\n/g, '\n');
+}
+
 /**
  * The customer copy of a canonical command: platform paths made portable,
  * then a trailing marker carrying the hash of the body. The marker is how a
  * re-run tells "ours, untouched, safe to update" from "the customer edited
- * it, leave it alone".
+ * it, leave it alone". Always LF, whatever the canonical source's checkout
+ * used, so the hash is the same on every machine.
  */
 export function renderKitCommand(content, platformRoot) {
-  const body = `${rewritePlatformPaths(content, platformRoot).replace(/\s+$/, '')}\n`;
+  const body = `${rewritePlatformPaths(normalizeEol(content), platformRoot).replace(/\s+$/, '')}\n`;
   return (
     `${body}\n<!-- heyspex-kit: managed by hs install (sha256:${shortHash(body)}). ` +
     'Edit freely: once edited, hs install leaves this file alone. -->\n'
@@ -1005,27 +1181,44 @@ export function renderKitCommand(content, platformRoot) {
 }
 
 /**
+ * `managed`: carries the marker and the body still hashes to it — ours,
+ * untouched, from ANY kit version (the marker survives the render changing).
+ * `customized`: marker present but the body no longer hashes to it (a human
+ * edit). `unmanaged`: no marker at all.
+ *
+ * A marker is accepted over the LF body or over its CRLF form: the 0.2.2
+ * package rendered on a CRLF checkout and hashed the body with `\r\n` in
+ * it, then git normalised the committed copy to LF — those files are ours,
+ * never a customer edit.
  * @param {string} content
  * @returns {'managed' | 'customized' | 'unmanaged'}
  */
 export function kitFileState(content) {
-  const m = String(content).match(MARKER_RE);
+  const text = normalizeEol(String(content));
+  const m = text.match(MARKER_RE);
   if (!m) return 'unmanaged';
-  const body = String(content).slice(0, m.index).replace(/\n$/, '');
-  return shortHash(`${body}\n`) === m[1] ? 'managed' : 'customized';
+  const body = `${text.slice(0, m.index).replace(/\n$/, '')}\n`;
+  if (shortHash(body) === m[1]) return 'managed';
+  // Legacy CRLF-checkout render: the old renderer trimmed the trailing whitespace (the final
+  // `\r\n` with it) and appended `\n`, so it hashed inner CRLFs plus one final LF.
+  if (shortHash(`${body.slice(0, -1).replace(/\n/g, '\r\n')}\n`) === m[1]) return 'managed';
+  return 'customized';
 }
 
 /**
  * Whether to write one kit file. `raw` is the canonical (unrendered) content:
  * an existing file equal to it is an old verbatim copy (`hs connect
- * --fix-commands` before this change) and is safe to replace.
+ * --fix-commands` before this change) and is safe to replace. EOL-insensitive
+ * throughout ({@link normalizeEol}): a CRLF checkout of the rendered file is
+ * `unchanged`, a managed file from an older render is `update`.
  * @returns {{ write: boolean, reason: 'missing' | 'unchanged' | 'update' | 'legacy-copy' | 'customized' | 'forced' }}
  */
 export function planKitFileWrite({ existing, rendered, raw, force }) {
   if (existing === null || existing === undefined) return { write: true, reason: 'missing' };
-  if (existing === rendered) return { write: false, reason: 'unchanged' };
-  if (kitFileState(existing) === 'managed') return { write: true, reason: 'update' };
-  if (existing === raw) return { write: true, reason: 'legacy-copy' };
+  const have = normalizeEol(existing);
+  if (have === normalizeEol(rendered)) return { write: false, reason: 'unchanged' };
+  if (kitFileState(have) === 'managed') return { write: true, reason: 'update' };
+  if (have === normalizeEol(raw)) return { write: true, reason: 'legacy-copy' };
   return force ? { write: true, reason: 'forced' } : { write: false, reason: 'customized' };
 }
 

package/scripts/lib/dev-mode.mjs

@@ -127,6 +127,20 @@ export function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = def
   }
 }
 
+/**
+ * How a local override stands against the cloud admin setting:
+ *   'not-applicable' — no local override won the resolution;
+ *   'unverified'     — an override won, but the cloud setting could not be read;
+ *   'stale'          — the cloud setting was read and disagrees;
+ *   'in-sync'        — the cloud setting was read (or is known-unset) and agrees.
+ * Pure.
+ */
+export function overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== 'local-override') return 'not-applicable';
+  if (!cloudKnown) return 'unverified';
+  return staleAgainstCloud ? 'stale' : 'in-sync';
+}
+
 /**
  * Resolve the effective mode. `cloudSetting` is injected by the caller:
  *   { mode, reliance } when the account_settings.dev_mode value is known,
@@ -191,6 +205,11 @@ export function resolveDevMode({
     source === 'local-override' &&
     cloudValue !== null &&
     (cloudValue.mode !== mode || (mode === 'dev' && cloudValue.reliance !== semantics.reliance));
+  // `staleAgainstCloud: false` used to mean both "checked, agrees" and "never
+  // checked" — the cloud read failed (or went to localhost under a local
+  // override) and the override silently read as fresh. `cloudCheck` keeps the
+  // two apart: an override the cloud could not confirm is 'unverified'.
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
 
   return {
     mode,
@@ -211,6 +230,7 @@ export function resolveDevMode({
       record: local.record,
       parseError: local.parseError,
       staleAgainstCloud,
+      cloudCheck,
     },
     cloudSetting: { known: cloudKnown, value: cloudValue },
   };
@@ -429,9 +449,15 @@ async function discardResponseBody(res) {
   }
 }
 
-/** Best-effort GET of the cloud admin setting via the console API. */
+/**
+ * Best-effort GET of the cloud admin setting via the console API. The setting
+ * lives in the CLOUD console's account_settings, so the URL defaults to
+ * {@link CLOUD_CONSOLE_URL} — callers must NOT pass the resolved console URL,
+ * which under a local override is localhost and can never answer for the
+ * cloud (the staleness check then silently read "not stale").
+ */
 export async function fetchCloudDevMode({
-  consoleUrl,
+  consoleUrl = CLOUD_CONSOLE_URL,
   fetchImpl = fetch,
   homeDir = heyspexHome(),
   timeoutMs = 4000,

package/scripts/lib/shared-path-helpers.mjs

@@ -20,7 +20,9 @@
  * `scripts/verify-mcp-package.mjs`) because it is in the static import closure
  * of `vendor/heyspex-mcp/cli.mjs`.
  */
+import { realpathSync } from "node:fs";
 import { isAbsolute, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * Refuse to build a path under `root` when the root itself is not absolute, or
@@ -132,3 +134,33 @@ export function resolveCodeAndVaultRoots({ vaultRoot, explicit, packageRoot, env
   }
   return roots;
 }
+
+/**
+ * Is the module at `metaUrl` (its `import.meta.url`) the script node was
+ * started with? The naive `import.meta.url === pathToFileURL(process.argv[1]).href`
+ * fails through an `npm link` / junction / symlinked `node_modules/heyspex`:
+ * node realpaths the module for `import.meta.url` but leaves `argv[1]` as the
+ * link path, so the guard came out false and the script silently printed
+ * nothing and exited 0 (the satellite status line, [[HS-561M]] for `hs`).
+ * Realpath both sides; case-insensitive on Windows, where drive-letter casing
+ * differs between a shim-built path and what realpath reports.
+ * @param {string} metaUrl
+ */
+export function isMainModule(metaUrl) {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  const normalize = (p) => {
+    let real;
+    try {
+      real = realpathSync.native(p);
+    } catch {
+      real = resolve(p);
+    }
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  };
+  try {
+    return normalize(argv1) === normalize(fileURLToPath(metaUrl));
+  } catch {
+    return false;
+  }
+}