@danielblomma/cortex-mcp 1.7.2 → 2.0.2

package/bin/cortex.mjs

@@ -1,9 +1,20 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { normalizeProjectRoot } from "./wsl.mjs";
+import {
+  bullet,
+  printBullet,
+  spinner,
+  gradient,
+  muted,
+  accent,
+  bold,
+  headerBanner
+} from "./style.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -24,43 +35,62 @@ const GITIGNORE_LINES = [
   "mcp/node_modules/"
 ];
 
-const CORTEX_LOGO = [
-  "  CCC    OOO   RRRR  TTTTT  EEEEE  X   X",
-  " C   C  O   O  R   R   T    E       X X",
-  " C      O   O  RRRR    T    EEEE     X",
-  " C   C  O   O  R  R    T    E       X X",
-  "  CCC    OOO   R   R   T    EEEEE  X   X"
-].join("\n");
-
 function printBanner(title) {
-  console.log(CORTEX_LOGO);
-  if (title) {
-    console.log(title);
+  process.stdout.write(headerBanner({ tagline: title }));
+}
+
+// Help-row formatter: "<command>" in accent cyan, gap, "<description>" in muted grey.
+function helpRow(cmd, desc) {
+  const target = 46;
+  const pad = cmd.length >= target ? " " : " ".repeat(target - cmd.length);
+  if (desc) {
+    return `  ${accent(cmd)}${pad}${muted(desc)}`;
   }
-  console.log("");
+  return `  ${accent(cmd)}`;
+}
+
+function helpSection(title) {
+  return `\n${bold(muted(title))}`;
 }
 
 function printHelp() {
-  console.log("Cortex CLI");
+  console.log(gradient("CORTEX CLI") + muted("  ·  governance for AI coding agents"));
+  console.log(muted("  Cortex is in control. Calm, intelligent, always monitoring."));
+  console.log(helpSection("USAGE"));
+  console.log(helpRow("cortex <command> [options]"));
+
+  console.log(helpSection("CONTEXT"));
+  console.log(helpRow("init [path]", "Scaffold a project with --force/--bootstrap/--connect/--watch"));
+  console.log(helpRow("connect [path]", "Re-register MCP clients (Codex + Claude Code)"));
+  console.log(helpRow("bootstrap", "Install deps, ingest, embed, load graph"));
+  console.log(helpRow("update", "Refresh context for changed files"));
+  console.log(helpRow("status", "Project context status"));
+  console.log(helpRow("doctor", "Diagnose setup health"));
+  console.log(helpRow("ingest [--changed] [--verbose]", "Re-index source files"));
+  console.log(helpRow("embed [--changed]", "Recompute embeddings"));
+  console.log(helpRow("graph-load [--no-reset]", "Reload the dependency graph"));
+  console.log(helpRow("dashboard [--interval <sec>]", "Live local dashboard"));
+  console.log(helpRow("memory-compile [--dry-run] [--verbose]", "Compile memory artifacts"));
+  console.log(helpRow("memory-lint [--verbose] [--json]", "Lint compiled memory"));
+  console.log(helpRow("watch [start|stop|status|run|once]", "Background sync (--interval, --debounce, --mode)"));
+
+  console.log(helpSection("GOVERNANCE"));
+  console.log(helpRow("enterprise <api-key>", "Install enforcement + hooks + daemon (sudo)"));
+  console.log(helpRow("  ", "[--endpoint <url>] [--frameworks <csv>] [--no-hooks] [--no-daemon]"));
+  console.log(helpRow("enterprise status", "Show local enforcement state"));
+  console.log(helpRow("enterprise sync", "Force re-fetch + re-apply (sudo)"));
+  console.log(helpRow("enterprise uninstall", "Remove enforcement (sudo, --break-glass --reason)"));
+  console.log(helpRow("enterprise repair", "Verify managed paths, clear tamper-lock (sudo)"));
+  console.log(helpRow("run <claude|codex|copilot> [args...]", "Wrap an AI CLI in cortex enforcement"));
+  console.log(helpRow("daemon [start|stop|status]", "Local supervisor daemon"));
+  console.log(helpRow("hooks [install|uninstall|status] [--project]", "Claude Code hooks"));
+  console.log(helpRow("telemetry test", "Smoke-test the push pipeline"));
+
+  console.log(helpSection("MISC"));
+  console.log(helpRow("mcp", "Run the MCP stdio server for the current project"));
+  console.log(helpRow("version", "Print CLI version"));
+  console.log(helpRow("help", "This screen"));
   console.log("");
-  console.log("Usage:");
-  console.log("  cortex init [path] [--force] [--bootstrap] [--connect] [--no-connect] [--watch] [--no-watch]");
-  console.log("  cortex connect [path] [--skip-build]");
-  console.log("  cortex mcp");
-  console.log(
-    "  cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]"
-  );
-  console.log("  cortex bootstrap");
-  console.log("  cortex update");
-  console.log("  cortex status");
-  console.log("  cortex doctor");
-  console.log("  cortex ingest [--changed] [--verbose]");
-  console.log("  cortex embed [--changed]");
-  console.log("  cortex graph-load [--no-reset]");
-  console.log("  cortex dashboard [--interval <sec>]");
-  console.log("  cortex memory-compile [--dry-run] [--verbose]");
-  console.log("  cortex memory-lint [--verbose] [--json]");
-  console.log("  cortex help");
 }
 
 function readCliVersion() {
@@ -926,6 +956,30 @@ async function run() {
     return;
   }
 
+  if (command === "daemon") {
+    return runDaemonCommand(rest);
+  }
+
+  if (command === "hook") {
+    return runHookShim(rest);
+  }
+
+  if (command === "hooks") {
+    return runHooksCommand(rest);
+  }
+
+  if (command === "telemetry") {
+    return runTelemetryCommand(rest);
+  }
+
+  if (command === "enterprise") {
+    return runEnterpriseCommand(rest);
+  }
+
+  if (command === "run") {
+    return runRunCommand(rest);
+  }
+
   const passthrough = new Set([
     "bootstrap",
     "update",
@@ -949,6 +1003,598 @@ async function run() {
   await runContextCommand(process.cwd(), [command, ...rest]);
 }
 
+// ---------------------------------------------------------------------------
+// v2.0.0: daemon + hooks commands
+// ---------------------------------------------------------------------------
+
+const DAEMON_DIR = path.join(process.env.HOME || "", ".cortex");
+const PID_FILE = path.join(DAEMON_DIR, "daemon.pid");
+
+function pidFileExists() {
+  return fs.existsSync(PID_FILE);
+}
+
+function readPid() {
+  try {
+    const raw = fs.readFileSync(PID_FILE, "utf8").trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+
+function resolveProjectMcpDist() {
+  // v2.0.0: daemon/hooks/cli are built into the project's mcp/dist/
+  // (via 'cortex bootstrap'). PACKAGE_ROOT/scaffold/mcp/ is the source
+  // tree the scaffold is copied from. The actual built code lives in
+  // each project's <cwd>/mcp/dist/ after bootstrap.
+  const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+  return path.join(target, "mcp", "dist");
+}
+
+function resolveDaemonEntry() {
+  return path.join(resolveProjectMcpDist(), "daemon", "main.js");
+}
+
+function resolveHookEntry(name) {
+  return path.join(resolveProjectMcpDist(), "hooks", `${name}.js`);
+}
+
+function resolveCliEntry(name) {
+  return path.join(resolveProjectMcpDist(), "cli", `${name}.js`);
+}
+
+async function runDaemonCommand(args) {
+  const sub = args[0] || "status";
+  if (sub === "start") {
+    if (isPidAlive(readPid())) {
+      console.log("Daemon already running.");
+      return;
+    }
+    fs.mkdirSync(DAEMON_DIR, { recursive: true });
+    const entry = resolveDaemonEntry();
+    if (!fs.existsSync(entry)) {
+      throw new Error(`Daemon entry not found: ${entry}. Build cortex first.`);
+    }
+    const logFd = fs.openSync(path.join(DAEMON_DIR, "daemon.log"), "a");
+    const child = spawn(process.execPath, [entry], {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+    });
+    child.unref();
+    console.log(`Daemon started (pid=${child.pid}). Log: ${path.join(DAEMON_DIR, "daemon.log")}`);
+    return;
+  }
+  if (sub === "stop") {
+    const pid = readPid();
+    if (!isPidAlive(pid)) {
+      console.log("Daemon not running.");
+      return;
+    }
+    try {
+      process.kill(pid, "SIGTERM");
+      console.log(`Sent SIGTERM to pid ${pid}`);
+    } catch (err) {
+      throw new Error(`Failed to stop daemon: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return;
+  }
+  if (sub === "status") {
+    const pid = readPid();
+    if (isPidAlive(pid)) {
+      console.log(`Daemon running (pid=${pid})`);
+    } else {
+      console.log("Daemon not running.");
+      if (pidFileExists()) {
+        console.log(`(stale pid file at ${PID_FILE})`);
+      }
+    }
+    return;
+  }
+  throw new Error(`Unknown daemon subcommand: ${sub}. Try start|stop|status`);
+}
+
+async function runHookShim(args) {
+  const name = args[0];
+  if (!name) {
+    throw new Error("Usage: cortex hook <name>");
+  }
+  const entry = resolveHookEntry(name);
+  if (!fs.existsSync(entry)) {
+    throw new Error(`Hook script not found: ${entry}`);
+  }
+  // Forward stdin → child, stdout/stderr → parent. Hook protocol = stdio.
+  const child = spawn(process.execPath, [entry], { stdio: "inherit" });
+  await new Promise((resolve) => {
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+      resolve(undefined);
+    });
+  });
+}
+
+const HOOK_DEFS = [
+  { event: "PreToolUse", matcher: "Edit|Write|Bash|MultiEdit", name: "pre-tool-use" },
+  { event: "Stop", matcher: undefined, name: "stop" },
+  { event: "SessionStart", matcher: undefined, name: "session-start" },
+  { event: "SessionEnd", matcher: undefined, name: "session-end" },
+  { event: "UserPromptSubmit", matcher: undefined, name: "user-prompt-submit" },
+  { event: "PreCompact", matcher: undefined, name: "pre-compact" },
+];
+
+function managedClaudeSettingsPath() {
+  if (process.platform === "darwin") {
+    return "/Library/Application Support/ClaudeCode/managed-settings.json";
+  }
+  if (process.platform === "linux") {
+    return "/etc/claude-code/managed-settings.json";
+  }
+  return null;
+}
+
+function settingsPathFor(scope) {
+  if (scope === "project") {
+    return path.join(process.cwd(), ".claude", "settings.json");
+  }
+  let home = process.env.HOME || "";
+  const isRoot = process.getuid && process.getuid() === 0;
+  if (isRoot) {
+    const sudoUidRaw = process.env.SUDO_UID;
+    const sudoUid = sudoUidRaw ? parseInt(sudoUidRaw, 10) : NaN;
+    if (Number.isFinite(sudoUid)) {
+      try {
+        home = os.userInfo({ uid: sudoUid }).homedir;
+      } catch {
+        // Fall back to HOME below.
+      }
+    }
+  }
+  return path.join(home, ".claude", "settings.json");
+}
+
+function readJsonSafe(file) {
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function hookInstalledInSettings(settings, def) {
+  const rows = settings.hooks?.[def.event] || [];
+  return rows.some((row) => (row.hooks?.[0]?.command || "").startsWith(`cortex hook ${def.name}`));
+}
+
+function readManagedClaudeSettings() {
+  const file = managedClaudeSettingsPath();
+  if (!file) return { file: null, settings: {} };
+  return { file, settings: readJsonSafe(file) };
+}
+
+function hasManagedClaudeHooks() {
+  const { settings } = readManagedClaudeSettings();
+  if (settings.allowManagedHooksOnly !== true) return false;
+  return HOOK_DEFS.every((def) => hookInstalledInSettings(settings, def));
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+// Enterprise == govern. One command, sudo-elevated, hard-fail without it.
+// `cortex enterprise <api-key>` does the full install. Subcommands status/sync/uninstall
+// dispatch to scaffold/mcp/dist/cli/govern.js.
+
+function requireSudoElevation() {
+  const isRoot = process.getuid && process.getuid() === 0;
+  if (!isRoot) {
+    process.stderr.write(bullet("fail", "This command requires admin privileges to install non-bypassable enforcement.", process.stderr) + "\n");
+    process.stderr.write(muted("  Re-run as: sudo " + process.argv.slice(1).join(" "), process.stderr) + "\n");
+    process.exit(1);
+  }
+  const sudoUser = process.env.SUDO_USER;
+  const sudoUidRaw = process.env.SUDO_UID;
+  const sudoGidRaw = process.env.SUDO_GID;
+  if (!sudoUser || !sudoUidRaw || !sudoGidRaw) {
+    process.stderr.write(bullet("fail", "Use 'sudo' to elevate (not 'su' or a root login).", process.stderr) + "\n");
+    process.stderr.write(muted("  Cortex needs SUDO_USER/SUDO_UID/SUDO_GID set so that enterprise.yml,", process.stderr) + "\n");
+    process.stderr.write(muted("  Claude Code hooks and the daemon end up owned by your user.", process.stderr) + "\n");
+    process.exit(1);
+  }
+  const uid = parseInt(sudoUidRaw, 10);
+  const gid = parseInt(sudoGidRaw, 10);
+  if (!Number.isFinite(uid) || !Number.isFinite(gid)) {
+    process.stderr.write(bullet("fail", "SUDO_UID/SUDO_GID are not valid integers — refusing to drop privileges.", process.stderr) + "\n");
+    process.exit(1);
+  }
+  return { user: sudoUser, uid, gid };
+}
+
+function dropPrivileges(sudo) {
+  const sudoInfo = os.userInfo({ uid: sudo.uid });
+  process.setgid(sudo.gid);
+  process.setuid(sudo.uid);
+  process.env.HOME = sudoInfo.homedir;
+  process.env.USER = sudo.user;
+  process.env.LOGNAME = sudo.user;
+  return sudoInfo.homedir;
+}
+
+function loadGovernModule() {
+  const entry = resolveCliEntry("govern");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
+    );
+  }
+  return import(pathToFileURL(entry).href);
+}
+
+const ENTERPRISE_SUBCOMMANDS = new Set(["status", "sync", "uninstall", "repair", "help", "--help", "-h"]);
+
+async function runEnterpriseCommand(args) {
+  if (args.length === 0 || ENTERPRISE_SUBCOMMANDS.has(args[0])) {
+    return runEnterpriseSubcommand(args);
+  }
+  return runEnterpriseInstall(args);
+}
+
+async function runEnterpriseSubcommand(args) {
+  const sub = args[0] ?? "help";
+
+  if (sub === "help" || sub === "--help" || sub === "-h" || !sub) {
+    console.log(gradient("cortex enterprise") + muted("  ·  governance, armed."));
+    console.log(helpRow("enterprise <api-key>", "Install (sudo). Managed enforcement + hooks + daemon."));
+    console.log(helpRow("  ", "[--endpoint <url>] [--frameworks <csv>] [--no-hooks] [--no-daemon]"));
+    console.log(helpRow("enterprise status [--verbose|--json]", "Show local enforcement state"));
+    console.log(helpRow("enterprise sync", "Force re-fetch + re-apply (sudo)"));
+    console.log(helpRow("enterprise uninstall", "Remove. [--break-glass --reason \"<text>\"] in enforced mode (sudo)"));
+    console.log(helpRow("enterprise repair", "Verify managed paths, clear .cortex-tamper.lock (sudo)"));
+    console.log("");
+    console.log(muted("Default endpoint: https://cortex-web-rho.vercel.app"));
+    return;
+  }
+
+  if (sub === "status") {
+    let verbose = false;
+    let json = false;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--verbose" || args[i] === "-v") verbose = true;
+      else if (args[i] === "--json") json = true;
+      else if (args[i].startsWith("-")) {
+        throw new Error(`Unknown enterprise status option: ${args[i]}`);
+      }
+    }
+    const mod = await loadGovernModule();
+    mod.runGovernStatus({ cwd: process.cwd(), verbose, json });
+    return;
+  }
+
+  if (sub === "sync") {
+    requireSudoElevation();
+    const mod = await loadGovernModule();
+    await mod.runGovernSync({ cwd: process.cwd() });
+    return;
+  }
+
+  if (sub === "uninstall") {
+    let breakGlass = false;
+    let reason;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--break-glass") breakGlass = true;
+      else if (args[i] === "--reason" && args[i + 1]) {
+        reason = args[i + 1];
+        i++;
+      } else if (args[i].startsWith("-")) {
+        throw new Error(`Unknown enterprise uninstall option: ${args[i]}`);
+      }
+    }
+    requireSudoElevation();
+    const mod = await loadGovernModule();
+    const result = await mod.runGovernUninstall({
+      cli: "all",
+      breakGlass,
+      reason,
+      cwd: process.cwd(),
+    });
+    if (!result.ok) {
+      printBullet("fail", result.message, process.stderr);
+      process.exit(1);
+    }
+    printBullet("ok", result.message);
+    return;
+  }
+
+  if (sub === "repair") {
+    let reason;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--reason" && args[i + 1]) {
+        reason = args[i + 1];
+        i++;
+      } else if (args[i].startsWith("-")) {
+        throw new Error(`Unknown enterprise repair option: ${args[i]}`);
+      }
+    }
+    requireSudoElevation();
+    const mod = await loadGovernModule();
+    const result = await mod.runGovernRepair({ cwd: process.cwd(), reason });
+    if (!result.ok) {
+      printBullet("fail", result.message, process.stderr);
+      process.exit(1);
+    }
+    printBullet("ok", result.message);
+    return;
+  }
+
+  throw new Error(`Unknown enterprise subcommand: ${sub}`);
+}
+
+async function runEnterpriseInstall(args) {
+  const apiKey = args[0];
+  let endpoint;
+  let frameworks;
+  let installHooks = true;
+  let startDaemon = true;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--endpoint" && args[i + 1]) {
+      endpoint = args[i + 1];
+      i++;
+    } else if (args[i] === "--frameworks" && args[i + 1]) {
+      frameworks = args[i + 1].split(",").map((s) => s.trim()).filter(Boolean);
+      i++;
+    } else if (args[i] === "--no-hooks") {
+      installHooks = false;
+    } else if (args[i] === "--no-daemon") {
+      startDaemon = false;
+    } else if (args[i].startsWith("-")) {
+      throw new Error(`Unknown enterprise install option: ${args[i]}`);
+    }
+  }
+
+  const sudo = requireSudoElevation();
+
+  process.stdout.write(headerBanner({ tagline: "  Cortex enterprise — activating governance" }));
+
+  const enterpriseEntry = resolveCliEntry("enterprise-setup");
+  if (!fs.existsSync(enterpriseEntry)) {
+    printBullet("fail", `Build the project's MCP first (missing ${enterpriseEntry}). Run 'cortex bootstrap' in the project root.`);
+    process.exit(1);
+  }
+  const enterpriseMod = await import(pathToFileURL(enterpriseEntry).href);
+
+  // Step 1 — Initializing Cortex core (license validation + enterprise.yml).
+  const step1 = spinner("Initializing Cortex core");
+  const setupResult = await enterpriseMod.runEnterpriseSetup({ apiKey, endpoint, cwd: process.cwd() });
+  if (!setupResult.ok) {
+    step1.stop("fail", `Initializing Cortex core — ${setupResult.message}`);
+    process.exit(1);
+  }
+  step1.stop("ok", `Initializing Cortex core — license ${setupResult.edition}, expires ${setupResult.expiresAt}`);
+  printBullet("info", muted(`config: ${setupResult.configPath}`));
+
+  // enterprise.yml was just written as root; transfer ownership before we drop privs.
+  try {
+    fs.chownSync(setupResult.configPath, sudo.uid, sudo.gid);
+  } catch (err) {
+    printBullet("warn", `Could not chown ${setupResult.configPath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // Step 2 — Loading policy engine (govern install: managed config + frameworks).
+  const baseUrl = (endpoint ?? "https://cortex-web-rho.vercel.app").replace(/\/$/, "");
+  const step2 = spinner("Loading policy engine");
+  const governMod = await loadGovernModule();
+  const governResult = await governMod.runGovernInstall({
+    cli: "all",
+    mode: "enforced",
+    cwd: process.cwd(),
+    apiKey,
+    baseUrl,
+    frameworks,
+  });
+  if (!governResult.ok) {
+    step2.stop("fail", `Loading policy engine — ${governResult.message}`);
+    process.exit(1);
+  }
+  step2.stop("ok", "Loading policy engine — policies armed");
+
+  // govern.local.json was written as root in cwd/.context. chown it back.
+  const governStatePath = path.join(process.cwd(), ".context", "govern.local.json");
+  if (fs.existsSync(governStatePath)) {
+    try {
+      fs.chownSync(governStatePath, sudo.uid, sudo.gid);
+    } catch (err) {
+      printBullet("warn", `Could not chown ${governStatePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Step 3 — Connecting audit pipeline (telemetry endpoint already wired by govern install).
+  const step3 = spinner("Connecting audit pipeline");
+  step3.stop("ok", `Connecting audit pipeline — endpoint ${baseUrl}`);
+
+  // Drop privileges before user-scope writes (Claude Code hooks in $HOME) and daemon spawn.
+  dropPrivileges(sudo);
+
+  // Step 4 — Preparing MCP gateway (Claude Code hooks bind the MCP surface).
+  if (installHooks) {
+    const step4 = spinner("Preparing MCP gateway");
+    try {
+      if (hasManagedClaudeHooks()) {
+        step4.stop("ok", "Preparing MCP gateway — managed Claude hooks active");
+      } else {
+        await runHooksCommand(["install"]);
+        step4.stop("ok", "Preparing MCP gateway — hooks installed");
+      }
+    } catch (err) {
+      step4.stop("fail", `Preparing MCP gateway — ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    printBullet("warn", "Preparing MCP gateway — skipped (--no-hooks)");
+  }
+
+  // Step 5 — Installing guardrails (supervisor daemon).
+  if (startDaemon) {
+    const step5 = spinner("Installing guardrails");
+    try {
+      await runDaemonCommand(["start"]);
+      step5.stop("ok", "Installing guardrails — daemon online");
+    } catch (err) {
+      step5.stop("fail", `Installing guardrails — ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    printBullet("warn", "Installing guardrails — skipped (--no-daemon)");
+  }
+
+  console.log("");
+  console.log(bullet("ok", bold("Cortex is running.")));
+  console.log(muted("  Monitoring AI activity. No violations detected."));
+  console.log(muted("  Next: ") + accent("cortex enterprise status") + muted("  ·  ") + accent("cortex telemetry test"));
+  console.log("");
+}
+
+const RUN_CLIS = new Set(["claude", "codex", "copilot"]);
+
+async function runRunCommand(args) {
+  const sub = args[0];
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    console.log("Usage:");
+    console.log("  cortex run <claude|codex|copilot> [args...]");
+    console.log("");
+    console.log("Wraps the named AI CLI in cortex enforcement:");
+    console.log("  claude/codex: passthrough — their own managed-config + sandbox");
+    console.log("                cover Tier 1 enforcement after 'cortex enterprise <key>'.");
+    console.log("  copilot:      Tier 2 — OS-level sandbox (sandbox-exec on macOS,");
+    console.log("                bwrap on Linux). Denies writes to ~/.copilot/,");
+    console.log("                ~/.copilot.local/, /etc/copilot* so AI cannot");
+    console.log("                reconfigure itself out of governance.");
+    console.log("");
+    console.log("Tip: alias copilot='cortex run copilot' so direct 'copilot' invocations");
+    console.log("are also wrapped. Direct invocations are otherwise caught by Tier 3");
+    console.log("ungoverned-session detection (Phase 5).");
+    return;
+  }
+  if (!RUN_CLIS.has(sub)) {
+    throw new Error(`Unknown AI CLI: ${sub}. Use claude, codex, or copilot.`);
+  }
+  const entry = resolveCliEntry("run");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
+    );
+  }
+  const mod = await import(pathToFileURL(entry).href);
+  const exitCode = await mod.runAiCli({ cli: sub, args: args.slice(1) });
+  process.exit(exitCode);
+}
+
+async function runTelemetryCommand(args) {
+  const sub = args[0] || "help";
+  if (sub === "test") {
+    const entry = resolveCliEntry("telemetry-test");
+    if (!fs.existsSync(entry)) {
+      throw new Error(`Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`);
+    }
+    const mod = await import(pathToFileURL(entry).href);
+    const code = await mod.runTelemetryTest();
+    process.exit(code);
+  }
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    console.log("Usage:");
+    console.log("  cortex telemetry test    Smoke-test the push pipeline end-to-end");
+    return;
+  }
+  throw new Error(`Unknown telemetry subcommand: ${sub}`);
+}
+
+async function runHooksCommand(args) {
+  const sub = args[0] || "status";
+  const scope = args.includes("--project") ? "project" : "user";
+  const target = settingsPathFor(scope);
+
+  if (sub === "install") {
+    const settings = readJsonSafe(target);
+    settings.hooks = settings.hooks || {};
+    for (const def of HOOK_DEFS) {
+      const entry = {
+        ...(def.matcher ? { matcher: def.matcher } : {}),
+        hooks: [{ type: "command", command: `cortex hook ${def.name}` }],
+      };
+      const existing = settings.hooks[def.event] || [];
+      const filtered = existing.filter((row) => {
+        const cmd = (row.hooks?.[0]?.command || "");
+        return !cmd.startsWith("cortex hook ");
+      });
+      settings.hooks[def.event] = [...filtered, entry];
+    }
+    writeJson(target, settings);
+    console.log(`Installed cortex hooks into ${target}`);
+    console.log(`Hooks: ${HOOK_DEFS.map((d) => d.name).join(", ")}`);
+    return;
+  }
+  if (sub === "uninstall") {
+    const settings = readJsonSafe(target);
+    if (settings.hooks) {
+      for (const event of Object.keys(settings.hooks)) {
+        settings.hooks[event] = (settings.hooks[event] || []).filter((row) => {
+          const cmd = (row.hooks?.[0]?.command || "");
+          return !cmd.startsWith("cortex hook ");
+        });
+        if (settings.hooks[event].length === 0) {
+          delete settings.hooks[event];
+        }
+      }
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+      }
+    }
+    writeJson(target, settings);
+    console.log(`Removed cortex hooks from ${target}`);
+    return;
+  }
+  if (sub === "status") {
+    const settings = readJsonSafe(target);
+    const managed = scope === "user" ? readManagedClaudeSettings() : { file: null, settings: {} };
+    const installed = [];
+    for (const def of HOOK_DEFS) {
+      const userFound = hookInstalledInSettings(settings, def);
+      const managedFound = scope === "user" ? hookInstalledInSettings(managed.settings, def) : false;
+      const found = userFound || managedFound;
+      let source = "";
+      if (userFound && managedFound) source = "user+managed";
+      else if (userFound) source = "user";
+      else if (managedFound) source = "managed";
+      installed.push({ name: def.name, event: def.event, found, source });
+    }
+    console.log(`Settings file: ${target}`);
+    if (scope === "user" && managed.file) {
+      console.log(`Managed settings: ${managed.file}`);
+    }
+    for (const row of installed) {
+      console.log(`  ${row.found ? "✓" : "✗"} ${row.event} → ${row.name}${row.source ? ` (${row.source})` : ""}`);
+    }
+    if (scope === "user" && managed.settings.allowManagedHooksOnly === true) {
+      console.log("  note: managed Claude hooks are authoritative; user hooks may be intentionally absent");
+    }
+    return;
+  }
+  throw new Error(`Unknown hooks subcommand: ${sub}. Try install|uninstall|status`);
+}
+
 function resolveArgv1() {
   if (!process.argv[1]) return null;
   try {
@@ -963,7 +1609,8 @@ const invokedAsScript =
 
 if (invokedAsScript) {
   run().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(bullet("fail", message, process.stderr) + "\n");
     process.exit(1);
   });
 }