@gamaze/hicortex 0.18.2 → 0.19.0

package/dist/localhost-bypass.d.ts

@@ -0,0 +1,27 @@
+/** Marker filename inside the Hicortex home dir. */
+export declare const LOCALHOST_BYPASS_MARKER = ".allow-localhost-bypass";
+/** Marker contents — a one-line note. Its mere PRESENCE is the signal. */
+export declare const LOCALHOST_BYPASS_MARKER_CONTENT: string;
+/**
+ * Resolve the marker file path for a given home dir. Defaults to the canonical
+ * Hicortex home (honors HICORTEX_HOME), so callers in tests can point the env
+ * override at a temp dir.
+ */
+export declare function localhostBypassMarkerPath(home?: string): string;
+/**
+ * Does the localhost auth-bypass marker exist? Pure filesystem check — no
+ * logging, no side-effects. Used by both createAuthMiddleware (gates the
+ * bypass per-request via a boot-time capture in mcp-server.ts) and the
+ * hosted-mode boot assertion.
+ */
+export declare function localhostBypassEnabled(home?: string): boolean;
+/**
+ * Write the localhost auth-bypass marker file (self-hosted init only — never
+ * in hosted mode). Idempotent: overwrites an existing marker so a re-init
+ * refreshes the explanatory note. Ensures the parent dir exists. Does NOT
+ * touch auth or any other config — just the one marker file.
+ *
+ * Returns true when a NEW marker was created (for init's "✓" reporting), false
+ * when one already existed (refreshed in place).
+ */
+export declare function writeLocalhostBypassMarker(home?: string): boolean;

package/dist/localhost-bypass.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCALHOST_BYPASS_MARKER_CONTENT = exports.LOCALHOST_BYPASS_MARKER = void 0;
+exports.localhostBypassMarkerPath = localhostBypassMarkerPath;
+exports.localhostBypassEnabled = localhostBypassEnabled;
+exports.writeLocalhostBypassMarker = writeLocalhostBypassMarker;
+/**
+ * Localhost auth-bypass marker file (#110 §2, #271 — Phase 0B).
+ *
+ * The localhost auth bypass in createAuthMiddleware (viz.ts) is marker-GATED
+ * from 0.18: it applies ONLY when this marker file exists in the Hicortex
+ * home dir. Self-hosted `init` writes the marker, so existing installs keep
+ * working after upgrade + re-init; a hosted tenant dir provisioned by any
+ * means (script, hand, restored tar) is fail-closed by default — no marker,
+ * no bypass, every connection (localhost included) needs the bearer token.
+ *
+ * Rationale (spec 2026-07-27 §2): with the bypass unconditional, a future
+ * `trust proxy` enablement would make `req.ip` header-spoofable and the
+ * bypass remotely triggerable. Inverting the default to "off unless marked"
+ * makes the bypass opt-in via a filesystem side-effect of self-hosted init,
+ * so a tenant home built from a bare config + DB restore cannot accidentally
+ * ship with the bypass active. The hosted-mode boot assertion (mcp-server.ts)
+ * refuses to start if BOTH hostedMode=true AND the marker is present, so even
+ * a stray marker cannot open a hosted tenant.
+ *
+ * Marker file name: `.allow-localhost-bypass` (dot-prefixed; not a secret —
+ * its mere presence is the signal; no contents needed).
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_js_1 = require("./paths.js");
+/** Marker filename inside the Hicortex home dir. */
+exports.LOCALHOST_BYPASS_MARKER = ".allow-localhost-bypass";
+/** Marker contents — a one-line note. Its mere PRESENCE is the signal. */
+exports.LOCALHOST_BYPASS_MARKER_CONTENT = "# Written by `hicortex init` (self-hosted). Opt-in to the localhost auth\n" +
+    "# bypass. DELETE this file to require the bearer token on localhost too\n" +
+    "# (fail-closed). Hosted-mode (hostedMode:true) refuses to start with this\n" +
+    "# marker present — see specs/2026-07-27-hosted-service.md §2.\n";
+/**
+ * Resolve the marker file path for a given home dir. Defaults to the canonical
+ * Hicortex home (honors HICORTEX_HOME), so callers in tests can point the env
+ * override at a temp dir.
+ */
+function localhostBypassMarkerPath(home = (0, paths_js_1.hicortexHome)()) {
+    return (0, node_path_1.join)(home, exports.LOCALHOST_BYPASS_MARKER);
+}
+/**
+ * Does the localhost auth-bypass marker exist? Pure filesystem check — no
+ * logging, no side-effects. Used by both createAuthMiddleware (gates the
+ * bypass per-request via a boot-time capture in mcp-server.ts) and the
+ * hosted-mode boot assertion.
+ */
+function localhostBypassEnabled(home = (0, paths_js_1.hicortexHome)()) {
+    return (0, node_fs_1.existsSync)(localhostBypassMarkerPath(home));
+}
+/**
+ * Write the localhost auth-bypass marker file (self-hosted init only — never
+ * in hosted mode). Idempotent: overwrites an existing marker so a re-init
+ * refreshes the explanatory note. Ensures the parent dir exists. Does NOT
+ * touch auth or any other config — just the one marker file.
+ *
+ * Returns true when a NEW marker was created (for init's "✓" reporting), false
+ * when one already existed (refreshed in place).
+ */
+function writeLocalhostBypassMarker(home = (0, paths_js_1.hicortexHome)()) {
+    const markerPath = localhostBypassMarkerPath(home);
+    const existed = (0, node_fs_1.existsSync)(markerPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(markerPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(markerPath, exports.LOCALHOST_BYPASS_MARKER_CONTENT, { mode: 0o644 });
+    return !existed;
+}

package/dist/mcp-server.d.ts

@@ -10,7 +10,25 @@
  *   GET  /sse        — SSE stream for MCP clients
  *   POST /messages   — message endpoint for MCP clients
  */
+import express from "express";
 import type { MemorySearchResult } from "./types.js";
+/**
+ * Resolve the request body-size limit in MB (#7). Pure — exported for tests.
+ * Precedence: an explicit config value > hosted-mode default (5) > self-hosted
+ * default (25, the historical fixed value → no regression). A finite positive
+ * config value wins; invalid/absent falls through.
+ */
+export declare function resolveBodyLimitMb(configVal: unknown, hostedMode: boolean): number;
+/**
+ * Express error middleware (#7): translate express.json's default HTML 413
+ * (entity.too.large) into a consistent JSON response. Catches body-parser
+ * errors only — which express.json emits BEFORE any route runs — so by
+ * registration order (this sits ahead of the routes) it never intercepts an
+ * error thrown inside a route handler; those reach Express's default handler.
+ * The `status === 413 || type === "entity.too.large"` check is defense-in-depth
+ * on top of that ordering. Exported so tests exercise the real handler.
+ */
+export declare function makeBodyLimitErrorHandler(limitMb: number): express.ErrorRequestHandler;
 export declare function startServer(options?: {
     port?: number;
     host?: string;

package/dist/mcp-server.js

@@ -48,6 +48,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBodyLimitMb = resolveBodyLimitMb;
+exports.makeBodyLimitErrorHandler = makeBodyLimitErrorHandler;
 exports.startServer = startServer;
 exports.formatResults = formatResults;
 const express_1 = __importDefault(require("express"));
@@ -59,6 +61,10 @@ const db_js_1 = require("./db.js");
 const llm_js_1 = require("./llm.js");
 const features_js_1 = require("./features.js");
 const config_read_js_1 = require("./config-read.js");
+const localhost_bypass_js_1 = require("./localhost-bypass.js");
+const hosted_boot_js_1 = require("./hosted-boot.js");
+const token_budget_js_1 = require("./token-budget.js");
+const paths_js_1 = require("./paths.js");
 const state_js_1 = require("./state.js");
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
@@ -403,9 +409,94 @@ function createMcpServer() {
 // ---------------------------------------------------------------------------
 // HTTP server with SSE transport
 // ---------------------------------------------------------------------------
+/**
+ * Resolve the request body-size limit in MB (#7). Pure — exported for tests.
+ * Precedence: an explicit config value > hosted-mode default (5) > self-hosted
+ * default (25, the historical fixed value → no regression). A finite positive
+ * config value wins; invalid/absent falls through.
+ */
+function resolveBodyLimitMb(configVal, hostedMode) {
+    const cfg = Number(configVal);
+    if (Number.isFinite(cfg) && cfg > 0)
+        return cfg;
+    return hostedMode ? 5 : 25;
+}
+/**
+ * Express error middleware (#7): translate express.json's default HTML 413
+ * (entity.too.large) into a consistent JSON response. Catches body-parser
+ * errors only — which express.json emits BEFORE any route runs — so by
+ * registration order (this sits ahead of the routes) it never intercepts an
+ * error thrown inside a route handler; those reach Express's default handler.
+ * The `status === 413 || type === "entity.too.large"` check is defense-in-depth
+ * on top of that ordering. Exported so tests exercise the real handler.
+ */
+function makeBodyLimitErrorHandler(limitMb) {
+    return (err, _req, res, next) => {
+        const status = err.status;
+        const type = err.type;
+        if (status === 413 || type === "entity.too.large") {
+            res.status(413).json({ error: "request body too large", limit_mb: limitMb });
+            return;
+        }
+        next(err);
+    };
+}
 async function startServer(options = {}) {
     const port = options.port ?? 8787;
     const host = options.host ?? "0.0.0.0";
+    // ---------------------------------------------------------------------------
+    // Hosted-mode boot gate (#110 §1-§2, #271 — Phase 0B).
+    //
+    // MUST run BEFORE resolveDbPath/initDb: in hosted mode with HICORTEX_DB_PATH
+    // set, the server must refuse the attacker-chosen DB location WITHOUT first
+    // touching it. The hosted signals (hostedMode from config, bypassMarkerPresent
+    // from the marker file) do NOT depend on the DB, so reading them now is safe.
+    // CR warning 3: this block was previously after initDb, letting a hostile
+    // HICORTEX_DB_PATH create/touch a file at the chosen path before the gate.
+    //
+    // CR warning 1: the marker is a HOME-level file (like config.json, written by
+    // init to HICORTEX_HOME). Read it from hicortexHome() — NOT stateDir, which
+    // is dirname(dbPath) and drifts when HICORTEX_DB_PATH relocates the DB. The
+    // config key hostedMode likewise lives at <hicortexHome>/config.json.
+    //
+    // Decision logic lives in hosted-boot.ts (pure, unit-tested); the side-effect
+    // (console.error + process.exit) is local to boot. The marker state is
+    // captured once here and reused below to gate the localhost bypass in
+    // createAuthMiddleware (no per-request stat). CR warning 4: the upgrade-path
+    // warning is decided by the pure shouldEmitBypassWarning helper (behavior-
+    // tested), not an inline branch.
+    const bootConfig = readConfigFile((0, paths_js_1.hicortexHome)());
+    const hostedMode = (0, config_read_js_1.readStrictBoolean)(bootConfig ?? {}, "hostedMode") === true;
+    let bypassMarkerPresent = (0, localhost_bypass_js_1.localhostBypassEnabled)();
+    const bootDecision = (0, hosted_boot_js_1.checkHostedBoot)({
+        hostedMode,
+        dbPathEnvSet: !!process.env.HICORTEX_DB_PATH,
+        bypassMarkerPresent,
+    });
+    if (!bootDecision.ok) {
+        console.error(bootDecision.message);
+        process.exit(1);
+    }
+    // Upgrade migration (CR S1): self-hosted server-mode CC MCP registration
+    // carries NO bearer token (init.ts:192 — only client-mode adds the header),
+    // so it relies entirely on the localhost bypass. An existing install that
+    // upgrades without re-running init has no marker → the bypass silently
+    // disappears → every server-mode CC MCP call 401s. Auto-write the marker on
+    // first post-upgrade boot in self-hosted mode to preserve the prior
+    // unconditional-bypass behaviour. Hosted mode is untouched: checkHostedBoot
+    // refuses to start with a marker present, so this block — gated on
+    // !hostedMode — never runs for a hosted tenant. bypassMarkerPresent is
+    // reassigned so createAuthMiddleware below gates the bypass for THIS boot
+    // too (the file write and the in-memory flag stay in sync).
+    if (!hostedMode && !bypassMarkerPresent) {
+        (0, localhost_bypass_js_1.writeLocalhostBypassMarker)((0, paths_js_1.hicortexHome)());
+        bypassMarkerPresent = true;
+        console.log("[hicortex] Localhost auth-bypass marker written (upgrade migration).");
+    }
+    const bypassWarning = (0, hosted_boot_js_1.shouldEmitBypassWarning)(hostedMode, bypassMarkerPresent);
+    if (bypassWarning) {
+        console.warn(bypassWarning);
+    }
     // Initialize core
     const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
     console.log(`[hicortex] Initializing database at ${dbPath}`);
@@ -431,6 +522,17 @@ async function startServer(options = {}) {
         const { agentId } = (0, init_js_1.ensureAndPersistAgentId)((0, node_path_1.join)(stateDir, "config.json"));
         savedConfig.agentId = agentId;
     }
+    // #5: token-budget enforcement. Mode-agnostic — gates on cap > 0. Self-hosted
+    // uses config llmTokensPerMonth (default 0 = off); hosted uses HICORTEX_TOKEN_CAP
+    // env (provider-set, tenant-immutable) which takes precedence. Initialised here
+    // (after stateDir + savedConfig are known) so the warn-dedup can seed from state.
+    (0, token_budget_js_1.initTokenBudget)(stateDir, savedConfig?.llmTokensPerMonth);
+    // #7: request body-size limit. Config key wins; else 5 MB hosted / 25 MB
+    // self-hosted (the prior fixed value → no regression). Guards the OOM vector
+    // (the body is fully parsed into memory before the distiller truncates to 80K
+    // chars). Legitimate capture segments are ≤60K chars (~200KB), so this never
+    // constrains real flow — it's an abuse/backstop. Oversized → 413.
+    const bodyLimitMb = resolveBodyLimitMb(savedConfig?.distillBodyLimitMb, hostedMode);
     if (savedConfig?.llmBackend === "claude-cli") {
         const claudePath = (0, llm_js_1.findClaudeBinary)();
         if (claudePath) {
@@ -574,7 +676,11 @@ async function startServer(options = {}) {
     // Express app
     const app = (0, express_1.default)();
     // Raise the body limit — whole-session denoised transcripts exceed the 100 kB default.
-    app.use(express_1.default.json({ limit: "25mb" }));
+    app.use(express_1.default.json({ limit: `${bodyLimitMb}mb` }));
+    // #7: JSON 413 on body-limit exceed (see makeBodyLimitErrorHandler). Server-side
+    // only — the client capture loop treats 413 like any non-2xx (holds cursor);
+    // it never fires for legitimate capture (segments ≤200KB ≪ the limit).
+    app.use(makeBodyLimitErrorHandler(bodyLimitMb));
     // CORS: reflect ONLY explicitly-allowlisted origins (config.corsAllowedOrigins),
     // and never send Access-Control-Allow-Credentials. Reflecting any origin with
     // credentials — combined with the localhost auth bypass and the default 0.0.0.0
@@ -615,7 +721,7 @@ async function startServer(options = {}) {
     // /dashboard has its own shell-exemption pattern. Gives the console one entry
     // point: http://<host>:8787/ → /dashboard.
     app.get("/", (_req, res) => res.redirect("/dashboard"));
-    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious));
+    app.use((0, viz_js_1.createAuthMiddleware)(authToken, authTokenPrevious, bypassMarkerPresent));
     // SSE transport management — each connection gets its own McpServer instance
     const transports = new Map();
     // Health endpoint — PUBLIC minimal probe. Unauthenticated (the auth
@@ -935,7 +1041,8 @@ async function startServer(options = {}) {
     });
     // REST /distill — canonical capture endpoint (0.9.0+).
     // Every machine (including the server itself) POSTs denoised session text here.
-    // The server distills, embeds, stores. Body limit: 25 MB (raised at app init).
+    // The server distills, embeds, stores. Body limit: see `distillBodyLimitMb`
+    // (default 25 MB self-hosted / 5 MB hosted); oversized → 413 (#7).
     //
     // Accepts text (string, preferred nightly path) OR messages (array, legacy).
     // Performs session-level dedup when session_id is present without segment_id.
@@ -1027,12 +1134,27 @@ async function startServer(options = {}) {
         const sourcePrefix = session_id
             ? `${session_id}${segment_id ? `#${segment_id}` : ""}`
             : undefined;
+        // #5: declared outside the try so the finally can record tokens spent even
+        // when distillSession throws partway through (the LLM calls already happened).
+        let distillUsage = { prompt: 0, completion: 0, total: 0 };
         try {
+            // #5: token-budget gate — refuse (429) BEFORE the LLM call if the tenant is
+            // already at/over the monthly cap. Placed after the dedup short-circuits so
+            // a skipped duplicate neither trips the gate nor consumes budget. The client
+            // capture loop holds its cursor on 429 (dup-over-loss, capture.ts:303).
+            if ((0, token_budget_js_1.isTokenBudgetExceeded)(stateDir)) {
+                res.status(429).json({ error: "token budget exceeded", retry: "next billing period" });
+                return;
+            }
             // Collect gate-dropped entries so they can ride back in the response and
             // land in the caller's file-persisted nightly log (#156 audit trail); the
             // server-side per-entry console.log in distillChunk stays as well.
             const dropped = [];
-            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize, dropped);
+            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize, dropped, (u) => {
+                distillUsage.prompt += u.prompt_tokens ?? 0;
+                distillUsage.completion += u.completion_tokens ?? 0;
+                distillUsage.total += u.total_tokens ?? 0;
+            });
             // Phase 1 — embed every chunk up front (async). If ANY embed fails we
             // never reach the insert, so nothing is stored.
             const createdAt = new Date(date).toISOString();
@@ -1084,12 +1206,26 @@ async function startServer(options = {}) {
                 ids,
                 distilled: ids.length,
                 dropped: dropped.map((d) => (d.length > 120 ? `${d.slice(0, 120)}…` : d)),
+                // #287: this segment's metered usage — the same breakdown
+                // recordDistillUsage accrues below. Lets the capturing nightly
+                // attribute distill tokens in its dashboard snapshot
+                // (new_this_run.tokens_by_stage.distill). Always present (zeros when
+                // no chunk reached an LLM call); pre-#287 clients ignore it.
+                usage: distillUsage,
             });
         }
         catch (err) {
             res.status(500).json({ error: "Distillation failed" });
             console.error(`[hicortex] /distill: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
         }
+        finally {
+            // #5: record tokens spent against the monthly budget — in finally so a
+            // mid-distil throw (some chunks' LLM calls already happened) still counts.
+            // No-op when cap=0 (enforcement off) or distillUsage.total=0 (gate refused
+            // / no chunk reached an LLM call).
+            if (distillUsage.total > 0)
+                (0, token_budget_js_1.recordDistillUsage)(stateDir, distillUsage);
+        }
     });
     // -------------------------------------------------------------------------
     // REST /update — update a memory (and re-embed when content changes).
@@ -1367,6 +1503,13 @@ async function startServer(options = {}) {
     // express adapter that injects the live db + config. STRICTLY view-only —
     // no mutation endpoints on the dashboard surface.
     app.get("/dashboard/data", (0, dashboard_js_1.dashboardDataHandler)(() => db, () => readConfigFile(stateDir)));
+    // GET /account — account identity for the console nav (name/org/plan from
+    // config). The LIGHTWEIGHT twin of the account block inside /dashboard/data:
+    // the /viz and /identity/ui pages need only this, not the metric payload;
+    // also the natural whoami for the future OAuth session (#292). Bearer-only
+    // (standard auth middleware, no shell exemption — it carries data); localhost
+    // bypass applies. Handler lives in src/dashboard.ts next to its twin.
+    app.get("/account", (0, dashboard_js_1.accountHandler)(() => readConfigFile(stateDir)));
     // SSE endpoint — each connection gets its own McpServer + transport
     app.get("/sse", async (req, res) => {
         const transport = new sse_js_1.SSEServerTransport("/messages", res);

package/dist/memory-instructions.js

@@ -30,7 +30,7 @@ exports.MEMORY_SECTION_NAME = "memory";
  *  injected once per session into every agent on the fleet. */
 function renderMemoryInstructions() {
     return [
-        "Your long-term memory is Hicortex — shared across all agents and sessions.",
+        "Hicortex is your persistent identity and long-term memory: what you learn, decide, and correct survives every session, compaction, and model switch — one memory shared by all your agents.",
         "- A `## Memory recall (auto)` index may arrive with prompts: it is a MENU, not content. Fetch a full memory with `hicortex_get(id)` when the entry could change how you handle the current task.",
         "- Recall before assuming: `hicortex_search` for prior decisions/facts/preferences, `hicortex_recent` to catch up on a project.",
         "- Cite any memory you rely on by id + date, and mark it `FETCHED` (you read the full memory via `hicortex_get`) or `SNIPPET` (the one-line entry only). Don't present a SNIPPET citation as established. On conflicts, newer memories supersede older.",

package/dist/nightly.js

@@ -75,6 +75,7 @@ const capture_js_1 = require("./capture.js");
 const dashboard_js_1 = require("./dashboard.js");
 const telemetry_js_1 = require("./telemetry.js");
 const init_js_1 = require("./init.js");
+const backup_js_1 = require("./backup.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 function readNightlyConfig(stateDir) {
     const configPath = (0, node_path_1.join)(stateDir, "config.json");
@@ -168,7 +169,16 @@ function makeRemotePost(serverUrl, authToken) {
 async function normalizePostResult(resp) {
     if (resp.status === 201) {
         const data = (await resp.json().catch(() => ({})));
-        return { status: 201, distilled: data.distilled ?? 0, dropped: data.dropped ?? [] };
+        // #287: the daemon reports the segment's metered usage. Shape-validated
+        // so a partial payload can't NaN the run's totals; a pre-#287 daemon
+        // simply omits it → capture sums zero (snapshot stays consolidation-only).
+        const usage = parseUsage(data.usage);
+        return {
+            status: 201,
+            distilled: data.distilled ?? 0,
+            dropped: data.dropped ?? [],
+            ...(usage ? { usage } : {}),
+        };
     }
     if (resp.status === 200) {
         const data = (await resp.json().catch(() => ({})));
@@ -177,6 +187,18 @@ async function normalizePostResult(resp) {
     const data = (await resp.json().catch(() => ({})));
     return { status: resp.status, error: data.error ?? "unknown error" };
 }
+/** Strict {prompt, completion, total} parser for /distill's usage field (#287);
+ *  undefined on anything malformed — the caller then treats it as unmetered. */
+function parseUsage(u) {
+    if (typeof u !== "object" || u === null)
+        return undefined;
+    const { prompt, completion, total } = u;
+    const num = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : null;
+    const p = num(prompt), c = num(completion), t = num(total);
+    if (p === null || c === null || t === null)
+        return undefined;
+    return { prompt: p, completion: c, total: t };
+}
 function writeLastRun(stateDir = HICORTEX_HOME) {
     (0, state_js_1.updateState)((s) => {
         s.lastNightly = new Date().toISOString();
@@ -347,6 +369,13 @@ async function runNightly(options = {}) {
         let batches = [];
         let memoriesIngested = 0;
         let hadTransientFailure = false;
+        // #287: distill tokens metered by the daemon across this run's segment
+        // POSTs (summed from the /distill responses by the capture loop).
+        // Forwarded to the dashboard snapshot so new_this_run.tokens is the run's
+        // TRUE total (distill + consolidation) and the distill share lands in
+        // tokens_by_stage. Zero when the daemon predates the usage field — the
+        // snapshot writer gates on total > 0, so old servers keep today's shape.
+        let distillUsage;
         // consolidateOnly (hosted service): skip capture entirely. The hosted
         // consolidation timer uses this so per-tenant nightly runs don't ingest the
         // operator's local sessions into the tenant's DB.
@@ -423,6 +452,7 @@ async function runNightly(options = {}) {
                         sourceDomain: savedConfig?.sourceDomain,
                     });
                     memoriesIngested = result.memoriesIngested;
+                    distillUsage = result.distillUsage;
                     // A 429/401 stop must hold the watermark too (fix 1): the loop abandoned
                     // the remaining sessions, and mtime discovery would never re-find them.
                     hadTransientFailure = result.hadTransientFailure || result.stopped !== undefined;
@@ -430,7 +460,12 @@ async function runNightly(options = {}) {
                 finally {
                     releaseLock();
                 }
-                console.log(`[hicortex] Capture complete: ${memoriesIngested} new memories`);
+                console.log(`[hicortex] Capture complete: ${memoriesIngested} new memories` +
+                    // #287: distill tokens the daemon metered for those segments (absent
+                    // when the daemon predates the usage field or nothing distilled).
+                    (distillUsage && distillUsage.total > 0
+                        ? ` · ${distillUsage.total.toLocaleString()} distill tokens`
+                        : ""));
                 // Prune aged-out cursors (90d) — only on a clean run so a transient
                 // failure doesn't drop a still-needed cursor.
                 if (!dryRun && !hadTransientFailure) {
@@ -630,6 +665,53 @@ async function runNightly(options = {}) {
             }
         }
         console.log(`[hicortex] Nightly pipeline complete.`);
+        // Backup stage (#6, Phase 0B) — a transactionally-consistent snapshot of
+        // the irreplaceable data (DB + identity + state), packaged as one tar.gz
+        // the operator ships offsite via the optional `backupCommand` hook. Runs
+        // ONLY on a full nightly (capture-only is frequent + stateless; dry-run
+        // writes nothing). Backup failure must NOT fail the nightly — capture +
+        // consolidation have already succeeded; the snapshot is on disk and the
+        // failure surfaces as `backupOk:false` in the dashboard snapshot + telemetry
+        // for alerting (the operator's hook owns active alerting; no in-product
+        // channel yet — Phase 3).
+        let backupPath;
+        let backupBytes;
+        let backupOk;
+        if (!dryRun && !captureOnly) {
+            try {
+                const backupDir = typeof savedConfig?.backupDir === "string" && savedConfig.backupDir.trim()
+                    ? savedConfig.backupDir
+                    : undefined;
+                const bRes = await (0, backup_js_1.createBackup)({ db, home: stateDir, outDir: backupDir });
+                backupPath = bRes.path;
+                backupBytes = bRes.bytes;
+                backupOk = true;
+                console.log(`[hicortex] Backup: ${bRes.files} files, ${bRes.bytes.toLocaleString()} bytes -> ${bRes.path}`);
+                const cmd = typeof savedConfig?.backupCommand === "string" && savedConfig.backupCommand.trim()
+                    ? savedConfig.backupCommand
+                    : undefined;
+                if (cmd && backupPath) {
+                    const hook = await (0, backup_js_1.runBackupHook)(backupPath, cmd);
+                    if (!hook.ok) {
+                        // The artifact is on disk; only the offsite copy failed. Keep
+                        // backupPath/backupBytes (the snapshot records what was produced)
+                        // but flip backupOk so the aggregate can alert.
+                        backupOk = false;
+                        console.error(`[hicortex] Backup hook failed (exit ${hook.exitCode ?? "n/a"}). ` +
+                            `Artifact is on disk; offsite copy did NOT complete.`);
+                    }
+                    else {
+                        console.log(`[hicortex] Backup hook ok (exit 0).`);
+                    }
+                }
+            }
+            catch (err) {
+                // The whole backup stage failed (snapshot, tar, or write). Do NOT
+                // propagate — capture/consolidation already succeeded. Surface + continue.
+                backupOk = false;
+                console.error(`[hicortex] Backup FAILED: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         // Dashboard snapshot (#224) — full nightly only. The snapshot reflects
         // corpus state regardless of whether consolidation/LLM ran, so it is
         // ALWAYS written here (the use case is history; an LLM-less install still
@@ -673,6 +755,12 @@ async function runNightly(options = {}) {
                     // when consolidation didn't run or made no metered calls).
                     tokensThisRun,
                     tokensByStage,
+                    // #287: the capture phase's distill tokens (from the /distill
+                    // responses). The writer merges them into `tokens` +
+                    // `tokens_by_stage.distill` so the customer-facing total is the
+                    // run's TRUE spend; zero (old daemon / nothing distilled) is a no-op
+                    // and the row keeps its consolidation-only shape.
+                    distillUsage,
                     // #255 CR: always-on budget usage — undefined when consolidation
                     // didn't run (capture-only / no_llm / throttled). Forwarded whenever
                     // consolidation ran so the digest renders a continuous used/max bar.
@@ -682,6 +770,13 @@ async function runNightly(options = {}) {
                     // (capture-only / no_llm / throttled) or didn't exhaust.
                     budgetExhausted,
                     budgetDeferredByStage,
+                    // #6 backup stage — hoisted from the block above. Present whenever
+                    // the backup stage ran (full nightly); undefined on capture-only /
+                    // dry-run. backupOk flips to false on snapshot OR hook failure so the
+                    // dashboard digest can flag a night the offsite copy didn't complete.
+                    backupPath,
+                    backupBytes,
+                    backupOk,
                 }, memorySoftCapResolved);
             }
             catch (snapErr) {
@@ -728,6 +823,13 @@ async function runNightly(options = {}) {
                 // exhausted (false is omitted to keep the ping minimal; the aggregate
                 // treats absent as "not exhausted / not measurable").
                 ...(budgetExhausted ? { budget_exhausted: true } : {}),
+                // #6 backup stage outcome — forwarded only when the backup stage ran
+                // (full nightly). `ok` is false on snapshot OR hook failure; the fleet
+                // aggregate surfaces a sustained drop in backup_ok as a data-loss risk.
+                // Absent on capture-only / dry-run / client runs (no backup ran).
+                ...(backupOk !== undefined
+                    ? { backup: { ok: backupOk === true, bytes: backupBytes ?? 0 } }
+                    : {}),
                 sessions: batches.length,
                 ok: !hadTransientFailure,
                 shown: adoption.shown,

package/dist/prompts.js

@@ -120,6 +120,7 @@ EXTRACT into this markdown format:
 
 ### Decisions Made
 - [D] [SUBJECT]: [decision] — [reasoning] (${date})
+  (ONLY decisions the user explicitly made or confirmed — never an AI proposal)
 
 ### Knowledge Learned
 - [K] [SUBJECT]: [knowledge] — [context/source] (${date})
@@ -145,10 +146,19 @@ TYPE TAG (critical — prefix EVERY bullet with exactly one letter + space):
 - [K] KNOWLEDGE — a durable truth that will hold across sessions: "the API is at
   :8787", "uv is used for packages", "config lives in ~/.hicortex/". Not tied
   to a single moment.
-- [D] DECISIONS — a choice made that future work builds on, and that a later
-  decision can SUPERSEDE: "switched from gemma4 to qwen3.5", "adopted the
-  graded-schema tag model". Not knowledge (it can change) and not experience
-  (it persists and constrains).
+- [D] DECISIONS — a choice the USER explicitly made or confirmed in the
+  transcript: they said "do X / agreed / ok / go ahead", approved the plan, or
+  the transcript shows the change actually being carried out. It must be a
+  choice future work builds on and that a later decision can SUPERSEDE:
+  "switched from gemma4 to qwen3.5", "adopted the graded-schema tag model".
+  Not knowledge (it can change) and not experience (it persists and constrains).
+- An AI recommendation or proposal is NEVER a decision, however detailed or
+  well-reasoned — even if the user seemed receptive. If the user declined,
+  deferred ("hold", "later", "wait for X"), or did not answer: record it as
+  [E] EXPERIENCE with proposal framing ("AI proposed X → user declined/held
+  because Y"), or under Corrections & Rejections.
+- SELF-CHECK: if an item's text says "AI recommended/proposed" or the user
+  "has not (yet) confirmed" it, that item is NOT [D] — re-tag it [E].
 - NEVER use [L] (learnings). Learnings are extracted by a SEPARATE reflection stage,
   not here. If the model emits [L], it is wrong — re-tag as experience/knowledge/decisions.
 The type tag goes BEFORE the subject, never as a section/category bracket.
@@ -161,6 +171,8 @@ entity. The subject is what a future reader would search for.
 - NOT:    "[E] User rejected AI's bundling of unknown loads"
 - Write:  "[K] Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
 - NOT:    "[K] Discovered that cron sessions are filtered out"
+- Write:  "[E] Qwen3.8-27B swap: AI proposed switching → user held on Qwen3.6-35B-A3B until an MoE variant ships"
+- NOT:    "[D] Qwen3.8-27B: switch from Qwen3.6-27B — drop-in upgrade"
 Reason: each item's first words (after the type tag) become the memory's one-line
 index entry AND dominate its search embedding. An item that opens with a category
 label, a sentiment ("Strong Negative"), or "User rejected…" is unfindable — it
@@ -169,6 +181,9 @@ the subject; put reaction, intensity and reasoning AFTER it.
 
 RULES:
 - Extract MAX 20 items total (quality over quantity)
+- Use EXACT names/versions/paths/numbers as they appear in the transcript —
+  never substitute what seems current or more standard (writing "Qwen3.6-27B"
+  when the transcript says "Qwen3.6-35B-A3B" is a fabrication)
 - Each must be useful if recalled in a future session
 - Skip: routine code edits, standard tool usage, trivial fixes
 - Include: architectural decisions, debugging breakthroughs, user preferences,

package/dist/telemetry.d.ts

@@ -116,6 +116,20 @@ export interface TelemetryPayload {
      * the dashboard snapshot, not on the wire (mirrors `tokens_this_run`).
      */
     budget_exhausted?: boolean;
+    /**
+     * Backup stage outcome (#6, Phase 0B). Present on every full nightly (absent
+     * on capture-only / dry-run / client runs — no backup stage runs there).
+     * `ok` is false when EITHER the snapshot write OR the operator's
+     * `backupCommand` hook failed — the aggregate data-loss-risk signal (a
+     * sustained drop in `backup.ok` means offsite copies are silently not
+     * landing). `bytes` is the compressed artifact size (0 when the snapshot
+     * itself failed before producing a file). The operator's hook owns active
+     * alerting (email/Discord); this field is the passive fleet-health signal.
+     */
+    backup?: {
+        ok: boolean;
+        bytes: number;
+    };
 }
 /**
  * Check if telemetry is enabled. Disabled by:

package/dist/token-budget.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+export declare function resolveTokenCap(configCap: unknown): number;
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+export declare function initTokenBudget(stateDir: string, configCap: unknown): void;
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+export declare function getTokenCap(): number;
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+export declare function isTokenBudgetExceeded(stateDir: string): boolean;
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+export declare function recordDistillUsage(stateDir: string, usage: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): void;