heyspex 0.2.2 → 0.2.3

package/vendor/heyspex-mcp/vault-resolve.mjs

@@ -14,61 +14,67 @@
  * DATABASE_URL may be absent), so this port does NOT make a network/account
  * lookup. Instead it reads the offline registry file
  * (`~/.heyspex/registry.json`, same shape as
- * `spex-console/src/lib/vault-registry/registry-file.ts`) for tier-1
- * (explicit vaultId) and tier-4 (the offline active-vault pointer). That
- * offline pointer is how an MCP restart picks up a CLI `hs vault use` switch
- * without Neon.
+ * `spex-console/src/lib/vault-registry/registry-file.ts`) only to map ids to
+ * checkout paths (explicit ids, env roots, repo bindings, markers). It never
+ * reads the file's active-vault pointer.
  *
- * Precedence stack (highest wins) — ONE order shared with the TS resolver
- * (`spex-console/src/lib/vault-resolve/index.ts`), pinned row-by-row by the
- * shared fixture `spex-console/src/lib/vault-resolve/precedence-fixtures.json`
- * ([[HS-VVNQ]], decision memory `vault-resolver-precedence`). History: HS-C87T
- * put the folder the process started in above the registry pointer; HS-VVNQ
- * then put it above the env vars too, because the plugin manifest
- * (`plugins/heyspex/.mcp.json`) sets `HEYSPEX_VAULT_ROOT=${CLAUDE_PROJECT_DIR}`
- * on EVERY session — an env tier above the walk silently outranked every
- * on-disk pin and marker:
- *   1. explicit vaultId            -> registry lookup (vaults[].id)
- *   2. cwd-contained vault OR a    -> walk UP from cwd through every ancestor
- *      satellite attachment            looking for a heyspex.yaml marker, a
- *                                     specs/ dir, or a satellite repo's MCP
- *                                     manifest pin (readSatellitePin); the
- *                                     nearest match wins, attachment first.
- *                                     Sources: 'satellite-pin' (attachment);
- *                                     'cwd-marker' (heyspex.yaml carries a
- *                                     `vault_id` — that id IS the vault id,
- *                                     registry row or not); 'marker-registry-
- *                                     mismatch' (the marker id disagrees with
- *                                     the registry row for that root — the
- *                                     marker id wins and stderr names
- *                                     `hs connect --check`); 'cwd-heuristic'
- *                                     (a marker without `vault_id`, or a bare
- *                                     specs/ dir: id from the registry row, else
- *                                     the `unregistered` sentinel). Logs one
- *                                     stderr notice iff the cwd vault differs
- *                                     from the registry's active vault — silent
- *                                     when they agree.
- *   3. HEYSPEX_VAULT_ROOT env      -> repo root (legacy escape hatch)
- *   3. HEYSPEX_VAULT_DIR env       -> the specs/ dir itself (repo root = parent)
- *   4. registry active_vault_id    -> the offline active pointer (vaults[].id);
- *                                     schema v2: the current account's row
- *                                     (`accounts[current_account_id]`), v1:
- *                                     the machine-global field
- *                                     — reached only when cwd sits inside no
- *                                     vault and no env var names one
- *   5. cwd fallback                -> cwd itself (no marker found anywhere;
- *                                     preserves the pre-existing default)
+ * Precedence stack (highest wins). Owner ruling 2026-10-14 ([[HS-TYJA]],
+ * amending HS-VVNQ / decision `vault-resolver-precedence-explicit-then`):
+ * "there shouldn't be one active vault ... Vault is active when user is
+ * launched an agent in the repo folder belonging to a vault." Full contract
+ * (inputs, every failure code, what each caller does): `vault-binding.mjs`.
+ *   1. explicit vaultId            -> its registry row                'explicit'
+ *      (unknown id -> VAULT_NOT_FOUND, never a cascade)
+ *   2. HEYSPEX_VAULT_ROOT env      -> a vault (true override)          'env-vault-root'
+ *      HEYSPEX_VAULT_DIR env       -> a vault's specs/ dir             'env-vault-dir'
+ *      (a vault = a checkout on disk or a registered vault root;
+ *      anything else, e.g. an unregistered code repo -> VAULT_NOT_FOUND)
+ *   3. walk UP from the cwd (realpath'd) to the filesystem root, nearest
+ *      folder wins; at each level, in order:
+ *        satellite marker: heyspex.yaml relative `vault_path`        'satellite-pin'
+ *          (-> the clone at vault_path; not cloned here -> the satellite
+ *          dir itself with `vaultCloned: false`, which disk writers refuse)
+ *        satellite pin (.mcp.json / .cursor/mcp.json)                'satellite-pin'
+ *        vault checkout: heyspex.yaml `vault_id`                     'cwd-marker'
+ *          (disagreeing with the registry row for that root)         'marker-registry-mismatch'
+ *        vault checkout without vault_id / bare specs/               'cwd-heuristic'
+ *        heyspex.yaml `kind: repo-binding` (a bound code repo)       'repo-binding'
+ *      a linked git worktree that matched nothing walks again from its
+ *      main checkout (`worktreeOf` on the result).
+ *   4. nothing                     -> sentinel id, `error`           'unbound'
+ *      (VAULT_UNBOUND, or VAULT_BINDING_BROKEN when a binding names a
+ *      vault this machine cannot find). `resolveVaultOrThrow` throws it.
+ * The registry `active_vault_id` / per-account pointers are NEVER consulted.
  *
  * Resolution is SYNCHRONOUS (all inputs are fs/env) and, via getActiveConfig(),
- * memoized once per process. If the registry can't be read, tier 4 simply
- * finds nothing and resolution falls through to tier 5 — i.e. today's
- * behavior, so nothing regresses when no registry exists.
+ * memoized once per process. It never throws: an unreadable registry only
+ * means explicit ids and bindings cannot be mapped to folders.
  */
 
 import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { withoutUnusableDirEnv } from './usable-dir-env.mjs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import {
+  findGitCheckout,
+  isRepoBindingDir,
+  locateBoundVault,
+  readRepoBinding,
+  registryVaults,
+  unboundError,
+  VAULT_NOT_FOUND,
+  VaultResolutionError,
+} from './vault-binding.mjs';
+
+export {
+  isVaultResolutionError,
+  VAULT_BINDING_BROKEN,
+  VAULT_NOT_FOUND,
+  VAULT_UNBOUND,
+  VaultResolutionError,
+} from './vault-binding.mjs';
 
 /**
  * Placeholder vaultId for tiers 3-5, which resolve a filesystem path but have
@@ -106,11 +112,10 @@ function isNonEmptyString(v) {
  * Read + defensively parse `~/.heyspex/registry.json`. A missing or malformed
  * file returns `null` (never throws) so callers fall through to env/cwd tiers —
  * mirroring registry-file.ts `loadVaultRegistry`'s fail-closed contract.
- * Reads schema v1 and v2 alike; `active_vault_id` is the pointer
- * {@link registryPointerVaultId} picks.
+ * Reads schema v1 and v2 alike. The active pointer is NOT read.
  *
  * @param {{ registryDir?: string }} [opts]
- * @returns {{ vaults: Array<{ id: string, repo_root_abs: string }>, active_vault_id: string|null }|null}
+ * @returns {{ vaults: Array<{ id: string, repo_root_abs: string }>, raw: Record<string, unknown> }|null}
  */
 function loadRegistry(opts = {}) {
   const filePath = vaultRegistryFilePath(opts);
@@ -131,7 +136,10 @@ function loadRegistry(opts = {}) {
     if (!isNonEmptyString(raw.repo_root_abs)) continue;
     vaults.push({ id: raw.id, repo_root_abs: raw.repo_root_abs });
   }
-  return { vaults, active_vault_id: registryPointerVaultId(json) };
+  // `raw` feeds the repo-binding tier (display names, git remotes). The
+  // active pointer is deliberately NOT read: local resolution never consults
+  // it ([[HS-TYJA]]); registryPointerVaultId stays exported for the console.
+  return { vaults, raw: json };
 }
 
 /** Mirrors registry-file.ts `LEGACY_REGISTRY_ACCOUNT_ID`. */
@@ -419,49 +427,23 @@ export function findBrokenSatellitePin(startDir, stopAt) {
  */
 export function isVaultRoot(dir) {
   if (normalizeRoot(dir) === normalizeRoot(tmpdir())) return false;
+  // A bound CODE repo (heyspex.yaml `vault:` binding, no specs/) names a vault;
+  // it is not one ([[HS-TYJA]]).
+  if (isRepoBindingDir(dir)) return false;
+  // Nor is a SATELLITE code repo (heyspex.yaml `vault_path:`), even when a
+  // stray specs/ sits beside it - that is exactly the junk a mis-targeted
+  // `hs pull` left in mlc-app.
+  if (readMarkerVaultPath(dir) !== null) return false;
   return existsSync(join(dir, 'heyspex.yaml')) || existsSync(join(dir, 'specs'));
 }
 
-/**
- * Extract `vault_id: <value>` from raw heyspex.yaml text, or `null` if absent.
- * Same semantics as `spex-console/src/lib/cli/init.ts` `parseVaultId` (the
- * writer's own reader): first line-anchored `vault_id:` key, value trimmed,
- * one matching pair of surrounding quotes stripped, empty -> `null`. Kept to
- * this one line-regex on purpose — `hs init` writes the marker as flat
- * `key: value` lines, so a YAML parser buys nothing here.
- *
- * @param {string} content
- * @returns {string|null}
- */
-export function parseMarkerVaultId(content) {
-  const m = String(content ?? '').match(/^vault_id:\s*(.+?)\s*$/m);
-  if (!m) return null;
-  const unquoted = m[1].trim().replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1');
-  return unquoted.length > 0 ? unquoted : null;
-}
-
-/**
- * The `vault_id` written in `<dir>/heyspex.yaml`, or `null` (no marker, no
- * key, unreadable). Never throws.
- *
- * @param {string} dir
- * @returns {string|null}
- */
-function readMarkerVaultId(dir) {
-  try {
-    return parseMarkerVaultId(readFileSync(join(dir, 'heyspex.yaml'), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Extract `vault_path: <value>` from raw heyspex.yaml text, or `null`.
- * The PORTABLE satellite declaration (owner principles P1/P3, 2026-10-16): a
- * code repo (e.g. mlc-app) commits a `heyspex.yaml` carrying its `vault_id`
- * plus a RELATIVE `vault_path` (e.g. `../mlc-specs`) to where the attached
- * vault is usually cloned. No absolute path is ever committed. An absolute,
- * empty or unexpanded `${...}` value is not a declaration (returns null).
+ * The PORTABLE satellite declaration (owner principles 2026-10-16, HS-FWB6 on
+ * main): a code repo (e.g. mlc-app) commits a `heyspex.yaml` carrying its
+ * `vault_id` plus a RELATIVE `vault_path` (e.g. `../mlc-specs`) to where the
+ * attached vault is usually cloned. An absolute, empty or unexpanded `${...}`
+ * value is not a declaration (returns null). Same parse as main's twin.
  *
  * @param {string} content
  * @returns {string|null}
@@ -474,17 +456,24 @@ export function parseMarkerVaultPath(content) {
   return v;
 }
 
+/** The `vault_path` of `<dir>/heyspex.yaml`, or null. Never throws. */
+function readMarkerVaultPath(dir) {
+  try {
+    return parseMarkerVaultPath(readFileSync(join(dir, 'heyspex.yaml'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Is `<dir>/heyspex.yaml` a committed SATELLITE marker (it carries a relative
  * `vault_path`)? Returns the attachment it declares, or `null`.
  *
- *   - `vaultId`: the marker's `vault_id` (the vault this repo is bound to; the
- *     ONLY thing a fresh machine without the vault clone needs, because
- *     cloud-routed writes name the vault by id).
+ *   - `vaultId`: the marker's `vault_id` (the vault this repo is bound to).
  *   - `vaultRootAbs`: `resolve(dir, vault_path)` when that directory exists on
- *     THIS machine and is a vault root whose own marker does not name a
+ *     THIS machine and is a vault checkout whose own marker does not name a
  *     DIFFERENT vault id; otherwise `null` (not cloned here, or a different
- *     vault sits at that path - never read the wrong vault's disk).
+ *     vault sits at that path - never read or write the wrong vault's disk).
  *
  * @param {string} dir
  * @returns {{ vaultId: string|null, vaultPath: string, vaultRootAbs: string|null }|null}
@@ -501,13 +490,46 @@ export function readMarkerSatellite(dir) {
   const vaultId = parseMarkerVaultId(raw);
   const candidate = resolve(dir, vaultPath);
   let vaultRootAbs = null;
-  if (normalizeRoot(candidate) !== normalizeRoot(dir) && isVaultRoot(candidate)) {
+  if (normalizeRoot(candidate) !== normalizeRoot(dir) && isVaultCheckoutDir(candidate)) {
     const theirs = readMarkerVaultId(candidate);
     if (!vaultId || !theirs || theirs === vaultId) vaultRootAbs = candidate;
   }
   return { vaultId, vaultPath, vaultRootAbs };
 }
 
+/**
+ * Extract `vault_id: <value>` from raw heyspex.yaml text, or `null` if absent.
+ * Same semantics as `spex-console/src/lib/cli/init.ts` `parseVaultId` (the
+ * writer's own reader): first line-anchored `vault_id:` key, value trimmed,
+ * one matching pair of surrounding quotes stripped, empty -> `null`. Kept to
+ * this one line-regex on purpose — `hs init` writes the marker as flat
+ * `key: value` lines, so a YAML parser buys nothing here.
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function parseMarkerVaultId(content) {
+  const m = String(content ?? '').match(/^vault_id:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const unquoted = m[1].trim().replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1');
+  return unquoted.length > 0 ? unquoted : null;
+}
+
+/**
+ * The `vault_id` written in `<dir>/heyspex.yaml`, or `null` (no marker, no
+ * key, unreadable). Never throws.
+ *
+ * @param {string} dir
+ * @returns {string|null}
+ */
+function readMarkerVaultId(dir) {
+  try {
+    return parseMarkerVaultId(readFileSync(join(dir, 'heyspex.yaml'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The marker id and the registry row for the same root disagree. The marker
  * wins (it is the repo's own on-disk declaration, written by `hs init` /
@@ -543,15 +565,19 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
   let dir = startDir;
   const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
   for (let i = 0; i < 256; i += 1) {
-    // Precedence (see inspectSatellitePin): committed satellite marker, then
-    // any valid manifest pin, then the generic vault-root test.
+    // A committed satellite marker (heyspex.yaml `vault_path`) outranks any
+    // manifest pin at the same level (same precedence as main's HS-FWB6).
+    // Uncloned here -> the satellite dir is reported (cloud tools still work by
+    // the marker id) and flagged `vaultCloned: false` so disk writers refuse.
     const marked = readMarkerSatellite(dir);
-    if (marked) {
-      return { repoRootAbs: marked.vaultRootAbs ?? dir, satellite: true, markerSatellite: marked };
-    }
+    if (marked) return { repoRootAbs: marked.vaultRootAbs ?? dir, satellite: true, markerSatellite: marked, satelliteDir: dir };
     const pinned = readSatellitePin(dir);
     if (pinned) return { repoRootAbs: pinned, satellite: true };
+    // A vault checkout at this level beats a binding at this level (a file
+    // that is a vault marker is never parsed as a binding anyway).
     if (isVaultRoot(dir)) return { repoRootAbs: dir, satellite: false };
+    const binding = readRepoBinding(dir);
+    if (binding) return { repoRootAbs: dir, satellite: false, binding };
     if (boundary && dir === boundary) break;
     const parent = dirname(dir);
     if (parent === dir) break;
@@ -561,27 +587,32 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
 }
 
 /**
- * When the cwd-contained vault (tier 2) wins, tell the operator if that
- * silently overrode the registry's active vault — the customer-visible
- * failure this task fixes (packaged server writing bookkeeping into the
- * WRONG repo with no warning). Prints nothing when there is no registry
- * pointer, the pointer is stale/unresolvable, or the two vaults are the same
- * repo (the owner's own sessions: cwd = the platform repo = the registry's
- * active vault too — must stay silent and unaffected).
- *
- * @param {string} cwdVaultRoot
- * @param {{ vaults: Array<{id:string, repo_root_abs:string}>, active_vault_id: string|null }|null} registry
+ * Canonical start folder for the walk: absolute, with symlinks / Windows
+ * junctions resolved (so a link into a bound repo resolves like the repo).
+ * A missing folder keeps its lexical form.
+ * @param {string} p
  */
-function maybeLogCwdOverrideNotice(cwdVaultRoot, registry) {
-  if (!registry || !isNonEmptyString(registry.active_vault_id)) return;
-  const activeRecord = findVaultById(registry, registry.active_vault_id);
-  if (!activeRecord) return;
-  const registryRoot = resolve(activeRecord.repo_root_abs);
-  const resolvedCwdRoot = resolve(cwdVaultRoot);
-  if (registryRoot === resolvedCwdRoot) return; // same vault — no notice
-  process.stderr.write(
-    `[heyspex-mcp] vault resolution: started inside ${resolvedCwdRoot} — overriding the registry's active vault ${registryRoot}, using the cwd vault.\n`,
-  );
+function canonicalDir(p) {
+  const abs = resolve(p);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+}
+
+/**
+ * The main checkout of a LINKED git worktree containing `dir` (its `.git` is a
+ * file whose gitdir has a `commondir`), or null. Worktrees outside the main
+ * repo's tree resolve like their repo when their own walk finds nothing.
+ * @param {string} dir
+ */
+function mainCheckoutOfWorktree(dir) {
+  const co = findGitCheckout(dir);
+  if (!co || resolve(co.commonDir) === resolve(co.gitDir)) return null;
+  if (basename(co.commonDir).toLowerCase() !== '.git') return null; // bare repo: no main checkout
+  const main = dirname(co.commonDir);
+  return resolve(main) === resolve(co.root) ? null : main;
 }
 
 /**
@@ -593,16 +624,10 @@ function maybeLogCwdOverrideNotice(cwdVaultRoot, registry) {
  * `source` names WHICH tier answered, and callers gate on it — `bin/hs.mjs`'s
  * `findRegistryVaultRoot`, `dev-factory/judge.mjs`'s `resolveVaultRoot`,
  * `dev-factory/lib/vault-root.mjs` and `dev-factory/lib/worker-lifecycle.mjs`
- * all accept anything that is not the last-resort `'cwd-heuristic'`. So the
- * label has to be true: a satellite attachment found by the walk (tier 2) is
- * `'satellite-pin'`, NOT `'env-vault-root'` (which it reported until
- * 2026-09-18, even with no env var set anywhere). Both are accepted by every
- * gate above, so the rename is behavior-preserving.
- *
- * `'cwd-marker'` and `'marker-registry-mismatch'` (a heyspex.yaml `vault_id`
- * named the vault) are likewise real answers, accepted by the same gates.
+ * all accept anything that is not `'unbound'` or the last-resort
+ * `'cwd-heuristic'`.
  *
- * @param {'explicit'|'account-pointer'|'env-vault-root'|'env-vault-dir'|'satellite-pin'|'cwd-marker'|'marker-registry-mismatch'|'cwd-heuristic'} source
+ * @param {'explicit'|'env-vault-root'|'env-vault-dir'|'satellite-pin'|'repo-binding'|'cwd-marker'|'marker-registry-mismatch'|'cwd-heuristic'|'unbound'} source
  */
 function finalize(vaultId, repoRootAbs, source) {
   const resolvedRoot = resolve(repoRootAbs);
@@ -614,151 +639,234 @@ function finalize(vaultId, repoRootAbs, source) {
   };
 }
 
+/** Is `dir` an existing directory that is a vault checkout (see {@link isVaultRoot})? */
+function isVaultCheckoutDir(dir) {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return isVaultRoot(dir);
+}
+
 /**
- * Resolve the active vault synchronously via the 5-tier precedence stack.
+ * Resolve the vault for this process. Order (owner ruling 2026-10-14,
+ * [[HS-TYJA]]; full contract in vault-binding.mjs): explicit id -> env
+ * override -> walk up from the launch folder -> unbound. Never throws: a
+ * failure returns source `'unbound'` with a typed `error`
+ * (VAULT_UNBOUND / VAULT_BINDING_BROKEN / VAULT_NOT_FOUND).
  *
- * @param {{ vaultId?: string, cwd?: string, registryDir?: string, cwdWalkRoot?: string }} [options]
- *   - `vaultId`: explicit override (tier 1).
- *   - `cwd`: working dir for the cwd-contained-vault walk-up (tier 2; defaults
- *     to `CLAUDE_PROJECT_DIR` then `process.cwd()`).
+ * @param {{ vaultId?: string, cwd?: string, registryDir?: string, cwdWalkRoot?: string, env?: Record<string, string|undefined> }} [options]
+ *   - `env`: environment to read HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR /
+ *     CLAUDE_PROJECT_DIR from (default `process.env`; tests inject).
+ *   - `vaultId`: explicit override (tier 1). Must name a registry row whose
+ *     folder exists, else VAULT_NOT_FOUND (an explicit ask never cascades to a
+ *     different vault).
+ *   - `cwd`: where the walk starts (defaults to `CLAUDE_PROJECT_DIR` then
+ *     `process.cwd()`).
  *   - `registryDir`: registry dir override (tests only; defaults to ~/.heyspex).
- *   - `cwdWalkRoot`: test-only fence for the tier-2 walk-up (see
- *     {@link findCwdVaultOrAttachment}); production code never sets this.
- * @returns {{ vaultId: string, repoRootAbs: string, specsDirAbs: string, source: string }}
+ *   - `cwdWalkRoot`: test-only fence for the walk; production never sets it.
+ * @returns {{ vaultId: string, repoRootAbs: string, specsDirAbs: string, source: string, error?: VaultResolutionError, boundRepoAbs?: string, worktreeOf?: string }}
  */
 export function resolveActiveVault(options = {}) {
   const registry = loadRegistry(options);
+  // An env value that is still an unexpanded ${...} placeholder, a relative path or (for the
+  // project-dir vars) a missing folder is UNSET, never a path (HS-C0NW: Copilot does not expand
+  // ${CLAUDE_PROJECT_DIR}). A registered vault root with no local checkout stays valid, so
+  // HEYSPEX_VAULT_ROOT skips the exists check.
+  const env = withoutUnusableDirEnv(options.env ?? process.env, { requireExisting: { HEYSPEX_VAULT_ROOT: false } });
+  const cwdBase = canonicalDir(
+    isNonEmptyString(options.cwd)
+      ? options.cwd
+      : (isNonEmptyString(env.CLAUDE_PROJECT_DIR)
+        ? env.CLAUDE_PROJECT_DIR
+        : process.cwd()),
+  );
 
-  // Tier 1 — explicit vaultId (CLI --vault / caller override). Unchanged:
-  // an explicit ask always wins over everything else.
+  // Tier 1 — explicit vaultId (CLI --vault / caller override). An explicit ask
+  // always wins, and an explicit ask for a vault this machine cannot find is
+  // an ERROR, never a silent fall-through to some other vault.
   if (isNonEmptyString(options.vaultId)) {
+    // A registered id resolves, even when this machine has no checkout of it
+    // (cloud reliance: reads/writes go to the console by vault id; the
+    // disk-tier dispatch gate refuses an absent root). An id this machine has
+    // no registry row for is VAULT_NOT_FOUND.
     const record = findVaultById(registry, options.vaultId);
     if (record) return finalize(record.id, record.repo_root_abs, 'explicit');
-    // Unknown explicit id: cascade rather than fail closed (matches TS resolver).
+    return unresolved(cwdBase, new VaultResolutionError(
+      VAULT_NOT_FOUND,
+      `--vault ${options.vaultId}: no registered vault has that id on this machine. List them with \`hs vault list\`; register a checkout with \`hs vault register <path>\`.`,
+      { fix: 'hs vault list', from: cwdBase, details: { vaultId: options.vaultId } },
+    ));
   }
 
-  // Tier 2 — cwd-contained vault (HS-C87T). Backward-compat note: the OLD
-  // getConfig() fell back to CLAUDE_PROJECT_DIR then process.cwd() as a bare
-  // repo root. We keep honoring CLAUDE_PROJECT_DIR as the cwd base (an
-  // explicit `options.cwd` caller/test override still takes precedence over
-  // it), but now WALK UP from that base looking for a heyspex.yaml marker or
-  // a specs/ dir at any ancestor level — not just the base and its immediate
-  // parent — so the vault the process was actually started inside/under wins
-  // over a stale registry pointer from a different terminal/console tab.
-  const cwdBase = resolve(
-    isNonEmptyString(options.cwd)
-      ? options.cwd
-      : (isNonEmptyString(process.env.CLAUDE_PROJECT_DIR)
-        ? process.env.CLAUDE_PROJECT_DIR
-        : process.cwd()),
-  );
-  //
-  // A SATELLITE repo ([[satellite.ts]]) has no marker of its own — it records
-  // an explicit attachment in its MCP manifests instead — so the walk checks
-  // BOTH signals at each level and takes the nearest: an explicit attachment
-  // in this repo beats a vault that merely happens to sit further up the
-  // tree (e.g. two sibling checkouts under one parent that has a stray
-  // `specs/`), and both still beat the machine-global pointer at tier 4.
-  const cwdMatch = findCwdVaultOrAttachment(cwdBase, options.cwdWalkRoot);
+  // Tier 2 — HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR env: a TRUE override, above
+  // the walk (owner ruling 2026-10-14, [[HS-TYJA]]). It must name a vault
+  // checkout: a stale pin at a CODE repo (the old plugin manifest's
+  // HEYSPEX_VAULT_ROOT=${CLAUDE_PROJECT_DIR}) is refused with VAULT_NOT_FOUND
+  // instead of silently becoming "the vault".
+  const envRoot = env.HEYSPEX_VAULT_ROOT;
+  if (isNonEmptyString(envRoot)) {
+    const root = resolve(envRoot.trim());
+    // Reverse-resolve the pinned root to its registered id when the registry
+    // knows that repo ([[HS-XOZ3-DIAG-NWG6-vault-identity-split-reconciled-to]]).
+    const envRecord = findVaultByRoot(registry, root);
+    // Accepted: a vault checkout on disk, or a root the registry registers as
+    // a vault (with or without a local checkout - cloud reliance). Refused:
+    // anything else, e.g. an unregistered code repo (the old plugin pin
+    // HEYSPEX_VAULT_ROOT=${CLAUDE_PROJECT_DIR}) or a missing unknown path.
+    if (!isVaultCheckoutDir(root) && !envRecord) {
+      return unresolved(cwdBase, envNotVaultError('HEYSPEX_VAULT_ROOT', envRoot, root, cwdBase));
+    }
+    const envMarkerId = envRecord ? null : readMarkerVaultId(root);
+    return finalize(envRecord?.id ?? envMarkerId ?? UNREGISTERED_VAULT_ID, root, 'env-vault-root');
+  }
+  const envDir = env.HEYSPEX_VAULT_DIR;
+  if (isNonEmptyString(envDir)) {
+    // Historically points AT the specs/ dir itself, so repo root = its parent
+    // (specsDirAbs then round-trips back).
+    const specsDirFromEnv = resolve(envDir.trim());
+    const root = dirname(specsDirFromEnv);
+    const envDirRecord = findVaultByRoot(registry, root);
+    let ok = false;
+    try {
+      ok = statSync(specsDirFromEnv).isDirectory() && basename(specsDirFromEnv).toLowerCase() === 'specs';
+    } catch {
+      ok = false;
+    }
+    // A registered vault root names a vault even without a local specs/.
+    if (!ok && envDirRecord) ok = true;
+    if (!ok) return unresolved(cwdBase, envNotVaultError('HEYSPEX_VAULT_DIR', envDir, specsDirFromEnv, cwdBase));
+    return finalize(envDirRecord?.id ?? readMarkerVaultId(root) ?? UNREGISTERED_VAULT_ID, root, 'env-vault-dir');
+  }
+
+  // Tier 3 — the folder the process was launched in. Walk UP from the cwd base
+  // to the filesystem root; at each level the nearest of: a satellite pin, a
+  // vault checkout, a heyspex.yaml repo binding. A linked git worktree whose
+  // own walk finds nothing resolves like its main checkout.
+  let cwdMatch = findCwdVaultOrAttachment(cwdBase, options.cwdWalkRoot);
+  let worktreeOf = null;
+  if (!cwdMatch && !isNonEmptyString(options.cwdWalkRoot)) {
+    const main = mainCheckoutOfWorktree(cwdBase);
+    if (main) {
+      cwdMatch = findCwdVaultOrAttachment(canonicalDir(main));
+      if (cwdMatch) worktreeOf = resolve(main);
+    }
+  }
+  const tag = (r) => (worktreeOf ? { ...r, worktreeOf } : r);
+  if (cwdMatch?.binding) {
+    // A bound CODE repo ([[HS-3PEQ]] `heyspex.yaml` `vault:`). The binding's id
+    // is the vault; this machine's registry row for that id says where its
+    // checkout is.
+    try {
+      const located = locateBoundVault(cwdMatch.binding, { vaults: registryVaults(registry?.raw) }, {
+        bindingDir: cwdMatch.repoRootAbs,
+        from: cwdBase,
+      });
+      if (located.notice) noticeOnce(`[heyspex] vault resolution: ${located.notice}\n`);
+      return tag({
+        ...finalize(located.vaultId, located.repoRootAbs, 'repo-binding'),
+        boundRepoAbs: resolve(cwdMatch.repoRootAbs),
+      });
+    } catch (err) {
+      return unresolved(cwdBase, err);
+    }
+  }
   if (cwdMatch) {
-    // The override notice is for an ACCIDENT of where the process started —
-    // "you are inside vault X, the registry says Y". A satellite attachment
-    // is not an accident: the repo names its vault on disk, deliberately, and
-    // that pin is meant to outrank the machine-global pointer. Warning on it
-    // would fire on every single satellite session. Stays suppressed.
-    if (!cwdMatch.satellite) maybeLogCwdOverrideNotice(cwdMatch.repoRootAbs, registry);
     if (cwdMatch.satellite) {
-      // `'satellite-pin'`, not `'env-vault-root'`: nothing set an env var —
-      // the walk read an on-disk manifest pin. See finalize()'s doc comment
-      // for the gate sites that consume this (all of them reject only
-      // `'cwd-heuristic'`, so both labels are accepted identically).
+      // `'satellite-pin'`: the walk read an on-disk manifest pin (no env var).
       const pinnedRecord = findVaultByRoot(registry, cwdMatch.repoRootAbs);
-      // A committed satellite marker names the vault by id: that id IS the
-      // binding (works on a fresh machine with no registry row and no clone).
-      const markerId = cwdMatch.markerSatellite?.vaultId ?? null;
-      const bound = finalize(
-        markerId ?? pinnedRecord?.id ?? UNREGISTERED_VAULT_ID,
+      const marked = cwdMatch.markerSatellite;
+      if (marked) {
+        // A committed satellite marker names the vault by id: that id IS the
+        // binding. `boundRepoAbs` is the satellite (a code repo, never a
+        // vault); `vaultCloned: false` means `repoRootAbs` is that satellite,
+        // NOT a vault checkout - disk writers (`hs pull --apply`, the mirror
+        // catch-up hook) must refuse it.
+        const bound = {
+          ...finalize(marked.vaultId ?? pinnedRecord?.id ?? UNREGISTERED_VAULT_ID, cwdMatch.repoRootAbs, 'satellite-pin'),
+          boundRepoAbs: resolve(cwdMatch.satelliteDir),
+          vaultPath: marked.vaultPath,
+        };
+        return tag(marked.vaultRootAbs ? bound : { ...bound, vaultCloned: false });
+      }
+      return tag(finalize(
+        pinnedRecord?.id ?? UNREGISTERED_VAULT_ID,
         cwdMatch.repoRootAbs,
         'satellite-pin',
-      );
-      // The marker names a vault that is NOT cloned on this machine: the
-      // binding is cloud-only. Disk readers must not report an empty vault -
-      // they answer from the cloud and say so (read-path.mjs).
-      if (cwdMatch.markerSatellite && !cwdMatch.markerSatellite.vaultRootAbs) {
-        return { ...bound, vaultCloned: false, vaultPath: cwdMatch.markerSatellite.vaultPath };
-      }
-      return bound;
+      ));
     }
-    // A heyspex.yaml `vault_id` IS the vault's id ([[HS-VVNQ]]): `hs init` /
-    // `hs connect` wrote it there. Before this, the id came ONLY from a
-    // registry row keyed by this root, so a connected repo on a machine
-    // whose registry lacked (or mis-keyed) that row resolved to the
-    // `unregistered` sentinel and every console call was refused. The
-    // registry row is still consulted — as the thing the marker is checked
-    // against, not as the source.
+    // A heyspex.yaml `vault_id` IS the vault's id ([[HS-VVNQ]]); the registry
+    // row is the thing the marker is checked against, not the source.
     const markerRecord = findVaultByRoot(registry, cwdMatch.repoRootAbs);
     const markerVaultId = readMarkerVaultId(cwdMatch.repoRootAbs);
     if (markerVaultId) {
       if (markerRecord && markerRecord.id !== markerVaultId) {
         logMarkerRegistryMismatch(cwdMatch.repoRootAbs, markerVaultId, markerRecord.id);
-        return finalize(markerVaultId, cwdMatch.repoRootAbs, 'marker-registry-mismatch');
+        return tag(finalize(markerVaultId, cwdMatch.repoRootAbs, 'marker-registry-mismatch'));
       }
-      return finalize(markerVaultId, cwdMatch.repoRootAbs, 'cwd-marker');
+      return tag(finalize(markerVaultId, cwdMatch.repoRootAbs, 'cwd-marker'));
     }
-    // No `vault_id` on the marker (or a bare specs/ dir): same reverse lookup
-    // as the satellite and env tiers — a vault the registry knows reports its
-    // REGISTERED id, so the console-scoping header (console-fetch.mjs
-    // `getVaultIdHeader`) can name it ([[HS-M95C]]).
-    return finalize(markerRecord?.id ?? UNREGISTERED_VAULT_ID, cwdMatch.repoRootAbs, 'cwd-heuristic');
+    // No `vault_id` on the marker (or a bare specs/ dir): the registry row id
+    // for this root, else the `unregistered` sentinel.
+    return tag(finalize(markerRecord?.id ?? UNREGISTERED_VAULT_ID, cwdMatch.repoRootAbs, 'cwd-heuristic'));
   }
 
-  // Tier 3 — HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR env (legacy escape hatch).
-  // [[HS-VVNQ]]: BELOW the walk. The plugin manifest sets
-  // HEYSPEX_VAULT_ROOT=${CLAUDE_PROJECT_DIR} on every session, so an env tier
-  // above the walk outranked every satellite pin and heyspex.yaml marker on
-  // disk. It still outranks the machine-global registry pointer.
-  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
-  if (isNonEmptyString(envRoot)) {
-    // Reverse-resolve the pinned root to its registered id when the registry
-    // knows that repo ([[HS-XOZ3-DIAG-NWG6-vault-identity-split-reconciled-to]]).
-    const envRecord = findVaultByRoot(registry, envRoot);
-    return finalize(envRecord?.id ?? UNREGISTERED_VAULT_ID, resolve(envRoot), 'env-vault-root');
-  }
-  const envDir = process.env.HEYSPEX_VAULT_DIR;
-  if (isNonEmptyString(envDir)) {
-    // Historically points AT the specs/ dir itself, so repo root = its parent
-    // (specsDirAbs then round-trips back).
-    // Same reverse lookup as HEYSPEX_VAULT_ROOT, matching the TS resolver.
-    const specsDirFromEnv = resolve(envDir);
-    const envDirRecord = findVaultByRoot(registry, dirname(specsDirFromEnv));
-    return finalize(
-      envDirRecord?.id ?? UNREGISTERED_VAULT_ID,
-      dirname(specsDirFromEnv),
-      'env-vault-dir',
-    );
-  }
+  // Tier 4 — nothing names a vault: UNBOUND. The registry's active pointer is
+  // retired (owner ruling 2026-10-14: "there shouldn't be one active vault");
+  // it is never read here. Non-throwing API: callers gate on `source` (see
+  // {@link isResolvedVault}); `error` carries the typed VAULT_UNBOUND.
+  return unresolved(cwdBase, unboundError(cwdBase, registryVaults(registry?.raw)));
+}
 
-  // Tier 4 — registry active_vault_id (the OFFLINE active pointer). Reached
-  // only when cwd sits inside no vault at all (the walk found neither marker
-  // anywhere up the tree) and no env var names one. This is how an MCP
-  // restart picks up a CLI `hs vault use` switch without Neon. Mirrors the TS
-  // resolver's account-pointer tier, sourced from the registry file here.
-  // The ORDER is pinned (decision memory `vault-resolver-precedence`); what a
-  // consumer does with `source: 'account-pointer'` is its own call — the
-  // console transport (console-fetch.mjs `vaultIdHeaderFor`) REFUSES
-  // vault-scoped requests on it (`VAULT_NOT_PINNED`) unless
-  // HEYSPEX_ALLOW_POINTER_VAULT=1, because the pointer mirrors whatever the
-  // owner last clicked in the console, not anything this repo declared.
-  if (registry && isNonEmptyString(registry.active_vault_id)) {
-    const record = findVaultById(registry, registry.active_vault_id);
-    if (record) return finalize(record.id, record.repo_root_abs, 'account-pointer');
-    // Stale/corrupt pointer (no matching row): cascade rather than throw.
+/** VAULT_NOT_FOUND for an env override that names no vault checkout. */
+function envNotVaultError(name, raw, abs, cwdBase) {
+  const shown = abs.replace(/\\/g, '/');
+  return new VaultResolutionError(
+    VAULT_NOT_FOUND,
+    `${name}=${raw} does not name a vault checkout (${shown} ${name === 'HEYSPEX_VAULT_DIR' ? 'is not an existing specs/ folder' : 'has no specs/ folder and no vault heyspex.yaml'}). ` +
+      `Unset ${name} so the vault bound to this repo is used (\`hs vault resolve\` shows it), or point it at a vault checkout.`,
+    { fix: `unset ${name}`, from: cwdBase, details: { env: name, value: raw, path: shown } },
+  );
+}
+
+/** The non-throwing failure shape: sentinel id, source 'unbound', typed `error`. */
+function unresolved(cwdBase, error) {
+  return { ...finalize(UNREGISTERED_VAULT_ID, cwdBase, 'unbound'), error };
+}
+
+const _noticed = new Set();
+function noticeOnce(line) {
+  if (_noticed.has(line)) return;
+  _noticed.add(line);
+  try {
+    process.stderr.write(line);
+  } catch {
+    /* a stderr failure never becomes a resolution failure */
   }
+}
+
+/**
+ * Did resolution name a vault? False only for `'unbound'` (nothing named one,
+ * or a repo binding points at a vault this machine cannot find). A
+ * `'cwd-heuristic'` result is a real checkout (a bare specs/ dir); callers that
+ * also refuse unregistered roots check `vaultId` themselves.
+ * @param {{ source?: string } | null | undefined} resolved
+ */
+export function isResolvedVault(resolved) {
+  return Boolean(resolved) && resolved.source !== 'unbound';
+}
 
-  // Tier 5 — last-resort cwd fallback: no marker found anywhere up the tree,
-  // no registry pointer either. Preserves the pre-existing default value old
-  // getConfig() would have produced.
-  return finalize(UNREGISTERED_VAULT_ID, cwdBase, 'cwd-heuristic');
+/**
+ * Strict form of {@link resolveActiveVault}: returns the same shape, or THROWS
+ * the typed {@link VaultResolutionError} (VAULT_UNBOUND / VAULT_BINDING_BROKEN)
+ * when nothing names a vault. Use from commands that must stop (spexcode, `hs`).
+ * @param {Parameters<typeof resolveActiveVault>[0]} [options]
+ */
+export function resolveVaultOrThrow(options = {}) {
+  const resolved = resolveActiveVault(options);
+  if (resolved.source === 'unbound') throw resolved.error;
+  return resolved;
 }
 
 let _cached = null;