Skip to content

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.

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.ts
index 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.ts
index 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 = 64
const 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.rows
const 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) => void
pollMs?: number
}
diff --git a/cli/src/engines/hermes/reader.ts b/cli/src/engines/hermes/reader.ts
index 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: string
sessionId: string
onEvents: (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) => void
pollMs?: number
}
diff --git a/cli/src/engines/kilo/reader.ts b/cli/src/engines/kilo/reader.ts
index 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_000
const 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.rows
const 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: string
sessionId: string
onEvents: (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) => void
pollMs?: number
}
diff --git a/cli/src/engines/opencode/reader.ts b/cli/src/engines/opencode/reader.ts
index 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_000
const 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.rows
const 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: string
sessionId: string
onEvents: (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) => void
pollMs?: number
}
diff --git a/cli/src/engines/opencode/sessionModel.ts b/cli/src/engines/opencode/sessionModel.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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/roll
import { 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) return
missingSqliteReported = 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.rows
if (rows.length !== 1) return null // 0 = nothing to adopt, >1 = ambiguous
const id = rows[0].id
return 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.ts
index 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.PATH
afterEach(() => {
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:sqlite
resetSqliteAvailabilityCache()
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.ts
index 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 null
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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
+}