context-mode 1.0.89 → 1.0.90

package/build/session/db.d.ts

@@ -7,6 +7,7 @@
  */
 import { SQLiteBase } from "../db-base.js";
 import type { SessionEvent } from "../types.js";
+import type { ProjectAttribution } from "./project-attribution.js";
 /**
  * Returns the worktree suffix to append to session identifiers.
  * Returns empty string when running in the main working tree.
@@ -24,6 +25,9 @@ export interface StoredEvent {
     category: string;
     priority: number;
     data: string;
+    project_dir: string;
+    attribution_source: string;
+    attribution_confidence: number;
     source_hook: string;
     created_at: string;
     data_hash: string;
@@ -71,7 +75,7 @@ export declare class SessionDB extends SQLiteBase {
      * Eviction: if session exceeds MAX_EVENTS_PER_SESSION, evicts the
      * lowest-priority (then oldest) event.
      */
-    insertEvent(sessionId: string, event: SessionEvent, sourceHook?: string): void;
+    insertEvent(sessionId: string, event: SessionEvent, sourceHook?: string, attribution?: Partial<ProjectAttribution>): void;
     /**
      * Retrieve events for a session with optional filtering.
      */
@@ -84,8 +88,13 @@ export declare class SessionDB extends SQLiteBase {
      * Get the total event count for a session.
      */
     getEventCount(sessionId: string): number;
+    /**
+     * Return the most recently attributed project dir for a session.
+     */
+    getLatestAttributedProjectDir(sessionId: string): string | null;
     /**
      * Ensure a session metadata entry exists. Idempotent (INSERT OR IGNORE).
+     * `projectDir` is the session origin directory, not per-event attribution.
      */
     ensureSession(sessionId: string, projectDir: string): void;
     /**

package/build/session/db.js

@@ -62,6 +62,7 @@ const S = {
     getEventsByPriority: "getEventsByPriority",
     getEventsByTypeAndPriority: "getEventsByTypeAndPriority",
     getEventCount: "getEventCount",
+    getLatestAttributedProject: "getLatestAttributedProject",
     checkDuplicate: "checkDuplicate",
     evictLowestPriority: "evictLowestPriority",
     updateMetaLastEvent: "updateMetaLastEvent",
@@ -109,6 +110,9 @@ export class SessionDB extends SQLiteBase {
         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,
         source_hook TEXT NOT NULL,
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
         data_hash TEXT NOT NULL DEFAULT ''
@@ -136,6 +140,24 @@ export class SessionDB extends SQLiteBase {
         consumed INTEGER NOT NULL DEFAULT 0
       );
     `);
+        // Migration: add per-event attribution columns for existing DBs.
+        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");
+            }
+            this.db.exec("CREATE INDEX IF NOT EXISTS idx_session_events_project ON session_events(session_id, project_dir)");
+        }
+        catch {
+            // best-effort migration only
+        }
     }
     prepareStatements() {
         this.stmts = new Map();
@@ -143,17 +165,34 @@ export class SessionDB extends SQLiteBase {
             this.stmts.set(key, this.db.prepare(sql));
         };
         // ── Events ──
-        p(S.insertEvent, `INSERT INTO session_events (session_id, type, category, priority, data, source_hook, data_hash)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`);
-        p(S.getEvents, `SELECT id, session_id, type, category, priority, data, source_hook, created_at, data_hash
+        p(S.insertEvent, `INSERT INTO session_events (
+         session_id, type, category, priority, data,
+         project_dir, attribution_source, attribution_confidence,
+         source_hook, data_hash
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        p(S.getEvents, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              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, source_hook, created_at, data_hash
+        p(S.getEventsByType, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              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, source_hook, created_at, data_hash
+        p(S.getEventsByPriority, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              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, source_hook, created_at, data_hash
+        p(S.getEventsByTypeAndPriority, `SELECT id, session_id, type, category, priority, data,
+              project_dir, attribution_source, attribution_confidence,
+              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 ?
@@ -201,13 +240,25 @@ 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") {
+    insertEvent(sessionId, event, sourceHook = "PostToolUse", attribution) {
         // 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
+            ?? "").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;
         // Atomic: dedup check + eviction + insert in a single transaction
         // to prevent race conditions from concurrent hook calls.
         const transaction = this.db.transaction(() => {
@@ -221,7 +272,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, sourceHook, dataHash);
+            this.stmt(S.insertEvent).run(sessionId, event.type, event.category, event.priority, event.data, projectDir, attributionSource, attributionConfidence, sourceHook, dataHash);
             // Update meta if session exists
             this.stmt(S.updateMetaLastEvent).run(sessionId);
         });
@@ -252,11 +303,19 @@ export class SessionDB extends SQLiteBase {
         const row = this.stmt(S.getEventCount).get(sessionId);
         return row.cnt;
     }
+    /**
+     * 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;
+    }
     // ═══════════════════════════════════════════
     // 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);

package/build/session/extract.js

@@ -364,7 +364,7 @@ function extractSubagent(input) {
  * MCP tool calls (context7, playwright, claude-mem, ctx-stats, etc.).
  */
 function extractMcp(input) {
-    const { tool_name, tool_input } = input;
+    const { tool_name, tool_input, tool_response } = input;
     if (!tool_name.startsWith("mcp__"))
         return [];
     // Extract readable tool name: last segment after __
@@ -373,10 +373,18 @@ function extractMcp(input) {
     // Extract first string argument for context
     const firstArg = Object.values(tool_input).find((v) => typeof v === "string");
     const argStr = firstArg ? `: ${safeString(String(firstArg))}` : "";
+    // Append tool_response so ctx_search can find what the MCP returned — not
+    // just the call shape. Without this, bodies from external MCPs (jira tickets,
+    // grafana loki lines, sentry issues, context7 docs) are invisible to search.
+    // No truncation: matches the rule_content precedent above — SQLite TEXT is
+    // unbounded and large responses are the ones a cache most wants to preserve.
+    const responseStr = tool_response && tool_response.length > 0
+        ? `\nresponse: ${safeString(tool_response)}`
+        : "";
     return [{
             type: "mcp",
             category: "mcp",
-            data: safeString(`${toolShort}${argStr}`),
+            data: safeString(`${toolShort}${argStr}${responseStr}`),
             priority: 3,
         }];
 }

package/build/session/project-attribution.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Project attribution heuristics for session events.
+ *
+ * Goal: avoid pinning all activity to the startup directory when work shifts
+ * across projects mid-session. This module resolves a best-effort project
+ * directory per event and attaches a confidence score + source signal.
+ */
+import type { SessionEvent } from "../types.js";
+/**
+ * Confidence scores for project attribution sources.
+ *
+ * Higher = more reliable signal. The hierarchy reflects how directly
+ * the signal indicates the user's intended project:
+ * - Explicit config (workspace roots) > explicit navigation (cd) > implicit context
+ * - Path-bearing events score higher than fallbacks without path signals
+ */
+export declare const ATTRIBUTION_CONFIDENCE: {
+    /** Explicit workspace root from IDE/editor config */
+    readonly WORKSPACE_ROOT: 0.98;
+    /** User explicitly navigated here (cd command) */
+    readonly CWD_EVENT: 0.9;
+    /** Hook payload cwd — reliable but implicit */
+    readonly INPUT_CWD: 0.88;
+    /** Session startup directory */
+    readonly SESSION_ORIGIN: 0.82;
+    /** Carry-forward from previous high-confidence event */
+    readonly LAST_SEEN: 0.76;
+    /** Inferred from file path prefix matching */
+    readonly EVENT_PATH: 0.7;
+    /** Minimum confidence to carry forward as lastKnownProjectDir */
+    readonly CARRY_FORWARD_THRESHOLD: 0.55;
+    /** Fallback: input_cwd without path signal */
+    readonly FALLBACK_INPUT_CWD: 0.45;
+    /** Fallback: last_seen without path signal */
+    readonly FALLBACK_LAST_SEEN: 0.4;
+    /** Fallback: session_origin without path signal */
+    readonly FALLBACK_SESSION_ORIGIN: 0.35;
+};
+export type AttributionSource = "event_path" | "cwd_event" | "input_cwd" | "workspace_root" | "last_seen" | "session_origin" | "unknown";
+export interface ProjectAttribution {
+    projectDir: string;
+    source: AttributionSource;
+    confidence: number;
+}
+export interface AttributionContext {
+    sessionOriginDir?: string | null;
+    inputProjectDir?: string | null;
+    workspaceRoots?: string[] | null;
+    lastKnownProjectDir?: string | null;
+}
+/**
+ * Resolve the most likely project directory for one event.
+ */
+export declare function resolveProjectAttribution(event: SessionEvent, context: AttributionContext): ProjectAttribution;
+/**
+ * Convenience helper: resolve attributions for a stream of events while
+ * carrying forward the latest confident project as context.
+ */
+export declare function resolveProjectAttributions(events: SessionEvent[], context: AttributionContext): ProjectAttribution[];
+/**
+ * 0..100 score for UI display.
+ */
+export declare function confidenceToPercent(confidence: number): number;
+/**
+ * True when attribution is strong enough for project-level spending claims.
+ */
+export declare function isHighConfidenceAttribution(confidence: number): boolean;
+/**
+ * Lightweight utility used by some hooks to normalize path separators
+ * before writing attribution metadata.
+ */
+export declare function normalizeProjectDir(projectDir: string): string;
+export declare const PROJECT_ATTRIBUTION_VERSION = 1;

package/build/session/project-attribution.js

@@ -0,0 +1,231 @@
+/**
+ * Project attribution heuristics for session events.
+ *
+ * Goal: avoid pinning all activity to the startup directory when work shifts
+ * across projects mid-session. This module resolves a best-effort project
+ * directory per event and attaches a confidence score + source signal.
+ */
+import { dirname, isAbsolute, normalize, resolve, sep } from "node:path";
+/**
+ * Confidence scores for project attribution sources.
+ *
+ * Higher = more reliable signal. The hierarchy reflects how directly
+ * the signal indicates the user's intended project:
+ * - Explicit config (workspace roots) > explicit navigation (cd) > implicit context
+ * - Path-bearing events score higher than fallbacks without path signals
+ */
+export const ATTRIBUTION_CONFIDENCE = {
+    /** Explicit workspace root from IDE/editor config */
+    WORKSPACE_ROOT: 0.98,
+    /** User explicitly navigated here (cd command) */
+    CWD_EVENT: 0.9,
+    /** Hook payload cwd — reliable but implicit */
+    INPUT_CWD: 0.88,
+    /** Session startup directory */
+    SESSION_ORIGIN: 0.82,
+    /** Carry-forward from previous high-confidence event */
+    LAST_SEEN: 0.76,
+    /** Inferred from file path prefix matching */
+    EVENT_PATH: 0.7,
+    /** Minimum confidence to carry forward as lastKnownProjectDir */
+    CARRY_FORWARD_THRESHOLD: 0.55,
+    /** Fallback: input_cwd without path signal */
+    FALLBACK_INPUT_CWD: 0.45,
+    /** Fallback: last_seen without path signal */
+    FALLBACK_LAST_SEEN: 0.4,
+    /** Fallback: session_origin without path signal */
+    FALLBACK_SESSION_ORIGIN: 0.35,
+};
+function normalizePath(path) {
+    const norm = normalize(path).replace(/\\/g, "/");
+    if (norm.length <= 1)
+        return norm;
+    return norm.replace(/\/+$/, "");
+}
+function isPrefixPath(path, prefix) {
+    if (!path || !prefix)
+        return false;
+    if (path === prefix)
+        return true;
+    return path.startsWith(`${prefix}/`);
+}
+function normalizeRoots(roots) {
+    if (!roots || roots.length === 0)
+        return [];
+    const normalized = roots
+        .filter((r) => typeof r === "string" && r.trim().length > 0)
+        .map((r) => normalizePath(r));
+    // dedupe + longest-first for stable best match
+    const unique = Array.from(new Set(normalized));
+    return unique.sort((a, b) => b.length - a.length);
+}
+function parseFileSearchPath(data) {
+    const marker = " in ";
+    const idx = data.lastIndexOf(marker);
+    if (idx < 0)
+        return null;
+    const path = data.slice(idx + marker.length).trim();
+    return path.length > 0 ? path : null;
+}
+function looksLikePath(value) {
+    if (!value)
+        return false;
+    // Fast path-like checks: separators, dot segments, drive roots.
+    return value.includes("/")
+        || value.includes("\\")
+        || value.startsWith(".")
+        || /^[A-Za-z]:[\\/]/.test(value);
+}
+function extractPathSignal(event) {
+    if (event.type === "cwd") {
+        return { rawPath: event.data, fromCwdEvent: true };
+    }
+    if (event.type === "file_search") {
+        const path = parseFileSearchPath(event.data);
+        if (path)
+            return { rawPath: path, fromCwdEvent: false };
+    }
+    const fileTypes = new Set([
+        "file_read",
+        "file_write",
+        "file_edit",
+        "file_glob",
+        "rule",
+    ]);
+    if (fileTypes.has(event.type) && looksLikePath(event.data)) {
+        return { rawPath: event.data, fromCwdEvent: false };
+    }
+    return null;
+}
+function absolutizePath(rawPath, context) {
+    if (!rawPath)
+        return null;
+    // Ignore broad glob-only patterns that aren't useful for attribution.
+    if (rawPath.includes("*") && !isAbsolute(rawPath) && !/^[A-Za-z]:[\\/]/.test(rawPath)) {
+        return null;
+    }
+    if (isAbsolute(rawPath) || /^[A-Za-z]:[\\/]/.test(rawPath)) {
+        return normalizePath(rawPath);
+    }
+    // For relative paths, anchor to the most recent known project first.
+    const anchor = context.lastKnownProjectDir
+        || context.inputProjectDir
+        || context.sessionOriginDir
+        || null;
+    if (!anchor)
+        return null;
+    return normalizePath(resolve(anchor, rawPath));
+}
+function inferProjectFromAbsolutePath(absPath, event, context) {
+    const normalizedRoots = normalizeRoots(context.workspaceRoots);
+    const normalizedOrigin = context.sessionOriginDir ? normalizePath(context.sessionOriginDir) : "";
+    const normalizedInput = context.inputProjectDir ? normalizePath(context.inputProjectDir) : "";
+    const normalizedLast = context.lastKnownProjectDir ? normalizePath(context.lastKnownProjectDir) : "";
+    // 1) Prefer explicit workspace roots (highest confidence).
+    const workspaceRoot = normalizedRoots.find((root) => isPrefixPath(absPath, root));
+    if (workspaceRoot) {
+        return { projectDir: workspaceRoot, source: "workspace_root", confidence: ATTRIBUTION_CONFIDENCE.WORKSPACE_ROOT };
+    }
+    // 2) Prefer stable known roots from session context.
+    if (normalizedInput && isPrefixPath(absPath, normalizedInput)) {
+        return { projectDir: normalizedInput, source: "input_cwd", confidence: ATTRIBUTION_CONFIDENCE.INPUT_CWD };
+    }
+    if (normalizedOrigin && isPrefixPath(absPath, normalizedOrigin)) {
+        return { projectDir: normalizedOrigin, source: "session_origin", confidence: ATTRIBUTION_CONFIDENCE.SESSION_ORIGIN };
+    }
+    if (normalizedLast && isPrefixPath(absPath, normalizedLast)) {
+        return { projectDir: normalizedLast, source: "last_seen", confidence: ATTRIBUTION_CONFIDENCE.LAST_SEEN };
+    }
+    // 3) Direct cwd events indicate explicit operator intent to shift project.
+    if (event.type === "cwd") {
+        return { projectDir: absPath, source: "cwd_event", confidence: ATTRIBUTION_CONFIDENCE.CWD_EVENT };
+    }
+    // 4) Fallback for out-of-root absolute paths.
+    // For known file events, use parent directory to avoid attributing to a file path.
+    const fileLike = new Set(["file_read", "file_write", "file_edit", "rule"]);
+    const projectDir = fileLike.has(event.type) ? normalizePath(dirname(absPath)) : absPath;
+    return { projectDir, source: "event_path", confidence: ATTRIBUTION_CONFIDENCE.EVENT_PATH };
+}
+function fallbackAttribution(context) {
+    if (context.inputProjectDir) {
+        return {
+            projectDir: normalizePath(context.inputProjectDir),
+            source: "input_cwd",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_INPUT_CWD,
+        };
+    }
+    if (context.lastKnownProjectDir) {
+        return {
+            projectDir: normalizePath(context.lastKnownProjectDir),
+            source: "last_seen",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_LAST_SEEN,
+        };
+    }
+    if (context.sessionOriginDir) {
+        return {
+            projectDir: normalizePath(context.sessionOriginDir),
+            source: "session_origin",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_SESSION_ORIGIN,
+        };
+    }
+    return { projectDir: "", source: "unknown", confidence: 0 };
+}
+/**
+ * Resolve the most likely project directory for one event.
+ */
+export function resolveProjectAttribution(event, context) {
+    try {
+        const pathSignal = extractPathSignal(event);
+        if (!pathSignal)
+            return fallbackAttribution(context);
+        const absPath = absolutizePath(pathSignal.rawPath, context);
+        if (!absPath)
+            return fallbackAttribution(context);
+        return inferProjectFromAbsolutePath(absPath, event, context);
+    }
+    catch {
+        return fallbackAttribution(context);
+    }
+}
+/**
+ * Convenience helper: resolve attributions for a stream of events while
+ * carrying forward the latest confident project as context.
+ */
+export function resolveProjectAttributions(events, context) {
+    const out = [];
+    let lastKnown = context.lastKnownProjectDir ? normalizePath(context.lastKnownProjectDir) : "";
+    for (const ev of events) {
+        const attribution = resolveProjectAttribution(ev, {
+            ...context,
+            lastKnownProjectDir: lastKnown || context.lastKnownProjectDir || null,
+        });
+        out.push(attribution);
+        if (attribution.projectDir && attribution.confidence >= ATTRIBUTION_CONFIDENCE.CARRY_FORWARD_THRESHOLD) {
+            lastKnown = attribution.projectDir;
+        }
+    }
+    return out;
+}
+/**
+ * 0..100 score for UI display.
+ */
+export function confidenceToPercent(confidence) {
+    const clamped = Math.max(0, Math.min(1, confidence));
+    return Math.round(clamped * 100);
+}
+/**
+ * True when attribution is strong enough for project-level spending claims.
+ */
+export function isHighConfidenceAttribution(confidence) {
+    return confidence >= 0.8;
+}
+/**
+ * Lightweight utility used by some hooks to normalize path separators
+ * before writing attribution metadata.
+ */
+export function normalizeProjectDir(projectDir) {
+    return normalizePath(projectDir);
+}
+export const PROJECT_ATTRIBUTION_VERSION = 1;
+// Keep explicit references to path separator for bundlers that tree-shake too aggressively.
+void sep;

package/build/store.d.ts

@@ -53,11 +53,15 @@ export declare class ContentStore {
     searchTrigram(query: string, limit?: number, source?: string, mode?: "AND" | "OR", contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode): SearchResult[];
     fuzzyCorrect(query: string): string | null;
     searchWithFallback(query: string, limit?: number, source?: string, contentType?: "code" | "prose", sourceMatchMode?: SourceMatchMode): SearchResult[];
+    /** Number of sources auto-refreshed in the last searchWithFallback call. */
+    lastRefreshCount: number;
     getSourceMeta(label: string): {
         label: string;
         chunkCount: number;
         codeChunkCount: number;
         indexedAt: string;
+        filePath: string | null;
+        contentHash: string | null;
     } | null;
     listSources(): Array<{
         label: string;

package/build/store.js

@@ -10,6 +10,7 @@
 var _a;
 import { loadDatabase, applyWALPragmas, closeDB, cleanOrphanedWALFiles, withRetry, deleteDBFiles, isSQLiteCorruptionError } from "./db-base.js";
 import { readFileSync, readdirSync, unlinkSync, existsSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 // ─────────────────────────────────────────────────────────
@@ -357,7 +358,9 @@ export class ContentStore {
         label TEXT NOT NULL,
         chunk_count INTEGER NOT NULL DEFAULT 0,
         code_chunk_count INTEGER NOT NULL DEFAULT 0,
-        indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
+        indexed_at TEXT NOT NULL DEFAULT (datetime('now')),
+        file_path TEXT,
+        content_hash TEXT
       );
 
       CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
@@ -382,11 +385,20 @@ export class ContentStore {
 
       CREATE INDEX IF NOT EXISTS idx_sources_label ON sources(label);
     `);
+        // Stale detection columns — safe for existing DBs (ALTER is O(1) in SQLite)
+        try {
+            this.#db.exec("ALTER TABLE sources ADD COLUMN file_path TEXT");
+        }
+        catch { /* already exists */ }
+        try {
+            this.#db.exec("ALTER TABLE sources ADD COLUMN content_hash TEXT");
+        }
+        catch { /* already exists */ }
     }
     #prepareStatements() {
         // Write path
-        this.#stmtInsertSourceEmpty = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count) VALUES (?, 0, 0)");
-        this.#stmtInsertSource = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count) VALUES (?, ?, ?)");
+        this.#stmtInsertSourceEmpty = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count, file_path, content_hash) VALUES (?, 0, 0, ?, ?)");
+        this.#stmtInsertSource = this.#db.prepare("INSERT INTO sources (label, chunk_count, code_chunk_count, file_path, content_hash) VALUES (?, ?, ?, ?, ?)");
         this.#stmtInsertChunk = this.#db.prepare("INSERT INTO chunks (title, content, source_id, content_type) VALUES (?, ?, ?, ?)");
         this.#stmtInsertChunkTrigram = this.#db.prepare("INSERT INTO chunks_trigram (title, content, source_id, content_type) VALUES (?, ?, ?, ?)");
         this.#stmtInsertVocab = this.#db.prepare("INSERT OR IGNORE INTO vocabulary (word) VALUES (?)");
@@ -576,7 +588,7 @@ export class ContentStore {
        ORDER BY c.rowid`);
         this.#stmtSourceChunkCount = this.#db.prepare("SELECT chunk_count FROM sources WHERE id = ?");
         this.#stmtChunkContent = this.#db.prepare("SELECT content FROM chunks WHERE source_id = ?");
-        this.#stmtSourceMeta = this.#db.prepare("SELECT label, chunk_count, code_chunk_count, indexed_at FROM sources WHERE label = ?");
+        this.#stmtSourceMeta = this.#db.prepare("SELECT label, chunk_count, code_chunk_count, indexed_at, file_path, content_hash FROM sources WHERE label = ?");
         this.#stmtStats = this.#db.prepare(`
       SELECT
         (SELECT COUNT(*) FROM sources) AS sources,
@@ -597,7 +609,10 @@ export class ContentStore {
         const text = content ?? readFileSync(path, "utf-8");
         const label = source ?? path ?? "untitled";
         const chunks = this.#chunkMarkdown(text);
-        return withRetry(() => this.#insertChunks(chunks, label, text));
+        // Stale detection: store file_path + SHA-256 for file-backed sources
+        const filePath = path ?? undefined;
+        const contentHash = filePath ? createHash("sha256").update(text).digest("hex") : undefined;
+        return withRetry(() => this.#insertChunks(chunks, label, text, filePath, contentHash));
     }
     // ── Index Plain Text ──
     /**
@@ -644,7 +659,7 @@ export class ContentStore {
      * into both FTS5 tables within a transaction and extracts vocabulary.
      * Uses cached prepared statements from #prepareStatements().
      */
-    #insertChunks(chunks, label, text) {
+    #insertChunks(chunks, label, text, filePath, contentHash) {
         const codeChunks = chunks.filter((c) => c.hasCode).length;
         // Atomic dedup + insert: delete previous source with same label,
         // then insert new content — all within a single transaction.
@@ -654,10 +669,10 @@ export class ContentStore {
             this.#stmtDeleteChunksTrigramByLabel.run(label);
             this.#stmtDeleteSourcesByLabel.run(label);
             if (chunks.length === 0) {
-                const info = this.#stmtInsertSourceEmpty.run(label);
+                const info = this.#stmtInsertSourceEmpty.run(label, filePath ?? null, contentHash ?? null);
                 return Number(info.lastInsertRowid);
             }
-            const info = this.#stmtInsertSource.run(label, chunks.length, codeChunks);
+            const info = this.#stmtInsertSource.run(label, chunks.length, codeChunks, filePath ?? null, contentHash ?? null);
             const sourceId = Number(info.lastInsertRowid);
             for (const chunk of chunks) {
                 const ct = chunk.hasCode ? "code" : "prose";
@@ -861,6 +876,8 @@ export class ContentStore {
     }
     // ── Unified Fallback Search ──
     searchWithFallback(query, limit = 3, source, contentType, sourceMatchMode = "like") {
+        // Step 0: Auto-refresh stale file-backed sources before searching
+        this.#refreshStaleSources();
         // Step 1: RRF fusion (porter OR + trigram OR → merge)
         const rrfResults = this.#rrfSearch(query, limit, source, contentType, sourceMatchMode);
         if (rrfResults.length > 0) {
@@ -887,12 +904,44 @@ export class ContentStore {
         }
         return [];
     }
+    /** Number of sources auto-refreshed in the last searchWithFallback call. */
+    lastRefreshCount = 0;
+    /**
+     * Check all file-backed sources for staleness and auto re-index changed files.
+     * Uses mtime as a fast gate — only computes SHA-256 when mtime has advanced
+     * past indexed_at. Gracefully skips deleted files and non-file sources.
+     */
+    #refreshStaleSources() {
+        this.lastRefreshCount = 0;
+        const sources = this.#db.prepare("SELECT label, file_path, content_hash, indexed_at FROM sources WHERE file_path IS NOT NULL").all();
+        for (const src of sources) {
+            try {
+                if (!existsSync(src.file_path))
+                    continue; // file deleted — keep cached results
+                const mtime = statSync(src.file_path).mtime;
+                const indexedAt = new Date(src.indexed_at + "Z");
+                if (mtime <= indexedAt)
+                    continue; // file unchanged — fast path
+                // mtime advanced — check hash to confirm real change (not just touch)
+                const newContent = readFileSync(src.file_path, "utf-8");
+                const newHash = createHash("sha256").update(newContent).digest("hex");
+                if (newHash === src.content_hash)
+                    continue; // content identical — skip
+                // File genuinely changed — re-index
+                this.index({ path: src.file_path, source: src.label });
+                this.lastRefreshCount++;
+            }
+            catch {
+                // Graceful degradation — never break search for stale detection
+            }
+        }
+    }
     // ── Sources ──
     getSourceMeta(label) {
         const row = this.#stmtSourceMeta.get(label);
         if (!row)
             return null;
-        return { label: row.label, chunkCount: row.chunk_count, codeChunkCount: row.code_chunk_count, indexedAt: row.indexed_at };
+        return { label: row.label, chunkCount: row.chunk_count, codeChunkCount: row.code_chunk_count, indexedAt: row.indexed_at, filePath: row.file_path ?? null, contentHash: row.content_hash ?? null };
     }
     listSources() {
         return this.#stmtListSources.all();