heyspex 0.2.2 → 0.2.3

package/dist/cli/hs-connect.mjs

@@ -154,9 +154,9 @@ function resolveBearer({ envToken, credentialsText, accountId, legacyAccountId }
   if (entry?.mcp_token) return { token: entry.mcp_token, source: "credentials-file" };
   return { token: null, source: null };
 }
-function readTextOrNull(read, path7) {
+function readTextOrNull(read, path9) {
   try {
-    const raw = read(path7);
+    const raw = read(path9);
     return typeof raw === "string" ? raw : null;
   } catch {
     return null;
@@ -260,6 +260,11 @@ function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile: readFile2 =
     return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
   }
 }
+function overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
 function resolveDevMode({
   env = process.env,
   homeDir = heyspexHome(),
@@ -299,6 +304,7 @@ function resolveDevMode({
   const semantics = deriveSemantics(mode, reliance);
   const consoleUrl = source === "local-override" && local.record?.console_url ? local.record.console_url.replace(/\/+$/, "") : semantics.consoleUrl;
   const staleAgainstCloud = source === "local-override" && cloudValue !== null && (cloudValue.mode !== mode || mode === "dev" && cloudValue.reliance !== semantics.reliance);
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
   return {
     mode,
     reliance: semantics.reliance,
@@ -316,7 +322,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -996,19 +1003,19 @@ var require_gray_matter = __commonJS({
 });
 
 // spex-console/bin/hs-connect.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 import {
-  copyFileSync,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync6,
+  copyFileSync as copyFileSync2,
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync7,
   readdirSync as readdirSync3,
-  readFileSync as readFileSync11,
-  statSync,
-  writeFileSync as writeFileSync6
+  readFileSync as readFileSync14,
+  statSync as statSync5,
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import path6 from "node:path";
+import path8 from "node:path";
 import process4 from "node:process";
-import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { fileURLToPath as fileURLToPath5 } from "node:url";
 
 // scripts/lib/console-url-resolver.mjs
 init_heyspex_home();
@@ -1116,7 +1123,9 @@ function resolveConsoleUrl({
 }
 
 // scripts/lib/shared-path-helpers.mjs
+import { realpathSync } from "node:fs";
 import { isAbsolute, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 function resolveCodeRoot({
   explicit,
   packageRoot: packageRoot2,
@@ -1239,10 +1248,10 @@ function classifyHttpFailureReason(res) {
   if (res.status === 401) return "unauthorized";
   return "server-error";
 }
-async function cloudHttpRequest(http, method, path7, body) {
-  const scopeHeaders = http.scope ? http.scope.headersFor(method, path7) : {};
+async function cloudHttpRequest(http, method, path9, body) {
+  const scopeHeaders = http.scope ? http.scope.headersFor(method, path9) : {};
   try {
-    const res = await http.fetchImpl(`${http.consoleUrl}${path7}`, {
+    const res = await http.fetchImpl(`${http.consoleUrl}${path9}`, {
       method,
       headers: {
         "content-type": "application/json",
@@ -3014,12 +3023,12 @@ var SUSPENSION_ELAPSED_FACTOR = 3;
 var SUSPENSION_MIN_OVERSHOOT_MS = 5e3;
 var MAX_SUSPENSION_RETRIES = 2;
 function withTimeout(promise, ms, label) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const timer = setTimeout(() => reject(new NeonProbeTimeoutError(label, ms)), ms);
     promise.then(
       (value) => {
         clearTimeout(timer);
-        resolve5(value);
+        resolve6(value);
       },
       (err) => {
         clearTimeout(timer);
@@ -3038,7 +3047,7 @@ var NeonProbeTimeoutError = class _NeonProbeTimeoutError extends Error {
   }
 };
 function sleep(ms) {
-  return new Promise((resolve5) => setTimeout(resolve5, ms));
+  return new Promise((resolve6) => setTimeout(resolve6, ms));
 }
 function emitProbeFailure(options2, failure) {
   try {
@@ -4032,7 +4041,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path2 from "node:path";
 import os2 from "node:os";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
 
 // scripts/lib/hook-dispositions.mjs
 var HOSTS = Object.freeze(["claude-code", "cursor", "copilot"]);
@@ -4380,8 +4389,16 @@ var 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';",
   "",
@@ -4391,6 +4408,7 @@ var 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 (;;) {",
@@ -4425,31 +4443,109 @@ var 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");
+var LAUNCHER_YIELD_MARKER = "// yields-to-plugin: v1";
+var 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");
 function renderCustomerLauncher(surface = "claude") {
   const l = CUSTOMER_LAUNCHERS[surface];
-  return LAUNCHER_TEMPLATE.replace(
+  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
   );
@@ -4675,25 +4771,33 @@ var MARKER_RE = /\n<!-- heyspex-kit: managed by hs install \(sha256:([0-9a-f]{16
 function shortHash(text2) {
   return createHash("sha256").update(text2, "utf8").digest("hex").slice(0, 16);
 }
+function normalizeEol(text2) {
+  return text2 === null || text2 === void 0 ? text2 : String(text2).replace(/\r\n/g, "\n");
+}
 function renderKitCommand(content, platformRoot) {
-  const body = `${rewritePlatformPaths(content, platformRoot).replace(/\s+$/, "")}
+  const body = `${rewritePlatformPaths(normalizeEol(content), platformRoot).replace(/\s+$/, "")}
 `;
   return `${body}
 <!-- heyspex-kit: managed by hs install (sha256:${shortHash(body)}). Edit freely: once edited, hs install leaves this file alone. -->
 `;
 }
 function kitFileState(content) {
-  const m = String(content).match(MARKER_RE);
+  const text2 = normalizeEol(String(content));
+  const m = text2.match(MARKER_RE);
   if (!m) return "unmanaged";
-  const body = String(content).slice(0, m.index).replace(/\n$/, "");
-  return shortHash(`${body}
-`) === m[1] ? "managed" : "customized";
+  const body = `${text2.slice(0, m.index).replace(/\n$/, "")}
+`;
+  if (shortHash(body) === m[1]) return "managed";
+  if (shortHash(`${body.slice(0, -1).replace(/\n/g, "\r\n")}
+`) === m[1]) return "managed";
+  return "customized";
 }
 function planKitFileWrite({ existing, rendered, raw, force }) {
   if (existing === null || existing === void 0) 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" };
 }
 function listKitCommandFiles(platformRoot, deps, opts = {}) {
@@ -4737,14 +4841,14 @@ var fsDeps = {
 function invokedDirectly(importMetaUrl, selfBasename, argv1 = process.argv[1]) {
   try {
     if (!argv1) return false;
-    const self = fileURLToPath(importMetaUrl);
+    const self = fileURLToPath2(importMetaUrl);
     if (path2.basename(self) !== selfBasename) return false;
     return pathToFileURL(path2.resolve(argv1)).href === pathToFileURL(self).href;
   } catch {
     return false;
   }
 }
-var SELF = fileURLToPath(import.meta.url);
+var SELF = fileURLToPath2(import.meta.url);
 if (invokedDirectly(import.meta.url, "customer-kit.mjs")) {
   const platformRoot = path2.resolve(path2.dirname(SELF), "..", "..");
   const target = path2.join(platformRoot, "plugins", "heyspex", "hooks", "hooks.json");
@@ -4790,6 +4894,11 @@ import { join as join6 } from "node:path";
 init_credentials();
 var CLOUD_CONSOLE_URL2 = "https://app.heyspex.com";
 var LOCAL_CONSOLE_URL2 = "http://localhost:3000";
+function overrideCloudCheck2(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
 function normalizeMode2(raw) {
   const v = String(raw ?? "").trim().toLowerCase();
   if (v === "prod" || v === "production") return { mode: "prod", reliance: "cloud" };
@@ -4897,6 +5006,7 @@ function resolveDevMode2({
   const semantics = deriveSemantics2(mode, reliance);
   const consoleUrl = source === "local-override" && local.record?.console_url ? local.record.console_url.replace(/\/+$/, "") : semantics.consoleUrl;
   const staleAgainstCloud = source === "local-override" && cloudValue !== null && (cloudValue.mode !== mode || mode === "dev" && cloudValue.reliance !== semantics.reliance);
+  const cloudCheck = overrideCloudCheck2(source, cloudKnown, staleAgainstCloud);
   return {
     mode,
     reliance: semantics.reliance,
@@ -4914,7 +5024,8 @@ function resolveDevMode2({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -4950,16 +5061,16 @@ init_credentials();
 import { randomUUID } from "node:crypto";
 
 // spex-console/src/lib/cli/control-shared.ts
-import path3 from "node:path";
+import path4 from "node:path";
 
 // scripts/lib/hs-command.mjs
 import { existsSync as existsSync2 } from "node:fs";
 import { delimiter, dirname as dirname3, join as join7 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 var HS_BIN_NAME = "hs";
 var HS_DISPATCHER_PATH = (() => {
   try {
-    const here = dirname3(fileURLToPath2(import.meta.url));
+    const here = dirname3(fileURLToPath3(import.meta.url));
     return join7(dirname3(dirname3(here)), "bin", "hs.mjs");
   } catch {
     return null;
@@ -4973,8 +5084,8 @@ var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER
 // vendor/heyspex-mcp/console-fetch.mjs
 init_heyspex_home();
 init_credentials();
-import { readFileSync as readFileSync10 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
+import { readFileSync as readFileSync11 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
 import { join as join10 } from "node:path";
 
 // vendor/heyspex-mcp/vault-less-endpoints.mjs
@@ -4987,14 +5098,14 @@ var VAULT_LESS_ENDPOINTS = Object.freeze([
   "GET /api/workspaces",
   "* /api/admin/dev-mode"
 ]);
-function pathnameOf(path7) {
-  const raw = String(path7 ?? "").split("?")[0].split("#")[0];
+function pathnameOf(path9) {
+  const raw = String(path9 ?? "").split("?")[0].split("#")[0];
   const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
   return noTrailing || "/";
 }
-function isVaultLessEndpoint(method, path7) {
+function isVaultLessEndpoint(method, path9) {
   const m = String(method || "GET").toUpperCase();
-  const pathname = pathnameOf(path7);
+  const pathname = pathnameOf(path9);
   return VAULT_LESS_ENDPOINTS.some((row2) => {
     const [rowMethod, rowPath] = row2.split(" ");
     return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
@@ -5015,9 +5126,30 @@ import { basename, join as join8, isAbsolute as isAbsolute2 } from "node:path";
 
 // vendor/heyspex-mcp/vault-resolve.mjs
 init_heyspex_home();
-import { existsSync as existsSync4, readFileSync as readFileSync9 } from "node:fs";
-import { homedir as homedir7, tmpdir } from "node:os";
-import { dirname as dirname4, join as join9, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync10, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { homedir as homedir8, tmpdir } from "node:os";
+
+// vendor/heyspex-mcp/usable-dir-env.mjs
+import { statSync } from "node:fs";
+import { isAbsolute as isAbsolute3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { basename as basename2, dirname as dirname4, join as join9, resolve as resolve4 } from "node:path";
+
+// vendor/heyspex-mcp/vault-binding.mjs
+import {
+  copyFileSync,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync9,
+  realpathSync as realpathSync2,
+  renameSync as renameSync4,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync6
+} from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import path3 from "node:path";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
@@ -5119,11 +5251,11 @@ function readPairedBearer(opts = {}) {
 function readPairedToken(opts = {}) {
   return readPairedBearer(opts).token ?? void 0;
 }
-function scopeHeadersFor(scope, method, path7) {
+function scopeHeadersFor(scope, method, path9) {
   if (scope === "none") {
-    if (!isVaultLessEndpoint(method, path7)) {
+    if (!isVaultLessEndpoint(method, path9)) {
       throw new Error(
-        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path7} is vault-scoped and must name { accountId, vaultId }.`
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path9} is vault-scoped and must name { accountId, vaultId }.`
       );
     }
     return {};
@@ -5134,7 +5266,7 @@ function cloudRequestScope(scope) {
   const named = { accountId: scope.accountId, vaultId: scope.vaultId };
   return {
     ...named,
-    headersFor: (method, path7) => isVaultLessEndpoint(method, path7) ? {} : scopeHeadersFor(named, method, path7)
+    headersFor: (method, path9) => isVaultLessEndpoint(method, path9) ? {} : scopeHeadersFor(named, method, path9)
   };
 }
 function withCloudScope(deps, accountId, vaultId) {
@@ -5381,12 +5513,15 @@ var HELP = [
   "(spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
   "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
   "plus a generated CLAUDE.md, the kept-principles index, and the template_version",
-  "pin; with --git, one initial `git init` + commit. Rerunnable: a <dir> that already",
-  "holds heyspex.yaml and an empty/placeholder-only specs/ is accepted, existing",
-  "files are never overwritten (an existing CLAUDE.md gets a CLAUDE.md.template",
-  "beside it), and the result lists each manifest row as created or kept. Refuses a",
-  "non-empty <dir> without heyspex.yaml, or a specs/ holding managed specs.",
-  "See init.customer-vault.ts.",
+  "pin; with --git, one initial `git init` + commit. On an EXISTING vault (<dir>",
+  "holds heyspex.yaml with a vault_id) it is a REFRESH \u2014 the repair `hs doctor`'s",
+  "vault-template row names: only missing shipped files are added, template_version",
+  "is written/updated in heyspex.yaml (every other byte and the vault_id kept),",
+  "nothing existing is ever overwritten (an existing CLAUDE.md gets a",
+  "CLAUDE.md.template beside it), the result lists each manifest row as created or",
+  "kept, and a second run writes nothing. <dir> may be any path (a satellite repo",
+  "names its vault, e.g. `hs init --customer-vault ../my-specs`). Refuses only a",
+  "non-empty <dir> that has no heyspex.yaml. See init.customer-vault.ts.",
   "",
   "Flags:",
   "  --console-url <url>  console_url value (default: the mode-aware console --",
@@ -5650,9 +5785,9 @@ function detectMarkerAttachment(repoRoot, deps) {
 function readPinnedVaultRoot(repoRoot, deps) {
   const pins = [];
   for (const rel of SATELLITE_MANIFEST_RELS) {
-    const path7 = deps.joinPath(repoRoot, ...rel);
-    if (!deps.fileExists(path7)) continue;
-    const raw = deps.readFile(path7);
+    const path9 = deps.joinPath(repoRoot, ...rel);
+    if (!deps.fileExists(path9)) continue;
+    const raw = deps.readFile(path9);
     if (!raw) continue;
     let value;
     try {
@@ -5736,7 +5871,7 @@ function checkHarnessCommandDrift(repoRoot, deps) {
       const installedContent = deps.fileExists(installedPath) ? deps.readFile(installedPath) : null;
       if (installedContent === null) {
         out.missingFiles.push(`${label}/${f.file}`);
-      } else if (installedContent !== f.content) {
+      } else if (normalizeEol(installedContent) !== normalizeEol(f.content)) {
         out.staleFiles.push(`${label}/${f.file}`);
       }
     }
@@ -5756,8 +5891,8 @@ function row(id, label, present, detail) {
     ...detail ? { detail } : {}
   };
 }
-function readIfExists(deps, path7) {
-  return deps.fileExists(path7) ? deps.readFile(path7) : null;
+function readIfExists(deps, path9) {
+  return deps.fileExists(path9) ? deps.readFile(path9) : null;
 }
 var PRE_COMMIT_HOOK_MARKER = "run-pre-commit-checks.mjs";
 function hasHeyspexMcpEntry(raw) {
@@ -6067,12 +6202,12 @@ function runConnectChecks(repoRoot, deps, opts = {}) {
   };
 }
 var CLOUD_READ_TIMEOUT_MS = 8e3;
-async function cloudGet(http, token, path7) {
+async function cloudGet(http, token, path9) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CLOUD_READ_TIMEOUT_MS);
   timer.unref?.();
   try {
-    const res = await http.fetch(`${http.consoleUrl.replace(/\/+$/, "")}${path7}`, {
+    const res = await http.fetch(`${http.consoleUrl.replace(/\/+$/, "")}${path9}`, {
       method: "GET",
       headers: token ? { authorization: `Bearer ${token}` } : {},
       signal: controller.signal
@@ -6090,7 +6225,7 @@ async function cloudGet(http, token, path7) {
     clearTimeout(timer);
   }
 }
-function readFailure(read, path7, http) {
+function readFailure(read, path9, http) {
   if (read === null) {
     return {
       cause: "no sign-in token on this machine, so the console was not asked",
@@ -6106,9 +6241,9 @@ function readFailure(read, path7, http) {
     };
   }
   if (read.status === 401) {
-    return { cause: `GET ${path7} answered HTTP 401 (the sign-in was refused)`, repair: "hs login" };
+    return { cause: `GET ${path9} answered HTTP 401 (the sign-in was refused)`, repair: "hs login" };
   }
-  return { cause: `GET ${path7} answered HTTP ${read.status}`, repair: retry };
+  return { cause: `GET ${path9} answered HTTP ${read.status}`, repair: retry };
 }
 var str2 = (v) => typeof v === "string" && v ? v : null;
 function cloudRow(id, fields) {
@@ -6296,7 +6431,13 @@ async function defaultCheckMcpBuild(deps, opts) {
   }
 }
 var shortFp = (fp) => fp ? fp.slice(0, 12) : null;
-function hookScriptPath(command, repoRoot) {
+function hookScriptPath(command, repoRoot, joinPath) {
+  const bootstrap = /^\s*node\s+-e\s+"[^"]*\/\/([^"\s]+)"/.exec(command);
+  if (bootstrap) {
+    const rel = bootstrap[1].replace(/^\/+/, "");
+    if (rel === "bin/run-hook.mjs") return null;
+    return joinPath(repoRoot, ...rel.split("/"));
+  }
   const m = /^\s*node\s+(?:"([^"]+)"|(\S+))/.exec(command);
   const raw = m?.[1] ?? m?.[2];
   if (!raw) return null;
@@ -6330,7 +6471,7 @@ function hooksRow(repoRoot, deps) {
       const list = Array.isArray(group?.hooks) ? group.hooks : [];
       for (const h of list) {
         if (typeof h?.command !== "string" || ourHookTail(h.command) === null) continue;
-        const script = hookScriptPath(h.command, repoRoot);
+        const script = hookScriptPath(h.command, repoRoot, deps.joinPath);
         if (script) scripts.add(script);
       }
     }
@@ -6370,7 +6511,7 @@ async function mcpBuildRow(vaultSubject, deps) {
   );
 }
 async function readCloudView(http, tokens) {
-  const get = (token, path7) => http && token ? cloudGet(http, token, path7) : Promise.resolve(null);
+  const get = (token, path9) => http && token ? cloudGet(http, token, path9) : Promise.resolve(null);
   const [session, vaults2, workspaces2, devMode] = await Promise.all([
     get(tokens.current, "/api/mcp/session"),
     get(tokens.repo, "/api/vaults?include_archived=true"),
@@ -6381,9 +6522,9 @@ async function readCloudView(http, tokens) {
     cause: "no console URL configured for this machine",
     repair: "hs login"
   };
-  const fail = (read, path7) => http ? readFailure(read, path7, http) : noConsole;
-  const shapeFailure = (path7, what) => ({
-    cause: `GET ${path7} answered without ${what}`,
+  const fail = (read, path9) => http ? readFailure(read, path9, http) : noConsole;
+  const shapeFailure = (path9, what) => ({
+    cause: `GET ${path9} answered without ${what}`,
     repair: `retry \`hs connect --check\` once ${http?.consoleUrl ?? "the console"} answers`
   });
   const sessionBody = session?.ok ? session.json : null;
@@ -6691,7 +6832,7 @@ function writeProjectContract(ctx, options2 = {}) {
 }
 
 // spex-console/src/lib/cli/init.customer-vault.ts
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 
 // spex-console/src/lib/cli/template-manifest.sources.mjs
 var UNIVERSAL_TEMPLATE_ROWS = [
@@ -7176,41 +7317,42 @@ var SCAFFOLD_FOLDERS = [
   "checks",
   "events"
 ];
-var PLACEHOLDER_FILES = /* @__PURE__ */ new Set([".gitkeep"]);
-function isDir(deps, path7, name) {
-  if (deps.isDirectory) return deps.isDirectory(path7);
-  try {
-    const kids = deps.readdir(path7);
-    return kids.length > 0 || !name.includes(".");
-  } catch {
-    return false;
-  }
+function defaultVaultName(targetDir) {
+  return basename3(targetDir) || targetDir;
 }
-function findManagedSpecs(deps, targetDir, manifestDests) {
-  const out = [];
-  const walk = (abs, rel) => {
-    for (const name of deps.readdir(abs)) {
-      const childAbs = deps.joinPath(abs, name);
-      const childRel = `${rel}/${name}`;
-      if (isDir(deps, childAbs, name)) walk(childAbs, childRel);
-      else if (!PLACEHOLDER_FILES.has(name) && name.endsWith(".md") && !manifestDests.has(childRel))
-        out.push(childRel);
-    }
-  };
-  const specsRoot = deps.joinPath(targetDir, "specs");
-  if (deps.exists(specsRoot)) walk(specsRoot, "specs");
-  return out;
+function readTemplateVersionPin(yamlText) {
+  const m = yamlText.match(/^template_version:[ \t]*(.*?)[ \t]*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
 }
-function defaultVaultName(targetDir) {
-  return basename2(targetDir) || targetDir;
+function stampTemplateVersion(content, version) {
+  if (readTemplateVersionPin(content) === version) return content;
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const line = `template_version: ${version}`;
+  if (/^template_version:[^\r\n]*$/m.test(content)) {
+    return content.replace(/^template_version:[^\r\n]*$/m, line);
+  }
+  const body = content.replace(/(?:\r?\n)+$/, "");
+  return body.length === 0 ? `${line}${eol}` : `${body}${eol}${line}${eol}`;
+}
+function parentDirOf(deps, targetDir, dest) {
+  const segments = dest.split("/");
+  if (segments.length < 2) return null;
+  return deps.joinPath(targetDir, ...segments.slice(0, -1));
 }
 function runCustomerVaultInit(args, deps, options2 = {}) {
   const { targetDir } = args;
   const written = [];
   const filter = options2.manifestFilter ?? (() => true);
   const rows = TEMPLATE_MANIFEST.filter(filter);
+  const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
+  const markerPresent = deps.exists(targetDir) && deps.exists(heyspexYamlPath);
+  const existingYaml = markerPresent ? deps.readFile?.(heyspexYamlPath) ?? null : null;
+  const existingVaultId = existingYaml ? parseVaultId(existingYaml) : null;
+  const mode = markerPresent && existingVaultId ? "refresh" : "scaffold";
   if (deps.exists(targetDir)) {
-    const markerPresent = deps.exists(deps.joinPath(targetDir, "heyspex.yaml"));
     if (!markerPresent && deps.readdir(targetDir).length > 0) {
       return {
         code: EXIT.INVALID_ARG,
@@ -7220,43 +7362,43 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
         written: []
       };
     }
-    if (markerPresent) {
-      const manifestDests = new Set(TEMPLATE_MANIFEST.map((r) => r.dest));
-      const managed = findManagedSpecs(deps, targetDir, manifestDests);
-      if (managed.length > 0) {
-        return {
-          code: EXIT.INVALID_ARG,
-          message: `${targetDir}/specs already holds managed spec(s) (${managed.slice(0, 3).join(", ")}${managed.length > 3 ? ", ..." : ""}) \u2014 customer-vault init refuses to write over an existing vault.`,
-          payload: { ok: false, error: "specs_not_empty", path: targetDir, specs: managed },
-          isError: true,
-          written: []
-        };
-      }
-    }
   } else {
     deps.mkdirRecursive(targetDir);
   }
-  const specsRoot = deps.joinPath(targetDir, "specs");
-  deps.mkdirRecursive(specsRoot);
-  for (const folder of SCAFFOLD_FOLDERS) {
-    deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
+  if (mode === "scaffold") {
+    const specsRoot = deps.joinPath(targetDir, "specs");
+    deps.mkdirRecursive(specsRoot);
+    for (const folder of SCAFFOLD_FOLDERS) {
+      deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
+    }
   }
-  const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
   let vaultId;
-  if (deps.exists(heyspexYamlPath)) {
-    const existingYaml = deps.readFile?.(heyspexYamlPath) ?? null;
-    vaultId = (existingYaml ? parseVaultId(existingYaml) : null) ?? "";
+  let pin;
+  if (markerPresent) {
+    vaultId = existingVaultId ?? "";
+    const stamped = existingYaml === null ? null : stampTemplateVersion(existingYaml, TEMPLATE_VERSION);
+    if (stamped !== null && stamped !== existingYaml) {
+      deps.writeFile(heyspexYamlPath, stamped);
+      written.push(heyspexYamlPath);
+      pin = "written";
+    } else {
+      pin = "kept";
+    }
   } else {
     vaultId = mintVaultId();
     deps.writeFile(
       heyspexYamlPath,
-      renderHeyspexYaml({
-        consoleUrl: options2.consoleUrl ?? DEFAULT_CONSOLE_URL2,
-        vaultRoot: "specs/",
-        vaultId
-      })
+      stampTemplateVersion(
+        renderHeyspexYaml({
+          consoleUrl: options2.consoleUrl ?? DEFAULT_CONSOLE_URL2,
+          vaultRoot: "specs/",
+          vaultId
+        }),
+        TEMPLATE_VERSION
+      )
     );
     written.push(heyspexYamlPath);
+    pin = "written";
   }
   const readConfigSeed = deps.readConfigSeed;
   const configSeed = seedConfigYaml(
@@ -7272,6 +7414,10 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
       rowResults.push({ dest: row2.dest, action: "kept" });
       continue;
     }
+    if (mode === "refresh") {
+      const parent = parentDirOf(deps, targetDir, row2.dest);
+      if (parent && !deps.exists(parent)) deps.mkdirRecursive(parent);
+    }
     if (row2.classification === "universal-template") {
       const srcAbs = deps.joinPath(deps.platformRoot, ...row2.source.split("/"));
       deps.copyFile(srcAbs, destAbs);
@@ -7291,24 +7437,41 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
       targetDir,
       vaultName: options2.vaultName ?? defaultVaultName(targetDir),
       templateVersion: TEMPLATE_VERSION,
+      mode,
       manifestRows: rows,
       rows: rowResults,
       deps,
-      recordWrite: (path7) => {
-        written.push(path7);
+      recordWrite: (path9) => {
+        written.push(path9);
       }
     };
     for (const hook of options2.afterScaffold) hook(ctx);
   }
   const createdCount = rowResults.filter((r) => r.action === "created").length;
   const keptCount = rowResults.length - createdCount;
+  const added = rowResults.filter((r) => r.action === "created").map((r) => r.dest);
+  let message2;
+  if (mode === "refresh") {
+    const parts = [];
+    if (added.length > 0)
+      parts.push(`added ${added.length} missing template file(s): ${added.join(", ")}`);
+    if (pin === "written")
+      parts.push(`pinned template_version: ${TEMPLATE_VERSION} in heyspex.yaml`);
+    const hookWrites = written.length - added.length - (pin === "written" ? 1 : 0);
+    if (hookWrites > 0) parts.push(`${hookWrites} other file(s) written`);
+    message2 = parts.length > 0 ? `Refreshed customer vault at ${targetDir}: ${parts.join("; ")} (${keptCount} existing file(s) kept untouched).` : `Customer vault at ${targetDir} is already current (template v${TEMPLATE_VERSION}, ${keptCount} file(s) kept) \u2014 nothing written.`;
+  } else {
+    message2 = `Initialized customer vault at ${targetDir} (${written.length} files written, ${createdCount} manifest rows created, ${keptCount} kept, template v${TEMPLATE_VERSION}).`;
+  }
   return {
     code: EXIT.OK,
-    message: `Initialized customer vault at ${targetDir} (${written.length} files written, ${createdCount} manifest rows created, ${keptCount} kept, template v${TEMPLATE_VERSION}).`,
+    message: message2,
     payload: {
       ok: true,
+      mode,
       targetDir,
       templateVersion: TEMPLATE_VERSION,
+      templatePin: pin,
       vaultId,
       written,
       rows: rowResults,
@@ -7350,14 +7513,14 @@ function templatePinHook() {
 }
 
 // spex-console/src/lib/cli/principle-selection.ts
-import { basename as basename3 } from "node:path";
+import { basename as basename4 } from "node:path";
 var PRINCIPLES_INDEX_DEST = "specs/principles-index.md";
 function principleKey(row2) {
-  const base = basename3(row2.dest, ".md");
+  const base = basename4(row2.dest, ".md");
   return base.startsWith("principle-") ? base.slice("principle-".length) : base;
 }
 function principleWikilink(row2) {
-  return basename3(row2.dest, ".md");
+  return basename4(row2.dest, ".md");
 }
 function parsePrinciplesFlag(value, rows) {
   const principleRows = rows.filter((row2) => row2.group === "principle");
@@ -7423,13 +7586,13 @@ function applyCustomerTemplate(args) {
       templateVersion: ctx.templateVersion
     });
     for (const file of contractFiles) {
-      const path7 = ctx.deps.joinPath(ctx.targetDir, file);
-      if (force && ctx.deps.exists(path7)) {
-        if (ctx.deps.readFile?.(path7) === content) {
+      const path9 = ctx.deps.joinPath(ctx.targetDir, file);
+      if (force && ctx.deps.exists(path9)) {
+        if (ctx.deps.readFile?.(path9) === content) {
           contracts.push({ file, action: "unchanged" });
         } else {
-          ctx.deps.writeFile(path7, content);
-          ctx.recordWrite(path7);
+          ctx.deps.writeFile(path9, content);
+          ctx.recordWrite(path9);
           contracts.push({ file, action: "overwritten" });
         }
         continue;
@@ -7468,12 +7631,17 @@ function applyCustomerTemplate(args) {
 }
 
 // spex-console/src/lib/cli/install.ts
-import { isAbsolute as isAbsolute3, resolve as resolveNodePath2 } from "node:path";
+import { isAbsolute as isAbsolute4, resolve as resolveNodePath2 } from "node:path";
+
+// spex-console/src/lib/vault-resolve/index.ts
+import { existsSync as existsSync6, readFileSync as readFileSync12, realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import path5 from "node:path";
 
 // scripts/install-cursor-hooks.mjs
 import fs2 from "node:fs";
-import path4 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import path6 from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // scripts/cursor-hooks/manifest.mjs
 var SHIM = "scripts/cursor-hooks/_run.mjs";
@@ -7617,9 +7785,9 @@ function timeoutFor(entry) {
 }
 
 // scripts/install-cursor-hooks.mjs
-var PLATFORM_ROOT = path4.resolve(path4.dirname(fileURLToPath3(import.meta.url)), "..");
-var REPO_ROOT = process.env.HS_SETUP_TARGET?.trim() ? path4.resolve(process.env.HS_SETUP_TARGET.trim()) : PLATFORM_ROOT;
-var SETTINGS_PATH = path4.join(REPO_ROOT, ".cursor", "hooks.json");
+var PLATFORM_ROOT = path6.resolve(path6.dirname(fileURLToPath4(import.meta.url)), "..");
+var REPO_ROOT = process.env.HS_SETUP_TARGET?.trim() ? path6.resolve(process.env.HS_SETUP_TARGET.trim()) : PLATFORM_ROOT;
+var SETTINGS_PATH = path6.join(REPO_ROOT, ".cursor", "hooks.json");
 function cursorKitFor(targetRoot, platformRoot = PLATFORM_ROOT) {
   const customer = !samePlatformPath(targetRoot, platformRoot);
   return {
@@ -7631,7 +7799,7 @@ function cursorKitFor(targetRoot, platformRoot = PLATFORM_ROOT) {
 }
 var KIT = cursorKitFor(REPO_ROOT);
 var ACTIVE_HOOKS = KIT.hooks;
-var LAUNCHER_PATH = path4.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.cursor.rel);
+var LAUNCHER_PATH = path6.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.cursor.rel);
 var LEGACY_MARKER = "scripts/claude-hooks/";
 function readSettings() {
   try {
@@ -7650,7 +7818,7 @@ function readSettings() {
   return { version: 1, hooks: {} };
 }
 function writeSettings(settings) {
-  fs2.mkdirSync(path4.dirname(SETTINGS_PATH), { recursive: true });
+  fs2.mkdirSync(path6.dirname(SETTINGS_PATH), { recursive: true });
   fs2.writeFileSync(SETTINGS_PATH, `${JSON.stringify(settings, null, 2)}
 `, "utf8");
 }
@@ -7685,7 +7853,7 @@ function sameEntry(raw, entry, render = KIT.commandFor) {
   const want = desiredEntry(entry, render);
   return commandOf(raw) === want.command && raw.timeout === want.timeout && (raw.matcher ?? void 0) === (want.matcher ?? void 0);
 }
-var PLUGIN_HOOKS_PATH = path4.join(REPO_ROOT, "plugins", "heyspex", "hooks", "cursor-hooks.json");
+var PLUGIN_HOOKS_PATH = path6.join(REPO_ROOT, "plugins", "heyspex", "hooks", "cursor-hooks.json");
 function pluginHooksDocument() {
   const hooks = {};
   for (const entry of HOOKS) {
@@ -7715,7 +7883,7 @@ function syncPluginHooks() {
     have = null;
   }
   if (have === want) return false;
-  fs2.mkdirSync(path4.dirname(PLUGIN_HOOKS_PATH), { recursive: true });
+  fs2.mkdirSync(path6.dirname(PLUGIN_HOOKS_PATH), { recursive: true });
   fs2.writeFileSync(PLUGIN_HOOKS_PATH, want, "utf8");
   return true;
 }
@@ -7788,7 +7956,7 @@ function install({ json = false } = {}) {
   if (KIT.customer) {
     const plan = launcherPlan();
     if (plan.write) {
-      fs2.mkdirSync(path4.dirname(LAUNCHER_PATH), { recursive: true });
+      fs2.mkdirSync(path6.dirname(LAUNCHER_PATH), { recursive: true });
       fs2.writeFileSync(LAUNCHER_PATH, plan.text, "utf8");
       launcherWritten = true;
     }
@@ -7815,10 +7983,10 @@ function install({ json = false } = {}) {
     return;
   }
   if (pluginChanged) {
-    console.log(`install-cursor-hooks: regenerated ${path4.relative(REPO_ROOT, PLUGIN_HOOKS_PATH)}`);
+    console.log(`install-cursor-hooks: regenerated ${path6.relative(REPO_ROOT, PLUGIN_HOOKS_PATH)}`);
   }
   if (launcherWritten) {
-    console.log(`install-cursor-hooks: wrote ${path4.relative(REPO_ROOT, LAUNCHER_PATH)} (resolves node_modules/heyspex)`);
+    console.log(`install-cursor-hooks: wrote ${path6.relative(REPO_ROOT, LAUNCHER_PATH)} (resolves node_modules/heyspex)`);
   }
   if (!settingsChanged) {
     console.log(`install-cursor-hooks: already installed (${ACTIVE_HOOKS.length} hooks, no changes).`);
@@ -7829,7 +7997,7 @@ function install({ json = false } = {}) {
   if (repaired.length) parts.push(`repaired ${repaired.length}`);
   if (removed.length) parts.push(`removed ${removed.length}`);
   console.log(
-    `install-cursor-hooks: ${parts.join("; ")} \u2192 ${path4.relative(REPO_ROOT, SETTINGS_PATH)} (${ACTIVE_HOOKS.length} hooks registered)`
+    `install-cursor-hooks: ${parts.join("; ")} \u2192 ${path6.relative(REPO_ROOT, SETTINGS_PATH)} (${ACTIVE_HOOKS.length} hooks registered)`
   );
   for (const line of removed) console.log(`  - ${line}`);
   console.log(
@@ -8078,8 +8246,8 @@ function formatReceipt(receipt) {
 // spex-console/src/lib/cli/receipt-readback.ts
 var RECEIPT_CLOUD_READS = 3;
 var RECEIPT_REREAD_DELAY_MS = 1e3;
-var realSleep = (ms) => new Promise((resolve5) => {
-  setTimeout(resolve5, ms);
+var realSleep = (ms) => new Promise((resolve6) => {
+  setTimeout(resolve6, ms);
 });
 function message(err) {
   return err instanceof Error ? err.message : String(err);
@@ -8117,11 +8285,11 @@ function readLocalReceiptSide(subject, registryOpts = {}) {
     return unreadSide(`registry.json could not be read: ${message(err)}`);
   }
 }
-async function readList(http, path7, key) {
-  const res = await cloudHttpRequest(http, "GET", path7);
+async function readList(http, path9, key) {
+  const res = await cloudHttpRequest(http, "GET", path9);
   const rows = res.json?.[key];
   if (!res.ok || !Array.isArray(rows)) {
-    return { reason: `GET ${path7.split("?")[0]} answered HTTP ${res.status}` };
+    return { reason: `GET ${path9.split("?")[0]} answered HTTP ${res.status}` };
   }
   return { rows: rows.filter((r) => Boolean(r) && typeof r === "object") };
 }
@@ -8196,7 +8364,7 @@ async function readReceiptSides(subject, deps) {
 var import_gray_matter = __toESM(require_gray_matter(), 1);
 import { createHash as createHash2 } from "node:crypto";
 import { promises as fs3 } from "node:fs";
-import path5 from "node:path";
+import path7 from "node:path";
 
 // spex-console/src/lib/vault-id.ts
 var FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
@@ -8778,8 +8946,8 @@ async function indexTemplateToCloud(args) {
         const res = await cloudHttpRequest(args.http, "GET", REINDEX_PATH);
         return { status: res.status, json: res.json };
       },
-      post: async (path7, body) => {
-        const res = await cloudHttpRequest(args.http, "POST", path7, body);
+      post: async (path9, body) => {
+        const res = await cloudHttpRequest(args.http, "POST", path9, body);
         return { status: res.status, json: res.json };
       }
     });
@@ -8825,39 +8993,58 @@ async function indexTemplateToCloud(args) {
 // spex-console/src/lib/cli/install.ts
 var MCP_REL = ["vendor", "heyspex-mcp", "cli.mjs"];
 var PORTABLE_MCP_CLI = Object.freeze({
+  claude: `\${CLAUDE_PROJECT_DIR:-.}/${CUSTOMER_LAUNCHERS.claude.rel.join("/")}`,
+  cursor: `\${workspaceFolder}/${CUSTOMER_LAUNCHERS.cursor.rel.join("/")}`
+});
+var LEGACY_PORTABLE_MCP_CLI = Object.freeze({
   claude: `\${CLAUDE_PROJECT_DIR:-.}/${PORTABLE_PACKAGE_DIR}/${MCP_REL.join("/")}`,
   cursor: `\${workspaceFolder}/${PORTABLE_PACKAGE_DIR}/${MCP_REL.join("/")}`
 });
+var LAUNCHER_MCP_FLAG = "--mcp";
+function mcpServerArgs(cliPath) {
+  return /[\\/]heyspex[\\/]run-hook\.mjs$/.test(cliPath) ? [cliPath, LAUNCHER_MCP_FLAG] : [cliPath];
+}
+function repairLegacyMcpManifest(manifest, surface) {
+  const servers = manifest?.mcpServers;
+  const entry = servers && typeof servers === "object" ? servers.heyspex : void 0;
+  if (!entry || !Array.isArray(entry.args) || entry.args[0] !== LEGACY_PORTABLE_MCP_CLI[surface]) {
+    return false;
+  }
+  entry.args = mcpServerArgs(PORTABLE_MCP_CLI[surface]);
+  return true;
+}
 function mcpCliArgFor(surface, platformRoot, targetDir, joinPath) {
   return samePlatformPath(targetDir, platformRoot) ? mcpCliPath(platformRoot, joinPath) : PORTABLE_MCP_CLI[surface];
 }
 function mcpCliPath(platformRoot, joinPath) {
   return joinPath(platformRoot, ...MCP_REL);
 }
-function renderCursorMcpJson(cliAbsPath, attachedVaultRoot) {
+function renderCursorMcpJson(cliAbsPath, attachedVaultRoot, opts = {}) {
+  const pin = vaultRootPin(attachedVaultRoot, "${workspaceFolder}", opts);
   return {
     mcpServers: {
       heyspex: {
         type: "stdio",
         command: "node",
-        args: [cliAbsPath],
-        env: {
-          HEYSPEX_VAULT_ROOT: attachedVaultRoot ?? "${workspaceFolder}"
-        }
+        args: mcpServerArgs(cliAbsPath),
+        ...pin ? { env: { HEYSPEX_VAULT_ROOT: pin } } : {}
       }
     }
   };
 }
-function renderClaudeMcpJson(cliAbsPath, attachedVaultRoot) {
+function vaultRootPin(attachedVaultRoot, placeholder, opts = {}) {
+  if (attachedVaultRoot) return attachedVaultRoot;
+  return opts.targetIsVault === false ? null : placeholder;
+}
+function renderClaudeMcpJson(cliAbsPath, attachedVaultRoot, opts = {}) {
+  const pin = vaultRootPin(attachedVaultRoot, "${CLAUDE_PROJECT_DIR:-.}", opts);
   return {
     mcpServers: {
       heyspex: {
         type: "stdio",
         command: "node",
-        args: [cliAbsPath],
-        env: {
-          HEYSPEX_VAULT_ROOT: attachedVaultRoot ?? "${CLAUDE_PROJECT_DIR:-.}"
-        }
+        args: mcpServerArgs(cliAbsPath),
+        ...pin ? { env: { HEYSPEX_VAULT_ROOT: pin } } : {}
       }
     }
   };
@@ -9135,7 +9322,6 @@ var WRITE_TARGET_KIND = {
   claudeMcp: "claude_mcp",
   claudeMd: "claude_md",
   agentsMd: "agents_md",
-  statuslineVendor: "statusline_vendor",
   gitignore: "gitignore",
   claudeMdTemplate: "claude_md_template",
   agentsMdTemplate: "agents_md_template"
@@ -9192,12 +9378,6 @@ var INSTALL_WRITE_TARGETS = [
     path: (targetDir, joinPath) => joinPath(targetDir, "AGENTS.md.template"),
     appliesTo: (args, opts) => Boolean(args.registerVault) && !opts.attached && opts.installContract
   },
-  {
-    kind: WRITE_TARGET_KIND.statuslineVendor,
-    rel: "scripts/claude-statusline",
-    path: (targetDir, joinPath) => joinPath(targetDir, "scripts", "claude-statusline"),
-    appliesTo: (args) => (args.statusline ?? true) && args.claude
-  },
   {
     kind: WRITE_TARGET_KIND.gitignore,
     rel: ".gitignore",
@@ -9330,7 +9510,7 @@ var INSTALL_HELP = [
 
 // spex-console/src/lib/cli/install-identity.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { join as join11 } from "node:path";
 import { createInterface } from "node:readline/promises";
 init_credentials();
@@ -9338,7 +9518,7 @@ init_credentials();
 // vendor/heyspex-mcp/whoami.mjs
 init_heyspex_home();
 init_credentials();
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 var SESSION_PATH = "/api/mcp/session";
 async function probeCredentialIdentity({ consoleUrl, token, fetchImpl = fetch } = {}) {
   if (!token) return { kind: "no_credential" };
@@ -9622,7 +9802,7 @@ function isInteractiveTerminal() {
 }
 function defaultIdentityGateIo(opts) {
   const consoleUrl = opts.consoleUrl.trim().replace(/\/+$/, "");
-  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join11(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync5(p));
+  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join11(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync7(p));
   return {
     consoleUrl,
     interactive: opts.interactive ?? isInteractiveTerminal(),
@@ -10036,9 +10216,9 @@ function detachedSatelliteWarning(repoRoot, gitRemote, registryBefore, deps) {
     reasons.push(`${wiredManifests.join(" + ")} already declares the heyspex MCP server`);
   }
   const contractFiles = ["CLAUDE.md", "AGENTS.md"].filter((name) => {
-    const path7 = deps.joinPath(repoRoot, name);
-    if (!deps.fileExists(path7)) return false;
-    const content = deps.readFile(path7);
+    const path9 = deps.joinPath(repoRoot, name);
+    if (!deps.fileExists(path9)) return false;
+    const content = deps.readFile(path9);
     return content !== null && HEYSPEX_CONTRACT_MARKERS.some((m) => content.includes(m));
   });
   if (contractFiles.length > 0) {
@@ -10857,7 +11037,32 @@ async function runConnectFullRun(args, deps) {
     const mcpConfirmedBy = "read .mcp.json + .cursor/mcp.json";
     const claudeMissing = !deps.fileExists(claudeMcpPath);
     const cursorMissing = !deps.fileExists(cursorMcpPath);
-    if (!claudeMissing && !cursorMissing) {
+    const repairedLegacy = [];
+    for (const [file, surface, missing] of [
+      [claudeMcpPath, "claude", claudeMissing],
+      [cursorMcpPath, "cursor", cursorMissing]
+    ]) {
+      if (missing || samePlatformPath(repoRoot, platformRoot)) continue;
+      let parsed = null;
+      try {
+        parsed = JSON.parse(deps.readFile(file) ?? "");
+      } catch {
+        continue;
+      }
+      if (!repairLegacyMcpManifest(parsed, surface)) continue;
+      if (!args.dryRun) deps.writeFile(file, `${JSON.stringify(parsed, null, 2)}
+`);
+      repairedLegacy.push(file);
+    }
+    if (repairedLegacy.length > 0 && !claudeMissing && !cursorMissing) {
+      steps.push({
+        id: "mcp_entry",
+        label,
+        status: "run",
+        detail: `${args.dryRun ? "would repoint" : "repointed"} ${repairedLegacy.join(", ")} at the committed launcher (${PORTABLE_MCP_CLI.claude})`,
+        confirmed_by: mcpConfirmedBy
+      });
+    } else if (!claudeMissing && !cursorMissing) {
       steps.push({
         id: "mcp_entry",
         label,
@@ -10880,12 +11085,14 @@ async function runConnectFullRun(args, deps) {
       try {
         const claudeCli = mcpCliArgFor("claude", platformRoot, repoRoot, deps.joinPath);
         const cursorCli = mcpCliArgFor("cursor", platformRoot, repoRoot, deps.joinPath);
-        const pinnedRoot = satellite?.vaultRootAbs;
+        const markerRel = satellite?.viaMarker ? satellite.vaultPath : void 0;
+        const claudePin = markerRel ? "${CLAUDE_PROJECT_DIR:-.}/" + markerRel : satellite?.vaultRootAbs;
+        const cursorPin = markerRel ? "${workspaceFolder}/" + markerRel : satellite?.vaultRootAbs;
         const written = [];
         if (claudeMissing) {
           deps.writeFile(
             claudeMcpPath,
-            `${JSON.stringify(renderClaudeMcpJson(claudeCli, pinnedRoot), null, 2)}
+            `${JSON.stringify(renderClaudeMcpJson(claudeCli, claudePin), null, 2)}
 `
           );
           written.push(claudeMcpPath);
@@ -10894,7 +11101,7 @@ async function runConnectFullRun(args, deps) {
           deps.mkdir(deps.joinPath(repoRoot, ".cursor"));
           deps.writeFile(
             cursorMcpPath,
-            `${JSON.stringify(renderCursorMcpJson(cursorCli, pinnedRoot), null, 2)}
+            `${JSON.stringify(renderCursorMcpJson(cursorCli, cursorPin), null, 2)}
 `
           );
           written.push(cursorMcpPath);
@@ -11279,11 +11486,11 @@ function resolveDoctorCommand(repoRoot, platformRoot, deps) {
   const hs = deps.joinPath(platformRoot, "bin", "hs.mjs");
   return deps.fileExists(hs) ? { args: [hs, "doctor", "--json"], confirmedBy: "hs doctor --json" } : null;
 }
-function assertMarker(content, path7, vaultId, accountId) {
-  if (content === null) throw new Error(`${path7} could not be read back after the write`);
+function assertMarker(content, path9, vaultId, accountId) {
+  if (content === null) throw new Error(`${path9} could not be read back after the write`);
   const back = parseVaultId(content);
   if (vaultId && back !== vaultId) {
-    throw new Error(`${path7} reads back vault_id ${back ?? "(none)"}, not ${vaultId}`);
+    throw new Error(`${path9} reads back vault_id ${back ?? "(none)"}, not ${vaultId}`);
   }
 }
 var MIRRORED_SKILL_DIRS = [
@@ -11437,7 +11644,7 @@ async function runFixHarnessCommands(args, deps) {
       continue;
     }
     const existingContent = deps.fileExists(installedPath) ? deps.readFile(installedPath) : null;
-    if (existingContent === f.content) {
+    if (existingContent !== null && normalizeEol(existingContent) === normalizeEol(f.content)) {
       unchangedCount += 1;
       continue;
     }
@@ -11624,6 +11831,104 @@ var HELP3 = [
   "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 write-failed"
 ].join("\n");
 
+// spex-console/src/lib/cli/generated-file-eol.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync8, readFileSync as readFileSync13 } from "node:fs";
+import { dirname as dirname6, relative, resolve as resolve5 } from "node:path";
+function dominantEol(text2) {
+  const crlf = (text2.match(/\r\n/g) ?? []).length;
+  const lf = (text2.match(/\n/g) ?? []).length - crlf;
+  if (crlf === 0 && lf === 0) return null;
+  return crlf > lf ? "\r\n" : "\n";
+}
+function applyEol(text2, eol) {
+  const lf = text2.replace(/\r\n/g, "\n");
+  return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
+}
+function defaultRunGit(args, cwd) {
+  try {
+    const res = spawnSync3("git", args, {
+      cwd,
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 1e4
+    });
+    if (res.status !== 0) return null;
+    return String(res.stdout ?? "").trim();
+  } catch {
+    return null;
+  }
+}
+function defaultReadFile4(path9) {
+  try {
+    return readFileSync13(path9, "utf8");
+  } catch {
+    return null;
+  }
+}
+function existingAncestor(path9) {
+  let dir = dirname6(resolve5(path9));
+  for (; ; ) {
+    if (existsSync8(dir)) return dir;
+    const parent = dirname6(dir);
+    if (parent === dir) return dir;
+    dir = parent;
+  }
+}
+function createGeneratedFileEol(opts) {
+  const readFile2 = opts.readFile ?? defaultReadFile4;
+  const runGit = opts.runGit ?? defaultRunGit;
+  const platform = opts.platform ?? process.platform;
+  const attrCache = /* @__PURE__ */ new Map();
+  let configEol;
+  const configDefault = () => {
+    if (configEol !== void 0) return configEol;
+    if (runGit(["rev-parse", "--is-inside-work-tree"], opts.repoRoot) !== "true") {
+      configEol = null;
+      return configEol;
+    }
+    const get = (key) => runGit(["config", "--get", key], opts.repoRoot);
+    const coreEol = (get("core.eol") ?? "").toLowerCase();
+    if (coreEol === "crlf") configEol = "\r\n";
+    else if (coreEol === "lf") configEol = "\n";
+    else if (platform === "win32" && (get("core.autocrlf") ?? "").toLowerCase() === "true")
+      configEol = "\r\n";
+    else configEol = null;
+    return configEol;
+  };
+  const attrEol = (path9) => {
+    const abs = resolve5(path9);
+    const cwd = existingAncestor(abs);
+    const rel = relative(cwd, abs).replace(/\\/g, "/") || ".";
+    const key = `${cwd}\0${rel}`;
+    let out = attrCache.get(key);
+    if (out === void 0) {
+      out = runGit(["check-attr", "eol", "--", rel], cwd) ?? "";
+      attrCache.set(key, out);
+    }
+    const m = out.match(/:\s*eol:\s*(\S+)\s*$/);
+    const value = (m?.[1] ?? "").toLowerCase();
+    if (value === "crlf") return "\r\n";
+    if (value === "lf") return "\n";
+    return null;
+  };
+  const eolFor = (path9, existing) => {
+    const current = existing === void 0 ? readFile2(path9) : existing;
+    if (current !== null) {
+      const have = dominantEol(current);
+      if (have) return have;
+    }
+    return attrEol(path9) ?? configDefault() ?? "\n";
+  };
+  return {
+    eolFor,
+    convert: (path9, content, existing) => {
+      if (!content.includes("\n")) return content;
+      return applyEol(content, eolFor(path9, existing));
+    }
+  };
+}
+
 // spex-console/bin/run-entry.ts
 import process3 from "node:process";
 var BinExit = class extends Error {
@@ -11655,7 +11960,7 @@ function runEntry(name, main2, options2 = {}) {
 // spex-console/bin/hs-connect.ts
 function readFile(p) {
   try {
-    return readFileSync11(p, "utf8");
+    return readFileSync14(p, "utf8");
   } catch {
     return null;
   }
@@ -11667,13 +11972,13 @@ function listDir(p) {
     return [];
   }
 }
-var packageRoot = path6.resolve(path6.dirname(fileURLToPath4(import.meta.url)), "..", "..");
+var packageRoot = path8.resolve(path8.dirname(fileURLToPath5(import.meta.url)), "..", "..");
 var satelliteWalkDeps = {
-  fileExists: (p) => existsSync6(p),
+  fileExists: (p) => existsSync9(p),
   readFile,
-  joinPath: (...segments) => path6.join(...segments),
-  parentDir: (p) => path6.dirname(p),
-  resolveDir: (p) => path6.resolve(p)
+  joinPath: (...segments) => path8.join(...segments),
+  parentDir: (p) => path8.dirname(p),
+  resolveDir: (p) => path8.resolve(p)
 };
 async function main() {
   const identityArgv = extractIdentityFlags(process4.argv.slice(3));
@@ -11698,7 +12003,7 @@ async function main() {
   }
   const cwd = resolveConnectCwd(process4.env, process4.cwd());
   const satelliteRepoRoot = findSatelliteRepoRoot(cwd, satelliteWalkDeps);
-  const repoRoot = satelliteRepoRoot ?? (process4.env.HS_VAULT_ROOT ? path6.resolve(process4.env.HS_VAULT_ROOT) : cwd);
+  const repoRoot = satelliteRepoRoot ?? (process4.env.HS_VAULT_ROOT ? path8.resolve(process4.env.HS_VAULT_ROOT) : cwd);
   const platformRoot = resolveCodeRoot({
     // The two install-specific overrides outrank HS_PKG_ROOT here, so they
     // ride in as `explicit`; the rest of the ladder (HS_PKG_ROOT, then the
@@ -11709,7 +12014,7 @@ async function main() {
   const consoleUrl = resolveSpexConsoleUrl(repoRoot, readFile);
   if (parsed.args.sub === "run" && !parsed.args.dryRun) {
     const gate = await runIdentityGate(
-      defaultIdentityGateIo({ consoleUrl, platformRoot: path6.resolve(platformRoot) }),
+      defaultIdentityGateIo({ consoleUrl, platformRoot: path8.resolve(platformRoot) }),
       identityArgv.flags,
       "hs connect"
     );
@@ -11722,28 +12027,29 @@ async function main() {
       return;
     }
   }
+  const eol = createGeneratedFileEol({ repoRoot });
   const result = await runConnect(parsed.args, {
     repoRoot,
     cwd,
-    platformRoot: path6.resolve(platformRoot),
-    fileExists: (p) => existsSync6(p),
+    platformRoot: path8.resolve(platformRoot),
+    fileExists: (p) => existsSync9(p),
     readFile,
     listDir,
-    writeFile: (p, c) => writeFileSync6(p, c, "utf8"),
-    mkdir: (p) => mkdirSync6(p, { recursive: true }),
-    copyFile: (src, dest) => copyFileSync(src, dest),
+    writeFile: (p, c) => writeFileSync7(p, eol.convert(p, c), "utf8"),
+    mkdir: (p) => mkdirSync7(p, { recursive: true }),
+    copyFile: (src, dest) => copyFileSync2(src, dest),
     isDirectory: (p) => {
       try {
-        return statSync(p).isDirectory();
+        return statSync5(p).isDirectory();
       } catch {
         return false;
       }
     },
-    joinPath: (...s) => path6.join(...s),
-    basename: (p) => path6.basename(p),
+    joinPath: (...s) => path8.join(...s),
+    basename: (p) => path8.basename(p),
     now: () => (/* @__PURE__ */ new Date()).toISOString(),
     spawn: (command, args, opts) => {
-      const res = spawnSync3(command, args, {
+      const res = spawnSync4(command, args, {
         cwd: opts?.cwd,
         ...opts?.env ? { env: mergeChildEnv(process4.env, opts.env) } : {},
         encoding: "utf8",