heyspex 0.1.0

package/bin/hs.mjs

@@ -0,0 +1,1028 @@
+#!/usr/bin/env node
+/**
+ * hs — HeySpex vault CLI (foundation for indexer / future commands).
+ *
+ * Per [[HS-TASK-DE5Z-hs-index-rebuild]] and [[HS-EPIC-0027-implement-hs-bd-successor-m4-cli-mcp]].
+ *
+ * Dispatcher only: parses `hs <namespace> <command>`, locates the vault root,
+ * and delegates to the matching implementation inside `spex-console/bin/`.
+ *
+ * Implementations live in spex-console/ because they import the TypeScript indexer
+ * service directly. tsx (a workspace devDep, hoisted to the repo-root
+ * node_modules) executes the .ts entrypoints.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { runtimeFilesCheckRow } from "../scripts/lib/standalone-doctor.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, "..");
+
+// Captured before anything in this process could ever chdir (it doesn't
+// today, but every dispatched entry below is spawned with its own `cwd`
+// override — see dispatchSpexConsoleEntry). This is the ONE true record of
+// where the caller actually invoked `hs` from; forward it (HS_INVOKED_CWD)
+// to every dispatched entry whose cwd-derived logic must resolve the
+// caller's repo, not the platform checkout dir the entry is spawned in
+// (dispatchSpexConsoleEntry's spawns run with cwd=spex-console/; several raw
+// spawns below run with cwd=PKG_ROOT). Set on process.env itself (rather than
+// threaded through each individual spawn call) so it reaches EVERY dispatch —
+// both the ones that build `env` by spreading `...process.env` and the ones
+// that pass no `env` override at all and so inherit process.env verbatim —
+// without having to touch every call site. Per
+// [[HS-NXNP-36X3-DIAG-the-hs-launcher-loses-the-caller-s]]: `hs connect` was
+// the first verb fixed this way (its own `HS_INVOKED_CWD` env entry below is
+// now redundant with this but kept — see the connect dispatch — as it costs
+// nothing and documents the specific need).
+const INVOKED_CWD = process.cwd();
+process.env.HS_INVOKED_CWD = INVOKED_CWD;
+
+/**
+ * Walk up from `start` until we find a directory containing `specs/`.
+ * That directory is the vault root.
+ */
+function findVaultRoot(start) {
+  let dir = path.resolve(start);
+  while (true) {
+    const candidate = path.join(dir, "specs");
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Extract the global `hs --vault <id> <subcommand>` one-shot override
+ * ([[HS-Q1HZ-TASK-hs-vault-cli-list-register-switch-active]]). `--vault`
+ * (or `--vault=<id>`) may appear anywhere in argv -- it is stripped out here
+ * so the remaining tokens parse as a normal `hs <namespace> <command>`
+ * invocation; the extracted id is forwarded via `HS_VAULT_ID_OVERRIDE` env
+ * to whatever entry gets dispatched. This never mutates the persisted active
+ * pointer -- it only feeds `resolveActiveVaultRoot`'s `options.vaultId` for
+ * that one invocation (consumed today by `hs vault active`).
+ */
+function extractGlobalVaultFlag(argv) {
+  const idx = argv.findIndex(
+    (a) => a === "--vault" || a.startsWith("--vault="),
+  );
+  if (idx === -1) return { vaultIdOverride: undefined, rest: argv };
+  const arg = argv[idx];
+  if (arg.startsWith("--vault=")) {
+    return {
+      vaultIdOverride: arg.slice("--vault=".length),
+      rest: [...argv.slice(0, idx), ...argv.slice(idx + 1)],
+    };
+  }
+  return {
+    vaultIdOverride: argv[idx + 1],
+    rest: [...argv.slice(0, idx), ...argv.slice(idx + 2)],
+  };
+}
+
+function usage() {
+  process.stdout.write(
+    [
+      "hs — HeySpex vault CLI",
+      "",
+      "Usage:",
+      "  hs login [--console-url <url>] [--label <t>] [--json]  Sign in via your browser (no code to type)",
+      "  hs init [--console-url <url>] [--force]     Write the heyspex.yaml vault marker",
+      "  hs install [--target <dir>] [--platform <dir>]  Bootstrap vault + Cursor/Claude MCP",
+      "  hs invite [<name>]                     Mint a short pairing code (other computer: hs join CODE)",
+      "  hs join <code>                         Join with a pairing code (LAN auto-find; no IP to type)",
+      "  hs join [<repo>] [--dir d] [--code c] [--at url] [--profile p] [--skip steps] [--json] [--yes]  Fresh-machine onboarding (clone → toolchain → deps → doctor → agent layer → secrets → verify)",
+      "  hs vault list|register|switch|active         Manage registered vaults + active pointer",
+      "  hs workspace list|create|switch              Manage registered workspaces (company containers)",
+      "  hs connect [--dry-run] [--json] | --check [--json]  Detect+scaffold+register this repo (or read-only check)",
+      "  hs --vault <id> <subcommand>                 One-shot vault override for this invocation",
+      "  hs doctor [--fix] [--json] [--check-gateway]  Check every install surface; --fix repairs what it can",
+      "  hs gateway validate [slug] [--json]        Validate user-authored gateway skills (.heyspex/skills/user/)",
+      "  hs mode on|off|status|toggle               Master switch: HeySpex layer on or off (restart Claude Code)",
+      "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
+      "  hs setup claude|cursor [--check|--uninstall]  Install agent lifecycle hooks",
+      "  hs skills sync|check                       Propagate skills to Cursor/Codex/Claude (cwd-safe)",
+      "  hs index rebuild [--verbose] [--dry-run]   Full idempotent rebuild of the index",
+      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply)",
+      "  hs milestone show <id> [--json]            Show a milestone (flags needs-breakdown when epicless)",
+      "  hs factory status|fleet|results [--json]   Dev-Factory read-only status (fleet, routing, calibrations, results)",
+      "  hs factory run status [--json]             Live assisted/autonomous dispatcher run (pids, queue, stop hints)",
+      "  hs code-watcher scan [--json]              Capture build-correctness failures (tsc) → Resolution",
+      "  hs server status [--json]                  Ground-truth dev-server status (running? which port[s]?)",
+      "  hs view <surface> [spec-id] [--width N --height N --browser edge|chrome]  Open one surface in a chromeless app-mode window",
+      "  hs server stop [--json]                    Stop the spex-console dev server (any terminal)",
+      "  hs defer <id> [--until <when>] [--json]    Time-shift a spec (defer_until)",
+      "  hs undefer <id> [--json]                   Clear a spec's defer_until",
+      "  hs spawn [<id>] [--dry-run] [--json]       Launch a fresh /hs-next agent in a new terminal",
+      "  hs capture \"<text>\"|--clipboard|--file <p> [--add]  Capture → console drafts (--add chains a group)",
+      "  hs companion start|stop|status|build     Desktop companion tray app",
+      "  hs registry list [--json]                  List launch registry entries",
+      "  hs env init|set|list|run|export|rotate    Encrypted env vault (ADR-0020)",
+      "  hs env profiles | key export|import        Named profiles + second-machine key transfer",
+      "  hs env grant add|list|remove | key generate  Contractor/CI decrypt grants (ADR-0021)",
+      "  hs settings list|get|set                   Read/change workflow settings (.heyspex/config.yaml)",
+      "  hs classifier stats [--json] [--recent N]  Intent Classifier decision stats (read-only)",
+      "  hs next [spec_id] [--summary] [--json]     Resolve on-deck brief (MCP fallback)",
+      "  hs auto [filename] [--json]                Resolve /hs-auto dispatch plan",
+      "  hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]  One-shot MCP tool",
+      "  hs mcp pair <code> [--console-url <url>]   Redeem a console pairing code (cross-machine fallback for hs login)",
+      "  hs test run <id|manifest> [--format ...]   Run open-format API tests (Hurl/.http) per AC",
+      "  hs test gate [dir] [--report <j>] [--threshold n]  Mutation-testing gate — reject suites that kill no mutants",
+      "  hs test conform <spec> --url <u> | --report <x>    OpenAPI conformance / docs↔impl drift (Schemathesis)",
+      "  hs check run <id|manifest> [--json]        Verify acceptance criteria vs the frozen checks manifest (per-AC pass/fail)",
+      "  hs revalidate [--json] [--apply]           Re-run the frozen checks of already-stamped work; report what has decayed",
+      "  hs agent import <collection> <role>        Import a community agent into a type:agent vault spec",
+      "  hs agent list [collection]                 List vendored agent collections / roles",
+      "",
+      "Control plane (Neon — requires a reachable console):",
+      "  hs pin get|set <id>|clear                  Read/set/clear the on-deck pin",
+      "  hs claim acquire|release <id> | list       Atomic spec claims",
+      "  hs claim progress <id> --stage <verb>      Report live work-stage",
+      "  hs handoff record|load [--lane <k>]        Resume-context coordination",
+      "  hs events show <id> [--kind --since]       Per-spec audit log",
+      "  hs export-events [--since <date>]          Idempotent audit export → specs/events/",
+      "  hs prereq <blocked-id> [<action> <prereq>] Cross-milestone prerequisite resolution",
+      "  hs queue submit|next|claim|complete|fail|list  Fleet-queue dispatch (Neon, direct — no console hop)",
+      "",
+      "  hs <verb> --help                           Per-verb help",
+      "  hs --help                                  Show this help",
+      "  hs --version                               Show CLI version",
+      "",
+      "Vault root is detected by walking up from the current directory until a",
+      "specs/ folder is found. Override with HS_VAULT_ROOT.",
+      "",
+    ].join("\n"),
+  );
+}
+
+/**
+ * Run a spex-console-side TypeScript entrypoint (under `spex-console/bin/`) via
+ * tsx, passing `args` and the resolved vault root. Used by every `hs` verb whose
+ * implementation imports the spex-console TypeScript directly.
+ *
+ * Three cases, in order ([[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]):
+ *   1. Monorepo checkout: `.ts` source AND `tsx` both present — run via tsx,
+ *      exactly as before this task.
+ *   2. Published install of a BUNDLED verb (currently only `hs-init.ts` /
+ *      `hs-install.ts` — see `scripts/build-cli-bundle.mjs`'s doc comment
+ *      for why only these two): neither the source nor tsx exists, but
+ *      `dist/cli/<name>.mjs` does — run the plain-JS bundle directly with
+ *      `node`, no tsx/TypeScript involved.
+ *   3. Neither exists: the package install is incomplete (a verb this
+ *      package version never bundled, or a broken install) — same exit
+ *      code as before, reworded.
+ */
+function dispatchSpexConsoleEntry(entryFile, args, vaultRoot, extraEnv = {}) {
+  const consoleDir = path.join(PKG_ROOT, "spex-console");
+  const tsEntry = path.join(consoleDir, "bin", entryFile);
+  const tsxEntry = path.join(
+    PKG_ROOT,
+    "node_modules",
+    "tsx",
+    "dist",
+    "cli.mjs",
+  );
+  const bundleEntry = path.join(
+    PKG_ROOT,
+    "dist",
+    "cli",
+    entryFile.replace(/\.ts$/, ".mjs"),
+  );
+
+  const spawnEnv = { ...process.env, HS_VAULT_ROOT: vaultRoot, ...extraEnv };
+  let child;
+
+  if (existsSync(tsEntry) && existsSync(tsxEntry)) {
+    // Case 1 — monorepo: invoke tsx's ESM entry directly with node. This
+    // avoids npm's .cmd shim (which triggers Node 24's `shell:true`
+    // deprecation warning on Windows) and works identically across
+    // platforms. tsx is hoisted to the repo-root node_modules by the npm
+    // workspace install, not spex-console/node_modules.
+    child = spawn(process.execPath, [tsxEntry, tsEntry, ...args], {
+      cwd: consoleDir,
+      stdio: "inherit",
+      env: spawnEnv,
+    });
+  } else if (existsSync(bundleEntry)) {
+    // Case 2 — published install, verb was bundled: plain node, no tsx/TS.
+    // cwd is the CALLER's real invocation directory (not a spex-console/
+    // that doesn't exist in a published install) so a relative path the
+    // caller typed (e.g. `hs init --customer-vault vault`) resolves the
+    // same way it would for any other CLI the caller ran from that shell.
+    child = spawn(process.execPath, [bundleEntry, ...args], {
+      cwd: INVOKED_CWD,
+      stdio: "inherit",
+      env: spawnEnv,
+    });
+  } else {
+    // Case 3 — package incomplete: this verb has neither a monorepo source
+    // (with tsx) nor a bundled fallback.
+    process.stderr.write(
+      `hs: this package install is incomplete — no implementation for ` +
+        `\`${entryFile}\` (checked ${tsEntry}, ${bundleEntry}).\n` +
+        `    If you're in a source checkout, run \`npm install\` first.\n` +
+        `    If you installed the published \`heyspex\` package, this verb ` +
+        `is not yet available outside a source checkout.\n`,
+    );
+    process.exit(1);
+  }
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.exit(1);
+    }
+    process.exit(code ?? 0);
+  });
+  child.on("error", (err) => {
+    process.stderr.write(`hs: failed to spawn ${entryFile}: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+/**
+ * `hs doctor` when running from a published-package install (no
+ * `scripts/heyspex-doctor.mjs` on disk — that script only ships inside a
+ * source clone; see the dispatch site for why). Checks the one thing that
+ * genuinely applies here and is exactly what
+ * [[HS-BFXF-WBJU-DIAG-hs-never-resolves-on-a-fresh-machine]] is about: did
+ * `npm install` actually put the sibling `heyspex` / `heyspex-mcp` bins on
+ * PATH alongside this one. `hs` itself trivially "resolved" (this process IS
+ * it), so there is nothing to check about `hs` other than reporting its
+ * version.
+ */
+function runStandaloneDoctor(args) {
+  const jsonOut = args.includes("--json");
+  let version = "0.0.0";
+  try {
+    version =
+      JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf-8"))
+        .version || version;
+  } catch {
+    // fall through with the placeholder
+  }
+
+  const report = {
+    mode: "published-install",
+    version,
+    binPath: process.argv[1],
+    ok: true,
+    checks: [],
+  };
+  report.checks.push({
+    id: "hs-resolved",
+    status: "ok",
+    detail: `hs ${version} → ${process.argv[1]}`,
+  });
+
+  // `runtime-files` ([[HS-67ES-0JNK-TASK-fresh-install-honesty-statusline-only]]
+  // AC3): verifies the package's own runtime files (dynamic-imported/spawned
+  // by the MCP server and `hs source`, plus the two `dist/cli` bundles `hs
+  // init`/`hs install` dispatch to) actually exist next to THIS `bin/hs.mjs`
+  // — the check `hs doctor` did not have before, so a broken package (a
+  // runtime file missing from `package.json` `files`) passed every existing
+  // check and only surfaced on the customer's FIFTH command
+  // (`heyspex_preflight`'s `MODULE_NOT_FOUND`), not the first.
+  const runtimeFilesRow = runtimeFilesCheckRow(PKG_ROOT);
+  if (runtimeFilesRow.status !== "ok") report.ok = false;
+  report.checks.push(runtimeFilesRow);
+
+  const hsLinkLib = path.join(PKG_ROOT, "scripts", "lib", "hs-link.mjs");
+  if (existsSync(hsLinkLib)) {
+    // Deliberately synchronous top-level work below via a nested async IIFE
+    // — `missingSiblingBins` is a plain sync fs walk, but `import()` itself
+    // is async and this function must stay callable from a non-async call
+    // site without turning the whole dispatcher async.
+    import(pathToFileURL(hsLinkLib).href)
+      .then(({ missingSiblingBins }) => {
+        const strays = missingSiblingBins();
+        if (strays.length > 0) {
+          report.ok = false;
+          report.checks.push({
+            id: "sibling-bins-on-path",
+            status: "fail",
+            detail: `${strays.join(", ")} not on PATH`,
+            human:
+              `This \`hs\` resolved because it was invoked directly (npx, or ` +
+              `node_modules/.bin) — but ${strays.join(" / ")} will not resolve ` +
+              `from anywhere else on this machine unless you run ` +
+              "`npm install -g heyspex`.",
+          });
+        } else {
+          report.checks.push({
+            id: "sibling-bins-on-path",
+            status: "ok",
+            detail: "hs / heyspex / heyspex-mcp all resolve on PATH",
+          });
+        }
+        printStandaloneDoctorReport(report, jsonOut);
+      })
+      .catch(() => {
+        printStandaloneDoctorReport(report, jsonOut);
+      });
+    return;
+  }
+  printStandaloneDoctorReport(report, jsonOut);
+}
+
+function printStandaloneDoctorReport(report, jsonOut) {
+  if (jsonOut) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.ok ? 0 : 1);
+    return;
+  }
+  process.stdout.write(
+    "HeySpex setup check — published-package install (not a source clone)\n\n",
+  );
+  for (const check of report.checks) {
+    const label = check.status === "ok" ? "  ok  " : " FAIL ";
+    process.stdout.write(`[ ${label} ] ${check.detail}\n`);
+    if (check.human) process.stdout.write(`         ${check.human}\n`);
+  }
+  process.stdout.write(
+    "\nNote: the full `hs doctor` (git hooks, Cursor wiring, console secrets, and\n" +
+      "dozens of other source-checkout-only checks) only ships inside a clone of\n" +
+      "https://github.com/pwhermanson/workflow-protocol — this is the subset that\n" +
+      "applies to a published install.\n",
+  );
+  process.exit(report.ok ? 0 : 1);
+}
+
+function main(argv) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    usage();
+    process.exit(0);
+  }
+  if (argv[0] === "--version" || argv[0] === "-V") {
+    // Read root package.json for version. This file is ESM (no `require`
+    // in scope) — a prior version of this block called the undefined global
+    // `require(...)`, which threw and was silently swallowed by the catch
+    // below, so `hs --version` always printed the "0.0.0" fallback instead
+    // of the real version (found while proving the HS-BFXF fresh-install
+    // repro against a packed `heyspex` tarball).
+    try {
+      const pkg = JSON.parse(
+        readFileSync(path.join(PKG_ROOT, "package.json"), "utf-8"),
+      );
+      process.stdout.write(`hs ${pkg.version || "0.0.0"}\n`);
+    } catch {
+      process.stdout.write("hs 0.0.0\n");
+    }
+    process.exit(0);
+  }
+
+  const { vaultIdOverride, rest: argvAfterVaultFlag } =
+    extractGlobalVaultFlag(argv);
+  argv = argvAfterVaultFlag;
+
+  const namespace = argv[0];
+  const command = argv[1];
+  const rest = argv.slice(2);
+
+  const vaultRoot = process.env.HS_VAULT_ROOT || findVaultRoot(process.cwd());
+
+  // `hs init` writes the top-level heyspex.yaml vault marker
+  // ([[HS-EPIC-AEHR-audit-export-heyspex-yaml-and-heyspex-retirement]] §2). It
+  // may run on a fresh directory that has no specs/ yet, so it bypasses the
+  // hard vault gate below and falls back to the current directory.
+  if (namespace === "init") {
+    dispatchSpexConsoleEntry("hs-init.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
+  // `hs install` bootstraps a customer/project vault + agent MCP wiring. May run
+  // on a fresh directory with no specs/ yet (like init).
+  if (namespace === "install") {
+    dispatchSpexConsoleEntry(
+      "hs-install.ts",
+      argv,
+      vaultRoot || process.cwd(),
+      {
+        HS_PKG_ROOT: PKG_ROOT,
+      },
+    );
+    return;
+  }
+
+  // `hs join` — fresh-machine onboarding orchestrator (R18): clone → toolchain
+  // → deps → doctor → agent layer → secrets → verify. May run on a machine
+  // with no vault at all (that is its whole point), so it bypasses the hard
+  // vault gate like init/install. The launch cwd is forwarded because the
+  // dispatcher runs entries with cwd=spex-console.
+  if (namespace === "join") {
+    dispatchSpexConsoleEntry("hs-join.ts", argv, vaultRoot || process.cwd(), {
+      HS_JOIN_CWD: process.cwd(),
+    });
+    return;
+  }
+
+  // `hs invite` — TeamViewer-short host side. Alias of `hs env invite`
+  // (optional name defaults to "peer"). Needs a vault (this machine owns it).
+  if (namespace === "invite") {
+    if (!vaultRoot) {
+      process.stderr.write(
+        "hs: no vault detected — could not find a specs/ folder " +
+          "walking up from the current directory. " +
+          "Set HS_VAULT_ROOT or run from inside a vault.\n",
+      );
+      process.exit(1);
+    }
+    dispatchSpexConsoleEntry("hs-env.ts", ["env", "invite", ...argv.slice(1)], vaultRoot);
+    return;
+  }
+
+  // `hs setup claude|cursor` — install agent lifecycle hooks into the vault root.
+  if (namespace === "setup") {
+    const agent = command?.toLowerCase();
+    const SCRIPTS = {
+      claude: "install-claude-code-hooks.mjs",
+      cursor: "install-cursor-hooks.mjs",
+    };
+    if (!agent || !Object.hasOwn(SCRIPTS, agent)) {
+      process.stderr.write(
+        `hs setup: expected \`claude\` or \`cursor\` (got \`${command ?? ""}\`)\n` +
+          "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
+          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n",
+      );
+      process.exit(2);
+    }
+    const setupFlags = rest.filter(
+      (a) => a === "--check" || a === "--uninstall",
+    );
+    const script = path.join(PKG_ROOT, "scripts", SCRIPTS[agent]);
+    const target = vaultRoot || process.cwd();
+    const child = spawn(process.execPath, [script, ...setupFlags], {
+      cwd: target,
+      stdio: "inherit",
+      env: { ...process.env, HS_SETUP_TARGET: target },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(
+        `hs setup: failed to run ${SCRIPTS[agent]}: ${err.message}\n`,
+      );
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs skills sync|check` — propagate .commandcode/skills → Cursor/Codex/Claude shims.
+  if (namespace === "skills") {
+    const action = command?.toLowerCase();
+    if (action !== "sync" && action !== "check") {
+      process.stderr.write(
+        `hs skills: expected \`sync\` or \`check\` (got \`${command ?? ""}\`)\n` +
+          "  hs skills sync    Copy skills + slash shims to all agent harnesses\n" +
+          "  hs skills check   Exit 1 if any harness copy is stale\n",
+      );
+      process.exit(2);
+    }
+    const script = path.join(PKG_ROOT, "scripts", "sync-skills.mjs");
+    const target = vaultRoot || PKG_ROOT;
+    const childArgs = action === "check" ? ["--check"] : [];
+    const child = spawn(process.execPath, [script, ...childArgs], {
+      cwd: target,
+      stdio: "inherit",
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(
+        `hs skills: failed to run sync-skills.mjs: ${err.message}\n`,
+      );
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs vault list|register|switch|active` — the vault registry + active
+  // pointer CLI ([[HS-Q1HZ-TASK-hs-vault-cli-list-register-switch-active]]).
+  // May run outside any vault (registering a fresh directory, or listing/
+  // switching from anywhere), so it bypasses the hard vault gate below like
+  // init/install/setup.
+  if (namespace === "vault") {
+    dispatchSpexConsoleEntry("hs-vault.ts", argv, vaultRoot || process.cwd(), {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs workspace list|create|switch` — the workspace (company container)
+  // registry CLI ([[HS-Q1HZ-TASK-hs-workspace-cli-list-create-switch]]). Same
+  // no-vault-required rationale as `hs vault` above.
+  if (namespace === "workspace") {
+    dispatchSpexConsoleEntry(
+      "hs-workspace.ts",
+      argv,
+      vaultRoot || process.cwd(),
+    );
+    return;
+  }
+
+  // `hs login` — browser hand-off pairing (RFC 8252 loopback):
+  // one-shot 127.0.0.1 listener → default browser at <console>/companion/connect
+  // → the console mints the single-use code and redirects it back → silent
+  // redeem into ~/.heyspex/credentials.yaml. Same redemption as `hs mcp pair`,
+  // which stays as the cross-machine typed-code fallback
+  // ([[HS-IFQM-IZQ7-EPIC-hs-login-browser-hand-off-for-cli-and]]). This is an
+  // auth verb, so it bypasses the hard vault gate below like init/install —
+  // signing in is exactly what you do BEFORE you have a vault here.
+  if (namespace === "login") {
+    const cliPath = path.join(PKG_ROOT, "vendor", "heyspex-mcp", "cli.mjs");
+    const loginRoot = vaultRoot || process.cwd();
+    const child = spawn(process.execPath, [cliPath, "login", ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        HEYSPEX_VAULT_ROOT: loginRoot,
+        HS_VAULT_ROOT: loginRoot,
+        HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
+      },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run login: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs connect --check [--json]` — the read-only connect-checks report
+  // ([[HS-I2OO-EKLJ-TASK-shared-connect-checks-module-with-a]] on
+  // [[HS-QYH8-EKLJ-EPIC-hs-connect-one-command-repo-connect-verb]]). May run
+  // in an unconnected repo (no specs/ yet — that is the point), so it
+  // bypasses the hard vault gate below like init/install/vault/workspace.
+  if (namespace === "connect") {
+    dispatchSpexConsoleEntry("hs-connect.ts", argv, vaultRoot || process.cwd(), {
+      HS_INVOKED_CWD: INVOKED_CWD,
+    });
+    return;
+  }
+
+  // `hs doctor [--fix]` — verify every install surface (MCP, hooks, skills,
+  // statusline, git hooks, console secrets) and repair what can repair itself.
+  // Diagnosing whether the install itself is healthy must not first require a
+  // vault to exist, so — like init/install/connect — this bypasses the hard
+  // vault gate below. [[HS-BFXF-WBJU-DIAG-hs-never-resolves-on-a-fresh-machine]]:
+  // the very first thing a stranger runs after `npm install heyspex` in an
+  // empty project is exactly this, from a directory with no `specs/` yet.
+  if (namespace === "doctor") {
+    const script = path.join(PKG_ROOT, "scripts", "heyspex-doctor.mjs");
+    if (!existsSync(script)) {
+      // Published-package install (per HS-ZJSP-0JNK): the full doctor audits
+      // dozens of source-checkout-only surfaces (git hooks, Cursor wiring,
+      // console secrets…) that a `npm install heyspex` consumer never has, so
+      // it is deliberately not in the package's `files`. Run the small
+      // subset that DOES apply to a published install instead of crashing
+      // with MODULE_NOT_FOUND.
+      runStandaloneDoctor(argv.slice(1));
+      return;
+    }
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs doctor: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  if (!vaultRoot) {
+    process.stderr.write(
+      "hs: no vault detected — could not find a specs/ folder " +
+        "walking up from the current directory. " +
+        "Set HS_VAULT_ROOT or run from inside a vault.\n",
+    );
+    process.exit(1);
+  }
+
+  if (namespace === "index" && command === "rebuild") {
+    dispatchSpexConsoleEntry("hs-index-rebuild.ts", rest, vaultRoot);
+    return;
+  }
+
+  // `hs pull` — cloud → disk vault reconciliation. In cloud mode a filed spec
+  // lands in the cloud content store ONLY, invisible to promote / vault scans /
+  // wikilink resolution / git ([[HS-OQNH-21DO-DIAG-cloud-written-specs-are-invisible-to]]).
+  // This is the missing pull half. Additive and one-directional: it never
+  // pushes, never deletes, and only REPORTS unless `--apply` is given.
+  // Forwards the full argv; the entrypoint drops the leading `pull` token.
+  if (namespace === "pull") {
+    dispatchSpexConsoleEntry("hs-vault-pull.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs milestone show <id>` — print a milestone, flagging needs-breakdown when
+  // it has no epics ([[HS-TASK-HMSE]] / [[HS-EPIC-MNBD]]). Forwards the full
+  // argv; the entrypoint drops the leading `milestone` token.
+  if (namespace === "milestone") {
+    dispatchSpexConsoleEntry("hs-milestone.ts", argv, vaultRoot);
+    return;
+  }
+
+  if (namespace === "factory" && command === "run") {
+    dispatchSpexConsoleEntry("hs-factory-run.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs factory status|fleet|results` — Dev-Factory read-only status surface
+  // (fleet, routing table, calibrations, launch results). CLI face of the
+  // shared core reader that also backs /api/admin/factory/* ([[HS-0DG1-EPIC]] —
+  // capability-three-faces). Forwards the full argv; the entrypoint drops the
+  // leading `factory` token.
+  if (namespace === "factory") {
+    dispatchSpexConsoleEntry("hs-factory.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs code-watcher scan` — run the build tools (tsc --noEmit; test/lint to
+  // follow), parse failures, and write the build-correctness snapshot the
+  // Resolution surface reads ([[HS-TASK-2B4P]] / [[HS-EPIC-RHNJ]]). Forwards the
+  // full argv; the entrypoint drops the leading `code-watcher` token.
+  if (namespace === "code-watcher") {
+    dispatchSpexConsoleEntry("hs-code-watcher.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs server status` / `hs server stop` — ground-truth status and stop for
+  // the spex-console Next.js dev server. Pure Node cores under scripts/
+  // (same as npm run console:status / console:stop). Call status before any
+  // server-impacting task; stop from any terminal (not only the one that
+  // started it). See [[dev-server-lifecycle-and-db-safety]].
+  if (namespace === "server" && (command === "status" || command === "stop")) {
+    const scriptName =
+      command === "stop" ? "dev-server-stop.mjs" : "dev-server-status.mjs";
+    const script = path.join(PKG_ROOT, "scripts", scriptName);
+    const child = spawn(process.execPath, [script, ...rest], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(
+        `hs: failed to run ${scriptName}: ${err.message}\n`,
+      );
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs source status|preflight|commit|push` — SpexSource: the local-git
+  // preflight/commit/push path for agent sessions
+  // ([[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]). Pure Node
+  // cores under scripts/lib/, invoked directly (not via dispatchSpexConsoleEntry
+  // — these are plain .mjs modules, not spex-console TS entries). Forwards the
+  // full argv; each script drops the leading `source <verb>` tokens itself.
+  if (namespace === "source") {
+    // `hs source --help` / `-h` — bare usage, no subprocess spawned. Must be
+    // checked BEFORE the SOURCE_ENTRYPOINTS lookup below: `command` here is
+    // "--help"/"-h", which is not a known verb, so without this special case
+    // it fell into the "unknown verb" error path (exit 2) instead of exiting
+    // 0 with usage ([[HS-PO09-0JNK-TASK-packed-mcp-server-runs-the-agent-loop]] AC4).
+    if (command === "--help" || command === "-h") {
+      process.stdout.write(
+        "hs source — SpexSource local-git preflight/commit/push for agent sessions\n\n" +
+          "  hs source status              Read-only tree status + path-scoped stage plan\n" +
+          "  hs source preflight           Alias of status\n" +
+          "  hs source commit              Stage + commit per the preflight plan\n" +
+          "  hs source push                Push the committed branch\n" +
+          "  hs source log <spec-id>       Commit-history lookup for a spec (console settlement,\n" +
+          "                                 falling back to local git log)\n",
+      );
+      process.exit(0);
+    }
+    const SOURCE_ENTRYPOINTS = {
+      status: "hs-source-preflight.mjs",
+      preflight: "hs-source-preflight.mjs",
+      commit: "hs-source-commit.mjs",
+      push: "hs-source-push.mjs",
+      log: "hs-source-log.mjs",
+    };
+    const scriptName = SOURCE_ENTRYPOINTS[command];
+    if (!scriptName) {
+      process.stderr.write(
+        `hs: unknown \`hs source\` verb \`${command ?? ""}\` — expected one of: ${Object.keys(SOURCE_ENTRYPOINTS).join(", ")}\n`,
+      );
+      process.exit(2);
+    }
+    const script = path.join(PKG_ROOT, "scripts", "lib", scriptName);
+    const child = spawn(process.execPath, [script, command, ...rest], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run ${scriptName}: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs view <surface> [spec-id]` — open one console surface in a chromeless
+  // app-mode browser window (the solo console gauge —
+  // [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]]). Probes ground-truth
+  // server status first; a down console prints a clear message, never a blank window.
+  if (namespace === "view") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-view.mjs");
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs view: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs dev [mode:local|mode:cloud|mode:prod]` — dev/prod mode + local/cloud
+  // reliance (epic HS-Q6M2). Bare `hs dev` prints the resolved mode + sources;
+  // mode:* switches (writes ~/.heyspex/dev-mode.json + credentials.yaml
+  // console_url, best-effort cloud admin setting). Forwards the full argv;
+  // the entrypoint drops the leading `dev` token.
+  if (namespace === "dev") {
+    dispatchSpexConsoleEntry("hs-dev.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs defer <id>` / `hs undefer <id>` are top-level verbs (not namespaced):
+  // forward the full argv (verb + args) to the spex-console entrypoint.
+  if (namespace === "defer" || namespace === "undefer") {
+    dispatchSpexConsoleEntry("hs-defer.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs spawn [<id>] [--prompt ...] [--dry-run] [--json]` — launch a FRESH
+  // /hs-next agent session in a new terminal ([[HS-EPIC-NWUE]] / [[HS-TASK-MAPK]]).
+  // The CLI face of the What's Next hero Launch button + POST /api/agent/start;
+  // forwards the full argv (verb + args), the entrypoint drops the leading token.
+  if (namespace === "spawn") {
+    dispatchSpexConsoleEntry("hs-spawn.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs capture "<text>"|--clipboard|--file <p> [--add]` — CLI capture into
+  // the console drafts inbox; --add chains into the previous CLI capture's
+  // group (the multi-capture "add another?" gesture). Pure Node, posts the
+  // same heyspex.capture/0.1 envelope the companion sends to /api/drafts.
+  if (namespace === "capture") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-capture-cli.mjs");
+    const captureArgs = command ? [command, ...rest] : rest;
+    const child = spawn(process.execPath, [script, ...captureArgs], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run capture: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs companion start|stop|status|build` — companion tray host (companion/src/HeySpex.Companion.Host).
+  if (namespace === "companion") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-companion.mjs");
+    const companionArgs = command ? [command, ...rest] : ["start", ...rest];
+    const child = spawn(process.execPath, [script, ...companionArgs], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run companion: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  if (namespace === "registry") {
+    dispatchSpexConsoleEntry("hs-registry.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs env init|set|list|run|export|rotate` — encrypted env vault (ADR-0020).
+  // Pure local fs (no console): forwards the full argv, the entrypoint drops the
+  // leading `env` token. [[HS-CDFS-TASK]] / [[HS-9VD2-TASK]].
+  if (namespace === "env") {
+    dispatchSpexConsoleEntry("hs-env.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs next [spec_id] [--summary] [--json]` — resolve the on-deck brief without
+  // MCP ([[HS-TASK-ISK7]] / [[tool-agnostic-mcp-first-cli-second]]).
+  if (namespace === "next") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-next.mjs");
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs next: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs mode on|off|status|toggle` — the master switch for the whole HeySpex
+  // agent layer (hooks, MCP server, statusline, CLAUDE.md agent contract).
+  // Turning it off makes this repo behave like a plain codebase in Claude Code.
+  // Core: scripts/heyspex-mode.mjs · docs/claude-code-setup.md.
+  if (namespace === "mode") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-mode.mjs");
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs mode: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs gateway validate [slug] [--json]` — validate user-authored gateway
+  // skills and their scope coverage (HS-WEC3; core: scripts/gateway-skills-lib.mjs).
+  // Registration subcommands print a blocked-on-HS-DCCP notice until the
+  // connector's server-registration table exists.
+  if (namespace === "gateway") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-gateway.mjs");
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs gateway: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs settings list|get|set` — read/change HeySpex workflow settings in
+  // .heyspex/config.yaml (settings capability; core: vendor/heyspex-mcp/
+  // config-settings.mjs; write-permission rules: agent-settings-protocol).
+  if (namespace === "settings") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-settings.mjs");
+    const child = spawn(process.execPath, [script, ...argv], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs settings: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs classifier stats` — read-only view of HeySpex Intent Classifier decisions
+  // (.heyspex/intent-classifier-history.jsonl). Pure local read.
+  if (namespace === "classifier") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-classifier.mjs");
+    const child = spawn(process.execPath, [script, ...argv], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs classifier: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs auto [filename] [--json]` — resolve /hs-auto COO dispatch plan.
+  if (namespace === "auto") {
+    const script = path.join(PKG_ROOT, "scripts", "hs-auto.mjs");
+    const child = spawn(process.execPath, [script, ...argv.slice(1)], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run hs auto: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]`
+  // without the stdio JSON-RPC loop (parity for agents when heyspex_* tools are
+  // missing from the palette — [[cursor-mcp-official-notes]]).
+  // `hs mcp pair <code> [--console-url <url>]` — redeem a console pairing
+  // code for a persistent `hsmcp_` bearer, stored in ~/.heyspex/credentials.yaml
+  // ([[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]]).
+  if (namespace === "mcp") {
+    if (command !== "call" && command !== "pair" && command !== "login") {
+      process.stderr.write(
+        `hs: unknown mcp subcommand \`${command ?? ""}\` (expected: call | pair | login)\n` +
+          "  hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]\n" +
+          "  hs mcp pair <code> [--console-url <url>] [--label <text>] [--json]\n" +
+          "  hs mcp login [--console-url <url>] [--label <text>] [--json]   (alias of `hs login`)\n",
+      );
+      process.exit(2);
+    }
+    const cliPath = path.join(PKG_ROOT, "vendor", "heyspex-mcp", "cli.mjs");
+    const child = spawn(process.execPath, [cliPath, command, ...rest], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        HEYSPEX_VAULT_ROOT: vaultRoot,
+        HS_VAULT_ROOT: vaultRoot,
+        // One-shot MCP tool — no stdio loop, no stderr brief-tier noise in PS.
+        HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
+      },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run mcp ${command}: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs test run <id|manifest>` — run open-format API/contract tests (Hurl/.http)
+  // bound to acceptance criteria ([[HS-EPIC-Q0KU-open-format-test-substrate-hs-test-run-h]];
+  // supersedes the .spex plan per [[HS-RES-W0F6-testing-direction-pivot-open-formats-mut]]).
+  // Forwards the full argv; the entrypoint drops the leading `test` token.
+  if (namespace === "test") {
+    dispatchSpexConsoleEntry("hs-test.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs check run <id|manifest>` — verify a spec's acceptance criteria against its
+  // frozen checks manifest, per-criterion pass/fail against the real tree
+  // ([[HS-EPIC-DCEP-acceptance-criteria-checks-manifest-dete]], the deterministic
+  // kernel of [[HS-MIL-Y5DN-verification-engine-shared-deterministic]]). Forwards
+  // the full argv; the entrypoint drops the leading `check` token.
+  if (namespace === "check") {
+    dispatchSpexConsoleEntry("hs-check.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs revalidate` — re-run the FROZEN manifests of work already stamped
+  // `review_pending`/`in_review` and report what has decayed since the stamp
+  // ([[HS-R5LF-36QL-EPIC-stamped-work-is-re-verified-on-a]]). Read-only with
+  // respect to the repo; the Resolution plan is a dry run unless `--apply`.
+  if (namespace === "revalidate") {
+    dispatchSpexConsoleEntry("hs-revalidate.ts", argv, vaultRoot);
+    return;
+  }
+
+  // `hs agent import <collection> <role>` / `hs agent list` — import a community
+  // agent definition from a vendored collection into a `type: agent` vault spec
+  // ([[HS-TASK-6D5P]] / [[HS-EPIC-TMXZ-default-agent-roster-and-import-path]] AC#2).
+  // The CLI face of the shared import normalizer; forwards the full argv, the
+  // entrypoint drops the leading `agent` token.
+  if (namespace === "agent") {
+    dispatchSpexConsoleEntry("hs-agent.ts", argv, vaultRoot);
+    return;
+  }
+
+  // Neon control-plane verbs ([[HS-EPIC-CLMW-hs-cli-mcp-wrappers-for-control-plane]]).
+  // Each forwards the full argv (namespace/verb + args); the entrypoint drops
+  // the leading namespace token and parses the rest.
+  const CONTROL_ENTRYPOINTS = {
+    pin: "hs-pin.ts",
+    claim: "hs-claim.ts",
+    handoff: "hs-handoff.ts",
+    events: "hs-events.ts",
+    "export-events": "hs-export-events.ts",
+    prereq: "hs-prereq.ts",
+    queue: "hs-queue.ts",
+  };
+  if (Object.hasOwn(CONTROL_ENTRYPOINTS, namespace)) {
+    dispatchSpexConsoleEntry(CONTROL_ENTRYPOINTS[namespace], argv, vaultRoot);
+    return;
+  }
+
+  process.stderr.write(`hs: unknown command \`${argv.join(" ")}\`\n\n`);
+  usage();
+  process.exit(2);
+}
+
+main(process.argv.slice(2));