@duckmind/dm-linux-x64 0.65.4 → 0.65.6

package/extensions/dm-lens/tools/lsp-navigation.js

@@ -8,6 +8,7 @@ import {
   recordLspMutationOutcome
 } from "../clients/lsp-mutation.js";
 import { uriToPath } from "../clients/path-utils.js";
+import { escapeRegExp } from "../clients/string-utils.js";
 import { isRecordableProjectPath } from "../clients/file-utils.js";
 import { compactRenderResult } from "./render-compact.js";
 import {
@@ -108,9 +109,6 @@ function emptyReasonForOperation(operation) {
     return "no-call-hierarchy-results";
   return "no-results";
 }
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function parseSymbolSelector(symbol) {
   const trimmed = symbol.trim();
   const match = /^([^#]*)(?:#(-?\d+))?$/.exec(trimmed);
@@ -509,45 +507,19 @@ async function openFileBestEffort(lspService, filePath, waitForDiagnostics = fal
   if (!fileContent)
     return;
   try {
-    if (typeof lspService.touchFile === "function") {
-      await lspService.touchFile(filePath, fileContent, {
-        diagnostics: waitForDiagnostics ? "document" : "none",
-        source: "lsp_navigation",
-        clientScope: waitForDiagnostics ? "all" : "primary"
-      });
-    } else {
-      await lspService.openFile(filePath, fileContent);
-    }
+    await lspService.touchFile(filePath, fileContent, {
+      diagnostics: waitForDiagnostics ? "document" : "none",
+      source: "lsp_navigation",
+      clientScope: waitForDiagnostics ? "all" : "primary"
+    });
   } catch {}
 }
 export function createLspNavigationTool(getFlag, mutationDeps) {
   return {
     name: "lsp_navigation",
     label: "LSP Navigate",
-    description: `Navigate code using LSP (Language Server Protocol). LSP is enabled by default; disable with --no-lsp.
-` + `Operations:
-` + `- definition: Jump to where a symbol is defined
-` + `- typeDefinition: Jump to the definition of a symbol's TYPE (e.g. the class/interface of a variable)
-` + `- declaration: Jump to a symbol's declaration (e.g. an extern/forward decl, distinct from its definition)
-` + `- references: Find all usages of a symbol
-` + `- hover: Get type/doc info at a position
-` + `- signatureHelp: Show callable signatures at cursor
-` + `- documentSymbol: List all symbols (functions/classes/vars) in a file
-` + `- findSymbol: Search document symbols in a file by name/detail with optional kind/top-level/exact filters
-` + `- workspaceSymbol: Search symbols across the whole project (best with path context)
-` + `- codeAction: Find available quick fixes/refactors at a range
-` + `- rename: Compute or apply workspace edits for renaming a symbol
-` + `- rename_file: Preview/apply LSP-aware source file rename notifications
-` + `- implementation: Jump to interface implementations
-` + `- prepareCallHierarchy: Get callable item at position (for incoming/outgoing)
-` + `- incomingCalls: Find all functions/methods that CALL this function
-` + `- outgoingCalls: Find all functions/methods CALLED by this function
-` + `- executeCommand: Run a server-advertised command via workspace/executeCommand. HARDENED: allowlisted to commands the server advertised; dry-run by default (reports whether advertised) — set apply:true to actually run. Pass command (+ optional commandArguments).
-` + `- workspaceDiagnostics: List all diagnostics tracked by active LSP clients
-` + `- capabilities: Show cached operation support for active LSP servers
-
-` + "Line and character are 1-based (as shown in editors). For position-based operations, prefer passing symbol when you know the line but not the exact character; character can be omitted or -1 and dm-lens will resolve the symbol column. Use symbol#N for repeated symbols on the same line (1-based occurrence).",
-    promptSnippet: "Find definitions, references, and hover info via LSP",
+    description: 'Navigate source with language-server operations such as definition, references, hover, and rename. Example: use `{operation: "references", path: "src/app.ts", line: 12}`.',
+    promptSnippet: "Navigate definitions and references with LSP",
     renderResult: compactRenderResult(({ details, args, isError, text }) => {
       const op = details?.operation ?? (typeof args.operation === "string" ? args.operation : "lsp");
       if (isError || details?.supported === false) {
@@ -562,55 +534,55 @@ export function createLspNavigationTool(getFlag, mutationDeps) {
     }),
     parameters: Type.Object({
       operation: Type.String({
-        description: "LSP operation to perform. Valid values: " + VALID_OPERATIONS.join(", ")
+        description: "LSP operation to perform. Valid values: definition, typeDefinition, declaration, references, hover, signatureHelp, documentSymbol, findSymbol, workspaceSymbol, codeAction, rename, rename_file, implementation, prepareCallHierarchy, incomingCalls, outgoingCalls, executeCommand, workspaceDiagnostics, capabilities."
       }),
       path: Type.Optional(Type.String({
-        description: "Absolute or relative file path. Required for file-scoped operations; optional for workspaceSymbol/workspaceDiagnostics."
+        description: "Target file path."
       })),
       line: Type.Optional(Type.Number({
-        description: "Line number (1-based). Required for definition/references/hover/implementation"
+        description: "1-based line number."
       })),
       character: Type.Optional(Type.Number({
-        description: "Character offset (1-based). Optional when symbol is provided; use -1 to force symbol-column resolution."
+        description: "1-based character offset."
       })),
       symbol: Type.Optional(Type.String({
-        description: "Symbol name on the target line for automatic character resolution. Use symbol#N to select the Nth occurrence on the line."
+        description: "Symbol for automatic character resolution."
       })),
       endLine: Type.Optional(Type.Number({
-        description: "End line (1-based). Optional; used by codeAction range."
+        description: "1-based range end line."
       })),
       endCharacter: Type.Optional(Type.Number({
-        description: "End character (1-based). Optional; used by codeAction range."
+        description: "1-based range end character."
       })),
       newName: Type.Optional(Type.String({
-        description: "Required for rename operation."
+        description: "New symbol name."
       })),
       newFilePath: Type.Optional(Type.String({
-        description: "Required for rename_file operation."
+        description: "New file path."
       })),
       apply: Type.Optional(Type.Boolean({
-        description: "rename/executeCommand: apply for real. rename defaults to preview; executeCommand defaults to a dry-run that only reports whether the command is advertised — set apply:true to actually run it."
+        description: "Apply a mutation instead of previewing it."
       })),
       command: Type.Optional(Type.String({
-        description: "executeCommand only: the server command id to run. Must be one the server advertised (see the capabilities operation)."
+        description: "Server command identifier."
       })),
       commandArguments: Type.Optional(Type.Array(Type.Unknown(), {
-        description: "executeCommand only: arguments array passed to workspace/executeCommand."
+        description: "Arguments for the server command."
       })),
       query: Type.Optional(Type.String({
-        description: "Symbol name to search. Used by workspaceSymbol and findSymbol."
+        description: "Symbol search query."
       })),
       kinds: Type.Optional(Type.Array(Type.String(), {
-        description: "findSymbol only: restrict matches to symbol kind labels such as function, class, method, variable, interface."
+        description: "Symbol-kind filters."
       })),
       exactMatch: Type.Optional(Type.Boolean({
-        description: "findSymbol only: match whole symbol names/details exactly instead of substring matching."
+        description: "Require an exact symbol match."
       })),
       topLevelOnly: Type.Optional(Type.Boolean({
-        description: "findSymbol only: do not search nested child symbols."
+        description: "Exclude nested symbols."
       })),
       maxResults: Type.Optional(Type.Number({
-        description: "findSymbol only: maximum matches to return. Default 20."
+        description: "Maximum symbol matches."
       })),
       callHierarchyItem: Type.Optional(Type.Object({
         name: Type.String(),
@@ -636,9 +608,7 @@ export function createLspNavigationTool(getFlag, mutationDeps) {
             character: Type.Number()
           })
         })
-      }, {
-        description: "Call hierarchy item. Required for incomingCalls/outgoingCalls"
-      }))
+      }, {}))
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const startedAt = Date.now();

package/extensions/dm-lens/tools/lsp-structured-output.js

@@ -5,7 +5,7 @@ function asRecord(value) {
 function finiteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
-export function lspStatusFromFailureKind(failureKind) {
+function lspStatusFromFailureKind(failureKind) {
   if (failureKind === "success" || failureKind === "fallback_success") {
     return "success";
   }
@@ -131,7 +131,7 @@ function collectCallHierarchyLocationSummaries(result, operation) {
   }
   return out;
 }
-export function collectLspToolLocationsForOperation(operation, result, filePath) {
+function collectLspToolLocationsForOperation(operation, result, filePath) {
   if ([
     "definition",
     "typeDefinition",
@@ -195,7 +195,7 @@ function parseBalancedJsonPrefix(text) {
   }
   return;
 }
-export function parseLspNavigationTextPayload(text) {
+function parseLspNavigationTextPayload(text) {
   const notes = [];
   const hints = [];
   const errors = [];

package/extensions/dm-lens/tools/module-report.js

@@ -18,8 +18,8 @@ export function createModuleReportTool(getProjectRoot) {
   return {
     name: "module_report",
     label: "Module Report",
-    description: "Structured, navigable overview of a source module — a token-efficient substitute for reading the whole file. Returns each symbol's name/kind/signature/line-range (plus a first-line `doc` summary when a doc comment is attached), important inline callbacks/closures/lambdas with stable handles, plus who-uses-this, risk flags, and ranked recommendedReads. To read a symbol's body: call read/read_symbol with offset=startLine, limit=endLine-startLine+1 on THIS report's `path` — those aren't repeated per symbol. Prefer this before a full read; then use read_symbol (or read) for the exact body you need.\n" + "Single mode: language-uniform tree-sitter outline + review-graph who-uses-this + inline executable extraction; degrades to outline-only when no cached graph is available. `semantic.source` reports whether graph data was used.\n" + 'Pass `blastRadius: true` to also get the cross-file blast radius — the transitive dependents of this module aggregated to ranked file `read` args ("if you change this, verify these files"). Read-only over the cached graph; omitted on a cold cache. Supersedes the standalone impact query.\n' + "Pass `callGraph: true` to include bounded derived callers/callees from the cached FunctionCallGraph; unavailable cache state is explicit and never reported as zero calls.\n" + '`view: "compact"` returns a line-oriented text rendering (one line per symbol/callback, cheapest option) instead of JSON — same data, roughly a quarter of the token cost; use it for a quick skim. Default view returns JSON. An outline shows shape, not bodies — it does NOT count as having read a symbol\'s body for editing; use read_symbol for that.',
-    promptSnippet: "Navigable file outline — a cheap substitute for reading a whole file",
+    description: "Return a navigable source-module outline with symbols, references, and read handles. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use module_report on `src/app.ts` before read_symbol.",
+    promptSnippet: "Outline a source module before reading a body",
     renderResult: compactRenderResult(({ details, args, isError }) => {
       const base = baseName(args.path) || "module";
       if (isError || details?.available === false) {
@@ -36,7 +36,7 @@ export function createModuleReportTool(getProjectRoot) {
     }),
     parameters: Type.Object({
       path: Type.String({
-        description: "Absolute or workspace-relative path to the source file."
+        description: "Source file, e.g. `src/app.ts`."
       }),
       maxRefsPerSymbol: Type.Optional(Type.Number({
         description: "Cap on who-uses-this entries per symbol (default 10)."
@@ -131,7 +131,7 @@ export function createReadSymbolTool(getProjectRoot, recordSymbolRead) {
   return {
     name: "read_symbol",
     label: "Read Symbol",
-    description: "Return the verbatim source of a single named symbol or module_report callback handle in a file — a targeted, cheap alternative to reading the whole file. Pair with module_report: module_report finds the symbol/callback handle, read_symbol shows its body. Unlike an outline, this delivers the actual lines, so it counts as having read that symbol for the read-before-edit guard. The returned body includes an attached doc comment when one exists. Accepts a dotted `Class.method` name to resolve a member directly, falling back to a plain top-level lookup when the qualifier doesn't resolve. A miss embeds the ~3 nearest symbol names in the file so a typo self-corrects without a second call. When multiple same-file symbols share a name (overloads, a type and a value sharing a name), the first is returned with an `ambiguous` note; pass `kind` to pick a specific one.",
+    description: "Return one symbol's verbatim source. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use read_symbol after module_report identifies `parseConfig`.",
     promptSnippet: "Read one symbol's body instead of the whole file",
     renderResult: compactRenderResult(({ details, args, isError, lineCount }) => {
       const base = baseName(args.path);
@@ -220,7 +220,7 @@ export function createReadEnclosingTool(getProjectRoot, recordSymbolRead) {
   return {
     name: "read_enclosing",
     label: "Read Enclosing",
-    description: "Return the verbatim source for the smallest useful symbol/callback enclosing a line in a file. Use after ast_grep_search, diagnostics, or LSP locations when you need exact body text without reading the whole file. Uses tree-sitter only — no LSP or graph build — and records read-guard coverage for the returned range.",
+    description: "Return the smallest symbol or callback enclosing a line. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use read_enclosing after a diagnostic points to line 42.",
     promptSnippet: "Read the enclosing symbol or callback body for a line",
     renderResult: compactRenderResult(({ details, args, isError }) => {
       const base = baseName(args.path);

package/extensions/dm-lens/tools/project-report.js

@@ -3,7 +3,10 @@ import {
   projectReport,
   renderCompactProjectReport
 } from "../clients/lens-engine.js";
-import { compactRenderResult } from "./render-compact.js";
+import {
+  compactRenderResult,
+  renderToolText
+} from "./render-compact.js";
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -11,8 +14,8 @@ export function createProjectReportTool(getProjectRoot) {
   return {
     name: "project_report",
     label: "Project Report",
-    description: "Project-level orientation from the review graph — 'orient me in this project' before drilling into any one file. First step of a wider discovery funnel: project_report orients, module_report explains a file, read_symbol reads a body. Six capped, ranked sections: a trust header (graph freshness, file coverage, edge-resolution-quality mix), hubs (top fan-in files — the repo's contract surface), entry points (near-zero fan-in / high fan-out files — activation/CLI/mains), a directory-level subsystem map (import cycles + layering violations, e.g. a forbidden clients/ -> tools/ edge), risk hotspots (fan-in × max per-symbol cyclomatic complexity), and suspected dead weight (zero-importer files, shipped with a low-confidence disclaimer — dynamic imports/runtime registration/test-only reachability all produce false positives). Every file line carries a `suggestedNext` module_report call. No per-symbol detail and no prose summary — structural facts only. Read-only over the cached graph: returns `available: false` with a retry hint on a cold cache and kicks off a background build (never blocks this call).\n" + '`view: "compact"` returns a line-oriented text rendering instead of JSON (cheapest option); default view returns JSON. Pass `focus` to re-rank every section toward a task hint (does not expand scope).',
-    promptSnippet: "Project-level orientation from the review graph",
+    description: "Orient in a project from its review graph, with ranked hubs and entry points. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use project_report before module_report when the target file is unknown.",
+    promptSnippet: "Orient in a project before choosing a file",
     renderResult: compactRenderResult(({ details, isError }) => {
       if (isError || details?.available === false) {
         return `project_report — unavailable${details?.hint ? `: ${details.hint}` : ""}`;
@@ -47,24 +50,14 @@ export function createProjectReportTool(getProjectRoot) {
         });
       } catch (err) {
         return {
-          content: [
-            {
-              type: "text",
-              text: `Project report failed: ${errorMessage(err)}`
-            }
-          ],
+          ...renderToolText(`Project report failed: ${errorMessage(err)}`),
           isError: true,
           details: { available: false }
         };
       }
       if (!report.available) {
         return {
-          content: [
-            {
-              type: "text",
-              text: report.hint ?? "No review graph cached for this workspace yet."
-            }
-          ],
+          ...renderToolText(report.hint ?? "No review graph cached for this workspace yet.", report),
           isError: true,
           details: { available: false, hint: report.hint }
         };
@@ -72,6 +65,7 @@ export function createProjectReportTool(getProjectRoot) {
       const text = params.view === "compact" ? renderCompactProjectReport(report) : JSON.stringify(report);
       return {
         content: [{ type: "text", text }],
+        isError: false,
         details: {
           available: true,
           hubs: report.hubs?.length ?? 0,

package/extensions/dm-lens/tools/render-compact.js

@@ -1,4 +1,223 @@
 import { Text } from "../clients/deps/dm-tui-compat.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { recordDegradationOnce } from "../clients/degradation-ledger.js";
+import { getGlobalDmLensLogDir } from "../clients/probe-home-state.js";
+export const MAX_RESULT_BYTES = 40 * 1024;
+export const COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES = 8 * 1024 * 1024;
+const FOOTER_MAX_DIGITS = String(Number.MAX_SAFE_INTEGER).length;
+const FOOTER_DIAG_LINE_MAX_CHARS = 200;
+const FOOTER_DIAG_SECTION_MAX_BYTES = 1024;
+export const RESULT_FOOTER_RESERVE_BYTES = Buffer.byteLength(`
+
+result error
+${"x".repeat(FOOTER_DIAG_SECTION_MAX_BYTES)}
+usage tokens=${"9".repeat(FOOTER_MAX_DIGITS)} elapsed-ms=${"9".repeat(FOOTER_MAX_DIGITS)} bytes=${"9".repeat(FOOTER_MAX_DIGITS)} truncated=false`, "utf8");
+export const RESULT_PAYLOAD_BUDGET_BYTES = MAX_RESULT_BYTES - RESULT_FOOTER_RESERVE_BYTES;
+function renderHeadTail(text, maxBytes, markerFor) {
+  const render = (kept) => {
+    const head = Math.floor(kept / 2);
+    const tail = kept - head;
+    return `${text.slice(0, head)}${markerFor(head, tail)}${text.slice(text.length - tail)}`;
+  };
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const kept = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(render(kept), "utf8") <= maxBytes)
+      low = kept;
+    else
+      high = kept - 1;
+  }
+  return { text: render(low), keptCharacters: low };
+}
+export function boundToolText(text, maxBytes = MAX_RESULT_BYTES) {
+  const totalBytes = Buffer.byteLength(text, "utf8");
+  if (totalBytes <= maxBytes) {
+    return { text, truncated: false, omittedCharacters: 0 };
+  }
+  const fullOutputPath = path.join(getGlobalDmLensLogDir(), `tool-result-${Date.now()}-${randomUUID()}.log`);
+  fs.mkdirSync(path.dirname(fullOutputPath), { recursive: true });
+  if (totalBytes > COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES) {
+    const omittedBytes = totalBytes - COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES;
+    recordDegradationOnce({
+      kind: "mcp-complete-result-budget-exceeded",
+      subject: "complete-result",
+      reason: `${totalBytes} input bytes exceeded ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}-byte budget`,
+      metadata: {
+        totalBytes,
+        budgetBytes: COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES
+      }
+    });
+    const logText = renderHeadTail(text, COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES, (head, tail) => {
+      const keptBytes = Buffer.byteLength(`${text.slice(0, head)}${text.slice(text.length - tail)}`, "utf8");
+      return `
+
+[incomplete: ${totalBytes - keptBytes} bytes omitted, budget ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}]
+
+[Full output: ${fullOutputPath}]
+
+`;
+    });
+    fs.writeFileSync(fullOutputPath, logText.text, "utf8");
+    const output = renderHeadTail(logText.text, maxBytes, () => `
+
+[incomplete: ${omittedBytes} bytes omitted, budget ${COMPLETE_MCP_RESULT_INPUT_BUDGET_BYTES}]
+
+[Full output: ${fullOutputPath}]
+
+`);
+    return {
+      text: output.text,
+      truncated: true,
+      omittedCharacters: text.length - logText.keptCharacters,
+      fullOutputPath
+    };
+  }
+  fs.writeFileSync(fullOutputPath, text, "utf8");
+  const output = renderHeadTail(text, maxBytes, (head, tail) => `
+
+[${text.length - head - tail} characters omitted. Full output: ${fullOutputPath}]
+
+`);
+  return {
+    text: output.text,
+    truncated: true,
+    omittedCharacters: text.length - output.keptCharacters,
+    fullOutputPath
+  };
+}
+const CONTRACT_FOOTER_TAIL_RE = /(?:^|\n)result (?:ok|error)\n(?:diag severity=[^\n]*\n)*usage tokens=\d+ elapsed-ms=\d+ bytes=(\d+) truncated=(true|false)$/;
+export function renderToolResultContract(result, delivery) {
+  const normalized = {
+    ...result,
+    isError: result.isError === true
+  };
+  const content = result.content ?? [];
+  const textBlocks = content.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text);
+  if (textBlocks.length === 0)
+    return normalized;
+  const text = textBlocks.join(`
+`);
+  if (CONTRACT_FOOTER_TAIL_RE.test(text))
+    return normalized;
+  const details = normalized.details;
+  const diagLines = [];
+  let diagSectionBytes = 0;
+  if (Array.isArray(details?.diagnostics)) {
+    for (const value of details.diagnostics) {
+      if (!value || typeof value !== "object")
+        continue;
+      const severity = value.severity;
+      if (typeof severity !== "string")
+        continue;
+      const line = `diag severity=${severity.slice(0, FOOTER_DIAG_LINE_MAX_CHARS)}`;
+      const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+      if (diagSectionBytes + lineBytes > FOOTER_DIAG_SECTION_MAX_BYTES)
+        break;
+      diagLines.push(line);
+      diagSectionBytes += lineBytes;
+    }
+  }
+  const tokens = normalized.usage?.tokens ?? Math.ceil(Buffer.byteLength(text, "utf8") / 4);
+  const elapsedMs = normalized.usage?.elapsedMs ?? 0;
+  const deliveredBytes = delivery?.bytes ?? Buffer.byteLength(text, "utf8");
+  const truncated = delivery?.truncated === true;
+  const contractLines = [
+    `result ${normalized.isError ? "error" : "ok"}`,
+    ...diagLines,
+    `usage tokens=${tokens} elapsed-ms=${elapsedMs} bytes=${deliveredBytes} truncated=${truncated ? "true" : "false"}`
+  ];
+  let lastTextIndex = -1;
+  for (let index = content.length - 1;index >= 0; index--) {
+    const block = content[index];
+    if (block?.type === "text" && typeof block.text === "string") {
+      lastTextIndex = index;
+      break;
+    }
+  }
+  if (lastTextIndex < 0)
+    return normalized;
+  return {
+    ...normalized,
+    content: content.map((block, index) => index === lastTextIndex && block.type === "text" ? { ...block, text: `${block.text}
+
+${contractLines.join(`
+`)}` } : block)
+  };
+}
+export function boundResultPayload(result) {
+  if (!result.content) {
+    return { result, deliveredBytes: 0, truncated: false };
+  }
+  const joined = fullTextOf(result);
+  const bound = boundToolText(joined, RESULT_PAYLOAD_BUDGET_BYTES);
+  const firstText = result.content.findIndex((block) => block.type === "text" && typeof block.text === "string");
+  let retainedText = false;
+  const content = result.content.filter((block, index) => block.type !== "text" || typeof block.text !== "string" || index === firstText).map((block) => {
+    if (block.type === "text" && typeof block.text === "string" && !retainedText) {
+      retainedText = true;
+      return { ...block, text: bound.text };
+    }
+    return block;
+  });
+  const deliveredBytes = Buffer.byteLength(fullTextOf({ content }), "utf8");
+  return {
+    result: { ...result, content },
+    deliveredBytes,
+    truncated: bound.truncated
+  };
+}
+export function renderToolText(summary, structured, compact = false) {
+  const rawText = structured === undefined ? summary : `${summary}
+
+\`\`\`json
+${JSON.stringify(structured, compact ? undefined : null, compact ? undefined : 2)}
+\`\`\``;
+  return {
+    content: [{ type: "text", text: rawText }],
+    details: structured
+  };
+}
+export function stripResultDetails(result) {
+  const { details: _details, ...rest } = result;
+  return rest;
+}
+export function finalizeToolResultWithDelivery(result) {
+  const normalized = { ...result, isError: result.isError === true };
+  const existingText = fullTextOf(normalized);
+  const existingFooter = CONTRACT_FOOTER_TAIL_RE.exec(existingText);
+  if (existingFooter && Buffer.byteLength(existingText, "utf8") <= MAX_RESULT_BYTES) {
+    return {
+      result: normalized,
+      deliveredBytes: Number(existingFooter[1]),
+      truncated: existingFooter[2] === "true"
+    };
+  }
+  const bound = boundResultPayload(normalized);
+  const text = fullTextOf(bound.result);
+  const keptFooter = CONTRACT_FOOTER_TAIL_RE.exec(text);
+  if (keptFooter) {
+    return {
+      result: bound.result,
+      deliveredBytes: Number(keptFooter[1]),
+      truncated: keptFooter[2] === "true"
+    };
+  }
+  const stamped = renderToolResultContract(bound.result, {
+    bytes: bound.deliveredBytes,
+    truncated: bound.truncated
+  });
+  return {
+    result: stamped,
+    deliveredBytes: bound.deliveredBytes,
+    truncated: bound.truncated
+  };
+}
+export function finalizeToolResult(result) {
+  return finalizeToolResultWithDelivery(result).result;
+}
 const DM_LENS_BLUE_FG = "\x1B[1m\x1B[38;2;96;165;250m";
 const RESET_FG = "\x1B[39m\x1B[22m";
 export function fullTextOf(result) {
@@ -30,7 +249,7 @@ export function selectCompactText(result, args, expanded, summarize) {
   }
   return { text: summary, style: result.isError ? "error" : "brand" };
 }
-export function paintCompact(style, text, theme) {
+function paintCompact(style, text, theme) {
   if (style === "brand") {
     return `${DM_LENS_BLUE_FG}${text}${RESET_FG}`;
   }

package/extensions/dm-lens/tools/symbol-search.js

@@ -3,7 +3,7 @@ import { Type } from "../clients/deps/typebox.js";
 import {
   symbolSearch
 } from "../clients/lens-engine.js";
-import { baseName, compactRenderResult } from "./render-compact.js";
+import { compactRenderResult } from "./render-compact.js";
 function suggestedNext(relPath) {
   return { tool: "module_report", path: relPath };
 }
@@ -11,8 +11,8 @@ export function createSymbolSearchTool(getProjectRoot) {
   return {
     name: "symbol_search",
     label: "Symbol Search",
-    description: "Ranked identifier search over the persisted word index (BM25 + priors demoting tests/vendor/docs) — answers 'which files are most relevant to <query>' by identifier. First step of the discovery funnel: symbol_search finds candidates, module_report explains the file, read_symbol reads the body. Complements grep (raw substrings) and lsp_navigation (exact references). Each hit's startLine/endLine mark its best-matching line (offset=startLine, limit=endLine-startLine+1 for a one-line peek); use module_report on `file` for the real outline. Returns available:false with a retry hint if the index isn't built yet — it self-builds in the background (never blocks this call).",
-    promptSnippet: "Ranked identifier search — find relevant files by name/usage",
+    description: "Find relevant files by ranked identifier search. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: search `authenticate user` before module_report.",
+    promptSnippet: "Find files by identifier",
     renderResult: compactRenderResult(({ details, isError }) => {
       if (isError || details?.available === false) {
         return `symbol_search "${details?.query ?? ""}" — unavailable${details?.hint ? `: ${details.hint}` : ""}`;
@@ -133,5 +133,3 @@ ${JSON.stringify(payload)}`
     }
   };
 }
-
-export { baseName };