heyspex 0.2.2 → 0.2.3

package/dist/cli/hs-vault.mjs

@@ -129,9 +129,9 @@ function resolveBearer({ envToken, credentialsText, accountId: accountId2, legac
   if (entry?.mcp_token) return { token: entry.mcp_token, source: "credentials-file" };
   return { token: null, source: null };
 }
-function readTextOrNull(read, path5) {
+function readTextOrNull(read, path6) {
   try {
-    const raw = read(path5);
+    const raw = read(path6);
     return typeof raw === "string" ? raw : null;
   } catch {
     return null;
@@ -196,13 +196,13 @@ var init_session_owner = __esm({
 });
 
 // spex-console/src/lib/heyspex-home.ts
-import { homedir as homedir6 } from "node:os";
+import { homedir as homedir7 } 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();
+  return homedir7();
 }
 var init_heyspex_home2 = __esm({
   "spex-console/src/lib/heyspex-home.ts"() {
@@ -230,7 +230,7 @@ var init_types = __esm({
 });
 
 // spex-console/src/lib/vault-registry/registry-file.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname4, join as join7, resolve as resolve4 } from "node:path";
 function vaultRegistryDir(opts = {}) {
   return opts.registryDir ?? join7(heyspexHome2(), ".heyspex");
@@ -337,9 +337,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync4(filePath)) return { kind: "missing" };
+  if (!existsSync5(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync6(filePath, "utf8");
+    const raw = readFileSync7(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -409,10 +409,10 @@ function assertNotRealHomeRegistryUnderTest(filePath) {
 function writeVaultRegistry(registry, opts = {}) {
   const filePath = vaultRegistryFilePath(opts);
   assertNotRealHomeRegistryUnderTest(filePath);
-  mkdirSync3(dirname4(filePath), { recursive: true });
+  mkdirSync4(dirname4(filePath), { recursive: true });
   const tmpPath = `${filePath}.tmp`;
-  writeFileSync3(tmpPath, serializeVaultRegistry(registry), "utf8");
-  renameSync3(tmpPath, filePath);
+  writeFileSync4(tmpPath, serializeVaultRegistry(registry), "utf8");
+  renameSync4(tmpPath, filePath);
 }
 function isValidId(id) {
   if (!isNonEmptyString(id)) return false;
@@ -581,10 +581,10 @@ function rekeyVaultRowsToCloudIds(registry, proofs, plan) {
   };
 }
 function planRegistryMigration(registry, opts = {}) {
-  const pathExists = opts.pathExists ?? ((p) => existsSync4(p));
+  const pathExists = opts.pathExists ?? ((p) => existsSync5(p));
   const readMarker = opts.readMarker ?? ((root) => {
     try {
-      return readFileSync6(join7(root, "heyspex.yaml"), "utf8");
+      return readFileSync7(join7(root, "heyspex.yaml"), "utf8");
     } catch {
       return null;
     }
@@ -735,8 +735,8 @@ var init_registry_file = __esm({
 });
 
 // scripts/lib/dev-mode.mjs
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
 import { join as join8 } from "node:path";
 function devModeFilePath(homeDir = heyspexHome()) {
   return join8(homeDir, ".heyspex", DEV_MODE_FILENAME);
@@ -791,6 +791,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(),
@@ -830,6 +835,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,
@@ -847,7 +853,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -861,7 +868,7 @@ var init_dev_mode = __esm({
     CLOUD_CONSOLE_URL = "https://app.heyspex.com";
     LOCAL_CONSOLE_URL = "http://localhost:3000";
     DEV_MODE_FILENAME = "dev-mode.json";
-    defaultReadFile = (p) => readFileSync7(p, "utf8");
+    defaultReadFile = (p) => readFileSync8(p, "utf8");
   }
 });
 
@@ -936,12 +943,12 @@ var init_default_workspace = __esm({
 });
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 function resolveConfiguredAccountId(opts = {}) {
   return resolveSessionOwnerUncached({
     env: opts.env ?? process.env,
     homeDir: opts.homeDir ?? heyspexHome2(),
-    readFile: opts.readFile ?? ((p) => readFileSync9(p, "utf-8"))
+    readFile: opts.readFile ?? ((p) => readFileSync10(p, "utf-8"))
   });
 }
 function resolveCloudAccountIdOrRefuse(opts = {}) {
@@ -962,10 +969,10 @@ function classifyHttpFailureReason(res) {
   if (res.status === 401) return "unauthorized";
   return "server-error";
 }
-async function cloudHttpRequest(http, method, path5, body) {
-  const scopeHeaders = http.scope ? http.scope.headersFor(method, path5) : {};
+async function cloudHttpRequest(http, method, path6, body) {
+  const scopeHeaders = http.scope ? http.scope.headersFor(method, path6) : {};
   try {
-    const res = await http.fetchImpl(`${http.consoleUrl}${path5}`, {
+    const res = await http.fetchImpl(`${http.consoleUrl}${path6}`, {
       method,
       headers: {
         "content-type": "application/json",
@@ -1036,8 +1043,8 @@ async function classifyWorkspaceConflictHttp(id, conflictJson, http) {
   if (!Array.isArray(rows)) return { written: false, reason: "server-error" };
   return rows.some((w) => w.id === id) ? { written: true } : { written: false, reason: "owned-by-other-account" };
 }
-async function mutateHttp(http, method, path5, body, landed) {
-  const res = await cloudHttpRequest(http, method, path5, body);
+async function mutateHttp(http, method, path6, body, landed) {
+  const res = await cloudHttpRequest(http, method, path6, body);
   if (res.ok) return landed;
   if (res.status === 404) return "not_found";
   if (res.status === 403 && isOwnedByOtherAccountCode(errorCodeOf(res.json))) {
@@ -3432,13 +3439,13 @@ var init_spec_read_service = __esm({
 });
 
 // spex-console/bin/hs-vault.ts
-import { existsSync as existsSync8, readFileSync as readFileSync11 } from "node:fs";
-import path4 from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync12 } from "node:fs";
+import path5 from "node:path";
 import process4 from "node:process";
 import { createInterface as createInterface2 } from "node:readline/promises";
 
 // spex-console/src/lib/cli/control-shared.ts
-import path from "node:path";
+import path2 from "node:path";
 
 // scripts/lib/hs-command.mjs
 import { existsSync } from "node:fs";
@@ -3462,8 +3469,8 @@ var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER
 init_heyspex_home();
 init_credentials();
 init_session_owner();
-import { readFileSync as readFileSync5 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
 import { join as join6 } from "node:path";
 
 // vendor/heyspex-mcp/vault-less-endpoints.mjs
@@ -3476,14 +3483,14 @@ var VAULT_LESS_ENDPOINTS = Object.freeze([
   "GET /api/workspaces",
   "* /api/admin/dev-mode"
 ]);
-function pathnameOf(path5) {
-  const raw = String(path5 ?? "").split("?")[0].split("#")[0];
+function pathnameOf(path6) {
+  const raw = String(path6 ?? "").split("?")[0].split("#")[0];
   const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
   return noTrailing || "/";
 }
-function isVaultLessEndpoint(method, path5) {
+function isVaultLessEndpoint(method, path6) {
   const m = String(method || "GET").toUpperCase();
-  const pathname = pathnameOf(path5);
+  const pathname = pathnameOf(path6);
   return VAULT_LESS_ENDPOINTS.some((row) => {
     const [rowMethod, rowPath] = row.split(" ");
     return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
@@ -3503,7 +3510,9 @@ import {
 import { basename, join as join4, isAbsolute as isAbsolute2 } from "node:path";
 
 // scripts/lib/shared-path-helpers.mjs
+import { realpathSync } from "node:fs";
 import { isAbsolute, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function resolveCodeRoot({
   explicit,
   packageRoot,
@@ -3522,9 +3531,30 @@ function resolveCodeRoot({
 
 // vendor/heyspex-mcp/vault-resolve.mjs
 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";
+import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { homedir as homedir5, 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 dirname3, join as join5, resolve as resolve3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-binding.mjs
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  realpathSync as realpathSync2,
+  renameSync as renameSync3,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import path from "node:path";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
@@ -3628,11 +3658,11 @@ function readPairedBearer(opts = {}) {
 function readPairedToken(opts = {}) {
   return readPairedBearer(opts).token ?? void 0;
 }
-function scopeHeadersFor(scope, method, path5) {
+function scopeHeadersFor(scope, method, path6) {
   if (scope === "none") {
-    if (!isVaultLessEndpoint(method, path5)) {
+    if (!isVaultLessEndpoint(method, path6)) {
       throw new Error(
-        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path5} 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()} ${path6} is vault-scoped and must name { accountId, vaultId }.`
       );
     }
     return {};
@@ -3643,7 +3673,7 @@ function cloudRequestScope(scope) {
   const named = { accountId: scope.accountId, vaultId: scope.vaultId };
   return {
     ...named,
-    headersFor: (method, path5) => isVaultLessEndpoint(method, path5) ? {} : scopeHeadersFor(named, method, path5)
+    headersFor: (method, path6) => isVaultLessEndpoint(method, path6) ? {} : scopeHeadersFor(named, method, path6)
   };
 }
 function withCloudScope(deps, accountId2, vaultId) {
@@ -3654,8 +3684,8 @@ function withCloudScope(deps, accountId2, vaultId) {
 // scripts/lib/console-url-resolver.mjs
 init_heyspex_home();
 init_dev_mode();
-import { readFileSync as readFileSync8 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
 import { join as join9 } from "node:path";
 var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 function trimTrailingSlash(url) {
@@ -3693,7 +3723,7 @@ function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile: readFile
   }
 }
 function defaultReadFile2(p) {
-  return readFileSync8(p, "utf8");
+  return readFileSync9(p, "utf8");
 }
 function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery = defaultReadFile2 } = {}) {
   if (!repoRoot) return null;
@@ -3793,7 +3823,7 @@ var HELP = [
 init_heyspex_home2();
 init_registry_file();
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { join as join10 } from "node:path";
 import { createInterface } from "node:readline/promises";
 init_credentials();
@@ -3802,7 +3832,7 @@ init_session_owner();
 // 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" };
@@ -3877,12 +3907,15 @@ var HELP2 = [
   "(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 --",
@@ -3955,9 +3988,9 @@ function parseMarkerVaultPath(content) {
 function readPinnedVaultRoot(repoRoot, deps) {
   const pins = [];
   for (const rel of SATELLITE_MANIFEST_RELS) {
-    const path5 = deps.joinPath(repoRoot, ...rel);
-    if (!deps.fileExists(path5)) continue;
-    const raw = deps.readFile(path5);
+    const path6 = deps.joinPath(repoRoot, ...rel);
+    if (!deps.fileExists(path6)) continue;
+    const raw = deps.readFile(path6);
     if (!raw) continue;
     let value;
     try {
@@ -4222,7 +4255,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) => join10(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync5(p));
+  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join10(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync6(p));
   return {
     consoleUrl,
     interactive: opts.interactive ?? isInteractiveTerminal(),
@@ -4294,7 +4327,7 @@ init_postgres();
 init_neon_probe();
 
 // spex-console/src/lib/vault-registry/repo-identity.ts
-import path2 from "node:path";
+import path3 from "node:path";
 
 // spex-console/src/lib/vault-registry/vault-workspace-store.ts
 function mapProbeFailureReason(reason) {
@@ -4775,7 +4808,7 @@ function buildCloseNotDestroyConfirm(kind, verb, displayName) {
 }
 
 // spex-console/src/lib/vault-registry/list.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 init_account_pointer();
 init_registry_file();
 async function defaultNeonReadTierEnabled() {
@@ -4808,7 +4841,7 @@ async function listVaultsForWorkspace(accountId2, workspaceId, deps = {}) {
   const activeId = await getActiveVault(accountId2, sharedPointerDeps) ?? await adoptSole(accountId2, sharedPointerDeps);
   const rows = deps.includeArchived ? allRows : allRows.filter((v) => !v.archived);
   const scoped = workspaceId ? rows.filter((v) => v.workspace_id === workspaceId) : rows;
-  const pathExists = deps.pathExists ?? existsSync6;
+  const pathExists = deps.pathExists ?? existsSync7;
   const anyPathUnusable = scoped.some((v) => !v.repo_root_abs || !pathExists(v.repo_root_abs));
   const neonBackedServeable = anyPathUnusable && neonRows !== null ? await (deps.neonReadTierEnabled ?? defaultNeonReadTierEnabled)() : false;
   return {
@@ -4976,9 +5009,9 @@ async function unregisterVault(input, deps = {}) {
 }
 
 // spex-console/src/lib/vault-resolve/index.ts
-import { existsSync as existsSync7, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync11, realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import path3 from "node:path";
+import path4 from "node:path";
 var UNREGISTERED_VAULT_ID2 = "unregistered";
 var NoActiveVaultError = class _NoActiveVaultError extends Error {
   constructor(message2 = "resolveActiveVaultRoot: no active vault found -- no explicit vaultId, no heyspex.yaml or specs/ directory at or above cwd, no HEYSPEX_VAULT_ROOT/HEYSPEX_VAULT_DIR env, and no account active_vault_id. Run `hs vault register` to register a vault.") {
@@ -4986,6 +5019,22 @@ var NoActiveVaultError = class _NoActiveVaultError extends Error {
     this.name = "NoActiveVaultError";
     Object.setPrototypeOf(this, _NoActiveVaultError.prototype);
   }
+  /** Stable machine code ([[HS-TYJA]]), shared with `vault-binding.mjs`. */
+  code = "VAULT_UNBOUND";
+  /** The exact repair command. */
+  fix = "hs vault bind --vault <name|id>";
+  /** The folder resolution walked from (forward slashes), when known. */
+  from = null;
+};
+var VaultResolutionFailure = class _VaultResolutionFailure extends NoActiveVaultError {
+  constructor(code, message2, fix, from) {
+    super(message2);
+    this.name = "VaultResolutionError";
+    this.code = code;
+    this.fix = fix;
+    this.from = from ? from.replace(/\\/g, "/") : null;
+    Object.setPrototypeOf(this, _VaultResolutionFailure.prototype);
+  }
 };
 async function defaultRegistryLookup() {
   return null;
@@ -4994,13 +5043,13 @@ async function defaultAccountPointerLookup() {
   return null;
 }
 function finalize(vaultId, repoRootAbs, source) {
-  const resolvedRoot = path3.resolve(repoRootAbs);
+  const resolvedRoot = path4.resolve(repoRootAbs);
   return {
     vaultId,
     repoRootAbs: resolvedRoot,
     // Always derived the same way regardless of which layer resolved the
     // root, per this task's acceptance criteria.
-    specsDirAbs: path3.join(resolvedRoot, "specs"),
+    specsDirAbs: path4.join(resolvedRoot, "specs"),
     source
   };
 }
@@ -5012,7 +5061,7 @@ function parseMarkerVaultId(content) {
 }
 function readMarkerVaultId(dir) {
   try {
-    return parseMarkerVaultId(readFileSync10(path3.join(dir, "heyspex.yaml"), "utf8"));
+    return parseMarkerVaultId(readFileSync11(path4.join(dir, "heyspex.yaml"), "utf8"));
   } catch {
     return null;
   }
@@ -5020,39 +5069,75 @@ function readMarkerVaultId(dir) {
 function readMarkerSatellite(dir) {
   let raw;
   try {
-    raw = readFileSync10(path3.join(dir, "heyspex.yaml"), "utf8");
+    raw = readFileSync11(path4.join(dir, "heyspex.yaml"), "utf8");
   } catch {
     return null;
   }
   const vaultPath = parseMarkerVaultPath(raw);
   if (!vaultPath) return null;
   const vaultId = parseMarkerVaultId(raw);
-  const candidate = path3.resolve(dir, vaultPath);
+  const candidate = path4.resolve(dir, vaultPath);
   let vaultRootAbs = null;
-  if (candidate.toLowerCase() !== path3.resolve(dir).toLowerCase() && isVaultRootDir(candidate)) {
+  if (candidate.toLowerCase() !== path4.resolve(dir).toLowerCase() && isVaultRootDir(candidate)) {
     const theirs = readMarkerVaultId(candidate);
     if (!vaultId || !theirs || theirs === vaultId) vaultRootAbs = candidate;
   }
   return { vaultId, vaultRootAbs };
 }
 function isVaultRootDir(dir) {
-  const norm = (p) => path3.resolve(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+  const norm = (p) => path4.resolve(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
   if (norm(dir) === norm(tmpdir2())) return false;
-  return existsSync7(path3.join(dir, "heyspex.yaml")) || existsSync7(path3.join(dir, "specs"));
+  if (!existsSync8(path4.join(dir, "specs")) && readRepoBinding2(dir)) return false;
+  return existsSync8(path4.join(dir, "heyspex.yaml")) || existsSync8(path4.join(dir, "specs"));
+}
+function parseRepoBinding(content) {
+  const src = String(content ?? "");
+  if (/^(vault_id|vault_root):/m.test(src)) return null;
+  const kind = src.match(/^kind:\s*(.+?)\s*$/m)?.[1]?.replace(/^["']|["']$/g, "").trim();
+  if (kind && kind !== "repo-binding") return null;
+  const lines = src.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^vault:(\s|$)/.test(l));
+  if (start === -1) return null;
+  const unq = (v) => v.trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
+  const scalar = lines[start].slice("vault:".length).trim();
+  if (scalar && !scalar.startsWith("#")) {
+    const id = unq(scalar);
+    return id ? { id, name: null, remote: null } : null;
+  }
+  const out = {
+    id: null,
+    name: null,
+    remote: null
+  };
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const l = lines[i];
+    if (!l.trim() || /^\s*#/.test(l)) continue;
+    if (!/^\s+/.test(l)) break;
+    const m = l.match(/^\s+([a-z_]+):\s*(.*)$/);
+    if (m && (m[1] === "id" || m[1] === "name" || m[1] === "remote")) out[m[1]] = unq(m[2]) || null;
+  }
+  return out.id ? { id: out.id, name: out.name, remote: out.remote } : null;
+}
+function readRepoBinding2(dir) {
+  try {
+    return parseRepoBinding(readFileSync11(path4.join(dir, "heyspex.yaml"), "utf8"));
+  } catch {
+    return null;
+  }
 }
 function findCwdVaultOrAttachment(startDir, stopAt) {
   const deps = {
-    fileExists: (p) => existsSync7(p),
+    fileExists: (p) => existsSync8(p),
     readFile: (p) => {
       try {
-        return readFileSync10(p, "utf8");
+        return readFileSync11(p, "utf8");
       } catch {
         return null;
       }
     },
-    joinPath: (...segments) => path3.join(...segments)
+    joinPath: (...segments) => path4.join(...segments)
   };
-  const boundary = stopAt ? path3.resolve(stopAt) : null;
+  const boundary = stopAt ? path4.resolve(stopAt) : null;
   let dir = startDir;
   for (let i = 0; i < 256; i += 1) {
     const marked = readMarkerSatellite(dir);
@@ -5064,15 +5149,33 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
       };
     }
     const pinned = readPinnedVaultRoot(dir, deps).find((pin) => !isAtOrUnder(pin.value, dir));
-    if (pinned) return { repoRootAbs: path3.resolve(pinned.value), satellite: true };
+    if (pinned) return { repoRootAbs: path4.resolve(pinned.value), satellite: true };
     if (isVaultRootDir(dir)) return { repoRootAbs: dir, satellite: false };
+    const binding = readRepoBinding2(dir);
+    if (binding) return { repoRootAbs: dir, satellite: false, binding };
     if (boundary && dir === boundary) return null;
-    const parent = path3.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
   return null;
 }
+function isExistingDir(p) {
+  try {
+    return statSync4(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function envNotVaultError(name, raw, abs, from) {
+  const shown = abs.replace(/\\/g, "/");
+  return new VaultResolutionFailure(
+    "VAULT_NOT_FOUND",
+    `${name}=${raw} does not name a vault checkout (${shown}). Unset ${name} so the vault bound to this repo is used (\`hs vault resolve\` shows it), or point it at a vault checkout.`,
+    `unset ${name}`,
+    from
+  );
+}
 async function resolveActiveVaultRoot(options = {}) {
   const registryLookup = options.registryLookup ?? defaultRegistryLookup;
   const accountPointerLookup = options.accountPointerLookup ?? defaultAccountPointerLookup;
@@ -5084,7 +5187,7 @@ async function resolveActiveVaultRoot(options = {}) {
     }
   };
   const finalizePathTier = async (repoRootAbs, source) => {
-    const resolvedRoot = path3.resolve(repoRootAbs);
+    const resolvedRoot = path4.resolve(repoRootAbs);
     const recovered = await registryLookupByRoot(resolvedRoot);
     if (recovered) return finalize(recovered.id, resolvedRoot, source);
     return finalize(UNREGISTERED_VAULT_ID2, resolvedRoot, source);
@@ -5104,17 +5207,79 @@ async function resolveActiveVaultRoot(options = {}) {
       detail: `explicit vaultId "${options.vaultId}" has no registry.json row and no Neon row`
     });
   }
-  const cwdBase = path3.resolve(options.cwd ?? process.cwd());
+  const fromDir = path4.resolve(options.cwd ?? process.cwd());
+  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
+  if (envRoot) {
+    const root = path4.resolve(envRoot.trim());
+    const envIsVault = isExistingDir(root) && isVaultRootDir(root);
+    if (!envIsVault && !await registryLookupByRoot(root)) {
+      onTier({
+        tier: "env-vault-root",
+        outcome: "empty",
+        detail: `${envRoot} is not a vault checkout`
+      });
+      throw envNotVaultError("HEYSPEX_VAULT_ROOT", envRoot, root, fromDir);
+    }
+    onTier({ tier: "env-vault-root", outcome: "resolved", detail: envRoot });
+    return finalizePathTier(root, "env-vault-root");
+  }
+  onTier({ tier: "env-vault-root", outcome: "skipped", detail: "HEYSPEX_VAULT_ROOT unset" });
+  const envDir = process.env.HEYSPEX_VAULT_DIR;
+  if (envDir) {
+    const specsDirFromEnv = path4.resolve(envDir.trim());
+    const envDirIsSpecs = isExistingDir(specsDirFromEnv) && path4.basename(specsDirFromEnv).toLowerCase() === "specs";
+    const envDirRegistered = Boolean(await registryLookupByRoot(path4.dirname(specsDirFromEnv)));
+    if (!envDirIsSpecs && !envDirRegistered) {
+      onTier({
+        tier: "env-vault-dir",
+        outcome: "empty",
+        detail: `${envDir} is not a specs/ folder`
+      });
+      throw envNotVaultError("HEYSPEX_VAULT_DIR", envDir, specsDirFromEnv, fromDir);
+    }
+    onTier({ tier: "env-vault-dir", outcome: "resolved", detail: envDir });
+    return finalizePathTier(path4.dirname(specsDirFromEnv), "env-vault-dir");
+  }
+  onTier({ tier: "env-vault-dir", outcome: "skipped", detail: "HEYSPEX_VAULT_DIR unset" });
+  let cwdBase = path4.resolve(options.cwd ?? process.cwd());
+  try {
+    cwdBase = realpathSync4(cwdBase);
+  } catch {
+  }
   const cwdMatch = findCwdVaultOrAttachment(cwdBase, options.cwdWalkRoot);
+  if (cwdMatch?.binding) {
+    const record = await registryLookup(cwdMatch.binding.id);
+    const root = record ? record.repoRootAbs : null;
+    if (root) {
+      onTier({
+        tier: "repo-binding",
+        outcome: "resolved",
+        detail: `${cwdMatch.repoRootAbs} -> ${cwdMatch.binding.id}`
+      });
+      return finalize(cwdMatch.binding.id, root, "repo-binding");
+    }
+    onTier({
+      tier: "repo-binding",
+      outcome: "no-registry-row",
+      detail: `${cwdMatch.repoRootAbs}/heyspex.yaml binds ${cwdMatch.binding.id}, which has no registry row (or folder) on this machine`
+    });
+    const bindingDir = cwdMatch.repoRootAbs.replace(/\\/g, "/");
+    throw new VaultResolutionFailure(
+      "VAULT_BINDING_BROKEN",
+      `${bindingDir}/heyspex.yaml binds this repo to vault ${cwdMatch.binding.name ?? cwdMatch.binding.id} (${cwdMatch.binding.id}), but this machine has no registered checkout of it. Clone it (or \`hs pull\` in an existing checkout), \`hs vault register <path>\`, then \`hs vault bind --vault ${cwdMatch.binding.id}\` in ${bindingDir}.`,
+      `hs vault bind --vault ${cwdMatch.binding.id}`,
+      cwdBase
+    );
+  }
   if (cwdMatch?.satellite) {
     onTier({ tier: "satellite-pin", outcome: "resolved", detail: cwdMatch.repoRootAbs });
     if (cwdMatch.markerVaultId) {
-      return finalize(cwdMatch.markerVaultId, path3.resolve(cwdMatch.repoRootAbs), "satellite-pin");
+      return finalize(cwdMatch.markerVaultId, path4.resolve(cwdMatch.repoRootAbs), "satellite-pin");
     }
     return finalizePathTier(cwdMatch.repoRootAbs, "satellite-pin");
   }
-  if (cwdMatch) {
-    const root = path3.resolve(cwdMatch.repoRootAbs);
+  if (cwdMatch && !cwdMatch.binding) {
+    const root = path4.resolve(cwdMatch.repoRootAbs);
     const record = await registryLookupByRoot(root);
     const markerVaultId = readMarkerVaultId(root);
     if (markerVaultId) {
@@ -5137,19 +5302,18 @@ async function resolveActiveVaultRoot(options = {}) {
     outcome: "empty",
     detail: `no satellite pin, heyspex.yaml or specs/ at or above ${cwdBase}`
   });
-  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
-  if (envRoot) {
-    onTier({ tier: "env-vault-root", outcome: "resolved", detail: envRoot });
-    return finalizePathTier(path3.resolve(envRoot), "env-vault-root");
-  }
-  onTier({ tier: "env-vault-root", outcome: "skipped", detail: "HEYSPEX_VAULT_ROOT unset" });
-  const envDir = process.env.HEYSPEX_VAULT_DIR;
-  if (envDir) {
-    const specsDirFromEnv = path3.resolve(envDir);
-    onTier({ tier: "env-vault-dir", outcome: "resolved", detail: envDir });
-    return finalizePathTier(path3.dirname(specsDirFromEnv), "env-vault-dir");
+  if (!options.allowAccountPointer) {
+    onTier({
+      tier: "account-pointer",
+      outcome: "skipped",
+      detail: "account pointer retired for local resolution (HS-TYJA)"
+    });
+    const unbound = new NoActiveVaultError(
+      `No HeySpex vault is bound to ${cwdBase.replace(/\\/g, "/")}, and it is not inside a vault checkout. There is no default "active" vault. Bind this repo: \`hs vault bind --vault <name|id>\` (register a vault checkout first with \`hs vault register <path>\` if \`hs vault list\` shows none).`
+    );
+    unbound.from = cwdBase.replace(/\\/g, "/");
+    throw unbound;
   }
-  onTier({ tier: "env-vault-dir", outcome: "skipped", detail: "HEYSPEX_VAULT_DIR unset" });
   const pointerVaultId = await accountPointerLookup(options.accountId);
   if (pointerVaultId) {
     const record = await registryLookup(pointerVaultId);
@@ -5485,11 +5649,11 @@ function readLocalReceiptSide(subject, registryOpts = {}) {
     return unreadSide(`registry.json could not be read: ${message(err)}`);
   }
 }
-async function readList(http, path5, key) {
-  const res = await cloudHttpRequest(http, "GET", path5);
+async function readList(http, path6, key) {
+  const res = await cloudHttpRequest(http, "GET", path6);
   const rows = res.json?.[key];
   if (!res.ok || !Array.isArray(rows)) {
-    return { reason: `GET ${path5.split("?")[0]} answered HTTP ${res.status}` };
+    return { reason: `GET ${path6.split("?")[0]} answered HTTP ${res.status}` };
   }
   return { rows: rows.filter((r) => Boolean(r) && typeof r === "object") };
 }
@@ -6034,6 +6198,7 @@ async function readActivePointers(deps) {
   const str2 = (v) => typeof v === "string" && v ? v : null;
   return { local, cloud: { vault: str2(body.vault_id), workspace: str2(body.workspace_id) } };
 }
+var SWITCH_DEPRECATION_NOTE = "Note (deprecated): local agents, hs, spexcode and the MCP server ignore the active vault -- they write to the vault bound to the repo they run in. Use `hs vault bind --vault <name|id>` in a repo, and `hs vault resolve` to see which vault a folder writes to.";
 async function runSwitch(args, deps) {
   deps = scopedTo(deps, args.id);
   const subject = { accountId: accountId(deps), vaultId: args.id };
@@ -6117,11 +6282,13 @@ async function runSwitch(args, deps) {
   return finishVaultWrite(
     {
       code: EXIT.OK,
-      message: `Switched active vault to "${args.id}"${workspaceSwitched ? ` (workspace: ${workspaceId})` : ""}.`,
+      message: `Switched active vault to "${args.id}"${workspaceSwitched ? ` (workspace: ${workspaceId})` : ""}.
+` + SWITCH_DEPRECATION_NOTE,
       payload: {
         ok: true,
         vault_id: args.id,
-        workspace_id: workspaceSwitched ? workspaceId : null
+        workspace_id: workspaceSwitched ? workspaceId : null,
+        deprecation: SWITCH_DEPRECATION_NOTE
       },
       isError: false
     },
@@ -6556,7 +6723,7 @@ function runEntry(name, main2, options = {}) {
 // spex-console/bin/hs-vault.ts
 function readFile(p) {
   try {
-    return readFileSync11(p, "utf8");
+    return readFileSync12(p, "utf8");
   } catch {
     return null;
   }
@@ -6594,7 +6761,7 @@ async function main() {
     return;
   }
   const vaultIdOverride = process4.env.HS_VAULT_ID_OVERRIDE?.trim() || void 0;
-  const cwd = process4.env.HS_INVOKED_CWD?.trim() || (process4.env.HS_VAULT_ROOT ? path4.resolve(process4.env.HS_VAULT_ROOT) : process4.cwd());
+  const cwd = process4.env.HS_INVOKED_CWD?.trim() || (process4.env.HS_VAULT_ROOT ? path5.resolve(process4.env.HS_VAULT_ROOT) : process4.cwd());
   const invokedCwd = process4.env.HS_INVOKED_CWD?.trim() || process4.cwd();
   const consoleUrl = resolveSpexConsoleUrl(cwd, readFile);
   const gate = await gateWriteVerb({
@@ -6602,7 +6769,7 @@ async function main() {
     sub: parsed.args.sub,
     writeVerbs: VAULT_WRITE_VERBS,
     flags: identityArgv.flags,
-    io: defaultIdentityGateIo({ consoleUrl, platformRoot: path4.resolve(process4.cwd(), "..") })
+    io: defaultIdentityGateIo({ consoleUrl, platformRoot: path5.resolve(process4.cwd(), "..") })
   });
   if (gate && !gate.ok) {
     process4.stderr.write(
@@ -6615,17 +6782,17 @@ async function main() {
   const result = await runVault(
     parsed.args,
     {
-      fileExists: (p) => existsSync8(p),
+      fileExists: (p) => existsSync9(p),
       readFile,
-      resolvePath: (p) => path4.resolve(invokedCwd, p),
-      joinPath: (...s) => path4.join(...s),
-      basename: (p) => path4.basename(p),
+      resolvePath: (p) => path5.resolve(invokedCwd, p),
+      joinPath: (...s) => path5.join(...s),
+      basename: (p) => path5.basename(p),
       now: () => (/* @__PURE__ */ new Date()).toISOString(),
       cwd,
       conflictScan: {
-        fileExists: (p) => existsSync8(p),
+        fileExists: (p) => existsSync9(p),
         readFile,
-        joinPath: (...s) => path4.join(...s)
+        joinPath: (...s) => path5.join(...s)
       },
       confirm,
       neon: { http: { fetchImpl: fetch, consoleUrl, token: readPairedToken() } }