@roamcode.ai/server 1.0.0

package/dist/session-store.js

@@ -0,0 +1,654 @@
+import { createRequire } from "node:module";
+import { parseProviderOptions } from "./providers/options.js";
+import { normalizeSessionDefaults, SessionDefaultsConflictError, } from "./session-defaults.js";
+const require = createRequire(import.meta.url);
+const concreteSessionStores = new WeakSet();
+/** Internal trust check used by security-sensitive capabilities; only stores opened by this module are accepted. */
+export function isConcreteSessionStore(store) {
+    return concreteSessionStores.has(store);
+}
+function brandSessionStore(store) {
+    concreteSessionStores.add(store);
+    return store;
+}
+/** Parse the stored spawn_args JSON back into a string[] — tolerant: a NULL, malformed, or non-array value
+ *  (an ancient row, a hand-edited DB) yields undefined so the session simply respawns flag-less, never throws. */
+function parseSpawnArgs(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    try {
+        const v = JSON.parse(raw);
+        return Array.isArray(v) && v.every((x) => typeof x === "string") ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function legacyRowToSession(r) {
+    const spawnArgs = parseSpawnArgs(r.spawn_args);
+    return {
+        provider: "claude",
+        id: r.id,
+        cwd: r.cwd,
+        dangerouslySkip: r.dangerously_skip === 1,
+        status: r.status,
+        createdAt: r.created_at,
+        lastActivityAt: r.last_activity_at,
+        mode: "terminal",
+        // Only carry a REAL name — NULL/"" stays absent so consumers can `?? cwd` and toEqual-style tests
+        // of unnamed rows don't grow a noise field.
+        ...(typeof r.name === "string" && r.name.length > 0 ? { name: r.name } : {}),
+        ...(spawnArgs && spawnArgs.length > 0 ? { spawnArgs } : {}),
+    };
+}
+function parseCodexOptions(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("Invalid Codex launch options");
+    }
+    const { provider, ...options } = raw;
+    if (provider !== "codex")
+        throw new Error("Invalid Codex launch options provider");
+    return parseProviderOptions("codex", options);
+}
+function validateCodexOptions(options) {
+    return parseCodexOptions(options);
+}
+function validateProviderSessionId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.length > 2048 ||
+        /[\p{Cc}\p{Zl}\p{Zp}]/u.test(value)) {
+        throw new Error("Invalid provider session id");
+    }
+    return value;
+}
+function validateIntegrationStatus(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("Invalid integration status");
+    }
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.some((key) => !["attachments", "activity", "detail"].includes(key)) ||
+        (record.attachments !== "ready" && record.attachments !== "degraded") ||
+        (record.activity !== "ready" && record.activity !== "degraded") ||
+        (record.detail !== undefined && (typeof record.detail !== "string" || record.detail.length > 2048))) {
+        throw new Error("Invalid integration status");
+    }
+    return {
+        attachments: record.attachments,
+        activity: record.activity,
+        ...(typeof record.detail === "string" && record.detail.length > 0 ? { detail: record.detail } : {}),
+    };
+}
+function parseIntegrationStatus(raw) {
+    if (raw === null || raw.length === 0)
+        return undefined;
+    return validateIntegrationStatus(JSON.parse(raw));
+}
+function providerRowToSession(r) {
+    try {
+        if (r.provider !== "codex")
+            return undefined;
+        const launchOptions = parseCodexOptions(JSON.parse(r.launch_options_json));
+        const integrationStatus = parseIntegrationStatus(r.integration_status_json);
+        return {
+            provider: "codex",
+            id: r.id,
+            cwd: r.cwd,
+            status: r.status,
+            createdAt: r.created_at,
+            lastActivityAt: r.last_activity_at,
+            mode: "terminal",
+            launchOptions,
+            ...(typeof r.name === "string" && r.name.length > 0 ? { name: r.name } : {}),
+            ...(typeof r.provider_session_id === "string" && r.provider_session_id.length > 0
+                ? { providerSessionId: r.provider_session_id }
+                : {}),
+            ...(integrationStatus ? { integrationStatus } : {}),
+        };
+    }
+    catch {
+        // Keep corrupt rows in SQLite for diagnostics, but never surface them to a launcher.
+        return undefined;
+    }
+}
+function compareSessions(a, b) {
+    return a.createdAt - b.createdAt || a.id.localeCompare(b.id);
+}
+function cloneSession(session) {
+    if (session.provider === "claude") {
+        return { ...session, ...(session.spawnArgs ? { spawnArgs: [...session.spawnArgs] } : {}) };
+    }
+    return {
+        ...session,
+        launchOptions: {
+            ...session.launchOptions,
+            ...(session.launchOptions.addDirs ? { addDirs: [...session.launchOptions.addDirs] } : {}),
+        },
+        ...(session.integrationStatus ? { integrationStatus: { ...session.integrationStatus } } : {}),
+    };
+}
+function cloneStoredSessionDefaults(value) {
+    return {
+        defaults: normalizeSessionDefaults(value.defaults),
+        revision: value.revision,
+        updatedAt: value.updatedAt,
+    };
+}
+function appSettingRowToSessionDefaults(row) {
+    if (!row)
+        return undefined;
+    try {
+        return {
+            defaults: normalizeSessionDefaults(JSON.parse(row.value_json)),
+            revision: row.revision,
+            updatedAt: row.updated_at,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * In-memory fallback used when the native better-sqlite3 module cannot load
+ * (no toolchain / unsupported platform) so the server still boots. NOT durable
+ * across process restarts — surfaced as a diagnostic by the caller.
+ */
+function inMemoryStore() {
+    const map = new Map();
+    const provisionalProviderSessionIds = new Map();
+    let sessionDefaults;
+    const write = (s) => {
+        provisionalProviderSessionIds.delete(s.id);
+        if (s.provider === "codex") {
+            const launchOptions = validateCodexOptions(s.launchOptions);
+            const integrationStatus = s.integrationStatus ? validateIntegrationStatus(s.integrationStatus) : undefined;
+            const providerSessionId = validateProviderSessionId(s.providerSessionId);
+            map.set(s.id, cloneSession({
+                ...s,
+                mode: "terminal",
+                launchOptions,
+                ...(providerSessionId ? { providerSessionId } : {}),
+                ...(integrationStatus ? { integrationStatus } : {}),
+            }));
+            return;
+        }
+        if (s.provider !== "claude")
+            throw new Error("Unknown session provider");
+        map.set(s.id, cloneSession({ ...s, mode: "terminal" }));
+    };
+    return {
+        claimNew: (s) => {
+            if (map.has(s.id))
+                throw new Error(`Session id ${s.id} already exists`);
+            write(s);
+        },
+        upsert: (s) => {
+            const existing = map.get(s.id);
+            if (existing && existing.provider !== s.provider) {
+                throw new Error(`Session id ${s.id} already belongs to ${existing.provider}`);
+            }
+            write(s);
+        },
+        has: (id) => map.has(id),
+        get: (id) => {
+            const v = map.get(id);
+            return v ? cloneSession(v) : undefined;
+        },
+        list: () => [...map.values()].map(cloneSession).sort(compareSessions),
+        setStatus: (id, status) => {
+            const v = map.get(id);
+            if (v)
+                v.status = status;
+        },
+        touch: (id, at) => {
+            const v = map.get(id);
+            if (v)
+                v.lastActivityAt = at;
+        },
+        setName: (id, name) => {
+            const v = map.get(id);
+            if (!v)
+                return;
+            if (name === undefined)
+                delete v.name; // clear = the field goes back to absent, mirroring NULL
+            else
+                v.name = name;
+        },
+        setProviderSessionId: (id, value) => {
+            const v = map.get(id);
+            if (!v || v.provider !== "codex")
+                return;
+            const providerSessionId = validateProviderSessionId(value);
+            provisionalProviderSessionIds.delete(id);
+            if (providerSessionId === undefined)
+                delete v.providerSessionId;
+            else
+                v.providerSessionId = providerSessionId;
+        },
+        markProvisionalProviderSessionId: (id, value) => {
+            const v = map.get(id);
+            const providerSessionId = validateProviderSessionId(value);
+            if (!v || v.provider !== "codex" || v.providerSessionId !== undefined || provisionalProviderSessionIds.has(id)) {
+                throw new Error("Provisional provider identity unavailable");
+            }
+            provisionalProviderSessionIds.set(id, providerSessionId);
+        },
+        clearProvisionalProviderSessionId: (id, value) => {
+            if (provisionalProviderSessionIds.get(id) !== value)
+                throw new Error("Provisional provider identity changed");
+            provisionalProviderSessionIds.delete(id);
+        },
+        commitProvisionalProviderSessionId: (id, value) => {
+            const v = map.get(id);
+            if (!v ||
+                v.provider !== "codex" ||
+                v.providerSessionId !== undefined ||
+                provisionalProviderSessionIds.get(id) !== value) {
+                throw new Error("Provisional provider identity changed");
+            }
+            v.providerSessionId = value;
+            provisionalProviderSessionIds.delete(id);
+        },
+        getSessionDefaults: () => (sessionDefaults ? cloneStoredSessionDefaults(sessionDefaults) : undefined),
+        putSessionDefaults: (defaults, expectedRevision, updatedAt) => {
+            if ((sessionDefaults?.revision ?? 0) !== expectedRevision) {
+                throw new SessionDefaultsConflictError(sessionDefaults ? cloneStoredSessionDefaults(sessionDefaults) : undefined);
+            }
+            sessionDefaults = {
+                defaults: normalizeSessionDefaults(defaults),
+                revision: expectedRevision + 1,
+                updatedAt,
+            };
+            return cloneStoredSessionDefaults(sessionDefaults);
+        },
+        delete: (id) => {
+            provisionalProviderSessionIds.delete(id);
+            map.delete(id);
+        },
+        close: () => {
+            provisionalProviderSessionIds.clear();
+            map.clear();
+            sessionDefaults = undefined;
+        },
+        mode: "memory-fallback",
+    };
+}
+export function openSessionStore(opts) {
+    let Database;
+    try {
+        // Dynamic require keeps the native dep out of the module graph until needed
+        // and lets us fall back gracefully if the build is missing. Injectable so tests force the fallback.
+        if (opts.loadDatabase) {
+            Database = opts.loadDatabase();
+        }
+        else {
+            const mod = require("better-sqlite3");
+            Database = (mod.default ?? mod);
+        }
+    }
+    catch {
+        return brandSessionStore(inMemoryStore());
+    }
+    const db = new Database(opts.dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("busy_timeout = 5000");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      cwd TEXT NOT NULL,
+      dangerously_skip INTEGER NOT NULL DEFAULT 0,
+      status TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      last_activity_at INTEGER NOT NULL,
+      mode TEXT NOT NULL DEFAULT 'terminal',
+      name TEXT
+    )
+  `);
+    // TERMINAL-ONLY MIGRATION: a chat-era DB carries dead columns (model, effort, permission_mode,
+    // display_name, context_window) and possibly stale mode!='terminal' rows the app never surfaces.
+    // Drop the dead columns and prune the stale rows so the schema matches the terminal-only model. All
+    // guarded (best-effort): on a FRESH DB the columns don't exist ("no such column"); on an ancient SQLite
+    // DROP COLUMN may be unsupported — either way we swallow and boot with the columns simply unused.
+    for (const col of ["model", "effort", "permission_mode", "display_name", "context_window"]) {
+        try {
+            db.exec(`ALTER TABLE sessions DROP COLUMN ${col}`);
+        }
+        catch {
+            // column already gone (fresh DB) or DROP COLUMN unsupported — harmless, leave it be
+        }
+    }
+    // A pre-`mode` (Plan-5) DB lacks the column entirely; add it so the prune + queries below work.
+    try {
+        db.exec("ALTER TABLE sessions ADD COLUMN mode TEXT NOT NULL DEFAULT 'terminal'");
+    }
+    catch {
+        // column already exists — nothing to do
+    }
+    // Session-name migration: a pre-name DB gains the nullable column; existing rows read back name-less
+    // (NULL → the field stays absent), so old sessions are simply "unnamed" — no backfill needed.
+    try {
+        db.exec("ALTER TABLE sessions ADD COLUMN name TEXT");
+    }
+    catch {
+        // column already exists — nothing to do
+    }
+    // spawn-args migration: the user's chosen spawn flags (JSON), so a RESTART can respawn an ended session
+    // with the same model/effort/permission/danger/add-dir. A pre-spawn_args DB gains the nullable column;
+    // existing rows read back NULL → those sessions respawn flag-less (the old behavior), no backfill needed.
+    try {
+        db.exec("ALTER TABLE sessions ADD COLUMN spawn_args TEXT");
+    }
+    catch {
+        // column already exists — nothing to do
+    }
+    // Prune leftover non-terminal (chat) rows — never adopted or surfaced by the terminal app, just cruft.
+    try {
+        db.exec("DELETE FROM sessions WHERE mode IS NOT NULL AND mode != 'terminal'");
+    }
+    catch {
+        // best-effort — never block boot on the prune
+    }
+    // Rollback-safe provider migration: Codex rows live only in this additive table. The legacy `sessions`
+    // table remains byte-for-byte compatible with older builds, which continue to see Claude rows only.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS provider_sessions (
+      id TEXT PRIMARY KEY,
+      provider TEXT NOT NULL CHECK (provider = 'codex'),
+      cwd TEXT NOT NULL,
+      status TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      last_activity_at INTEGER NOT NULL,
+      name TEXT,
+      provider_session_id TEXT,
+      provisional_provider_session_id TEXT,
+      launch_options_json TEXT NOT NULL,
+      integration_status_json TEXT
+    );
+    CREATE INDEX IF NOT EXISTS provider_sessions_activity_idx
+      ON provider_sessions(last_activity_at DESC);
+
+    CREATE TABLE IF NOT EXISTS app_settings (
+      key TEXT PRIMARY KEY,
+      value_json TEXT NOT NULL,
+      revision INTEGER NOT NULL CHECK (revision > 0),
+      updated_at INTEGER NOT NULL
+    );
+  `);
+    try {
+        db.exec("ALTER TABLE provider_sessions ADD COLUMN provisional_provider_session_id TEXT");
+    }
+    catch {
+        // Column already exists on fresh/current databases.
+    }
+    // A previous process can only leave provisional state by terminating before cross-check/rollback.
+    // It is never resumable and is safe to discard before this process accepts work.
+    db.exec("UPDATE provider_sessions SET provisional_provider_session_id = NULL");
+    const legacyUpsertStmt = db.prepare(`
+    INSERT INTO sessions (id, cwd, dangerously_skip, status, created_at, last_activity_at, mode, name, spawn_args)
+    VALUES (@id, @cwd, @dangerously_skip, @status, @created_at, @last_activity_at, @mode, @name, @spawn_args)
+    ON CONFLICT(id) DO UPDATE SET
+      cwd=excluded.cwd, dangerously_skip=excluded.dangerously_skip,
+      status=excluded.status, created_at=excluded.created_at, last_activity_at=excluded.last_activity_at,
+      mode=excluded.mode, name=excluded.name, spawn_args=excluded.spawn_args
+  `);
+    const providerUpsertStmt = db.prepare(`
+    INSERT INTO provider_sessions (
+      id, provider, cwd, status, created_at, last_activity_at, name,
+      provider_session_id, provisional_provider_session_id, launch_options_json, integration_status_json
+    ) VALUES (
+      @id, @provider, @cwd, @status, @created_at, @last_activity_at, @name,
+      @provider_session_id, NULL, @launch_options_json, @integration_status_json
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      provider=excluded.provider, cwd=excluded.cwd, status=excluded.status,
+      created_at=excluded.created_at, last_activity_at=excluded.last_activity_at,
+      name=excluded.name, provider_session_id=excluded.provider_session_id,
+      provisional_provider_session_id=NULL, launch_options_json=excluded.launch_options_json,
+      integration_status_json=excluded.integration_status_json
+  `);
+    const legacyInsertStmt = db.prepare(`
+    INSERT INTO sessions (id, cwd, dangerously_skip, status, created_at, last_activity_at, mode, name, spawn_args)
+    VALUES (@id, @cwd, @dangerously_skip, @status, @created_at, @last_activity_at, @mode, @name, @spawn_args)
+  `);
+    const providerInsertStmt = db.prepare(`
+    INSERT INTO provider_sessions (
+      id, provider, cwd, status, created_at, last_activity_at, name,
+      provider_session_id, provisional_provider_session_id, launch_options_json, integration_status_json
+    ) VALUES (
+      @id, @provider, @cwd, @status, @created_at, @last_activity_at, @name,
+      @provider_session_id, NULL, @launch_options_json, @integration_status_json
+    )
+  `);
+    const legacyGetStmt = db.prepare("SELECT * FROM sessions WHERE id = ?");
+    const providerGetStmt = db.prepare("SELECT * FROM provider_sessions WHERE id = ?");
+    const legacyListStmt = db.prepare("SELECT * FROM sessions");
+    const providerListStmt = db.prepare("SELECT * FROM provider_sessions");
+    const legacyStatusStmt = db.prepare("UPDATE sessions SET status = ? WHERE id = ?");
+    const providerStatusStmt = db.prepare("UPDATE provider_sessions SET status = ? WHERE id = ?");
+    const legacyTouchStmt = db.prepare("UPDATE sessions SET last_activity_at = ? WHERE id = ?");
+    const providerTouchStmt = db.prepare("UPDATE provider_sessions SET last_activity_at = ? WHERE id = ?");
+    const legacyNameStmt = db.prepare("UPDATE sessions SET name = ? WHERE id = ?");
+    const providerNameStmt = db.prepare("UPDATE provider_sessions SET name = ? WHERE id = ?");
+    const providerSessionIdStmt = db.prepare("UPDATE provider_sessions SET provider_session_id = ?, provisional_provider_session_id = NULL WHERE id = ?");
+    const providerMarkProvisionalStmt = db.prepare(`
+    UPDATE provider_sessions
+    SET provisional_provider_session_id = ?
+    WHERE id = ? AND provider_session_id IS NULL AND provisional_provider_session_id IS NULL
+  `);
+    const providerClearProvisionalStmt = db.prepare(`
+    UPDATE provider_sessions
+    SET provisional_provider_session_id = NULL
+    WHERE id = ? AND provider_session_id IS NULL AND provisional_provider_session_id = ?
+  `);
+    const providerCommitProvisionalStmt = db.prepare(`
+    UPDATE provider_sessions
+    SET provider_session_id = ?, provisional_provider_session_id = NULL
+    WHERE id = ? AND provider_session_id IS NULL AND provisional_provider_session_id = ?
+  `);
+    const legacyDeleteStmt = db.prepare("DELETE FROM sessions WHERE id = ?");
+    const providerDeleteStmt = db.prepare("DELETE FROM provider_sessions WHERE id = ?");
+    const sessionDefaultsGetStmt = db.prepare("SELECT * FROM app_settings WHERE key = 'session_defaults'");
+    const sessionDefaultsPutStmt = db.prepare(`
+    INSERT INTO app_settings (key, value_json, revision, updated_at)
+    VALUES ('session_defaults', ?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET
+      value_json=excluded.value_json, revision=excluded.revision, updated_at=excluded.updated_at
+  `);
+    const ownerOf = (id) => {
+        const hasLegacy = legacyGetStmt.get(id) !== undefined;
+        const hasProvider = providerGetStmt.get(id) !== undefined;
+        // A cross-table id collision is ambiguous. Fail closed instead of mutating or launching the wrong owner.
+        if (hasLegacy === hasProvider)
+            return undefined;
+        return hasLegacy ? "claude" : "codex";
+    };
+    const upsertLegacyAtomically = db.transaction((s) => {
+        if (providerGetStmt.get(s.id) !== undefined) {
+            throw new Error(`Session id ${s.id} already belongs to codex`);
+        }
+        legacyUpsertStmt.run({
+            id: s.id,
+            cwd: s.cwd,
+            dangerously_skip: s.dangerouslySkip ? 1 : 0,
+            status: s.status,
+            created_at: s.createdAt,
+            last_activity_at: s.lastActivityAt,
+            mode: s.mode ?? "terminal",
+            name: s.name ?? null,
+            spawn_args: s.spawnArgs && s.spawnArgs.length > 0 ? JSON.stringify(s.spawnArgs) : null,
+        });
+    });
+    const upsertProviderAtomically = db.transaction((s, launchOptions, integrationStatus, providerSessionId) => {
+        if (legacyGetStmt.get(s.id) !== undefined) {
+            throw new Error(`Session id ${s.id} already belongs to claude`);
+        }
+        providerUpsertStmt.run({
+            id: s.id,
+            provider: "codex",
+            cwd: s.cwd,
+            status: s.status,
+            created_at: s.createdAt,
+            last_activity_at: s.lastActivityAt,
+            name: s.name ?? null,
+            provider_session_id: providerSessionId ?? null,
+            launch_options_json: JSON.stringify(launchOptions),
+            integration_status_json: integrationStatus ? JSON.stringify(integrationStatus) : null,
+        });
+    });
+    const claimLegacyAtomically = db.transaction((s) => {
+        if (legacyGetStmt.get(s.id) !== undefined || providerGetStmt.get(s.id) !== undefined) {
+            throw new Error(`Session id ${s.id} already exists`);
+        }
+        legacyInsertStmt.run({
+            id: s.id,
+            cwd: s.cwd,
+            dangerously_skip: s.dangerouslySkip ? 1 : 0,
+            status: s.status,
+            created_at: s.createdAt,
+            last_activity_at: s.lastActivityAt,
+            mode: s.mode ?? "terminal",
+            name: s.name ?? null,
+            spawn_args: s.spawnArgs && s.spawnArgs.length > 0 ? JSON.stringify(s.spawnArgs) : null,
+        });
+    });
+    const claimProviderAtomically = db.transaction((s, launchOptions, integrationStatus, providerSessionId) => {
+        if (legacyGetStmt.get(s.id) !== undefined || providerGetStmt.get(s.id) !== undefined) {
+            throw new Error(`Session id ${s.id} already exists`);
+        }
+        providerInsertStmt.run({
+            id: s.id,
+            provider: "codex",
+            cwd: s.cwd,
+            status: s.status,
+            created_at: s.createdAt,
+            last_activity_at: s.lastActivityAt,
+            name: s.name ?? null,
+            provider_session_id: providerSessionId ?? null,
+            launch_options_json: JSON.stringify(launchOptions),
+            integration_status_json: integrationStatus ? JSON.stringify(integrationStatus) : null,
+        });
+    });
+    const putSessionDefaultsAtomically = db.transaction((defaults, expectedRevision, updatedAt) => {
+        const row = sessionDefaultsGetStmt.get();
+        const current = appSettingRowToSessionDefaults(row);
+        if (row !== undefined && current === undefined) {
+            throw new SessionDefaultsConflictError(undefined);
+        }
+        if ((row?.revision ?? 0) !== expectedRevision) {
+            throw new SessionDefaultsConflictError(current ? cloneStoredSessionDefaults(current) : undefined);
+        }
+        const stored = {
+            defaults,
+            revision: (row?.revision ?? 0) + 1,
+            updatedAt,
+        };
+        sessionDefaultsPutStmt.run(JSON.stringify(defaults), stored.revision, updatedAt);
+        return cloneStoredSessionDefaults(stored);
+    });
+    return brandSessionStore({
+        claimNew: (s) => {
+            if (s.provider === "claude") {
+                claimLegacyAtomically.immediate(s);
+                return;
+            }
+            if (s.provider !== "codex")
+                throw new Error("Unknown session provider");
+            const launchOptions = validateCodexOptions(s.launchOptions);
+            const integrationStatus = s.integrationStatus ? validateIntegrationStatus(s.integrationStatus) : undefined;
+            const providerSessionId = validateProviderSessionId(s.providerSessionId);
+            claimProviderAtomically.immediate(s, launchOptions, integrationStatus, providerSessionId);
+        },
+        upsert: (s) => {
+            if (s.provider === "claude") {
+                upsertLegacyAtomically.immediate(s);
+                return;
+            }
+            if (s.provider !== "codex")
+                throw new Error("Unknown session provider");
+            const launchOptions = validateCodexOptions(s.launchOptions);
+            const integrationStatus = s.integrationStatus ? validateIntegrationStatus(s.integrationStatus) : undefined;
+            const providerSessionId = validateProviderSessionId(s.providerSessionId);
+            upsertProviderAtomically.immediate(s, launchOptions, integrationStatus, providerSessionId);
+        },
+        has: (id) => legacyGetStmt.get(id) !== undefined || providerGetStmt.get(id) !== undefined,
+        get: (id) => {
+            const owner = ownerOf(id);
+            if (owner === "claude") {
+                return legacyRowToSession(legacyGetStmt.get(id));
+            }
+            if (owner === "codex") {
+                return providerRowToSession(providerGetStmt.get(id));
+            }
+            return undefined;
+        },
+        list: () => {
+            const legacyRows = legacyListStmt.all();
+            const providerRows = providerListStmt.all();
+            const providerIds = new Set(providerRows.map((row) => row.id));
+            const ambiguousIds = new Set(legacyRows.filter((row) => providerIds.has(row.id)).map((row) => row.id));
+            const legacy = legacyRows.filter((row) => !ambiguousIds.has(row.id)).map(legacyRowToSession);
+            const provider = providerRows
+                .filter((row) => !ambiguousIds.has(row.id))
+                .map(providerRowToSession)
+                .filter((session) => session !== undefined);
+            return [...legacy, ...provider].sort(compareSessions);
+        },
+        setStatus: (id, status) => {
+            const owner = ownerOf(id);
+            if (owner === "claude")
+                legacyStatusStmt.run(status, id);
+            else if (owner === "codex")
+                providerStatusStmt.run(status, id);
+        },
+        touch: (id, at) => {
+            const owner = ownerOf(id);
+            if (owner === "claude")
+                legacyTouchStmt.run(at, id);
+            else if (owner === "codex")
+                providerTouchStmt.run(at, id);
+        },
+        setName: (id, name) => {
+            const owner = ownerOf(id);
+            if (owner === "claude")
+                legacyNameStmt.run(name ?? null, id);
+            else if (owner === "codex")
+                providerNameStmt.run(name ?? null, id);
+        },
+        setProviderSessionId: (id, value) => {
+            if (ownerOf(id) !== "codex")
+                return;
+            providerSessionIdStmt.run(validateProviderSessionId(value) ?? null, id);
+        },
+        markProvisionalProviderSessionId: (id, value) => {
+            const providerSessionId = validateProviderSessionId(value);
+            if (providerMarkProvisionalStmt.run(providerSessionId, id).changes !== 1) {
+                throw new Error("Provisional provider identity unavailable");
+            }
+        },
+        clearProvisionalProviderSessionId: (id, value) => {
+            if (providerClearProvisionalStmt.run(id, validateProviderSessionId(value)).changes !== 1) {
+                throw new Error("Provisional provider identity changed");
+            }
+        },
+        commitProvisionalProviderSessionId: (id, value) => {
+            const providerSessionId = validateProviderSessionId(value);
+            if (providerCommitProvisionalStmt.run(providerSessionId, id, providerSessionId).changes !== 1) {
+                throw new Error("Provisional provider identity changed");
+            }
+        },
+        getSessionDefaults: () => appSettingRowToSessionDefaults(sessionDefaultsGetStmt.get()),
+        putSessionDefaults: (defaults, expectedRevision, updatedAt) => putSessionDefaultsAtomically.immediate(normalizeSessionDefaults(defaults), expectedRevision, updatedAt),
+        delete: (id) => {
+            const owner = ownerOf(id);
+            if (owner === "claude")
+                legacyDeleteStmt.run(id);
+            else if (owner === "codex")
+                providerDeleteStmt.run(id);
+        },
+        close: () => db.close(),
+        mode: "sqlite",
+    });
+}

package/dist/start.d.ts

@@ -0,0 +1,31 @@
+import type { ClaudeAvailability, ClaudeVersionProbe } from "./diag.js";
+import type { CreateServerResult } from "./transport.js";
+import type { ProviderAvailability } from "./providers/types.js";
+export declare function providerPreflightWarning(name: string, availability: ProviderAvailability): string | undefined;
+export declare function runProviderPreflight(providers: ReadonlyArray<{
+    name: string;
+    probe(): Promise<ProviderAvailability>;
+}>, warn?: (msg: string) => void): Promise<void>;
+/**
+ * STARTUP PREFLIGHT (#7): format a prominent, actionable boot warning when `claude --version` couldn't
+ * run. The server still boots (sessions just won't start until the operator fixes it) — this is purely
+ * to surface WHY in the logs immediately, like the better-sqlite3 fallback warning. Returns `undefined`
+ * when claude is available (no warning). PURE so it's unit-testable without spawning.
+ */
+export declare function claudePreflightWarning(availability: ClaudeAvailability): string | undefined;
+/**
+ * Run the startup preflight: best-effort probe `claude --version` and print {@link claudePreflightWarning}
+ * if it's missing/failing. NEVER throws and NEVER blocks boot — a hung/slow claude can't stall startup
+ * (the probe is short-timeout-guarded). Injectable probe + log sink so it's testable without a spawn.
+ */
+export declare function runClaudePreflight(probe: ClaudeVersionProbe, warn?: (msg: string) => void): Promise<void>;
+export declare function startServer(env?: NodeJS.ProcessEnv): Promise<CreateServerResult & {
+    url: string;
+    token?: string;
+    tokenGenerated: boolean;
+}>;
+/** Install process-wide crash guards so a stray unhandled rejection or a listener-less EventEmitter
+ *  `error` (e.g. a write-after-teardown on a dying claude child, or a detached updater spawn failure)
+ *  LOGS instead of taking the whole server down — for an always-on self-hosted server, staying up beats
+ *  crashing. Install ONCE at a process entry (never in startServer, which tests call repeatedly). */
+export declare function installCrashGuards(): void;