@repo-os/repoos 0.5.45

package/dist/core/db.js

@@ -0,0 +1,747 @@
+/**
+ * SQLite database layer for RepoOS.
+ *
+ * Provides durable storage for session stats (time, tokens, cost) across all
+ * agent types. Uses bun:sqlite (Bun) or node:sqlite (Node >= 22), with graceful
+ * degradation if neither is available.
+ *
+ * Zero runtime dependencies — sqlite is a platform builtin.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+let Database;
+let dbAvailable = false;
+let sqliteLoadAttempted = false;
+// RepoOS is ESM, so the CommonJS global `require` is not available. Create a
+// local resolver for optional runtime builtins instead; otherwise telemetry
+// silently degrades even on Node versions that provide `node:sqlite`.
+const runtimeRequire = createRequire(import.meta.url);
+/**
+ * Load SQLite on first actual use, not at module import time. Node prints an
+ * ExperimentalWarning the moment `node:sqlite` is required on some Node
+ * versions — since this module is reachable from nearly every command's
+ * import graph, requiring it eagerly at the top of the file would fire that
+ * warning before the CLI even dispatches to a command, before anything has
+ * a chance to suppress it. Both Bun and Node 22+ have builtin sqlite support;
+ * we try Bun first, then fall back to node:sqlite, and gracefully degrade if
+ * neither is available.
+ */
+function loadSqlite() {
+    if (sqliteLoadAttempted)
+        return;
+    sqliteLoadAttempted = true;
+    try {
+        const global = globalThis;
+        if (global.Bun && typeof global.Bun === "object") {
+            // Running in Bun — use bun:sqlite if available
+            try {
+                const sqlite = runtimeRequire("bun:sqlite");
+                Database = sqlite.Database;
+                dbAvailable = true;
+            }
+            catch {
+                // bun:sqlite not available, try node:sqlite below
+            }
+        }
+        // Fallback to node:sqlite (Node 22+)
+        if (!dbAvailable) {
+            try {
+                const sqlite = runtimeRequire("node:sqlite");
+                Database = sqlite.DatabaseSync;
+                dbAvailable = true;
+            }
+            catch {
+                // node:sqlite not available — degrade gracefully
+            }
+        }
+    }
+    catch {
+        // Any error during initialization — degrade gracefully
+    }
+}
+/** Schema versions and their migrations. */
+const MIGRATIONS = [
+    {
+        version: 1,
+        up: `
+      CREATE TABLE IF NOT EXISTS sessions (
+        sessionId TEXT PRIMARY KEY,
+        sessionType TEXT NOT NULL,
+        taskId TEXT,
+        agent TEXT NOT NULL,
+        model TEXT NOT NULL,
+        codingAgent TEXT NOT NULL,
+        startedAt TEXT NOT NULL,
+        endedAt TEXT,
+        elapsedMs INTEGER NOT NULL DEFAULT 0,
+        inputTokens INTEGER,
+        outputTokens INTEGER,
+        totalTokens INTEGER,
+        costUsd REAL,
+        costSource TEXT NOT NULL DEFAULT 'none',
+        status TEXT NOT NULL DEFAULT 'active',
+        lastActivityAt TEXT NOT NULL,
+        createdAt TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updatedAt TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_taskId ON sessions(taskId);
+      CREATE INDEX IF NOT EXISTS idx_sessions_sessionType ON sessions(sessionType);
+      CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent);
+      CREATE INDEX IF NOT EXISTS idx_sessions_model ON sessions(model);
+      CREATE INDEX IF NOT EXISTS idx_sessions_startedAt ON sessions(startedAt);
+      CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version INTEGER PRIMARY KEY,
+        appliedAt TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+    `,
+    },
+    {
+        version: 2,
+        up: `
+      -- Allowed users with roles
+      CREATE TABLE IF NOT EXISTS auth_users (
+        email TEXT PRIMARY KEY,
+        role TEXT NOT NULL DEFAULT 'member',
+        display_name TEXT,
+        auth_source TEXT NOT NULL DEFAULT 'otp',
+        added_by TEXT,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+
+      -- Server-side sessions (hashed tokens)
+      CREATE TABLE IF NOT EXISTS auth_sessions (
+        session_id TEXT PRIMARY KEY,
+        token_hash TEXT NOT NULL UNIQUE,
+        email TEXT NOT NULL,
+        role TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_auth_sessions_token_hash ON auth_sessions(token_hash);
+      CREATE INDEX IF NOT EXISTS idx_auth_sessions_email ON auth_sessions(email);
+
+      -- OTP challenges (hashed codes)
+      CREATE TABLE IF NOT EXISTS auth_otp (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        email TEXT NOT NULL,
+        code_hash TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        expires_at TEXT NOT NULL,
+        used_at TEXT,
+        source_ip TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_auth_otp_email ON auth_otp(email);
+
+      -- Audit log for membership/role changes
+      CREATE TABLE IF NOT EXISTS auth_audit_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        action TEXT NOT NULL,
+        target_email TEXT,
+        actor_email TEXT,
+        details TEXT,
+        created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      );
+    `,
+    },
+    {
+        // Prompt-cache token visibility (Phase 0). Nullable — left NULL for any
+        // session whose CLI reported no cache figures, and for every row that
+        // predates this migration.
+        version: 3,
+        up: `
+      ALTER TABLE sessions ADD COLUMN cacheReadTokens INTEGER;
+      ALTER TABLE sessions ADD COLUMN cacheCreationTokens INTEGER;
+    `,
+    },
+    {
+        // Agent-turn (model round-trip) count per session. Nullable — NULL for a
+        // CLI that reports nothing countable, and for every pre-migration row.
+        version: 4,
+        up: `ALTER TABLE sessions ADD COLUMN turns INTEGER;`,
+    },
+    {
+        // Raw per-event usage capture. One row per usage-bearing CLI event
+        // (opencode `step_finish`, claude `result`/`assistant`, codex `usage`),
+        // recorded BEFORE the lossy fold into `sessions`. `sessions` is a derived
+        // rollup; this table is the ground truth you can rebuild it from and diff
+        // extraction bugs against. Append-only, best-effort.
+        version: 5,
+        up: `
+      CREATE TABLE IF NOT EXISTS session_usage_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        sessionId TEXT NOT NULL,
+        taskId TEXT,
+        agent TEXT,
+        model TEXT,
+        codingAgent TEXT,
+        eventType TEXT,
+        ts TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        inputTokens INTEGER,
+        outputTokens INTEGER,
+        totalTokens INTEGER,
+        cacheReadTokens INTEGER,
+        cacheCreationTokens INTEGER,
+        costUsd REAL,
+        turns INTEGER,
+        raw TEXT NOT NULL,
+        -- sessionId + hash(raw): the durable agent log is replayed verbatim on
+        -- server restart/adopt, so the same event line can arrive twice. A
+        -- UNIQUE key + INSERT OR IGNORE keeps this table idempotent under replay.
+        dedupeKey TEXT NOT NULL DEFAULT ''
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_usage_events_sessionId ON session_usage_events(sessionId);
+      CREATE INDEX IF NOT EXISTS idx_usage_events_taskId ON session_usage_events(taskId);
+      CREATE INDEX IF NOT EXISTS idx_usage_events_ts ON session_usage_events(ts);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_usage_events_dedupe ON session_usage_events(dedupeKey);
+    `,
+    },
+];
+/** Singleton database instance. */
+let dbInstance = null;
+/** Trailing-window duration in ms for each finite usage range. */
+const USAGE_RANGE_MS = {
+    "1d": 24 * 60 * 60 * 1000,
+    "7d": 7 * 24 * 60 * 60 * 1000,
+    "30d": 30 * 24 * 60 * 60 * 1000,
+};
+/** Database wrapper providing high-level operations. */
+export class RepoOSDb {
+    db;
+    available;
+    /**
+     * Open or create the database. If SQLite is not available, sets available=false
+     * and all operations become no-ops (fail-soft).
+     */
+    constructor(repoRoot) {
+        this.available = false;
+        loadSqlite();
+        if (!dbAvailable || !Database)
+            return;
+        try {
+            const cacheDir = join(repoRoot, ".repoos");
+            if (!existsSync(cacheDir)) {
+                mkdirSync(cacheDir, { recursive: true });
+            }
+            const dbPath = join(cacheDir, "repoos.db");
+            this.db = new Database(dbPath);
+            // Enable WAL mode for better concurrency
+            this.db.exec("PRAGMA journal_mode=WAL");
+            this.db.exec("PRAGMA synchronous=NORMAL");
+            // Only consider the store available once the schema is actually in place;
+            // a failed migration must degrade gracefully (available=false) rather than
+            // leave a half-initialized DB that silently no-ops every read (0230).
+            this.available = this.runMigrations();
+        }
+        catch {
+            // Initialization failed — graceful degradation
+        }
+    }
+    /** Apply pending migrations. Returns true only if the schema is in place. */
+    runMigrations() {
+        if (!this.db)
+            return false;
+        try {
+            let currentVersion = 0;
+            try {
+                const result = this.db
+                    .prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1")
+                    .all();
+                currentVersion = result.length > 0 ? result[0].version : 0;
+            }
+            catch {
+                // No schema_version yet — run all migrations below.
+                currentVersion = 0;
+            }
+            for (const migration of MIGRATIONS) {
+                if (migration.version > currentVersion) {
+                    this.db.exec(migration.up);
+                    this.db.exec(`INSERT INTO schema_version (version) VALUES (${migration.version})`);
+                }
+            }
+            return true;
+        }
+        catch {
+            // A migration failed — the schema is incomplete, so report unavailable.
+            return false;
+        }
+    }
+    isAvailable() {
+        return this.available;
+    }
+    /**
+     * Create or update a session record. The sessionId is unique; multiple turns
+     * update the same record (idempotent).
+     */
+    upsertSession(session) {
+        if (!this.available || !this.db)
+            return;
+        try {
+            const stmt = this.db.prepare(`
+        INSERT INTO sessions (
+          sessionId, sessionType, taskId, agent, model, codingAgent,
+          startedAt, endedAt, elapsedMs, inputTokens, outputTokens, totalTokens,
+          cacheReadTokens, cacheCreationTokens, turns,
+          costUsd, costSource, status, lastActivityAt, updatedAt
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+        ON CONFLICT(sessionId) DO UPDATE SET
+          -- A per-task cli/model override (or an agent switch mid-session) is
+          -- resolved by the time the agent actually runs, so a later upsert
+          -- carries the accurate CLI/model — the first insert may have used the
+          -- base config agent. Keep an existing real value only when the new
+          -- one is a bare fallback ("unknown"/"default"/"").
+          agent = CASE WHEN excluded.agent IN ('', 'unknown') THEN agent ELSE excluded.agent END,
+          model = CASE WHEN excluded.model IN ('', 'default') THEN model ELSE excluded.model END,
+          codingAgent = CASE WHEN excluded.codingAgent IN ('', 'unknown') THEN codingAgent ELSE excluded.codingAgent END,
+          endedAt = excluded.endedAt,
+          elapsedMs = excluded.elapsedMs,
+          inputTokens = COALESCE(excluded.inputTokens, inputTokens),
+          outputTokens = COALESCE(excluded.outputTokens, outputTokens),
+          totalTokens = COALESCE(excluded.totalTokens, totalTokens),
+          cacheReadTokens = COALESCE(excluded.cacheReadTokens, cacheReadTokens),
+          cacheCreationTokens = COALESCE(excluded.cacheCreationTokens, cacheCreationTokens),
+          turns = COALESCE(excluded.turns, turns),
+          costUsd = COALESCE(excluded.costUsd, costUsd),
+          costSource = excluded.costSource,
+          status = excluded.status,
+          lastActivityAt = excluded.lastActivityAt,
+          updatedAt = datetime('now')
+      `);
+            stmt.run(session.sessionId, session.sessionType, session.taskId ?? null, session.agent, session.model, session.codingAgent, session.startedAt, session.endedAt ?? null, session.elapsedMs, session.inputTokens ?? null, session.outputTokens ?? null, session.totalTokens ?? null, session.cacheReadTokens ?? null, session.cacheCreationTokens ?? null, session.turns ?? null, session.costUsd ?? null, session.costSource ?? "none", session.status ?? "active", session.lastActivityAt);
+        }
+        catch {
+            // Operation failed — continue gracefully
+        }
+    }
+    /**
+     * Append one raw usage-bearing CLI event, exactly as reported, before it is
+     * folded into the `sessions` rollup. Best-effort and append-only: a failure
+     * here never disturbs the session record or the request.
+     */
+    recordUsageEvent(ev) {
+        if (!this.available || !this.db)
+            return;
+        try {
+            const raw = ev.raw.length > 20_000 ? `${ev.raw.slice(0, 20_000)}…[truncated]` : ev.raw;
+            // djb2 hash — small, dependency-free, only needs to be stable, not secure.
+            let h = 5381;
+            for (let i = 0; i < ev.raw.length; i++)
+                h = ((h << 5) + h + ev.raw.charCodeAt(i)) | 0;
+            const dedupeKey = `${ev.sessionId}:${h >>> 0}`;
+            const stmt = this.db.prepare(`
+        INSERT OR IGNORE INTO session_usage_events (
+          sessionId, taskId, agent, model, codingAgent, eventType,
+          inputTokens, outputTokens, totalTokens,
+          cacheReadTokens, cacheCreationTokens, costUsd, turns, raw, dedupeKey
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            stmt.run(ev.sessionId, ev.taskId ?? null, ev.agent ?? null, ev.model ?? null, ev.codingAgent ?? null, ev.eventType ?? null, ev.inputTokens ?? null, ev.outputTokens ?? null, ev.totalTokens ?? null, ev.cacheReadTokens ?? null, ev.cacheCreationTokens ?? null, ev.costUsd ?? null, ev.turns ?? null, raw, dedupeKey);
+        }
+        catch {
+            // Append is best-effort — continue gracefully.
+        }
+    }
+    /** Retrieve a session record by ID. */
+    getSession(sessionId) {
+        if (!this.available || !this.db)
+            return null;
+        try {
+            const result = this.db.prepare("SELECT * FROM sessions WHERE sessionId = ?").all(sessionId);
+            return result.length > 0 ? result[0] : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Retrieve all sessions for a task. */
+    getTaskSessions(taskId) {
+        if (!this.available || !this.db)
+            return [];
+        try {
+            return this.db
+                .prepare("SELECT * FROM sessions WHERE taskId = ? ORDER BY startedAt DESC")
+                .all(taskId);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Aggregate stats for a task (all sessions and review rounds). */
+    getTaskStats(taskId) {
+        if (!this.available || !this.db)
+            return null;
+        try {
+            const rows = this.getTaskSessions(taskId);
+            if (rows.length === 0)
+                return null;
+            const agg = this.aggregateRows(rows);
+            return {
+                taskId,
+                totalSessions: agg.totalSessions,
+                totalElapsedMs: agg.totalElapsedMs,
+                totalInputTokens: agg.totalInputTokens,
+                totalOutputTokens: agg.totalOutputTokens,
+                totalTokens: agg.totalTokens,
+                totalCacheReadTokens: agg.totalCacheReadTokens,
+                totalCacheCreationTokens: agg.totalCacheCreationTokens,
+                totalTurns: agg.totalTurns,
+                totalCostUsd: agg.totalCostUsd,
+                costSource: agg.costSource,
+                roles: this.groupRows(rows, (r) => r.sessionType)
+                    .map(([role, group]) => this.toRoleStats(role, group))
+                    .sort((a, b) => b.totalElapsedMs - a.totalElapsedMs),
+                sessions: rows,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Cutoff ISO timestamp for a usage range's trailing window, or null for
+     * "all". `startedAt` is NOT NULL ISO text, so a lexicographic `>= ?`
+     * comparison against an ISO cutoff is correct — and `idx_sessions_startedAt`
+     * covers it.
+     */
+    usageRangeSince(range) {
+        if (range === "all")
+            return null;
+        return new Date(Date.now() - USAGE_RANGE_MS[range]).toISOString();
+    }
+    /**
+     * Aggregate totals broken down by day, using the server's LOCAL time zone
+     * (the day a session's `endedAt` falls into on this machine). Done in JS so
+     * the grouping genuinely reflects local wall-clock days rather than SQLite's
+     * UTC `date()`.
+     *
+     * The optional range filters on `startedAt` (0334) — the same predicate the
+     * headline totals use — so the per-day table always agrees with the board
+     * summary for the selected window.
+     */
+    getDailyTotals(range = "all") {
+        if (!this.available || !this.db)
+            return [];
+        try {
+            const since = this.usageRangeSince(range);
+            const rows = (since
+                ? this.db
+                    .prepare("SELECT * FROM sessions WHERE endedAt IS NOT NULL AND startedAt >= ?")
+                    .all(since)
+                : this.db.prepare("SELECT * FROM sessions WHERE endedAt IS NOT NULL").all());
+            const byDay = new Map();
+            for (const r of rows) {
+                const d = new Date(r.endedAt);
+                if (Number.isNaN(d.getTime()))
+                    continue;
+                const day = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+                const list = byDay.get(day);
+                if (list)
+                    list.push(r);
+                else
+                    byDay.set(day, [r]);
+            }
+            return [...byDay.entries()]
+                .map(([day, group]) => {
+                const agg = this.aggregateRows(group);
+                return {
+                    day,
+                    totalSessions: agg.totalSessions,
+                    totalElapsedMs: agg.totalElapsedMs,
+                    totalInputTokens: agg.totalInputTokens,
+                    totalOutputTokens: agg.totalOutputTokens,
+                    totalTokens: agg.totalTokens,
+                    totalCostUsd: agg.totalCostUsd,
+                    costSource: agg.costSource,
+                };
+            })
+                .sort((a, b) => (a.day < b.day ? 1 : -1));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Aggregate stats grouped by session type, optionally scoped to a usage range (0334). */
+    getSessionTypeStats(range = "all") {
+        if (!this.available || !this.db)
+            return [];
+        try {
+            const since = this.usageRangeSince(range);
+            const rows = (since
+                ? this.db.prepare("SELECT * FROM sessions WHERE startedAt >= ?").all(since)
+                : this.db.prepare("SELECT * FROM sessions").all());
+            return this.groupRows(rows, (r) => r.sessionType)
+                .map(([sessionType, group]) => {
+                const agg = this.aggregateRows(group);
+                return {
+                    sessionType,
+                    role: sessionType,
+                    totalSessions: agg.totalSessions,
+                    totalElapsedMs: agg.totalElapsedMs,
+                    totalInputTokens: agg.totalInputTokens,
+                    totalOutputTokens: agg.totalOutputTokens,
+                    totalTokens: agg.totalTokens,
+                    totalCacheReadTokens: agg.totalCacheReadTokens,
+                    totalCacheCreationTokens: agg.totalCacheCreationTokens,
+                    totalTurns: agg.totalTurns,
+                    totalCostUsd: agg.totalCostUsd,
+                    costSource: agg.costSource,
+                };
+            })
+                .sort((a, b) => (b.totalCostUsd ?? 0) - (a.totalCostUsd ?? 0));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Group sessions by a key, preserving insertion order of keys. */
+    groupRows(rows, key) {
+        const map = new Map();
+        for (const r of rows) {
+            const k = key(r);
+            const list = map.get(k);
+            if (list)
+                list.push(r);
+            else
+                map.set(k, [r]);
+        }
+        return [...map.entries()];
+    }
+    /** Build a single role's totals from a group of sessions. */
+    toRoleStats(role, rows) {
+        const agg = this.aggregateRows(rows);
+        return {
+            role,
+            totalSessions: agg.totalSessions,
+            totalElapsedMs: agg.totalElapsedMs,
+            totalInputTokens: agg.totalInputTokens,
+            totalOutputTokens: agg.totalOutputTokens,
+            totalTokens: agg.totalTokens,
+            totalCacheReadTokens: agg.totalCacheReadTokens,
+            totalCacheCreationTokens: agg.totalCacheCreationTokens,
+            totalTurns: agg.totalTurns,
+            totalCostUsd: agg.totalCostUsd,
+            costSource: agg.costSource,
+        };
+    }
+    /**
+     * Sum usage across a group of sessions. costSource is classified as "mixed"
+     * when the group's spend comes from more than one source, otherwise the
+     * single non-"none" source (or "none"). This drives honest labeling in the UI
+     * (estimates and Kiro credits are never silently shown as firm USD, 0230).
+     */
+    aggregateRows(rows) {
+        let totalSessions = 0;
+        let totalElapsedMs = 0;
+        let totalInputTokens = null;
+        let totalOutputTokens = null;
+        let totalTokens = null;
+        let totalCacheReadTokens = null;
+        let totalCacheCreationTokens = null;
+        let totalTurns = null;
+        let totalCostUsd = null;
+        const sources = new Set();
+        for (const r of rows) {
+            totalSessions += 1;
+            totalElapsedMs += r.elapsedMs || 0;
+            if (r.inputTokens != null)
+                totalInputTokens = (totalInputTokens ?? 0) + r.inputTokens;
+            if (r.outputTokens != null)
+                totalOutputTokens = (totalOutputTokens ?? 0) + r.outputTokens;
+            if (r.totalTokens != null)
+                totalTokens = (totalTokens ?? 0) + r.totalTokens;
+            if (r.cacheReadTokens != null)
+                totalCacheReadTokens = (totalCacheReadTokens ?? 0) + r.cacheReadTokens;
+            if (r.cacheCreationTokens != null)
+                totalCacheCreationTokens = (totalCacheCreationTokens ?? 0) + r.cacheCreationTokens;
+            if (r.turns != null)
+                totalTurns = (totalTurns ?? 0) + r.turns;
+            if (r.costUsd != null) {
+                totalCostUsd = (totalCostUsd ?? 0) + r.costUsd;
+                sources.add(r.costSource || "extractUsage");
+            }
+        }
+        let costSource = "none";
+        if (sources.size > 1)
+            costSource = "mixed";
+        else if (sources.size === 1)
+            costSource = [...sources][0];
+        return {
+            totalSessions,
+            totalElapsedMs,
+            totalInputTokens,
+            totalOutputTokens,
+            totalTokens,
+            totalCacheReadTokens,
+            totalCacheCreationTokens,
+            totalTurns,
+            totalCostUsd,
+            costSource,
+        };
+    }
+    /**
+     * Board-level summary: total spend, tokens, time, most expensive session/task.
+     * The optional range (0334) scopes every figure — headline totals, cost
+     * source, most-expensive lookups, roles, days — to sessions started within
+     * the trailing window, so all parts of the panel agree; "all" (the default)
+     * is the unfiltered pre-range behavior.
+     */
+    getBoardStats(range = "all") {
+        if (!this.available || !this.db) {
+            return {
+                totalSessions: 0,
+                totalElapsedMs: 0,
+                totalTokens: null,
+                totalCostUsd: null,
+                costSource: "none",
+                mostExpensiveSession: null,
+                mostExpensiveTask: null,
+                roles: [],
+                days: [],
+            };
+        }
+        try {
+            const since = this.usageRangeSince(range);
+            const startedFilter = since ? "WHERE startedAt >= ?" : "";
+            const startedFilterAnd = since ? "AND startedAt >= ?" : "";
+            const startedArgs = since ? [since] : [];
+            const summary = this.db
+                .prepare(`
+        SELECT
+          COUNT(*) as totalSessions,
+          COALESCE(SUM(elapsedMs), 0) as totalElapsedMs,
+          SUM(CASE WHEN totalTokens IS NOT NULL THEN totalTokens ELSE 0 END) as totalTokens,
+          SUM(CASE WHEN costUsd IS NOT NULL THEN costUsd ELSE 0 END) as totalCostUsd
+        FROM sessions
+        ${startedFilter}
+      `)
+                .all(...startedArgs)[0];
+            const mostExpensive = this.db
+                .prepare(`
+        SELECT * FROM sessions
+        WHERE costUsd IS NOT NULL
+        ${startedFilterAnd}
+        ORDER BY costUsd DESC
+        LIMIT 1
+      `)
+                .all(...startedArgs);
+            const mostExpensiveSession = mostExpensive.length > 0 ? mostExpensive[0] : null;
+            const mostExpensiveTaskResult = this.db
+                .prepare(`
+        SELECT
+          taskId,
+          SUM(CASE WHEN costUsd IS NOT NULL THEN costUsd ELSE 0 END) as costUsd
+        FROM sessions
+        WHERE taskId IS NOT NULL
+        ${startedFilterAnd}
+        GROUP BY taskId
+        ORDER BY costUsd DESC
+        LIMIT 1
+      `)
+                .all(...startedArgs);
+            const mostExpensiveTask = mostExpensiveTaskResult.length > 0
+                ? {
+                    taskId: mostExpensiveTaskResult[0].taskId,
+                    costUsd: mostExpensiveTaskResult[0].costUsd,
+                }
+                : null;
+            // Representative cost source across the (range-scoped) sessions — mirrors
+            // the per-role / per-day classification in aggregateRows so estimates and
+            // Kiro credits are never silently shown as firm USD at the board level
+            // (0230).
+            const sourceRows = this.db
+                .prepare(`SELECT DISTINCT COALESCE(costSource, 'extractUsage') as costSource FROM sessions WHERE costUsd IS NOT NULL ${startedFilterAnd}`)
+                .all(...startedArgs);
+            const costSource = sourceRows.length > 1
+                ? "mixed"
+                : sourceRows.length === 1
+                    ? sourceRows[0].costSource
+                    : "none";
+            return {
+                totalSessions: summary.totalSessions || 0,
+                totalElapsedMs: summary.totalElapsedMs || 0,
+                totalTokens: summary.totalTokens || null,
+                totalCostUsd: summary.totalCostUsd || null,
+                costSource,
+                mostExpensiveSession,
+                mostExpensiveTask,
+                roles: this.getSessionTypeStats(range),
+                days: this.getDailyTotals(range),
+            };
+        }
+        catch {
+            return {
+                totalSessions: 0,
+                totalElapsedMs: 0,
+                totalTokens: null,
+                totalCostUsd: null,
+                costSource: "none",
+                mostExpensiveSession: null,
+                mostExpensiveTask: null,
+                roles: [],
+                days: [],
+            };
+        }
+    }
+    /** Close the database connection. */
+    close() {
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch {
+                // Already closed or error during close
+            }
+            this.db = null;
+        }
+    }
+}
+/**
+ * Get or create the singleton database instance for a repo root.
+ * Returns null if SQLite is not available (graceful degradation).
+ */
+export function getRepoOSDb(repoRoot) {
+    if (!dbInstance) {
+        dbInstance = new RepoOSDb(repoRoot);
+    }
+    return dbInstance.isAvailable() ? dbInstance : null;
+}
+/** Reset the singleton (for tests). */
+export function resetDbInstance() {
+    if (dbInstance) {
+        dbInstance.close();
+    }
+    dbInstance = null;
+}
+/** Convenience function to get task stats from the singleton database. */
+export function getTaskStats(repoRoot, taskId) {
+    const db = getRepoOSDb(repoRoot);
+    return db?.getTaskStats(taskId) ?? null;
+}
+/** Convenience function to get session type stats from the singleton database. */
+export function getSessionTypeStats(repoRoot) {
+    const db = getRepoOSDb(repoRoot);
+    return db?.getSessionTypeStats() ?? [];
+}
+/** Convenience function to get board stats from the singleton database. */
+export function getBoardStats(repoRoot) {
+    const db = getRepoOSDb(repoRoot);
+    return (db?.getBoardStats() ?? {
+        totalSessions: 0,
+        totalElapsedMs: 0,
+        totalTokens: null,
+        totalCostUsd: null,
+        costSource: "none",
+        mostExpensiveSession: null,
+        mostExpensiveTask: null,
+        roles: [],
+        days: [],
+    });
+}