@aexol/spectral 0.0.1

package/dist/server/shutdown.js

@@ -0,0 +1,180 @@
+/**
+ * Graceful shutdown helper for `spectral serve`.
+ *
+ * Why a separate module:
+ *  - The shutdown flag (`shutdownState.isShuttingDown`) is read by the relay
+ *    dispatcher to reject new `client_message` envelopes. Putting it on
+ *    `serve.ts` would create a circular import (dispatcher → serve → relay
+ *    client → …); pulling it out keeps the dependency graph linear.
+ *  - The orchestration is small but has enough edge cases (idempotent on a
+ *    second SIGTERM, bounded wait for in-flight streams, best-effort store
+ *    close) that it's worth one focused unit test.
+ *
+ * Behaviour summary (matches the contract in the Batch 6 brief):
+ *  1. First SIGINT/SIGTERM:
+ *     - Log "Shutting down…" to stderr.
+ *     - Flip `shutdownState.isShuttingDown = true`. From this point on the
+ *       dispatcher refuses new `client_message` frames with an error
+ *       wrapped as a `ws_event` (so the browser sees the rejection on the
+ *       same stream it was using).
+ *     - Wait up to `gracePeriodMs` (default 5_000 ms) for the in-flight
+ *       stream count reported by `inFlightCount()` to drain to 0. Polled
+ *       every 100 ms — any non-zero value indicates an active turn.
+ *     - Close the relay (code 1000, reason "shutdown") and dispose the
+ *       manager. The dispose order matters: relay first so the backend
+ *       sees a clean close before our local state goes; manager second so
+ *       any pi processes get torn down deterministically.
+ *     - Close the SQLite store (best-effort — a failure here just gets
+ *       logged; the process is exiting anyway).
+ *     - Exit with the supplied code (default 0).
+ *  2. Second SIGINT/SIGTERM during the grace period: skip the wait, force
+ *     immediate exit with code 1. We don't want a hung pi process to
+ *     prevent operators from killing the server with a second Ctrl-C.
+ *
+ * The function is intentionally framework-free — it takes plain callbacks
+ * for everything I/O-shaped so the unit test can exercise the orchestration
+ * without spawning a real relay or sqlite handle.
+ */
+/**
+ * Process-wide shutdown flag. Read by the dispatcher to gate new
+ * `client_message` envelopes; written by `gracefulShutdown` (and by tests
+ * via `resetShutdownState`).
+ *
+ * Module-level singleton because there is exactly one server process per
+ * `spectral serve` invocation; co-locating with serve.ts would require
+ * threading the flag through the dispatcher's deps (already a small
+ * object) and risks dispatcher tests carrying serve.ts state.
+ */
+export const shutdownState = {
+    isShuttingDown: false,
+};
+/**
+ * Reset the singleton flag. Tests use this in `beforeEach` so a previous
+ * test's shutdown doesn't bleed into the next. Production code must NOT
+ * call this — once the process is shutting down, it's shutting down.
+ */
+export function resetShutdownState() {
+    shutdownState.isShuttingDown = false;
+}
+/**
+ * Number of times `gracefulShutdown` has been entered in this process.
+ * 0 → first signal: do the full graceful sequence.
+ * ≥1 → second signal during grace: bail with code 1 immediately.
+ *
+ * Deliberately a module-level counter rather than a closure so the second
+ * signal handler (which closes over a different invocation of the function)
+ * still observes the increment.
+ */
+let entryCount = 0;
+/** Test-only: reset the entry counter alongside `shutdownState`. */
+export function resetShutdownEntryCount() {
+    entryCount = 0;
+}
+/**
+ * Run the graceful shutdown sequence. Idempotent on the entry-count
+ * dimension: the second concurrent call resolves immediately after
+ * triggering an immediate exit.
+ *
+ * Returns once the supplied `exitFn` has been invoked (or would have been
+ * invoked in production where `process.exit` does not return). Tests can
+ * await it to assert ordering.
+ */
+export async function gracefulShutdown(opts = {}) {
+    const logger = opts.logger ?? console;
+    const exitFn = opts.exitFn ?? ((code) => process.exit(code));
+    const sleep = opts.sleep ?? defaultSleep;
+    const gracePeriodMs = opts.gracePeriodMs ?? 5_000;
+    const pollIntervalMs = opts.pollIntervalMs ?? 100;
+    const exitCode = opts.exitCode ?? 0;
+    entryCount += 1;
+    // Second signal during a graceful shutdown: don't wait around, just go.
+    // Code 1 signals "abnormal exit" — operators wanted out NOW, not after
+    // pi finishes its turn.
+    if (entryCount > 1) {
+        try {
+            logger.error("Shutdown forced by repeated signal — exiting immediately.");
+        }
+        catch {
+            // ignore — best-effort
+        }
+        exitFn(1);
+        return;
+    }
+    // First signal: announce intent, flip the flag (dispatcher reads this on
+    // every inbound `client_message`), then drain.
+    try {
+        logger.error("Shutting down…");
+    }
+    catch {
+        // ignore — best-effort
+    }
+    shutdownState.isShuttingDown = true;
+    // Bounded wait for in-flight turns. We don't accept new ones (the flag
+    // is set), but we let the ones that already started finish so the user
+    // doesn't see a half-streamed assistant message orphaned in the UI.
+    if (opts.inFlightCount) {
+        const start = Date.now();
+        while (Date.now() - start < gracePeriodMs) {
+            let count;
+            try {
+                count = opts.inFlightCount();
+            }
+            catch {
+                // Defensive: a misbehaving counter shouldn't trap the shutdown.
+                // Treat it as "drained" and move on.
+                count = 0;
+            }
+            if (count <= 0)
+                break;
+            await sleep(pollIntervalMs);
+        }
+    }
+    // Order matters: relay → manager → store. See module-level comment.
+    if (opts.closeRelay) {
+        try {
+            await opts.closeRelay();
+        }
+        catch (err) {
+            try {
+                logger.warn(`Relay close failed during shutdown: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    if (opts.disposeManager) {
+        try {
+            await opts.disposeManager();
+        }
+        catch (err) {
+            try {
+                logger.warn(`Manager dispose failed during shutdown: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    if (opts.closeStore) {
+        try {
+            opts.closeStore();
+        }
+        catch (err) {
+            try {
+                logger.warn(`Store close failed during shutdown: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    exitFn(exitCode);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        // Don't keep the loop alive purely for the shutdown poll.
+        t.unref?.();
+    });
+}

package/dist/server/storage.js

@@ -0,0 +1,491 @@
+/**
+ * SQLite-backed project/session/message storage for `spectral serve`.
+ *
+ * Two-tier model:
+ *   projects ─< sessions ─< messages
+ *
+ * Single-process, single-file. Using `better-sqlite3` because:
+ *  - Synchronous API is a perfect fit for the per-WS-event write pattern.
+ *  - No connection pool, no callback churn, transactions are trivial.
+ *  - Native module ships prebuilt binaries for every Node version we support.
+ *
+ * Schema migrations:
+ *   We track schema with the `user_version` PRAGMA. When opening a DB whose
+ *   version does not match `SCHEMA_VERSION`, we DROP every known table and
+ *   recreate. This is safe pre-1.0 because the agent UI is local-only and
+ *   the data is conversation history we explicitly opted not to migrate
+ *   for the project-tier rollout. Anything newer (real users with real
+ *   data) needs a proper migration table.
+ *
+ * Foreign keys are enabled so DELETE FROM projects cascades to sessions
+ * cascades to messages. The route layer must still tear down any in-flight
+ * pi streams BEFORE deleting — see `SessionStreamManager.disposeProjectStreams`.
+ *
+ * The repo is intentionally a thin wrapper. We do NOT expose `Database`
+ * itself — callers go through the typed methods so we can swap the backend
+ * later (e.g. if we ever need to colocate with a remote service).
+ */
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stripJsoncComments } from "../studio-binding.js";
+/**
+ * Schema version. Bump + the on-open migration drops & recreates every table.
+ * Since this is local-only conversation history pre-1.0, we explicitly do not
+ * preserve user data across schema changes.
+ */
+const SCHEMA_VERSION = 2;
+const SCHEMA_SQL = `
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  model_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user','assistant','system')),
+  content TEXT NOT NULL,
+  events_jsonl TEXT NOT NULL DEFAULT '',
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at);
+`;
+/**
+ * Synchronous binding-file reader for a project at the given filesystem path.
+ * Returns null when no `.aexol/aexol.jsonc` exists at that path.
+ */
+function readBindingSync(projectPath) {
+    try {
+        const raw = readFileSync(join(projectPath, ".aexol", "aexol.jsonc"), "utf8");
+        return JSON.parse(stripJsoncComments(raw));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        // Rethrow on unexpected I/O errors (permissions, etc.).
+        throw err;
+    }
+}
+/** Augment a WireProject row with Studio binding fields when present. */
+function applyBindingFields(project) {
+    const binding = readBindingSync(project.path);
+    if (!binding)
+        return project;
+    return {
+        ...project,
+        studioProjectId: binding.projectId,
+        studioProjectName: binding.name || binding.projectId,
+    };
+}
+/** Tables we own — used by the migration drop step. */
+const KNOWN_TABLES = ["messages", "sessions", "projects"];
+export class SessionStore {
+    path;
+    db;
+    closed = false;
+    // Project statements
+    stmtListProjects;
+    stmtGetProject;
+    stmtCreateProject;
+    stmtUpdateProject;
+    stmtDeleteProject;
+    stmtListSessionsByProject;
+    stmtListSessionIdsByProject;
+    // Session statements
+    stmtGetSession;
+    stmtCreateSession;
+    stmtDeleteSession;
+    stmtListMessages;
+    stmtAppendMessage;
+    stmtTouchSession;
+    stmtRenameSession;
+    stmtSessionWithCount;
+    // Phase 3: per-session sticky model.
+    stmtGetSessionModel;
+    stmtSetSessionModel;
+    constructor(path) {
+        this.path = path;
+        // Make sure the parent directory exists. mkdirSync with recursive is a
+        // no-op when the dir already exists.
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        this.db = new Database(path);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("foreign_keys = ON");
+        // ---- migration --------------------------------------------------------
+        // Detect schema version and drop+recreate on mismatch. Pre-1.0: no data
+        // preservation. The first open on a brand-new file reports version 0
+        // and falls through to the create path below (drops are no-ops on
+        // missing tables).
+        const versionRow = this.db.pragma("user_version", { simple: true });
+        if (versionRow !== SCHEMA_VERSION) {
+            // Disable FKs for the duration of the drop so order doesn't matter
+            // (we drop children first regardless, but this keeps it bullet-proof
+            // if KNOWN_TABLES order is ever reshuffled).
+            this.db.pragma("foreign_keys = OFF");
+            const tx = this.db.transaction(() => {
+                for (const t of KNOWN_TABLES) {
+                    this.db.exec(`DROP TABLE IF EXISTS ${t}`);
+                }
+            });
+            tx();
+            this.db.pragma("foreign_keys = ON");
+        }
+        this.db.exec(SCHEMA_SQL);
+        // Stamp the version AFTER schema creation so a crash mid-create is
+        // detected next open and re-runs the (idempotent) create.
+        this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
+        // ---- additive column migration ---------------------------------------
+        // Phase 3 (Available Models): per-session sticky model selection lives in
+        // a new `sessions.model_id` column. We do this as an idempotent ALTER
+        // (not a SCHEMA_VERSION bump + drop) because the column is purely
+        // additive — older rows have NULL model_id and fall back to pi's own
+        // settings file, which is the pre-Phase-3 behaviour. Bumping
+        // SCHEMA_VERSION would also nuke conversation history we now want to
+        // preserve. The check is cheap (one PRAGMA per startup) and safe to run
+        // every time.
+        const sessionCols = this.db
+            .prepare(`PRAGMA table_info(sessions)`)
+            .all();
+        if (!sessionCols.some((c) => c.name === "model_id")) {
+            this.db.exec(`ALTER TABLE sessions ADD COLUMN model_id TEXT`);
+        }
+        // ---- one-time cleanup -------------------------------------------------
+        // Historical garbage from prior runs of the bridge that persisted every
+        // intermediate `message_end` pi emitted, including pure-framing rows
+        // with no visible content. Those rows were silently dropped by the
+        // client's hydration path, but they polluted message counts and were
+        // surfaced by `SELECT * FROM messages`. The bridge no longer emits
+        // these going forward — this DELETE catches the backlog. Conservative
+        // pattern: only rows with empty content, tiny JSONL, AND none of the
+        // four meaningful wire-event substrings. Idempotent and cheap; safe to
+        // run on every startup.
+        try {
+            const cleanup = this.db
+                .prepare(`DELETE FROM messages
+           WHERE role = 'assistant'
+             AND length(content) = 0
+             AND length(events_jsonl) < 200
+             AND events_jsonl NOT LIKE '%text_delta%'
+             AND events_jsonl NOT LIKE '%thinking_delta%'
+             AND events_jsonl NOT LIKE '%tool_call%'
+             AND events_jsonl NOT LIKE '%tool_result%'`)
+                .run();
+            if (cleanup.changes > 0) {
+                console.log(`[storage] Cleaned ${cleanup.changes} empty assistant message(s) from prior runs`);
+            }
+        }
+        catch (err) {
+            // Defensive: cleanup must never block startup. A failure here just
+            // leaves the rows in place — they were already harmless to the
+            // client (they hydrate to no segments and are skipped).
+            console.warn(`[storage] cleanup of empty assistant messages failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ---- project statements ----------------------------------------------
+        this.stmtListProjects = this.db.prepare(`
+      SELECT p.id, p.name, p.path, p.created_at, p.updated_at,
+             (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id) AS session_count
+      FROM projects p
+      ORDER BY p.updated_at DESC
+    `);
+        this.stmtGetProject = this.db.prepare(`SELECT id, name, path, created_at, updated_at FROM projects WHERE id = ?`);
+        this.stmtCreateProject = this.db.prepare(`INSERT INTO projects (id, name, path, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`);
+        this.stmtUpdateProject = this.db.prepare(`UPDATE projects SET name = ?, path = ?, updated_at = ? WHERE id = ?`);
+        this.stmtDeleteProject = this.db.prepare(`DELETE FROM projects WHERE id = ?`);
+        this.stmtListSessionsByProject = this.db.prepare(`
+      SELECT s.id, s.project_id, s.title, s.created_at, s.updated_at,
+             (SELECT COUNT(*) FROM messages m WHERE m.session_id = s.id) AS message_count
+      FROM sessions s
+      WHERE s.project_id = ?
+      ORDER BY s.updated_at DESC
+    `);
+        this.stmtListSessionIdsByProject = this.db.prepare(`SELECT id FROM sessions WHERE project_id = ?`);
+        // ---- session statements ----------------------------------------------
+        this.stmtGetSession = this.db.prepare(`SELECT id, project_id, title, created_at, updated_at FROM sessions WHERE id = ?`);
+        this.stmtCreateSession = this.db.prepare(`INSERT INTO sessions (id, project_id, title, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`);
+        this.stmtDeleteSession = this.db.prepare(`DELETE FROM sessions WHERE id = ?`);
+        this.stmtListMessages = this.db.prepare(`SELECT id, session_id, role, content, events_jsonl, created_at
+       FROM messages WHERE session_id = ? ORDER BY created_at ASC, id ASC`);
+        this.stmtAppendMessage = this.db.prepare(`INSERT INTO messages (id, session_id, role, content, events_jsonl, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        this.stmtTouchSession = this.db.prepare(`UPDATE sessions SET updated_at = ? WHERE id = ?`);
+        this.stmtRenameSession = this.db.prepare(`UPDATE sessions SET title = ?, updated_at = ? WHERE id = ?`);
+        this.stmtSessionWithCount = this.db.prepare(`
+      SELECT s.id, s.project_id, s.title, s.created_at, s.updated_at,
+             (SELECT COUNT(*) FROM messages m WHERE m.session_id = s.id) AS message_count
+      FROM sessions s
+      WHERE s.id = ?
+    `);
+        this.stmtGetSessionModel = this.db.prepare(`SELECT model_id FROM sessions WHERE id = ?`);
+        this.stmtSetSessionModel = this.db.prepare(`UPDATE sessions SET model_id = ? WHERE id = ?`);
+    }
+    /** Smoke check: returns the names of the tables in the DB. */
+    listTables() {
+        const rows = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type = 'table'`)
+            .all();
+        return rows.map((r) => r.name);
+    }
+    // ----------------------------------------------------------------------
+    // Projects
+    // ----------------------------------------------------------------------
+    listProjects() {
+        return this.stmtListProjects.all().map((r) => {
+            const project = {
+                id: r.id,
+                name: r.name,
+                path: r.path,
+                createdAt: r.created_at,
+                updatedAt: r.updated_at,
+                sessionCount: r.session_count,
+            };
+            return applyBindingFields(project);
+        });
+    }
+    createProject(input) {
+        const id = input.id ?? randomUUID();
+        const name = input.name.trim() || "Untitled project";
+        const path = input.path;
+        const now = Date.now();
+        this.stmtCreateProject.run(id, name, path, now, now);
+        return {
+            id,
+            name,
+            path,
+            createdAt: now,
+            updatedAt: now,
+            sessionCount: 0,
+        };
+    }
+    /** Returns null if not found. */
+    getProject(id) {
+        const row = this.stmtGetProject.get(id);
+        if (!row)
+            return null;
+        // Re-fetch with count to keep the wire shape consistent. Cheap.
+        const withCount = this.stmtListProjects.all().find((r) => r.id === id);
+        const project = {
+            id: row.id,
+            name: row.name,
+            path: row.path,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            sessionCount: withCount?.session_count ?? 0,
+        };
+        return applyBindingFields(project);
+    }
+    /**
+     * Update a project's name and/or path. At least one must be provided.
+     * Returns the updated project, or null if not found. Empty `name` falls
+     * back to "Untitled project" for parity with createProject.
+     */
+    updateProject(id, input) {
+        const existing = this.stmtGetProject.get(id);
+        if (!existing)
+            return null;
+        const nextName = input.name !== undefined
+            ? (input.name.trim() || "Untitled project")
+            : existing.name;
+        const nextPath = input.path !== undefined ? input.path : existing.path;
+        const now = Date.now();
+        this.stmtUpdateProject.run(nextName, nextPath, now, id);
+        return this.getProject(id);
+    }
+    /**
+     * Delete a project. Cascades to sessions and messages via FK.
+     * Caller MUST tear down any active SessionStream subscribers / pi
+     * processes for sessions in this project BEFORE invoking this.
+     * Returns the list of session ids that belonged to the project (so
+     * the caller can include them in the stream-teardown call).
+     */
+    deleteProject(id) {
+        const sessionIds = this.stmtListSessionIdsByProject.all(id).map((r) => r.id);
+        const info = this.stmtDeleteProject.run(id);
+        return { deleted: info.changes > 0, sessionIds };
+    }
+    /** Sessions belonging to a single project, newest-first. */
+    listSessionsByProject(projectId) {
+        return this.stmtListSessionsByProject.all(projectId).map((r) => ({
+            id: r.id,
+            projectId: r.project_id,
+            title: r.title,
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+            messageCount: r.message_count,
+        }));
+    }
+    // ----------------------------------------------------------------------
+    // Sessions
+    // ----------------------------------------------------------------------
+    createSession(input) {
+        if (!input.projectId) {
+            throw new Error("createSession requires projectId");
+        }
+        // Verify the project exists so we get a clean error rather than a raw
+        // FK violation at INSERT time.
+        const project = this.stmtGetProject.get(input.projectId);
+        if (!project)
+            throw new Error(`Unknown projectId: ${input.projectId}`);
+        const id = input.id ?? randomUUID();
+        const title = input.title?.trim() || "New conversation";
+        const now = Date.now();
+        this.stmtCreateSession.run(id, input.projectId, title, now, now);
+        // Touch the project so it floats to the top of the project list.
+        this.stmtUpdateProject.run(project.name, project.path, now, project.id);
+        return {
+            id,
+            projectId: input.projectId,
+            title,
+            createdAt: now,
+            updatedAt: now,
+            messageCount: 0,
+        };
+    }
+    /** Returns null if not found. */
+    getSession(id) {
+        const row = this.stmtGetSession.get(id);
+        if (!row)
+            return null;
+        const messages = this.getMessages(id);
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            title: row.title,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            messages,
+        };
+    }
+    /** Convenience for routes/managers that just need the projectId. */
+    getSessionProjectId(id) {
+        const row = this.stmtGetSession.get(id);
+        return row ? row.project_id : null;
+    }
+    getMessages(sessionId) {
+        return this.stmtListMessages.all(sessionId).map((r) => ({
+            id: r.id,
+            role: r.role,
+            content: r.content,
+            events: r.events_jsonl,
+            createdAt: r.created_at,
+        }));
+    }
+    /**
+     * Append a message and bump the session's updated_at in one transaction.
+     * Throws if the session doesn't exist (FK violation).
+     */
+    appendMessage(sessionId, msg) {
+        const id = msg.id ?? randomUUID();
+        const createdAt = msg.createdAt ?? Date.now();
+        const eventsJsonl = msg.eventsJsonl ?? "";
+        const tx = this.db.transaction(() => {
+            this.stmtAppendMessage.run(id, sessionId, msg.role, msg.content, eventsJsonl, createdAt);
+            this.stmtTouchSession.run(createdAt, sessionId);
+        });
+        tx();
+        return {
+            id,
+            role: msg.role,
+            content: msg.content,
+            events: eventsJsonl,
+            createdAt,
+        };
+    }
+    /**
+     * Rename a session. Bumps `updated_at`. Returns the updated summary, or
+     * null if the session doesn't exist. Title is trimmed; an empty title falls
+     * back to "New conversation" for parity with createSession().
+     */
+    renameSession(id, title) {
+        const trimmed = title.trim() || "New conversation";
+        const now = Date.now();
+        const info = this.stmtRenameSession.run(trimmed, now, id);
+        if (info.changes === 0)
+            return null;
+        const row = this.stmtSessionWithCount.get(id);
+        if (!row)
+            return null;
+        return {
+            id: row.id,
+            projectId: row.project_id,
+            title: row.title,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            messageCount: row.message_count,
+        };
+    }
+    /** Returns true if a row was deleted. Cascades to messages. */
+    deleteSession(id) {
+        const info = this.stmtDeleteSession.run(id);
+        return info.changes > 0;
+    }
+    // ----------------------------------------------------------------------
+    // Per-session sticky model (Phase 3 — Available Models whitelist)
+    // ----------------------------------------------------------------------
+    /**
+     * Get the persisted modelId for a session, or null if none was ever set or
+     * the session does not exist. The CLI uses this for cross-restart recovery:
+     * when an envelope arrives WITHOUT a `modelId` but SQLite has a value
+     * persisted from an earlier turn, we apply the persisted value before
+     * forwarding to pi. When neither envelope nor SQLite have a value, we
+     * leave model selection to pi's own settings file (pre-Phase-3 behaviour).
+     */
+    getSessionModel(sessionId) {
+        const row = this.stmtGetSessionModel.get(sessionId);
+        return row?.model_id ?? null;
+    }
+    /**
+     * Persist the modelId for a session. Pass `null` to clear. Does NOT bump
+     * `updated_at` — model selection is metadata, not user activity, so it
+     * shouldn't promote a session to the top of the sidebar. Silently no-ops
+     * when the session does not exist (the caller has already validated the
+     * sessionId via attach/getSession in the normal flow).
+     */
+    setSessionModel(sessionId, modelId) {
+        this.stmtSetSessionModel.run(modelId, sessionId);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+    }
+}
+export function preflightSqlite(dbPath) {
+    try {
+        const store = new SessionStore(dbPath);
+        // Touch the schema check to make sure the DB is readable.
+        store.listTables();
+        store.close();
+        return { ok: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: `Failed to load native sqlite module (${msg}).\n` +
+                `  This usually means the native binary couldn't be built for your Node.js version.\n` +
+                `  Try: cd ~/.spectral && npm rebuild better-sqlite3\n` +
+                `  Or reinstall: npm install -g @aexol/spectral`,
+        };
+    }
+}