smart-context-mcp 1.18.1 → 1.20.0

package/src/playbooks/yaml-mini.js

@@ -0,0 +1,162 @@
+const COMMENT_RE = /(^|\s)#.*$/;
+
+const stripComment = (line) => {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (ch === '\\' && (inSingle || inDouble)) { i += 1; continue; }
+    if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '\'' && !inDouble) inSingle = !inSingle;
+    else if (ch === '#' && !inSingle && !inDouble) return line.slice(0, i).trimEnd();
+  }
+  return line.replace(COMMENT_RE, '$1').trimEnd();
+};
+
+const unquoteScalar = (raw) => {
+  const trimmed = raw.trim();
+  if (trimmed === '') return null;
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith('\'') && trimmed.endsWith('\''))) {
+    return trimmed.slice(1, -1).replace(/\\(.)/g, '$1');
+  }
+  if (/^-?\d+$/.test(trimmed)) return parseInt(trimmed, 10);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return parseFloat(trimmed);
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (trimmed === 'null' || trimmed === '~') return null;
+  return trimmed;
+};
+
+const indentOf = (line) => {
+  let i = 0;
+  while (i < line.length && line[i] === ' ') i += 1;
+  return i;
+};
+
+const parseFlowInline = (rest) => {
+  if (rest === '' || rest === undefined) return undefined;
+  const trimmed = rest.trim();
+  if (trimmed === '{}') return {};
+  if (trimmed === '[]') return [];
+  return unquoteScalar(rest);
+};
+
+class Reader {
+  constructor(lines) {
+    this.lines = lines;
+    this.idx = 0;
+  }
+
+  peek() {
+    while (this.idx < this.lines.length) {
+      const raw = stripComment(this.lines[this.idx]);
+      if (raw.trim() === '') { this.idx += 1; continue; }
+      return { raw, indent: indentOf(raw), content: raw.slice(indentOf(raw)) };
+    }
+    return null;
+  }
+
+  consume() {
+    const next = this.peek();
+    if (next) this.idx += 1;
+    return next;
+  }
+}
+
+const parseValue = (reader, baseIndent) => {
+  const first = reader.peek();
+  if (!first || first.indent < baseIndent) return null;
+
+  if (first.content.startsWith('- ') || first.content === '-') {
+    return parseSequence(reader, first.indent);
+  }
+  return parseMapping(reader, first.indent);
+};
+
+const parseMapping = (reader, baseIndent) => {
+  const obj = {};
+  while (true) {
+    const next = reader.peek();
+    if (!next || next.indent < baseIndent) break;
+    if (next.indent > baseIndent) break;
+    if (next.content.startsWith('-')) break;
+
+    const colon = next.content.indexOf(':');
+    if (colon === -1) throw new Error(`YAML parse error: missing ':' near "${next.content}"`);
+
+    const key = next.content.slice(0, colon).trim();
+    const rest = next.content.slice(colon + 1).trim();
+    reader.consume();
+
+    if (rest === '' || rest === undefined) {
+      const nestedPeek = reader.peek();
+      if (nestedPeek && nestedPeek.indent > baseIndent) {
+        obj[key] = parseValue(reader, nestedPeek.indent);
+      } else {
+        obj[key] = null;
+      }
+    } else {
+      obj[key] = parseFlowInline(rest);
+    }
+  }
+  return obj;
+};
+
+const parseSequence = (reader, baseIndent) => {
+  const arr = [];
+  while (true) {
+    const next = reader.peek();
+    if (!next || next.indent !== baseIndent) break;
+    if (!next.content.startsWith('-')) break;
+
+    const tail = next.content.slice(1).trimStart();
+    reader.consume();
+
+    if (tail === '') {
+      const nestedPeek = reader.peek();
+      if (nestedPeek && nestedPeek.indent > baseIndent) {
+        arr.push(parseValue(reader, nestedPeek.indent));
+      } else {
+        arr.push(null);
+      }
+    } else if (tail.includes(':') && !/^["']/.test(tail)) {
+      const colon = tail.indexOf(':');
+      const key = tail.slice(0, colon).trim();
+      const rest = tail.slice(colon + 1).trim();
+      const item = {};
+      if (rest === '') {
+        const nestedPeek = reader.peek();
+        if (nestedPeek && nestedPeek.indent > baseIndent) {
+          const nested = parseMapping(reader, nestedPeek.indent);
+          item[key] = nested;
+        } else {
+          item[key] = null;
+        }
+      } else {
+        item[key] = parseFlowInline(rest);
+      }
+      const nestedPeek = reader.peek();
+      const itemIndent = baseIndent + 2;
+      if (nestedPeek && nestedPeek.indent >= itemIndent && !nestedPeek.content.startsWith('-')) {
+        const rest2 = parseMapping(reader, nestedPeek.indent);
+        Object.assign(item, rest2);
+      }
+      arr.push(item);
+    } else {
+      arr.push(parseFlowInline(tail));
+    }
+  }
+  return arr;
+};
+
+export const parseYamlMini = (input) => {
+  if (typeof input !== 'string') throw new Error('YAML parse: input must be a string');
+  const lines = input.replace(/\r\n?/g, '\n').split('\n');
+  const reader = new Reader(lines);
+  const first = reader.peek();
+  if (!first) return null;
+  const baseIndent = first.indent;
+  if (first.content.startsWith('-')) return parseSequence(reader, baseIndent);
+  return parseMapping(reader, baseIndent);
+};

package/src/server.js

@@ -10,6 +10,9 @@ import { smartReadBatch } from './tools/smart-read-batch.js';
 import { smartShell } from './tools/smart-shell.js';
 import { smartTest } from './tools/smart-test.js';
 import { smartReview } from './tools/smart-review.js';
+import { smartPlaybook } from './tools/smart-playbook.js';
+import { globalMemory } from './tools/global-memory.js';
+import { startIndexWatcher, isWatchEnabled, setActiveWatcher } from './index-watcher.js';
 import { smartSummary } from './tools/smart-summary.js';
 import { smartStatus } from './tools/smart-status.js';
 import { smartDoctor } from './tools/smart-doctor.js';
@@ -126,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(),
@@ -134,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(),
@@ -153,22 +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. 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 }) => asTextResult(await smartSearch({ query, cwd, intent, maxFiles, kinds })),
+    async ({ query, cwd = '.', intent, maxFiles, maxTokens, kinds, mode, semantic, semanticLimit }) =>
+      asTextResult(await smartSearch({ query, cwd, intent, maxFiles, maxTokens, kinds, mode, semantic, semanticLimit })),
   );
 
   server.tool(
@@ -178,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(),
@@ -190,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(
@@ -234,6 +266,37 @@ export const createDevctxServer = () => {
       asTextResult(await smartReview({ ref, maxFiles, maxCallers, maxTests, includeBlame })),
   );
 
+  server.tool(
+    'smart_playbook',
+    'Run a declarative workflow (playbook) that composes other smart_* tools in one call. Built-in playbooks: preflight-merge (smart_review + smart_test affected + checkpoint), debug-flake (last_failure + curated debug context + affected tests), refactor-safe (curated context + affected tests + checkpoint), doc-sync (ADR search + docs context), ramp-up (status + doctor + ADR overview). Override or add your own in .devctx/playbooks/*.yaml (or *.json). Pass list=true to enumerate available playbooks. Pass dryRun=true to resolve and validate steps without executing them. Args support {{args.X}} interpolation against defaults + caller args. Only smart_* tools are allowed inside playbooks; shell access stays gated by smart_shell allowlist.',
+    {
+      name: z.string().optional(),
+      args: z.record(z.string(), z.any()).optional(),
+      list: z.boolean().optional(),
+      dryRun: z.boolean().optional(),
+      stopOnFail: z.boolean().optional(),
+    },
+    async ({ name, args, list, dryRun, stopOnFail }) =>
+      asTextResult(await smartPlaybook({ name, args, list, dryRun, stopOnFail })),
+  );
+
+  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, 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', 'noise_stats', 'noise_reset']),
+      kind: z.enum(['decision', 'pattern', 'playbook', 'note']).optional(),
+      content: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      query: z.string().optional(),
+      limit: z.number().int().min(1).max(100).optional(),
+      id: z.number().int().optional(),
+      projectScope: z.boolean().optional(),
+    },
+    async ({ action, kind, content, tags, query, limit, id, projectScope }) =>
+      asTextResult(await globalMemory({ action, kind, content, tags, query, limit, id, projectScope })),
+  );
+
   server.tool(
     'build_index',
     'Build a lightweight symbol index for the project. Speeds up smart_search ranking and smart_read symbol lookups. Pass incremental=true to only reindex files with changed mtime (much faster for large repos). Pass warmCache=true to preload frequently accessed files after indexing. Without incremental, rebuilds from scratch. Sends progress notifications during indexing for large projects.',
@@ -545,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,
@@ -560,6 +631,7 @@ export const createDevctxServer = () => {
         event,
         force,
         maxTokens,
+        tokenBudget,
         ensureSession,
         includeMetrics,
         metricsWindow,
@@ -576,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',
       })),
@@ -616,8 +697,22 @@ export const runDevctxServer = async () => {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
+  const watcher = isWatchEnabled() ? startIndexWatcher() : null;
+  if (watcher) {
+    setActiveWatcher(watcher);
+    if (process.env.DEVCTX_DEBUG === '1') {
+      process.stderr.write('[devctx] reactive index watcher: ENABLED\n');
+    }
+  }
+
   const shutdown = () => {
-    transport.close().catch(() => {}).finally(() => process.exit(0));
+    const finalize = async () => {
+      try { if (watcher) await watcher.stop(); } catch { /* noop */ }
+      try { setActiveWatcher(null); } catch { /* noop */ }
+      try { await transport.close(); } catch { /* noop */ }
+      process.exit(0);
+    };
+    finalize();
   };
 
   process.on('SIGINT', shutdown);

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

@@ -0,0 +1,110 @@
+import {
+  saveEntry,
+  recallEntries,
+  markEntryUsed,
+  deleteEntry,
+  listKinds,
+  getStats,
+  recordNoiseHint,
+  getNoiseHints,
+  resetNoiseHints,
+  isGlobalMemoryEnabled,
+  VALID_GLOBAL_KINDS,
+} from '../global-memory/store.js';
+import { containsLikelySecret } from '../global-memory/scrub.js';
+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', 'noise_stats', 'noise_reset']);
+
+export const globalMemory = async ({
+  action = 'stats',
+  kind,
+  content,
+  tags,
+  query,
+  limit,
+  id,
+  projectScope = true,
+} = {}) => {
+  if (!VALID_ACTIONS.has(action)) {
+    return { success: false, error: `Invalid action: ${action}. Must be one of: ${[...VALID_ACTIONS].join(', ')}` };
+  }
+
+  if (!isGlobalMemoryEnabled()) {
+    return {
+      success: false,
+      disabled: true,
+      message: 'Global memory is opt-in. Set DEVCTX_GLOBAL_MEMORY=true to enable.',
+      hint: 'Stored content is automatically scrubbed for secrets/emails/paths before persistence.',
+    };
+  }
+
+  recordDevctxOperation();
+
+  try {
+    switch (action) {
+      case 'save': {
+        if (!kind || !content) return { success: false, error: 'save requires kind and content' };
+        if (!VALID_GLOBAL_KINDS.has(kind)) {
+          return { success: false, error: `Invalid kind. Must be one of: ${[...VALID_GLOBAL_KINDS].join(', ')}` };
+        }
+        const secretFlag = containsLikelySecret(content);
+        const result = await saveEntry({
+          kind,
+          content,
+          tags,
+          projectPath: projectScope ? projectRoot : null,
+        });
+        recordDecision({
+          tool: 'global_memory',
+          action: `save ${kind}`,
+          reason: DECISION_REASONS.RELATED_FILES ?? 'cross-project memory',
+          alternative: 'Re-derive context next session manually',
+          expectedBenefit: EXPECTED_BENEFITS.TOKEN_SAVINGS(content.length / 4),
+          context: secretFlag ? 'Content contained likely secrets; scrubbed before persistence' : 'Saved without secret hits',
+        });
+        return { success: true, ...result, scrubbedFromSecrets: secretFlag };
+      }
+      case 'recall': {
+        const result = await recallEntries({
+          kind,
+          query,
+          limit: limit ?? 10,
+          projectPath: projectScope ? projectRoot : null,
+        });
+        return { success: true, action, ...result };
+      }
+      case 'list': {
+        const result = await listKinds();
+        return { success: true, action, ...result };
+      }
+      case 'delete': {
+        if (!id) return { success: false, error: 'delete requires id' };
+        const result = await deleteEntry({ id });
+        return { success: true, action, ...result };
+      }
+      case 'mark_used': {
+        if (!id) return { success: false, error: 'mark_used requires id' };
+        const result = await markEntryUsed({ id });
+        return { success: true, action, ...result };
+      }
+      case 'stats':
+      default: {
+        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) };
+  }
+};