pi-lens 3.8.51 → 3.8.52

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [3.8.52] - 2026-06-14
+
+### Fixed
+
+- **read-guard: canonicalize path map keys — stops false `zero_read` blocks (closes #210)** — `ReadGuard` keyed its `reads`/`edits`/`exemptions` maps on the **raw** file-path string, relying on the read-path and edit-path strings being byte-for-byte identical. `resolveToolCallFilePath` returns absolute paths verbatim, so the key was whatever separator/casing the model emitted — and models freely mix `/` and `\` on Windows. The regression trigger: read-guard started recording reads from new sources that produce a *different* path form than the Edit tool — `ast_grep_search` matches (#169, slash-normalized from ast-grep output) and LSP-expanded synthetic reads (URI → forward slash). On Windows a file read via search/LSP got a `C:/…` key while the follow-up edit arrived `C:\…` → key miss → false `zero_read` ("Edit without read") despite the file having been read, repeatedly, in a real session (`pi-free`: reads logged `C:/…`, the blocking edit `C:\…`). Every map access now keys through `normalizeFilePath` (folds separators + Windows casing), so record and lookup always agree. **Why it slipped:** every read-guard test used the *same* POSIX path on both `recordRead` and `checkEdit`, so the raw keys always matched — no test exercised cross-separator/cross-source agreement. Closed by `tests/clients/read-guard-path-normalization.test.ts` (forward↔back-slash both directions, Windows case-folding, exemption parity, and a negative: a genuinely-unread file still blocks).
+
+### Added
+
+- **Live tool-smoke harness driving the real dispatch path (refs #209, layer 2)** — `scripts/smoke-tools.mjs` installs (via the real `ensureTool` auto-install) and runs each supported tool against a minimal real project per language (`tests/fixtures/tool-smoke/<lang>/`), driving pi-lens's **real** dispatch path so a smoke pass means the actual runner→spawn code worked (not a hand-rolled stand-in). Step 1 (default) asserts each target tool spawns and exits cleanly (no `timeout`/`exception`/`server_error`); Step 2 (`--step2`) additionally asserts a parseable diagnostic on the fixture's known defect. Per-runner truth comes from a new optional `onRunnerResult` sink threaded through `dispatchForFile`→`runGroup` (fires per executed runner with its exact `RunnerResult` incl. `failureKind`) exposed via `dispatchLintDetailed` — no duplication of dispatch's selection/gating. Opt-in/nightly (installs + spawns real tools), never a per-PR gate; not shipped in the npm tarball. Already surfaced a real wiring gap: `markdownlint` is registered (priority 30) and installs, but the markdown write-dispatch group is `["spellcheck","vale"]`, so it never runs on markdown writes.
+
+- **Deterministic auto-install registry-consistency guard (refs #209, layer 1)** — the live install→run net for every supported tool is expensive and environment-dependent (deferred to layer 2); this catches the cheap-to-catch class per-PR. A new `tests/clients/installer/tool-registry-consistency.test.ts` exports the previously-private `TOOLS` array and locks the **install contract** that `installTool` silently depends on: each `npm` entry declares `packageName`+`binaryName`, each `pip`/`gem` entry declares `packageName`, each `github` entry declares an `owner/repo` + `assetMatch` + `binaryName` and no `packageName` — a half-wired entry compiles fine today but just `return false`s at install time, so it "looks registered" while never installing. It also asserts ids are globally unique, `checkCommand`/`binaryName` are clean executable tokens, and every `github` tool's `assetMatch` is total/safe (never throws across the platform×arch matrix incl. unsupported platforms, resolves at least one combo, rejects freebsd/sunos/aix). **Fixed a coverage drift it surfaced:** `GITHUB_TOOLS` (the curated list the asset-matrix value-test iterates) had drifted to 9 of the 14 actual `github`-strategy tools, leaving `hadolint`, `gitleaks`, `taplo`, and `vale` asset selection **completely untested** — they're now in `GITHUB_TOOLS` (so the full matrix test covers them), and a bidirectional sync assertion keeps the list ≡ "github tools with full cross-platform coverage" going forward (`swiftlint` is intentionally excluded — no Windows asset).
+
 ## [3.8.51] - 2026-06-14
 
 ### Added

package/dist/clients/dispatch/dispatcher.js

@@ -389,7 +389,7 @@ export function formatLatencyReport(report) {
  * Groups themselves are run in parallel by dispatchForFile, so this
  * function must NOT mutate shared state.
  */
-async function runGroup(ctx, group, registry) {
+async function runGroup(ctx, group, registry, onRunnerResult) {
     const diagnostics = [];
     const latencies = [];
     let hadBlocker = false;
@@ -458,6 +458,7 @@ async function runGroup(ctx, group, registry) {
             continue;
         }
         const result = await runRunner(ctx, runner, semantic);
+        onRunnerResult?.(runnerId, result);
         const runnerEnd = Date.now();
         const duration = runnerEnd - runnerStart;
         latencies.push({
@@ -508,7 +509,7 @@ async function runGroup(ctx, group, registry) {
     return { diagnostics, latencies, hadBlocker };
 }
 // --- Main Dispatch Function ---
-export async function dispatchForFile(ctx, groups, registry) {
+export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     const _overallStart = Date.now();
     if (ctx.fileRole === "generated") {
         return {
@@ -543,7 +544,7 @@ export async function dispatchForFile(ctx, groups, registry) {
     // each other's results. Within each group, mode:"fallback" semantics are
     // preserved (sequential first-success). Results are merged in original
     // group order so output is deterministic.
-    const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry)));
+    const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
     // Count baseline warnings before filtering (for delta count display)
     const relativeKey = path.relative(ctx.cwd, ctx.filePath).replace(/\\/g, "/");
     const baselineAbsKey = `session.baseline.${normalizeMapKey(ctx.filePath)}`;

package/dist/clients/dispatch/integration.js

@@ -1030,6 +1030,44 @@ export async function dispatchLintWithResult(filePath, cwd, pi, modifiedRanges,
     }
     return result;
 }
+/**
+ * Same real dispatch path as {@link dispatchLintWithResult} (real context, real
+ * file-kind→runner selection, real `run()` → spawn → tool), but also returns
+ * each runner's exact `RunnerResult` (status + `failureKind` + diagnostics) via
+ * the `onRunnerResult` sink. The live tool-smoke harness (#209) uses this to
+ * assert each supported tool spawned and exited cleanly without re-implementing
+ * dispatch's selection/gating. Defaults to `blockingOnly: false` so every
+ * applicable runner (not just blocking ones) executes.
+ */
+export async function dispatchLintDetailed(filePath, cwd, pi, options) {
+    const empty = {
+        diagnostics: [],
+        blockers: [],
+        warnings: [],
+        baselineWarningCount: 0,
+        fixed: [],
+        resolvedCount: 0,
+        output: "",
+        blockerOutput: "",
+        hasBlockers: false,
+    };
+    const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, options?.blockingOnly ?? false, options?.modifiedRanges);
+    sessionFacts.clearFileFactsFor(ctx.filePath);
+    const kind = ctx.kind;
+    if (!kind)
+        return { result: empty, runners: [] };
+    const groups = withSemgrepGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+    if (groups.length === 0)
+        return { result: empty, runners: [] };
+    const runners = [];
+    const sink = (runnerId, result) => {
+        runners.push({ runnerId, result });
+    };
+    await runProviders(ctx);
+    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry, sink);
+    trackSessionSlopStats(ctx, result.diagnostics);
+    return { result, runners };
+}
 /**
  * Check if a file should be processed by the dispatcher
  * based on the file kind

package/dist/clients/installer/index.js

@@ -83,7 +83,7 @@ function logSessionStart(msg) {
         // best-effort logging
     });
 }
-const TOOLS = [
+export const TOOLS = [
     // Core LSP servers
     {
         id: "typescript-language-server",
@@ -1940,6 +1940,18 @@ export async function checkAllTools() {
 export function isKnownToolId(toolId) {
     return TOOLS.some((tool) => tool.id === toolId);
 }
+/**
+ * GitHub-release tools that ship an asset for **every** supported
+ * platform/arch combo (linux/darwin/win32 × x64/arm64). This is the set the
+ * full asset-matrix test (tests/clients/installer/github-release.test.ts)
+ * iterates, so membership must stay in lockstep with the registry — the
+ * tool-registry-consistency test enforces that every `installStrategy: "github"`
+ * entry resolving all six combos appears here, and vice versa.
+ *
+ * `swiftlint` is deliberately absent: it has no Windows asset (macOS + Linux
+ * only), so it cannot satisfy the full matrix and is covered by the weaker
+ * "at least one platform" guard instead.
+ */
 export const GITHUB_TOOLS = [
     "shellcheck",
     "shfmt",
@@ -1950,6 +1962,10 @@ export const GITHUB_TOOLS = [
     "tflint",
     "terraform-ls",
     "zls",
+    "hadolint",
+    "gitleaks",
+    "taplo",
+    "vale",
 ];
 /**
  * Resolve the GitHub asset filename substring for a tool on a given platform/arch.

package/dist/clients/read-guard.js

@@ -11,6 +11,7 @@
  */
 import * as fs from "node:fs";
 import { createFileTime } from "./file-time.js";
+import { normalizeFilePath } from "./path-utils.js";
 import { logReadGuardEvent } from "./read-guard-logger.js";
 // --- Constants ---
 const DEFAULT_CONFIG = {
@@ -132,16 +133,31 @@ export class ReadGuard {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.fileTime = createFileTime(sessionId);
     }
+    /**
+     * Canonical Map key for a file path. Read sources arrive with mixed
+     * separators/casing — the Read tool gives OS-native backslashes on Windows,
+     * while LSP-expanded and search-tool reads arrive slash-normalized from URIs.
+     * Keying the reads/edits/exemptions maps on the raw path made a read recorded
+     * under one form invisible to an edit checked under another, producing a false
+     * `zero_read` block despite the file having been read. `normalizeFilePath`
+     * folds separators and Windows casing to one key, so record and lookup always
+     * agree. Every map access in this class MUST key through here.
+     */
+    key(filePath) {
+        return normalizeFilePath(filePath);
+    }
     // --- Public API ---
     /**
      * Record that a file was read.
      * Call this from the tool_call handler after any LSP expansion.
      */
     recordRead(record) {
+        const filePath = this.key(record.filePath);
         const storedRecord = {
             ...record,
+            filePath,
             lineHashes: record.lineHashes ??
-                captureLineHashes(record.filePath, record.effectiveOffset, record.effectiveLimit),
+                captureLineHashes(filePath, record.effectiveOffset, record.effectiveLimit),
         };
         const arr = this.reads.get(storedRecord.filePath) ?? [];
         arr.push(storedRecord);
@@ -174,6 +190,9 @@ export class ReadGuard {
      * Returns verdict with action and optional reason for blocking.
      */
     checkEdit(filePath, touchedLines, editRanges, options) {
+        // Canonicalize once: every map lookup below (and every private helper this
+        // passes filePath to) must agree with how recordRead keyed the read.
+        filePath = this.key(filePath);
         // Check exemptions
         if (this.exemptions.has(filePath)) {
             this.exemptions.delete(filePath); // One-time use
@@ -370,7 +389,7 @@ export class ReadGuard {
      * read so immediate follow-up edits are not blocked by zero_read.
      */
     noteCreatedFile(filePath, turnIndex, writeIndex) {
-        this.pendingCreations.set(filePath, { turnIndex, writeIndex });
+        this.pendingCreations.set(this.key(filePath), { turnIndex, writeIndex });
     }
     /**
      * Refresh the FileTime stamp after the model's own write lands on disk.
@@ -378,6 +397,7 @@ export class ReadGuard {
      * file doesn't see "file_modified" caused by our own previous edit.
      */
     recordWritten(filePath) {
+        filePath = this.key(filePath);
         this.fileTime.read(filePath);
         this.writtenThisSession.add(filePath);
         const creation = this.pendingCreations.get(filePath);
@@ -391,7 +411,7 @@ export class ReadGuard {
      * Called via /lens-allow-edit command.
      */
     addExemption(filePath) {
-        this.exemptions.add(filePath);
+        this.exemptions.add(this.key(filePath));
         logReadGuardEvent({
             event: "exemption_added",
             sessionId: this.sessionId,
@@ -441,13 +461,13 @@ export class ReadGuard {
      * Get all read records for a file (for debugging).
      */
     getReadHistory(filePath) {
-        return this.reads.get(filePath) ?? [];
+        return this.reads.get(this.key(filePath)) ?? [];
     }
     /**
      * Get all edit records for a file (for debugging).
      */
     getEditHistory(filePath) {
-        return this.edits.get(filePath) ?? [];
+        return this.edits.get(this.key(filePath)) ?? [];
     }
     // --- Private helpers ---
     injectCreationRead(filePath, turnIndex, writeIndex) {

package/dist/clients/sg-runner.js

@@ -22,6 +22,20 @@ function escapeWindowsArg(arg) {
     // Escape quotes by doubling them
     return `"${arg.replace(/"/g, '""')}"`;
 }
+/**
+ * Build the `bash -c` argv that runs `cmd` with `allArgs` as POSITIONAL
+ * parameters. The script is the constant `"$0" "$@"`, so bash re-emits the
+ * command and every arg verbatim — no parameter expansion, no word-splitting.
+ *
+ * Two properties this guarantees, neither of which string-interpolation could:
+ *  - ast-grep `$METAVAR` patterns reach the binary literally (not shell-expanded).
+ *  - an environment-derived command path (PATH-resolved `ast-grep`/`sg`/`npx`)
+ *    cannot inject shell — it's argv[0], never part of the script string
+ *    (CodeQL js/shell-command-injection-from-environment).
+ */
+export function buildBashRunArgs(cmd, allArgs) {
+    return ["-c", '"$0" "$@"', cmd, ...allArgs];
+}
 function sgExcludeArgsForProject(rootDir) {
     return getProjectIgnoreGlobs(rootDir).flatMap((glob) => [
         "--globs",
@@ -265,24 +279,15 @@ export class SgRunner {
             const hasBash = process.env.MSYSTEM || process.env.GIT_SHELL;
             let proc;
             if (isWindows && hasBash) {
-                // Use bash -c with properly escaped command
-                // In bash, use single quotes around arguments containing $ to prevent expansion
-                const escapedArgs = allArgs.map((arg) => {
-                    // For bash, wrap $-containing args in single quotes
-                    if (arg.includes("$")) {
-                        return `'${arg.replace(/'/g, "'\\''")}'`;
-                    }
-                    // For other args with spaces/special chars, use double quotes
-                    if (/[\s"]/.test(arg)) {
-                        return `"${arg.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-                    }
-                    return arg;
-                });
-                const escapedCmd = /[\s"]/g.test(command.cmd)
-                    ? `"${command.cmd.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
-                    : command.cmd;
-                const bashCommand = `${escapedCmd} ${escapedArgs.join(" ")}`;
-                proc = spawn("bash", ["-c", bashCommand], {
+                // Run via bash (Git Bash/MSYS2) so $-metavariables in ast-grep
+                // patterns aren't shell-expanded. Pass the command + args as
+                // POSITIONAL parameters (`"$0"`/`"$@"`) instead of interpolating
+                // them into the -c string: bash re-emits `"$@"` verbatim — no
+                // parameter expansion, no word-splitting — so patterns stay literal
+                // AND an environment-derived command path cannot inject shell
+                // (fixes CodeQL js/shell-command-injection-from-environment). This
+                // also removes the brittle hand-rolled quoting it replaced.
+                proc = spawn("bash", buildBashRunArgs(command.cmd, allArgs), {
                     stdio: ["ignore", "pipe", "pipe"],
                     windowsHide: true,
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "3.8.51",
+	"version": "3.8.52",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {