heyspex 0.2.5 → 0.2.7

package/dist/cli/hs-handoff.mjs

@@ -0,0 +1,2576 @@
+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-handoff.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 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/launch-model-aliases.ts
+var FAMILIES = [
+  { canonical: "claude-opus", family: "opus", cliNativeBareForm: "opus" },
+  { canonical: "claude-sonnet", family: "sonnet", cliNativeBareForm: "sonnet" },
+  { canonical: "claude-fable", family: "fable", cliNativeBareForm: "fable" },
+  { canonical: "claude-haiku", family: "haiku", cliNativeBareForm: null }
+];
+var ALIAS_LOOKUP = new Map(
+  FAMILIES.flatMap((entry) => [[entry.canonical, entry], [entry.family, entry]])
+);
+var MODEL_ALIAS_INPUT_FORMS = Array.from(ALIAS_LOOKUP.keys());
+function normalizeModelAlias(value) {
+  const key = value.trim().toLowerCase();
+  if (!key) return null;
+  return ALIAS_LOOKUP.get(key) ?? null;
+}
+function isModelAliasValue(value) {
+  return normalizeModelAlias(value) !== null;
+}
+function canonicalizeModelAlias(value) {
+  return normalizeModelAlias(value)?.canonical ?? null;
+}
+
+// dev-factory/model-catalog.json
+var model_catalog_default = {
+  _comment: "SINGLE SOURCE OF TRUTH for model ids, aliases, retirements, context windows, capabilities and list prices \u2014 every cloud provider the fleet can call (DeepSeek, Anthropic, OpenAI, Gemini, OpenRouter, GitHub Models) AND every local runtime (Ollama, vLLM). Hand-edit THIS file when a vendor ships or retires a model; never scatter a new literal id through the code. Readers: dev-factory/lib/model-catalog.mjs (typed accessors + self-test), dev-factory/cloud-clients.mjs (the whole PROVIDERS table is derived from `providerKeys` below), dev-factory/lib/fleet-manifest.mjs (context/VRAM/cost tables), spexharness/src/chat/compact.mjs (window sizes), spex-console/src/lib/model-catalog.ts (the console's ONLY import path \u2014 keep it so when dev-factory merges into SpexFleet one line moves), dev-factory/judge.mjs, dev-factory/router.mjs --self-test (refuses retired ids in routing-table.json), scripts/check-model-ids.mjs (refuses retired ids in live code). ROUTING (which seat runs which model, which machine hosts which local model) stays in routing-table.json \u2014 this file says what a model IS and how it is reached, not who uses it. UPGRADE RECIPE: (1) add the new id under `models` with its window/price; (2) move the old id into `aliases` (old \u2192 new) and `retired`; (3) repoint the `roles` / `providerKeys` you want moved; (4) run `node dev-factory/lib/model-catalog.mjs --self-test && node dev-factory/router.mjs --self-test && npm run check:model-ids`. `verifiedOn` per provider records when the prices were last checked against the vendor's sheet.",
+  verified: "2026-09-18",
+  cloud: {
+    deepseek: {
+      kind: "openai",
+      company: "deepseek",
+      baseUrl: "https://api.deepseek.com/v1",
+      betaBaseUrl: "https://api.deepseek.com/beta",
+      anthropicBaseUrl: "https://api.deepseek.com/anthropic",
+      userIdField: "user_id",
+      _userIdFieldNote: "Wire field for per-seat cache/scheduling isolation (DeepSeek rate-limit doc: user_id isolates KVCache and scheduling). cloud-clients.mjs sends opts.userId (defaulting to opts.seat) under this name only for providers that declare it; betaBaseUrl is used only when a caller opts into strict tool schemas (opts.strictTools) \u2014 DeepSeek's strict mode is served from /beta.",
+      keyEnv: "HEYSPEX_DEEPSEEK_API_KEY",
+      keyEnvFallback: "DEEPSEEK_API_KEY",
+      source: "https://api-docs.deepseek.com/quick_start/pricing",
+      verifiedOn: "2026-09-18",
+      peakHoursUtc: { days: [1, 2, 3, 4, 5], ranges: [["01:00", "04:00"], ["06:00", "10:00"]], note: "Off-peak rates are half of peak; all other hours are off-peak (DeepSeek pricing note 3)." },
+      roles: {
+        cheap: "deepseek-flash",
+        strong: "deepseek-v4-pro",
+        chatDefault: "deepseek-flash",
+        judge: "deepseek-flash",
+        legacyJudge: "deepseek-chat"
+      },
+      models: {
+        "deepseek-flash": {
+          displayName: "DeepSeek-V4.1-Flash",
+          released: "2026-09-10",
+          contextWindow: 1048576,
+          maxOutputTokens: 393216,
+          tier: "cheap",
+          capabilities: ["api", "metered", "tools", "thinking", "json", "vision", "strict-tools", "fim", "prefix"],
+          thinkingDefault: true,
+          effortLevels: ["low", "high", "max"],
+          concurrencyLimit: 2500,
+          pricePer1M: {
+            peak: { cacheHit: 6e-3, cacheMiss: 0.3, output: 1.2 },
+            offPeak: { cacheHit: 3e-3, cacheMiss: 0.15, output: 0.6 }
+          }
+        },
+        "deepseek-v4-pro": {
+          displayName: "DeepSeek-V4-Pro-0813",
+          released: "2026-08-13",
+          contextWindow: 1048576,
+          maxOutputTokens: 393216,
+          tier: "strong",
+          capabilities: ["api", "metered", "tools", "thinking", "json", "strict-tools", "fim", "prefix", "max_reasoning"],
+          thinkingDefault: true,
+          effortLevels: ["low", "high", "max"],
+          concurrencyLimit: 500,
+          note: "Retirement announced 2026-09-10 was reversed; service continues past 2026-09-14 at unchanged billing (pricing note 2).",
+          pricePer1M: {
+            peak: { cacheHit: 0.044, cacheMiss: 1.32, output: 3.96 },
+            offPeak: { cacheHit: 0.022, cacheMiss: 0.66, output: 1.98 }
+          }
+        }
+      },
+      aliases: {
+        "deepseek-v4-flash": "deepseek-flash",
+        "deepseek-v4-flash-vision-exp": "deepseek-flash",
+        "deepseek-chat": "deepseek-flash"
+      },
+      retired: [
+        { id: "deepseek-v4-flash", on: "2026-09-10", servedBy: "deepseek-flash", note: "Legacy name still accepted by the API and routed to V4.1 Flash at the Flash price 'temporarily'." },
+        { id: "deepseek-v4-flash-vision-exp", on: "2026-09-10", servedBy: "deepseek-flash" }
+      ],
+      unlisted: {
+        "deepseek-chat": "Not on the 2026-09-10 model sheet. Kept only as the held-constant LLM-judge alias (PROVIDERS key `deepseek`); priced as deepseek-flash. Verify with --liveness before relying on it."
+      },
+      emitAliasesAsProviderKeys: true,
+      providerKeys: {
+        "deepseek-flash": { model: "deepseek-flash" },
+        "deepseek-v4-pro": { model: "deepseek-v4-pro" },
+        deepseek: { model: "deepseek-chat", legacyAliasOf: "deepseek-flash", note: "Legacy alias, held-constant LLM judge. Sends `deepseek-chat` on the wire, priced as deepseek-flash." }
+      }
+    },
+    anthropic: {
+      kind: "anthropic",
+      company: "anthropic",
+      baseUrl: "https://api.anthropic.com/v1",
+      keyEnv: "HEYSPEX_ANTHROPIC_API_KEY",
+      source: "claude-api skill model table (cached 2026-06-24) \u2014 first-party API rates",
+      verifiedOn: "2026-06-24",
+      _note: "Anthropic models are excluded from the dev-factory council by construction and are the ceiling/reference arm in benches; the PROVIDERS keys `claude` / `claude-opus` still point at the 4.x generation on purpose (flip `providerKeys` to the 5-family when the owner rules on it \u2014 the ids and prices are already here). Claude Code CLI launches use the bare alias words in `cliAliases` (resolved by spex-console/src/lib/model-registry/launch-resolve.ts), not these ids.",
+      roles: {
+        default: "claude-opus-5",
+        strong: "claude-opus-5",
+        mid: "claude-sonnet-5",
+        cheap: "claude-haiku-4-5",
+        max: "claude-fable-5-1",
+        previousStrong: "claude-opus-4-8",
+        previousMid: "claude-sonnet-4-6"
+      },
+      cliAliases: { opus: "claude-opus-5", sonnet: "claude-sonnet-5", haiku: "claude-haiku-4-5", fable: "claude-fable-5-1" },
+      models: {
+        "claude-fable-5-1": { displayName: "Claude Fable 5.1", contextWindow: 1048576, maxOutputTokens: 131072, tier: "max", capabilities: ["api", "metered", "tools", "thinking", "vision", "json"], noTemp: true, thinkingAlwaysOn: true, pricePer1M: { input: 10, output: 50 } },
+        "claude-opus-5": { displayName: "Claude Opus 5", contextWindow: 1048576, maxOutputTokens: 131072, tier: "strong", capabilities: ["api", "metered", "tools", "thinking", "vision", "json"], noTemp: true, pricePer1M: { input: 5, output: 25 } },
+        "claude-sonnet-5": { displayName: "Claude Sonnet 5", contextWindow: 1048576, maxOutputTokens: 131072, tier: "strong", capabilities: ["api", "metered", "tools", "thinking", "vision", "json"], noTemp: true, pricePer1M: { input: 2, output: 10 } },
+        "claude-haiku-4-5": { displayName: "Claude Haiku 4.5", contextWindow: 2e5, maxOutputTokens: 65536, tier: "cheap", capabilities: ["api", "metered", "tools", "thinking", "vision"], pricePer1M: { input: 1, output: 5 } },
+        "claude-opus-4-8": { displayName: "Claude Opus 4.8", contextWindow: 1048576, maxOutputTokens: 131072, tier: "strong", capabilities: ["api", "metered", "tools", "thinking", "vision", "json"], noTemp: true, generation: "previous", pricePer1M: { input: 5, output: 25 } },
+        "claude-sonnet-4-6": { displayName: "Claude Sonnet 4.6", contextWindow: 1048576, maxOutputTokens: 131072, tier: "strong", capabilities: ["api", "metered", "tools", "thinking", "vision", "json"], generation: "previous", pricePer1M: { input: 3, output: 15 } }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: {
+        claude: { model: "claude-sonnet-4-6", note: "Generic Claude key \u2014 previous generation kept on purpose; see _note." },
+        "claude-opus": { model: "claude-opus-4-8", noTemp: true, note: "Opus key \u2014 previous generation kept on purpose. Old table priced this at $15/$75; the sheet says $5/$25." }
+      }
+    },
+    openai: {
+      kind: "openai",
+      company: "openai",
+      baseUrl: "https://api.openai.com/v1",
+      keyEnv: "HEYSPEX_OPENAI_API_KEY",
+      source: "carried over from cloud-clients.mjs PROVIDERS (no vendor re-verification in this pass)",
+      verifiedOn: "2026-06-28",
+      roles: { default: "gpt-4o" },
+      models: {
+        "gpt-4o": { contextWindow: 128e3, tier: "strong", capabilities: ["api", "metered", "tools", "vision", "json"], pricePer1M: { input: 2.5, output: 10 } }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: { openai: { model: "gpt-4o" } }
+    },
+    gemini: {
+      kind: "openai",
+      company: "google",
+      baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+      keyEnv: "HEYSPEX_GEMINI_API_KEY",
+      source: "carried over from cloud-clients.mjs PROVIDERS (no vendor re-verification in this pass)",
+      verifiedOn: "2026-06-28",
+      roles: { default: "gemini-2.5-pro", strong: "gemini-2.5-pro" },
+      models: {
+        "gemini-2.5-pro": { contextWindow: 1048576, tier: "strong", capabilities: ["api", "metered", "tools", "vision", "json", "thinking"], pricePer1M: { input: 1.25, output: 10 } }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: { gemini: { model: "gemini-2.5-pro" } }
+    },
+    openrouter: {
+      kind: "openai",
+      company: "openrouter",
+      baseUrl: "https://openrouter.ai/api/v1",
+      keyEnv: "OPENROUTER_API_KEY",
+      source: "carried over from cloud-clients.mjs PROVIDERS (OpenRouter list prices as dated per model)",
+      verifiedOn: "2026-07-10",
+      _note: "Same-family fallbacks hosted via OpenRouter (council key resilience, 2026-07-08 dogfood audit): a customer fleet with ONE OpenRouter key can still seat all three decorrelated council families \u2014 the MODEL family is what decorrelates blind spots, not the API host. grok-4.3 is the decorrelated director-seat primary (owner directive 2026-07-10, HS-E1O0); glm-5.2 is the 'beat Opus cheaper' candidate (HS-XNJI), not yet wired into any tier.",
+      roles: { cheap: "openai/gpt-4o-mini", director: "x-ai/grok-4.3", directorFallback: "z-ai/glm-5.2", geminiFallback: "google/gemini-2.5-pro", gpt4oFallback: "openai/gpt-4o" },
+      models: {
+        "openai/gpt-4o-mini": { contextWindow: 128e3, tier: "cheap", capabilities: ["api", "metered", "tools", "json"], pricePer1M: { input: 0.15, output: 0.6 } },
+        "openai/gpt-4o": { contextWindow: 128e3, tier: "strong", capabilities: ["api", "metered", "tools", "vision", "json"], pricePer1M: { input: 2.5, output: 10 } },
+        "google/gemini-2.5-pro": { contextWindow: 1048576, tier: "strong", capabilities: ["api", "metered", "tools", "vision", "json"], pricePer1M: { input: 1.25, output: 10 } },
+        "z-ai/glm-5.2": { displayName: "GLM-5.2 (Z.ai, open-weight 744B)", contextWindow: 2e5, tier: "strong", capabilities: ["api", "metered", "tools", "json"], verifiedOn: "2026-06-30", pricePer1M: { input: 0.95, output: 3 } },
+        "x-ai/grok-4.3": { displayName: "Grok 4.3 (xAI)", contextWindow: 256e3, tier: "strong", capabilities: ["api", "metered", "tools", "json", "thinking", "structured-outputs"], verifiedOn: "2026-07-10", pricePer1M: { input: 1.25, output: 2.5 } }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: {
+        openrouter: { model: "openai/gpt-4o-mini" },
+        "gemini-openrouter": { model: "google/gemini-2.5-pro" },
+        "gpt4o-openrouter": { model: "openai/gpt-4o" },
+        "glm-5.2": { model: "z-ai/glm-5.2" },
+        "grok-4.3": { model: "x-ai/grok-4.3" }
+      }
+    },
+    "github-models": {
+      kind: "openai",
+      company: "github",
+      baseUrl: "https://models.github.ai/inference",
+      keyEnv: "HEYSPEX_GITHUB_TOKEN",
+      keyEnvFallback: "GITHUB_TOKEN",
+      source: "GitHub Models bills via Copilot credits; gpt-4o list price mirrored for the ledger (estimate)",
+      verifiedOn: "2026-06-28",
+      _note: "Copilot-ecosystem credits as a cloud tier (HS-32OM fleet onboarding). Model ids are publisher-namespaced.",
+      roles: { default: "openai/gpt-4o" },
+      models: {
+        "openai/gpt-4o": { contextWindow: 128e3, tier: "strong", capabilities: ["api", "metered", "tools", "vision", "json"], pricePer1M: { input: 2.5, output: 10 } }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: { "github-models": { model: "openai/gpt-4o" } }
+    }
+  },
+  local: {
+    ollama: {
+      kind: "ollama",
+      _comment: "Local fleet models. WHERE each fits (canHost) and WHO uses it (purposes) live in routing-table.json; per-machine speeds live in fleet-manifest.mjs STATIC_SPEEDS. Ids are Ollama tags exactly as `ollama list` prints them. Local models have no PROVIDERS entry \u2014 callModel treats an unknown id as an Ollama id.",
+      roles: {
+        builder: "gpt-oss:20b",
+        coder: "qwen3-coder:30b",
+        judgeFallback: "qwen3-coder:30b",
+        vision: "qwen3.6:27b",
+        small: "qwen3:8b"
+      },
+      models: {
+        "gpt-oss:20b": { contextWindow: 131072, vramRequiredMb: 13800, architecture: "gptoss", capabilities: ["tools", "thinking"] },
+        "qwen3-coder:30b": { contextWindow: 262144, vramRequiredMb: 18600, architecture: "qwen3moe", capabilities: ["tools"] },
+        "qwen3.6:27b": { contextWindow: 262144, vramRequiredMb: 17400, architecture: "qwen35", capabilities: ["tools", "thinking", "vision"] },
+        "qwen2.5-coder:32b": { contextWindow: 131072, vramRequiredMb: 19900, architecture: "qwen2", capabilities: ["tools", "insert"] },
+        "qwen3:8b": { contextWindow: 32768, vramRequiredMb: 5200, architecture: "qwen3", capabilities: ["tools", "thinking"] },
+        "deepseek-r1:70b": { contextWindow: 131072, vramRequiredMb: 42500, architecture: "deepseek", capabilities: ["tools", "thinking"], note: "Q2_K quant \u2014 lower quality than Q4_K_M." },
+        "llama3.3:70b": { contextWindow: 131072, vramRequiredMb: 42500, architecture: "llama3", capabilities: ["tools"] },
+        "VibeThinker-3B": { contextWindow: 8192, vramRequiredMb: 3300, architecture: "qwen2", capabilities: [], note: "Fits anywhere \u226412GB." }
+      },
+      aliases: {},
+      retired: []
+    },
+    vllm: {
+      kind: "openai",
+      _comment: "Night Action vLLM + DSpark pilot (RTX 3060, matched draft `deepseek-ai/dspark_qwen3_8b_block7`). AWQ quant target (bf16 ~16GB does not fit 12GB VRAM alongside the draft; AWQ ~5.6GB does). Reference: HS-XNJI Experiment 1/2. Local, free, no key \u2014 vLLM OpenAI-compat endpoint on port 8000.",
+      baseUrl: "http://192.168.1.252:8000/v1",
+      keyEnv: null,
+      roles: { default: "Qwen/Qwen3-8B-AWQ" },
+      models: {
+        "Qwen/Qwen3-8B-AWQ": { contextWindow: 32768, vramRequiredMb: 5600, architecture: "qwen3", tier: "local", capabilities: ["api", "tools", "thinking"] }
+      },
+      aliases: {},
+      retired: [],
+      providerKeys: { "qwen3-8b-dspark": { model: "Qwen/Qwen3-8B-AWQ", local: true } }
+    }
+  }
+};
+
+// dev-factory/lib/model-catalog.mjs
+var MODEL_CATALOG_PATH = new URL("../model-catalog.json", import.meta.url).href;
+function loadModelCatalog(doc = (
+  /** @type {any} */
+  model_catalog_default
+)) {
+  return doc;
+}
+var MODEL_CATALOG = Object.freeze(loadModelCatalog());
+function buildIndex(catalog) {
+  const byId = /* @__PURE__ */ new Map();
+  const aliases = /* @__PURE__ */ new Map();
+  const retired = /* @__PURE__ */ new Map();
+  const providers = /* @__PURE__ */ new Map();
+  for (const [locality, block] of Object.entries({ cloud: catalog.cloud ?? {}, local: catalog.local ?? {} })) {
+    for (const [provider, p] of Object.entries(block)) {
+      if (provider.startsWith("_")) continue;
+      providers.set(provider, { ...p, provider, locality, kind: p.kind ?? locality });
+      for (const [id, m] of Object.entries(p.models ?? {})) {
+        byId.set(id, Object.freeze({ id, kind: locality, provider, tier: m.tier ?? (locality === "local" ? "local" : null), ...m }));
+      }
+      for (const [alias, target] of Object.entries(p.aliases ?? {})) aliases.set(alias, { target, provider, kind: locality });
+      for (const r of p.retired ?? []) retired.set(r.id, { ...r, provider, kind: locality });
+    }
+  }
+  return { byId, aliases, retired, providers };
+}
+var INDEX = buildIndex(MODEL_CATALOG);
+var ALL_MODEL_IDS = Object.freeze([...INDEX.byId.keys()]);
+var MODEL_ALIASES = Object.freeze(Object.fromEntries([...INDEX.aliases].map(([a, v]) => [a, v.target])));
+var RETIRED_MODEL_IDS = Object.freeze([...INDEX.retired.keys()]);
+var PROVIDER_NAMES = Object.freeze([...INDEX.providers.keys()]);
+function resolveModelId(id) {
+  if (typeof id !== "string" || !id) return id;
+  const hit = INDEX.aliases.get(id);
+  return hit ? hit.target : id;
+}
+function modelInfo(id) {
+  return INDEX.byId.get(resolveModelId(id)) ?? null;
+}
+function providerOf(id) {
+  const m = modelInfo(id);
+  return m ? INDEX.providers.get(m.provider) ?? null : null;
+}
+function providerInfo(name) {
+  return INDEX.providers.get(name) ?? null;
+}
+function isLocalModel(id) {
+  return modelInfo(id)?.kind === "local";
+}
+function roleBlock(name, extra = {}) {
+  const p = INDEX.providers.get(name) ?? {};
+  const roles = p.roles ?? {};
+  const upper = Object.fromEntries(Object.entries(roles).map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase(), v]));
+  return Object.freeze({
+    provider: name,
+    kind: p.kind ?? null,
+    company: p.company ?? name,
+    baseUrl: p.baseUrl ?? null,
+    keyEnv: p.keyEnv ?? null,
+    keyEnvFallback: p.keyEnvFallback ?? null,
+    verifiedOn: p.verifiedOn ?? MODEL_CATALOG.verified,
+    roles: Object.freeze({ ...roles }),
+    ids: Object.freeze(Object.keys(p.models ?? {})),
+    aliases: Object.freeze({ ...p.aliases ?? {} }),
+    retired: Object.freeze((p.retired ?? []).map((r) => r.id)),
+    ...upper,
+    // e.g. roles.chatDefault → CHAT_DEFAULT, roles.cheap → CHEAP
+    ...extra
+  });
+}
+var DS = MODEL_CATALOG.cloud?.deepseek ?? {};
+var DEEPSEEK = roleBlock("deepseek", {
+  FLASH: DS.roles?.cheap,
+  PRO: DS.roles?.strong,
+  anthropicBaseUrl: DS.anthropicBaseUrl ?? null,
+  peakHoursUtc: DS.peakHoursUtc ?? null
+});
+var ANTHROPIC = roleBlock("anthropic", { cliAliases: Object.freeze({ ...MODEL_CATALOG.cloud?.anthropic?.cliAliases ?? {} }) });
+var OPENAI = roleBlock("openai");
+var GEMINI = roleBlock("gemini");
+var OPENROUTER = roleBlock("openrouter");
+var GITHUB_MODELS = roleBlock("github-models");
+var OLLAMA = roleBlock("ollama");
+var VLLM = roleBlock("vllm");
+function isDeepSeekPeak(date = /* @__PURE__ */ new Date()) {
+  const p = DEEPSEEK.peakHoursUtc;
+  if (!p) return true;
+  const day = date.getUTCDay();
+  if (Array.isArray(p.days) && !p.days.includes(day)) return false;
+  const mins = date.getUTCHours() * 60 + date.getUTCMinutes();
+  const toMin = (hhmm) => {
+    const [h, m] = String(hhmm).split(":").map(Number);
+    return h * 60 + (m || 0);
+  };
+  return (p.ranges ?? []).some(([a, b]) => mins >= toMin(a) && mins < toMin(b));
+}
+function deepseekPricePer1M(id, { cacheHit = false, peak = null, at = /* @__PURE__ */ new Date() } = {}) {
+  const m = modelInfo(id);
+  if (!m || m.provider !== "deepseek" || !m.pricePer1M?.peak) return null;
+  const corner = peak ?? isDeepSeekPeak(at) ? m.pricePer1M.peak : m.pricePer1M.offPeak;
+  return { input: cacheHit ? corner.cacheHit : corner.cacheMiss, output: corner.output };
+}
+function listPricePer1M(id) {
+  const m = modelInfo(id);
+  if (!m) return null;
+  if (m.kind === "local") return { input: 0, output: 0 };
+  if (m.provider === "deepseek") return deepseekPricePer1M(id, { peak: true });
+  if (m.pricePer1M && Number.isFinite(m.pricePer1M.input)) return { input: m.pricePer1M.input, output: m.pricePer1M.output };
+  return null;
+}
+function providerEntries() {
+  const out = {};
+  for (const [name, p] of INDEX.providers) {
+    if (!p.providerKeys || !p.baseUrl) continue;
+    const base = { kind: p.kind ?? "openai", baseUrl: p.baseUrl, keyEnv: p.keyEnv ?? null };
+    if (p.keyEnvFallback) base.keyEnvFallback = p.keyEnvFallback;
+    if (p.company && p.company !== name) base.company = p.company;
+    if (p.betaBaseUrl) base.betaBaseUrl = p.betaBaseUrl;
+    if (p.userIdField) base.userIdField = p.userIdField;
+    const entryFor = (modelId, overrides = {}) => {
+      const target = resolveModelId(modelId);
+      const m = modelInfo(target);
+      const price = listPricePer1M(target) ?? { input: 0, output: 0 };
+      const e = { ...base, model: modelId, priceIn: price.input, priceOut: price.output, tier: m?.tier ?? (p.locality === "local" ? "local" : "strong") };
+      if (m?.kind === "local" || overrides.local) e.local = true;
+      if (m?.noTemp || overrides.noTemp) e.noTemp = true;
+      if (overrides.legacyAliasOf) e.legacyAliasOf = overrides.legacyAliasOf;
+      return e;
+    };
+    for (const [key, spec] of Object.entries(p.providerKeys)) out[key] = entryFor(spec.model, spec);
+    if (p.emitAliasesAsProviderKeys) {
+      for (const [alias, target] of Object.entries(p.aliases ?? {})) {
+        if (out[alias] || Object.values(p.providerKeys).some((s) => s.model === alias)) continue;
+        out[alias] = entryFor(target, { legacyAliasOf: target });
+      }
+    }
+  }
+  return out;
+}
+function fleetManifestModelRows() {
+  const contextWindows = {};
+  const costEstimates = {};
+  for (const id of ALL_MODEL_IDS) {
+    const m = modelInfo(id);
+    contextWindows[id] = {
+      contextWindow: m.contextWindow,
+      vramRequiredMb: m.vramRequiredMb ?? null,
+      architecture: m.architecture ?? m.provider,
+      capabilities: m.capabilities ?? []
+    };
+    const price = listPricePer1M(id);
+    if (m.kind === "local") {
+      costEstimates[id] = { kind: "free", note: `local model, zero API cost.${m.note ? " " + m.note : ""}` };
+    } else if (m.provider === "deepseek") {
+      costEstimates[id] = {
+        kind: "metered",
+        usdPerMInput: price.input,
+        usdPerMOutput: price.output,
+        note: `${m.displayName ?? id}: peak cache-miss list rates (model-catalog.json, verified ${providerInfo("deepseek")?.verifiedOn}); off-peak halves, cache hits ~50x cheaper`
+      };
+    } else if (price) {
+      costEstimates[id] = {
+        kind: "metered",
+        usdPerMInput: price.input,
+        usdPerMOutput: price.output,
+        note: `${m.displayName ?? id}: list rates (model-catalog.json, verified ${providerOf(id)?.verifiedOn ?? MODEL_CATALOG.verified})`
+      };
+    } else {
+      costEstimates[id] = { kind: "metered", note: m.note ?? "pricing not recorded in model-catalog.json" };
+    }
+  }
+  return { contextWindows, costEstimates };
+}
+function runSelfTest({ log = console.log } = {}) {
+  let ok = true;
+  const check = (name, cond) => {
+    log(`  ${cond ? "\u2713" : "\u2717"} ${name}`);
+    if (!cond) ok = false;
+  };
+  log("== model-catalog self-test ==\n");
+  check("catalog has a verified date", /^\d{4}-\d{2}-\d{2}$/.test(String(MODEL_CATALOG.verified)));
+  check(
+    "every provider role points at a current id of that provider",
+    [...INDEX.providers.values()].every((p) => Object.values(p.roles ?? {}).every((id) => id in (p.models ?? {}) || (p.aliases ?? {})[id]))
+  );
+  check(
+    "every providerKeys.model is a current id or a declared alias of that provider",
+    [...INDEX.providers.values()].every((p) => Object.values(p.providerKeys ?? {}).every((s) => s.model in (p.models ?? {}) || (p.aliases ?? {})[s.model]))
+  );
+  check(
+    "no alias target is itself an alias or retired",
+    Object.values(MODEL_ALIASES).every((t) => INDEX.byId.has(t) && !INDEX.retired.has(t))
+  );
+  check(
+    "every retired id has an alias to its successor",
+    RETIRED_MODEL_IDS.every((id) => MODEL_ALIASES[id])
+  );
+  check(
+    "no current id is also listed as retired",
+    ALL_MODEL_IDS.every((id) => !INDEX.retired.has(id))
+  );
+  check(
+    "every model has a positive context window",
+    ALL_MODEL_IDS.every((id) => modelInfo(id).contextWindow > 0)
+  );
+  check(
+    "every cloud model has a list price",
+    ALL_MODEL_IDS.filter((id) => !isLocalModel(id)).every((id) => listPricePer1M(id)?.input > 0 && listPricePer1M(id)?.output > 0)
+  );
+  check(
+    "DeepSeek prices are four-corner, positive, and off-peak is half of peak",
+    DEEPSEEK.ids.every((id) => {
+      const p = modelInfo(id).pricePer1M;
+      return ["cacheHit", "cacheMiss", "output"].every((k) => p?.peak?.[k] > 0 && Math.abs(p.peak[k] - 2 * p.offPeak[k]) < 1e-9);
+    })
+  );
+  check(
+    "every local model has a VRAM figure",
+    ALL_MODEL_IDS.filter(isLocalModel).every((id) => Number.isFinite(modelInfo(id).vramRequiredMb))
+  );
+  check(
+    "resolveModelId maps a retired id to its successor",
+    RETIRED_MODEL_IDS.every((id) => ALL_MODEL_IDS.includes(resolveModelId(id)))
+  );
+  check("providerEntries covers every providerKey and every DeepSeek alias, with prices", (() => {
+    const e = providerEntries();
+    const keys = [...INDEX.providers.values()].flatMap((p) => Object.keys(p.providerKeys ?? {}));
+    return keys.every((k) => e[k]?.model && e[k].baseUrl && Number.isFinite(e[k].priceIn)) && Object.keys(DEEPSEEK.aliases).every((a) => e[a]?.legacyAliasOf || e.deepseek?.model === a);
+  })());
+  check(
+    "isDeepSeekPeak: Tue 02:30 UTC is peak, Sat 02:30 UTC is not, Tue 12:00 UTC is not",
+    isDeepSeekPeak(/* @__PURE__ */ new Date("2026-09-15T02:30:00Z")) && !isDeepSeekPeak(/* @__PURE__ */ new Date("2026-09-19T02:30:00Z")) && !isDeepSeekPeak(/* @__PURE__ */ new Date("2026-09-15T12:00:00Z"))
+  );
+  check(
+    "fleetManifestModelRows covers every catalog id",
+    Object.keys(fleetManifestModelRows().contextWindows).length === ALL_MODEL_IDS.length
+  );
+  check(
+    "Claude CLI alias words resolve to current Anthropic ids",
+    Object.values(ANTHROPIC.cliAliases).every((id) => ANTHROPIC.ids.includes(id))
+  );
+  log(`
+${ok ? "\u2713 self-test PASS \u2014 catalog invariants verified." : "\u2717 self-test FAIL"}`);
+  return ok ? 0 : 1;
+}
+var isMain = typeof process !== "undefined" && Array.isArray(process.argv) && Boolean(process.argv[1]) && /model-catalog\.mjs$/.test(String(process.argv[1]).replace(/\\/g, "/"));
+if (isMain) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--self-test")) process.exit(runSelfTest());
+  if (argv.includes("--print")) {
+    console.log(JSON.stringify({ DEEPSEEK, ANTHROPIC, OPENAI, GEMINI, OPENROUTER, GITHUB_MODELS, OLLAMA, VLLM, ALL_MODEL_IDS, MODEL_ALIASES, RETIRED_MODEL_IDS, providerEntries: providerEntries() }, null, 2));
+    process.exit(0);
+  }
+  if (argv.length) {
+    console.error("usage: node dev-factory/lib/model-catalog.mjs --self-test | --print");
+    process.exit(64);
+  }
+}
+
+// spex-console/src/lib/model-catalog.ts
+var ANTHROPIC2 = ANTHROPIC;
+var OLLAMA2 = OLLAMA;
+
+// spex-console/src/lib/launch-preferences.ts
+var USE_CASE_SETTINGS_KEY = {
+  "task-creation": "taskCreation",
+  "task-implementation": "taskImplementation",
+  handoff: "handoff",
+  milestone: "milestone",
+  epic: "epic",
+  sprint: "sprint"
+};
+var LAUNCH_SETTINGS_BUCKET_KEYS = Object.values(
+  USE_CASE_SETTINGS_KEY
+);
+var DEFAULT_LAUNCH_MODEL_PREFERENCES = {
+  // Every Claude default is a version-less ALIAS, never a pinned id (owner
+  // ruling 2026-09-01: "I don't like seeing these numbers hard-set"). Claude
+  // renumbers a family every few months, and a pinned default silently keeps
+  // opening last season's model until someone notices and edits this file.
+  // An alias resolves to the newest id in its family at launch time
+  // (`launch-model-aliases.ts`), so the shipped default never goes stale.
+  // Anyone who WANTS a pinned id can still set one — `hs next model epic
+  // claude-opus-4-8` stores it byte-for-byte. Non-Claude values have no alias
+  // vocabulary and stay exact: `composer-2.5-fast` is a Cursor model, and
+  // `qwen3-coder:30b` a local fleet one.
+  taskCreation: {
+    claudeCode: "claude-opus",
+    cursorAgent: "claude-opus",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  taskImplementation: {
+    claudeCode: "claude-sonnet",
+    cursorAgent: "composer-2.5-fast",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  // A handoff resume re-enters existing work — same weight class as task
+  // implementation (Sonnet), Claude Code only by default (no --tool flag on
+  // `hs handoff`). Settings key: `launchModels.handoff.*`.
+  handoff: {
+    claudeCode: "claude-sonnet",
+    cursorAgent: "composer-2.5-fast",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  // Launching a milestone, epic or sprint means BREAKING IT DOWN into child
+  // work, not writing code — the same job `taskCreation` already weights at
+  // Opus, so these three inherit that weight class rather than task
+  // implementation's Sonnet. Settings keys: `launchModels.{milestone,epic,sprint}.*`.
+  milestone: {
+    claudeCode: "claude-opus",
+    cursorAgent: "claude-opus",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  epic: {
+    claudeCode: "claude-opus",
+    cursorAgent: "claude-opus",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  sprint: {
+    claudeCode: "claude-opus",
+    cursorAgent: "claude-opus",
+    fleet: OLLAMA2.CODER,
+    defaultAgent: "claude-code"
+  },
+  closeTerminalOnTaskComplete: true,
+  autoClaimOnLaunch: false,
+  // Handheld is the safest default (human in the loop); mvp matches the active
+  // operating mode. Both are user-settable in Settings.
+  defaultRunMode: "handheld",
+  defaultReviewProfile: "mvp"
+};
+var CLAUDE_LAUNCH_MODEL_OPTIONS = [
+  { id: ANTHROPIC2.STRONG, label: "Claude Opus 5" },
+  { id: ANTHROPIC2.MID, label: "Claude Sonnet 5" },
+  { id: "claude-fable-5", label: "Claude Fable 5" },
+  { id: ANTHROPIC2.PREVIOUS_STRONG, label: "Claude Opus 4.8" },
+  { id: ANTHROPIC2.PREVIOUS_MID, label: "Claude Sonnet 4.6" },
+  { id: ANTHROPIC2.CHEAP, label: "Claude Haiku 4.5" }
+];
+var CURSOR_LAUNCH_MODEL_OPTIONS = [
+  { id: "auto", label: "Auto" },
+  { id: "composer-2.5-fast", label: "Composer 2.5 Fast" },
+  { id: ANTHROPIC2.PREVIOUS_STRONG, label: "Claude Opus 4.8 (via Cursor)" },
+  { id: ANTHROPIC2.PREVIOUS_MID, label: "Claude Sonnet 4.6 (via Cursor)" }
+];
+var CLAUDE_PERMISSION_MODE_OPTIONS = [
+  "acceptEdits",
+  "auto",
+  "bypassPermissions",
+  "manual",
+  "dontAsk",
+  "plan"
+];
+var CURSOR_PERMISSION_MODE_OPTIONS = [];
+
+// 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/handoff.ts
+var ALL_LAUNCH_MODEL_OPTIONS = [...CLAUDE_LAUNCH_MODEL_OPTIONS, ...CURSOR_LAUNCH_MODEL_OPTIONS];
+function isKnownModelValue(value, options) {
+  return options.some((o) => o.id === value) || isModelAliasValue(value);
+}
+function validModelOptionsList(options) {
+  return [...options.map((o) => o.id), ...MODEL_ALIAS_INPUT_FORMS];
+}
+var ALL_LAUNCH_PERMISSION_MODE_OPTIONS = [
+  ...CLAUDE_PERMISSION_MODE_OPTIONS,
+  ...CURSOR_PERMISSION_MODE_OPTIONS
+];
+var LANE_CODE_CHARSET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+var LANE_CODE_LENGTH = 4;
+var LANE_CODE_MAX_LENGTH = 12;
+var LANE_CODE_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
+function mintLaneCode(occupied, randomUnit = Math.random) {
+  const taken = new Set([...occupied].map((c) => String(c).toUpperCase()));
+  let length = LANE_CODE_LENGTH;
+  for (; length <= LANE_CODE_MAX_LENGTH; ) {
+    const maxAttempts = Math.min(LANE_CODE_CHARSET.length ** length, 1e4);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      let code = "";
+      for (let i = 0; i < length; i++) {
+        const idx = Math.floor(randomUnit() * LANE_CODE_CHARSET.length);
+        code += LANE_CODE_CHARSET[Math.min(idx, LANE_CODE_CHARSET.length - 1)];
+      }
+      if (!LANE_CODE_RE.test(code)) continue;
+      if (!taken.has(code)) return code;
+    }
+    length++;
+  }
+  throw new Error(
+    `could not mint a lane code up to ${LANE_CODE_MAX_LENGTH} characters \u2014 ${occupied.size} lane(s) already in flight`
+  );
+}
+function isKnownPermissionModeValue(value, options) {
+  return options.includes(value);
+}
+function validateLaunchFlags(args) {
+  if (args.launch && args.sub === "record") {
+    return {
+      code: EXIT.USAGE,
+      message: "--launch is not valid with record (use load, or the bare-code shorthand)"
+    };
+  }
+  if (args.launch && args.all) {
+    return {
+      code: EXIT.USAGE,
+      message: "--launch is not valid with --all (launch targets a single lane)"
+    };
+  }
+  if (args.newCode && args.sub !== "record") {
+    return { code: EXIT.USAGE, message: "--new-code is only valid on record" };
+  }
+  if (args.newCode && args.lane !== void 0) {
+    return {
+      code: EXIT.USAGE,
+      message: "--new-code mints the lane code, so it cannot be combined with --lane"
+    };
+  }
+  if (args.dryRun && !args.launch) {
+    return { code: EXIT.USAGE, message: "--dry-run requires --launch" };
+  }
+  if (args.force && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--force requires --launch (e.g. hs handoff <CODE> --force)"
+    };
+  }
+  if (args.modelOverride !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--model requires --launch (e.g. hs handoff <CODE> --model <value> --launch)"
+    };
+  }
+  if (args.modelOverride !== void 0 && !isKnownModelValue(args.modelOverride, ALL_LAUNCH_MODEL_OPTIONS)) {
+    const validOptions = validModelOptionsList(ALL_LAUNCH_MODEL_OPTIONS);
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown model "${args.modelOverride}". Valid options: ${validOptions.join(", ")}`
+    };
+  }
+  if (args.permissionModeOverride !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--permission-mode requires --launch (e.g. hs handoff <CODE> --permission-mode <mode> --launch)"
+    };
+  }
+  if (args.permissionModeOverride !== void 0 && !isKnownPermissionModeValue(args.permissionModeOverride, ALL_LAUNCH_PERMISSION_MODE_OPTIONS)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown permission mode "${args.permissionModeOverride}". Valid modes: ${ALL_LAUNCH_PERMISSION_MODE_OPTIONS.join(", ")}`
+    };
+  }
+  return null;
+}
+function parseHandoffArgs(argv) {
+  const subRaw = argv[0];
+  if (subRaw === "--help" || subRaw === "-h" || subRaw === void 0) {
+    return { help: true };
+  }
+  if (subRaw === "model") {
+    const args2 = { sub: "model", blockers: [], links: [], all: false, 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") args2.json = true;
+      else if (arg.startsWith("-")) {
+        return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+      } else if (args2.modelValue === void 0) {
+        args2.modelValue = arg;
+      } else {
+        return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+      }
+    }
+    return { args: args2 };
+  }
+  if (subRaw === "permission-mode") {
+    const args2 = {
+      sub: "permission-mode",
+      blockers: [],
+      links: [],
+      all: false,
+      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") args2.json = true;
+      else if (arg.startsWith("-")) {
+        return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+      } else if (args2.permissionModeValue === void 0) {
+        args2.permissionModeValue = arg;
+      } else {
+        return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+      }
+    }
+    return { args: args2 };
+  }
+  if (subRaw === "delete") {
+    const args2 = {
+      sub: "delete",
+      blockers: [],
+      links: [],
+      all: false,
+      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") args2.json = true;
+      else if (arg === "--yes" || arg === "-y") args2.yes = true;
+      else if (arg === "--lane" || arg.startsWith("--lane=")) {
+        const v = arg.startsWith("--lane=") ? arg.slice("--lane=".length) : argv[++i];
+        if (v === void 0) {
+          return { error: { code: EXIT.INVALID_ARG, message: "--lane requires a value" } };
+        }
+        args2.lane = v;
+      } else if (arg.startsWith("-")) {
+        return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+      } else if (args2.lane === void 0) {
+        args2.lane = arg;
+      } else {
+        return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+      }
+    }
+    if (args2.lane === void 0) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: "delete needs a lane code (e.g. hs handoff delete US2R --yes)"
+        }
+      };
+    }
+    return { args: args2 };
+  }
+  if (subRaw !== "record" && subRaw !== "load") {
+    if (!subRaw.startsWith("-")) {
+      const args2 = {
+        sub: "load",
+        lane: subRaw,
+        blockers: [],
+        links: [],
+        all: false,
+        json: false,
+        launch: true
+      };
+      for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--launch") args2.launch = true;
+        else if (arg === "--no-launch") args2.launch = false;
+        else if (arg === "--dry-run") args2.dryRun = true;
+        else if (arg === "--force") args2.force = true;
+        else if (arg === "--json") args2.json = true;
+        else if (arg === "--model" || arg.startsWith("--model=")) {
+          const v = arg.startsWith("--model=") ? arg.slice("--model=".length) : argv[++i];
+          if (v === void 0) {
+            return { error: { code: EXIT.INVALID_ARG, message: "--model requires a value" } };
+          }
+          args2.modelOverride = v;
+        } else if (arg === "--permission-mode" || arg.startsWith("--permission-mode=")) {
+          const v = arg.startsWith("--permission-mode=") ? arg.slice("--permission-mode=".length) : argv[++i];
+          if (v === void 0) {
+            return {
+              error: { code: EXIT.INVALID_ARG, message: "--permission-mode requires a value" }
+            };
+          }
+          args2.permissionModeOverride = v;
+        } else {
+          return { error: { code: EXIT.USAGE, message: `unknown subcommand: ${subRaw}` } };
+        }
+      }
+      const flagError2 = validateLaunchFlags(args2);
+      if (flagError2) return { error: flagError2 };
+      return { args: args2 };
+    }
+    return { error: { code: EXIT.USAGE, message: `unknown subcommand: ${subRaw}` } };
+  }
+  const sub = subRaw;
+  const args = { sub, blockers: [], links: [], all: false, json: false };
+  const takeValue = (arg, inline, i) => {
+    if (arg.startsWith(`${inline}=`)) return arg.slice(inline.length + 1);
+    return argv[++i.v];
+  };
+  for (const counter = { v: 1 }; counter.v < argv.length; counter.v++) {
+    const arg = argv[counter.v];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") args.json = true;
+    else if (arg === "--all") args.all = true;
+    else if (arg === "--new-code") args.newCode = true;
+    else if (arg === "--launch") args.launch = true;
+    else if (arg === "--dry-run") args.dryRun = true;
+    else if (arg === "--force") args.force = true;
+    else if (arg === "--lane" || arg.startsWith("--lane=")) {
+      const v = takeValue(arg, "--lane", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--lane requires a value" } };
+      args.lane = v;
+    } else if (arg === "--agent" || arg.startsWith("--agent=")) {
+      const v = takeValue(arg, "--agent", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--agent requires a value" } };
+      args.agent = v;
+    } else if (arg === "--session" || arg.startsWith("--session=")) {
+      const v = takeValue(arg, "--session", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--session requires a value" } };
+      args.session = v;
+    } else if (arg === "--spec" || arg.startsWith("--spec=")) {
+      const v = takeValue(arg, "--spec", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--spec requires a value" } };
+      args.specId = v;
+    } else if (arg === "--phase" || arg.startsWith("--phase=")) {
+      const v = takeValue(arg, "--phase", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--phase requires a value" } };
+      args.phase = v;
+    } else if (arg === "--time" || arg.startsWith("--time=")) {
+      const v = takeValue(arg, "--time", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--time requires a value" } };
+      args.estimatedTime = v;
+    } else if (arg === "--blocker" || arg.startsWith("--blocker=")) {
+      const v = takeValue(arg, "--blocker", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--blocker requires a value" } };
+      args.blockers.push(v);
+    } else if (arg === "--link" || arg.startsWith("--link=")) {
+      const v = takeValue(arg, "--link", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--link requires a value" } };
+      args.links.push(v);
+    } else if (arg === "--model" || arg.startsWith("--model=")) {
+      const v = takeValue(arg, "--model", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--model requires a value" } };
+      args.modelOverride = v;
+    } else if (arg === "--permission-mode" || arg.startsWith("--permission-mode=")) {
+      const v = takeValue(arg, "--permission-mode", counter);
+      if (v === void 0)
+        return { error: { code: EXIT.INVALID_ARG, message: "--permission-mode requires a value" } };
+      args.permissionModeOverride = v;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  const flagError = validateLaunchFlags(args);
+  if (flagError) return { error: flagError };
+  return { args };
+}
+function describeContext(c) {
+  if (!c) return "(no current handoff context)";
+  const parts = [c.laneKey ? `lane ${c.laneKey}` : ""];
+  if (c.specId) parts.push(`spec ${c.specId}`);
+  if (c.phase) parts.push(`phase ${c.phase}`);
+  if (c.estimatedTime) parts.push(`~${c.estimatedTime}`);
+  return parts.filter(Boolean).join(" \xB7 ");
+}
+async function launchHandoff(lane, args, deps, context) {
+  const contextLine = describeContext(context);
+  const body = {
+    prompt: `/hs-handoff ${lane}`,
+    launchUseCase: "handoff",
+    ...args.dryRun ? { dryRun: true } : {},
+    // The route holds a 5-minute in-flight marker per lane so a second window
+    // for the same code is a no-op (the runaway-chain guard). `--force` is the
+    // deliberate re-open.
+    ...args.force ? { force: true } : {},
+    // Per-launch override ([[HS-AWU6]]) — slots above the spec/settings ladder
+    // server-side (`resolveLaunchTarget`, modelSource: "override"). The stored
+    // `hs handoff model` default is never written on this path.
+    ...args.modelOverride !== void 0 ? { modelOverride: args.modelOverride } : {},
+    // Per-launch permission-mode override ([[HS-JKA6]]) — additive, same shape
+    // as modelOverride above. Never persisted; the per-agent settings default
+    // (if any) lives at `launchPermissions.handoff.{claudeCode,cursorAgent}`,
+    // untouched by this flag.
+    ...args.permissionModeOverride !== void 0 ? { permissionModeOverride: args.permissionModeOverride } : {}
+  };
+  const res = await controlRequest(deps, { method: "POST", path: "/api/agent/start", body });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  const payload = res.body ?? {};
+  const agent = typeof payload.agent === "string" ? payload.agent : "?";
+  const model = typeof payload.model === "string" ? payload.model : "?";
+  const modelSource = typeof payload.modelSource === "string" ? payload.modelSource : "?";
+  const modelDisplay = typeof payload.modelDisplay === "string" ? payload.modelDisplay : model;
+  const prompt = typeof payload.prompt === "string" ? payload.prompt : `/hs-handoff ${lane}`;
+  const permissionMode = typeof payload.permissionMode === "string" && payload.permissionMode ? payload.permissionMode : null;
+  const permissionModeSource = typeof payload.permissionModeSource === "string" ? payload.permissionModeSource : null;
+  const cursorPermissionModeNote = args.permissionModeOverride !== void 0 && agent === "cursor-agent" ? "\n  note: cursor-agent has no --permission-mode equivalent; the requested override was ignored." : "";
+  if (args.dryRun) {
+    return {
+      code: EXIT.OK,
+      message: `${contextLine}
+[dry-run] would launch handoff resume for lane ${lane}
+  agent:  ${agent}
+  model:  ${modelDisplay} (source: ${modelSource})
+` + (permissionMode ? `  permission: ${permissionMode} (source: ${permissionModeSource})
+` : "") + `  prompt: ${prompt}` + cursorPermissionModeNote,
+      payload: {
+        ok: true,
+        dryRun: true,
+        lane,
+        context: context ?? null,
+        agent,
+        model,
+        modelDisplay,
+        modelSource,
+        permissionMode,
+        permissionModeSource,
+        prompt
+      },
+      isError: false
+    };
+  }
+  if (payload.alreadyActive) {
+    return {
+      code: EXIT.OK,
+      message: `${contextLine}
+handoff resume for lane ${lane} is already active (${String(payload.reason ?? "in_flight")}).
+  re-open it anyway with: hs handoff ${lane} --force`,
+      payload: { ok: true, lane, context: context ?? null, ...payload },
+      isError: false
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `${contextLine}
+Launched handoff resume for lane ${lane} -> ${agent} (${model}).
+  prompt: ${prompt}` + cursorPermissionModeNote,
+    payload: { ok: true, lane, context: context ?? null, ...payload },
+    isError: false
+  };
+}
+async function runHandoffModel(args, deps) {
+  const dryRunRes = await controlRequest(deps, {
+    method: "POST",
+    path: "/api/agent/start",
+    body: { prompt: "/hs-handoff", launchUseCase: "handoff", dryRun: true }
+  });
+  if (!dryRunRes.ok) return dryRunRes.error;
+  if (dryRunRes.status !== 200) return writeFailed(dryRunRes.status, dryRunRes.body);
+  const current = dryRunRes.body ?? {};
+  const currentModel = typeof current.model === "string" ? current.model : "?";
+  const currentSource = typeof current.modelSource === "string" ? current.modelSource : "?";
+  const currentAgent = typeof current.agent === "string" ? current.agent : "claude-code";
+  const currentModelDisplay = typeof current.modelDisplay === "string" ? current.modelDisplay : currentModel;
+  if (args.modelValue === void 0) {
+    return {
+      code: EXIT.OK,
+      message: `handoff default model: ${currentModelDisplay} (source: ${currentSource}, agent: ${currentAgent})`,
+      payload: {
+        ok: true,
+        model: currentModel,
+        modelDisplay: currentModelDisplay,
+        modelSource: currentSource,
+        agent: currentAgent
+      },
+      isError: false
+    };
+  }
+  const options = currentAgent === "cursor-agent" ? CURSOR_LAUNCH_MODEL_OPTIONS : CLAUDE_LAUNCH_MODEL_OPTIONS;
+  if (!isKnownModelValue(args.modelValue, options)) {
+    const validOptions = validModelOptionsList(options);
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown model "${args.modelValue}" for agent ${currentAgent}. Valid options: ${validOptions.join(", ")}`,
+      payload: {
+        ok: false,
+        error: "invalid_model",
+        value: args.modelValue,
+        agent: currentAgent,
+        validOptions
+      },
+      isError: true
+    };
+  }
+  const valueToStore = canonicalizeModelAlias(args.modelValue) ?? args.modelValue;
+  const bucketField = currentAgent === "cursor-agent" ? "cursorAgent" : currentAgent === "dev-factory-fleet" ? "fleet" : "claudeCode";
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchModels: { handoff: { [bucketField]: valueToStore } } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: `handoff default model set -> ${valueToStore} (agent: ${currentAgent}).`,
+    payload: { ok: true, model: valueToStore, agent: currentAgent },
+    isError: false
+  };
+}
+async function runHandoffPermissionMode(args, deps) {
+  const dryRunRes = await controlRequest(deps, {
+    method: "POST",
+    path: "/api/agent/start",
+    body: { prompt: "/hs-handoff", launchUseCase: "handoff", dryRun: true }
+  });
+  if (!dryRunRes.ok) return dryRunRes.error;
+  if (dryRunRes.status !== 200) return writeFailed(dryRunRes.status, dryRunRes.body);
+  const current = dryRunRes.body ?? {};
+  const currentAgent = typeof current.agent === "string" ? current.agent : "claude-code";
+  const currentMode = typeof current.permissionMode === "string" && current.permissionMode ? current.permissionMode : null;
+  const currentSource = typeof current.permissionModeSource === "string" ? current.permissionModeSource : null;
+  if (args.permissionModeValue === void 0) {
+    return {
+      code: EXIT.OK,
+      message: currentMode ? `handoff default permission-mode: ${currentMode} (source: ${currentSource}, agent: ${currentAgent})` : `handoff default permission-mode: unset (agent: ${currentAgent}) \u2014 claude's own default prompting applies.`,
+      payload: {
+        ok: true,
+        permissionMode: currentMode,
+        permissionModeSource: currentSource,
+        agent: currentAgent
+      },
+      isError: false
+    };
+  }
+  if (currentAgent !== "claude-code") {
+    return {
+      code: EXIT.USAGE,
+      message: `hs handoff permission-mode is not supported for agent ${currentAgent} yet (no --permission-mode equivalent). The active handoff agent must be claude-code.`,
+      payload: { ok: false, error: "unsupported_agent", agent: currentAgent },
+      isError: true
+    };
+  }
+  if (!isKnownPermissionModeValue(args.permissionModeValue, CLAUDE_PERMISSION_MODE_OPTIONS)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown permission mode "${args.permissionModeValue}" for agent ${currentAgent}. Valid modes: ${CLAUDE_PERMISSION_MODE_OPTIONS.join(", ")}`,
+      payload: {
+        ok: false,
+        error: "invalid_permission_mode",
+        value: args.permissionModeValue,
+        agent: currentAgent,
+        validOptions: CLAUDE_PERMISSION_MODE_OPTIONS
+      },
+      isError: true
+    };
+  }
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchPermissions: { handoff: { claudeCode: args.permissionModeValue } } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  const bypassCaveat = args.permissionModeValue === "bypassPermissions" ? "\n  caveat: bypassPermissions skips ALL permission prompts \u2014 trusted repos only." : "";
+  return {
+    code: EXIT.OK,
+    message: `handoff default permission-mode set -> ${args.permissionModeValue} (agent: ${currentAgent}).${bypassCaveat}`,
+    payload: { ok: true, permissionMode: args.permissionModeValue, agent: currentAgent },
+    isError: false
+  };
+}
+async function runHandoffDelete(lane, args, deps) {
+  const path3 = `/api/control/handoff-context?lane=${encodeURIComponent(lane)}`;
+  const read = await controlRequest(deps, { method: "GET", path: path3 });
+  if (!read.ok) return read.error;
+  if (read.status !== 200) return writeFailed(read.status, read.body);
+  const existing = read.body?.context ?? null;
+  if (!existing) {
+    return {
+      code: EXIT.NOT_FOUND,
+      message: `no live lane ${lane} \u2014 nothing to delete.`,
+      payload: { ok: false, error: "lane_not_found", lane },
+      isError: true
+    };
+  }
+  if (!args.yes) {
+    return {
+      code: EXIT.USAGE,
+      message: `Would delete ${describeContext(existing)}
+  blockers: ${existing.blockers?.length ?? 0} \xB7 links: ${existing.links?.length ?? 0}
+  A lane holds coordination only, so this is re-recordable \u2014 but nothing
+  is removed without the explicit confirm.
+  delete it with: hs handoff delete ${lane} --yes`,
+      payload: { ok: false, error: "confirm_required", lane, context: existing },
+      isError: true
+    };
+  }
+  const res = await controlRequest(deps, { method: "DELETE", path: path3 });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: `Deleted lane ${lane}.
+  it held: ${describeContext(existing)}
+  re-record it with: hs handoff record --lane ${lane} --spec ${existing.specId ?? "<id>"}`,
+    payload: { ok: true, lane, deleted: existing },
+    isError: false
+  };
+}
+async function runHandoff(args, deps) {
+  if (args.sub === "model") {
+    return runHandoffModel(args, deps);
+  }
+  if (args.sub === "permission-mode") {
+    return runHandoffPermissionMode(args, deps);
+  }
+  const id = resolveAgentIdentity(args.agent, args.session);
+  const lane = args.lane?.trim() || id.sessionId;
+  if (args.sub === "delete") {
+    return runHandoffDelete(lane, args, deps);
+  }
+  if (args.sub === "load") {
+    const path3 = args.all ? "/api/control/handoff-context" : `/api/control/handoff-context?lane=${encodeURIComponent(lane)}`;
+    const res2 = await controlRequest(deps, { method: "GET", path: path3 });
+    if (!res2.ok) return res2.error;
+    if (res2.status !== 200) return writeFailed(res2.status, res2.body);
+    if (args.all) {
+      const contexts = res2.body?.contexts ?? [];
+      const lines = contexts.length ? contexts.map((c) => `  ${describeContext(c)}`).join("\n") : "  (no active lanes)";
+      return {
+        code: EXIT.OK,
+        message: `${contexts.length} active lane(s):
+${lines}`,
+        payload: { ok: true, contexts },
+        isError: false
+      };
+    }
+    const context2 = res2.body?.context ?? null;
+    if (args.launch) {
+      if (!context2) {
+        return {
+          code: EXIT.NOT_FOUND,
+          message: `no current handoff context for lane ${lane} \u2014 refusing to launch (empty or expired lane).`,
+          payload: { ok: false, error: "lane_not_found", lane },
+          isError: true
+        };
+      }
+      return launchHandoff(lane, args, deps, context2);
+    }
+    return {
+      code: EXIT.OK,
+      message: describeContext(context2),
+      payload: { ok: true, lane, context: context2 },
+      isError: false
+    };
+  }
+  let recordLane = lane;
+  if (args.newCode) {
+    const listed = await controlRequest(deps, {
+      method: "GET",
+      path: "/api/control/handoff-context"
+    });
+    if (!listed.ok) return listed.error;
+    if (listed.status !== 200) return writeFailed(listed.status, listed.body);
+    const occupied = new Set(
+      (listed.body?.contexts ?? []).map((c) => String(c.laneKey ?? "").toUpperCase()).filter(Boolean)
+    );
+    recordLane = mintLaneCode(occupied);
+  }
+  const body = {
+    lane_key: recordLane,
+    agent: id.agent,
+    ...args.specId !== void 0 ? { spec_id: args.specId } : {},
+    ...args.phase !== void 0 ? { phase: args.phase } : {},
+    ...args.estimatedTime !== void 0 ? { estimated_time: args.estimatedTime } : {},
+    ...args.blockers.length ? { blockers: args.blockers } : {},
+    ...args.links.length ? { links: args.links } : {}
+  };
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/control/handoff-context",
+    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);
+  const context = res.body?.context ?? null;
+  if (args.newCode) {
+    return {
+      code: EXIT.OK,
+      message: `Handoff code: ${recordLane}
+  ${describeContext(context)}
+  resume it with: hs handoff ${recordLane}`,
+      payload: { ok: true, lane: recordLane, minted: true, context },
+      isError: false
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `Handoff recorded \u2192 ${describeContext(context)}`,
+    payload: { ok: true, lane, context },
+    isError: false
+  };
+}
+var HELP2 = [
+  "Usage:",
+  "  hs handoff record [flags]            Upsert this lane's current resume context",
+  "  hs handoff record --new-code [flags] Mint a fresh code, record it, print it",
+  "  hs handoff delete <CODE> [--yes]     Drop one lane (prints it and refuses without --yes)",
+  "  hs handoff load [--lane <k>] [--all] Print the current resume context for a lane (never launches)",
+  "  hs handoff <CODE> [--dry-run]         Resolve the lane, print its summary, and LAUNCH its resume (default)",
+  "  hs handoff <CODE> --no-launch        Same resolution, print-only \u2014 the human peek, no launch",
+  "  hs handoff <CODE> --force            Launch again even if this lane already has a window opening",
+  "  hs handoff load --lane <k> --launch [--dry-run]  Spelled-out equivalent of the default-launch shorthand",
+  "  hs handoff <CODE> --model <value>    One-off model override for this launch (--launch implied)",
+  "  hs handoff <CODE> --permission-mode <mode>  One-off permission-mode override for this launch",
+  "  hs handoff model [<value>]           Print (or set) the handoff use case's default model",
+  "  hs handoff permission-mode [<value>] Print (or set) the ACTIVE agent's default permission-mode",
+  "",
+  "`hs handoff record --new-code` MINTS the lane code rather than letting anyone",
+  "invent one. Codes are 4 characters, uppercase letters and digits with the",
+  "lookalikes dropped (no 0/O, no 1/I/L), always carrying a letter \u2014 the same",
+  "shape every spec file key has, so a lane code reads like every other id you",
+  "see. The mint checks the live lane list first, so it can never collide with a",
+  'lane already in flight. This replaces the old "pick a 4-character code and',
+  'collision-check it yourself" step, which is how a lane once ended up named',
+  "FLEET.",
+  "",
+  "`hs handoff delete <CODE>` drops ONE lane. Rows already self-purge on a server",
+  "TTL, so this is for the case a TTL cannot help with: a lane recorded under the",
+  "wrong code, sitting in the listing next to the right one. There is no trash and",
+  "no delete-all \u2014 a lane is coordination only (spec, phase, blockers, links), so",
+  "the row printed back to you IS the undo: re-record it from what you see. The",
+  "safe outcome is the default, so with no --yes it prints the lane and refuses.",
+  "",
+  "Wraps PUT/GET/DELETE /api/control/handoff-context (Neon control plane). Self-purging:",
+  "`record` overwrites in place on the lane key (not append); rows expire on a",
+  "server TTL. Coordination ONLY \u2014 durable knowledge goes to vault memory and is",
+  "rejected by the endpoint.",
+  "",
+  "`hs handoff <CODE>` LAUNCHES by default (owner ruling 2026-09-01, [[HS-RVKN]]:",
+  "why else would the command be typed if not to launch it?) \u2014 it resolves the",
+  "lane FIRST (an empty/expired lane refuses before any launch call, exit 10),",
+  "prints the lane summary so you see what you're resuming, then POSTs the SAME",
+  "/api/agent/start the What's Next Launch button uses (launchUseCase: handoff)",
+  "\u2014 never a second launcher, never a spawn from this CLI process itself.",
+  "`--no-launch` skips the launch and prints the summary only \u2014 the machine-safe",
+  "equivalent is the spelled-out `hs handoff load --lane <CODE>` (no --launch),",
+  "which never defaults to launching. `--launch` on the shorthand is a harmless",
+  "explicit alias (already the default). `--dry-run` prints the resolved",
+  "agent/model/prompt without spawning, and composes with the shorthand exactly",
+  "like `--model`/`--permission-mode` \u2014 none of the three require an explicit",
+  "`--launch` on the bare-code form any more. Not valid on `record` or with",
+  "`--all`.",
+  "",
+  "One lane opens ONE window: the route holds a 5-minute in-flight marker per",
+  "lane, so a repeat `hs handoff <CODE>` prints `already active (in_flight)`",
+  "instead of spawning a second terminal. That is what stops a launched session",
+  "which re-runs the bare form from opening an endless chain of windows. Pass",
+  "`--force` when you actually want the window re-opened.",
+  "",
+  `\`hs handoff model <value>\` accepts an exact model id (e.g. ${ANTHROPIC2.PREVIOUS_STRONG},`,
+  "pinned byte-for-byte) OR a version-less alias that tracks the latest of a",
+  "family as Claude updates it: claude-opus, claude-sonnet, claude-fable,",
+  "claude-haiku, or the bare opus/sonnet/fable/haiku forms. An alias is stored",
+  "in its canonical claude-<family> form and resolved at launch/dry-run time \u2014",
+  "`hs handoff model` (no value) and `--dry-run` show both the tracking form",
+  "and what it resolves to right now.",
+  "",
+  "`--model <value>` on a launch overrides the resolved model for THIS launch",
+  "only, above the spec/settings default \u2014 the stored `hs handoff model`",
+  "default is untouched. Same vocabulary as `hs handoff model <value>` (exact",
+  "id or alias); unknown values are refused before any request is sent. Not",
+  "valid without launching (bare-code default, or spelled-out --launch), or on",
+  "record/model.",
+  "",
+  "`--permission-mode <mode>` on a launch overrides the resolved",
+  "`claude --permission-mode` for THIS launch only, above the per-agent",
+  "`launchPermissions.handoff.{claudeCode,cursorAgent}` settings default (set",
+  `via \`hs handoff permission-mode <value>\`, not this flag). Valid modes: ${ALL_LAUNCH_PERMISSION_MODE_OPTIONS.join(", ")}`,
+  "(the exact `claude --help` vocabulary) \u2014 unknown values are refused before",
+  "any request is sent. Not valid without launching, or on record/model. Unset",
+  "(no flag, no settings default) means no --permission-mode reaches the",
+  "spawned claude CLI \u2014 its own default prompting mode. bypassPermissions",
+  "means the spawned session skips ALL permission prompts \u2014 trusted repos",
+  "only. cursor-agent has no equivalent flag; a requested override is ignored",
+  "with a printed note.",
+  "",
+  "`hs handoff permission-mode [<value>]` ([[HS-TG56]]) prints (no value) or",
+  "sets (a value) the DEFAULT `--permission-mode` for the ACTIVE handoff agent",
+  "\u2014 `launchPermissions.handoff.claudeCode`, written via PUT /api/settings,",
+  "using the SAME dry-run resolution `model`/`--dry-run` use to find the active",
+  "agent. Validated against that agent's own vocabulary: claude-code accepts",
+  `${CLAUDE_PERMISSION_MODE_OPTIONS.join(", ")}`,
+  "; cursor-agent has none yet, so a cursor-active session refuses the set with",
+  "a plain not-supported-yet message and writes nothing. An unknown value on",
+  "claude-code is refused with that list, writing nothing. Setting",
+  "bypassPermissions prints a one-line trusted-repos caveat after the",
+  'confirmation. No value with nothing configured prints "unset" plainly \u2014',
+  "claude's own default prompting mode applies.",
+  "",
+  "Flags:",
+  "  --lane <key>     Lane identity (default: the detected session id).",
+  "  --agent <name>   Writing agent (default: detected identity).",
+  "  --session <id>   Session id (default: detected identity; also default lane).",
+  "  --spec <id>      Current spec id (record).",
+  '  --phase <label>  Short phase label, e.g. "slice" (record).',
+  '  --time <est>     Human time estimate, e.g. "~2h" (record).',
+  "  --blocker <line> A coordination blocker; repeatable (record).",
+  "  --link <id>      A relevant spec id/link; repeatable (record).",
+  "  --all            List every active lane (load).",
+  "  --new-code       Mint the lane code instead of naming one (record only).",
+  "  --yes, -y        Confirm a delete. Without it, delete prints and refuses.",
+  "  --launch         Launch the resolved lane's resume session. Default true on the",
+  "                   bare-code shorthand (this flag is then a harmless no-op alias);",
+  "                   opt-in on the spelled-out `load` form.",
+  "  --no-launch      Bare-code shorthand only: print the resolved summary, don't launch.",
+  "  --dry-run        Resolve + print the launch target, don't spawn.",
+  "  --model <value>  One-off model override for this launch only.",
+  "  --permission-mode <mode>  One-off permission-mode override for this launch only.",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found (empty/expired lane) \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-handoff.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 handoff: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process3.exitCode = EXIT.USAGE;
+    return;
+  }
+  const parsed = parseHandoffArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${HELP2}
+`);
+    process3.exitCode = EXIT.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs handoff: ${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 handoff: ${scoped.error.message}
+`);
+    process3.exitCode = scoped.error.code;
+    return;
+  }
+  const result = await runHandoff(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 handoff", main, { fallbackCode: EXIT.WRITE_FAILED });