useathena 0.1.0

package/dist/cli/format.js

@@ -0,0 +1,76 @@
+/**
+ * Hand-rolled ANSI formatting — no dependency earns its keep for this.
+ * Honors NO_COLOR and non-TTY output.
+ */
+const enabled = process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+function paint(code, text) {
+    return enabled ? `[${code}m${text}` : text;
+}
+export const bold = (s) => paint(1, s);
+export const dim = (s) => paint(2, s);
+export const green = (s) => paint(32, s);
+export const yellow = (s) => paint(33, s);
+export const red = (s) => paint(31, s);
+export const cyan = (s) => paint(36, s);
+export const magenta = (s) => paint(35, s);
+export function statusBadge(status) {
+    switch (status) {
+        case "active":
+            return green("● active   ");
+        case "validated":
+            return cyan("◐ validated");
+        case "candidate":
+            return yellow("○ candidate");
+        case "stale":
+            return red("◌ stale    ");
+        case "retired":
+            return dim("· retired  ");
+        default:
+            return status;
+    }
+}
+export function readinessBadge(readiness) {
+    switch (readiness) {
+        case "act":
+            return green("ACT");
+        case "act_with_caveats":
+            return yellow("ACT WITH CAVEATS");
+        case "inspect_first":
+            return yellow("INSPECT FIRST");
+        case "ask_human":
+            return red("ASK HUMAN");
+        default:
+            return readiness;
+    }
+}
+export function confidenceBar(confidence) {
+    const filled = Math.round(confidence * 10);
+    const bar = "▰".repeat(filled) + "▱".repeat(10 - filled);
+    const color = confidence >= 0.7 ? green : confidence >= 0.4 ? yellow : red;
+    return `${color(bar)} ${confidence.toFixed(2)}`;
+}
+export function hitRate(upheld, overridden) {
+    const total = upheld + overridden;
+    if (total === 0)
+        return dim("no outcomes yet");
+    const rate = upheld / total;
+    const text = `${upheld}/${total} upheld`;
+    return rate >= 0.7 ? green(text) : rate >= 0.4 ? yellow(text) : red(text);
+}
+export function wrap(text, indent, width = 88) {
+    const words = text.split(/\s+/);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line.length + word.length + 1 > width && line.length > 0) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line.length === 0 ? word : `${line} ${word}`;
+        }
+    }
+    if (line.length > 0)
+        lines.push(line);
+    return lines.map((l) => indent + l).join("\n");
+}

package/dist/cli/setup.js

@@ -0,0 +1,316 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { configPath, dbPath, loadConfig, saveConfig } from "../config.js";
+import { DEFAULT_ANTHROPIC_MODEL, modelClientFromSpec, SUPPORTED_SPECS } from "../model/registry.js";
+import { bold, cyan, dim, green, red, yellow } from "./format.js";
+/**
+ * First-run wizard (aliases: setup, onboard): pick a model provider, prove it
+ * answers, wire up the sensors. `npx useathena onboard --yes` is the one-command
+ * path: it accepts every default, including a global self-install when running
+ * from the npx cache (hooks and MCP registrations must outlive cache pruning).
+ * Granular escape hatches: --model <spec>, --hook/--no-hook, --skip-test.
+ */
+const OLLAMA_TAGS_URL = "http://127.0.0.1:11434/api/tags";
+export async function runSetup(args, packageRoot) {
+    const interactive = process.stdin.isTTY === true && !args.includes("--yes");
+    const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+    try {
+        console.log(`${bold("athena setup")}\n`);
+        console.log(`${green("✓")} store ready at ${bold(dbPath())}`);
+        const config = loadConfig();
+        const spec = await chooseModelSpec(args, config, rl);
+        config.model = spec;
+        saveConfig(config);
+        console.log(`${green("✓")} model: ${bold(spec)} ${dim(`(saved to ${configPath()})`)}`);
+        if (!args.includes("--skip-test")) {
+            await testModel(spec, config);
+        }
+        const home = await ensureDurableInstall(rl, packageRoot);
+        const mcpRegistered = await offerClaudeCode(args, rl, home.bin);
+        if (!mcpRegistered) {
+            console.log(`\n${bold("connect your agent (MCP):")}`);
+            console.log(`  claude mcp add --scope user athena -- ${home.bin} mcp`);
+            console.log(dim(`  (other MCP clients: stdio command "${home.bin} mcp")`));
+        }
+        console.log(`\n${bold("browser sensor")} ${dim("(LinkedIn and Gmail draft edits)")}:`);
+        console.log(`  1. chrome://extensions → Developer mode → Load unpacked → ${join(home.root, "apps", "chrome-extension")}`);
+        console.log(`  2. run ${bold("athena serve")} and paste the printed token into the extension options page`);
+        console.log(`\n${bold("the loop:")} capture runs in the background — then`);
+        console.log(`  ${cyan("athena learn")}            infer tacit rules from captured evidence`);
+        console.log(`  ${cyan("athena rules")}            see what athena believes (and how confidently)`);
+        console.log(`  ${cyan('athena brief "task"')}     the judgment an agent gets before acting`);
+        console.log(dim(`\nrules serve themselves once replay-validated; they graduate to confident\nthrough upheld outcomes — or faster via: athena review`));
+    }
+    finally {
+        rl?.close();
+    }
+}
+async function chooseModelSpec(args, config, rl) {
+    const flagged = flag(args, "model");
+    if (flagged) {
+        modelClientFromSpec(flagged, config); // validate the spec before saving it
+        return flagged;
+    }
+    const options = await buildProviderOptions(config);
+    if (!rl) {
+        const auto = options.find((option) => option.auto !== undefined);
+        if (!auto?.auto) {
+            throw new Error(`no provider auto-detected — pass one explicitly: athena setup --model <spec>  (${SUPPORTED_SPECS})`);
+        }
+        return auto.auto;
+    }
+    console.log(`\n${bold("model provider")} ${dim("— powers rule inference; capture works without it")}`);
+    options.forEach((option, index) => {
+        console.log(`  ${bold(String(index + 1))}. ${option.name}  ${dim(option.hint)}`);
+    });
+    while (true) {
+        const answer = (await rl.question(`pick [1-${options.length}, default 1] > `)).trim();
+        const index = answer === "" ? 0 : Number(answer) - 1;
+        const option = options[index];
+        if (!option) {
+            console.log(yellow("not an option, try again"));
+            continue;
+        }
+        try {
+            return await option.resolve(rl, config);
+        }
+        catch (error) {
+            console.log(red(String(error instanceof Error ? error.message : error)));
+        }
+    }
+}
+async function buildProviderOptions(config) {
+    const options = [];
+    if (onPath("claude")) {
+        options.push({
+            name: "cli:claude",
+            hint: "your Claude subscription via the claude CLI — no API key",
+            auto: "cli:claude",
+            resolve: async () => "cli:claude",
+        });
+    }
+    if (onPath("codex")) {
+        options.push({
+            name: "cli:codex",
+            hint: "your ChatGPT subscription via the codex CLI — no API key",
+            auto: "cli:codex",
+            resolve: async () => "cli:codex",
+        });
+    }
+    const hasAnthropicKey = Boolean(process.env.ANTHROPIC_API_KEY ?? config.keys?.anthropic);
+    options.push({
+        name: "anthropic",
+        hint: hasAnthropicKey
+            ? `Anthropic API, key found — ${DEFAULT_ANTHROPIC_MODEL}`
+            : "Anthropic API — asks for an API key",
+        ...(hasAnthropicKey ? { auto: "anthropic" } : {}),
+        resolve: async (rl, config) => {
+            if (!hasAnthropicKey)
+                await promptForKey(rl, config, "anthropic", "ANTHROPIC_API_KEY");
+            return "anthropic";
+        },
+    });
+    const hasOpenAiKey = Boolean(process.env.OPENAI_API_KEY ?? config.keys?.openai);
+    options.push({
+        name: "openai",
+        hint: hasOpenAiKey ? "OpenAI API, key found — asks for a model" : "OpenAI API — asks for a key and a model",
+        resolve: async (rl, config) => {
+            if (!hasOpenAiKey)
+                await promptForKey(rl, config, "openai", "OPENAI_API_KEY");
+            const model = (await rl.question("OpenAI model name (e.g. gpt-5.2) > ")).trim();
+            if (!model)
+                throw new Error("a model name is required for the openai provider");
+            return `openai:${model}`;
+        },
+    });
+    const ollamaModels = await detectOllamaModels();
+    if (ollamaModels.length > 0) {
+        options.push({
+            name: "ollama",
+            hint: `local Ollama is running — ${ollamaModels.slice(0, 3).join(", ")}${ollamaModels.length > 3 ? ", …" : ""}`,
+            resolve: async (rl) => {
+                const fallback = ollamaModels[0] ?? "";
+                const model = (await rl.question(`Ollama model [${fallback}] > `)).trim() || fallback;
+                return `ollama:${model}`;
+            },
+        });
+    }
+    options.push({
+        name: "custom",
+        hint: `any spec: ${SUPPORTED_SPECS}`,
+        resolve: async (rl, config) => {
+            const spec = (await rl.question("model spec > ")).trim();
+            modelClientFromSpec(spec, config); // validate before accepting
+            return spec;
+        },
+    });
+    return options;
+}
+async function promptForKey(rl, config, provider, envVar) {
+    const key = (await rl.question(`${provider} API key ${dim(`(stored 0600 in ${configPath()}; or export ${envVar} instead)`)} > `)).trim();
+    if (!key)
+        throw new Error(`an API key is required — or export ${envVar} and re-run setup`);
+    config.keys = { ...config.keys, [provider]: key };
+}
+async function testModel(spec, config) {
+    console.log(dim(`testing ${spec} with one inference call (CLI runners can take ~30s)…`));
+    try {
+        const client = modelClientFromSpec(spec, config);
+        const result = await client.generateJson({
+            system: "You are a JSON echo. Reply with JSON only, no prose.",
+            prompt: 'Reply with exactly this JSON object: {"ok": true}',
+        });
+        if (typeof result !== "object" || result === null)
+            throw new Error(`unexpected reply: ${JSON.stringify(result)}`);
+        console.log(`${green("✓")} model responds`);
+    }
+    catch (error) {
+        console.log(red(`✗ model test failed: ${String(error instanceof Error ? error.message : error).slice(0, 200)}`));
+        console.log(dim("  the choice is saved anyway — fix the provider and re-run: athena setup"));
+    }
+}
+/**
+ * One-off runs from the npx (or pnpm dlx) cache must not be what hooks and MCP
+ * registrations point at — the cache gets pruned. Self-install globally so the
+ * recorded paths survive; the running package root is the install source, which
+ * works the same for registry, git, and tarball invocations.
+ */
+async function ensureDurableInstall(rl, packageRoot) {
+    const local = { root: packageRoot, bin: join(packageRoot, "bin", "athena") };
+    const parts = packageRoot.split(sep);
+    const ephemeral = parts.includes("_npx") || parts.some((part) => part.startsWith("dlx-"));
+    if (!ephemeral)
+        return local;
+    let wanted = true;
+    if (rl) {
+        const answer = (await rl.question(`\nRunning via npx — install athena globally so hooks and MCP survive the npx cache? [Y/n] `))
+            .trim()
+            .toLowerCase();
+        wanted = answer === "" || answer === "y" || answer === "yes";
+    }
+    if (!wanted) {
+        console.log(yellow("  skipping global install — hook/MCP paths will break when the npx cache is pruned"));
+        return local;
+    }
+    const packageName = readPackageName(packageRoot);
+    console.log(dim("installing globally (npm install -g)…"));
+    const install = spawnSync("npm", ["install", "-g", packageRoot], { encoding: "utf8" });
+    if (install.status !== 0) {
+        console.log(red(`✗ global install failed: ${(install.stderr ?? "").trim().slice(-300)}`));
+        console.log(yellow(`  continuing with npx-cache paths — install manually with: npm install -g ${packageName}`));
+        return local;
+    }
+    const prefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" }).stdout?.trim();
+    const root = prefix ? join(prefix, "lib", "node_modules", packageName) : "";
+    const bin = prefix ? join(prefix, "bin", "athena") : "";
+    if (root && existsSync(bin)) {
+        console.log(`${green("✓")} installed globally — ${bold("athena")} is now on your PATH`);
+        return { root, bin };
+    }
+    return local;
+}
+/** Wire up Claude Code end to end: sensor hook + MCP registration. */
+async function offerClaudeCode(args, rl, athenaBin) {
+    if (args.includes("--no-hook"))
+        return false;
+    const hasClaudeDir = existsSync(join(homedir(), ".claude"));
+    let wanted = args.includes("--hook") || (args.includes("--yes") && hasClaudeDir);
+    if (!wanted && rl && hasClaudeDir) {
+        const answer = (await rl.question(`\nWire up Claude Code? ${dim("(sensor hook + MCP registration)")} [Y/n] `))
+            .trim()
+            .toLowerCase();
+        wanted = answer === "" || answer === "y" || answer === "yes";
+    }
+    if (!wanted)
+        return false;
+    const { settingsPath, changed } = installClaudeCodeHook(athenaBin);
+    console.log(changed
+        ? `${green("✓")} hook installed in ${settingsPath} ${dim("(restart Claude Code sessions to pick it up)")}`
+        : `${green("✓")} hook already installed in ${settingsPath}`);
+    if (!onPath("claude"))
+        return false;
+    const existing = spawnSync("claude", ["mcp", "get", "athena"], { stdio: "ignore" });
+    if (existing.status === 0) {
+        console.log(`${green("✓")} MCP server already registered with Claude Code`);
+        return true;
+    }
+    const added = spawnSync("claude", ["mcp", "add", "--scope", "user", "athena", "--", athenaBin, "mcp"], {
+        encoding: "utf8",
+    });
+    if (added.status === 0) {
+        console.log(`${green("✓")} MCP server registered with Claude Code (scope: user)`);
+        return true;
+    }
+    console.log(yellow(`could not register MCP automatically: ${(added.stderr ?? "").trim().slice(-200)}`));
+    return false;
+}
+/**
+ * Merge the UserPromptSubmit hook into ~/.claude/settings.json. Any previous
+ * athena entry is replaced (handles a bin path that moved); everything else in
+ * the file is preserved, and the pre-edit file is kept as a one-off backup.
+ */
+export function installClaudeCodeHook(athenaBin) {
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    const command = `${athenaBin} hook user-prompt`;
+    let settings = {};
+    const exists = existsSync(settingsPath);
+    if (exists) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`${settingsPath} is not valid JSON (${String(error)}) — fix it or add the hook manually: athena hook install --print`);
+        }
+    }
+    const hooks = (settings.hooks ??= {});
+    const entries = (hooks.UserPromptSubmit ??= []);
+    const isAthena = (entry) => (entry.hooks ?? []).some((h) => h.command?.includes("hook user-prompt") === true && h.command.includes("athena"));
+    const kept = entries.filter((entry) => !isAthena(entry));
+    const upToDate = entries.some((entry) => (entry.hooks ?? []).some((h) => h.command === command));
+    if (upToDate && kept.length === entries.length - 1) {
+        return { settingsPath, changed: false };
+    }
+    kept.push({ hooks: [{ type: "command", command }] });
+    hooks.UserPromptSubmit = kept;
+    if (exists)
+        copyFileSync(settingsPath, `${settingsPath}.athena-backup`);
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return { settingsPath, changed: true };
+}
+async function detectOllamaModels() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1200);
+    try {
+        const response = await fetch(OLLAMA_TAGS_URL, { signal: controller.signal });
+        if (!response.ok)
+            return [];
+        const body = (await response.json());
+        return (body.models ?? []).map((m) => m.name).filter((name) => typeof name === "string");
+    }
+    catch {
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readPackageName(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return pkg.name ?? "useathena";
+    }
+    catch {
+        return "useathena";
+    }
+}
+function onPath(command) {
+    return spawnSync("which", [command], { stdio: "ignore" }).status === 0;
+}
+function flag(args, name) {
+    const index = args.indexOf(`--${name}`);
+    return index >= 0 ? args[index + 1] : undefined;
+}

package/dist/cli.js

@@ -0,0 +1,291 @@
+import { createInterface } from "node:readline/promises";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AthenaStore } from "./store/store.js";
+import { dbPath } from "./config.js";
+import { startApiServer } from "./api/server.js";
+import { handleUserPrompt } from "./sensors/claude-code-hook.js";
+import { modelClientFromSpec, resolveModelSpec } from "./model/registry.js";
+import { applyReview, cmdBrief, cmdCapture, cmdLearn, cmdOpen, cmdRules, cmdStatus, renderReviewItem, reviewQueue, } from "./cli/commands.js";
+import { recordOutcome } from "./serve/outcome.js";
+import { loadConfig } from "./config.js";
+import { installClaudeCodeHook, runSetup } from "./cli/setup.js";
+import { bold, dim, green, red, yellow } from "./cli/format.js";
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const athenaBin = join(packageRoot, "bin", "athena");
+const HELP = `${bold("athena")} — agents that learn the tacit knowledge behind how you work
+
+usage: athena <command> [args]
+
+  ${bold("setup")} [--model spec] [--yes]
+                            first-run wizard: store, model provider, sensors, MCP
+                            (alias: onboard — npx useathena onboard --yes)
+  ${bold("init")}                      create the local store and print MCP setup
+  ${bold("status")}                    what athena has captured, learned, and served
+  ${bold("rules")} [--domain d] [--all]  the learned tacit rules (--all includes stale/retired)
+  ${bold("review")}                    review queue: approve or reject inferred rules (optional —
+                            rules also graduate on their own via upheld outcomes)
+  ${bold("learn")} [--domain d]        run the hypothesis engine over captured instances
+  ${bold("capture")} <kind> --summary "..." [--domain d] [--before t|@f] [--after t|@f]
+                            capture a judgment moment (kinds: correction, override,
+                            decision, escalation, failed_attempt, approval, manual_note)
+  ${bold("brief")} "task" [--domain d]  compile the brief an agent would get for a task
+  ${bold("record")} outcome <briefId> <uncorrected|corrected|abandoned>
+  ${bold("open")} <athena://ref | id>  inspect any entity
+  ${bold("hook")} install [--print]    install the Claude Code sensor hook into ~/.claude/settings.json
+  ${bold("serve")} [--port n]          local API for browser sensors (default 127.0.0.1:4517)
+  ${bold("mcp")}                       run the MCP stdio server (claude mcp add athena -- athena mcp)
+
+store: ${dbPath()}  ${dim("(override with ATHENA_DB)")}
+model: ${resolveModelSpec(loadConfig())}  ${dim("(set via athena setup; override with ATHENA_MODEL)")}`;
+function flag(args, name) {
+    const index = args.indexOf(`--${name}`);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === "help" || command === "--help") {
+        console.log(HELP);
+        return;
+    }
+    if (command === "hook") {
+        await runHook(args);
+        return;
+    }
+    const store = new AthenaStore(dbPath());
+    try {
+        switch (command) {
+            case "setup":
+            case "onboard": {
+                await runSetup(args, packageRoot);
+                break;
+            }
+            case "init": {
+                console.log(`${green("✓")} store ready at ${bold(dbPath())}`);
+                console.log(`\nConnect your agent (Claude Code):\n  ${bold(`claude mcp add --scope user athena -- ${athenaBin} mcp`)}`);
+                console.log(`\nThen capture corrections (or let your agent record them) and run ${bold("athena learn")}.`);
+                console.log(dim(`\nfor the guided version (model provider, sensors): athena setup`));
+                break;
+            }
+            case "status":
+                console.log(cmdStatus(store));
+                break;
+            case "rules": {
+                const domain = flag(args, "domain");
+                console.log(cmdRules(store, {
+                    ...(domain !== undefined ? { domain } : {}),
+                    all: args.includes("--all"),
+                }));
+                break;
+            }
+            case "brief": {
+                const task = args.find((a) => !a.startsWith("--"));
+                if (!task)
+                    throw new Error('usage: athena brief "task description" [--domain d]');
+                console.log(cmdBrief(store, task, flag(args, "domain")));
+                break;
+            }
+            case "capture": {
+                const kind = args.find((a) => !a.startsWith("--"));
+                const summary = flag(args, "summary");
+                if (!kind || !summary)
+                    throw new Error('usage: athena capture <kind> --summary "..." [...]');
+                const domain = flag(args, "domain");
+                const task = flag(args, "task");
+                const before = flag(args, "before");
+                const after = flag(args, "after");
+                const app = flag(args, "app");
+                const flags = {
+                    kind,
+                    summary,
+                    ...(domain !== undefined ? { domain } : {}),
+                    ...(task !== undefined ? { task } : {}),
+                    ...(before !== undefined ? { before } : {}),
+                    ...(after !== undefined ? { after } : {}),
+                    ...(app !== undefined ? { app } : {}),
+                };
+                console.log(cmdCapture(store, flags));
+                break;
+            }
+            case "learn": {
+                const config = loadConfig();
+                const model = modelClientFromSpec(resolveModelSpec(config), config);
+                console.log(dim(`thinking with ${model.id}…`));
+                const domain = flag(args, "domain");
+                console.log(await cmdLearn(store, model, domain !== undefined ? { domain } : {}));
+                break;
+            }
+            case "review": {
+                await reviewLoop(store);
+                break;
+            }
+            case "record": {
+                const [sub, briefId, result] = args;
+                if (sub !== "outcome" || !briefId || !result) {
+                    throw new Error("usage: athena record outcome <briefId> <uncorrected|corrected|abandoned>");
+                }
+                const outcome = recordOutcome(store, { briefId: briefId, result: result });
+                console.log(`${green("✓")} recorded ${outcome.id} (${outcome.result})`);
+                break;
+            }
+            case "open": {
+                const ref = args[0];
+                if (!ref)
+                    throw new Error("usage: athena open <athena://ref | id>");
+                console.log(cmdOpen(store, ref));
+                break;
+            }
+            case "serve": {
+                const port = Number(flag(args, "port") ?? 4517);
+                const token = loadOrCreateServeToken();
+                const server = await startApiServer(store, { token, port });
+                const address = server.address();
+                const actualPort = address !== null && typeof address !== "string" ? address.port : port;
+                console.log(`${green("●")} athena API listening on ${bold(`http://127.0.0.1:${actualPort}`)}`);
+                console.log(`  token: ${bold(token)} ${dim("(paste into the extension options page)")}`);
+                console.log(dim("  ctrl-c to stop"));
+                await new Promise((resolve) => {
+                    process.on("SIGINT", () => {
+                        server.close();
+                        resolve();
+                    });
+                    process.on("SIGTERM", () => {
+                        server.close();
+                        resolve();
+                    });
+                });
+                break;
+            }
+            case "mcp": {
+                // stdio transport: stdout belongs to the protocol, so print nothing.
+                const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+                const { buildMcpServer } = await import("./mcp/server.js");
+                const server = buildMcpServer(store);
+                await server.connect(new StdioServerTransport());
+                await new Promise((resolve) => {
+                    process.on("SIGINT", resolve);
+                    process.on("SIGTERM", resolve);
+                });
+                break;
+            }
+            default:
+                console.error(red(`unknown command: ${command}`));
+                console.log(HELP);
+                process.exitCode = 1;
+        }
+    }
+    finally {
+        store.close();
+    }
+}
+/** The serve token guards the local API against other local processes. */
+function loadOrCreateServeToken() {
+    const tokenPath = join(dirname(dbPath()), "serve.token");
+    try {
+        const existing = readFileSync(tokenPath, "utf8").trim();
+        if (existing.length >= 16)
+            return existing;
+    }
+    catch {
+        // first run — create below
+    }
+    const token = randomBytes(24).toString("base64url");
+    mkdirSync(dirname(tokenPath), { recursive: true });
+    writeFileSync(tokenPath, `${token}\n`, { mode: 0o600 });
+    return token;
+}
+/**
+ * Hook mode runs on every prompt the user types into Claude Code:
+ * stdout stays silent (it would pollute agent context), errors go to
+ * ~/.athena/hook.log, and the exit code is always 0 — a broken sensor
+ * must never block the user's prompt.
+ */
+async function runHook(args) {
+    const sub = args[0];
+    if (sub === "install") {
+        if (args.includes("--print")) {
+            const snippet = {
+                hooks: {
+                    UserPromptSubmit: [{ hooks: [{ type: "command", command: `${athenaBin} hook user-prompt` }] }],
+                },
+            };
+            console.log(`Add this to .claude/settings.json (workspace or ~/.claude/settings.json):\n`);
+            console.log(JSON.stringify(snippet, null, 2));
+        }
+        else {
+            const { settingsPath, changed } = installClaudeCodeHook(athenaBin);
+            console.log(changed
+                ? `${green("✓")} hook installed in ${bold(settingsPath)} ${dim("(restart Claude Code sessions to pick it up)")}`
+                : `${green("✓")} hook already installed in ${bold(settingsPath)}`);
+        }
+        console.log(`\nThen connect the MCP server:\n  ${bold(`claude mcp add --scope user athena -- ${athenaBin} mcp`)}`);
+        return;
+    }
+    if (sub !== "user-prompt") {
+        console.error(red("usage: athena hook <user-prompt|install>"));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        let raw = "";
+        for await (const chunk of process.stdin)
+            raw += chunk;
+        const input = JSON.parse(raw);
+        if (typeof input.prompt !== "string")
+            return;
+        const store = new AthenaStore(dbPath());
+        try {
+            handleUserPrompt(store, input);
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (error) {
+        try {
+            const logDir = join(homedir(), ".athena");
+            mkdirSync(logDir, { recursive: true });
+            appendFileSync(join(logDir, "hook.log"), `${new Date().toISOString()} ${String(error)}\n`);
+        }
+        catch {
+            // a broken sensor must never block the prompt
+        }
+    }
+}
+async function reviewLoop(store) {
+    const queue = reviewQueue(store);
+    if (queue.length === 0) {
+        console.log(dim("review queue is empty"));
+        return;
+    }
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (const [index, hypothesis] of queue.entries()) {
+            console.log(`\n${renderReviewItem(store, hypothesis, index + 1, queue.length)}\n`);
+            const answer = (await readline.question(`${bold("[a]")}pprove  ${bold("[r]")}eject  ${bold("[s]")}kip  ${bold("[q]")}uit > `))
+                .trim()
+                .toLowerCase();
+            if (answer === "a") {
+                applyReview(store, hypothesis.id, "approve");
+                console.log(green("approved — now served to agents"));
+            }
+            else if (answer === "r") {
+                applyReview(store, hypothesis.id, "reject");
+                console.log(red("rejected — retired"));
+            }
+            else if (answer === "q") {
+                break;
+            }
+            else {
+                console.log(yellow("skipped"));
+            }
+        }
+    }
+    finally {
+        readline.close();
+    }
+}
+await main();