heyspex 0.2.5 → 0.2.7

package/dist/cli/hs-pin.mjs

@@ -0,0 +1,1336 @@
+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;
+};
+
+// scripts/lib/heyspex-home.mjs
+import { homedir } from "node:os";
+function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+var init_heyspex_home = __esm({
+  "scripts/lib/heyspex-home.mjs"() {
+    "use strict";
+  }
+});
+
+// vendor/heyspex-mcp/credentials.mjs
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import os, { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+function credentialsFilePath(homeDir = heyspexHome()) {
+  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, path3) {
+  try {
+    const raw = read(path3);
+    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 = heyspexHome(), 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 = heyspexHome(), 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";
+    init_heyspex_home();
+    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 mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { join as join8 } from "node:path";
+function devModeFilePath(homeDir = heyspexHome()) {
+  return join8(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 = heyspexHome(), 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 overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
+function resolveDevMode({
+  env = process.env,
+  homeDir = heyspexHome(),
+  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);
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
+  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,
+      cloudCheck
+    },
+    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_heyspex_home();
+    init_credentials();
+    CLOUD_CONSOLE_URL = "https://app.heyspex.com";
+    LOCAL_CONSOLE_URL = "http://localhost:3000";
+    DEV_MODE_FILENAME = "dev-mode.json";
+    defaultReadFile = (p) => readFileSync8(p, "utf8");
+  }
+});
+
+// spex-console/bin/hs-pin.ts
+import { readFileSync as readFileSync10 } from "node:fs";
+import process3 from "node:process";
+
+// spex-console/src/lib/cli/control-shared.ts
+import path2 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_heyspex_home();
+init_credentials();
+import { readFileSync as readFileSync6 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join6 } from "node:path";
+
+// vendor/heyspex-mcp/session-owner.mjs
+init_heyspex_home();
+init_credentials();
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), 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(path3) {
+  const raw = String(path3 ?? "").split("?")[0].split("#")[0];
+  const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
+  return noTrailing || "/";
+}
+function isVaultLessEndpoint(method, path3) {
+  const m = String(method || "GET").toUpperCase();
+  const pathname = pathnameOf(path3);
+  return VAULT_LESS_ENDPOINTS.some((row) => {
+    const [rowMethod, rowPath] = row.split(" ");
+    return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
+  });
+}
+
+// vendor/heyspex-mcp/write-outbox.mjs
+import {
+  readdirSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2,
+  mkdirSync as mkdirSync2,
+  existsSync as existsSync2,
+  renameSync as renameSync2,
+  rmSync
+} from "node:fs";
+import { basename, join as join4, isAbsolute as isAbsolute2 } from "node:path";
+
+// scripts/lib/shared-path-helpers.mjs
+import { realpathSync } from "node:fs";
+import { isAbsolute, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+init_heyspex_home();
+import { existsSync as existsSync4, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { homedir as homedir5, tmpdir } from "node:os";
+
+// vendor/heyspex-mcp/usable-dir-env.mjs
+import { statSync } from "node:fs";
+import { isAbsolute as isAbsolute3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { basename as basename2, dirname as dirname3, join as join5, resolve as resolve3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-binding.mjs
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  realpathSync as realpathSync2,
+  renameSync as renameSync3,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import path 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) => readFileSync6(p, "utf8"));
+  try {
+    const raw = read(join6(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 existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname4, join as join7, resolve as resolve4 } from "node:path";
+
+// spex-console/src/lib/heyspex-home.ts
+import { homedir as homedir7 } from "node:os";
+function heyspexHome2(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir7();
+}
+
+// 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 ?? join7(heyspexHome2(), ".heyspex");
+}
+function vaultRegistryFilePath(opts = {}) {
+  return join7(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 (!existsSync5(filePath)) return { kind: "missing" };
+  try {
+    const raw = readFileSync7(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). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  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
+};
+var VAULT_ID_HEADER = "x-heyspex-vault-id";
+var ACCOUNT_ID_HEADER = "x-heyspex-account-id";
+function readPairedBearer(opts = {}) {
+  return readBearer(opts);
+}
+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(opts);
+    return token ? { authorization: `Bearer ${token}` } : {};
+  } catch {
+    return {};
+  }
+}
+function scopeHeadersFor(scope, method, path3) {
+  if (scope === "none") {
+    if (!isVaultLessEndpoint(method, path3)) {
+      throw new Error(
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path3} 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, {
+      method: req.method,
+      headers: {
+        "content-type": "application/json",
+        // A remote console (cloud vault write mode, [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]])
+        // 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),
+        // 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) } : {}
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: {
+        code: EXIT.CONSOLE_UNREACHABLE,
+        message: `could not reach console at ${deps.consoleUrl}: ${message}
+  Start the dev server or set HEYSPEX_CONSOLE_URL.`,
+        payload: {
+          ok: false,
+          error: "console_unreachable",
+          url: deps.consoleUrl,
+          message
+        },
+        isError: true
+      }
+    };
+  }
+  let parsed = null;
+  try {
+    parsed = await res.json();
+  } catch {
+  }
+  if (res.status === 402) {
+    return {
+      ok: false,
+      error: {
+        code: EXIT.NEON_REQUIRED,
+        message: "this command requires the Neon control plane, which is not configured (console returned 402).",
+        payload: {
+          ok: false,
+          error: "neon_required",
+          status: 402,
+          console_response: parsed
+        },
+        isError: true
+      }
+    };
+  }
+  return { ok: true, status: res.status, body: parsed };
+}
+function envelopeMessage(body) {
+  if (body && typeof body === "object" && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string") return m;
+  }
+  return "";
+}
+function writeFailed(status, body) {
+  const detail = envelopeMessage(body);
+  return {
+    code: EXIT.WRITE_FAILED,
+    message: `console returned ${status}${detail ? `: ${detail}` : ""}`,
+    payload: { ok: false, error: "write_failed", status, console_response: body },
+    isError: true
+  };
+}
+function parseTtl(token) {
+  const trimmed = token.trim().toLowerCase();
+  if (trimmed === "none" || trimmed === "null") return { value: null };
+  const n = Number(trimmed);
+  if (!Number.isFinite(n) || n < 0) {
+    return { error: `--ttl must be a non-negative number of ms, or "none"` };
+  }
+  return { value: n };
+}
+function normalizeRoot(p) {
+  return path2.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 });
+}
+
+// scripts/lib/console-url-resolver.mjs
+init_heyspex_home();
+init_dev_mode();
+import { readFileSync as readFileSync9 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
+import { join as join9 } 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 = heyspexHome(), readFile = defaultReadFile2 } = {}) {
+  try {
+    const raw = readFile(join9(homeDir, ".heyspex", "credentials.yaml"));
+    const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
+  } catch {
+    return null;
+  }
+}
+function defaultReadFile2(p) {
+  return readFileSync9(p, "utf8");
+}
+function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery: readDiscovery2 = defaultReadFile2 } = {}) {
+  if (!repoRoot) return null;
+  try {
+    const discovery = String(readDiscovery2(join9(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 = heyspexHome(),
+  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;
+    }
+  }
+  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 HELP = [
+  "Usage:",
+  "  hs defer <spec-id> [--until <when>] [--json] [--no-daemon]",
+  "  hs undefer <spec-id> [--json] [--no-daemon]",
+  "",
+  "Time-shift a spec via its `defer_until` frontmatter field. A deferred spec is",
+  "scheduler-invisible until the date passes, then auto-revives.",
+  "",
+  "Arguments:",
+  "  <spec-id>        The spec to defer/undefer (e.g. HS-TASK-EWL5).",
+  "",
+  "Flags:",
+  "  --until <when>   ISO date, or relative offset +Nd / +Nw / +Nm / +Ny.",
+  "                   Defaults to +1y (matches the console Defer button).",
+  "                   Ignored by `undefer` (which always clears the field).",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --no-daemon      Write straight to the vault (no console needed; CI path).",
+  "  --help, -h       Show this help.",
+  "",
+  "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/src/lib/cli/agent-identity.ts
+function resolveAgentIdentity(argAgent, argSession) {
+  const trimmedAgent = typeof argAgent === "string" ? argAgent.trim() : "";
+  const trimmedSession = typeof argSession === "string" ? argSession.trim() : "";
+  if (trimmedAgent && trimmedSession) {
+    return { agent: trimmedAgent, sessionId: trimmedSession };
+  }
+  const claudeSession = (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || "").trim();
+  if (claudeSession) {
+    return {
+      agent: trimmedAgent || "Claude Code",
+      sessionId: trimmedSession || claudeSession
+    };
+  }
+  const cursorSession = (process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION_ID || process.env.COMPOSER_SESSION_ID || "").trim();
+  if (cursorSession) {
+    return {
+      agent: trimmedAgent || "Cursor",
+      sessionId: trimmedSession || cursorSession
+    };
+  }
+  return {
+    agent: trimmedAgent || process.env.HEYSPEX_AGENT?.trim() || "External agent",
+    sessionId: trimmedSession || process.env.HEYSPEX_SESSION_ID?.trim() || process.env.HEYSPEX_AGENT_SESSION?.trim() || "local"
+  };
+}
+
+// spex-console/src/lib/cli/pin.ts
+function parsePinArgs(argv) {
+  const subRaw = argv[0];
+  if (subRaw === "--help" || subRaw === "-h" || subRaw === void 0) {
+    return { help: true };
+  }
+  if (subRaw !== "get" && subRaw !== "set" && subRaw !== "clear") {
+    return {
+      error: { code: EXIT.USAGE, message: `unknown subcommand: ${subRaw}` }
+    };
+  }
+  const sub = subRaw;
+  let specId;
+  let by;
+  let ttlMs;
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--by") {
+      by = argv[++i];
+      if (by === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--by requires a value" } };
+      }
+    } else if (arg.startsWith("--by=")) {
+      by = arg.slice("--by=".length);
+    } else if (arg === "--ttl" || arg.startsWith("--ttl=")) {
+      const token = arg === "--ttl" ? argv[++i] : arg.slice("--ttl=".length);
+      if (token === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--ttl requires a value" } };
+      }
+      const res = parseTtl(token);
+      if ("error" in res) {
+        return { error: { code: EXIT.INVALID_ARG, message: res.error } };
+      }
+      ttlMs = res.value;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (sub === "set" && specId === void 0) {
+      specId = arg;
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (sub === "set" && !specId) {
+    return { error: { code: EXIT.USAGE, message: "pin set requires a spec id" } };
+  }
+  return { args: { sub, specId, by, ttlMs, json } };
+}
+function describePin(pin) {
+  if (!pin || !pin.specId) return "(no pin)";
+  const fuse = pin.expiresAt ? ` \xB7 fuse ${pin.expiresAt}` : " \xB7 no fuse";
+  return `${pin.specId}${pin.pinnedBy ? ` (by ${pin.pinnedBy})` : ""}${fuse}`;
+}
+async function runPin(args, deps) {
+  if (args.sub === "get") {
+    const res2 = await controlRequest(deps, { method: "GET", path: "/api/control/pin" });
+    if (!res2.ok) return res2.error;
+    if (res2.status !== 200) return writeFailed(res2.status, res2.body);
+    const pin = res2.body?.pin ?? null;
+    return {
+      code: EXIT.OK,
+      message: describePin(pin),
+      payload: { ok: true, pin },
+      isError: false
+    };
+  }
+  const pinnedBy = args.by?.trim() || resolveAgentIdentity(deps.argAgent, deps.argSession).agent;
+  const body = args.sub === "set" ? {
+    spec_id: args.specId,
+    pinned_by: pinnedBy,
+    ...args.ttlMs !== void 0 ? { ttl_ms: args.ttlMs } : {}
+  } : { spec_id: null, pinned_by: pinnedBy };
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/control/pin",
+    body
+  });
+  if (!res.ok) return res.error;
+  if (res.status === 400) {
+    const detail = envelopeMessage(res.body);
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `console rejected the request${detail ? `: ${detail}` : ""}`,
+      payload: { ok: false, error: "invalid_request", message: detail },
+      isError: true
+    };
+  }
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  if (args.sub === "set") {
+    const pin = res.body?.pin ?? null;
+    return {
+      code: EXIT.OK,
+      message: `Pinned \u2192 ${describePin(pin)}`,
+      payload: { ok: true, pin },
+      isError: false
+    };
+  }
+  const cleared = Boolean(res.body?.cleared);
+  return {
+    code: EXIT.OK,
+    message: cleared ? "Pin cleared" : "No pin to clear",
+    payload: { ok: true, cleared },
+    isError: false
+  };
+}
+var HELP2 = [
+  "Usage:",
+  "  hs pin get                         Print the current pinned spec",
+  "  hs pin set <spec-id> [flags]       Pin a spec to the top (on-deck)",
+  "  hs pin clear [flags]               Clear the on-deck pin",
+  "",
+  "Wraps GET/PUT /api/control/pin (Neon control plane). Requires a",
+  "reachable console with Neon configured.",
+  "",
+  "Flags:",
+  "  --by <actor>     Who is pinning (default: detected agent identity).",
+  "  --ttl <ms|none>  Fuse in ms; `none` = no fuse (default: server 7-day fuse).",
+  "                   (set only)",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 server-error \xB7 14 neon-required"
+].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-pin.ts
+function readDiscovery(p) {
+  try {
+    return readFileSync10(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const vaultRoot = process3.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process3.stderr.write(
+      "hs pin: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process3.exitCode = EXIT.USAGE;
+    return;
+  }
+  const parsed = parsePinArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${HELP2}
+`);
+    process3.exitCode = EXIT.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs pin: ${parsed.error.message}
+`);
+    process3.exitCode = parsed.error.code;
+    return;
+  }
+  const consoleUrl = resolveSpexConsoleUrl(vaultRoot, readDiscovery);
+  const scoped = resolveControlScopeFromMachine(vaultRoot);
+  if (!scoped.ok) {
+    process3.stderr.write(`hs pin: ${scoped.error.message}
+`);
+    process3.exitCode = scoped.error.code;
+    return;
+  }
+  const result = await runPin(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}
+`);
+  process3.exitCode = result.code;
+}
+runEntry("hs pin", main, { fallbackCode: EXIT.WRITE_FAILED });