@gamaze/hicortex 0.18.2 → 0.19.0

package/dist/backup.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Backup mechanism — a transactionally-consistent snapshot of the irreplaceable
+ * data (#6, Phase 0B).
+ *
+ * For a product whose value is accumulated memory, silent backup loss is
+ * existential (spec §8). The live DB runs with WAL on, so a plain `cp`/`tar` of
+ * `hicortex.db` is torn (the `-wal` file holds uncommitted pages → a copy that
+ * looks fine until you restore it). This module uses better-sqlite3's native
+ * `db.backup(path)` — the SQLite online-backup API, already proven in `dedup.ts`
+ * — which folds the WAL into a single self-contained, consistent snapshot, then
+ * packages it with the hand-edited identity layer + capture state into one
+ * `tar.gz` artifact the operator ships offsite.
+ *
+ * Backup set (the irreplaceable data under HICORTEX_HOME):
+ *   - `hicortex.db`            — via db.backup() to a temp snapshot (WAL-safe)
+ *   - `identity/` (whole tree) — global `*.md` AND per-agent `agents/<id>/*.md`
+ *   - `context/` (legacy)      — additive fallback (identity-store.ts migrate)
+ *   - `state.json`             — cursors/tier/timestamps (state.ts)
+ *   - `capture-cursors.json`   — per-session capture positions (capture-cursors.ts)
+ *
+ * Excluded by design:
+ *   - `config.json`            — secrets (authToken/llmApiKey); re-creatable via init
+ *   - `backups/`               — output dir (never back up the backups)
+ *   - logs (`nightly.log`, `server*.log`) — re-creatable, noisy, not data
+ *   - `models/`                — embedder cache (re-downloadable)
+ *   - `capture.lock`           — a transient single-flight lock, not state
+ *   - `.allow-localhost-bypass` — a hosted fail-closed marker, not data
+ *
+ * Vectors: `db.backup()` copies the vec0 shadow tables (they're real tables).
+ * If a restore ever finds them missing, vectors regenerate from
+ * `memories.content` via the embedder — non-destructive either way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBackup = createBackup;
+exports.runBackupHook = runBackupHook;
+exports.runBackupCli = runBackupCli;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_zlib_1 = require("node:zlib");
+const tar_stream_1 = require("tar-stream");
+const paths_js_1 = require("./paths.js");
+const db_js_1 = require("./db.js");
+const init_js_1 = require("./init.js");
+/**
+ * Hook timeout — a stuck offsite upload (rclone/aws/B2 hung on a dead network)
+ * must NOT hang the nightly. 5 min is generous for typical tarball uploads; the
+ * operator's wrapper can re-queue on timeout. Mirrors the capture-lock "don't
+ * block forever" discipline.
+ */
+const HOOK_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Create a backup artifact. Snapshots the live DB via the online-backup API,
+ * packages it with the identity tree + state into a single `tar.gz`, and writes
+ * it to `outFile` (default `<home>/backups/hicortex-<ISO>.tar.gz`) or streams
+ * to stdout. Returns `{ path?, bytes, files }`.
+ *
+ * Never partially writes a file artifact on failure: if the tar pipeline errors
+ * mid-stream the (likely-truncated) file is removed before the error propagates,
+ * so a stale half-backup is never left on disk to masquerade as a good one.
+ */
+async function createBackup(opts) {
+    if (opts.stdout && (opts.outFile || opts.outDir)) {
+        throw new Error("[hicortex] backup: --stdout is mutually exclusive with --out / backupDir");
+    }
+    // 1. Snapshot the live DB via the WAL-safe online-backup API (proven at
+    //    dedup.ts:499). Runs concurrently with the live DB — no writer blocking,
+    //    no torn copy. The temp file is cleaned up in `finally` below.
+    const snapshotPath = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `hicortex-backup-${(0, node_crypto_1.randomBytes)(6).toString("hex")}.db`);
+    await opts.db.backup(snapshotPath);
+    let totalBytes = 0;
+    let fileCount = 0;
+    // Resolve the output target (file path or stdout). The ISO stamp is filename-
+    // safe (colons/dots → dashes) so it survives every filesystem.
+    const iso = new Date().toISOString().replace(/[:.]/g, "-");
+    const outFile = opts.stdout
+        ? undefined
+        : opts.outFile ?? (0, node_path_1.join)(opts.outDir ?? (0, node_path_1.join)(opts.home, "backups"), `hicortex-${iso}.tar.gz`);
+    // Prepare the output dir up front so a later mkdirSync failure (permissions,
+    // read-only mount) surfaces BEFORE we spend time tarring — fail loud, early.
+    if (outFile)
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outFile), { recursive: true });
+    // 2. Build the entry list (deterministic order for diffable tarballs).
+    const entries = [{ name: "hicortex.db", file: snapshotPath }];
+    appendTree(entries, (0, node_path_1.join)(opts.home, "identity"), "identity");
+    appendTree(entries, (0, node_path_1.join)(opts.home, "context"), "context");
+    pushIfExists(entries, (0, node_path_1.join)(opts.home, "state.json"), "state.json");
+    pushIfExists(entries, (0, node_path_1.join)(opts.home, "capture-cursors.json"), "capture-cursors.json");
+    // 3. Pack → gzip → sink (file or stdout). Entries are added SEQUENTIALLY:
+    //    tar-stream writes headers in call order, and concurrent entry() calls
+    //    would interleave headers into a corrupt tar. Each entry streams from disk
+    //    so the DB snapshot (potentially large) is never fully in memory.
+    const packStream = (0, tar_stream_1.pack)();
+    const gzip = (0, node_zlib_1.createGzip)();
+    packStream.pipe(gzip);
+    const sink = opts.stdout ? process.stdout : (0, node_fs_1.createWriteStream)(outFile);
+    gzip.pipe(sink);
+    gzip.on("data", (chunk) => {
+        totalBytes += chunk.length;
+    });
+    // Completion signal — DIFFERENT per sink type:
+    //   - File: await the file stream's 'finish' (all bytes flushed to disk) so
+    //     the offsite hook reads a complete, closed file.
+    //   - stdout: process.stdout is a special non-closable stream that NEVER
+    //     emits 'finish', so awaiting it deadlocks. Instead await gzip's 'end'
+    //     (the last compressed byte has been emitted and handed to stdout); the
+    //     OS drains process.stdout asynchronously and Node won't exit while it
+    //     has pending buffered bytes.
+    const sinkFinished = opts.stdout
+        ? new Promise((resolve, reject) => {
+            gzip.on("end", resolve);
+            gzip.on("error", reject);
+            packStream.on("error", reject);
+            // A downstream pipe closing early (--stdout | head, or rclone dying)
+            // emits 'error' (EPIPE) on process.stdout — listen so it rejects cleanly
+            // instead of becoming an uncaughtException (and so we never hang waiting
+            // for gzip 'end' that will never come once the sink has errored).
+            sink.on("error", reject);
+        })
+        : new Promise((resolve, reject) => {
+            sink.on("finish", resolve);
+            sink.on("error", reject);
+            gzip.on("error", reject);
+            packStream.on("error", reject);
+        });
+    try {
+        for (const entry of entries) {
+            const size = (0, node_fs_1.statSync)(entry.file).size;
+            await new Promise((resolve, reject) => {
+                const writable = packStream.entry({ name: entry.name, size }, (err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+                const rs = (0, node_fs_1.createReadStream)(entry.file);
+                rs.on("error", reject);
+                rs.pipe(writable);
+            });
+            fileCount++;
+        }
+        packStream.finalize();
+        await sinkFinished;
+        return { path: outFile, bytes: totalBytes, files: fileCount };
+    }
+    catch (err) {
+        // Never leave a truncated/half-written artifact on disk masquerading as a
+        // good backup — a restore drill against it would fail at the worst time.
+        if (!opts.stdout && outFile) {
+            try {
+                (0, node_fs_1.rmSync)(outFile, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; the real error is the one we re-throw.
+            }
+        }
+        throw err;
+    }
+    finally {
+        // Always remove the temp DB snapshot (best-effort, never masks a real error).
+        try {
+            (0, node_fs_1.rmSync)(snapshotPath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/**
+ * Run the operator's post-backup offsite hook. The configured `command` is split
+ * on whitespace and the artifact path appended as the LAST arg (e.g.
+ * `rclone copyto <path> remote:hicortex/` → `["rclone","copyto",path,...]`).
+ * Cloud creds + active alerting stay in the operator's wrapper, out of the
+ * product. NEVER throws — a hook failure is reported as `{ ok:false }` so the
+ * nightly continues (capture/consolidation already succeeded; the backup itself
+ * is on disk). 5 min timeout so a hung upload can't hang the nightly.
+ *
+ * Whitespace-split caveat: commands with quoted args containing spaces should
+ * be a wrapper script (`/etc/hicortex/offsite.sh`), not a one-liner — the split
+ * here is deliberately dumb to avoid re-implementing a shell parser.
+ */
+async function runBackupHook(artifactPath, command) {
+    // Missing/empty command = nothing configured. Not an error (the nightly only
+    // calls this when a command IS set), but the defensive contract is { ok:false }
+    // so a caller that forgets the guard still gets an honest "no hook ran".
+    if (!command || !command.trim()) {
+        return { ok: false };
+    }
+    const parts = command.trim().split(/\s+/);
+    const [cmd, ...baseArgs] = parts;
+    const args = [...baseArgs, artifactPath];
+    return new Promise((resolve) => {
+        try {
+            (0, node_child_process_1.execFile)(cmd, args, { timeout: HOOK_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+                if (err) {
+                    const execErr = err;
+                    // err.code: number = process exit code; "ENOENT" = binary not found.
+                    // err.signal: set when killed (timeout → SIGTERM). Extract a numeric
+                    // exit code only (the alerting signal); spawn/timeout failures are
+                    // reported with undefined exitCode.
+                    const exitCode = typeof execErr.code === "number" ? execErr.code : undefined;
+                    const reason = execErr.signal != null
+                        ? `killed by signal ${execErr.signal} (timeout?)`
+                        : execErr.code === "ENOENT"
+                            ? `command not found: ${cmd}`
+                            : execErr.message;
+                    console.error(`[hicortex] backup hook failed: ${reason}`);
+                    if (stderr) {
+                        console.error(`[hicortex]   hook stderr: ${stderr.toString().trim().slice(0, 2000)}`);
+                    }
+                    resolve({ ok: false, exitCode });
+                    return;
+                }
+                if (stdout) {
+                    console.log(`[hicortex] backup hook stdout: ${stdout.toString().trim().slice(0, 2000)}`);
+                }
+                resolve({ ok: true, exitCode: 0 });
+            });
+        }
+        catch (err) {
+            // Synchronous spawn failure (shouldn't happen with execFile, but defensive
+            // — the contract is "never throws").
+            console.error(`[hicortex] backup hook could not run: ${err instanceof Error ? err.message : String(err)}`);
+            resolve({ ok: false });
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// File-set helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively append every regular file under `absDir` to `entries`, with
+ * in-tar paths rooted at `relRoot`. Symlinks are SKIPPED (security — a symlink
+ * in identity/ could escape home; the identity store already lstat-skips them
+ * on read, and we do the same on backup so a restored tree can't point outside
+ * itself). Missing dir = no-op (fresh install may have no identity/ yet).
+ */
+function appendTree(entries, absDir, relRoot) {
+    if (!(0, node_fs_1.existsSync)(absDir))
+        return;
+    const walk = (dir, rel) => {
+        let ents;
+        try {
+            ents = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch {
+            // EACCES / transient — skip this subtree rather than aborting the backup.
+            return;
+        }
+        for (const ent of ents) {
+            // withFileTypes uses the entry's own type (not the target's), so a symlink
+            // is correctly identified without an extra lstat — skip symlinks so a
+            // link in identity/ can't escape home into the tarball.
+            const abs = (0, node_path_1.join)(dir, ent.name);
+            const relPath = (0, node_path_1.join)(rel, ent.name);
+            if (ent.isSymbolicLink())
+                continue;
+            if (ent.isDirectory()) {
+                walk(abs, relPath);
+            }
+            else if (ent.isFile()) {
+                // Normalize to forward slashes for tar (posix convention), even though
+                // join already produces them on mac/linux.
+                entries.push({ name: relPath.split("\\").join("/"), file: abs });
+            }
+        }
+    };
+    walk(absDir, relRoot);
+}
+// (Extraction of a backup artifact is intentionally NOT in this module: the
+// restore path is manual for Phase 0 (spec §8) and tested directly via
+// tar-stream's extract() in tests/backup.test.ts. A future `hicortex restore`
+// command would grow its own module; packaging + extraction don't belong
+// together — one writes artifacts, the other consumes them.)
+/**
+ * Push a single regular file onto `entries` if it exists. Skips symlinks and
+ * non-files (the state files are plain files; a symlink here would be suspect).
+ */
+function pushIfExists(entries, abs, name) {
+    try {
+        const st = (0, node_fs_1.lstatSync)(abs);
+        if (st.isFile())
+            entries.push({ name, file: abs });
+    }
+    catch {
+        // ENOENT or unreadable — skip. A fresh install may lack capture-cursors.json.
+    }
+}
+/**
+ * Run the `hicortex backup` CLI command. Loads config (for `backupDir` /
+ * `backupCommand`), opens the DB, writes (or streams) the artifact, runs the
+ * offsite hook when configured, prints the artifact path, and exits non-zero on
+ * any failure (a failed backup must be visible — `cron`/launchd surfaces it).
+ */
+async function runBackupCli(opts) {
+    const home = (0, paths_js_1.hicortexHome)();
+    const { config } = (0, init_js_1.loadConfigStrict)((0, node_path_1.join)(home, "config.json"));
+    const backupDir = typeof config.backupDir === "string" && config.backupDir.trim()
+        ? config.backupDir
+        : undefined;
+    const backupCommand = typeof config.backupCommand === "string" && config.backupCommand.trim()
+        ? config.backupCommand
+        : undefined;
+    const db = (0, db_js_1.initDb)((0, db_js_1.resolveDbPath)());
+    try {
+        const result = await createBackup({
+            db,
+            home,
+            // CLI `--out <dir>` takes precedence over the config `backupDir`. When
+            // --stdout is set, don't forward backupDir at all — a configured backupDir
+            // (for the nightly) must not block a manual --stdout stream (the mutual-
+            // exclusivity check would otherwise reject it).
+            outDir: opts.stdout ? undefined : (opts.outDir ?? backupDir),
+            stdout: opts.stdout,
+        });
+        if (result.path) {
+            console.log(`[hicortex] Backup written: ${result.path} ` +
+                `(${result.files} files, ${result.bytes.toLocaleString()} bytes)`);
+        }
+        else {
+            console.error(`[hicortex] Backup streamed to stdout (${result.files} files, ${result.bytes.toLocaleString()} bytes compressed)`);
+        }
+        // Only run the hook when we have an on-disk artifact path to hand it. The
+        // --stdout path is already an offsite transport (piped to rclone/aws/B2),
+        // so a second hook would double-ship.
+        if (result.path && backupCommand) {
+            const hook = await runBackupHook(result.path, backupCommand);
+            if (!hook.ok) {
+                console.error(`[hicortex] Backup hook failed (exit ${hook.exitCode ?? "n/a"}). ` +
+                    `Artifact is on disk; offsite copy did NOT complete.`);
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`[hicortex] Backup hook ok (exit 0).`);
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/capture.d.ts

@@ -71,6 +71,15 @@ export interface PostResult {
     dropped?: string[];
     skipped?: boolean;
     error?: string;
+    /**
+     * The segment's metered LLM usage from the 201 body (#287). Absent on a
+     * pre-#287 daemon (or any non-201) — callers must treat absent as zero.
+     */
+    usage?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
 }
 export type PostFn = (body: DistillBody) => Promise<PostResult>;
 export interface CaptureOptions {
@@ -100,6 +109,17 @@ export interface CaptureResult {
      * (429 memory cap) or "auth" (401). The caller decides watermark handling.
      */
     stopped?: "limit" | "auth";
+    /**
+     * Sum of the successful segments' reported LLM usage (#287) — the run's
+     * distill spend, for the dashboard snapshot's token totals. Zero-filled when
+     * the daemon predates the usage field (an old server) or nothing distilled,
+     * so callers gate on `total > 0`, not on presence.
+     */
+    distillUsage: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
 }
 /**
  * Split an already-denoised string into ≤maxChars pieces (A2 hard-split).

package/dist/capture.js

@@ -139,6 +139,9 @@ async function captureBatches(batches, opts) {
     let sessionsSent = 0;
     let hadTransientFailure = false;
     let stopped;
+    // #287: distill tokens reported by successful 201s only — skips (200) and
+    // failures metered nothing client-side.
+    const distillUsage = { prompt: 0, completion: 0, total: 0 };
     for (const batch of batches) {
         const short = batch.sessionId.slice(0, 8);
         const segments = packSegments(batch.entries, batch.startCursor, batch.entryCursors, segmentMaxChars);
@@ -205,6 +208,11 @@ async function captureBatches(batches, opts) {
             if (result.status === 201) {
                 memoriesIngested += result.distilled ?? 0;
                 sessionPosted = true;
+                if (result.usage) {
+                    distillUsage.prompt += result.usage.prompt;
+                    distillUsage.completion += result.usage.completion;
+                    distillUsage.total += result.usage.total;
+                }
                 if (advancesBoundary)
                     lastConfirmedEnd = seg.segEnd;
                 console.log(`[hicortex]     → ${result.distilled ?? 0} memories (segment ${body.segment_id})`);
@@ -258,7 +266,7 @@ async function captureBatches(batches, opts) {
         if (stopped)
             break;
     }
-    return { memoriesIngested, sessionsSent, hadTransientFailure, stopped };
+    return { memoriesIngested, sessionsSent, hadTransientFailure, stopped, distillUsage };
 }
 // ---------------------------------------------------------------------------
 // Single-flight guard (A5)

package/dist/cli.js

@@ -184,6 +184,33 @@ switch (command) {
         });
         break;
     }
+    case "backup": {
+        // Backup — transactionally-consistent snapshot of the irreplaceable data
+        // (#6, Phase 0B). Mirrors `dedup`: flags parsed here, the runner (config
+        // load + DB open + createBackup + hook + close) lives in backup.ts so this
+        // switch stays thin and the heavy module is lazily imported.
+        const args = process.argv.slice(3);
+        let outDir;
+        try {
+            outDir = (0, cli_args_js_1.readValueFlag)(args, "--out");
+        }
+        catch {
+            console.error("[hicortex] backup: --out requires a directory path");
+            process.exit(1);
+        }
+        const stdout = args.includes("--stdout");
+        // `--out` is the output DIRECTORY (the artifact is auto-named
+        // hicortex-<ISO>.tar.gz inside it) — matches the `backupDir` config and the
+        // natural "put the backup here" invocation. Omit for the default <home>/backups.
+        const backupOptions = { outDir, stdout };
+        import("./backup.js").then(({ runBackupCli }) => {
+            runBackupCli(backupOptions).catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] backup failed: ${err}`);
+                process.exit(1);
+            });
+        });
+        break;
+    }
     case "dedup": {
         const args = process.argv.slice(3);
         let threshold;
@@ -310,6 +337,7 @@ Commands:
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)
+  backup          Snapshot the DB + identity + state to a tar.gz (online, WAL-safe)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   classify-types    Backfill episode→fact/decision type tags over the corpus (server mode)
   learnings-identity  Fetch identity + lessons and print Markdown to stdout (CC SessionStart hook)
@@ -335,6 +363,8 @@ Options:
   dedup --apply             Execute the merge (default: dry run, report only)
   dedup --threshold <t>     Override config dedupMergeThreshold for one run
   dedup --db <path>         DB path override (defaults to the configured DB)
+  backup --out <dir>        Write the artifact into <dir> as hicortex-<ISO>.tar.gz (default: <home>/backups)
+  backup --stdout           Stream the tar.gz to stdout (offsite pipe: hicortex backup --stdout | rclone rcat …)
   classify-domains --all    Reclassify every memory (default: only NULL/stale-domain rows)
   classify-domains --batch <n>  Memories per batch (default: 200)
   classify-domains --reset  Restart from the beginning (ignore saved cursor)

package/dist/config-read.d.ts

@@ -1,7 +1,8 @@
 /**
  * Strict config readers for primitive values. Pure functions — no LlmConfig
- * dependency — shared by the nightly preflight knobs and the distill-tier
- * overlay (llm.ts / mcp-server.ts).
+ * dependency — shared by the nightly preflight knobs, the distill-tier
+ * overlay (llm.ts / mcp-server.ts), and the dashboard account identity
+ * (dashboard.ts).
  *
  * The point is to reject wrong-typed config values AT THE BOUNDARY (disk →
  * runtime) with a warn, rather than casting them straight through. The trap
@@ -42,6 +43,31 @@ export declare function readNonNegativeConfig(config: Record<string, unknown>, k
  * posture, and the parseConfigDomains leniency contract for the absent case.
  */
 export declare function parseHours(config: Record<string, unknown> | null | undefined, key: string): number[] | null;
+/**
+ * Read an optional non-empty string from a config object. Returns the trimmed
+ * string when valid, `null` when the key is absent, blank, OR present-but-not-
+ * a-string (with a warn in the latter case). Used for display-only keys (e.g.
+ * dashboard account identity) where "not set" and "invalid" mean the same
+ * thing: render nothing.
+ */
+export declare function readStringConfig(config: Record<string, unknown>, key: string): string | null;
+/**
+ * Account identity shown in the console nav (name + plan pill). The display
+ * keys are operator-set config (hosted installs); each field is null when
+ * absent, blank, or wrong-typed (readStringConfig) — the page renders nothing
+ * for an all-null account (the self-hosted default), never the string "null".
+ *
+ * ONE construction shared by the /dashboard/data payload and GET /account so
+ * the nav element cannot drift between them (same reason the digest reuses
+ * formatIndexLine).
+ */
+export interface AccountIdentity {
+    name: string | null;
+    org: string | null;
+    plan: string | null;
+}
+/** Read the account identity (displayName/orgName/planLabel) from config. */
+export declare function readAccount(config: Record<string, unknown> | null | undefined): AccountIdentity;
 /**
  * Warn if the saved config carries keys that 0.16.8+ ignores. Call at every
  * config read (daemon boot + nightly). The warning clears once the keys are

package/dist/config-read.js

@@ -1,8 +1,9 @@
 "use strict";
 /**
  * Strict config readers for primitive values. Pure functions — no LlmConfig
- * dependency — shared by the nightly preflight knobs and the distill-tier
- * overlay (llm.ts / mcp-server.ts).
+ * dependency — shared by the nightly preflight knobs, the distill-tier
+ * overlay (llm.ts / mcp-server.ts), and the dashboard account identity
+ * (dashboard.ts).
  *
  * The point is to reject wrong-typed config values AT THE BOUNDARY (disk →
  * runtime) with a warn, rather than casting them straight through. The trap
@@ -17,6 +18,8 @@ exports.readPositiveConfig = readPositiveConfig;
 exports.readStrictBoolean = readStrictBoolean;
 exports.readNonNegativeConfig = readNonNegativeConfig;
 exports.parseHours = parseHours;
+exports.readStringConfig = readStringConfig;
+exports.readAccount = readAccount;
 exports.warnIgnoredConfigKeys = warnIgnoredConfigKeys;
 /**
  * Read a positive finite number from a config object. Returns `def` when the
@@ -96,6 +99,33 @@ function parseHours(config, key) {
     }
     return out.length > 0 ? out.sort((a, b) => a - b) : null;
 }
+/**
+ * Read an optional non-empty string from a config object. Returns the trimmed
+ * string when valid, `null` when the key is absent, blank, OR present-but-not-
+ * a-string (with a warn in the latter case). Used for display-only keys (e.g.
+ * dashboard account identity) where "not set" and "invalid" mean the same
+ * thing: render nothing.
+ */
+function readStringConfig(config, key) {
+    const v = config[key];
+    if (v === undefined)
+        return null;
+    if (typeof v === "string") {
+        const t = v.trim();
+        return t.length > 0 ? t : null;
+    }
+    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a string — ignored.`);
+    return null;
+}
+/** Read the account identity (displayName/orgName/planLabel) from config. */
+function readAccount(config) {
+    const c = config ?? {};
+    return {
+        name: readStringConfig(c, "displayName"),
+        org: readStringConfig(c, "orgName"),
+        plan: readStringConfig(c, "planLabel"),
+    };
+}
 /**
  * Config keys that ≤0.16.7 accepted and 0.16.8+ IGNORES. Two groups:
  *  - per-stage model keys + the nested `models` block (#231): one model now

package/dist/consolidate.js

@@ -985,8 +985,6 @@ exports.DEFAULT_SUPERSESSION_MAX_CALLS = 0;
 const SUPERSESSION_NEIGHBOR_POOL = 15;
 /** Older-neighbor pairs kept per candidate after filtering. */
 const SUPERSESSION_NEIGHBOR_TOP_K = 5;
-/** Candidate rows read per SQL page (call budget stops the loop well before this in practice). */
-const SUPERSESSION_BATCH_SIZE = 500;
 /**
  * A memory whose content/type marks it as a SUPERSEDABLE claim — one a newer
  * memory about the same subject can replace. Decisions and corrections were the
@@ -1122,8 +1120,8 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
               OR content LIKE '%[Corrections & Rejections]%'
               OR content LIKE '%[Facts Learned]%'
               OR content LIKE '%[Project State Changes]%')
-       ORDER BY rowid ASC LIMIT ?`)
-        .all(startCursor, SUPERSESSION_BATCH_SIZE);
+       ORDER BY rowid ASC`)
+        .all(startCursor);
     let scanned = 0;
     let evaluated = 0;
     let superseded = 0;