@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/repl/store/session-store.js

@@ -0,0 +1,792 @@
+/**
+ * SessionStore — Sprint α6.4 (PR-PUGI-CLI-SESSION-STORE).
+ *
+ * SQLite-indexed, JSONL-durable session store. The JSONL log is the
+ * source of truth; the SQLite tables are a queryable cache. Layout:
+ *
+ *   ~/.pugi/projects/<project-slug>/
+ *     session.db                 SQLite index (sessions + FTS5)
+ *     session.lock               PID lockfile
+ *     sessions/<session-id>/
+ *       events.0.jsonl           active append log
+ *       events.1.jsonl           older rotations (50 MB threshold)
+ *
+ * The store lives entirely under `$HOME/.pugi/` per the local-first
+ * invariants memo (`feedback_no_landing_oes_secondary_2026_05_23.md`)
+ * — never write inside the repo unless the operator explicitly opts in
+ * via `--workspace`. The repo's `.pugi/` directory (touched by `pugi
+ * init`) is a SEPARATE concept used for artifacts + per-repo settings.
+ *
+ * Why node:sqlite over better-sqlite3:
+ *
+ *   - Zero install-time native build. better-sqlite3 needs prebuilt
+ *     binaries for every Node ABI × platform; missing a wheel forces
+ *     a node-gyp compile that fails on bare-metal CI agents without
+ *     a C++ toolchain. Pugi CLI ships via npm to operators who almost
+ *     certainly do not have build-essential installed.
+ *   - Available since Node 22.5.0 (stable subset; LTS as of 2026). Our
+ *     `engines.node` is pinned to `>=22.5.0` in apps/pugi-cli +
+ *     packages/pugi-sdk so npm refuses to install the CLI on Node 20.x
+ *     instead of crash-on-import. CI runs Node 22 (matrix-free; see
+ *     `.github/workflows/ci.yml`).
+ *   - Marked Experimental by Node — silenced via process.emitWarning
+ *     suppression at boot. The API surface we use (DatabaseSync,
+ *     StatementSync, exec/prepare) is the stable subset that has
+ *     shipped unchanged since Node 22.5.
+ *
+ * Schema is created at first open. `schema_meta` carries a single row
+ * `('version', '1')`; future migrations bump the version + run the
+ * delta. v1 is the only schema this PR ships.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { JsonlEventLog } from './jsonl-log.js';
+import { takeLock } from './lockfile.js';
+import { uuidV7 } from './uuid-v7.js';
+const SCHEMA_VERSION = '1';
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    workspace_root TEXT NOT NULL,
+    branch TEXT,
+    project_slug TEXT NOT NULL,
+    title TEXT,
+    turn_count INTEGER NOT NULL DEFAULT 0,
+    event_count INTEGER NOT NULL DEFAULT 0,
+    model TEXT,
+    tenant_id TEXT,
+    status TEXT NOT NULL DEFAULT 'active'
+  );
+  CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at DESC);
+  CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_slug, updated_at DESC);
+  CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(
+    id UNINDEXED,
+    title,
+    body,
+    tokenize='unicode61'
+  );
+  CREATE TABLE IF NOT EXISTS schema_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+`;
+/** Default list limit. Operators rarely scroll past the most recent 50. */
+const DEFAULT_LIST_LIMIT = 50;
+/** Hard cap on list limit. Protects the picker UI from huge result sets. */
+const MAX_LIST_LIMIT = 1000;
+/** Default search limit. */
+const DEFAULT_SEARCH_LIMIT = 20;
+/** Hard cap on search limit. */
+const MAX_SEARCH_LIMIT = 200;
+/** Title truncation per spec §4.2 MUST-ship #1. */
+const TITLE_MAX_CHARS = 80;
+/**
+ * Resolve the absolute path of the per-project store directory under
+ * `$HOME/.pugi/projects/<slug>/`. Exported so the CLI dispatcher can
+ * print the location in `pugi doctor` output.
+ */
+export function resolveProjectStoreDir(projectSlug, homeOverride) {
+    const home = homeOverride ?? homedir();
+    return resolve(home, '.pugi', 'projects', sanitiseSlugForFs(projectSlug));
+}
+/**
+ * Concrete SessionStore implementation. Construct, then `open()` to
+ * bind one session; `close()` to release the lock + SQLite handle.
+ */
+export class SqliteSessionStore {
+    projectSlug;
+    home;
+    now;
+    killProbe;
+    projectDir;
+    db = null;
+    lock = null;
+    /**
+     * Active JSONL log for the currently-open session. `null` between
+     * `open()` calls. Only one session is bound at a time — the REPL
+     * runs one session per REPL lifetime; multi-session is a CLI-only
+     * concern (`pugi sessions list`).
+     */
+    activeLog = null;
+    activeSessionId = null;
+    constructor(opts) {
+        this.projectSlug = opts.projectSlug;
+        this.home = opts.home ?? homedir();
+        this.now = opts.now ?? Date.now;
+        this.killProbe = opts.killProbe;
+        this.projectDir = resolveProjectStoreDir(this.projectSlug, this.home);
+    }
+    /**
+     * Open the SQLite connection + take the lockfile + insert-or-reopen
+     * the session row. Idempotent in the sense that a second `open()`
+     * with the same session id reuses the connection and returns the
+     * existing row. A second `open()` with a different id rebinds the
+     * active log to the new session (the SQLite connection stays).
+     */
+    async open(input) {
+        if (!existsSync(this.projectDir)) {
+            mkdirSync(this.projectDir, { recursive: true, mode: 0o700 });
+        }
+        if (this.db === null) {
+            this.takeLockOrThrow();
+            this.openDatabase();
+        }
+        const id = input.id ?? uuidV7(this.now);
+        const sessionDir = resolve(this.projectDir, 'sessions', id);
+        if (!existsSync(sessionDir)) {
+            mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+        }
+        // Rebind the active JSONL log to the new session id.
+        if (this.activeLog && this.activeSessionId !== id) {
+            this.activeLog.close();
+            this.activeLog = null;
+        }
+        if (!this.activeLog) {
+            this.activeLog = new JsonlEventLog({ sessionDir, now: this.now });
+            this.activeSessionId = id;
+        }
+        const existing = this.getSessionSync(id);
+        if (existing) {
+            // Reopen path: bump updated_at so the listing reflects activity.
+            return this.updateSessionMetaSync(id, {});
+        }
+        return this.insertSessionSync({
+            id,
+            workspaceRoot: input.workspaceRoot,
+            projectSlug: this.projectSlug,
+            branch: input.branch ?? null,
+            model: input.model ?? null,
+            tenantId: input.tenantId ?? null,
+        });
+    }
+    /**
+     * Append one event. Writes the JSONL line first (durable truth),
+     * then updates the SQLite cache. On the first non-empty `user`
+     * event, sets the session title if it is still null.
+     */
+    async appendEvent(event) {
+        const log = this.requireActiveLog();
+        const db = this.requireDb();
+        const sessionId = this.requireSessionId();
+        log.append(event);
+        const ts = this.now();
+        const isUserTurn = event.kind === 'user';
+        const titlePatch = this.maybeTitleFromEvent(sessionId, event);
+        // Single UPDATE: bump event_count, bump updated_at, conditionally
+        // bump turn_count and set title. Splitting into multiple statements
+        // would race the lockfile if a second process slipped through.
+        const sql = `
+      UPDATE sessions
+         SET event_count = event_count + 1,
+             updated_at  = ?,
+             turn_count  = turn_count + ${isUserTurn ? 1 : 0},
+             title       = COALESCE(title, ?)
+       WHERE id = ?
+    `;
+        db.prepare(sql).run(ts, titlePatch ?? null, sessionId);
+        // Mirror the user-turn body into FTS so substring search hits
+        // every previous user turn, not just the most recent one.
+        // Previously this called `upsertFtsRow(... body)` which did
+        // DELETE+INSERT and DROPPED every prior turn from the FTS body.
+        // We append-with-newline to the existing body so subsequent
+        // searches still hit terms from earlier turns.
+        if (event.kind === 'user') {
+            const body = extractEventText(event);
+            if (body.length > 0) {
+                this.appendFtsBody(sessionId, body);
+            }
+        }
+    }
+    async listSessions(opts) {
+        const db = this.requireDb();
+        const limit = clampLimit(opts?.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
+        // Default: active+archived (suppress aborted). Caller opts into
+        // 'all' explicitly to see aborted rows, or names one status to
+        // narrow further. Spec'd on `SessionListOptions.status` in
+        // ./types.ts — keep this branch in lockstep with that doc comment.
+        const statusFilter = opts?.status ?? 'active+archived';
+        const cursor = opts?.cursor;
+        const where = [];
+        const params = [];
+        if (opts?.project) {
+            where.push('project_slug = ?');
+            params.push(opts.project);
+        }
+        if (statusFilter === 'all') {
+            // No status clause — return every row regardless of status.
+        }
+        else if (statusFilter === 'active+archived') {
+            // Default path — suppress 'aborted' rows from the listing.
+            where.push(`status != 'aborted'`);
+        }
+        else {
+            where.push('status = ?');
+            params.push(statusFilter);
+        }
+        if (cursor) {
+            // Pagination cursor: return rows STRICTLY older than the cursor
+            // row's updated_at. We resolve the cursor's updated_at in a
+            // single subquery so an invalid cursor degrades to an empty
+            // result instead of a hard error.
+            where.push('updated_at < (SELECT updated_at FROM sessions WHERE id = ?)');
+            params.push(cursor);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+        const sql = `
+      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+             title, turn_count, event_count, model, tenant_id, status
+        FROM sessions
+        ${whereClause}
+       ORDER BY updated_at DESC
+       LIMIT ?
+    `;
+        const stmt = db.prepare(sql);
+        const rows = stmt.all(...params, limit);
+        return rows.map(rawToSession);
+    }
+    async loadEvents(sessionId, opts) {
+        const log = this.logForSession(sessionId);
+        // For the ACTIVE session we share the long-lived JsonlEventLog
+        // owned by `this.activeLog`; we must NOT close it. For any other
+        // session we constructed a fresh JsonlEventLog inside
+        // logForSession; close it here so the file descriptor it opens
+        // lazily during read does not leak. Without this guard, repeated
+        // loadEvents() calls for inactive sessions accumulated fds and
+        // tripped EMFILE under high load.
+        const isActive = this.activeLog === log;
+        try {
+            return log.read(opts);
+        }
+        finally {
+            if (!isActive) {
+                log.close();
+            }
+        }
+    }
+    async getSession(sessionId) {
+        return this.getSessionSync(sessionId);
+    }
+    async updateSessionMeta(sessionId, patch) {
+        return this.updateSessionMetaSync(sessionId, patch);
+    }
+    async search(query, opts) {
+        const trimmed = query.trim();
+        if (trimmed.length === 0) {
+            throw new Error('SessionStore.search requires a non-empty query');
+        }
+        const db = this.requireDb();
+        const limit = clampLimit(opts?.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+        // FTS5 MATCH on title+body. Always wrap as a quoted phrase + escape
+        // embedded `"` so an unbalanced quote in the operator's input
+        // (`pugi sessions --search 'cabinet"'`) cannot crash SQLite with
+        // `SQLITE_ERROR: fts5: syntax error`. The wrapper is defensive —
+        // operator-typed FTS5 syntax (`body:cabinet OR title:sidebar`) is
+        // intentionally NOT supported anymore; the upside is "no surprise
+        // crash on a stray quote" and the downside is "no power-user FTS5
+        // syntax", which the spec accepts.
+        const ftsQuery = sanitiseFtsQuery(trimmed);
+        // FTS5 requires MATCH against the virtual-table name itself; the
+        // column-restricted form (`f.body MATCH ?`) is rejected with
+        // `unable to use function MATCH in the requested context`. We
+        // search title+body together by matching against `sessions_fts`.
+        const sql = `
+      SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
+             s.project_slug, s.title, s.turn_count, s.event_count, s.model,
+             s.tenant_id, s.status
+        FROM sessions_fts f
+        JOIN sessions s ON s.id = f.id
+       WHERE sessions_fts MATCH ?
+       ORDER BY s.updated_at DESC
+       LIMIT ?
+    `;
+        let rows;
+        try {
+            rows = db.prepare(sql).all(ftsQuery, limit);
+        }
+        catch (error) {
+            // Wrap SQLITE_ERROR from FTS5 so the CLI can print a single-line
+            // operator-friendly message + exit 2 instead of dumping a stack.
+            // The dispatcher branches on error.code === 'EFTS5_SYNTAX'.
+            if (isSqliteError(error)) {
+                throw new FtsSyntaxError(ftsQuery, error);
+            }
+            throw error;
+        }
+        return rows.map(rawToSession);
+    }
+    async close() {
+        if (this.activeLog) {
+            this.activeLog.close();
+            this.activeLog = null;
+            this.activeSessionId = null;
+        }
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch {
+                /* idempotent — already closed */
+            }
+            this.db = null;
+        }
+        if (this.lock) {
+            this.lock.release();
+            this.lock = null;
+        }
+    }
+    /**
+     * Open the per-project SQLite file in read-only mode WITHOUT taking
+     * the lockfile and WITHOUT inserting a session row. The caller
+     * receives a small view that supports `list` / `search` / `get` and
+     * must call `close()` when done.
+     *
+     * SQLite supports multiple concurrent readers even when a writer
+     * holds an OS-level lock, so this view is safe to open while a live
+     * REPL is writing in the same project.
+     *
+     * Used by `pugi resume --list`, `pugi sessions --local`, `pugi
+     * sessions --search`, and `pugi resume <id>` so those read-only
+     * commands no longer mint a stub session row + pollute the listing.
+     */
+    static async openReadOnly(projectStoreDir) {
+        const dbPath = resolve(projectStoreDir, 'session.db');
+        if (!existsSync(dbPath)) {
+            throw Object.assign(new Error(`No session database at ${dbPath}`), { code: 'ENOENT' });
+        }
+        // node:sqlite DatabaseSync accepts a `{ readOnly: true }` option
+        // which maps to SQLITE_OPEN_READONLY. The option form is the
+        // documented API; the file-URI form (file:...?mode=ro) also works.
+        const db = new DatabaseSync(dbPath, { readOnly: true });
+        return new SqliteSessionStoreReadOnlyView(db);
+    }
+    /* ------------------------------------------------------------ */
+    /* Internals                                                    */
+    /* ------------------------------------------------------------ */
+    takeLockOrThrow() {
+        const lockPath = resolve(this.projectDir, 'session.lock');
+        // Surface SessionLockBusyError as-is so the dispatcher can branch
+        // on `error.code === 'EBUSY_SESSION_LOCK'`. Anything else
+        // (EACCES, ENOSPC) propagates so the caller sees the real cause.
+        this.lock = takeLock(lockPath, this.killProbe ? { kill: this.killProbe } : undefined);
+    }
+    openDatabase() {
+        const dbPath = resolve(this.projectDir, 'session.db');
+        this.db = new DatabaseSync(dbPath);
+        // WAL mode: writers do not block readers. The lockfile already
+        // serialises us across processes, but WAL keeps an in-process
+        // read query from blocking the append-event writer.
+        this.db.exec('PRAGMA journal_mode = WAL');
+        // synchronous=NORMAL is safe with WAL and avoids the per-fsync
+        // hit on every COMMIT. Crash safety is provided by the JSONL log
+        // (the source of truth), not by SQLite — losing the index after
+        // power loss is recoverable via `pugi sessions --rebuild`.
+        this.db.exec('PRAGMA synchronous = NORMAL');
+        this.db.exec('PRAGMA foreign_keys = ON');
+        this.db.exec(SCHEMA_SQL);
+        // Stamp the schema version. INSERT OR IGNORE so a reopen against
+        // an existing v1 database is a no-op.
+        this.db
+            .prepare('INSERT OR IGNORE INTO schema_meta(key, value) VALUES (?, ?)')
+            .run('version', SCHEMA_VERSION);
+    }
+    requireDb() {
+        if (!this.db)
+            throw new Error('SessionStore is not open');
+        return this.db;
+    }
+    requireActiveLog() {
+        if (!this.activeLog) {
+            throw new Error('SessionStore has no active session — call open() first');
+        }
+        return this.activeLog;
+    }
+    requireSessionId() {
+        if (!this.activeSessionId) {
+            throw new Error('SessionStore has no active session id');
+        }
+        return this.activeSessionId;
+    }
+    logForSession(sessionId) {
+        if (this.activeSessionId === sessionId && this.activeLog) {
+            return this.activeLog;
+        }
+        const sessionDir = resolve(this.projectDir, 'sessions', sessionId);
+        return new JsonlEventLog({ sessionDir, now: this.now });
+    }
+    getSessionSync(sessionId) {
+        const db = this.requireDb();
+        const stmt = db.prepare(`
+      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+             title, turn_count, event_count, model, tenant_id, status
+        FROM sessions
+       WHERE id = ?
+    `);
+        const row = stmt.get(sessionId);
+        return row ? rawToSession(row) : null;
+    }
+    insertSessionSync(input) {
+        const db = this.requireDb();
+        const ts = this.now();
+        db.prepare(`
+      INSERT INTO sessions
+        (id, created_at, updated_at, workspace_root, branch, project_slug,
+         title, turn_count, event_count, model, tenant_id, status)
+      VALUES (?, ?, ?, ?, ?, ?, NULL, 0, 0, ?, ?, 'active')
+    `).run(input.id, ts, ts, input.workspaceRoot, input.branch, input.projectSlug, input.model, input.tenantId);
+        // Seed an empty FTS row so the title patch path can rely on a
+        // single UPDATE OR REPLACE without first checking for the row.
+        this.upsertFtsRow(input.id, '', '');
+        return {
+            id: input.id,
+            createdAt: ts,
+            updatedAt: ts,
+            workspaceRoot: input.workspaceRoot,
+            branch: input.branch,
+            projectSlug: input.projectSlug,
+            title: null,
+            turnCount: 0,
+            eventCount: 0,
+            model: input.model,
+            tenantId: input.tenantId,
+            status: 'active',
+        };
+    }
+    updateSessionMetaSync(sessionId, patch) {
+        const db = this.requireDb();
+        const ts = this.now();
+        // Build a dynamic UPDATE. We only allow fields declared on
+        // SessionRowPatch to land in SQL; an unknown key throws so the
+        // caller sees the bug at the call site.
+        const ALLOWED_PATCH_FIELDS = new Set([
+            'workspaceRoot',
+            'branch',
+            'projectSlug',
+            'title',
+            'turnCount',
+            'eventCount',
+            'model',
+            'tenantId',
+            'status',
+        ]);
+        const sets = ['updated_at = ?'];
+        const params = [ts];
+        for (const key of Object.keys(patch)) {
+            if (!ALLOWED_PATCH_FIELDS.has(key)) {
+                throw new Error(`SessionStore.updateSessionMeta: unknown field '${String(key)}'`);
+            }
+            const column = camelToSnake(key);
+            sets.push(`${column} = ?`);
+            params.push(patch[key] === undefined ? null : patch[key]);
+        }
+        params.push(sessionId);
+        const sql = `UPDATE sessions SET ${sets.join(', ')} WHERE id = ?`;
+        const result = db.prepare(sql).run(...params);
+        if (Number(result.changes) === 0) {
+            throw new Error(`SessionStore.updateSessionMeta: session '${sessionId}' not found`);
+        }
+        // Mirror title changes into the FTS row.
+        if (patch.title !== undefined) {
+            this.upsertFtsRow(sessionId, patch.title ?? '', this.bodyForFts(sessionId));
+        }
+        const row = this.getSessionSync(sessionId);
+        if (!row) {
+            throw new Error(`SessionStore.updateSessionMeta: session '${sessionId}' vanished after UPDATE`);
+        }
+        return row;
+    }
+    /**
+     * Pick a title from a fresh `user` event when the session does not
+     * yet have one. Returns the truncated title or null when no patch
+     * should be applied. Idempotent — once title is non-null, subsequent
+     * calls return null.
+     */
+    maybeTitleFromEvent(sessionId, event) {
+        if (event.kind !== 'user')
+            return null;
+        const existing = this.getSessionSync(sessionId);
+        if (!existing || existing.title)
+            return null;
+        const text = extractEventText(event);
+        if (text.length === 0)
+            return null;
+        return text.slice(0, TITLE_MAX_CHARS);
+    }
+    upsertFtsRow(sessionId, title, body) {
+        const db = this.requireDb();
+        // FTS5 virtual tables don't support UPSERT — emulate with delete +
+        // insert. Cheap because each session has one FTS row.
+        db.prepare('DELETE FROM sessions_fts WHERE id = ?').run(sessionId);
+        db.prepare('INSERT INTO sessions_fts (id, title, body) VALUES (?, ?, ?)')
+            .run(sessionId, title, body);
+    }
+    /**
+     * Append text to the FTS body of one session, preserving every prior
+     * turn. Reads the current row, concatenates `body + '\n' + addition`,
+     * and rewrites the row via the DELETE+INSERT path because FTS5
+     * virtual tables do not support UPDATE on the content column in the
+     * external-content-table configuration we use.
+     *
+     * Each session has at most one FTS row (one row per session id), so
+     * the read-modify-write here is O(1) on the FTS index.
+     *
+     * Wrapped in BEGIN IMMEDIATE / COMMIT so a concurrent ReadOnlyView
+     * cannot observe the brief "row deleted" window between the DELETE
+     * and the INSERT that upsertFtsRow performs. BEGIN IMMEDIATE acquires
+     * the write lock at BEGIN time, failing fast on contention instead of
+     * leaving the txn half-applied. On any error we ROLLBACK and rethrow
+     * so the caller's catch surface stays unchanged.
+     */
+    appendFtsBody(sessionId, addition) {
+        const db = this.requireDb();
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const existingBody = this.bodyForFts(sessionId);
+            const existingTitle = this.titleForFts(sessionId);
+            const nextBody = existingBody.length === 0
+                ? addition
+                : `${existingBody}\n${addition}`;
+            this.upsertFtsRow(sessionId, existingTitle, nextBody);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch {
+                // Swallow rollback failures; the original error is the one
+                // worth surfacing. SQLite auto-rolls back when the txn handle
+                // goes out of scope if ROLLBACK itself fails.
+            }
+            throw err;
+        }
+    }
+    titleForFts(sessionId) {
+        const row = this.getSessionSync(sessionId);
+        return row?.title ?? '';
+    }
+    bodyForFts(sessionId) {
+        const db = this.requireDb();
+        const stmt = db.prepare('SELECT body FROM sessions_fts WHERE id = ?');
+        const row = stmt.get(sessionId);
+        return row?.body ?? '';
+    }
+}
+/**
+ * Read-only view returned by `SqliteSessionStore.openReadOnly`. Holds
+ * a DatabaseSync handle opened with `readOnly: true`; no lockfile, no
+ * inserts. Exists so `pugi sessions --local` / `pugi resume --list` /
+ * `pugi sessions --search` / `pugi resume <id>` can read the store
+ * without polluting the session history with a stub row on every call.
+ */
+export class SqliteSessionStoreReadOnlyView {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async list(opts) {
+        const limit = clampLimit(opts?.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
+        const statusFilter = opts?.status ?? 'active+archived';
+        const cursor = opts?.cursor;
+        const where = [];
+        const params = [];
+        if (opts?.project) {
+            where.push('project_slug = ?');
+            params.push(opts.project);
+        }
+        if (statusFilter === 'all') {
+            // No status clause.
+        }
+        else if (statusFilter === 'active+archived') {
+            where.push(`status != 'aborted'`);
+        }
+        else {
+            where.push('status = ?');
+            params.push(statusFilter);
+        }
+        if (cursor) {
+            where.push('updated_at < (SELECT updated_at FROM sessions WHERE id = ?)');
+            params.push(cursor);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+        const sql = `
+      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+             title, turn_count, event_count, model, tenant_id, status
+        FROM sessions
+        ${whereClause}
+       ORDER BY updated_at DESC
+       LIMIT ?
+    `;
+        const rows = this.db
+            .prepare(sql)
+            .all(...params, limit);
+        return rows.map(rawToSession);
+    }
+    async search(query, opts) {
+        const trimmed = query.trim();
+        if (trimmed.length === 0) {
+            throw new Error('SessionStore.search requires a non-empty query');
+        }
+        const limit = clampLimit(opts?.limit ?? DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+        const ftsQuery = sanitiseFtsQuery(trimmed);
+        const sql = `
+      SELECT s.id, s.created_at, s.updated_at, s.workspace_root, s.branch,
+             s.project_slug, s.title, s.turn_count, s.event_count, s.model,
+             s.tenant_id, s.status
+        FROM sessions_fts f
+        JOIN sessions s ON s.id = f.id
+       WHERE sessions_fts MATCH ?
+       ORDER BY s.updated_at DESC
+       LIMIT ?
+    `;
+        let rows;
+        try {
+            rows = this.db.prepare(sql).all(ftsQuery, limit);
+        }
+        catch (error) {
+            if (isSqliteError(error)) {
+                throw new FtsSyntaxError(ftsQuery, error);
+            }
+            throw error;
+        }
+        return rows.map(rawToSession);
+    }
+    async get(sessionId) {
+        const stmt = this.db.prepare(`
+      SELECT id, created_at, updated_at, workspace_root, branch, project_slug,
+             title, turn_count, event_count, model, tenant_id, status
+        FROM sessions
+       WHERE id = ?
+    `);
+        const row = stmt.get(sessionId);
+        return row ? rawToSession(row) : null;
+    }
+    async close() {
+        try {
+            this.db.close();
+        }
+        catch {
+            /* idempotent */
+        }
+    }
+}
+function rawToSession(raw) {
+    return {
+        id: raw.id,
+        createdAt: Number(raw.created_at),
+        updatedAt: Number(raw.updated_at),
+        workspaceRoot: raw.workspace_root,
+        branch: raw.branch,
+        projectSlug: raw.project_slug,
+        title: raw.title,
+        turnCount: Number(raw.turn_count),
+        eventCount: Number(raw.event_count),
+        model: raw.model,
+        tenantId: raw.tenant_id,
+        status: coerceStatus(raw.status),
+    };
+}
+function coerceStatus(raw) {
+    if (raw === 'active' || raw === 'archived' || raw === 'aborted') {
+        return raw;
+    }
+    // Defence-in-depth — unknown status means a future schema wrote it.
+    // Treat as active so the row still appears in the picker.
+    return 'active';
+}
+function camelToSnake(input) {
+    return input.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+}
+function clampLimit(raw, max) {
+    if (!Number.isFinite(raw) || raw <= 0)
+        return 1;
+    if (raw > max)
+        return max;
+    return Math.floor(raw);
+}
+/**
+ * Sanitise a project slug for filesystem use. Same rules as
+ * `slugForCwd` in history.ts (lowercase alphanum + hyphen, collapse
+ * runs of hyphens, empty -> `default`). Re-implemented inline to
+ * avoid a circular import with the repl module.
+ */
+function sanitiseSlugForFs(raw) {
+    const cleaned = raw.replace(/[^a-z0-9-]/gi, '-').toLowerCase().replace(/-+/g, '-');
+    const trimmed = cleaned.replace(/^-+|-+$/g, '');
+    return trimmed.length === 0 ? 'default' : trimmed;
+}
+/**
+ * Pull a human-readable text body out of an event payload. We support
+ * three shapes the producer commonly emits:
+ *
+ *   - `{ text: string }`   — explicit text body.
+ *   - `{ brief: string }`  — REPL `dispatch` brief.
+ *   - `string`             — payload is the body itself.
+ *
+ * Anything else returns the empty string so a typo at the call site
+ * silently degrades to "no FTS body" rather than crashing the writer.
+ */
+function extractEventText(event) {
+    const payload = event.payload;
+    if (typeof payload === 'string')
+        return payload;
+    if (typeof payload === 'object' && payload !== null) {
+        const candidate = payload.text
+            ?? payload.brief;
+        if (typeof candidate === 'string')
+            return candidate;
+    }
+    return '';
+}
+/**
+ * Sanitise a plain-text query for FTS5 MATCH binding. Always wraps the
+ * input in double-quoted phrase syntax and doubles any embedded `"` so
+ * a stray quote in the operator's input cannot break out of the phrase
+ * and trip FTS5's parser.
+ *
+ * Trade-off: power-user FTS5 syntax (`body:cabinet OR title:sidebar`)
+ * is no longer reachable — every input is treated as a literal token
+ * or phrase. The spec accepts this in exchange for "never crashes on a
+ * stray punctuation character". Hyphens, colons, asterisks, and
+ * parentheses all degrade to literal matches inside the quoted phrase.
+ *
+ * The complementary defence in `search()` wraps the prepare/all call in
+ * try/catch + rethrows as `FtsSyntaxError`. Belt + suspenders: even if
+ * a future input shape slips past this helper, the error message is
+ * still operator-readable instead of a stack trace.
+ */
+function sanitiseFtsQuery(query) {
+    return `"${query.replace(/"/g, '""')}"`;
+}
+/**
+ * SQLite errors land on the JS side with `error.code` strings like
+ * `'SQLITE_ERROR'`, `'SQLITE_CONSTRAINT_UNIQUE'`, etc. We treat any
+ * `SQLITE_*` code as recoverable for the FTS5 syntax wrap — operator
+ * input is the only realistic source of these errors during search.
+ */
+function isSqliteError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const code = error.code;
+    return typeof code === 'string' && code.startsWith('SQLITE_');
+}
+/**
+ * Thrown by `search()` when SQLite rejects an FTS5 query as malformed.
+ * The CLI dispatcher branches on `error.code === 'EFTS5_SYNTAX'` to
+ * surface a one-line operator-friendly message + exit 2.
+ */
+export class FtsSyntaxError extends Error {
+    code = 'EFTS5_SYNTAX';
+    query;
+    cause;
+    constructor(query, cause) {
+        super(`Invalid search query (FTS5 syntax error): ${query}`);
+        this.name = 'FtsSyntaxError';
+        this.query = query;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=session-store.js.map