heyspex 0.1.0 → 0.2.0

package/dist/cli/hs-claim.mjs

@@ -1,9 +1,290 @@
 import { createRequire as __hsCreateRequire } from 'node:module';
 const require = __hsCreateRequire(import.meta.url);
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// vendor/heyspex-mcp/credentials.mjs
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import os, { homedir } from "node:os";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+function credentialsFilePath(homeDir = homedir()) {
+  return join2(homeDir, ".heyspex", "credentials.yaml");
+}
+function parseMcpToken(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  const token = raw.match(MCP_TOKEN_LINE_RE)?.[1]?.trim();
+  return token ? token : null;
+}
+function isValidAccountId(id) {
+  return typeof id === "string" && ACCOUNT_ID_RE.test(id);
+}
+function topLevelScalar(raw, key) {
+  const re = new RegExp(`^${key}:[ \\t]*["']?([^"'\\r\\n#]+)`, "m");
+  const value = raw.match(re)?.[1]?.trim();
+  return value ? value : null;
+}
+function decodeScalar(text) {
+  const t = text.trim();
+  if (t === "" || t === "null" || t === "~") return null;
+  if (t.startsWith('"')) {
+    try {
+      const v = JSON.parse(t);
+      return typeof v === "string" && v ? v : null;
+    } catch {
+      return t.replace(/^"|"$/g, "") || null;
+    }
+  }
+  if (t.startsWith("'")) return t.replace(/^'|'$/g, "") || null;
+  const bare = t.replace(/\s+#.*$/, "").trim();
+  return bare || null;
+}
+function emptyAccount() {
+  return { mcp_token: null, console_url: null, email: null, paired_at: null };
+}
+function findAccountsBlock(lines) {
+  const start = lines.findIndex((l) => /^accounts:[ \t]*(#.*)?$/.test(l));
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length && (lines[end].trim() === "" || /^[ \t]/.test(lines[end]))) end += 1;
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  return { start, end };
+}
+function parseAccountsBlock(lines) {
+  const accounts = {};
+  const block = findAccountsBlock(lines);
+  if (!block) return accounts;
+  let current = null;
+  for (const line of lines.slice(block.start + 1, block.end)) {
+    const header = line.match(/^ {2}([^\s:#][^:]*):[ \t]*(#.*)?$/);
+    if (header) {
+      const id = decodeScalar(header[1]);
+      current = isValidAccountId(id) ? id : null;
+      if (current) accounts[current] = emptyAccount();
+      continue;
+    }
+    const field = line.match(/^ {4}([a-z_]+):(.*)$/);
+    if (field && current && ACCOUNT_FIELDS.includes(field[1])) {
+      accounts[current][field[1]] = decodeScalar(field[2]);
+    }
+  }
+  return accounts;
+}
+function parseCredentialsStore(raw) {
+  const text = typeof raw === "string" ? raw : "";
+  if (topLevelScalar(text, "schema_version") !== String(CREDENTIALS_SCHEMA_VERSION)) {
+    const token = parseMcpToken(text);
+    if (!token) return { schemaVersion: 1, currentAccountId: null, accounts: {} };
+    return {
+      schemaVersion: 1,
+      currentAccountId: LEGACY_ACCOUNT_ID,
+      accounts: {
+        [LEGACY_ACCOUNT_ID]: { ...emptyAccount(), mcp_token: token, console_url: topLevelScalar(text, "console_url") }
+      }
+    };
+  }
+  const accounts = parseAccountsBlock(text.split(/\r?\n/));
+  const current = topLevelScalar(text, "current_account_id");
+  return {
+    schemaVersion: 2,
+    currentAccountId: current && accounts[current] ? current : null,
+    accounts
+  };
+}
+function resolveBearer({ envToken, credentialsText, accountId, legacyAccountId } = {}) {
+  const fromEnv = typeof envToken === "string" ? envToken.trim() : "";
+  if (fromEnv) return { token: fromEnv, source: "env" };
+  const store = parseCredentialsStore(credentialsText);
+  let entry;
+  if (typeof accountId === "string" && accountId.trim()) {
+    const wanted = accountId.trim();
+    entry = store.accounts[wanted];
+    if (!entry && store.schemaVersion === 1 && legacyAccountId && wanted === legacyAccountId) {
+      entry = store.accounts[LEGACY_ACCOUNT_ID];
+    }
+  } else {
+    entry = store.currentAccountId ? store.accounts[store.currentAccountId] : void 0;
+  }
+  if (entry?.mcp_token) return { token: entry.mcp_token, source: "credentials-file" };
+  return { token: null, source: null };
+}
+function readTextOrNull(read, path2) {
+  try {
+    const raw = read(path2);
+    return typeof raw === "string" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function readLegacyConfigAccountId(read, homeDir) {
+  const raw = readTextOrNull(read, join2(homeDir, ".heyspex", "config.yaml"));
+  const value = raw?.match(CONFIG_ACCOUNT_ID_RE)?.[1]?.trim() ?? "";
+  return value || null;
+}
+function readBearer({ env = process.env, homeDir = homedir(), readFile, accountId } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, "utf8"));
+  const credentialsText = readTextOrNull(read, credentialsFilePath(homeDir));
+  const named = typeof accountId === "string" && accountId.trim() ? accountId.trim() : null;
+  const legacyAccountId = named && parseCredentialsStore(credentialsText).schemaVersion === 1 ? readLegacyConfigAccountId(read, homeDir) : null;
+  return resolveBearer({ envToken: env?.[MCP_TOKEN_ENV], credentialsText, accountId: named, legacyAccountId });
+}
+function readCurrentAccountId({ homeDir = homedir(), readFile } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, "utf8"));
+  const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
+  if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
+    return store.currentAccountId;
+  }
+  if (store.schemaVersion === 2 && store.currentAccountId === null) return null;
+  return readLegacyConfigAccountId(read, homeDir);
+}
+var MCP_TOKEN_ENV, MCP_TOKEN_LINE_RE, CREDENTIALS_SCHEMA_VERSION, LEGACY_ACCOUNT_ID, ACCOUNT_FIELDS, ACCOUNT_ID_RE, CONFIG_ACCOUNT_ID_RE;
+var init_credentials = __esm({
+  "vendor/heyspex-mcp/credentials.mjs"() {
+    "use strict";
+    MCP_TOKEN_ENV = "HEYSPEX_MCP_TOKEN";
+    MCP_TOKEN_LINE_RE = /^mcp_token:[ \t]*["']?([^"'\r\n#]+)/m;
+    CREDENTIALS_SCHEMA_VERSION = 2;
+    LEGACY_ACCOUNT_ID = "legacy";
+    ACCOUNT_FIELDS = ["mcp_token", "console_url", "email", "paired_at"];
+    ACCOUNT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.@+-]*$/;
+    CONFIG_ACCOUNT_ID_RE = /^account_id:\s*["']?([^"'\r\n#]+)/m;
+  }
+});
+
+// scripts/lib/dev-mode.mjs
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join7 } from "node:path";
+function devModeFilePath(homeDir = homedir6()) {
+  return join7(homeDir, ".heyspex", DEV_MODE_FILENAME);
+}
+function normalizeMode(raw) {
+  const v = String(raw ?? "").trim().toLowerCase();
+  if (v === "prod" || v === "production") return { mode: "prod", reliance: "cloud" };
+  if (v === "dev") return { mode: "dev", reliance: null };
+  if (v === "local") return { mode: "dev", reliance: "local" };
+  if (v === "cloud") return { mode: "dev", reliance: "cloud" };
+  return null;
+}
+function normalizeReliance(raw) {
+  const v = String(raw ?? "").trim().toLowerCase();
+  return v === "local" || v === "cloud" ? v : null;
+}
+function deriveSemantics(mode, reliance) {
+  const effectiveReliance = mode === "prod" ? "cloud" : reliance ?? "local";
+  const local = mode === "dev" && effectiveReliance === "local";
+  return {
+    reliance: effectiveReliance,
+    consoleUrl: local ? LOCAL_CONSOLE_URL : CLOUD_CONSOLE_URL,
+    readTier: local ? "disk" : "neon",
+    vaultWriteMode: local ? "local" : "cloud"
+  };
+}
+function readLocalDevModeRecord({ homeDir = homedir6(), readFile = defaultReadFile } = {}) {
+  let raw;
+  try {
+    raw = readFile(devModeFilePath(homeDir));
+  } catch {
+    return { record: null, parseError: null };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const mode = parsed?.mode === "prod" || parsed?.mode === "dev" ? parsed.mode : null;
+    const reliance = normalizeReliance(parsed?.reliance);
+    if (!mode || mode === "dev" && !reliance) {
+      return { record: null, parseError: `invalid dev-mode record: ${JSON.stringify(parsed)}` };
+    }
+    return {
+      record: {
+        mode,
+        reliance: mode === "prod" ? "cloud" : reliance,
+        console_url: typeof parsed.console_url === "string" ? parsed.console_url : null,
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : null,
+        source: typeof parsed.source === "string" ? parsed.source : null
+      },
+      parseError: null
+    };
+  } catch (err) {
+    return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
+  }
+}
+function resolveDevMode({
+  env = process.env,
+  homeDir = homedir6(),
+  readFile = defaultReadFile,
+  cloudSetting = void 0
+} = {}) {
+  const local = readLocalDevModeRecord({ homeDir, readFile });
+  const cloudKnown = cloudSetting !== void 0;
+  const cloudValue = cloudKnown && cloudSetting ? {
+    mode: cloudSetting.mode === "dev" ? "dev" : "prod",
+    reliance: normalizeReliance(cloudSetting.reliance) ?? "cloud"
+  } : null;
+  let mode;
+  let reliance;
+  let source;
+  let relianceSource;
+  const envParsed = normalizeMode(env.HEYSPEX_DEV_MODE);
+  if (envParsed) {
+    mode = envParsed.mode;
+    const envReliance = envParsed.reliance ?? normalizeReliance(env.HEYSPEX_DEV_RELIANCE);
+    reliance = envReliance ?? "local";
+    source = "env";
+    relianceSource = envReliance ? "env" : "assumed-local";
+  } else if (local.record) {
+    mode = local.record.mode;
+    reliance = local.record.reliance;
+    source = "local-override";
+  } else if (cloudValue) {
+    mode = cloudValue.mode;
+    reliance = cloudValue.reliance;
+    source = "cloud-setting";
+  } else {
+    mode = "prod";
+    reliance = "cloud";
+    source = "default";
+  }
+  const semantics = deriveSemantics(mode, reliance);
+  const consoleUrl = source === "local-override" && local.record?.console_url ? local.record.console_url.replace(/\/+$/, "") : semantics.consoleUrl;
+  const staleAgainstCloud = source === "local-override" && cloudValue !== null && (cloudValue.mode !== mode || mode === "dev" && cloudValue.reliance !== semantics.reliance);
+  return {
+    mode,
+    reliance: semantics.reliance,
+    consoleUrl,
+    readTier: semantics.readTier,
+    vaultWriteMode: semantics.vaultWriteMode,
+    sources: {
+      mode: source,
+      reliance: relianceSource ?? source,
+      consoleUrl: source === "local-override" && local.record?.console_url ? "local-override" : "derived",
+      readTier: "derived",
+      vaultWriteMode: "derived"
+    },
+    localOverride: {
+      present: local.record !== null,
+      record: local.record,
+      parseError: local.parseError,
+      staleAgainstCloud
+    },
+    cloudSetting: { known: cloudKnown, value: cloudValue }
+  };
+}
+var CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, DEV_MODE_FILENAME, defaultReadFile;
+var init_dev_mode = __esm({
+  "scripts/lib/dev-mode.mjs"() {
+    "use strict";
+    init_credentials();
+    CLOUD_CONSOLE_URL = "https://app.heyspex.com";
+    LOCAL_CONSOLE_URL = "http://localhost:3000";
+    DEV_MODE_FILENAME = "dev-mode.json";
+    defaultReadFile = (p) => readFileSync6(p, "utf8");
+  }
+});
 
 // spex-console/bin/hs-claim.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import process2 from "node:process";
+import { readFileSync as readFileSync8 } from "node:fs";
+import process3 from "node:process";
 
 // spex-console/src/lib/work-stages.ts
 var WORK_STAGES = [
@@ -46,12 +327,356 @@ function resolveAgentIdentity(argAgent, argSession) {
 }
 
 // spex-console/src/lib/cli/control-shared.ts
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import path from "node:path";
+
+// scripts/lib/hs-command.mjs
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var HS_BIN_NAME = "hs";
+var HS_DISPATCHER_PATH = (() => {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(dirname(dirname(here)), "bin", "hs.mjs");
+  } catch {
+    return null;
+  }
+})();
+function shellQuote(p) {
+  return /[\\\s]/.test(p) ? `"${p}"` : p;
+}
+var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER_PATH)}` : HS_BIN_NAME;
+function candidateNames(name, env) {
+  if (process.platform !== "win32") return [name];
+  const pathext = (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim().toLowerCase()).filter(Boolean);
+  const extensions = [.../* @__PURE__ */ new Set([...pathext, ".ps1"])];
+  return [name, ...extensions.map((ext) => name + ext)];
+}
+function findOnPath(name, { env = process.env, exists = existsSync } = {}) {
+  try {
+    const raw = env.PATH ?? env.Path ?? env.path ?? "";
+    for (const dir of String(raw).split(delimiter)) {
+      const trimmed = dir.trim().replace(/^"(.*)"$/, "$1");
+      if (!trimmed) continue;
+      for (const candidate of candidateNames(name, env)) {
+        const full = join(trimmed, candidate);
+        try {
+          if (exists(full)) return full;
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+var cached = null;
+var HS_ON_PATH_OVERRIDE_ENV = "HEYSPEX_HS_ON_PATH";
+function onPathOverride(env) {
+  const raw = String(env?.[HS_ON_PATH_OVERRIDE_ENV] ?? "");
+  if (raw === "1") return true;
+  if (raw === "0") return false;
+  return void 0;
+}
+function describeHsCommand({ env, exists, useCache = true } = {}) {
+  const injected = env !== void 0 || exists !== void 0;
+  const effectiveEnv = env ?? process.env;
+  const override = onPathOverride(effectiveEnv);
+  if (override !== void 0) {
+    return {
+      onPath: override,
+      prefix: override ? HS_BIN_NAME : HS_DISPATCHER_PREFIX,
+      resolvedPath: null,
+      dispatcherPath: HS_DISPATCHER_PATH
+    };
+  }
+  if (useCache && !injected && cached) return cached;
+  const resolvedPath = findOnPath(HS_BIN_NAME, {
+    env: env ?? process.env,
+    exists: exists ?? existsSync
+  });
+  const answer = {
+    onPath: resolvedPath !== null,
+    prefix: resolvedPath !== null ? HS_BIN_NAME : HS_DISPATCHER_PREFIX,
+    resolvedPath,
+    dispatcherPath: HS_DISPATCHER_PATH
+  };
+  if (useCache && !injected) cached = answer;
+  return answer;
+}
+function hsCommand(args = "", options = {}) {
+  let prefix = HS_DISPATCHER_PREFIX;
+  try {
+    prefix = describeHsCommand(options).prefix;
+  } catch {
+  }
+  const tail = String(args ?? "").trim();
+  return tail ? `${prefix} ${tail}` : prefix;
+}
+
+// vendor/heyspex-mcp/console-fetch.mjs
+init_credentials();
+import { readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join5 } from "node:path";
+
+// vendor/heyspex-mcp/session-owner.mjs
+init_credentials();
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir2(), readFile } = {}) {
+  const fromEnv = typeof env?.HS_ACCOUNT_ID === "string" ? env.HS_ACCOUNT_ID.trim() : "";
+  if (fromEnv) return fromEnv;
+  return readCurrentAccountId({ homeDir, readFile });
+}
+
+// vendor/heyspex-mcp/vault-less-endpoints.mjs
+var 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"
+]);
+function pathnameOf(path2) {
+  const raw = String(path2 ?? "").split("?")[0].split("#")[0];
+  const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
+  return noTrailing || "/";
+}
+function isVaultLessEndpoint(method, path2) {
+  const m = String(method || "GET").toUpperCase();
+  const pathname = pathnameOf(path2);
+  return VAULT_LESS_ENDPOINTS.some((row) => {
+    const [rowMethod, rowPath] = row.split(" ");
+    return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
+  });
+}
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir3, tmpdir } from "node:os";
+import { dirname as dirname3, join as join4, resolve as resolve2 } from "node:path";
+
+// vendor/heyspex-mcp/console-fetch.mjs
+var VAULT_NOT_REGISTERED = "VAULT_NOT_REGISTERED";
+var VaultNotRegisteredError = class extends Error {
+  /**
+   * @param {string | null | undefined} repoRootAbs the root the resolver settled on
+   * @param {string | null | undefined} source the resolver tier that produced it
+   * @param {{ reason?: 'unregistered' | 'legacy-id', legacyId?: string | null }} [detail]
+   */
+  constructor(repoRootAbs, source, { reason = "unregistered", legacyId = null } = {}) {
+    const root = typeof repoRootAbs === "string" && repoRootAbs.trim() ? repoRootAbs.trim() : null;
+    const where = root ? ` (${root})` : "";
+    const why = reason === "legacy-id" ? `This repo${where} is registered on this machine under a legacy id (\`${legacyId}\`), not the vault id the console knows, and its heyspex.yaml carries no \`vault_id\` to stand in for it, ` : `This repo${where} is not connected to a HeySpex vault on this machine (\`hs connect\` has not registered it), `;
+    super(
+      why + `so the console call was refused before it was sent. Run \`${hsCommand("connect")}\`${root ? ` in ${root}` : ""} to ${reason === "legacy-id" ? "re-register" : "connect"} it, then try again. Nothing was sent.`
+    );
+    this.name = "VaultNotRegisteredError";
+    this.code = VAULT_NOT_REGISTERED;
+    this.reason = reason;
+    this.repoRootAbs = root;
+    this.source = typeof source === "string" ? source : null;
+    this.legacyId = legacyId;
+  }
+};
+var CLOUD_VAULT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isCloudVaultId(value) {
+  return typeof value === "string" && CLOUD_VAULT_ID_RE.test(value.trim());
+}
+var MARKER_VAULT_ID_RE = /^vault_id:[ \t]*["']?([^"'\r\n#]+)/m;
+function readMarkerVaultId(repoRootAbs, { readFile } = {}) {
+  if (typeof repoRootAbs !== "string" || !repoRootAbs.trim()) return null;
+  const read = readFile ?? ((p) => readFileSync4(p, "utf8"));
+  try {
+    const raw = read(join5(repoRootAbs, "heyspex.yaml"));
+    const value = String(raw ?? "").match(MARKER_VAULT_ID_RE)?.[1]?.trim() ?? "";
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+function cloudVaultIdFor(resolved, { readMarkerVaultId: readMarker = readMarkerVaultId } = {}) {
+  const rowId = resolved.vaultId.trim();
+  if (isCloudVaultId(rowId)) return rowId;
+  const marker = readMarker(resolved.repoRootAbs);
+  if (isCloudVaultId(marker)) return marker.trim();
+  throw new VaultNotRegisteredError(resolved.repoRootAbs, resolved.source, { reason: "legacy-id", legacyId: rowId });
+}
+var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
+
+// spex-console/src/lib/cli/control-shared.ts
+init_credentials();
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname4, join as join6, resolve as resolve3 } from "node:path";
+
+// spex-console/src/lib/vault-registry/types.ts
+var LEGACY_REGISTRY_ACCOUNT_ID = "legacy";
+var VAULT_REGISTRY_SCHEMA_VERSION = 2;
+function emptyVaultRegistry() {
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    current_account_id: null,
+    accounts: {},
+    workspaces: [],
+    vaults: []
+  };
+}
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+function vaultRegistryDir(opts = {}) {
+  return opts.registryDir ?? join6(homedir5(), ".heyspex");
+}
+function vaultRegistryFilePath(opts = {}) {
+  return join6(vaultRegistryDir(opts), "registry.json");
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function accountOf(o) {
+  return isNonEmptyString(o.account_id) ? o.account_id : LEGACY_REGISTRY_ACCOUNT_ID;
+}
+function normalizeWorkspace(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.created_at)) return null;
+  const record = {
+    id: o.id,
+    display_name: o.display_name,
+    created_at: o.created_at,
+    archived: o.archived === true,
+    account_id: accountOf(o)
+  };
+  if (isNonEmptyString(o.github_org)) record.github_org = o.github_org;
+  return record;
+}
+function normalizeVault(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.workspace_id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.repo_root_abs)) return null;
+  if (typeof o.schema_version !== "number") return null;
+  if (!isNonEmptyString(o.registered_at)) return null;
+  const record = {
+    id: o.id,
+    workspace_id: o.workspace_id,
+    display_name: o.display_name,
+    repo_root_abs: o.repo_root_abs,
+    schema_version: o.schema_version,
+    registered_at: o.registered_at,
+    archived: o.archived === true,
+    account_id: accountOf(o)
+  };
+  if (isNonEmptyString(o.github_remote)) record.github_remote = o.github_remote;
+  return record;
+}
+function normalizeStoredPointers(raw) {
+  const o = raw && typeof raw === "object" ? raw : {};
+  const out = {};
+  for (const field of ["active_vault_id", "active_workspace_id"]) {
+    const v = o[field];
+    if (v === null || isNonEmptyString(v)) out[field] = v;
+  }
+  return out;
+}
+function normalizePointers(raw) {
+  const o = raw && typeof raw === "object" ? raw : {};
+  return {
+    active_vault_id: isNonEmptyString(o.active_vault_id) ? o.active_vault_id : null,
+    active_workspace_id: isNonEmptyString(o.active_workspace_id) ? o.active_workspace_id : null
+  };
+}
+function registryFileSchemaOf(json) {
+  if (!json || typeof json !== "object" || Array.isArray(json)) return null;
+  return json.schema_version === 2 ? 2 : 1;
+}
+function parseVaultRegistryFile(json) {
+  const schema = registryFileSchemaOf(json);
+  if (schema === null) return emptyVaultRegistry();
+  const o = json;
+  const workspacesRaw = Array.isArray(o.workspaces) ? o.workspaces : [];
+  const workspaces = workspacesRaw.map(normalizeWorkspace).filter((w) => w !== null);
+  const vaultsRaw = Array.isArray(o.vaults) ? o.vaults : [];
+  const vaults = vaultsRaw.map(normalizeVault).filter((v) => v !== null);
+  if (schema === 1) {
+    const legacy = normalizePointers(o);
+    const hasLegacyState = legacy.active_vault_id !== null || legacy.active_workspace_id !== null || workspaces.length > 0 || vaults.length > 0;
+    return {
+      schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+      current_account_id: hasLegacyState ? LEGACY_REGISTRY_ACCOUNT_ID : null,
+      accounts: hasLegacyState ? { [LEGACY_REGISTRY_ACCOUNT_ID]: legacy } : {},
+      workspaces,
+      vaults
+    };
+  }
+  const accounts = {};
+  if (o.accounts && typeof o.accounts === "object" && !Array.isArray(o.accounts)) {
+    for (const [id, pointers] of Object.entries(o.accounts)) {
+      if (isNonEmptyString(id)) accounts[id] = normalizeStoredPointers(pointers);
+    }
+  }
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    current_account_id: isNonEmptyString(o.current_account_id) ? o.current_account_id : null,
+    accounts,
+    workspaces,
+    vaults
+  };
+}
+function readRegistryJson(opts) {
+  const filePath = vaultRegistryFilePath(opts);
+  if (!existsSync3(filePath)) return { kind: "missing" };
+  try {
+    const raw = readFileSync5(filePath, "utf8");
+    const json = JSON.parse(raw);
+    if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
+    return { kind: "ok", raw, json };
+  } catch {
+    return { kind: "unreadable" };
+  }
+}
+function inspectVaultRegistry(opts = {}) {
+  const read = readRegistryJson(opts);
+  if (read.kind !== "ok") {
+    return {
+      registry: emptyVaultRegistry(),
+      file_schema_version: null,
+      registry_unreadable: read.kind === "unreadable"
+    };
+  }
+  return {
+    registry: parseVaultRegistryFile(read.json),
+    file_schema_version: registryFileSchemaOf(read.json),
+    registry_unreadable: false
+  };
+}
+function loadVaultRegistry(opts = {}) {
+  return inspectVaultRegistry(opts).registry;
+}
+
+// spex-console/src/lib/cli/control-shared.ts
 var EXIT = {
   /** Success. */
   OK: 0,
+  /**
+   * A read-only CHECK ran correctly and its answer is "no" — `hs connect
+   * --check` on an unconnected repo. Distinct from {@link EXIT.USAGE} so a
+   * script can tell "you typed the command wrong" from "the command worked,
+   * the repo is not connected". Both were `1` until 2026-09-18, which made
+   * `--check` unusable in a conditional: every caller had to parse stdout to
+   * find out which of the two had happened.
+   */
+  CHECK_FAILED: 2,
   /** Usage error — unknown subcommand/flag, or a missing required argument. */
   USAGE: 1,
   /** Claim race lost — the spec is already claimed by another agent (409). */
@@ -73,31 +698,94 @@ var EXIT = {
    * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
    * malformed command.
    */
-  FORBIDDEN: 15
+  FORBIDDEN: 15,
+  /**
+   * A CLOUD write refused because no account id could be resolved (no
+   * `HS_ACCOUNT_ID` env var, no `account_id:` in `~/.heyspex/config.yaml`) --
+   * `resolveCloudAccountIdOrRefuse` in `vault-workspace-shared.ts`
+   * ([[HS-YU1S-UAGY-TASK-cloud-writes-refuse-without-a]]). Distinct from
+   * `FORBIDDEN` -- this is "not signed in at all", not "signed in but not
+   * authorized for this override".
+   */
+  SIGN_IN_REQUIRED: 16,
+  /**
+   * Signed in, but the account a repo would be attached to was not confirmed:
+   * a non-interactive install/connect with no matching `--account` / `--yes`,
+   * an `account_id` that disagrees with the bearer's user, or the human
+   * aborting the identity prompt (`install-identity.ts`,
+   * [[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]]).
+   */
+  IDENTITY_UNCONFIRMED: 17,
+  /**
+   * The repo this verb runs in is not registered on this machine (no
+   * `~/.heyspex/registry.json` row for its root, or a legacy slug row with no
+   * cloud `vault_id` in its heyspex.yaml), so the call was refused LOCALLY —
+   * nothing was sent. Names `hs connect`
+   * ([[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]]).
+   */
+  VAULT_NOT_REGISTERED: 18,
+  /**
+   * The local half of a setup verb (`hs connect`, `hs vault *`, `hs workspace
+   * *`) was written but the CLOUD half did not land -- the console refused
+   * it or was never reached. The verb's receipt names the failed half and the
+   * exact command to re-run
+   * ([[HS-STCY-WW9R-TASK-add-a-shared-receipt-that-reads-back]], invariant 6).
+   * Distinct from {@link EXIT.WRITE_FAILED} so a script can tell "re-run to
+   * sync the cloud" from a generic server failure.
+   */
+  CLOUD_WRITE_FAILED: 19,
+  /**
+   * The repo's committed `heyspex.yaml` records `account: <A>` but the machine
+   * is signed in as another account, so `hs connect` refused and wrote
+   * nothing (marker, registry, cloud). Repair: `hs login --switch-account <A>`
+   * ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]], invariant 4).
+   */
+  ACCOUNT_MISMATCH: 20,
+  /**
+   * Both sides of a setup verb's receipt were read back and still DISAGREE
+   * after a short bounded re-read of the cloud side (a briefly stale read is
+   * absorbed first). The write may well have landed; what the verb cannot
+   * claim is that this machine and the console now say the same thing. The
+   * receipt prints the diffs and the command to re-run
+   * ([[HS-FKSR-WW9R-TASK-make-one-hs-connect-run-create-a-cloud]], invariant 6).
+   * Distinct from {@link EXIT.CLOUD_WRITE_FAILED} (a write that did not land).
+   */
+  RECEIPT_DISAGREE: 21
 };
-function readPairedToken() {
-  try {
-    const raw = readFileSync(join(homedir(), ".heyspex", "credentials.yaml"), "utf-8");
-    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
-    return match?.[1];
-  } catch {
-    return void 0;
-  }
+var VAULT_ID_HEADER = "x-heyspex-vault-id";
+var ACCOUNT_ID_HEADER = "x-heyspex-account-id";
+function readPairedBearer(opts = {}) {
+  return readBearer(opts);
 }
-function bearerHeaderFor(consoleUrl) {
+function readPairedToken(opts = {}) {
+  return readPairedBearer(opts).token ?? void 0;
+}
+function bearerHeaderFor(consoleUrl, opts = {}) {
   try {
     const host = new URL(consoleUrl).hostname;
     if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1") {
       return {};
     }
-    const token = readPairedToken();
+    const token = readPairedToken(opts);
     return token ? { authorization: `Bearer ${token}` } : {};
   } catch {
     return {};
   }
 }
+function scopeHeadersFor(scope, method, path2) {
+  if (scope === "none") {
+    if (!isVaultLessEndpoint(method, path2)) {
+      throw new Error(
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path2} is vault-scoped and must name { accountId, vaultId }.`
+      );
+    }
+    return {};
+  }
+  return { [VAULT_ID_HEADER]: scope.vaultId, [ACCOUNT_ID_HEADER]: scope.accountId };
+}
 async function controlRequest(deps, req) {
   const url = `${deps.consoleUrl}${req.path}`;
+  const scopeHeaders = scopeHeadersFor(deps.scope, req.method, req.path);
   let res;
   try {
     res = await deps.fetchImpl(url, {
@@ -108,7 +796,10 @@ async function controlRequest(deps, req) {
         // authenticates every control call; loopback never asked, so the header
         // is attached only when the target is non-loopback and a paired token
         // exists. Same `hsmcp_` bearer the MCP server presents.
-        ...bearerHeaderFor(deps.consoleUrl)
+        ...bearerHeaderFor(deps.consoleUrl),
+        // Invariant 2: name the vault and the account on every call, or the
+        // console serves whatever its leftover pointer says.
+        ...scopeHeaders
       },
       ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {}
     });
@@ -178,6 +869,72 @@ function parseTtl(token) {
   }
   return { value: n };
 }
+function normalizeRoot(p) {
+  return path.resolve(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+function resolveControlScope(input) {
+  const target = normalizeRoot(input.vaultRoot);
+  const row = input.vaults.find((v) => normalizeRoot(v.repo_root_abs) === target) ?? null;
+  if (!row) {
+    return {
+      ok: false,
+      error: {
+        code: EXIT.VAULT_NOT_REGISTERED,
+        message: `this repo (${input.vaultRoot}) is not connected to a HeySpex vault on this machine (\`hs connect\` has not registered it), so the call was refused before it was sent. Run \`${hsCommand("connect")}\` in ${input.vaultRoot}, then try again.`,
+        payload: {
+          ok: false,
+          error: "vault_not_registered",
+          reason: "unregistered",
+          vault_root: input.vaultRoot
+        },
+        isError: true
+      }
+    };
+  }
+  let vaultId;
+  try {
+    vaultId = cloudVaultIdFor(
+      { vaultId: row.id, repoRootAbs: row.repo_root_abs, source: "registry" },
+      input.readMarkerVaultId ? { readMarkerVaultId: input.readMarkerVaultId } : {}
+    );
+  } catch (err) {
+    if (!(err instanceof VaultNotRegisteredError)) throw err;
+    const refused = err;
+    return {
+      ok: false,
+      error: {
+        code: EXIT.VAULT_NOT_REGISTERED,
+        message: refused.message,
+        payload: {
+          ok: false,
+          error: "vault_not_registered",
+          reason: refused.reason ?? "legacy-id",
+          vault_root: input.vaultRoot,
+          legacy_id: refused.legacyId ?? row.id
+        },
+        isError: true
+      }
+    };
+  }
+  const accountId = input.accountId?.trim() ?? "";
+  if (!accountId) {
+    return {
+      ok: false,
+      error: {
+        code: EXIT.SIGN_IN_REQUIRED,
+        message: `no HeySpex account is configured on this machine (\`hs login\` has not been run), so the call was refused before it was sent. Run \`${hsCommand("login")}\` on this machine, then try again.`,
+        payload: { ok: false, error: "sign_in_required", vault_root: input.vaultRoot },
+        isError: true
+      }
+    };
+  }
+  return { ok: true, scope: { accountId, vaultId } };
+}
+function resolveControlScopeFromMachine(vaultRoot, opts = {}) {
+  const registry = loadVaultRegistry(opts.registry);
+  const accountId = resolveSessionOwnerUncached({ env: opts.env, homeDir: opts.homeDir });
+  return resolveControlScope({ vaultRoot, accountId, vaults: registry.vaults });
+}
 
 // spex-console/src/lib/cli/claim.ts
 function parseClaimArgs(argv) {
@@ -441,41 +1198,120 @@ var HELP = [
   "            12 console-unreachable \xB7 13 server-error \xB7 14 neon-required"
 ].join("\n");
 
-// spex-console/src/lib/cli/defer.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
 // scripts/lib/console-url-resolver.mjs
-import { readFileSync as readFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
-var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
-
-// spex-console/src/lib/cli/defer.ts
-function resolveSpexConsoleUrl(vaultRoot, readDiscovery2, opts = {}) {
-  const env = opts.env ?? process.env;
-  const raw = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
-  if (raw && raw.length > 0) return raw.replace(/\/+$/, "");
+init_dev_mode();
+import { readFileSync as readFileSync7 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join8 } from "node:path";
+var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+function isLoopbackConsoleUrl(url) {
+  if (typeof url !== "string" || !url) return false;
+  try {
+    return LOOPBACK_HOSTS.has(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+var staleLoopbackCredentialsWarned = false;
+function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
+  if (staleLoopbackCredentialsWarned) return;
+  staleLoopbackCredentialsWarned = true;
+  try {
+    log(
+      `[heyspex] ignoring console_url ${credentialsUrl} from ~/.heyspex/credentials.yaml: the resolved reliance is cloud, and a loopback console cannot serve it \u2014 using ${derivedUrl} (set HEYSPEX_CONSOLE_URL to override explicitly, or run \`hs dev mode:local\` to go back to a local console).
+`
+    );
+  } catch {
+  }
+}
+function readCredentialsConsoleUrl({ homeDir = homedir7(), readFile = defaultReadFile2 } = {}) {
   try {
-    const homeDir = opts.homeDir ?? os.homedir();
-    const readFile = opts.readFile ?? ((p) => readFileSync3(p, "utf-8"));
-    const credentials = readFile(path.join(homeDir, ".heyspex", "credentials.yaml"));
-    const match = credentials.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const raw = readFile(join8(homeDir, ".heyspex", "credentials.yaml"));
+    const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
     const value = match?.[1]?.trim();
-    if (value && value.length > 0) return value.replace(/\/+$/, "");
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
   } catch {
+    return null;
   }
-  for (const name of ["console-url", "cockpit-url"]) {
-    try {
-      const discovery = readDiscovery2(`${vaultRoot}/.heyspex/${name}`);
-      if (discovery && discovery.trim().length > 0) {
-        return discovery.trim().replace(/\/+$/, "");
-      }
-    } catch {
+}
+function defaultReadFile2(p) {
+  return readFileSync7(p, "utf8");
+}
+function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery: readDiscovery2 = defaultReadFile2 } = {}) {
+  if (!repoRoot) return null;
+  try {
+    const discovery = String(readDiscovery2(join8(repoRoot, ".heyspex", "console-url")) ?? "").trim();
+    if (discovery.length > 0) return trimTrailingSlash(discovery);
+  } catch {
+  }
+  return null;
+}
+var ConsoleUrlUnresolvedError = class extends Error {
+  constructor() {
+    super(
+      "resolveConsoleUrl: local reliance with no HEYSPEX_CONSOLE_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the localhost:3000 default in strict mode."
+    );
+    this.name = "ConsoleUrlUnresolvedError";
+  }
+};
+function resolveModeEnvelope({ env, homeDir }) {
+  try {
+    const resolved = resolveDevMode({ env, homeDir });
+    return {
+      reliance: resolved.reliance === "cloud" ? "cloud" : "local",
+      consoleUrl: resolved.consoleUrl || DEFAULT_CONSOLE_URL
+    };
+  } catch {
+    return { reliance: "local", consoleUrl: DEFAULT_CONSOLE_URL };
+  }
+}
+function resolveConsoleUrl({
+  repoRoot,
+  env = process.env,
+  homeDir = homedir7(),
+  strict = false,
+  devMode,
+  log = (line) => process.stderr.write(line),
+  readFile = defaultReadFile2,
+  readDiscovery: readDiscovery2 = defaultReadFile2
+} = {}) {
+  const envUrl = env.HEYSPEX_CONSOLE_URL?.trim();
+  if (envUrl) return trimTrailingSlash(envUrl);
+  const mode = devMode ?? resolveModeEnvelope({ env, homeDir });
+  const cloud = mode.reliance === "cloud";
+  const derivedUrl = trimTrailingSlash(
+    cloud && isLoopbackConsoleUrl(mode.consoleUrl) ? CLOUD_CONSOLE_URL : mode.consoleUrl || DEFAULT_CONSOLE_URL
+  );
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir, readFile });
+  if (credentialsUrl) {
+    if (cloud && isLoopbackConsoleUrl(credentialsUrl)) {
+      warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log });
+    } else {
+      return credentialsUrl;
     }
   }
-  return DEFAULT_CONSOLE_URL;
+  if (!cloud) {
+    const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery: readDiscovery2 });
+    if (discoveryUrl) return discoveryUrl;
+    if (strict) throw new ConsoleUrlUnresolvedError();
+  }
+  return derivedUrl;
+}
+
+// spex-console/src/lib/cli/defer.ts
+function resolveSpexConsoleUrl(vaultRoot, readDiscovery2, opts = {}) {
+  return resolveConsoleUrl({
+    repoRoot: vaultRoot,
+    env: opts.env,
+    homeDir: opts.homeDir,
+    readFile: opts.readFile,
+    readDiscovery: readDiscovery2,
+    log: opts.log
+  });
 }
 var HELP2 = [
   "Usage:",
@@ -499,43 +1335,80 @@ var HELP2 = [
   "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 write-failed"
 ].join("\n");
 
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
 // spex-console/bin/hs-claim.ts
 function readDiscovery(p) {
   try {
-    return readFileSync4(p, "utf-8");
+    return readFileSync8(p, "utf-8");
   } catch {
     return null;
   }
 }
 async function main() {
-  const vaultRoot = process2.env.HS_VAULT_ROOT;
+  const vaultRoot = process3.env.HS_VAULT_ROOT;
   if (!vaultRoot) {
-    process2.stderr.write(
+    process3.stderr.write(
       "hs claim: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
     );
-    process2.exit(EXIT.USAGE);
+    process3.exitCode = EXIT.USAGE;
+    return;
   }
-  const parsed = parseClaimArgs(process2.argv.slice(3));
+  const parsed = parseClaimArgs(process3.argv.slice(3));
   if (parsed.help) {
-    process2.stdout.write(`${HELP}
+    process3.stdout.write(`${HELP}
 `);
-    process2.exit(EXIT.OK);
+    process3.exitCode = EXIT.OK;
+    return;
   }
   if (parsed.error) {
-    process2.stderr.write(`hs claim: ${parsed.error.message}
+    process3.stderr.write(`hs claim: ${parsed.error.message}
 `);
-    process2.exit(parsed.error.code);
+    process3.exitCode = parsed.error.code;
+    return;
   }
   const consoleUrl = resolveSpexConsoleUrl(vaultRoot, readDiscovery);
-  const result = await runClaim(parsed.args, { fetchImpl: fetch, consoleUrl });
-  const sink = result.isError ? process2.stderr : process2.stdout;
+  const scoped = resolveControlScopeFromMachine(vaultRoot);
+  if (!scoped.ok) {
+    process3.stderr.write(`hs claim: ${scoped.error.message}
+`);
+    process3.exitCode = scoped.error.code;
+    return;
+  }
+  const result = await runClaim(parsed.args, {
+    fetchImpl: fetch,
+    consoleUrl,
+    scope: scoped.scope
+  });
+  const sink = result.isError ? process3.stderr : process3.stdout;
   sink.write(`${parsed.args.json ? JSON.stringify(result.payload) : result.message}
 `);
-  process2.exit(result.code);
+  process3.exitCode = result.code;
 }
-main().catch((err) => {
-  const message = err instanceof Error ? err.message : String(err);
-  process2.stderr.write(`hs claim: unhandled: ${message}
-`);
-  process2.exit(EXIT.WRITE_FAILED);
-});
+runEntry("hs claim", main, { fallbackCode: EXIT.WRITE_FAILED });