@gamaze/hicortex 0.19.6 → 0.20.0

package/dist/llm.d.ts

@@ -48,6 +48,15 @@ export interface LlmConfig {
     /** TTL the daemon caches a probe outcome for (#337). Default 300000.
      *  See HicortexConfig.llmProbeTtlMs. */
     probeTtlMs?: number;
+    /** Single-flight serialization: at most ONE in-flight LLM request per
+     *  endpoint, ever (#355). Default true — a correctness property for local
+     *  single-user model servers (two concurrent large-context calls stall/OOM
+     *  the server and the machine under it). See HicortexConfig.llmSingleFlight. */
+    singleFlight?: boolean;
+    /** How long a queued call waits for the in-flight call before failing as
+     *  endpoint-down (#355). Default 900000 — the same ceiling as llmTimeoutMs.
+     *  See HicortexConfig.llmSingleFlightWaitMs. */
+    singleFlightWaitMs?: number;
 }
 /**
  * Resolve LLM configuration from explicit config-file overrides or
@@ -155,6 +164,14 @@ export interface LlmResult {
 export declare class LlmCircuitOpenError extends Error {
     constructor(endpoint: string, cooldownRemainingMs: number);
 }
+/**
+ * The TOTAL-failure class the retry ladder matches (#337, unchanged strings —
+ * this is the same matcher the ladder has always used, now also the breaker's
+ * definition of "endpoint may be down"). A fast HTTP 500, a parse error, or a
+ * rate limit is NOT in this class: those prove the endpoint ANSWERS.
+ */
+declare function isTotalFailure(message: string): boolean;
+export { isTotalFailure };
 export declare class LlmClient {
     private config;
     private ollamaCallCount;
@@ -213,6 +230,21 @@ export declare class LlmClient {
     probe(timeoutMs?: number): Promise<boolean>;
     private complete;
     private completeOnce;
+    /** The single-flight wait budget for a call with ceiling `timeoutMs`.
+     *  An explicit `llmSingleFlightWaitMs` wins; otherwise the default is
+     *  max(900 s, llmTimeoutMs) so a waiter never gives up before a legitimate
+     *  in-flight call's own (possibly raised) ceiling expires (2nd-review
+     *  finding 2 — a hardcoded 900 s made a raised-timeout install treat a
+     *  healthy-busy endpoint as down). */
+    private flightWaitMs;
+    /** Resolve the flight guard for this call, or undefined when disabled.
+     *  `staleMs` is derived from THIS call's timeout ceiling (≥ the 30-min
+     *  floor, 2× timeout) so a raised `llmTimeoutMs` can never get a live
+     *  call's lock reclaimed mid-flight (CR #355 finding 3). The lock file
+     *  records its own lease, so reclaim is judged by the HOLDER's lease, not
+     *  this waiter's parameter (2nd-review finding 3). */
+    private acquireFlightGuard;
+    private dispatchOnce;
     /**
      * Claude CLI: shell out to `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.

package/dist/llm.js

@@ -25,7 +25,13 @@ exports.resolveSavedLlmConfig = resolveSavedLlmConfig;
 exports.findClaudeBinary = findClaudeBinary;
 exports.claudeCliConfig = claudeCliConfig;
 exports.probeOllama = probeOllama;
+exports.isTotalFailure = isTotalFailure;
 const config_read_js_1 = require("./config-read.js");
+// #355: single-flight guard + canonical home (where the per-endpoint flight
+// lock files live — the daemon and the nightly share the home, so the lock
+// serializes them across processes).
+const llm_flight_js_1 = require("./llm-flight.js");
+const paths_js_1 = require("./paths.js");
 // #337: the openai-compat + anthropic request paths fetch through undici's OWN
 // fetch with an explicit dispatcher (below). Node's global fetch is also undici
 // under the hood, but with a hidden 5-minute response-HEADER timer that fires
@@ -133,6 +139,16 @@ function applyTierTuningOverlay(llmConfig, savedConfig) {
     if (savedConfig.llmProbeTtlMs !== undefined) {
         llmConfig.probeTtlMs = (0, config_read_js_1.readPositiveConfig)(savedConfig, "llmProbeTtlMs", 300000);
     }
+    // #355 single-flight. Default ON (a correctness property, not a tuning
+    // option); the wait budget defaults to the timeout ceiling so a queued call
+    // never gives up before the in-flight call's own ceiling expires.
+    const singleFlight = (0, config_read_js_1.readStrictBoolean)(savedConfig, "llmSingleFlight");
+    if (singleFlight !== undefined) {
+        llmConfig.singleFlight = singleFlight;
+    }
+    if (savedConfig.llmSingleFlightWaitMs !== undefined) {
+        llmConfig.singleFlightWaitMs = (0, config_read_js_1.readPositiveConfig)(savedConfig, "llmSingleFlightWaitMs", 900000);
+    }
 }
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
@@ -440,7 +456,8 @@ class LlmClient {
      */
     async probe(timeoutMs) {
         try {
-            await this.completeOnce(this.config.model, "Reply with OK.", 1, timeoutMs ?? this.config.probeTimeoutMs ?? 60_000);
+            const budget = timeoutMs ?? this.config.probeTimeoutMs ?? 60_000;
+            await this.completeOnce(this.config.model, "Reply with OK.", 1, budget, budget);
             return true;
         }
         catch {
@@ -492,7 +509,57 @@ class LlmClient {
         this.recordBreakerFailure();
         throw lastErr;
     }
-    async completeOnce(model, prompt, maxTokens, timeoutMs) {
+    async completeOnce(model, prompt, maxTokens, timeoutMs, 
+    /** Optional cap on the single-flight WAIT budget (the probe passes its
+     *  own timeout so a busy endpoint costs one bounded failure, not the full
+     *  900 s queue budget — the #337 "one fast failure" contract). */
+    maxFlightWaitMs) {
+        // #355 single-flight: at most ONE in-flight request per endpoint, ever —
+        // wrapping the per-attempt dispatch (not the ladder) so the lock is
+        // released between retries and a crashed attempt cannot outlive its call.
+        // The probe serializes too: a probe racing a real call would be exactly
+        // the two-concurrent-callers pattern this guard exists to prevent.
+        // Fail-open by construction: acquireLlmFlight never throws; a filesystem
+        // refusal degrades to unserialized dispatch.
+        const waitMs = Math.min(this.flightWaitMs(timeoutMs), maxFlightWaitMs ?? Infinity);
+        const guard = await this.acquireFlightGuard(timeoutMs, waitMs);
+        if (guard?.kind === "timeout") {
+            // Message deliberately contains "timeout" so isTotalFailure() matches:
+            // the ladder retries it and the breaker accrues on exhaustion — a
+            // persistently contended endpoint is indistinguishable from a slow one.
+            throw new Error(`single-flight wait timeout after ${waitMs}ms for ${this.endpointKey} — ` +
+                `another LLM call holds the flight lock (treated as endpoint-down)`);
+        }
+        try {
+            return await this.dispatchOnce(model, prompt, maxTokens, timeoutMs);
+        }
+        finally {
+            if (guard?.kind === "acquired")
+                guard.release();
+        }
+    }
+    /** The single-flight wait budget for a call with ceiling `timeoutMs`.
+     *  An explicit `llmSingleFlightWaitMs` wins; otherwise the default is
+     *  max(900 s, llmTimeoutMs) so a waiter never gives up before a legitimate
+     *  in-flight call's own (possibly raised) ceiling expires (2nd-review
+     *  finding 2 — a hardcoded 900 s made a raised-timeout install treat a
+     *  healthy-busy endpoint as down). */
+    flightWaitMs(timeoutMs) {
+        return this.config.singleFlightWaitMs ?? Math.max(900_000, timeoutMs);
+    }
+    /** Resolve the flight guard for this call, or undefined when disabled.
+     *  `staleMs` is derived from THIS call's timeout ceiling (≥ the 30-min
+     *  floor, 2× timeout) so a raised `llmTimeoutMs` can never get a live
+     *  call's lock reclaimed mid-flight (CR #355 finding 3). The lock file
+     *  records its own lease, so reclaim is judged by the HOLDER's lease, not
+     *  this waiter's parameter (2nd-review finding 3). */
+    async acquireFlightGuard(timeoutMs, waitMs) {
+        if (this.config.singleFlight === false)
+            return undefined; // kill switch
+        const staleMs = Math.max(llm_flight_js_1.DEFAULT_STALE_MS, 2 * timeoutMs);
+        return (0, llm_flight_js_1.acquireLlmFlight)((0, paths_js_1.hicortexHome)(), this.endpointKey, waitMs, staleMs);
+    }
+    async dispatchOnce(model, prompt, maxTokens, timeoutMs) {
         if (this.config.provider === "claude-cli") {
             return this.completeClaude(model, prompt, timeoutMs);
         }

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,7 +623,11 @@ 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.
@@ -926,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
@@ -1083,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;
@@ -1105,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)
@@ -1114,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.`);
@@ -1161,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[];

package/dist/opencode-transcript-reader.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readOpencodeSessions = readOpencodeSessions;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const OPENCODE_DATA_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".local", "share", "opencode");
+/**
+ * Fence around every block the opencode plugin injects (opencode-plugin/
+ * hicortex/index.ts CONTEXT_START/END). Duplicated here because the plugin
+ * is dependency-free and outside the package — keep the strings in sync.
+ */
+const FENCE_START = "<!-- hicortex-context-start -->";
+const FENCE_END = "<!-- hicortex-context-end -->";
+/**
+ * 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`).
+ */
+function readOpencodeSessions(since, opencodeHome = OPENCODE_DATA_HOME, cursors = {}) {
+    const dbPath = (0, node_path_1.join)(opencodeHome, "opencode.db");
+    if (!(0, node_fs_1.existsSync)(dbPath))
+        return []; // no opencode on this machine
+    let db;
+    try {
+        db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch {
+        return []; // locked / unreadable — skip, retry next run
+    }
+    const batches = [];
+    try {
+        // Discovery: sessions touched since the watermark. parent_id IS NULL
+        // drops sub-agent sessions (the CC isSidechain equivalent).
+        const sessions = db
+            .prepare(`SELECT id, directory, parent_id FROM session
+          WHERE time_updated > ? AND parent_id IS NULL
+          ORDER BY time_created`)
+            .all(since.getTime());
+        // Delta rows for one session. EXCLUSIVE on time_created; the id
+        // tie-break makes the read order total when two messages share a
+        // millisecond. json_extract pulls the role out of the JSON data column.
+        const msgStmt = db.prepare(`SELECT id, time_created, json_extract(data, '$.role') AS role
+         FROM message
+        WHERE session_id = ? AND time_created > ?
+        ORDER BY time_created, id`);
+        // The message's text parts in part.time_created order (distinct within a
+        // message on real data, so the join order is deterministic). Non-text
+        // part types (tool/reasoning/step-start/step-finish) are excluded here.
+        const partStmt = db.prepare(`SELECT json_extract(data, '$.text') AS text
+         FROM part
+        WHERE message_id = ? AND json_extract(data, '$.type') = 'text'
+        ORDER BY time_created`);
+        // Highest time_created in the session — used only for the shrink guard.
+        const maxStmt = db.prepare("SELECT MAX(time_created) AS m FROM message WHERE session_id = ?");
+        for (const s of sessions) {
+            const cursorKey = `opencode:${s.id}`;
+            const pos = cursors[cursorKey] ?? { cursor: 0, gen: 0 };
+            let startCursor = pos.cursor;
+            let gen = pos.gen;
+            // Shrink guard (the Hermes fix-8 pattern): a stored cursor above the
+            // session's max time_created means the DB was reset/restored — re-read
+            // from 0 and bump the generation so post-reset segment ids can't
+            // collide with pre-reset ones on the server's content-blind dedup.
+            if (startCursor > 0) {
+                const max = maxStmt.get(s.id).m ?? 0;
+                if (startCursor > max) {
+                    startCursor = 0;
+                    gen = pos.gen + 1;
+                }
+            }
+            const rows = msgStmt.all(s.id, startCursor);
+            if (rows.length === 0)
+                continue; // empty delta — nothing to post
+            const entries = [];
+            const entryCursors = [];
+            for (const r of rows) {
+                const parts = partStmt.all(r.id);
+                const content = parts
+                    .map((p) => (typeof p.text === "string" ? p.text : ""))
+                    // Fenced parts are Hicortex injection echo, not conversation.
+                    .filter((t) => t !== "" && !t.includes(FENCE_START) && !t.includes(FENCE_END))
+                    .join("\n");
+                // A message with no surviving text (tool-only / fenced-only) yields
+                // no entry. It also stays unconsumed (the cursor advances only to the
+                // last ENTRY), so it is re-scanned next run — dup-over-loss, and the
+                // entryless tail costs one no-op query until a text message lands.
+                if (content.trim() === "")
+                    continue;
+                // A NULL role passes through as "" — extractConversationText renders
+                // anything not "user" as ASSISTANT, so no turn is fabricated.
+                entries.push({ role: r.role ?? "", content });
+                entryCursors.push(r.time_created); // one end-cursor per entry
+            }
+            if (entries.length === 0)
+                continue; // entryless delta posts nothing
+            // date = the delta's LAST message time — already milliseconds, so
+            // unlike the Hermes reader there is no *1000 (copying that line would
+            // put the date ~57,000 years out).
+            batches.push({
+                sessionId: s.id,
+                projectName: (0, node_path_1.basename)(s.directory ?? "") || "opencode",
+                sourceAgent: "opencode",
+                date: new Date(rows[rows.length - 1].time_created).toISOString().slice(0, 10),
+                entries,
+                cursorKey,
+                startCursor,
+                generation: gen,
+                entryCursors,
+            });
+        }
+    }
+    catch {
+        // Query failed (schema drift on an opencode upgrade) — no-op, don't crash the run.
+        return [];
+    }
+    finally {
+        db.close();
+    }
+    return batches;
+}