sigmap 8.22.0 → 8.24.0

package/CHANGELOG.md

@@ -10,6 +10,30 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.24.0] — 2026-07-28
+
+Minor release — **"Trust Quick Wins I" (v8.24, G3a)**: the secret-redaction engine that already protects signatures, `get_lines`, and evidence packs becomes a standalone command for arbitrary text.
+
+### Added
+- **`sigmap redact` (#511, PR #512):** new `src/security/redact.js` — `redactText()` masks only the matched secret substring (`[REDACTED:<pattern name>]`), preserving surrounding text (unlike the generation-time scanner's whole-line replacement, which is unchanged). Findings carry 1-based line numbers with per-pattern counts. CLI: `sigmap redact [file] [--json]` — file argument or stdin; redacted text on stdout (pipe-clean), summary on stderr. Reuses the existing 10-pattern bank verbatim; zero new dependencies; never throws. 6 new integration tests including an every-pattern mask sweep (130 test files).
+
+### Changed
+- Test fixtures for secret patterns are assembled at runtime (no secret-shaped literals in committed blobs) — GitHub Push Protection rejected the first push over the fake samples, which validated the detection class this command implements.
+
+---
+
+## [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.

package/README.md

@@ -122,8 +122,8 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.22-main (21 repositories, including R language)
-Date      : 2026-07-27
+Benchmark : sigmap-v8.24-main (21 repositories, including R language)
+Date      : 2026-07-28
 
 Hit@5          : 82.2%   (grep-agent baseline 44.8%  — 1.59× lift)
 Token reduction: 96.8%   (across 21 repos)
@@ -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,
@@ -14374,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.
@@ -14767,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 };
   
 };
 
@@ -14934,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.22.0',
+    version: '8.24.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -15006,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;
@@ -15452,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 };
@@ -17458,6 +17528,66 @@ __factories["./src/security/patterns"] = function(module, exports) {
   
 };
 
+// ── ./src/security/redact ──
+__factories["./src/security/redact"] = function(module, exports) {
+  
+  /**
+   * Standalone text redaction (v8.24 G3a) — the same pattern bank the
+   * generation-time scanner uses (security/patterns.js), applied to arbitrary
+   * text. Unlike scanner.js (which replaces whole signature lines), this masks
+   * only the matched secret substring so surrounding text stays readable.
+   *
+   * Zero dependencies; never throws — on any error the original text is
+   * returned unredacted.
+   */
+
+  const { PATTERNS } = __require('./src/security/patterns');
+
+  // Global variants of the pattern regexes (needed for replace-all per line).
+  const GLOBAL_PATTERNS = PATTERNS.map((p) => ({
+    name: p.name,
+    regex: new RegExp(p.regex.source, p.regex.flags.includes('g') ? p.regex.flags : p.regex.flags + 'g'),
+  }));
+
+  /**
+   * Redact secrets in arbitrary text.
+   * @param {string} text
+   * @returns {{
+   *   text: string, redacted: boolean,
+   *   findings: Array<{ line: number, pattern: string }>,
+   *   counts: Object<string, number>
+   * }}
+   */
+  function redactText(text) {
+    if (typeof text !== 'string' || text.length === 0) {
+      return { text: typeof text === 'string' ? text : '', redacted: false, findings: [], counts: {} };
+    }
+    try {
+      const findings = [];
+      const counts = {};
+      const lines = text.split('\n');
+      const out = lines.map((line, i) => {
+        let masked = line;
+        for (const p of GLOBAL_PATTERNS) {
+          p.regex.lastIndex = 0;
+          if (!p.regex.test(masked)) continue;
+          p.regex.lastIndex = 0;
+          masked = masked.replace(p.regex, `[REDACTED:${p.name}]`);
+          findings.push({ line: i + 1, pattern: p.name });
+          counts[p.name] = (counts[p.name] || 0) + 1;
+        }
+        return masked;
+      });
+      return { text: out.join('\n'), redacted: findings.length > 0, findings, counts };
+    } catch (_) {
+      return { text, redacted: false, findings: [], counts: {} };
+    }
+  }
+
+  module.exports = { redactText };
+  
+};
+
 // ── ./src/security/scanner ──
 __factories["./src/security/scanner"] = function(module, exports) {
   
@@ -18408,6 +18538,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) {
   
@@ -18586,10 +18833,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,
@@ -20158,7 +20407,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.22.0';
+const VERSION = '8.24.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -22043,6 +22292,9 @@ 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} redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
   ${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
@@ -23494,6 +23746,72 @@ 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] === 'redact') {
+    const jsonOut = args.includes('--json');
+    const { redactText } = requireSourceOrBundled('./src/security/redact');
+    const fileArg = args.slice(1).find((a) => !a.startsWith('--'));
+    let input;
+    if (fileArg) {
+      try {
+        input = fs.readFileSync(path.resolve(cwd, fileArg), 'utf8');
+      } catch (err) {
+        console.error(`[sigmap] redact: cannot read ${fileArg}: ${err.message}`);
+        process.exit(1);
+      }
+    } else if (!process.stdin.isTTY) {
+      try {
+        input = fs.readFileSync(0, 'utf8');
+      } catch (err) {
+        console.error(`[sigmap] redact: cannot read stdin: ${err.message}`);
+        process.exit(1);
+      }
+    } else {
+      console.error('[sigmap] usage: sigmap redact <file>   or   <cmd> | sigmap redact');
+      process.exit(1);
+    }
+    const r = redactText(input);
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(r) + '\n');
+      process.exit(0);
+    }
+    process.stdout.write(r.text);
+    const parts = Object.entries(r.counts).map(([k, v]) => `${k}×${v}`);
+    console.error(r.redacted
+      ? `[sigmap] redact: masked ${r.findings.length} secret(s) — ${parts.join(', ')}`
+      : '[sigmap] redact: no secrets found');
+    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,13 +11,13 @@ 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.22.0 | Benchmark: sigmap-v8.22-main (2026-07-27)
+# Version: 8.24.0 | Benchmark: sigmap-v8.24-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.22-main, 2026-07-27)
+## Core metrics (benchmark: sigmap-v8.24-main, 2026-07-28)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
@@ -26,7 +26,7 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 | 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,9 @@ 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 redact [file]                     Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json)
 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 +141,7 @@ sigmap --version                         Show version
 
 ---
 
-## MCP server — 20 tools
+## MCP server — 21 tools
 
 Start with `sigmap --mcp` (stdio JSON-RPC). Configure once:
 
@@ -306,6 +309,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 +345,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.22.0 | Benchmark: sigmap-v8.22-main (2026-07-27)
+# Version: 8.24.0 | Benchmark: sigmap-v8.24-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.22-main, 2026-07-27)
+## Core metrics (benchmark: sigmap-v8.24-main, 2026-07-28)
 
 - 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: 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: 20
+- 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.22.0",
+  "version": "8.24.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.22.0",
+  "version": "8.24.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.22.0",
+  "version": "8.24.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/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.22.0',
+  version: '8.24.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/security/redact.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Standalone text redaction (v8.24 G3a) — the same pattern bank the
+ * generation-time scanner uses (security/patterns.js), applied to arbitrary
+ * text. Unlike scanner.js (which replaces whole signature lines), this masks
+ * only the matched secret substring so surrounding text stays readable.
+ *
+ * Zero dependencies; never throws — on any error the original text is
+ * returned unredacted.
+ */
+
+const { PATTERNS } = require('./patterns');
+
+// Global variants of the pattern regexes (needed for replace-all per line).
+const GLOBAL_PATTERNS = PATTERNS.map((p) => ({
+  name: p.name,
+  regex: new RegExp(p.regex.source, p.regex.flags.includes('g') ? p.regex.flags : p.regex.flags + 'g'),
+}));
+
+/**
+ * Redact secrets in arbitrary text.
+ * @param {string} text
+ * @returns {{
+ *   text: string, redacted: boolean,
+ *   findings: Array<{ line: number, pattern: string }>,
+ *   counts: Object<string, number>
+ * }}
+ */
+function redactText(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { text: typeof text === 'string' ? text : '', redacted: false, findings: [], counts: {} };
+  }
+  try {
+    const findings = [];
+    const counts = {};
+    const lines = text.split('\n');
+    const out = lines.map((line, i) => {
+      let masked = line;
+      for (const p of GLOBAL_PATTERNS) {
+        p.regex.lastIndex = 0;
+        if (!p.regex.test(masked)) continue;
+        p.regex.lastIndex = 0;
+        masked = masked.replace(p.regex, `[REDACTED:${p.name}]`);
+        findings.push({ line: i + 1, pattern: p.name });
+        counts[p.name] = (counts[p.name] || 0) + 1;
+      }
+      return masked;
+    });
+    return { text: out.join('\n'), redacted: findings.length > 0, findings, counts };
+  } catch (_) {
+    return { text, redacted: false, findings: [], counts: {} };
+  }
+}
+
+module.exports = { redactText };

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,