@gamaze/hicortex 0.18.3 → 0.19.0

package/dist/dashboard.d.ts

@@ -42,12 +42,21 @@ export interface DashboardMetrics {
          *  cap; undefined on backfill rows (a stage outcome, not reconstructable). */
         evicted?: number;
         /**
-         * Total LLM tokens consumed by this run's consolidation (#246). Undefined
-         * in lockstep with `tokens_by_stage` (and on backfill rows, which can't
-         * reconstruct a per-run meter).
+         * Total LLM tokens consumed by this run (#246 consolidation meter; #287
+         * widened to the TRUE total — distill + consolidation). Undefined in
+         * lockstep with `tokens_by_stage` (and on backfill rows, which can't
+         * reconstruct a per-run meter). Older snapshots are consolidation-only:
+         * historical rows can't be reconstructed, which is accepted (#287).
+         * Inherent under-count, same acceptance: attribution is response-based,
+         * so tokens a FAILED distill already spent (500 after spend, response
+         * lost after commit) reach the monthly meter but never a run's total —
+         * after such a night, the month's bars sum slightly below the headline.
          */
         tokens?: number;
-        /** Per-stage breakdown of `tokens` (#246). Undefined on backfill rows. */
+        /**
+         * Per-stage breakdown of `tokens` (#246; #287 adds a `distill` entry for
+         * capture-time distillation). Undefined on backfill rows.
+         */
         tokens_by_stage?: Record<string, {
             prompt: number;
             completion: number;
@@ -79,6 +88,19 @@ export interface DashboardMetrics {
          * shape is clean on healthy runs.
          */
         budget_deferred_by_stage?: Record<string, number>;
+        /**
+         * #6 backup stage outcome (Phase 0B). Present whenever the backup stage
+         * ran (full nightly); absent on capture-only / dry-run / backfill rows.
+         * `ok` is false when the snapshot OR the operator's offsite hook failed —
+         * the page flags a night the offsite copy didn't land. `bytes` is the
+         * compressed artifact size; `path` is the on-disk artifact (for "where
+         * did the last backup land?" debugging — not a restore button).
+         */
+        backup?: {
+            ok: boolean;
+            bytes: number;
+            path?: string;
+        };
     };
     /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
      *  disabled); always present in real snapshots, undefined on backfilled
@@ -102,6 +124,17 @@ export interface DashboardSnapshot {
 }
 /** The /dashboard/data response — the full payload the page renders. */
 export interface DashboardData {
+    /**
+     * Account identity (hosted): who the viewer is, so a user holding two
+     * tenant tokens can tell whose data the page shows. Each field is null when
+     * its config key (displayName/orgName/planLabel) is absent — the page
+     * renders nothing when ALL are null (the self-hosted default).
+     */
+    account: {
+        name: string | null;
+        org: string | null;
+        plan: string | null;
+    };
     headline: {
         total_memories: number;
         uses_per_showing: number | null;
@@ -149,9 +182,10 @@ export interface DashboardData {
             supersession: number;
             added: number;
             evicted?: number;
-            /** Total tokens consumed that run (#246). Undefined = no metered run. */
+            /** Total tokens consumed that run (#246; #287: distill + consolidation).
+             *  Undefined = no metered run. */
             tokens?: number;
-            /** Per-stage breakdown of `tokens` (#246). */
+            /** Per-stage breakdown of `tokens` (#246; #287 adds `distill`). */
             tokens_by_stage?: Record<string, {
                 prompt: number;
                 completion: number;
@@ -207,6 +241,19 @@ export interface NightlyDelta {
         completion: number;
         total: number;
     }>;
+    /**
+     * Distill tokens metered by the daemon across this run's capture POSTs
+     * (#287) — summed from the /distill responses by the capture loop. Merged
+     * into the snapshot so `new_this_run.tokens` is the run's TRUE total
+     * (distill + consolidation) and `distill` joins `tokens_by_stage`. Zero
+     * (a daemon predating the usage field, or nothing distilled) is a no-op:
+     * the row keeps its consolidation-only shape.
+     */
+    distillUsage?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
     /**
      * Always-on consolidation-budget usage (#255 CR). Forwarded whenever
      * consolidation ran so the dashboard renders a continuous used/max bar.
@@ -227,6 +274,15 @@ export interface NightlyDelta {
      * with `budgetExhausted`.
      */
     budgetDeferredByStage?: Record<string, number>;
+    /**
+     * #6 backup stage (Phase 0B). Hoisted from the nightly backup block. 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
+     * digest can flag a night the offsite copy didn't land.
+     */
+    backupPath?: string;
+    backupBytes?: number;
+    backupOk?: boolean;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
@@ -286,3 +342,12 @@ export declare function handleDashboardData(db: Database.Database, query: {
  * Failures surface as a 500 with the usual {error} shape — no silent degrade.
  */
 export declare function dashboardDataHandler(getDb: () => Database.Database, getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;
+/**
+ * Express adapter for GET /account — the account identity ONLY (name/org/plan
+ * from config), so the /viz and /identity/ui pages can render the nav account
+ * element without pulling the full /dashboard/data payload. Same readAccount()
+ * construction as the dashboard payload — one shape, two surfaces. Also the
+ * natural whoami for the future OAuth session (#292). Failures surface as a
+ * 500 with the usual {error} shape (same as dashboardDataHandler).
+ */
+export declare function accountHandler(getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;

package/dist/dashboard.js

@@ -25,6 +25,7 @@ exports.writeSnapshot = writeSnapshot;
 exports.backfillSnapshots = backfillSnapshots;
 exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
+exports.accountHandler = accountHandler;
 const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
@@ -92,17 +93,36 @@ function computeDashboardMetrics(db) {
  */
 function writeSnapshot(db, runAt, delta, memorySoftCap) {
     const metrics = computeDashboardMetrics(db);
+    // #287: merge the run's two meters into the customer-facing total. `tokens`
+    // = consolidation (tokensThisRun) + distill (distillUsage.total); the distill
+    // share joins the stage map under its own key. Both fields stay in lockstep —
+    // emitted when EITHER phase metered, omitted when neither did (the page
+    // treats undefined as "no data for this day"). A zero/absent distillUsage
+    // (old daemon, nothing distilled) changes nothing: tokens/tokens_by_stage
+    // come through exactly as the consolidation report produced them.
+    const hasDistill = (delta.distillUsage?.total ?? 0) > 0;
+    const metered = delta.tokensThisRun !== undefined || hasDistill;
+    const mergedTokens = metered
+        ? (delta.tokensThisRun ?? 0) + (hasDistill ? delta.distillUsage.total : 0)
+        : undefined;
+    const mergedStages = metered
+        ? { ...(delta.tokensByStage ?? {}), ...(hasDistill ? { distill: delta.distillUsage } : {}) }
+        : undefined;
+    // Shape fidelity: `tokens_by_stage` with zero keys never existed pre-#287
+    // (the key was simply absent) — keep it that way so consumers that treat
+    // "present" as "has a breakdown" stay right.
+    const emitStages = mergedStages && Object.keys(mergedStages).length > 0 ? mergedStages : undefined;
     metrics.new_this_run = {
         added: delta.added,
         lessonsGenerated: delta.lessonsGenerated,
         dedup: delta.dedup,
         supersession: delta.supersession,
         evicted: delta.evicted,
-        // #246: forward only when consolidation actually metered tokens this run.
-        // Absent on capture-only / throttled / no-LLM / no-metered-call runs — the
-        // page treats undefined as "no data for this day", matching adoption.
-        ...(delta.tokensThisRun !== undefined ? { tokens: delta.tokensThisRun } : {}),
-        ...(delta.tokensByStage !== undefined ? { tokens_by_stage: delta.tokensByStage } : {}),
+        // #246: forward only when a phase actually metered tokens this run. Absent
+        // on capture-only / throttled / no-LLM / no-metered-call runs — the page
+        // treats undefined as "no data for this day", matching adoption.
+        ...(mergedTokens !== undefined ? { tokens: mergedTokens } : {}),
+        ...(emitStages !== undefined ? { tokens_by_stage: emitStages } : {}),
         // #255 CR: always-on usage metric — forward calls_used + max_calls
         // whenever consolidation ran (regardless of exhaustion) so the page can
         // render a continuous used/max bar. Presence = a run happened; absence =
@@ -121,6 +141,17 @@ function writeSnapshot(db, runAt, delta, memorySoftCap) {
                     : {}),
             }
             : {}),
+        // #6 backup stage — forwarded as a nested object only when the stage ran
+        // (backupOk !== undefined). Absent on capture-only / dry-run / backfill.
+        ...(delta.backupOk !== undefined
+            ? {
+                backup: {
+                    ok: delta.backupOk === true,
+                    bytes: delta.backupBytes ?? 0,
+                    ...(delta.backupPath ? { path: delta.backupPath } : {}),
+                },
+            }
+            : {}),
     };
     if (memorySoftCap !== undefined) {
         metrics.capacity = { memory_soft_cap: memorySoftCap };
@@ -418,8 +449,9 @@ function handleDashboardData(db, query, config) {
             supersession: dayMetrics?.new_this_run?.supersession ?? supersessionCount,
             added: dayMetrics?.new_this_run?.added ?? sampleRows.length,
             evicted: dayMetrics?.new_this_run?.evicted,
-            // #246: only present when the day's nightly metered tokens. Both fields
-            // are forwarded together — the page renders either the breakdown or nothing.
+            // #246/#287: only present when the day's nightly metered tokens (distill
+            // or consolidation). Both fields are forwarded together — the page
+            // renders either the breakdown or nothing.
             tokens: dayMetrics?.new_this_run?.tokens,
             tokens_by_stage: dayMetrics?.new_this_run?.tokens_by_stage,
             // #255 CR: always-on usage metric — present whenever consolidation ran
@@ -441,6 +473,10 @@ function handleDashboardData(db, query, config) {
     return {
         status: 200,
         body: {
+            // Account identity — read defensively like the numeric knobs above:
+            // null when absent/not a string (page renders nothing, never "null").
+            // Shared readAccount() so GET /account renders the identical shape.
+            account: (0, config_read_js_1.readAccount)(config),
             range: rangeParam,
             headline,
             series,
@@ -469,3 +505,21 @@ function dashboardDataHandler(getDb, getConfig) {
         }
     };
 }
+/**
+ * Express adapter for GET /account — the account identity ONLY (name/org/plan
+ * from config), so the /viz and /identity/ui pages can render the nav account
+ * element without pulling the full /dashboard/data payload. Same readAccount()
+ * construction as the dashboard payload — one shape, two surfaces. Also the
+ * natural whoami for the future OAuth session (#292). Failures surface as a
+ * 500 with the usual {error} shape (same as dashboardDataHandler).
+ */
+function accountHandler(getConfig) {
+    return (_req, res) => {
+        try {
+            res.status(200).json({ account: (0, config_read_js_1.readAccount)(getConfig()) });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}

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"));
@@ -407,6 +409,38 @@ 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";
@@ -493,6 +527,12 @@ async function startServer(options = {}) {
     // 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) {
@@ -636,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
@@ -997,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.
@@ -1161,6 +1206,12 @@ 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) {
@@ -1452,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: