pi-lens 3.8.40 → 3.8.41

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to pi-lens will be documented in this file.
 
 ## [Unreleased]
 
+## [3.8.41] - 2026-05-05
+
+### Fixed
+
+- **tree-sitter wasm abort loop and memory leak (fixes #56)** — when the emscripten wasm runtime aborts (OOM or assertion failure on large workspaces), the module-level heap is permanently corrupted. pi-lens was re-invoking the dead runtime on every subsequent file write, printing `Aborted()` to stderr on each query and leaking memory on each retry. Added a module-level `_wasmAborted` flag: the first abort detected in the query catch loop poisons the singleton and prevents any further tree-sitter calls for the session. The runner skips cleanly with `reason: wasm_aborted_fatal` logged to `tree-sitter.log`.
+- **`turn_end` phases now instrumented in latency log** — `handleTurnEnd` previously had no `logLatency` calls; all timing data was buried in plain-text `dbg()` lines in `sessionstart.log`. Added per-phase latency entries for `cascade_merge`, `jscpd`, `knip`, and `madge`, plus a `tool_result` total with `fileCount` and `blockerSections`. This gives a baseline for measuring the cost of future turn_end additions (e.g. LSP re-query).
+- **Cascade ran graph build on non-code files** — markdown, YAML, JSON, and other files without a dispatchable kind were reaching `buildOrUpdateGraph`, causing cold graph builds that took up to 3–4 seconds per write with zero useful output. `computeCascadeForFile` now exits immediately with `cascade_skip / non_code_file` when `detectFileKind` returns `undefined`, consistent with the existing `shouldDispatch` gate used by the lint pipeline.
+
+### Added
+
+- **Per-server LSP diagnostic strategies** — new `clients/lsp/server-strategies.ts` codifies known server behavior (TypeScript, rust-analyzer, pyright, ESLint) so timing decisions are automatic rather than one-size-fits-all. Strategies control first-push seeding, debounce window, pull retry budget, aggregate wait timeout, and whether a server benefits from a semantic second pull pass. Env var overrides (`PI_LENS_LSP_*`) take precedence. Unknown servers get a conservative default.
+- **Result-aware diagnostic racing (`raceToCompletion`)** — new `clients/lsp/aggregation.ts` replaces the simple `Promise.race` + grace window pattern with a result-quality-aware aggregator. The grace window only triggers when at least one client has returned non-empty diagnostics, preventing premature resolution when the fastest client returns empty (e.g., TypeScript's syntactic pass). Document mode uses 0ms grace; full mode keeps the 400ms default.
+- **`seedFirstPush` early-exit for clean files** — `raceToCompletion`'s completion predicate now also fires when a `seedFirstPush` server (TypeScript, ESLint) returns any result, even an empty one. These servers' first push is authoritative — waiting further yields nothing. Cuts clean-file diagnostic latency from ~1000ms to ~450ms in full mode and to near-zero in document mode (cascade neighbor touches).
+
+- **`/lens-toggle` session switch** — added a single command to toggle pi-lens on/off at runtime without restarting pi. When off, write/edit analysis, read-guard, formatting, cascade, turn-end checks, and context injection are paused; running `/lens-toggle` again resumes them. `--no-lens` starts a session in the disabled state. Closes #49.
+- **Experimental Semgrep CLI dispatch integration** — added a config-gated `semgrep` dispatch runner that normalizes Semgrep JSON findings into pi-lens diagnostics. The runner never auto-installs Semgrep and only runs when a local `.semgrep.yml`/`.semgrep.yaml`/`semgrep.yml`/`semgrep.yaml` is discovered or when explicitly configured with `--lens-semgrep --lens-semgrep-config <auto|p/pack|path>` / `/lens-semgrep enable --config <...>`. Dispatch scans pass `--metrics=off`; local rule scans do not require a Semgrep token, while Semgrep AppSec/Pro/managed configs may require `semgrep login` or `SEMGREP_APP_TOKEN`.
+- **`/lens-semgrep` command** — new project command for managing Semgrep dispatch: `status` shows CLI/config/effective state, `init` writes a starter `.semgrep.yml` and enables dispatch, `enable [--config <auto|p/pack|path>]` persists activation in `.pi-lens/semgrep.json`, `disable` persists opt-out, and `clear` removes the pi-lens Semgrep config to return to local-config auto-discovery.
+- **Semgrep severity policy metadata** — Semgrep rules can opt into pi-lens blocking semantics with metadata such as `metadata.pi-lens.semantic: blocking` and `metadata.pi-lens.defect_class: injection`. Otherwise, pi-lens promotes only high-signal Semgrep `ERROR` findings in security defect classes (`injection`, `secrets`, `safety`) to blockers and leaves other findings as warnings.
+- **Experimental terminal dashboard** — `--lens-dashboard` / `PI_LENS_DASHBOARD=1` streams redacted session telemetry to a per-session JSONL file (`~/.pi-lens/dashboard-events/{sessionId}.jsonl`) and opens a live terminal dashboard. The dashboard shows the working folder, detected languages, formatter/linter activity, LSP servers spawned, diagnostics grouped by file with OSC-8 clickable links, and a session-start summary of languages, tools, configs, and autoinstalls. Each session gets its own event file; old files are pruned after 7 days (configurable via `PI_LENS_DASHBOARD_RETENTION_DAYS`). Use `PI_LENS_DASHBOARD_LOG_ONLY=1` to emit JSONL without opening a terminal. The viewer auto-scrolls to the latest content on each render.
+
+### Changed
+
+- **LSP diagnostic pipeline latency optimization** — six targeted refactors reduce per-file diagnostic wait times by 50–900ms depending on the language server: first-push seeding skips the debounce timer for TypeScript and ESLint (~150–200ms saved); adaptive debounce computes remaining wait from `pushDiagnosticTimestamps` (50–140ms saved); per-server aggregate wait times (1000ms for TypeScript, 3000ms for rust-analyzer, 1500ms default); semantic settle pass gated to rust-analyzer only; pull retry budget zeroed for TypeScript/ESLint. Global constants `DIAGNOSTICS_DEBOUNCE_MS`, `PULL_DIAGNOSTICS_RETRY_BUDGET_MS`, and `DIAGNOSTICS_AGGREGATE_WAIT_MS` replaced by per-server strategy values from the new `server-strategies.ts`.
+
+### Fixed
+
+- **Cascade neighbor touch cache ignores `writeSeq` on hit** — the A5 neighbor touch cache checked only `turnSeq` on cache hits, so a neighbor diagnosed at writeSeq=1 was served stale results when a second file write (writeSeq=2) cascaded to the same neighbor in the same turn. Fixed by requiring both `turnSeq` and `writeSeq` to match before using the cached entry.
+- **Cascade fallback neighbors include other primary files** — `appendFallbackNeighbors` (the degraded-LSP path) excluded only the current primary file from the passive diagnostic snapshot sweep, but not other files edited as primary this turn. Those files could appear as cascade neighbors even though their own pipeline run is the authoritative diagnostic source. Fixed by adding a `primaryFilesThisTurn` check consistent with the B10 filter in the main neighbor path.
+
+- **Semgrep dispatch plan regression** — kept the experimental Semgrep runner out of static `TOOL_PLANS` exposure and appends it only at runtime when Semgrep is actually configured. Fixes CI regressions in plan-shape tests while preserving config-gated Semgrep dispatch.
+- **Widget theme method binding crash** — `renderWidget` now calls `theme.fg(...)` directly instead of destructuring `fg`, preserving the `this` binding required by pi's `Theme` class. Fixes the `Cannot read properties of undefined (reading 'fgColors')` widget render crash. Closes #53.
+- **Read-guard follow-up edits after own writes** — tuned `file_modified` handling so a file changed by the agent's own prior allowed edit, immediate format, autofix, or deferred `agent_end` formatting does not force a redundant re-read when the next edit is still within already-read ranges. The guard still blocks zero-read and out-of-range edits, and external/stale changes outside the own-edit grace window remain protected. `PI_LENS_READ_GUARD_OWN_EDIT_GRACE_MS` controls the default 120s grace window.
+- **Read-guard log noise and growth** — `~/.pi-lens/read-guard.log` now defaults to block/warn/anomaly events instead of logging every read and allowed edit. Verbose logging is available with `PI_LENS_READ_GUARD_VERBOSE=1` or `PI_LENS_READ_GUARD_LOG=verbose`; allowed-edit logging can be restored with `PI_LENS_READ_GUARD_LOG_ALLOWS=1`. The log now rotates at 1MB by default (`PI_LENS_READ_GUARD_MAX_BYTES`).
+- **Pipelines skipped for external and vendor files** — agents reading dependency source (global npm packages, project-local `node_modules`) previously triggered LSP server spawns, tree-sitter read-range expansion, read-guard recording, and complexity baseline capture on those files — all noise with no diagnostic value. Added `isExternalOrVendorFile()` (built on the existing `isUnderDir` helper for correct Windows case handling) and gated all five pipeline paths: LSP auto-touch, tree-sitter expansion, read-guard recording, complexity baseline, and the full dispatch pipeline on write/edit.
+- **Security: absolute paths for `cmd.exe` and `osascript` spawn calls** — dashboard terminal launch now resolves both executables via `process.env.SystemRoot` / absolute macOS path instead of relying on `PATH`, eliminating the SonarCloud S4036 PATH-injection finding.
+- **Security: installed binary permissions tightened** — `chmod` calls on downloaded tool binaries changed from `0o755` to `0o750`, removing world-execute permission (SonarCloud S2612). GitHub Actions `contents: write` permission moved from workflow level to the `release` job only (S8233).
+- **Agent messages: full-file-read options removed** — read-guard block messages no longer offer "read the full file" as an alternative. The out-of-range block now presents only the pre-computed targeted `offset`/`limit`; the zero-read block gives a single imperative directive. "Re-read the file" fallback text in ambiguous-edit messages replaced with "Re-read the relevant section" throughout.
+- **Agent messages: indentation-mismatch RETRYABLE made explicitly directive** — the block now opens with "Retry the same edit call immediately with the corrected oldText shown below — copy it exactly as-is" and labels each corrected entry with "do not shorten, do not change newText", preventing agents from improvising instead of copying the corrected text verbatim.
+- **SonarCloud reliability fixes** — five `.sort()` calls on string arrays given explicit `localeCompare` comparators (S2871); three identical-branch conditionals collapsed (S3923 in `knip-client.ts`, `shellcheck.ts`, `production-readiness.ts`); emoji character class converted to alternation to handle multi-codepoint variation-selector emojis (S5868); regex alternation precedence made explicit with non-capturing groups (S5850); `| 0` in hash function annotated as intentional 32-bit truncation (S7767).
+- **CI: build step added before tests** — Vitest's native ESM resolver requires compiled `.js` output when `vi.resetModules()` is used; without a prior `tsc` build, imports of newly-added exports resolved as `undefined` in CI.
+- **Widget: diagnostic rows exceeded terminal width** — the custom `truncate()` helper stripped ANSI sequences to measure length but sliced the raw string, losing OSC-8 hyperlinks and SGR sequences from the count. Replaced with pi-tui's `truncateToWidth()` / `visibleWidth()` which correctly account for all escape sequences. All widget lines (header, file rows, separators, diagnostic detail, LSP status) are now clamped. Closes #54.
+- **Widget: file list capped at 5 entries, basename deduplication** — reduced max file rows from 6 to 5 to keep the widget compact. Added basename deduplication (last write wins) so that different files with the same name (e.g. `pi-lens/index.ts` and `pi-webaio/index.ts`) show as a single merged entry instead of flooding the widget with near-identical labels.
+
 ## [3.8.40] - 2026-05-04
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@ On every `write` and `edit`, pi-lens runs a fast, language-aware pipeline (check
 2. **Auto-format** — deferred to `agent_end` by default; queued files are formatted once after all agent tool calls complete. Use `--immediate-format` for per-edit formatting
 3. **Auto-fix** — safe autofixes from 6 tools (Biome `check --write`, Ruff `check --fix`, ESLint `--fix`, stylelint `--fix`, sqlfluff `fix`, RuboCop `-a`) applied before analysis
 4. **LSP file sync** — opens/updates the file in active language servers
-5. **Dispatch lint** — parallel runner groups: LSP diagnostics, tree-sitter structural rules, ast-grep security/correctness rules, fact rules, language-specific linters, similarity detection
+5. **Dispatch lint** — parallel runner groups: LSP diagnostics, tree-sitter structural rules, ast-grep security/correctness rules, fact rules, language-specific linters, experimental Semgrep security scans, similarity detection
 6. **Cascade diagnostics** — review-graph impact cascade showing which other files were affected and how diagnostics propagated
 
 Results are inline and actionable:
@@ -153,6 +153,36 @@ Structural rules are organized by language in `rules/tree-sitter-queries/`:
 - **Style/smells** — nested-ternary, long-parameter-list, large-class, prefer-optional-chain, redundant-state, require-await
 - **Agent stubs** — no-unimplemented-stub, no-raise-not-implemented, no-ellipsis-body
 
+### Semgrep CLI Integration (Experimental)
+
+pi-lens can run the locally installed `semgrep` CLI as an optional dispatch runner for security-focused findings. Semgrep diagnostics are normalized into the same pi-lens `Diagnostic` model as LSP, tree-sitter, ast-grep, and linters: high-signal security findings can become blocking, while other findings remain warnings for `/lens-booboo`/history.
+
+Activation is intentionally gated:
+
+- pi-lens **does not auto-install Semgrep**.
+- A local `.semgrep.yml`, `.semgrep.yaml`, `semgrep.yml`, or `semgrep.yaml` enables the runner when the `semgrep` CLI is available.
+- Without a local config, Semgrep stays skipped unless explicitly configured with `--lens-semgrep --lens-semgrep-config <auto|p/pack|path>` or `/lens-semgrep enable --config <auto|p/pack|path>`.
+- Local `.semgrep.yml` scans do not require a Semgrep token. Semgrep AppSec/Pro/managed configurations may require `semgrep login` or `SEMGREP_APP_TOKEN`.
+- pi-lens passes `--metrics=off` for dispatch scans.
+
+Commands:
+
+- `/lens-semgrep status` — show CLI availability, discovered local config, persisted pi-lens config, and effective dispatch state
+- `/lens-semgrep init` — create a starter `.semgrep.yml` with a blocking `eval(...)` rule and enable Semgrep dispatch
+- `/lens-semgrep enable [--config <auto|p/pack|path>]` — persist Semgrep dispatch activation in `.pi-lens/semgrep.json`
+- `/lens-semgrep disable` — persistently disable Semgrep dispatch for this project
+- `/lens-semgrep clear` — remove `.pi-lens/semgrep.json` and return to local-config auto-discovery
+
+Local rules can opt into pi-lens blocking semantics with metadata:
+
+```yaml
+metadata:
+  pi-lens:
+    semantic: blocking
+    defect_class: injection
+    confidence: high
+```
+
 ## Dependencies
 
 Auto-install behavior depends on gate type:
@@ -199,6 +229,7 @@ Auto-install behavior depends on gate type:
 | `vscode-html-languageserver-bin`    | HTML LSP                         | Yes            | Language-default                   |
 | `svelte-language-server`            | Svelte LSP                       | Yes            | Flow-gated                         |
 | `@vue/language-server`              | Vue LSP                          | Yes            | Flow-gated                         |
+| `semgrep`                           | Experimental security dispatch   | Manual         | Local config / explicit opt-in     |
 | `psscriptanalyzer`                  | PowerShell linting               | Manual         | —                                  |
 
 Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detected from PATH or installed via native package managers (`go install`, `gem install`) when their language is detected.
@@ -210,6 +241,7 @@ Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detecte
 pi
 
 # Optional switches
+pi --no-lens             # Start pi-lens disabled for this session; /lens-toggle can re-enable
 pi --no-lsp              # Disable unified LSP diagnostics
 pi --no-autoformat        # Skip auto-formatting entirely
 pi --immediate-format      # Format immediately after each edit instead of deferring to agent_end
@@ -217,6 +249,8 @@ pi --no-autofix           # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfl
 pi --no-tests             # Skip test 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)
+pi --lens-semgrep         # Enable Semgrep dispatch when a local/configured Semgrep config exists
+pi --lens-semgrep-config p/ci  # Explicit Semgrep config for dispatch (requires --lens-semgrep)
 ```
 
 ## Environment Variables
@@ -233,10 +267,12 @@ pi --lens-guard           # Block git commit/push when unresolved blockers exist
 
 ## Key Commands
 
+- `/lens-toggle` — toggle pi-lens on/off for the current session without restarting
 - `/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
+- `/lens-semgrep` — manage experimental Semgrep dispatch (`status`, `init`, `enable`, `disable`, `clear`)
 
 ## Language Coverage
 

package/clients/cache/rule-cache.ts

@@ -50,7 +50,7 @@ export class RuleCache {
 
 	private computeRuleHash(ruleFiles: string[]): string {
 		const hash = crypto.createHash("sha256");
-		for (const file of ruleFiles.sort()) {
+		for (const file of ruleFiles.sort((a, b) => a.localeCompare(b))) {
 			if (fs.existsSync(file)) {
 				const stat = fs.statSync(file);
 				hash.update(`${file}:${stat.mtimeMs}:${stat.size}`);

package/clients/complexity-client.ts

@@ -386,7 +386,7 @@ export class ComplexityClient {
 		let count = 0;
 
 		const aiPatterns = [
-			/[🔍✅📝🔧🐛⚠️🚀💡🎯📌🏷️🔑🏗️🧪🗑️🔄♻️📋🔖📊💬🔥💎⭐🌟🎯🎨🔧🛠️]/u,
+			/(?:🔍|✅|📝|🔧|🐛|⚠️|🚀|💡|🎯|📌|🏷️|🔑|🏗️|🧪|🗑️|🔄|♻️|📋|🔖|📊|💬|🔥|💎|⭐|🌟|🎨|🛠️)/u,
 			/\/\/\s*(Initialize|Setup|Clean up|Create|Define|Check if|Handle|Process|Validate|Return|Get|Set|Add|Remove|Update|Fetch)\b/i,
 			/\/\/\s*(This function|This method|This code|Here we|Now we)\b/i,
 			/\/\*\*?\s*(Overview|Summary|Description|Example|Usage)\s*\*?\//i,

package/clients/dependency-checker.ts

@@ -408,7 +408,7 @@ export class DependencyChecker {
 		let output = `[Circular Deps] ${circular.length} cycle(s) found:\n`;
 
 		for (const dep of circular) {
-			const cycleKey = dep.path.sort().join("→");
+			const cycleKey = dep.path.sort((a, b) => a.localeCompare(b)).join("→");
 			if (seen.has(cycleKey)) continue;
 			seen.add(cycleKey);
 

package/clients/dispatch/diagnostic-taxonomy.ts

@@ -12,6 +12,9 @@ const SILENT_ERROR_HINTS = [
 
 const INJECTION_HINTS = [
 	"sql-injection",
+	"command-injection",
+	"template-injection",
+	"xss",
 	"eval",
 	"exec",
 	"inner-html",
@@ -56,7 +59,16 @@ export function classifyDefect(
 		return "correctness";
 	}
 
-	if (text.includes("unsafe") || text.includes("security")) return "safety";
+	if (
+		text.includes("unsafe") ||
+		text.includes("security") ||
+		text.includes("ssrf") ||
+		text.includes("path-traversal") ||
+		text.includes("deserial") ||
+		text.includes("auth-bypass") ||
+		text.includes("crypto")
+	)
+		return "safety";
 	if (text.includes("style") || text.includes("format")) return "style";
 
 	return "unknown";

package/clients/dispatch/dispatcher.ts

@@ -16,6 +16,7 @@
 
 import * as path from "node:path";
 import type { FileKind } from "../file-kinds.js";
+import { recordRunner } from "../widget-state.js";
 import { detectFileKind } from "../file-kinds.js";
 import { isTestFile } from "../file-utils.js";
 import { getPrimaryDispatchGroup } from "../language-policy.js";
@@ -389,6 +390,7 @@ function buildCoverageNotice(
 		"similarity",
 		"spellcheck",
 		"fact-rules",
+		"semgrep",
 	]);
 	const anyLinterHasCoverage = runnerLatencies.some(
 		(r) =>
@@ -597,6 +599,13 @@ async function runGroup(
 			diagnosticCount: result.diagnostics.length,
 			semantic: result.semantic ?? semantic,
 		});
+		recordRunner(
+			ctx.filePath,
+			runnerId,
+			result.status,
+			result.diagnostics.length,
+			duration,
+		);
 
 		diagnostics.push(...result.diagnostics);
 

package/clients/dispatch/fact-scheduler.ts

@@ -69,7 +69,7 @@ export function scheduleProviders(providers: FactProvider[]): FactProvider[] {
     const cycleParticipants = providers
       .filter((p) => !result.includes(p))
       .map((p) => p.id)
-      .sort();
+      .sort((a, b) => a.localeCompare(b));
     throw new Error(
       `Cycle detected among FactProviders: ${cycleParticipants.join(", ")}`,
     );

package/clients/dispatch/integration.ts

@@ -16,6 +16,7 @@ import {
 	formatSlopScoreSummary,
 	type SlopScoreSummary,
 } from "../session-summary.js";
+import { resolveSemgrepConfig } from "../semgrep-config.js";
 import {
 	clearCoverageNoticeState,
 	clearLatencyReports,
@@ -290,6 +291,52 @@ export function getDispatchSlopScoreLine(): string {
 	return formatSlopScoreSummary(summary);
 }
 
+const SEMGREP_SUPPORTED_KINDS = new Set<FileKind>([
+	"csharp",
+	"css",
+	"cxx",
+	"dart",
+	"docker",
+	"go",
+	"html",
+	"java",
+	"json",
+	"jsts",
+	"kotlin",
+	"lua",
+	"php",
+	"python",
+	"ruby",
+	"rust",
+	"shell",
+	"swift",
+	"terraform",
+	"yaml",
+]);
+
+function withSemgrepGroup(
+	kind: FileKind,
+	groups: RunnerGroup[],
+	ctx: ReturnType<typeof createDispatchContext>,
+): RunnerGroup[] {
+	if (!SEMGREP_SUPPORTED_KINDS.has(kind)) return groups;
+	const config = resolveSemgrepConfig(ctx.cwd, {
+		enabled: Boolean(ctx.pi.getFlag("lens-semgrep")),
+		config: ctx.pi.getFlag("lens-semgrep-config"),
+	});
+	if (!config.enabled) return groups;
+	if (groups.some((group) => group.runnerIds.includes("semgrep"))) return groups;
+	return [
+		...groups,
+		{
+			mode: "all",
+			runnerIds: ["semgrep"],
+			filterKinds: [kind],
+			semantic: "warning",
+		},
+	];
+}
+
 function withPrimaryPolicyGroup(
 	kind: keyof typeof TOOL_PLANS,
 	groups: RunnerGroup[],
@@ -430,6 +477,11 @@ export async function computeCascadeForFile(
 		return undefined;
 	}
 
+	if (!detectFileKind(filePath)) {
+		logCascade({ phase: "cascade_skip", filePath, reason: "non_code_file" });
+		return undefined;
+	}
+
 	const normalizedFile = resolveRunnerPath(cwd, filePath);
 	const normalizedFileKey = normalizeMapKey(normalizedFile);
 
@@ -586,7 +638,7 @@ export async function computeCascadeForFile(
 				// write sequence. A new write (higher writeSeq) invalidates the cache entry.
 				const cached =
 					writeSeq != null ? neighborTouchCache.get(cacheKey) : undefined;
-				if (cached?.turnSeq === turnSeq) {
+				if (cached?.turnSeq === turnSeq && cached?.writeSeq === writeSeq) {
 					producedLspData = true;
 					const durationMs = Date.now() - neighborStart;
 					logCascade({
@@ -821,6 +873,7 @@ function appendFallbackNeighbors(
 	for (const [diagPath, { diags, ts }] of allDiags) {
 		const diagKey = normalizeMapKey(diagPath);
 		if (diagKey === normalizedFileKey || seen.has(diagKey)) continue;
+		if (primaryFilesThisTurn.has(diagKey)) continue;
 		if (!nodeFs.existsSync(diagPath)) continue;
 		if (now - ts > CASCADE_TTL_MS) continue;
 		const errors = convertLspDiagnostics(
@@ -919,7 +972,7 @@ export async function dispatchLint(
 	const kind = ctx.kind;
 	if (!kind) return "";
 
-	const groups = getDispatchGroupsForKind(kind, pi);
+	const groups = withSemgrepGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
 	if (groups.length === 0) return "";
 
 	await runProviders(ctx);
@@ -962,7 +1015,7 @@ export async function dispatchLintWithResult(
 		};
 	}
 
-	const groups = getDispatchGroupsForKind(kind, pi);
+	const groups = withSemgrepGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
 	if (groups.length === 0) {
 		return {
 			diagnostics: [],

package/clients/dispatch/runners/index.ts

@@ -34,6 +34,7 @@ import pythonSlopRunner from "./python-slop.js";
 import rubocopRunner from "./rubocop.js";
 import ruffRunner from "./ruff.js";
 import rustClippyRunner from "./rust-clippy.js";
+import semgrepRunner from "./semgrep.js";
 import shellcheckRunner from "./shellcheck.js";
 import shfmtRunner from "./shfmt.js";
 // Import similarity runner
@@ -65,6 +66,7 @@ export function registerDefaultRunners(registry: RunnerRegistry): void {
 	registry.register(pythonSlopRunner); // Python slop via CLI (priority 25)
 	registry.register(typeSafetyRunner); // Type safety checks (priority 20)
 	registry.register(shellcheckRunner); // Shell script linting (priority 20)
+	registry.register(semgrepRunner); // Semgrep security/deep static analysis (config/flag-gated, priority 50)
 	// DISABLED: registerRunner(astGrepRunner); // Replaced by ast-grep-napi for dispatch
 	// CLI ast-grep kept for ast_grep_search/ast_grep_replace tools only
 	registry.register(similarityRunner); // Semantic reuse detection (priority 35)

package/clients/dispatch/runners/semgrep.ts

@@ -0,0 +1,269 @@
+import * as path from "node:path";
+import { classifyDefect } from "../diagnostic-taxonomy.js";
+import { PRIORITY } from "../priorities.js";
+import type {
+	DefectClass,
+	Diagnostic,
+	DispatchContext,
+	OutputSemantic,
+	RunnerDefinition,
+	RunnerResult,
+} from "../types.js";
+import { safeSpawnAsync } from "../../safe-spawn.js";
+import { resolveSemgrepConfig } from "../../semgrep-config.js";
+import { createAvailabilityChecker } from "./utils/runner-helpers.js";
+
+const semgrep = createAvailabilityChecker("semgrep", ".exe");
+const MAX_DIAGNOSTICS = 50;
+
+interface SemgrepJsonOutput {
+	results?: SemgrepResult[];
+	errors?: Array<{ message?: string; type?: string; level?: string }>;
+}
+
+interface SemgrepResult {
+	check_id?: string;
+	path?: string;
+	start?: { line?: number; col?: number };
+	extra?: {
+		message?: string;
+		severity?: string;
+		metadata?: Record<string, unknown>;
+		fix?: string;
+		fix_regex?: unknown;
+	};
+}
+
+function getPiLensMetadata(
+	metadata: Record<string, unknown>,
+): Record<string, unknown> {
+	const nested = metadata["pi-lens"] ?? metadata.pi_lens;
+	return nested && typeof nested === "object"
+		? (nested as Record<string, unknown>)
+		: {};
+}
+
+function metadataString(
+	metadata: Record<string, unknown>,
+	piLens: Record<string, unknown>,
+	key: string,
+): string | undefined {
+	const direct = piLens[key] ?? metadata[`pi_lens_${key}`];
+	return typeof direct === "string" && direct.trim()
+		? direct.trim()
+		: undefined;
+}
+
+function metadataBoolean(
+	metadata: Record<string, unknown>,
+	piLens: Record<string, unknown>,
+	key: string,
+): boolean {
+	return piLens[key] === true || metadata[`pi_lens_${key}`] === true;
+}
+
+function normalizeDefectClass(
+	value: string | undefined,
+): DefectClass | undefined {
+	if (!value) return undefined;
+	const normalized = value.toLowerCase().replace(/_/g, "-");
+	if (
+		normalized === "silent-error" ||
+		normalized === "injection" ||
+		normalized === "secrets" ||
+		normalized === "async-misuse" ||
+		normalized === "correctness" ||
+		normalized === "safety" ||
+		normalized === "style" ||
+		normalized === "unknown" ||
+		normalized === "unused-value"
+	) {
+		return normalized;
+	}
+	if (
+		normalized.includes("traversal") ||
+		normalized.includes("ssrf") ||
+		normalized.includes("xss") ||
+		normalized.includes("deserial") ||
+		normalized.includes("crypto") ||
+		normalized.includes("auth")
+	) {
+		return "safety";
+	}
+	return undefined;
+}
+
+function semgrepSemantic(
+	result: SemgrepResult,
+	defectClass: DefectClass,
+): OutputSemantic {
+	const metadata = result.extra?.metadata ?? {};
+	const piLens = getPiLensMetadata(metadata);
+	const explicitSemantic = metadataString(metadata, piLens, "semantic");
+	if (
+		explicitSemantic === "blocking" ||
+		metadataBoolean(metadata, piLens, "blocking")
+	) {
+		return "blocking";
+	}
+	if (explicitSemantic === "warning" || explicitSemantic === "silent") {
+		return explicitSemantic;
+	}
+
+	const severity = String(result.extra?.severity ?? "").toUpperCase();
+	const confidence = String(
+		metadata.confidence ??
+			metadata.semgrep_confidence ??
+			piLens.confidence ??
+			"",
+	).toLowerCase();
+	const highSignalSecurity =
+		defectClass === "injection" ||
+		defectClass === "secrets" ||
+		defectClass === "safety";
+
+	if (severity === "ERROR" && highSignalSecurity && confidence !== "low") {
+		return "blocking";
+	}
+
+	return "warning";
+}
+
+function mapSeverity(
+	semgrepSeverity: string | undefined,
+	semantic: OutputSemantic,
+): Diagnostic["severity"] {
+	if (semantic === "blocking") return "error";
+	const severity = String(semgrepSeverity ?? "").toUpperCase();
+	if (severity === "ERROR") return "error";
+	if (severity === "INFO") return "info";
+	return "warning";
+}
+
+function parseSemgrepJson(raw: string, ctx: DispatchContext): Diagnostic[] {
+	if (!raw.trim()) return [];
+	let parsed: SemgrepJsonOutput;
+	try {
+		parsed = JSON.parse(raw) as SemgrepJsonOutput;
+	} catch {
+		return [];
+	}
+
+	const results = Array.isArray(parsed.results) ? parsed.results : [];
+	const diagnostics: Diagnostic[] = [];
+
+	for (const [index, result] of results.entries()) {
+		if (diagnostics.length >= MAX_DIAGNOSTICS) break;
+		const rule = result.check_id || "semgrep";
+		const message = result.extra?.message || rule;
+		const metadata = result.extra?.metadata ?? {};
+		const piLens = getPiLensMetadata(metadata);
+		const explicitDefect = normalizeDefectClass(
+			metadataString(metadata, piLens, "defect_class"),
+		);
+		const defectClass =
+			explicitDefect ?? classifyDefect(rule, "semgrep", message);
+		const semantic = semgrepSemantic(result, defectClass);
+		const filePath = result.path || ctx.filePath;
+		const line = result.start?.line ?? 1;
+		const column = result.start?.col ?? 1;
+		const fixSuggestion =
+			metadataString(metadata, piLens, "fix") ??
+			(typeof result.extra?.fix === "string" ? result.extra.fix : undefined);
+
+		diagnostics.push({
+			id: `semgrep:${rule}:${path.basename(filePath)}:${line}:${column}:${index}`,
+			message: `[${rule}] ${message}`,
+			filePath,
+			line,
+			column,
+			severity: mapSeverity(result.extra?.severity, semantic),
+			semantic,
+			tool: "semgrep",
+			rule,
+			defectClass,
+			fixable: Boolean(fixSuggestion || result.extra?.fix_regex),
+			autoFixAvailable: false,
+			fixKind:
+				fixSuggestion || result.extra?.fix_regex ? "suggestion" : undefined,
+			fixSuggestion,
+		});
+	}
+
+	return diagnostics;
+}
+
+const semgrepRunner: RunnerDefinition = {
+	id: "semgrep",
+	appliesTo: [
+		"csharp",
+		"css",
+		"cxx",
+		"dart",
+		"docker",
+		"go",
+		"html",
+		"java",
+		"json",
+		"jsts",
+		"kotlin",
+		"lua",
+		"php",
+		"python",
+		"ruby",
+		"rust",
+		"shell",
+		"swift",
+		"terraform",
+		"yaml",
+	],
+	priority: PRIORITY.DEEP_LANGUAGE_ANALYSIS,
+	enabledByDefault: false,
+
+	async when(ctx: DispatchContext): Promise<boolean> {
+		return resolveSemgrepConfig(ctx.cwd, {
+			enabled: Boolean(ctx.pi.getFlag("lens-semgrep")),
+			config: ctx.pi.getFlag("lens-semgrep-config"),
+		}).enabled;
+	},
+
+	async run(ctx: DispatchContext): Promise<RunnerResult> {
+		const cwd = ctx.cwd || process.cwd();
+		const resolved = resolveSemgrepConfig(cwd, {
+			enabled: Boolean(ctx.pi.getFlag("lens-semgrep")),
+			config: ctx.pi.getFlag("lens-semgrep-config"),
+		});
+		if (!resolved.enabled) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+
+		if (!semgrep.isAvailable(cwd)) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+		const cmd = semgrep.getCommand(cwd) ?? "semgrep";
+		const args = ["scan", "--json", "--metrics=off", "--timeout", "5"];
+		if (resolved.configArg) args.push("--config", resolved.configArg);
+		args.push(ctx.filePath);
+
+		const result = await safeSpawnAsync(cmd, args, { cwd, timeout: 20000 });
+		const raw = result.stdout || "";
+		const diagnostics = parseSemgrepJson(raw, ctx);
+		if (diagnostics.length === 0) {
+			return {
+				status: result.error ? "failed" : "succeeded",
+				diagnostics: [],
+				semantic: "none",
+				rawOutput: (result.stderr || "").slice(0, 500),
+			};
+		}
+
+		const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
+		return {
+			status: hasBlocking ? "failed" : "succeeded",
+			diagnostics,
+			semantic: hasBlocking ? "blocking" : "warning",
+		};
+	},
+};
+
+export default semgrepRunner;

package/clients/dispatch/runners/shellcheck.ts

@@ -148,14 +148,8 @@ const shellcheckRunner: RunnerDefinition = {
 		}
 		if (!cmd) return { status: "skipped", diagnostics: [], semantic: "none" };
 
-		// Determine shell dialect from file extension
-		const shellDialect = ctx.filePath.endsWith(".zsh")
-			? "bash"
-			: ctx.filePath.endsWith(".fish")
-				? "bash"
-				: ctx.filePath.endsWith(".sh")
-					? "bash"
-					: "bash"; // Default to bash for generic shell files
+		// Determine shell dialect from file extension (all map to bash for shellcheck)
+		const shellDialect = "bash";
 
 		// Build args
 		// --format json: JSON output