context-mode 1.0.89 → 1.0.91

package/build/session/analytics.js

@@ -8,6 +8,17 @@
  *   const engine = new AnalyticsEngine(sessionDb);
  *   const report = engine.queryAll(runtimeStats);
  */
+function semverNewer(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}
 // ─────────────────────────────────────────────────────────
 // Category labels and hints for session continuity display
 // ─────────────────────────────────────────────────────────
@@ -216,7 +227,7 @@ export class AnalyticsEngine {
     }
 }
 // ─────────────────────────────────────────────────────────
-// formatReport — renders FullReport as concise, honest output
+// formatReport — renders FullReport as sales-grade savings dashboard
 // ─────────────────────────────────────────────────────────
 /** Format bytes as human-readable KB or MB. */
 function kb(b) {
@@ -224,7 +235,7 @@ function kb(b) {
         return `${(b / 1024 / 1024).toFixed(1)} MB`;
     if (b >= 1024)
         return `${(b / 1024).toFixed(1)} KB`;
-    return `${b} B`;
+    return `${Math.round(b)} B`;
 }
 /** Format session uptime as human-readable duration. */
 function formatDuration(uptimeMin) {
@@ -237,28 +248,34 @@ function formatDuration(uptimeMin) {
     const m = Math.round(min % 60);
     return m > 0 ? `${h}h ${m}m` : `${h}h`;
 }
+/** Format large numbers with K/M suffixes */
+function fmtNum(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}
 /**
- * Build a before/after comparison bar.
- *
- * The "without" bar is always full (40 chars).
- * The "with" bar is proportional to the ratio of returned vs total.
+ * Build a proportional bar using █ chars, scaled to a fixed width.
+ * Returns e.g. "████████████████████████████████████████" for full width.
  */
-function comparisonBars(total, returned) {
-    const BAR_WIDTH = 40;
-    const withoutBar = "#".repeat(BAR_WIDTH);
-    const withFill = total > 0 ? Math.max(1, Math.round((returned / total) * BAR_WIDTH)) : BAR_WIDTH;
-    const withBar = "#".repeat(withFill) + " ".repeat(BAR_WIDTH - withFill);
-    return { withoutBar, withBar };
+function dataBar(bytes, maxBytes, width = 40) {
+    if (maxBytes <= 0)
+        return "░".repeat(width);
+    const filled = Math.max(1, Math.round((bytes / maxBytes) * width));
+    return "█".repeat(Math.min(filled, width)) + "░".repeat(Math.max(0, width - filled));
 }
 /**
- * Render a FullReport as a before/after comparison developers instantly understand.
+ * Render a FullReport as a visual savings dashboard designed for screenshotting.
  *
- * Design rules:
- * - If no savings, show "fresh session" format (no fake percentages)
- * - Active session shows BEFORE vs AFTER -- what would have flooded your conversation vs what actually did
- * - Per-tool table only if 2+ different tools were called
- * - Time gained is the hero metric
- * - Under 15 lines for typical sessions
+ * Design principles:
+ * - Before/After comparison bar is the HERO — one glance = "wow"
+ * - "tokens saved" is the number people share
+ * - Per-tool breakdown shows what each tool SAVED, sorted by impact
+ * - Session memory: one line, reframed as value
+ * - No: Pct column, category tables, tips, jargon
+ * - Under 22 lines for heavy sessions, under 10 for fresh
  */
 export function formatReport(report, version, latestVersion) {
     const lines = [];
@@ -267,86 +284,100 @@ export function formatReport(report, version, latestVersion) {
     const totalKeptOut = report.savings.kept_out + (report.cache ? report.cache.bytes_saved : 0);
     const totalReturned = report.savings.total_bytes_returned;
     const totalCalls = report.savings.total_calls;
-    // ── Fresh session: almost no activity ──
+    const grandTotal = totalKeptOut + totalReturned;
+    const savingsPct = grandTotal > 0 ? (totalKeptOut / grandTotal) * 100 : 0;
+    const tokensSaved = Math.round(totalKeptOut / 4);
+    // ── Fresh session: no savings yet ──
     if (totalKeptOut === 0) {
-        lines.push(`context-mode -- session (${duration})`);
+        lines.push(`context-mode  ${duration}  ${totalCalls} calls`);
         lines.push("");
         if (totalCalls === 0) {
-            lines.push("No tool calls yet.");
+            lines.push("No tool calls yet. Use batch_execute or execute to start saving tokens.");
         }
         else {
-            const callLabel = totalCalls === 1 ? "1 tool call" : `${totalCalls} tool calls`;
-            lines.push(`${callLabel}  |  ${kb(totalReturned)} in context  |  no savings yet`);
+            lines.push(`${kb(totalReturned)} entered context  |  0 tokens saved`);
         }
+        // Footer
         lines.push("");
-        lines.push("Tip: Use ctx_execute to analyze files in sandbox -- savings start there.");
-        lines.push("");
-        lines.push(version ? `v${version}` : "context-mode");
-        if (version && latestVersion && latestVersion !== "unknown" && latestVersion !== version) {
-            lines.push(`Update available: v${version} -> v${latestVersion}  |  Run: ctx_upgrade`);
+        const versionStr = version ? `v${version}` : "context-mode";
+        lines.push(versionStr);
+        if (version && latestVersion && latestVersion !== "unknown" && semverNewer(latestVersion, version)) {
+            lines.push(`Update available: v${version} -> v${latestVersion}  |  ctx_upgrade`);
         }
         return lines.join("\n");
     }
-    // ── Active session with real savings ──
-    const grandTotal = totalKeptOut + totalReturned;
-    const savingsPercent = grandTotal > 0
-        ? ((totalKeptOut / grandTotal) * 100).toFixed(1)
-        : "0.0";
-    // ── Time saved estimate (hero metric) ──
-    // ~4 bytes per token, ~1000 tokens per minute of context window capacity
-    const minSaved = Math.round(totalKeptOut / 4 / 1000);
-    lines.push(`context-mode -- session (${duration})`);
+    // ── Active session: visual savings dashboard ──
+    // Line 1: Hero metric — the screenshottable number
+    lines.push(`${fmtNum(tokensSaved)} tokens saved  ·  ${savingsPct.toFixed(1)}% reduction  ·  ${duration}`);
+    lines.push("");
+    // Lines 2-3: Before/After comparison bars — the visual proof
+    lines.push(`Without context-mode  |${dataBar(grandTotal, grandTotal)}| ${kb(grandTotal)}`);
+    lines.push(`With context-mode     |${dataBar(totalReturned, grandTotal)}| ${kb(totalReturned)}`);
     lines.push("");
-    // ── Before/after comparison ──
-    const { withoutBar, withBar } = comparisonBars(grandTotal, totalReturned);
-    lines.push(`Without context-mode:  |${withoutBar}| ${kb(grandTotal)} in your conversation`);
-    lines.push(`With context-mode:     |${withBar}| ${kb(totalReturned)} in your conversation`);
+    // Value statement — the line people share
+    lines.push(`${kb(totalKeptOut)} kept out of your conversation. Never entered context.`);
     lines.push("");
-    const savingsLine = `${kb(totalKeptOut)} processed in sandbox, never entered your conversation. (${savingsPercent}% reduction)`;
-    lines.push(savingsLine);
-    if (minSaved > 0) {
-        const timeSaved = minSaved >= 60
-            ? `+${Math.floor(minSaved / 60)}h ${minSaved % 60}m`
-            : `+${minSaved}m`;
-        lines.push(`${timeSaved} session time gained.`);
+    // Compact stats row
+    const statParts = [`${totalCalls} calls`];
+    if (report.cache && report.cache.hits > 0) {
+        statParts.push(`${report.cache.hits} cache hits (+${kb(report.cache.bytes_saved)})`);
     }
-    // ── Per-tool table (only if 2+ different tools) ──
+    lines.push(statParts.join("  ·  "));
+    // ── Per-tool breakdown (only if 2+ tools, sorted by saved) ──
     const activatedTools = report.savings.by_tool.filter((t) => t.calls > 0);
     if (activatedTools.length >= 2) {
         lines.push("");
-        for (const t of activatedTools) {
-            const returned = t.context_kb * 1024;
-            const callLabel = `${t.calls} call${t.calls !== 1 ? "s" : ""}`;
-            lines.push(`  ${t.tool.padEnd(22)} ${callLabel.padEnd(10)} ${kb(returned)} used`);
+        // Estimate per-tool saved using global savings ratio
+        const toolRows = activatedTools.map((t) => {
+            const returnedBytes = t.context_kb * 1024;
+            const estimatedTotal = savingsPct < 100
+                ? returnedBytes / (1 - savingsPct / 100)
+                : returnedBytes;
+            const estimatedSaved = Math.max(0, estimatedTotal - returnedBytes);
+            return { ...t, returnedBytes, estimatedSaved };
+        }).sort((a, b) => b.estimatedSaved - a.estimatedSaved);
+        // Compact table: tool name, calls, saved
+        for (const t of toolRows) {
+            const name = t.tool.length > 22 ? t.tool.slice(0, 19) + "..." : t.tool;
+            lines.push(`  ${name.padEnd(22)}  ${String(t.calls).padStart(4)} calls  ${kb(t.estimatedSaved).padStart(8)} saved`);
         }
     }
-    // ── Session continuity breakdown ──
-    if (report.continuity.by_category.length > 0) {
+    // ── Session memory — business-friendly ──
+    if (report.continuity.total_events > 0) {
         lines.push("");
-        lines.push(`Session continuity: ${report.continuity.total_events} events preserved across ${report.continuity.compact_count} compaction${report.continuity.compact_count !== 1 ? "s" : ""}`);
-        lines.push("");
-        for (const c of report.continuity.by_category) {
-            const cat = c.category.padEnd(9);
-            const count = String(c.count).padStart(3);
-            const preview = c.preview.length > 45 ? c.preview.slice(0, 42) + "..." : c.preview;
-            lines.push(`  ${cat} ${count}   ${preview.padEnd(47)} ${c.why}`);
+        const cats = report.continuity.by_category;
+        // Pick the top 3-4 most impactful categories for a human-readable summary
+        const highlights = [];
+        const fileCount = cats.find(c => c.category === "file")?.count;
+        const gitCount = cats.find(c => c.category === "git")?.count;
+        const promptCount = cats.find(c => c.category === "prompt")?.count;
+        const errorCount = cats.find(c => c.category === "error")?.count;
+        const taskCount = cats.find(c => c.category === "task")?.count;
+        if (fileCount)
+            highlights.push(`${fileCount} files`);
+        if (gitCount)
+            highlights.push(`${gitCount} git ops`);
+        if (promptCount)
+            highlights.push(`${promptCount} prompts`);
+        if (errorCount)
+            highlights.push(`${errorCount} errors`);
+        if (taskCount)
+            highlights.push(`${taskCount} tasks`);
+        const summary = highlights.length > 0 ? `  ·  ${highlights.join(", ")}` : "";
+        if (report.continuity.compact_count > 0) {
+            lines.push(`${fmtNum(report.continuity.total_events)} events remembered across ${report.continuity.compact_count} compaction${report.continuity.compact_count !== 1 ? "s" : ""}${summary}`);
+            lines.push("Zero knowledge lost — picks up exactly where you left off.");
+        }
+        else {
+            lines.push(`${fmtNum(report.continuity.total_events)} events tracked${summary}`);
         }
     }
-    // ── Footer: version + outdated warning ──
-    const footerParts = [];
-    if (report.continuity.by_category.length === 0 && report.continuity.compact_count > 0) {
-        footerParts.push(`${report.continuity.compact_count} compaction${report.continuity.compact_count !== 1 ? "s" : ""}`);
-    }
-    if (report.continuity.by_category.length === 0 && report.continuity.total_events > 0) {
-        footerParts.push(`${report.continuity.total_events} event${report.continuity.total_events !== 1 ? "s" : ""} preserved`);
-    }
-    const versionStr = version ? `v${version}` : "context-mode";
-    footerParts.push(versionStr);
+    // ── Footer ──
     lines.push("");
-    lines.push(footerParts.join("  |  "));
-    // Outdated warning in footer
+    const versionStr = version ? `v${version}` : "context-mode";
+    lines.push(versionStr);
     if (version && latestVersion && latestVersion !== "unknown" && latestVersion !== version) {
-        lines.push(`Update available: v${version} -> v${latestVersion}  |  Run: ctx_upgrade`);
+        lines.push(`Update available: v${version} -> v${latestVersion}  |  ctx_upgrade`);
     }
     return lines.join("\n");
 }

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;