great-cto 2.9.1 → 2.9.3

package/dist/leash.js

@@ -0,0 +1,289 @@
+// `great-cto leash <subcommand>` — install, start, status, kill, update.
+//
+// Distribution model: we track llm-leash by *git repository* (not PyPI) so
+// every push to https://github.com/avelikiy/llm-leash main is one
+// `great-cto leash update` away. The repo is cloned to ~/.great_cto/llm-leash
+// and installed as editable (`pip install -e .`). Updates run `git pull` +
+// `pip install -e . --upgrade`.
+//
+// Three sources of truth:
+//   1. Installed SHA   = git rev-parse HEAD in ~/.great_cto/llm-leash
+//   2. Latest SHA      = GitHub commits API
+//   3. Pinned SHA      = .great_cto/leash.json → "pinned_sha" (optional)
+//
+// If pinned_sha is set, update() refuses to bump past it without --force.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log, success, warn, error, cyan, dim, bold } from "./ui.js";
+const REPO_URL = "https://github.com/avelikiy/llm-leash.git";
+const REPO_API = "https://api.github.com/repos/avelikiy/llm-leash";
+const INSTALL_ROOT = join(homedir(), ".great_cto", "llm-leash");
+const CONFIG_PATH = join(homedir(), ".great_cto", "leash.json");
+// ── public API ────────────────────────────────────────────────────────────────
+export async function runLeash(argv) {
+    const sub = argv[0];
+    switch (sub) {
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            return { exitCode: 0 };
+        case "install":
+            return install();
+        case "update":
+            return update(argv.includes("--force"));
+        case "status":
+            return status();
+        case "start":
+            return startProxy(argv.slice(1));
+        case "kill":
+            return killAll();
+        case "uninstall":
+            return uninstall();
+        default:
+            error(`great-cto leash: unknown subcommand '${sub}'`);
+            printHelp();
+            return { exitCode: 2 };
+    }
+}
+// ── subcommands ───────────────────────────────────────────────────────────────
+function printHelp() {
+    log(bold("great-cto leash") + " — runtime governance for LLM agents (https://github.com/avelikiy/llm-leash)");
+    log("");
+    log("  " + cyan("install") + "       clone the repo, install as editable, write default config");
+    log("  " + cyan("update") + "        git pull + reinstall (auto-pulls latest commits from main)");
+    log("  " + cyan("status") + "        installed version vs GitHub latest, last audit-log entry");
+    log("  " + cyan("start") + "         start the HTTP proxy on :8765 (env-var deployment)");
+    log("  " + cyan("kill") + "          fire kill switch — stops all in-flight LLM calls (<300 ms)");
+    log("  " + cyan("uninstall") + "     remove ~/.great_cto/llm-leash (config left intact)");
+    log("");
+    log(dim("  Config: " + CONFIG_PATH));
+    log(dim("  Install dir: " + INSTALL_ROOT));
+}
+function install() {
+    if (!hasGit()) {
+        error("git is required. Install git first: https://git-scm.com/downloads");
+        return { exitCode: 1 };
+    }
+    if (!hasPython()) {
+        error("python3 is required. Install Python 3.10+ first: https://www.python.org/downloads/");
+        return { exitCode: 1 };
+    }
+    mkdirSync(join(homedir(), ".great_cto"), { recursive: true });
+    if (existsSync(INSTALL_ROOT)) {
+        warn(`llm-leash already cloned at ${INSTALL_ROOT}.`);
+        log(`  Run ${cyan("great-cto leash update")} to pull latest.`);
+        return { exitCode: 0 };
+    }
+    log(dim(`  cloning ${REPO_URL} → ${INSTALL_ROOT}`));
+    const cloneResult = spawnSync("git", ["clone", REPO_URL, INSTALL_ROOT], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 120_000,
+    });
+    if (cloneResult.status !== 0) {
+        error(`git clone failed: ${cloneResult.stderr?.toString() || "unknown"}`);
+        return { exitCode: 1 };
+    }
+    log(dim(`  pip install -e .`));
+    const pipResult = spawnSync(pythonCmd(), ["-m", "pip", "install", "-e", INSTALL_ROOT, "--quiet"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 240_000,
+    });
+    if (pipResult.status !== 0) {
+        warn("pip install reported errors — leash CLI may not be on PATH yet:");
+        warn(pipResult.stderr?.toString() || "");
+        log(`  Try: ${cyan(`${pythonCmd()} -m pip install -e ${INSTALL_ROOT}`)}`);
+    }
+    // Default config (only if absent — never clobber user changes)
+    if (!existsSync(CONFIG_PATH)) {
+        const defaults = {
+            enabled: true,
+            install_root: INSTALL_ROOT,
+            audit_path: join(homedir(), ".leash", "audit.jsonl"),
+            proxy_url: "http://localhost:8765",
+            daily_cap_usd: 50,
+            monthly_cap_usd: 500,
+        };
+        writeFileSync(CONFIG_PATH, JSON.stringify(defaults, null, 2));
+        success(`wrote ${CONFIG_PATH}`);
+    }
+    const sha = getInstalledSha();
+    success(`llm-leash installed at ${INSTALL_ROOT}${sha ? ` (HEAD: ${sha})` : ""}`);
+    log("");
+    log("Next: " + cyan("great-cto leash status") + " — verify proxy reachable");
+    log("      " + cyan("great-cto leash start") + " — start HTTP proxy on :8765");
+    return { exitCode: 0 };
+}
+function update(force) {
+    if (!existsSync(INSTALL_ROOT)) {
+        warn("llm-leash not installed. Run `great-cto leash install` first.");
+        return { exitCode: 1 };
+    }
+    const cfg = readConfig();
+    const beforeSha = getInstalledSha();
+    if (cfg.pinned_sha && !force) {
+        log(dim(`  pinned to ${cfg.pinned_sha} in ${CONFIG_PATH} — checkout pinned commit`));
+        const co = spawnSync("git", ["-C", INSTALL_ROOT, "fetch", "--quiet"], { stdio: "ignore", timeout: 60_000 });
+        if (co.status !== 0) {
+            error("git fetch failed");
+            return { exitCode: 1 };
+        }
+        const reset = spawnSync("git", ["-C", INSTALL_ROOT, "reset", "--hard", cfg.pinned_sha], {
+            stdio: ["ignore", "pipe", "pipe"], timeout: 30_000,
+        });
+        if (reset.status !== 0) {
+            error(`reset to pinned ${cfg.pinned_sha} failed: ${reset.stderr?.toString()}`);
+            return { exitCode: 1 };
+        }
+    }
+    else {
+        log(dim(`  git pull origin main`));
+        const pull = spawnSync("git", ["-C", INSTALL_ROOT, "pull", "--ff-only", "origin", "main"], {
+            stdio: ["ignore", "pipe", "pipe"], timeout: 60_000,
+        });
+        if (pull.status !== 0) {
+            error(`git pull failed: ${pull.stderr?.toString()}`);
+            log(`  Try: ${cyan(`cd ${INSTALL_ROOT} && git status`)}`);
+            return { exitCode: 1 };
+        }
+    }
+    const afterSha = getInstalledSha();
+    if (beforeSha === afterSha) {
+        log(dim(`  already at latest (${afterSha})`));
+        return { exitCode: 0 };
+    }
+    log(dim(`  pip install -e . --upgrade`));
+    const pip = spawnSync(pythonCmd(), ["-m", "pip", "install", "-e", INSTALL_ROOT, "--upgrade", "--quiet"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 240_000,
+    });
+    if (pip.status !== 0) {
+        warn("pip reinstall reported errors:");
+        warn(pip.stderr?.toString() || "");
+    }
+    success(`llm-leash: ${beforeSha} → ${afterSha}`);
+    // Persist last-known SHA for the version-check hook
+    if (afterSha)
+        writeVersionCache(afterSha);
+    return { exitCode: 0 };
+}
+async function status() {
+    const installed = existsSync(INSTALL_ROOT);
+    if (!installed) {
+        log(bold("llm-leash:") + " " + dim("not installed"));
+        log(`  Install: ${cyan("great-cto leash install")}`);
+        return { exitCode: 0 };
+    }
+    const cfg = readConfig();
+    const head = getInstalledSha() || "?";
+    const latest = await fetchLatestSha();
+    log(bold("llm-leash:") + " installed at " + dim(INSTALL_ROOT));
+    log(`  Installed HEAD : ${head}`);
+    log(`  GitHub latest  : ${latest || dim("unknown (network?)")}`);
+    log(`  Config         : ${CONFIG_PATH}`);
+    log(`  Audit log      : ${cfg.audit_path || dim("default")}`);
+    log(`  Daily cap      : ${cfg.daily_cap_usd ? "$" + cfg.daily_cap_usd : dim("not set")}`);
+    log(`  Pinned SHA     : ${cfg.pinned_sha || dim("none — track main")}`);
+    if (latest && latest !== head) {
+        log("");
+        warn(`Update available. Run ${cyan("great-cto leash update")} to bump.`);
+    }
+    return { exitCode: 0 };
+}
+function startProxy(extraArgs) {
+    if (!existsSync(INSTALL_ROOT)) {
+        warn("llm-leash not installed. Run `great-cto leash install` first.");
+        return { exitCode: 1 };
+    }
+    log(`Starting llm-leash proxy on http://localhost:8765 …`);
+    log(dim(`  set ANTHROPIC_BASE_URL=http://localhost:8765 to route via leash`));
+    const r = spawnSync(pythonCmd(), ["-m", "leash.proxy", ...extraArgs], {
+        stdio: "inherit",
+    });
+    return { exitCode: r.status ?? 0 };
+}
+function killAll() {
+    const r = spawnSync("leash", ["kill", "--all", "--reason", "cli"], {
+        stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+    });
+    if (r.status === 0) {
+        success("kill switch fired");
+        return { exitCode: 0 };
+    }
+    // Fall back to python -m
+    const r2 = spawnSync(pythonCmd(), ["-m", "leash", "kill", "--all", "--reason", "cli"], {
+        stdio: "inherit", timeout: 5000,
+    });
+    return { exitCode: r2.status ?? 1 };
+}
+function uninstall() {
+    if (!existsSync(INSTALL_ROOT)) {
+        log(dim("nothing to remove"));
+        return { exitCode: 0 };
+    }
+    const r = spawnSync("rm", ["-rf", INSTALL_ROOT], { stdio: "inherit", timeout: 30_000 });
+    if (r.status === 0)
+        success(`removed ${INSTALL_ROOT}`);
+    log(dim(`config left intact at ${CONFIG_PATH}`));
+    return { exitCode: r.status ?? 0 };
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function hasGit() {
+    return spawnSync("git", ["--version"], { stdio: "ignore", timeout: 3000 }).status === 0;
+}
+function hasPython() {
+    return spawnSync(pythonCmd(), ["--version"], { stdio: "ignore", timeout: 3000 }).status === 0;
+}
+function pythonCmd() {
+    // Prefer python3, fall back to python
+    if (spawnSync("python3", ["--version"], { stdio: "ignore", timeout: 2000 }).status === 0)
+        return "python3";
+    return "python";
+}
+function getInstalledSha() {
+    if (!existsSync(INSTALL_ROOT))
+        return null;
+    const r = spawnSync("git", ["-C", INSTALL_ROOT, "rev-parse", "--short", "HEAD"], {
+        stdio: ["ignore", "pipe", "ignore"], timeout: 3000,
+    });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.toString().trim();
+}
+async function fetchLatestSha() {
+    try {
+        const res = await fetch(`${REPO_API}/commits/main`, {
+            headers: {
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "great-cto-leash",
+            },
+            // Node 20 has native AbortController + fetch; cap at 6 s.
+            signal: AbortSignal.timeout(6000),
+        });
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return j.sha?.slice(0, 7) || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readConfig() {
+    try {
+        if (existsSync(CONFIG_PATH))
+            return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch { /* ignore */ }
+    return {};
+}
+function writeVersionCache(sha) {
+    const cache = join(homedir(), ".great_cto", "leash-version.json");
+    try {
+        writeFileSync(cache, JSON.stringify({
+            installed_sha: sha,
+            last_checked: new Date().toISOString(),
+        }, null, 2));
+    }
+    catch { /* best-effort */ }
+}

package/dist/main.js

@@ -10,15 +10,14 @@
 //   7. bootstrap .great_cto/PROJECT.md
 //   8. print next steps
 import { resolve } from "node:path";
-import { banner, bold, cyan, dim, error, gray, green, log, step, warn, yellow, confirm } from "./ui.js";
+import { banner, bold, cyan, dim, error, green, log, step, success, warn, yellow, confirm } from "./ui.js";
 import { detect } from "./detect.js";
 import { pickArchetype, suggestCompliance } from "./archetypes.js";
 import { install, findInstalledVersions } from "./installer.js";
 import { enableGreatCto } from "./settings.js";
 import { bootstrap } from "./bootstrap.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
-import { isTelemetryEnabled, sendInstallPing, telemetrySubcommand, computeAnonId, } from "./telemetry.js";
-import { readFileSync, writeFileSync, mkdirSync, existsSync as fsExistsSync } from "node:fs";
+import { readFileSync, copyFileSync, chmodSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -96,8 +95,8 @@ function parseArgs(argv) {
             args.command = "webhook";
         else if (a === "report")
             args.command = "report";
-        else if (a === "telemetry")
-            args.command = "telemetry";
+        else if (a === "leash")
+            args.command = "leash";
         // Slash-commands surfaced as CLI subcommands so users get a clear hint
         // instead of a confusing usage error. These work only in the chat plugin.
         else if (a === "start" || a === "audit" || a === "inbox" || a === "digest" ||
@@ -114,8 +113,14 @@ function parseArgs(argv) {
             args.dir = a.slice("--dir=".length);
         else if (a === "--dir")
             args.dir = argv[++i] ?? args.dir;
-        else if (a === "init" || a === "help" || a === "version") {
-            args.command = a;
+        else if (a === "init" || a === "install" || a === "help" || a === "version") {
+            // `install` is an alias for `init`. Both run the same flow; only
+            // difference: `install` upgrades llm-leash to latest on every run,
+            // while `init` is silent-skip when already installed.
+            args.command = (a === "install" ? "init" : a);
+            if (a === "install") {
+                args._fromInstall = true;
+            }
         }
         else if (!a.startsWith("-") && args.command === "init" && i === 0) {
             // First positional that isn't a recognised subcommand → unknown
@@ -349,7 +354,8 @@ function printHelp() {
     log(`${bold("great-cto")} — one-command install for the great_cto Claude Code plugin
 
 ${bold("Usage:")}
-  npx great-cto [init] [options]
+  npx great-cto install [options]    Same as init; also upgrades llm-leash
+  npx great-cto [init] [options]     Detect + bootstrap; installs llm-leash if absent
   npx great-cto board [--port 3141] [--no-open]
   npx great-cto register [--dir PATH]
   npx great-cto scan [path] [--severity LVL] [--scanner NAME] [--sarif FILE]
@@ -398,13 +404,6 @@ ${bold("Claude Code adapter:")}
   great-cto adapt --dry-run            Preview what would be written
   ${dim("Idempotent — re-run after editing .great_cto/PROJECT.md")}
 
-${bold("Telemetry (opt-IN, off by default):")}
-  great-cto telemetry status           Show current state + endpoint + anon_id
-  great-cto telemetry on               Enable anonymous usage events
-  great-cto telemetry off              Disable (also: DO_NOT_TRACK=1)
-  great-cto telemetry whoami           Print your anon_id (8 hex chars)
-  ${dim("Privacy: docs/PRIVACY.md · no code, no repo names, no PII")}
-
 ${bold("Webhook server (preview):")}
   great-cto serve --port 3142          Webhook receiver (logs to ~/.great_cto/webhook-events.log)
   ${dim("Endpoints: POST /webhook/github, POST /webhook/generic, GET /events, GET /healthz")}
@@ -757,23 +756,18 @@ async function runInit(args) {
     if (!bs.created) {
         log(`  ${dim("PROJECT.md already exists at")} ${bs.projectMdPath} ${dim("— kept as-is")}`);
     }
+    // ── 6. install pre-push git hook ─────────────────────────
+    installPrePushHook(args.dir);
+    // ── 7. install / update llm-leash (runtime governance) ───
+    // `init` is idempotent (silent skip when present). `install` always
+    // upgrades to the latest commit on llm-leash main. Both best-effort:
+    // missing git/python doesn't fail the flow.
+    const fromInstall = args._fromInstall === true;
+    await tryInstallLeash(fromInstall);
     // ── done ─────────────────────────────────────────────────
     log("");
     log(green(bold("✓ great_cto is ready.")));
     log("");
-    // ── 6. opt-IN telemetry prompt ───────────────────────────
-    // Aggressive opt-IN promo (Option A from telemetry strategy).
-    // Shows up only when interactive + not CI + not already decided + DO_NOT_TRACK unset.
-    await promoteTelemetryOptIn({ archetype: archetype, cliVersion: getCliVersion(), yes: args.yes });
-    // If telemetry is enabled (either via prior opt-in or env var), fire a fresh
-    // install-ping so re-runs of `init` (after upgrades) count toward WAU/MAU.
-    if (isTelemetryEnabled()) {
-        await sendInstallPing({
-            cliVersion: getCliVersion(),
-            archetype: archetype,
-            consent: true,
-        }).catch(() => { });
-    }
     log(bold("Next steps:"));
     log(`  1. ${dim("Restart Claude Code to pick up the plugin.")}`);
     log(`  2. ${dim("Edit")} ${cyan(".great_cto/PROJECT.md")} ${dim("to refine goals and compliance.")}`);
@@ -785,80 +779,69 @@ async function runInit(args) {
     log("");
     return 0;
 }
-// ── Telemetry opt-IN prompt ────────────────────────────────────────────────
-// Shows after a successful init when interactive. NOT shown if:
-//   - --yes / -y was used (skip-confirmation mode)
-//   - DO_NOT_TRACK=1 (respect honest signal)
-//   - Already opted in or explicitly opted out (no nag)
-//   - CI environment
-//   - Non-TTY stdin (piped install)
-async function promoteTelemetryOptIn(opts) {
-    // Skip prompts in non-interactive mode.
-    if (opts.yes)
-        return;
-    if (!process.stdin.isTTY)
-        return;
-    if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
-        return;
-    if (process.env.CI || process.env.GITHUB_ACTIONS)
-        return;
-    // If user already made a decision (either way), respect it — don't re-ask.
-    const cfgFile = join(homedir(), ".great_cto", "telemetry.json");
-    if (fsExistsSync(cfgFile)) {
-        try {
-            const cfg = JSON.parse(readFileSync(cfgFile, "utf8"));
-            if (cfg.enabled === true || cfg.enabled === false)
-                return;
+/**
+ * Copy scripts/hooks/pre-push.sh from the installed plugin into the project's
+ * .git/hooks/pre-push so that future pushes are scanned for private project
+ * name leaks. Best-effort — never throws.
+ */
+function installPrePushHook(projectDir) {
+    try {
+        const gitHooksDir = join(projectDir, ".git", "hooks");
+        if (!fsExistsSync(gitHooksDir))
+            return; // not a git repo — skip silently
+        const dest = join(gitHooksDir, "pre-push");
+        if (fsExistsSync(dest)) {
+            log(`  ${dim("pre-push hook already present — skipped")}`);
+            return;
         }
-        catch { /* malformed — ask again */ }
+        // Locate source: dist/main.js → ../../scripts/hooks/pre-push.sh
+        const here = dirname(fileURLToPath(import.meta.url));
+        const src = join(here, "..", "..", "scripts", "hooks", "pre-push.sh");
+        if (!fsExistsSync(src)) {
+            warn("pre-push hook source not found — skipping hook installation");
+            return;
+        }
+        copyFileSync(src, dest);
+        chmodSync(dest, 0o755);
+        success("installed pre-push hook (blocks private project name leaks)");
     }
-    // The honest, brand-aligned ask.
-    log(dim("─".repeat(60)));
-    log(bold("Help great_cto learn from how you use it?"));
-    log("");
-    log(dim("Anonymous usage data (default: off). Helps cross-project"));
-    log(dim("lessons promote to a global pattern library."));
-    log("");
-    log(dim("Here is exactly what would be sent — one event per command:"));
-    log("");
-    log(gray(`  {`));
-    log(gray(`    "version": "${opts.cliVersion}",`));
-    log(gray(`    "command": "init",`));
-    log(gray(`    "archetype": "${opts.archetype}",`));
-    log(gray(`    "node": "${process.version.replace(/^v/, "")}",`));
-    log(gray(`    "os": "${process.platform}",`));
-    log(gray(`    "exit_code": 0,`));
-    log(gray(`    "duration_ms": 1234,`));
-    log(gray(`    "anon_id": "${computeAnonId()}"   ${dim("// 8 hex chars, not reversible")}`));
-    log(gray(`  }`));
-    log("");
-    log(dim("No code, no repo names, no file paths, no PII."));
-    log(dim("Toggle anytime: " + cyan("npx great-cto telemetry off")));
-    log(dim("Privacy: " + cyan("github.com/avelikiy/great_cto/blob/main/docs/PRIVACY.md")));
-    log("");
-    const yes = await confirm(bold("Enable anonymous telemetry?"), false);
-    log("");
-    // Persist the decision either way so we never re-ask.
-    try {
-        const dir = join(homedir(), ".great_cto");
-        mkdirSync(dir, { recursive: true });
-        writeFileSync(join(dir, "telemetry.json"), JSON.stringify({ enabled: yes, decided_at: new Date().toISOString() }, null, 2) + "\n");
+    catch {
+        // Best-effort: hook failure must never block init
     }
-    catch { /* best-effort */ }
-    if (yes) {
-        log(green(`✓ Telemetry enabled. Thank you.`));
-        log(dim(`  See your anon_id anytime: ${cyan("npx great-cto telemetry whoami")}`));
-        log("");
-        // Send the first event — the install-ping itself.
-        await sendInstallPing({
-            cliVersion: opts.cliVersion,
-            archetype: opts.archetype,
-            consent: true,
-        });
+}
+/**
+ * Best-effort llm-leash install — runs after bootstrap so every great-cto
+ * init turns on runtime governance for free.
+ *
+ *   forceUpdate=false  (called from `init`)    — silent-skip if installed
+ *   forceUpdate=true   (called from `install`) — git pull + reinstall
+ *
+ * Never throws. Opt out via env: GREAT_CTO_SKIP_LEASH=1
+ */
+async function tryInstallLeash(forceUpdate = false) {
+    if (process.env.GREAT_CTO_SKIP_LEASH === "1") {
+        log(`  ${dim("skipped llm-leash install (GREAT_CTO_SKIP_LEASH=1)")}`);
+        return;
     }
-    else {
-        log(dim(`Telemetry off. ${cyan("npx great-cto telemetry on")} to change later.`));
-        log("");
+    try {
+        const { runLeash } = await import("./leash.js");
+        const { existsSync } = await import("node:fs");
+        const installRoot = join(homedir(), ".great_cto", "llm-leash");
+        if (existsSync(installRoot)) {
+            if (forceUpdate) {
+                log(`  ${dim("updating llm-leash to latest …")}`);
+                await runLeash(["update"]);
+            }
+            else {
+                log(`  ${dim("llm-leash already installed — skipped")}`);
+            }
+            return;
+        }
+        log(`  ${dim("installing llm-leash (runtime governance) …")}`);
+        await runLeash(["install"]);
+    }
+    catch {
+        warn("llm-leash install failed — run `great-cto leash install` manually later");
     }
 }
 async function main() {
@@ -875,12 +858,6 @@ async function main() {
         log(`Run ${cyan("great-cto --help")} for usage.`);
         process.exit(2);
     }
-    if (args.command === "telemetry") {
-        const sub = rawArgv[rawArgv.indexOf("telemetry") + 1];
-        const { exitCode, output } = telemetrySubcommand(sub);
-        process.stdout.write(output);
-        process.exit(exitCode);
-    }
     if (args.command === "scan") {
         try {
             const code = await runScan(args, rawArgv);
@@ -992,6 +969,19 @@ async function main() {
             process.exit(2);
         }
     }
+    if (args.command === "leash") {
+        try {
+            const { runLeash } = await import("./leash.js");
+            // rawArgv[0] is "leash" — pass the rest as subcommand + flags
+            const leashArgs = rawArgv.slice(rawArgv.indexOf("leash") + 1);
+            const result = await runLeash(leashArgs);
+            process.exit(result.exitCode);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
     if (args.command === "chat-only-hint") {
         const tried = args._slashTried || "<command>";
         error(`'${tried}' is a chat slash command, not a CLI subcommand.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",
@@ -70,6 +70,7 @@
     "index.mjs",
     "dist/",
     "agentshield-rules/",
+    "postinstall.mjs",
     "README.md"
   ],
   "type": "module",
@@ -77,6 +78,7 @@
     "build": "tsc",
     "test": "npm run build && node --test tests/*.test.mjs tests/**/*.test.mjs",
     "test:e2e": "npm run build && node ../../tests/run-archetype-e2e.mjs",
+    "postinstall": "node postinstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
@@ -86,4 +88,4 @@
   "engines": {
     "node": ">=18.17.0"
   }
-}
+}

package/postinstall.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * great-cto postinstall — best-effort one-time setup that runs when the npm
+ * package is installed globally or as a dependency.
+ *
+ * Currently does one thing: install llm-leash (https://github.com/avelikiy/llm-leash)
+ * for runtime governance — budget caps, audit log, kill switch, HITL gates.
+ *
+ * Design rules:
+ *   - NEVER fail the npm install. All errors swallowed.
+ *   - Idempotent — skips if ~/.great_cto/llm-leash already cloned.
+ *   - Honors GREAT_CTO_SKIP_LEASH=1 to opt out (CI envs, restricted machines).
+ *   - Skips on CI by default unless GREAT_CTO_FORCE_LEASH=1 — npm install in
+ *     CI shouldn't trigger 30s of git clone + pip install per build.
+ *   - Skips if `npm install` was invoked with --ignore-scripts (npm sets
+ *     `npm_config_ignore_scripts=true` — actually no, it just doesn't run
+ *     scripts; we can't detect it from inside).
+ *   - Detached output — postinstall noise is intentional and short.
+ *
+ * The "real" install path remains `great-cto leash install`. This hook just
+ * makes the common case (one-shot `npm install -g great-cto`) feel zero-config.
+ */
+
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const INSTALL_ROOT = path.join(homedir(), '.great_cto', 'llm-leash');
+
+function main() {
+  // ── opt-outs ─────────────────────────────────────────────────────────────
+  if (process.env.GREAT_CTO_SKIP_LEASH === '1') {
+    return; // silent
+  }
+
+  // Skip in CI unless explicitly forced — CI builds get no benefit from
+  // having leash installed in the runner's home dir, and the latency hurts.
+  const inCI = process.env.CI === 'true' || process.env.CI === '1';
+  if (inCI && process.env.GREAT_CTO_FORCE_LEASH !== '1') {
+    return;
+  }
+
+  // Already installed — fast exit
+  if (existsSync(INSTALL_ROOT)) {
+    return;
+  }
+
+  // Need git + python3 — bail silently if either is missing
+  if (!hasCommand('git') || !hasCommand('python3')) {
+    console.log('[great-cto] llm-leash skipped — git or python3 not on PATH');
+    console.log('[great-cto] run `great-cto leash install` later to enable runtime governance');
+    return;
+  }
+
+  // Locate the bundled dist/main.js — postinstall runs with cwd=package root
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const cli = path.join(here, 'dist', 'main.js');
+  if (!existsSync(cli)) {
+    return; // package built incorrectly — fail-safe
+  }
+
+  console.log('[great-cto] installing llm-leash for runtime governance (~30s) …');
+  console.log('[great-cto] opt out next time: GREAT_CTO_SKIP_LEASH=1 npm install -g great-cto');
+
+  const result = spawnSync(process.execPath, [cli, 'leash', 'install'], {
+    stdio: 'inherit',
+    timeout: 300_000,
+    env: { ...process.env, NO_COLOR: process.env.NO_COLOR || '1' },
+  });
+
+  if (result.status !== 0) {
+    console.log('[great-cto] llm-leash install hit an issue — run `great-cto leash install` later');
+  }
+}
+
+function hasCommand(cmd) {
+  try {
+    const r = spawnSync(cmd, ['--version'], { stdio: 'ignore', timeout: 3000 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+try { main(); } catch { /* never fail npm install */ }

package/dist/telemetry.js

@@ -1,225 +0,0 @@
-// Anonymous opt-IN telemetry — default OFF.
-//
-// See docs/PRIVACY.md for the full policy. Short version:
-//   - Default: disabled (opt-in)
-//   - Honors DO_NOT_TRACK=1 (industry standard, https://consoledonottrack.com)
-//   - Skipped automatically in CI environments
-//   - No paths, no code, no PII — just {ts, version, command, archetype, node, os, exit, duration_ms, anon_id}
-//   - anon_id is sha256(user@hostname) truncated to 8 hex chars; not reversible
-//
-// Opt-in (any one):
-//   GREAT_CTO_TELEMETRY=on               (env var)
-//   ~/.great_cto/telemetry.json: { "enabled": true }
-//   npx great-cto telemetry on
-//
-// Opt-out (overrides everything):
-//   DO_NOT_TRACK=1                       (highest priority)
-//   GREAT_CTO_TELEMETRY=off
-//   GREAT_CTO_DISABLE_TELEMETRY=1        (legacy alias from v2.x)
-//   GREATCTO_NO_TELEMETRY=1              (legacy alias from v2.x)
-//   ~/.great_cto/telemetry.json: { "enabled": false }
-//
-// Endpoint:  https://telemetry.greatcto.systems/v1/event  (Cloudflare Worker → D1)
-// Worker:    workers/telemetry/index.ts
-// Schema v1: see docs/PRIVACY.md "What we collect"
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import * as crypto from "node:crypto";
-const TELEMETRY_ENDPOINT = process.env.GREAT_CTO_TELEMETRY_ENDPOINT
-    || "https://great-cto-telemetry.alexander-velikiy.workers.dev/v1/event";
-// Note: workers.dev URL is the temporary default until telemetry.greatcto.systems
-// custom domain is bound. Override anytime with GREAT_CTO_TELEMETRY_ENDPOINT.
-const TELEMETRY_TIMEOUT_MS = 1000;
-// Allowlist — anything else is dropped client-side and server-side.
-const ALLOWED_COMMANDS = new Set([
-    "init", "scan", "ci", "list-rules", "board", "register",
-    "adapt", "mcp", "report", "serve", "webhook",
-    "version", "help", "telemetry",
-]);
-// Allowlist for archetype field. Match the 25 documented + "none" + "unknown".
-const ALLOWED_ARCHETYPES = new Set([
-    "none", "unknown", "greenfield",
-    "enterprise-saas", "agent-product", "ai-system", "mlops",
-    "cli-tool", "cli", "library", "sdk", "devtools",
-    "fintech", "regulated", "compliance",
-    "iot-embedded", "web3", "marketplace", "cms", "edtech",
-    "gov-public", "insurance", "data-platform", "streaming",
-    "mobile-app", "infra", "web-service", "agent",
-]);
-function configPath() {
-    return path.join(os.homedir(), ".great_cto", "telemetry.json");
-}
-function legacyConfigPath() {
-    return path.join(os.homedir(), ".great_cto", "config.json");
-}
-function readConfig() {
-    // Try new file first.
-    try {
-        return JSON.parse(fs.readFileSync(configPath(), "utf8"));
-    }
-    catch { /* fall through */ }
-    // Fall back to legacy config.json (read-only — never write to it).
-    try {
-        const legacy = JSON.parse(fs.readFileSync(legacyConfigPath(), "utf8"));
-        return { enabled: legacy.telemetry, install_id: legacy.install_id };
-    }
-    catch {
-        return {};
-    }
-}
-function writeConfig(cfg) {
-    const file = configPath();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
-}
-/** Detect CI / automation environments — never send from these. */
-function isCI() {
-    const flags = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "CIRCLECI", "BUILDKITE",
-        "JENKINS_URL", "TF_BUILD", "DRONE", "TRAVIS", "APPVEYOR",
-        "BITBUCKET_BUILD_NUMBER", "TEAMCITY_VERSION", "CODEBUILD_BUILD_ID"];
-    return flags.some(f => process.env[f] != null && process.env[f] !== "");
-}
-/** Compute anon_id deterministically per machine, never reversible. */
-export function computeAnonId() {
-    const seed = `great_cto/${os.userInfo().username || "?"}/${os.hostname() || "?"}`;
-    return crypto.createHash("sha256").update(seed).digest("hex").slice(0, 8);
-}
-/** Resolve telemetry-enabled state. Pure function, no side effects. */
-export function isTelemetryEnabled(cliFlag = false) {
-    // Opt-out wins, in priority order:
-    if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
-        return false;
-    if (process.env.GREAT_CTO_TELEMETRY === "off")
-        return false;
-    if (process.env.GREAT_CTO_DISABLE_TELEMETRY === "1")
-        return false;
-    if (process.env.GREATCTO_NO_TELEMETRY === "1")
-        return false;
-    if (cliFlag)
-        return false;
-    if (isCI())
-        return false;
-    // Opt-in checks:
-    if (process.env.GREAT_CTO_TELEMETRY === "on")
-        return true;
-    const cfg = readConfig();
-    if (cfg.enabled === true)
-        return true;
-    if (cfg.telemetry === true)
-        return true; // legacy
-    // Default: opt-out.
-    return false;
-}
-function sanitize(opts) {
-    const command = opts.command.toLowerCase();
-    if (!ALLOWED_COMMANDS.has(command))
-        return null;
-    const archetypeRaw = (opts.archetype || "none").toLowerCase().trim();
-    const archetype = ALLOWED_ARCHETYPES.has(archetypeRaw) ? archetypeRaw : "unknown";
-    return {
-        ts: new Date().toISOString(),
-        version: opts.cliVersion,
-        command,
-        archetype,
-        node: process.version.replace(/^v/, ""),
-        os: process.platform,
-        exit_code: typeof opts.exitCode === "number" ? opts.exitCode : 0,
-        duration_ms: typeof opts.durationMs === "number" ? Math.max(0, Math.round(opts.durationMs)) : 0,
-        anon_id: computeAnonId(),
-    };
-}
-/** Fire-and-forget POST. Never blocks. Never throws. Never logs unless DRYRUN. */
-async function send(evt) {
-    if (process.env.GREAT_CTO_TELEMETRY_DRYRUN === "1") {
-        process.stderr.write(`[telemetry] would-send: ${JSON.stringify(evt)}\n`);
-        return;
-    }
-    try {
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), TELEMETRY_TIMEOUT_MS);
-        await fetch(TELEMETRY_ENDPOINT, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(evt),
-            signal: ctrl.signal,
-        }).catch(() => { });
-        clearTimeout(timer);
-    }
-    catch { /* best-effort */ }
-}
-// --- Public API ------------------------------------------------------------
-/** First-run/install ping. Sent only when enabled. Idempotent across runs. */
-export async function sendInstallPing(opts) {
-    if (!opts.consent)
-        return;
-    if (!isTelemetryEnabled())
-        return;
-    const evt = sanitize({ cliVersion: opts.cliVersion, command: "init", archetype: opts.archetype });
-    if (!evt)
-        return;
-    await send(evt);
-}
-/** Per-command usage ping. Sent only when enabled. Fire-and-forget. */
-export async function sendUsagePing(opts) {
-    if (!isTelemetryEnabled())
-        return;
-    const evt = sanitize({
-        cliVersion: opts.cliVersion,
-        command: opts.subcommand,
-        archetype: opts.archetype,
-        exitCode: opts.exitCode,
-        durationMs: opts.durationMs,
-    });
-    if (!evt)
-        return;
-    await send(evt);
-}
-/**
- * Legacy shim — preserved for backwards compatibility with callers in main.ts
- * that pass `--no-telemetry`. With opt-IN default, consent resolution is
- * trivial: enabled iff isTelemetryEnabled() returns true.
- */
-export function resolveTelemetryConsent(cliFlag) {
-    return isTelemetryEnabled(cliFlag);
-}
-// --- `npx great-cto telemetry <on|off|status|whoami>` subcommand -----------
-export function telemetrySubcommand(arg) {
-    const action = (arg || "status").toLowerCase();
-    switch (action) {
-        case "on": {
-            const cfg = readConfig();
-            cfg.enabled = true;
-            writeConfig(cfg);
-            return { exitCode: 0, output: `✓ telemetry enabled (config: ${configPath()})\n` +
-                    `  Anonymous events go to ${TELEMETRY_ENDPOINT}\n` +
-                    `  See docs/PRIVACY.md for the full data schema.\n` };
-        }
-        case "off": {
-            const cfg = readConfig();
-            cfg.enabled = false;
-            writeConfig(cfg);
-            return { exitCode: 0, output: `✓ telemetry disabled (config: ${configPath()})\n` };
-        }
-        case "status": {
-            const enabled = isTelemetryEnabled();
-            const reason = enabled
-                ? "enabled (sending events to " + TELEMETRY_ENDPOINT + ")"
-                : isCI()
-                    ? "disabled (CI environment detected)"
-                    : process.env.DO_NOT_TRACK === "1"
-                        ? "disabled (DO_NOT_TRACK=1)"
-                        : "disabled (default; run 'great-cto telemetry on' to enable)";
-            return { exitCode: 0, output: `telemetry: ${reason}\n` +
-                    `anon_id  : ${computeAnonId()}\n` +
-                    `endpoint : ${TELEMETRY_ENDPOINT}\n` +
-                    `config   : ${configPath()}\n` };
-        }
-        case "whoami": {
-            return { exitCode: 0, output: computeAnonId() + "\n" };
-        }
-        default: {
-            return { exitCode: 2, output: `usage: great-cto telemetry <on|off|status|whoami>\n` };
-        }
-    }
-}