@mxalbert/context-mode 2.0.0

package/build/session/db.js

@@ -0,0 +1,1330 @@
+/**
+ * SessionDB — Persistent per-project SQLite database for session events.
+ *
+ * Stores raw events captured by hooks during a Claude Code session,
+ * session metadata, and resume snapshots. Extends SQLiteBase from
+ * the shared package.
+ */
+import { SQLiteBase, defaultDBPath, logDbError } from "../db-base.js";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdirSync, realpathSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+// ─────────────────────────────────────────────────────────
+// Storage root resolution
+// ─────────────────────────────────────────────────────────
+//
+// This lives beside the session DB path helpers because packaged hooks and the
+// statusline already consume `hooks/session-db.bundle.mjs` as their no-build
+// runtime bridge. Keeping the storage resolver here avoids adding a second
+// generated hook bundle just to share CONTEXT_MODE_DIR behavior.
+const STORAGE_ROOT_ENV = "CONTEXT_MODE_DIR";
+const STORAGE_SESSIONS_SUBDIR = "sessions";
+const STORAGE_CONTENT_SUBDIR = "content";
+export class StorageDirectoryError extends Error {
+    kind;
+    path;
+    overrideEnvVar;
+    ignoredEnvVar;
+    ignoredReason;
+    constructor(kind, path, overrideEnvVar = STORAGE_ROOT_ENV, cause, message, metadata = {}) {
+        super(message ?? storageDirectoryErrorMessage(kind, path, metadata), { cause });
+        this.name = "StorageDirectoryError";
+        this.kind = kind;
+        this.path = path;
+        this.overrideEnvVar = overrideEnvVar;
+        this.ignoredEnvVar = metadata.ignoredEnvVar;
+        this.ignoredReason = metadata.ignoredReason;
+    }
+}
+const writableStorageCache = new Map();
+export function resolveDefaultSessionDir(opts) {
+    const env = opts.env ?? process.env;
+    const legacyEnvVar = opts.legacySessionDirEnv;
+    const legacy = legacyEnvVar ? env[legacyEnvVar]?.trim() : undefined;
+    if (legacy && legacyEnvVar) {
+        opts.onLegacySessionDir?.(legacyEnvVar, legacy);
+        return legacy;
+    }
+    return join(resolveConfigDirForDefaultSession(opts.configDir, opts.configDirEnv, env), "context-mode", "sessions");
+}
+function resolveConfigDirForDefaultSession(configDir, configDirEnv, env) {
+    const envValue = configDirEnv ? env[configDirEnv] : undefined;
+    if (envValue && envValue.trim() !== "") {
+        return resolveConfigDirValue(envValue.trim());
+    }
+    return resolveConfigDirValue(configDir, homedir());
+}
+function resolveConfigDirValue(value, baseDir) {
+    if (value.startsWith("~"))
+        return resolve(homedir(), value.replace(/^~[/\\]?/, ""));
+    if (isAbsolute(value))
+        return resolve(value);
+    return baseDir ? resolve(baseDir, value) : resolve(value);
+}
+function invalidStorageOverride(kind, path, detail) {
+    return new StorageDirectoryError(kind, path, STORAGE_ROOT_ENV, undefined, [`Invalid ${STORAGE_ROOT_ENV} for context-mode ${kind} directory: ${detail}`, storageDirectoryHint()].join("\n"));
+}
+function storageOverrideRoot(kind) {
+    const raw = process.env[STORAGE_ROOT_ENV];
+    if (raw === undefined)
+        return { kind: "unset" };
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return { kind: "ignored-empty", ignoredEnvVar: STORAGE_ROOT_ENV, ignoredReason: "empty" };
+    }
+    if (!isAbsolute(trimmed)) {
+        throw invalidStorageOverride(kind, trimmed, `${STORAGE_ROOT_ENV} must be an absolute path.`);
+    }
+    return { kind: "override", root: resolve(trimmed) };
+}
+function ignoredStorageMetadata(root) {
+    return root.kind === "ignored-empty"
+        ? { ignoredEnvVar: root.ignoredEnvVar, ignoredReason: root.ignoredReason }
+        : {};
+}
+function overrideStorageDir(kind, subdir) {
+    const root = storageOverrideRoot(kind);
+    if (root.kind !== "override")
+        return null;
+    return {
+        kind,
+        path: join(root.root, subdir),
+        envVar: STORAGE_ROOT_ENV,
+        source: "override",
+    };
+}
+function defaultStorageDir(kind, getDefaultDir, metadata) {
+    return {
+        kind,
+        path: resolve(getDefaultDir()),
+        envVar: null,
+        source: "default",
+        ...metadata,
+    };
+}
+export function resolveSessionStorageDir(getDefaultDir) {
+    const root = storageOverrideRoot("session");
+    if (root.kind === "override") {
+        return {
+            kind: "session",
+            path: join(root.root, STORAGE_SESSIONS_SUBDIR),
+            envVar: STORAGE_ROOT_ENV,
+            source: "override",
+        };
+    }
+    return defaultStorageDir("session", getDefaultDir, ignoredStorageMetadata(root));
+}
+export function resolveContentStorageDir(getSessionDir) {
+    const override = overrideStorageDir("content", STORAGE_CONTENT_SUBDIR);
+    if (override)
+        return override;
+    const session = resolveSessionStorageDir(getSessionDir);
+    return {
+        kind: "content",
+        path: join(dirname(session.path), STORAGE_CONTENT_SUBDIR),
+        envVar: session.envVar,
+        source: session.source,
+        ignoredEnvVar: session.ignoredEnvVar,
+        ignoredReason: session.ignoredReason,
+    };
+}
+export function resolveStatsStorageDir(getDefaultSessionDir) {
+    const override = overrideStorageDir("stats", STORAGE_SESSIONS_SUBDIR);
+    if (override)
+        return override;
+    const session = resolveSessionStorageDir(getDefaultSessionDir);
+    return {
+        kind: "stats",
+        path: session.path,
+        envVar: session.envVar,
+        source: session.source,
+        ignoredEnvVar: session.ignoredEnvVar,
+        ignoredReason: session.ignoredReason,
+    };
+}
+export function formatStorageDirectoryError(err) {
+    return err.message;
+}
+export function describeStorageDirectorySource(dir) {
+    if (dir.source === "override" && dir.envVar)
+        return `via ${dir.envVar}`;
+    if (dir.ignoredEnvVar && dir.ignoredReason === "empty")
+        return `default; ignored empty ${dir.ignoredEnvVar}`;
+    return "default";
+}
+export function clearStorageDirectoryCheckCacheForTests() {
+    writableStorageCache.clear();
+}
+export function ensureWritableStorageDir(dir) {
+    const key = [
+        dir.kind,
+        dir.path,
+        dir.source,
+        dir.envVar ?? "",
+        dir.ignoredEnvVar ?? "",
+        dir.ignoredReason ?? "",
+    ].join("\0");
+    const cached = writableStorageCache.get(key);
+    if (cached instanceof StorageDirectoryError)
+        throw cached;
+    if (cached === dir.path)
+        return cached;
+    try {
+        mkdirSync(dir.path, { recursive: true });
+        accessSync(dir.path, constants.W_OK);
+        writableStorageCache.set(key, dir.path);
+        return dir.path;
+    }
+    catch (err) {
+        const storageErr = new StorageDirectoryError(dir.kind, pathFromStorageError(err) ?? dir.path, STORAGE_ROOT_ENV, err, undefined, { ignoredEnvVar: dir.ignoredEnvVar, ignoredReason: dir.ignoredReason });
+        writableStorageCache.set(key, storageErr);
+        throw storageErr;
+    }
+}
+function storageDirectoryErrorMessage(kind, path, metadata = {}) {
+    return [
+        `context-mode ${kind} directory is not writable: ${path}`,
+        ignoredStorageOverrideHint(metadata),
+        storageDirectoryHint(),
+    ].filter(Boolean).join("\n");
+}
+function ignoredStorageOverrideHint(metadata) {
+    if (metadata.ignoredEnvVar && metadata.ignoredReason === "empty") {
+        return `Ignored empty ${metadata.ignoredEnvVar}; using adapter default.`;
+    }
+    return null;
+}
+function storageDirectoryHint() {
+    return `Set ${STORAGE_ROOT_ENV} to a writable absolute path.`;
+}
+function pathFromStorageError(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const path = err.path;
+    return typeof path === "string" && path.length > 0 ? path : null;
+}
+// ─────────────────────────────────────────────────────────
+// Worktree isolation
+// ─────────────────────────────────────────────────────────
+/**
+ * Returns the worktree suffix to append to session identifiers.
+ * Returns empty string when running in the main working tree.
+ *
+ * Set CONTEXT_MODE_SESSION_SUFFIX to an explicit value to override
+ * (useful in CI environments or when git is unavailable).
+ * Set to empty string to disable isolation entirely.
+ */
+// Memoized per (projectDir, env override) — recomputing on every tool call cost
+// ~12ms (git worktree list subprocess fork) on macOS, 50ms+ on Windows.
+// Key by projectDir so callers can pass the actual workspace even when the
+// MCP server has chdir'd into the installed package directory.
+let _wtCache;
+export function normalizeWorktreePath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (/^\/+$/.test(normalized))
+        return "/";
+    if (/^[A-Za-z]:\/+$/.test(normalized))
+        return `${normalized.slice(0, 2)}/`;
+    return normalized.replace(/\/+$/, "");
+}
+// Case-insensitive filesystems (macOS HFS+/APFS default, Windows NTFS default)
+// can report `currentRoot` and `mainRoot` with different casing for the same
+// physical directory — git itself sometimes preserves the on-disk casing while
+// user-supplied paths use a different casing. Compare canonically by resolving
+// symlinks via realpath and case-folding on these platforms. POSIX/Linux is
+// strictly case-sensitive so this is a no-op there.
+function canonicalizeForCompare(root) {
+    let resolved = root;
+    try {
+        resolved = realpathSync.native(root);
+    }
+    catch {
+        // Path may not exist (test fixtures, deleted dirs); fall back to as-given.
+    }
+    const normalized = normalizeWorktreePath(resolved);
+    if (process.platform === "win32" || process.platform === "darwin") {
+        return normalized.toLowerCase();
+    }
+    return normalized;
+}
+function gitOutput(projectDir, args) {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+        encoding: "utf-8",
+        timeout: 2000,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function getCurrentWorktreeRoot(projectDir) {
+    const root = gitOutput(projectDir, ["rev-parse", "--show-toplevel"]);
+    return root.length > 0 ? normalizeWorktreePath(root) : null;
+}
+function getMainWorktreeRoot(projectDir) {
+    const root = gitOutput(projectDir, ["worktree", "list", "--porcelain"])
+        .split(/\r?\n/)
+        .find((line) => line.startsWith("worktree "))
+        ?.replace("worktree ", "")
+        ?.trim();
+    return root ? normalizeWorktreePath(root) : null;
+}
+export function getWorktreeSuffix(projectDir = process.cwd()) {
+    const envSuffix = process.env.CONTEXT_MODE_SESSION_SUFFIX;
+    if (_wtCache && _wtCache.projectDir === projectDir && _wtCache.envSuffix === envSuffix) {
+        return _wtCache.suffix;
+    }
+    let suffix = "";
+    if (envSuffix !== undefined) {
+        suffix = envSuffix ? `__${envSuffix}` : "";
+    }
+    else {
+        try {
+            const currentRoot = getCurrentWorktreeRoot(projectDir);
+            const mainRoot = getMainWorktreeRoot(projectDir);
+            if (currentRoot && mainRoot) {
+                // Use the canonicalized currentRoot for BOTH the comparison and the
+                // hash so the suffix DB filename stays stable across casing-variant
+                // calls on the same machine (round-5 finding). Previously the hash
+                // ate raw casing, so the same linked worktree could land at two
+                // different `__<8-hex>` files depending on which casing the caller
+                // passed in.
+                const canonicalCurrent = canonicalizeForCompare(currentRoot);
+                const canonicalMain = canonicalizeForCompare(mainRoot);
+                if (canonicalCurrent !== canonicalMain) {
+                    suffix = `__${createHash("sha256").update(canonicalCurrent).digest("hex").slice(0, 8)}`;
+                }
+            }
+        }
+        catch {
+            // git not available or not a git repo — no suffix
+        }
+    }
+    _wtCache = { projectDir, envSuffix, suffix };
+    return suffix;
+}
+// Test-only helper: clear the memoization between cases.
+export function _resetWorktreeSuffixCacheForTests() {
+    _wtCache = undefined;
+}
+// ─────────────────────────────────────────────────────────
+// SessionDB path resolution + case-fold migration
+// ─────────────────────────────────────────────────────────
+/**
+ * Hash a project directory the way the deployed code (≤ v1.0.111) did:
+ * normalize slashes only, preserve raw casing. Kept exported so the
+ * migration helper can locate pre-fix DB files for one-shot rename.
+ *
+ * Do NOT call this for new code paths — use {@link hashProjectDirCanonical}.
+ */
+export function hashProjectDirLegacy(projectDir) {
+    return createHash("sha256")
+        .update(normalizeWorktreePath(projectDir))
+        .digest("hex")
+        .slice(0, 16);
+}
+/**
+ * Hash a project directory case-stably. On case-insensitive filesystems
+ * (macOS HFS+/APFS, Windows NTFS) the path is lowercased so that
+ * `/Users/Mert/proj` and `/users/mert/proj` resolve to the same DB file.
+ * On Linux (case-sensitive) casing is preserved.
+ *
+ * Used as the base half of the SessionDB filename:
+ *   <baseHash><worktreeSuffix>.db
+ */
+export function hashProjectDirCanonical(projectDir) {
+    const normalized = normalizeWorktreePath(projectDir);
+    const folded = (process.platform === "darwin" || process.platform === "win32")
+        ? normalized.toLowerCase()
+        : normalized;
+    return createHash("sha256").update(folded).digest("hex").slice(0, 16);
+}
+/**
+ * Resolve the per-project FTS5 content store DB path, performing a one-shot
+ * migration from a legacy raw-casing filename to the canonical one when only
+ * the legacy file (with optional `-wal` / `-shm` SQLite sidecars) exists.
+ *
+ * Same dual-hash safety contract as {@link resolveSessionDbPath}:
+ *   - Linux: canonical hash equals legacy hash → no migration attempted.
+ *   - Mac/Win: rename legacy → canonical when canonical missing.
+ *   - Both exist: leave legacy alone (data-loss safety). Caller picks
+ *     canonical; reconciliation is a manual operation.
+ *
+ * Differs from `resolveSessionDbPath` in two ways:
+ *   1. No worktree suffix — the FTS5 store is per-project, not per-worktree.
+ *   2. The `-wal` / `-shm` sidecars travel with the main `.db` during
+ *      migration so an active SQLite WAL checkpoint is not stranded behind.
+ */
+export function resolveContentStorePath(opts) {
+    const { projectDir, contentDir } = opts;
+    const canonicalHash = hashProjectDirCanonical(projectDir);
+    const canonicalPath = join(contentDir, `${canonicalHash}.db`);
+    if (existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyHash = hashProjectDirLegacy(projectDir);
+    if (legacyHash === canonicalHash)
+        return canonicalPath; // Linux short-circuit
+    const legacyPath = join(contentDir, `${legacyHash}.db`);
+    if (existsSync(legacyPath)) {
+        try {
+            renameSync(legacyPath, canonicalPath);
+            // Travel the SQLite sidecars too so an active WAL is not orphaned.
+            for (const suffix of ["-wal", "-shm"]) {
+                try {
+                    renameSync(legacyPath + suffix, canonicalPath + suffix);
+                }
+                catch { /* sidecar may not exist */ }
+            }
+        }
+        catch {
+            // Race or permission issue — caller will create canonicalPath fresh.
+        }
+    }
+    return canonicalPath;
+}
+/**
+ * Resolve the SessionDB file path for a project, performing a one-shot
+ * migration from legacy raw-casing filenames to canonical ones when only
+ * the legacy file exists.
+ *
+ * Migration rules:
+ *   - Linux: `legacyHash === canonicalHash` so the resolver short-circuits;
+ *     no migration ever runs (case-sensitive FS, never any drift).
+ *   - macOS / Windows: if the canonical path does not exist but a legacy
+ *     path does, rename in place. This preserves the user's session
+ *     history across the casing-fix upgrade.
+ *   - When BOTH paths exist (rare — usually only if the user previously
+ *     ran two terminals with different casing) the legacy file is left
+ *     UNTOUCHED. The canonical path wins; manual reconciliation needed.
+ *     Avoiding the rename here is the data-loss safety guarantee.
+ *
+ * Worktree separation is preserved: each call only ever migrates the ONE
+ * legacy file matching THIS projectDir's hash. Different worktrees have
+ * different physical paths → different hashes → different DB files; the
+ * migration cannot collapse worktrees.
+ */
+export function resolveSessionDbPath(opts) {
+    return resolveSessionPath({ ...opts, ext: ".db" });
+}
+/**
+ * Generalized resolver: same case-fold + one-shot legacy-rename semantics
+ * as {@link resolveSessionDbPath}, parameterised on the file extension so
+ * the SAME logic powers `.db`, `-events.md`, and `.cleanup` paths.
+ *
+ * Source of truth for hooks: `hooks/session-helpers.mjs` imports this
+ * function from the bundled output (`hooks/session-db.bundle.mjs`) so the
+ * JS hooks and the TS server can never drift again on hash, suffix, or
+ * migration policy.
+ *
+ * Optional `suffix` lets the hook layer inject its cross-process cached
+ * worktree suffix (the marker-file optimisation that amortises the
+ * `git worktree list` cost across hook forks). When omitted, falls back
+ * to {@link getWorktreeSuffix} which uses an in-process cache only.
+ */
+export function resolveSessionPath(opts) {
+    const { projectDir, sessionsDir, ext } = opts;
+    const suffix = opts.suffix ?? getWorktreeSuffix(projectDir);
+    const canonicalHash = hashProjectDirCanonical(projectDir);
+    const canonicalPath = join(sessionsDir, `${canonicalHash}${suffix}${ext}`);
+    if (existsSync(canonicalPath))
+        return canonicalPath;
+    const legacyHash = hashProjectDirLegacy(projectDir);
+    if (legacyHash === canonicalHash)
+        return canonicalPath; // Linux or already canonical
+    const legacyPath = join(sessionsDir, `${legacyHash}${suffix}${ext}`);
+    if (existsSync(legacyPath)) {
+        try {
+            renameSync(legacyPath, canonicalPath);
+        }
+        catch {
+            // Race or permission issue — caller will create canonicalPath on first
+            // write. Better to lose this rename than to throw and break ctx_stats.
+        }
+    }
+    return canonicalPath;
+}
+// ─────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────
+/** Maximum events per session before FIFO eviction kicks in. */
+const MAX_EVENTS_PER_SESSION = 1000;
+/** Number of recent events to check for deduplication. */
+const DEDUP_WINDOW = 5;
+/**
+ * Coerce an arbitrary input to a non-negative integer suitable for
+ * SQLite's INTEGER column. Accepts undefined / null / NaN / floats
+ * and returns 0 for invalid inputs so the column never violates its
+ * NOT NULL DEFAULT 0 contract.
+ */
+function clampNonNegativeInt(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.floor(n);
+}
+// ─────────────────────────────────────────────────────────
+// Statement keys (typed enum to avoid string typos)
+// ─────────────────────────────────────────────────────────
+const S = {
+    insertEvent: "insertEvent",
+    getEvents: "getEvents",
+    getEventsByType: "getEventsByType",
+    getEventsByPriority: "getEventsByPriority",
+    getEventsByTypeAndPriority: "getEventsByTypeAndPriority",
+    getEventCount: "getEventCount",
+    getLatestAttributedProject: "getLatestAttributedProject",
+    checkDuplicate: "checkDuplicate",
+    evictLowestPriority: "evictLowestPriority",
+    updateMetaLastEvent: "updateMetaLastEvent",
+    ensureSession: "ensureSession",
+    getSessionStats: "getSessionStats",
+    getSessionRollup: "getSessionRollup",
+    getMaxFileEdits: "getMaxFileEdits",
+    getLatestCommitMessage: "getLatestCommitMessage",
+    incrementCompactCount: "incrementCompactCount",
+    getUsageCursor: "getUsageCursor",
+    setUsageCursor: "setUsageCursor",
+    upsertResume: "upsertResume",
+    getResume: "getResume",
+    markResumeConsumed: "markResumeConsumed",
+    claimLatestUnconsumedResume: "claimLatestUnconsumedResume",
+    deleteEvents: "deleteEvents",
+    deleteMeta: "deleteMeta",
+    deleteResume: "deleteResume",
+    getOldSessions: "getOldSessions",
+    searchEvents: "searchEvents",
+    incrementToolCall: "incrementToolCall",
+    getToolCallTotals: "getToolCallTotals",
+    getToolCallByTool: "getToolCallByTool",
+    getEventBytesSummary: "getEventBytesSummary",
+};
+// ─────────────────────────────────────────────────────────
+// Schema migration helpers (shared with the analytics aggregator)
+// ─────────────────────────────────────────────────────────
+/**
+ * Columns that the current `session_events` schema requires but earlier
+ * versions of context-mode did not write. Older DBs on disk are missing
+ * these — the analytics aggregator opens every DB it finds across all
+ * adapters, so without an in-place migration the SUM queries below fail
+ * the entire DB (the catch at the top of the read loop swallows the
+ * "no such column" error and the DB contributes zero to every column,
+ * not just the new ones). v1.0.148 hotfix.
+ */
+const SESSION_EVENTS_REQUIRED_COLUMNS = [
+    ["project_dir", "TEXT NOT NULL DEFAULT ''"],
+    ["attribution_source", "TEXT NOT NULL DEFAULT 'unknown'"],
+    ["attribution_confidence", "REAL NOT NULL DEFAULT 0"],
+    ["bytes_avoided", "INTEGER NOT NULL DEFAULT 0"],
+    ["bytes_returned", "INTEGER NOT NULL DEFAULT 0"],
+];
+/**
+ * Apply any missing post-v1.0.130 `session_events` columns to an already-
+ * open writable database handle. Idempotent — each ALTER is guarded by a
+ * PRAGMA table_xinfo check, and the project_dir index is created only
+ * when a migration actually ran. Returns true if any column was added.
+ *
+ * Used by both the SessionDB constructor (for the active DB) and the
+ * analytics aggregator (for the 100+ historical DBs that never get
+ * opened through SessionDB). ADR-0001 compatible: no EXCLUSIVE pragma,
+ * no acquireDbLock — relies on the SQLite busy_timeout + WAL semantics
+ * already provided by SQLiteBase.
+ */
+export function applyMissingSessionEventsColumns(db) {
+    const colInfo = db.pragma("table_xinfo(session_events)");
+    const cols = new Set(colInfo.map((c) => c.name));
+    let changed = false;
+    for (const [name, spec] of SESSION_EVENTS_REQUIRED_COLUMNS) {
+        if (!cols.has(name)) {
+            db.exec(`ALTER TABLE session_events ADD COLUMN ${name} ${spec}`);
+            changed = true;
+        }
+    }
+    if (changed) {
+        db.exec("CREATE INDEX IF NOT EXISTS idx_session_events_project ON session_events(session_id, project_dir)");
+    }
+    return changed;
+}
+/**
+ * Open a session DB file briefly, run any missing schema migrations,
+ * and close. Best-effort: missing tables, file-locks, corrupt files,
+ * and any DatabaseCtor error are swallowed silently — the caller
+ * (analytics aggregator) handles the readonly query that follows and
+ * will skip the DB if it remains unreadable.
+ *
+ * Lazy migration entry point for the analytics aggregator, which would
+ * otherwise read 100+ historical DBs with the old (pre-v1.0.130) schema
+ * and lose every signal (not just bytes_avoided) because the SELECT
+ * statement references columns that don't exist on legacy schemas.
+ *
+ * Two open/close cycles in the worst case (one readonly probe to detect
+ * legacy schema, one writable to migrate). For already-migrated DBs
+ * (the common case after first read), this opens writable once and
+ * exits without writing — cheaper than always-writable.
+ */
+export function ensureSessionEventsSchema(dbPath, DatabaseCtor) {
+    let db = null;
+    try {
+        db = new DatabaseCtor(dbPath);
+        applyMissingSessionEventsColumns(db);
+    }
+    catch (err) {
+        // best-effort — missing table, file lock, corrupt DB, or DatabaseCtor
+        // load failure. The aggregator's existing skip-on-error handles the
+        // downstream readonly query. Logged (rate-limited) so transient
+        // SQLITE_IOERR / lock storms are diagnosable instead of invisible.
+        logDbError("ensureSessionEventsSchema", err, dbPath);
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+// ─────────────────────────────────────────────────────────
+// SessionDB
+// ─────────────────────────────────────────────────────────
+export class SessionDB extends SQLiteBase {
+    constructor(opts) {
+        super(opts?.dbPath ?? defaultDBPath("session"));
+    }
+    /** Shorthand to retrieve a cached statement. */
+    stmt(key) {
+        return this.stmts.get(key);
+    }
+    // ── Schema ──
+    initSchema() {
+        // ── Migration: fix data_hash generated column from older schema ──
+        // Old schema had data_hash as GENERATED ALWAYS AS — new schema uses explicit INSERT.
+        // Detect and recreate table if needed (session data is ephemeral, safe to drop).
+        // `?? []` — bun:sqlite's adapter returns undefined for a missing table's
+        // table_xinfo; without the fallback this catch fired a TypeError on
+        // EVERY fresh DB, which would make the logging below log-storm on
+        // healthy opens. With it, the catch only fires on real DB failures.
+        try {
+            const colInfo = (this.db.pragma("table_xinfo(session_events)") ?? []);
+            const hashCol = colInfo.find((c) => c.name === "data_hash");
+            if (hashCol && hashCol.hidden !== 0) {
+                // hidden != 0 means generated column — must recreate
+                this.db.exec("DROP TABLE session_events");
+            }
+        }
+        catch (err) {
+            logDbError("SessionDB.initSchema.dataHashMigration", err, this.dbPath);
+        }
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS session_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        category TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 2,
+        data TEXT NOT NULL,
+        project_dir TEXT NOT NULL DEFAULT '',
+        attribution_source TEXT NOT NULL DEFAULT 'unknown',
+        attribution_confidence REAL NOT NULL DEFAULT 0,
+        bytes_avoided INTEGER NOT NULL DEFAULT 0,
+        bytes_returned INTEGER NOT NULL DEFAULT 0,
+        source_hook TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        data_hash TEXT NOT NULL DEFAULT ''
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session_events_session ON session_events(session_id);
+      CREATE INDEX IF NOT EXISTS idx_session_events_type ON session_events(session_id, type);
+      CREATE INDEX IF NOT EXISTS idx_session_events_priority ON session_events(session_id, priority);
+
+      CREATE TABLE IF NOT EXISTS session_meta (
+        session_id TEXT PRIMARY KEY,
+        project_dir TEXT NOT NULL,
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_event_at TEXT,
+        event_count INTEGER NOT NULL DEFAULT 0,
+        compact_count INTEGER NOT NULL DEFAULT 0
+      );
+
+      CREATE TABLE IF NOT EXISTS session_resume (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL UNIQUE,
+        snapshot TEXT NOT NULL,
+        event_count INTEGER NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        consumed INTEGER NOT NULL DEFAULT 0
+      );
+
+      CREATE TABLE IF NOT EXISTS tool_calls (
+        session_id TEXT NOT NULL,
+        tool TEXT NOT NULL,
+        calls INTEGER NOT NULL DEFAULT 0,
+        bytes_returned INTEGER NOT NULL DEFAULT 0,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (session_id, tool)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id);
+    `);
+        // Migration: add per-event attribution columns for existing DBs.
+        // Shared helper — the analytics aggregator (analytics.ts) runs the
+        // SAME migration against every historical DB it scans, so the column
+        // list lives in one place at the top of this module.
+        try {
+            applyMissingSessionEventsColumns(this.db);
+        }
+        catch (err) {
+            // best-effort migration only — but surface it (rate-limited) so a
+            // repeatedly failing migration is diagnosable.
+            logDbError("SessionDB.initSchema.migrateColumns", err, this.dbPath);
+        }
+        // Migration: per-session usage high-water cursor for the Stop hook's
+        // cursor-aware main-turn capture (extractTranscriptUsageSince). Stores the
+        // uuid of the last assistant turn already emitted so the next Stop forwards
+        // only NEW spend. Idempotent — guarded by a table_xinfo column check.
+        try {
+            const metaCols = (this.db.pragma("table_xinfo(session_meta)") ?? []);
+            if (!metaCols.some((c) => c.name === "usage_cursor")) {
+                this.db.exec("ALTER TABLE session_meta ADD COLUMN usage_cursor TEXT");
+            }
+        }
+        catch (err) {
+            // best-effort migration only — surface it (rate-limited).
+            logDbError("SessionDB.initSchema.usageCursorMigration", err, this.dbPath);
+        }
+    }
+    prepareStatements() {
+        this.stmts = new Map();
+        const p = (key, sql) => {
+            this.stmts.set(key, this.db.prepare(sql));
+        };
+        // ── Events ──
+        p(S.insertEvent, `INSERT INTO session_events (
+         session_id, type, category, priority, data,
+         project_dir, attribution_source, attribution_confidence,
+         bytes_avoided, bytes_returned,
+         source_hook, data_hash
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        p(S.getEvents, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              bytes_avoided, bytes_returned,
+              source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByType, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              bytes_avoided, bytes_returned,
+              source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND type = ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByPriority, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              bytes_avoided, bytes_returned,
+              source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND priority >= ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventsByTypeAndPriority, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              bytes_avoided, bytes_returned,
+              source_hook, created_at, data_hash
+       FROM session_events WHERE session_id = ? AND type = ? AND priority >= ? ORDER BY id ASC LIMIT ?`);
+        p(S.getEventCount, `SELECT COUNT(*) AS cnt FROM session_events WHERE session_id = ?`);
+        p(S.getLatestAttributedProject, `SELECT project_dir
+       FROM session_events
+       WHERE session_id = ? AND project_dir != ''
+       ORDER BY id DESC
+       LIMIT 1`);
+        p(S.checkDuplicate, `SELECT 1 FROM (
+         SELECT type, data_hash FROM session_events
+         WHERE session_id = ? ORDER BY id DESC LIMIT ?
+       ) AS recent
+       WHERE recent.type = ? AND recent.data_hash = ?
+       LIMIT 1`);
+        p(S.evictLowestPriority, `DELETE FROM session_events WHERE id = (
+         SELECT id FROM session_events WHERE session_id = ?
+         ORDER BY priority ASC, id ASC LIMIT 1
+       )`);
+        p(S.updateMetaLastEvent, `UPDATE session_meta
+       SET last_event_at = datetime('now'), event_count = event_count + 1
+       WHERE session_id = ?`);
+        // ── Meta ──
+        p(S.ensureSession, `INSERT OR IGNORE INTO session_meta (session_id, project_dir) VALUES (?, ?)`);
+        p(S.getSessionStats, `SELECT session_id, project_dir, started_at, last_event_at, event_count, compact_count
+       FROM session_meta WHERE session_id = ?`);
+        // ── Session rollup (seed-parity aggregator) ────────────────────────
+        // Single query producing 9 of the 12 platform-side session_summary +
+        // session_metadata fields. Computed against the local SessionDB
+        // session_events table at forward time so every outgoing canonical
+        // event carries a session-wide snapshot at that moment — matches the
+        // seed.ts shape where each event row has tool_calls/errors/etc. stamped.
+        // max_file_edits and edit_test_cycles need separate GROUP BY queries
+        // (below). compact_count is read from session_meta (already in getSessionStats).
+        p(S.getSessionRollup, `SELECT
+         COUNT(*) AS tool_calls,
+         COALESCE(SUM(CASE WHEN category = 'error' THEN 1 ELSE 0 END), 0) AS errors,
+         COUNT(DISTINCT type) AS unique_tools,
+         COUNT(DISTINCT CASE WHEN category = 'file' THEN data END) AS unique_files,
+         CASE WHEN SUM(CASE WHEN type = 'git_commit' THEN 1 ELSE 0 END) > 0 THEN 1 ELSE 0 END AS has_commit,
+         CAST(COALESCE((MAX(strftime('%s', created_at)) - MIN(strftime('%s', created_at))) / 60.0, 0) AS INTEGER) AS duration_min,
+         COALESCE(SUM(CASE WHEN type = 'external_ref' THEN 1 ELSE 0 END), 0) AS sources_indexed,
+         CAST(COALESCE(SUM(bytes_avoided) / 1024.0, 0) AS INTEGER) AS total_chunks,
+         COALESCE(SUM(CASE WHEN type IN ('file_search', 'file_glob') THEN 1 ELSE 0 END), 0) AS search_queries
+       FROM session_events
+       WHERE session_id = ?`);
+        // max_file_edits: max edits on any single file path in the session.
+        // Two-level aggregation — GROUP BY data first, then MAX of those counts.
+        p(S.getMaxFileEdits, `SELECT COALESCE(MAX(c), 0) AS max_file_edits
+       FROM (
+         SELECT COUNT(*) AS c
+         FROM session_events
+         WHERE session_id = ? AND category = 'file' AND type IN ('file_edit', 'file_write')
+         GROUP BY data
+       )`);
+        // v1.0.161 (Bug 2): latest commit message from session's type='git_commit'
+        // events. Used by rollup spread to stamp commit_message symmetric with
+        // has_commit on every outgoing event. Separate prepared statement (vs.
+        // sub-select in getSessionRollup) keeps the binding shape uniform — every
+        // rollup query takes a single sessionId parameter.
+        p(S.getLatestCommitMessage, `SELECT data
+       FROM session_events
+       WHERE session_id = ? AND type = 'git_commit'
+       ORDER BY id DESC
+       LIMIT 1`);
+        p(S.incrementCompactCount, `UPDATE session_meta SET compact_count = compact_count + 1 WHERE session_id = ?`);
+        p(S.getUsageCursor, `SELECT usage_cursor FROM session_meta WHERE session_id = ?`);
+        p(S.setUsageCursor, `UPDATE session_meta SET usage_cursor = ? WHERE session_id = ?`);
+        // ── Resume ──
+        p(S.upsertResume, `INSERT INTO session_resume (session_id, snapshot, event_count)
+       VALUES (?, ?, ?)
+       ON CONFLICT(session_id) DO UPDATE SET
+         snapshot = excluded.snapshot,
+         event_count = excluded.event_count,
+         created_at = datetime('now'),
+         consumed = 0`);
+        p(S.getResume, `SELECT snapshot, event_count, consumed FROM session_resume WHERE session_id = ?`);
+        p(S.markResumeConsumed, `UPDATE session_resume SET consumed = 1 WHERE session_id = ?`);
+        // Atomic "pick newest unconsumed snapshot AND mark it consumed in one
+        // statement". Required for race-safe cross-session resume injection
+        // (Mickey / PR #376) — two parallel chat-turn hooks must not both read
+        // the same row before either one writes consumed=1.
+        //
+        // The `session_id != ?` clause prevents self-injection (v1.0.106): when
+        // Session B compacts mid-flight and produces its own row, B's next chat
+        // turn must NOT claim that row back into its own prompt — that's wasted
+        // tokens and steals the snapshot meant for the next fresh session.
+        p(S.claimLatestUnconsumedResume, `UPDATE session_resume
+       SET consumed = 1
+       WHERE id = (
+         SELECT id FROM session_resume
+         WHERE consumed = 0
+           AND session_id != ?
+         ORDER BY created_at DESC, id DESC
+         LIMIT 1
+       )
+       RETURNING session_id, snapshot`);
+        // ── Delete ──
+        p(S.deleteEvents, `DELETE FROM session_events WHERE session_id = ?`);
+        p(S.deleteMeta, `DELETE FROM session_meta WHERE session_id = ?`);
+        p(S.deleteResume, `DELETE FROM session_resume WHERE session_id = ?`);
+        // ── Search ──
+        p(S.searchEvents, `SELECT id, session_id, category, type, data, created_at
+       FROM session_events
+       WHERE (project_dir = ? OR project_dir = '')
+         AND (data LIKE '%' || ? || '%' ESCAPE '\\' OR category LIKE '%' || ? || '%' ESCAPE '\\')
+         AND (? IS NULL OR category = ?)
+       ORDER BY id ASC
+       LIMIT ?`);
+        // ── Cleanup ──
+        p(S.getOldSessions, `SELECT session_id FROM session_meta WHERE started_at < datetime('now', ? || ' days')`);
+        // ── Tool calls (persistent counter) ──
+        p(S.incrementToolCall, `INSERT INTO tool_calls (session_id, tool, calls, bytes_returned)
+       VALUES (?, ?, 1, ?)
+       ON CONFLICT(session_id, tool) DO UPDATE SET
+         calls = calls + 1,
+         bytes_returned = bytes_returned + excluded.bytes_returned,
+         updated_at = datetime('now')`);
+        p(S.getToolCallTotals, `SELECT COALESCE(SUM(calls), 0) AS calls,
+              COALESCE(SUM(bytes_returned), 0) AS bytes_returned
+       FROM tool_calls WHERE session_id = ?`);
+        p(S.getToolCallByTool, `SELECT tool, calls, bytes_returned
+       FROM tool_calls WHERE session_id = ? ORDER BY calls DESC`);
+        // ── Event-level byte accounting (D2 PRD Phase 2) ──
+        p(S.getEventBytesSummary, `SELECT COALESCE(SUM(bytes_avoided), 0) AS bytes_avoided,
+              COALESCE(SUM(bytes_returned), 0) AS bytes_returned
+       FROM session_events WHERE session_id = ?`);
+    }
+    // ═══════════════════════════════════════════
+    // Events
+    // ═══════════════════════════════════════════
+    /**
+     * Insert a session event with deduplication and FIFO eviction.
+     *
+     * Deduplication: skips if the same type + data_hash appears in the
+     * last DEDUP_WINDOW events for this session.
+     *
+     * Eviction: if session exceeds MAX_EVENTS_PER_SESSION, evicts the
+     * lowest-priority (then oldest) event.
+     */
+    insertEvent(sessionId, event, sourceHook = "PostToolUse", attribution, bytes) {
+        // SHA256-based dedup hash (first 16 hex chars = 8 bytes of entropy)
+        const dataHash = createHash("sha256")
+            .update(event.data)
+            .digest("hex")
+            .slice(0, 16)
+            .toUpperCase();
+        const projectDir = String(attribution?.projectDir
+            ?? event.project_dir
+            ?? this._getSessionProjectDir(sessionId)).trim();
+        const attributionSource = String(attribution?.source
+            ?? event.attribution_source
+            ?? "unknown");
+        const rawConfidence = Number(attribution?.confidence
+            ?? event.attribution_confidence
+            ?? 0);
+        const attributionConfidence = Number.isFinite(rawConfidence)
+            ? Math.max(0, Math.min(1, rawConfidence))
+            : 0;
+        const bytesAvoided = clampNonNegativeInt(bytes?.bytesAvoided);
+        const bytesReturned = clampNonNegativeInt(bytes?.bytesReturned);
+        // Atomic: dedup check + eviction + insert in a single transaction
+        // to prevent race conditions from concurrent hook calls.
+        const transaction = this.db.transaction(() => {
+            // Deduplication check: same type + data_hash in last N events
+            const dup = this.stmt(S.checkDuplicate).get(sessionId, DEDUP_WINDOW, event.type, dataHash);
+            if (dup)
+                return;
+            // Enforce max events with FIFO eviction of lowest priority
+            const countRow = this.stmt(S.getEventCount).get(sessionId);
+            if (countRow.cnt >= MAX_EVENTS_PER_SESSION) {
+                this.stmt(S.evictLowestPriority).run(sessionId);
+            }
+            // Insert the event
+            this.stmt(S.insertEvent).run(sessionId, event.type, event.category, event.priority, event.data, projectDir, attributionSource, attributionConfidence, bytesAvoided, bytesReturned, sourceHook, dataHash);
+            // Update meta if session exists
+            this.stmt(S.updateMetaLastEvent).run(sessionId);
+        });
+        this.withRetry(() => transaction());
+    }
+    /**
+     * Bulk-insert N events in a SINGLE transaction.
+     *
+     * PostToolUse hooks emit 5–15 events per tool call. Calling insertEvent()
+     * in a loop runs N transactions = N WAL commits = N fsync candidates,
+     * which is painful on Windows NTFS where commit latency dominates.
+     * One transaction = one commit, dedup/evict checks reuse cached statements.
+     *
+     * Cross-platform: uses the same WAL-mode transaction primitive as
+     * insertEvent — behavior identical on macOS / Linux / Windows.
+     */
+    bulkInsertEvents(sessionId, events, sourceHook = "PostToolUse", attributions, bytesList) {
+        if (!events || events.length === 0)
+            return;
+        if (events.length === 1) {
+            // Cheaper to fall through to insertEvent (its own dedicated transaction).
+            this.insertEvent(sessionId, events[0], sourceHook, attributions?.[0], bytesList?.[0]);
+            return;
+        }
+        // Pre-compute hashes + normalized attribution outside the transaction
+        // so the SQL transaction holds only DB work (shorter lock window).
+        const prepared = events.map((event, i) => {
+            const dataHash = createHash("sha256")
+                .update(event.data)
+                .digest("hex")
+                .slice(0, 16)
+                .toUpperCase();
+            const attribution = attributions?.[i];
+            // #827: store project_dir in canonical path shape so the search-time
+            // allow-set lookup (getSessionIdsForProject) matches regardless of the
+            // separator / trailing-slash form the host adapter happened to emit.
+            // normalizeWorktreePath is the same rule used for project-hash stability.
+            const rawProjectDir = String(attribution?.projectDir ?? event.project_dir ?? this._getSessionProjectDir(sessionId) ?? "").trim();
+            const projectDir = rawProjectDir === "" ? "" : normalizeWorktreePath(rawProjectDir);
+            const attributionSource = String(attribution?.source ?? event.attribution_source ?? "unknown");
+            const rawConfidence = Number(attribution?.confidence ?? event.attribution_confidence ?? 0);
+            const attributionConfidence = Number.isFinite(rawConfidence)
+                ? Math.max(0, Math.min(1, rawConfidence))
+                : 0;
+            const eventBytes = bytesList?.[i];
+            const bytesAvoided = clampNonNegativeInt(eventBytes?.bytesAvoided);
+            const bytesReturned = clampNonNegativeInt(eventBytes?.bytesReturned);
+            return {
+                event,
+                dataHash,
+                projectDir,
+                attributionSource,
+                attributionConfidence,
+                bytesAvoided,
+                bytesReturned,
+            };
+        });
+        const transaction = this.db.transaction(() => {
+            let cnt = this.stmt(S.getEventCount).get(sessionId).cnt;
+            for (const row of prepared) {
+                const dup = this.stmt(S.checkDuplicate).get(sessionId, DEDUP_WINDOW, row.event.type, row.dataHash);
+                if (dup)
+                    continue;
+                if (cnt >= MAX_EVENTS_PER_SESSION) {
+                    this.stmt(S.evictLowestPriority).run(sessionId);
+                }
+                else {
+                    cnt++;
+                }
+                this.stmt(S.insertEvent).run(sessionId, row.event.type, row.event.category, row.event.priority, row.event.data, row.projectDir, row.attributionSource, row.attributionConfidence, row.bytesAvoided, row.bytesReturned, sourceHook, row.dataHash);
+            }
+            this.stmt(S.updateMetaLastEvent).run(sessionId);
+        });
+        this.withRetry(() => transaction());
+    }
+    /**
+     * Retrieve events for a session with optional filtering.
+     */
+    getEvents(sessionId, opts) {
+        const limit = opts?.limit ?? 1000;
+        const type = opts?.type;
+        const minPriority = opts?.minPriority;
+        if (type && minPriority !== undefined) {
+            return this.stmt(S.getEventsByTypeAndPriority).all(sessionId, type, minPriority, limit);
+        }
+        if (type) {
+            return this.stmt(S.getEventsByType).all(sessionId, type, limit);
+        }
+        if (minPriority !== undefined) {
+            return this.stmt(S.getEventsByPriority).all(sessionId, minPriority, limit);
+        }
+        return this.stmt(S.getEvents).all(sessionId, limit);
+    }
+    /**
+     * Get the total event count for a session.
+     */
+    getEventCount(sessionId) {
+        const row = this.stmt(S.getEventCount).get(sessionId);
+        return row.cnt;
+    }
+    /**
+     * Aggregate per-event byte accounting for a session.
+     *
+     * Returns the total bytes context-mode kept OUT of the model context
+     * window (`bytesAvoided`) and the total it actually returned to the
+     * model (`bytesReturned`). Both default to 0 for unknown sessions.
+     *
+     * Used by the Insight dashboard to render the "saved vs returned"
+     * panel without scanning every event row in JS.
+     */
+    getEventBytesSummary(sessionId) {
+        const row = this.stmt(S.getEventBytesSummary).get(sessionId);
+        return {
+            bytesAvoided: Number(row?.bytes_avoided ?? 0),
+            bytesReturned: Number(row?.bytes_returned ?? 0),
+        };
+    }
+    /**
+     * Return the most recently attributed project dir for a session.
+     */
+    getLatestAttributedProjectDir(sessionId) {
+        const row = this.stmt(S.getLatestAttributedProject).get(sessionId);
+        return row?.project_dir || null;
+    }
+    /**
+     * Look up the project_dir from session_meta as a last-resort fallback
+     * for event attribution. Prevents project_dir='' orphans when the caller
+     * (e.g. pi adapter) omits the attribution parameter.
+     */
+    _getSessionProjectDir(sessionId) {
+        try {
+            const row = this.db.prepare("SELECT project_dir FROM session_meta WHERE session_id = ?").get(sessionId);
+            return row?.project_dir || "";
+        }
+        catch (err) {
+            // Best-effort fallback: still return "" but surface why (rate-limited).
+            logDbError("SessionDB.getSessionProjectDir", err, this.dbPath);
+            return "";
+        }
+    }
+    /**
+     * Search events by text query scoped to a project directory.
+     *
+     * Performs a case-insensitive LIKE search across the `data` and `category`
+     * columns. An optional `source` parameter filters by exact category match.
+     * Returns results ordered by monotonic id (chronological).
+     *
+     * Best-effort: returns empty array on any error.
+     */
+    searchEvents(query, limit, projectDir, source) {
+        try {
+            const escapedQuery = query.replace(/[%_]/g, (char) => "\\" + char);
+            const sourceParam = source ?? null;
+            return this.stmt(S.searchEvents).all(projectDir, escapedQuery, escapedQuery, sourceParam, sourceParam, limit);
+        }
+        catch (err) {
+            // Best-effort: still return [] but surface why (rate-limited to
+            // once per op+code+message per ~30s).
+            logDbError("SessionDB.searchEvents", err, this.dbPath);
+            return [];
+        }
+    }
+    /**
+     * Return the distinct list of session ids whose events were attributed
+     * to a given `project_dir`. Powers the ctx_search `project:` filter
+     * (#737) via the 2-step IN-clause strategy — ATTACH DATABASE is avoided
+     * because SQLite's WAL + ATTACH combination has known correctness
+     * trade-offs flagged in the upstream docs.
+     *
+     * Backed by the `idx_session_events_project(session_id, project_dir)`
+     * composite index, so 1000-session lookups complete in single-digit
+     * milliseconds. Best-effort: returns `[]` on any error.
+     */
+    getSessionIdsForProject(projectDir) {
+        try {
+            // #827: match by canonical path shape, not raw bytes. The host adapter
+            // may store `project_dir` in a different separator / trailing-slash
+            // shape than the search path resolves the scope in — most visibly on
+            // Windows, where attribution often carries `C:\Users\me\proj` while the
+            // server resolves `C:/Users/me/proj`. An exact `project_dir = ?` match
+            // then returned an EMPTY allow-set and ctx_search reported "No results
+            // found" even though the content was present. We fold BOTH sides through
+            // the same canonical rule used for project-hash stability
+            // (normalizeWorktreePath): backslash → forward slash, then strip the
+            // trailing slash. Normalizing in SQL (RTRIM(REPLACE(...))) covers rows
+            // already written un-normalized without a migration, while the JS-side
+            // normalize keeps the bound parameter in the identical shape. This
+            // preserves the #737 project scope — distinct directories still differ
+            // after normalization, so cross-project isolation is intact.
+            const normalized = normalizeWorktreePath(projectDir);
+            const rows = this.db
+                .prepare(`SELECT DISTINCT session_id
+              FROM session_events
+             WHERE RTRIM(REPLACE(project_dir, '\\', '/'), '/') = ?`)
+                .all(normalized);
+            return rows.map((r) => r.session_id);
+        }
+        catch (err) {
+            // Best-effort: still return [] but surface why (rate-limited).
+            logDbError("SessionDB.getSessionIdsForProject", err, this.dbPath);
+            return [];
+        }
+    }
+    // ═══════════════════════════════════════════
+    // Meta
+    // ═══════════════════════════════════════════
+    /**
+     * Ensure a session metadata entry exists. Idempotent (INSERT OR IGNORE).
+     * `projectDir` is the session origin directory, not per-event attribution.
+     */
+    ensureSession(sessionId, projectDir) {
+        this.stmt(S.ensureSession).run(sessionId, projectDir);
+    }
+    /**
+     * Get session statistics/metadata.
+     */
+    getSessionStats(sessionId) {
+        const row = this.stmt(S.getSessionStats).get(sessionId);
+        return row ?? null;
+    }
+    /**
+     * Session rollup snapshot — 12 aggregate fields the analytics platform
+     * stamps onto every outgoing event row (seed.ts shape parity).
+     *
+     * Called from session-loaders BEFORE `maybeForward`; the snapshot is
+     * computed against the LOCAL SessionDB and threaded into the canonical
+     * event so the platform-side Zod schema receives the rich shape without
+     * the bridge ever hand-mapping fields (PRD §5.4 ABI passthrough).
+     *
+     * Returns zeroed defaults for unknown sessions — callers MUST tolerate
+     * a snapshot from an empty session (first event into a fresh DB).
+     */
+    getSessionRollup(sessionId) {
+        const main = this.stmt(S.getSessionRollup).get(sessionId);
+        const maxRow = this.stmt(S.getMaxFileEdits).get(sessionId);
+        const commitRow = this.stmt(S.getLatestCommitMessage).get(sessionId);
+        const meta = this.getSessionStats(sessionId);
+        // edit_test_cycles: heuristic — min(file edits, errors) approximates
+        // the number of edit-then-test attempts in a session. Exact pattern
+        // detection (consecutive file_edit followed by error_tool) would need
+        // a windowed query; this scalar pair under-counts but never overshoots.
+        const fileEdits = (main?.tool_calls ?? 0) > 0
+            ? (main?.unique_files ?? 0)
+            : 0;
+        const errors = main?.errors ?? 0;
+        const editTestCycles = Math.min(fileEdits, errors);
+        return {
+            tool_calls: main?.tool_calls ?? 0,
+            errors: main?.errors ?? 0,
+            unique_tools: main?.unique_tools ?? 0,
+            unique_files: main?.unique_files ?? 0,
+            max_file_edits: maxRow?.max_file_edits ?? 0,
+            has_commit: main?.has_commit ?? 0,
+            commit_message: commitRow?.data ?? "",
+            edit_test_cycles: editTestCycles,
+            duration_min: main?.duration_min ?? 0,
+            compact_count: meta?.compact_count ?? 0,
+            sources_indexed: main?.sources_indexed ?? 0,
+            total_chunks: main?.total_chunks ?? 0,
+            search_queries: main?.search_queries ?? 0,
+        };
+    }
+    /**
+     * Increment the compact_count for a session (tracks snapshot rebuilds).
+     */
+    incrementCompactCount(sessionId) {
+        this.stmt(S.incrementCompactCount).run(sessionId);
+    }
+    /**
+     * Read the per-session usage high-water cursor — the uuid of the last
+     * assistant turn already emitted by the Stop hook's main-turn capture.
+     * Returns null when unset (first Stop) or the session row is absent.
+     */
+    getUsageCursor(sessionId) {
+        const row = this.stmt(S.getUsageCursor).get(sessionId);
+        return row?.usage_cursor ?? null;
+    }
+    /**
+     * Advance the per-session usage high-water cursor to `uuid`. No-op when the
+     * session_meta row does not exist yet (callers ensureSession first).
+     */
+    setUsageCursor(sessionId, uuid) {
+        this.stmt(S.setUsageCursor).run(uuid, sessionId);
+    }
+    // ═══════════════════════════════════════════
+    // Resume
+    // ═══════════════════════════════════════════
+    /**
+     * Upsert a resume snapshot for a session. Resets consumed flag on update.
+     */
+    upsertResume(sessionId, snapshot, eventCount) {
+        this.stmt(S.upsertResume).run(sessionId, snapshot, eventCount ?? 0);
+    }
+    /**
+     * Retrieve the resume snapshot for a session.
+     */
+    getResume(sessionId) {
+        const row = this.stmt(S.getResume).get(sessionId);
+        return row ?? null;
+    }
+    /**
+     * Mark the resume snapshot as consumed (already injected into conversation).
+     */
+    markResumeConsumed(sessionId) {
+        this.stmt(S.markResumeConsumed).run(sessionId);
+    }
+    /**
+     * Atomically claim the most recent unconsumed resume snapshot in this DB,
+     * EXCLUDING any row that belongs to `currentSessionId`.
+     *
+     * `SessionDB` is sharded per project (see `resolveSessionDbPath` — SHA-256
+     * of canonical project dir), so "this DB" already implies "this project".
+     * The atomic
+     * `UPDATE … RETURNING` ensures concurrent processes for the same project
+     * cannot both inject the same snapshot (Mickey / PR #376 race).
+     *
+     * The `currentSessionId` parameter prevents self-injection: when a session
+     * compacts mid-flight and produces its own row, that session's next chat
+     * turn must NOT claim that row back (wasted tokens AND it would consume
+     * the snapshot meant for the next fresh session).
+     *
+     * Pass an empty string to allow self-claim (legacy behaviour, only useful
+     * in tests or one-off harnesses).
+     *
+     * Returns null when no unconsumed snapshot exists for any other session.
+     */
+    claimLatestUnconsumedResume(currentSessionId) {
+        const row = this.stmt(S.claimLatestUnconsumedResume).get(currentSessionId);
+        if (!row)
+            return null;
+        return { sessionId: row.session_id, snapshot: row.snapshot };
+    }
+    /**
+     * Return the most recent session_id from session_meta, or null if none.
+     * Used by the runtime to attach persistent counters to the right session
+     * after a process restart.
+     */
+    getLatestSessionId() {
+        try {
+            const row = this.db.prepare("SELECT session_id FROM session_meta ORDER BY started_at DESC LIMIT 1").get();
+            return row?.session_id ?? null;
+        }
+        catch (err) {
+            logDbError("SessionDB.getLatestSessionId", err, this.dbPath);
+            return null;
+        }
+    }
+    // ═══════════════════════════════════════════
+    // Tool call counters (Bug #1 + #2 — survive restart, --continue, upgrade)
+    // ═══════════════════════════════════════════
+    /**
+     * Increment the persistent tool-call counter for `tool` in `sessionId`.
+     * Adds `bytesReturned` to the cumulative total. Idempotent across
+     * SessionDB instances — counters survive process restart.
+     */
+    incrementToolCall(sessionId, tool, bytesReturned = 0) {
+        const safeBytes = Number.isFinite(bytesReturned) && bytesReturned > 0 ? Math.round(bytesReturned) : 0;
+        try {
+            this.stmt(S.incrementToolCall).run(sessionId, tool, safeBytes);
+        }
+        catch (err) {
+            // best-effort: counter must never throw and break the parent call —
+            // but surface it (rate-limited) instead of vanishing.
+            logDbError("SessionDB.incrementToolCall", err, this.dbPath);
+        }
+    }
+    /**
+     * Get aggregated tool-call stats for `sessionId`. Returns zero-stats
+     * when the session has no recorded calls.
+     */
+    getToolCallStats(sessionId) {
+        try {
+            const totals = this.stmt(S.getToolCallTotals).get(sessionId);
+            const rows = this.stmt(S.getToolCallByTool).all(sessionId);
+            const byTool = {};
+            for (const row of rows) {
+                byTool[row.tool] = {
+                    calls: row.calls,
+                    bytesReturned: row.bytes_returned,
+                };
+            }
+            return {
+                totalCalls: totals?.calls ?? 0,
+                totalBytesReturned: totals?.bytes_returned ?? 0,
+                byTool,
+            };
+        }
+        catch (err) {
+            logDbError("SessionDB.getToolCallStats", err, this.dbPath);
+            return { totalCalls: 0, totalBytesReturned: 0, byTool: {} };
+        }
+    }
+    // ═══════════════════════════════════════════
+    // Lifecycle
+    // ═══════════════════════════════════════════
+    /**
+     * Delete all data for a session (events, meta, resume).
+     */
+    deleteSession(sessionId) {
+        this.db.transaction(() => {
+            this.stmt(S.deleteEvents).run(sessionId);
+            this.stmt(S.deleteResume).run(sessionId);
+            this.stmt(S.deleteMeta).run(sessionId);
+        })();
+    }
+    /**
+     * Remove sessions older than maxAgeDays. Returns the count of deleted sessions.
+     */
+    cleanupOldSessions(maxAgeDays = 7) {
+        const negDays = `-${maxAgeDays}`;
+        const oldSessions = this.stmt(S.getOldSessions).all(negDays);
+        for (const { session_id } of oldSessions) {
+            this.deleteSession(session_id);
+        }
+        return oldSessions.length;
+    }
+    /**
+     * Delete event rows whose session_id has no matching session_meta row.
+     *
+     * Orphaned events accumulate when meta rows were aged out by an older
+     * version of `cleanupOldSessions` but the matching events were left
+     * behind (or when callers wrote events without a meta upsert). The Kimi
+     * Code sessionstart hook calls this on every startup as a self-healing
+     * step; surfacing it as a SessionDB method keeps the SQL definition in
+     * one place instead of letting hook scripts reach through to
+     * `db.db.exec(...)` and re-encode schema knowledge in mjs files.
+     */
+    pruneOrphanedEvents() {
+        const result = this.db
+            .prepare(`DELETE FROM session_events WHERE session_id NOT IN (SELECT session_id FROM session_meta)`)
+            .run();
+        return Number(result.changes ?? 0);
+    }
+}