useathena 0.1.0 → 0.2.1

package/README.md

@@ -44,11 +44,15 @@ The MVP is not a broad knowledge base. It is a working closed loop for tacit jud
    - Every learned rule cites the evidence that produced it.
    - Agents can propose evidence and outcomes, but cannot directly mutate durable rules.
 
-3. Infer tacit rules from evidence.
+3. Infer tacit rules — and explicit facts — from evidence.
    - The hypothesis engine clusters examples by domain.
    - It infers cues, expectancies, goals, rules, and boundary conditions.
    - It replay-validates against held-out examples before a rule can be served.
-   - Inference is model-backed, not a fake deterministic string matcher.
+   - It also extracts entity facts ("Acme's renewal is in September") — deduped,
+     cited, and staleness-tracked; restatements confirm instead of duplicating.
+   - Inference is model-backed, not a fake deterministic string matcher — and it
+     triggers itself: once enough new evidence accumulates, a background
+     `athena learn` runs automatically (disable with `ATHENA_AUTO_LEARN=off`).
 
 4. Validate before serving; review is optional.
    - Replay-validated rules are served to agents immediately, flagged with caveats.
@@ -59,10 +63,18 @@ The MVP is not a broad knowledge base. It is a working closed loop for tacit jud
 
 5. Brief agents before they act.
    - MCP exposes exactly four tools: `athena_brief`, `athena_open`, `athena_record`, and `athena_search`.
-   - A brief returns applicable rules, confidence, boundaries, citations, do-not-assume items, open questions, and a readiness verdict.
-
-6. Learn from outcomes.
-   - Agents record whether their briefed output was accepted, corrected, abandoned, or unknown.
+   - A brief returns applicable rules, confidence, boundaries, citations, entity facts, do-not-assume items, open questions, and a readiness verdict.
+   - It also carries a knowledge map — what else athena knows and the query that
+     retrieves each slice — so agents pull what they need instead of being flooded.
+
+6. Learn from outcomes — mostly without anyone reporting.
+   - Agents register the artifact they produced (`athena_record type=output`); when
+     a sensor later captures what the human actually did with it, the outcome
+     records itself: approval → uncorrected, edit → corrected with the diff as a
+     counterexample. Matching is conservative; a false match would corrupt trust.
+   - Short approval sign-offs in Claude Code ("lgtm", "ship it") count as observed
+     approvals; unresolved drafts expire to `unknown` after the match window.
+   - Explicit reporting still works everywhere sensors can't see.
    - Rules gain trust when upheld and lose trust when overridden.
    - Repeated counterexamples make rules stale.
 
@@ -75,18 +87,26 @@ Implemented:
 - Core schema and typed domain model.
 - SQLite store with invariants and lexical search.
 - Capture ingestion with structured diffs.
-- LLM-backed hypothesis engine.
+- LLM-backed hypothesis engine, plus entity-fact extraction from the same
+  evidence (deduped, cited, staleness-tracked; `athena facts`).
+- Auto-learn: sensors trigger a background `athena learn` once enough new
+  evidence accumulates — the loop no longer stalls on a forgotten command.
 - Model-agnostic providers: `cli:claude`, `cli:codex`, Anthropic API,
   OpenAI-compatible APIs, and local models via Ollama / LM Studio / vLLM.
 - Golden-scenario eval harness.
-- Brief compilation, outcome recording, and autonomous rule promotion
-  (validated rules graduate to active through upheld outcomes).
+- Brief compilation with a knowledge map, outcome recording, and autonomous rule
+  promotion (validated rules graduate to active through upheld outcomes).
+- Automatic outcome detection: agents register drafts (`athena_record
+  type=output` / `athena record output`), sensors match what the human actually
+  sent, and the outcome records itself.
 - MCP server with the four-tool agent surface (`athena mcp`).
 - CLI with a first-run `athena setup` wizard, plus init, status, capture, learn,
-  review, brief, rules, open, record, serve, and hook install.
-- Claude Code sensor hook (installed by `athena setup` or `athena hook install`).
-- Localhost API for browser sensors.
+  review, brief, rules, facts, open, record, export, serve, and hook install.
+- Claude Code sensor hook (corrections, approvals, and `remember:` notes).
+- Localhost API for browser sensors — installable as a login service
+  (`athena serve install`, done by setup) so capture survives reboots.
 - Chrome extension v0.1 for LinkedIn and Gmail draft-edit capture.
+- `athena export`: one JSON bundle of everything learned (`--redact` for sharing).
 - One-command onboarding: `npx useathena onboard --yes` (npm package `useathena`,
   binary `athena`; GitHub installs work too).
 
@@ -141,9 +161,12 @@ Onboarding does everything: creates the local store, detects which model provide
 you have (claude CLI, codex CLI, Anthropic or OpenAI API keys, a running Ollama),
 verifies the one you pick with a real inference call, installs itself globally so
 hooks survive the npx cache, wires up Claude Code (sensor hook + MCP registration),
-and prints the browser-extension setup. `--yes` takes the first detected provider
-and says yes to all of it; opt out per-piece with `--no-hook`, `--skip-test`, or
-`--model <spec>`.
+installs the browser-sensor API as a login service, and prints the extension setup
+with its token. `--yes` takes the first detected provider and says yes to all of it;
+opt out per-piece with `--no-hook`, `--no-service`, `--skip-test`, or `--model <spec>`.
+
+Already installed? `athena update` pulls the latest published version and
+restarts the background serve service on the new code.
 
 Model providers are spec strings, set once by `setup` (or per-run via `ATHENA_MODEL`):
 
@@ -194,10 +217,12 @@ npm run athena -- capture correction \
   --after "Saw your post on GTM hiring. Would be glad to connect."
 ```
 
-Learn candidate rules from captured evidence:
+Learn candidate rules (and entity facts) from captured evidence — this also runs
+automatically in the background once enough new evidence accumulates:
 
 ```bash
 npm run athena -- learn --domain linkedin.outreach
+npm run athena -- facts
 ```
 
 Review inferred rules:
@@ -212,12 +237,19 @@ Ask for the kind of brief an agent should get before acting:
 npm run athena -- brief "draft a LinkedIn connection note to a GTM leader" --domain linkedin.outreach
 ```
 
-Start the localhost API for the Chrome extension:
+Start the localhost API for the Chrome extension (or install it as a login
+service with `serve install`):
 
 ```bash
 npm run athena -- serve
 ```
 
+Export everything athena has learned as one JSON bundle (`--redact` strips raw text):
+
+```bash
+npm run athena -- export
+```
+
 ## Design principles
 
 - Instances are immutable evidence; hypotheses are revisable views over evidence.

package/dist/api/server.js

@@ -1,6 +1,10 @@
 import { createServer } from "node:http";
-import { timingSafeEqual } from "node:crypto";
-import { ingestSensorEvent } from "../capture/ingest.js";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { dbPath } from "../config.js";
+import { ingestAndMatch } from "../serve/auto-outcome.js";
+import { maybeAutoLearn } from "../serve/auto-learn.js";
 /**
  * The localhost door for browser sensors. Deliberately tiny:
  *   GET  /health  → liveness, no auth
@@ -20,6 +24,22 @@ const INSTANCE_KINDS = new Set([
     "approval",
     "manual_note",
 ]);
+/** The serve token guards the local API against other local processes. */
+export 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;
+}
 export function startApiServer(store, options) {
     const server = createServer((request, response) => {
         void handle(store, options, request, response);
@@ -47,8 +67,14 @@ async function handle(store, options, request, response) {
         try {
             const body = await readBody(request);
             const event = parseEvent(body, options.sensorId ?? "sen_extension");
-            const instance = ingestSensorEvent(store, event);
-            json(response, 201, { captured: instance.id, kind: instance.kind, domain: instance.situation.domain });
+            const { instance, autoOutcome } = ingestAndMatch(store, event);
+            maybeAutoLearn(store);
+            json(response, 201, {
+                captured: instance.id,
+                kind: instance.kind,
+                domain: instance.situation.domain,
+                ...(autoOutcome ? { autoOutcome: { id: autoOutcome.id, result: autoOutcome.result } } : {}),
+            });
         }
         catch (error) {
             json(response, 400, { error: error instanceof Error ? error.message : "invalid request" });

package/dist/cli/commands.js

@@ -1,9 +1,13 @@
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { newId } from "../core/ids.js";
 import { refTo } from "../core/refs.js";
 import { openRef } from "../store/open.js";
-import { ingestSensorEvent } from "../capture/ingest.js";
+import { ingestAndMatch } from "../serve/auto-outcome.js";
+import { AUTO_LEARN_THRESHOLD, LAST_LEARN_AT } from "../serve/auto-learn.js";
 import { compileBrief } from "../serve/brief.js";
 import { LlmHypothesisEngine } from "../engine/engine.js";
+import { materializeFacts } from "../engine/facts.js";
 import { bold, confidenceBar, cyan, dim, green, hitRate, readinessBadge, red, statusBadge, wrap, yellow } from "./format.js";
 /**
  * Command logic, pure-ish: store in, rendered string out. The interactive
@@ -33,6 +37,16 @@ export function cmdStatus(store) {
                 : ""),
         `  ${bold(String(counts.briefs))} briefs served, ${bold(String(counts.outcomes))} outcomes recorded`,
     ];
+    if (counts.facts > 0) {
+        lines.splice(3, 0, `  ${bold(String(counts.facts))} fact${counts.facts === 1 ? "" : "s"} about ${bold(String(store.listObjects().length))} entities`);
+    }
+    if (counts.unmatchedDrafts > 0) {
+        lines.push(`  ${bold(String(counts.unmatchedDrafts))} agent draft${counts.unmatchedDrafts === 1 ? "" : "s"} awaiting an observed outcome`);
+    }
+    const pending = store.countInstancesSince(store.getMeta(LAST_LEARN_AT));
+    if (pending > 0) {
+        lines.push(`  ${bold(String(pending))} instance${pending === 1 ? "" : "s"} awaiting inference ${dim(`(auto-learn runs at ${AUTO_LEARN_THRESHOLD}; or now: athena learn)`)}`);
+    }
     if (judged.length > 0) {
         const rate = Math.round((corrected / judged.length) * 100);
         const paint = rate <= 30 ? green : rate <= 60 ? yellow : red;
@@ -118,8 +132,11 @@ export function cmdCapture(store, flags) {
         ...(flags.before !== undefined ? { before: { mediaType: "text/plain", content: maybeFile(flags.before) } } : {}),
         ...(flags.after !== undefined ? { after: { mediaType: "text/plain", content: maybeFile(flags.after) } } : {}),
     };
-    const instance = ingestSensorEvent(store, event);
-    return `${green("captured")} ${instance.id} ${dim(`(${instance.kind}, ${instance.situation.domain})`)}`;
+    const { instance, autoOutcome } = ingestAndMatch(store, event);
+    const matched = autoOutcome
+        ? `\n${green("✓")} matched a registered agent draft — outcome ${autoOutcome.result} recorded (${autoOutcome.id})`
+        : "";
+    return `${green("captured")} ${instance.id} ${dim(`(${instance.kind}, ${instance.situation.domain})`)}${matched}`;
 }
 function maybeFile(value) {
     return value.startsWith("@") ? readFileSync(value.slice(1), "utf8") : value;
@@ -134,20 +151,79 @@ export async function cmdLearn(store, model, options = {}) {
     }
     const engine = new LlmHypothesisEngine(model);
     const inferred = await engine.infer(instances);
+    store.setMeta(LAST_LEARN_AT, new Date().toISOString());
     const existingRules = new Set(store.listHypotheses({ limit: 1000 }).map((h) => h.rule));
     let saved = 0;
     const lines = [];
-    for (const hypothesis of inferred) {
+    for (const hypothesis of inferred.hypotheses) {
         if (existingRules.has(hypothesis.rule))
             continue;
         store.saveHypothesis(hypothesis);
         saved += 1;
         lines.push("", renderRule(hypothesis));
     }
-    const header = `${bold(String(saved))} new rule${saved === 1 ? "" : "s"} from ${instances.length} instances ${dim(`(engine: ${model.id})`)}`;
+    const { created, confirmed } = materializeFacts(store, inferred.facts);
+    for (const fact of created) {
+        const entity = store.getObject(fact.objectId);
+        lines.push("", `${cyan("fact")} ${dim(`(${entity?.name ?? fact.objectId})`)} ${wrap(fact.statement, "  ").trim()}`);
+    }
+    const factNote = created.length + confirmed.length > 0
+        ? `, ${bold(String(created.length))} new fact${created.length === 1 ? "" : "s"}${confirmed.length > 0 ? ` (${confirmed.length} confirmed)` : ""}`
+        : "";
+    const header = `${bold(String(saved))} new rule${saved === 1 ? "" : "s"}${factNote} from ${instances.length} instances ${dim(`(engine: ${model.id})`)}`;
     const footer = saved > 0 ? `\n\n${yellow("review them: athena review")}` : "";
     return header + lines.join("\n") + footer;
 }
+export function cmdFacts(store, options = {}) {
+    let facts;
+    if (options.entity) {
+        const objects = store.resolveObject(options.entity);
+        if (objects.length === 0)
+            return dim(`no entity matches "${options.entity}"`);
+        facts = objects.flatMap((object) => store.listFacts({ objectId: object.id }));
+    }
+    else {
+        facts = store.listFacts(options.domain !== undefined ? { domain: options.domain } : {});
+    }
+    if (facts.length === 0) {
+        return dim("no facts yet — facts are extracted from evidence when you run: athena learn");
+    }
+    return facts
+        .map((fact) => {
+        const entity = store.getObject(fact.objectId);
+        return [
+            `${cyan(entity?.name ?? "?")}  ${confidenceBar(fact.confidence)}  ${dim(fact.domain)}  ${dim(fact.id)}`,
+            wrap(fact.statement, "  "),
+            dim(`  ${fact.supportingInstanceIds.length} supporting, last confirmed ${fact.lastConfirmedAt.slice(0, 10)}`),
+        ].join("\n");
+    })
+        .join("\n\n");
+}
+export function cmdRecordDraft(store, briefId, content) {
+    const brief = store.getBrief(briefId);
+    if (!brief)
+        throw new Error(`unknown brief ${briefId}`);
+    const draft = {
+        id: newId("drf"),
+        briefId: brief.id,
+        content,
+        contentHash: createHash("sha256").update(content).digest("hex").slice(0, 16),
+        mediaType: "text/plain",
+        domain: domainOfBrief(store, brief.id),
+        recordedAt: new Date().toISOString(),
+    };
+    store.saveDraft(draft);
+    return `${green("registered")} ${draft.id} ${dim("— the outcome records itself when a sensor sees the final version")}`;
+}
+function domainOfBrief(store, briefId) {
+    const brief = store.getBrief(briefId);
+    if (brief?.domain)
+        return brief.domain;
+    const first = brief?.rules[0];
+    if (first)
+        return store.getHypothesis(first.hypothesisId)?.domain ?? "general";
+    return "general";
+}
 // --- review queue ---
 export function reviewQueue(store) {
     return store

package/dist/cli/export.js

@@ -0,0 +1,35 @@
+/**
+ * One self-describing JSON bundle of everything athena has learned and how it
+ * got there — the raw material for improving the engine: wrong rules become
+ * eval scenarios, missed captures become sensor fixes, outcome history grades
+ * the briefs. `redact` strips raw text (artifact contents, probe answers) and
+ * keeps structure + metrics, for sharing outside the inner circle.
+ */
+export const EXPORT_FORMAT_VERSION = 1;
+export function buildExport(store, options = {}) {
+    const instances = store.listInstances({ limit: 10_000 });
+    return {
+        athenaExport: EXPORT_FORMAT_VERSION,
+        exportedAt: new Date().toISOString(),
+        redacted: options.redact === true,
+        counts: store.counts(),
+        hypotheses: store.listHypotheses({ limit: 10_000 }),
+        facts: store.listFacts({ limit: 10_000 }),
+        objects: store.listObjects(),
+        instances: options.redact ? instances.map(redactInstance) : instances,
+        briefs: store.listBriefs(10_000),
+        outcomes: store.listOutcomes(),
+        drafts: store.listDrafts().map((draft) => (options.redact ? { ...draft, content: "(redacted)" } : draft)),
+    };
+}
+function redactInstance(instance) {
+    return {
+        ...instance,
+        ...(instance.before ? { before: { ...instance.before, content: "(redacted)" } } : {}),
+        ...(instance.after ? { after: { ...instance.after, content: "(redacted)" } } : {}),
+        ...(instance.diff
+            ? { diff: { ...instance.diff, hunks: [] } }
+            : {}),
+        probeAnswers: instance.probeAnswers.map((probe) => ({ ...probe, answer: "(redacted)" })),
+    };
+}

package/dist/cli/service.js

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { dbPath } from "../config.js";
+/**
+ * Keep `athena serve` running without a dedicated terminal: a per-user login
+ * service (launchd on macOS, systemd --user on Linux) runs the same command
+ * the user would run by hand and restarts it if it dies. Logs land next to
+ * the store so `athena serve` stays debuggable.
+ */
+export const SERVICE_LABEL = "com.useathena.serve";
+export const SYSTEMD_UNIT = "athena-serve.service";
+export function launchdPlist(nodePath, athenaBin, logPath) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${athenaBin}</string>
+    <string>serve</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logPath}</string>
+  <key>StandardErrorPath</key><string>${logPath}</string>
+</dict>
+</plist>
+`;
+}
+export function systemdUnit(nodePath, athenaBin) {
+    return `[Unit]
+Description=athena local API for browser sensors
+
+[Service]
+ExecStart=${nodePath} ${athenaBin} serve
+Restart=always
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function serviceInstalled(platform = process.platform) {
+    if (platform === "darwin")
+        return existsSync(join(homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`));
+    if (platform === "linux")
+        return existsSync(join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT));
+    return false;
+}
+export function installService(athenaBin, platform = process.platform) {
+    const logPath = join(dirname(dbPath()), "serve.log");
+    if (platform === "darwin") {
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+        mkdirSync(dirname(plistPath), { recursive: true });
+        writeFileSync(plistPath, launchdPlist(process.execPath, athenaBin, logPath));
+        spawnSync("launchctl", ["unload", plistPath], { stdio: "ignore" }); // replace any previous version
+        const load = spawnSync("launchctl", ["load", plistPath], { encoding: "utf8" });
+        if (load.status !== 0) {
+            return {
+                installed: false,
+                path: plistPath,
+                message: `wrote ${plistPath} but launchctl load failed: ${(load.stderr ?? "").trim().slice(0, 200)}`,
+            };
+        }
+        return { installed: true, path: plistPath, message: `serve runs at login (launchd ${SERVICE_LABEL}, logs: ${logPath})` };
+    }
+    if (platform === "linux") {
+        const unitPath = join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT);
+        mkdirSync(dirname(unitPath), { recursive: true });
+        writeFileSync(unitPath, systemdUnit(process.execPath, athenaBin));
+        spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+        const enable = spawnSync("systemctl", ["--user", "enable", "--now", SYSTEMD_UNIT], { encoding: "utf8" });
+        if (enable.status !== 0) {
+            return {
+                installed: false,
+                path: unitPath,
+                message: `wrote ${unitPath} but systemctl enable failed: ${(enable.stderr ?? "").trim().slice(0, 200)}`,
+            };
+        }
+        return { installed: true, path: unitPath, message: `serve runs at login (systemd --user ${SYSTEMD_UNIT})` };
+    }
+    return { installed: false, message: `no service template for ${platform} — run "athena serve" manually or add it to your startup apps` };
+}
+export function uninstallService(platform = process.platform) {
+    if (platform === "darwin") {
+        const plistPath = join(homedir(), "Library", "LaunchAgents", `${SERVICE_LABEL}.plist`);
+        if (!existsSync(plistPath))
+            return { installed: false, message: "no launchd agent installed" };
+        spawnSync("launchctl", ["unload", plistPath], { stdio: "ignore" });
+        rmSync(plistPath);
+        return { installed: false, path: plistPath, message: `removed ${plistPath}` };
+    }
+    if (platform === "linux") {
+        const unitPath = join(homedir(), ".config", "systemd", "user", SYSTEMD_UNIT);
+        if (!existsSync(unitPath))
+            return { installed: false, message: "no systemd unit installed" };
+        spawnSync("systemctl", ["--user", "disable", "--now", SYSTEMD_UNIT], { stdio: "ignore" });
+        rmSync(unitPath);
+        spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+        return { installed: false, path: unitPath, message: `removed ${unitPath}` };
+    }
+    return { installed: false, message: `nothing to uninstall on ${platform}` };
+}

package/dist/cli/setup.js

@@ -4,14 +4,16 @@ 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 { loadOrCreateServeToken } from "../api/server.js";
 import { DEFAULT_ANTHROPIC_MODEL, modelClientFromSpec, SUPPORTED_SPECS } from "../model/registry.js";
+import { installService } from "./service.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.
+ * Granular escape hatches: --model <spec>, --hook/--no-hook, --no-service, --skip-test.
  */
 const OLLAMA_TAGS_URL = "http://127.0.0.1:11434/api/tags";
 export async function runSetup(args, packageRoot) {
@@ -35,9 +37,15 @@ export async function runSetup(args, packageRoot) {
             console.log(`  claude mcp add --scope user athena -- ${home.bin} mcp`);
             console.log(dim(`  (other MCP clients: stdio command "${home.bin} mcp")`));
         }
+        const serviceRunning = await offerServeService(args, rl, home.bin);
         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`);
+        if (serviceRunning) {
+            console.log(`  2. extension options page → token ${bold(loadOrCreateServeToken())}`);
+        }
+        else {
+            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)`);
@@ -212,6 +220,26 @@ async function ensureDurableInstall(rl, packageRoot) {
     }
     return local;
 }
+/**
+ * The browser sensor only captures while `athena serve` is up — installing it
+ * as a login service removes the "keep a terminal open" failure mode.
+ */
+async function offerServeService(args, rl, athenaBin) {
+    if (args.includes("--no-service"))
+        return false;
+    let wanted = args.includes("--yes");
+    if (!wanted && rl) {
+        const answer = (await rl.question(`\nRun the browser-sensor API at login? ${dim("(background service for athena serve)")} [Y/n] `))
+            .trim()
+            .toLowerCase();
+        wanted = answer === "" || answer === "y" || answer === "yes";
+    }
+    if (!wanted)
+        return false;
+    const result = installService(athenaBin);
+    console.log(result.installed ? `${green("✓")} ${result.message}` : yellow(`  ${result.message}`));
+    return result.installed;
+}
 /** Wire up Claude Code end to end: sensor hook + MCP registration. */
 async function offerClaudeCode(args, rl, athenaBin) {
     if (args.includes("--no-hook"))

package/dist/cli/update.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { installService, serviceInstalled } from "./service.js";
+import { bold, dim, green, red, yellow } from "./format.js";
+export function compareVersions(a, b) {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return Math.sign(diff);
+    }
+    return 0;
+}
+export function planUpdate(opts) {
+    if (opts.devCheckout)
+        return "dev-checkout";
+    return compareVersions(opts.current, opts.latest) < 0 ? "install" : "up-to-date";
+}
+export function readPackageInfo(packageRoot) {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+    return { name: pkg.name, version: pkg.version };
+}
+export async function fetchLatestVersion(name, timeoutMs = 10_000) {
+    const response = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok)
+        throw new Error(`npm registry lookup failed: HTTP ${response.status}`);
+    const body = (await response.json());
+    if (!body.version)
+        throw new Error("npm registry reply had no version");
+    return body.version;
+}
+export function nudgeLine(current, latest) {
+    if (compareVersions(current, latest) >= 0)
+        return undefined;
+    return `\n${yellow("↑")} ${latest} is out (you run ${current}) — update with ${bold("athena update")}`;
+}
+/** One quiet line at the end of `athena status` when the registry is ahead; silent offline. */
+export async function updateNudge(packageRoot) {
+    try {
+        const { name, version } = readPackageInfo(packageRoot);
+        return nudgeLine(version, await fetchLatestVersion(name, 1_500));
+    }
+    catch {
+        return undefined;
+    }
+}
+function globalAthenaBin() {
+    const prefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" }).stdout?.trim();
+    if (!prefix)
+        return undefined;
+    const bin = join(prefix, "bin", "athena");
+    return existsSync(bin) ? bin : undefined;
+}
+export async function runUpdate(packageRoot, athenaBin) {
+    const { name, version } = readPackageInfo(packageRoot);
+    const latest = await fetchLatestVersion(name);
+    const plan = planUpdate({ current: version, latest, devCheckout: existsSync(join(packageRoot, ".git")) });
+    if (plan === "dev-checkout") {
+        console.log(`${yellow("dev checkout")} at ${packageRoot} — update with ${bold("git pull")} (running ${version}, registry has ${latest})`);
+        return;
+    }
+    if (plan === "up-to-date") {
+        console.log(`${green("✓")} athena ${version} is up to date`);
+        return;
+    }
+    console.log(dim(`updating ${name} ${version} → ${latest} (npm install -g)…`));
+    const install = spawnSync("npm", ["install", "-g", `${name}@latest`], { encoding: "utf8" });
+    if (install.status !== 0) {
+        console.log(red(`✗ update failed: ${(install.stderr ?? "").trim().slice(-300)}`));
+        console.log(yellow(`  retry manually: npm install -g ${name}@latest`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`${green("✓")} athena ${latest} installed`);
+    if (serviceInstalled()) {
+        const result = installService(globalAthenaBin() ?? athenaBin);
+        console.log(result.installed ? `${green("✓")} serve service restarted on ${latest}` : yellow(result.message));
+    }
+}