pi-lens 3.8.27 → 3.8.29

package/CHANGELOG.md

@@ -2,6 +2,109 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [Unreleased]
+
+## [3.8.29] - 2026-04-21
+
+### Added
+- **New diagnostic commands** — added `/lens-tools` and `/lens-health` for system visibility:
+  - `/lens-tools` — shows tool installation status: globally installed, pi-lens auto-installed, or npx fallback
+  - `/lens-health` — shows runtime health: pipeline crashes, slow runners, diagnostic stats
+  - Both provide actionable visibility into the pi-lens toolchain
+- **Streamlined ast-grep skill** — reduced skill from 7,759 bytes to 2,313 bytes (~70% reduction):
+  - Removed verbose CLI tips and YAML rule authoring sections (agent uses tools, not CLI)
+  - Removed redundant testing documentation
+  - Kept essential: Golden Rules, Quick Reference, Common Gotchas
+- **Configurable log cleanup** — automatic retention and rotation for `~/.pi-lens/*.log` files:
+  - Environment variable `PI_LENS_LOG_RETENTION_DAYS` (default: 7) — days to keep log files
+  - Environment variable `PI_LENS_MAX_LOG_SIZE_MB` (default: 10) — max size before rotation
+  - Runs automatically on session start, notifies when cleanup occurs
+  - Rotated backups (`.log.*`) cleaned after retention period
+  - Project-level logs (`{cwd}/.pi-lens/*`) intentionally excluded from cleanup
+
+### Changed
+- **`/lens-tools` output improved** — added explanatory note when GitHub-release tools are shown as missing: "GitHub-release tools auto-install when you open files of those languages"
+- **Simplified agent prompts** — removed verbose prompt sections to reduce token burn:
+  - Removed startup notes about project rules count (now just logged, not shown)
+  - Removed tooling hints for missing language tools (Go/Rust/Ruby install suggestions)
+  - Removed project rules section from system prompt (no longer injects `## Project Rules` block)
+  - Updated core guidance to clarify: automated checks run on edits/writes, blocking errors shown inline must be fixed
+- **Simplified CLI flags** — removed 16 flags to reduce surface area and cognitive load:
+  - Removed per-tool disable flags: `--no-biome`, `--no-ast-grep`, `--no-shellcheck`, `--no-madge`, `--no-oxlint`, `--no-ruff`, `--no-go`, `--no-rust`
+  - Removed per-tool autofix flags: `--no-autofix-biome`, `--no-autofix-ruff`
+  - Removed feature flags: `--lens-verbose`, `--error-debt`, `--auto-install`, `--lens-eslint-core`
+  - Removed redundant `--lens-lsp` flag (LSP is default-on; use `--no-lsp` to disable)
+  - Removed internal dead flag: `--lens-blocking-only`
+  - **Removed `--no-lsp-install` flag** — LSP servers now always auto-install when needed (no manual opt-out)
+  - New minimal flag set: `--no-lsp`, `--no-autoformat`, `--no-autofix`, `--no-tests`, `--no-delta`, `--lens-guard`
+- **Cross-platform line ending handling** — all `.split("\n")` changed to `.split(/\r?\n/)` for Windows CRLF compatibility (11 files updated)
+
+### Fixed
+- **Biome VCS/ignore file errors eliminated** — disabled VCS integration in biome config to prevent "ignore file not found" errors:
+  - Changed `vcs.enabled: true` → `vcs.enabled: false` in `config/biome/core.jsonc`
+  - Biome was searching for `.gitignore` files that don't exist when running on arbitrary projects via pi-lens
+  - Eliminates biome:parse-error spam in logs when biome runs outside its config directory
+- **LSP server thrashing eliminated** — added 240s idle timeout to prevent repeated LSP shutdown/startup cycles:
+  - New `scheduleLSPIdleReset()` in `runtime-turn.ts` defers server reset when no files modified
+  - Cancel pending reset when active editing resumes (avoids interrupting workflows)
+  - Eliminates ~1-2s cold-start penalty during active development sessions
+  - Debug logging added for scheduling and cancellation events
+- **Biome check runner JSON parsing** — fixed error where biome's stderr warnings broke JSON parsing:
+  - Changed from parsing `stdout || stderr` to parsing `stdout` only
+  - Biome outputs text warnings (e.g., "couldn't find ignore file") to stderr which broke the JSON parser
+  - Fixes biome-check-json runner failing with parse errors instead of providing lint diagnostics
+- **Auto-install verification gap** — `getToolPath()` now verifies tool binaries actually work before using them:
+  - Runs `--version` check on local npm tools (not just file existence)
+  - Detects broken/corrupted installations (e.g., wrapper exists but package missing)
+  - Triggers automatic reinstall when binary verification fails
+  - Fixes case where `@biomejs/biome` package deleted but `.cmd` wrapper remained
+- **Error swallowing in tool availability checks** — `runtime-session.ts` now logs errors when biome/ast-grep/ruff/knip/dep/jscpd availability checks fail (was silently returning `false`)
+- **Biome check runner reliability** — fixed path resolution and configuration issues causing "skipped" status and parse errors:
+  - Fixed biome flag: `--output-format=json` → `--reporter=json`
+  - Fixed `findBiome()` to check `~/.pi-lens/tools/` directory (was falling back to bare "biome" not in PATH)
+  - Fixed `findBiome()` to return `{cmd, argsPrefix}` object for proper npx fallback with `@biomejs/biome` prefix
+  - Added `vcs.root: "."` to `config/biome/core.jsonc` to respect project `.gitignore`
+- **LSP error messaging** — improved error messages for Windows .cmd shim failures to distinguish "npm .cmd shim failed (underlying binary not installed)" from "may be missing or corrupted"
+- **Windows installer improvements** — multiple fixes for Windows tool discovery and LSP stability:
+  - Prefer `.cmd` over extensionless in local TOOLS_DIR path lookup on Windows
+  - Bypass PS1 hangs in LSP initialization with hard-kill on timeout
+  - Remove `.ps1` from pyright managed candidates and ast-grep discovery on Windows
+  - Use `SYSTEMDRIVE` env var instead of hardcoded `C:` for cargo fallback path
+- **Rust LSP** — exponential backoff circuit breaker for failing LSP connections
+- **Installer reliability** — remove `console.error` verbosity, route all events to `sessionstart.log`
+- **Circular dependencies** — fixed circular dependencies identified in code review
+- **Knip race condition** — fixed race condition in knip tool discovery
+- **Non-blocking tool availability checks** — changed all `ensureAvailable()` methods to use async `safeSpawnAsync` instead of sync `safeSpawn`, completing the startup unblocking work:
+  - `ruff-client.ts`, `biome-client.ts`, `sg-runner.ts` (first batch)
+  - `knip-client.ts`, `dependency-checker.ts`, `jscpd-client.ts` (second batch)
+  - `sg-runner.ts` — added missing `safeSpawnAsync` import
+- **Secrets scanner false positives** — fixed incorrect flagging of environment variable name references (e.g., `"FIREWORKS_API_KEY"`, `"AWS_ACCESS_KEY_ID"`) as hardcoded secrets:
+  - Added word boundaries to `hardcoded-secret` regex pattern
+  - Added `looksLikeEnvVarName()` filter to skip UPPERCASE_SNAKE_CASE values
+  - Prevents false positives when env var names are used as placeholder strings
+
+### Changed
+- **Biome check performance** — reduced lint latency from ~1.4s to ~100ms per file (92% improvement):
+  - Removed redundant `--version` pre-check spawn (~200ms saved)
+  - Switched from `biome check` to `biome lint` command (skip format validation)
+  - Added binary path caching per cwd to avoid repeated fs checks
+  - Benchmark: 107ms average vs 1400ms baseline
+- **Tree-sitter performance** — reduced structural analysis latency by 30-50%:
+  - Execute queries in parallel with concurrency limit of 6 (was sequential)
+  - Skip entity snapshot extraction for changes under 5 lines (~500-800ms saved for trivial edits)
+  - Reduces tree-sitter latency from ~3s to ~1-2s for typical files
+
+## [3.8.28] - 2026-04-19
+
+### Fixed
+- **Session startup no longer blocks the Node event loop** — tool availability probes (biome, ast-grep, ruff, knip, jscpd, madge) now run via async `ensureAvailable()` in a fire-and-forget IIFE instead of `setImmediate` + `spawnSync`, eliminating ~8–10 s of main-thread freeze on startup.
+- **Biome binary lookup extended** — `getBiomeBinary()` now checks `~/.pi-lens/tools/node_modules/.bin/biome` so the async probe finds the pre-installed binary without falling back to `npx`.
+- **CSS roots and Windows LSP shims tightened** — improved root resolution for CSS language server on Windows.
+- **Zig compile coverage kept active** — LSP availability check no longer incorrectly disables Zig compile diagnostics.
+- **Ruby LSP startup budgets relaxed** — reduced false-negative LSP attach failures on slower machines.
+- **Kotlin and Zig LSP availability improved** — more reliable server detection across platforms.
+- **Standalone Python and Ruby LSP roots fixed** — correct workspace root used when opening files outside a project directory.
+
 ## [3.8.27] - 2026-04-19
 
 ### Added

package/README.md

@@ -42,6 +42,7 @@ At `turn_end`, pi-lens:
 - persists turn findings for next context injection
 - updates debt/diagnostic tracking and cleans transient state
 - renders a review-graph impact cascade showing affected files and diagnostic propagation
+- manages LSP server lifecycle with a 240s idle timeout (resets when editing resumes)
 
 ## Install
 
@@ -62,17 +63,22 @@ pi install git:github.com/apmantza/pi-lens
 pi
 
 # Optional switches
-pi --no-lsp              # Disable unified LSP, use language-specific fallbacks
+pi --no-lsp              # Disable unified LSP diagnostics
 pi --no-autoformat        # Skip auto-formatting
 pi --no-autofix           # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfluff, RuboCop)
 pi --no-tests             # Skip test runner
-pi --no-shellcheck        # Disable shellcheck runner
+pi --no-delta             # Disable delta mode (show all diagnostics, not just new ones)
+pi --lens-guard           # Block git commit/push when unresolved blockers exist (experimental)
 ```
 
+LSP is enabled by default. Use `--no-lsp` to use language-specific fallbacks (ts-lsp, pyright) instead of the unified LSP service.
+
 ## Key Commands
 
 - `/lens-booboo` — full quality report for current project state
 - `/lens-health` — runtime health, latency, and diagnostic telemetry
+- `/lens-tools` — tool installation status: globally installed, auto-installed, or npx fallback
+- `/lens-tdi` — Technical Debt Index (TDI) and project health trend
 
 ## Language Coverage
 
@@ -147,6 +153,8 @@ pi-lens builds a review graph (`file → symbol → dependency`) during session
 
 pi-lens includes **37 language server definitions**. LSP is **enabled by default** (`--lsp` or no flag). Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
 
+**LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
+
 LSP servers for: TypeScript, Deno, Python (pyright + pylsp), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, C# (omnisharp), F#, Java, Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, OCaml, Clojure, Terraform, Nix, Bash, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, ESLint, CSS.
 
 ## Runners
@@ -251,4 +259,14 @@ Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detecte
 
 - Not every auto-install runs in every project: gate type decides when install is attempted.
 - Rule packs are customizable via project-level rule directories.
-- Inline suppression: `// pi-lens-ignore` or `# pi-lens-ignore` comments suppress diagnostic output for that line.
+- Inline suppression: `// pi-lens-ignore` or `# pi-lens-ignore` comments suppress diagnostic output for that line.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PI_LENS_STARTUP_MODE` | auto | `full`, `minimal`, or `quick` — override session startup behavior |
+| `PI_LENS_LOG_RETENTION_DAYS` | 7 | Days to retain log files before automatic cleanup |
+| `PI_LENS_MAX_LOG_SIZE_MB` | 10 | Max size in MB before rotating active log files |
+
+Logs are stored in `~/.pi-lens/` and automatically cleaned up at session start based on these settings.

package/clients/architect-client.ts

@@ -187,7 +187,7 @@ export class ArchitectClient {
 				// biome-ignore lint/suspicious/noAssignInExpressions: RegExp.exec iteration
 				while ((match = regex.exec(content)) !== null) {
 					// Convert index to line number
-					const lineNum = content.slice(0, match.index).split("\n").length;
+					const lineNum = content.slice(0, match.index).split(/\r?\n/).length;
 					violations.push({
 						pattern: rule.pattern,
 						message: check.message,
@@ -263,7 +263,7 @@ export class ArchitectClient {
 		const ruleBlocks = content.split(/(?=^ {2}- pattern:)/m);
 
 		for (const block of ruleBlocks) {
-			const lines = block.split("\n");
+			const lines = block.split(/\r?\n/);
 			let rule: ArchitectRule | null = null;
 			let section: "must_not" | "must" | null = null;
 			let violation: {

package/clients/ast-grep-client.ts

@@ -345,7 +345,7 @@ message: found
 			output += `  ${ruleInfo} (${loc})${fix}\n`;
 
 			if (d.ruleDescription?.note) {
-				const shortNote = d.ruleDescription.note.split("\n")[0];
+				const shortNote = d.ruleDescription.note.split(/\r?\n/)[0];
 				output += `    → ${shortNote}\n`;
 			}
 		}

package/clients/ast-grep-parser.ts

@@ -51,7 +51,7 @@ export class AstGrepParser {
 		}
 
 		return output
-			.split("\n")
+			.split(/\r?\n/)
 			.filter((l) => l.trim())
 			.map((line) => {
 				try {

package/clients/ast-grep-rule-manager.ts

@@ -67,7 +67,7 @@ export class AstGrepRuleManager {
 		);
 		if (noteMatch) {
 			result.note = noteMatch[1]
-				.split("\n")
+				.split(/\r?\n/)
 				.map((line) => line.trim())
 				.filter((line) => line.length > 0)
 				.join(" ");
@@ -82,7 +82,7 @@ export class AstGrepRuleManager {
 		const fixMatch = content.match(/^fix:\s*\|?([\s\S]*?)(?=^\w|^rule:|Z)/m);
 		if (fixMatch) {
 			result.fix = fixMatch[1]
-				.split("\n")
+				.split(/\r?\n/)
 				.map((line) => line.replace(/^\s*\|?\s*/, ""))
 				.filter((line) => line.length > 0)
 				.join("\n");

package/clients/biome-client.ts

@@ -9,6 +9,7 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
 import { safeSpawn, safeSpawnAsync } from "./safe-spawn.js";
@@ -60,16 +61,29 @@ export class BiomeClient {
 		if (this.localBinaryPath) return { cmd: this.localBinaryPath, args: [] };
 
 		// Walk up from cwd looking for node_modules/.bin/biome.
+		// Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
+		// so we avoid the ~1.5s `npx @biomejs/biome --version` fallback when
+		// the tool is already installed but not in the project's node_modules.
 		// On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
 		const isWin = process.platform === "win32";
+		const piLensBin = path.join(
+			os.homedir(),
+			".pi-lens",
+			"tools",
+			"node_modules",
+			".bin",
+		);
 		const candidates = isWin
 			? [
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+					path.join(piLensBin, "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				]
 			: [
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				];
 		for (const p of candidates) {
 			if (fs.existsSync(p)) {
@@ -123,7 +137,7 @@ export class BiomeClient {
 		if (this.biomeAvailable !== null) return this.biomeAvailable;
 
 		// Check if already available
-		const result = this.spawnBiome(["--version"], 10000);
+		const result = await this.spawnBiomeAsync(["--version"], 10000);
 		if (!result.error && result.status === 0) {
 			this.biomeAvailable = true;
 			return true;
@@ -554,8 +568,8 @@ export class BiomeClient {
 	}
 
 	private computeDiff(original: string, formatted: string): string {
-		const origLines = original.split("\n");
-		const formLines = formatted.split("\n");
+		const origLines = original.split(/\r?\n/);
+		const formLines = formatted.split(/\r?\n/);
 
 		let changedLines = 0;
 		const changes: string[] = [];

package/clients/complexity-client.ts

@@ -213,7 +213,7 @@ export class ComplexityClient {
 		sourceFile: ts.SourceFile;
 	}): FileComplexity {
 		const { absolutePath, content, sourceFile } = parsed;
-		const lines = content.split("\n");
+		const lines = content.split(/\r?\n/);
 
 		// Line counts and function collection
 		const { codeLines, commentLines } = this.countLines(sourceFile, lines);
@@ -393,7 +393,7 @@ export class ComplexityClient {
 			/\/\*\*?\s*(Overview|Summary|Description|Example|Usage)\s*\*?\//i,
 		];
 
-		const lines = sourceText.split("\n");
+		const lines = sourceText.split(/\r?\n/);
 		for (const line of lines) {
 			// Only check comment lines
 			const trimmed = line.trim();
@@ -583,9 +583,10 @@ export class ComplexityClient {
 		let match;
 		while ((match = commentRegex.exec(text)) !== null) {
 			const lineStart = text.lastIndexOf("\n", match.index) + 1;
-			const startLine = text.substring(0, lineStart).split("\n").length - 1;
+			const startLine = text.substring(0, lineStart).split(/\r?\n/).length - 1;
 			const endLine =
-				text.substring(0, match.index + match[0].length).split("\n").length - 1;
+				text.substring(0, match.index + match[0].length).split(/\r?\n/).length -
+				1;
 			for (let i = startLine; i <= endLine; i++) {
 				commentPositions.add(i);
 			}

package/clients/dependency-checker.ts

@@ -11,7 +11,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { safeSpawn } from "./safe-spawn.js";
+import { safeSpawn, safeSpawnAsync } from "./safe-spawn.js";
 
 // --- Types ---
 
@@ -63,7 +63,7 @@ export class DependencyChecker {
 		if (this.available !== null) return this.available;
 
 		// Check if available in PATH
-		const result = safeSpawn("madge", ["--version"], {
+		const result = await safeSpawnAsync("madge", ["--version"], {
 			timeout: 5000,
 		});
 		this.available = !result.error && result.status === 0;

package/clients/dispatch/diagnostic-taxonomy.ts

@@ -1,14 +1,4 @@
-import type { Diagnostic } from "./types.js";
-
-export type DefectClass =
-	| "silent-error"
-	| "injection"
-	| "secrets"
-	| "async-misuse"
-	| "correctness"
-	| "safety"
-	| "style"
-	| "unknown";
+import type { DefectClass, Diagnostic } from "./types.js";
 
 const SILENT_ERROR_HINTS = [
 	"empty-catch",
@@ -20,9 +10,27 @@ const SILENT_ERROR_HINTS = [
 	"silent",
 ];
 
-const INJECTION_HINTS = ["sql-injection", "eval", "exec", "inner-html", "javascript-url"];
-const SECRET_HINTS = ["secret", "token", "password", "api-key", "hardcoded-secrets"];
-const ASYNC_HINTS = ["await-in-loop", "promise", "concurrency", "async", "then-catch"];
+const INJECTION_HINTS = [
+	"sql-injection",
+	"eval",
+	"exec",
+	"inner-html",
+	"javascript-url",
+];
+const SECRET_HINTS = [
+	"secret",
+	"token",
+	"password",
+	"api-key",
+	"hardcoded-secrets",
+];
+const ASYNC_HINTS = [
+	"await-in-loop",
+	"promise",
+	"concurrency",
+	"async",
+	"then-catch",
+];
 
 function hasAny(haystack: string, hints: string[]): boolean {
 	return hints.some((h) => haystack.includes(h));
@@ -40,7 +48,11 @@ export function classifyDefect(
 	if (hasAny(text, SECRET_HINTS)) return "secrets";
 	if (hasAny(text, ASYNC_HINTS)) return "async-misuse";
 
-	if (text.includes("no-") || text.includes("return") || text.includes("constructor")) {
+	if (
+		text.includes("no-") ||
+		text.includes("return") ||
+		text.includes("constructor")
+	) {
 		return "correctness";
 	}
 
@@ -50,6 +62,8 @@ export function classifyDefect(
 	return "unknown";
 }
 
-export function classifyDiagnostic(d: Pick<Diagnostic, "rule" | "tool" | "message">): DefectClass {
+export function classifyDiagnostic(
+	d: Pick<Diagnostic, "rule" | "tool" | "message">,
+): DefectClass {
 	return classifyDefect(d.rule, d.tool, d.message);
 }

package/clients/dispatch/dispatcher.ts

@@ -17,15 +17,15 @@
 import * as path from "node:path";
 import type { FileKind } from "../file-kinds.js";
 import { detectFileKind } from "../file-kinds.js";
+import { isTestFile } from "../file-utils.js";
 import { getPrimaryDispatchGroup } from "../language-policy.js";
 import { resolveLanguageRootForFile } from "../language-profile.js";
-import { isTestFile } from "../file-utils.js";
 import { logLatency } from "../latency-logger.js";
 import { normalizeMapKey } from "../path-utils.js";
 import { RUNTIME_CONFIG } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
-import { FactStore } from "./fact-store.js";
+import type { FactStore } from "./fact-store.js";
 import { getToolPlan } from "./plan.js";
 import { resolveRunnerPath } from "./runner-context.js";
 import { getToolProfile } from "./tool-profile.js";
@@ -135,7 +135,7 @@ export function createDispatchContext(
 		cwd: normalizedCwd,
 		kind,
 		pi,
-		autofix: !!(pi.getFlag("autofix-biome") || pi.getFlag("autofix-ruff")),
+		autofix: false,
 		deltaMode: !pi.getFlag("no-delta"),
 		facts,
 		blockingOnly,
@@ -215,7 +215,10 @@ function dedupeOverlappingDiagnostics(diagnostics: Diagnostic[]): Diagnostic[] {
  * Syntax: `// pi-lens-ignore: rule-id` (JS/TS) or `# pi-lens-ignore: rule-id` (Python/Ruby/etc.)
  * Place on the same line as the diagnostic or the line immediately above it.
  */
-function applyInlineSuppressions(diagnostics: Diagnostic[], content: string): Diagnostic[] {
+function applyInlineSuppressions(
+	diagnostics: Diagnostic[],
+	content: string,
+): Diagnostic[] {
 	if (!content || !diagnostics.length) return diagnostics;
 
 	// Build a set of (line, ruleId) pairs that are suppressed.
@@ -226,9 +229,12 @@ function applyInlineSuppressions(diagnostics: Diagnostic[], content: string): Di
 	for (let i = 0; i < lines.length; i++) {
 		const m = SUPPRESS_RE.exec(lines[i]);
 		if (!m) continue;
-		const rules = m[1].split(",").map((r) => r.trim()).filter(Boolean);
+		const rules = m[1]
+			.split(",")
+			.map((r) => r.trim())
+			.filter(Boolean);
 		const suppressedLine = i + 1; // same line (1-based)
-		const nextLine = i + 2;      // next line (1-based)
+		const nextLine = i + 2; // next line (1-based)
 		for (const ruleId of rules) {
 			suppressed.add(`${suppressedLine}:${ruleId}`);
 			suppressed.add(`${nextLine}:${ruleId}`);
@@ -342,7 +348,7 @@ function buildCoverageNotice(
 	runnerLatencies: RunnerLatency[],
 ): Diagnostic | undefined {
 	if (!ctx.kind) return undefined;
-	const lspEnabled = !!ctx.pi.getFlag("lens-lsp") && !ctx.pi.getFlag("no-lsp");
+	const lspEnabled = !ctx.pi.getFlag("no-lsp");
 	const primary = getPrimaryDispatchGroup(ctx.kind, lspEnabled);
 	if (!primary || primary.runnerIds.length === 0) return undefined;
 
@@ -367,7 +373,9 @@ function buildCoverageNotice(
 		(plan?.groups ?? [])
 			.filter(
 				(group) =>
-					!group.runnerIds.every((runnerId) => primary.runnerIds.includes(runnerId)),
+					!group.runnerIds.every((runnerId) =>
+						primary.runnerIds.includes(runnerId),
+					),
 			)
 			.flatMap((group) => group.runnerIds)
 			.filter((runnerId) => !primary.runnerIds.includes(runnerId)),
@@ -376,7 +384,12 @@ function buildCoverageNotice(
 	// Structural-only runners (tree-sitter, ast-grep, similarity) are not
 	// substitutes for real linters — don't suppress the notice if only they ran.
 	const STRUCTURAL_RUNNERS = new Set([
-		"tree-sitter", "ast-grep-napi", "similarity", "spellcheck", "architect", "fact-rules",
+		"tree-sitter",
+		"ast-grep-napi",
+		"similarity",
+		"spellcheck",
+		"architect",
+		"fact-rules",
 	]);
 	const anyLinterHasCoverage = runnerLatencies.some(
 		(r) =>
@@ -499,7 +512,7 @@ async function runGroup(
 		? group.runnerIds.filter((id) => {
 				const runner = registry.get(id);
 				return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
-		  })
+			})
 		: group.runnerIds;
 
 	const semantic = group.semantic ?? "warning";
@@ -668,12 +681,20 @@ export async function dispatchForFile(
 	// This avoids partial-baseline corruption when processing multiple groups.
 	const dedupedDiagnostics = dedupeOverlappingDiagnostics(allDiagnostics);
 	const overlapSuppressed = suppressLintOverlapsWithLsp(dedupedDiagnostics);
-	const fileContent = ctx.facts.getFileFact<string>(ctx.filePath, "file.content") ?? "";
-	const inlineSuppressed = applyInlineSuppressions(overlapSuppressed, fileContent);
+	const fileContent =
+		ctx.facts.getFileFact<string>(ctx.filePath, "file.content") ?? "";
+	const inlineSuppressed = applyInlineSuppressions(
+		overlapSuppressed,
+		fileContent,
+	);
 	let visibleDiagnostics = inlineSuppressed;
 	let resolvedCount = 0;
 	if (ctx.deltaMode && previousBaseline) {
-		const filtered = filterDelta(visibleDiagnostics, previousBaseline, (d) => d.id);
+		const filtered = filterDelta(
+			visibleDiagnostics,
+			previousBaseline,
+			(d) => d.id,
+		);
 		visibleDiagnostics = promoteDeltaUnusedToBlockers(filtered.new);
 		resolvedCount = filtered.fixed.length;
 	}
@@ -693,15 +714,19 @@ export async function dispatchForFile(
 
 	// Append fixed and fixable diagnostics to the persistent worklog
 	if (fixedItems.length > 0) {
-		import("../fix-worklog.js").then(({ appendToWorklog }) => {
-			appendToWorklog(ctx.cwd, fixedItems, true);
-		}).catch(() => {});
+		import("../fix-worklog.js")
+			.then(({ appendToWorklog }) => {
+				appendToWorklog(ctx.cwd, fixedItems, true);
+			})
+			.catch(() => {});
 	}
 	const fixableWarnings = warnings.filter((d) => d.fixable);
 	if (fixableWarnings.length > 0) {
-		import("../fix-worklog.js").then(({ appendToWorklog }) => {
-			appendToWorklog(ctx.cwd, fixableWarnings, false);
-		}).catch(() => {});
+		import("../fix-worklog.js")
+			.then(({ appendToWorklog }) => {
+				appendToWorklog(ctx.cwd, fixableWarnings, false);
+			})
+			.catch(() => {});
 	}
 
 	const inlineBlockers = blockers.filter((d) => d.tool !== "similarity");
@@ -804,7 +829,10 @@ function looksLikeDiagnosticCodePath(value: string): boolean {
 	return false;
 }
 
-function normalizeDiagnosticFilePath(ctx: DispatchContext, rawPath?: string): string {
+function normalizeDiagnosticFilePath(
+	ctx: DispatchContext,
+	rawPath?: string,
+): string {
 	if (typeof rawPath === "string" && looksLikeDiagnosticCodePath(rawPath)) {
 		ctx.log(
 			`runner path normalization: ignored diagnostic code-like path '${rawPath}', using current file`,

package/clients/dispatch/facts/try-catch-facts.ts

@@ -39,15 +39,16 @@ const DEFAULT_VALUE_PATTERN =
 const STRUCTURED_ERROR_PATTERN =
   /\breturn\s+\{[^}]*(?:success\s*:\s*false|error\s*:)/;
 
-const EXPLAINING_COMMENT_PATTERN =
-  /\/\/[^\n]*(intentional|expected|ignore|ok|safe|fallback|known|silent|no-op)/i;
+// Any non-trivial comment (≥ 4 non-space chars) counts as documented intent.
+// This covers patterns like: // continue, /* not found */, // best-effort, etc.
+const EXPLAINING_COMMENT_PATTERN = /(?:\/\/\s*\S.{3,}|\/\*\s*\S[\s\S]{3,}?\*\/)/;
 
 const FS_PROBE_PATTERN =
   /\b(?:existsSync|statSync|lstatSync|readFileSync|accessSync)\b/;
 
 const DB_PATTERN = /\b(?:query|execute|findOne|findMany|findById|insert|update|delete|select|prisma\.|knex\.|sequelize\.)/;
 const NETWORK_PATTERN = /\b(?:fetch|axios|http\.|https\.|request\.|got\.|undici\.)/;
-const FS_PATTERN = /\b(?:readFile|writeFile|appendFile|readdir|mkdir|stat|unlink|existsSync|readFileSync)\b/;
+const FS_PATTERN = /\b(?:readFileSync?|writeFileSync?|appendFileSync?|readdirSync?|mkdirSync?|statSync?|unlinkSync?|existsSync|accessSync?|copyFileSync?|renameSync?)\b/;
 const PROCESS_PATTERN = /\b(?:spawn|exec|execSync|spawnSync|child_process\.)\b/;
 
 function detectBoundaryCategory(