heyspex 0.2.2 → 0.2.3

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

@@ -0,0 +1,839 @@
+/**
+ * vault-binding.mjs — which vault a CODE repo writes to: the repo binding.
+ *
+ * Owner ruling 2026-10-14 ([[HS-TYJA]], amends decision
+ * `vault-resolver-precedence-explicit-then`): "there shouldn't be one active
+ * vault. All vaults are active at the same time. Vault is active when user is
+ * launched an agent in the repo folder belonging to a vault. Then that agent
+ * will write to that vault by default." So there is NO machine-global or
+ * account-global "active vault" in local resolution any more. A process finds
+ * its vault from the folder it was launched in, nothing else.
+ *
+ * ── The binding (HS-3PEQ: `heyspex.yaml` `vault:` is the home of "which vault
+ *    this repo is") ─────────────────────────────────────────────────────────
+ * A code repo that is not itself a vault carries, at its root, a COMMITTABLE
+ * file (no machine path in it, so every clone on every machine shares it):
+ *
+ *     kind: repo-binding
+ *     binding_version: 1
+ *     vault:
+ *       id: 800f39cb-9245-412e-b957-e42fb80e2d8b
+ *       name: heyspex-specs
+ *       remote: github.com/pwhermanson/heyspex-specs
+ *
+ *   - `id` is the vault's identity (the cloud vault id). `name` is for humans.
+ *     `remote` is the vault repo's git identity (where to clone it from).
+ *   - WHERE the vault is checked out is per machine: the registry row
+ *     `~/.heyspex/registry.json` vaults[id].repo_root_abs. Resolution is
+ *     heyspex.yaml id -> registry row by id -> its folder; no row (or no
+ *     folder) on this machine -> VAULT_BINDING_BROKEN.
+ *   - A vault checkout's OWN heyspex.yaml is a different file (top-level
+ *     `vault_id:` / `vault_root:`, written by `hs init`); see
+ *     {@link isVaultMarkerText}. The two can never be read as each other.
+ *   - `linked_repos[]` in the registry is the per-machine REVERSE index (which
+ *     folders on this machine are bound to which vault), written by the same
+ *     command. Resolution never needs it: the walk finds the repo's own
+ *     heyspex.yaml, so a moved or renamed CODE repo keeps resolving.
+ *
+ * ── Resolution contract (vault-resolve.mjs `resolveActiveVault`) ───────────
+ * Inputs: an explicit vault id (`--vault`, `options.vaultId`), the env
+ * (`HEYSPEX_VAULT_ROOT`, `HEYSPEX_VAULT_DIR`), and the cwd (`options.cwd`, else
+ * `CLAUDE_PROJECT_DIR`, else `process.cwd()`). Order, first match wins:
+ *   1. explicit vault id (must name a registry row, else
+ *      VAULT_NOT_FOUND - never a silent cascade)                   'explicit'
+ *   2. HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR (a vault checkout on disk
+ *      or a registered vault root, else VAULT_NOT_FOUND)           'env-vault-root' / 'env-vault-dir'
+ *   3. walk up from the cwd (symlinks/junctions resolved), nearest folder
+ *      wins; at each level:
+ *        satellite pin in .mcp.json / .cursor/mcp.json             'satellite-pin'
+ *        vault checkout (specs/ or a vault-marker heyspex.yaml)     'cwd-marker' | 'marker-registry-mismatch' | 'cwd-heuristic'
+ *        heyspex.yaml repo binding (this module)                   'repo-binding'
+ *      then, if the cwd is a linked git worktree and nothing matched,
+ *      the same walk from its main checkout (worktrees resolve like their repo)
+ *   4. nothing -> source 'unbound' + a {@link VaultResolutionError} VAULT_UNBOUND
+ *      on `result.error` (non-throwing API), or thrown by
+ *      `resolveVaultOrThrow` (strict API).
+ * The registry's `active_vault_id` (and v2 per-account pointers) is NEVER read.
+ *
+ * ── Failure modes (stable `code`; each error carries message, `from` = the
+ *    folder resolution walked from, and `fix` = the exact repair command) ───
+ *   VAULT_UNBOUND           cwd is in no vault checkout and no bound repo.
+ *                           Fix: `hs vault bind --vault <id|name>` in the repo.
+ *   VAULT_BINDING_BROKEN    heyspex.yaml binds vault <id>, but this machine's
+ *                           registry has no row for it. (A row whose folder
+ *                           is missing still resolves - cloud tools work by
+ *                           id - with a notice; the disk-tier gate refuses.)
+ *                           Fix: clone/`hs pull` + `hs vault register <path>`,
+ *                           then `hs vault bind --vault <id>`.
+ *   VAULT_NOT_FOUND         an explicit --vault / HEYSPEX_VAULT_ROOT /
+ *                           HEYSPEX_VAULT_DIR names no vault checkout, or
+ *                           `hs vault bind --vault X` names no registered vault.
+ *   VAULT_BINDING_CONFLICT  `hs vault bind` would re-point a repo that is
+ *                           already bound to another vault. Fix: `--force`.
+ *   VAULT_BIND_TARGET_IS_VAULT  `hs vault bind` run inside a vault checkout -
+ *                           it already resolves to itself; nothing to bind.
+ *   REPO_NOT_FOUND          the bind target folder does not exist.
+ *   REGISTRY_UNREADABLE     `hs vault bind` found an unparseable registry.json
+ *                           (it never overwrites one). Fix: `hs doctor --fix`.
+ * Callers: the MCP transport (console-fetch.mjs) returns these as a typed
+ * local refusal (`refusal: code`, nothing sent) per call - the server itself
+ * always boots; `hs` prints the message and exits 1 (`--json`: the
+ * {@link VaultResolutionError#toJSON} shape); spexcode / dev-factory print the
+ * message and stop before any run.
+ *
+
+ * Pure Node ESM, node builtins only (the MCP server and dev-factory keep their
+ * no-install contract). Every function that touches disk takes injectable
+ * paths so tests run on temp fixtures and never touch the real ~/.heyspex.
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+// ── Errors ──────────────────────────────────────────────────────────────────
+
+export const VAULT_UNBOUND = 'VAULT_UNBOUND';
+export const VAULT_BINDING_BROKEN = 'VAULT_BINDING_BROKEN';
+export const VAULT_BINDING_CONFLICT = 'VAULT_BINDING_CONFLICT';
+export const VAULT_NOT_FOUND = 'VAULT_NOT_FOUND';
+export const VAULT_BIND_TARGET_IS_VAULT = 'VAULT_BIND_TARGET_IS_VAULT';
+export const REPO_NOT_FOUND = 'REPO_NOT_FOUND';
+export const REGISTRY_UNREADABLE = 'REGISTRY_UNREADABLE';
+
+/**
+ * The one typed error for "which vault does this process write to" failures,
+ * shared by the MCP server, `hs` and spexcode. `code` is stable for machine
+ * matching; `fix` is the runnable repair command; `details` is JSON-safe.
+ */
+export class VaultResolutionError extends Error {
+  /**
+   * @param {string} code one of the codes exported above
+   * @param {string} message human sentence(s), already naming the fix
+   * @param {{ fix?: string|null, from?: string|null, details?: Record<string, unknown> }} [extra]
+   *   `fix`: the exact command that repairs it. `from`: the folder resolution
+   *   walked from (or the folder the command acted on), forward slashes.
+   */
+  constructor(code, message, { fix = null, from = null, details = {} } = {}) {
+    super(message);
+    this.name = 'VaultResolutionError';
+    this.code = code;
+    this.fix = fix;
+    this.from = typeof from === 'string' && from ? displayPath(from) : null;
+    this.details = details;
+  }
+
+  /**
+   * Stable machine shape (`hs vault resolve --json`, MCP refusals). Keys are
+   * fixed: ok, error (= code, kept for older readers), code, message, from,
+   * fix, details.
+   */
+  toJSON() {
+    return { ok: false, error: this.code, code: this.code, message: this.message, from: this.from, fix: this.fix, details: this.details };
+  }
+}
+
+/** Duck-typed check that survives two copies of this module (vendored bundles). */
+export function isVaultResolutionError(err) {
+  return Boolean(err) && (err instanceof VaultResolutionError || err.name === 'VaultResolutionError') && typeof err.code === 'string';
+}
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical comparison key for a filesystem path. Resolves junctions/symlinks
+ * when the path exists (`realpathSync.native`, so `C:\link` and its target
+ * compare equal), then: absolute, forward slashes, no trailing separator, and
+ * on case-insensitive platforms (win32, darwin) lower-cased — `C:\Dev\` and
+ * `c:/dev` name one directory there.
+ *
+ * @param {string} p
+ * @param {{ platform?: NodeJS.Platform, followLinks?: boolean }} [opts]
+ * @returns {string}
+ */
+export function normalizeRepoPath(p, { platform = process.platform, followLinks = true } = {}) {
+  if (typeof p !== 'string' || !p.trim()) return '';
+  const win = platform === 'win32';
+  let abs = win ? path.win32.resolve(p.trim()) : path.resolve(p.trim());
+  if (followLinks) {
+    try {
+      abs = realpathSync.native(abs);
+    } catch {
+      /* missing path: compare the lexical form */
+    }
+  }
+  let out = abs.replace(/[\\/]+/g, '/');
+  if (out.length > 1) out = out.replace(/\/+$/, '');
+  if (/^[a-zA-Z]:$/.test(out)) out += '/';
+  return win || platform === 'darwin' ? out.toLowerCase() : out;
+}
+
+/** Same folder under {@link normalizeRepoPath}. */
+export function samePath(a, b, opts) {
+  const na = normalizeRepoPath(a, opts);
+  return na !== '' && na === normalizeRepoPath(b, opts);
+}
+
+/** Absolute path in the form written to disk (forward slashes, no trailing slash). */
+export function displayPath(p) {
+  return path.resolve(p).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// ── Git identity (filesystem only: no `git` spawn, so hooks stay fast) ─────
+
+/**
+ * The git checkout containing `startDir`: walks up to the nearest `.git` (a
+ * directory, or a worktree/submodule `.git` FILE pointing at its git dir).
+ *
+ * @param {string} startDir
+ * @returns {{ root: string, gitDir: string, commonDir: string } | null}
+ */
+export function findGitCheckout(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 256; i += 1) {
+    const dotGit = path.join(dir, '.git');
+    if (existsSync(dotGit)) {
+      let gitDir = dotGit;
+      if (!isDir(dotGit)) {
+        try {
+          const m = readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
+          if (m) gitDir = path.resolve(dir, m[1]);
+        } catch {
+          /* unreadable .git file: treat the dir as the root anyway */
+        }
+      }
+      let commonDir = gitDir;
+      try {
+        const rel = readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim();
+        if (rel) commonDir = path.resolve(gitDir, rel);
+      } catch {
+        /* not a linked worktree */
+      }
+      return { root: dir, gitDir, commonDir };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Canonical identity of a git remote URL: `host/owner/repo`, lower-cased,
+ * without scheme, credentials, port or `.git`. `git@github.com:a/b.git`,
+ * `https://user:tok@github.com/A/b` and `ssh://git@github.com/a/b` all map to
+ * `github.com/a/b`. Returns null for anything unparseable.
+ *
+ * @param {string|null|undefined} url
+ * @returns {string|null}
+ */
+export function normalizeRemote(url) {
+  if (typeof url !== 'string' || !url.trim()) return null;
+  let s = url.trim();
+  const scp = s.match(/^[^@/\s]+@([^:/\s]+):(.+)$/); // git@host:owner/repo
+  if (scp && !/^[a-z]+:\/\//i.test(s)) s = `${scp[1]}/${scp[2]}`;
+  else s = s.replace(/^[a-z+]+:\/\//i, '').replace(/^[^@/]*@/, '');
+  s = s.replace(/^([^/:]+):\d+\//, '$1/').replace(/\.git\/?$/i, '').replace(/\/+$/, '');
+  return s.includes('/') ? s.toLowerCase() : null;
+}
+
+/**
+ * The `origin` remote identity of the checkout containing `dir` (falls back
+ * to the first remote), or null.
+ * @param {string} dir
+ * @returns {string|null}
+ */
+export function readGitRemoteIdentity(dir) {
+  const co = findGitCheckout(dir);
+  if (!co) return null;
+  let text;
+  try {
+    text = readFileSync(path.join(co.commonDir, 'config'), 'utf8');
+  } catch {
+    return null;
+  }
+  const remotes = [];
+  let current = null;
+  for (const line of text.split(/\r?\n/)) {
+    const sec = line.match(/^\s*\[\s*remote\s+"([^"]+)"\s*\]/);
+    if (sec) {
+      current = sec[1];
+      continue;
+    }
+    if (/^\s*\[/.test(line)) {
+      current = null;
+      continue;
+    }
+    const url = current && line.match(/^\s*url\s*=\s*(.+?)\s*$/);
+    if (url) remotes.push({ name: current, url: url[1] });
+  }
+  const pick = remotes.find((r) => r.name === 'origin') ?? remotes[0];
+  return pick ? normalizeRemote(pick.url) : null;
+}
+
+// ── heyspex.yaml `vault:` binding ────────────────────────────────────────────
+//
+// TWO different files are both named heyspex.yaml, and they must never be
+// confused (a code repo would otherwise resolve as a vault, or a vault as a
+// bound repo):
+//
+//   VAULT MARKER (a vault checkout's own root, written by `hs init`):
+//       schema_version: 2
+//       vault_root: specs/
+//       vault_id: <uuid>
+//     Identified by the top-level `vault_id:` / `vault_root:` keys.
+//
+//   REPO BINDING (a code repo, written by `hs vault bind`; COMMITTABLE):
+//       kind: repo-binding
+//       binding_version: 1
+//       vault:
+//         id: <uuid>
+//         name: <display name>
+//         remote: <host/owner/repo of the vault's git remote>
+//     Identified by `kind: repo-binding` + the `vault:` block. It carries the
+//     vault's stable identity ONLY - never a machine path. Where the vault is
+//     checked out on THIS machine is the registry's business
+//     (`~/.heyspex/registry.json` vaults[].repo_root_abs, per machine).
+//
+// A file carrying BOTH a vault-marker key and a `vault:` block is a vault
+// marker (the checkout wins); its `vault:` block is ignored.
+
+/** `kind:` value of a repo-binding heyspex.yaml. */
+export const REPO_BINDING_KIND = 'repo-binding';
+/** Bump when the binding block's shape changes. */
+export const REPO_BINDING_VERSION = 1;
+
+const BINDING_KEYS = ['id', 'name', 'remote'];
+const MARKER_KEY_RE = /^(vault_id|vault_root):/m;
+const OWN_TOP_KEYS_RE = /^(kind|binding_version|schema_version):/;
+const OWN_HEADER_RE = /^# HeySpex repo binding/;
+const OWN_HEADER_CONT_RE = /^# (write to the vault below|Agents launched in this repo write|checked out is per machine)/;
+
+/** True when heyspex.yaml text is a VAULT MARKER (top-level vault_id / vault_root). */
+export function isVaultMarkerText(text) {
+  return MARKER_KEY_RE.test(String(text ?? ''));
+}
+
+/** Top-level `kind:` of heyspex.yaml text, or null. */
+function topLevelKind(text) {
+  const m = String(text ?? '').match(/^kind:\s*(.+?)\s*$/m);
+  return m ? m[1].replace(/^["']|["']$/g, '').trim() || null : null;
+}
+
+/**
+ * Parse the `vault:` binding out of heyspex.yaml text. Accepts the block form
+ * written by {@link renderRepoBinding} and the scalar shorthand `vault: <id>`.
+ * Returns null when there is no `vault:` key, it carries no id, the file is a
+ * vault marker ({@link isVaultMarkerText}), or `kind:` names something other
+ * than `repo-binding`. A legacy `path:` key (stage-1 files) is ignored.
+ *
+ * @param {string} text
+ * @returns {{ id: string, name: string|null, remote: string|null } | null}
+ */
+export function parseRepoBinding(text) {
+  const src = String(text ?? '');
+  if (isVaultMarkerText(src)) return null;
+  const kind = topLevelKind(src);
+  if (kind !== null && kind !== REPO_BINDING_KIND) return null;
+  const lines = src.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^vault:(\s|$)/.test(l));
+  if (start === -1) return null;
+  const unq = (v) => v.trim().replace(/\s+#.*$/, '').replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1').trim();
+  const scalar = lines[start].slice('vault:'.length).trim();
+  if (scalar && !scalar.startsWith('#')) {
+    const id = unq(scalar);
+    return id ? { id, name: null, remote: null } : null;
+  }
+  const out = { id: null, name: null, remote: null };
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const l = lines[i];
+    if (!l.trim() || /^\s*#/.test(l)) continue;
+    if (!/^\s+/.test(l)) break; // next top-level key
+    const m = l.match(/^\s+([a-z_]+):\s*(.*)$/);
+    if (m && BINDING_KEYS.includes(m[1])) out[m[1]] = unq(m[2]) || null;
+  }
+  return out.id ? out : null;
+}
+
+/** heyspex.yaml path of a folder. */
+function markerPath(dir) {
+  return path.join(dir, 'heyspex.yaml');
+}
+
+function readTextOrNull(file) {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `vault:` binding in `<dir>/heyspex.yaml`, or null (no file, no block,
+ * a vault marker, unreadable). Never throws.
+ * @param {string} dir
+ */
+export function readRepoBinding(dir) {
+  const text = readTextOrNull(markerPath(dir));
+  return text === null ? null : parseRepoBinding(text);
+}
+
+/**
+ * Is `dir` a bound CODE repo (a repo-binding heyspex.yaml and no `specs/` of
+ * its own)? Such a folder is never a vault root.
+ * @param {string} dir
+ */
+export function isRepoBindingDir(dir) {
+  return !existsSync(path.join(dir, 'specs')) && readRepoBinding(dir) !== null;
+}
+
+/**
+ * New heyspex.yaml text for a repo binding. The canonical header, `kind`,
+ * `binding_version` and the `vault:` block are (re)written; any OTHER
+ * top-level content an existing file carries is preserved after them. Pure:
+ * the same inputs always give byte-identical output (idempotent re-binds).
+ *
+ * @param {string|null} existing current file text (null = no file)
+ * @param {{ id: string, name?: string|null, remote?: string|null }} binding
+ */
+export function renderRepoBinding(existing, binding) {
+  const fmt = (v) => (/[:#'"\s{}[\],&*!|>%@`]/.test(v) ? JSON.stringify(v) : v);
+  const block = ['vault:'];
+  for (const k of BINDING_KEYS) {
+    const v = binding[k];
+    if (typeof v === 'string' && v.trim()) block.push(`  ${k}: ${fmt(v.trim())}`);
+  }
+  const head = [
+    '# HeySpex repo binding - written by `hs vault bind`; commit this file.',
+    '# Agents launched in this repo write to the vault below. Where that vault is',
+    '# checked out is per machine (~/.heyspex/registry.json), never recorded here.',
+    `kind: ${REPO_BINDING_KIND}`,
+    `binding_version: ${REPO_BINDING_VERSION}`,
+    ...block,
+  ];
+  const eol = existing && existing.includes('\r\n') ? '\r\n' : '\n';
+  const rest = [];
+  if (existing && existing.trim()) {
+    const lines = existing.split(/\r?\n/);
+    let inVault = false;
+    let leading = true;
+    for (const l of lines) {
+      // Our own header comment (this and earlier wordings) leads the file;
+      // it is regenerated above, so drop it here.
+      if (leading && (OWN_HEADER_RE.test(l) || OWN_HEADER_CONT_RE.test(l))) continue;
+      leading = false;
+      if (/^vault:(\s|$)/.test(l)) {
+        inVault = true;
+        continue;
+      }
+      if (inVault) {
+        if (l === '' || /^\s+/.test(l)) continue;
+        inVault = false;
+      }
+      if (OWN_TOP_KEYS_RE.test(l)) continue;
+      rest.push(l);
+    }
+  }
+  while (rest.length && !rest[rest.length - 1].trim()) rest.pop();
+  while (rest.length && !rest[0].trim()) rest.shift();
+  return [...head, ...(rest.length ? ['', ...rest] : []), ''].join(eol);
+}
+
+/**
+ * Write a file atomically: temp file in the same folder, then rename over the
+ * target (a crash leaves either the old or the new file, never half of one).
+ */
+function writeFileAtomic(file, text) {
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, text, 'utf8');
+  try {
+    renameSync(tmp, file);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* best effort */
+    }
+    throw err;
+  }
+}
+
+// ── Registry (~/.heyspex/registry.json) ────────────────────────────────────
+
+/** Current shape of a `linked_repos[]` row; bump when the row shape changes. */
+export const LINKED_REPO_ROW_VERSION = 1;
+
+export function defaultRegistryDir() {
+  return path.join(homedir(), '.heyspex');
+}
+
+/**
+ * Read registry.json for the binding commands. Unlike the resolver's
+ * fail-open reader, a writer must not clobber a file it could not parse.
+ *
+ * @param {string} registryDir
+ * @returns {{ kind: 'missing' } | { kind: 'ok', json: Record<string, any>, text: string } | { kind: 'unreadable', error: string }}
+ */
+export function readRegistryFile(registryDir) {
+  const file = path.join(registryDir, 'registry.json');
+  if (!existsSync(file)) return { kind: 'missing' };
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+    const json = JSON.parse(text);
+    if (!json || typeof json !== 'object' || Array.isArray(json)) return { kind: 'unreadable', error: 'not a JSON object' };
+    return { kind: 'ok', json, text };
+  } catch (err) {
+    return { kind: 'unreadable', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Registered, non-archived vault rows: `{ id, name, root, remote }`. */
+export function registryVaults(json) {
+  const rows = Array.isArray(json?.vaults) ? json.vaults : [];
+  return rows
+    .filter((v) => v && typeof v.id === 'string' && v.id.trim() && typeof v.repo_root_abs === 'string' && v.repo_root_abs.trim() && !v.archived)
+    .map((v) => ({
+      id: v.id,
+      name: typeof v.display_name === 'string' && v.display_name.trim() ? v.display_name : v.id,
+      root: path.resolve(v.repo_root_abs),
+      remote: normalizeRemote(v.github_remote),
+    }));
+}
+
+/** Normalized `linked_repos[]` rows (unknown fields preserved under `raw`). */
+export function registryLinkedRepos(json) {
+  const rows = Array.isArray(json?.linked_repos) ? json.linked_repos : [];
+  return rows.filter((r) => r && typeof r.repo_root_abs === 'string' && typeof r.vault_id === 'string');
+}
+
+/**
+ * Upgrade a registry object in place to carry `linked_repos[]`. Additive and
+ * idempotent: `schema_version` is left as is (HS-HHLU: the key is optional, old
+ * readers ignore it; both loaders already tolerate unknown keys), and rows
+ * missing `row_version` are stamped. Returns true when anything changed.
+ */
+export function migrateRegistryForBindings(json) {
+  let changed = false;
+  if (!Array.isArray(json.linked_repos)) {
+    json.linked_repos = [];
+    changed = true;
+  }
+  for (const r of json.linked_repos) {
+    if (r && typeof r === 'object' && r.row_version !== LINKED_REPO_ROW_VERSION) {
+      r.row_version = LINKED_REPO_ROW_VERSION;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/**
+ * Write registry.json atomically (temp file + rename). Before the FIRST write
+ * that introduces `linked_repos[]` it copies the original to
+ * `registry.json.bak-pre-linked-repos` (once; never overwritten), so the
+ * migration is reversible.
+ */
+function writeRegistryFile(registryDir, json, { originalText, migrated }) {
+  const file = path.join(registryDir, 'registry.json');
+  if (migrated && typeof originalText === 'string') {
+    const bak = path.join(registryDir, 'registry.json.bak-pre-linked-repos');
+    if (!existsSync(bak)) copyFileSync(file, bak);
+  }
+  mkdirSync(registryDir, { recursive: true });
+  writeFileAtomic(file, `${JSON.stringify(json, null, 2)}\n`);
+}
+
+// ── Resolving a binding to a vault checkout ────────────────────────────────
+
+/** `hs vault bind --vault <id>` for the error/fix text (id quoted only when needed). */
+function bindCommand(id, { force = false } = {}) {
+  const sel = /^[A-Za-z0-9._-]+$/.test(String(id)) ? id : JSON.stringify(String(id));
+  return `hs vault bind --vault ${sel}${force ? ' --force' : ''}`;
+}
+
+/**
+ * Where the vault named by `binding` lives on THIS machine: the registry row
+ * whose id is `binding.id` (a missing folder still resolves - the id is known,
+ * so cloud tools work - with a notice; the disk-tier gate refuses it). That is
+ * the only lookup -
+ * the binding file carries no path, and a registry row with the same git
+ * remote under a DIFFERENT id is a different vault identity, never silently
+ * substituted (it is named in the error instead). Throws VAULT_BINDING_BROKEN
+ * when this machine has no usable checkout of the bound vault.
+ *
+ * @param {{ id: string, name?: string|null, remote?: string|null }} binding
+ * @param {{ vaults: Array<{ id: string, name: string, root: string, remote: string|null }> }} registry
+ * @param {{ bindingDir: string, from?: string }} ctx  `from`: the folder the walk started at
+ * @returns {{ vaultId: string, repoRootAbs: string, via: 'registry', notice: string|null }}
+ */
+export function locateBoundVault(binding, registry, { bindingDir, from = bindingDir }) {
+  const vaults = registry?.vaults ?? [];
+  const row = vaults.find((v) => v.id === binding.id);
+  if (row && isDir(row.root)) {
+    return { vaultId: row.id, repoRootAbs: row.root, via: 'registry', notice: null };
+  }
+  if (row && !existsSync(row.root)) {
+    // Registered on this machine, no local checkout: the vault id is known,
+    // so cloud reads/writes work; the disk-tier gate refuses the absent root.
+    return {
+      vaultId: row.id,
+      repoRootAbs: row.root,
+      via: 'registry',
+      notice: `vault ${row.name} (${row.id}) bound in ${displayPath(bindingDir)}/heyspex.yaml has no local checkout at ${displayPath(row.root)}; cloud tools work, disk tools will refuse until it is cloned there.`,
+    };
+  }
+  const label = binding.name ? `${binding.name} (${binding.id})` : binding.id;
+  const sameRemote = binding.remote ? vaults.filter((v) => v.remote === binding.remote && v.id !== binding.id) : [];
+  const why = row
+    ? `the registry row for it points at ${displayPath(row.root)}, which is not a vault checkout`
+    : 'this machine has no registry row for that vault id';
+  const clone = binding.remote ? `git clone https://${binding.remote}.git` : 'clone the vault repo';
+  const hint = sameRemote.length
+    ? ` Note: registered vault ${sameRemote.map((v) => `${v.name} (${v.id})`).join(', ')} has the same git remote under a different id - if that is the same vault, re-bind with \`${bindCommand(sameRemote[0].id, { force: true })}\`.`
+    : '';
+  throw new VaultResolutionError(
+    VAULT_BINDING_BROKEN,
+    `${displayPath(bindingDir)}/heyspex.yaml binds this repo to vault ${label}, but ${why}. ` +
+      `Get a checkout of the vault on this machine (${clone}, or \`hs pull\` inside an existing checkout) and register it (\`hs vault register <path>\`), ` +
+      `then run \`${bindCommand(binding.id)}\` in ${displayPath(bindingDir)}.${hint}`,
+    {
+      fix: bindCommand(binding.id),
+      from,
+      details: { bindingDir: displayPath(bindingDir), binding, registryRoot: row ? displayPath(row.root) : null },
+    },
+  );
+}
+
+/**
+ * The VAULT_UNBOUND error for a cwd that resolved to nothing. Lists every
+ * registered vault so the message carries the exact bind command.
+ *
+ * @param {string} cwd
+ * @param {Array<{ id: string, name: string, root: string }>} vaults
+ */
+export function unboundError(cwd, vaults) {
+  const repo = findGitCheckout(cwd)?.root ?? path.resolve(cwd);
+  const list = vaults.length
+    ? vaults.map((v) => `    ${v.name}  ${v.id}  ${displayPath(v.root)}`).join('\n')
+    : '    (none registered on this machine - clone a vault and run `hs vault register <path>`)';
+  const fix = vaults.length === 1 ? bindCommand(vaults[0].id) : 'hs vault bind --vault <name|id>';
+  return new VaultResolutionError(
+    VAULT_UNBOUND,
+    `No HeySpex vault is bound to ${displayPath(repo)}, and it is not inside a vault checkout. ` +
+      'There is no default "active" vault: an agent writes to the vault bound to the repo it was launched in.\n' +
+      `  registered vaults:\n${list}\n` +
+      `  bind this repo:   ${fix}   (run in ${displayPath(repo)})\n` +
+      '  or override once: HEYSPEX_VAULT_ROOT=<vault checkout>',
+    { fix, from: cwd, details: { cwd: displayPath(cwd), repo: displayPath(repo), registered: vaults.map((v) => ({ id: v.id, name: v.name, root: displayPath(v.root) })) } },
+  );
+}
+
+// ── The commands (`hs vault bind` / `hs vault bindings`) ───────────────────
+
+/**
+ * Find the registered vault a user named: id, display name (case-insensitive)
+ * or the path of its checkout.
+ */
+export function findVaultBySelector(vaults, selector) {
+  if (typeof selector !== 'string' || !selector.trim()) return null;
+  const s = selector.trim();
+  return (
+    vaults.find((v) => v.id === s) ??
+    vaults.find((v) => v.name.toLowerCase() === s.toLowerCase()) ??
+    vaults.find((v) => samePath(v.root, s)) ??
+    null
+  );
+}
+
+/**
+ * Bind a code repo to a vault: write `<repo>/heyspex.yaml` (kind: repo-binding,
+ * the vault's id/name/remote - no path) and the registry `linked_repos[]` row
+ * (this machine's path for the repo). Idempotent (re-binding the same vault
+ * rewrites nothing and reports `unchanged`); refuses to re-point a bound repo
+ * without `force` (VAULT_BINDING_CONFLICT, naming the current binding); refuses
+ * a vault checkout (VAULT_BIND_TARGET_IS_VAULT). A registry row for the same
+ * git remote whose folder no longer exists is replaced (the repo was
+ * moved/renamed) and reported in `movedFrom`. Both writes are atomic; the
+ * registry is backed up once before `linked_repos[]` is first introduced.
+ *
+ * @param {{ repo?: string, cwd?: string, vault?: string|null, force?: boolean, dryRun?: boolean, registryDir?: string, now?: () => Date }} opts
+ *   `repo`: folder to bind (default: the git checkout containing `cwd`, else `cwd`).
+ *   `vault`: id, name or checkout path of a registered vault; when omitted the
+ *   repo's existing binding is re-asserted (refreshes name/remote + registry row).
+ */
+export function bindRepo({
+  repo,
+  cwd = process.cwd(),
+  vault = null,
+  force = false,
+  dryRun = false,
+  registryDir = defaultRegistryDir(),
+  now = () => new Date(),
+} = {}) {
+  const repoRoot = path.resolve(repo ?? findGitCheckout(cwd)?.root ?? cwd);
+  if (!isDir(repoRoot)) {
+    throw new VaultResolutionError(REPO_NOT_FOUND, `The folder to bind does not exist: ${displayPath(repoRoot)}.`, {
+      fix: 'hs vault bind --repo <existing folder> --vault <name|id>',
+      from: cwd,
+      details: { repo: displayPath(repoRoot) },
+    });
+  }
+  const reg = readRegistryFile(registryDir);
+  if (reg.kind === 'unreadable') {
+    throw new VaultResolutionError(
+      REGISTRY_UNREADABLE,
+      `~/.heyspex/registry.json could not be parsed (${reg.error}); nothing was written. Repair it (or run \`hs doctor --fix\`) and retry.`,
+      { fix: 'hs doctor --fix', from: repoRoot, details: { registryDir: displayPath(registryDir) } },
+    );
+  }
+  const json = reg.kind === 'ok' ? reg.json : { schema_version: 1, workspaces: [], vaults: [] };
+  const vaults = registryVaults(json);
+
+  const existingText = readTextOrNull(markerPath(repoRoot));
+  if (isVaultMarkerText(existingText) || existsSync(path.join(repoRoot, 'specs'))) {
+    const self = vaults.find((v) => samePath(v.root, repoRoot));
+    throw new VaultResolutionError(
+      VAULT_BIND_TARGET_IS_VAULT,
+      `${displayPath(repoRoot)} is itself a vault checkout${self ? ` (${self.name}, ${self.id})` : ''}; agents launched here already write to it. Nothing to bind.`,
+      { fix: 'hs vault resolve', from: repoRoot, details: { repo: displayPath(repoRoot), vaultId: self?.id ?? null } },
+    );
+  }
+
+  const current = existingText === null ? null : parseRepoBinding(existingText);
+  const selector = vault ?? current?.id ?? null;
+  if (!selector) {
+    throw unboundError(repoRoot, vaults);
+  }
+  const target = findVaultBySelector(vaults, selector);
+  if (!target) {
+    const list = vaults.map((v) => `    ${v.name}  ${v.id}  ${displayPath(v.root)}`).join('\n') || '    (none)';
+    throw new VaultResolutionError(
+      VAULT_NOT_FOUND,
+      `No registered vault matches "${selector}" (by id, name or path).\n  registered vaults:\n${list}\n  Register the vault first: hs vault register <path>`,
+      { fix: 'hs vault register <path>', from: repoRoot, details: { selector } },
+    );
+  }
+  if (current && current.id !== target.id && !force) {
+    throw new VaultResolutionError(
+      VAULT_BINDING_CONFLICT,
+      `${displayPath(repoRoot)} is already bound to vault ${current.name ?? current.id} (${current.id}). ` +
+        `Re-run with --force to bind it to ${target.name} (${target.id}) instead.`,
+      { fix: bindCommand(target.id, { force: true }), from: repoRoot, details: { repo: displayPath(repoRoot), current, requested: { id: target.id, name: target.name } } },
+    );
+  }
+
+  const binding = { id: target.id, name: target.name, remote: target.remote ?? readGitRemoteIdentity(target.root) };
+  const nextText = renderRepoBinding(existingText, binding);
+  const yamlChanged = nextText !== existingText;
+
+  const migrated = migrateRegistryForBindings(json);
+  const repoNorm = normalizeRepoPath(repoRoot);
+  const repoRemote = readGitRemoteIdentity(repoRoot);
+  const rows = json.linked_repos;
+  const existingIdx = rows.findIndex((r) => r && typeof r.repo_root_abs === 'string' && normalizeRepoPath(r.repo_root_abs) === repoNorm);
+  let movedFrom = null;
+  if (existingIdx === -1 && repoRemote) {
+    const moved = rows.findIndex((r) => r && r.git_remote === repoRemote && typeof r.repo_root_abs === 'string' && !isDir(r.repo_root_abs));
+    if (moved !== -1) {
+      movedFrom = rows[moved].repo_root_abs;
+      rows.splice(moved, 1);
+    }
+  }
+  const prev = existingIdx === -1 ? null : rows[existingIdx];
+  const row = {
+    repo_root_abs: displayPath(repoRoot),
+    vault_id: target.id,
+    git_remote: repoRemote,
+    bound_at: prev && prev.vault_id === target.id && prev.bound_at ? prev.bound_at : now().toISOString(),
+    row_version: LINKED_REPO_ROW_VERSION,
+  };
+  const rowChanged = !prev || JSON.stringify(prev) !== JSON.stringify({ ...prev, ...row });
+  // Collapse duplicate rows for the same folder (e.g. `C:\x` and `c:/x/`).
+  const dupes = rows.filter((r) => r && typeof r.repo_root_abs === 'string' && normalizeRepoPath(r.repo_root_abs) === repoNorm);
+  const deduped = dupes.length > 1;
+  const kept = rows.filter((r) => !(r && typeof r.repo_root_abs === 'string' && normalizeRepoPath(r.repo_root_abs) === repoNorm));
+  kept.push(prev ? { ...prev, ...row } : row);
+  json.linked_repos = kept;
+
+  const registryChanged = rowChanged || migrated || Boolean(movedFrom) || deduped;
+  const status = !yamlChanged && !registryChanged ? 'unchanged' : current && current.id !== target.id ? 'rebound' : current ? 'refreshed' : 'bound';
+  if (!dryRun) {
+    if (yamlChanged) writeFileAtomic(markerPath(repoRoot), nextText);
+    if (registryChanged) writeRegistryFile(registryDir, json, { originalText: reg.kind === 'ok' ? reg.text : null, migrated });
+  }
+  return {
+    ok: true,
+    status,
+    dryRun,
+    repo: displayPath(repoRoot),
+    vault: { id: target.id, name: target.name, path: displayPath(target.root), remote: binding.remote },
+    previous: current && current.id !== target.id ? current : null,
+    movedFrom,
+    wrote: dryRun ? [] : [...(yamlChanged ? [displayPath(markerPath(repoRoot))] : []), ...(registryChanged ? [displayPath(path.join(registryDir, 'registry.json'))] : [])],
+  };
+}
+
+/**
+ * Every binding this machine knows (`linked_repos[]`), each health-checked
+ * against the repo's own heyspex.yaml. Status per row:
+ *   ok             heyspex.yaml binds the same vault and the vault is registered
+ *   repo-missing   the repo folder is gone (moved/renamed: re-run `hs vault bind` in the new folder)
+ *   marker-missing the folder exists but its heyspex.yaml carries no binding
+ *   marker-differs heyspex.yaml binds a different vault (it wins at resolution time)
+ *   vault-unknown  the bound vault id has no registry row
+ * Output is sorted by repo path so it is stable across runs.
+ *
+ * @param {{ registryDir?: string }} [opts]
+ */
+export function listBindings({ registryDir = defaultRegistryDir() } = {}) {
+  const reg = readRegistryFile(registryDir);
+  const json = reg.kind === 'ok' ? reg.json : {};
+  const vaults = registryVaults(json);
+  const rows = registryLinkedRepos(json).map((r) => {
+    const v = vaults.find((x) => x.id === r.vault_id) ?? null;
+    let status = 'ok';
+    let marker = null;
+    if (!isDir(r.repo_root_abs)) status = 'repo-missing';
+    else {
+      marker = readRepoBinding(r.repo_root_abs);
+      if (!marker) status = 'marker-missing';
+      else if (marker.id !== r.vault_id) status = 'marker-differs';
+      else if (!v) status = 'vault-unknown';
+    }
+    return {
+      repo: displayPath(r.repo_root_abs),
+      vault_id: r.vault_id,
+      vault_name: v?.name ?? null,
+      vault_path: v ? displayPath(v.root) : null,
+      git_remote: r.git_remote ?? null,
+      bound_at: r.bound_at ?? null,
+      status,
+      ...(status === 'marker-differs' ? { marker_vault_id: marker.id } : {}),
+    };
+  });
+  rows.sort((a, b) => (normalizeRepoPath(a.repo, { followLinks: false }) < normalizeRepoPath(b.repo, { followLinks: false }) ? -1 : 1));
+  return {
+    registry: reg.kind,
+    vaults: vaults.map((v) => ({ id: v.id, name: v.name, path: displayPath(v.root) })).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+    bindings: rows,
+  };
+}