@gamaze/hicortex 0.17.1 → 0.17.2

package/dist/dashboard.d.ts

@@ -38,6 +38,27 @@ export interface DashboardMetrics {
         lessonsGenerated?: number;
         dedup: number;
         supersession: number;
+        /** Memories evicted by the capacity stage this run (#245). 0 when under
+         *  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).
+         */
+        tokens?: number;
+        /** Per-stage breakdown of `tokens` (#246). Undefined on backfill rows. */
+        tokens_by_stage?: Record<string, {
+            prompt: number;
+            completion: number;
+            total: number;
+        }>;
+    };
+    /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
+     *  disabled); always present in real snapshots, undefined on backfilled
+     *  rows (the historical config isn't recoverable from created_at). */
+    capacity?: {
+        memory_soft_cap: number;
     };
     /** Recall adoption aggregate. Null in backfilled rows. uses_per_showing is
      *  null when shown_sum = 0 (divide-by-zero guard). */
@@ -55,12 +76,28 @@ export interface DashboardSnapshot {
 }
 /** The /dashboard/data response — the full payload the page renders. */
 export interface DashboardData {
-    range: "7d" | "30d" | "90d" | "all";
     headline: {
         total_memories: number;
         uses_per_showing: number | null;
         cold_count: number;
+        /** Corpus vs cap (#245). `memory_soft_cap` is 0 when the cap is disabled
+         *  (indefinite growth); the page renders no gauge in that case. */
+        memory_soft_cap: number;
+        /**
+         * LLM token usage this billing period (#246). `used` is the running total
+         * (state.llmTokensThisPeriod.total after monthly reset); `cap` is the
+         * configured `llmTokensPerMonth` (0 = unlimited, page renders no cap).
+         * `used` is 0 when no consolidation has metered tokens yet — the page
+         * hides the stat in that case. `period_start` is the ISO timestamp of the
+         * current accrual period (for the "X this month" label).
+         */
+        tokens: {
+            used: number;
+            cap: number;
+            period_start: string | null;
+        };
     };
+    range: "7d" | "30d" | "90d" | "all";
     series: DashboardSnapshot[];
     composition: {
         by_type: Record<string, number>;
@@ -85,6 +122,15 @@ export interface DashboardData {
             dedup: number;
             supersession: number;
             added: number;
+            evicted?: number;
+            /** Total tokens consumed that run (#246). Undefined = no metered run. */
+            tokens?: number;
+            /** Per-stage breakdown of `tokens` (#246). */
+            tokens_by_stage?: Record<string, {
+                prompt: number;
+                completion: number;
+                total: number;
+            }>;
         };
         dedup_merges: {
             loser_id: string;
@@ -105,14 +151,37 @@ export interface NightlyDelta {
     lessonsGenerated?: number;
     dedup: number;
     supersession: number;
+    /** Memories evicted by the capacity stage this run (#245). */
+    evicted?: number;
+    /**
+     * Total LLM tokens consumed by this run's consolidation (#246). Undefined
+     * when consolidation didn't run (capture-only / no_llm / throttled / skipped)
+     * or made no metered calls. Stamped into the snapshot so the dashboard can
+     * show a usage trend.
+     */
+    tokensThisRun?: number;
+    /**
+     * Per-stage breakdown of `tokensThisRun` (#246) — same shape as
+     * ConsolidationReport.budget.tokens_by_stage. Undefined in lockstep with
+     * `tokensThisRun`.
+     */
+    tokensByStage?: Record<string, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }>;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
  * nightly.ts passes `now`). OR-replace on the PRIMARY KEY is intentional: a
  * manual re-run for the same instant overwrites, the nightly never produces
  * two rows for the same instant. Returns the row that was written.
+ *
+ * `memorySoftCap` (#245) is the resolved cap (0 = disabled) from the config;
+ * it is stamped into `metrics.capacity` so a historical snapshot records what
+ * cap produced its eviction count. Optional for callers that don't track it.
  */
-export declare function writeSnapshot(db: Database.Database, runAt: string, delta: NightlyDelta): DashboardSnapshot;
+export declare function writeSnapshot(db: Database.Database, runAt: string, delta: NightlyDelta, memorySoftCap?: number): DashboardSnapshot;
 /**
  * When the dashboard_snapshots table is empty, synthesize one row per day from
  * existing memories. Idempotent (only runs when the table is empty — the

package/dist/dashboard.js

@@ -27,6 +27,8 @@ exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
 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");
+const state_js_1 = require("./state.js");
 // ---------------------------------------------------------------------------
 // Metric computation — one SELECT each, prepared inline. Pure: takes a db,
 // returns a value. No side effects, no I/O beyond the open db handle.
@@ -83,15 +85,28 @@ function computeDashboardMetrics(db) {
  * nightly.ts passes `now`). OR-replace on the PRIMARY KEY is intentional: a
  * manual re-run for the same instant overwrites, the nightly never produces
  * two rows for the same instant. Returns the row that was written.
+ *
+ * `memorySoftCap` (#245) is the resolved cap (0 = disabled) from the config;
+ * it is stamped into `metrics.capacity` so a historical snapshot records what
+ * cap produced its eviction count. Optional for callers that don't track it.
  */
-function writeSnapshot(db, runAt, delta) {
+function writeSnapshot(db, runAt, delta, memorySoftCap) {
     const metrics = computeDashboardMetrics(db);
     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 } : {}),
     };
+    if (memorySoftCap !== undefined) {
+        metrics.capacity = { memory_soft_cap: memorySoftCap };
+    }
     db.prepare("INSERT OR REPLACE INTO dashboard_snapshots (run_at, metrics) VALUES (?, ?)").run(runAt, JSON.stringify(metrics));
     return { run_at: runAt, metrics };
 }
@@ -295,10 +310,25 @@ function handleDashboardData(db, query, config) {
     // Live composition (so day-one with no snapshots still shows the corpus).
     const live = computeDashboardMetrics(db);
     // Headline = live corpus (the chart shows history; the headline shows now).
+    // `memory_soft_cap` (#245): resolve from the live config (the source of
+    // truth for "what cap is in force right now"), defaulting to the production
+    // default. The page renders no gauge when it's 0 (disabled).
+    //
+    // `tokens` (#246): period accrual from state.json (the same single source
+    // the throttle check reads, so the dashboard always agrees with the runtime
+    // decision). The cap is `llmTokensPerMonth` (0 = unlimited). The page hides
+    // the stat entirely when `used` is 0 (no metered run yet).
+    const tokenState = (0, state_js_1.loadState)().llmTokensThisPeriod;
     const headline = {
         total_memories: live.totals.mem,
         uses_per_showing: live.adoption?.uses_per_showing ?? null,
         cold_count: live.adoption?.cold_count ?? 0,
+        memory_soft_cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "memorySoftCap", consolidate_js_1.DEFAULT_MEMORY_SOFT_CAP),
+        tokens: {
+            used: tokenState?.total ?? 0,
+            cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "llmTokensPerMonth", 0),
+            period_start: tokenState?.periodStart ?? null,
+        },
     };
     // Digest: pick the day to summarize. `date` (YYYY-MM-DD) wins; else the most
     // recent snapshot's day (real nightly OR backfill — both carry valid ISO
@@ -369,6 +399,11 @@ function handleDashboardData(db, query, config) {
             dedup: dayMetrics?.new_this_run?.dedup ?? dedupRows.length,
             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.
+            tokens: dayMetrics?.new_this_run?.tokens,
+            tokens_by_stage: dayMetrics?.new_this_run?.tokens_by_stage,
         },
         dedup_merges: dedupRows.map((r) => ({
             loser_id: r.loser_id,

package/dist/distiller.js

@@ -312,7 +312,7 @@ async function distillChunk(llm, transcript, projectName, date) {
     // failures, 4xx/5xx, model-not-found, timeouts) propagate up to the caller
     // so the nightly pipeline can treat them as "retry later" instead of
     // "processed successfully with zero extractions".
-    const result = await llm.completeDistill(prompt);
+    const { text: result } = await llm.completeDistill(prompt);
     if (!result)
         return { entries: [], dropped: [] };
     if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {

package/dist/domain-classify.d.ts

@@ -50,7 +50,7 @@
  *   Work, Ventures, Hardware, Finances, Property, Vehicles, Boating, Health,
  *   Family, People, Travel
  */
-import type { LlmClient } from "./llm.js";
+import type { LlmClient, LlmUsage } from "./llm.js";
 import type { DomainDef } from "./types.js";
 export type { DomainDef };
 /** Max characters of memory content fed to the classifier prompt. */
@@ -160,5 +160,11 @@ export declare function parseTagReply(reply: string, domains: DomainDef[]): TagR
  *
  * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
  *          or null on infra error.
+ *
+ * `onUsage` (#246) is an optional callback fired ONCE with the LlmUsage from
+ * the SUCCESSFUL attempt (the one whose reply parsed). Throwing/unparseable
+ * attempts don't fire it — only the call that produced the kept result is
+ * metered. The consolidation caller wires this to BudgetTracker.recordUsage;
+ * the CLI caller (classify-domains) has no tracker and omits it.
  */
-export declare function classifyMemoryTags(content: string, project: string | null | undefined, domains: DomainDef[], llm: LlmClient): Promise<TagResult | null>;
+export declare function classifyMemoryTags(content: string, project: string | null | undefined, domains: DomainDef[], llm: LlmClient, onUsage?: (usage: LlmUsage) => void): Promise<TagResult | null>;

package/dist/domain-classify.js

@@ -257,8 +257,14 @@ function parseTagReply(reply, domains) {
  *
  * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
  *          or null on infra error.
+ *
+ * `onUsage` (#246) is an optional callback fired ONCE with the LlmUsage from
+ * the SUCCESSFUL attempt (the one whose reply parsed). Throwing/unparseable
+ * attempts don't fire it — only the call that produced the kept result is
+ * metered. The consolidation caller wires this to BudgetTracker.recordUsage;
+ * the CLI caller (classify-domains) has no tracker and omits it.
  */
-async function classifyMemoryTags(content, project, domains, llm) {
+async function classifyMemoryTags(content, project, domains, llm, onUsage) {
     if (domains.length === 0)
         return { tags: [] };
     const prompt = buildClassifyPrompt(content, project, domains);
@@ -268,8 +274,19 @@ async function classifyMemoryTags(content, project, domains, llm) {
         let raw;
         try {
             // ~64 tokens covers a short JSON object with a handful of tags.
-            raw = await llm.completeClassify(prompt, 64);
+            const r = await llm.completeClassify(prompt, 64);
+            raw = r.text;
             threw = false;
+            // Surface the usage ONLY when this attempt's reply parses (below). Hold
+            // the value across the parse check so the metered call is the one whose
+            // result is actually kept.
+            const heldUsage = r.usage;
+            const parsed = parseTagReply(raw, domains);
+            if (parsed) {
+                if (heldUsage && onUsage)
+                    onUsage(heldUsage);
+                return parsed;
+            }
         }
         catch (err) {
             threw = true;
@@ -278,9 +295,6 @@ async function classifyMemoryTags(content, project, domains, llm) {
             console.warn(`[hicortex] tag classify LLM error: ${err instanceof Error ? err.message : String(err)} — aborting this memory (will retry)`);
             return null; // infra error → abort untouched (never filed, never decayed)
         }
-        const parsed = parseTagReply(raw, domains);
-        if (parsed)
-            return parsed;
         if (attempt === 0) {
             console.warn(`[hicortex] tag classify: unparseable reply "${raw.slice(0, 60)}" — retrying once`);
         }

package/dist/init.js

@@ -246,7 +246,7 @@ function allowHicortexTools() {
     // Only EDIT an existing CC settings file — never invent one. On a host with
     // no CC client (a server, or a Hermes-only box) ~/.claude/settings.json is
     // absent; creating a stub there is wrong, and the earlier mkdir+write was the
-    // ENOENT throw on bedrock's init. Without this entry CC just PROMPTS before
+    // ENOENT throw on a host with no CC client. Without this entry CC just PROMPTS before
     // tool use instead of auto-allowing — the MCP still works either way.
     if (!(0, node_fs_1.existsSync)(CC_SETTINGS)) {
         console.log(`  ℹ ${CC_SETTINGS} not found — skipping CC tool permissions (no CC client here; ` +

package/dist/llm.d.ts

@@ -108,6 +108,33 @@ export declare class RateLimitError extends Error {
     retryAfterMs: number;
     constructor(retryAfterMs: number);
 }
+/**
+ * Token-usage triplet reported by every LLM call (#246). All three fields are
+ * populated from real API responses — no estimation, no fallback. `usage` is
+ * `undefined` ONLY when a backend genuinely returned no usage object (which
+ * should never happen on a healthy path: OpenAI-compat and Ollama both echo
+ * usage on every successful completion). Callers that record usage must treat
+ * `undefined` as "no signal this call" and skip — never as zero (zero would
+ * silently undercount a real cost).
+ *
+ * Field names mirror the OpenAI spec (`prompt_tokens` / `completion_tokens` /
+ * `total_tokens`) so the shape is parseable by anything that already speaks
+ * that API. Ollama's `prompt_eval_count` / `eval_count` are mapped at the
+ * provider boundary in completeOllama.
+ */
+export interface LlmUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * The result of every LLM completion. `text` is the trimmed model output;
+ * `usage` is the token accounting from the API response (#246).
+ */
+export interface LlmResult {
+    text: string;
+    usage?: LlmUsage;
+}
 export declare class LlmClient {
     private config;
     private ollamaCallCount;
@@ -125,32 +152,43 @@ export declare class LlmClient {
      * ollama flush stays (provider-gated) — it is a scoring-call-count cadence and
      * scoring is the highest-frequency call, so this is where the flush belongs.
      */
-    completeFast(prompt: string, maxTokens?: number): Promise<string>;
+    completeFast(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Reflect-tier completion (nightly reflection). One model serves all phases
      * (#231) — this is a thin wrapper kept for call-site readability.
      */
-    completeReflect(prompt: string, maxTokens?: number): Promise<string>;
+    completeReflect(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Distillation-tier completion (session knowledge extraction). One model
      * serves all phases (#231) — thin wrapper kept for call-site readability.
      */
-    completeDistill(prompt: string, maxTokens?: number): Promise<string>;
+    completeDistill(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
      * Classification-tier completion (memory tag classification). One model
      * serves all phases (#231) — thin wrapper kept for call-site readability.
      */
-    completeClassify(prompt: string, maxTokens?: number): Promise<string>;
+    completeClassify(prompt: string, maxTokens?: number): Promise<LlmResult>;
     private complete;
     private completeOnce;
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
+     *
+     * Token usage (#246): the claude CLI JSON output does not carry a token
+     * usage field, so this path returns `usage: undefined`. The CLI is billed
+     * by Claude subscription, not per-token — there is nothing to meter. The
+     * fair-use cap therefore never trips on a claude-cli install, which is the
+     * correct outcome (no meterable cost to defend against).
      */
     private completeClaude;
     /**
      * Ollama: use /api/generate with think:false (important for qwen3.5 models).
      * num_ctx is read from config (one value, all phases — #231; default 8192).
+     *
+     * Token usage (#246): the FINAL streamed chunk carries the per-request
+     * accounting as `prompt_eval_count` (input) + `eval_count` (output). Earlier
+     * chunks have null/zero — only the terminal chunk is meaningful, so we keep
+     * updating as chunks arrive and the last one wins.
      */
     private completeOllama;
     /**
@@ -166,11 +204,21 @@ export declare class LlmClient {
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.
+     *
+     * Token usage (#246): Anthropic's response carries `usage.input_tokens` +
+     * `usage.output_tokens`. Mapped to the OpenAI-spec field names so downstream
+     * accounting is uniform across providers.
      */
     private completeAnthropic;
     /**
      * OpenAI-compatible /v1/chat/completions (works for OpenAI, OpenRouter, etc).
      * enableThinking is read from config here (one value, all phases — #231).
+     *
+     * Token usage (#246): the OpenAI spec's `usage` object is always present on
+     * a successful completion — `prompt_tokens` / `completion_tokens` /
+     * `total_tokens`. The MLX gateway emits the same shape (verified v0.31.3).
+     * Parsed verbatim; absent only on a non-conforming endpoint, in which case
+     * `usage` stays undefined (no signal, never a fabricated zero).
      */
     private completeOpenAiCompat;
 }

package/dist/llm.js

@@ -365,6 +365,12 @@ class LlmClient {
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
+     *
+     * Token usage (#246): the claude CLI JSON output does not carry a token
+     * usage field, so this path returns `usage: undefined`. The CLI is billed
+     * by Claude subscription, not per-token — there is nothing to meter. The
+     * fair-use cap therefore never trips on a claude-cli install, which is the
+     * correct outcome (no meterable cost to defend against).
      */
     async completeClaude(model, prompt, timeoutMs) {
         const { execSync } = require("node:child_process");
@@ -375,7 +381,7 @@ class LlmClient {
             if (data.is_error) {
                 throw new Error(`Claude CLI error: ${data.result}`);
             }
-            return (data.result ?? "").trim();
+            return { text: (data.result ?? "").trim() };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -388,6 +394,11 @@ class LlmClient {
     /**
      * Ollama: use /api/generate with think:false (important for qwen3.5 models).
      * num_ctx is read from config (one value, all phases — #231; default 8192).
+     *
+     * Token usage (#246): the FINAL streamed chunk carries the per-request
+     * accounting as `prompt_eval_count` (input) + `eval_count` (output). Earlier
+     * chunks have null/zero — only the terminal chunk is meaningful, so we keep
+     * updating as chunks arrive and the last one wins.
      */
     async completeOllama(model, prompt, maxTokens, timeoutMs) {
         const url = `${this.config.baseUrl.replace(/\/$/, "")}/api/generate`;
@@ -418,8 +429,13 @@ class LlmClient {
             }
             throw new Error(`Ollama error ${resp.status}: ${text}`);
         }
-        // Collect streamed response chunks
+        // Collect streamed response chunks. The terminal chunk carries the token
+        // accounting (`prompt_eval_count` / `eval_count`); earlier chunks have
+        // null. Track the latest values so the final ones win (mirrors the official
+        // ollama-js streaming parser).
         let result = "";
+        let promptTokens;
+        let completionTokens;
         const reader = resp.body?.getReader();
         if (!reader)
             throw new Error("No response body");
@@ -436,11 +452,26 @@ class LlmClient {
                     const data = JSON.parse(line);
                     if (data.response)
                         result += data.response;
+                    // Token accounting — only present on the terminal chunk. Keep the last
+                    // non-null value; missing on both → usage stays undefined (no signal).
+                    if (typeof data.prompt_eval_count === "number") {
+                        promptTokens = data.prompt_eval_count;
+                    }
+                    if (typeof data.eval_count === "number") {
+                        completionTokens = data.eval_count;
+                    }
                 }
                 catch { /* skip malformed lines */ }
             }
         }
-        return result.trim();
+        const usage = promptTokens !== undefined && completionTokens !== undefined
+            ? {
+                prompt_tokens: promptTokens,
+                completion_tokens: completionTokens,
+                total_tokens: promptTokens + completionTokens,
+            }
+            : undefined;
+        return { text: result.trim(), usage };
     }
     /**
      * Flush ollama's accumulated memory: unload the model (keep_alive:0) so the
@@ -472,6 +503,10 @@ class LlmClient {
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.
+     *
+     * Token usage (#246): Anthropic's response carries `usage.input_tokens` +
+     * `usage.output_tokens`. Mapped to the OpenAI-spec field names so downstream
+     * accounting is uniform across providers.
      */
     async completeAnthropic(model, prompt, maxTokens, timeoutMs) {
         const baseUrl = this.config.baseUrl.replace(/\/$/, "");
@@ -499,11 +534,26 @@ class LlmClient {
         }
         const data = (await resp.json());
         const textBlock = data.content?.find((c) => c.type === "text");
-        return (textBlock?.text ?? "").trim();
+        const inT = data.usage?.input_tokens;
+        const outT = data.usage?.output_tokens;
+        const usage = typeof inT === "number" && typeof outT === "number"
+            ? {
+                prompt_tokens: inT,
+                completion_tokens: outT,
+                total_tokens: inT + outT,
+            }
+            : undefined;
+        return { text: (textBlock?.text ?? "").trim(), usage };
     }
     /**
      * OpenAI-compatible /v1/chat/completions (works for OpenAI, OpenRouter, etc).
      * enableThinking is read from config here (one value, all phases — #231).
+     *
+     * Token usage (#246): the OpenAI spec's `usage` object is always present on
+     * a successful completion — `prompt_tokens` / `completion_tokens` /
+     * `total_tokens`. The MLX gateway emits the same shape (verified v0.31.3).
+     * Parsed verbatim; absent only on a non-conforming endpoint, in which case
+     * `usage` stays undefined (no signal, never a fabricated zero).
      */
     async completeOpenAiCompat(model, prompt, maxTokens, timeoutMs) {
         const baseUrl = this.config.baseUrl.replace(/\/$/, "");
@@ -547,7 +597,17 @@ class LlmClient {
             throw new Error(`LLM API error ${resp.status}: ${text}`);
         }
         const data = (await resp.json());
-        return (data.choices?.[0]?.message?.content ?? "").trim();
+        const u = data.usage;
+        const usage = typeof u?.prompt_tokens === "number" &&
+            typeof u?.completion_tokens === "number" &&
+            typeof u?.total_tokens === "number"
+            ? {
+                prompt_tokens: u.prompt_tokens,
+                completion_tokens: u.completion_tokens,
+                total_tokens: u.total_tokens,
+            }
+            : undefined;
+        return { text: (data.choices?.[0]?.message?.content ?? "").trim(), usage };
     }
 }
 exports.LlmClient = LlmClient;

package/dist/nightly.d.ts

@@ -25,4 +25,11 @@ export declare function runNightly(options?: {
      * capture-only). Uniform across client + server/co-located.
      */
     watchdog?: boolean;
+    /**
+     * Consolidate-only mode (hosted service, #110): skip capture entirely, run
+     * consolidation only. The hosted consolidation timer uses this so per-tenant
+     * nightly runs don't ingest the operator's local sessions into the tenant's
+     * DB — the tenant's agents push via /distill; the server only consolidates.
+     */
+    consolidateOnly?: boolean;
 }): Promise<void>;