@mrclrchtr/supi-code-intelligence 0.2.0 → 1.1.3

package/README.md

@@ -1,212 +1,56 @@
 # @mrclrchtr/supi-code-intelligence
 
-SuPi Code Intelligence extension — the main agent-facing code understanding tool for [pi](https://github.com/earendil-works/pi).
+Project understanding for PI — your agent knows your codebase before you ask.
 
-Registers the `code_intel` tool with seven high-level actions and injects structural project context into the agent's first turn.
+The first thing an agent does in a new project is read files to figure out what's there. Code Intelligence skips that — it auto-injects a compact project map on turn one, so the agent is already oriented.
 
-## Injection Points
+Beyond the overview, it gives the agent high-level analysis: architecture briefs, impact assessment, call tracing, and smart search that knows when to use LSP vs. tree-sitter vs. text search.
 
-The extension hooks into pi's lifecycle at six points:
+## What you get
 
-| # | Injection Point | What It Does |
-|---|---|---|
-| 1 | `package.json` → `pi.extensions` | Manifest entry that tells pi to load the extension at startup |
-| 2 | `pi.registerTool({ name: "code_intel", ... })` | Makes the `code_intel` tool callable from agent turns |
-| 3 | `promptGuidelines` (7 guidelines) | Flattened into the system prompt's `Guidelines:` section — teaches the agent *when* to use each action |
-| 4 | `promptSnippet` (1 line) | Injected near the tool definition in context — short reminder to use `code_intel` over broad file reads |
-| 5 | `pi.on("session_start", ...)` | Resets injection dedup state and scans the active branch to avoid re-injecting on reload/resume |
-| 6 | `pi.on("before_agent_start", ...)` | On the first agent turn, builds an architecture model and injects a compact Markdown overview as a custom message (`customType: "code-intelligence-overview"`, `display: false`) — the agent sees it in conversation context without UI clutter |
+### Instant orientation
 
-### First-Turn Overview Flow
+Every session starts with a project map in the agent's context: what packages exist, how they depend on each other, which files matter. The agent walks in knowing your codebase instead of discovering it file by file.
 
-1. `session_start` fires → resets `hasInjectedOverview`, scans branch for existing `code-intelligence-overview` custom message
-2. First `before_agent_start` fires → calls `buildArchitectureModel(ctx.cwd)` to parse the project
-3. If modules are found, `generateOverview(model)` produces a dense Markdown summary (~500 tokens, max 8 modules) with git context when available
-4. Returns a `BeforeAgentStartEventResult` with a `customMessage`; pi places it in the agent's context
-5. Subsequent turns skip injection entirely
+### Architecture-level questions
 
-## Tool Actions
+Ask "what's in this package?" or "what depends on this module?" The agent gets a structural answer, not a file listing.
 
-### `brief` — Architecture overviews and focused briefs
+### Impact analysis
 
-Scopes: project (no params), package/directory (`path`), file (`file`), or anchored symbol (`file`, `line`, and `character`).
+Before a change: "show me everything that would break." The agent sees direct callers, downstream dependents, and risk level — before touching code.
 
-- Project-level brief: module listing, dependency graph, "start here" recommendations, suggested next queries
-- Focused brief (`path` or anchored symbol): stripped-down version with a single module or symbol focus
-- Now includes git context (branch, dirty files, last commit) when inside a git repository
-- Metadata returned: `BriefDetails` with confidence, focus target, public surfaces, dependency summary
+### Smarter search
 
-### `callers` — Find call sites for a symbol
+`code_intel pattern` is text search that knows about code structure. Search for definitions (not just any text match), group by directory, or filter by import/export. Falls back from LSP to tree-sitter to ripgrep automatically.
 
-- LSP-first (references query), falls back to heuristic text search (word-boundary ripgrep)
-- Results grouped by file with ranked, contextual call sites
-- Confidence labeling: `semantic` (LSP), `heuristic` (text search)
-
-### `callees` — Structural outgoing call map
-
-- Structural tree-sitter analysis for all grammars configured in `supi-tree-sitter`
-- Finds outgoing function/method calls from an anchored position
-- Supports JavaScript/TypeScript, Python, Rust, Go, C/C++, Java, Kotlin, Ruby, Bash, and R
-
-### `implementations` — Find concrete implementations
-
-- Resolves interface/abstract method implementations via LSP
-- Falls back to heuristic text search for `implements`/`extends` patterns
-
-### `affected` — Blast-radius analysis
-
-Before changing exported APIs, shared helpers, config surfaces, or cross-package contracts:
-- Direct references (callers/importers)
-- Downstream dependents (transitive)
-- Risk level: `low` | `medium` | `high`
-- Likely test files
-- Returns `AffectedDetails` metadata
-
-### `index` — Factual project map
-
-A non-interpretive project overview for quick orientation:
-
-- File counts by language/extension
-- Top-level directory tree with file counts
-- Landmark config files detected (package.json, tsconfig.json, Makefile, etc.)
-- Skips low-signal directories (`node_modules`, `dist`, `build`, `.git`)
-
-Use when you need to understand "what's here?" before diving into specific files.
-
-```json
-{ "action": "index" }
-```
-
-### `pattern` — Bounded, scope-aware text search
-
-Optimized for common agent lookups:
-
-- `pattern` is treated as a **literal string by default**
-- Set `regex: true` to opt into raw ripgrep regex semantics
-- Malformed regex input returns an explicit error instead of a misleading "No matches found"
-- Nearby matches in the same file deduplicate overlapping context lines to reduce token waste
-- Results grouped with file and context lines
-- `summary: true` returns aggregate counts by directory instead of line-level matches (useful for "how common is this pattern?")
-
-Examples:
+## Install
 
-```json
-{ "action": "pattern", "pattern": "sendMessage({", "path": "packages/" }
-{ "action": "pattern", "pattern": "register(Settings|Config)", "path": "packages/", "regex": true }
-{ "action": "pattern", "pattern": "createServerFn", "summary": true }
+```bash
+pi install npm:@mrclrchtr/supi-code-intelligence
 ```
 
-## Language & File Type Support
-
-| Feature / Language | JS/TS | Python | Rust | Go | Java/Kotlin | Ruby | PHP | Swift | C/C++ | Other text |
-|---|---|---|---|---|---|---|---|---|---|---|
-| **`index`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **`brief` (project)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅¹ |
-| **`brief` (directory/file)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| **`callers`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`callees`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
-| **`implementations`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`affected`** | ✅ | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ✅² | ⚠️³ |
-| **`pattern`** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁴ |
-
-**Legend:**
-- **✅** Fully supported for that action.
-- **⚠️** Partial or best-effort support (see footnotes).
-- **❌** Not supported for that action.
-- **¹** Project-level brief works for any project with a recognized manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.).
-- **²** Requires an active LSP server for semantic resolution; falls back to heuristic text search otherwise.
-- **³** Heuristic text-search fallback only; no semantic or structural resolution.
-- **⁴** `pattern` works on any text file. Binary files (`.png`, `.jpg`, `.zip`, `.pdf`, etc.) are explicitly rejected.
-
-## Confidence Labeling
-
-Every result carries a `confidence` label from the result metadata:
-
-| Label | Meaning |
-|---|---|
-| `semantic` | Truth from LSP (definitions, references, diagnostics) |
-| `structural` | From tree-sitter AST (outlines, imports/exports, syntax) |
-| `heuristic` | Text search / best-effort inference |
-| `unavailable` | No data could be produced |
-
-## Result Metadata
+## Quick look
 
-**Contract:** `details` is returned for every action handler execution. It is
-`undefined` *only* when the request is rejected before any handler runs
-(parameter validation errors, unknown action, missing required `pattern`).
+| Action | What the agent can ask |
+|--------|----------------------|
+| `brief` | "Summarize this package / file / project" |
+| `callers` | "Who calls this function?" |
+| `callees` | "What does this function call?" |
+| `affected` | "What breaks if I change this?" |
+| `pattern` | "Find this text / pattern" |
+| `index` | "What's in this project?" |
+| `implementations` | "What implements this interface?" |
 
-For no-result and error states, `details` carries `confidence: "unavailable"` or
-`confidence: "heuristic"` with appropriately zeroed counts, so consumers always
-get structured metadata back.
+Every result includes a confidence label (semantic / structural / heuristic) so the agent knows how much to trust the answer.
 
-- **`brief`** → `BriefDetails` (confidence, focus target, start-here suggestions, public surfaces, dependency summary, omitted count, next queries)
-- **`search`** → `SearchDetails` (callers/callees/implementations/pattern: confidence, scope, candidate count, omitted count)
-- **`affected`** → `AffectedDetails` (direct count, downstream count, risk level, likely tests, check-next list)
+## For extension developers
 
-## Parameter Validation
-
-The tool enforces these rules and returns explicit error messages:
-
-- `line`/`character` require `file`, not `path` — `path` is for scope/focus, `file` anchors a position
-- `file` that points to a directory is rejected — use `path` for directory scoping
-- Unknown actions are rejected with a list of supported actions
-
-## Architecture
-
-Each action employs an appropriate fallback chain from the available services:
-
-- **`@mrclrchtr/supi-lsp`** — Semantic truth via LSP (references, symbols, implementations, diagnostics)
-- **`@mrclrchtr/supi-tree-sitter`** — Structural extraction (outlines, imports/exports, callees, syntax context)
-- **`@mrclrchtr/supi-core`** — Project/root utilities (root walking, known-root mapping, path containment)
-
-**Per-action fallback chains:** `callers`, `implementations`, and `affected` use LSP → ripgrep text search; `callees` uses tree-sitter AST analysis; `brief` uses the architecture model (plus tree-sitter outline for anchored briefs); `pattern` and `index` use filesystem and text-search primitives.
-
-### Programmatic API
-
-The package exports its internal APIs for use by peer extensions:
+The architecture model and brief generator are exported for reuse:
 
 ```ts
-// Architecture model
-export type { ArchitectureModel, DependencyEdge, ModuleInfo } from "./architecture.ts";
-export { buildArchitectureModel, findModuleForPath, getDependencies, getDependents } from "./architecture.ts";
-
-// Brief generation
-export { generateFocusedBrief, generateOverview, generateProjectBrief } from "./brief.ts";
-
-// Target resolution
-export type { ResolvedTarget, TargetResolutionResult } from "./target-resolution.ts";
-export { normalizePath, resolveAnchoredTarget, resolveSymbolTarget, toZeroBased } from "./target-resolution.ts";
-
-// Result types
-export type { AffectedDetails, BriefDetails, CodeIntelResult, ConfidenceMode, DisambiguationCandidate, SearchDetails } from "./types.ts";
-```
+import { buildArchitectureModel, generateOverview } from "@mrclrchtr/supi-code-intelligence";
 
-## Session Integration
-
-- The overview custom message type (`code-intelligence-overview`) uses `display: false` so it appears in the LLM context but not in the TUI message log
-- On `session_start`, the extension scans the session branch for an existing overview to avoid re-injecting on `/reload` or session resume
-- The `hasInjectedOverview` flag is per-session, reset each `session_start`
-
-## Prompt Guidelines (full text)
-
-These seven guidelines are injected into the system prompt:
-
-> - Use `code_intel brief` before editing an unfamiliar package, directory, or file to get architecture context and reduce blind reads.
-> - Use `code_intel affected` before changing exported APIs, shared helpers, config surfaces, or cross-package contracts to check blast radius and risk.
-> - Use `code_intel callers` before modifying a function to verify all call sites; use `callees` and `implementations` for dependency and interface analysis.
-> - Use `code_intel pattern` for bounded, scope-aware text search when the question is textual rather than semantic; it treats patterns as literal strings by default and supports `regex: true` when needed.
-> - Use `code_intel index` for a factual project map (file counts, directory structure, landmark files) when you need to orient yourself in a new codebase.
-> - After `code_intel` narrows the target, use raw `lsp` and `tree_sitter` tools for precise drill-down on exact symbols, types, or AST nodes.
-> - Do not prefer `code_intel` over direct file reads or lower-level tools for trivial, already-localized edits or exact symbol/AST drill-down tasks.
-
-## Install
-
-Included in the `@mrclrchtr/supi` meta-package, or install standalone:
-
-```bash
-pi install npm:@mrclrchtr/supi-code-intelligence
+const model = await buildArchitectureModel("/project");
+const overview = generateOverview(model);
 ```
-
-## License
-
-MIT

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "0.2.0",
+  "version": "1.1.3",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,13 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "devDependencies": {
-    "@types/node": "25.6.2",
-    "vitest": "4.1.5"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/README.md

@@ -1,112 +1,66 @@
 # @mrclrchtr/supi-lsp
 
-Language Server Protocol integration for the [pi coding agent](https://github.com/earendil-works/pi).
+Language Server Protocol for PI — your agent navigates code like an IDE.
 
-## Install
-
-```bash
-pi install npm:@mrclrchtr/supi-lsp
-```
-
-## What it adds
-
-- `lsp` tool with `hover`, `definition`, `references`, `diagnostics`, `symbols`, `rename`, `code_actions`, `workspace_symbol`, `search`, `symbol_hover`, and `recover`
-- Stable system-prompt guidance that tells the agent to prefer LSP over grep/rg for code navigation
-- Proactive project scanning and eager startup of detected language servers
-- Automatic stale-diagnostic recovery when workspace sentinels change (`package.json`, root lockfiles, `tsconfig*`, generated `*.d.ts` files`) before the next agent turn, plus immediate recovery after successful `write` or `edit` calls for those paths
-- Inline diagnostic surfacing around reads, writes, and edits
-- Compact diagnostic context injection when outstanding diagnostics change, with stale-diagnostic warnings when needed
-- `/lsp-status` status overlay
+Without LSP, agents grep and guess. With it, they jump to definitions, find every reference, rename across files, and catch type errors inline. The same precision you get from an editor, available to your agent.
 
-## Public library API
+## What you get
 
-In addition to the extension entrypoint, `@mrclrchtr/supi-lsp` exports a reusable session-scoped service API for peer extensions:
+### Navigate with precision
 
-```ts
-import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
-
-const state = getSessionLspService("/project");
+Go-to-definition, find-references, rename, hover types. The agent stops guessing and starts navigating your codebase with IDE-level accuracy.
 
-if (state.kind === "ready") {
-  const service = state.service;
-  const hover = await service.hover("src/index.ts", { line: 5, character: 10 });
-  const defs = await service.definition("src/index.ts", { line: 5, character: 10 });
-  const refs = await service.references("src/index.ts", { line: 5, character: 10 });
-  const impls = await service.implementation("src/index.ts", { line: 5, character: 10 });
-  const symbols = await service.documentSymbols("src/index.ts");
-  const projectServers = service.getProjectServers();
-}
-```
+### Catch problems immediately
 
-Peer extensions can import from the package root without reaching into private files.
+Type errors, warnings, and hints surface inline after every edit. The agent sees mistakes as it makes them — not 10 turns later when tests fail.
 
-## Tool actions
+### Always ready
 
-The `lsp` tool supports these actions:
+Servers start automatically for your project. The agent gets language-aware guidance at session start and stale diagnostics are refreshed when dependencies change.
 
-- `hover`: type info at a position
-- `definition`: go to definition
-- `references`: find all references
-- `diagnostics`: per-file or project-wide diagnostics
-- `symbols`: document symbols
-- `rename`: workspace-wide rename
-- `code_actions`: quick fixes at a position
-- `workspace_symbol`: fuzzy symbol search across the project
-- `search`: symbol search with text fallback
-- `symbol_hover`: hover by symbol name
-- `recover`: refresh diagnostics after workspace-wide dependency, config, or generated-type changes
-
-Line and character positions are **1-based**.
-
-Example:
+## Install
 
-```json
-{
-  "action": "definition",
-  "file": "src/index.ts",
-  "line": 12,
-  "character": 8
-}
+```bash
+pi install npm:@mrclrchtr/supi-lsp
 ```
 
-## Configuration
+## Quick look
 
-If your install surface includes `/supi-settings` (for example via `@mrclrchtr/supi`), this package contributes an LSP settings section there. Use that panel to:
+The agent gets an `lsp` tool. The most-used actions:
 
-- enable or disable LSP globally
-- control the severity threshold
-- select active language servers
-- configure file exclusion patterns
+| Action | What the agent can do |
+|--------|----------------------|
+| `hover` | See the type of any symbol |
+| `definition` | Jump to where something is defined |
+| `references` | Find every usage across the project |
+| `diagnostics` | See errors, warnings, and hints |
+| `rename` | Rename across the entire project |
 
-## Commands
+Full action reference: the agent's system prompt includes complete guidelines for all 11 actions (hover, definition, references, diagnostics, symbols, rename, code_actions, workspace_symbol, search, symbol_hover, recover). All positions are 1-based.
 
-`/lsp-status` toggles an overlay showing active language servers and outstanding diagnostics:
+## Settings
 
-```text
- λ LSP inspector  /lsp-status toggles
- 3 servers running • 12 open files • 5 errors • 2 warnings
+Configure via `/supi-settings` (LSP panel):
 
- Servers
-   typescript  running    24 open files
-   python      running     8 open files
-   bash        running     0 open files
+- Enable or disable LSP per project
+- Set diagnostic severity threshold (errors only, or include warnings/hints)
+- Choose which language servers to activate
+- Add file exclusion patterns (gitignore-style globs)
 
- Problems
-   src/lsp.ts:42       Cannot find name 'foo'          ts(2304)
-   src/manager.ts:108  Property 'bar' does not exist   ts(2339)
-```
+Settings are stored in `~/.pi/agent/supi/config.json` (global) or `.pi/supi/config.json` (project). The `/lsp-status` command shows active servers and outstanding diagnostics.
 
-When no servers are available, the overlay shows `no LSP servers available for this project`. A compact status summary is always visible in the pi status bar.
+## For extension developers
 
-## Requirements
+This package exports a reusable session-scoped LSP service. Peer extensions can query the same LSP runtime without starting duplicate servers:
 
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `typebox`
-- relevant language servers installed and available on `PATH`
-- `@mrclrchtr/supi-core`
+```ts
+import { getSessionLspService, SessionLspService } from "@mrclrchtr/supi-lsp";
 
-## Source
+const state = getSessionLspService("/project");
+if (state.kind === "ready") {
+  const defs = await state.service.definition("src/index.ts", { line: 5, character: 10 });
+  const refs = await state.service.references("src/index.ts", { line: 5, character: 10 });
+}
+```
 
-- Extension entrypoint: `lsp.ts`
-- Public library surface: `index.ts`
+Import from the package root — no need to reach into internal files.

package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "0.2.0",
+  "version": "1.1.3",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -22,9 +22,13 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
   },
-  "devDependencies": {
-    "@types/node": "25.6.2",
-    "vitest": "4.1.5"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "main": "src/index.ts"
 }

package/node_modules/@mrclrchtr/supi-lsp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.0.0",
+  "version": "1.1.3",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "workspace:*"
+    "@mrclrchtr/supi-core": "1.1.3"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -32,9 +32,19 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
-  "devDependencies": {
-    "vitest": "4.1.5",
-    "@mrclrchtr/supi-test-utils": "workspace:*"
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [

package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/stale-diagnostics.ts

@@ -31,7 +31,7 @@ export function assessStaleDiagnostics(
   };
 }
 
-function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
+export function isLikelyStaleDiagnostic(diagnostic: Diagnostic): boolean {
   if (diagnostic.severity === undefined) return false;
   if (diagnostic.code !== undefined) {
     if (typeof diagnostic.code === "number" && MODULE_RESOLUTION_CODES.has(diagnostic.code)) {

package/node_modules/@mrclrchtr/supi-lsp/src/lsp.ts

@@ -29,6 +29,7 @@ import {
   removeLspTool,
 } from "./lsp-state.ts";
 import { LspManager } from "./manager/manager.ts";
+import { forceResyncStaleModuleFiles } from "./manager/manager-stale-resync.ts";
 import { registerLspAwareToolOverrides } from "./overrides.ts";
 import { registerLspMessageRenderer } from "./renderer.ts";
 import { scanMissingServers, scanProjectCapabilities, startDetectedServers } from "./scanner.ts";
@@ -305,6 +306,16 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
       // Refresh failures must not prevent agent startup
     }
     state.manager.pruneMissingFiles();
+
+    // Force re-open files with module-resolution errors to clear stale
+    // diagnostics that persist when the TS server caches by content hash.
+    // Must run before the diagnostic summary so fresh results are captured.
+    try {
+      await forceResyncStaleModuleFiles(state.manager, ctx.cwd);
+    } catch {
+      // Best-effort: don't fail the agent turn
+    }
+
     refreshProjectServers(state);
     updateLspUi(ctx, state.manager, state.inlineSeverity, state.projectServers);
 

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-stale-resync.ts

@@ -0,0 +1,47 @@
+import * as path from "node:path";
+import { isLikelyStaleDiagnostic } from "../diagnostics/stale-diagnostics.ts";
+import type { LspManager } from "./manager.ts";
+
+/**
+ * Force re-open files with module-resolution errors (e.g., "Cannot find module")
+ * to trigger fresh analysis by the language server.
+ *
+ * The TypeScript server caches diagnostics by file content hash. When a new
+ * file is created that resolves an existing file's import, the stale diagnostic
+ * persists because the importing file's content hasn't changed. Re-opening the
+ * file (didClose + didOpen) forces the server to re-resolve all imports.
+ *
+ * Returns true if any files were re-synced.
+ */
+export async function forceResyncStaleModuleFiles(
+  manager: LspManager,
+  cwd: string,
+): Promise<boolean> {
+  const outstanding = manager.getOutstandingDiagnostics(1);
+  const staleFiles: string[] = [];
+
+  for (const entry of outstanding) {
+    if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
+      staleFiles.push(entry.file);
+    }
+  }
+
+  if (staleFiles.length === 0) return false;
+
+  for (const file of staleFiles) {
+    const filePath = path.resolve(cwd, file);
+    // Close the file to clear cached diagnostics and remove from openDocs
+    manager.closeFile(filePath);
+    // Re-open to force the server to re-resolve imports
+    await manager.ensureFileOpen(filePath);
+  }
+
+  // Re-sync and wait for fresh diagnostics after the re-opens
+  try {
+    await manager.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 });
+  } catch {
+    // Best-effort: don't fail the agent turn if refresh has issues
+  }
+
+  return true;
+}

package/node_modules/@mrclrchtr/supi-lsp/src/settings-registration.ts

@@ -151,7 +151,7 @@ function buildLspSettingItems(
       id: "exclude",
       label: "Exclude Patterns",
       description:
-        "Gitignore patterns to suppress LSP diagnostics (e.g. __tests__/, *.generated.ts)",
+        "Gitignore patterns to suppress LSP diagnostics. Edit .pi/supi/config.json → lsp.exclude (or ~/.pi/agent/supi/config.json for global). Patterns like __tests__/ exclude a directory, *.test.ts wildcards match at any depth, /dist anchors to root.",
       currentValue: settings.exclude.length > 0 ? settings.exclude.join(", ") : "none",
       submenu: (_currentValue, done) => createExcludeSubmenu(scope, cwd, settings, done),
     },