heyspex 0.2.4 → 0.2.6

package/dist/cli/hs-next-launch.mjs

@@ -0,0 +1,2698 @@
+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-next-launch.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/vault-id.ts
+var FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
+function normalizeBareSpecIdToken(input) {
+  const token = String(input ?? "").trim().toUpperCase();
+  if (!token) return null;
+  if (token.startsWith("HS-")) return token;
+  const head = token.split("-")[0];
+  return FILE_KEY_RE.test(head) ? `HS-${token}` : null;
+}
+
+// spex-console/src/lib/launch-preferences.ts
+var NEXT_LAUNCH_KINDS = ["milestone", "epic", "sprint", "task"];
+function isNextLaunchKind(value) {
+  return NEXT_LAUNCH_KINDS.includes(value);
+}
+function launchUseCaseForKind(kind) {
+  return kind === "task" ? "task-implementation" : kind;
+}
+var USE_CASE_SETTINGS_KEY = {
+  "task-creation": "taskCreation",
+  "task-implementation": "taskImplementation",
+  handoff: "handoff",
+  milestone: "milestone",
+  epic: "epic",
+  sprint: "sprint"
+};
+function launchSettingsBucketKey(useCase) {
+  return USE_CASE_SETTINGS_KEY[useCase];
+}
+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/model-registry/types.ts
+function isLaunchBackend(v) {
+  return v === "anthropic" || v === "ollama" || v === "deepseek";
+}
+
+// spex-console/src/lib/cli/backend.ts
+var LAUNCH_BACKENDS = ["anthropic", "ollama", "deepseek"];
+var BACKEND_VALID_SET_MESSAGE = `valid backends: ${LAUNCH_BACKENDS.join(", ")}`;
+function isKnownBackendValue(raw) {
+  return isLaunchBackend(raw);
+}
+function unknownBackendMessage(raw) {
+  return `unknown backend "${raw}" \u2014 ${BACKEND_VALID_SET_MESSAGE}`;
+}
+function maskBackendEnvValue(key, value) {
+  if (key !== "ANTHROPIC_API_KEY") return value;
+  const last4 = value.length > 4 ? value.slice(-4) : value;
+  return `****${last4}`;
+}
+async function resolveKindBackend(kind, deps) {
+  const res = await controlRequest(deps, {
+    method: "POST",
+    path: "/api/agent/start",
+    body: { prompt: "/hs-next", launchUseCase: launchUseCaseForKind(kind), dryRun: true }
+  });
+  if (!res.ok) return { ok: false, error: res.error };
+  if (res.status !== 200) return { ok: false, error: writeFailed(res.status, res.body) };
+  const c = res.body ?? {};
+  return {
+    ok: true,
+    value: {
+      kind,
+      agent: typeof c.agent === "string" ? c.agent : "claude-code",
+      backend: typeof c.backend === "string" ? c.backend : "anthropic",
+      backendSource: typeof c.backendSource === "string" ? c.backendSource : "?"
+    }
+  };
+}
+async function resolveAllKindsBackend(deps) {
+  const out = [];
+  for (const kind of NEXT_LAUNCH_KINDS) {
+    const r = await resolveKindBackend(kind, deps);
+    if (!r.ok) return r;
+    out.push(r.value);
+  }
+  return { ok: true, value: out };
+}
+async function resolveBackendRows(kind, deps) {
+  if (kind) {
+    const one = await resolveKindBackend(kind, deps);
+    return one.ok ? { ok: true, rows: [one.value] } : one;
+  }
+  const all = await resolveAllKindsBackend(deps);
+  return all.ok ? { ok: true, rows: all.value } : all;
+}
+async function runNextBackend(args, deps) {
+  if (args.value === void 0) {
+    const resolved = await resolveBackendRows(args.kind, deps);
+    if (!resolved.ok) return resolved.error;
+    return {
+      code: EXIT.OK,
+      message: resolved.rows.map(
+        (r) => `${r.kind.padEnd(9)} backend: ${r.backend} (source: ${r.backendSource}, agent: ${r.agent})`
+      ).join("\n"),
+      payload: { ok: true, kinds: resolved.rows },
+      isError: false
+    };
+  }
+  if (!args.kind) {
+    return {
+      code: EXIT.USAGE,
+      message: `hs next backend needs a kind before a value \u2014 which kind of launch is "${args.value}" for? e.g. hs next backend epic ${args.value} (kinds: ${NEXT_LAUNCH_KINDS.join(", ")})`,
+      payload: { ok: false, error: "kind_required", value: args.value },
+      isError: true
+    };
+  }
+  if (!isKnownBackendValue(args.value)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: unknownBackendMessage(args.value),
+      payload: { ok: false, error: "invalid_backend", value: args.value, kind: args.kind },
+      isError: true
+    };
+  }
+  const settingsKey = launchSettingsBucketKey(launchUseCaseForKind(args.kind));
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchModels: { [settingsKey]: { claudeCodeBackend: args.value } } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: `${args.kind} default backend set -> ${args.value}.`,
+    payload: { ok: true, kind: args.kind, backend: args.value },
+    isError: false
+  };
+}
+
+// spex-console/src/lib/cli/next.ts
+var ALL_LAUNCH_MODEL_OPTIONS = [...CLAUDE_LAUNCH_MODEL_OPTIONS, ...CURSOR_LAUNCH_MODEL_OPTIONS];
+var ALL_LAUNCH_PERMISSION_MODE_OPTIONS = [
+  ...CLAUDE_PERMISSION_MODE_OPTIONS,
+  ...CURSOR_PERMISSION_MODE_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];
+}
+function isKnownPermissionModeValue(value, options) {
+  return options.includes(value);
+}
+var FRONT_TOKENS = {
+  handheld: "handheld",
+  assist: "assisted",
+  assisted: "assisted",
+  auto: "autonomous",
+  autonomous: "autonomous"
+};
+function buildNextPrompt(args) {
+  const parts = ["/hs-next"];
+  if (args.front && args.front !== "handheld") parts.push(args.front);
+  if (args.specId) parts.push(args.specId);
+  return parts.join(" ");
+}
+function validateLaunchFlags(args) {
+  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 next <id> --launch --force)"
+    };
+  }
+  if (args.autoClaim !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--claim/--no-claim require --launch (set the default with: hs next claim on|off)"
+    };
+  }
+  if (args.modelOverride !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--model requires --launch (e.g. hs next <id> --model <value> --launch)"
+    };
+  }
+  if (args.modelOverride !== void 0 && !isKnownModelValue(args.modelOverride, ALL_LAUNCH_MODEL_OPTIONS)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown model "${args.modelOverride}". Valid options: ${validModelOptionsList(ALL_LAUNCH_MODEL_OPTIONS).join(", ")}`
+    };
+  }
+  if (args.permissionModeOverride !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--permission-mode requires --launch (e.g. hs next <id> --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(", ")}`
+    };
+  }
+  if (args.backendOverride !== void 0 && !args.launch) {
+    return {
+      code: EXIT.USAGE,
+      message: "--backend requires --launch (e.g. hs next <id> --backend <value> --launch)"
+    };
+  }
+  if (args.backendOverride !== void 0 && !isKnownBackendValue(args.backendOverride)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: unknownBackendMessage(args.backendOverride)
+    };
+  }
+  return null;
+}
+function parseDefaultsTail(sub, argv) {
+  const args = { sub, launch: false, json: false };
+  const positionals = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") args.json = true;
+    else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else positionals.push(arg);
+  }
+  if (positionals.length > 2) {
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${positionals[2]}` } };
+  }
+  const [first, second] = positionals;
+  if (first !== void 0) {
+    if (!isNextLaunchKind(first)) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: `"${first}" is not a launch kind. Usage: hs next ${sub} [<kind>] [<value>] \u2014 kinds: ${NEXT_LAUNCH_KINDS.join(", ")}`
+        }
+      };
+    }
+    args.kind = first;
+  }
+  if (second !== void 0) {
+    if (sub === "model") args.modelValue = second;
+    else args.permissionModeValue = second;
+  }
+  return { args };
+}
+function parseBackendTail(argv) {
+  const args = { sub: "backend", launch: false, json: false };
+  const positionals = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") args.json = true;
+    else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else positionals.push(arg);
+  }
+  if (positionals.length > 2) {
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${positionals[2]}` } };
+  }
+  const [first, second] = positionals;
+  if (first !== void 0) {
+    if (!isNextLaunchKind(first)) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: `"${first}" is not a launch kind. Usage: hs next backend [<kind>] [<value>] \u2014 kinds: ${NEXT_LAUNCH_KINDS.join(", ")}`
+        }
+      };
+    }
+    args.kind = first;
+  }
+  if (second !== void 0) args.backendValue = second;
+  return { args };
+}
+function parseClaimTail(argv) {
+  const args = { sub: "claim", launch: false, json: false };
+  const positionals = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") args.json = true;
+    else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${positionals[1]}` } };
+  }
+  const value = positionals[0];
+  if (value !== void 0) {
+    const normalized = value.toLowerCase();
+    if (normalized === "on" || normalized === "auto" || normalized === "true") {
+      args.claimValue = true;
+    } else if (normalized === "off" || normalized === "manual" || normalized === "ask" || normalized === "false") {
+      args.claimValue = false;
+    } else {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: `"${value}" is not a claim mode. Use: hs next claim on|off (aliases: auto | manual).`
+        }
+      };
+    }
+  }
+  return { args };
+}
+function parseFrontTail(argv) {
+  const args = { sub: "front", launch: false, json: false };
+  const positionals = [];
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") args.json = true;
+    else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else positionals.push(arg);
+  }
+  if (positionals.length > 1) {
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${positionals[1]}` } };
+  }
+  const value = positionals[0];
+  if (value !== void 0) {
+    const normalized = FRONT_TOKENS[value.toLowerCase()];
+    if (!normalized) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: `"${value}" is not a front. Use: hs next front handheld|assist|auto.`
+        }
+      };
+    }
+    args.frontValue = normalized;
+  }
+  return { args };
+}
+function parseNextConsoleArgs(argv) {
+  const first = argv[0];
+  if (first === "--help" || first === "-h" || first === void 0) return { help: true };
+  if (first === "model" || first === "permission-mode") return parseDefaultsTail(first, argv);
+  if (first === "backend") return parseBackendTail(argv);
+  if (first === "claim") return parseClaimTail(argv);
+  if (first === "front") return parseFrontTail(argv);
+  const args = { sub: "launch", launch: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: 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 === "--claim") args.autoClaim = true;
+    else if (arg === "--no-claim") args.autoClaim = false;
+    else if (arg === "--json") args.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" } };
+      }
+      args.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" } };
+      }
+      args.permissionModeOverride = v;
+    } else if (arg === "--backend" || arg.startsWith("--backend=")) {
+      const v = arg.startsWith("--backend=") ? arg.slice("--backend=".length) : argv[++i];
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--backend requires a value" } };
+      }
+      args.backendOverride = v;
+    } else if (arg === "--front" || arg.startsWith("--front=")) {
+      const v = arg.startsWith("--front=") ? arg.slice("--front=".length) : argv[++i];
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--front requires a value" } };
+      }
+      const normalized = FRONT_TOKENS[v.toLowerCase()];
+      if (!normalized) {
+        return {
+          error: {
+            code: EXIT.USAGE,
+            message: `unknown front: ${v} (expected ${Object.keys(FRONT_TOKENS).join(" | ")})`
+          }
+        };
+      }
+      args.front = normalized;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (FRONT_TOKENS[arg.toLowerCase()] !== void 0 && args.front === void 0) {
+      args.front = FRONT_TOKENS[arg.toLowerCase()];
+    } else if (args.specId === void 0) {
+      const normalized = normalizeBareSpecIdToken(arg);
+      if (!normalized) {
+        return {
+          error: {
+            code: EXIT.USAGE,
+            message: `"${arg}" is not a spec id (HS-CJV2) or a bare key (CJV2).`
+          }
+        };
+      }
+      args.specId = normalized;
+    } else {
+      const normalized = normalizeBareSpecIdToken(arg);
+      if (!normalized) {
+        return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+      }
+      (args.specIds ??= []).push(normalized);
+    }
+  }
+  if (args.specIds && args.front !== "assisted" && args.front !== "autonomous") {
+    return {
+      error: {
+        code: EXIT.USAGE,
+        message: `unexpected argument: ${args.specIds[0]} \u2014 several ids are accepted only for an assisted/autonomous run (hs next assist|auto <milestone\u2026> --launch); a handheld launch opens one agent on one spec.`
+      }
+    };
+  }
+  const flagError = validateLaunchFlags(args);
+  if (flagError) return { error: flagError };
+  return { args };
+}
+async function runNextLaunch(args, deps) {
+  if (args.front === "assisted" || args.front === "autonomous") return runNextArm(args, deps);
+  const prompt = buildNextPrompt(args);
+  const body = {
+    prompt,
+    ...args.dryRun ? { dryRun: true } : {},
+    ...args.force ? { force: true } : {},
+    ...args.autoClaim !== void 0 ? { autoClaim: args.autoClaim } : {},
+    ...args.modelOverride !== void 0 ? { modelOverride: args.modelOverride } : {},
+    ...args.permissionModeOverride !== void 0 ? { permissionModeOverride: args.permissionModeOverride } : {},
+    ...args.backendOverride !== void 0 ? { backendOverride: args.backendOverride } : {}
+  };
+  const res = await controlRequest(deps, { method: "POST", path: "/api/agent/start", body });
+  if (!res.ok) return res.error;
+  if (res.status === 400) {
+    const errorPayload = res.body ?? {};
+    if (errorPayload.error === "backend_not_ready") {
+      const message = typeof errorPayload.message === "string" ? errorPayload.message : "";
+      const fix = typeof errorPayload.fix === "string" ? errorPayload.fix : "";
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: message + (fix ? `
+${fix}` : ""),
+        payload: { ok: false, error: "backend_not_ready", ...errorPayload },
+        isError: true
+      };
+    }
+  }
+  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 useCase = typeof payload.launchUseCase === "string" ? payload.launchUseCase : "?";
+  const autoClaim = payload.autoClaim === true;
+  const launchPrompt = typeof payload.prompt === "string" ? payload.prompt : prompt;
+  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." : "";
+  const backend = typeof payload.backend === "string" ? payload.backend : null;
+  const backendSource = typeof payload.backendSource === "string" ? payload.backendSource : null;
+  const backendNote = typeof payload.note === "string" ? payload.note : null;
+  const backendEnvPreview = payload.backendEnvPreview && typeof payload.backendEnvPreview === "object" && !Array.isArray(payload.backendEnvPreview) ? payload.backendEnvPreview : null;
+  const backendLines = backend ? [
+    `  backend: ${backend} (${backendSource ?? "?"})`,
+    ...backendEnvPreview ? Object.entries(backendEnvPreview).map(
+      ([k, v]) => `    ${k}=${maskBackendEnvValue(k, String(v))}`
+    ) : [],
+    ...backendNote ? [`  note: ${backendNote}`] : []
+  ] : [];
+  if (args.dryRun) {
+    return {
+      code: EXIT.OK,
+      message: `[dry-run] would launch ${prompt}
+  agent:  ${agent}
+  kind:   ${useCase}
+  model:  ${modelDisplay} (source: ${modelSource})
+` + (permissionMode ? `  permission: ${permissionMode} (source: ${permissionModeSource})
+` : "") + (backendLines.length ? `${backendLines.join("\n")}
+` : "") + `  claim:  ${autoClaim ? "auto (no handshake)" : "manual (agent asks first)"}
+  prompt: ${launchPrompt}` + cursorPermissionModeNote,
+      payload: {
+        ok: true,
+        dryRun: true,
+        specId: args.specId ?? null,
+        agent,
+        launchUseCase: useCase,
+        model,
+        modelDisplay,
+        modelSource,
+        permissionMode,
+        permissionModeSource,
+        backend,
+        backendSource,
+        ...backendNote ? { note: backendNote } : {},
+        autoClaim,
+        prompt
+      },
+      isError: false
+    };
+  }
+  if (payload.alreadyActive) {
+    const reopen = `hs next ${args.specId ?? ""} --launch --force`.replace(/\s+/g, " ").trim();
+    return {
+      code: EXIT.OK,
+      message: `${prompt} is already active (${String(payload.reason ?? "in_flight")}).
+  re-open it anyway with: ${reopen}`,
+      payload: { ok: true, specId: args.specId ?? null, ...payload },
+      isError: false
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `Launched ${prompt} -> ${agent} (${model}, ${useCase}).
+  prompt: ${prompt}` + cursorPermissionModeNote,
+    payload: { ok: true, specId: args.specId ?? null, ...payload },
+    isError: false
+  };
+}
+async function resolveKind(kind, deps) {
+  const res = await controlRequest(deps, {
+    method: "POST",
+    path: "/api/agent/start",
+    body: {
+      prompt: "/hs-next",
+      launchUseCase: launchUseCaseForKind(kind),
+      dryRun: true
+    }
+  });
+  if (!res.ok) return { ok: false, error: res.error };
+  if (res.status !== 200) return { ok: false, error: writeFailed(res.status, res.body) };
+  const c = res.body ?? {};
+  const model = typeof c.model === "string" ? c.model : "?";
+  return {
+    ok: true,
+    value: {
+      kind,
+      agent: typeof c.agent === "string" ? c.agent : "claude-code",
+      model,
+      modelDisplay: typeof c.modelDisplay === "string" ? c.modelDisplay : model,
+      modelSource: typeof c.modelSource === "string" ? c.modelSource : "?",
+      permissionMode: typeof c.permissionMode === "string" && c.permissionMode ? c.permissionMode : null,
+      permissionModeSource: typeof c.permissionModeSource === "string" ? c.permissionModeSource : null,
+      autoClaim: c.autoClaim === true
+    }
+  };
+}
+async function resolveAllKinds(deps) {
+  const out = [];
+  for (const kind of NEXT_LAUNCH_KINDS) {
+    const r = await resolveKind(kind, deps);
+    if (!r.ok) return r;
+    out.push(r.value);
+  }
+  return { ok: true, value: out };
+}
+async function resolveRows(kind, deps) {
+  if (kind) {
+    const one = await resolveKind(kind, deps);
+    return one.ok ? { ok: true, rows: [one.value] } : one;
+  }
+  const all = await resolveAllKinds(deps);
+  return all.ok ? { ok: true, rows: all.value } : all;
+}
+async function runNextModel(args, deps) {
+  if (args.modelValue === void 0) {
+    const resolved2 = await resolveRows(args.kind, deps);
+    if (!resolved2.ok) return resolved2.error;
+    return {
+      code: EXIT.OK,
+      message: resolved2.rows.map(
+        (r) => `${r.kind.padEnd(9)} model: ${r.modelDisplay} (source: ${r.modelSource}, agent: ${r.agent})`
+      ).join("\n"),
+      payload: { ok: true, kinds: resolved2.rows },
+      isError: false
+    };
+  }
+  if (!args.kind) {
+    return {
+      code: EXIT.USAGE,
+      message: `hs next model needs a kind before a value \u2014 which kind of launch is "${args.modelValue}" for? e.g. hs next model epic ${args.modelValue} (kinds: ${NEXT_LAUNCH_KINDS.join(", ")})`,
+      payload: { ok: false, error: "kind_required", value: args.modelValue },
+      isError: true
+    };
+  }
+  const resolved = await resolveKind(args.kind, deps);
+  if (!resolved.ok) return resolved.error;
+  const currentAgent = resolved.value.agent;
+  const options = currentAgent === "cursor-agent" ? CURSOR_LAUNCH_MODEL_OPTIONS : CLAUDE_LAUNCH_MODEL_OPTIONS;
+  if (!isKnownModelValue(args.modelValue, options)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `unknown model "${args.modelValue}" for agent ${currentAgent}. Valid options: ${validModelOptionsList(options).join(", ")}`,
+      payload: {
+        ok: false,
+        error: "invalid_model",
+        value: args.modelValue,
+        agent: currentAgent,
+        kind: args.kind
+      },
+      isError: true
+    };
+  }
+  const valueToStore = canonicalizeModelAlias(args.modelValue) ?? args.modelValue;
+  const bucketField = currentAgent === "cursor-agent" ? "cursorAgent" : currentAgent === "dev-factory-fleet" ? "fleet" : "claudeCode";
+  const settingsKey = launchSettingsBucketKey(launchUseCaseForKind(args.kind));
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchModels: { [settingsKey]: { [bucketField]: valueToStore } } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: `${args.kind} default model set -> ${valueToStore} (agent: ${currentAgent}).`,
+    payload: { ok: true, kind: args.kind, model: valueToStore, agent: currentAgent },
+    isError: false
+  };
+}
+async function runNextPermissionMode(args, deps) {
+  if (args.permissionModeValue === void 0) {
+    const resolved2 = await resolveRows(args.kind, deps);
+    if (!resolved2.ok) return resolved2.error;
+    return {
+      code: EXIT.OK,
+      message: resolved2.rows.map(
+        (r) => r.permissionMode ? `${r.kind.padEnd(9)} permission-mode: ${r.permissionMode} (source: ${r.permissionModeSource}, agent: ${r.agent})` : `${r.kind.padEnd(9)} permission-mode: unset (agent: ${r.agent}) \u2014 claude's own default prompting applies.`
+      ).join("\n"),
+      payload: { ok: true, kinds: resolved2.rows },
+      isError: false
+    };
+  }
+  if (!args.kind) {
+    return {
+      code: EXIT.USAGE,
+      message: `hs next permission-mode needs a kind before a value \u2014 which kind of launch is "${args.permissionModeValue}" for? e.g. hs next permission-mode task ${args.permissionModeValue} (kinds: ${NEXT_LAUNCH_KINDS.join(", ")})`,
+      payload: { ok: false, error: "kind_required", value: args.permissionModeValue },
+      isError: true
+    };
+  }
+  const resolved = await resolveKind(args.kind, deps);
+  if (!resolved.ok) return resolved.error;
+  const currentAgent = resolved.value.agent;
+  if (currentAgent !== "claude-code") {
+    return {
+      code: EXIT.USAGE,
+      message: `hs next permission-mode is not supported for agent ${currentAgent} yet (no --permission-mode equivalent). The active ${args.kind} launch agent must be claude-code.`,
+      payload: { ok: false, error: "unsupported_agent", agent: currentAgent, kind: args.kind },
+      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,
+        kind: args.kind,
+        validOptions: CLAUDE_PERMISSION_MODE_OPTIONS
+      },
+      isError: true
+    };
+  }
+  const settingsKey = launchSettingsBucketKey(launchUseCaseForKind(args.kind));
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchPermissions: { [settingsKey]: { 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: `${args.kind} default permission-mode set -> ${args.permissionModeValue} (agent: ${currentAgent}).${bypassCaveat}`,
+    payload: {
+      ok: true,
+      kind: args.kind,
+      permissionMode: args.permissionModeValue,
+      agent: currentAgent
+    },
+    isError: false
+  };
+}
+async function runNextClaim(args, deps) {
+  if (args.claimValue === void 0) {
+    const resolved = await resolveKind("task", deps);
+    if (!resolved.ok) return resolved.error;
+    const on = resolved.value.autoClaim;
+    return {
+      code: EXIT.OK,
+      message: on ? "claim: auto \u2014 a launched agent claims its spec and starts, no handshake." : "claim: manual \u2014 a launched agent asks before it claims (the default).",
+      payload: { ok: true, autoClaim: on },
+      isError: false
+    };
+  }
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchModels: { autoClaimOnLaunch: args.claimValue } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: args.claimValue ? "claim default set -> auto. Launched agents claim and start with no handshake.\n  caveat: nothing pauses for you between launch and first edit \u2014 use --no-claim for a one-off ask." : "claim default set -> manual. Launched agents ask before they claim.",
+    payload: { ok: true, autoClaim: args.claimValue },
+    isError: false
+  };
+}
+var DISPATCHER_ENSURE_HINT = "node dev-factory/coo-dispatcher.mjs --ensure";
+var FRONT_DESCRIPTIONS = {
+  handheld: "handheld \u2014 `hs next <id>` walks down to one task and opens one agent on it, with you in the loop (the default).",
+  assisted: "assisted \u2014 `hs next <milestone>` arms a dispatcher run that pauses at decision gates for you.",
+  autonomous: "autonomous \u2014 `hs next <milestone>` arms an unattended dispatcher run; you review the retrospective after."
+};
+function readFrontFromSettings(body) {
+  const raw = body?.settings?.launchModels?.defaultRunMode;
+  return raw === "assisted" || raw === "autonomous" ? raw : "handheld";
+}
+async function runNextFront(args, deps) {
+  if (args.frontValue === void 0) {
+    const res2 = await controlRequest(deps, { method: "GET", path: "/api/settings" });
+    if (!res2.ok) return res2.error;
+    if (res2.status !== 200) return writeFailed(res2.status, res2.body);
+    const front = readFrontFromSettings(res2.body);
+    return {
+      code: EXIT.OK,
+      message: `front: ${FRONT_DESCRIPTIONS[front]}
+  override once: hs next assist|auto <id> (or --front <name>); set: hs next front <name>`,
+      payload: { ok: true, front },
+      isError: false
+    };
+  }
+  const res = await controlRequest(deps, {
+    method: "PUT",
+    path: "/api/settings",
+    body: { launchModels: { defaultRunMode: args.frontValue } }
+  });
+  if (!res.ok) return res.error;
+  if (res.status !== 200) return writeFailed(res.status, res.body);
+  return {
+    code: EXIT.OK,
+    message: `front default set -> ${args.frontValue}. ${FRONT_DESCRIPTIONS[args.frontValue]}
+` + (args.frontValue === "handheld" ? "  a bare `hs next <id>` asks to claim one task again." : "  a bare `hs next <milestone>` now offers to arm the run; `hs next handheld <id>` still opens one agent."),
+    payload: { ok: true, front: args.frontValue },
+    isError: false
+  };
+}
+async function runNextArm(args, deps) {
+  const front = args.front === "autonomous" ? "autonomous" : "assisted";
+  const word = front === "autonomous" ? "auto" : "assist";
+  const ids = [args.specId, ...args.specIds ?? []].filter(
+    (v) => typeof v === "string" && v !== ""
+  );
+  if (ids.length === 0) {
+    return {
+      code: EXIT.USAGE,
+      message: `an ${front} launch arms a dispatcher run and needs at least one milestone id: hs next ${word} <HS-MIL\u2026> --launch`,
+      payload: { ok: false, error: "usage" },
+      isError: true
+    };
+  }
+  const ignored = [
+    args.autoClaim !== void 0 ? "--claim/--no-claim" : null,
+    args.modelOverride !== void 0 ? "--model" : null,
+    args.permissionModeOverride !== void 0 ? "--permission-mode" : null,
+    args.backendOverride !== void 0 ? "--backend" : null
+  ].filter((v) => v !== null);
+  const ignoredNote = ignored.length > 0 ? `
+  note: ${ignored.join(", ")} apply to a handheld agent launch, not to a dispatcher run \u2014 ignored.` : "";
+  if (args.dryRun) {
+    return {
+      code: EXIT.OK,
+      message: `[dry-run] would arm ${front} run on ${ids.join(", ")}
+  writes: dev-factory/coo-queue.json (this order) + the run front \u2014 no process is spawned
+  then, if the dispatcher is not live: ${DISPATCHER_ENSURE_HINT}` + ignoredNote,
+      payload: { ok: true, dryRun: true, front, milestoneIds: ids },
+      isError: false
+    };
+  }
+  const res = await controlRequest(deps, {
+    method: "POST",
+    path: "/api/factory/run/launch",
+    body: { milestoneId: ids[0], milestoneIds: ids, front, arm: true }
+  });
+  if (!res.ok) return res.error;
+  const payload = res.body ?? {};
+  const detail = typeof payload.detail === "string" ? payload.detail : "";
+  if (res.status !== 200) {
+    if (!detail) return writeFailed(res.status, res.body);
+    const grainHint = /unknown or closed milestone/.test(detail) ? `
+  ${front} runs arm at milestone grain \u2014 pass a milestone id (see: hs milestone show <id>), or open one agent on a single spec with handheld: hs next <id> --launch` : "";
+    return {
+      code: res.status === 409 ? EXIT.CONFLICT : res.status === 501 ? EXIT.WRITE_FAILED : EXIT.INVALID_ARG,
+      message: `arm refused: ${detail}${grainHint}`,
+      payload,
+      isError: true
+    };
+  }
+  const live = payload.dispatcherLive === true;
+  const ensure = typeof payload.ensureCommand === "string" ? payload.ensureCommand : DISPATCHER_ENSURE_HINT;
+  return {
+    code: EXIT.OK,
+    message: `armed ${front} run on ${ids.join(", ")}
+  ${detail}
+` + (live ? "  dispatcher: live \u2014 it picks the queue up on its next tick" : `  dispatcher: not running \u2014 start it in a terminal: ${ensure}`) + "\n  watch: hs factory run status" + ignoredNote,
+    payload,
+    isError: false
+  };
+}
+async function runNextConsole(args, deps) {
+  if (args.sub === "model") return runNextModel(args, deps);
+  if (args.sub === "front") return runNextFront(args, deps);
+  if (args.sub === "permission-mode") return runNextPermissionMode(args, deps);
+  if (args.sub === "backend")
+    return runNextBackend({ kind: args.kind, value: args.backendValue }, deps);
+  if (args.sub === "claim") return runNextClaim(args, deps);
+  return runNextLaunch(args, deps);
+}
+var HELP2 = [
+  "Usage:",
+  "  hs next [<id>] [--summary] [--json]        Print the on-deck brief (no launch)",
+  "  hs next <id> --launch [--dry-run]          Resolve + LAUNCH a session on that spec",
+  "  hs next <id> --launch --force              Launch again even if a window is already opening",
+  "  hs next <id> --launch --claim              Auto-claim this launch (no handshake)",
+  "  hs next <id> --launch --model <value>      One-off model override for this launch",
+  "  hs next <id> --launch --permission-mode <mode>  One-off permission-mode override",
+  `  hs next <id> --launch --backend <${LAUNCH_BACKENDS.join("|")}>  One-off backend override`,
+  "  hs next model [<kind>] [<value>]           Print (or set) a kind's default model",
+  "  hs next permission-mode [<kind>] [<value>] Print (or set) a kind's default permission-mode",
+  "  hs next backend [<kind>] [<value>]         Print (or set) a kind's default backend",
+  "  hs next claim [on|off]                     Print (or set) the auto-claim default",
+  "  hs next front [handheld|assist|auto]       Print (or set) the default front",
+  "  hs next assist|auto <milestone\u2026> --launch  Arm a dispatcher run on one or more milestones",
+  "",
+  `Kinds: ${NEXT_LAUNCH_KINDS.join(", ")}. Each kind keeps its OWN default model and`,
+  "permission mode, because launching a milestone or an epic means breaking it",
+  "down while launching a task means writing code \u2014 different work, different",
+  "weight class. `sprint` is settable now and inert until sprints ship: no",
+  "SPRINT spec type is minted yet, so no launch resolves to it. Auto-claim is",
+  "deliberately NOT per-kind \u2014 it answers 'am I still asked before work starts',",
+  "which is one answer for the whole session.",
+  "",
+  "A bare key works everywhere an id does \u2014 `hs next CJV2` is `hs next HS-CJV2`.",
+  "",
+  "Fronts. handheld opens ONE agent on ONE spec with you in the loop \u2014 the",
+  "launch above. assist / auto do not open a terminal: they arm a dispatcher",
+  "run over the milestone(s) you name, by writing the same queue + front files",
+  "the What's Next Run button writes for the already-running coo-dispatcher",
+  "(assisted pauses at decision gates for you; autonomous applies the",
+  "recommended option and reports after). Several milestone ids queue in the",
+  "order given. `hs next front <name>` stores the default; a front word on the",
+  "command overrides it for that call only. Cold-starting the dispatcher stays",
+  "a terminal job \u2014 the reply prints the --ensure command when it is not live.",
+  "",
+  "Launch is OPT-IN here, unlike `hs handoff <CODE>` which launches by default:",
+  "bare `hs next` already has a job \u2014 printing the on-deck brief \u2014 so it keeps",
+  "doing that. `--launch` POSTs the SAME /api/agent/start the What's Next Launch",
+  "button uses, never a second launcher and never a spawn from this CLI process.",
+  "The route reads the KIND off the spec id and pulls that kind's model +",
+  "permission mode from settings. `--dry-run` prints the resolved",
+  "agent/kind/model/claim/prompt without spawning.",
+  "",
+  "One target opens ONE window: the route holds a short in-flight marker, so a",
+  "repeat launch prints `already active` instead of opening a second terminal.",
+  "Pass `--force` when you actually want it re-opened.",
+  "",
+  "`hs next model <kind> <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 next model` (no value) shows both the tracking",
+  "form and what it resolves to right now, for every kind at once.",
+  "",
+  "`--model` / `--permission-mode` / `--backend` / `--claim` on a launch override",
+  "the resolved value for THAT launch only, above the settings default \u2014 the",
+  "stored defaults are untouched. Unknown values are refused before any",
+  "request is sent. None of them is valid without --launch.",
+  "",
+  `Valid permission modes: ${CLAUDE_PERMISSION_MODE_OPTIONS.join(", ")}`,
+  "(the exact `claude --help` vocabulary). Unset \u2014 no flag, no settings default",
+  "\u2014 means no --permission-mode reaches the spawned claude CLI, 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, and setting a",
+  "default on a cursor-active kind is refused with a plain not-supported-yet",
+  "message.",
+  "",
+  `${BACKEND_VALID_SET_MESSAGE}. Which model service answers a claude-code`,
+  "launch: `anthropic` (default, api.anthropic.com), `ollama` (a local model",
+  "server on localhost:11434) or `deepseek` (DeepSeek's Anthropic-compatible",
+  "endpoint). `hs next backend <kind> <value>` sets the per-kind default",
+  "(`launchModels.<kind>.claudeCodeBackend`); `--backend <value>` on a launch",
+  "overrides it for that launch only, never persisted. A dry-run prints the",
+  "resolved backend, its source, and the environment it would set \u2014 any secret",
+  "(ANTHROPIC_API_KEY) masked to its last four characters, never shown in full.",
+  "Applies to the claude-code agent only; every other agent always resolves to",
+  "anthropic.",
+  "",
+  "Flags:",
+  "  --launch         Launch a session on the resolved target.",
+  "  --dry-run        Resolve + print the launch target, don't spawn.",
+  "  --force          Launch again even if this target already has a window opening.",
+  "  --claim          Auto-claim on this launch (skip the confirm handshake).",
+  "  --no-claim       Ask before claiming on this launch, whatever the default is.",
+  "  --front <name>   handheld | assist | auto \u2014 forwarded into the prompt.",
+  "  --model <value>  One-off model override for this launch only.",
+  "  --permission-mode <mode>  One-off permission-mode override for this launch only.",
+  `  --backend <value>  One-off backend override for this launch only (${LAUNCH_BACKENDS.join(" | ")}).`,
+  "  --json           Emit a machine-readable JSON result.",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 12 console-unreachable \xB7",
+  "13 server-error \xB7 14 neon-required"
+].join("\n");
+
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
+// spex-console/bin/hs-next-launch.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 next: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process3.exitCode = EXIT.USAGE;
+    return;
+  }
+  const parsed = parseNextConsoleArgs(process3.argv.slice(3));
+  if (parsed.help) {
+    process3.stdout.write(`${HELP2}
+`);
+    process3.exitCode = EXIT.OK;
+    return;
+  }
+  if (parsed.error) {
+    process3.stderr.write(`hs next: ${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 next: ${scoped.error.message}
+`);
+    process3.exitCode = scoped.error.code;
+    return;
+  }
+  const result = await runNextConsole(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 next", main, { fallbackCode: EXIT.WRITE_FAILED });