@nxuss/lemma 1.8.1 → 1.9.0

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

@@ -1,4 +1,13 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-export declare const LEMMA_TURBOMODE_PROMPT = "You are operating in LEMMA TURBOMODE. Your goal: reduce what enters the model's context \u2014 file reads, command output, and repeated reasoning \u2014 without ever costing the user a correct answer. Every reduction is recorded in an auditable ledger that also records what Lemma spent to achieve it.\n\nThere is no fixed multiplier to hit. Lemma's own overhead (this prompt plus every tool schema) is charged to that ledger before a single token is saved, so a session only comes out ahead if the reductions below actually exceed it. Optimize for real net savings, not for a number.\n\n## MANDATORY TURBOMODE RULES \u2014 VIOLATE THESE AND YOU WASTE THE USER'S MONEY\n\n### 0. Every tool call costs tokens too\nA tool call and its result both stay in the transcript and are re-sent on every later turn. Before calling a Lemma tool, expect it to save more than that round-trip costs \u2014 on a small file or a short command, reading it directly is cheaper. Never call a reporting tool on a schedule: a report is not work. Call one only when the user asks how the session is going.\n\n### 0b. The tool list you see is not everything Lemma has\nSchemas for situational tools are withheld from this session to keep the per-turn cost down. When\nno advertised tool fits, call `lemma_toolbox` (action=\"list\" with a query) before concluding\nLemma can't do it, then action=\"call\" to run what you find. Never tell the user a capability is\nmissing without checking the toolbox first.\n\n### 1. Compression is for YOUR context only \u2014 never for code shown to the user\nLemma's compressors (turbosqueeze, wormhole_squeeze, squeeze_prompt \u2014 via the toolbox) exist to\nshrink code before it enters your own reasoning window. NEVER hand a compressed version to the\nuser: they get the real, complete file (comments, imports, formatting intact) so it stays\ncopy-pasteable and correct. If you reasoned over a squeezed version, re-fetch the untouched\noriginal before 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. 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### 4. 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### 5. 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 repeating the user's question back to them.\n- Exception: disclosures required elsewhere in these rules (cache-hit source per rule 2,\n  a risky/irreversible action) are never fluff \u2014 say them in one short line. Conciseness trims\n  filler, not information the user needs to trust the answer.\n\n### 6. 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### 7. 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### 8. 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### 9. 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. Anything the toolbox hands you is still a candidate, not a verdict\nTools reached via `lemma_toolbox` (auto-fixes for failing tests, cached prompt patterns,\nBrain-suggested patches) return suggestions. Check a suggested fix actually addresses the failing\nassertion before applying it \u2014 a wrong auto-fix applied blind costs far more (broken build,\ndebugging round-trip) than the tokens saved by skipping the check.\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 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.";
+/**
+ * This text is injected into the system prompt and re-sent on every turn of the session, so
+ * its length is a recurring charge against the very savings it asks for. It is kept to the
+ * rules that change behaviour or protect correctness; anything that only restates good default
+ * behaviour (be concise, don't pad) was removed rather than paid for on every request.
+ *
+ * The full rationale and scoring model live in the `lemma-turbomode` prompt resource, which
+ * the client can fetch on demand instead of carrying permanently.
+ */
+export declare const LEMMA_TURBOMODE_PROMPT = "You are operating in LEMMA TURBOMODE. Reduce what enters the model's context \u2014 file reads, command output, repeated reasoning \u2014 without ever costing the user a correct answer. Lemma's own overhead (this prompt + every tool schema) is charged to the ledger before a single token is saved, so optimize for real net savings, not for a multiplier.\n\n## RULES\n\n**0. Tool calls cost tokens too.** A call and its result stay in the transcript and are re-sent every later turn. Expect a Lemma tool to save more than that round-trip costs \u2014 on a small file or short command, reading it directly is cheaper. Never call a reporting tool on a schedule.\n\n**0b. The advertised list is not everything Lemma has.** Situational schemas are withheld to keep per-turn cost down. Before concluding Lemma can't do something, call `lemma_toolbox` (action=\"list\" with a query), then action=\"call\".\n\n**1. Compression is for YOUR context only.** NEVER hand a compressed version to the user \u2014 they get the real, complete file, comments and imports intact. If you reasoned over a squeezed version, re-fetch the original before presenting it.\n\n**2. A cache hit is a hint, not an answer.** `smarter_cache` requires similarity >= 0.8. Always tell the user the answer came from cache. If they're about to act on it (run a command, apply a patch, ship code), verify against current state first \u2014 cached answers go stale. On a MISS or any doubt, reason normally.\n\n**3. Locate before reading only when locating is cheaper.** Don't know which file? `get_ast_hologram` / `search_workspace` beats reading candidates one by one. Already know the file? Read it \u2014 a lookup round-trip on a small file costs more than the file. `read_workspace_file` carries real line numbers and takes offset/limit, so prefer a targeted range on large files.\n\n**4. store_memory only after verification.** Store once the fix actually worked (tests pass, build succeeded, user confirmed) \u2014 not your first attempt. A wrong answer stored here becomes a false cache hit for a future session, and unwinding that costs far more than it saved.\n\n**5. Never trade a required disclosure for brevity.** A cache-hit source or a risky/irreversible action is not filler. One short line.\n\n**6. File-dependent questions \u2192 state_hash_cache, not smarter_cache.** It only hits when the referenced files' hashes are unchanged: a guaranteed-valid answer instead of a similarity guess. Look up before, store after. Use `smarter_cache` only for file-independent questions.\n\n**7. Edit in place.** `apply_workspace_patch` or `surgical_ast_insert` over rewriting a file with `write_workspace_file`; reserve the full write for renames, structural rewrites and new files. For mechanical work, `get_routing_advice` says whether a cheaper model suffices.\n\n**8. \"How much did we save\" \u2192 token_receipt, don't estimate.** It returns a real auditable log. Show the byType breakdown so the user can verify it.\n\n**9. What the toolbox hands you is a candidate, not a verdict.** Auto-fixes, cached patterns and Brain-suggested patches are suggestions. Check a fix addresses the actual failing assertion before applying it.\n\n## SCORING\nCorrectness first, then cost \u2014 a fast wrong answer costs more than a slow right one once you count the round-trip to fix it. A verified cache hit is best; a MISS followed by reasoning from scratch is the normal GOOD outcome, not a failure. A cached or auto-fixed result delivered without disclosure or verification is a FAIL regardless of tokens saved.\n\nFewer tokens for the SAME quality of answer \u2014 never a worse answer for fewer tokens.";
 export declare function setupPromptsHandlers(server: Server): void;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/esm/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,sBAAsB,23NAsFqF,CAAC;AAEzH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CA8BzD"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,slHA6BkD,CAAC;AAEtF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CA8BzD"}

package/dist/esm/mcp/prompts.js

@@ -1,91 +1,43 @@
 import { GetPromptRequestSchema, ListPromptsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-export const LEMMA_TURBOMODE_PROMPT = `You are operating in LEMMA TURBOMODE. Your goal: reduce what enters the model's context — file reads, command output, and repeated reasoning — without ever costing the user a correct answer. Every reduction is recorded in an auditable ledger that also records what Lemma spent to achieve it.
+/**
+ * This text is injected into the system prompt and re-sent on every turn of the session, so
+ * its length is a recurring charge against the very savings it asks for. It is kept to the
+ * rules that change behaviour or protect correctness; anything that only restates good default
+ * behaviour (be concise, don't pad) was removed rather than paid for on every request.
+ *
+ * The full rationale and scoring model live in the `lemma-turbomode` prompt resource, which
+ * the client can fetch on demand instead of carrying permanently.
+ */
+export const LEMMA_TURBOMODE_PROMPT = `You are operating in LEMMA TURBOMODE. Reduce what enters the model's context — file reads, command output, repeated reasoning — without ever costing the user a correct answer. Lemma's own overhead (this prompt + every tool schema) is charged to the ledger before a single token is saved, so optimize for real net savings, not for a multiplier.
 
-There is no fixed multiplier to hit. Lemma's own overhead (this prompt plus every tool schema) is charged to that ledger before a single token is saved, so a session only comes out ahead if the reductions below actually exceed it. Optimize for real net savings, not for a number.
+## RULES
 
-## MANDATORY TURBOMODE RULES — VIOLATE THESE AND YOU WASTE THE USER'S MONEY
+**0. Tool calls cost tokens too.** A call and its result stay in the transcript and are re-sent every later turn. Expect a Lemma tool to save more than that round-trip costs — on a small file or short command, reading it directly is cheaper. Never call a reporting tool on a schedule.
 
-### 0. Every tool call costs tokens too
-A tool call and its result both stay in the transcript and are re-sent on every later turn. Before calling a Lemma tool, expect it to save more than that round-trip costs — on a small file or a short command, reading it directly is cheaper. Never call a reporting tool on a schedule: a report is not work. Call one only when the user asks how the session is going.
+**0b. The advertised list is not everything Lemma has.** Situational schemas are withheld to keep per-turn cost down. Before concluding Lemma can't do something, call \`lemma_toolbox\` (action="list" with a query), then action="call".
 
-### 0b. The tool list you see is not everything Lemma has
-Schemas for situational tools are withheld from this session to keep the per-turn cost down. When
-no advertised tool fits, call \`lemma_toolbox\` (action="list" with a query) before concluding
-Lemma can't do it, then action="call" to run what you find. Never tell the user a capability is
-missing without checking the toolbox first.
+**1. Compression is for YOUR context only.** NEVER hand a compressed version to the user — they get the real, complete file, comments and imports intact. If you reasoned over a squeezed version, re-fetch the original before presenting it.
 
-### 1. Compression is for YOUR context only — never for code shown to the user
-Lemma's compressors (turbosqueeze, wormhole_squeeze, squeeze_prompt — via the toolbox) exist to
-shrink code before it enters your own reasoning window. NEVER hand a compressed version to the
-user: they get the real, complete file (comments, imports, formatting intact) so it stays
-copy-pasteable and correct. If you reasoned over a squeezed version, re-fetch the untouched
-original before presenting it.
+**2. A cache hit is a hint, not an answer.** \`smarter_cache\` requires similarity >= 0.8. Always tell the user the answer came from cache. If they're about to act on it (run a command, apply a patch, ship code), verify against current state first — cached answers go stale. On a MISS or any doubt, reason normally.
 
-### 2. smarter_cache (threshold 0.8) is a hint, not an answer
-Call \`smarter_cache\` with the user's question before reasoning from scratch — a hit can save
-time. But NEVER return a cache hit verbatim as if freshly reasoned:
-- Require similarity >= 0.8 (raised from 0.75 — 0.75 was matching questions that weren't
-  actually the same question).
-- Always tell the user the answer came from cache (e.g. "from a cached earlier answer:").
-- If the user is about to act on the answer (run a command, apply a patch, ship code), verify
-  it against current file/tool state before using it — cached answers can be stale.
-- On a MISS, or on any doubt, reason normally.
+**3. Locate before reading only when locating is cheaper.** Don't know which file? \`get_ast_hologram\` / \`search_workspace\` beats reading candidates one by one. Already know the file? Read it — a lookup round-trip on a small file costs more than the file. \`read_workspace_file\` carries real line numbers and takes offset/limit, so prefer a targeted range on large files.
 
-### 3. Before reading files → call get_ast_hologram
-NEVER 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.
+**4. store_memory only after verification.** Store once the fix actually worked (tests pass, build succeeded, user confirmed) — not your first attempt. A wrong answer stored here becomes a false cache hit for a future session, and unwinding that costs far more than it saved.
 
-### 4. After every VERIFIED solution → call store_memory automatically
-Store via \`store_memory\` once you've confirmed the fix/answer actually worked (tests pass,
-the user confirmed, the build succeeded) — not the first thing you tried. A wrong answer stored
-here becomes a "cache hit" served to a future session, and unwinding that costs far more than
-the tokens it saved. Verified answers are still free to cache aggressively.
+**5. Never trade a required disclosure for brevity.** A cache-hit source or a risky/irreversible action is not filler. One short line.
 
-### 5. Answer concisely — no fluff, but never at the cost of a required disclosure
-- No "Sure, I can help you with that" — just do it.
-- No unnecessary explanation of what you did — unless asked.
-- No repeating the user's question back to them.
-- Exception: disclosures required elsewhere in these rules (cache-hit source per rule 2,
-  a risky/irreversible action) are never fluff — say them in one short line. Conciseness trims
-  filler, not information the user needs to trust the answer.
+**6. File-dependent questions → state_hash_cache, not smarter_cache.** It only hits when the referenced files' hashes are unchanged: a guaranteed-valid answer instead of a similarity guess. Look up before, store after. Use \`smarter_cache\` only for file-independent questions.
 
-### 6. For questions tied to specific files → prefer state_hash_cache over smarter_cache
-If the question depends on the current content of specific files (not just "similar wording"),
-call \`state_hash_cache\` (action="lookup") instead of \`smarter_cache\`. It only returns a hit
-when the referenced files' content hashes are unchanged — a guaranteed-valid answer, not a
-similarity guess. After answering, call it again with action="store" to cache it. Use
-\`smarter_cache\` only for file-independent questions (explanations, general how-tos).
+**7. Edit in place.** \`apply_workspace_patch\` or \`surgical_ast_insert\` over rewriting a file with \`write_workspace_file\`; reserve the full write for renames, structural rewrites and new files. For mechanical work, \`get_routing_advice\` says whether a cheaper model suffices.
 
-### 7. Route model choice through get_routing_advice, don't assume the biggest model
-Before a mechanical/low-complexity task (formatting, boilerplate, simple lookups), call
-\`get_routing_advice\` with the task prompt. If it recommends a cheaper model and the current
-provider supports switching, say so instead of silently burning a large-model budget on trivial work.
+**8. "How much did we save" → token_receipt, don't estimate.** It returns a real auditable log. Show the byType breakdown so the user can verify it.
 
-### 8. Default all file edits to symbol-level patches via surgical_ast_insert
-When adding a method/function/property to an existing class, interface, or file, prefer
-\`surgical_ast_insert\` over regenerating and rewriting the whole file. Only fall back to a full
-\`write_workspace_file\` when the change isn't a clean insertion (renames, structural rewrites,
-new files).
+**9. What the toolbox hands you is a candidate, not a verdict.** Auto-fixes, cached patterns and Brain-suggested patches are suggestions. Check a fix addresses the actual failing assertion before applying it.
 
-### 9. When asked "how much did we actually save" → call token_receipt, don't estimate
-\`token_receipt\` returns a real, auditable log of what happened this session (exact cache hits,
-semantic cache hits, file reads, fresh reasoning) — not a projected percentage. Use it instead of
-inventing a savings number, and show the byType breakdown so the user can verify it themselves.
+## SCORING
+Correctness first, then cost — a fast wrong answer costs more than a slow right one once you count the round-trip to fix it. A verified cache hit is best; a MISS followed by reasoning from scratch is the normal GOOD outcome, not a failure. A cached or auto-fixed result delivered without disclosure or verification is a FAIL regardless of tokens saved.
 
-### 10. Anything the toolbox hands you is still a candidate, not a verdict
-Tools reached via \`lemma_toolbox\` (auto-fixes for failing tests, cached prompt patterns,
-Brain-suggested patches) return suggestions. Check a suggested fix actually addresses the failing
-assertion before applying it — a wrong auto-fix applied blind costs far more (broken build,
-debugging round-trip) than the tokens saved by skipping the check.
-
-## TURBOMODE SCORING
-Correctness first, then cost — a fast wrong answer is more expensive than a slow right one once
-you count the round-trip to find and fix it.
-- Verified cache hit (state_hash_cache, or a disclosed smarter_cache hit above threshold) = best outcome: correct AND ~0 tokens spent.
-- Cache MISS + reasoning from scratch = the normal, GOOD outcome whenever no verified cache exists. Reasoning is not a failure mode — it's what you do when you don't already have a trustworthy answer.
-- Reading full files without checking get_ast_hologram first = wasteful, avoid it when a cheaper lookup would've told you what you needed.
-- Any answer delivered without required disclosure (rule 6's exception), or a cached/auto-fixed result used without verification = FAIL, regardless of tokens saved — it can cost the user far more than tokens once it's wrong.
-
-Remember: the goal is spending fewer tokens on the SAME quality of answer, not a lower-quality answer for fewer tokens.`;
+Fewer tokens for the SAME quality of answer — never a worse answer for fewer tokens.`;
 export function setupPromptsHandlers(server) {
     server.setRequestHandler(ListPromptsRequestSchema, async () => {
         return {

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

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/mcp/prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAEtG,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wHAsFkF,CAAC;AAEzH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+MAA+M;oBAC5N,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,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,sBAAsB;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":"AACA,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAEtG;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qFA6B+C,CAAC;AAEtF,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,KAAK,IAAI,EAAE;QAC5D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,+MAA+M;oBAC5N,SAAS,EAAE,EAAE;iBACd;aACF;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjE,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,sBAAsB;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/esm/mcp/tool-profiles.d.ts

@@ -40,10 +40,19 @@ export interface ResolvedToolSurface<T extends {
     /** Situational groups that matched this project. */
     activeGroups: string[];
 }
+export interface ResolveOptions {
+    /**
+     * Returns false for a tool this session is not licensed to run. Such a tool must not be
+     * advertised: its schema would be re-sent every turn purely to be refused at call time.
+     * It stays registered and discoverable through `lemma_toolbox`, which is where a user
+     * finds out the capability exists and what it takes to unlock it.
+     */
+    isEntitled?: (name: string) => boolean;
+}
 export declare function resolveToolSurface<T extends {
     name: string;
     description?: string;
-}>(allDefinitions: T[], cwd?: string): ResolvedToolSurface<T>;
+}>(allDefinitions: T[], cwd?: string, options?: ResolveOptions): ResolvedToolSurface<T>;
 /**
  * One-line-per-tool catalog of everything not advertised, so the model can find and
  * invoke a hidden tool without its schema having been resident all session.

package/dist/esm/mcp/tool-profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-profiles.d.ts","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,EA0BnC,CAAC;AA4DF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAoE,CAAC;AAkBnG,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC7D,OAAO,EAAE,WAAW,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,uFAAuF;IACvF,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,oDAAoD;IACpD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,cAAc,EAAE,CAAC,EAAE,EACnB,GAAG,GAAE,MAAsB,GAC1B,mBAAmB,CAAC,CAAC,CAAC,CAmCxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAuDR"}
+{"version":3,"file":"tool-profiles.d.ts","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,EA0BnC,CAAC;AA4DF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,UAAoE,CAAC;AAkBnG,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC7D,OAAO,EAAE,WAAW,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,uFAAuF;IACvF,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,oDAAoD;IACpD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,cAAc,EAAE,CAAC,EAAE,EACnB,GAAG,GAAE,MAAsB,EAC3B,OAAO,GAAE,cAAmB,GAC3B,mBAAmB,CAAC,CAAC,CAAC,CA4CxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAuDR"}

package/dist/esm/mcp/tool-profiles.js

@@ -105,10 +105,19 @@ function readConfiguredProfile(cwd) {
         return env;
     return "auto";
 }
-export function resolveToolSurface(allDefinitions, cwd = process.cwd()) {
+export function resolveToolSurface(allDefinitions, cwd = process.cwd(), options = {}) {
     const profile = readConfiguredProfile(cwd);
+    // `lemma_toolbox` is the only route back to a withheld schema, so no entitlement check may
+    // ever remove it — doing so would turn every deferred tool into an unreachable one.
+    const entitlementCheck = options.isEntitled ?? (() => true);
+    const isEntitled = (name) => name === "lemma_toolbox" || entitlementCheck(name);
     if (profile === "full") {
-        return { profile, advertised: allDefinitions, hidden: [], activeGroups: ["*"] };
+        const advertised = [];
+        const hidden = [];
+        for (const def of allDefinitions) {
+            (isEntitled(def.name) ? advertised : hidden).push(def);
+        }
+        return { profile, advertised, hidden, activeGroups: ["*"] };
     }
     // Always advertised: it is the only route back to a withheld schema, so hiding it
     // would turn a deferred tool into a lost one.
@@ -133,7 +142,7 @@ export function resolveToolSurface(allDefinitions, cwd = process.cwd()) {
     const advertised = [];
     const hidden = [];
     for (const def of allDefinitions) {
-        (allowed.has(def.name) ? advertised : hidden).push(def);
+        (allowed.has(def.name) && isEntitled(def.name) ? advertised : hidden).push(def);
     }
     return { profile, advertised, hidden, activeGroups };
 }

package/dist/esm/mcp/tool-profiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-profiles.js","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-profiles.js","sourceRoot":"","sources":["../../../src/mcp/tool-profiles.ts"],"names":[],"mappings":"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"}

package/dist/esm/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;AAwjCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAqHD,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;AAqCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CAwEN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA0kCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAqHD,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;AAqCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CAwEN"}

package/dist/esm/mcp/tools.js

@@ -38,6 +38,8 @@ import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/C
 import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
 import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
 import { checkAlreadySent, recordSent } from "../utils/ReadWorkspaceCache.js";
+import { mapSqueezedToOriginal, withLineNumbers, sequentialNumbers } from "../utils/LineNumberMap.js";
+import { fileOutline, formatOutline } from "../utils/FileOutline.js";
 import { getCachedSearch, setCachedSearch } from "../utils/SearchCache.js";
 // ── Pro License Gate ──────────────────────────────────────────────────────────
 const LICENSE_FILE = path.join(os.homedir(), '.lemma-cache', 'license.json');
@@ -163,13 +165,16 @@ const toolDefinitions = [
     },
     {
         name: "read_workspace_file",
-        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.",
+        description: "Read a file inside the workspace. Compresses comments/whitespace and scrubs API keys. Every line carries its REAL line number in the original file (compression removes lines, it never renumbers them), so you can cite file:line and patch precisely without re-reading. The header lists which imports were compressed away. Use offset/limit to read a line range of a large file. If this exact view was already read this session and hasn't changed on disk, returns an UNCHANGED marker plus a symbol outline — reuse your copy, or pass force:true if it's no longer in your context.",
         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 },
+                lineNumbers: { type: "boolean", description: "Prefix each line with its real line number in the original file", default: true },
+                offset: { type: "number", description: "First line to read (1-indexed). Omit to start at the beginning." },
+                limit: { type: "number", description: "How many lines to read from offset. Omit to read to the end." },
             },
             required: ["filePath"],
         },
@@ -213,7 +218,7 @@ const toolDefinitions = [
     },
     {
         name: "run_workspace_command",
-        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.",
+        description: "Execute a bash command in the workspace root. Default timeout 120s — raise it with timeoutMs for a full test or build run (max 600s). Captures both stdout and stderr, and returns whatever was produced even if the command times out. 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: {
@@ -223,6 +228,11 @@ const toolDefinitions = [
                     description: "Return the complete untouched output instead of the distilled view",
                     default: false,
                 },
+                timeoutMs: {
+                    type: "number",
+                    description: "Milliseconds before the command is killed (default 120000, max 600000)",
+                    default: 120000,
+                },
             },
             required: ["command"],
         },
@@ -1044,7 +1054,15 @@ const allToolDefinitions = [
 ];
 // Narrow what gets advertised to what this project can actually use. Hidden tools stay
 // registered in `toolHandlers` and callable — both directly and through `lemma_toolbox`.
-const _toolSurface = resolveToolSurface(allToolDefinitions, process.cwd());
+//
+// The entitlement filter matters as much as the project filter: without it a free session
+// advertised the full core surface — read, search, patch, run, AST — and refused fourteen of
+// those twenty tools at call time. That is the worst of both, paying the per-turn schema cost
+// for capabilities the session cannot use. They remain listed in `lemma_toolbox`, so the
+// capability is still discoverable and the upgrade path is still visible.
+const _toolSurface = resolveToolSurface(allToolDefinitions, process.cwd(), {
+    isEntitled: (name) => isProUser() || FREE_TOOLS.has(name),
+});
 const toolDefinitionsArray = _toolSurface.advertised;
 const hiddenToolDefinitions = _toolSurface.hidden;
 /** Serialized size of every tool schema sent to the client, for cost accounting. */
@@ -1437,14 +1455,28 @@ async function handleReadWorkspaceFile(args) {
     const filePath = args?.filePath;
     const compact = args?.compact !== false;
     const force = !!args?.force;
+    const lineNumbers = args?.lineNumbers !== false;
+    const offset = typeof args?.offset === "number" && args.offset > 0 ? Math.floor(args.offset) : undefined;
+    const limit = typeof args?.limit === "number" && args.limit > 0 ? Math.floor(args.limit) : undefined;
     if (!filePath)
         throw new Error("filePath is required");
     const workspaceRoot = process.cwd();
     try {
         const { resolved } = safeResolvePath(workspaceRoot, filePath);
-        let content = fs.readFileSync(resolved, "utf8");
+        const fullContent = fs.readFileSync(resolved, "utf8");
+        const view = { compact, lineNumbers, offset, limit };
+        // The range is applied to the original file, before any compression: `offset` means the
+        // line the user would see in an editor, not a position in the squeezed output.
+        const allLines = fullContent.split("\n");
+        const startIndex = offset ? Math.min(offset - 1, allLines.length) : 0;
+        const endIndex = limit ? Math.min(startIndex + limit, allLines.length) : allLines.length;
+        const ranged = offset || limit ? allLines.slice(startIndex, endIndex).join("\n") : fullContent;
+        const rangeHeader = offset || limit
+            ? `[lines ${startIndex + 1}-${endIndex} of ${allLines.length} in ${filePath}]\n`
+            : "";
+        let content = ranged;
         const originalSize = content.length;
-        const dedup = checkAlreadySent(resolved, compact, content);
+        const dedup = checkAlreadySent(resolved, view, content);
         if (!force && dedup.unchanged) {
             reportSavings({
                 source: "contextSqueeze",
@@ -1453,17 +1485,32 @@ async function handleReadWorkspaceFile(args) {
                 toolName: "read_workspace_file",
                 filePath,
             });
+            // A hash alone is not actionable: the model's context may have been compacted since,
+            // in which case it no longer holds the copy this marker tells it to reuse. The outline
+            // costs ~50 tokens and is enough to either locate what it needs or decide to re-fetch.
+            const outline = formatOutline(fileOutline(content), allLines.length);
             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.`,
+                        text: [
+                            `UNCHANGED: ${filePath} is identical to what you already read this session (hash ${dedup.hash.slice(0, 12)}) — reuse your existing copy.`,
+                            `If it is no longer in your context, re-fetch with force:true. Structure:`,
+                            outline,
+                        ].join("\n"),
                     },
                 ],
             };
         }
+        // Line numbers are computed against the pre-squeeze text and carried through, so a
+        // compressed read still reports the position the code actually occupies on disk.
+        let numbers = null;
         if (compact) {
-            content = squeezeCode(content);
+            const squeezed = squeezeCode(content);
+            if (lineNumbers) {
+                numbers = mapSqueezedToOriginal(content, squeezed).map((n) => (n === null ? null : n + startIndex));
+            }
+            content = squeezed;
             if (content.length < originalSize) {
                 reportSavings({
                     source: "contextSqueeze",
@@ -1474,16 +1521,26 @@ async function handleReadWorkspaceFile(args) {
                 });
             }
         }
+        else if (lineNumbers) {
+            numbers = sequentialNumbers(content, startIndex + 1);
+        }
         try {
             const scrubber = new SemanticScrubber();
             const { maskedPrompt } = scrubber.mask(content);
+            // Masking must not change the line count, or every number after a masked secret would
+            // be off. If it ever does, drop the gutter rather than print numbers that lie.
+            if (numbers && maskedPrompt.split("\n").length !== content.split("\n").length) {
+                numbers = null;
+            }
             content = maskedPrompt;
         }
         catch (err) {
             logWarn("read_workspace_file", "SemanticScrubber failed, returning raw content");
         }
-        recordSent(resolved, compact, dedup.hash);
-        return { content: [{ type: "text", text: content }] };
+        if (numbers)
+            content = withLineNumbers(content, numbers);
+        recordSent(resolved, view, dedup.hash);
+        return { content: [{ type: "text", text: rangeHeader + content }] };
     }
     catch (err) {
         logError("read_workspace_file", err);
@@ -1535,13 +1592,35 @@ async function handleCreateWorkspaceFile(args) {
         return { content: [{ type: "text", text: `Error creating file: ${err.message}` }] };
     }
 }
+/**
+ * `read_workspace_file` now returns a "123| code" gutter, which makes it easy to paste a block
+ * back into a patch with the numbers still attached. That block matches nothing on disk, so the
+ * patch fails for a reason that has nothing to do with the edit. Strip the gutter when *every*
+ * non-empty line carries one — a uniform prefix is a gutter; a lone "12| " inside real code is
+ * not, and must be left alone.
+ */
+function stripLineNumberGutter(text) {
+    const lines = text.split("\n");
+    const nonEmpty = lines.filter((l) => l.trim().length > 0);
+    if (nonEmpty.length === 0)
+        return text;
+    const GUTTER = /^\s*\d+\|\s?/;
+    if (!nonEmpty.every((l) => GUTTER.test(l)))
+        return text;
+    return lines.map((l) => l.replace(GUTTER, "")).join("\n");
+}
 async function handleApplyWorkspacePatch(args) {
     const filePath = args?.filePath;
-    const searchContent = args?.searchContent;
-    const replaceContent = args?.replaceContent;
-    if (!filePath || !searchContent || replaceContent === undefined) {
+    const rawSearch = args?.searchContent;
+    const rawReplace = args?.replaceContent;
+    if (!filePath || !rawSearch || rawReplace === undefined) {
         throw new Error("filePath, searchContent, and replaceContent are required");
     }
+    const searchContent = stripLineNumberGutter(rawSearch);
+    // Only strip the replacement's gutter when the search block had one too: that pairing means
+    // the model was working from a numbered read. Stripping unconditionally would mangle a
+    // replacement that legitimately contains "1| " (a table, a doc block).
+    const replaceContent = searchContent !== rawSearch ? stripLineNumberGutter(rawReplace) : rawReplace;
     const workspaceRoot = process.cwd();
     try {
         const { resolved } = safeResolvePath(workspaceRoot, filePath);
@@ -1635,32 +1714,38 @@ async function handleRunWorkspaceCommand(args) {
         // 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.
+        // 15s was below the runtime of the commands this tool exists for: a real `npm test` or
+        // `tsc --noEmit` always tripped it, so the distillation pipeline never ran on the output
+        // it was built for and the call was pure overhead before falling back to a plain shell.
+        const DEFAULT_TIMEOUT_MS = 120000;
+        const MAX_TIMEOUT_MS = 600000;
+        const requested = typeof args?.timeoutMs === "number" && args.timeoutMs > 0 ? args.timeoutMs : DEFAULT_TIMEOUT_MS;
+        const timeoutMs = Math.min(Math.floor(requested), MAX_TIMEOUT_MS);
         const result = spawnSync(command, {
             cwd: workspaceRoot,
             shell: true,
             encoding: "utf8",
-            timeout: 15000,
+            timeout: timeoutMs,
             maxBuffer: 20 * 1024 * 1024,
             env: { ...process.env },
         });
-        if (result.error) {
-            const timedOut = result.error.code === "ETIMEDOUT";
+        const timedOut = !!result.error && result.error.code === "ETIMEDOUT";
+        if (result.error && !timedOut) {
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: timedOut
-                            ? `Command timed out after 15s: ${command}`
-                            : `Command could not be executed: ${result.error.message}`,
-                    },
-                ],
+                content: [{ type: "text", text: `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}.`;
+        // A timed-out run still produced output, and that partial output is normally where the
+        // failure is. Discarding it forced the whole command to be re-run somewhere else.
+        const header = timedOut
+            ? `Command timed out after ${Math.round(timeoutMs / 1000)}s (killed): ${command}\nOutput produced before the kill is below — it may be incomplete. Re-run with a higher timeoutMs if it was still making progress.`
+            : status === 0
+                ? "Command completed successfully."
+                : `Command failed with exit code ${status}.`;
         if (!combined.trim()) {
             return { content: [{ type: "text", text: `${header}\n\n(no output)` }] };
         }