@herbertgao/pi-extensions 2026.9.2 → 2026.9.4

package/node_modules/pi-lens/dist/tools/lsp-diagnostics.js

@@ -6,7 +6,6 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { Type } from "../clients/deps/typebox.js";
 import { getProjectIgnoreMatcher, isExcludedDirName, } from "../clients/file-utils.js";
 import { getLSPService, groupFilesByPrimaryServer, runPerServerGroups, } from "../clients/lsp/index.js";
 import { buildScopeKey, createWorkspaceDiagnosticsCacheContext, } from "../clients/lsp/workspace-diagnostics-cache.js";
@@ -20,23 +19,26 @@ import { attemptTsserverSyncDiagnostics } from "../clients/lsp/tsserver-sync.js"
 import { convertLspDiagnostics } from "../clients/dispatch/utils/lsp-diagnostics.js";
 import { demoteInferredProjectDiagnostics } from "../clients/lsp/inferred-project.js";
 import { isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.js";
-import { baseName, compactRenderResult } from "./render-compact.js";
-import { makeProgressReporter, scanningSummaryLine } from "./scan-progress.js";
+import { makeProgressReporter } from "./scan-progress.js";
 import { isWarmAttached, tryWarmAttachedDiagnostics, } from "../clients/warm-attach.js";
 import { extensionsForLanguage, SCAN_LANGUAGE_PRIORITY, } from "../clients/language-registry.js";
 const MAX_FILES = 100;
-const MAX_BATCH_FILES = 100;
+export const MAX_BATCH_FILES = 100;
 const MAX_DIAGNOSTICS = 200;
 const DEFAULT_BATCH_CONCURRENCY = 8;
 const MAX_BATCH_CONCURRENCY = 16;
 const DEFAULT_BATCH_FILE_DEADLINE_MS = 15_000;
 // LSP severities: 1=Error, 2=Warning, 3=Information, 4=Hint
-const SEVERITY_NAMES = {
+export const SEVERITY_NAMES = {
     1: "error",
     2: "warning",
     3: "information",
     4: "hint",
 };
+export const LSP_SEVERITY_FILTERS = [
+    ...Object.values(SEVERITY_NAMES),
+    "all",
+];
 function batchFileDeadlineMs() {
     const raw = Number(process.env.PI_LENS_LSP_BATCH_FILE_MS);
     return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_BATCH_FILE_DEADLINE_MS;
@@ -216,102 +218,8 @@ nextWriteIndex,
 // injecting "Unresolved from this turn" for three more turns after answering
 // "confirmed clean" for the same file. index.ts injects
 // `runtime.retireInlineBlockerOnConfirmedClean`. Optional/undefined in tests.
-onConfirmedNoBlockers) {
+onConfirmedNoBlockers, getService = getLSPService) {
     return {
-        name: "lsp_diagnostics",
-        label: "LSP Diagnostics",
-        description: "Get errors, warnings, and hints from language servers for a file or directory. " +
-            "Use BEFORE running builds to proactively check for issues. " +
-            "Works on directories by auto-detecting file extensions and scanning all matching files.",
-        promptSnippet: "Get LSP diagnostics for a file or directory (use before builds)",
-        renderResult: compactRenderResult(({ details, args, isError, text }) => {
-            // Streaming progress partials render the live bar (see scanningSummaryLine).
-            const scanning = scanningSummaryLine(details, text);
-            if (scanning)
-                return scanning;
-            if (isError) {
-                return `lsp_diagnostics — ${text.split("\n")[0] ?? "error"}`;
-            }
-            const count = details?.totalDiagnostics ?? details?.diagnostics?.length ?? 0;
-            const target = baseName(details?.filePath ?? args.path) || "workspace";
-            const files = details?.filesChecked ?? details?.filesScanned;
-            const scope = typeof files === "number" && files > 1
-                ? ` across ${files} files`
-                : target
-                    ? ` ${target}`
-                    : "";
-            const noun = count === 1 ? "diagnostic" : "diagnostics";
-            // #533: a batch/directory result with any unconfirmed files must NEVER
-            // compact-render as a bare "N diagnostics" — that erases the fact some
-            // files' clean status was never actually confirmed by the server.
-            const unconfirmedFiles = details?.unconfirmedFiles ?? 0;
-            const navigationOnlyFiles = details?.navigationOnlyFiles ?? 0;
-            if (navigationOnlyFiles > 0) {
-                return `lsp_diagnostics${scope} — ${count} ${noun} · ${details?.cleanFiles ?? 0} clean · ${navigationOnlyFiles} navigation-only`;
-            }
-            if (unconfirmedFiles > 0) {
-                const cleanFiles = details?.cleanFiles ?? 0;
-                const timedOutFiles = details?.timedOutFiles ?? 0;
-                const suffix = timedOutFiles > 0 ? ` (${timedOutFiles} timed out)` : "";
-                return `lsp_diagnostics${scope} — ${count} ${noun} · ${cleanFiles} clean · ${unconfirmedFiles} unconfirmed${suffix}`;
-            }
-            const outcomeCounts = details?.outcomeCounts;
-            const notConfirmed = outcomeCounts
-                ? (outcomeCounts.inconclusive ?? 0) +
-                    (outcomeCounts.unavailable ?? 0) +
-                    (outcomeCounts.unsupported ?? 0) +
-                    (outcomeCounts.failed ?? 0)
-                : 0;
-            if (notConfirmed > 0) {
-                return `lsp_diagnostics${scope} — ${count} ${noun} · ${notConfirmed} checks not confirmed`;
-            }
-            if ((details?.incompleteFiles ?? 0) > 0) {
-                return `lsp_diagnostics${scope} — incomplete (${details?.incompleteFiles} files not confirmed)`;
-            }
-            // Single-file mode: 0 diagnostics from an unconfirmed result — either a
-            // silent-on-clean server or (#570) a timed-out check — is not a clean
-            // render either.
-            if (count === 0 && details?.unconfirmed) {
-                return details?.timedOut
-                    ? `lsp_diagnostics${scope} — timed out (result may be incomplete)`
-                    : `lsp_diagnostics${scope} — unconfirmed (server cannot confirm clean)`;
-            }
-            return `lsp_diagnostics${scope} — ${count} ${noun}`;
-        }),
-        parameters: Type.Object({
-            path: Type.Optional(Type.String({
-                description: "File or directory path to check. For directories, all matching source files are scanned.",
-            })),
-            paths: Type.Optional(Type.Array(Type.String(), {
-                minItems: 1,
-                maxItems: MAX_BATCH_FILES,
-                description: "Explicit files to check as a bounded-concurrency batch. When provided, path is ignored.",
-            })),
-            severity: Type.Optional(Type.String({
-                enum: ["error", "warning", "information", "hint", "all"],
-                description: "Filter by severity level (default: all)",
-            })),
-            concurrency: Type.Optional(Type.Number({
-                description: "Batch/directory concurrency, in distinct LSP server groups run in parallel " +
-                    "(default 8, max 16) — not individual files. Files sharing one server " +
-                    "(e.g. a same-language batch) are always processed one at a time against " +
-                    "that server regardless of this value; this caps how many DIFFERENT " +
-                    "servers run concurrently.",
-            })),
-            waitMs: Type.Optional(Type.Number({
-                description: "Optional per-file LSP wait budget for batch diagnostics. Uses server defaults when omitted.",
-            })),
-            serverScope: Type.Optional(Type.String({
-                enum: ["primary", "all"],
-                description: "'primary' (fast, low-noise): only the file's actual language " +
-                    "server (e.g. typescript) — for 'does this have real type " +
-                    "errors'. 'all' (default): also touches cross-cutting auxiliary " +
-                    "scanners (ast-grep, opengrep, zizmor, typos, marksman) attached " +
-                    "to this file, including findings for files not yet dispatched " +
-                    "this session. Primary confirmation is always reported " +
-                    "separately from auxiliary findings regardless of this setting.",
-            })),
-        }),
         async execute(_toolCallId, params, _signal, onUpdate, ctx) {
             // Escape aborts the turn via ctx.signal; honor both it and the tool-call
             // signal so a batch/directory scan cancels rather than grinding on.
@@ -327,7 +235,7 @@ onConfirmedNoBlockers) {
                 ? Math.floor(typedParams.waitMs)
                 : undefined;
             const serverScope = typedParams.serverScope === "primary" ? "primary" : "all";
-            const lspService = getLSPService();
+            const lspService = getService();
             if (!lspService) {
                 return {
                     content: [
@@ -450,7 +358,7 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
             const attached = await tryWarmAttachedDiagnostics(absPath, content, attachedBudgetMs, "sweep");
             if (attached?.available) {
                 const scopedDiagnostics = serverScope === "primary"
-                    ? attached.response.diagnostics.filter((item) => item.source === primaryServerId(absPath))
+                    ? attached.response.diagnostics.filter((item) => item.serverId === primaryServerId(absPath))
                     : attached.response.diagnostics;
                 const filtered = applyAuxiliarySuppressions(scopedDiagnostics, content, { fileRole: detectFileRole(absPath, content) });
                 return {
@@ -546,6 +454,7 @@ function diagnosticsToFileDiags(file, diagnostics) {
         severity: d.severity,
         message: d.message,
         source: d.source,
+        serverId: d.serverId,
         code: d.code,
     }));
 }
@@ -704,7 +613,9 @@ observedAt) {
             scanOrigin: "lsp_diagnostics",
         });
         const retagged = retagAuxiliaryDiagnostics(diagnostics, rawDiags, content ?? "", { cwd, fileRole: detectFileRole(file, content) });
-        reconcileScanDiagnostics(file, retagged, true, writeIndex, observedAt);
+        const reconciled = reconcileScanDiagnostics(file, retagged, true, writeIndex, observedAt);
+        if (!reconciled)
+            return { confirmed: false, blocking: true };
         // #1561: the blocking tally comes from the SAME `isBlocking` predicate the
         // footer counts with — no second severity rule for the blocker-retire
         // decision to drift away from.
@@ -965,8 +876,8 @@ onConfirmedNoBlockers) {
         });
     }
     const primaryId = primaryServerId(absPath);
-    const primaryDiags = limited.filter((d) => d.source === primaryId);
-    const auxiliaryDiags = limited.filter((d) => d.source !== primaryId);
+    const primaryDiags = limited.filter((d) => d.serverId === primaryId);
+    const auxiliaryDiags = limited.filter((d) => d.serverId !== primaryId);
     // Primary confirmation is always its own line, independent of how many
     // auxiliary findings exist — a wall of ast-grep/opengrep noise must never
     // bury whether the actual language server confirmed the file clean.
@@ -999,7 +910,7 @@ onConfirmedNoBlockers) {
     // this result does NOT speak for, so "no auxiliary findings" can never be read
     // as "the security scanners found nothing".
     const coverageLine = unconfirmedServerIds.length > 0
-        ? `Auxiliary coverage INCOMPLETE — ${[...unconfirmedServerIds].join(", ")} did not answer within the wait budget, so ${unconfirmedServerIds.length === 1 ? "its findings are" : "their findings are"} NOT included here. This is not a clean bill of health for ${unconfirmedServerIds.length === 1 ? "that scanner" : "those scanners"}; re-check after the next edit, or use waitMs to wait longer.`
+        ? `Auxiliary coverage INCOMPLETE — ${[...unconfirmedServerIds].join(", ")} did not answer within the wait budget, so ${unconfirmedServerIds.length === 1 ? "its findings are" : "their findings are"} NOT included here. This is not a clean bill of health for ${unconfirmedServerIds.length === 1 ? "that scanner" : "those scanners"}; re-check after the next edit. waitMs can extend an ordinary wait, but it cannot override a session-demoted scanner.`
         : undefined;
     let text;
     if (total === 0) {
@@ -1228,8 +1139,8 @@ async function collectBatchDiagnostics(files, severity, lspService, options) {
     // `clean`/`unconfirmed` above already reflect ONLY the primary server's
     // confirmation; this split does the same job for the listed diagnostics.
     const primaryIdByFile = new Map(results.map((r) => [r.file, r.primaryServerId]));
-    const primaryDisplay = display.filter((d) => d.source === primaryIdByFile.get(d.file));
-    const auxiliaryDisplay = display.filter((d) => d.source !== primaryIdByFile.get(d.file));
+    const primaryDisplay = display.filter((d) => d.serverId === primaryIdByFile.get(d.file));
+    const auxiliaryDisplay = display.filter((d) => d.serverId !== primaryIdByFile.get(d.file));
     return {
         results,
         fileErrors,
@@ -1332,8 +1243,8 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
                 file: result.file,
                 outcome: result.outcome,
                 reason: result.inconclusiveReason ?? result.error ?? result.unavailable,
-                primaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.source === result.primaryServerId).length,
-                auxiliaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.source !== result.primaryServerId).length,
+                primaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.serverId === result.primaryServerId).length,
+                auxiliaryDiagnosticsCount: result.diagnostics.filter((diagnostic) => diagnostic.serverId !== result.primaryServerId).length,
             })),
             outcomeCounts,
             incompleteFiles: incompleteFiles > 0 ? incompleteFiles : undefined,

package/node_modules/pi-lens/dist/tools/lsp-navigation.js

@@ -557,29 +557,8 @@ 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.\n" +
-            "Operations:\n" +
-            "- definition: Jump to where a symbol is defined\n" +
-            "- typeDefinition: Jump to the definition of a symbol's TYPE (e.g. the class/interface of a variable)\n" +
-            "- declaration: Jump to a symbol's declaration (e.g. an extern/forward decl, distinct from its definition)\n" +
-            "- references: Find all usages of a symbol\n" +
-            "- hover: Get type/doc info at a position\n" +
-            "- signatureHelp: Show callable signatures at cursor\n" +
-            "- documentSymbol: List all symbols (functions/classes/vars) in a file\n" +
-            "- findSymbol: Search document symbols in a file by name/detail with optional kind/top-level/exact filters\n" +
-            "- workspaceSymbol: Search symbols across the whole project (best with path context)\n" +
-            "- codeAction: Find available quick fixes/refactors at a range\n" +
-            "- rename: Compute or apply workspace edits for renaming a symbol\n" +
-            "- rename_file: Preview/apply LSP-aware source file rename notifications\n" +
-            "- implementation: Jump to interface implementations\n" +
-            "- prepareCallHierarchy: Get callable item at position (for incoming/outgoing)\n" +
-            "- incomingCalls: Find all functions/methods that CALL this function\n" +
-            "- outgoingCalls: Find all functions/methods CALLED by this function\n" +
-            "- 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).\n" +
-            "- workspaceDiagnostics: List all diagnostics tracked by active LSP clients\n" +
-            "- capabilities: Show cached operation support for active LSP servers\n\n" +
-            "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 pi-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");
@@ -594,56 +573,55 @@ 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(),
@@ -669,9 +647,7 @@ 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/node_modules/pi-lens/dist/tools/module-report.js

@@ -26,12 +26,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) {
@@ -48,7 +44,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).",
@@ -157,7 +153,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);
@@ -259,7 +255,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/node_modules/pi-lens/dist/tools/project-report.js

@@ -9,7 +9,7 @@
  */
 import { Type } from "../clients/deps/typebox.js";
 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);
 }
@@ -17,9 +17,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}` : ""}`;
@@ -28,7 +27,9 @@ export function createProjectReportTool(getProjectRoot) {
                 `${details?.hubs ?? 0} hub(s)`,
                 `${details?.entryPoints ?? 0} entry point(s)`,
             ];
-            const view = details?.view && details.view !== "default" ? ` [${details.view}]` : "";
+            const view = details?.view && details.view !== "default"
+                ? ` [${details.view}]`
+                : "";
             return `project_report  ${parts.join(" · ")}${view}`;
         }),
         parameters: Type.Object({
@@ -55,24 +56,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 },
                 };
@@ -82,6 +73,7 @@ export function createProjectReportTool(getProjectRoot) {
                 : JSON.stringify(report);
             return {
                 content: [{ type: "text", text }],
+                isError: false,
                 details: {
                     available: true,
                     hubs: report.hubs?.length ?? 0,