sigmap 8.21.0 → 8.23.0

package/CHANGELOG.md

@@ -10,6 +10,31 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.23.0] — 2026-07-28
+
+Minor release — **"Agent Economy I" (v8.23, F1)**: SigMap's token savings become queryable *during* a session. A spend ledger over the existing gain log, an optional budget threshold, and context-freshness age — as a CLI command and the 21st MCP tool.
+
+### Added
+- **`sigmap budget` + MCP `get_budget` (#508, PR #509):** new `src/tracking/budget.js` — `budgetStatus()` sums the session's gain-log entries (estimated SigMap-emitted tokens: spent/baseline/saved, op count), computes remaining/pct against an optional budget, and reports generated-context age with a stale flag. Session identity: `SIGMAP_SESSION` env override, else UTC day bucket; `recordUsage` now stamps every entry with `session` (legacy entries match day buckets by timestamp prefix). New opt-in config keys `sessionBudgetTokens` and `contextTtlDays` (both default `null`). CLI: `sigmap budget [--json] [--session <key>] [--budget <tokens>]`. The MCP tool advises degrade-gracefully tactics (terse encoding, `squeeze`, summarize-then-drop) at ≥80% budget. 7 new integration tests (129 test files); tool-count guards advanced 20→21.
+
+### Changed
+- **Scope honesty by design:** the ledger counts tokens **SigMap emitted** (chars/4, labeled `estimated-tokens` on every surface) — not the host chat's total spend, which a CLI cannot see. Context freshness replaces the originally-planned prompt-cache "injection TTL", which was unverifiable and got cut in the plan audit.
+
+---
+
+## [8.22.0] — 2026-07-28
+
+Minor release — **"Hard Corpus" (v8.22)**: the benchmark corpus gains a no-leakage hard split with a deterministic leakage gate, and per-repo-size buckets stop tiny repos from flattering the average. The headline retrieval number gets harder — and honest.
+
+### Added
+- **Hard-split corpus + leakage gate + size buckets (#505, PR #506):** new `src/eval/corpus.js` — a task "leaks" when its BM25-tokenized query shares a stemmed token with the tokenized basenames of its expected files; `validateTasks` flags leaky `split: "hard"` tasks as violations, and `sizeBucket` groups repos at 200/1000 scanned files (tertiles of the 43-repo corpus). New CI gate `scripts/validate-task-corpus.mjs` (exit 1 on hard-split leakage). `loadTasks` carries the optional `split` field (default `easy`). `benchmark:honest` now reports hit@5/MRR per split and per size bucket — buckets use files scanned on disk, not the budget-capped context index. 15 hand-authored hard tasks (express, flask, axios, fastify, gin), all leak-free. 8 new integration tests (128 test files).
+- **MiniMax LLM-ablation provider (PR #504)** — thanks @octo-patch: `MINIMAX_API_KEY` support in `scripts/run-llm-ablation.mjs` (OpenAI-compatible endpoint, default model MiniMax-M3, `MINIMAX_BASE_URL` override) plus a pricing entry and tests.
+
+### Changed
+- **Headline honesty, again:** the leakage gate measured that **90 of 110 pre-existing easy tasks leak filename tokens**, and the new hard split scores **33.3% hit@5 vs the grep baseline's 53.3%** — with leakage removed, grep currently wins; that measured vocabulary-mismatch ceiling is what B2 (repo-mined expansion, v9.0) exists to attack. Overall corpus (125 tasks): 72.8% hit@5, honest lift 1.63× (+28pt).
+
+---
+
 ## [8.21.0] — 2026-07-19
 
 Minor release — **"Semantic Bridge II" (v8.21)**: doc-comment hints reach Go, Rust, and Java, and the import graph gains a principled centrality prior for ranking — flag-gated and measured.

package/README.md

@@ -59,10 +59,10 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 **Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
-- **85.6% hit@5** — right file in top 5 results (vs 42.7% single-shot grep baseline — 2.00× lift)
+- **82.2% hit@5** — right file in top 5 results (vs 44.8% single-shot grep baseline — 1.59× lift)
 - **96.8% token reduction** — average across 21 real repos
-- **66.7% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
-- **1.48 prompts per task** — down from 2.84 (48.0% fewer retries, modeled)
+- **64.8% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
+- **1.53 prompts per task** — down from 2.84 (46.1% fewer retries, modeled)
 <!--/SM:whyMetrics-->
 - **<!--SM:languages-->33<!--/SM:languages--> languages supported** — TypeScript, Python, Go, Rust, Java, R, and more
 - **No vendor lock-in** — works with any AI assistant or local LLM
@@ -98,7 +98,7 @@ sigmap verify answer.md --report        # standalone red/amber/green HTML report
 | Without SigMap | With SigMap |
 |---|---|
 | ❌ Non-reproducible agent guesses | ✅ Deterministic map — same input, same output, every time |
-| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->86%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
+| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->82%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
 | ❌ Embeddings / vector DB required | ✅ Zero deps, no infra, fully offline |
 
 ---
@@ -122,13 +122,13 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.21-main (21 repositories, including R language)
-Date      : 2026-07-19
+Benchmark : sigmap-v8.23-main (21 repositories, including R language)
+Date      : 2026-07-28
 
-Hit@5          : 85.6%   (grep-agent baseline 42.7%  — 2.00× lift)
+Hit@5          : 82.2%   (grep-agent baseline 44.8%  — 1.59× lift)
 Token reduction: 96.8%   (across 21 repos)
-Prompt reduction : 48.0% (2.84 → 1.48 prompts per task, modeled)
-Task success   : 66.7%   (proxy — modeled from retrieval tiers)
+Prompt reduction : 46.1% (2.84 → 1.53 prompts per task, modeled)
+Task success   : 64.8%   (proxy — modeled from retrieval tiers)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
 <!--/SM:benchmarkBlock-->
@@ -222,7 +222,7 @@ Use SigMap with open-source tools and fully self-hosted setups:
 | **JetBrains** | [Marketplace](https://plugins.jetbrains.com/plugin/31109-sigmap--ai-context-engine/) | [github.com/manojmallick/sigmap-jetbrains](https://github.com/manojmallick/sigmap-jetbrains) | IntelliJ IDEA, WebStorm, PyCharm, GoLand — tool window + actions |
 | **Neovim** | lazy.nvim / packer / vim-plug | [github.com/manojmallick/sigmap.nvim](https://github.com/manojmallick/sigmap.nvim) | `:SigMap`, `:SigMapQuery` float window, statusline widget |
 
-**MCP server** — 20 on-demand tools for Claude Code and Cursor:
+**MCP server** — 21 on-demand tools for Claude Code and Cursor:
 
 ```bash
 sigmap --mcp
@@ -269,7 +269,7 @@ SigMap treats coding agents as **consumers, not competitors**: it hands them a d
 
 | Agent | One-time setup | How it consumes SigMap |
 |---|---|---|
-| **Claude Code** | `sigmap mcp install claude` | 20 MCP tools (`search_signatures`, `get_lines`, `get_diff_context`, `squeeze_output`…) |
+| **Claude Code** | `sigmap mcp install claude` | 21 MCP tools (`search_signatures`, `get_lines`, `get_diff_context`, `squeeze_output`…) |
 | **Cursor** | `sigmap mcp install cursor` | MCP tools, plus the `cursor` adapter writes `.cursorrules` |
 | **Cline** | `sigmap mcp install cursor` | Reads `.cursorrules`; same MCP server |
 | **Continue** | `sigmap mcp install vscode` | MCP tools inside the Continue extension |

package/gen-context.js

@@ -1490,6 +1490,14 @@ __factories["./src/config/defaults"] = function(module, exports) {
     // Append run metrics to .context/usage.ndjson after each generate
     tracking: false,
 
+    // Session spend ledger (`sigmap budget` / MCP get_budget). Estimates only —
+    // counts tokens SigMap emitted (chars/4), not the host chat's total spend.
+    // Number → warn threshold for estimated SigMap-emitted tokens per session.
+    sessionBudgetTokens: null,
+
+    // Number of days before generated context counts as stale in budget output.
+    contextTtlDays: null,
+
     // MCP server configuration
     mcp: {
       autoRegister: true,
@@ -4101,6 +4109,93 @@ __factories["./src/eval/analyzer"] = function(module, exports) {
   
 };
 
+// ── ./src/eval/corpus ──
+__factories["./src/eval/corpus"] = function(module, exports) {
+  
+  /**
+   * Task-corpus hygiene (A3, v8.22 "Hard Corpus").
+   *
+   * A benchmark query "leaks" when it shares a token with the basenames of its
+   * expected files — hit@5 then partly measures filename matching, not
+   * retrieval. The criterion is deterministic and reuses the production
+   * tokenizer (identifier splitting + stemming from src/retrieval/bm25.js), so
+   * "payments" leaks against payment.js and "InterceptorManager" leaks against
+   * "interceptor manager" the same way the ranker would see them.
+   *
+   * Tasks carry an optional `split` field: 'hard' tasks MUST be leak-free
+   * (validateTasks reports them as violations); 'easy' tasks (the default) may
+   * leak — that is what makes them easy.
+   *
+   * Size buckets group repos by indexed file count so large repos stop being
+   * averaged away by tiny ones. Thresholds are the rough tertiles of the
+   * current benchmarks/repos corpus (43 repos, 27–3450 source files).
+   */
+
+  const { tokenize } = __require('./src/retrieval/bm25');
+
+  const BUCKET_LIMITS = { small: 200, medium: 1000 }; // files; large = above medium
+
+  /**
+   * Stemmed tokens of a file path's basename (extension stripped).
+   * @param {string} filePath
+   * @returns {string[]}
+   */
+  function basenameTokens(filePath) {
+    const base = String(filePath).split('/').pop() || '';
+    return tokenize(base.replace(/\.[^.]*$/, ''));
+  }
+
+  /**
+   * Leaked tokens between a query and its expected files' basenames.
+   * @param {string} query
+   * @param {string[]} expectedFiles
+   * @returns {{ leaked: string[], clean: boolean }}
+   */
+  function queryLeakage(query, expectedFiles) {
+    const qToks = new Set(tokenize(query));
+    const leaked = new Set();
+    for (const f of expectedFiles || []) {
+      for (const t of basenameTokens(f)) {
+        if (qToks.has(t)) leaked.add(t);
+      }
+    }
+    return { leaked: [...leaked].sort(), clean: leaked.size === 0 };
+  }
+
+  /**
+   * Validate a task list: every task gets a leakage result; hard-split tasks
+   * that leak are violations.
+   * @param {Array<{id?:string, query:string, expected_files?:string[], split?:string}>} tasks
+   * @returns {{ results: object[], hardViolations: object[] }}
+   */
+  function validateTasks(tasks) {
+    const results = [];
+    const hardViolations = [];
+    for (const t of tasks || []) {
+      const split = t.split === 'hard' ? 'hard' : 'easy';
+      const { leaked, clean } = queryLeakage(t.query, t.expected_files);
+      const row = { id: t.id || '?', split, leaked, clean };
+      results.push(row);
+      if (split === 'hard' && !clean) hardViolations.push(row);
+    }
+    return { results, hardViolations };
+  }
+
+  /**
+   * Size bucket for a repo by indexed file count.
+   * @param {number} fileCount
+   * @returns {'small'|'medium'|'large'}
+   */
+  function sizeBucket(fileCount) {
+    if (fileCount < BUCKET_LIMITS.small) return 'small';
+    if (fileCount <= BUCKET_LIMITS.medium) return 'medium';
+    return 'large';
+  }
+
+  module.exports = { basenameTokens, queryLeakage, validateTasks, sizeBucket, BUCKET_LIMITS };
+  
+};
+
 // ── ./src/eval/llm-ablation ──
 __factories["./src/eval/llm-ablation"] = function(module, exports) {
   
@@ -4400,7 +4495,7 @@ __factories["./src/eval/runner"] = function(module, exports) {
 
   /**
    * Load tasks from a JSONL file.
-   * Each line: { id, query, expected_files, repo }
+   * Each line: { id, query, expected_files, repo, split? ('easy'|'hard') }
    * Invalid or blank lines are silently skipped.
    * @param {string} tasksFile - absolute or relative path
    * @returns {Array<{id:string, query:string, expected:string[], repo:string}>}
@@ -4420,6 +4515,7 @@ __factories["./src/eval/runner"] = function(module, exports) {
             query: obj.query,
             expected: obj.expected_files,
             repo: obj.repo || '.',
+            split: obj.split === 'hard' ? 'hard' : 'easy',
           });
         }
       } catch {
@@ -14286,6 +14382,41 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     return out.join('\n');
   }
 
+  /**
+   * get_budget({ session?, budgetTokens? }) → string
+   *
+   * Session spend ledger (F1): estimated tokens SigMap emitted this session,
+   * optional budget remaining, and context freshness. Estimates only (chars/4);
+   * does NOT see the host chat's total spend.
+   */
+  function getBudget(args, cwd) {
+    const { budgetStatus } = __require('./src/tracking/budget');
+    let config = {};
+    try { config = __require('./src/config/loader').loadConfig(cwd) || {}; } catch (_) {}
+    const opts = { config };
+    if (args && args.session) opts.session = String(args.session);
+    if (args && args.budgetTokens != null) opts.budgetTokens = Number(args.budgetTokens);
+    const s = budgetStatus(cwd, opts);
+
+    const out = ['# SigMap session spend (estimates — chars/4; SigMap-emitted tokens only)'];
+    out.push('');
+    out.push(`Session   : ${s.session}`);
+    out.push(`Ops       : ${s.ops}`);
+    out.push(`Spent     : ~${s.spentTokens.toLocaleString()} tokens (baseline ~${s.baselineTokens.toLocaleString()}, saved ~${s.savedTokens.toLocaleString()})`);
+    if (s.budgetTokens != null) {
+      out.push(`Budget    : ${s.budgetTokens.toLocaleString()} → remaining ~${s.remainingTokens.toLocaleString()} (${s.pctUsed}% used)${s.overBudget ? '  ⚠ OVER BUDGET' : ''}`);
+      if (s.overBudget || (s.pctUsed != null && s.pctUsed >= 80)) {
+        out.push('Advice    : prefer terse output, squeeze large inputs, summarize-then-drop context.');
+      }
+    } else {
+      out.push('Budget    : none set (config sessionBudgetTokens or budgetTokens arg)');
+    }
+    out.push(s.context.exists
+      ? `Context   : ${s.context.ageDays} day(s) old${s.context.stale ? ` — STALE (> ${s.context.ttlDays}d TTL); re-run sigmap` : ''}`
+      : 'Context   : no generated context found — run sigmap first');
+    return out.join('\n');
+  }
+
   /**
    * get_callee_signatures — return the exact defining signature(s) of named
    * symbols from the index, so an agent never guesses a callee's parameter types.
@@ -14679,7 +14810,7 @@ __factories["./src/mcp/handlers"] = function(module, exports) {
     return header + sq.squeezed;
   }
 
-  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput };
+  module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput, getBudget };
   
 };
 
@@ -14846,11 +14977,11 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const readline = require('readline');
   const { TOOLS } = __require('./src/mcp/tools');
-  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput } = __require('./src/mcp/handlers');
+  const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput, getBudget } = __require('./src/mcp/handlers');
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.21.0',
+    version: '8.23.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -14918,6 +15049,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
         else if (name === 'get_architecture_overview') text = getArchitectureOverview(args, cwd);
         else if (name === 'verify_suggestion') text = verifySuggestion(args, cwd);
         else if (name === 'squeeze_output') text = squeezeOutput(args, cwd);
+        else if (name === 'get_budget') text = getBudget(args, cwd);
         else {
           respondError(id, -32601, `Unknown tool: ${name}`);
           return;
@@ -15364,6 +15496,32 @@ __factories["./src/mcp/tools"] = function(module, exports) {
         required: ['content'],
       },
     },
+    {
+      name: 'get_budget',
+      description:
+        'Session spend ledger — estimated tokens SigMap has emitted this session ' +
+        '(chars/4 estimates from the local gain log), optional budget remaining, and ' +
+        'context freshness. Scope honesty: counts only SigMap output, NOT the whole ' +
+        "chat's spend. Check this mid-session and degrade gracefully when near budget: " +
+        'prefer terse encoding, squeeze large outputs, summarize-then-drop context. ' +
+        'Local-only; no LLM, no network.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          session: {
+            type: 'string',
+            description:
+              'Session key to report on (default: SIGMAP_SESSION env or the UTC day bucket).',
+          },
+          budgetTokens: {
+            type: 'number',
+            description:
+              'Budget override in estimated tokens (default: config sessionBudgetTokens).',
+          },
+        },
+        required: [],
+      },
+    },
   ];
 
   module.exports = { TOOLS };
@@ -18320,6 +18478,123 @@ __factories["./src/tracking/aggregate"] = function(module, exports) {
   
 };
 
+// ── ./src/tracking/budget ──
+__factories["./src/tracking/budget"] = function(module, exports) {
+  
+  /**
+   * Session spend ledger (v8.23 F1) — a queryable view over the existing gain
+   * log (.context/gain.ndjson, written by recordUsage).
+   *
+   * Honesty scope: this ledger counts tokens **SigMap emitted** (chars/4
+   * estimates), not the host chat's total spend — conversation history, model
+   * output, and other tools are invisible to a CLI. Every number here is an
+   * estimate and is labeled as such in output.
+   *
+   * Session identity: `SIGMAP_SESSION` env var when the host sets one, else a
+   * UTC day bucket (YYYY-MM-DD). Legacy gain entries (written before the
+   * `session` field existed) match day-bucket sessions by timestamp prefix.
+   *
+   * Zero dependencies; local JSON only.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+  const { readGainLog } = __require('./src/tracking/logger');
+
+  // Same generated-context surfaces cache/freshen.js watches.
+  const CONTEXT_PATHS = [
+    ['.github', 'copilot-instructions.md'],
+    ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
+  ];
+
+  /** Session key: SIGMAP_SESSION override, else UTC day bucket. */
+  function sessionKey(env) {
+    const e = env || process.env;
+    if (e.SIGMAP_SESSION) return String(e.SIGMAP_SESSION);
+    return new Date().toISOString().slice(0, 10);
+  }
+
+  /** Newest mtime (ms) among generated context files, or 0 if none exist. */
+  function contextMtime(cwd) {
+    let newest = 0;
+    for (const parts of CONTEXT_PATHS) {
+      try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+    }
+    return newest;
+  }
+
+  /** Does a gain-log entry belong to this session? */
+  function entryInSession(entry, session) {
+    if (entry.session) return entry.session === session;
+    // Legacy entry: match day-bucket sessions on the timestamp date.
+    return /^\d{4}-\d{2}-\d{2}$/.test(session) && String(entry.ts || '').startsWith(session);
+  }
+
+  /**
+   * Session spend status.
+   * @param {string} cwd
+   * @param {object} [opts]
+   * @param {string} [opts.session]          session key (default: sessionKey())
+   * @param {number} [opts.budgetTokens]     budget override (else config sessionBudgetTokens)
+   * @param {number} [opts.contextTtlDays]   TTL override (else config contextTtlDays)
+   * @param {object} [opts.config]           loaded config (for the two keys above)
+   * @param {number} [opts.now]              clock override for tests (ms)
+   * @returns {{
+   *   session: string, unit: 'estimated-tokens', ops: number,
+   *   spentTokens: number, baselineTokens: number, savedTokens: number,
+   *   budgetTokens: number|null, remainingTokens: number|null, pctUsed: number|null,
+   *   overBudget: boolean,
+   *   context: { exists: boolean, ageMs: number|null, ageDays: number|null,
+   *              ttlDays: number|null, stale: boolean }
+   * }}
+   */
+  function budgetStatus(cwd, opts = {}) {
+    const session = opts.session || sessionKey();
+    const cfg = opts.config || {};
+    const budget = opts.budgetTokens != null ? Number(opts.budgetTokens)
+      : (Number.isFinite(cfg.sessionBudgetTokens) ? cfg.sessionBudgetTokens : null);
+    const ttlDays = opts.contextTtlDays != null ? Number(opts.contextTtlDays)
+      : (Number.isFinite(cfg.contextTtlDays) ? cfg.contextTtlDays : null);
+    const now = opts.now != null ? opts.now : Date.now();
+
+    let ops = 0, spent = 0, baseline = 0, saved = 0;
+    for (const e of readGainLog(cwd)) {
+      if (!entryInSession(e, session)) continue;
+      ops++;
+      spent += Number(e.actualTokens) || 0;
+      baseline += Number(e.baselineTokens) || 0;
+      saved += Number(e.savedTokens) || 0;
+    }
+
+    const mtime = contextMtime(cwd);
+    const ageMs = mtime > 0 ? Math.max(0, now - mtime) : null;
+    const ageDays = ageMs != null ? ageMs / 86400000 : null;
+
+    return {
+      session,
+      unit: 'estimated-tokens',
+      ops,
+      spentTokens: spent,
+      baselineTokens: baseline,
+      savedTokens: saved,
+      budgetTokens: budget,
+      remainingTokens: budget != null ? Math.max(0, budget - spent) : null,
+      pctUsed: budget > 0 ? Math.round((spent / budget) * 1000) / 10 : null,
+      overBudget: budget != null && spent > budget,
+      context: {
+        exists: mtime > 0,
+        ageMs,
+        ageDays: ageDays != null ? Math.round(ageDays * 10) / 10 : null,
+        ttlDays,
+        stale: ttlDays != null && ageDays != null && ageDays > ttlDays,
+      },
+    };
+  }
+
+  module.exports = { sessionKey, budgetStatus, contextMtime, entryInSession };
+  
+};
+
 // ── ./src/tracking/logger ──
 __factories["./src/tracking/logger"] = function(module, exports) {
   
@@ -18498,10 +18773,12 @@ __factories["./src/tracking/logger"] = function(module, exports) {
       const baseline = Math.max(0, Number(entry.baselineTokens) || 0);
       const actual = Math.max(0, Number(entry.actualTokens) || 0);
       const saved = Math.max(0, baseline - actual);
+      const ts = new Date().toISOString();
       const record = {
-        ts: new Date().toISOString(),
+        ts,
         v: entry.version || '0.9.0',
         op: entry.op || 'generate',
+        session: entry.session || process.env.SIGMAP_SESSION || ts.slice(0, 10),
         baselineTokens: baseline,
         actualTokens: actual,
         savedTokens: saved,
@@ -18544,6 +18821,8 @@ __factories["./src/tracking/pricing"] = function(module, exports) {
     'gpt-4o-mini': 0.15,
     'gemini-1.5-pro': 1.25,
     'gemini-1.5-flash': 0.075,
+    'minimax-m3': 0.6,
+    'minimax-m2.7': 0.3,
   };
 
   const DEFAULT_MODEL = 'claude-sonnet';
@@ -20068,7 +20347,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.21.0';
+const VERSION = '8.23.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -21953,6 +22232,8 @@ Usage:
   ${cmd} evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
   ${cmd} memory                            List cross-session stores (.context/) — entries, size, age
   ${cmd} memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
+  ${cmd} budget                            Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json)
+  ${cmd} budget --budget <tokens>          One-off budget override (config: sessionBudgetTokens, contextTtlDays)
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
@@ -23404,6 +23685,36 @@ function main() {
     process.exit(0);
   }
 
+  if (args[0] === 'budget') {
+    const jsonOut = args.includes('--json');
+    const { budgetStatus } = requireSourceOrBundled('./src/tracking/budget');
+    let config = {};
+    try { config = requireSourceOrBundled('./src/config/loader').loadConfig(cwd) || {}; } catch (_) {}
+    const opts = { config };
+    const sIdx = args.indexOf('--session');
+    if (sIdx !== -1 && args[sIdx + 1] && !args[sIdx + 1].startsWith('--')) opts.session = args[sIdx + 1];
+    const bIdx = args.indexOf('--budget');
+    if (bIdx !== -1 && args[bIdx + 1] && !args[bIdx + 1].startsWith('--')) opts.budgetTokens = Number(args[bIdx + 1]);
+    const st = budgetStatus(cwd, opts);
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(st) + '\n');
+      process.exit(0);
+    }
+    console.log('[sigmap] session spend (estimates — chars/4; SigMap-emitted tokens only)');
+    console.log(`  session   ${st.session}`);
+    console.log(`  ops       ${st.ops}`);
+    console.log(`  spent     ~${st.spentTokens.toLocaleString()} tokens  (baseline ~${st.baselineTokens.toLocaleString()}, saved ~${st.savedTokens.toLocaleString()})`);
+    if (st.budgetTokens != null) {
+      console.log(`  budget    ${st.budgetTokens.toLocaleString()} → remaining ~${st.remainingTokens.toLocaleString()} (${st.pctUsed}% used)${st.overBudget ? '  ⚠ OVER BUDGET' : ''}`);
+    } else {
+      console.log('  budget    none set (config sessionBudgetTokens or --budget <tokens>)');
+    }
+    console.log(st.context.exists
+      ? `  context   ${st.context.ageDays} day(s) old${st.context.stale ? `  ⚠ STALE (> ${st.context.ttlDays}d TTL) — re-run sigmap` : ''}`
+      : '  context   none generated yet — run sigmap first');
+    process.exit(0);
+  }
+
   if (args[0] === 'note') {
     const jsonOut = args.includes('--json');
     const { addNote, readNotes, formatNotes } = requireSourceOrBundled('./src/session/notes');

package/llms-full.txt

@@ -11,22 +11,22 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.21.0 | Benchmark: sigmap-v8.21-main (2026-07-19)
+# Version: 8.23.0 | Benchmark: sigmap-v8.23-main (2026-07-28)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.21-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.23-main, 2026-07-28)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
-| Retrieval hit@5 | 42.7% (single-shot grep) | 85.6% (2.00× lift) |
+| Retrieval hit@5 | 44.8% (single-shot grep) | 82.2% (1.59× lift) |
 | Token reduction | — | 96.8% average |
-| Task-success proxy (modeled) | — | 66.7% |
-| Prompts per task | 2.84 | 1.48 (48.0% fewer) |
+| Task-success proxy (modeled) | — | 64.8% |
+| Prompts per task | 2.84 | 1.53 (46.1% fewer) |
 | Supported languages | — | 33 |
-| MCP tools | — | 20 |
+| MCP tools | — | 21 |
 | npm runtime dependencies | — | 0 |
 
 ---
@@ -125,6 +125,8 @@ sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to
 sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
 sigmap memory                            List cross-session stores (.context/) — entries, size, age
 sigmap memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
+sigmap budget                            Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json)
+sigmap budget --budget <tokens>          One-off budget override (config: sessionBudgetTokens, contextTtlDays)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes
@@ -138,7 +140,7 @@ sigmap --version                         Show version
 
 ---
 
-## MCP server — 20 tools
+## MCP server — 21 tools
 
 Start with `sigmap --mcp` (stdio JSON-RPC). Configure once:
 
@@ -306,6 +308,14 @@ Compress noisy tool, command, or agent output before it enters context — a sta
 Input:  { content: string }
 ```
 
+### get_budget
+
+Session spend ledger — estimated tokens SigMap has emitted this session (chars/4 estimates from the local gain log), optional budget remaining, and context freshness. Scope honesty: counts only SigMap output, NOT the whole chat's spend. Check this mid-session and degrade gracefully when near budget: prefer terse encoding, squeeze large outputs, summarize-then-drop context. Local-only; no LLM, no network.
+
+```
+Input:  { session?: string, budgetTokens?: number }
+```
+
 ---
 
 ## Configuration (gen-context.config.json)
@@ -334,6 +344,8 @@ watchDebounce = 300
 routing = false
 format = default
 tracking = false
+sessionBudgetTokens = null
+contextTtlDays = null
 mcp = {"autoRegister":true}
 depMap = true
 versionPins = true

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.21.0 | Benchmark: sigmap-v8.21-main (2026-07-19)
+# Version: 8.23.0 | Benchmark: sigmap-v8.23-main (2026-07-28)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,13 +23,13 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.21-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.23-main, 2026-07-28)
 
-- hit@5 retrieval: 85.6% vs 42.7% single-shot grep baseline (2.00× lift)
+- hit@5 retrieval: 82.2% vs 44.8% single-shot grep baseline (1.59× lift)
 - Token reduction: 96.8% average across benchmark repos
-- Task-success proxy: 66.7% (modeled from retrieval tiers, not measured LLM sessions)
-- Prompts per task: 1.48 vs 2.84 baseline (48.0% fewer, modeled)
-- Languages: 33 supported · MCP tools: 20
+- Task-success proxy: 64.8% (modeled from retrieval tiers, not measured LLM sessions)
+- Prompts per task: 1.53 vs 2.84 baseline (46.1% fewer, modeled)
+- Languages: 33 supported · MCP tools: 21
 - Dependencies: zero npm runtime dependencies · fully offline
 
 ## Quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.21.0",
+  "version": "8.23.0",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.21.0",
+  "version": "8.23.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.21.0",
+  "version": "8.23.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/config/defaults.js

@@ -106,6 +106,14 @@ const DEFAULTS = {
   // Append run metrics to .context/usage.ndjson after each generate
   tracking: false,
 
+  // Session spend ledger (`sigmap budget` / MCP get_budget). Estimates only —
+  // counts tokens SigMap emitted (chars/4), not the host chat's total spend.
+  // Number → warn threshold for estimated SigMap-emitted tokens per session.
+  sessionBudgetTokens: null,
+
+  // Number of days before generated context counts as stale in budget output.
+  contextTtlDays: null,
+
   // MCP server configuration
   mcp: {
     autoRegister: true,

package/src/eval/corpus.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Task-corpus hygiene (A3, v8.22 "Hard Corpus").
+ *
+ * A benchmark query "leaks" when it shares a token with the basenames of its
+ * expected files — hit@5 then partly measures filename matching, not
+ * retrieval. The criterion is deterministic and reuses the production
+ * tokenizer (identifier splitting + stemming from src/retrieval/bm25.js), so
+ * "payments" leaks against payment.js and "InterceptorManager" leaks against
+ * "interceptor manager" the same way the ranker would see them.
+ *
+ * Tasks carry an optional `split` field: 'hard' tasks MUST be leak-free
+ * (validateTasks reports them as violations); 'easy' tasks (the default) may
+ * leak — that is what makes them easy.
+ *
+ * Size buckets group repos by indexed file count so large repos stop being
+ * averaged away by tiny ones. Thresholds are the rough tertiles of the
+ * current benchmarks/repos corpus (43 repos, 27–3450 source files).
+ */
+
+const { tokenize } = require('../retrieval/bm25');
+
+const BUCKET_LIMITS = { small: 200, medium: 1000 }; // files; large = above medium
+
+/**
+ * Stemmed tokens of a file path's basename (extension stripped).
+ * @param {string} filePath
+ * @returns {string[]}
+ */
+function basenameTokens(filePath) {
+  const base = String(filePath).split('/').pop() || '';
+  return tokenize(base.replace(/\.[^.]*$/, ''));
+}
+
+/**
+ * Leaked tokens between a query and its expected files' basenames.
+ * @param {string} query
+ * @param {string[]} expectedFiles
+ * @returns {{ leaked: string[], clean: boolean }}
+ */
+function queryLeakage(query, expectedFiles) {
+  const qToks = new Set(tokenize(query));
+  const leaked = new Set();
+  for (const f of expectedFiles || []) {
+    for (const t of basenameTokens(f)) {
+      if (qToks.has(t)) leaked.add(t);
+    }
+  }
+  return { leaked: [...leaked].sort(), clean: leaked.size === 0 };
+}
+
+/**
+ * Validate a task list: every task gets a leakage result; hard-split tasks
+ * that leak are violations.
+ * @param {Array<{id?:string, query:string, expected_files?:string[], split?:string}>} tasks
+ * @returns {{ results: object[], hardViolations: object[] }}
+ */
+function validateTasks(tasks) {
+  const results = [];
+  const hardViolations = [];
+  for (const t of tasks || []) {
+    const split = t.split === 'hard' ? 'hard' : 'easy';
+    const { leaked, clean } = queryLeakage(t.query, t.expected_files);
+    const row = { id: t.id || '?', split, leaked, clean };
+    results.push(row);
+    if (split === 'hard' && !clean) hardViolations.push(row);
+  }
+  return { results, hardViolations };
+}
+
+/**
+ * Size bucket for a repo by indexed file count.
+ * @param {number} fileCount
+ * @returns {'small'|'medium'|'large'}
+ */
+function sizeBucket(fileCount) {
+  if (fileCount < BUCKET_LIMITS.small) return 'small';
+  if (fileCount <= BUCKET_LIMITS.medium) return 'medium';
+  return 'large';
+}
+
+module.exports = { basenameTokens, queryLeakage, validateTasks, sizeBucket, BUCKET_LIMITS };

package/src/eval/runner.js

@@ -124,7 +124,7 @@ function estimateTokens(sigs) {
 
 /**
  * Load tasks from a JSONL file.
- * Each line: { id, query, expected_files, repo }
+ * Each line: { id, query, expected_files, repo, split? ('easy'|'hard') }
  * Invalid or blank lines are silently skipped.
  * @param {string} tasksFile - absolute or relative path
  * @returns {Array<{id:string, query:string, expected:string[], repo:string}>}
@@ -144,6 +144,7 @@ function loadTasks(tasksFile) {
           query: obj.query,
           expected: obj.expected_files,
           repo: obj.repo || '.',
+          split: obj.split === 'hard' ? 'hard' : 'easy',
         });
       }
     } catch {

package/src/mcp/handlers.js

@@ -586,6 +586,41 @@ function readMemory(args, cwd) {
   return out.join('\n');
 }
 
+/**
+ * get_budget({ session?, budgetTokens? }) → string
+ *
+ * Session spend ledger (F1): estimated tokens SigMap emitted this session,
+ * optional budget remaining, and context freshness. Estimates only (chars/4);
+ * does NOT see the host chat's total spend.
+ */
+function getBudget(args, cwd) {
+  const { budgetStatus } = require('../tracking/budget');
+  let config = {};
+  try { config = require('../config/loader').loadConfig(cwd) || {}; } catch (_) {}
+  const opts = { config };
+  if (args && args.session) opts.session = String(args.session);
+  if (args && args.budgetTokens != null) opts.budgetTokens = Number(args.budgetTokens);
+  const s = budgetStatus(cwd, opts);
+
+  const out = ['# SigMap session spend (estimates — chars/4; SigMap-emitted tokens only)'];
+  out.push('');
+  out.push(`Session   : ${s.session}`);
+  out.push(`Ops       : ${s.ops}`);
+  out.push(`Spent     : ~${s.spentTokens.toLocaleString()} tokens (baseline ~${s.baselineTokens.toLocaleString()}, saved ~${s.savedTokens.toLocaleString()})`);
+  if (s.budgetTokens != null) {
+    out.push(`Budget    : ${s.budgetTokens.toLocaleString()} → remaining ~${s.remainingTokens.toLocaleString()} (${s.pctUsed}% used)${s.overBudget ? '  ⚠ OVER BUDGET' : ''}`);
+    if (s.overBudget || (s.pctUsed != null && s.pctUsed >= 80)) {
+      out.push('Advice    : prefer terse output, squeeze large inputs, summarize-then-drop context.');
+    }
+  } else {
+    out.push('Budget    : none set (config sessionBudgetTokens or budgetTokens arg)');
+  }
+  out.push(s.context.exists
+    ? `Context   : ${s.context.ageDays} day(s) old${s.context.stale ? ` — STALE (> ${s.context.ttlDays}d TTL); re-run sigmap` : ''}`
+    : 'Context   : no generated context found — run sigmap first');
+  return out.join('\n');
+}
+
 /**
  * get_callee_signatures — return the exact defining signature(s) of named
  * symbols from the index, so an agent never guesses a callee's parameter types.
@@ -979,4 +1014,4 @@ function squeezeOutput(args, cwd) {
   return header + sq.squeezed;
 }
 
-module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput };
+module.exports = { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput, getBudget };

package/src/mcp/server.js

@@ -14,11 +14,11 @@
 
 const readline = require('readline');
 const { TOOLS } = require('./tools');
-const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput } = require('./handlers');
+const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, explainFile, listModules, queryContext, getMethodImpact, getImpact, getLines, readMemory, getCalleeSignatures, notifyFileCreated, notifySymbolAdded, notifyFileDeleted, getDiffContext, getArchitectureOverview, verifySuggestion, squeezeOutput, getBudget } = require('./handlers');
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.21.0',
+  version: '8.23.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 
@@ -86,6 +86,7 @@ function dispatch(msg, cwd) {
       else if (name === 'get_architecture_overview') text = getArchitectureOverview(args, cwd);
       else if (name === 'verify_suggestion') text = verifySuggestion(args, cwd);
       else if (name === 'squeeze_output') text = squeezeOutput(args, cwd);
+      else if (name === 'get_budget') text = getBudget(args, cwd);
       else {
         respondError(id, -32601, `Unknown tool: ${name}`);
         return;

package/src/mcp/tools.js

@@ -387,6 +387,32 @@ const TOOLS = [
       required: ['content'],
     },
   },
+  {
+    name: 'get_budget',
+    description:
+      'Session spend ledger — estimated tokens SigMap has emitted this session ' +
+      '(chars/4 estimates from the local gain log), optional budget remaining, and ' +
+      'context freshness. Scope honesty: counts only SigMap output, NOT the whole ' +
+      "chat's spend. Check this mid-session and degrade gracefully when near budget: " +
+      'prefer terse encoding, squeeze large outputs, summarize-then-drop context. ' +
+      'Local-only; no LLM, no network.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: {
+          type: 'string',
+          description:
+            'Session key to report on (default: SIGMAP_SESSION env or the UTC day bucket).',
+        },
+        budgetTokens: {
+          type: 'number',
+          description:
+            'Budget override in estimated tokens (default: config sessionBudgetTokens).',
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
 module.exports = { TOOLS };

package/src/tracking/budget.js

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * Session spend ledger (v8.23 F1) — a queryable view over the existing gain
+ * log (.context/gain.ndjson, written by recordUsage).
+ *
+ * Honesty scope: this ledger counts tokens **SigMap emitted** (chars/4
+ * estimates), not the host chat's total spend — conversation history, model
+ * output, and other tools are invisible to a CLI. Every number here is an
+ * estimate and is labeled as such in output.
+ *
+ * Session identity: `SIGMAP_SESSION` env var when the host sets one, else a
+ * UTC day bucket (YYYY-MM-DD). Legacy gain entries (written before the
+ * `session` field existed) match day-bucket sessions by timestamp prefix.
+ *
+ * Zero dependencies; local JSON only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readGainLog } = require('./logger');
+
+// Same generated-context surfaces cache/freshen.js watches.
+const CONTEXT_PATHS = [
+  ['.github', 'copilot-instructions.md'],
+  ['CLAUDE.md'], ['AGENTS.md'], ['.github', 'context-cold.md'],
+];
+
+/** Session key: SIGMAP_SESSION override, else UTC day bucket. */
+function sessionKey(env) {
+  const e = env || process.env;
+  if (e.SIGMAP_SESSION) return String(e.SIGMAP_SESSION);
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** Newest mtime (ms) among generated context files, or 0 if none exist. */
+function contextMtime(cwd) {
+  let newest = 0;
+  for (const parts of CONTEXT_PATHS) {
+    try { newest = Math.max(newest, fs.statSync(path.join(cwd, ...parts)).mtimeMs); } catch (_) {}
+  }
+  return newest;
+}
+
+/** Does a gain-log entry belong to this session? */
+function entryInSession(entry, session) {
+  if (entry.session) return entry.session === session;
+  // Legacy entry: match day-bucket sessions on the timestamp date.
+  return /^\d{4}-\d{2}-\d{2}$/.test(session) && String(entry.ts || '').startsWith(session);
+}
+
+/**
+ * Session spend status.
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string} [opts.session]          session key (default: sessionKey())
+ * @param {number} [opts.budgetTokens]     budget override (else config sessionBudgetTokens)
+ * @param {number} [opts.contextTtlDays]   TTL override (else config contextTtlDays)
+ * @param {object} [opts.config]           loaded config (for the two keys above)
+ * @param {number} [opts.now]              clock override for tests (ms)
+ * @returns {{
+ *   session: string, unit: 'estimated-tokens', ops: number,
+ *   spentTokens: number, baselineTokens: number, savedTokens: number,
+ *   budgetTokens: number|null, remainingTokens: number|null, pctUsed: number|null,
+ *   overBudget: boolean,
+ *   context: { exists: boolean, ageMs: number|null, ageDays: number|null,
+ *              ttlDays: number|null, stale: boolean }
+ * }}
+ */
+function budgetStatus(cwd, opts = {}) {
+  const session = opts.session || sessionKey();
+  const cfg = opts.config || {};
+  const budget = opts.budgetTokens != null ? Number(opts.budgetTokens)
+    : (Number.isFinite(cfg.sessionBudgetTokens) ? cfg.sessionBudgetTokens : null);
+  const ttlDays = opts.contextTtlDays != null ? Number(opts.contextTtlDays)
+    : (Number.isFinite(cfg.contextTtlDays) ? cfg.contextTtlDays : null);
+  const now = opts.now != null ? opts.now : Date.now();
+
+  let ops = 0, spent = 0, baseline = 0, saved = 0;
+  for (const e of readGainLog(cwd)) {
+    if (!entryInSession(e, session)) continue;
+    ops++;
+    spent += Number(e.actualTokens) || 0;
+    baseline += Number(e.baselineTokens) || 0;
+    saved += Number(e.savedTokens) || 0;
+  }
+
+  const mtime = contextMtime(cwd);
+  const ageMs = mtime > 0 ? Math.max(0, now - mtime) : null;
+  const ageDays = ageMs != null ? ageMs / 86400000 : null;
+
+  return {
+    session,
+    unit: 'estimated-tokens',
+    ops,
+    spentTokens: spent,
+    baselineTokens: baseline,
+    savedTokens: saved,
+    budgetTokens: budget,
+    remainingTokens: budget != null ? Math.max(0, budget - spent) : null,
+    pctUsed: budget > 0 ? Math.round((spent / budget) * 1000) / 10 : null,
+    overBudget: budget != null && spent > budget,
+    context: {
+      exists: mtime > 0,
+      ageMs,
+      ageDays: ageDays != null ? Math.round(ageDays * 10) / 10 : null,
+      ttlDays,
+      stale: ttlDays != null && ageDays != null && ageDays > ttlDays,
+    },
+  };
+}
+
+module.exports = { sessionKey, budgetStatus, contextMtime, entryInSession };

package/src/tracking/logger.js

@@ -175,10 +175,12 @@ function recordUsage(entry, cwd) {
     const baseline = Math.max(0, Number(entry.baselineTokens) || 0);
     const actual = Math.max(0, Number(entry.actualTokens) || 0);
     const saved = Math.max(0, baseline - actual);
+    const ts = new Date().toISOString();
     const record = {
-      ts: new Date().toISOString(),
+      ts,
       v: entry.version || '0.9.0',
       op: entry.op || 'generate',
+      session: entry.session || process.env.SIGMAP_SESSION || ts.slice(0, 10),
       baselineTokens: baseline,
       actualTokens: actual,
       savedTokens: saved,

package/src/tracking/pricing.js

@@ -20,6 +20,8 @@ const PRICES = {
   'gpt-4o-mini': 0.15,
   'gemini-1.5-pro': 1.25,
   'gemini-1.5-flash': 0.075,
+  'minimax-m3': 0.6,
+  'minimax-m2.7': 0.3,
 };
 
 const DEFAULT_MODEL = 'claude-sonnet';