failproofai 0.0.13-beta.0 → 0.0.13-beta.1

package/lib/cli-registry.ts

@@ -27,7 +27,7 @@
 import type { IntegrationType } from "@/src/hooks/types";
 
 /** Canonical CLI ids the registry knows about. Mirrors `INTEGRATION_TYPES`. */
-export const KNOWN_CLI_IDS = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"] as const satisfies readonly IntegrationType[];
+export const KNOWN_CLI_IDS = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini", "hermes"] as const satisfies readonly IntegrationType[];
 export type CliId = (typeof KNOWN_CLI_IDS)[number];
 
 /** Per-CLI metadata consumed by the dashboard. */
@@ -74,6 +74,11 @@ const CLI_ENTRIES: Record<CliId, CliEntry> = {
     label: "Gemini CLI",
     badgeClasses: "bg-sky-500/10 text-sky-400 border-sky-500/20",
   },
+  hermes: {
+    id: "hermes",
+    label: "Hermes",
+    badgeClasses: "bg-indigo-500/10 text-indigo-400 border-indigo-500/20",
+  },
 };
 
 export function getCliEntry(id: string): CliEntry | undefined {

package/lib/download-session.ts

@@ -14,6 +14,11 @@ import { resolveSessionFilePath, UUID_RE } from "./projects";
 import type { CliId } from "./cli-registry";
 
 export const OPENCODE_SESSION_RE = /^ses_[A-Za-z0-9]+$/;
+/** Hermes session IDs (e.g. `YYYYMMDD_HHMMSS_<hash>` / `cron_<hash>_...`). Kept
+ *  in sync with `getHermesSessionLog`'s validator in lib/hermes-sessions.ts —
+ *  a stricter pattern here would let a session list/open in the viewer yet fail
+ *  its download with `RangeError("Invalid session ID")`. */
+export const HERMES_SESSION_RE = /^[A-Za-z0-9_-]+$/;
 
 export type DownloadSource =
   | { kind: "file"; path: string }
@@ -23,6 +28,7 @@ export type DownloadSource =
  *  prefixes; everyone else is a UUID. */
 export function isValidSessionId(cli: CliId, sessionId: string): boolean {
   if (cli === "opencode") return OPENCODE_SESSION_RE.test(sessionId);
+  if (cli === "hermes") return HERMES_SESSION_RE.test(sessionId);
   return UUID_RE.test(sessionId);
 }
 
@@ -85,6 +91,16 @@ export async function resolveDownloadSource(
     return { kind: "synthesized", body, contentType: "application/json", extension: "json" };
   }
 
+  if (cli === "hermes") {
+    // Hermes keeps sessions in SQLite (~/.hermes/state.db). Synthesize a JSONL
+    // export of the session's raw `messages` rows.
+    const { getHermesSessionLog } = await import("./hermes-sessions");
+    const result = await getHermesSessionLog(sessionId);
+    if (!result) return null;
+    const body = result.rawLines.map((r) => JSON.stringify(r)).join("\n") + "\n";
+    return { kind: "synthesized", body, contentType: "application/x-ndjson", extension: "jsonl" };
+  }
+
   // Exhaustive — but TypeScript can't always see CliId is exhausted across the
   // if-chain above, so guard with a runtime fallback.
   const _exhaustive: never = cli;

package/lib/hermes-projects.ts

@@ -0,0 +1,164 @@
+/**
+ * Hermes (hermes-agent) session enumeration — AUDIT-ONLY.
+ *
+ * Reads the `sessions` table directly from `~/.hermes/state.db` via the bundled
+ * sql.js reader. All gateway users' sessions live in the one DB → "audit
+ * everyone from one place". Because we query the table (not a text `sessions
+ * list`), we get `source`/`cwd`/`message_count` up front — enough to group by
+ * channel and to build a real per-transcript cache key.
+ */
+import { openSqliteReadonly } from "./sqlite-reader";
+import { hermesDbPath, epochToMs } from "./hermes-sessions";
+import { runtimeCache } from "./runtime-cache";
+import type { ProjectFolder, SessionFile } from "./projects";
+import { formatDate } from "./format-date";
+
+export interface HermesSessionRef {
+  sessionId: string;
+  source?: string;
+  cwd?: string;
+  title?: string;
+  /** Slack/Telegram user that drove the session. */
+  userId?: string;
+  /** Channel id + type (group/dm) the session ran in. */
+  chatId?: string;
+  chatType?: string;
+  /** From `ended_at` (falls back to `started_at`) — epoch ms. */
+  mtimeMs: number;
+  /** `message_count` — a stable cache key for an ended session. Can lag (Hermes
+   *  may write it lazily / only at session end), so don't use it alone to decide
+   *  emptiness. */
+  messageCount: number;
+  /** True when the session has ≥1 real message row (`MAX(messages.timestamp)`
+   *  non-null). Reliable "non-empty" signal even when `message_count` is a
+   *  stale `0` for an in-progress session. */
+  hasMessages: boolean;
+}
+
+interface SessionRow {
+  id: string;
+  source: string | null;
+  cwd: string | null;
+  title: string | null;
+  user_id: string | null;
+  chat_id: string | null;
+  chat_type: string | null;
+  started_at: number | null;
+  ended_at: number | null;
+  message_count: number | null;
+  /** MAX(messages.timestamp) — the real last-activity time; advances on every
+   *  new message even while the session is still open (ended_at is null). */
+  last_activity: number | null;
+}
+
+/**
+ * List every Hermes session (all users). Returns `[]` when the DB is missing or
+ * unreadable (fail-open — the audit just skips Hermes).
+ */
+export async function getHermesSessions(): Promise<HermesSessionRef[]> {
+  const db = await openSqliteReadonly(hermesDbPath());
+  if (!db) return [];
+  try {
+    const rows = db.query<SessionRow>(
+      "SELECT s.id, s.source, s.cwd, s.title, s.user_id, s.chat_id, s.chat_type, " +
+        "s.started_at, s.ended_at, s.message_count, lm.last_activity " +
+        "FROM sessions s " +
+        "LEFT JOIN (SELECT session_id, MAX(timestamp) AS last_activity FROM messages GROUP BY session_id) lm " +
+        "ON lm.session_id = s.id " +
+        "ORDER BY lm.last_activity DESC",
+    );
+    return rows.map((r) => ({
+      sessionId: r.id,
+      source: r.source ?? undefined,
+      cwd: r.cwd ?? undefined,
+      title: r.title ?? undefined,
+      userId: r.user_id ?? undefined,
+      chatId: r.chat_id ?? undefined,
+      chatType: r.chat_type ?? undefined,
+      // Prefer the latest message time (advances live); fall back to ended/started.
+      mtimeMs: epochToMs(r.last_activity ?? r.ended_at ?? r.started_at),
+      messageCount: typeof r.message_count === "number" ? r.message_count : 0,
+      hasMessages: r.last_activity != null,
+    }));
+  } catch {
+    return [];
+  } finally {
+    db.close();
+  }
+}
+
+export const getCachedHermesSessions = runtimeCache(getHermesSessions, 2);
+
+// ── Dashboard history browser (projects list + project-detail sessions) ──
+
+/**
+ * Surface Hermes gateway sessions as synthetic "projects" grouped by `source`
+ * (slack/telegram/cli/cron) — gateway sessions have no cwd to group by. One
+ * ProjectFolder per source; its `name` is `hermes-<source>`, reversed in
+ * `getHermesSessionsByEncodedName`.
+ */
+export async function getHermesProjects(): Promise<ProjectFolder[]> {
+  const sessions = await getHermesSessions();
+  const latestBySource = new Map<string, number>();
+  for (const s of sessions) {
+    if (s.messageCount <= 0 && !s.hasMessages) continue; // skip empty (message_count can lag; trust real messages)
+    const src = s.source ?? "unknown";
+    latestBySource.set(src, Math.max(latestBySource.get(src) ?? 0, s.mtimeMs));
+  }
+  const out: ProjectFolder[] = [];
+  for (const [src, latest] of latestBySource) {
+    const lastModified = new Date(latest);
+    out.push({
+      name: `hermes-${src}`,
+      path: `hermes:${src}`,
+      isDirectory: true,
+      lastModified,
+      lastModifiedFormatted: formatDate(lastModified),
+      cli: ["hermes"],
+    });
+  }
+  out.sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  return out;
+}
+
+export interface HermesProjectByName {
+  cwd: string | null;
+  sessions: SessionFile[];
+}
+
+/**
+ * Resolve the Hermes sessions for a synthetic project name (`hermes-<source>`),
+ * for the project-detail page. Non-Hermes names resolve to empty.
+ */
+export async function getHermesSessionsByEncodedName(
+  name: string,
+): Promise<HermesProjectByName> {
+  if (!name.startsWith("hermes-")) return { cwd: null, sessions: [] };
+  const source = name.slice("hermes-".length);
+  const sessions = await getHermesSessions();
+  const matched = sessions.filter((s) => (s.messageCount > 0 || s.hasMessages) && (s.source ?? "unknown") === source);
+  return {
+    cwd: `hermes:${source}`,
+    sessions: matched.map((s) => {
+      const lastModified = new Date(s.mtimeMs);
+      return {
+        name: s.title ?? s.sessionId,
+        path: `hermes://${s.sessionId}`,
+        lastModified,
+        lastModifiedFormatted: formatDate(lastModified),
+        sessionId: s.sessionId,
+        cli: "hermes" as const,
+        userId: s.userId,
+        channelId: s.chatId,
+        channelType: s.chatType,
+      };
+    }),
+  };
+}
+
+export const getCachedHermesProjects = runtimeCache(getHermesProjects, 2);
+export const getCachedHermesSessionsByEncodedName = runtimeCache(
+  (name: string) => getHermesSessionsByEncodedName(name),
+  2,
+  { maxSize: 50 },
+);

package/lib/hermes-sessions.ts

@@ -0,0 +1,273 @@
+/**
+ * Hermes (hermes-agent) session transcript loader + parser.
+ *
+ * AUDIT-ONLY (Pillar 2). Hermes stores every gateway user's sessions in one
+ * SQLite DB (`~/.hermes/state.db`). We read it DIRECTLY via the bundled sql.js
+ * driver (lib/sqlite-reader.ts) — a reusable path for SQLite-backed agents.
+ * (opencode and the already-shipped CLIs keep their CLI shell-out unchanged.)
+ *
+ * Message shape is OpenAI Chat-Completions style (verified live): assistant tool
+ * calls are `tool_calls[].function.{name, arguments}` (stored as a JSON string
+ * column) and results are separate `role:"tool"` rows keyed by `tool_call_id`.
+ * `hermesRowsToLogEntries` pairs them (mirrors `lib/codex-sessions.ts`) and is a
+ * PURE function of the message rows, so it is unit-testable without a DB.
+ *
+ * DB path override: set `HERMES_DB_PATH` (used by tests and to point at a copied
+ * or remote state.db).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { openSqliteReadonly } from "./sqlite-reader";
+import { runtimeCache } from "./runtime-cache";
+import {
+  baseEntry,
+  formatTimestamp,
+  type LogEntry,
+  type UserEntry,
+  type AssistantEntry,
+  type GenericEntry,
+  type ContentBlock,
+  type ToolUseBlock,
+  type LogSource,
+} from "./log-entries";
+import { formatDuration } from "./format-duration";
+
+/** Absolute path to Hermes's SQLite DB (override with HERMES_DB_PATH). */
+export function hermesDbPath(): string {
+  return process.env.HERMES_DB_PATH || join(homedir(), ".hermes", "state.db");
+}
+
+/** Coerce a Hermes epoch value (seconds or ms) to epoch ms. Hermes stores
+ *  `started_at`/`ended_at`/`timestamp` as REAL epoch seconds. */
+export function epochToMs(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (value > 1e12) return value; // already ms
+    if (value > 1e9) return value * 1000; // seconds
+  }
+  return Date.now();
+}
+
+// ── Parsing helpers ──
+
+function safeJsonParse(s: unknown): unknown {
+  if (typeof s !== "string" || s.length === 0) return undefined;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return undefined;
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Text from a `content` field that may be a string or an array of
+ *  `{ type:"text", text }` blocks. */
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (isPlainObject(c) && typeof c.text === "string" ? (c.text as string) : ""))
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}
+
+function toDate(value: unknown, fallbackMs: number): Date {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (value > 1e12) return new Date(value);
+    if (value > 1e9) return new Date(value * 1000);
+  }
+  if (typeof value === "string") {
+    const ms = Date.parse(value);
+    if (!Number.isNaN(ms)) return new Date(ms);
+  }
+  return new Date(fallbackMs);
+}
+
+interface NormalizedToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+/** Normalize `tool_calls` (array, or the JSON-string column Hermes stores) into
+ *  `{ id, name, input }[]`. OpenAI shape: `{ id|call_id, function:{ name,
+ *  arguments } }` where `arguments` is itself a JSON string. */
+function normalizeToolCalls(raw: unknown): NormalizedToolCall[] {
+  const arr = Array.isArray(raw) ? raw : safeJsonParse(raw);
+  if (!Array.isArray(arr)) return [];
+  const out: NormalizedToolCall[] = [];
+  for (const tc of arr) {
+    if (!isPlainObject(tc)) continue;
+    const fn = isPlainObject(tc.function) ? tc.function : {};
+    const name =
+      typeof fn.name === "string"
+        ? fn.name
+        : typeof tc.name === "string"
+          ? (tc.name as string)
+          : "tool";
+    const id =
+      (typeof tc.id === "string" && tc.id) ||
+      (typeof tc.call_id === "string" && tc.call_id) ||
+      `${name}-${out.length}`;
+    const parsedArgs = isPlainObject(fn.arguments) ? fn.arguments : safeJsonParse(fn.arguments);
+    out.push({ id, name, input: isPlainObject(parsedArgs) ? parsedArgs : {} });
+  }
+  return out;
+}
+
+// ── Pure parser: message rows → LogEntry[] ──
+
+/**
+ * Convert `messages`-table rows (ordered by timestamp) into `LogEntry[]`.
+ * Pairs each assistant `tool_calls` entry with its later `role:"tool"` result
+ * by `tool_call_id`. Roles other than user/assistant/tool (e.g. Hermes's
+ * `session_meta`) become generic system entries so nothing is dropped. Pure —
+ * unit-testable with plain row objects.
+ */
+export function hermesRowsToLogEntries(
+  rows: Record<string, unknown>[],
+  source: LogSource = "session",
+): LogEntry[] {
+  const entries: LogEntry[] = [];
+  const toolUseById = new Map<string, ToolUseBlock>();
+  const toolUseStartMs = new Map<string, number>();
+  const baseMs = Date.now();
+
+  for (let i = 0; i < rows.length; i++) {
+    const m = rows[i];
+    if (!isPlainObject(m)) continue;
+
+    const role = typeof m.role === "string" ? m.role : "system";
+    const date = toDate(m.timestamp ?? m.time_created, baseMs + i);
+    const timestamp = date.toISOString();
+    const raw: Record<string, unknown> = {
+      uuid: m.id != null ? String(m.id) : `hermes-${i}`,
+      parentUuid: null,
+    };
+    const base = baseEntry(raw, timestamp, date, source);
+
+    if (role === "user") {
+      entries.push({
+        type: "user",
+        ...base,
+        message: { role: "user", content: extractText(m.content) },
+      } satisfies UserEntry);
+      continue;
+    }
+
+    if (role === "assistant") {
+      const blocks: ContentBlock[] = [];
+      const text = extractText(m.content);
+      if (text) blocks.push({ type: "text", text });
+      for (const tc of normalizeToolCalls(m.tool_calls)) {
+        const block: ToolUseBlock = { type: "tool_use", id: tc.id, name: tc.name, input: tc.input };
+        blocks.push(block);
+        toolUseById.set(tc.id, block);
+        toolUseStartMs.set(tc.id, date.getTime());
+      }
+      if (blocks.length === 0) continue; // empty assistant turn
+      entries.push({
+        type: "assistant",
+        ...base,
+        message: { role: "assistant", content: blocks },
+      } satisfies AssistantEntry);
+      continue;
+    }
+
+    if (role === "tool") {
+      const callId = typeof m.tool_call_id === "string" ? m.tool_call_id : undefined;
+      const block = callId ? toolUseById.get(callId) : undefined;
+      if (block) {
+        const startMs = (callId && toolUseStartMs.get(callId)) || date.getTime();
+        const durationMs = Math.max(0, date.getTime() - startMs);
+        block.result = {
+          timestamp,
+          timestampFormatted: formatTimestamp(date),
+          content: extractText(m.content),
+          durationMs,
+          durationFormatted: formatDuration(durationMs),
+        };
+        continue;
+      }
+      // Orphan tool result — fall through to a system entry.
+    }
+
+    entries.push({ type: "system", ...base, raw } satisfies GenericEntry);
+  }
+
+  entries.sort((a, b) => a.timestampMs - b.timestampMs);
+  return entries;
+}
+
+// ── DB loader ──
+
+export interface HermesSessionLogData {
+  entries: LogEntry[];
+  rawLines: Record<string, unknown>[];
+  cwd?: string;
+  filePath: string; // synthetic — hermes keeps sessions in a DB; we use hermes://<id>
+}
+
+interface HermesMessageRow {
+  id: number | null;
+  role: string | null;
+  content: string | null;
+  tool_call_id: string | null;
+  tool_calls: string | null;
+  tool_name: string | null;
+  timestamp: number | null;
+}
+
+/**
+ * Load one session by ID from `state.db`. Returns `null` when the DB is
+ * unavailable or the session doesn't exist.
+ */
+export async function getHermesSessionLog(
+  sessionId: string,
+): Promise<HermesSessionLogData | null> {
+  if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId)) return null;
+  const db = await openSqliteReadonly(hermesDbPath());
+  if (!db) return null;
+  try {
+    const sessionRows = db.query<{ source: string | null; cwd: string | null }>(
+      "SELECT source, cwd FROM sessions WHERE id = ?",
+      [sessionId],
+    );
+    if (sessionRows.length === 0) return null;
+    const { source, cwd: realCwd } = sessionRows[0];
+
+    const msgRows = db.query<HermesMessageRow>(
+      "SELECT id, role, content, tool_call_id, tool_calls, tool_name, timestamp " +
+        "FROM messages WHERE session_id = ? ORDER BY timestamp ASC",
+      [sessionId],
+    );
+
+    const entries = hermesRowsToLogEntries(
+      msgRows as unknown as Record<string, unknown>[],
+      "session",
+    );
+    // Gateway sessions have no cwd → group by source (slack/telegram/cli/cron).
+    const cwd =
+      realCwd && realCwd.length > 0 ? realCwd : source ? `hermes:${source}` : undefined;
+    return {
+      entries,
+      rawLines: msgRows as unknown as Record<string, unknown>[],
+      cwd,
+      filePath: `hermes://${sessionId}`,
+    };
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+export const getCachedHermesSessionLog = runtimeCache(
+  (sessionId: string) => getHermesSessionLog(sessionId),
+  2,
+  { maxSize: 50 },
+);

package/lib/projects.ts

@@ -16,7 +16,7 @@ import { formatDate } from "./format-date";
 export const UUID_RE = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 export const PATH_TRAVERSAL_RE = /(^|[\\/])\.\.($|[\\/])/;
 
-export type ProjectCli = "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" | "gemini";
+export type ProjectCli = "claude" | "codex" | "copilot" | "cursor" | "opencode" | "pi" | "gemini" | "hermes";
 
 export interface ProjectFolder {
   name: string;
@@ -40,6 +40,11 @@ export interface SessionFile {
   /** Originating agent CLI. Set when the session list mixes sources from more
    *  than one CLI, so the table can render a per-row CLI badge. */
   cli?: ProjectCli;
+  /** Gateway session metadata (Hermes only today): who drove it and where.
+   *  Other CLIs leave these undefined; the list renders them only when present. */
+  userId?: string;
+  channelId?: string;
+  channelType?: string; // e.g. "group" | "dm"
 }
 
 /** Stats a path and returns mtime. Falls back to epoch (1970-01-01) on error
@@ -139,6 +144,7 @@ export async function getProjectFolders(): Promise<ProjectFolder[]> {
     { getOpenCodeProjects },
     { getPiProjects },
     { getGeminiProjects },
+    { getHermesProjects },
   ] = await Promise.all([
     import("./codex-projects"),
     import("./copilot-projects"),
@@ -146,8 +152,9 @@ export async function getProjectFolders(): Promise<ProjectFolder[]> {
     import("./opencode-projects"),
     import("./pi-projects"),
     import("./gemini-projects"),
+    import("./hermes-projects"),
   ]);
-  const [claude, codex, copilot, cursor, opencode, pi, gemini] = await Promise.all([
+  const [claude, codex, copilot, cursor, opencode, pi, gemini, hermes] = await Promise.all([
     getClaudeProjectFolders(),
     getCodexProjects().catch((error) => {
       logError("Error reading Codex projects:", error);
@@ -173,8 +180,12 @@ export async function getProjectFolders(): Promise<ProjectFolder[]> {
       logError("Error reading Gemini projects:", error);
       return [] as ProjectFolder[];
     }),
+    getHermesProjects().catch((error) => {
+      logError("Error reading Hermes projects:", error);
+      return [] as ProjectFolder[];
+    }),
   ]);
-  return mergeProjectFolders(claude, codex, copilot, cursor, opencode, pi, gemini);
+  return mergeProjectFolders(claude, codex, copilot, cursor, opencode, pi, gemini, hermes);
 }
 
 /**

package/lib/sql-js-asm.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal ambient types for the pure-JS (asm.js) build of sql.js, which we
+ * import by subpath (`sql.js/dist/sql-asm.js`) so there is no `.wasm` to ship or
+ * locate. We only use a small read-only slice of the API.
+ */
+declare module "sql.js/dist/sql-asm.js" {
+  export interface SqlJsStatement {
+    bind(params?: unknown[]): boolean;
+    step(): boolean;
+    getAsObject(): Record<string, unknown>;
+    free(): boolean;
+  }
+  export interface SqlJsDatabase {
+    prepare(sql: string): SqlJsStatement;
+    run(sql: string, params?: unknown[]): void;
+    export(): Uint8Array;
+    close(): void;
+  }
+  export interface SqlJsStatic {
+    Database: new (data?: Uint8Array | null) => SqlJsDatabase;
+  }
+  export interface InitSqlJsConfig {
+    locateFile?: (file: string) => string;
+  }
+  export default function initSqlJs(config?: InitSqlJsConfig): Promise<SqlJsStatic>;
+}

package/lib/sqlite-reader.ts

@@ -0,0 +1,102 @@
+/**
+ * Reusable read-only SQLite access for audit adapters of SQLite-backed agents.
+ *
+ * Tiered so we read LIVE data (including the write-ahead log) wherever possible,
+ * and still run anywhere:
+ *   1. `node:sqlite` — a real connection that reads main DB + WAL together, so
+ *      brand-new rows are visible immediately. Built into Node ≥ 22.5 (no native
+ *      module, no flag on recent 22.x). Preferred.
+ *   2. `sql.js` (pure-JS/asm) — portable fallback for older Node. Reads the main
+ *      DB file's bytes only, so it reflects a snapshot up to the last WAL
+ *      checkpoint (very recent rows may lag). No native module — survives
+ *      `npm install --ignore-scripts`.
+ *
+ * Either way: read-only, and `null` on any failure (fail-open, so an absent or
+ * locked DB makes the audit skip that agent rather than crash).
+ *
+ * NOTE: opencode and every CLI that already ships keep their existing CLI
+ * shell-out — this layer is only for new SQLite integrations.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import initSqlJs, { type SqlJsStatic } from "sql.js/dist/sql-asm.js";
+
+export interface SqliteReader {
+  /** Run a parameterized read-only query; returns rows as plain objects. */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  close(): void;
+}
+
+// ── Tier 1: node:sqlite (WAL-aware, Node ≥ 22.5) ──
+
+interface NodeSqliteStmt {
+  all(...params: unknown[]): Record<string, unknown>[];
+}
+interface NodeSqliteDb {
+  prepare(sql: string): NodeSqliteStmt;
+  close(): void;
+}
+interface NodeSqliteModule {
+  DatabaseSync: new (path: string, options?: { readOnly?: boolean }) => NodeSqliteDb;
+}
+
+async function tryNodeSqlite(dbPath: string): Promise<SqliteReader | null> {
+  try {
+    // Dynamic import: on Node < 22.5 this rejects and we fall through to sql.js.
+    const mod = (await import("node:sqlite")) as unknown as NodeSqliteModule;
+    const db = new mod.DatabaseSync(dbPath, { readOnly: true });
+    return {
+      query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): T[] {
+        const stmt = db.prepare(sql);
+        return (params.length ? stmt.all(...params) : stmt.all()) as T[];
+      },
+      close() {
+        db.close();
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ── Tier 2: sql.js (portable snapshot) ──
+
+let sqlPromise: Promise<SqlJsStatic> | null = null;
+function loadSqlJs(): Promise<SqlJsStatic> {
+  if (!sqlPromise) sqlPromise = initSqlJs();
+  return sqlPromise;
+}
+
+async function trySqlJs(dbPath: string): Promise<SqliteReader | null> {
+  try {
+    const SQL = await loadSqlJs();
+    const db = new SQL.Database(readFileSync(dbPath));
+    return {
+      query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
+        const stmt = db.prepare(sql);
+        try {
+          if (params && params.length) stmt.bind(params);
+          const rows: T[] = [];
+          while (stmt.step()) rows.push(stmt.getAsObject() as T);
+          return rows;
+        } finally {
+          stmt.free();
+        }
+      },
+      close() {
+        db.close();
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Open a SQLite database file READ-ONLY. Prefers a WAL-aware `node:sqlite`
+ * connection (live data), falls back to a `sql.js` snapshot. Returns `null` on
+ * any failure. Always `close()` the reader when done.
+ */
+export async function openSqliteReadonly(dbPath: string): Promise<SqliteReader | null> {
+  if (!existsSync(dbPath)) return null;
+  return (await tryNodeSqlite(dbPath)) ?? (await trySqlJs(dbPath));
+}