heyspex 0.2.0 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "heyspex-marketplace",
+  "owner": {
+    "name": "pwher",
+    "email": "paul@monstergrowth.com"
+  },
+  "plugins": [
+    {
+      "name": "heyspex",
+      "source": "./plugins/heyspex",
+      "description": "SpexCode plugin (for Claude Code and GitHub Copilot CLI): HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+    }
+  ]
+}

package/bin/hs.mjs

@@ -25,7 +25,9 @@ import {
   vaultConfigCheckRow,
 } from "../scripts/lib/standalone-doctor.mjs";
 import {
+  findBrokenSatellitePin,
   isVaultRoot,
+  readMarkerSatellite,
   readSatellitePin,
   resolveActiveVault,
 } from "../vendor/heyspex-mcp/vault-resolve.mjs";
@@ -85,6 +87,7 @@ export const SPAWN_TARGETS = {
   "source:preflight": { path: "scripts/lib/hs-source-preflight.mjs" },
   "source:commit": { path: "scripts/lib/hs-source-commit.mjs" },
   "source:push": { path: "scripts/lib/hs-source-push.mjs" },
+  "source:branch": { path: "scripts/lib/hs-source-branch.mjs" },
   "source:log": { path: "scripts/lib/hs-source-log.mjs" },
   // `hs source identity` — the ONE sanctioned git-identity writer (human-only
   // set/clear, read-only show). Incident 2026-09-19, vault lesson
@@ -175,6 +178,8 @@ export const BUILTIN_VERBS = [
   "doctor",
   "index",
   "pull",
+  "push",
+  "import",
   "milestone",
   "factory",
   "code-watcher",
@@ -286,6 +291,13 @@ export function findVaultRoot(start, stopAt) {
     if (pinned) {
       return pinned;
     }
+    // A committed, portable satellite marker (heyspex.yaml with a relative
+    // `vault_path`): the attached vault's clone when it is on this machine,
+    // else this repo itself (cloud-only; the marker's vault_id binds it).
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return marked.vaultRootAbs ?? dir;
+    }
     if (isVaultRoot(dir)) {
       return dir;
     }
@@ -331,6 +343,72 @@ export function findRegistryVaultRoot(options = {}) {
   return resolved.repoRootAbs;
 }
 
+/** Env hatch: follow the account-wide active-vault pointer on purpose (same name the MCP transport uses). */
+export function pointerVaultAllowed(env = process.env) {
+  const v = String(env.HEYSPEX_ALLOW_POINTER_VAULT ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * Verbs that may legitimately run with only the machine's last-active vault
+ * (or none): they onboard, sign in, or manage the registry itself. EVERY other
+ * verb acts on a vault, and P1 (owner, 2026-10-16) says that vault is the one
+ * bound to the repo the agent runs in -- never the account-wide pointer.
+ */
+const POINTER_FALLBACK_NAMESPACES = new Set([
+  "init", "install", "join", "setup", "skills", "vault", "workspace",
+  "login", "whoami", "logout", "doctor", "registry", "companion", "trust",
+]);
+
+/** True when `hs <namespace> <command>` may run on the pointer-only fallback. */
+export function pointerFallbackAllowedFor(namespace, command) {
+  if (namespace === "mcp") return command === "pair" || command === "login" || command === "install";
+  return POINTER_FALLBACK_NAMESPACES.has(namespace);
+}
+
+/** The refusal printed when a satellite's pin / marker cannot be honoured. */
+export function brokenPinRefusalLine(broken) {
+  return (
+    `hs: this repo's vault pin cannot be honoured, so nothing was run. ${broken.dir}/${broken.source} ` +
+    `names \`${broken.raw}\`, but ${broken.reason}. ` +
+    "Fix the pin (a relative path such as ../<vault-repo> or ${CLAUDE_PROJECT_DIR:-.}/../<vault-repo> is portable), " +
+    "or commit a heyspex.yaml with vault_id and vault_path; hs will NOT fall back to the account-wide active vault.\n"
+  );
+}
+
+/** Nearest directory at/above `start` whose heyspex.yaml is a satellite marker (has vault_path), else null. */
+export function markerSatelliteDirFrom(start) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 256; i += 1) {
+    if (readMarkerSatellite(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/** The refusal for disk-writing verbs in a satellite whose vault clone is missing. */
+export function unclonedVaultRefusalLine(repo) {
+  const m = readMarkerSatellite(repo);
+  return (
+    `hs: ${repo} is bound to vault ${m?.vaultId ?? "(no vault_id)"} by its heyspex.yaml, but the vault ` +
+    `is not cloned at ${m?.vaultPath ?? "its vault_path"} on this machine, so this verb has no local vault to act on. ` +
+    "Clone the vault repo to that relative path (agents and cloud-routed MCP writes work without it).\n"
+  );
+}
+
+/** The refusal printed when only the account-wide pointer answered and the verb acts on a vault. */
+export function pointerOnlyRefusalLine(cwd, vaultRoot) {
+  return (
+    `hs: ${cwd} is not bound to a HeySpex vault (no heyspex.yaml, no specs/, no vault pin in .mcp.json), ` +
+    `so \`hs\` refused to follow the account-wide active vault${vaultRoot ? ` (${vaultRoot})` : ""}. ` +
+    "Bind this repo: run `hs connect` in a vault repo, `hs install --attach-vault <id> --target <repo>` for a code repo, " +
+    "or commit a heyspex.yaml with vault_id and a relative vault_path. " +
+    "To follow the pointer on purpose set HEYSPEX_ALLOW_POINTER_VAULT=1.\n"
+  );
+}
+
 /**
  * The vault-resolution ladder `main()` runs at the top of every invocation,
  * factored out so it is unit-testable without spawning a child process
@@ -358,6 +436,12 @@ export function resolveVaultRootForMain(cwd, env, stopAt) {
   if (env.HS_VAULT_ROOT) {
     return { vaultRoot: env.HS_VAULT_ROOT, usedRegistryFallback: false };
   }
+  // A pin that cannot be honoured is a REFUSAL, never a reason to fall
+  // through to the account-wide pointer (owner principle P1, 2026-10-16).
+  const brokenPin = findBrokenSatellitePin(cwd, stopAt);
+  if (brokenPin) {
+    return { vaultRoot: null, usedRegistryFallback: false, brokenPin };
+  }
   const walkedRoot = findVaultRoot(cwd, stopAt);
   if (walkedRoot) {
     return { vaultRoot: walkedRoot, usedRegistryFallback: false };
@@ -488,8 +572,10 @@ function usage() {
       "  hs skills list [--json]                    List registered skills (built-ins first, locked)",
       "  hs index rebuild [--verbose] [--dry-run]   Full idempotent rebuild of the index",
       "  hs index reconcile [--apply] [--cap-docs keep-out|index]  Per-spec newest-wins between disk and cloud (reports unless --apply)",
-      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply)",
-      "  hs source status|preflight|commit|push     Local git: tree status, path-scoped checks, commit, safe push",
+      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply; --watch --push adds the disk -> cloud leg)",
+      "  hs push [--apply] [--only <id>] [--force]  Send local spec edits up to the cloud vault (reports unless --apply)",
+      "  hs import <source-dir> [--folders a,b] [--plan f] [--dry-run] [--limit N]  Import a doc tree as GROUNDED spec-import captures (never raw, never research)",
+      "  hs source status|preflight|commit|push|branch  Local git: tree status, path-scoped checks, commit, safe push, session branch",
       "  hs source identity [show|set|clear]        Git author identity: show (read-only) / set, clear (HUMAN-ONLY)",
       "  hs milestone show <id> [--json]            Show a milestone (flags needs-breakdown when epicless)",
       "  hs factory status|fleet|results [--json]   Dev-Factory read-only status (fleet, routing, calibrations, results)",
@@ -858,10 +944,27 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
-  const { vaultRoot, usedRegistryFallback } = resolveVaultRootForMain(
-    process.cwd(),
-    process.env,
-  );
+  const resolvedMain = resolveVaultRootForMain(process.cwd(), process.env);
+  const { usedRegistryFallback, brokenPin } = resolvedMain;
+  // P1: the pointer is not a binding. A verb that acts on a vault runs with
+  // NO vault (and is refused at the gate) rather than on whatever vault the
+  // console last selected; onboarding/registry verbs keep the old fallback.
+  const pointerOnly =
+    usedRegistryFallback &&
+    !pointerVaultAllowed(process.env) &&
+    !pointerFallbackAllowedFor(namespace, command);
+  const vaultRoot = pointerOnly ? null : resolvedMain.vaultRoot;
+  if (pointerOnly) {
+    process.stderr.write(pointerOnlyRefusalLine(process.cwd(), resolvedMain.vaultRoot));
+  }
+  if (
+    brokenPin &&
+    namespace !== "doctor" &&
+    !pointerFallbackAllowedFor(namespace, command)
+  ) {
+    process.stderr.write(brokenPinRefusalLine(brokenPin));
+    process.exit(2);
+  }
 
   // `hs init` writes the top-level heyspex.yaml vault marker AND scaffolds
   // specs/ ([[HS-EPIC-AEHR-audit-export-heyspex-yaml-and-heyspex-retirement]]
@@ -920,7 +1023,9 @@ function main(argv) {
     dispatchSpexConsoleEntry(
       "hs-install.ts",
       argv,
-      vaultRoot || process.cwd(),
+      // In a committed-marker satellite the install target is the CODE repo
+      // (MCP entry, hooks, commands), never the vault clone the marker names.
+      markerSatelliteDirFrom(INVOKED_CWD) ?? (vaultRoot || process.cwd()),
       {
         HS_PKG_ROOT: PKG_ROOT,
       },
@@ -1197,6 +1302,18 @@ function main(argv) {
     process.exit(1);
   }
 
+  // A committed satellite marker whose vault clone is NOT on this machine
+  // resolves to the code repo itself (cloud-only binding). Verbs that write the
+  // vault's files to disk must never scaffold specs/ into a code repo.
+  if (
+    ["pull", "push", "index"].includes(namespace) &&
+    readMarkerSatellite(vaultRoot) &&
+    !existsSync(path.join(vaultRoot, "specs"))
+  ) {
+    process.stderr.write(unclonedVaultRefusalLine(vaultRoot));
+    process.exit(2);
+  }
+
   if (namespace === "index" && command === "rebuild") {
     dispatchSpexConsoleEntry("hs-index-rebuild.ts", rest, vaultRoot, {
       ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
@@ -1228,6 +1345,31 @@ function main(argv) {
     return;
   }
 
+  // `hs import <source-dir>` — a doc tree becomes GROUNDED spec-import captures
+  // in the cwd's vault (heyspex.yaml marker, never the account pointer): group-
+  // intent pass, foundational-to-specific order, sequential Ground=Expand with
+  // a running batch ledger, one intent-map doc, source links; never promotes
+  // ([[HS-0GOV-43G9-CAP-the-spec-import-function-should-not-stop]]). Forwards
+  // the full argv; the entrypoint drops the leading `import` token and resolves
+  // a relative <source-dir> against HS_INVOKED_CWD.
+  if (namespace === "import") {
+    dispatchSpexConsoleEntry("hs-import.ts", argv, vaultRoot, {
+      HS_INVOKED_CWD: INVOKED_CWD,
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs push` — disk -> cloud (SpexRelay local leg, HS-FCNH). Report-only
+  // unless --apply; never creates specs, never pushes status, refuses over a
+  // newer cloud copy. Forwards the full argv; the entrypoint drops `push`.
+  if (namespace === "push") {
+    dispatchSpexConsoleEntry("hs-vault-push.ts", argv, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
   // `hs milestone show <id>` — print a milestone, flagging needs-breakdown when
   // it has no epics ([[HS-TASK-HMSE]] / [[HS-EPIC-MNBD]]). Forwards the full
   // argv; the entrypoint drops the leading `milestone` token.
@@ -1357,7 +1499,9 @@ function main(argv) {
           "  hs source status              Read-only tree status + path-scoped stage plan\n" +
           "  hs source preflight           Alias of status\n" +
           "  hs source commit              Stage + commit per the preflight plan\n" +
-          "  hs source push                Push the committed branch\n" +
+          "  hs source push [branch]       Push the committed branch (no branch: the shared session-branch resolver's target)\n" +
+          "  hs source branch declare [<branch>] | show\n" +
+          "                                Declare the branch this session works on (cloud spec saves then land on it) / show the target\n" +
           "  hs source log <spec-id>       Commit-history lookup for a spec (console settlement,\n" +
           "                                 falling back to local git log)\n" +
           "  hs source identity [show] [--json]\n" +
@@ -1378,6 +1522,7 @@ function main(argv) {
       preflight: "source:preflight",
       commit: "source:commit",
       push: "source:push",
+      branch: "source:branch",
       log: "source:log",
       identity: "source:identity",
     };
@@ -1648,13 +1793,20 @@ function main(argv) {
       process.exit(2);
     }
     const cliPath = spawnTargetPath("heyspex-mcp-cli");
+    // The MCP engine resolves its vault by walking UP from ITS cwd. Launching
+    // it with cwd = the HeySpex checkout made every `hs mcp call` read the
+    // HeySpex vault no matter where the agent stood (found 2026-10-16 from
+    // mlc-specs / mlc-app). Run it from the repo the caller is in; an explicit
+    // HS_VAULT_ROOT keeps winning (the engine is started inside that vault).
+    const mcpCwd = process.env.HS_VAULT_ROOT && vaultRoot ? vaultRoot : INVOKED_CWD;
     const child = spawn(process.execPath, [cliPath, command, ...rest], {
-      cwd: PKG_ROOT,
+      cwd: mcpCwd,
       stdio: "inherit",
       env: {
         ...process.env,
-        HEYSPEX_VAULT_ROOT: vaultRoot,
-        HS_VAULT_ROOT: vaultRoot,
+        CLAUDE_PROJECT_DIR: mcpCwd,
+        HEYSPEX_VAULT_ROOT: vaultRoot ?? "",
+        HS_VAULT_ROOT: vaultRoot ?? "",
         // One-shot MCP tool — no stdio loop, no stderr brief-tier noise in PS.
         HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
       },

package/dist/cli/hs-check.mjs

@@ -5,11 +5,26 @@ var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
 
+// scripts/lib/heyspex-home.mjs
+import { homedir } from "node:os";
+function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+var init_heyspex_home = __esm({
+  "scripts/lib/heyspex-home.mjs"() {
+    "use strict";
+  }
+});
+
 // vendor/heyspex-mcp/credentials.mjs
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import os, { homedir } from "node:os";
+import os, { homedir as homedir2 } from "node:os";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
-function credentialsFilePath(homeDir = homedir()) {
+function credentialsFilePath(homeDir = heyspexHome()) {
   return join2(homeDir, ".heyspex", "credentials.yaml");
 }
 function parseMcpToken(raw) {
@@ -122,14 +137,14 @@ function readLegacyConfigAccountId(read, homeDir) {
   const value = raw?.match(CONFIG_ACCOUNT_ID_RE)?.[1]?.trim() ?? "";
   return value || null;
 }
-function readBearer({ env = process.env, homeDir = homedir(), readFile, accountId } = {}) {
+function readBearer({ env = process.env, homeDir = heyspexHome(), readFile, accountId } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, "utf8"));
   const credentialsText = readTextOrNull(read, credentialsFilePath(homeDir));
   const named = typeof accountId === "string" && accountId.trim() ? accountId.trim() : null;
   const legacyAccountId = named && parseCredentialsStore(credentialsText).schemaVersion === 1 ? readLegacyConfigAccountId(read, homeDir) : null;
   return resolveBearer({ envToken: env?.[MCP_TOKEN_ENV], credentialsText, accountId: named, legacyAccountId });
 }
-function readCurrentAccountId({ homeDir = homedir(), readFile } = {}) {
+function readCurrentAccountId({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, "utf8"));
   const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
   if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
@@ -142,6 +157,7 @@ var MCP_TOKEN_ENV, MCP_TOKEN_LINE_RE, CREDENTIALS_SCHEMA_VERSION, LEGACY_ACCOUNT
 var init_credentials = __esm({
   "vendor/heyspex-mcp/credentials.mjs"() {
     "use strict";
+    init_heyspex_home();
     MCP_TOKEN_ENV = "HEYSPEX_MCP_TOKEN";
     MCP_TOKEN_LINE_RE = /^mcp_token:[ \t]*["']?([^"'\r\n#]+)/m;
     CREDENTIALS_SCHEMA_VERSION = 2;
@@ -153,11 +169,11 @@ var init_credentials = __esm({
 });
 
 // scripts/lib/dev-mode.mjs
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { join as join7 } from "node:path";
-function devModeFilePath(homeDir = homedir6()) {
-  return join7(homeDir, ".heyspex", DEV_MODE_FILENAME);
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join8 } from "node:path";
+function devModeFilePath(homeDir = heyspexHome()) {
+  return join8(homeDir, ".heyspex", DEV_MODE_FILENAME);
 }
 function normalizeMode(raw) {
   const v = String(raw ?? "").trim().toLowerCase();
@@ -181,7 +197,7 @@ function deriveSemantics(mode, reliance) {
     vaultWriteMode: local ? "local" : "cloud"
   };
 }
-function readLocalDevModeRecord({ homeDir = homedir6(), readFile = defaultReadFile } = {}) {
+function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
     raw = readFile(devModeFilePath(homeDir));
@@ -211,7 +227,7 @@ function readLocalDevModeRecord({ homeDir = homedir6(), readFile = defaultReadFi
 }
 function resolveDevMode({
   env = process.env,
-  homeDir = homedir6(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = void 0
 } = {}) {
@@ -274,17 +290,18 @@ var CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, DEV_MODE_FILENAME, defaultReadFile;
 var init_dev_mode = __esm({
   "scripts/lib/dev-mode.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
     CLOUD_CONSOLE_URL = "https://app.heyspex.com";
     LOCAL_CONSOLE_URL = "http://localhost:3000";
     DEV_MODE_FILENAME = "dev-mode.json";
-    defaultReadFile = (p) => readFileSync6(p, "utf8");
+    defaultReadFile = (p) => readFileSync7(p, "utf8");
   }
 });
 
 // spex-console/bin/hs-check.ts
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync9 } from "node:fs";
 import path2 from "node:path";
 import process3 from "node:process";
 
@@ -822,17 +839,19 @@ function hsCommand(args = "", options = {}) {
 }
 
 // vendor/heyspex-mcp/console-fetch.mjs
+init_heyspex_home();
 init_credentials();
-import { readFileSync as readFileSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join5 } from "node:path";
+import { readFileSync as readFileSync5 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join6 } from "node:path";
 
 // vendor/heyspex-mcp/session-owner.mjs
+init_heyspex_home();
 init_credentials();
 import { readFileSync as readFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
+import { homedir as homedir3 } from "node:os";
 import { join as join3 } from "node:path";
-function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir2(), readFile } = {}) {
+function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
   const fromEnv = typeof env?.HS_ACCOUNT_ID === "string" ? env.HS_ACCOUNT_ID.trim() : "";
   if (fromEnv) return fromEnv;
   return readCurrentAccountId({ homeDir, readFile });
@@ -862,10 +881,23 @@ function isVaultLessEndpoint(method, path3) {
   });
 }
 
+// vendor/heyspex-mcp/write-outbox.mjs
+import {
+  readdirSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2,
+  mkdirSync as mkdirSync2,
+  existsSync as existsSync2,
+  renameSync as renameSync2,
+  rmSync
+} from "node:fs";
+import { basename, join as join4, isAbsolute as isAbsolute2 } from "node:path";
+
 // vendor/heyspex-mcp/vault-resolve.mjs
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { homedir as homedir3, tmpdir } from "node:os";
-import { dirname as dirname3, join as join4, resolve as resolve3 } from "node:path";
+init_heyspex_home();
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir4, tmpdir } from "node:os";
+import { dirname as dirname3, join as join5, resolve as resolve3 } from "node:path";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var VAULT_NOT_REGISTERED = "VAULT_NOT_REGISTERED";
@@ -897,9 +929,9 @@ function isCloudVaultId(value) {
 var MARKER_VAULT_ID_RE = /^vault_id:[ \t]*["']?([^"'\r\n#]+)/m;
 function readMarkerVaultId(repoRootAbs, { readFile } = {}) {
   if (typeof repoRootAbs !== "string" || !repoRootAbs.trim()) return null;
-  const read = readFile ?? ((p) => readFileSync4(p, "utf8"));
+  const read = readFile ?? ((p) => readFileSync5(p, "utf8"));
   try {
-    const raw = read(join5(repoRootAbs, "heyspex.yaml"));
+    const raw = read(join6(repoRootAbs, "heyspex.yaml"));
     const value = String(raw ?? "").match(MARKER_VAULT_ID_RE)?.[1]?.trim() ?? "";
     return value || null;
   } catch {
@@ -919,9 +951,18 @@ var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMAT
 init_credentials();
 
 // spex-console/src/lib/vault-registry/registry-file.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname4, join as join6, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname4, join as join7, resolve as resolve4 } from "node:path";
+
+// spex-console/src/lib/heyspex-home.ts
+import { homedir as homedir6 } from "node:os";
+function heyspexHome2(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir6();
+}
 
 // spex-console/src/lib/vault-registry/types.ts
 var LEGACY_REGISTRY_ACCOUNT_ID = "legacy";
@@ -938,10 +979,10 @@ function emptyVaultRegistry() {
 
 // spex-console/src/lib/vault-registry/registry-file.ts
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join6(homedir5(), ".heyspex");
+  return opts.registryDir ?? join7(heyspexHome2(), ".heyspex");
 }
 function vaultRegistryFilePath(opts = {}) {
-  return join6(vaultRegistryDir(opts), "registry.json");
+  return join7(vaultRegistryDir(opts), "registry.json");
 }
 function isNonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
@@ -1042,9 +1083,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync3(filePath)) return { kind: "missing" };
+  if (!existsSync4(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync5(filePath, "utf8");
+    const raw = readFileSync6(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -1319,10 +1360,11 @@ function resolveControlScopeFromMachine(vaultRoot, opts = {}) {
 }
 
 // scripts/lib/console-url-resolver.mjs
+init_heyspex_home();
 init_dev_mode();
-import { readFileSync as readFileSync7 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
-import { join as join8 } from "node:path";
+import { readFileSync as readFileSync8 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { join as join9 } from "node:path";
 var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, "");
@@ -1348,9 +1390,9 @@ function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
   } catch {
   }
 }
-function readCredentialsConsoleUrl({ homeDir = homedir7(), readFile = defaultReadFile2 } = {}) {
+function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile2 } = {}) {
   try {
-    const raw = readFile(join8(homeDir, ".heyspex", "credentials.yaml"));
+    const raw = readFile(join9(homeDir, ".heyspex", "credentials.yaml"));
     const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
     const value = match?.[1]?.trim();
     return value && value.length > 0 ? trimTrailingSlash(value) : null;
@@ -1359,12 +1401,12 @@ function readCredentialsConsoleUrl({ homeDir = homedir7(), readFile = defaultRea
   }
 }
 function defaultReadFile2(p) {
-  return readFileSync7(p, "utf8");
+  return readFileSync8(p, "utf8");
 }
 function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery = defaultReadFile2 } = {}) {
   if (!repoRoot) return null;
   try {
-    const discovery = String(readDiscovery(join8(repoRoot, ".heyspex", "console-url")) ?? "").trim();
+    const discovery = String(readDiscovery(join9(repoRoot, ".heyspex", "console-url")) ?? "").trim();
     if (discovery.length > 0) return trimTrailingSlash(discovery);
   } catch {
   }
@@ -1392,7 +1434,7 @@ function resolveModeEnvelope({ env, homeDir }) {
 function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir7(),
+  homeDir = heyspexHome(),
   strict = false,
   devMode,
   log = (line) => process.stderr.write(line),
@@ -1489,10 +1531,10 @@ function manifestForSpecId(vaultRoot, specId) {
 }
 function resolveManifestPath(target, vaultRoot, invokedCwd) {
   const literal = path2.resolve(invokedCwd, target);
-  if (existsSync4(literal)) return literal;
+  if (existsSync5(literal)) return literal;
   if (target.endsWith(".json")) return null;
   const byId = manifestForSpecId(vaultRoot, target);
-  return existsSync4(byId) ? byId : null;
+  return existsSync5(byId) ? byId : null;
 }
 function countTscErrors(output) {
   const matches = output.match(/error TS\d+/g);
@@ -1506,12 +1548,12 @@ function resolveWindowsPosixShell() {
     "C:\\Program Files\\Git\\bin\\bash.exe"
   ].filter((c) => typeof c === "string" && c.length > 0);
   for (const candidate of candidates) {
-    if (existsSync4(candidate)) return cachedPosixShell = candidate;
+    if (existsSync5(candidate)) return cachedPosixShell = candidate;
   }
   const where = spawnSync("where", ["bash"], { encoding: "utf8", windowsHide: true });
   if (where.status === 0 && where.stdout) {
     const hit = where.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).find((line) => !/\\system32\\/i.test(line));
-    if (hit && existsSync4(hit)) return cachedPosixShell = hit;
+    if (hit && existsSync5(hit)) return cachedPosixShell = hit;
   }
   return cachedPosixShell = null;
 }
@@ -1600,7 +1642,7 @@ async function main() {
   if (process3.argv[3] === "judge") {
     const pkgRoot = resolveCodeRoot({ vaultRoot });
     const judgeScript = path2.join(pkgRoot, "dev-factory", "judge.mjs");
-    if (!existsSync4(judgeScript)) {
+    if (!existsSync5(judgeScript)) {
       process3.stderr.write(
         `hs check judge: script not found at ${judgeScript} (source checkout only \u2014 not available in a published install).
 `
@@ -1642,7 +1684,7 @@ async function main() {
     process3.exitCode = EXIT.NOT_FOUND;
     return;
   }
-  const { manifest, error } = parseChecksManifest(readFileSync8(manifestPath, "utf-8"));
+  const { manifest, error } = parseChecksManifest(readFileSync9(manifestPath, "utf-8"));
   if (error) {
     process3.stderr.write(`hs check: ${manifestPath}: ${error}
 `);
@@ -1674,7 +1716,7 @@ async function main() {
   process3.exitCode = reportExitCode(report);
 }
 async function reportVerdict(target, report, vaultRoot, unattended = false) {
-  if (existsSync4(target) || target.endsWith(".json")) {
+  if (existsSync5(target) || target.endsWith(".json")) {
     process3.stderr.write(
       "hs check: --report needs a spec-id target (to identify the claim), not a manifest path.\n"
     );
@@ -1682,7 +1724,7 @@ async function reportVerdict(target, report, vaultRoot, unattended = false) {
   }
   const consoleUrl = resolveSpexConsoleUrl(vaultRoot, (p) => {
     try {
-      return readFileSync8(p, "utf-8");
+      return readFileSync9(p, "utf-8");
     } catch {
       return null;
     }