heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/vault-less-endpoints.mjs

@@ -0,0 +1,52 @@
+// vault-less-endpoints.mjs — the ONE list of console endpoints that have no
+// vault yet ([[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]],
+// epic [[HS-BIWR-WW9R-EPIC-explicit-vault-scope-on-every-console]] invariant 2).
+//
+// Every other console request from the MCP server (console-fetch.mjs) and from
+// the `hs` HTTP client (spex-console/src/lib/cli/control-shared.ts) MUST name
+// `{ account, vault }` in its headers or refuse LOCALLY — a call that sends no
+// vault is served from the account's leftover pointer, which is the 2026-10-02
+// incident ([[HS-M95C-QQAV-DIAG-in-prod-mode-every-mcp-call-from-a]]). The
+// endpoints below are the explicit exceptions: pairing, sign-in identity,
+// creating/listing the vaults and workspaces themselves, and the dev-mode
+// switch. They are matched by METHOD + exact pathname (query string ignored),
+// never by prefix — `/api/vaults/active` is vault-scoped and stays gated.
+//
+// Plain Node ESM, zero dependencies, so the TS CLI imports it bare (same as
+// `credentials.mjs`) and the two runtimes can never drift apart on the list.
+
+/**
+ * `"<METHOD> <pathname>"` rows; `*` matches any method.
+ * @type {readonly string[]}
+ */
+export const VAULT_LESS_ENDPOINTS = Object.freeze([
+  '* /api/mcp/session',
+  '* /api/mcp/pairing-codes',
+  'POST /api/vaults',
+  'GET /api/vaults',
+  'POST /api/workspaces',
+  'GET /api/workspaces',
+  '* /api/admin/dev-mode',
+]);
+
+/** Pathname of a request path — the part before `?`, trailing slash dropped. */
+export function pathnameOf(path) {
+  const raw = String(path ?? '').split('?')[0].split('#')[0];
+  const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, '') : raw;
+  return noTrailing || '/';
+}
+
+/**
+ * True when `method` + `path` name an endpoint that legitimately has no vault
+ * yet, so the vault header is omitted and no local refusal fires.
+ * @param {string | null | undefined} method HTTP method (any case; missing → GET)
+ * @param {string} path request path, with or without a query string
+ */
+export function isVaultLessEndpoint(method, path) {
+  const m = String(method || 'GET').toUpperCase();
+  const pathname = pathnameOf(path);
+  return VAULT_LESS_ENDPOINTS.some((row) => {
+    const [rowMethod, rowPath] = row.split(' ');
+    return rowPath === pathname && (rowMethod === '*' || rowMethod === m);
+  });
+}

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

@@ -19,28 +19,43 @@
  * offline pointer is how an MCP restart picks up a CLI `hs vault use` switch
  * without Neon.
  *
- * Precedence stack (highest wins) — REORDERED by [[HS-C87T-0JNK-TASK]]: a
- * packaged server started with cwd inside an empty target vault used to
- * resolve to whatever vault another terminal/console last marked active on
- * the machine (old tier order put the registry pointer above cwd), silently
- * writing its bookkeeping into the WRONG repo. Now the folder the process was
- * actually started in/under wins over the registry's stale-by-comparison
- * 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. HEYSPEX_VAULT_ROOT env      -> repo root (legacy escape hatch)
- *   2. HEYSPEX_VAULT_DIR env       -> the specs/ dir itself (repo root = parent)
- *   3. cwd-contained vault         -> walk UP from cwd through every ancestor
- *                                     looking for a heyspex.yaml marker or a
- *                                     specs/ dir; the nearest match wins. Logs
- *                                     one stderr notice iff this differs from
- *                                     the registry's active vault (tier 4) —
- *                                     silent when they agree (the common case:
- *                                     the owner's own sessions start inside the
- *                                     platform repo, which is also the
- *                                     registry's active vault).
- *   4. registry active_vault_id    -> the offline active pointer (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 at all (tier 3 found nothing)
+ *                                     vault and no env var names one
  *   5. cwd fallback                -> cwd itself (no marker found anywhere;
  *                                     preserves the pre-existing default)
  *
@@ -51,7 +66,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 
 /**
@@ -90,6 +105,8 @@ 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.
  *
  * @param {{ registryDir?: string }} [opts]
  * @returns {{ vaults: Array<{ id: string, repo_root_abs: string }>, active_vault_id: string|null }|null}
@@ -113,8 +130,49 @@ function loadRegistry(opts = {}) {
     if (!isNonEmptyString(raw.repo_root_abs)) continue;
     vaults.push({ id: raw.id, repo_root_abs: raw.repo_root_abs });
   }
-  const active_vault_id = isNonEmptyString(json.active_vault_id) ? json.active_vault_id : null;
-  return { vaults, active_vault_id };
+  return { vaults, active_vault_id: registryPointerVaultId(json) };
+}
+
+/** Mirrors registry-file.ts `LEGACY_REGISTRY_ACCOUNT_ID`. */
+const LEGACY_REGISTRY_ACCOUNT_ID = 'legacy';
+
+/**
+ * The offline active-vault pointer of a parsed registry file, schema v1 or v2
+ * ([[HS-RXLG-WW9R-TASK-key-registry-json-per-account-schema-v2]]). Mirrors
+ * registry-file.ts `currentAccountPointers`:
+ *   - v2: `accounts[current_account_id].active_vault_id`. An ABSENT field
+ *     reads the pre-account `legacy` row a not-yet-migrated machine left
+ *     behind; an explicit `null` is a clear (reads null) when the account
+ *     owns a row here, else it too reads `legacy`. No current account → the
+ *     `legacy` value or null — never some other account's.
+ *   - v1: the machine-global `active_vault_id`.
+ *
+ * @param {Record<string, unknown>} json
+ * @returns {string|null}
+ */
+export function registryPointerVaultId(json) {
+  if (!json || typeof json !== 'object') return null;
+  if (json.schema_version !== 2) {
+    return isNonEmptyString(json.active_vault_id) ? json.active_vault_id : null;
+  }
+  const accounts =
+    json.accounts && typeof json.accounts === 'object' && !Array.isArray(json.accounts)
+      ? json.accounts
+      : {};
+  const current = isNonEmptyString(json.current_account_id) ? json.current_account_id : null;
+  const rowOf = (id) => (id && accounts[id] && typeof accounts[id] === 'object' ? accounts[id] : null);
+  const own = rowOf(current);
+  if (own && isNonEmptyString(own.active_vault_id)) return own.active_vault_id;
+  // An explicit null is a CLEAR — but only from an account that owns a row
+  // here; a stray row of an account that owns nothing still reads legacy.
+  const ownsRows = [json.vaults, json.workspaces].some(
+    (rows) => Array.isArray(rows) && rows.some((r) => r && r.account_id === current),
+  );
+  if (own && own.active_vault_id === null && ownsRows && current !== LEGACY_REGISTRY_ACCOUNT_ID) {
+    return null;
+  }
+  const legacy = rowOf(LEGACY_REGISTRY_ACCOUNT_ID);
+  return legacy && isNonEmptyString(legacy.active_vault_id) ? legacy.active_vault_id : null;
 }
 
 /** Find a vault row by id. Returns null when absent. */
@@ -124,40 +182,214 @@ function findVaultById(registry, vaultId) {
 }
 
 /**
- * Walk UP from `startDir` through every ancestor directory looking for a
- * `heyspex.yaml` marker file or a `specs/` dir — the two on-disk signals that
- * a folder IS a vault root (mirrors `hs init`'s marker + the entity-model's
- * folder layout). Returns the nearest matching ancestor (closest to
- * `startDir` wins), or `null` if the walk reaches the filesystem root (or
- * `stopAt`, inclusive) with no match. Bounded to guard against any path
- * pathology; real filesystems never nest this deep.
+ * Normalize a path for comparison: forward slashes, no trailing separator,
+ * lower-cased (this CLI's primary platform is Windows, where `C:\Dev` and
+ * `c:\dev` name one directory). Mirrors `satellite.ts`'s
+ * `normalizePathForCompare`.
+ */
+function normalizeRoot(p) {
+  return resolve(p)
+    .replace(/[\\/]+/g, '/')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+/**
+ * REVERSE-resolve a filesystem repo root to its registered vault row — the
+ * `.mjs` twin of the TS resolver's `registryLookupByRoot`. Without it a
+ * path-first tier reports the `unregistered` sentinel even when the registry
+ * knows that exact repo, which misfiles the whole index under `unregistered`
+ * ([[HS-XOZ3-DIAG-NWG6-vault-identity-split-reconciled-to]]).
+ *
+ * @param {{ vaults: Array<{id: string, repo_root_abs: string}> }|null} registry
+ * @param {string} repoRootAbs
+ */
+function findVaultByRoot(registry, repoRootAbs) {
+  if (!registry || !isNonEmptyString(repoRootAbs)) return null;
+  const target = normalizeRoot(repoRootAbs);
+  return registry.vaults.find((v) => normalizeRoot(v.repo_root_abs) === target) ?? null;
+}
+
+/**
+ * The MCP manifests a SATELLITE repo records its vault attachment in, and the
+ * env key inside them. Mirrors `spex-console/src/lib/cli/satellite.ts`
+ * (`SATELLITE_MANIFEST_RELS` / `SATELLITE_VAULT_ENV`) — keep the two in sync;
+ * the TS module carries the full rationale.
+ */
+const SATELLITE_MANIFESTS = [['.mcp.json'], ['.cursor', 'mcp.json']];
+
+/**
+ * Is `p` an ABSOLUTE path? Pure string test over the three shapes a real pin
+ * can carry: a Windows drive path (`C:\vault`, `C:/vault`), a UNC share
+ * (`\\server\share\vault`) and a POSIX root (`/vault`). Mirrors
+ * `satellite.ts`'s `isAbsolutePathForCompare` — keep the two in sync; the TS
+ * module carries the full rationale for why a non-absolute pin is refused
+ * rather than resolved.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isAbsolutePin(p) {
+  const s = p.trim();
+  return /^[\\/]/.test(s) || /^[a-zA-Z]:[\\/]/.test(s);
+}
+
+/**
+ * Read a satellite attachment out of `dir`'s MCP manifests: the heyspex
+ * server's `env.HEYSPEX_VAULT_ROOT` pin, when it names a path OUTSIDE `dir`.
+ * Two kinds of value are NOT an attachment:
+ *
+ *   - one still carrying an unexpanded `${...}` — the client's own
+ *     project-dir placeholder that a normal (this-repo-IS-the-vault) install
+ *     writes; and
+ *   - one that is not an ABSOLUTE path ({@link isAbsolutePin}). This used to
+ *     be `resolve(trimmed)`, which resolved a relative pin against
+ *     `process.cwd()` — NOT the manifest's own directory — so a manifest in
+ *     `<repo>` pinning `../some-vault` returned a directory beside whatever
+ *     folder the MCP server happened to be launched from. No resolution is
+ *     defensible here: the same string also reaches the server as the
+ *     `HEYSPEX_VAULT_ROOT` env var, where tier 2 resolves it against the
+ *     server process's cwd, so a manifest-dir rule would contradict the
+ *     runtime. Refusing fails safe and matches `satellite.ts`.
+ *
+ * Pure + synchronous and never throws — an unreadable/unparseable manifest
+ * reads as "no attachment", the same fail-open posture as the registry
+ * loader above.
+ *
+ * @param {string} dir
+ * @returns {string|null} the attached vault's absolute repo root
+ */
+export function readSatellitePin(dir) {
+  for (const rel of SATELLITE_MANIFESTS) {
+    let raw;
+    try {
+      raw = readFileSync(join(dir, ...rel), 'utf8');
+    } catch {
+      continue;
+    }
+    let value;
+    try {
+      value = JSON.parse(raw)?.mcpServers?.heyspex?.env?.HEYSPEX_VAULT_ROOT;
+    } catch {
+      continue;
+    }
+    if (!isNonEmptyString(value)) continue;
+    const trimmed = value.trim();
+    if (trimmed.includes('${')) continue;
+    if (!isAbsolutePin(trimmed)) continue;
+    const pinned = normalizeRoot(trimmed);
+    const here = normalizeRoot(dir);
+    if (pinned === here || pinned.startsWith(`${here}/`)) continue; // ordinary install
+    return resolve(trimmed);
+  }
+  return null;
+}
+
+/**
+ * Is `dir` a vault root? True when it contains a `heyspex.yaml` marker file
+ * OR a `specs/` dir — the two on-disk signals that a folder IS a vault root
+ * (mirrors `hs init`'s marker + the entity-model's folder layout). This is
+ * the ONE definition of "is this a vault root" — every walk/check in this
+ * file (and in `bin/hs.mjs`) routes through it rather than re-testing the
+ * two signals inline. Pure and synchronous: no config reads, no walking, no
+ * side effects — just the two existsSync checks.
+ *
+ * One exclusion ([[HS-VVNQ]]): the OS temp directory ITSELF is never a vault
+ * root. It is shared scratch for every process on the machine, test runs
+ * leave a stray `specs/` there, and once the walk outranks env and the
+ * pointer, every process started anywhere under it would otherwise resolve
+ * to that junk folder. Subdirectories of it (a real scratch vault) still
+ * count. The TS resolver applies the same rule.
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function isVaultRoot(dir) {
+  if (normalizeRoot(dir) === normalizeRoot(tmpdir())) 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;
+  }
+}
+
+/**
+ * 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` /
+ * `hs connect`); this notice names the command whose `id_agreement` row
+ * reports the same disagreement so the operator can repair the registry.
+ *
+ * @param {string} repoRootAbs
+ * @param {string} markerVaultId
+ * @param {string} registryVaultId
+ */
+function logMarkerRegistryMismatch(repoRootAbs, markerVaultId, registryVaultId) {
+  process.stderr.write(
+    `[heyspex-mcp] vault resolution: ${resolve(repoRootAbs)}/heyspex.yaml says vault_id ${markerVaultId} but the registry row for that root says ${registryVaultId} — using the marker id. Run \`hs connect --check\` to see and repair the disagreement.\n`,
+  );
+}
+
+/**
+ * Walk UP from `startDir` taking the NEAREST of the two tier-2 (walk) signals: a
+ * vault root (see {@link isVaultRoot}) or a satellite attachment (see
+ * {@link readSatellitePin}). The attachment is checked FIRST at each level,
+ * because a repo that explicitly names its vault is never also asking to be
+ * one.
  *
  * @param {string} startDir
  * @param {string|undefined} stopAt - test-only walk boundary (checked, then
  *   the walk stops — never climbs past it). Unset in production, so the walk
  *   always reaches the real filesystem root; tests use it to fence the walk
- *   inside a disposable tmp fixture so ambient/unrelated directories higher up
- *   the real tree (e.g. a stray `specs` folder under the OS temp dir) can't
- *   produce a false match.
- * @returns {string|null}
+ *   inside a disposable tmp fixture so ambient/unrelated directories higher
+ *   up the real tree cannot produce a false match.
+ * @returns {{ repoRootAbs: string, satellite: boolean }|null}
  */
-function findCwdVaultRoot(startDir, stopAt) {
+function findCwdVaultOrAttachment(startDir, stopAt) {
   let dir = startDir;
   const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
   for (let i = 0; i < 256; i += 1) {
-    if (existsSync(join(dir, 'heyspex.yaml')) || existsSync(join(dir, 'specs'))) {
-      return dir;
-    }
-    if (boundary && dir === boundary) break; // hit the test-only fence
+    const pinned = readSatellitePin(dir);
+    if (pinned) return { repoRootAbs: pinned, satellite: true };
+    if (isVaultRoot(dir)) return { repoRootAbs: dir, satellite: false };
+    if (boundary && dir === boundary) break;
     const parent = dirname(dir);
-    if (parent === dir) break; // reached filesystem root
+    if (parent === dir) break;
     dir = parent;
   }
   return null;
 }
 
 /**
- * When the cwd-contained vault (tier 3) wins, tell the operator if that
+ * 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
@@ -186,7 +418,19 @@ function maybeLogCwdOverrideNotice(cwdVaultRoot, registry) {
  *
  * @param {string} vaultId
  * @param {string} repoRootAbs
- * @param {'explicit'|'account-pointer'|'env-vault-root'|'env-vault-dir'|'cwd-heuristic'} source
+ * `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.
+ *
+ * @param {'explicit'|'account-pointer'|'env-vault-root'|'env-vault-dir'|'satellite-pin'|'cwd-marker'|'marker-registry-mismatch'|'cwd-heuristic'} source
  */
 function finalize(vaultId, repoRootAbs, source) {
   const resolvedRoot = resolve(repoRootAbs);
@@ -203,11 +447,11 @@ function finalize(vaultId, repoRootAbs, source) {
  *
  * @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 3; defaults
+ *   - `cwd`: working dir for the cwd-contained-vault walk-up (tier 2; defaults
  *     to `CLAUDE_PROJECT_DIR` then `process.cwd()`).
  *   - `registryDir`: registry dir override (tests only; defaults to ~/.heyspex).
- *   - `cwdWalkRoot`: test-only fence for the tier-3 walk-up (see
- *     {@link findCwdVaultRoot}); production code never sets this.
+ *   - `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 }}
  */
 export function resolveActiveVault(options = {}) {
@@ -221,23 +465,7 @@ export function resolveActiveVault(options = {}) {
     // Unknown explicit id: cascade rather than fail closed (matches TS resolver).
   }
 
-  // Tier 2 — HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR env (legacy escape hatch).
-  // [[HS-C87T-0JNK-TASK]]: moved ABOVE both the cwd-contained vault and the
-  // registry pointer — an explicit env override must win "regardless" of
-  // where the process was started or what the registry says is active.
-  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
-  if (isNonEmptyString(envRoot)) {
-    return finalize(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).
-    const specsDirFromEnv = resolve(envDir);
-    return finalize(UNREGISTERED_VAULT_ID, dirname(specsDirFromEnv), 'env-vault-dir');
-  }
-
-  // Tier 3 — cwd-contained vault (HS-C87T). Backward-compat note: the OLD
+  // 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
@@ -252,15 +480,85 @@ export function resolveActiveVault(options = {}) {
         ? process.env.CLAUDE_PROJECT_DIR
         : process.cwd()),
   );
-  const cwdVaultRoot = findCwdVaultRoot(cwdBase, options.cwdWalkRoot);
-  if (cwdVaultRoot) {
-    maybeLogCwdOverrideNotice(cwdVaultRoot, registry);
-    return finalize(UNREGISTERED_VAULT_ID, cwdVaultRoot, 'cwd-heuristic');
+  //
+  // 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);
+  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).
+      const pinnedRecord = findVaultByRoot(registry, cwdMatch.repoRootAbs);
+      return finalize(
+        pinnedRecord?.id ?? UNREGISTERED_VAULT_ID,
+        cwdMatch.repoRootAbs,
+        'satellite-pin',
+      );
+    }
+    // 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.
+    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 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');
+  }
+
+  // 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 — registry active_vault_id (the OFFLINE active pointer). Reached
-  // only when cwd sits inside no vault at all (tier 3 found neither marker
-  // anywhere up the tree) — e.g. an ad-hoc script dir. This is how an MCP
+  // 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.
   if (registry && isNonEmptyString(registry.active_vault_id)) {