pi-lens 3.8.70 → 3.8.71

package/CHANGELOG.md

@@ -4,12 +4,36 @@ All notable changes to pi-lens will be documented in this file.
 
 ## [Unreleased]
 
+## [3.8.71] - 2026-07-20
+
 ### Added
 
+- **`ty` (astral-sh/ty) support as an alternative Python language server** (closes #717) — `PythonServer.spawn()` (`clients/lsp/server.ts`) now tries a bare `ty server` on `PATH` after the existing local `pyright-langserver`/`basedpyright-langserver` candidates fail, and before pyright's managed/auto-install fallback. Strictly opt-in and PATH-only: ty is deliberately NOT added to the installer registry (`clients/installer/index.ts`)/`ensureTool`, and the `resolveAndLaunch` call hardcodes `allowInstall: false`, so ty is only ever picked up when a user has already installed it themselves (`uv tool install ty` / `pipx install ty` / `pip install ty`) — it never displaces an already-installed pyright/basedpyright and never becomes the silently auto-installed Python LSP default (that stays pyright). ty's CLI invocation shape differs from pyright/basedpyright's shared `--stdio` flag — it's launched via the `server` subcommand instead — so it gets its own `resolveAndLaunch` call rather than joining the existing `localCandidates` array. No `initializationOptions` payload is sent to ty: it has no stable `pythonPath`-equivalent init option yet (astral-sh/ty#2032) and instead auto-discovers `.venv`/`VIRTUAL_ENV` relative to `cwd`. New tests in `tests/clients/lsp/server-policy.test.ts` cover the ty fallback tier (launched when pyright/basedpyright aren't found locally, `ty server` args, never triggers install, and pyright still wins when found locally).
+- **`/lens-map` command: a human-facing, self-contained interactive HTML project map rendered from the review graph** (closes #679) — a new `clients/lens-map.ts` aggregates the (symbol-level) review graph up to FILE-level nodes and deduped, weighted file→file edges, computes a deterministic force-directed layout (pairwise repulsion + edge-spring attraction + center gravity, seeded from a hash of each file's own path so re-running on an unchanged project reproduces the same map), and renders it to a zero-dependency HTML page — embedded JSON payload + vanilla JS/SVG, no CDN script, no npm deps. Interactions: pan (drag background), zoom (wheel), hover (highlights direct neighbors, dims the rest), click (fixed detail panel: path, symbol count, in/out degree, transitive dependents). Node radius scales with transitive dependents; fill is a neutral brand-blue intensity scale by dependents only (light `#2563eb` family / dark `#60a5fa` family) — complexity-aware coloring is explicitly deferred to #306, noted inline. "external" kind nodes (third-party/stdlib import targets) are excluded from the map; their count is surfaced in the header instead. Test files (per `detectFileRole` from `clients/file-role.ts` — `.test.`/`.spec.`/`__tests__/`/etc. path patterns) are ALSO excluded, along with their edges, and computed BEFORE degree/dependents/truncation ranking so they can never inflate a file's rank or count toward the node cap; their count is surfaced in the header too (`testFileCount`). Compiled twins are merged, not double-rendered: in compile-in-place projects the review graph's import resolution often lands on the compiled `X.js` sibling of an `X.ts` source, so when both exist the compiled node's symbols and ALL its edges remap onto the source node (`.js`→`.ts`/`.tsx`, `.mjs`→`.mts`, `.cjs`→`.cts`; edges that become self-referential after the merge collapse like other same-file edges; compiled files with no source twin — vendored deps, pure-JS projects — are untouched), with the merge count surfaced as `compiledTwinCount` in the header and command output. Untracked-gitignored files are excluded too — the set is computed by asking git itself (`ls-files --others --ignored --exclude-standard`, honoring git's semantic that a TRACKED file is never ignored, so committed vendored files matching an ignore pattern stay on the map; outside a git repo the filter degrades to a no-op), with twin-merge taking precedence over exclusion (an ignored compiled file whose source twin survives is merged, edges preserved, rather than dropped) and the dropped count surfaced as `ignoredFileCount`. The viewer ships four pure client-side interactions (no payload/schema changes, no CSP exceptions): search-to-highlight (case-insensitive substring over file paths, ring + dim-the-rest), a min-edge-weight slider (sub-threshold edges hide; nodes left with zero visible edges fade in place — positions never shift), label culling (labels render only when zoomed past 1.5× or for the top-25 files by transitive dependents), and path tracing (select a node, shift+click — or arm the "trace path" toggle and click — a second node to BFS their connection over UNDIRECTED edges, highlighting the chain; Esc/background-click clears). All four compose through one `recomputeVisibility` pass with documented precedence (trace > search > weight for opacity; culling only affects labels). A graph exceeding `PI_LENS_MAP_MAX_NODES` (default 500) files keeps only the highest-degree ones, with a visible truncation note in the page header. Security: every graph-derived string (file paths) reaches the page ONLY via a `<script type="application/json">` block (with `<`/`>`/`&` escaped to their unicode forms, so no substring can ever break out of the tag) read back and rendered through DOM `textContent`/`createElementNS` client-side — never string-concatenated into HTML markup (the #504-spike XSS-from-repo-content mitigation, since repo file names are attacker-influenceable in cloned repos). Written to `<project data dir>/reports/lens-map.html` (`getProjectDataDir`, never a hardcoded `.pi-lens`), notified via `ctx.ui.notify` with the absolute path — no browser auto-open. Unlike `module_report`'s read-only #256 contract, `/lens-map` DOES build the review graph on a cold cache (`buildOrUpdateGraph`) since the user explicitly asked for a map and a few seconds' build cost is acceptable for this non-hot-path command. Human-only: no agent tool, no MCP mirror. New `tests/clients/lens-map.test.ts` covers aggregation (symbol→file collapse + edge dedup/weighting, external-node exclusion+count, transitive-dependents BFS, degree-ranked truncation), layout (determinism, all-finite coordinates, empty-graph), rendering (script-tag-breakout escaping of a malicious file name, CSP meta + both theme accents present), and an end-to-end `generateLensMap` write against a temp `PILENS_DATA_DIR`.
+- `lens_diagnostic_mark` tool (situational, activate via `pi_lens_activate_tools`): record a disposition for a diagnostics finding — `false-positive` / `suppress` (writes an inline `pi-lens-ignore` comment) / `defer` (session-only) / `flagged` (to fix, tagged in `lens_diagnostics mode=full`). Anchored by content, with the binding strength chosen per disposition — `false-positive` uses a site-specific anchor (rule + normalized message + the flagged line's own content hash, so it re-fires if that line is rewritten); `suppress`/`defer`/`flagged` use an intent-level anchor (rule + normalized message, no line hash) that survives edits elsewhere in the file. Honored by both the per-edit dispatch path and `lens_diagnostics mode=full`. Every mark is also appended to a machine-global NDJSON telemetry log (`~/.pi-lens/dispositions.log`, size-capped via `PI_LENS_DISPOSITION_LOG_MAX_BYTES`, records `previousDisposition` on re-marks and `defer` marks whose in-memory state has no other durable trace — the #181 false-positive rule-tuning signal) and published on pi's shared event bus as `pilens:diagnostic:disposition` (`v: 1`, fire-and-forget, honors the `PI_LENS_BUS_PUBLISH` kill switch) (#690).
+- **`pilens:autofix:start` bus event, symmetric to `pilens:format:start`, so the same in-process listener can also see the `agent_end` actionable-warnings autofix batch before it mutates files** (#684) — follow-up to #673/#674: `clients/runtime-agent-end.ts`'s actionable-warnings autofix batch (gated by `getFlag("lens-actionable-warning-autofix")`) has the identical "runs later, unpredictably" timing shape as deferred formatting (reads a cached report, applies fixes as a batch well after the edit that produced the warnings), but only ever emitted `pilens:files:touched` (`reason: "autofix"`) AFTER the fact. `pilens:autofix:start` (`clients/format-events-publish.ts`, `{v, source, cwd, paths, fileCount, eligibleCount}`) now fires once per batch, right before `applyConservativeActionableWarningFixes` runs, but ONLY when the cached report is confirmed fresh (`checkActionableWarningsReportFresh`) AND has at least one autofix-eligible warning — mirroring `pilens:format:start`'s "only when there's genuine work" gate exactly, so a no-op batch never signals a start. `pipeline.ts`'s synchronous per-edit `runAutofix` (biome/ruff/eslint, awaited inside the `tool_result` hook) isn't deferred and doesn't have this race, so it doesn't get a `start` event.
+- **Two new `pi.events` bus signals so an in-process extension can observe pi-lens's deferred-format queue before it mutates files, not just after** (#673) — `pilens:files:touched` (#482) only reports what changed AFTER deferred formatting at `agent_end` completes; there was no way for a same-process listener (e.g. a review/snapshot controller deriving an immutable candidate tree mid-turn) to know a file was queued for a formatter that hasn't run yet. `pilens:format:queued` (`clients/format-events-publish.ts`) fires once when a file NEWLY enters `RuntimeCoordinator`'s deferred-format pending queue (`{v, source, filePath, cwd, tool}`) — a second edit to an already-queued file before `agent_end` does not re-fire, avoiding spam. `pilens:format:start` fires once at the same moment as the existing `agent_end_deferred_format_start` latency-log phase, with the full pending file list (`{v, source, cwd, paths, fileCount}`), only when there's at least one file queued. Both follow the exact `pilens:files:touched` conventions: versioned frozen-additive payloads, fire-and-forget (bus failures swallowed, `dbg` invoked at most once per event type), logged via `logBusEvent`. This is visibility only — no synchronous flush/barrier API; that remains a separate future feature. `RuntimeCoordinator.deferFormat()` now returns a boolean (new-entry vs re-touch) so its caller (`clients/runtime-tool-result.ts`) knows when to publish.
+- **`lens_diagnostics mode=full` and `lsp_diagnostics`'s batch/directory sweep now cache confirmed per-file LSP results across calls** (#671) — previously `runWorkspaceDiagnostics` re-touched EVERY file through the language server(s) on every call, with zero memory of a prior sweep: calling `mode=full` twice back-to-back with no edits in between paid the full LSP round-trip cost both times. A new persisted cache (`clients/lsp/workspace-diagnostics-cache.ts`, `<project-data-dir>/cache/lsp-workspace-diagnostics.json`) now lets a repeat sweep skip any file that hasn't changed since its last CONFIRMED touch, reusing the same per-file result instead. Invalidation is deliberately layered: (1) the file's own mtime must be unchanged; (2) when the project has a persisted reverse-dependency index (`clients/reverse-deps.ts`, already built by the cascade path), every file it imports must also be unchanged since the entry was recorded — closing the cross-file blind spot where file A's diagnostics can change purely because a dependency B's exported shape changed, with zero edits to A itself (no index available this session falls back to mtime-only, matching the existing cheap-tier `project-diagnostics.json` cache's accepted blind spot). An inconclusive/timed-out/errored touch is NEVER persisted as cacheable — reusing an unconfirmed result as "cached clean" would reintroduce the exact false-clean bug class #571/#630 already fixed for the live path. `runWorkspaceDiagnostics` and `tools/lsp-diagnostics.ts`'s batch/directory sweep (`mapWithConcurrency`) share ONE cache store, keyed by a `scopeKey` fingerprint of what each touch actually covers (client scope + excluded servers) so a file swept by either tool benefits the other's next sweep, without ever cross-serving an entry recorded under a different scope (the workspace sweep excludes opengrep via a separate CLI extractor; `lsp_diagnostics` doesn't). Survives a partial/aborted sweep gracefully — already-completed files' fresh results are still cached, and a corrupt/missing cache file fails open to "touch everything".
+
 ### Changed
 
+- **`release.yml` publishes to npm via OIDC trusted publishing instead of a long-lived `NPM_TOKEN`, and `package.json` declares an `allowScripts` allowlist for npm v12's install-time script review** (closes #737) — follow-up to https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/. The `publish-npm` job now requests a GitHub Actions OIDC token (`permissions.id-token: write`) and runs a bare `npm publish`, no `NODE_AUTH_TOKEN`/`secrets.NPM_TOKEN` involved — the trusted publisher (repo `apmantza/pi-lens`, workflow `release.yml`) was already registered on npmjs.com. The workflow's `has_npm_token` gate is gone entirely (OIDC needs no secret to check for); release/dry-run/smoke-load steps now gate purely on the existing version-tag-missing check. The publish job pins `npm@11.18.0` before installing (`npm install -g npm@11.18.0 --ignore-scripts`) since OIDC trusted publishing needs npm >= 11.5.1 and the Node 22 runner's bundled npm isn't guaranteed new enough — pinned to the latest 11.x rather than 12.x, whose stricter `engines.node` (`^22.22.2 || ^24.15.0 || >=26.0.0`) isn't guaranteed by the workflow's `node-version: 22` pin. Separately, `package.json` gains an `allowScripts` field (the field npm v12's `npm approve-scripts` manages, verified by reading npm's own `docs/content/commands/npm-approve-scripts.md` and `lib/utils/allow-scripts-writer.js` locally rather than guessed) approving the runtime/dev dependencies confirmed (via `npm view <pkg> scripts` and a real `npm approve-scripts --all` run) to have install-time lifecycle scripts: `@ast-grep/cli` (`postinstall`, a direct runtime dependency) plus `@google/genai`/`protobufjs` (transitive through the `@earendil-works/pi-coding-agent` devDependency, needed so the repo's own CI installs — which build `dist/` via `prepare` — don't get flagged). `@ast-grep/napi`, `web-tree-sitter`, `pidusage`, and `@earendil-works/pi-tui` were also audited and have no install-time scripts, so nothing was added for them. README's install section gains a short note on `npm approve-scripts` and git-dependency approval for npm v12 consumers.
+- **Consolidated the hand-duplicated "walk up directories looking for one of a list of config filenames" loop across 4 sites** (closes #680) — `clients/opengrep-config.ts`'s `findLocalOpengrepConfig`, `clients/typos-config.ts`'s `findLocalTyposConfig`, `clients/zizmor-config.ts`'s `findLocalZizmorConfig`, and `clients/sgconfig.ts`'s `findLocalSgconfig` each independently hand-rolled the identical `walkUpDirs` + nested-filename-check loop. New `findLocalToolConfig(startDir, names)` in `clients/path-utils.ts`, alongside the file's other shared walk-up primitives (`walkUpDirs`, `findNearestContaining`, `findNearestMarkerRoot`), is the single source of truth; all 4 call sites are now one-line wrappers over it with their own filename list, keeping their existing public name/signature (so no caller elsewhere needed to change). Pure internal refactor, zero behavior change — deliberately does NOT touch `clients/tool-policy.ts`'s `has*Config` family (different shape: `boolean` return, tool-specific content-sniffing) or `clients/project-lens-config.ts`'s `discoverPiLensProjectConfig` (adds mtime caching), both out of scope per the issue. New unit tests for `findLocalToolConfig` in `tests/clients/path-utils.test.ts`; all 4 migrated sites' existing test suites pass unmodified.
+- **Extracted `index.ts`'s `tool_call` handler (read-guard preflight: LSP auto-touch, read-range tracking/expansion, oldText autopatch, edit-guard block/relocation, pre-write duplicate-export detection) into `clients/runtime-tool-call.ts`** (closes #678) — pure refactor, no behavior change. `tool_call` was the one lifecycle hook whose logic still lived inline in the entry point while its three siblings (`session_start` → `clients/runtime-session.ts`, `tool_result` → `clients/runtime-tool-result.ts`, `turn_end`/`agent_end` → `clients/runtime-turn.ts`/`clients/runtime-agent-end.ts`) had already been extracted; at ~800 lines it was also the largest, and the most safety-critical (it mutates the agent's own edits — relocation/autopatch — before they reach disk), living in the file that's hardest to unit-test directly. New `handleToolCall(deps)` follows the exact same dependency-injection shape as its siblings; `index.ts`'s `pi.on("tool_call", ...)` registration is now a thin call site. Verified line-by-line against the original (diff of the extracted body vs. the pre-extraction source shows only the necessary renames/import-path fixes, no logic changes) plus the full existing test suite (including the dedicated `tests/index-integration.test.ts` `tool_call` coverage) passing unmodified. New `tests/clients/runtime-tool-call.test.ts` unit-tests `handleToolCall` directly against mocked deps (lensEnabled short-circuit, read-guard read recording + LSP auto-touch, zero-read edit block, write-then-edit read-guard interaction, duplicate-export write block).
+- **Consolidated the hand-duplicated "load a JSON cache file, try/catch, version/shape-validate" boilerplate across 7 sites** (closes #676) — `clients/project-diagnostics/cache.ts` (two load functions), `clients/lsp/workspace-diagnostics-cache.ts`, `clients/cache-manager.ts` (three load sites: `readCache`, `isCacheFresh`, `readTurnState`), `clients/cache/rule-cache.ts`, `clients/project-snapshot.ts`, and `clients/session-state-store.ts` each independently wrote the same `JSON.parse(fs.readFileSync(path, "utf-8"))` → structural/version guard → `undefined`/`null`-on-any-throw shape. New `clients/json-cache-read.ts` extracts only the read/parse/try-catch mechanics into `readJsonCache`/`readJsonCacheAsync` (the latter for `session-state-store.ts`'s `fs.promises` call site), taking a `validate(parsed): T | undefined` callback plus an optional `onError` hook for the one site (`CacheManager.readCache`) that logs a read failure rather than silently swallowing it. Every site's own validation logic — including `rule-cache.ts`'s extra `ruleHash` field check, alongside the version check every other site has — is preserved exactly as its `validate` callback; this is pure boilerplate deduplication, not a behavior change. (`clients/generated-artifacts.ts`, listed in the issue, turned out on inspection to have no JSON-cache-read pattern at all — no code changed there.) New `tests/clients/json-cache-read.test.ts` unit-tests the shared helper directly (valid payload, corrupt JSON, valid-but-wrong-shape, missing file, `validate`/`onError` throwing); all pre-existing tests for the migrated sites pass unmodified.
+
 ### Fixed
 
+- **`pilens_health`'s resource footprint no longer reports dead instances from stale instance-registry entries** (closes #735 — observed live during dogfooding: after a `pi` process was hard-killed, `pilens_health` kept reporting its pid as a live instance at 233MB RSS) — `computeResourceFootprint`/`getResourceFootprint` (`clients/instance-registry.ts`) aggregated whatever `~/.pi-lens/instances.json` entries existed, trusting each entry's heartbeat-cached `rssBytes`/`cpuPercent` with no pid-liveness check at all, so a killed/crashed instance kept inflating the headline instance count/RSS/CPU numbers until its entry aged out (up to `STALE_HEARTBEAT_MS`, 6h). Fix: `computeResourceFootprint` now takes an optional `isPidAlive` predicate and drops any instance whose pid it reports dead BEFORE aggregation (both `perInstance` and the totals — `pilens_health`'s text summary derives directly from `totalRssBytes`/`totalCpuPercent`/`instanceCount`, so no separate text-layer fix was needed); `getResourceFootprint` defaults that predicate to the #449/#525 reaper's own `realIsPidAlive` (`clients/instance-reaper.ts`) — reused rather than reimplemented, per that function's own docstring precedent (`clients/lsp-budget.ts`) — and opportunistically (fire-and-forget, best-effort) prunes newly-dead pids' entries from the on-disk registry too, a bonus cleanup layered on top of, not a replacement for, the scheduled reaper sweep. Dropped rather than flagged `stale: true`: unlike heartbeat staleness (which the reaper deliberately treats as "maybe idle-but-alive" and never uses to hide/remove anything), a pid-confirmed-dead instance is unambiguous, and every existing caller already expects a footprint of currently-live instances. No pid-reuse identity check (unlike the reaper's child-pid `matchProcess`): `InstanceEntry` never recorded the host's own command line to verify against (the same gap #525 documented for the reaper's PARENT pid and deliberately left unfixed there), and a health-report false positive is a far smaller blast radius than the reaper's own mistaken-kill risk. Both parameters are optional and default to prior (unfiltered) pure behavior when omitted, so every pre-#735 caller/test is unaffected. New tests in `tests/clients/instance-registry.test.ts`: `computeResourceFootprint` drops a dead-pid instance from both `perInstance` and the totals when `isPidAlive` is supplied, and applies no filtering when it's omitted; `getResourceFootprint` excludes a dead-pid instance end-to-end and opportunistically prunes it from the registry file, while leaving the registry untouched when every pid is alive.
+- **The shared project ignore matcher is now tracked-aware, so a git-tracked file whose name happens to match a `.gitignore`/global ignore pattern is no longer invisible to every scan and to the review graph** (closes #703 — the residual documented-but-out-of-scope gap left by #694/#701) — `getProjectIgnoreMatcher` (`clients/file-utils.ts`) applied ignore *patterns* with no knowledge of what git actually tracks, but git's own rule is that ignore rules only ever apply to UNTRACKED files. Concretely: pi-lens's own tracked `clients/test-runner-client.ts` matches `.gitignore`'s `test-*.ts` pattern (meant for scratch test files) and was silently dropped from every walk — the review graph never parsed it and instead materialized a phantom `clients/test-runner-client.js` node (0 symbols, no content hash) standing in for its 5 real importers, blacking out `who-uses-this`/`blastRadius` for that file. Fix: each `GitignorePattern` is now tagged with the layer it came from (`global`/`gitignore`/`pilens`, precedence order unchanged). A winning positive match from the `global` or `gitignore` layers — both of which emulate git — now inherits git's "a tracked file is never ignored" rule and is rescued via a new async, `git ls-files`-backed tracked-files set (`clients/git-tracked-ignore.ts`'s new `collectTrackedFiles`, mirroring #701's `collectUntrackedIgnoredIds` shape exactly: memoized per-root with a 30s TTL, fail-open to `undefined` on no-git/spawn-failure/timeout). A winning match from the `pilens` layer (`.pi-lens.json`'s `ignore` field) is pi-lens-native intent, not a git emulation, and keeps excluding regardless of tracked status. Since `isIgnored` must stay synchronous and hot (called per file in every walk), the tracked-set lookup is a synchronous read of a snapshot the async fetch populates as a side effect; a new `ProjectIgnoreMatcher.ensureTrackedIndex(): Promise<void>` lets an async walker prime that snapshot ONCE per walk (not per file) before its loop starts. Wired into every async walk entry point with a real loop: `startup-scan.ts` (source-file counting), `language-profile.ts` (warmup language detection), `source-filter.ts`'s `collectSourceFilesAsync` (the shared collector behind the word-index build, `getSourceFilesAsync`, and most background scanners), `pipeline.ts`'s `snapshotProjectFiles` (autofix change detection), and `lsp/index.ts`'s workspace-diagnostics sweep walk. Sync-only consumers (`collectSourceFiles`, `jscpd-client.ts`, `tree-sitter-client.ts`'s structural search, `review-graph/workspace-modules.ts`, `project-scan-policy.ts`, `dispatch/integration.ts`'s per-edit cascade-neighbor check) are left unprimed and degrade to today's pattern-only behavior by design — the seam is opt-in, never silently forced onto a hot synchronous path. `REVIEW_GRAPH_VERSION` bumped `v5` → `v6`: a persisted v5 graph is missing every tracked-but-pattern-matched file's real node and instead carries a phantom compiled-artifact node in its place, so it's rejected and rebuilt clean rather than merged with newly-walked v6 nodes. New `tests/clients/tracked-aware-ignore-matcher.test.ts` (real-git-repo fixtures, following #701's pattern): a tracked file matching a `.gitignore` pattern is rescued once primed and stays excluded when never primed (documents the fail-open default); a `.pi-lens.json` match still excludes a tracked file; an untracked file matching `.gitignore` is unaffected; negation still wins last-match-wins across layers; a non-git directory degrades to pattern-only without throwing; cross-separator (`/` vs `\`) paths resolve to the same verdict; and an end-to-end `collectSourceFilesAsync` walk over a fixture repo includes the tracked pattern-matched file.
+- **The startup scan-context walk no longer re-runs and discards itself on every single `pi` process start in a large monorepo** (closes #699 — bisected and reported by @aaronkyriesenbach, who traced a consistent ~17s-per-startup cost via a package-toggle bisection down to `resolveStartupScanContextAsync()`) — `resolveStartupScanContext(Async)` (`clients/startup-scan.ts`) already early-exited its counting walk as soon as the running count passed `MAX_STARTUP_SOURCE_FILES` (2000; `if (count > limit) return count;`, predating this issue), so the 17s wasn't a missing early exit — it was that nothing ever survived the walk to inform the NEXT process. The interactive full-mode path (`clients/runtime-session.ts`) only reused a `too-many-source-files` verdict when `project-snapshot.json`'s seq-based freshness matched, but the background warmup timer used by every `-p`/`--print` (quick-mode) invocation — the ONLY place a one-shot process ever reaches scan-context, since quick mode returns before the synchronous path touches it — never persisted the verdict at all, for either outcome; a one-shot process exits right after computing it, so the walk (and, per the reporter's bisection, the ~2s warmup-delay `setTimeout` that keeps the process alive to run it) recomputed and discarded the result on every single startup, `--no-lens` included (that flag never reaches the quick-mode gate). Fix: (1) the background warmup now checks `project-snapshot.json` for a still-fresh persisted verdict BEFORE walking, and unconditionally persists whatever it computes (`canWarmCaches` true or false) afterward via the existing `saveRuntimeProjectSnapshot`/`startupScan` field, mirroring the interactive path instead of duplicating a parallel cache file; (2) a new `computedAt` timestamp on `StartupScanContext` plus `isStartupScanVerdictFresh` (TTL-gated via `PI_LENS_STARTUP_SCAN_VERDICT_TTL_MS`, default 24h, lazy-memoized) covers the one case the existing seq-based freshness check can't: a `too-many-source-files` verdict never advances the snapshot's seq on its own (pi-lens writes nothing while `canWarmCaches` is false), so without a TTL a repo that later shrinks below the threshold would stay stuck on a stale negative verdict forever — the interactive full-mode path now applies the same TTL gate. Corrupt/missing cache files fail open via the existing `readJsonCache` plumbing (re-walk, never throw); cache writes are best-effort via `saveRuntimeProjectSnapshot`'s own try/catch, and never block startup. Measured on this repo (742 source files, `canWarmCaches:true`, so the same walk+persist code path the `too-many-source-files` branch shares): a cold in-process walk costs ~3.7s; a second in-process call hits the existing per-process memo at ~0ms; a genuinely separate process reading the persisted verdict off disk (simulating the next `pi` startup) costs ~0.7ms — the 17s monorepo repro itself wasn't reproduced here (no monorepo of that shape available), but the mechanism is identical. New `tests/clients/startup-scan-verdict-cache.test.ts` (TTL getter + env override + memoization, `isStartupScanVerdictFresh` fresh/expired/missing-`computedAt`/non-TTL'd-reasons, `computedAt` stamping, and a pinning test for the pre-existing early-exit-at-limit+1 behavior) and `tests/clients/runtime-session-scan-cache.test.ts` (full `handleSessionStart` integration: cold walk persists and a second call reuses it without re-invoking `resolveStartupScanContext`, an expired verdict re-walks, a corrupt snapshot fails open).
+- **Review graph import resolution now prefers `.ts`/`.tsx` (and `.mts`/`.cts`) source twins over compiled `.js`/`.mjs`/`.cjs` siblings, and node creation is gated against untracked-AND-gitignored files** (closes #694) — on a compile-in-place repo (pi-lens's own build included) EVERY cross-file import edge was landing on the compiled artifact node instead of the source: measured on pi-lens's own graph, `clients/dispatch/types` had 90 import edges / 84 distinct importer files all on `types.js` and **zero** on `types.ts`, blacking out `module_report`'s `blastRadius`/`usedBy`, the impact cascade, and word-index priors for the dispatch system's central type hub. Root cause: both `resolveJsTs` (`clients/review-graph/import-resolvers.ts`, the cold `module_report` path) and `localImportToFile` (`clients/review-graph/builder.ts`, the warm graph-build path) tried the LITERAL specifier path (`./foo.js`) as their FIRST existence-checked candidate — since Node's ESM resolver requires the runtime `.js` extension even for a `.ts` source, that candidate almost always existed on disk (the compiled sibling) and won before the `.ts`/`.tsx` candidates further down the list were ever tried. Fix: a new shared `jsTsCandidatePaths` (import-resolvers.ts) tries the source twin (`.mts` for an `.mjs` specifier, `.cts` for `.cjs`, else `.ts`/`.tsx`) BEFORE the literal/compiled extension, used by both resolvers so the cold and warm paths can never diverge on which twin wins; falls back to the compiled file unchanged when no source twin exists (pure-JS projects, vendored `.js`). Separately, import-resolution-created file nodes (`addJsTsFile`'s local-import target, the tree-sitter `resolveImportToFiles` loop, and cxx `#include` targets) previously had NO ignore-awareness at all — an untracked-AND-gitignored build artifact with no surviving source twin still became a first-class graph node. New `clients/git-tracked-ignore.ts` (extracted from #679's `/lens-map`, which now re-uses it too) computes the untracked-AND-ignored id set via `git ls-files --others --ignored --exclude-standard` — respecting THE critical git semantic that a tracked file is never "ignored" even when a `.gitignore` pattern matches it (pi-lens's own tracked `clients/deps/*.js` vendored sources match the repo's `*.js` pattern and must stay graph nodes) — memoized per-cwd with a 30s time bound so the hot per-edit/cascade rebuild path shares one `git` spawn instead of paying for one per file/per edit; any resolution failure (non-git cwd, git absent) degrades to `undefined` and every caller skips the filter rather than guessing via a tracked-unaware pattern matcher. `REVIEW_GRAPH_VERSION` bumped `"v4"` → `"v5"` (same safe-rebuild pattern as the v2→v3/#260 and v3→v4/#655 bumps): a persisted v4 graph from a compile-in-place project has edges materialized on compiled artifact nodes throughout, so it's rejected and rebuilt clean rather than merged with newly-built v5 edges. Residual, documented but not fixed here: the INITIAL file walk (`getGraphSourceFiles` → `collectProjectSourceFilesAsync` → the pattern-only `getProjectIgnoreMatcher`) is still tracked-unaware and can wrongly exclude a tracked file whose name matches an ignore pattern (e.g. a tracked `test-*.ts` file matching a `test-*.ts` ignore rule) — fixing that needs the same async tracked-check threaded through a widely-shared, currently-synchronous matcher, which is out of scope for this change. Verified on pi-lens's own graph: `clients/dispatch/types.ts` now carries all 90 import edges / 84 importers (was 0), `types.js` carries 0 (was 90), and `computeTransitiveImpact` from `types.ts` now returns 130 dependents (was an empty/blacked-out result). New tests: `tests/clients/review-graph/import-resolvers.test.ts` (twin preference across `.js`/`.mjs`/`.cjs`, fallback-when-no-twin, extensionless specifiers); `tests/clients/git-tracked-ignore.test.ts` (tracked-vs-ignored set computation, no-git degrade, TTL memoization); `tests/clients/review-graph.service.test.ts` (real-git-repo ignore-gated node creation — an ignored untracked target never becomes a node while a tracked file matching the same pattern does; the v4→v5 migration rebuild).
+- **Scan-provenance labels no longer poison a diagnostic's dedup identity, and the workspace sweep now honors ast-grep's `skipTestFiles` gate like the per-edit path does** (closes #692) — found via live dogfooding (`pi-drykiss`): a `lens_diagnostics mode=full` run reported 726 warnings, largely the same findings twice. Root cause: `convertLspDiagnostics` (`clients/dispatch/utils/lsp-diagnostics.ts`) baked a caller-supplied `source` option straight into `rule` (`${source}:${code}`) — three "reconcile this scan's fresh results into widget state" call sites (`tools/lens-diagnostics.ts`'s footer reconcile, `tools/lsp-diagnostics.ts`'s footer reconcile) passed a scan-provenance label (`"lens_diagnostics_full"`, `"lsp_diagnostics"`) there, silently clobbering the diagnostic's REAL source (e.g. `ast-grep`) in the field that defines its identity. A per-edit write of the same finding kept rule `ast-grep:<id>`, so `normalizeRuleForDedup`'s prefix strip (which only knows about `ast-grep:`) matched one write but not the other, producing two divergent dedup keys for one finding — and the same corruption broke inline `pi-lens-ignore: <id>` suppression for scan-written entries and lost their tool provenance (`tool` stayed `"lsp"` instead of e.g. `"ast-grep"`, since the per-edit-only aux re-tag loop never ran on the scan path). Fix: the `source` override is gone from `rule` derivation entirely (`rule` now always comes from the diagnostic's own `d.source ?? tool`); scan provenance, where still wanted, now lives in a new dedicated `Diagnostic.scanOrigin` field that is purely informational and never read by identity/dedup/suppression logic. The per-edit dispatch runner's (`clients/dispatch/runners/lsp.ts`) aux re-tag logic (tool id + semantic policy + defect class + native-suppression + `skipTestFiles`) is now a shared helper, `retagAuxiliaryDiagnostics` (`clients/dispatch/auxiliary-lsp.ts`), used by both the per-edit path and the two scan-reconcile call sites, so a scan-written aux finding gets identical treatment instead of keeping tool `"lsp"`. Separately, `clients/lsp/index.ts`'s workspace sweep applied `applyAuxiliarySuppressions` to every file's results but never passed a `fileRole`, so ast-grep's `skipTestFiles` gate (#687/#688 — added only to the per-edit merge loop) never applied to a `mode=full` sweep, re-surfacing every ast-grep finding on `*.test.ts` files wholesale; `applyAuxiliarySuppressions` now takes an optional `{fileRole}` third argument (all existing 2-arg callers unaffected), wired at the sweep's call site via `detectFileRole`, and the same gap was found and fixed in `tools/lsp-diagnostics.ts`'s own standalone-query suppression call via grep-siblings. Three `convertLspDiagnostics(..., {source: "cascade"})` call sites in `clients/dispatch/integration.ts` (cascade neighbor diagnostics — ephemeral display output, never reconciled into persisted widget/dedup state) had the override dropped rather than migrated, since it had no remaining purpose once identity no longer reads it. New tests: `tests/clients/dispatch/utils/lsp-diagnostics.test.ts` (dedup-key/rule equality between per-edit and scan-origin conversions of the same finding, `scanOrigin` present only on the scan path and never leaking into `rule`/`id`); `tests/clients/dispatch/auxiliary-lsp.test.ts` gains `retagAuxiliaryDiagnostics` coverage (matches the per-edit runner's prior behavior exactly) and `applyAuxiliarySuppressions`'s new `fileRole` gate; `tests/clients/dispatch/inline-suppressions.test.ts` gains a round-trip suppression test for a scan-written entry.
+- **`oxlint` no longer skips test files** (refs #576) — its `skipTestFiles: true` (bare, no confirmed-FP rationale attached — the original comment was a generic "test files often use patterns that trigger false positives" assumption, unlike the confirmed-FP class that justifies ast-grep's skip, see #687) was inconsistent with every other correctness-oriented runner in the dispatch set: type checkers (mypy/phpstan/detekt/dart-analyze/dotnet-build/javac/etc.) and the primary language servers (typescript-lsp/pyright-lsp/rust-lsp) never skip test files, since a real correctness bug in a test is still a bug. oxlint catches genuine correctness issues, not just style, so it now follows that precedent. New test in `tests/clients/dispatch/runners/oxlint.test.ts` asserts `skipTestFiles: false`.
+- **`no-javascript-url` ast-grep rule no longer flags a `javascript:` string literal used as adversarial test input, and ast-grep's own `skipTestFiles` policy now survives when its LSP surface (not just the in-process napi runner) is active** (closes #687) — two related false-positive fixes found via the same live dogfooding pass on `pi-free` that surfaced #686. (1) `rules/ast-grep-rules/rules/no-javascript-url(-js).yml` matched any string literal starting with `"javascript:`, with no check on how it was used — `expect(openBrowser("javascript:alert(1)")).toBe(false)` (a test asserting the guard REJECTS the URL) matched identically to a real `a.href = "javascript:..."` sink. Fix: exclude literals whose nearest enclosing call is `expect`/`it`/`test`/`describe` (or a `.only`/`.skip`/`.each` variant) — the existing bare `const u = "javascript:..."` invalid fixture (flagged regardless of downstream use) is intentionally preserved, so this narrows only the test-framework-wrapped case, not the rule's broader intent. (2) `clients/dispatch/runners/ast-grep-napi.ts` already declares `skipTestFiles: true`, but that only applies to the in-process napi fallback runner — when the ast-grep LSP binary is installed (the common path), that runner skips entirely in favor of `clients/dispatch/runners/lsp.ts`'s auxiliary-diagnostic merge (`clients/dispatch/auxiliary-lsp.ts`'s `AUXILIARY_LSP_PROFILES`), which had no test-file gating at all — confirmed live: `cline-xml-bridge.test.ts`/`open-browser.test.ts` (pi-free) both got ast-grep findings despite being test files. New `AuxiliaryLspProfile.skipTestFiles` field, set only on the `ast-grep` profile (opengrep/zizmor/typos keep running on test files — a hardcoded secret or typo in a test fixture is still worth flagging), gated in `lsp.ts`'s merge loop on `ctx.fileRole === "test"`. New/updated tests: `no-javascript-url(-js)-test.yml` fixtures for the `expect`/`it`/`test.each` cases; `tests/clients/dispatch/auxiliary-lsp.test.ts` asserts only the ast-grep profile sets `skipTestFiles`; `tests/clients/dispatch/runners/runner-status-semantics.test.ts` covers the merge loop dropping ast-grep (but not opengrep) findings on a `fileRole: "test"` file, and keeping them on a regular source file.
+- **`find-import-file-without-extension` ast-grep rule no longer flags bare/scoped package specifiers with a subpath** — found via live dogfooding on 2026-07-16 (no separate tracking issue; a contained rule fix). The rule's regex only checked whether a string's final path segment lacked a file extension; it never checked whether the string was actually a RELATIVE import (`./`/`../`) at all. A package specifier with a subpath — `@earendil-works/pi-ai/compat`, `lodash/debounce` — has a `/` before its final segment too, so it matched the identical shape as a genuinely broken relative import like `./utils`. The existing test fixture only covered a slash-less bare specifier (`"package"`), never a scoped/deep one, so the gap went unnoticed. Fix: `rules/ast-grep-rules/rules/find-import-file-without-extension.yml` now requires the string to start with `./` or `../` (`^\.\.?/`) before applying the missing-extension check. New fixtures cover scoped (`@scope/pkg/sub`), deep bare (`lodash/debounce`), and parent-relative (`../sibling/util`) cases; all 251 ast-grep rule-test fixtures still pass.
+- **Cold LSP servers now actually get their full warm-up budget instead of being silently capped at their normal per-edit timeout** — found via live dogfooding on 2026-07-15, immediately after #667/#668's `ensureWarmForSweep` shipped (no separate tracking issue filed; this is a direct regression-in-effect follow-up to that PR, referenced here rather than under a new issue number). `ensureWarmForSweep` (`clients/lsp/index.ts`) is supposed to give a genuinely cold server (mid-launch, no index built yet) a generous one-time budget to become ready — it defaults to `warmupTimeoutMs()` (20000ms) and passes that as `touchFile`'s `maxClientWaitMs`/`maxDiagnosticsWaitMs`. But `touchFile`'s `perServerTimeout` resolves that caller cap as a CEILING (`Math.min(callerCap, strategy.aggregateWaitMs)`) — deliberate and correct for the normal per-edit dispatch path (#242, so a slow strategy can't blow past the pipeline's cap), but exactly backwards for a cold warm-up call, which needs MORE time than the server's normal warm-state budget, not less. The effective warm-up deadline silently collapsed to whatever the server's steady-state `aggregateWaitMs` is (e.g. 1000ms for typescript) regardless of the 20000ms actually requested — confirmed against live logs (`lsp_sweep_warmup_start timeoutMs:20000` immediately followed by `lsp_diagnostics_timeout ... timeoutMs:1000 durationMs:1015`), defeating the warm-up feature entirely for any server whose normal per-edit budget is short. Fix: a new `LSPTouchFileOptions.warmupOverride` flag, set only by `ensureWarmForSweep`'s own `touchFile` call, makes `perServerTimeout` treat the caller cap as a FLOOR instead (`Math.max(callerCap, strategyWait)`) — every other caller (per-edit dispatch, cascade touches) leaves it unset and keeps the exact pre-existing ceiling-only semantics. New regression test in `tests/clients/lsp/sweep-warmup.test.ts` asserts a cold server's `waitForDiagnostics` call actually receives the full requested 20000ms budget, not typescript's 1000ms `aggregateWaitMs`.
+
 ## [3.8.70] - 2026-07-14
 
 ### Added

package/README.md

@@ -18,6 +18,10 @@ pi-lens gives AI coding agents fast, language-aware feedback while they write/ed
 - Review-graph intelligence for supported languages via bundled tree-sitter WASMs
 - Ranked identifier search (`symbol_search`) over an always-warm word index,
   feeding the discovery funnel (symbol_search → module_report → read_symbol)
+- Diagnostic triage (`lens_diagnostic_mark`): findings can be marked
+  false-positive, suppressed in source, deferred, or flagged-to-fix — honored
+  across all surfaces
+- `/lens-map` — interactive HTML dependency map of the project
 - Read-guard and edit-autopatch support to reduce bad edits
 - Background security/dependency scans for opted-in projects
 
@@ -33,6 +37,14 @@ Or from git:
 pi install git:github.com/apmantza/pi-lens
 ```
 
+> **npm v12 users:** dependency lifecycle scripts (e.g. `@ast-grep/cli`'s
+> `postinstall`) now require explicit approval — if `npm install` warns about
+> unreviewed install scripts, review and allow them with
+> `npm approve-scripts`, or trust the `allowScripts` entries already declared
+> in this package's `package.json`. Installing from a git source (`pi install
+> git:...` / `pi update --extension git:...`) may similarly prompt for
+> git-dependency approval; accept it to let the `prepare` build step run.
+
 ## Documentation
 
 - [Agent tools](docs/agent-tools.md) — pi tool names, scopes, and arguments
@@ -42,6 +54,8 @@ pi install git:github.com/apmantza/pi-lens
 - [Word index](docs/word-index.md) — identifier search (`symbol_search`) and
   the discovery funnel
 - [Tools and commands](docs/tools.md) — runtime flags and slash commands
+- [Diagnostic dispositions](docs/dispositions.md) — triage: false-positive,
+  suppress, defer, flagged-to-fix
 - [Configuration](docs/globalconfig.md) — global and project config files
 - [Environment variables](docs/env_variables.md) — common env vars and full
   reference link
@@ -170,6 +184,8 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/xificurC"><img src="https://avatars.githubusercontent.com/u/4800719?v=4" width="100px;" alt=""/><br /><sub><b>Peter Nagy</b></sub></a><br /><a href="#bug-xificurC" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/orest-tokovenko-block"><img src="https://avatars.githubusercontent.com/u/190554467?v=4" width="100px;" alt=""/><br /><sub><b>Orest Tokovenko</b></sub></a><br /><a href="#bug-orest-tokovenko-block" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://eisterman.dev/"><img src="https://avatars.githubusercontent.com/u/3028953?v=4" width="100px;" alt=""/><br /><sub><b>Federico Pasqua</b></sub></a><br /><a href="#bug-eisterman" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ymek"><img src="https://avatars.githubusercontent.com/u/300569?v=4" width="100px;" alt=""/><br /><sub><b>Myke Stubbs</b></sub></a><br /><a href="#code-ymek" title="Code">💻</a> <a href="#bug-ymek" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/black-snow"><img src="https://avatars.githubusercontent.com/u/579733?v=4" width="100px;" alt=""/><br /><sub><b>Ronald</b></sub></a><br /><a href="#bug-black-snow" title="Bug reports">🐛</a></td>
     </tr>
 </tbody>
 </table>

package/dist/clients/bus-events-logger.js

@@ -1,14 +1,16 @@
 /**
  * Persistent NDJSON trace of `pi.events` bus publish attempts
- * (`pilens:files:touched` #482 / `pilens:diagnostics` #502).
+ * (`pilens:files:touched` #482 / `pilens:diagnostics` #502 /
+ * `pilens:format:queued` + `pilens:format:start` #673).
  *
- * Both producers (clients/bus-publish.ts, clients/diagnostics-publish.ts) are
- * fire-and-forget: on failure or on a structural no-op (never wired, kill
- * switch off) they only invoke an optional `dbg` callback, which varies by
- * host and is a documented no-op in the MCP host (clients/mcp/session.ts's
- * `dbg: noop`). That leaves bus-publish outcomes invisible in exactly the
- * context where they matter most — same failure shape as the #544 MCP
- * session_start incident this repo already fixed once.
+ * All four producers (clients/bus-publish.ts, clients/diagnostics-publish.ts,
+ * clients/format-events-publish.ts) are fire-and-forget: on failure or on a
+ * structural no-op (never wired, kill switch off) they only invoke an
+ * optional `dbg` callback, which varies by host and is a documented no-op in
+ * the MCP host (clients/mcp/session.ts's `dbg: noop`). That leaves
+ * bus-publish outcomes invisible in exactly the context where they matter
+ * most — same failure shape as the #544 MCP session_start incident this repo
+ * already fixed once.
  *
  * This module gives bus events the same durable trace every other pi-lens
  * subsystem already has (latency.log, cascade.log, read-guard.log, ...) —

package/dist/clients/cache/rule-cache.js

@@ -8,6 +8,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "../file-utils.js";
+import { readJsonCache } from "../json-cache-read.js";
 const CACHE_VERSION = "v3";
 export class RuleCache {
     cacheFile;
@@ -36,12 +37,15 @@ export class RuleCache {
             this.ensureCacheDir();
             if (!fs.existsSync(this.cacheFile))
                 return null;
-            const cached = JSON.parse(fs.readFileSync(this.cacheFile, "utf-8"));
             const currentHash = this.computeRuleHash(ruleFiles);
-            if (cached.version !== CACHE_VERSION || cached.ruleHash !== currentHash) {
-                return null; // Cache invalid
-            }
-            return cached;
+            const cached = readJsonCache(this.cacheFile, (parsed) => {
+                const entry = parsed;
+                if (entry.version !== CACHE_VERSION || entry.ruleHash !== currentHash) {
+                    return undefined; // Cache invalid
+                }
+                return entry;
+            });
+            return cached ?? null;
         }
         catch {
             return null;

package/dist/clients/cache-manager.js

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
+import { readJsonCache } from "./json-cache-read.js";
 import { normalizeMapKey } from "./path-utils.js";
 // --- Defaults ---
 const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 minutes
@@ -72,13 +73,20 @@ export class CacheManager {
             return null;
         }
         try {
-            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+            const onReadError = (err) => {
+                this.log(`Cache read error: ${scanner} — ${err}`);
+            };
+            const meta = readJsonCache(metaPath, (parsed) => parsed, onReadError);
+            if (meta === undefined)
+                return null;
             const age = Date.now() - new Date(meta.timestamp).getTime();
             if (age > maxAgeMs) {
                 this.log(`Cache stale: ${scanner} (age: ${Math.round(age / 1000)}s, max: ${maxAgeMs / 1000}s)`);
                 return null;
             }
-            const data = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+            const data = readJsonCache(cachePath, (parsed) => parsed, onReadError);
+            if (data === undefined)
+                return null;
             this.log(`Cache hit: ${scanner} (age: ${Math.round(age / 1000)}s)`);
             return { data, meta };
         }
@@ -111,7 +119,9 @@ export class CacheManager {
         if (!fs.existsSync(metaPath))
             return false;
         try {
-            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+            const meta = readJsonCache(metaPath, (parsed) => parsed);
+            if (meta === undefined)
+                return false;
             const age = Date.now() - new Date(meta.timestamp).getTime();
             return age <= maxAgeMs;
         }
@@ -150,16 +160,12 @@ export class CacheManager {
                 lastUpdated: new Date().toISOString(),
             };
         }
-        try {
-            return JSON.parse(fs.readFileSync(statePath, "utf-8"));
-        }
-        catch {
-            return {
-                ...DEFAULT_TURN_STATE,
-                files: {},
-                lastUpdated: new Date().toISOString(),
-            };
-        }
+        const state = readJsonCache(statePath, (parsed) => parsed);
+        return (state ?? {
+            ...DEFAULT_TURN_STATE,
+            files: {},
+            lastUpdated: new Date().toISOString(),
+        });
     }
     /**
      * Write turn state.

package/dist/clients/diagnostic-dispositions.js

@@ -0,0 +1,298 @@
+/**
+ * Agent+user disposition layer over dispatch diagnostics (#690, unifying #181/
+ * #503/#504's discussion). Four dispositions:
+ *
+ *   false-positive — the rule misfired. Project-persistent, routed nowhere
+ *                     special yet (telemetry hookup is a fast-follow).
+ *   suppress       — real finding, deliberate policy not to fix. Persistent,
+ *                     but the mechanism is an inline `pi-lens-ignore` comment
+ *                     written into the source (see suppress-writer.ts), not
+ *                     just a store entry — portable, git-visible, discoverable
+ *                     without pi-lens's own store. The store entry here is an
+ *                     audit-trail mirror, not the enforcement point.
+ *   defer          — fix later, not now. Session-ephemeral: held in memory
+ *                     only, so it naturally resurfaces on process restart —
+ *                     never persisted, never needs pruning.
+ *   flagged        — user wants the agent to fix this. Persistent until
+ *                     resolved; surfaced through the existing lens_diagnostics
+ *                     query (tagged), not a separate file/tool the agent has
+ *                     to separately poll.
+ *
+ * Anchoring: TWO flavors, chosen per-disposition because each one binds to a
+ * different thing conceptually:
+ *
+ *   STRICT ("dd:" prefix) — relativeFile|tool|rule|normalizedMessage|
+ *     lineContentHash(diagnostic's own line). Used ONLY for false-positive: a
+ *     false-positive judgment is about THIS specific piece of code — if the
+ *     line is rewritten, the rule earned a fresh chance to fire on the new
+ *     content, so the mark should NOT follow it. Reuses read-guard's
+ *     lineContentHash so a no-op formatter/whitespace pass doesn't rot the
+ *     anchor, while a semantic edit to the flagged line correctly invalidates
+ *     it.
+ *   WEAK ("ddw:" prefix) — relativeFile|tool|rule|normalizedMessage, no line
+ *     hash at all. Used for defer, flagged, and suppress: these are
+ *     intent-level judgments ("I'll get to this", "fix this", "policy says
+ *     don't") about a finding identity, not about one exact line's bytes —
+ *     they must survive incidental edits elsewhere on the flagged line
+ *     (reformatting, a nearby rename) without silently dropping the mark.
+ *     suppress's real enforcement is the inline comment (see
+ *     suppress-writer.ts) which travels with the code by construction; the
+ *     weak-anchored store entry is just an audit mirror plus a second,
+ *     belt-and-braces filter.
+ *
+ * Distinct prefixes ("dd:" vs "ddw:") keep the two id spaces from ever
+ * colliding in the same store.
+ *
+ * Content is hashed only from the diagnostic's own line (for the strict
+ * anchor), not a surrounding window as #181's original sketch considered.
+ * Two diagnostics on the same file/tool/rule/message whose flagged line
+ * happens to have identical content collide on the SAME strict anchor —
+ * deliberately: identical content at the same rule/message is a semantically
+ * equivalent finding, so marking one intentionally marks all of them (e.g. a
+ * copy-pasted line repeated a few times in the same file). If that
+ * assumption proves wrong in practice, a surrounding-window hash can be
+ * layered on later without changing the store shape.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { logDispositionEvent } from "./disposition-logger.js";
+import { publishDisposition } from "./disposition-publish.js";
+import { getProjectDataDir } from "./file-utils.js";
+import { normalizeMapKey } from "./path-utils.js";
+import { lineContentHash } from "./read-guard.js";
+// "defer" is session-ephemeral by design (#690) — held only in memory so it
+// resurfaces for free on the next process run, with no expiry/pruning logic
+// needed. Stores WEAK anchors (see module doc) so a deferred finding stays
+// hidden all session even if the flagged line itself is edited.
+const deferredThisSession = new Set();
+function normalizeMessage(message) {
+    return message.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function relativeFile(filePath, cwd) {
+    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
+    return rel && !rel.startsWith("..") ? rel : normalizeMapKey(filePath);
+}
+/** Site-specific anchor — see module doc. Used only for false-positive. */
+export function computeStrictAnchor(args) {
+    const lines = args.content?.split(/\r?\n/);
+    const lineText = args.line !== undefined && lines ? (lines[args.line - 1] ?? "") : "";
+    const parts = [
+        relativeFile(args.filePath, args.cwd),
+        args.tool ?? "",
+        args.rule ?? "",
+        normalizeMessage(args.message),
+        lineContentHash(lineText),
+    ];
+    return `dd:${createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 12)}`;
+}
+/** Intent-level anchor — see module doc. Used for defer/flagged/suppress. */
+export function computeWeakAnchor(args) {
+    const parts = [
+        relativeFile(args.filePath, args.cwd),
+        args.tool ?? "",
+        args.rule ?? "",
+        normalizeMessage(args.message),
+    ];
+    return `ddw:${createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 12)}`;
+}
+/** Both anchors a stored/filtered diagnostic would compute — the one shared
+ * derivation both the dispatch-pipeline filter and lens-diagnostics' flagged
+ * tag lookup must use so a mark and a fresh diagnostic converge on the same
+ * ids. */
+export function anchorsForDiagnostic(cwd, filePath, diagnostic, content) {
+    const args = {
+        cwd,
+        filePath,
+        tool: diagnostic.tool,
+        rule: diagnostic.rule,
+        message: diagnostic.message,
+        line: diagnostic.line,
+        content,
+    };
+    return { strict: computeStrictAnchor(args), weak: computeWeakAnchor(args) };
+}
+function statePath(cwd) {
+    return path.join(getProjectDataDir(cwd), "cache", "diagnostic-dispositions.json");
+}
+let stateCache = null;
+function readState(cwd) {
+    const p = statePath(cwd);
+    let stat;
+    try {
+        stat = fs.statSync(p);
+    }
+    catch {
+        if (stateCache && stateCache.path === p && stateCache.missing) {
+            return stateCache.state;
+        }
+        const empty = {};
+        stateCache = { path: p, missing: true, mtimeMs: -1, size: -1, state: empty };
+        return empty;
+    }
+    if (stateCache &&
+        stateCache.path === p &&
+        !stateCache.missing &&
+        stateCache.mtimeMs === stat.mtimeMs &&
+        stateCache.size === stat.size) {
+        return stateCache.state;
+    }
+    let state;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+        state =
+            parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        state = {};
+    }
+    stateCache = {
+        path: p,
+        missing: false,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        state,
+    };
+    return state;
+}
+function writeState(cwd, state) {
+    const p = statePath(cwd);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(state, null, 2));
+    // Refresh the cache from the write we just did instead of invalidating it —
+    // avoids an immediate re-stat+re-parse of the file we already have in hand,
+    // and guards against coarse filesystem mtime granularity making a
+    // read-immediately-after-write look like a cache hit on stale data.
+    const stat = fs.statSync(p);
+    stateCache = {
+        path: p,
+        missing: false,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        state,
+    };
+}
+/** Test-only escape hatch — the state cache is module-level, so tests that
+ * write the store file out-of-band (or across separate cwds sharing a stat
+ * coincidence) need to reset it between cases. */
+export function _resetStateCacheForTests() {
+    stateCache = null;
+}
+/** Fire-and-forget mark telemetry (see markDisposition's doc): the NDJSON log
+ * entry (project-relative path — rule-tuning data, not machine layout) and
+ * the bus event (absolute normalized path — in-process consumers navigate).
+ * Neither can throw into the mark path; both are already internally
+ * fail-safe, but the try/catch keeps a future regression in either from
+ * breaking a mark. */
+function emitMarkTelemetry(cwd, target, disposition, anchor, reason, existing) {
+    try {
+        logDispositionEvent({
+            event: "mark",
+            disposition,
+            tool: target.tool,
+            rule: target.rule,
+            filePath: relativeFile(target.filePath, cwd),
+            line: target.line,
+            reason,
+            anchor,
+            previousDisposition: existing?.disposition,
+        });
+        publishDisposition({
+            cwd,
+            filePath: target.filePath,
+            disposition,
+            tool: target.tool,
+            rule: target.rule,
+            line: target.line,
+            anchor,
+            reason,
+        });
+    }
+    catch {
+        // never let telemetry break a mark
+    }
+}
+/**
+ * Record a disposition. Picks the anchor flavor per-disposition (see module
+ * doc): strict for false-positive, weak for everything else. Returns the
+ * anchor actually used, so callers (the mark tool) can report/verify it.
+ *
+ * This is THE single choke point for mark telemetry — the NDJSON log
+ * (disposition-logger.ts, #181's FP-rule-tuning signal) and the
+ * `pilens:diagnostic:disposition` bus event (disposition-publish.ts) both
+ * hang off it, so the agent tool and any future UI caller are covered without
+ * per-caller wiring.
+ */
+export function markDisposition(cwd, target, disposition, reason) {
+    const anchor = disposition === "false-positive"
+        ? computeStrictAnchor(target)
+        : computeWeakAnchor(target);
+    // Captured for BOTH branches: a defer never writes the store, but a store
+    // entry can already exist at the same weak anchor (a prior flagged/suppress
+    // mark) — the log should record what this mark shadowed either way.
+    const existing = readState(cwd).dispositions?.[anchor];
+    emitMarkTelemetry(cwd, target, disposition, anchor, reason, existing);
+    if (disposition === "defer") {
+        deferredThisSession.add(anchor);
+        return anchor;
+    }
+    const state = readState(cwd);
+    state.dispositions ??= {};
+    const now = new Date().toISOString();
+    const capturesFixContext = disposition === "flagged";
+    const lineText = capturesFixContext
+        ? (target.content?.split(/\r?\n/)[target.line !== undefined ? target.line - 1 : -1] ?? existing?.lineText)?.trim()
+        : existing?.lineText;
+    state.dispositions[anchor] = {
+        disposition,
+        reason: reason ?? existing?.reason,
+        createdAt: existing?.createdAt ?? now,
+        lastSeenAt: now,
+        line: capturesFixContext ? (target.line ?? existing?.line) : existing?.line,
+        lineText,
+    };
+    writeState(cwd, state);
+    return anchor;
+}
+export function getDisposition(cwd, anchor) {
+    return readState(cwd).dispositions?.[anchor];
+}
+export function isDeferredThisSession(anchor) {
+    return deferredThisSession.has(anchor);
+}
+/** Test-only escape hatch — defer state is module-level (one process = one
+ * session), so tests need to reset it between cases. */
+export function _resetDeferredForTests() {
+    deferredThisSession.clear();
+}
+/**
+ * Drop diagnostics disposed false-positive/suppress, or deferred this session,
+ * from `diagnostics`. `flagged` diagnostics are kept as-is — callers that want
+ * to surface the flag (e.g. lens_diagnostics' rendering) look it up separately
+ * via getDisposition on the WEAK anchor (anchorsForDiagnostic(...).weak).
+ *
+ * Computes both anchors per diagnostic (cheap — same hash primitive, twice)
+ * since false-positive is keyed strict while defer/suppress are keyed weak;
+ * see module doc for why each disposition binds the way it does.
+ */
+export function applyDispositions(diagnostics, cwd, filePath, content) {
+    if (!diagnostics.length)
+        return diagnostics;
+    const dispositions = readState(cwd).dispositions;
+    if (!dispositions && deferredThisSession.size === 0)
+        return diagnostics;
+    return diagnostics.filter((d) => {
+        const { strict, weak } = anchorsForDiagnostic(cwd, filePath, d, content);
+        if (deferredThisSession.has(weak))
+            return false;
+        if (dispositions?.[strict]?.disposition === "false-positive")
+            return false;
+        // Belt-and-braces: the inline `pi-lens-ignore` comment is the real
+        // suppress enforcement (see suppress-writer.ts) and normally already
+        // dropped this finding upstream via applyInlineSuppressions. This is a
+        // harmless second cover for the store-only audit trail case.
+        if (dispositions?.[weak]?.disposition === "suppress")
+            return false;
+        return true;
+    });
+}