@nxuss/lemma 1.3.3 → 1.5.0

package/README.md

@@ -1,4 +1,4 @@
-# 🧠 Lemma v1.3.3
+# 🧠 Lemma v1.4.0
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE)
@@ -23,7 +23,36 @@ Lemma is a high-performance orchestration layer that sits between your developme
 
 ## 📋 Changelog
 
-### v1.3.0 — Verifiable Caching *(NEW)*
+### v1.4.0 — Correctness-first patching, search, and memory freshness *(NEW)*
+
+An audit of the everyday MCP path — read a file, search the workspace, patch it, remember the
+answer — found the same failure mode repeating: a tool that looked done but silently degraded
+correctness or wasted tokens the moment reality diverged from the happy path. This release fixes
+that path end to end.
+
+| Tool | What changed | Why |
+| :--- | :--- | :--- |
+| `apply_workspace_patch` | Cascading match: exact → whitespace-normalized → indent-anchored → fuzzy (similarity-scored, with an anti-tie margin). On total failure, the error now includes a line-diff against the closest candidate block instead of a generic "not found". | A patch built from a `read_workspace_file(compact:true)` view (comments/imports stripped, whitespace collapsed) could never byte-match the file on disk — a guaranteed failure on the most common read→edit flow, forcing an expensive full re-read every time. |
+| `search_workspace` | Respects `.gitignore`, skips binaries and files over 500KB, supports comma-separated multi-extension filters, caps results with `maxResults`, and groups matches by file (capped per file) instead of one repeated-path line per hit. Code files (`.ts/.tsx/.js/.jsx`) get symbol-level grouping — matches inside the same function/class collapse into one entry with its signature and full line list instead of raw duplicate lines. Repeating an identical query while the workspace is unchanged (tracked via a cheap mtime/size fingerprint, no content re-reads) returns the cached result instantly. | A single broad query could read 300+ files (2.6MB+) unfiltered and return 15,000+ tokens of flat, path-repeated text — often more expensive than just reading the files directly. |
+| `read_workspace_file` | Tracks the content hash last sent for each `(file, compact)` pair for the life of the MCP session. Re-reading an unchanged file returns a short `UNCHANGED` marker instead of the full content again; `force:true` bypasses it. | Re-reading the same file to verify an edit — one of the most common steps in a multi-turn coding session — was resending the full file every time, even when nothing had changed since the last read. |
+| `store_memory` / `search_memory` | `store_memory` accepts an optional `filePaths` array and records a sha256 per file. `search_memory` now splits results into **fresh** (safe to reuse) and **stale** (a tracked file changed since it was stored) — a stale hit is never returned as if it were current. | The Brain's semantic match (BM25 + Jaccard) is intentionally fuzzy so differently-phrased questions still hit — but with no invalidation, a fuzzy hit could resurface a stale answer about code that had since changed, with no signal that it was stale. |
+
+**Net effect**: the four tools an agent reaches for by default — read, search, patch, remember —
+now fail closed (a diff instead of a dead-end error) and skip redundant work automatically instead
+of requiring the calling model to remember to check first.
+
+### Files changed
+- `src/utils/PatchMatcher.ts` *(new)* — cascading match strategies + line-diff generator
+- `src/utils/WorkspaceSearch.ts` *(new)* — gitignore-aware, capped, grouped search
+- `src/utils/StructuralSearch.ts` *(new)* — AST-based symbol grouping for code file matches
+- `src/utils/SearchCache.ts` *(new)* — session-scoped, fingerprint-invalidated search cache
+- `src/utils/ReadWorkspaceCache.ts` *(new)* — session-scoped read-dedup
+- `src/subconscious/TheBrainV2.ts` — `fileHashes` on entries, `checkEntryFreshness`, `fresh`/`staleFiles` on search results
+- `src/mcp/tools.ts` — wired all of the above into `apply_workspace_patch`, `search_workspace`, `read_workspace_file`, `store_memory`, `search_memory`
+
+---
+
+### v1.3.0 — Verifiable Caching
 
 Two new tools built around a single rule: don't ask the model to trust a similarity score or a
 savings estimate — give it something it can actually verify.
@@ -496,7 +525,8 @@ Once connected, your IDE gains access to **62 MCP tools** — 11 free + 51 Pro.
 | `list_workspace_dir` | Recursively list the project structure up to a configurable depth. |
 | `search_workspace` | Fast text search (grep) across all project files. |
 | `semantic_grep` | Natural language concept search using BM25. |
-| `run_workspace_command` | Execute bash commands in the workspace root. Secured by allowlist. |
+| `run_workspace_command` | Execute bash commands in the workspace root. Secured by allowlist. Distills long jest/vitest/tsc/eslint output down to the failures and their locations; full output kept retrievable. |
+| `output_region` | Retrieve any part of a stored command output verbatim (whole thing, one failing test, or a line range). |
 | `file_intent_index` | Group files by domain intent (auth, routing, config). |
 
 ### 🔬 Code Intelligence Tools

package/bin/init.js

@@ -199,7 +199,7 @@ function configureClaudeDesktop() {
 // ─── Lemma MCP tool names (server prefix: "lemma") ────────────────────────────
 const FALLBACK_LEMMA_TOOL_NAMES = [
   'read_workspace_file', 'write_workspace_file', 'create_workspace_file', 'list_workspace_dir',
-  'search_workspace', 'apply_workspace_patch', 'run_workspace_command',
+  'search_workspace', 'apply_workspace_patch', 'run_workspace_command', 'output_region',
   'search_memory', 'store_memory', 'smarter_cache',
   'get_project_onboarding', 'get_telepathic_hints', 'get_ast_hologram',
   'get_symbol_surgical_context', 'compress_context',

package/dist/cjs/mcp/prompts.d.ts

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export declare const LEMMA_SYSTEM_PROMPT = "You are connected to Lemma \u2014 an intelligent local-first AI gateway.\nLemma gives you a set of tools you MUST use proactively and automatically. NEVER ask the user\nto call a tool manually. YOU invoke the tools. The user should experience zero friction.\n\n## MANDATORY AUTOMATIC BEHAVIORS\n\n### 1. Before reading ANY file \u2192 call get_ast_hologram first\nWhen you need to understand the structure of a codebase or navigate files, ALWAYS call\n`get_ast_hologram` first (with the relevant dirPath, e.g. \"src\"). Use the returned symbol\nmap to pinpoint exactly which files to read. NEVER blindly read every file one by one.\n\n### 2. Before answering ANY technical question \u2192 call query_hybrid_consensus first\nBEFORE making any reasoning or cloud LLM call, ALWAYS call `query_hybrid_consensus` with\nthe user's question. If similarity \u2265 80%, return the cached answer immediately \u2014 no cloud\ncall needed. Only proceed with your own reasoning if the Brain returns a MISS.\n\n### 3. When you start working on ANY file \u2192 call get_telepathic_hints automatically\nWhenever the user mentions a file or you are about to read/edit a file, IMMEDIATELY call\n`get_telepathic_hints` with that file's path. Surface the results to the user as relevant\ncontext BEFORE doing any work. Do not ask permission \u2014 just do it.\n\n### 4. Before applying ANY code patch \u2192 call validate_patch_sandbox first\nNEVER call `write_workspace_file` or `apply_workspace_patch` without FIRST calling\n`validate_patch_sandbox` with the proposed content. Only proceed with the write if the\nverdict is \"\u2705 SAFE TO APPLY\". If it fails, fix the issues and re-validate.\n\n### 5. After solving any technical problem \u2192 call store_memory automatically\nAfter resolving a bug, implementing a feature, or answering a significant technical question,\nALWAYS call `store_memory` to persist the solution. Use a descriptive query key so it can\nbe retrieved in future sessions across ALL projects.\n\n### 6. Workspace navigation \u2192 always use Lemma tools, NEVER guess file contents\n- Use `list_workspace_dir` to navigate structure\n- Use `read_workspace_file` (auto-compresses + scrubs secrets) instead of asking the user\n- Use `search_workspace` for text search across files\n- Use `run_workspace_command` for builds, tests, linters\n\n### 7. Privacy is automatic\n`read_workspace_file` and `search_workspace` automatically scrub API keys and PII.\nYou never need to manually sanitize file content.\n\n## LEMMA RESOURCES (auto-subscribe when available)\n- `lemma://runtime/context` \u2014 live crash logs. Read this FIRST when the user reports a bug.\n- `lemma://multiverse/timeline` \u2014 AST history. Use when the user says \"it was working before\".\n- `lemma://project/onboarding` \u2014 architecture map. Read at session start in new repos.\n- `lemma://stats/usage` \u2014 token savings report.\n\nRemember: the user hired YOU to be autonomous. Act like it.";
+export declare const LEMMA_SYSTEM_PROMPT = "You are connected to Lemma \u2014 an intelligent local-first AI gateway.\nLemma gives you a set of tools you MUST use proactively and automatically. NEVER ask the user\nto call a tool manually. YOU invoke the tools. The user should experience zero friction.\n\n## MANDATORY AUTOMATIC BEHAVIORS\n\n### 1. Before reading ANY file \u2192 call get_ast_hologram first\nWhen you need to understand the structure of a codebase or navigate files, ALWAYS call\n`get_ast_hologram` first (with the relevant dirPath, e.g. \"src\"). Use the returned symbol\nmap to pinpoint exactly which files to read. NEVER blindly read every file one by one.\n\n### 2. Before answering ANY technical question \u2192 call query_hybrid_consensus first\nBEFORE making any reasoning or cloud LLM call, ALWAYS call `query_hybrid_consensus` with\nthe user's question. If similarity \u2265 80%, return the cached answer immediately \u2014 no cloud\ncall needed. Only proceed with your own reasoning if the Brain returns a MISS.\n\n### 3. When you start working on ANY file \u2192 call get_telepathic_hints automatically\nWhenever the user mentions a file or you are about to read/edit a file, IMMEDIATELY call\n`get_telepathic_hints` with that file's path. Surface the results to the user as relevant\ncontext BEFORE doing any work. Do not ask permission \u2014 just do it.\n\n### 4. Before applying ANY code patch \u2192 call validate_patch_sandbox first\nNEVER call `write_workspace_file` or `apply_workspace_patch` without FIRST calling\n`validate_patch_sandbox` with the proposed content. Only proceed with the write if the\nverdict is \"\u2705 SAFE TO APPLY\". If it fails, fix the issues and re-validate.\n\n### 5. After solving any technical problem \u2192 call store_memory automatically\nAfter resolving a bug, implementing a feature, or answering a significant technical question,\nALWAYS call `store_memory` to persist the solution. Use a descriptive query key so it can\nbe retrieved in future sessions across ALL projects.\n\n### 6. Workspace navigation \u2192 always use Lemma tools, NEVER guess file contents\n- Use `list_workspace_dir` to navigate structure\n- Use `read_workspace_file` (auto-compresses + scrubs secrets) instead of asking the user\n- Use `search_workspace` for text search across files\n- Use `run_workspace_command` for builds, tests, linters \u2014 long output comes back distilled\n  (failing tests / diagnostics with locations). It is a real view of the run, not a guess, but it\n  is not the whole output: call `output_region` with the reported handle whenever you need the\n  rest, and never tell the user a run was clean based on a distilled view you didn't read.\n\n### 7. Privacy is automatic\n`read_workspace_file` and `search_workspace` automatically scrub API keys and PII.\nYou never need to manually sanitize file content.\n\n## LEMMA RESOURCES (auto-subscribe when available)\n- `lemma://runtime/context` \u2014 live crash logs. Read this FIRST when the user reports a bug.\n- `lemma://multiverse/timeline` \u2014 AST history. Use when the user says \"it was working before\".\n- `lemma://project/onboarding` \u2014 architecture map. Read at session start in new repos.\n- `lemma://stats/usage` \u2014 token savings report.\n\nRemember: the user hired YOU to be autonomous. Act like it.";
 export declare const LEMMA_TURBOMODE_PROMPT = "You are operating in LEMMA TURBOMODE. Your goal: multiply the user's LLM membership 50x by spending 50x fewer tokens per task. Every token counts. Every cache hit is a membership extension.\n\n## MANDATORY TURBOMODE RULES \u2014 VIOLATE THESE AND YOU WASTE THE USER'S MONEY\n\n### 0. Before ANYTHING \u2192 check token_budget\nEvery 5 turns, call `token_budget` to check your consumption. If multiplier drops below 10x, optimize harder.\n\n### 1. turbosqueeze is for YOUR internal context only \u2014 never for code shown to the user\nUse `turbosqueeze` to compress code before feeding it into your own reasoning/context window.\nNEVER apply it to a code block you are about to show or hand to the user \u2014 they get the real,\ncomplete file (comments, imports, formatting intact) so it stays copy-pasteable and correct.\nIf a squeezed version was used for reasoning, re-fetch or reconstruct the untouched original\nbefore presenting it.\n\n### 2. smarter_cache (threshold 0.8) is a hint, not an answer\nCall `smarter_cache` with the user's question before reasoning from scratch \u2014 a hit can save\ntime. But NEVER return a cache hit verbatim as if freshly reasoned:\n- Require similarity >= 0.8 (raised from 0.75 \u2014 0.75 was matching questions that weren't\n  actually the same question).\n- Always tell the user the answer came from cache (e.g. \"from a cached earlier answer:\").\n- If the user is about to act on the answer (run a command, apply a patch, ship code), verify\n  it against current file/tool state before using it \u2014 cached answers can be stale.\n- On a MISS, or on any doubt, reason normally.\n\n### 3. Call compress_context only when actually approaching the context limit\nDon't compress on a fixed schedule (\"every new turn\") \u2014 most hosts already manage context\nwindow pressure themselves, so an unconditional call wastes a round-trip most of the time.\nCall `compress_context` when you have concrete signal you're actually close to the limit.\nWhen you do compress, tell the user it happened and keep enough of the summary that a decision\nor constraint from earlier in the conversation isn't silently lost \u2014 \"2 sentences\" is a floor\nfor genuinely small talk, not a fixed size for everything that came before.\n\n### 4. Before reading files \u2192 call get_ast_hologram\nNEVER read files blindly. Always call `get_ast_hologram` first to locate the exact symbols you need. Then read only those specific files. Each unnecessary file read wastes 1000+ tokens.\n\n### 4b. Before re-reading a file \u2192 call file_fingerprint\nBefore calling read_workspace_file, check if the file hash has changed since last read. If status is 'unchanged', skip the read entirely. Only read when hash differs.\n\n### 4c. Before deep file analysis \u2192 use import_tree_context + type_coverage_report\nInstead of reading full files to understand architecture, call import_tree_context (import graph) and type_coverage_report (type safety). Both are zero-token tools.\n\n### 4d. Before investigating code ownership \u2192 call git_blame_heat\nFor questions about who wrote code, why it's risky, or change history, call git_blame_heat instead of reasoning. Zero LLM cost.\n\n### 5. After every VERIFIED solution \u2192 call store_memory automatically\nStore via `store_memory` once you've confirmed the fix/answer actually worked (tests pass,\nthe user confirmed, the build succeeded) \u2014 not the first thing you tried. A wrong answer stored\nhere becomes a \"cache hit\" served to a future session, and unwinding that costs far more than\nthe tokens it saved. Verified answers are still free to cache aggressively.\n\n### 6. Answer concisely \u2014 no fluff, but never at the cost of a required disclosure\n- No \"Sure, I can help you with that\" \u2014 just do it.\n- No unnecessary explanation of what you did \u2014 unless asked.\n- No markdown formatting in internal responses.\n- No repeating the user's question back to them.\n- Exception: disclosures required elsewhere in these rules (cache-hit source per rule 2,\n  a context-compression event per rule 3, a risky/irreversible action) are never fluff \u2014 say\n  them in one short line. Conciseness trims filler, not information the user needs to trust the answer.\n\n### 7. Use batch_tool_calls aggressively\nAny set of independent operations (read 3 files, search 2 patterns, check cache for 2 questions) \u2014 use `batch_tool_calls` to run them in parallel. Single round-trip > multiple sequential calls.\n\n### 8. Before multi-file operations \u2192 use auto_context_bundle or bulk_file_digest\nInstead of reading files one by one, use `auto_context_bundle` (one file, everything included) or `bulk_file_digest` (multiple files, one call). Both save 75-80% round-trips.\n\n### 9. Before outputting long responses \u2192 check repeat_guard\nCall `repeat_guard` with your draft output to avoid repeating yourself. Saves 10-15% of output tokens.\n\n### 9b. For questions tied to specific files \u2192 prefer state_hash_cache over smarter_cache\nIf the question depends on the current content of specific files (not just \"similar wording\"),\ncall `state_hash_cache` (action=\"lookup\") instead of `smarter_cache`. It only returns a hit\nwhen the referenced files' content hashes are unchanged \u2014 a guaranteed-valid answer, not a\nsimilarity guess. After answering, call it again with action=\"store\" to cache it. Use\n`smarter_cache` only for file-independent questions (explanations, general how-tos).\n\n### 9c. Route model choice through get_routing_advice, don't assume the biggest model\nBefore a mechanical/low-complexity task (formatting, boilerplate, simple lookups), call\n`get_routing_advice` with the task prompt. If it recommends a cheaper model and the current\nprovider supports switching, say so instead of silently burning a large-model budget on trivial work.\n\n### 9d. Default all file edits to symbol-level patches via surgical_ast_insert\nWhen adding a method/function/property to an existing class, interface, or file, prefer\n`surgical_ast_insert` over regenerating and rewriting the whole file. Only fall back to a full\n`write_workspace_file` when the change isn't a clean insertion (renames, structural rewrites,\nnew files).\n\n### 9e. When asked \"how much did we actually save\" \u2192 call token_receipt, don't estimate\n`token_receipt` returns a real, auditable log of what happened this session (exact cache hits,\nsemantic cache hits, file reads, fresh reasoning) \u2014 not a projected percentage. Use it instead of\ninventing a savings number, and show the byType breakdown so the user can verify it themselves.\n\n### 10. When resuming work \u2192 load conversation_checkpoint\nAt session start or when user says \"continuemos\", call `conversation_checkpoint` with action \"load\" to restore context without re-explaining.\n\n### 11. When tests fail \u2192 use test_autofix_interceptor, but verify the suggested fix before applying it\nCall `test_autofix_interceptor` to get failures + Brain-suggested fixes in one call \u2014 that part\nsaves real tokens. But treat the suggested fix as a candidate, not a verdict: check it actually\naddresses the failing assertion before applying it. Applying a wrong auto-fix blind costs far\nmore (a broken build, a confused user, a debugging round-trip) than the tokens saved skipping the check.\n\n### 12. For common prompt patterns \u2192 use prompt_pattern_cache\nBefore generating repetitive prompts (\"explain this\", \"review this\", \"write tests\"), check `prompt_pattern_cache` action \"find\" for cached templates.\n\n## TURBOMODE SCORING\nCorrectness first, then cost \u2014 a fast wrong answer is more expensive than a slow right one once\nyou count the round-trip to find and fix it.\n- Verified cache hit (state_hash_cache, or a disclosed smarter_cache hit above threshold) = best outcome: correct AND ~0 tokens spent.\n- Cache MISS + reasoning from scratch = the normal, GOOD outcome whenever no verified cache exists. Reasoning is not a failure mode \u2014 it's what you do when you don't already have a trustworthy answer.\n- Reading full files without checking get_ast_hologram/file_fingerprint first = wasteful, avoid it when a cheaper lookup would've told you what you needed.\n- Any answer delivered without required disclosure (rule 6's exception), or a cached/auto-fixed result used without verification = FAIL, regardless of tokens saved \u2014 it can cost the user far more than tokens once it's wrong.\n\nRemember: the goal is spending fewer tokens on the SAME quality of answer, not a lower-quality answer for fewer tokens.";
 export declare function setupPromptsHandlers(server: Server): void;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/cjs/mcp/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,eAAO,MAAM,mBAAmB,m6FA+C4B,CAAC;AAE7D,eAAO,MAAM,sBAAsB,27QA+GqF,CAAC;AAEzH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiDzD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,eAAO,MAAM,mBAAmB,0uGAkD4B,CAAC;AAE7D,eAAO,MAAM,sBAAsB,27QA+GqF,CAAC;AAEzH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiDzD"}

package/dist/cjs/mcp/prompts.js

@@ -38,7 +38,10 @@ be retrieved in future sessions across ALL projects.
 - Use \`list_workspace_dir\` to navigate structure
 - Use \`read_workspace_file\` (auto-compresses + scrubs secrets) instead of asking the user
 - Use \`search_workspace\` for text search across files
-- Use \`run_workspace_command\` for builds, tests, linters
+- Use \`run_workspace_command\` for builds, tests, linters — long output comes back distilled
+  (failing tests / diagnostics with locations). It is a real view of the run, not a guess, but it
+  is not the whole output: call \`output_region\` with the reported handle whenever you need the
+  rest, and never tell the user a run was clean based on a distilled view you didn't read.
 
 ### 7. Privacy is automatic
 \`read_workspace_file\` and \`search_workspace\` automatically scrub API keys and PII.

package/dist/cjs/mcp/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":";;;AAqKA,oDAiDC;AArND,iEAAsG;AAEzF,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4DA+CyB,CAAC;AAEhD,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wHA+GkF,CAAC;AAEzH,SAAgB,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,mCAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+JAA+J;oBAC5K,SAAS,EAAE,EAAE;iBACd;gBACD;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,wOAAwO;oBACrP,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,qCAAqC;gBAClD,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,2BAAmB;yBAC1B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,8BAAsB;yBAC7B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":";;;AAwKA,oDAiDC;AAxND,iEAAsG;AAEzF,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4DAkDyB,CAAC;AAEhD,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wHA+GkF,CAAC;AAEzH,SAAgB,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,mCAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+JAA+J;oBAC5K,SAAS,EAAE,EAAE;iBACd;gBACD;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,wOAAwO;oBACrP,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,qCAAqC;gBAClD,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,2BAAmB;yBAC1B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC9C,OAAO;gBACL,WAAW,EAAE,8CAA8C;gBAC3D,QAAQ,EAAE;oBACR;wBACE,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE;4BACP,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,8BAAsB;yBAC7B;qBACF;iBACF;aACF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cjs/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAwiCnE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CA2DN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAukCnE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CA2DN"}

package/dist/cjs/mcp/tools.js

@@ -72,6 +72,11 @@ const SurgicalASTInsert_1 = require("../utils/SurgicalASTInsert");
 const mcp_tools_1 = require("../infra/mcp-tools");
 const StateHashCache_1 = require("../utils/StateHashCache");
 const TokenReceipt_1 = require("../utils/TokenReceipt");
+const CommandOutputDistiller_1 = require("../utils/CommandOutputDistiller");
+const PatchMatcher_1 = require("../utils/PatchMatcher");
+const WorkspaceSearch_1 = require("../utils/WorkspaceSearch");
+const ReadWorkspaceCache_1 = require("../utils/ReadWorkspaceCache");
+const SearchCache_1 = require("../utils/SearchCache");
 // ── Pro License Gate ──────────────────────────────────────────────────────────
 const LICENSE_FILE = path_1.default.join(os_1.default.homedir(), '.lemma-cache', 'license.json');
 let _proStatusCache = null;
@@ -128,7 +133,7 @@ const toolDefinitions = [
     },
     {
         name: "search_memory",
-        description: "Search Lemma's semantic memory (The Brain) before answering technical questions. Retrieves past solutions, fixes, and context from ALL your projects globally. If similarity > 50%, use this answer directly.",
+        description: "Search Lemma's semantic memory (The Brain) before investigating something from scratch — retrieves past solutions, fixes, and context from ALL your projects globally. Results are split into 'fresh' (safe to reuse — either untracked general knowledge, or every file it depended on still hashes the same) and 'stale' (a similar question was answered before, but a tracked file changed since — re-verify against current state before reusing). Never treat a stale result as current.",
         inputSchema: {
             type: "object",
             properties: {
@@ -140,13 +145,14 @@ const toolDefinitions = [
     },
     {
         name: "store_memory",
-        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain.",
+        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused.",
         inputSchema: {
             type: "object",
             properties: {
                 query: { type: "string", description: "The natural language query key" },
                 response: { type: "string", description: "The complete technical content to memorize" },
                 provider: { type: "string", description: "Optional model provider name", default: "generic" },
+                filePaths: { type: "array", items: { type: "string" }, description: "Paths (relative to project root) this answer depends on. If any changes later, this memory is marked stale instead of being silently reused." },
             },
             required: ["query", "response"],
         },
@@ -175,12 +181,13 @@ const toolDefinitions = [
     },
     {
         name: "read_workspace_file",
-        description: "Read a file inside the workspace. Automatically compresses comments/whitespace and scrubs API keys.",
+        description: "Read a file inside the workspace. Automatically compresses comments/whitespace and scrubs API keys. If this exact file (same compact mode) was already read this session and hasn't changed on disk, returns a short UNCHANGED marker instead of resending the full content — reuse your existing copy. Pass force:true to always get the full content.",
         inputSchema: {
             type: "object",
             properties: {
                 filePath: { type: "string", description: "Path relative to the project root" },
                 compact: { type: "boolean", description: "Whether to compress comments and whitespace", default: true },
+                force: { type: "boolean", description: "Bypass the unchanged-file short-circuit and always return full content", default: false },
             },
             required: ["filePath"],
         },
@@ -211,7 +218,7 @@ const toolDefinitions = [
     },
     {
         name: "apply_workspace_patch",
-        description: "Apply a smart search-and-replace patch to an existing file. Safe against duplicate matches.",
+        description: "Apply a smart search-and-replace patch to an existing file. Falls back through whitespace-normalized, indent-anchored, and fuzzy matching if the exact block isn't found — so a searchContent built from a compacted read still applies. Safe against duplicate matches. On total failure, the error includes a diff against the closest candidate block.",
         inputSchema: {
             type: "object",
             properties: {
@@ -224,15 +231,35 @@ const toolDefinitions = [
     },
     {
         name: "run_workspace_command",
-        description: "Execute a bash command in the workspace root. Maximum execution timeout of 15 seconds.",
+        description: "Execute a bash command in the workspace root (15s timeout). Captures both stdout and stderr. Long test/build/lint output is distilled deterministically — for jest, vitest and tsc it returns the failing tests or diagnostics with their locations and reasons, dropping code frames and node_modules stack frames; anything else falls back to head/tail plus error-matching lines. The complete output is always stored first and the reply carries a handle: nothing is lost, use output_region to retrieve any part verbatim. Pass raw:true to skip distillation.",
         inputSchema: {
             type: "object",
             properties: {
                 command: { type: "string", description: "The bash command to run" },
+                raw: {
+                    type: "boolean",
+                    description: "Return the complete untouched output instead of the distilled view",
+                    default: false,
+                },
             },
             required: ["command"],
         },
     },
+    {
+        name: "output_region",
+        description: "Retrieve any part of a command output previously stored by run_workspace_command, verbatim. This is what makes distillation lossless — use it when the distilled view isn't enough. Pass all:true for the whole output, section for one named block (a failing test title or a file path, as listed in the distilled view), or startLine/endLine for a range.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                handle: { type: "string", description: "The handle reported by run_workspace_command" },
+                section: { type: "string", description: "Name of a section to retrieve (failing test title or file path)" },
+                startLine: { type: "number", description: "First line to return (1-indexed, inclusive)" },
+                endLine: { type: "number", description: "Last line to return (1-indexed, inclusive)" },
+                all: { type: "boolean", description: "Return the complete stored output", default: false },
+            },
+            required: ["handle"],
+        },
+    },
     {
         name: "list_workspace_dir",
         description: "List files and subdirectories recursively to navigate the repository structure.",
@@ -246,12 +273,13 @@ const toolDefinitions = [
     },
     {
         name: "search_workspace",
-        description: "Perform a fast local text search (grep) across all files in the project workspace.",
+        description: "Perform a fast local text search (grep) across all files in the project workspace. Respects .gitignore, skips binaries and files over 500KB, groups results by file (capped per file), and stops at maxResults. For code files (.ts/.tsx/.js/.jsx), matches inside the same function/class/method are collapsed into one entry with its signature and line range instead of raw duplicate lines. Repeating an identical query while the workspace is unchanged returns the cached result instantly instead of re-scanning.",
         inputSchema: {
             type: "object",
             properties: {
                 query: { type: "string", description: "The keyword or text pattern to search for" },
-                extension: { type: "string", description: "Optional file extension filter (e.g., 'ts', 'json')" },
+                extension: { type: "string", description: "Optional file extension filter, comma-separated for multiple (e.g., 'ts,tsx')" },
+                maxResults: { type: "number", description: "Maximum total matches to return before truncating", default: 200 },
             },
             required: ["query"],
         },
@@ -1014,6 +1042,7 @@ const toolHandlers = {
     create_workspace_file: handleCreateWorkspaceFile,
     apply_workspace_patch: handleApplyWorkspacePatch,
     run_workspace_command: handleRunWorkspaceCommand,
+    output_region: handleOutputRegion,
     list_workspace_dir: handleListWorkspaceDir,
     search_workspace: handleSearchWorkspace,
     squeeze_prompt: handleSqueezePrompt,
@@ -1152,12 +1181,27 @@ async function handleSearchMemory(args) {
         if (results.length === 0) {
             return { content: [{ type: "text", text: "No relevant memories found in Lemma's Brain." }] };
         }
-        const formatted = results
-            .map((r, i) => {
-            return `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
-        })
-            .join("\n\n---\n\n");
-        return { content: [{ type: "text", text: `Lemma found ${results.length} memories:\n\n${formatted}` }] };
+        const fresh = results.filter((r) => r.fresh);
+        const stale = results.filter((r) => !r.fresh);
+        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
+        if (fresh.length > 0) {
+            // Only a fresh hit (or an untracked, purely conceptual entry) counts as a real
+            // avoided re-investigation — this is the only case worth crediting as savings.
+            const bestFresh = fresh[0];
+            const tokensSaved = Math.max(100, Math.floor(String(bestFresh.response).length / 4));
+            (0, reportSavings_1.reportSavings)({ source: "cache", tokens: tokensSaved, toolName: "search_memory", query: query.substring(0, 100) });
+        }
+        const parts = [];
+        if (fresh.length > 0) {
+            parts.push(`Lemma found ${fresh.length} fresh ${fresh.length === 1 ? "memory" : "memories"} (from cache — say so if you use this):\n\n${fresh.map(formatResult).join("\n\n---\n\n")}`);
+        }
+        if (stale.length > 0) {
+            const staleText = stale
+                .map((r, i) => `${formatResult(r, i)}\nSTALE — changed since stored: ${r.staleFiles.join(", ")}`)
+                .join("\n\n---\n\n");
+            parts.push(`${stale.length} more ${stale.length === 1 ? "memory is" : "memories are"} similar but STALE (underlying file(s) changed) — do not reuse verbatim, re-verify against current file state:\n\n${staleText}`);
+        }
+        return { content: [{ type: "text", text: parts.join("\n\n===\n\n") }] };
     }
     catch (e) {
         (0, utils_1.logError)("search_memory", e);
@@ -1168,11 +1212,12 @@ async function handleStoreMemory(args) {
     const query = args?.query;
     const responseText = args?.response;
     const provider = args?.provider || "generic";
+    const filePaths = Array.isArray(args?.filePaths) ? args.filePaths : undefined;
     if (!query || !responseText)
         throw new Error("Query and response are required");
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const storeRes = brain.store(query, responseText, provider);
+        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths);
         const tokensSaved = Math.max(100, Math.floor(responseText.length / 4));
         (0, reportSavings_1.reportSavings)({
             source: "cache",
@@ -1180,7 +1225,8 @@ async function handleStoreMemory(args) {
             toolName: "store_memory",
             query: query.substring(0, 100),
         });
-        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}` }] };
+        const trackingNote = filePaths && filePaths.length > 0 ? ` Tracking freshness against ${filePaths.length} file(s) — this memory auto-invalidates if they change.` : "";
+        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}` }] };
     }
     catch (e) {
         (0, utils_1.logError)("store_memory", e);
@@ -1225,6 +1271,7 @@ async function handleAutoHeal(args) {
 async function handleReadWorkspaceFile(args) {
     const filePath = args?.filePath;
     const compact = args?.compact !== false;
+    const force = !!args?.force;
     if (!filePath)
         throw new Error("filePath is required");
     const workspaceRoot = process.cwd();
@@ -1232,6 +1279,24 @@ async function handleReadWorkspaceFile(args) {
         const { resolved } = (0, utils_1.safeResolvePath)(workspaceRoot, filePath);
         let content = fs_1.default.readFileSync(resolved, "utf8");
         const originalSize = content.length;
+        const dedup = (0, ReadWorkspaceCache_1.checkAlreadySent)(resolved, compact, content);
+        if (!force && dedup.unchanged) {
+            (0, reportSavings_1.reportSavings)({
+                source: "contextSqueeze",
+                charsBefore: originalSize,
+                charsAfter: 0,
+                toolName: "read_workspace_file",
+                filePath,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `UNCHANGED: ${filePath} is identical to what you already read this session (hash ${dedup.hash.slice(0, 12)}) — reuse your existing copy. Pass force:true to re-fetch anyway.`,
+                    },
+                ],
+            };
+        }
         if (compact) {
             content = (0, ContextSqueezer_1.squeezeCode)(content);
             if (content.length < originalSize) {
@@ -1252,6 +1317,7 @@ async function handleReadWorkspaceFile(args) {
         catch (err) {
             (0, utils_1.logWarn)("read_workspace_file", "SemanticScrubber failed, returning raw content");
         }
+        (0, ReadWorkspaceCache_1.recordSent)(resolved, compact, dedup.hash);
         return { content: [{ type: "text", text: content }] };
     }
     catch (err) {
@@ -1318,30 +1384,44 @@ async function handleApplyWorkspacePatch(args) {
             return { content: [{ type: "text", text: `Error: File ${filePath} does not exist.` }] };
         }
         const originalContent = fs_1.default.readFileSync(resolved, "utf8");
-        const index = originalContent.indexOf(searchContent);
-        if (index === -1) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error: Target search content not found in file. Make sure the search content matches exactly, including indentation, tabs, spaces, and newlines.`,
-                    },
-                ],
-            };
-        }
-        if (originalContent.indexOf(searchContent, index + 1) !== -1) {
+        const matchResult = (0, PatchMatcher_1.findMatch)(originalContent, searchContent);
+        if (!Array.isArray(matchResult)) {
+            if (matchResult.reason === "ambiguous") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: Multiple matches found for the search content. Please provide a larger search block with unique surrounding context lines to make it unambiguous.`,
+                        },
+                    ],
+                };
+            }
+            if (matchResult.candidateDiff) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: No match found for the search content. Closest candidate starts at line ${matchResult.candidateStartLine} (- = your searchContent, + = actual file content):\n\n${matchResult.candidateDiff}`,
+                        },
+                    ],
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Error: Multiple matches found for the search content. Please provide a larger search block with unique surrounding context lines to make it unambiguous.`,
+                        text: `Error: Target search content not found in file, and no similar block was found to diff against.`,
                     },
                 ],
             };
         }
-        const updatedContent = originalContent.replace(searchContent, replaceContent);
-        fs_1.default.writeFileSync(resolved, updatedContent, "utf8");
-        return { content: [{ type: "text", text: `Success: Patch successfully applied to ${filePath}` }] };
+        const match = matchResult[0];
+        const contentLines = originalContent.split("\n");
+        const finalReplace = match.strategy === "exact" ? replaceContent : (0, PatchMatcher_1.reindentReplacement)(replaceContent, searchContent, contentLines[match.startLine]);
+        const updatedLines = [...contentLines.slice(0, match.startLine), ...finalReplace.split("\n"), ...contentLines.slice(match.endLine + 1)];
+        fs_1.default.writeFileSync(resolved, updatedLines.join("\n"), "utf8");
+        const note = match.strategy === "exact" ? "" : ` (matched via ${match.strategy}, score ${match.score.toFixed(2)})`;
+        return { content: [{ type: "text", text: `Success: Patch successfully applied to ${filePath}${note}` }] };
     }
     catch (err) {
         (0, utils_1.logError)("apply_workspace_patch", err);
@@ -1377,25 +1457,95 @@ async function handleRunWorkspaceCommand(args) {
     // ── End allowlist check ────────────────────────────────────────────────
     const workspaceRoot = process.cwd();
     try {
-        const output = (0, child_process_1.execSync)(command, {
+        // spawnSync rather than execSync: execSync leaves stderr attached to the parent unless
+        // stdio is overridden, which silently dropped the output of every tool that reports on
+        // stderr (jest and tsc both do) on a successful run. It also gives us stdout, stderr and
+        // the exit code through one code path instead of a throw-on-failure split.
+        const result = (0, child_process_1.spawnSync)(command, {
             cwd: workspaceRoot,
+            shell: true,
             encoding: "utf8",
             timeout: 15000,
+            maxBuffer: 20 * 1024 * 1024,
             env: { ...process.env },
         });
-        return { content: [{ type: "text", text: `Command completed successfully.\n\nOutput:\n${output}` }] };
+        if (result.error) {
+            const timedOut = result.error.code === "ETIMEDOUT";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: timedOut
+                            ? `Command timed out after 15s: ${command}`
+                            : `Command could not be executed: ${result.error.message}`,
+                    },
+                ],
+            };
+        }
+        const stdout = result.stdout || "";
+        const stderr = result.stderr || "";
+        const combined = [stdout, stderr].filter((s) => s.trim().length > 0).join("\n");
+        const status = result.status ?? 0;
+        const header = status === 0 ? "Command completed successfully." : `Command failed with exit code ${status}.`;
+        if (!combined.trim()) {
+            return { content: [{ type: "text", text: `${header}\n\n(no output)` }] };
+        }
+        const distilled = (0, CommandOutputDistiller_1.distillCommandOutput)(combined, { command, raw: args?.raw === true });
+        if (distilled.handle) {
+            (0, TokenReceipt_1.recordReceiptEvent)("tool_call", `run_workspace_command distilled (${distilled.format})`, {
+                command,
+                originalChars: distilled.originalChars,
+                distilledChars: distilled.distilledChars,
+                handle: distilled.handle,
+            });
+        }
+        return {
+            content: [
+                { type: "text", text: `${header}\n\nOutput:\n${distilled.text}${(0, CommandOutputDistiller_1.buildDistillFooter)(distilled)}` },
+            ],
+        };
     }
     catch (err) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `Command failed with exit code ${err.status || "unknown"}.\n\nStdout:\n${err.stdout || ""}\n\nStderr:\n${err.stderr || err.message || ""}`,
+                    text: `Command could not be executed: ${err?.message || String(err)}`,
                 },
             ],
         };
     }
 }
+async function handleOutputRegion(args) {
+    const handle = args?.handle;
+    if (!handle)
+        throw new Error("handle is required");
+    const region = (0, CommandOutputDistiller_1.readRegion)({
+        handle,
+        section: args?.section,
+        startLine: args?.startLine,
+        endLine: args?.endLine,
+        all: args?.all === true,
+    });
+    if (!region.found) {
+        const parts = [region.error ?? `Could not read region for handle "${handle}".`];
+        if (region.availableSections?.length) {
+            parts.push("", "Available sections:", ...region.availableSections.map((s) => `  ${s}`));
+        }
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+    }
+    const scope = region.startLine === 1 && region.endLine === region.totalLines
+        ? `complete output (${region.totalLines} lines)`
+        : `lines ${region.startLine}-${region.endLine} of ${region.totalLines}`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Raw output for \`${region.command ?? "?"}\` — ${scope}, verbatim:\n\n${region.text}`,
+            },
+        ],
+    };
+}
 function listDirRecursive(currentDir, relativePath, depth, maxDepth) {
     if (depth > maxDepth)
         return [];
@@ -1442,53 +1592,28 @@ async function handleListWorkspaceDir(args) {
         return { content: [{ type: "text", text: `Error listing directory: ${err.message}` }] };
     }
 }
-function searchDirRecursive(currentDir, relativePath, query, extFilter) {
-    try {
-        const entries = fs_1.default.readdirSync(currentDir, { withFileTypes: true });
-        let result = [];
-        for (const entry of entries) {
-            if (["node_modules", ".git", "dist", "chroma_data", ".lemma"].includes(entry.name))
-                continue;
-            const rel = relativePath ? path_1.default.join(relativePath, entry.name) : entry.name;
-            const full = path_1.default.join(currentDir, entry.name);
-            if (entry.isDirectory()) {
-                result.push(...searchDirRecursive(full, rel, query, extFilter));
-            }
-            else {
-                if (extFilter && !entry.name.endsWith(`.${extFilter}`))
-                    continue;
-                try {
-                    const content = fs_1.default.readFileSync(full, "utf8");
-                    if (content.toLowerCase().includes(query.toLowerCase())) {
-                        const lines = content.split("\n");
-                        lines.forEach((lineText, idx) => {
-                            if (lineText.toLowerCase().includes(query.toLowerCase())) {
-                                result.push({ filePath: rel, line: idx + 1, text: lineText.trim() });
-                            }
-                        });
-                    }
-                }
-                catch { }
-            }
-        }
-        return result;
-    }
-    catch {
-        return [];
-    }
-}
 async function handleSearchWorkspace(args) {
     const query = args?.query;
     const extension = args?.extension;
+    const maxResults = args?.maxResults || 200;
     if (!query)
         throw new Error("query is required");
     const workspaceRoot = process.cwd();
     try {
-        const results = searchDirRecursive(workspaceRoot, "", query, extension);
-        if (results.length === 0) {
-            return { content: [{ type: "text", text: `No matches found in the workspace for "${query}".` }] };
-        }
-        let formatted = results.map((r) => `[${r.filePath}:${r.line}] ${r.text}`).join("\n");
+        const extensions = (0, WorkspaceSearch_1.parseExtensionFilter)(extension);
+        const cached = (0, SearchCache_1.getCachedSearch)(workspaceRoot, query, extensions, maxResults);
+        if (cached.text !== null) {
+            (0, reportSavings_1.reportSavings)({ source: "cache", tokens: Math.floor(cached.text.length / 4), toolName: "search_workspace", query: query.substring(0, 100) });
+            return { content: [{ type: "text", text: cached.text }] };
+        }
+        const { matches, truncated } = (0, WorkspaceSearch_1.searchWorkspace)(workspaceRoot, query, extensions, maxResults);
+        if (matches.length === 0) {
+            const emptyText = `No matches found in the workspace for "${query}".`;
+            (0, SearchCache_1.setCachedSearch)(query, extensions, maxResults, cached.fingerprint, emptyText);
+            return { content: [{ type: "text", text: emptyText }] };
+        }
+        const grouped = (0, WorkspaceSearch_1.groupSearchResults)(matches, truncated, undefined, workspaceRoot);
+        let formatted = grouped.formatted;
         try {
             const scrubber = new SemanticScrubber_1.SemanticScrubber();
             const { maskedPrompt } = scrubber.mask(formatted);
@@ -1497,8 +1622,16 @@ async function handleSearchWorkspace(args) {
         catch (err) {
             (0, utils_1.logWarn)("search_workspace", "SemanticScrubber failed, returning raw results");
         }
+        const truncationNote = grouped.truncated ? ` (truncated at ${maxResults} matches — narrow your query or extension filter for the rest)` : "";
+        const resultText = `Found ${grouped.totalMatches} matches across ${grouped.filesMatched} files${truncationNote}:\n\n${formatted}`;
+        (0, SearchCache_1.setCachedSearch)(query, extensions, maxResults, cached.fingerprint, resultText);
         return {
-            content: [{ type: "text", text: `Found ${results.length} matches:\n\n${formatted}` }],
+            content: [
+                {
+                    type: "text",
+                    text: resultText,
+                },
+            ],
         };
     }
     catch (err) {