context-mode 1.0.111 → 1.0.112

package/build/session/db.d.ts

@@ -8,8 +8,93 @@
 import { SQLiteBase } from "../db-base.js";
 import type { SessionEvent } from "../types.js";
 import type { ProjectAttribution } from "./project-attribution.js";
-export declare function getWorktreeSuffix(): string;
+export declare function normalizeWorktreePath(path: string): string;
+export declare function getWorktreeSuffix(projectDir?: string): string;
 export declare function _resetWorktreeSuffixCacheForTests(): void;
+/**
+ * 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 declare function hashProjectDirLegacy(projectDir: string): string;
+/**
+ * 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 declare function hashProjectDirCanonical(projectDir: string): string;
+/**
+ * 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 declare function resolveContentStorePath(opts: {
+    projectDir: string;
+    contentDir: string;
+}): string;
+/**
+ * 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 declare function resolveSessionDbPath(opts: {
+    projectDir: string;
+    sessionsDir: string;
+}): string;
+/**
+ * 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 declare function resolveSessionPath(opts: {
+    projectDir: string;
+    sessionsDir: string;
+    ext: string;
+    suffix?: string;
+}): string;
 /** A stored event row from the session_events table. */
 export interface StoredEvent {
     id: number;
@@ -21,10 +106,19 @@ export interface StoredEvent {
     project_dir: string;
     attribution_source: string;
     attribution_confidence: number;
+    bytes_avoided: number;
+    bytes_returned: number;
     source_hook: string;
     created_at: string;
     data_hash: string;
 }
+/** Optional per-event byte accounting passed to {@link SessionDB.insertEvent}. */
+export interface EventBytes {
+    /** Bytes context-mode prevented from entering the model context window. */
+    bytesAvoided?: number;
+    /** Bytes context-mode actually returned to the model. */
+    bytesReturned?: number;
+}
 /** Session metadata row from the session_meta table. */
 export interface SessionMeta {
     session_id: string;
@@ -79,7 +173,7 @@ export declare class SessionDB extends SQLiteBase {
      */
     insertEvent(sessionId: string, event: Omit<SessionEvent, "data_hash"> & {
         data_hash?: string;
-    }, sourceHook?: string, attribution?: Partial<ProjectAttribution>): void;
+    }, sourceHook?: string, attribution?: Partial<ProjectAttribution>, bytes?: EventBytes): void;
     /**
      * Bulk-insert N events in a SINGLE transaction.
      *
@@ -91,7 +185,7 @@ export declare class SessionDB extends SQLiteBase {
      * Cross-platform: uses the same WAL-mode transaction primitive as
      * insertEvent — behavior identical on macOS / Linux / Windows.
      */
-    bulkInsertEvents(sessionId: string, events: SessionEvent[], sourceHook?: string, attributions?: Array<Partial<ProjectAttribution> | undefined>): void;
+    bulkInsertEvents(sessionId: string, events: SessionEvent[], sourceHook?: string, attributions?: Array<Partial<ProjectAttribution> | undefined>, bytesList?: Array<EventBytes | undefined>): void;
     /**
      * Retrieve events for a session with optional filtering.
      */
@@ -104,6 +198,20 @@ export declare class SessionDB extends SQLiteBase {
      * Get the total event count for a session.
      */
     getEventCount(sessionId: string): number;
+    /**
+     * 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: string): {
+        bytesAvoided: number;
+        bytesReturned: number;
+    };
     /**
      * Return the most recently attributed project dir for a session.
      */
@@ -154,8 +262,9 @@ export declare class SessionDB extends SQLiteBase {
      * Atomically claim the most recent unconsumed resume snapshot in this DB,
      * EXCLUDING any row that belongs to `currentSessionId`.
      *
-     * `SessionDB` is sharded per project (see `getSessionDBPath` — SHA-256 of
-     * project dir), so "this DB" already implies "this project". The atomic
+     * `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).
      *

package/build/session/db.js

@@ -8,6 +8,8 @@
 import { SQLiteBase, defaultDBPath } from "../db-base.js";
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, renameSync } from "node:fs";
+import { join } from "node:path";
 // ─────────────────────────────────────────────────────────
 // Worktree isolation
 // ─────────────────────────────────────────────────────────
@@ -19,15 +21,61 @@ import { execFileSync } from "node:child_process";
  * (useful in CI environments or when git is unavailable).
  * Set to empty string to disable isolation entirely.
  */
-// Memoized per (cwd, env override) — recomputing on every tool call cost
+// Memoized per (projectDir, env override) — recomputing on every tool call cost
 // ~12ms (git worktree list subprocess fork) on macOS, 50ms+ on Windows.
-// Key by cwd so a defensive `process.chdir()` invalidates rather than
-// returning stale data.
+// 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 getWorktreeSuffix() {
+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;
-    const cwd = process.cwd();
-    if (_wtCache && _wtCache.cwd === cwd && _wtCache.envSuffix === envSuffix) {
+    if (_wtCache && _wtCache.projectDir === projectDir && _wtCache.envSuffix === envSuffix) {
         return _wtCache.suffix;
     }
     let suffix = "";
@@ -36,24 +84,27 @@ export function getWorktreeSuffix() {
     }
     else {
         try {
-            const mainWorktree = execFileSync("git", ["worktree", "list", "--porcelain"], {
-                encoding: "utf-8",
-                timeout: 2000,
-                stdio: ["ignore", "pipe", "ignore"],
-            })
-                .split(/\r?\n/)
-                .find((l) => l.startsWith("worktree "))
-                ?.replace("worktree ", "")
-                ?.trim();
-            if (mainWorktree && cwd !== mainWorktree) {
-                suffix = `__${createHash("sha256").update(cwd).digest("hex").slice(0, 8)}`;
+            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 = { cwd, envSuffix, suffix };
+    _wtCache = { projectDir, envSuffix, suffix };
     return suffix;
 }
 // Test-only helper: clear the memoization between cases.
@@ -61,12 +112,160 @@ 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)
 // ─────────────────────────────────────────────────────────
@@ -96,6 +295,7 @@ const S = {
     incrementToolCall: "incrementToolCall",
     getToolCallTotals: "getToolCallTotals",
     getToolCallByTool: "getToolCallByTool",
+    getEventBytesSummary: "getEventBytesSummary",
 };
 // ─────────────────────────────────────────────────────────
 // SessionDB
@@ -133,6 +333,8 @@ export class SessionDB extends SQLiteBase {
         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 ''
@@ -184,6 +386,12 @@ export class SessionDB extends SQLiteBase {
             if (!cols.has("attribution_confidence")) {
                 this.db.exec("ALTER TABLE session_events ADD COLUMN attribution_confidence REAL NOT NULL DEFAULT 0");
             }
+            if (!cols.has("bytes_avoided")) {
+                this.db.exec("ALTER TABLE session_events ADD COLUMN bytes_avoided INTEGER NOT NULL DEFAULT 0");
+            }
+            if (!cols.has("bytes_returned")) {
+                this.db.exec("ALTER TABLE session_events ADD COLUMN bytes_returned INTEGER NOT NULL DEFAULT 0");
+            }
             this.db.exec("CREATE INDEX IF NOT EXISTS idx_session_events_project ON session_events(session_id, project_dir)");
         }
         catch {
@@ -199,23 +407,28 @@ export class SessionDB extends SQLiteBase {
         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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+       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 = ?`);
@@ -297,6 +510,10 @@ export class SessionDB extends SQLiteBase {
        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
@@ -310,7 +527,7 @@ export class SessionDB extends SQLiteBase {
      * Eviction: if session exceeds MAX_EVENTS_PER_SESSION, evicts the
      * lowest-priority (then oldest) event.
      */
-    insertEvent(sessionId, event, sourceHook = "PostToolUse", attribution) {
+    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)
@@ -329,6 +546,8 @@ export class SessionDB extends SQLiteBase {
         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(() => {
@@ -342,7 +561,7 @@ export class SessionDB extends SQLiteBase {
                 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, sourceHook, dataHash);
+            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);
         });
@@ -359,12 +578,12 @@ export class SessionDB extends SQLiteBase {
      * Cross-platform: uses the same WAL-mode transaction primitive as
      * insertEvent — behavior identical on macOS / Linux / Windows.
      */
-    bulkInsertEvents(sessionId, events, sourceHook = "PostToolUse", attributions) {
+    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]);
+            this.insertEvent(sessionId, events[0], sourceHook, attributions?.[0], bytesList?.[0]);
             return;
         }
         // Pre-compute hashes + normalized attribution outside the transaction
@@ -382,7 +601,18 @@ export class SessionDB extends SQLiteBase {
             const attributionConfidence = Number.isFinite(rawConfidence)
                 ? Math.max(0, Math.min(1, rawConfidence))
                 : 0;
-            return { event, dataHash, projectDir, attributionSource, attributionConfidence };
+            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;
@@ -396,7 +626,7 @@ export class SessionDB extends SQLiteBase {
                 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, sourceHook, row.dataHash);
+                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);
         });
@@ -427,6 +657,23 @@ export class SessionDB extends SQLiteBase {
         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.
      */
@@ -502,8 +749,9 @@ export class SessionDB extends SQLiteBase {
      * Atomically claim the most recent unconsumed resume snapshot in this DB,
      * EXCLUDING any row that belongs to `currentSessionId`.
      *
-     * `SessionDB` is sharded per project (see `getSessionDBPath` — SHA-256 of
-     * project dir), so "this DB" already implies "this project". The atomic
+     * `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).
      *

package/build/session/event-emit.d.ts

@@ -0,0 +1,48 @@
+/**
+ * event-emit — Phase 5+7 of D2 PRD (stats-event-driven-architecture)
+ *
+ * Server-side helpers that record sandbox / index / cache work into
+ * `session_events` with the new `bytes_avoided` / `bytes_returned`
+ * columns so the renderer can compute the real $ saved instead of the
+ * conservative `events × 256` token estimate.
+ *
+ * Design notes
+ * ────────────
+ * - Uses the public `SessionDB.insertEvent(... , bytes)` API the schema
+ *   engineer extended in this branch — same dedup + FIFO eviction +
+ *   transaction wrapping you'd get from any other event source.
+ * - Best-effort error swallowing matches `persistToolCallCounter` in
+ *   `persist-tool-calls.ts`. A stats-side failure must NEVER break the
+ *   parent MCP tool call.
+ * - Resolves the latest `session_id` from `session_meta` so the wiring
+ *   in `server.ts` is `setImmediate(() => emit*({...}))` — no need to
+ *   plumb session ids through every handler.
+ */
+/**
+ * Record a `ctx_execute` / `ctx_execute_file` / `ctx_batch_execute` run.
+ * `bytesReturned` is the size of the stdout text the user actually saw —
+ * the rest of the sandbox output stayed out of context.
+ */
+export declare function emitSandboxExecuteEvent(opts: {
+    sessionDbPath: string;
+    toolName: string;
+    bytesReturned: number;
+}): void;
+/**
+ * Record a `ctx_index` / `trackIndexed` write — content kept out of
+ * context by being chunked into FTS5 instead of returned inline.
+ */
+export declare function emitIndexWriteEvent(opts: {
+    sessionDbPath: string;
+    source: string;
+    bytesAvoided: number;
+}): void;
+/**
+ * Record a `ctx_fetch_and_index` TTL cache hit — bytes the user would
+ * have spent re-fetching the same URL within the 24h cache window.
+ */
+export declare function emitCacheHitEvent(opts: {
+    sessionDbPath: string;
+    source: string;
+    bytesAvoided: number;
+}): void;