The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
refactor: introduce sqliteRead and AttachTracker modules to unify SQLite querying and manage concurrent session attachments
0xken15d40ebd7a33ab
diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex e73eeb185..1e85183db 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -32,6 +32,7 @@ import { homedir, hostname } from 'os'import { env } from './config/env.js'import { VERSION } from './version.js'import { sqlitePreflightMessage } from './lib/sqliteAvailability.js'+import { AttachTracker, forEachBounded } from './lib/attachTracker.js'import { binaryOnPath } from './lib/binaryOnPath.js'import { warmLoginShellEnvironment } from './lib/loginShellEnv.js'import { ensureUtf8Locale } from './lib/childLocale.js'@@ -286,6 +287,8 @@ const KILO_DB = join(env.KILO_DATA_DIR, 'kilo.db')const HERMES_DB = join(env.HERMES_HOME, 'state.db')// Devin likewise keeps all history in one SQLite store (WAL) — polled per session by DevinReader.const DEVIN_DB = join(env.DEVIN_HOME, 'sessions.db')+/** How many agents' histories a daemon boot reads at once — see hydrateOnBoot. */+const BOOT_ATTACH_CONCURRENCY = 4// How long a control-plane call the daemon proxies for a local client (`/api/machines`, `/api/auth/me`)// may wait on the backend. Under the desktop app's own 30s receive timeout, so a slow backend is@@ -1893,7 +1896,7 @@ async function runForeground(session: AuthSession): Promise<void> {})})- const attachSession = async (+ const attachSessionNow = async (session: RegisteredSession,reset = false,replayCursorFromStart = false,@@ -2143,6 +2146,20 @@ async function runForeground(session: AuthSession): Promise<void> {if (pollsQuestions(session.engine)) questionWatcher.start(session.sessionId)return true}++ /** One attach per session at a time, and a record of what is being read — see lib/attachTracker. */+ const attaches = new AttachTracker<AgentEngine>({+ onSlow: (session, elapsedMs) => console.warn(+ `[agent] ${sid(session.agentId)} attach still running · engine=${session.engine} · session=${sid(session.sessionId)} · ${Math.round(elapsedMs / 1000)}s`,+ ),+ })+ const attachSession = (+ session: RegisteredSession,+ reset = false,+ replayCursorFromStart = false,+ replayFromStart = false,+ ): Promise<boolean> =>+ attaches.attach(session, reset, () => attachSessionNow(session, reset, replayCursorFromStart, replayFromStart))const input = new SessionInputController({getSession: (id) => registry.resolve(id),onDelivery: (event) => {@@ -2933,12 +2950,24 @@ async function runForeground(session: AuthSession): Promise<void> {if (wasDormant || wasLaunching || adopted) {const active = registry.byAgent(current.agentId)if (!active) return- if (active.sessionId && !await attachSession(active)) {- registry.setActive(active.agentId, false)+ if (!active.sessionId) {+ syncRecapPool()+ announceSession(active)return}- syncRecapPool()- announceSession(active)+ // Not awaited: the attach reads this agent's whole history, and this callback runs inside the+ // reconcile pass whose completion is what publishes `discoveryReady`. One agent's slow store+ // must not hold the pass — or, at boot, the app — see the boot hydration below for the same rule.+ void attachSession(active).then((attached) => {+ if (!attached) {+ registry.setActive(active.agentId, false)+ return+ }+ syncRecapPool()+ announceSession(active)+ }).catch((err) => {+ console.error(`[discovery] ${sid(active.agentId)} attach failed:`, err instanceof Error ? err.message : err)+ })return}// An agent that was already awake changed grid under us. Nobody was told: this branch wrote the@@ -3449,6 +3478,9 @@ async function runForeground(session: AuthSession): Promise<void> {restarting,discoveryReady,discoveryError,+ // Agents whose history is being read right now (see hydrateOnBoot). Normally empty or gone in a+ // second; one that stays here names the store that is slow, which no other field does.+ attaching: attaches.attaching(),fingerprint: backend.e2eeFingerprint(),config: {watching: `${terminalConfig.backends.join(' + ')} terminals across all supported engines`,@@ -3872,16 +3904,46 @@ async function runForeground(session: AuthSession): Promise<void> {console.error(`[cli] history handler error (session ${batch.sessionId}):`, err instanceof Error ? err.message : err)}})- for (const session of registry.list()) {- // An UNBOUND process agent has no transcript to attach to yet. Discovery keeps it visible and the- // hook/store repair path binds it as soon as the engine reports a session. Attaching an- // empty session id here would tear down an agent the user can see running in their pane, which is- // exactly what a self-update restart must never do.- if (!session.active || !session.sessionId) continue- if (!await attachSession(session)) registry.setActive(session.agentId, false)- else {- input.setTurnOpen(session.agentId, sessionTurnOpen(session.sessionId))- }+ /**+ * Re-attach every agent the registry kept — in the BACKGROUND, a few at a time.+ *+ * An attach reads the agent's whole history (the transcript to EOF, or every row of its SQLite+ * session) to rebuild the live normalizer's state. It used to run here as an awaited loop, one agent+ * after another, before the first reconcile pass — so the daemon reported `discoveryReady:false`,+ * and the desktop app sat on "still scanning for agents", until the LAST agent's history had been+ * read. One agent was enough to hold every other: measured, an opencode session whose store the+ * `sqlite3` CLI never finished reading kept a machine's app out of every agent it had, for good.+ *+ * What the app needs at ready is the registry (which agents, on which panes), and that is already+ * authoritative. What the attach produces is per-agent: its own live stream, its own open-turn+ * replay, its own chips. So readiness no longer waits for it, and a slow or stuck read costs that+ * one agent its history — visible in `/api/status` as `attaching`, and in the log after 15s — never+ * the app. A pane that turns out dead is put dormant when its attach says so, which is also what the+ * reconcile pass would do on its own.+ *+ * Bounded, not unbounded: four at a time keeps the disk and the engines' stores from being hit by+ * every session at once on a machine with many, and still means one slow one delays at most the+ * three behind it rather than all of them. Called after restore has put every pane back (below), so+ * the pane an attach validates is the one the agent will keep.+ *+ * An UNBOUND process agent has no transcript to attach to yet. Discovery keeps it visible and the+ * hook/store repair path binds it as soon as the engine reports a session. Attaching an empty+ * session id here would tear down an agent the user can see running in their pane, which is exactly+ * what a self-update restart must never do.+ */+ const hydrateOnBoot = async (): Promise<void> => {+ const sessions = registry.list().filter((session) => session.active && session.sessionId)+ if (!sessions.length) return+ const startedAt = Date.now()+ await forEachBounded(sessions, BOOT_ATTACH_CONCURRENCY, async (session) => {+ try {+ if (!await attachSession(session)) registry.setActive(session.agentId, false)+ else input.setTurnOpen(session.agentId, sessionTurnOpen(session.sessionId))+ } catch (err) {+ console.error(`[agent] ${sid(session.agentId)} attach failed:`, err instanceof Error ? err.message : err)+ }+ })+ console.log(`[agent] re-attached ${sessions.length} agent(s) · ${Date.now() - startedAt}ms`)}/*** What the launch builder needs to know about THIS machine, read at launch time.@@ -4034,6 +4096,10 @@ async function runForeground(session: AuthSession): Promise<void> {// Every DSH agent the registry kept gets its viewer and verdict watch back — restored or not, an// agent whose pane is still up is still that harness.for (const session of registry.list()) if (session.dsh) attachDsh(session)+ // After restore, deliberately: an attach validates the pane it finds, and one that looked at a dead+ // pane a moment before restore rebuilt it would put the restored agent dormant on its way out. Not+ // awaited, also deliberately — see hydrateOnBoot.+ void hydrateOnBoot()await agentReconciler.start(env.TERMINAL_RECONCILE_INTERVAL_MS ?? env.TMUX_REAP_INTERVAL_MS)for (const task of await loadCursorPendingTasks(env.ADAPTER_DATA_DIR)) {onCursorTaskStart(task.sessionId, task.toolUseId, task.input)diff --git a/cli/src/engines/devin/reader.ts b/cli/src/engines/devin/reader.tsindex fbf689771..0229e8b1a 100644--- a/cli/src/engines/devin/reader.ts+++ b/cli/src/engines/devin/reader.ts@@ -3,29 +3,26 @@** Devin keeps every session's history in ONE SQLite store (`<DEVIN_HOME>/sessions.db`, WAL) and writes no* transcript file unless the user passes `--export`, so there is nothing to byte-offset-tail. This polls- * the DB every ~1s through the `sqlite3` CLI (shelled out, like tmux/git — keeps the adapter's single- * pure-JS bundle; no native SQLite dependency) and feeds the same `emitSessionEvents` funnel the- * file-based engines use. Same shape as the opencode/hermes readers.+ * the DB every ~1s (through `lib/sqliteRead`: `node:sqlite` in-process, or the `sqlite3` CLI on a+ * Node without it) and feeds the same `emitSessionEvents` funnel the file-based engines use. Same+ * shape as the opencode/hermes readers.** Two Devin specifics:- * - **The store is WAL.** The DB must be read IN PLACE (`file:…?mode=ro`), never from a copy of+ * - **The store is WAL.** The DB must be read IN PLACE (read-only, at its own path), never from a copy of* `sessions.db` alone — a copy misses everything still in `-wal` (an in-flight session looks empty).* - **Rows repeat.** `message_nodes` is a forest and Devin re-persists the whole chain per inference, so* `row_id` alone is not a safe cursor. `row_id` drives the incremental read, `message_id` deduplicates:* 29 raw rows collapsed to 6 real messages in the captured session.*/-import { execFile } from 'child_process'-import { promisify } from 'util'import type { LiveEvent, TurnState } from '../../lib/normalize.js'import { newTurnState } from '../../lib/normalize.js'+import { sqliteReadAll } from '../../lib/sqliteRead.js'import { devinMessageToEvents, type DvMessage } from './normalizer.js'import { DevinErrorTail } from './errorLog.js'-const execFileAsync = promisify(execFile)--// Devin session ids are lowercase word slugs (`blue-agustinia`, `classy-tourmaline`). Strict, because the-// id is interpolated into SQL.+// Devin session ids are lowercase word slugs (`blue-agustinia`, `classy-tourmaline`). Strict: the id is+// also a registry key and a log-file name.const SESSION_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/const MAX_SESSION_ID_LEN = 64const POLL_MS = 1_000@@ -44,7 +41,7 @@ const COLUMNS = [].join(', ')export class DevinSqliteMissing extends Error {- constructor() { super('sqlite3 CLI not found on PATH — Devin sessions cannot be mirrored') }+ constructor() { super('no SQLite reader (node:sqlite absent and no sqlite3 CLI on PATH) — Devin sessions cannot be mirrored') }}function str(value: unknown): string | null {@@ -58,7 +55,7 @@ export function isDevinSessionId(sessionId: string): boolean {/*** Read a Devin session's messages, optionally only those after `afterRowId`, deduped by `message_id`* (first occurrence wins) and with the system prefix dropped.- * Throws `DevinSqliteMissing` when the `sqlite3` binary is absent; returns [] on a transient error.+ * Throws `DevinSqliteMissing` when this machine has no way to read SQLite; returns [] on a transient error.*/export async function readDevinMessages(dbPath: string,@@ -66,30 +63,17 @@ export async function readDevinMessages(afterRowId?: number | null,): Promise<DvMessage[]> {if (!isDevinSessionId(sessionId)) return []- const after = Number.isFinite(afterRowId as number) && (afterRowId as number) > 0- ? ` AND row_id > ${Math.trunc(afterRowId as number)}`- : ''- const sql = `SELECT ${COLUMNS} FROM message_nodes WHERE session_id = '${sessionId}'${after}`+ const bounded = Number.isFinite(afterRowId as number) && (afterRowId as number) > 0+ const sql = `SELECT ${COLUMNS} FROM message_nodes WHERE session_id = ?${bounded ? ' AND row_id > ?' : ''}`+ " AND json_extract(chat_message, '$.role') <> 'system' ORDER BY row_id;"+ const params = bounded ? [sessionId, Math.trunc(afterRowId as number)] : [sessionId]- let stdout: string- try {- // `.timeout` is the SILENT dot-command form — `PRAGMA busy_timeout=…` prints a row under -json and- // would corrupt the single-array parse below. `query_only` is silent and guards against writes.- ;({ stdout } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', `file:${dbPath}?mode=ro`, sql],- { maxBuffer: MAX_BUFFER },- ))- } catch (err) {- if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') throw new DevinSqliteMissing()+ const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: MAX_BUFFER })+ if (!result.ok) {+ if (result.reason === 'missing') throw new DevinSqliteMissing()return [] // db locked / mid-write — retry next tick}-- const trimmed = stdout.trim()- if (!trimmed) return []- let rows: Array<Record<string, unknown>>- try { rows = JSON.parse(trimmed) } catch { return [] }+ const rows = result.rowsconst seen = new Set<string>()const out: DvMessage[] = []@@ -123,7 +107,7 @@ export interface DevinReaderDeps {* without it the turn never closes and the web spins forever.*/onTurnAborted?: (message: string) => void- /** Reports the one-time fatal "sqlite3 missing" so the caller can warn + stop the reader. */+ /** Reports the one-time fatal "no SQLite reader" so the caller can warn + stop the reader. */onFatal?: (err: Error) => voidpollMs?: number}diff --git a/cli/src/engines/hermes/reader.ts b/cli/src/engines/hermes/reader.tsindex 7a64c0c40..9a9ff4b13 100644--- a/cli/src/engines/hermes/reader.ts+++ b/cli/src/engines/hermes/reader.ts@@ -2,25 +2,22 @@* Hermes live tailer.** Hermes keeps every surface's history in ONE SQLite store (`<HERMES_HOME>/state.db`, WAL), so there is- * no file to byte-offset-tail. This polls the DB every ~1s through the `sqlite3` CLI (shelled out, like- * tmux/git — keeps the adapter's single pure-JS bundle; no native SQLite dependency) and feeds the same- * `emitSessionEvents` funnel the file-based engines use.+ * no file to byte-offset-tail. This polls the DB every ~1s (through `lib/sqliteRead`: `node:sqlite`+ * in-process, or the `sqlite3` CLI on a Node without it) and feeds the same `emitSessionEvents`+ * funnel the file-based engines use.** `messages.id` is an INTEGER primary key, which makes the incremental cursor trivial (`id > lastSeen`).* The connection is opened READ-ONLY: Hermes retries writes ~15 times on contention, and a long-held* reader would eat into that budget.*/-import { execFile } from 'child_process'-import { promisify } from 'util'import type { LiveEvent } from '../../lib/normalize.js'+import { sqliteReadAll } from '../../lib/sqliteRead.js'import {messageToEvents, newHermesTurnState, isTerminalFinish,type HermesTurnState, type HmMessage,} from './normalizer.js'-const execFileAsync = promisify(execFile)-// `YYYYMMDD_HHMMSS_<hex>` — CLI/TUI use 6 hex chars, the gateway 8.const SESSION_ID_RE = /^[0-9]{8}_[0-9]{6}_[0-9a-fA-F]{4,16}$/const POLL_MS = 1_000@@ -30,7 +27,7 @@ const COLUMNS ='id, role, coalesce(content, \'\') AS content, tool_call_id, tool_calls, tool_name, finish_reason, reasoning'export class HermesSqliteMissing extends Error {- constructor() { super('sqlite3 CLI not found on PATH — Hermes sessions cannot be mirrored') }+ constructor() { super('no SQLite reader (node:sqlite absent and no sqlite3 CLI on PATH) — Hermes sessions cannot be mirrored') }}function str(value: unknown): string | null {@@ -39,7 +36,7 @@ function str(value: unknown): string | null {/*** Read a Hermes session's messages, optionally only those after `afterId`.- * Throws `HermesSqliteMissing` when the `sqlite3` binary is absent; returns [] on a transient error.+ * Throws `HermesSqliteMissing` when this machine has no way to read SQLite; returns [] on a transient error.*/export async function readHermesMessages(dbPath: string,@@ -47,29 +44,17 @@ export async function readHermesMessages(afterId?: number | null,): Promise<HmMessage[]> {if (!SESSION_ID_RE.test(sessionId)) return []- const after = Number.isFinite(afterId as number) && (afterId as number) > 0 ? ` AND id > ${Math.trunc(afterId as number)}` : ''- const sql = `SELECT ${COLUMNS} FROM messages WHERE session_id = '${sessionId}'${after} ORDER BY id;`-- let stdout: string- try {- // `.timeout` is the SILENT dot-command form — `PRAGMA busy_timeout=…` prints a row under -json and- // would corrupt the single-array parse below. `query_only` is silent and guards against writes.- ;({ stdout } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', `file:${dbPath}?mode=ro`, sql],- { maxBuffer: MAX_BUFFER },- ))- } catch (err) {- if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') throw new HermesSqliteMissing()+ const bounded = Number.isFinite(afterId as number) && (afterId as number) > 0+ const sql = `SELECT ${COLUMNS} FROM messages WHERE session_id = ?${bounded ? ' AND id > ?' : ''} ORDER BY id;`+ const params = bounded ? [sessionId, Math.trunc(afterId as number)] : [sessionId]++ const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: MAX_BUFFER })+ if (!result.ok) {+ if (result.reason === 'missing') throw new HermesSqliteMissing()return [] // db locked / mid-write — retry next tick}- const trimmed = stdout.trim()- if (!trimmed) return []- let rows: Array<Record<string, unknown>>- try { rows = JSON.parse(trimmed) } catch { return [] }-- return rows.map((row) => ({+ return result.rows.map((row) => ({id: Number(row.id) || 0,role: typeof row.role === 'string' ? row.role : '',content: typeof row.content === 'string' ? row.content : '',@@ -103,34 +88,23 @@ export async function isHermesSubagentSession(dbPath: string, sessionId: string)* inserted its row, so an immediate lookup said "not a sub-agent" and the child took over the pane.* Callers that can afford to wait should treat null as "ask again shortly".*- * Async, like every other query against this store: `.timeout 3000` means a contended read can park for- * seconds, and hermes writes to this DB constantly — a synchronous spawn here would freeze the whole- * daemon (every engine's poll, every socket, the device stream) for as long as the lock is held.+ * Read through `lib/sqliteRead` like every other query against this store: hermes writes to this DB+ * constantly, and the read's busy wait is bounded there so a contended lookup cannot park the daemon.*/export async function hermesSessionSource(dbPath: string, sessionId: string): Promise<string | null> {if (!SESSION_ID_RE.test(sessionId)) return ''- try {- const { stdout: raw } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', `file:${dbPath}?mode=ro`,- `SELECT source FROM sessions WHERE id = '${sessionId}';`],- { maxBuffer: 1 << 20, timeout: 5_000 },- )- const stdout = raw.trim()- if (!stdout) return null- const rows = JSON.parse(stdout) as Array<{ source?: unknown }>- if (rows.length === 0) return null- return typeof rows[0]?.source === 'string' ? rows[0].source : ''- } catch {- return '' // sqlite3 missing / db locked — treat as a normal session, exactly as before- }+ const result = await sqliteReadAll(dbPath, 'SELECT source FROM sessions WHERE id = ?;', [sessionId], { maxBuffer: 1 << 20 })+ if (!result.ok) return '' // no reader / db locked — treat as a normal session, exactly as before+ if (result.rows.length === 0) return null+ const source = result.rows[0]?.source+ return typeof source === 'string' ? source : ''}export interface HermesReaderDeps {dbPath: stringsessionId: stringonEvents: (events: LiveEvent[]) => void- /** Reports the one-time fatal "sqlite3 missing" so the caller can warn + stop the reader. */+ /** Reports the one-time fatal "no SQLite reader" so the caller can warn + stop the reader. */onFatal?: (err: Error) => voidpollMs?: number}diff --git a/cli/src/engines/kilo/reader.ts b/cli/src/engines/kilo/reader.tsindex 11cbbe9ec..a57901e16 100644--- a/cli/src/engines/kilo/reader.ts+++ b/cli/src/engines/kilo/reader.ts@@ -2,10 +2,10 @@* Kilo live tailer.** Kilo has no per-session transcript file — it writes `message`/`part` rows to a SQLite DB. We- * cannot byte-offset-tail it, so this reader **polls** the DB every ~1s via the `sqlite3` CLI (shelled- * out, like tmux/git — keeps the adapter's single pure-JS bundle intact; no native SQLite dependency)- * and diffs against per-part state to emit incremental `LiveEvent`s into the same- * `emitSessionEvents` funnel the file-based engines use.+ * cannot byte-offset-tail it, so this reader **polls** the DB every ~1s (through `lib/sqliteRead`:+ * `node:sqlite` in-process, or the `sqlite3` CLI on a Node without it) and diffs against per-part+ * state to emit incremental `LiveEvent`s into the same `emitSessionEvents` funnel the file-based+ * engines use.** Measured on kilo 7.4.20: the conversation is written to the legacy `message`/`part` tables, so those* are the primary cursor. Unlike opencode's store, kilo's `session_message` table is NOT empty — it held@@ -14,9 +14,8 @@* reach for it as an ordering key if that ever looks tempting.*/-import { execFile } from 'child_process'-import { promisify } from 'util'import type { LiveEvent } from '../../lib/normalize.js'+import { sqliteReadAll } from '../../lib/sqliteRead.js'import {MAX_OUTPUT, MAX_THINKING, clip, object, str,kiloToolName, toolOutputText, toolResultText, toolSummary, userMessageText,@@ -24,8 +23,6 @@ import {type KiloMessage, type KiloPart, type ChildStats,} from './normalizer.js'-const execFileAsync = promisify(execFile)-const ID_RE = /^[A-Za-z0-9_]+$/const POLL_MS = 1_000const MAX_BUFFER = 32 * 1024 * 1024@@ -38,10 +35,10 @@ function parseJson(text: unknown): Record<string, unknown> {interface Cursor { tc: number; id: string }/**- * Read messages (+ their parts) for one session from kilo.db via the `sqlite3` CLI.+ * Read messages (+ their parts) for one session from kilo.db.* `after` restricts to messages strictly after that boundary (for incremental polling).- * Opens the DB with `query_only` + a busy timeout so it never contends with kilo's writer.- * Throws `KiloSqliteMissing` if the `sqlite3` binary is absent.+ * Read-only, with a short busy timeout, so it never contends with kilo's writer.+ * Throws `KiloSqliteMissing` when this machine has no way to read SQLite at all.*/export async function readKiloMessages(dbPath: string,@@ -49,33 +46,25 @@ export async function readKiloMessages(after?: Cursor | null,): Promise<KiloMessage[]> {if (!ID_RE.test(sessionId)) return []- const cond = after && ID_RE.test(after.id) && Number.isFinite(after.tc)- ? `AND (m.time_created > ${Math.trunc(after.tc)} OR (m.time_created = ${Math.trunc(after.tc)} AND m.id > '${after.id}'))`+ const bounded = !!after && ID_RE.test(after.id) && Number.isFinite(after.tc)+ const cond = bounded+ ? 'AND (m.time_created > ? OR (m.time_created = ? AND m.id > ?)) ': ''const sql =- `SELECT m.id AS mid, m.time_created AS mtc, m.data AS mdata, p.id AS pid, p.data AS pdata ` +- `FROM message m LEFT JOIN part p ON p.message_id = m.id ` +- `WHERE m.session_id = '${sessionId}' ${cond} ` +- `ORDER BY m.time_created, m.id, p.time_created, p.id;`+ 'SELECT m.id AS mid, m.time_created AS mtc, m.data AS mdata, p.id AS pid, p.data AS pdata ' ++ 'FROM message m LEFT JOIN part p ON p.message_id = m.id ' ++ `WHERE m.session_id = ? ${cond}` ++ 'ORDER BY m.time_created, m.id, p.time_created, p.id;'+ const params = bounded+ ? [sessionId, Math.trunc(after!.tc), Math.trunc(after!.tc), after!.id]+ : [sessionId]- let stdout: string- try {- // `.timeout` is the silent dot-command form (the `PRAGMA busy_timeout=…` form prints a JSON row- // under -json, which would corrupt the single-array parse below). query_only guards against writes.- ({ stdout } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', dbPath, sql],- { maxBuffer: MAX_BUFFER },- ))- } catch (err) {- if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') throw new KiloSqliteMissing()+ const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: MAX_BUFFER })+ if (!result.ok) {+ if (result.reason === 'missing') throw new KiloSqliteMissing()return [] // db locked / transient — retry next tick}-- const trimmed = stdout.trim()- if (!trimmed) return []- let rows: Array<Record<string, unknown>>- try { rows = JSON.parse(trimmed) } catch { return [] }+ const rows = result.rowsconst byId = new Map<string, KiloMessage>()const order: string[] = []@@ -99,14 +88,14 @@ export async function readKiloMessages(}export class KiloSqliteMissing extends Error {- constructor() { super('sqlite3 CLI not found on PATH — Kilo sessions cannot be mirrored') }+ constructor() { super('no SQLite reader (node:sqlite absent and no sqlite3 CLI on PATH) — Kilo sessions cannot be mirrored') }}export interface KiloReaderDeps {dbPath: stringsessionId: stringonEvents: (events: LiveEvent[]) => void- /** Reports the one-time fatal "sqlite3 missing" so the caller can warn + stop the reader. */+ /** Reports the one-time fatal "no SQLite reader" so the caller can warn + stop the reader. */onFatal?: (err: Error) => voidpollMs?: number}diff --git a/cli/src/engines/opencode/reader.ts b/cli/src/engines/opencode/reader.tsindex 754e503b5..cc31e2aaf 100644--- a/cli/src/engines/opencode/reader.ts+++ b/cli/src/engines/opencode/reader.ts@@ -2,18 +2,17 @@* OpenCode live tailer.** OpenCode has no per-session transcript file — it writes `message`/`part` rows to a SQLite DB. We- * cannot byte-offset-tail it, so this reader **polls** the DB every ~1s via the `sqlite3` CLI (shelled- * out, like tmux/git — keeps the adapter's single pure-JS bundle intact; no native SQLite dependency)- * and diffs against per-part state to emit incremental `LiveEvent`s into the same- * `emitSessionEvents` funnel the file-based engines use.+ * cannot byte-offset-tail it, so this reader **polls** the DB every ~1s (through `lib/sqliteRead`:+ * `node:sqlite` in-process, or the `sqlite3` CLI on a Node without it) and diffs against per-part+ * state to emit incremental `LiveEvent`s into the same `emitSessionEvents` funnel the file-based+ * engines use.** opencode 1.18.6 writes the legacy `message`/`part` tables (the newer `session_message`/`seq` tables* exist but are empty), so those are the primary cursor.*/-import { execFile } from 'child_process'-import { promisify } from 'util'import type { LiveEvent } from '../../lib/normalize.js'+import { sqliteReadAll } from '../../lib/sqliteRead.js'import {MAX_OUTPUT, MAX_THINKING, clip, object, str,opencodeToolName, toolOutputText, toolSummary, userMessageText,@@ -21,8 +20,6 @@ import {type OcMessage, type OcPart, type ChildStats,} from './normalizer.js'-const execFileAsync = promisify(execFile)-const ID_RE = /^[A-Za-z0-9_]+$/const POLL_MS = 1_000const MAX_BUFFER = 32 * 1024 * 1024@@ -35,10 +32,10 @@ function parseJson(text: unknown): Record<string, unknown> {interface Cursor { tc: number; id: string }/**- * Read messages (+ their parts) for one session from opencode.db via the `sqlite3` CLI.+ * Read messages (+ their parts) for one session from opencode.db.* `after` restricts to messages strictly after that boundary (for incremental polling).- * Opens the DB with `query_only` + a busy timeout so it never contends with opencode's writer.- * Throws `OpencodeSqliteMissing` if the `sqlite3` binary is absent.+ * Read-only, with a short busy timeout, so it never contends with opencode's writer.+ * Throws `OpencodeSqliteMissing` when this machine has no way to read SQLite at all.*/export async function readOpencodeMessages(dbPath: string,@@ -46,33 +43,25 @@ export async function readOpencodeMessages(after?: Cursor | null,): Promise<OcMessage[]> {if (!ID_RE.test(sessionId)) return []- const cond = after && ID_RE.test(after.id) && Number.isFinite(after.tc)- ? `AND (m.time_created > ${Math.trunc(after.tc)} OR (m.time_created = ${Math.trunc(after.tc)} AND m.id > '${after.id}'))`+ const bounded = !!after && ID_RE.test(after.id) && Number.isFinite(after.tc)+ const cond = bounded+ ? 'AND (m.time_created > ? OR (m.time_created = ? AND m.id > ?)) ': ''const sql =- `SELECT m.id AS mid, m.time_created AS mtc, m.data AS mdata, p.id AS pid, p.data AS pdata ` +- `FROM message m LEFT JOIN part p ON p.message_id = m.id ` +- `WHERE m.session_id = '${sessionId}' ${cond} ` +- `ORDER BY m.time_created, m.id, p.time_created, p.id;`+ 'SELECT m.id AS mid, m.time_created AS mtc, m.data AS mdata, p.id AS pid, p.data AS pdata ' ++ 'FROM message m LEFT JOIN part p ON p.message_id = m.id ' ++ `WHERE m.session_id = ? ${cond}` ++ 'ORDER BY m.time_created, m.id, p.time_created, p.id;'+ const params = bounded+ ? [sessionId, Math.trunc(after!.tc), Math.trunc(after!.tc), after!.id]+ : [sessionId]- let stdout: string- try {- // `.timeout` is the silent dot-command form (the `PRAGMA busy_timeout=…` form prints a JSON row- // under -json, which would corrupt the single-array parse below). query_only guards against writes.- ({ stdout } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', dbPath, sql],- { maxBuffer: MAX_BUFFER },- ))- } catch (err) {- if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') throw new OpencodeSqliteMissing()+ const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: MAX_BUFFER })+ if (!result.ok) {+ if (result.reason === 'missing') throw new OpencodeSqliteMissing()return [] // db locked / transient — retry next tick}-- const trimmed = stdout.trim()- if (!trimmed) return []- let rows: Array<Record<string, unknown>>- try { rows = JSON.parse(trimmed) } catch { return [] }+ const rows = result.rowsconst byId = new Map<string, OcMessage>()const order: string[] = []@@ -96,14 +85,14 @@ export async function readOpencodeMessages(}export class OpencodeSqliteMissing extends Error {- constructor() { super('sqlite3 CLI not found on PATH — OpenCode sessions cannot be mirrored') }+ constructor() { super('no SQLite reader (node:sqlite absent and no sqlite3 CLI on PATH) — OpenCode sessions cannot be mirrored') }}export interface OpencodeReaderDeps {dbPath: stringsessionId: stringonEvents: (events: LiveEvent[]) => void- /** Reports the one-time fatal "sqlite3 missing" so the caller can warn + stop the reader. */+ /** Reports the one-time fatal "no SQLite reader" so the caller can warn + stop the reader. */onFatal?: (err: Error) => voidpollMs?: number}diff --git a/cli/src/engines/opencode/sessionModel.ts b/cli/src/engines/opencode/sessionModel.tsindex 0cf8e2086..4825c9dba 100644--- a/cli/src/engines/opencode/sessionModel.ts+++ b/cli/src/engines/opencode/sessionModel.ts@@ -121,7 +121,9 @@ export async function setOpencodeSessionModel(try {// `-bail` stops at the first failing statement; the shell then exits with the transaction still// open, and SQLite rolls it back on close — so a failing second UPDATE leaves the first unapplied.- ({ stdout } = await execFileAsync('sqlite3', ['-batch', '-bail', dbPath, sql]))+ // Bounded: a CLI that never answers used to hold this `agent_create` open for good. The write+ // itself waits at most `busy_timeout` (5s, above) for opencode's lock, so 15s is generous.+ ({ stdout } = await execFileAsync('sqlite3', ['-batch', '-bail', dbPath, sql], { timeout: 15_000, killSignal: 'SIGKILL' }))} catch (err) {const error = err as NodeJS.ErrnoException & { stderr?: string }if (error?.code === 'ENOENT') {diff --git a/cli/src/lib/attachTracker.spec.ts b/cli/src/lib/attachTracker.spec.tsnew file mode 100644index 000000000..cda399552--- /dev/null+++ b/cli/src/lib/attachTracker.spec.ts@@ -0,0 +1,147 @@+import { describe, expect, it, vi } from 'vitest'+import { AttachTracker, forEachBounded } from './attachTracker.js'++type Engine = 'opencode' | 'claude'+const subject = (sessionId: string, engine: Engine = 'claude') => ({ sessionId, agentId: `agent-${sessionId}`, engine })++function deferred<T>() {+ let resolve!: (value: T) => void+ let reject!: (reason: unknown) => void+ const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })+ return { promise, resolve, reject }+}++describe('AttachTracker', () => {+ it('a second plain attach of the same session joins the one in flight', async () => {+ const tracker = new AttachTracker<Engine>()+ const first = deferred<boolean>()+ const start = vi.fn(() => first.promise)+ const a = tracker.attach(subject('s1'), false, start)+ const b = tracker.attach(subject('s1'), false, start)+ expect(start).toHaveBeenCalledTimes(1)+ first.resolve(true)+ expect(await Promise.all([a, b])).toEqual([true, true])+ expect(tracker.attaching()).toEqual([])+ })++ it('a reset waits for the attach in flight, then folds afresh', async () => {+ const tracker = new AttachTracker<Engine>()+ const first = deferred<boolean>()+ const order: string[] = []+ const a = tracker.attach(subject('s1'), false, () => first.promise)+ const b = tracker.attach(subject('s1'), true, async () => { order.push('reset'); return true })+ await Promise.resolve()+ expect(order).toEqual([])+ first.resolve(true)+ expect(await Promise.all([a, b])).toEqual([true, true])+ expect(order).toEqual(['reset'])+ })++ it('a reset still runs after the attach it waited on failed', async () => {+ const tracker = new AttachTracker<Engine>()+ const first = deferred<boolean>()+ const a = tracker.attach(subject('s1'), false, () => first.promise).catch(() => 'failed')+ const b = tracker.attach(subject('s1'), true, async () => true)+ first.reject(new Error('boom'))+ expect(await a).toBe('failed')+ expect(await b).toBe(true)+ })++ it('a start that throws synchronously frees the slot', async () => {+ const tracker = new AttachTracker<Engine>()+ await expect(tracker.attach(subject('s1'), false, () => { throw new Error('sync') })).rejects.toThrow('sync')+ expect(tracker.attaching()).toEqual([])+ expect(await tracker.attach(subject('s1'), false, async () => true)).toBe(true)+ })++ it('different sessions run side by side', async () => {+ const tracker = new AttachTracker<Engine>()+ const one = deferred<boolean>()+ const two = deferred<boolean>()+ const starts = vi.fn()+ const a = tracker.attach(subject('s1'), false, () => { starts('s1'); return one.promise })+ const b = tracker.attach(subject('s2'), false, () => { starts('s2'); return two.promise })+ expect(starts.mock.calls.map((c) => c[0])).toEqual(['s1', 's2'])+ two.resolve(false)+ one.resolve(true)+ expect(await Promise.all([a, b])).toEqual([true, false])+ })++ // What `/api/status` shows: the store that is slow, by name, longest-running first.+ it('reports what is being read, longest-running first', async () => {+ let clock = 1_000+ const tracker = new AttachTracker<Engine>({ now: () => clock })+ const slow = deferred<boolean>()+ const fast = deferred<boolean>()+ void tracker.attach(subject('ses_slow', 'opencode'), false, () => slow.promise)+ clock += 40_000+ void tracker.attach(subject('ses_fast'), false, () => fast.promise)+ clock += 500+ expect(tracker.attaching()).toEqual([+ { sessionId: 'ses_slow', agentId: 'agent-ses_slow', engine: 'opencode', sinceMs: 40_500 },+ { sessionId: 'ses_fast', agentId: 'agent-ses_fast', engine: 'claude', sinceMs: 500 },+ ])+ fast.resolve(true)+ await Promise.resolve()+ expect(tracker.attaching().map((a) => a.sessionId)).toEqual(['ses_slow'])+ slow.resolve(true)+ })++ it('names an attach that runs long, once, and not one that finished', async () => {+ vi.useFakeTimers()+ try {+ const onSlow = vi.fn()+ const tracker = new AttachTracker<Engine>({ slowMs: 15_000, onSlow })+ const stuck = deferred<boolean>()+ const quick = deferred<boolean>()+ void tracker.attach(subject('stuck', 'opencode'), false, () => stuck.promise)+ const done = tracker.attach(subject('quick'), false, () => quick.promise)+ quick.resolve(true)+ await done+ await vi.advanceTimersByTimeAsync(15_000)+ expect(onSlow).toHaveBeenCalledTimes(1)+ expect(onSlow.mock.calls[0][0]).toMatchObject({ sessionId: 'stuck', engine: 'opencode' })+ await vi.advanceTimersByTimeAsync(60_000)+ expect(onSlow).toHaveBeenCalledTimes(1)+ stuck.resolve(true)+ } finally {+ vi.useRealTimers()+ }+ })+})++describe('forEachBounded', () => {+ it('runs at most `limit` at a time, in order, and one that never finishes holds only its own slot', async () => {+ const gates = new Map<number, ReturnType<typeof deferred<void>>>()+ const started: number[] = []+ const all = forEachBounded([1, 2, 3, 4, 5], 2, async (n) => {+ started.push(n)+ const gate = deferred<void>()+ gates.set(n, gate)+ await gate.promise+ })+ await Promise.resolve()+ expect(started).toEqual([1, 2])+ // 1 is the agent whose store hangs: it never resolves. Everything else still gets read.+ gates.get(2)!.resolve()+ await vi.waitFor(() => expect(started).toEqual([1, 2, 3]))+ gates.get(3)!.resolve()+ await vi.waitFor(() => expect(started).toEqual([1, 2, 3, 4]))+ gates.get(4)!.resolve()+ await vi.waitFor(() => expect(started).toEqual([1, 2, 3, 4, 5]))+ gates.get(5)!.resolve()+ let settled = false+ void all.then(() => { settled = true })+ await new Promise((r) => setTimeout(r, 20))+ expect(settled).toBe(false)+ gates.get(1)!.resolve()+ await all+ })++ it('handles an empty list and a limit larger than the list', async () => {+ const seen: number[] = []+ await forEachBounded([], 4, async () => { seen.push(0) })+ await forEachBounded([1, 2], 10, async (n) => { seen.push(n) })+ expect(seen).toEqual([1, 2])+ })+})diff --git a/cli/src/lib/attachTracker.ts b/cli/src/lib/attachTracker.tsnew file mode 100644index 000000000..21b8ec9ad--- /dev/null+++ b/cli/src/lib/attachTracker.ts@@ -0,0 +1,96 @@+/**+ * Bookkeeping for session attaches — the reads of an agent's whole history that rebuild its live+ * normalizer (cli.ts `attachSessionNow`). Two jobs, both born of the same incident: a daemon whose+ * boot sat on ONE agent's store for good, with nothing in any log to say which.+ *+ * - ONE attach per session at a time. Boot hydrates every agent in the background, and the first+ * reconcile pass, a hook, or a cursor discovery can ask for the same session while that is still+ * running. A second fold on top of the first is the duplicate-turn class of bug (a turn opened,+ * closed after 44ms and opened again), so a plain attach JOINS the one in flight, and a `reset`+ * waits for it and then folds afresh.+ * - Saying what the daemon is busy with. `/api/status` lists the attaches in flight, and one that+ * runs long is logged by name.+ */++export interface AttachSubject<E> {+ sessionId: string+ agentId: string+ engine: E+}++export interface AttachInFlight<E> {+ sessionId: string+ agentId: string+ engine: E+ /** How long this attach has been running. */+ sinceMs: number+}++export interface AttachTrackerOptions<E> {+ /** After this long, `onSlow` is told once about the attach. */+ slowMs?: number+ onSlow?: (subject: AttachSubject<E>, elapsedMs: number) => void+ now?: () => number+}++const DEFAULT_SLOW_MS = 15_000++export class AttachTracker<E> {+ private readonly inFlight = new Map<string, { run: Promise<boolean>; subject: AttachSubject<E>; since: number }>()+ private readonly slowMs: number+ private readonly onSlow?: (subject: AttachSubject<E>, elapsedMs: number) => void+ private readonly now: () => number++ constructor(options: AttachTrackerOptions<E> = {}) {+ this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS+ this.onSlow = options.onSlow+ this.now = options.now ?? Date.now+ }++ /**+ * Run `start` for this session — unless one is already running, in which case a plain attach+ * returns THAT one's result and `start` is never called; a `reset` waits for it, then runs `start`.+ */+ async attach(session: AttachSubject<E>, reset: boolean, start: () => Promise<boolean>): Promise<boolean> {+ // A loop, not an if: two resets waiting on the same attach would otherwise both start at once.+ for (let pending = this.inFlight.get(session.sessionId); pending; pending = this.inFlight.get(session.sessionId)) {+ if (!reset) return pending.run+ await pending.run.catch(() => false)+ }+ const since = this.now()+ const slow = setTimeout(() => this.onSlow?.(session, this.now() - since), this.slowMs)+ slow.unref?.()+ // A `start` that throws before it returns a promise must still clear the timer and the slot.+ let started: Promise<boolean>+ try { started = start() } catch (err) { started = Promise.reject(err) }+ const run = started.finally(() => {+ clearTimeout(slow)+ if (this.inFlight.get(session.sessionId)?.run === run) this.inFlight.delete(session.sessionId)+ })+ this.inFlight.set(session.sessionId, { run, subject: session, since })+ return run+ }++ /** What is being read right now, longest-running first. */+ attaching(): Array<AttachInFlight<E>> {+ const now = this.now()+ return [...this.inFlight.values()]+ .map(({ subject, since }) => ({+ sessionId: subject.sessionId, agentId: subject.agentId, engine: subject.engine, sinceMs: now - since,+ }))+ .sort((a, b) => b.sinceMs - a.sinceMs)+ }+}++/**+ * `fn` over every item, at most `limit` at a time, in order of the list. A rejection is the caller's+ * to catch inside `fn`; here it would stop that worker's share of the list, which is not what a boot+ * wants, so `fn` is expected to swallow its own.+ */+export async function forEachBounded<T>(items: readonly T[], limit: number, fn: (item: T) => Promise<void>): Promise<void> {+ const queue = [...items]+ const worker = async (): Promise<void> => {+ for (let item = queue.shift(); item !== undefined; item = queue.shift()) await fn(item)+ }+ await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, queue.length)) }, worker))+}diff --git a/cli/src/lib/sessionRepair.ts b/cli/src/lib/sessionRepair.tsindex 20195b7f4..e2a09ffa0 100644--- a/cli/src/lib/sessionRepair.ts+++ b/cli/src/lib/sessionRepair.ts@@ -14,10 +14,8 @@* unbound until its next turn, which is recoverable — mis-binding is not.*/-import { execFile } from 'child_process'import { open, readdir, readFile, realpath, stat } from 'fs/promises'import { basename, dirname, join, sep } from 'path'-import { promisify } from 'util'import { env } from '../config/env.js'import { museEvent, museWorkspaceRoot } from '../engines/muse/normalizer.js'import type { AgentEngine } from '../engines/types.js'@@ -25,8 +23,7 @@ import { readCodexRolloutMeta, resolveCodexRollout } from '../engines/codex/rollimport { agyConversationForPid, findAgyTranscript } from '../engines/agy/session.js'import { copilotSessionCwd, copilotSessionForPid, findCopilotTranscript } from '../engines/copilot/session.js'import { sqlitePreflightMessage } from './sqliteAvailability.js'--const execFileAsync = promisify(execFile)+import { sqliteReadAll, type SqliteParam } from './sqliteRead.js'/*** Clock granularity only. `ps` reports start time to the second, so a file created in the same second@@ -175,41 +172,31 @@ async function fileEngineSession(let missingSqliteReported = false-/** The store-backed repair branch cannot work without the `sqlite3` CLI; warn on the first miss only. */+/** The store-backed repair branch cannot work without a SQLite reader; warn on the first miss only. */function reportMissingSqliteOnce(): void {if (missingSqliteReported) returnmissingSqliteReported = true- console.warn(sqlitePreflightMessage() ?? '[preflight] sqlite3 CLI not found on PATH')+ console.warn(sqlitePreflightMessage() ?? '[preflight] no SQLite reader available')}-async function dbEngineSession(dbPath: string, sql: string): Promise<RepairedSession | null> {- let stdout: string- try {- // Same invocation the readers use: `.timeout` as a dot-command (the PRAGMA form prints a row under- // -json and corrupts the parse), and query_only so a repair can never write to the user's store.- ({ stdout } = await execFileAsync(- 'sqlite3',- ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', dbPath, sql],- { maxBuffer: 1024 * 1024 },- ))- } catch (err) {- // A missing binary is not a transient DB lock, and repair returning null forever with no signal is+/** Read-only, through the same helper the readers use, so a repair can never write to the user's store. */+async function dbEngineSession(dbPath: string, sql: string, params: SqliteParam[]): Promise<RepairedSession | null> {+ const result = await sqliteReadAll(dbPath, sql, params, { maxBuffer: 1024 * 1024 })+ if (!result.ok) {+ // No reader at all is not a transient DB lock, and repair returning null forever with no signal is// how "my opencode agents never appear on Ubuntu" looks from the outside. Say it once.- if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') reportMissingSqliteOnce()+ if (result.reason === 'missing') reportMissingSqliteOnce()return null}- const trimmed = stdout.trim()- if (!trimmed) return null- let rows: Array<Record<string, unknown>>- try { rows = JSON.parse(trimmed) as Array<Record<string, unknown>> } catch { return null }+ const rows = result.rowsif (rows.length !== 1) return null // 0 = nothing to adopt, >1 = ambiguousconst id = rows[0].idreturn typeof id === 'string' && id ? { sessionId: id } : null}-/** SQL-escape a directory for a literal comparison (the readers build literals the same way). */-function quote(value: string): string {- return `'${value.replace(/'/g, "''")}'`+/** One `?` per directory, for an `IN (…)` over both spellings of the cwd. */+function placeholders(count: number): string {+ return Array.from({ length: count }, () => '?').join(', ')}/**@@ -250,7 +237,7 @@ export async function findLiveSession(// The DB engines match on a directory STRING, so ask for both spellings of it (see sameDir).const real = await realpath(cwd).catch(() => cwd)const dirs = real === cwd ? [cwd] : [cwd, real]- const dirList = dirs.map(quote).join(', ')+ const dirList = placeholders(dirs.length)switch (engine) {case 'claude': {// Native Claude publishes a PID-to-conversation record even before a hook binds it.@@ -317,8 +304,9 @@ export async function findLiveSession(return dbEngineSession(join(env.OPENCODE_DATA_DIR, 'opencode.db'),`SELECT id FROM session WHERE directory IN (${dirList}) AND parent_id IS NULL`- + ` AND (time_created >= ${Math.trunc(sinceMs)} OR time_updated >= ${Math.trunc(sinceMs)})`- + ` ORDER BY time_updated DESC LIMIT 2;`,+ + ' AND (time_created >= ? OR time_updated >= ?)'+ + ' ORDER BY time_updated DESC LIMIT 2;',+ [...dirs, Math.trunc(sinceMs), Math.trunc(sinceMs)],)case 'kilo':// Same store shape as opencode (measured: `session` is byte-identical between the two DBs), and@@ -326,15 +314,17 @@ export async function findLiveSession(return dbEngineSession(join(env.KILO_DATA_DIR, 'kilo.db'),`SELECT id FROM session WHERE directory IN (${dirList}) AND parent_id IS NULL`- + ` AND (time_created >= ${Math.trunc(sinceMs)} OR time_updated >= ${Math.trunc(sinceMs)})`- + ` ORDER BY time_updated DESC LIMIT 2;`,+ + ' AND (time_created >= ? OR time_updated >= ?)'+ + ' ORDER BY time_updated DESC LIMIT 2;',+ [...dirs, Math.trunc(sinceMs), Math.trunc(sinceMs)],)case 'hermes':// started_at is epoch SECONDS (fractional).return dbEngineSession(join(env.HERMES_HOME, 'state.db'),- `SELECT id FROM sessions WHERE cwd IN (${dirList}) AND started_at >= ${Math.trunc(sinceMs / 1000)}`- + ` ORDER BY started_at DESC LIMIT 2;`,+ `SELECT id FROM sessions WHERE cwd IN (${dirList}) AND started_at >= ?`+ + ' ORDER BY started_at DESC LIMIT 2;',+ [...dirs, Math.trunc(sinceMs / 1000)],)case 'devin':// created_at is epoch SECONDS (integer).@@ -343,8 +333,9 @@ export async function findLiveSession(// created_at is when the session began; last_activity_at moves when devin resumes into it, which// is the only marker a continued session leaves behind.`SELECT id FROM sessions WHERE working_directory IN (${dirList})`- + ` AND (created_at >= ${Math.trunc(sinceMs / 1000)} OR last_activity_at >= ${Math.trunc(sinceMs / 1000)})`- + ` ORDER BY last_activity_at DESC LIMIT 2;`,+ + ' AND (created_at >= ? OR last_activity_at >= ?)'+ + ' ORDER BY last_activity_at DESC LIMIT 2;',+ [...dirs, Math.trunc(sinceMs / 1000), Math.trunc(sinceMs / 1000)],)case 'copilot': {// The lock the process holds is the only thing a `/resume` leaves behind, and it is exact.diff --git a/cli/src/lib/sqliteAvailability.spec.ts b/cli/src/lib/sqliteAvailability.spec.tsindex 19d066815..9a9345c12 100644--- a/cli/src/lib/sqliteAvailability.spec.ts+++ b/cli/src/lib/sqliteAvailability.spec.ts@@ -2,13 +2,15 @@ import { describe, expect, it, afterEach } from 'vitest'import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { delimiter, join } from 'node:path'-import { hasSqliteCli, resetSqliteAvailabilityCache, sqlitePreflightMessage } from './sqliteAvailability.js'+import { hasSqliteCli, hasSqliteReader, resetSqliteAvailabilityCache, sqlitePreflightMessage } from './sqliteAvailability.js'+import { overrideBuiltinSqlite } from './sqliteRead.js'const dirs: string[] = []const realPath = process.env.PATHafterEach(() => {process.env.PATH = realPath+ overrideBuiltinSqlite(undefined)resetSqliteAvailabilityCache()for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })})@@ -35,16 +37,29 @@ describe('sqlite3 preflight', () => {// Ubuntu does not ship sqlite3 (measured on a stock ubuntu:24.04 image), so on Linux this is the// default state, not an exotic one. The line must name the affected engines AND the fix — a bare// "sqlite3 not found" leaves the user with four engines that mirror nothing and no idea why.- it('names the affected engines and the fix when it is absent', () => {+ it('names the affected engines and the fix when neither reader is available', () => {process.env.PATH = pathWith(false)+ overrideBuiltinSqlite(null) // a Node without node:sqliteresetSqliteAvailabilityCache()expect(hasSqliteCli()).toBe(false)+ expect(hasSqliteReader()).toBe(false)const message = sqlitePreflightMessage()expect(message).toContain('sqlite3')for (const engine of ['opencode', 'kilo', 'hermes', 'devin']) expect(message).toContain(engine)expect(message).toMatch(/apt install sqlite3|on PATH/)})+ // The installers' Node carries node:sqlite, and a daemon on it has nothing to warn about even on a+ // Linux box with no CLI at all.+ it('stays silent without the CLI when this Node has node:sqlite', () => {+ process.env.PATH = pathWith(false)+ overrideBuiltinSqlite(class { prepare(): never { throw new Error('unused') } exec(): void {} close(): void {} } as never)+ resetSqliteAvailabilityCache()+ expect(hasSqliteCli()).toBe(false)+ expect(hasSqliteReader()).toBe(true)+ expect(sqlitePreflightMessage()).toBeNull()+ })+it('ignores a non-executable file of the same name', () => {const dir = mkdtempSync(join(tmpdir(), 'sqlite-probe-'))dirs.push(dir)diff --git a/cli/src/lib/sqliteAvailability.ts b/cli/src/lib/sqliteAvailability.tsindex 616d4e4be..7ae35b4ef 100644--- a/cli/src/lib/sqliteAvailability.ts+++ b/cli/src/lib/sqliteAvailability.ts@@ -1,16 +1,19 @@/**- * Is the `sqlite3` CLI present?+ * Can this daemon read the SQLite stores at all?*- * Four engines keep their conversations in SQLite rather than in a transcript file and are read by- * shelling out to `sqlite3` (`engines/{opencode,kilo,hermes,devin}/reader.ts`), as is one branch of- * session repair. macOS ships `/usr/bin/sqlite3` in the base system, so this has never had to be- * checked; a stock `ubuntu:24.04` does NOT ship it (measured), and neither does a slim Node image, so- * on Linux those four engines silently mirror nothing until the user installs it.+ * Four engines keep their conversations in SQLite rather than in a transcript file+ * (`engines/{opencode,kilo,hermes,devin}/reader.ts`), as does one branch of session repair. They read+ * through `lib/sqliteRead`: `node:sqlite` when this Node has it (the installers' Node does), else the+ * `sqlite3` CLI. macOS ships `/usr/bin/sqlite3` in the base system; a stock `ubuntu:24.04` does NOT+ * (measured), and neither does a slim Node image — so on Linux, on a Node without the binding, those+ * four engines silently mirror nothing until the user installs it.** Resolved from PATH directly rather than by spawning: this runs on the startup path and the answer is- * only used for one advisory log line.+ * only used for one advisory log line and to gate the one path that still needs the CLI (the opencode+ * store rewrite in `sessionModel.ts`, a write the built-in binding is not used for).*/import { binaryOnPath } from './binaryOnPath.js'+import { builtinSqlite } from './sqliteRead.js'/** Engines that cannot be mirrored without the CLI. Keep in sync with the readers listed above. */export const SQLITE_BACKED_ENGINES = ['opencode', 'kilo', 'hermes', 'devin'] as const@@ -23,13 +26,18 @@ export function hasSqliteCli(): boolean {return cached}+/** Either way to read a store will do. */+export function hasSqliteReader(): boolean {+ return builtinSqlite() !== null || hasSqliteCli()+}+/** One advisory line at startup. Says what is affected and exactly how to fix it — never throws. */export function sqlitePreflightMessage(): string | null {- if (hasSqliteCli()) return null+ if (hasSqliteReader()) return nullconst install = process.platform === 'linux'? 'sudo apt install sqlite3 (or your distro\'s equivalent)': 'install the sqlite3 CLI and make sure it is on PATH'- return `[preflight] sqlite3 CLI not found on PATH — ${SQLITE_BACKED_ENGINES.join(', ')}`+ return `[preflight] no SQLite reader (this Node has no node:sqlite, and no sqlite3 CLI on PATH) — ${SQLITE_BACKED_ENGINES.join(', ')}`+ ` agents cannot be mirrored. Every other engine is unaffected. Fix: ${install}`}diff --git a/cli/src/lib/sqliteRead.spec.ts b/cli/src/lib/sqliteRead.spec.tsnew file mode 100644index 000000000..7264b1c72--- /dev/null+++ b/cli/src/lib/sqliteRead.spec.ts@@ -0,0 +1,163 @@+import { afterEach, beforeEach, describe, expect, it } from 'vitest'+import { execFileSync } from 'node:child_process'+import { chmodSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import {+ builtinSqlite, closeSqliteHandles, inlineSqlParams, overrideBuiltinSqlite, sqliteReadAll,+} from './sqliteRead.js'++const hasCli = (() => {+ try { execFileSync('sqlite3', ['-version'], { stdio: 'ignore' }); return true } catch { return false }+})()+const hasBuiltin = builtinSqlite() !== null++function run(db: string, sql: string): void {+ execFileSync('sqlite3', [db, sql], { stdio: ['ignore', 'ignore', 'inherit'] })+}++describe('inlineSqlParams', () => {+ it('quotes strings, doubles embedded quotes, passes numbers and NULL through', () => {+ expect(inlineSqlParams('SELECT ? , ?, ?, ?', ["it's", 42, 1.5, null]))+ .toBe("SELECT 'it''s' , 42, 1.5, NULL")+ })++ it('refuses a mismatch between placeholders and parameters either way', () => {+ expect(() => inlineSqlParams('SELECT ?, ?', ['a'])).toThrow(/more placeholders/)+ expect(() => inlineSqlParams('SELECT ?', ['a', 'b'])).toThrow(/more parameters/)+ })++ it("leaves a ? inside the SQL's own string literals alone", () => {+ expect(inlineSqlParams("SELECT json_extract(d, '$.why?') FROM t WHERE id = ? AND note = 'it''s ?'", [7]))+ .toBe("SELECT json_extract(d, '$.why?') FROM t WHERE id = 7 AND note = 'it''s ?'")+ })++ it('refuses what a literal cannot carry', () => {+ expect(() => inlineSqlParams('SELECT ?', ['a\0b'])).toThrow(/NUL/)+ expect(() => inlineSqlParams('SELECT ?', [Number.NaN])).toThrow(/non-finite/)+ })+})++// The CLI seeds the fixture store, so both paths need it; the built-in path additionally needs this+// Node to carry node:sqlite (the installers' Node does; CI's may not).+const withCli = hasCli ? describe : describe.skip++withCli('sqliteReadAll', () => {+ let dir = ''+ let db = ''+ beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'sqlite-read-'))+ db = join(dir, 'store.db')+ run(db, 'CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT, time_created INTEGER, data TEXT);'+ + "INSERT INTO message VALUES ('m1','ses_a',1,'{\"role\":\"user\"}');"+ + "INSERT INTO message VALUES ('m2','ses_a',2,'{\"role\":\"assistant\"}');"+ + "INSERT INTO message VALUES ('m3','ses_b',3,'{\"role\":\"user\"}');")+ })+ afterEach(() => {+ closeSqliteHandles()+ overrideBuiltinSqlite(undefined)+ rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })+ })++ const paths: Array<['builtin' | 'cli', () => void]> = [+ ['cli', () => overrideBuiltinSqlite(null)],+ ...(hasBuiltin ? [['builtin', () => overrideBuiltinSqlite(undefined)] as ['builtin', () => void]] : []),+ ]++ for (const [via, select] of paths) {+ describe(`via ${via}`, () => {+ beforeEach(select)++ it('binds parameters in order and returns rows as plain objects', async () => {+ const result = await sqliteReadAll(db,+ 'SELECT id, time_created AS tc, data FROM message WHERE session_id = ? AND time_created > ? ORDER BY id;',+ ['ses_a', 1])+ expect(result).toEqual({ ok: true, via, rows: [{ id: 'm2', tc: 2, data: '{"role":"assistant"}' }] })+ })++ it('returns no rows, not an error, for an unknown session', async () => {+ const result = await sqliteReadAll(db, 'SELECT id FROM message WHERE session_id = ?;', ['nope'])+ expect(result).toEqual({ ok: true, via, rows: [] })+ })++ // A value with a quote in it must reach SQLite as data. The readers validate ids with a regex+ // before this, but the repair path passes directory names straight through.+ it('carries a quote inside a parameter as data', async () => {+ run(db, "INSERT INTO message VALUES ('m4','it''s',4,'{}');")+ const result = await sqliteReadAll(db, 'SELECT id FROM message WHERE session_id = ?;', ["it's"])+ expect(result).toEqual({ ok: true, via, rows: [{ id: 'm4' }] })+ })++ // The row that hung the sqlite3 CLI for good on one machine was ~7.5 MB. Whatever path is in use,+ // a row that size must come back whole, and quickly — this is the regression that blocked the app.+ it('reads a multi-megabyte row whole', async () => {+ const big = 'x'.repeat(8 * 1024 * 1024)+ writeFileSync(join(dir, 'big.sql'), `INSERT INTO message VALUES ('m5','ses_big',5,'${big}');`)+ execFileSync('sh', ['-c', `sqlite3 "${db}" < "${join(dir, 'big.sql')}"`])+ const started = Date.now()+ const result = await sqliteReadAll(db, 'SELECT data FROM message WHERE session_id = ?;', ['ses_big'])+ expect(result.ok).toBe(true)+ if (!result.ok) return+ expect((result.rows[0].data as string).length).toBe(big.length)+ expect(Date.now() - started).toBeLessThan(5_000)+ })++ it('reports a missing store as transient, and creates nothing', async () => {+ const result = await sqliteReadAll(join(dir, 'absent.db'), 'SELECT 1;', [])+ expect(result.ok).toBe(false)+ if (result.ok) return+ expect(result.reason).toBe('transient')+ expect(() => execFileSync('ls', [join(dir, 'absent.db')], { stdio: 'ignore' })).toThrow()+ })+ })+ }++ const withBuiltin = hasBuiltin ? it : it.skip++ // The handle is cached per path for the pollers' sake; a store rebuilt under the same name must+ // not keep answering from the file that was there before.+ withBuiltin('follows a store replaced on disk', async () => {+ overrideBuiltinSqlite(undefined)+ const first = await sqliteReadAll(db, 'SELECT count(*) AS n FROM message;', [])+ expect(first).toEqual({ ok: true, via: 'builtin', rows: [{ n: 3 }] })+ const fresh = join(dir, 'fresh.db')+ run(fresh, "CREATE TABLE message (id TEXT PRIMARY KEY); INSERT INTO message VALUES ('only');")+ renameSync(fresh, db)+ const second = await sqliteReadAll(db, 'SELECT count(*) AS n FROM message;', [])+ expect(second).toEqual({ ok: true, via: 'builtin', rows: [{ n: 1 }] })+ })++ it('reports missing when neither reader exists', async () => {+ overrideBuiltinSqlite(null)+ const realPath = process.env.PATH+ const empty = mkdtempSync(join(tmpdir(), 'no-sqlite-'))+ process.env.PATH = empty+ try {+ const result = await sqliteReadAll(db, 'SELECT 1;', [])+ expect(result).toMatchObject({ ok: false, reason: 'missing' })+ } finally {+ process.env.PATH = realPath+ rmSync(empty, { recursive: true, force: true })+ }+ })++ // The bound that was missing: a CLI that never answers used to hold its caller forever.+ it('gives up on a CLI that hangs', async () => {+ overrideBuiltinSqlite(null)+ const realPath = process.env.PATH+ const shim = mkdtempSync(join(tmpdir(), 'slow-sqlite-'))+ // `exec`, so the SIGKILL lands on the sleep itself rather than orphaning it under a dead shell.+ writeFileSync(join(shim, 'sqlite3'), '#!/bin/sh\nexec sleep 30\n')+ chmodSync(join(shim, 'sqlite3'), 0o755)+ process.env.PATH = shim+ try {+ const started = Date.now()+ const result = await sqliteReadAll(db, 'SELECT 1;', [], { cliTimeoutMs: 300 })+ expect(result).toMatchObject({ ok: false, reason: 'transient' })+ expect(Date.now() - started).toBeLessThan(5_000)+ } finally {+ process.env.PATH = realPath+ rmSync(shim, { recursive: true, force: true })+ }+ })+})diff --git a/cli/src/lib/sqliteRead.ts b/cli/src/lib/sqliteRead.tsnew file mode 100644index 000000000..1c7e5bf40--- /dev/null+++ b/cli/src/lib/sqliteRead.ts@@ -0,0 +1,240 @@+/**+ * Read-only SQLite access for the engines that keep their conversation in a store instead of a+ * transcript file (opencode, kilo, hermes, devin) and for the session-repair branch that looks them up.+ *+ * Two ways in, tried in this order:+ *+ * 1. `node:sqlite` — built into the Node the installers ship (22.23, see `runtime/current-node`),+ * and into any Node ≥ 22.13 without a flag. In-process, parameterised, no JSON round-trip: the+ * query that hung the `sqlite3` CLI for good on one machine (an opencode session with a ~7.5 MB+ * row) finishes here in tens of milliseconds. The binding is SYNCHRONOUS — it blocks the event+ * loop for the length of the query — so the busy timeout is kept short: a contended read returns+ * `transient` and the caller polls again next tick, exactly as a locked CLI read did before.+ * 2. The `sqlite3` CLI — for a daemon on a Node without the binding (`engines.node >= 20`). Same+ * invocation the readers always used, plus a hard timeout: a CLI that never answers used to hold+ * the caller (and, at boot, the whole daemon) forever.+ *+ * Neither present ⇒ `missing`, which the readers report once and stop on, as they did for a missing CLI.+ *+ * Every store this reads is WAL (measured: opencode, kilo, hermes), so a reader never blocks the+ * engine's writer and is rarely blocked by it; `busy_timeout` only covers the checkpoint window.+ */++import { execFile } from 'node:child_process'+import { statSync } from 'node:fs'+import { promisify } from 'node:util'++const execFileAsync = promisify(execFile)++export type SqliteRow = Record<string, unknown>+export type SqliteParam = string | number | null++export interface SqliteReadOptions {+ /** How long the built-in binding may wait on a lock. Short on purpose: it blocks the event loop. */+ busyTimeoutMs?: number+ /** Hard bound on the CLI fallback process. */+ cliTimeoutMs?: number+ /** stdout cap for the CLI fallback. */+ maxBuffer?: number+}++export type SqliteReadResult =+ | { ok: true; rows: SqliteRow[]; via: 'builtin' | 'cli' }+ /** `missing`: no way to read SQLite on this machine. `transient`: locked, mid-write, unreadable — retry. */+ | { ok: false; reason: 'missing' | 'transient'; error?: Error }++const DEFAULT_BUSY_TIMEOUT_MS = 250+const DEFAULT_CLI_TIMEOUT_MS = 5_000+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024++// ---- built-in binding ---------------------------------------------------------------------------++interface StatementLike { all(...params: SqliteParam[]): SqliteRow[] }+interface DatabaseLike {+ prepare(sql: string): StatementLike+ exec(sql: string): void+ close(): void+}+interface DatabaseConstructor { new (path: string, options: { readOnly: boolean }): DatabaseLike }++let builtin: DatabaseConstructor | null | undefined++/**+ * `node:sqlite` when this Node has it, else null. Resolved through `process.getBuiltinModule` (Node+ * ≥ 20.16 / 22.3) rather than `import()`: synchronous, and invisible to the bundler, which must not+ * try to resolve a module that only some runtimes have.+ *+ * The binding announces itself with an ExperimentalWarning on first load. That line would land in+ * `harness.log` at every daemon boot, so it is filtered — only that one warning, and every other+ * listener is kept.+ */+export function builtinSqlite(): DatabaseConstructor | null {+ if (builtin !== undefined) return builtin+ builtin = null+ const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule+ if (typeof get !== 'function') return builtin+ const previous = process.listeners('warning')+ process.removeAllListeners('warning')+ process.on('warning', (warning) => {+ if (warning.name === 'ExperimentalWarning' && /SQLite/i.test(warning.message)) return+ for (const listener of previous) listener.call(process, warning)+ })+ try {+ const mod = get.call(process, 'node:sqlite') as { DatabaseSync?: unknown } | undefined+ if (mod && typeof mod.DatabaseSync === 'function') builtin = mod.DatabaseSync as DatabaseConstructor+ } catch {+ builtin = null+ }+ return builtin+}++interface Handle { db: DatabaseLike; dev: number; ino: number }++/** One open handle per store: the readers poll every second, and opening is the expensive part. */+const handles = new Map<string, Handle>()++/**+ * The cached handle, or a fresh one. Keyed by path but checked by inode: an engine that rebuilds its+ * store (a reinstall, a `rm` and restart) leaves a handle on the OLD file, which would keep answering+ * from a database nobody writes to any more — a poller that never sees another row, with no error.+ */+function openHandle(Database: DatabaseConstructor, dbPath: string, busyTimeoutMs: number): DatabaseLike {+ const { dev, ino } = statSync(dbPath)+ const cached = handles.get(dbPath)+ if (cached && cached.dev === dev && cached.ino === ino) return cached.db+ if (cached) dropHandle(dbPath)+ const db = new Database(dbPath, { readOnly: true })+ // Not a write: the pragma is per-connection state, accepted on a read-only handle.+ db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(busyTimeoutMs))}`)+ handles.set(dbPath, { db, dev, ino })+ return db+}++function dropHandle(dbPath: string): void {+ const handle = handles.get(dbPath)+ handles.delete(dbPath)+ try { handle?.db.close() } catch { /* already gone */ }+}++/** Test seam, and for a store that was replaced on disk: forget every open handle. */+export function closeSqliteHandles(): void {+ for (const path of [...handles.keys()]) dropHandle(path)+}++function readBuiltin(+ Database: DatabaseConstructor,+ dbPath: string,+ sql: string,+ params: SqliteParam[],+ busyTimeoutMs: number,+): SqliteReadResult {+ try {+ const db = openHandle(Database, dbPath, busyTimeoutMs)+ return { ok: true, rows: db.prepare(sql).all(...params), via: 'builtin' }+ } catch (err) {+ // Locked, mid-checkpoint, the file replaced underneath the handle, not a database at all: every one+ // of these is "try again later" for a poller, and a handle that failed is not trusted again — the+ // next call reopens from the path.+ dropHandle(dbPath)+ return { ok: false, reason: 'transient', error: err instanceof Error ? err : new Error(String(err)) }+ }+}++// ---- CLI fallback -------------------------------------------------------------------------------++/**+ * The CLI takes no bound parameters, so the values are inlined as SQL literals: strings with their+ * quotes doubled (the only escaping SQLite needs), numbers as finite decimals, null as NULL. A NUL+ * byte cannot be carried in a literal and is refused rather than truncated. A `?` inside a string+ * literal of the SQL itself (`json_extract(data, '$.a?')`) is left alone: only bare ones bind.+ */+export function inlineSqlParams(sql: string, params: SqliteParam[]): string {+ let index = 0+ const out = sql.replace(/'(?:[^']|'')*'|\?/g, (match) => {+ if (match !== '?') return match+ if (index >= params.length) throw new Error('sqlite: more placeholders than parameters')+ const value = params[index++]+ if (value === null) return 'NULL'+ if (typeof value === 'number') {+ if (!Number.isFinite(value)) throw new Error('sqlite: non-finite number parameter')+ return String(value)+ }+ if (value.includes('\0')) throw new Error('sqlite: NUL byte in string parameter')+ return `'${value.replace(/'/g, "''")}'`+ })+ if (index !== params.length) throw new Error('sqlite: more parameters than placeholders')+ return out+}++/** A path as a `file:` URI body: the three characters SQLite's URI parser would otherwise read as syntax. */+function uriPath(path: string): string {+ return path.replace(/[%?#]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`)+}++async function readCli(+ dbPath: string,+ sql: string,+ params: SqliteParam[],+ timeoutMs: number,+ maxBuffer: number,+): Promise<SqliteReadResult> {+ let inlined: string+ try {+ inlined = inlineSqlParams(sql, params)+ } catch (err) {+ return { ok: false, reason: 'transient', error: err as Error }+ }+ let stdout: string+ try {+ // `.timeout` is the SILENT dot-command form — `PRAGMA busy_timeout=…` prints a row under -json and+ // would corrupt the single-array parse below. `query_only` is silent and guards against writes.+ // `mode=ro` so a path that does not exist yet is an error, not a freshly created empty store.+ ;({ stdout } = await execFileAsync(+ 'sqlite3',+ ['-json', '-cmd', '.timeout 3000', '-cmd', 'PRAGMA query_only=1', `file:${uriPath(dbPath)}?mode=ro`, inlined],+ { maxBuffer, timeout: timeoutMs, killSignal: 'SIGKILL' },+ ))+ } catch (err) {+ const error = err as NodeJS.ErrnoException+ if (error?.code === 'ENOENT') return { ok: false, reason: 'missing', error }+ return { ok: false, reason: 'transient', error }+ }+ const trimmed = stdout.trim()+ if (!trimmed) return { ok: true, rows: [], via: 'cli' }+ try {+ const rows = JSON.parse(trimmed) as unknown+ return { ok: true, rows: Array.isArray(rows) ? rows as SqliteRow[] : [], via: 'cli' }+ } catch (err) {+ return { ok: false, reason: 'transient', error: err as Error }+ }+}++// ---- entry point --------------------------------------------------------------------------------++/**+ * Run one read-only statement against `dbPath` and return its rows. `?` placeholders are bound from+ * `params` in order — build the SQL as a constant and pass the values here, never paste them in.+ */+export async function sqliteReadAll(+ dbPath: string,+ sql: string,+ params: SqliteParam[] = [],+ options: SqliteReadOptions = {},+): Promise<SqliteReadResult> {+ const Database = builtinSqlite()+ if (Database) {+ return readBuiltin(Database, dbPath, sql, params, options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS)+ }+ return readCli(+ dbPath,+ sql,+ params,+ options.cliTimeoutMs ?? DEFAULT_CLI_TIMEOUT_MS,+ options.maxBuffer ?? DEFAULT_MAX_BUFFER,+ )+}++/** Test seam: force the CLI path (or the built-in one) regardless of what this Node has. */+export function overrideBuiltinSqlite(value: DatabaseConstructor | null | undefined): void {+ builtin = value+}