@gamaze/hicortex 0.19.5 → 0.20.0

package/dist/mcp-server.js

@@ -48,6 +48,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDistillProbeGate = resolveDistillProbeGate;
 exports.resolveBodyLimitMb = resolveBodyLimitMb;
 exports.makeBodyLimitErrorHandler = makeBodyLimitErrorHandler;
 exports.makeContentLengthGate = makeContentLengthGate;
@@ -126,6 +127,33 @@ let memoryInstructionsEnabled = true;
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
+// #337: /distill readiness-probe outcomes, keyed like chunkSizeCache. The
+// daemon probes the GENERATION path (one 1-token completion) before
+// distilling — liveness-style endpoint checks cannot catch the incident
+// signature (a wedged gateway that keeps answering /v1/models while every
+// completion hangs). Outcomes are cached for llmProbeTtlMs (default 5 min),
+// so a healthy capture cadence pays at most one probe per window and a DEAD
+// endpoint turns into fast cached 503s instead of every request paying the
+// probe timeout. Module-scoped like chunkSizeCache (state spans requests).
+const distillProbeCache = new Map();
+/**
+ * Resolve the /distill probe gate (#337): true when the endpoint recently
+ * proved it can GENERATE (cached outcome inside its TTL, or a fresh probe),
+ * false when the probe failed — the caller answers 503 so the capture client
+ * holds its cursor and retries next run (nothing lost, dup-over-loss).
+ * Structural `llm` parameter (anything with probe()) so wiring tests drive
+ * the real cache + TTL discipline with a counting stub.
+ */
+async function resolveDistillProbeGate(llm, llmConfig) {
+    const key = `${llmConfig.provider}/${llmConfig.model}@${llmConfig.baseUrl}`;
+    const ttlMs = llmConfig.probeTtlMs ?? 300_000;
+    const cached = distillProbeCache.get(key);
+    if (cached && Date.now() - cached.at < ttlMs)
+        return cached.ok;
+    const ok = await llm.probe();
+    distillProbeCache.set(key, { ok, at: Date.now() });
+    return ok;
+}
 let VERSION = "0.3.x";
 try {
     const pkg = JSON.parse(require("node:fs").readFileSync(require("node:path").join(__dirname, "..", "package.json"), "utf-8"));
@@ -1165,6 +1193,16 @@ async function startServer(options = {}) {
                 return;
             }
         }
+        // #337: readiness gate — cached minimal generation probe BEFORE
+        // detectChunkSize + distillSession, so a dead endpoint never even pays the
+        // chunk-size probe. Placed AFTER the dedup short-circuits (a duplicate
+        // costs nothing and must not trip the gate). On failure: 503 with the
+        // diagnosis — the capture client treats non-201/200 as transient and holds
+        // its cursor (capture.ts), so the segment is retried next run, never lost.
+        if (!(await resolveDistillProbeGate(llm, llmConfig))) {
+            res.status(503).json({ error: "LLM endpoint not generating — session will be retried" });
+            return;
+        }
         // Cache detectChunkSize per endpoint so we probe at most once per server boot.
         // numCtx is passed so chunk size derives from the request's ACTUAL context
         // window (#231, #228) — the chunker and the request agree by construction.

package/dist/nightly.d.ts

@@ -35,6 +35,37 @@ export declare function computeSince(stateDir: string, recaptureWindowDays?: num
  * Exported for unit tests (pure on the header value).
  */
 export declare function parseRetryAfterMs(resp: Response): number | undefined;
+/**
+ * Evict-only nightly (#317) — the exported seam behind `nightly --evict-only`
+ * (the CLI path calls it via runNightly's evictOnly option; exporting it lets
+ * tests and the hosted evict timer exercise the exact mode on a temp DB
+ * without spawning a process).
+ *
+ * Runs ONLY stageMemoryCapEviction: opens the DB, evicts the lowest-value
+ * memories above the cap, closes. No capture, no watchdog, and NEVER an LLM
+ * client — the stage is pure database work, and the whole point of the mode
+ * is that a hosted trial tenant's corpus stays bounded without any LLM
+ * stages (the #298 trial-cost deviation). The cap resolves env-wins
+ * (resolveMemorySoftCap), so the hosted HICORTEX_MEMORY_CAP env pin —
+ * inherited by docker exec — is what governs here, immune to the
+ * tenant-writable config.json.
+ *
+ * Synchronous by design (better-sqlite3 is sync; there is nothing to await)
+ * and returns the stage result so callers (tests, operators scripting around
+ * the timer) can log/assert the outcome. The decay/recall/scoring knobs are
+ * configured from the same config a FULL nightly would read — the eviction
+ * ranker (effectiveStrength) must pick victims by the same clock the recall
+ * ranker uses, or an evict-only run would evict a different tail than the
+ * nightly would have.
+ */
+export declare function runEvictionOnly(options?: {
+    dbPath?: string;
+    stateDir?: string;
+    dryRun?: boolean;
+}): {
+    cap: number;
+    evicted: number;
+};
 export declare function runNightly(options?: {
     dryRun?: boolean;
     captureOnly?: boolean;
@@ -57,4 +88,14 @@ export declare function runNightly(options?: {
      * DB — the tenant's agents push via /distill; the server only consolidates.
      */
     consolidateOnly?: boolean;
+    /**
+     * Evict-only mode (#317): run ONLY the memory-cap eviction stage — no
+     * watchdog, no capture, and NEVER an LLM client (the stage is pure database
+     * work, consolidate.ts stageMemoryCapEviction). This is the trial hard wall:
+     * hosted trials get a low HICORTEX_MEMORY_CAP env pin and a per-tenant
+     * evict timer that execs this mode, so a trial corpus stays bounded with
+     * zero LLM stages (the #298 no-LLM-for-trials cost deviation). Also the
+     * lifetime converge tool — idempotent, cheap, safe to run at any cadence.
+     */
+    evictOnly?: boolean;
 }): Promise<void>;

package/dist/nightly.js

@@ -47,6 +47,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeSince = computeSince;
 exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.runEvictionOnly = runEvictionOnly;
 exports.runNightly = runNightly;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -68,6 +69,7 @@ const transcript_reader_js_1 = require("./transcript-reader.js");
 const hermes_transcript_reader_js_1 = require("./hermes-transcript-reader.js");
 const pi_transcript_reader_js_1 = require("./pi-transcript-reader.js");
 const oc_transcript_reader_js_1 = require("./oc-transcript-reader.js");
+const opencode_transcript_reader_js_1 = require("./opencode-transcript-reader.js");
 const features_js_1 = require("./features.js");
 const retrieval_js_1 = require("./retrieval.js");
 const state_js_1 = require("./state.js");
@@ -291,14 +293,65 @@ function rotateNightlyLog(stateDir = HICORTEX_HOME) {
     }
     catch { /* no log file, or unreadable — nothing to rotate */ }
 }
+/**
+ * Evict-only nightly (#317) — the exported seam behind `nightly --evict-only`
+ * (the CLI path calls it via runNightly's evictOnly option; exporting it lets
+ * tests and the hosted evict timer exercise the exact mode on a temp DB
+ * without spawning a process).
+ *
+ * Runs ONLY stageMemoryCapEviction: opens the DB, evicts the lowest-value
+ * memories above the cap, closes. No capture, no watchdog, and NEVER an LLM
+ * client — the stage is pure database work, and the whole point of the mode
+ * is that a hosted trial tenant's corpus stays bounded without any LLM
+ * stages (the #298 trial-cost deviation). The cap resolves env-wins
+ * (resolveMemorySoftCap), so the hosted HICORTEX_MEMORY_CAP env pin —
+ * inherited by docker exec — is what governs here, immune to the
+ * tenant-writable config.json.
+ *
+ * Synchronous by design (better-sqlite3 is sync; there is nothing to await)
+ * and returns the stage result so callers (tests, operators scripting around
+ * the timer) can log/assert the outcome. The decay/recall/scoring knobs are
+ * configured from the same config a FULL nightly would read — the eviction
+ * ranker (effectiveStrength) must pick victims by the same clock the recall
+ * ranker uses, or an evict-only run would evict a different tail than the
+ * nightly would have.
+ */
+function runEvictionOnly(options = {}) {
+    const stateDir = options.stateDir ?? HICORTEX_HOME;
+    const savedConfig = readNightlyConfig(stateDir);
+    // Same clock as the full nightly (see runNightly's identical trio) — the
+    // eviction ranker reads these module knobs.
+    (0, retrieval_js_1.configureDecay)({ halfLifeDays: savedConfig?.decayHalfLifeDays });
+    (0, retrieval_js_1.configureRecall)(savedConfig);
+    (0, retrieval_js_1.configureScoring)(savedConfig);
+    const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
+    console.log(`[hicortex] evict-only run${options.dryRun ? " (dry run)" : ""} — DB: ${dbPath}`);
+    const db = (0, db_js_1.initDb)(dbPath);
+    try {
+        const res = (0, consolidate_js_1.stageMemoryCapEviction)(db, options.dryRun ?? false, (0, consolidate_js_1.resolveMemorySoftCap)(savedConfig?.memorySoftCap));
+        console.log(`[hicortex] evict-only ${options.dryRun ? "would evict" : "evicted"} ${res.evicted} ` +
+            `memor${res.evicted === 1 ? "y" : "ies"} (cap ${res.cap})`);
+        return res;
+    }
+    finally {
+        db.close();
+    }
+}
 async function runNightly(options = {}) {
     const dryRun = options.dryRun ?? false;
     let captureOnly = options.captureOnly ?? false;
     const watchdog = options.watchdog ?? false;
     const consolidateOnly = options.consolidateOnly ?? false;
+    const evictOnly = options.evictOnly ?? false;
     if (captureOnly && consolidateOnly) {
         throw new Error("runNightly: captureOnly and consolidateOnly are mutually exclusive");
     }
+    if (evictOnly && captureOnly) {
+        throw new Error("runNightly: evictOnly and captureOnly are mutually exclusive");
+    }
+    if (evictOnly && consolidateOnly) {
+        throw new Error("runNightly: evictOnly and consolidateOnly are mutually exclusive");
+    }
     const stateDir = options.stateDir ?? HICORTEX_HOME;
     const recaptureWindowDays = options.recaptureWindowDays;
     rotateNightlyLog(stateDir);
@@ -318,6 +371,20 @@ async function runNightly(options = {}) {
     const savedConfig = readNightlyConfig(stateDir);
     // 0.16.8 upgrade guard: warn if ignored per-stage keys are still present.
     (0, config_read_js_1.warnIgnoredConfigKeys)(savedConfig);
+    // Evict-only (#317): the pure-DB maintenance mode. Branches BEFORE the
+    // watchdog gate, the agentId self-heal, and every capture/LLM step — the
+    // mode must stay strictly "open DB, evict to cap, close" (see
+    // runEvictionOnly below). A client-mode machine has no local DB to evict
+    // (the corpus lives on the remote server); skipping WITHOUT creating one is
+    // the honest answer there.
+    if (evictOnly) {
+        if (savedConfig?.mode === "client") {
+            console.log("[hicortex] evict-only: client mode has no local DB — nothing to evict");
+            return;
+        }
+        runEvictionOnly({ dbPath: options.dbPath, stateDir, dryRun });
+        return;
+    }
     // 0.16.2 activation gap: pre-0.16.2 installs never re-run init, so their
     // config has no agentId → capture sent source_agent_id: null forever (the
     // provenance feature was inert for the whole existing fleet). Self-heal on
@@ -428,6 +495,7 @@ async function runNightly(options = {}) {
         let hermesBatches = [];
         let piBatches = [];
         let ocBatches = [];
+        let opencodeBatches = [];
         let batches = [];
         let memoriesIngested = 0;
         let hadTransientFailure = false;
@@ -487,7 +555,11 @@ async function runNightly(options = {}) {
                     // OpenClaw persists sessions in the Pi v3 format at ~/.openclaw/agents/;
                     // no-ops when OC isn't installed.
                     ocBatches = (0, oc_transcript_reader_js_1.readOcTranscripts)(since, undefined, cursorMap);
-                    batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches];
+                    // opencode persists sessions in one SQLite store
+                    // (~/.local/share/opencode/opencode.db); no-ops when opencode isn't
+                    // installed (#347).
+                    opencodeBatches = (0, opencode_transcript_reader_js_1.readOpencodeSessions)(since, undefined, cursorMap);
+                    batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches, ...opencodeBatches];
                     if (ccBatches.length > 0)
                         console.log(`[hicortex] Found ${ccBatches.length} CC session(s)`);
                     if (hermesBatches.length > 0)
@@ -496,6 +568,8 @@ async function runNightly(options = {}) {
                         console.log(`[hicortex] Found ${piBatches.length} Pi session(s)`);
                     if (ocBatches.length > 0)
                         console.log(`[hicortex] Found ${ocBatches.length} OpenClaw session(s)`);
+                    if (opencodeBatches.length > 0)
+                        console.log(`[hicortex] Found ${opencodeBatches.length} opencode session(s)`);
                     console.log(`[hicortex] Total: ${batches.length} new session(s)`);
                     if (batches.length === 0 && !dryRun) {
                         console.log(captureOnly
@@ -549,12 +623,20 @@ async function runNightly(options = {}) {
         // Resolved cap (#245) for the dashboard snapshot. Hoisted so the snapshot
         // writer (outside the consolidation block) can stamp `capacity` even when
         // consolidation was skipped (the cap is still "in force" config-wise).
-        const memorySoftCapResolved = (0, config_read_js_1.readNonNegativeConfig)(savedConfig ?? {}, "memorySoftCap", consolidate_js_1.DEFAULT_MEMORY_SOFT_CAP);
+        // #317: resolved through the shared env-wins resolver — a
+        // HICORTEX_MEMORY_CAP pin governs the eviction input AND the snapshot
+        // stamp from this one value (the dashboard live headline resolves through
+        // the same function, so enforced + displayed can never disagree).
+        const memorySoftCapResolved = (0, consolidate_js_1.resolveMemorySoftCap)(savedConfig?.memorySoftCap);
         // Consolidation outcome for telemetry (0.17). undefined on capture-only runs
         // (which send no nightly ping). "skipped" = runConsolidation's built-in
         // nothing-to-do short-circuit (zero LLM calls), NOT a failure.
         // "throttled" (#246) = the llmTokensPerMonth fair-use cap was projected to
         // be exceeded, so consolidation was skipped before any LLM call.
+        // "endpoint_down" (#337) = the pre-consolidation readiness probe failed, or
+        // the LLM circuit breaker was open after the run — transient (retried next
+        // run), and NEVER "completed": the stages fail soft, so without this
+        // override a dead-endpoint run would report clean.
         let consolidationStatus;
         // #246: total consolidation tokens consumed this run (hoisted for telemetry
         // + the dashboard snapshot). Undefined when consolidation didn't run at all
@@ -620,95 +702,119 @@ async function runNightly(options = {}) {
                     }
                 }
                 if (consolidationStatus !== "throttled") {
-                    // One model serves all phases (#231) — there is no separate endpoint to
-                    // pre-flight. If the model doesn't answer, `complete()` already retries at
-                    // 30s/60s/120s (~3.5 min); anything still failing after that is an outage,
-                    // not a blip. A failed phase costs latency, not data: capture cursors hold
-                    // on failure (dup-over-loss), and consolidation has resumable cursors
-                    // (domainCursor, supersessionCursor). The nightly runs 2-4×/day, so the
-                    // wait is hours — no polling, no new config. (Issue #231.)
-                    const cfgDomains = (0, domain_classify_js_1.parseConfigDomains)(savedConfig);
-                    console.log(`[hicortex] Running consolidation...`);
-                    const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun, false, undefined, {
-                        domains: cfgDomains,
-                        contentDomainsReady: true,
-                        weakPrimaryFloor: (0, nofit_js_1.resolveWeakPrimaryFloor)(savedConfig),
-                    }, {
-                        minSimilarity: savedConfig?.supersessionMinSimilarity,
-                        maxCalls: savedConfig?.supersessionMaxCalls,
-                    }, 
-                    // #241: config-driven total LLM-call ceiling (default 5000, was 200).
-                    (0, config_read_js_1.readPositiveConfig)(savedConfig ?? {}, "consolidateMaxLlmCalls", consolidate_js_1.CONSOLIDATE_MAX_LLM_CALLS), 
-                    // #245: soft cap on the corpus (default 10000; 0 disables eviction).
-                    memorySoftCapResolved);
-                    console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
-                        (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
-                    consolidationStatus = report.status;
-                    // #245: capture the eviction count for the dashboard snapshot. The
-                    // stage always returns `evicted` (0 when under cap / disabled); report
-                    // it as 0 (a real value), not undefined, when the stage ran.
-                    evictedCount = report.stages.memory_cap?.evicted ?? 0;
-                    // Only set when reflection actually RAN (not skipped). A skipped stage
-                    // (e.g. endpoint offline, #232 fail-soft) must NOT collapse to 0 — that
-                    // would make "endpoint down" indistinguishable from "prompt too tight"
-                    // in the fleet aggregate. Leave undefined so the optional field is
-                    // omitted and the aggregate buckets skipped runs separately.
-                    const refl = report.stages.reflection;
-                    if (refl && !refl.skipped)
-                        lessonsGenerated = refl.lessons_generated;
-                    // #246: surface token totals for telemetry + dashboard snapshot. Both
-                    // fields stay undefined on a skipped/failed run (no metered calls →
-                    // nothing to report; the optional fields are omitted from the ping).
-                    const tokensTotal = report.budget?.tokens_total;
-                    if (tokensTotal && tokensTotal.total > 0) {
-                        tokensThisRun = tokensTotal.total;
-                        tokensByStage = report.budget?.tokens_by_stage;
+                    // #337: readiness probe — ONE minimal generation request before any
+                    // consolidation phase. This REPLACES the #231 no-preflight decision
+                    // (its premise "a failed phase costs latency, not data" was falsified
+                    // by the 2026-08-23/24 incident: the gateway answered /v1/models —
+                    // liveness — while generation was dead, and the nightly retried into
+                    // it for ~5 h, making the wedge monotonically worse). A failed probe
+                    // skips consolidation entirely with the diagnosis "LLM endpoint not
+                    // generating" (not-generating, not slow) and status endpoint_down —
+                    // a transient outcome: consolidation has resumable cursors, the
+                    // nightly re-runs 2-4×/day, and capture is unaffected (the daemon's
+                    // /distill path has its own probe). Zero LLM phases run when the
+                    // probe fails — one fast failure is the whole cost.
+                    const probeOk = await llm.probe();
+                    if (!probeOk) {
+                        console.error("[hicortex] LLM endpoint not generating — consolidation skipped " +
+                            "(endpoint_down, will retry next run). See the ops runbook's " +
+                            "known failure signatures; llmProbeTimeoutMs tunes the probe's patience.");
+                        consolidationStatus = "endpoint_down";
                     }
-                    // #255: budget exhaustion — always populated when consolidation ran
-                    // (report.budget.exhausted is a boolean). The dashboard + telemetry
-                    // treat true as a quality-degradation health signal. The
-                    // ran-vs-didn't-run distinction is carried by `budgetCallsUsed`/
-                    // `budgetMaxCalls` (forwarded whenever consolidation ran), NOT by a
-                    // false `budget_exhausted` flag — the snapshot forwards
-                    // `budget_exhausted` only on exhaustion (alert state), so the
-                    // aggregate reads: calls_used present + budget_exhausted undefined
-                    // = "ran and didn't exhaust"; calls_used undefined = "didn't run".
-                    budgetExhausted = report.budget?.exhausted;
-                    budgetDeferredByStage = report.budget?.deferred_by_stage;
-                    budgetCallsUsed = report.budget?.calls_used;
-                    budgetMaxCalls = report.budget?.max_calls;
-                    // #246: accrue to state.json (monthly reset + last-run estimate for
-                    // the next throttle check). Written even on a failed run — a partial
-                    // run that made metered calls before the failure still spent tokens,
-                    // and the next run's estimate should reflect that.
-                    if (!dryRun) {
-                        (0, state_js_1.updateState)((s) => {
-                            const now = new Date();
-                            const cur = s.llmTokensThisPeriod;
-                            let periodStart = cur?.periodStart ?? now.toISOString();
-                            let prompt = cur?.prompt ?? 0;
-                            let completion = cur?.completion ?? 0;
-                            let total = cur?.total ?? 0;
-                            // Monthly reset: if periodStart is in a previous calendar month,
-                            // zero the accrual before adding this run's contribution.
-                            const startD = new Date(periodStart);
-                            if (startD.getUTCFullYear() !== now.getUTCFullYear() ||
-                                startD.getUTCMonth() !== now.getUTCMonth()) {
-                                periodStart = now.toISOString();
-                                prompt = 0;
-                                completion = 0;
-                                total = 0;
-                            }
-                            if (tokensTotal) {
-                                prompt += tokensTotal.prompt;
-                                completion += tokensTotal.completion;
-                                total += tokensTotal.total;
-                            }
-                            s.llmTokensThisPeriod = {
-                                prompt, completion, total, periodStart,
-                            };
-                            s.llmTokensLastRun = tokensTotal?.total ?? 0;
-                        }, stateDir);
+                    else {
+                        const cfgDomains = (0, domain_classify_js_1.parseConfigDomains)(savedConfig);
+                        console.log(`[hicortex] Running consolidation...`);
+                        const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun, false, undefined, {
+                            domains: cfgDomains,
+                            contentDomainsReady: true,
+                            weakPrimaryFloor: (0, nofit_js_1.resolveWeakPrimaryFloor)(savedConfig),
+                        }, {
+                            minSimilarity: savedConfig?.supersessionMinSimilarity,
+                            maxCalls: savedConfig?.supersessionMaxCalls,
+                        }, 
+                        // #241: config-driven total LLM-call ceiling (default 5000, was 200).
+                        (0, config_read_js_1.readPositiveConfig)(savedConfig ?? {}, "consolidateMaxLlmCalls", consolidate_js_1.CONSOLIDATE_MAX_LLM_CALLS), 
+                        // #245: soft cap on the corpus (default 10000; 0 disables eviction).
+                        memorySoftCapResolved);
+                        console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
+                            (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
+                        consolidationStatus = report.status;
+                        // #337: the stages fail soft, so a run against an endpoint that died
+                        // MID-run would otherwise report "completed". An open breaker is the
+                        // honest signal — override to endpoint_down (lastConsolidated still
+                        // only advances on a clean "completed", so the work is re-run).
+                        if (llm.breakerOpen) {
+                            console.error(`[hicortex] LLM circuit breaker OPEN after consolidation — ` +
+                                `overriding "${report.status}" to endpoint_down (stages failed ` +
+                                `soft against a down endpoint; will retry next run).`);
+                            consolidationStatus = "endpoint_down";
+                        }
+                        // #245: capture the eviction count for the dashboard snapshot. The
+                        // stage always returns `evicted` (0 when under cap / disabled); report
+                        // it as 0 (a real value), not undefined, when the stage ran.
+                        evictedCount = report.stages.memory_cap?.evicted ?? 0;
+                        // Only set when reflection actually RAN (not skipped). A skipped stage
+                        // (e.g. endpoint offline, #232 fail-soft) must NOT collapse to 0 — that
+                        // would make "endpoint down" indistinguishable from "prompt too tight"
+                        // in the fleet aggregate. Leave undefined so the optional field is
+                        // omitted and the aggregate buckets skipped runs separately.
+                        const refl = report.stages.reflection;
+                        if (refl && !refl.skipped)
+                            lessonsGenerated = refl.lessons_generated;
+                        // #246: surface token totals for telemetry + dashboard snapshot. Both
+                        // fields stay undefined on a skipped/failed run (no metered calls →
+                        // nothing to report; the optional fields are omitted from the ping).
+                        const tokensTotal = report.budget?.tokens_total;
+                        if (tokensTotal && tokensTotal.total > 0) {
+                            tokensThisRun = tokensTotal.total;
+                            tokensByStage = report.budget?.tokens_by_stage;
+                        }
+                        // #255: budget exhaustion — always populated when consolidation ran
+                        // (report.budget.exhausted is a boolean). The dashboard + telemetry
+                        // treat true as a quality-degradation health signal. The
+                        // ran-vs-didn't-run distinction is carried by `budgetCallsUsed`/
+                        // `budgetMaxCalls` (forwarded whenever consolidation ran), NOT by a
+                        // false `budget_exhausted` flag — the snapshot forwards
+                        // `budget_exhausted` only on exhaustion (alert state), so the
+                        // aggregate reads: calls_used present + budget_exhausted undefined
+                        // = "ran and didn't exhaust"; calls_used undefined = "didn't run".
+                        budgetExhausted = report.budget?.exhausted;
+                        budgetDeferredByStage = report.budget?.deferred_by_stage;
+                        budgetCallsUsed = report.budget?.calls_used;
+                        budgetMaxCalls = report.budget?.max_calls;
+                        // #246: accrue to state.json (monthly reset + last-run estimate for
+                        // the next throttle check). Written even on a failed run — a partial
+                        // run that made metered calls before the failure still spent tokens,
+                        // and the next run's estimate should reflect that.
+                        if (!dryRun) {
+                            (0, state_js_1.updateState)((s) => {
+                                const now = new Date();
+                                const cur = s.llmTokensThisPeriod;
+                                let periodStart = cur?.periodStart ?? now.toISOString();
+                                let prompt = cur?.prompt ?? 0;
+                                let completion = cur?.completion ?? 0;
+                                let total = cur?.total ?? 0;
+                                // Monthly reset: if periodStart is in a previous calendar month,
+                                // zero the accrual before adding this run's contribution.
+                                const startD = new Date(periodStart);
+                                if (startD.getUTCFullYear() !== now.getUTCFullYear() ||
+                                    startD.getUTCMonth() !== now.getUTCMonth()) {
+                                    periodStart = now.toISOString();
+                                    prompt = 0;
+                                    completion = 0;
+                                    total = 0;
+                                }
+                                if (tokensTotal) {
+                                    prompt += tokensTotal.prompt;
+                                    completion += tokensTotal.completion;
+                                    total += tokensTotal.total;
+                                }
+                                s.llmTokensThisPeriod = {
+                                    prompt, completion, total, periodStart,
+                                };
+                                s.llmTokensLastRun = tokensTotal?.total ?? 0;
+                            }, stateDir);
+                        }
                     }
                 }
             }
@@ -898,6 +1004,7 @@ async function runNightly(options = {}) {
                 hermesBatches.length > 0 && "hermes",
                 piBatches.length > 0 && "pi",
                 ocBatches.length > 0 && "oc",
+                opencodeBatches.length > 0 && "opencode",
             ].filter(Boolean);
             const agentType = kinds.length > 1 ? "mixed" : (kinds[0] ?? "cc");
             // Adoption aggregates (0.15.1): corpus-wide exposure vs use. uses/shown
@@ -1055,6 +1162,7 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
     let hermesBatches = [];
     let piBatches = [];
     let ocBatches = [];
+    let opencodeBatches = [];
     let batches = [];
     let memoriesIngested = 0;
     let sessionsSent = 0;
@@ -1077,7 +1185,8 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
         hermesBatches = (0, hermes_transcript_reader_js_1.readHermesSessions)(since, undefined, cursorMap);
         piBatches = (0, pi_transcript_reader_js_1.readPiTranscripts)(since, undefined, cursorMap);
         ocBatches = (0, oc_transcript_reader_js_1.readOcTranscripts)(since, undefined, cursorMap);
-        batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches];
+        opencodeBatches = (0, opencode_transcript_reader_js_1.readOpencodeSessions)(since, undefined, cursorMap);
+        batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches, ...opencodeBatches];
         if (ccBatches.length > 0)
             console.log(`[hicortex] Found ${ccBatches.length} CC session(s)`);
         if (hermesBatches.length > 0)
@@ -1086,6 +1195,8 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
             console.log(`[hicortex] Found ${piBatches.length} Pi session(s)`);
         if (ocBatches.length > 0)
             console.log(`[hicortex] Found ${ocBatches.length} OpenClaw session(s)`);
+        if (opencodeBatches.length > 0)
+            console.log(`[hicortex] Found ${opencodeBatches.length} opencode session(s)`);
         console.log(`[hicortex] Total: ${batches.length} new session(s)`);
         if (batches.length === 0) {
             console.log(`[hicortex] Nothing to capture.`);
@@ -1133,6 +1244,7 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
             hermesBatches.length > 0 && "hermes",
             piBatches.length > 0 && "pi",
             ocBatches.length > 0 && "oc",
+            opencodeBatches.length > 0 && "opencode",
         ].filter(Boolean);
         const agentType = kinds.length > 1 ? "mixed" : (kinds[0] ?? "cc");
         await (0, telemetry_js_1.sendTelemetry)({

package/dist/opencode-transcript-reader.d.ts

@@ -0,0 +1,63 @@
+/**
+ * opencode transcript reader — the nightly capture path for the opencode
+ * coding agent (#347).
+ *
+ * opencode persists every session in ONE SQLite store:
+ *   ~/.local/share/opencode/opencode.db
+ *
+ * Schema (relevant columns, verified live on opencode 1.18.20/1.18.23):
+ *   session(id TEXT PK, directory TEXT, parent_id TEXT NULL,
+ *           time_created INTEGER, time_updated INTEGER)  — epoch MILLISECONDS
+ *   message(id TEXT PK, session_id TEXT, time_created INTEGER,
+ *           time_updated INTEGER, data TEXT)             — data = {"role",…}
+ *   part(id TEXT PK, message_id TEXT, time_created INTEGER, data TEXT)
+ *                                                         — data = {"type","text",…}
+ *
+ * The message row holds METADATA ONLY (role, model, cost — no text); the
+ * conversation text lives in the message's part rows as
+ * {"type":"text","text":…}. part types tool/reasoning/step-start/step-finish
+ * are plumbing, not conversation, and are excluded by the `$.type`='text'
+ * filter. A message left with no text yields no entry.
+ *
+ * Cursor: message.time_created (epoch ms) — deliberately NOT rowid. message
+ * has a TEXT primary key, so rowid is implicit, reusable after the
+ * session-delete cascade and renumbered by VACUUM — a stored rowid cursor can
+ * silently skip rows (loss, breaking the dup-over-loss invariant). Unlike the
+ * Hermes cursor column (INTEGER PRIMARY KEY AUTOINCREMENT — strictly
+ * increasing, never reused), time_created is never rewritten. The delta is
+ * EXCLUSIVE (`time_created > cursor`, ORDER BY time_created, id — the id
+ * tie-break makes the order total) so a rediscovered session with no new
+ * messages produces an empty delta and posts nothing; segment ids stay
+ * byte-stable for the server's segment-exact dedup. Residual gap: two
+ * messages written in the same millisecond with the capture boundary inside
+ * that group — bounded by that group's size, not observed on real data
+ * (smallest observed inter-message gap 13 ms).
+ *
+ * Sub-agent sessions (session.parent_id set) are skipped, mirroring the CC
+ * reader's isSidechain drop. Written defensively: parent_id was NULL for
+ * every session on the verified installs, so whether opencode populates it
+ * is unconfirmed — the skip costs nothing if the column stays empty.
+ *
+ * Marker-fenced text parts (Hicortex injection echo) are skipped so memory
+ * never re-enters itself — defense in depth: the recall channel the opencode
+ * plugin uses (experimental.chat.messages.transform) is verified NOT to
+ * persist its output, but the reader guards regardless.
+ *
+ * No-ops (returns []) when the database, a table, or a column is absent —
+ * the schema is young (migration tables present), so the reader
+ * shape-guards and never crashes the nightly run.
+ */
+import type { TranscriptBatch, CursorMap } from "./transcript-reader.js";
+/**
+ * Read opencode sessions updated since `since` (the bulk watermark; opencode
+ * times are epoch milliseconds, so `since.getTime()` compares directly —
+ * NO *1000, unlike the Hermes reader's unix-seconds store). Returns one
+ * batch per session, parallel to readHermesSessions().
+ *
+ * @param opencodeHome opencode's data dir (default
+ *   ~/.local/share/opencode); injectable for tests.
+ * @param cursors Per-session capture cursors (#189), keyed
+ *   `opencode:<sessionId>`. The cursor value is the highest captured
+ *   message.time_created; the delta is exclusive (`time_created > cursor`).
+ */
+export declare function readOpencodeSessions(since: Date, opencodeHome?: string, cursors?: CursorMap): TranscriptBatch[];