heyspex 0.1.0 → 0.2.1

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)
  *
@@ -50,8 +65,9 @@
  * behavior, so nothing regresses when no registry exists.
  */
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 
 /**
@@ -70,7 +86,7 @@ export const UNREGISTERED_VAULT_ID = 'unregistered';
  * @returns {string}
  */
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join(homedir(), '.heyspex');
+  return opts.registryDir ?? join(heyspexHome(), '.heyspex');
 }
 
 /**
@@ -90,6 +106,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 +131,76 @@ 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;
+}
+
+/**
+ * The account the MACHINE-LOCAL registry row for `repoRootAbs` was registered
+ * under (`vaults[].account_id`), or null (no row, or the pre-account `legacy`
+ * bucket). The repo-to-account binding lives here - per machine, per user -
+ * and NEVER in the committed heyspex.yaml: a second developer with another
+ * account must not inherit the first one's account (owner ruling 2026-10-16).
+ *
+ * @param {string} repoRootAbs
+ * @param {{ registryDir?: string }} [opts]
+ * @returns {string|null}
+ */
+export function registryAccountIdForRoot(repoRootAbs, opts = {}) {
+  if (!isNonEmptyString(repoRootAbs)) return null;
+  const file = vaultRegistryFilePath(opts);
+  let json;
+  try {
+    json = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+  const target = normalizeRoot(repoRootAbs);
+  const rows = Array.isArray(json?.vaults) ? json.vaults : [];
+  const row = rows.find((v) => v && isNonEmptyString(v.repo_root_abs) && normalizeRoot(v.repo_root_abs) === target);
+  const id = row?.account_id;
+  return isNonEmptyString(id) && id !== LEGACY_REGISTRY_ACCOUNT_ID ? id.trim() : null;
 }
 
 /** Find a vault row by id. Returns null when absent. */
@@ -124,40 +210,358 @@ 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) {
+  const d = inspectSatellitePin(dir);
+  return d && d.kind === 'pin' ? d.root : null;
+}
+
+/**
+ * Expand the client placeholders a PORTABLE pin may carry against the
+ * manifest's own directory: ${CLAUDE_PROJECT_DIR[:-default]} (Claude Code) and
+ * ${workspaceFolder} (Cursor). Anything else left as ${...} is unresolvable.
+ */
+function expandPinPlaceholders(value, dir) {
+  return value.replace(/\$\{(?:CLAUDE_PROJECT_DIR|workspaceFolder)(?::-[^}]*)?\}/g, dir);
+}
+
+/**
+ * Classify the heyspex server's HEYSPEX_VAULT_ROOT in `dir`'s MCP manifests.
+ * Returns null when no manifest names a pin at all, else one of:
+ *   { kind: 'pin', root, raw, source }       an attachment to a vault OUTSIDE dir
+ *   { kind: 'self' }                         ordinary install (pin is dir or under it)
+ *   { kind: 'broken', raw, source, reason }  a pin that cannot be resolved
+ *       (unknown ${...} placeholder). A broken pin must REFUSE, never fall
+ *       through to the account-wide pointer (owner principle P1).
+ *
+ * PORTABLE pins (owner principle P3, 2026-10-16): a pin may be RELATIVE
+ * ('../mlc-specs') or built on the project-dir placeholder
+ * ('${CLAUDE_PROJECT_DIR:-.}/../mlc-specs'); both resolve against the
+ * MANIFEST'S OWN directory, never the process cwd, so the committed manifest
+ * carries no machine-specific absolute path.
+ *
+ * @param {string} dir
+ */
+export function inspectSatellitePin(dir) {
+  // ONE precedence rule, identical in the TS twin (satellite.ts
+  // readPinnedVaultRoot + the resolver walk): at each directory a committed
+  // satellite MARKER (heyspex.yaml with vault_path) beats any manifest pin; of
+  // the manifests, the first VALID outside pin in read order (.mcp.json, then
+  // .cursor/mcp.json) wins no matter what the other manifest says; a broken
+  // pin refuses only when no manifest carries a valid one; 'self' (an ordinary
+  // install) is the weakest signal. Shared table: satellite-precedence-fixtures.json.
+  let broken = null;
+  let self = false;
+  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 source = rel.join('/');
+    const trimmed = value.trim();
+    const expanded = expandPinPlaceholders(trimmed, dir);
+    if (expanded.includes('${')) {
+      broken ??= { kind: 'broken', raw: trimmed, source, reason: 'it contains a placeholder other than ${CLAUDE_PROJECT_DIR} / ${workspaceFolder}' };
+      continue;
+    }
+    if (/^[a-zA-Z]:(?![\\/])/.test(expanded)) {
+      broken ??= { kind: 'broken', raw: trimmed, source, reason: 'a drive-relative path (C:dir) names no single directory' };
+      continue;
+    }
+    const abs = isAbsolutePin(expanded) ? resolve(expanded) : resolve(dir, expanded);
+    const pinned = normalizeRoot(abs);
+    const here = normalizeRoot(dir);
+    if (pinned === here || pinned.startsWith(`${here}/`)) {
+      self = true;
+      continue;
+    }
+    return { kind: 'pin', root: abs, raw: trimmed, source };
+  }
+  if (broken) return broken;
+  return self ? { kind: 'self' } : null;
+}
+
+/**
+ * Walk up from `startDir` looking for the NEAREST manifest pin that cannot be
+ * honoured: unresolvable placeholder, or a pin whose target is not a vault
+ * root on this machine. Returns null when the nearest pin (or marker) is fine
+ * or there is none. `hs` uses it to REFUSE instead of falling back to the
+ * account-wide pointer ([[HS-O40H]], owner principle P1).
+ *
+ * @param {string} startDir
+ * @param {string} [stopAt]
+ * @returns {{ dir: string, raw: string, source: string, reason: string }|null}
+ */
+export function findBrokenSatellitePin(startDir, stopAt) {
+  let dir = resolve(startDir);
+  const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
+  for (let i = 0; i < 256; i += 1) {
+    if (readMarkerSatellite(dir)) return null; // marker outranks any pin
+    const d = inspectSatellitePin(dir);
+    if (d?.kind === 'broken') return { dir, raw: d.raw, source: d.source, reason: d.reason };
+    if (d?.kind === 'pin') {
+      if (isVaultRoot(d.root)) return null;
+      return { dir, raw: d.raw, source: d.source, reason: `${d.root} is not a vault on this machine (no heyspex.yaml or specs/ there; clone the vault repo there or fix the pin)` };
+    }
+    if (d?.kind === 'self') return null;
+    if (readMarkerSatellite(dir) || isVaultRoot(dir)) return null;
+    if (boundary && dir === boundary) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  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;
+  }
+}
+
+/**
+ * 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).
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function parseMarkerVaultPath(content) {
+  const m = String(content ?? '').match(/^vault_path:[ \t]*(.+?)[ \t]*$/m);
+  if (!m) return null;
+  const v = m[1].trim().replace(/\s+#.*$/, '').replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1').trim();
+  if (!v || v.includes('${') || isAbsolutePin(v)) return null;
+  return v;
+}
+
+/**
+ * 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).
+ *   - `vaultRootAbs`: `resolve(dir, vault_path)` when that directory exists on
+ *     THIS machine and is a vault root 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).
+ *
+ * @param {string} dir
+ * @returns {{ vaultId: string|null, vaultPath: string, vaultRootAbs: string|null }|null}
+ */
+export function readMarkerSatellite(dir) {
+  let raw;
+  try {
+    raw = readFileSync(join(dir, 'heyspex.yaml'), 'utf8');
+  } catch {
+    return null;
+  }
+  const vaultPath = parseMarkerVaultPath(raw);
+  if (!vaultPath) return null;
+  const vaultId = parseMarkerVaultId(raw);
+  const candidate = resolve(dir, vaultPath);
+  let vaultRootAbs = null;
+  if (normalizeRoot(candidate) !== normalizeRoot(dir) && isVaultRoot(candidate)) {
+    const theirs = readMarkerVaultId(candidate);
+    if (!vaultId || !theirs || theirs === vaultId) vaultRootAbs = candidate;
+  }
+  return { vaultId, vaultPath, vaultRootAbs };
+}
+
+/**
+ * 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, markerSatellite?: ReturnType<typeof readMarkerSatellite> }|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;
+    // Precedence (see inspectSatellitePin): committed satellite marker, then
+    // any valid manifest pin, then the generic vault-root test.
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return { repoRootAbs: marked.vaultRootAbs ?? dir, satellite: true, markerSatellite: marked };
     }
-    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 +590,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 +619,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 +637,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,17 +652,103 @@ 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);
+      // 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,
+        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.
+    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.
+  // 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');