smart-context-mcp 1.19.0 → 1.20.0

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.19.0 (or later)
+# Should show: smart-context-mcp@1.20.0 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",
@@ -69,8 +69,10 @@
     "eval:context": "node ./evals/harness.js --tool=context",
     "eval:both": "node ./evals/harness.js --tool=both",
     "eval:self": "node ./evals/harness.js --root=../.. --corpus=./evals/corpus/self-tasks.json",
+    "eval:self:json": "node ./evals/harness.js --root=../.. --corpus=./evals/corpus/self-tasks.json --json",
     "eval:realworld": "node ./evals/realworld-eval.js",
     "eval:realworld:json": "node ./evals/realworld-eval.js --json",
+    "eval:kpi:baseline": "node ./evals/kpi-baseline.js",
     "eval:report": "node ./evals/report.js",
     "report:metrics": "node ./scripts/report-metrics.js",
     "report:workflows": "node ./scripts/report-workflow-metrics.js",
@@ -83,5 +85,6 @@
     "js-tiktoken": "^1.0.21",
     "typescript": "^6.0.2",
     "zod": "^4.1.5"
-  }
+  },
+  "packageManager": "pnpm@10.33.3+sha512.a19744364a7e248b92657a4ca5973f9354d21caf982579674b1c539f32c7420c47138ad8b1254df07aba9bc782d9b3029e3db34d5dbff974326eb74dac8ff489"
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.19.0",
+  "version": "1.20.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.19.0",
+      "version": "1.20.0",
       "transport": {
         "type": "stdio"
       },

package/src/global-memory/store.js

@@ -6,7 +6,7 @@ import { embed, cosineSimilarity, buildCorpusIdf } from '../embeddings/hashing.j
 
 const DEFAULT_GLOBAL_DIR = path.join(os.homedir(), '.devctx');
 const DEFAULT_GLOBAL_DB = path.join(DEFAULT_GLOBAL_DIR, 'global.db');
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 let sqliteModulePromise = null;
 
@@ -56,6 +56,18 @@ CREATE TABLE IF NOT EXISTS entries (
 CREATE INDEX IF NOT EXISTS idx_entries_kind ON entries(kind);
 CREATE INDEX IF NOT EXISTS idx_entries_project ON entries(project_hash);
 CREATE INDEX IF NOT EXISTS idx_entries_created ON entries(created_at DESC);
+
+CREATE TABLE IF NOT EXISTS noise_hints (
+  project_hash TEXT NOT NULL,
+  hint_key TEXT NOT NULL,
+  reason TEXT NOT NULL DEFAULT 'search_noise',
+  hits INTEGER NOT NULL DEFAULT 1,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY(project_hash, hint_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_noise_hints_project ON noise_hints(project_hash, hits DESC, updated_at DESC);
 `;
 
 const VALID_KINDS = new Set(['decision', 'pattern', 'playbook', 'note']);
@@ -245,6 +257,94 @@ export const listKinds = async ({ filePath = getGlobalDbPath() } = {}) => {
   }, { filePath, readOnly: true });
 };
 
+export const recordNoiseHint = async ({
+  projectPath,
+  hintKey,
+  reason = 'search_noise',
+  filePath = getGlobalDbPath(),
+} = {}) => {
+  if (!projectPath || !hintKey) {
+    return null;
+  }
+
+  const projectHash = hashProjectPath(projectPath);
+  const now = Date.now();
+  return withDb((db) => {
+    db.prepare(`
+      INSERT INTO noise_hints(project_hash, hint_key, reason, hits, created_at, updated_at)
+      VALUES(?, ?, ?, 1, ?, ?)
+      ON CONFLICT(project_hash, hint_key) DO UPDATE SET
+        reason = excluded.reason,
+        hits = noise_hints.hits + 1,
+        updated_at = excluded.updated_at
+    `).run(projectHash, hintKey, reason, now, now);
+
+    const row = db.prepare(`
+      SELECT hits, updated_at
+      FROM noise_hints
+      WHERE project_hash = ? AND hint_key = ?
+    `).get(projectHash, hintKey);
+
+    return {
+      projectHash,
+      hintKey,
+      hits: Number(row?.hits ?? 0),
+      updatedAt: Number(row?.updated_at ?? now),
+    };
+  }, { filePath });
+};
+
+export const getNoiseHints = async ({
+  projectPath,
+  limit = 50,
+  filePath = getGlobalDbPath(),
+} = {}) => {
+  if (!projectPath) {
+    return { hints: [], total: 0 };
+  }
+
+  const projectHash = hashProjectPath(projectPath);
+  return withDb((db) => {
+    if (!db) return { hints: [], total: 0 };
+    const rows = db.prepare(`
+      SELECT hint_key, reason, hits, updated_at
+      FROM noise_hints
+      WHERE project_hash = ?
+      ORDER BY hits DESC, updated_at DESC
+      LIMIT ?
+    `).all(projectHash, limit);
+
+    return {
+      hints: rows.map((row) => ({
+        hintKey: row.hint_key,
+        reason: row.reason,
+        hits: Number(row.hits),
+        penalty: Math.min(Number(row.hits) * 2, 12),
+        updatedAt: Number(row.updated_at),
+      })),
+      total: rows.length,
+    };
+  }, { filePath, readOnly: true });
+};
+
+export const resetNoiseHints = async ({
+  projectPath,
+  hintKey,
+  filePath = getGlobalDbPath(),
+} = {}) => {
+  if (!projectPath) {
+    return { deleted: 0 };
+  }
+
+  const projectHash = hashProjectPath(projectPath);
+  return withDb((db) => {
+    const result = hintKey
+      ? db.prepare('DELETE FROM noise_hints WHERE project_hash = ? AND hint_key = ?').run(projectHash, hintKey)
+      : db.prepare('DELETE FROM noise_hints WHERE project_hash = ?').run(projectHash);
+    return { deleted: Number(result.changes) };
+  }, { filePath });
+};
+
 export const getStats = async ({ filePath = getGlobalDbPath() } = {}) => {
   return withDb((db) => {
     if (!db) {

package/src/orchestration/base-orchestrator.js

@@ -16,6 +16,7 @@ import {
 export const DEFAULT_ORCHESTRATION_EVENT = 'session_end';
 export const DEFAULT_START_MAX_TOKENS = 350;
 export const DEFAULT_END_MAX_TOKENS = 350;
+const SIMPLE_TASK_SKIP_MAX_LENGTH = 40;
 
 const buildContextLines = (startResult) => {
   const context = buildOperationalContextLines(startResult, {
@@ -53,11 +54,31 @@ const buildFreshSessionUpdate = (prompt) => {
   };
 };
 
+const buildSimpleTaskStartResult = (prompt) => ({
+  phase: 'start',
+  skipSmartTurn: true,
+  continuity: {
+    state: 'simple_task_skip',
+    shouldReuseContext: false,
+    reason: 'Simple task heuristic skipped persisted continuity setup to avoid overhead.',
+  },
+  recommendedPath: {
+    phase: 'start',
+    mode: 'simple_task_skip',
+    nextTools: ['smart_read', 'smart_search'],
+    nextActions: [],
+    next: 'smart_read: Skip smart_turn for this simple task and use lightweight read/search directly.',
+  },
+  message: 'Simple task heuristic skipped smart_turn(start); use lightweight read/search flow unless the task grows.',
+  ...(prompt ? { promptPreview: truncate(prompt, MAX_FOCUS_LENGTH) } : {}),
+});
+
 const ensureIsolatedSession = async ({
   prompt,
   sessionId,
   startResult,
   startMaxTokens = DEFAULT_START_MAX_TOKENS,
+  tokenBudget,
   summaryTool = smartSummary,
   startTurn = smartTurn,
 }) => {
@@ -96,6 +117,7 @@ const ensureIsolatedSession = async ({
     prompt,
     ensureSession: false,
     maxTokens: startMaxTokens,
+    tokenBudget,
   });
 
   return {
@@ -112,11 +134,23 @@ export const resolveManagedStart = async ({
   ensureSession = true,
   allowIsolation = false,
   startMaxTokens = DEFAULT_START_MAX_TOKENS,
+  tokenBudget,
   startTurn = smartTurn,
   summaryTool = smartSummary,
   enableFastPath = true,
 }) => {
-  const simpleTask = enableFastPath && isSimpleTask(prompt);
+  const simpleTask = enableFastPath && isSimpleTask(prompt) && normalizeWhitespace(prompt).length <= SIMPLE_TASK_SKIP_MAX_LENGTH;
+
+  if (simpleTask && !preparedStartResult && !sessionId) {
+    const startResult = buildSimpleTaskStartResult(prompt);
+    return {
+      startResult,
+      isolated: false,
+      previousSessionId: null,
+      autoStarted: false,
+      fastPath: true,
+    };
+  }
 
   const startResult = preparedStartResult ?? await startTurn({
     phase: 'start',
@@ -124,6 +158,7 @@ export const resolveManagedStart = async ({
     prompt,
     ensureSession: simpleTask ? false : ensureSession,
     maxTokens: startMaxTokens,
+    tokenBudget,
   });
 
   if (!allowIsolation || simpleTask) {
@@ -141,6 +176,7 @@ export const resolveManagedStart = async ({
     sessionId,
     startResult,
     startMaxTokens,
+    tokenBudget,
     summaryTool,
     startTurn,
   });

package/src/server.js

@@ -129,7 +129,7 @@ export const createDevctxServer = () => {
 
   server.tool(
     'smart_read',
-    'Read a file with token-efficient modes. ALWAYS prefer outline/signatures/symbol/explain over full. Reading cascade: outline → signatures → symbol → explain → range → full (last resort). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use first for orientation. signatures (~85% savings): function signatures with parameters and return types — use when you need the API surface. symbol: extract specific functions/classes by name (string or array) — use when you know what to read; add context=true for callers, tests, and dependencies. explain (~95% savings): one-shot compact summary of a symbol (signature, docstring, first body line, side effects, caller count). Cached in SQLite by content hash — second call is free. Requires symbol. range: specific line range — use only when you need exact lines. full: raw content, no savings — only for config/lock files. maxTokens: token budget — auto-cascades to fit (outline → signatures → truncated). Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
+    'Read a file with token-efficient modes. ALWAYS prefer outline/signatures/symbol/explain over full. Reading cascade: outline → signatures → symbol → explain → range → full (last resort). Mode guide: outline (~90% savings): file structure, exports, top-level symbols — use first for orientation. signatures (~85% savings): function signatures with parameters and return types — use when you need the API surface. symbol: extract specific functions/classes by name (string or array) — use when you know what to read; add context=true for callers, tests, and dependencies. explain (~95% savings): one-shot compact summary of a symbol (signature, docstring, first body line, side effects, caller count). Cached in SQLite by content hash — second call is free. Requires symbol. range: specific line range — use only when you need exact lines. full: raw content, no savings — explicit last resort; with a token budget it degrades to lighter modes first and reports `fullMode` metadata explaining whether full was actually used. maxTokens: token budget — auto-degrades to lighter modes before truncation; when the budget changes the result, `budgetDetails` reports the final mode, truncation actions, and marks `scope="content"`. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',
     {
       filePath: z.string(),
       mode: z.enum(['full', 'outline', 'signatures', 'range', 'symbol', 'explain']).optional(),
@@ -137,15 +137,23 @@ export const createDevctxServer = () => {
       endLine: z.number().optional(),
       symbol: z.union([z.string(), z.array(z.string())]).optional(),
       maxTokens: z.number().int().min(1).optional(),
+      tokenBudget: z.union([
+        z.number().int().min(1),
+        z.object({
+          id: z.string().optional(),
+          maxTokens: z.number().int().min(1),
+          shared: z.boolean().optional(),
+        }),
+      ]).optional(),
       context: z.boolean().optional(),
     },
-    async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, context }) =>
-      asTextResult(await smartRead({ filePath, mode, startLine, endLine, symbol, maxTokens, context })),
+    async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, tokenBudget, context }) =>
+      asTextResult(await smartRead({ filePath, mode, startLine, endLine, symbol, maxTokens, tokenBudget, context })),
   );
 
   server.tool(
     'smart_read_batch',
-    'Read multiple files in one call. Each item accepts path, mode (prefer outline/signatures/symbol/explain — full saves 0 tokens), symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded. Max 20 files per call.',
+    'Read multiple files in one call. Each item accepts path, mode (prefer outline/signatures/symbol/explain — full saves 0 tokens), symbol, startLine, endLine, maxTokens (per-file budget). Optional global maxTokens budget with early stop when exceeded; when that happens, `budgetDetails` reports the batch-level stop point, marks `scope="batch"`, and includes `actions`. Max 20 files per call.',
     {
       files: z.array(z.object({
         path: z.string(),
@@ -156,25 +164,35 @@ export const createDevctxServer = () => {
         maxTokens: z.number().int().min(1).optional(),
       })).min(1).max(20),
       maxTokens: z.number().int().min(1).optional(),
+      tokenBudget: z.union([
+        z.number().int().min(1),
+        z.object({
+          id: z.string().optional(),
+          maxTokens: z.number().int().min(1),
+          shared: z.boolean().optional(),
+        }),
+      ]).optional(),
     },
-    async ({ files, maxTokens }) =>
-      asTextResult(await smartReadBatch({ files, maxTokens })),
+    async ({ files, maxTokens, tokenBudget }) =>
+      asTextResult(await smartReadBatch({ files, maxTokens, tokenBudget })),
   );
 
   server.tool(
     'smart_search',
-    'Search code with ranked, deduplicated results and index boosting. Best for: finding where a symbol is defined/used, understanding call chains, locating implementations. NOT ideal for: exact string matching (use Grep), finding files by name (use Glob), broad multi-word queries (generates noise). Optional intent adjusts ranking. maxFiles caps the number of files returned (default 15). kinds filters results by symbol kind from the index — e.g. ["adr","adr-section"] returns only architecture decision docs; ["class","function"] returns only those declarations; use to scope a query to a domain. Pass semantic=true to additionally include a local semantic re-rank (hashing-v1 embedder, TF-IDF over symbol signatures + file paths) — useful when the query is conceptual ("user registration flow", "rate limit middleware") rather than literal. semanticLimit caps the semantic block (default 8). Semantic block adds zero deps and runs in <5ms even on large indexes. When >30 files match, results include a hint suggesting Grep instead.',
+    'Search code with ranked, deduplicated results and index boosting. Best for: finding where a symbol is defined/used, understanding call chains, locating implementations. NOT ideal for: exact string matching (use Grep), finding files by name (use Glob), broad multi-word queries (generates noise). Optional intent adjusts ranking. `mode` controls search strategy: `needle` = exact literal only (no regex or term expansion), `balanced` = exact + regex + term expansion (default), `semantic` = exact-first plus a local semantic block only when exact signal is weak. maxFiles caps the number of files returned (default 5). maxTokens caps the overall response payload: `matches` is truncated first, then optional diagnostics and semantic blocks are compacted or omitted if needed. When budgeting happens, `budgetDetails` reports `actions`, which sections were compacted, and marks `scope="response"`. kinds filters results by symbol kind from the index — e.g. ["adr","adr-section"] returns only architecture decision docs; ["class","function"] returns only those declarations; use to scope a query to a domain. `semantic=true` remains supported as a legacy alias for `mode="semantic"`. semanticLimit caps the semantic block (default 8). Top ranked files include `matchedBy`, `boostSource`, `scoreBreakdown`, and `whyRanked` so ranking decisions are inspectable. Semantic block adds zero deps and runs in <5ms even on large indexes. When more files exist beyond the initial window, the response includes `hasMore`, `totalFiles`, and `nextSuggestedMaxFiles` to support expansion on demand. When the search is too broad or returns nothing useful, the response also includes actionable `suggestions` for refining the query, mode, or kinds.',
     {
       query: z.string(),
       cwd: z.string().optional(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
       maxFiles: z.number().int().min(1).max(50).optional(),
+      maxTokens: z.number().int().min(1).optional(),
       kinds: z.array(z.string()).optional(),
+      mode: z.enum(['needle', 'balanced', 'semantic']).optional(),
       semantic: z.boolean().optional(),
       semanticLimit: z.number().int().min(1).max(50).optional(),
     },
-    async ({ query, cwd = '.', intent, maxFiles, kinds, semantic, semanticLimit }) =>
-      asTextResult(await smartSearch({ query, cwd, intent, maxFiles, kinds, semantic, semanticLimit })),
+    async ({ query, cwd = '.', intent, maxFiles, maxTokens, kinds, mode, semantic, semanticLimit }) =>
+      asTextResult(await smartSearch({ query, cwd, intent, maxFiles, maxTokens, kinds, mode, semantic, semanticLimit })),
   );
 
   server.tool(
@@ -184,6 +202,14 @@ export const createDevctxServer = () => {
       task: z.string().optional(),
       intent: z.enum(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']).optional(),
       maxTokens: z.number().optional(),
+      tokenBudget: z.union([
+        z.number().int().min(1),
+        z.object({
+          id: z.string().optional(),
+          maxTokens: z.number().int().min(1),
+          shared: z.boolean().optional(),
+        }),
+      ]).optional(),
       entryFile: z.string().optional(),
       diff: z.union([z.boolean(), z.string()]).optional(),
       detail: z.enum(['minimal', 'balanced', 'deep']).optional(),
@@ -196,8 +222,8 @@ export const createDevctxServer = () => {
       pathMaxHops: z.number().int().min(1).max(10).optional(),
       pathDirected: z.boolean().optional(),
     },
-    async ({ task, intent, maxTokens, entryFile, diff, detail, include, prefetch, paths, pathMaxHops, pathDirected }) =>
-      asTextResult(await smartContext({ task, intent, maxTokens, entryFile, diff, detail, include, prefetch, paths, pathMaxHops, pathDirected })),
+    async ({ task, intent, maxTokens, tokenBudget, entryFile, diff, detail, include, prefetch, paths, pathMaxHops, pathDirected }) =>
+      asTextResult(await smartContext({ task, intent, maxTokens, tokenBudget, entryFile, diff, detail, include, prefetch, paths, pathMaxHops, pathDirected })),
   );
 
   server.tool(
@@ -256,9 +282,9 @@ export const createDevctxServer = () => {
 
   server.tool(
     'global_memory',
-    'Opt-in cross-project memory persisted to ~/.devctx/global.db (override with DEVCTX_GLOBAL_DB). Enable via DEVCTX_GLOBAL_MEMORY=true. Stores canonical decisions, recurring patterns, playbook drafts, and notes across projects so an agent can carry insights between repos without re-deriving them. Content is scrubbed for likely secrets/JWTs/API keys/emails/home paths before being persisted. Project paths are stored hashed (FNV-1a) instead of raw. Actions: save (kind+content+tags?), recall (kind?+query?+limit? — uses local hashing/TF-IDF embedder for ranking, zero deps), list (counts per kind), delete (id), mark_used (id), stats (db size + per-kind totals). Valid kinds: decision, pattern, playbook, note. projectScope=true (default) hashes the current project so recall can be filtered per-project; set false for repo-agnostic access.',
+    'Opt-in cross-project memory persisted to ~/.devctx/global.db (override with DEVCTX_GLOBAL_DB). Enable via DEVCTX_GLOBAL_MEMORY=true. Stores canonical decisions, recurring patterns, playbook drafts, notes, and repo-local noise hints so an agent can carry insights between repos without re-deriving them. Content is scrubbed for likely secrets/JWTs/API keys/emails/home paths before being persisted. Project paths are stored hashed (FNV-1a) instead of raw. Actions: save (kind+content+tags?), recall (kind?+query?+limit? — uses local hashing/TF-IDF embedder for ranking, zero deps), list (counts per kind), delete (id), mark_used (id), stats (db size + per-kind totals), noise_stats (inspect repo noise hints), noise_reset (reset repo noise hints or one hint via query). Valid kinds: decision, pattern, playbook, note. projectScope=true (default) hashes the current project so recall can be filtered per-project; set false for repo-agnostic access.',
     {
-      action: z.enum(['save', 'recall', 'list', 'delete', 'stats', 'mark_used']),
+      action: z.enum(['save', 'recall', 'list', 'delete', 'stats', 'mark_used', 'noise_stats', 'noise_reset']),
       kind: z.enum(['decision', 'pattern', 'playbook', 'note']).optional(),
       content: z.string().optional(),
       tags: z.array(z.string()).optional(),
@@ -582,13 +608,21 @@ export const createDevctxServer = () => {
       event: z.enum(['manual', 'milestone', 'decision', 'blocker', 'status_change', 'file_change', 'task_switch', 'task_complete', 'session_end', 'read_only', 'heartbeat']).optional(),
       force: z.boolean().optional(),
       maxTokens: z.number().int().min(100).max(2000).optional(),
+      tokenBudget: z.union([
+        z.number().int().min(1),
+        z.object({
+          id: z.string().optional(),
+          maxTokens: z.number().int().min(1),
+          shared: z.boolean().optional(),
+        }),
+      ]).optional(),
       ensureSession: z.boolean().optional(),
       includeMetrics: z.boolean().optional(),
       metricsWindow: z.enum(['24h', '7d', '30d', 'all']).optional(),
       latestMetrics: z.number().int().min(1).max(20).optional(),
       verbosity: z.enum(['minimal', 'standard', 'full']).optional().describe('Default "minimal" — returns compact recommendedPath/continuity/task. Use "standard" or "full" only when you need long instructions, candidates, or full checkpoint diagnostics.'),
     },
-    async ({ phase, sessionId, prompt, update, event, force, maxTokens, ensureSession, includeMetrics, metricsWindow, latestMetrics, verbosity }) =>
+    async ({ phase, sessionId, prompt, update, event, force, maxTokens, tokenBudget, ensureSession, includeMetrics, metricsWindow, latestMetrics, verbosity }) =>
       asTextResult(await smartTurn({
         phase,
         sessionId,
@@ -597,6 +631,7 @@ export const createDevctxServer = () => {
         event,
         force,
         maxTokens,
+        tokenBudget,
         ensureSession,
         includeMetrics,
         metricsWindow,
@@ -613,15 +648,24 @@ export const createDevctxServer = () => {
       sessionId: z.string().optional(),
       taskId: z.string().optional(),
       maxTokens: z.number().int().min(100).max(2000).optional(),
+      tokenBudget: z.union([
+        z.number().int().min(1),
+        z.object({
+          id: z.string().optional(),
+          maxTokens: z.number().int().min(1),
+          shared: z.boolean().optional(),
+        }),
+      ]).optional(),
       verbosity: z.enum(['minimal', 'standard', 'full']).optional(),
     },
-    async ({ prompt, sessionId, taskId, maxTokens, verbosity }) =>
+    async ({ prompt, sessionId, taskId, maxTokens, tokenBudget, verbosity }) =>
       asTextResult(await smartTurn({
         phase: 'start',
         prompt,
         sessionId,
         taskId,
         maxTokens,
+        tokenBudget,
         ensureSession: true,
         verbosity: verbosity ?? 'minimal',
       })),

package/src/storage/sqlite.js

@@ -6,7 +6,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { projectRoot } from '../utils/runtime-config.js';
 
 export const STATE_DB_FILENAME = 'state.sqlite';
-export const SQLITE_SCHEMA_VERSION = 7;
+export const SQLITE_SCHEMA_VERSION = 8;
 export const ACTIVE_SESSION_SCOPE = 'project';
 export const STATE_DB_SOFT_MAX_BYTES = 32 * 1024 * 1024;
 const STATE_DB_BUSY_TIMEOUT_MS = 1000;
@@ -20,6 +20,7 @@ export const EXPECTED_TABLES = [
   'hook_turn_state',
   'meta',
   'metrics_events',
+  'read_cache',
   'session_events',
   'sessions',
   'summary_cache',
@@ -266,6 +267,26 @@ const MIGRATIONS = [
         ON explain_cache(updated_at DESC)`,
     ],
   },
+  {
+    version: 8,
+    statements: [
+      `CREATE TABLE IF NOT EXISTS read_cache (
+        cache_key TEXT PRIMARY KEY,
+        file_path TEXT NOT NULL,
+        mode TEXT NOT NULL,
+        selector TEXT NOT NULL DEFAULT '',
+        content_hash TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        tokens INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_read_cache_file_mode
+        ON read_cache(file_path, mode, updated_at DESC)`,
+      `CREATE INDEX IF NOT EXISTS idx_read_cache_updated
+        ON read_cache(updated_at DESC)`,
+    ],
+  },
 ];
 
 let sqliteModulePromise = null;
@@ -1512,6 +1533,7 @@ export const runStorageMaintenance = async ({
     workflowMetrics: removeOlder('DELETE FROM workflow_metrics WHERE created_at < ?'),
     contextAccess: removeOlder('DELETE FROM context_access WHERE timestamp < ?'),
     explainCache: removeOlder('DELETE FROM explain_cache WHERE updated_at < ?'),
+    readCache: removeOlder('DELETE FROM read_cache WHERE updated_at < ?'),
   };
 
   setMeta(db, STORAGE_GC_META_KEY, String(now));
@@ -1955,6 +1977,9 @@ export const cleanupLegacyState = async ({
 const buildExplainCacheKey = ({ filePath, symbol, contentHash }) =>
   createHash('sha256').update(`${filePath}\u241F${symbol}\u241F${contentHash}`).digest('hex');
 
+const buildReadCacheKey = ({ filePath, mode, selector = '', contentHash }) =>
+  createHash('sha256').update(`${filePath}\u241F${mode}\u241F${selector}\u241F${contentHash}`).digest('hex');
+
 export const getExplainCache = async ({
   filePath: dbPath = getStateDbPath(),
   relPath,
@@ -2005,6 +2030,55 @@ export const clearExplainCache = async ({ filePath = getStateDbPath() } = {}) =>
   return db.prepare('DELETE FROM explain_cache').run().changes;
 }, { filePath });
 
+export const getReadCache = async ({
+  filePath: dbPath = getStateDbPath(),
+  relPath,
+  mode,
+  selector = '',
+  contentHash,
+} = {}) => withStateDb((db) => {
+  if (!relPath || !mode || !contentHash) return null;
+  const cacheKey = buildReadCacheKey({ filePath: relPath, mode, selector, contentHash });
+  const row = db.prepare(`
+    SELECT payload_json, tokens, updated_at
+    FROM read_cache
+    WHERE cache_key = ?
+  `).get(cacheKey);
+  if (!row) return null;
+  return {
+    payload: parseJsonText(row.payload_json, null),
+    tokens: row.tokens,
+    updatedAt: row.updated_at,
+  };
+}, { filePath: dbPath });
+
+export const setReadCache = async ({
+  filePath: dbPath = getStateDbPath(),
+  relPath,
+  mode,
+  selector = '',
+  contentHash,
+  payload,
+  tokens = 0,
+} = {}) => withStateDb((db) => {
+  if (!relPath || !mode || !contentHash || !payload) return null;
+  const cacheKey = buildReadCacheKey({ filePath: relPath, mode, selector, contentHash });
+  const now = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO read_cache(cache_key, file_path, mode, selector, content_hash, payload_json, tokens, created_at, updated_at)
+    VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(cache_key) DO UPDATE SET
+      payload_json = excluded.payload_json,
+      tokens = excluded.tokens,
+      updated_at = excluded.updated_at
+  `).run(cacheKey, relPath, mode, selector, contentHash, toJsonText(payload), tokens, now, now);
+  return { cacheKey, updatedAt: now };
+}, { filePath: dbPath });
+
+export const clearReadCachePersistent = async ({ filePath = getStateDbPath() } = {}) => withStateDb((db) => {
+  return db.prepare('DELETE FROM read_cache').run().changes;
+}, { filePath });
+
 const LAST_TEST_FAILURE_META_KEY = 'last_test_failure';
 
 export const setLastTestFailure = async ({

package/src/task-runner.js

@@ -129,6 +129,7 @@ const runWorkflowCommand = async ({
   client,
   prompt,
   sessionId,
+  tokenBudget,
   event,
   stdinPrompt = false,
   dryRun = false,
@@ -147,6 +148,7 @@ const runWorkflowCommand = async ({
   const startResolution = await withRunnerLockRetry(() => resolveManagedStart({
     prompt: requestedPrompt,
     sessionId,
+    tokenBudget,
     ensureSession: true,
     allowIsolation: false,
     startMaxTokens: DEFAULT_START_MAX_TOKENS,
@@ -425,6 +427,7 @@ export const runTaskRunner = async ({
   client = null,
   prompt = '',
   sessionId,
+  tokenBudget,
   event,
   stdinPrompt = false,
   dryRun = false,
@@ -456,6 +459,7 @@ export const runTaskRunner = async ({
       client: resolvedClient,
       prompt,
       sessionId,
+      tokenBudget,
       event,
       stdinPrompt,
       dryRun,

package/src/tools/global-memory.js

@@ -5,6 +5,9 @@ import {
   deleteEntry,
   listKinds,
   getStats,
+  recordNoiseHint,
+  getNoiseHints,
+  resetNoiseHints,
   isGlobalMemoryEnabled,
   VALID_GLOBAL_KINDS,
 } from '../global-memory/store.js';
@@ -13,7 +16,7 @@ import { projectRoot } from '../utils/paths.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 
-const VALID_ACTIONS = new Set(['save', 'recall', 'list', 'delete', 'stats', 'mark_used']);
+const VALID_ACTIONS = new Set(['save', 'recall', 'list', 'delete', 'stats', 'mark_used', 'noise_stats', 'noise_reset']);
 
 export const globalMemory = async ({
   action = 'stats',
@@ -92,6 +95,14 @@ export const globalMemory = async ({
         const stats = await getStats();
         return { success: true, action: 'stats', ...stats };
       }
+      case 'noise_stats': {
+        const result = await getNoiseHints({ projectPath: projectScope ? projectRoot : null, limit: limit ?? 50 });
+        return { success: true, action, ...result };
+      }
+      case 'noise_reset': {
+        const result = await resetNoiseHints({ projectPath: projectScope ? projectRoot : null, hintKey: query });
+        return { success: true, action, ...result };
+      }
     }
   } catch (err) {
     return { success: false, error: err?.message ?? String(err) };