context-mode 1.0.146 → 1.0.148

package/build/session/analytics.d.ts

@@ -427,6 +427,25 @@ export declare function getRealBytesStats(opts: {
     sessionId?: string;
     sessionsDir?: string;
     worktreeHash?: string;
+    /**
+     * v1.0.148 follow-up (Bug E+F): when set, the function aggregates across
+     * EVERY session whose `session_meta.project_dir` matches this value, not
+     * just one session_id. Resolves the per-conversation under-attribution:
+     * one Claude Code conversation typically spans many session_ids (resume
+     * cycles, /compact rebirths, PID sub-process sessions spawned by
+     * ctx_execute), so a single-session_id filter loses the sandbox-burst
+     * bytes_avoided that all live under the conversation's cwd.
+     *
+     * Uses a META subquery (`session_id IN (SELECT session_id FROM
+     * session_meta WHERE project_dir = ?)`), then sums ALL events for
+     * matching sessions regardless of their event-level project_dir
+     * (sandbox-burst events write `project_dir = ''` even when the
+     * META row carries the parent cwd — see Bug F).
+     *
+     * Mutually exclusive with `sessionId`. When both are set, `sessionId`
+     * wins for back-compat.
+     */
+    projectDir?: string;
     /**
      * v1.0.133 Slice 3: when set alongside `sessionId`, the function joins
      * the FTS5 content DB at this path and folds chunk bytes into

package/build/session/analytics.js

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, sep } from "node:path";
 import { loadDatabase as loadDatabaseImpl } from "../db-base.js";
+import { ensureSessionEventsSchema } from "./db.js";
 import { resolveClaudeConfigDir } from "../util/claude-config.js";
 function semverNewer(a, b) {
     const pa = a.split(".").map(Number);
@@ -857,6 +858,15 @@ export function getRealBytesStats(opts) {
     // don't need to type-narrow per row.
     for (const file of dbFiles) {
         const dbPath = join(sessionsDir, file);
+        // v1.0.148 hotfix: historical DBs were created with pre-v1.0.130
+        // schema (no bytes_avoided / bytes_returned / project_dir columns).
+        // The SELECT below references those columns, so without an in-place
+        // migration the prepare() throws and the surrounding catch silently
+        // skips the WHOLE DB — losing even the LENGTH(data) signal. Run the
+        // shared migration helper before opening readonly. Idempotent: a
+        // PRAGMA check inside the helper short-circuits when the DB is
+        // already current, so post-first-read calls are cheap.
+        ensureSessionEventsSchema(dbPath, DatabaseCtor);
         try {
             const sdb = new DatabaseCtor(dbPath, { readonly: true });
             try {
@@ -878,6 +888,36 @@ export function getRealBytesStats(opts) {
                     }
                     catch { /* old schema */ }
                 }
+                else if (opts.projectDir) {
+                    // Bug E+F: META-scoped aggregation. Take every session_id whose
+                    // session_meta.project_dir matches, then sum ALL of those
+                    // sessions' events regardless of the events' own project_dir
+                    // (sandbox-burst PID sessions write empty event-level project_dir
+                    // even when their META carries the parent cwd).
+                    const row = sdb.prepare(`SELECT
+               COALESCE(SUM(LENGTH(data)), 0)   AS data_bytes,
+               COALESCE(SUM(bytes_avoided), 0)  AS bytes_avoided,
+               COALESCE(SUM(bytes_returned), 0) AS bytes_returned
+             FROM session_events
+             WHERE session_id IN (
+               SELECT session_id FROM session_meta WHERE project_dir = ?
+             )`).get(opts.projectDir);
+                    if (row) {
+                        eventDataBytes += Number(row.data_bytes ?? 0);
+                        bytesAvoided += Number(row.bytes_avoided ?? 0);
+                        bytesReturned += Number(row.bytes_returned ?? 0);
+                    }
+                    try {
+                        const snap = sdb.prepare(`SELECT COALESCE(SUM(LENGTH(snapshot)), 0) AS bytes
+               FROM session_resume
+               WHERE session_id IN (
+                 SELECT session_id FROM session_meta WHERE project_dir = ?
+               )`).get(opts.projectDir);
+                        if (snap?.bytes)
+                            snapshotBytes += Number(snap.bytes);
+                    }
+                    catch { /* old schema */ }
+                }
                 else {
                     const row = sdb.prepare(`SELECT
                COALESCE(SUM(LENGTH(data)), 0)   AS data_bytes,
@@ -1504,34 +1544,44 @@ function renderNarrative5Section(args) {
         out.push(`  Without that, you'd be re-explaining everything to a blank model right now.`);
     }
     out.push("");
-    // Without/With bars — measured from real per-event bytes_returned / bytes_avoided.
+    // Without/With bars — strict compression (v1.0.148, Bug G / ADR-0004).
     //
-    // Honest definitions (v1.0.134 SLICE B — eventDataBytes floor):
-    //   Without = bytes the model WOULD have re-seen with no filtering
-    //           = bytes_avoided + bytes_returned + eventDataBytes
+    // Honest definitions:
+    //   Without = bytes the model WOULD have re-seen if context-mode
+    //             had not diverted them
+    //           = bytesAvoided + bytesReturned
     //   With    = bytes the model ACTUALLY re-saw after context-mode
-    //           = bytes_returned + eventDataBytes
+    //           = max(1, bytesReturned)
     //
-    // Why eventDataBytes belongs on BOTH sides:
-    //   `eventDataBytes` is the raw payload captured by the hook (tool args,
-    //   prompt body, etc). Those bytes were "kept out" — never inflated back
-    //   into context — but they still represent real measured signal. Pre-fix
-    //   the formula was `with = max(1, bytesReturned)`, which collapsed to 1
-    //   whenever the conversation hadn't accumulated any re-served bytes yet
-    //   (early in a session, or for tool-heavy work that never re-hits index).
-    //   That produced a degenerate ~100% kept-out bar even when the only
-    //   honest signal we had was a few KB of event payloads.
+    // Why eventDataBytes is excluded from this ratio:
+    //   `eventDataBytes` is the raw hook payload (tool args, prompt
+    //   body) we captured for the knowledge base. Those bytes are
+    //   analytics infrastructure — they NEVER enter the model context
+    //   window. Including them on either side (as v1.0.134 SLICE B did
+    //   to dodge a degenerate 100% bar) misrepresents context cost.
+    //   SLICE B was an incidental fix that crushed the displayed
+    //   percentage from ~95% (the true compression ratio) to ~56% on
+    //   live conversations. eventDataBytes is rendered in Section 2
+    //   (captures count), not in this Section 1 Without/With bar.
     //
-    // No fallback to heuristic. If the schema has zero signal for this
-    // conversation (no hook ever populated any of the three columns),
-    // the section is skipped entirely. Honesty over decoration.
+    // Empty-state branch:
+    //   If neither bytesAvoided nor bytesReturned has been measured yet
+    //   (early in a session, schema-migration recovery in progress, or
+    //   tool-heavy work that hasn't re-hit the index), we do NOT draw
+    //   a degenerate 0% / 100% bar. We emit one honest hint line and
+    //   skip the bar — honesty over decoration.
     const realConv = realBytes?.conversation;
     const measuredAvoided = realConv?.bytesAvoided ?? 0;
     const measuredReturned = realConv?.bytesReturned ?? 0;
-    const measuredEvent = realConv?.eventDataBytes ?? 0;
-    if (measuredAvoided + measuredReturned + measuredEvent > 0) {
-        const convBytesWithout = measuredAvoided + measuredReturned + measuredEvent;
-        const convBytesWith = Math.max(1, measuredReturned + measuredEvent);
+    if (measuredAvoided + measuredReturned === 0) {
+        // No measurable redirect activity yet — captures may exist, but
+        // nothing has been diverted from the model context window.
+        out.push("  No measurable redirect activity captured yet — bars will appear once context-mode diverts its first payload.");
+        out.push("");
+    }
+    else {
+        const convBytesWithout = measuredAvoided + measuredReturned;
+        const convBytesWith = Math.max(1, measuredReturned);
         const convTokensWithout = Math.max(1, Math.floor(convBytesWithout / 4));
         const convTokensWith = Math.max(1, Math.floor(convBytesWith / 4));
         const withoutBar = dataBar(convTokensWithout, convTokensWithout, 32);

package/build/session/db.d.ts

@@ -8,6 +8,42 @@
 import { SQLiteBase } from "../db-base.js";
 import type { SessionEvent } from "../types.js";
 import type { ProjectAttribution } from "./project-attribution.js";
+declare const STORAGE_ROOT_ENV: "CONTEXT_MODE_DIR";
+export type StorageDirectoryKind = "session" | "content" | "stats";
+export type StorageOverrideEnvVar = typeof STORAGE_ROOT_ENV;
+export type StorageDirectorySource = "default" | "override";
+export type IgnoredStorageOverrideReason = "empty";
+export interface ResolvedStorageDir {
+    kind: StorageDirectoryKind;
+    path: string;
+    envVar: StorageOverrideEnvVar | null;
+    source: StorageDirectorySource;
+    ignoredEnvVar?: StorageOverrideEnvVar;
+    ignoredReason?: IgnoredStorageOverrideReason;
+}
+export declare class StorageDirectoryError extends Error {
+    readonly kind: StorageDirectoryKind;
+    readonly path: string;
+    readonly overrideEnvVar: StorageOverrideEnvVar;
+    readonly ignoredEnvVar?: StorageOverrideEnvVar;
+    readonly ignoredReason?: IgnoredStorageOverrideReason;
+    constructor(kind: StorageDirectoryKind, path: string, overrideEnvVar?: StorageOverrideEnvVar, cause?: unknown, message?: string, metadata?: Pick<ResolvedStorageDir, "ignoredEnvVar" | "ignoredReason">);
+}
+export interface DefaultSessionDirOptions {
+    configDir: string;
+    configDirEnv?: string;
+    legacySessionDirEnv?: string;
+    onLegacySessionDir?: (envVar: string, dir: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveDefaultSessionDir(opts: DefaultSessionDirOptions): string;
+export declare function resolveSessionStorageDir(getDefaultDir: () => string): ResolvedStorageDir;
+export declare function resolveContentStorageDir(getSessionDir: () => string): ResolvedStorageDir;
+export declare function resolveStatsStorageDir(getDefaultSessionDir: () => string): ResolvedStorageDir;
+export declare function formatStorageDirectoryError(err: StorageDirectoryError): string;
+export declare function describeStorageDirectorySource(dir: ResolvedStorageDir): string;
+export declare function clearStorageDirectoryCheckCacheForTests(): void;
+export declare function ensureWritableStorageDir(dir: ResolvedStorageDir): string;
 export declare function normalizeWorktreePath(path: string): string;
 export declare function getWorktreeSuffix(projectDir?: string): string;
 export declare function _resetWorktreeSuffixCacheForTests(): void;
@@ -143,6 +179,50 @@ export interface ToolCallStats {
         bytesReturned: number;
     }>;
 }
+/**
+ * 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 declare function applyMissingSessionEventsColumns(db: {
+    pragma: (q: string) => Array<{
+        name: string;
+    }>;
+    exec: (sql: string) => void;
+}): boolean;
+/**
+ * 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 declare function ensureSessionEventsSchema(dbPath: string, DatabaseCtor: new (path: string, opts?: {
+    readonly?: boolean;
+}) => {
+    pragma: (q: string) => Array<{
+        name: string;
+    }>;
+    exec: (sql: string) => void;
+    close: () => void;
+}): void;
 export declare class SessionDB extends SQLiteBase {
     /**
      * Cached prepared statements. Stored in a Map to avoid the JS private-field
@@ -314,3 +394,4 @@ export declare class SessionDB extends SQLiteBase {
      */
     cleanupOldSessions(maxAgeDays?: number): number;
 }
+export {};

package/build/session/db.js

@@ -8,8 +8,203 @@
 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";
+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
 // ─────────────────────────────────────────────────────────
@@ -298,6 +493,87 @@ const S = {
     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 {
+        // best-effort — missing table, file lock, corrupt DB, or DatabaseCtor
+        // load failure. The aggregator's existing skip-on-error handles the
+        // downstream readonly query.
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+// ─────────────────────────────────────────────────────────
 // SessionDB
 // ─────────────────────────────────────────────────────────
 export class SessionDB extends SQLiteBase {
@@ -374,25 +650,11 @@ export class SessionDB extends SQLiteBase {
       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 {
-            const colInfo = this.db.pragma("table_xinfo(session_events)");
-            const cols = new Set(colInfo.map((c) => c.name));
-            if (!cols.has("project_dir")) {
-                this.db.exec("ALTER TABLE session_events ADD COLUMN project_dir TEXT NOT NULL DEFAULT ''");
-            }
-            if (!cols.has("attribution_source")) {
-                this.db.exec("ALTER TABLE session_events ADD COLUMN attribution_source TEXT NOT NULL DEFAULT 'unknown'");
-            }
-            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)");
+            applyMissingSessionEventsColumns(this.db);
         }
         catch {
             // best-effort migration only

package/build/session/extract.js

@@ -19,6 +19,22 @@ function safeStringAny(value) {
 }
 function isToolError(input) {
     const response = String(input.tool_response ?? "");
+    // PreToolUse rewrites curl/wget/inline-HTTP/WebFetch commands into
+    //   echo "context-mode: <guidance text including 'retry', 'fails', 'error'>"
+    // The user-facing copy legitimately mentions failure modes ("retry if it
+    // fails with a transient DNS error"), but those words must NOT classify
+    // our OWN guidance message as a tool error or it gets captured into
+    // session_resume and surfaces as a fake error in the next chat.
+    // We check BOTH sides because:
+    //   - real shell run → response starts with `context-mode:` (echo stdout)
+    //   - test/captured-output path → response is the raw command itself
+    //     (`echo "context-mode: …"`), so we also match the command shape
+    const command = String(input.tool_input?.command ?? "");
+    if (response.startsWith("context-mode:") ||
+        command.startsWith('echo "context-mode:') ||
+        command.startsWith("echo 'context-mode:")) {
+        return false;
+    }
     const isErrorFlag = input.tool_output?.isError === true || input.tool_output?.is_error === true;
     const isBashError = input.tool_name === "Bash" &&
         /exit code [1-9]|error:|Error:|FAIL|failed/i.test(response);

package/build/truncate.d.ts

@@ -5,6 +5,21 @@
  * SessionDB (snapshot building). They are extracted here so any
  * consumer can import them without pulling in the full store or executor.
  */
+/**
+ * Return a prefix of `str` no longer than `maxChars` UTF-16 code units, with
+ * the cut backed off by one unit if it would split a surrogate pair. Mirrors
+ * the surrogate-safety semantics of the internal `byteSafePrefix`, but uses
+ * a character budget rather than a byte budget.
+ *
+ * Use this instead of bare `str.slice(0, n)` whenever the result is later
+ * JSON-encoded for an RFC 8259-strict consumer (e.g. tool_result payloads
+ * sent back to the host LLM API). `JSON.stringify` will emit a lone high
+ * surrogate as a literal `\uD8xx` escape, which is invalid JSON.
+ *
+ * @param str      - Input string.
+ * @param maxChars - Hard cap in UTF-16 code units.
+ */
+export declare function charSafePrefix(str: string, maxChars: number): string;
 /**
  * Serialize a value to JSON, then truncate the result to `maxBytes` bytes.
  * If truncation occurs, the string is cut at a UTF-8-safe boundary and

package/build/truncate.js

@@ -43,6 +43,34 @@ function byteSafePrefix(str, maxBytes) {
     return str.slice(0, lo);
 }
 // ─────────────────────────────────────────────────────────
+// Char-count prefix (UTF-16 surrogate-safe)
+// ─────────────────────────────────────────────────────────
+/**
+ * Return a prefix of `str` no longer than `maxChars` UTF-16 code units, with
+ * the cut backed off by one unit if it would split a surrogate pair. Mirrors
+ * the surrogate-safety semantics of the internal `byteSafePrefix`, but uses
+ * a character budget rather than a byte budget.
+ *
+ * Use this instead of bare `str.slice(0, n)` whenever the result is later
+ * JSON-encoded for an RFC 8259-strict consumer (e.g. tool_result payloads
+ * sent back to the host LLM API). `JSON.stringify` will emit a lone high
+ * surrogate as a literal `\uD8xx` escape, which is invalid JSON.
+ *
+ * @param str      - Input string.
+ * @param maxChars - Hard cap in UTF-16 code units.
+ */
+export function charSafePrefix(str, maxChars) {
+    if (maxChars <= 0)
+        return "";
+    if (str.length <= maxChars)
+        return str;
+    let end = maxChars;
+    const code = str.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return str.slice(0, end);
+}
+// ─────────────────────────────────────────────────────────
 // JSON truncation
 // ─────────────────────────────────────────────────────────
 /**