@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/knip-client.js

@@ -8,11 +8,14 @@
  * Requires: npm install -D knip
  * Docs: https://knip.dev/
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
 import { findNearestMarkerRoot } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { createAvailabilityChecker, findManagedNodeToolBinary, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
+import { createAvailabilityLatch, describeUnavailability, } from "./dispatch/runners/utils/availability-policy.js";
 const EMPTY_RESULT = {
     success: false,
     issues: [],
@@ -56,7 +59,18 @@ export function readOverridePinnedPackageNames(targetDir) {
 }
 // --- Client ---
 export class KnipClient {
-    knipAvailable = null;
+    knipAvailability = createAvailabilityChecker("knip", ".cmd", ["--version"], {
+        environment: (cwd) => getManagedToolEnvironment("knip", cwd),
+        unclassifiedFailureOutcome: "missing",
+        fastPath: () => findManagedNodeToolBinary("knip"),
+    });
+    /**
+     * Client-side memo. Only a DURABLE verdict is latched — a transient probe
+     * failure expires, so an installed knip becomes available again without a
+     * host restart (#1467).
+     */
+    availabilityLatch = createAvailabilityLatch();
+    knipCommand = "knip";
     ensureInFlight = null;
     log;
     /**
@@ -75,7 +89,7 @@ export class KnipClient {
     inFlight = new Map();
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[knip] ${msg}`)
+            ? createSubsystemLogger("knip")
             : () => { };
     }
     /**
@@ -97,12 +111,17 @@ export class KnipClient {
         return findNearestMarkerRoot(startDir, ["package.json", "knip.json", "knip.ts", "knip.config.js", "knip.config.ts"], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
     /**
-     * Check if knip CLI is available, auto-install if not
+     * Check if knip CLI is available, auto-install if not.
+     *
+     * The memo returns `null` when the last verdict was transient and its
+     * cooldown has expired, which re-enters the probe. That is the difference
+     * between "knip is missing" (a fact worth caching) and "the probe timed out"
+     * (a moment worth retrying).
      */
     async ensureAvailable() {
-        // Fast path: already checked
-        if (this.knipAvailable !== null)
-            return this.knipAvailable;
+        const memo = this.availabilityLatch.read();
+        if (memo !== null)
+            return memo;
         if (this.ensureInFlight)
             return this.ensureInFlight;
         this.ensureInFlight = this.doEnsureAvailable();
@@ -114,27 +133,40 @@ export class KnipClient {
         }
     }
     async doEnsureAvailable() {
-        // Check if available in PATH (fast)
-        const pathResult = await safeSpawnAsync("knip", ["--version"], {
-            timeout: 5000,
-        });
-        if (!pathResult.error && pathResult.status === 0) {
-            this.knipAvailable = true;
-            this.log("Knip found in PATH");
+        const cwd = process.cwd();
+        const resolved = await resolveAvailableOrInstall(this.knipAvailability, "knip", cwd);
+        if (resolved !== null) {
+            this.knipCommand = resolved;
+            this.availabilityLatch.noteAvailable();
             return true;
         }
-        // Auto-install via pi-lens installer
-        this.log("Knip not found, attempting auto-install...");
-        const { ensureTool } = await import("./installer/index.js");
-        const installedPath = await ensureTool("knip");
-        if (installedPath) {
-            this.knipAvailable = true;
-            this.log(`Knip auto-installed: ${installedPath}`);
-            return true;
-        }
-        this.knipAvailable = false;
+        const verdict = this.knipAvailability.getVerdict(cwd);
+        this.availabilityLatch.noteUnavailable(verdict.outcome ?? "missing", verdict.cause ?? "not-found");
         return false;
     }
+    /**
+     * The single place a knip-unavailable result is worded. A transient probe
+     * failure must never be reported as "install knip" — knip is on disk.
+     */
+    unavailableResult() {
+        const verdict = this.knipAvailability.getVerdict(process.cwd());
+        const transient = verdict.outcome === "transient";
+        const retryAfterMs = verdict.retryAtMs
+            ? Math.max(0, verdict.retryAtMs - Date.now())
+            : undefined;
+        return {
+            ...EMPTY_RESULT,
+            failureKind: transient ? "unavailable-transient" : "unavailable-missing",
+            summary: describeUnavailability({
+                tool: "Knip",
+                installHint: "npm install -D knip",
+                outcome: verdict.outcome,
+                cause: verdict.cause,
+                elapsedMs: verdict.elapsedMs,
+                retryAfterMs,
+            }),
+        };
+    }
     /**
      * Run knip analysis on the project.
      *
@@ -160,10 +192,7 @@ export class KnipClient {
             };
         }
         if (!(await this.ensureAvailable())) {
-            return {
-                ...EMPTY_RESULT,
-                summary: "Knip not available. Install with: npm install -D knip",
-            };
+            return this.unavailableResult();
         }
         const key = path.resolve(targetDir);
         const existing = this.inFlight.get(key);
@@ -213,10 +242,10 @@ export class KnipClient {
             "--cache-location",
             cacheLocation,
         ];
-        const result = await safeSpawnAsync("knip", args, {
+        const result = await safeSpawnAsync(this.knipCommand, args, {
             timeout: ANALYSIS_TIMEOUT_MS,
             cwd: targetDir,
-            env: await this.getKnipEnvironment(targetDir),
+            env: await getManagedToolEnvironment("knip", targetDir),
         });
         if (result.error) {
             this.log(`Analysis error: ${result.error.message}`);
@@ -271,19 +300,6 @@ export class KnipClient {
             ? result
             : { ...result, issues, unusedDeps };
     }
-    async getKnipEnvironment(targetDir) {
-        const { getToolEnvironment } = await import("./installer/index.js");
-        const env = await getToolEnvironment();
-        const separator = process.platform === "win32" ? ";" : ":";
-        const currentPath = env.PATH || env.Path || process.env.PATH || "";
-        const localBin = path.join(targetDir, "node_modules", ".bin");
-        const augmentedPath = `${localBin}${separator}${currentPath}`;
-        return {
-            ...env,
-            PATH: augmentedPath,
-            ...(process.platform === "win32" ? { Path: augmentedPath } : {}),
-        };
-    }
     /**
      * Find unused exports in a specific file
      */

package/node_modules/pi-lens/dist/clients/language-policy.js

@@ -56,11 +56,13 @@ export const LANGUAGE_POLICY = {
     lua: { lspCapable: true },
     zig: { lspCapable: true },
     haskell: { lspCapable: true },
+    "helm-template": { lspCapable: false },
     elixir: { lspCapable: true },
     gleam: { lspCapable: true },
     ocaml: { lspCapable: true },
     clojure: { lspCapable: true },
     terraform: { lspCapable: true },
+    terragrunt: { lspCapable: false },
     nix: { lspCapable: true },
     toml: { lspCapable: true, startup: { defaults: ["taplo"] } },
 };
@@ -117,7 +119,7 @@ const PRIMARY_DISPATCH_GROUPS = {
     },
     yaml: {
         mode: "all",
-        runnerIds: ["lsp", "yamllint", "trivy-config"],
+        runnerIds: ["lsp", "yamllint", "trivy-config", "helm-lint"],
         filterKinds: ["yaml"],
     },
     sql: {
@@ -179,6 +181,11 @@ const PRIMARY_DISPATCH_GROUPS = {
     lua: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["lua"] },
     zig: { mode: "all", runnerIds: ["lsp", "zig-check"], filterKinds: ["zig"] },
     haskell: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["haskell"] },
+    "helm-template": {
+        mode: "all",
+        runnerIds: ["helm-lint"],
+        filterKinds: ["helm-template"],
+    },
     elixir: {
         mode: "all",
         runnerIds: ["lsp", "elixir-check", "credo"],
@@ -193,9 +200,14 @@ const PRIMARY_DISPATCH_GROUPS = {
     clojure: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["clojure"] },
     terraform: {
         mode: "all",
-        runnerIds: ["lsp", "tflint"],
+        runnerIds: ["lsp", "tflint", "trivy-config"],
         filterKinds: ["terraform"],
     },
+    terragrunt: {
+        mode: "all",
+        runnerIds: ["terragrunt"],
+        filterKinds: ["terragrunt"],
+    },
     nix: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["nix"] },
     toml: {
         mode: "all",

package/node_modules/pi-lens/dist/clients/language-profile.js

@@ -1,12 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { CODE_KINDS, detectFileKind, DOTNET_CSHARP_ROOT_MARKERS, DOTNET_FSHARP_ROOT_MARKERS, KIND_EXTENSIONS, } from "./file-kinds.js";
+import { CODE_KINDS, detectFileKind, DOTNET_CSHARP_ROOT_MARKERS, DOTNET_FSHARP_ROOT_MARKERS, KIND_EXTENSIONS, TERRAGRUNT_FILENAMES, } from "./file-kinds.js";
 import { getProjectIgnoreMatcher } from "./file-utils.js";
-import { direntsHaveMarkerGlobMatch } from "./path-utils.js";
+import { direntsHaveMarkerGlobMatch, normalizeMapKey } from "./path-utils.js";
 import { LANGUAGE_POLICY, } from "./language-policy.js";
 import { getSourceFiles } from "./scan-utils.js";
 import { readDirEntriesSafe, shouldRecurseIntoDir } from "./source-walker.js";
 import { findNearestDirWithAnyBasename } from "./workspace-topology.js";
+import { BoundedLruCache } from "./bounded-cache.js";
 /** Every registered kind participates in project-language detection (#894). */
 export const SUPPORTED_FILE_KINDS = Object.keys(KIND_EXTENSIONS);
 const PROJECT_MARKERS_BY_KIND = {
@@ -36,6 +37,7 @@ const PROJECT_MARKERS_BY_KIND = {
     elixir: ["mix.exs"],
     gleam: ["gleam.toml"],
     terraform: [".terraform.lock.hcl"],
+    terragrunt: TERRAGRUNT_FILENAMES,
     nix: ["flake.nix"],
     toml: ["pyproject.toml", "Cargo.toml", "taplo.toml"],
     csharp: DOTNET_CSHARP_ROOT_MARKERS,
@@ -80,6 +82,7 @@ const ROOT_MARKERS_BY_KIND = {
     elixir: ["mix.exs"],
     gleam: ["gleam.toml"],
     terraform: [".terraform.lock.hcl"],
+    terragrunt: TERRAGRUNT_FILENAMES,
     nix: ["flake.nix"],
     toml: ["pyproject.toml", "Cargo.toml", "taplo.toml"],
     csharp: DOTNET_CSHARP_ROOT_MARKERS,
@@ -101,16 +104,16 @@ function hasProjectMarker(projectRoot, marker) {
 // must not pollute the no-arg cache. The synchronous getSourceFiles() call
 // inside this function does the same expensive ignoreMatcher-driven walk
 // as resolveStartupScanContext, so the same memo strategy applies.
-const languageProfileCache = new Map();
+const languageProfileCache = new BoundedLruCache(32);
 export function detectProjectLanguageProfile(projectRoot, sourceFiles) {
     if (sourceFiles === undefined) {
-        const cached = languageProfileCache.get(projectRoot);
+        const cached = languageProfileCache.get(normalizeMapKey(projectRoot));
         if (cached)
             return cached;
     }
     const result = computeProjectLanguageProfile(projectRoot, sourceFiles);
     if (sourceFiles === undefined) {
-        languageProfileCache.set(projectRoot, result);
+        languageProfileCache.set(normalizeMapKey(projectRoot), result);
     }
     return result;
 }
@@ -297,6 +300,9 @@ export async function collectSourceFilesForWarmup(rootDir, maxFiles = MAX_WARMUP
                     break walk;
                 }
             }
+            // Each iteration performs only bounded dirent/ext/ignore checks. Keep the
+            // count cadence: the cost does not scale with the corpus item size, and
+            // this walk's existing matched-file ceiling bounds the total work.
             if (++processedSinceYield % yieldEvery === 0) {
                 // See countSourceFilesWithinLimitAsync for why setImmediate.
                 await new Promise((resolve) => setImmediate(resolve));
@@ -306,7 +312,7 @@ export async function collectSourceFilesForWarmup(rootDir, maxFiles = MAX_WARMUP
     return [...codeOut, ...nonCodeOut];
 }
 export async function detectProjectLanguageProfileAsync(projectRoot) {
-    const cached = languageProfileCache.get(projectRoot);
+    const cached = languageProfileCache.get(normalizeMapKey(projectRoot));
     if (cached)
         return cached;
     const files = await collectSourceFilesForWarmup(projectRoot);
@@ -315,6 +321,6 @@ export async function detectProjectLanguageProfileAsync(projectRoot) {
     // probe (`existsSync` for package.json / pyproject.toml / etc.) which
     // is constant-time and cheap.
     const result = detectProjectLanguageProfile(projectRoot, files);
-    languageProfileCache.set(projectRoot, result);
+    languageProfileCache.set(normalizeMapKey(projectRoot), result);
     return result;
 }

package/node_modules/pi-lens/dist/clients/latency-logger.js

@@ -9,11 +9,82 @@ const writer = createNdjsonLogger({
     filePath: LATENCY_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,
 });
+/**
+ * Most recent non-`loop_block` phase seen by `logLatency`, for cheap block
+ * attribution (#1122 / #1123 item 1): the event-loop-block probe fires at
+ * turn_end and cannot see *what* stalled the loop, so it stamps the last phase
+ * that ran as a starting point for root-causing a genuine block. Tracked before
+ * the test-mode guard so it is deterministic and unit-testable.
+ */
+let lastPhase;
+/**
+ * Phases excluded from `lastPhase` attribution alongside `loop_block`.
+ * #1412 L3: `lsp_typescript_project_identity` is the classic-TS first-open
+ * project-identity probe (tsserver-sync.ts) — a detached, best-effort
+ * telemetry sample fired on every first didOpen, not genuine work. Letting it
+ * win `lastPhase` would overwrite the real stall attribution for a
+ * loop_block that happens to land right after a first open.
+ * #1432 review: `advisory_provenance_decision`,
+ * `authoritative_content_attachment_decision`, and
+ * `agent_end_deferred_mutation_drain` are the same shape — zero-duration
+ * decision telemetry, not genuine work — so they get the same exclusion.
+ * `agent_end_deferred_mutation_requeue` (S2d gap 4's per-requeue record) and
+ * `session_end_bus_rollup` (S2d gap 5's session-end rollup) are new
+ * zero-duration siblings of the same shape, added alongside them.
+ *
+ * `lsp_aux_wait_outcome` (#1458) is DIFFERENT from every entry above: its
+ * `durationMs` is a REAL bounded wait (the post-primary auxiliary grace, up
+ * to a few seconds), not zero-duration decision telemetry. It is still
+ * excluded because it is a WAIT-OUTCOME RECORD written after the aux wait
+ * already completed, not the stall itself — that wait ran inside the
+ * `lsp_touch_file`/diagnostics phase surrounding it, so letting this summary
+ * row win `lastPhase` would misattribute a `loop_block` to the record instead
+ * of to whatever phase is actually stalled when the block fires.
+ * #1453: `tool_set_mutation` records an active-tool-set rewrite (zero-duration
+ * bookkeeping, and it fires during session_start where a real stall must stay
+ * attributed to the work around it), so it is excluded for the same reason.
+ * #1467: `availability_decision` records a tool-probe verdict. Its `durationMs`
+ * is the child's own probe time (often zero for a fast path or a cached
+ * decision) and the record is bookkeeping ABOUT a probe, not host work — a
+ * loop_block landing next to one must stay attributed to whatever really
+ * stalled the loop, which is frequently the very thing that expired the probe.
+ *
+ * #1461 slice 1: `finding_dead_path_drop` is the same shape — the record a
+ * delivery seam writes when it drops findings whose cited path no longer
+ * exists.
+ */
+const LAST_PHASE_EXCLUDED = new Set([
+    "loop_block",
+    "lsp_typescript_project_identity",
+    "advisory_provenance_decision",
+    "authoritative_content_attachment_decision",
+    "agent_end_deferred_mutation_drain",
+    "agent_end_deferred_mutation_requeue",
+    "session_end_bus_rollup",
+    "lsp_aux_wait_outcome",
+    "tool_set_mutation",
+    "availability_decision",
+    "finding_dead_path_drop",
+]);
+/**
+ * The last non-`loop_block` phase logged, or undefined if none yet. Carries its
+ * own `ts` so a consumer can gauge staleness: it is intentionally NOT cleared at
+ * turn/window boundaries, so on a turn that logged no phase of its own it may
+ * point at a prior turn's phase — compare `ts` against the block time before
+ * trusting it as the cause (it is a breadcrumb, not proof).
+ */
+export function getLastLoggedPhase() {
+    return lastPhase;
+}
 export function logLatency(entry) {
+    const ts = new Date().toISOString();
+    if (entry.type === "phase" && entry.phase && !LAST_PHASE_EXCLUDED.has(entry.phase)) {
+        lastPhase = { phase: entry.phase, ts };
+    }
     if (isTestMode()) {
         return;
     }
-    writer.log({ ...entry, ts: new Date().toISOString(), pid: process.pid });
+    writer.log({ ...entry, ts, pid: process.pid });
 }
 export function getLatencyLogPath() {
     return LATENCY_LOG_FILE;

package/node_modules/pi-lens/dist/clients/lens-config.js

@@ -1,3 +1,5 @@
+import { logExtension } from "./extension-log.js";
+import { notifyUserDegradation } from "./user-notify.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -20,7 +22,16 @@ function warnInvalidGlobalConfigOnce(configPath, reason) {
     if (warnedInvalidGlobalConfigs.has(key))
         return;
     warnedInvalidGlobalConfigs.add(key);
-    console.error(`[pi-lens] ignoring invalid global config ${configPath}: ${reason}`);
+    const message = `ignoring invalid global config ${configPath}: ${reason}`;
+    logExtension({
+        subsystem: "lens-config",
+        level: "warn",
+        message,
+        metadata: { configPath, reason },
+    });
+    // HUMAN-audience too: a config the user wrote is being ignored. Routed
+    // through the host's own render path (#1333), never a raw write.
+    notifyUserDegradation(`pi-lens: ${message}`);
 }
 /** For tests that need to force the warn-once cache to reset between cases. */
 export function resetGlobalConfigWarnCache() {

package/node_modules/pi-lens/dist/clients/lens-engine.js

@@ -13,27 +13,28 @@
  * adds thin wrappers over the remaining internal reach-ins (latency, project
  * scan, LSP status, diagnostic stats, LSP config).
  */
+import * as path from "node:path";
+import { minimatch } from "./deps/minimatch.js";
 import { getDiagnosticTracker } from "./diagnostic-tracker.js";
 import { getLatencyReports, } from "./dispatch/integration.js";
 import { getResourceFootprint as getResourceFootprintSnapshot, } from "./instance-registry.js";
 import { initLSPConfig } from "./lsp/config.js";
 import { getLSPService } from "./lsp/index.js";
-import { getOrLoadWarmWordIndex } from "./mcp/analyze.js";
+import { acquireWarmWordIndex } from "./mcp/analyze.js";
+import { normalizeMapKey } from "./path-utils.js";
 import { scanProjectDiagnostics } from "./project-diagnostics/scanner.js";
+import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
 import { getTreeSitterRuntimeStatus, } from "./tree-sitter-shared.js";
-import * as path from "node:path";
-import { minimatch } from "./deps/minimatch.js";
-import { normalizeMapKey } from "./path-utils.js";
-import { loadProjectSnapshot } from "./project-snapshot.js";
-import { centralityFromReverseDeps, deserializeWordIndex, getWordIndexBuildStatus, searchWordIndex, triggerBackgroundWordIndexBuild, } from "./word-index.js";
+import { centralityFromReverseDeps, getWordIndexBuildStatus, searchWordIndex, triggerBackgroundWordIndexBuild, } from "./word-index.js";
 // --- Facades (re-exported so adapters import only this module) ---------------
 export { analyzeFile, } from "./mcp/analyze.js";
 export { createMcpHost } from "./mcp/host-shim.js";
-export { ipcPathForCwd, requestWarmAnalyze, } from "./mcp/ipc.js";
+export { createWarmIpcLineReader, createWarmIpcRequestQueue, ipcPathForCwd, readTurnEndStatus, requestWarmAnalyze, WARM_TURN_END_SCHEMA_VERSION, } from "./mcp/ipc.js";
 export { analyzeFileFresh, canRebuildPiLens, REBUILD_UNAVAILABLE_MESSAGE, resolveRebuildScript, runRebuild, summarizeScan, } from "./mcp/review.js";
-export { runSessionStart, runTurnEnd, } from "./mcp/session.js";
+export { acknowledgeTurnEnd, runSessionStart, runTurnEnd, runTurnEndForIpc, } from "./mcp/session.js";
 export { moduleReport, readEnclosing, readSymbol, renderCompactModuleReport, } from "./module-report.js";
 export { projectReport, renderCompactProjectReport, } from "./project-report.js";
+export { createDefaultHostPorts, } from "./host-ports.js";
 // --- Query wrappers (own the remaining internal reach-ins) -------------------
 /** Recent dispatch latency reports (latency.log schema), newest first. */
 export function recentLatency(limit = 5, fileFilter) {
@@ -44,9 +45,21 @@ export function recentLatency(limit = 5, fileFilter) {
     }
     return reports.slice(-limit).reverse();
 }
-/** Cheap project-wide scan (tree-sitter + fact rules). */
-export function projectScan(cwd, maxFiles) {
-    return scanProjectDiagnostics({ cwd, tier: "cheap", maxFiles });
+/**
+ * Cheap project-wide scan (tree-sitter + fact rules).
+ *
+ * `includeGenerated` (#1107 phase 2 review): scan WITHOUT the generated/
+ * artifact NAME-heuristic filter — the actionable opt-out
+ * `generatedSkipNotice` below points a user at. Default `false` (existing
+ * filtering behavior unchanged).
+ */
+export function projectScan(cwd, maxFiles, includeGenerated) {
+    return scanProjectDiagnostics({
+        cwd,
+        tier: "cheap",
+        maxFiles,
+        includeGenerated,
+    });
 }
 /**
  * #784: `scanTruncated` (#760) reaches this seam intact but, until now, no
@@ -66,6 +79,53 @@ export function scanTruncationNotice(snapshot) {
     return (`⚠ Scan truncated at ${snapshot.filesScanned} file(s) — results are partial; ` +
         "raise maxProjectFiles in .pi-lens.json to scan fully.");
 }
+/**
+ * #1107 phase 2: `generatedNameOnlySkips`/`generatedDirSkips` reach this seam
+ * via `ProjectDiagnosticsSnapshot` but need explicit rendering, same pattern
+ * as `scanTruncationNotice` above — otherwise a user has no way to learn the
+ * generated-name heuristic silently excluded files/directories short of
+ * reading `latency.log`'s `source_walk_skip_summary` line directly.
+ *
+ * #1107 phase 2 review round 2 (P1, empirically proven): this deliberately
+ * keys off `generatedNameOnlySkips`, NOT the raw `generatedFileSkips` total.
+ * `generatedFileSkips` counts every file the generated/artifact heuristic
+ * skipped, including STRONG evidence (lockfiles, declaration files, minified/
+ * bundle/chunk output — expected on nearly every real repo) and
+ * content-CONFIRMED WEAK matches (the escape hatch checked and a genuine
+ * generated-code header was present). Keying the notice off that total meant
+ * a repo with nothing more unusual than a `package-lock.json` and an ambient
+ * `.d.ts` showed "2 file(s) excluded" on literally every scan forever — the
+ * signal drowned itself on day one. `generatedNameOnlySkips` is the narrower,
+ * genuinely at-risk residual: a WEAK name match trusted with NO corroborating
+ * evidence check at all (only reachable when a caller opts out of the header
+ * probe — source-filter.ts's default project-walk path always enables it).
+ * Post-escape-hatch, this should be rare-to-zero on the default path, which
+ * is exactly what makes the notice meaningful again when it DOES fire.
+ * `generatedDirSkips` stays in the trigger condition unchanged: directory-
+ * level pruning has no escape hatch at all (the walk never enumerates a
+ * pruned directory's contents to check them), so it is always a genuine
+ * "real files may be hiding in here, unverified" signal, not a
+ * false-positive-prone one — see `generatedDirSkips`'s doc on
+ * `SourceCollectionResult`.
+ *
+ * Returns `undefined` when neither counter is set (nothing to append).
+ */
+export function generatedSkipNotice(snapshot) {
+    const files = snapshot.generatedNameOnlySkips ?? 0;
+    const dirs = snapshot.generatedDirSkips ?? 0;
+    if (files === 0 && dirs === 0)
+        return undefined;
+    const parts = [];
+    if (files > 0)
+        parts.push(`${files} file(s)`);
+    if (dirs > 0)
+        parts.push(`${dirs} director${dirs === 1 ? "y" : "ies"}`);
+    return (`ℹ ${parts.join(" and ")} excluded by generated-name heuristics with no ` +
+        "confirming evidence — a real hand-written file/directory whose name " +
+        "looks generated (e.g. `gen.ts`, `generated/`) can be excluded too; " +
+        "pass includeGenerated: true to pilens_project_scan / lens_diagnostics " +
+        "to scan without this filter if you suspect a false skip.");
+}
 /** Process-wide tree-sitter health for host status surfaces. */
 export function treeSitterRuntimeStatus() {
     return getTreeSitterRuntimeStatus();
@@ -213,7 +273,7 @@ function toSymbolSearchHit(result) {
  * cwd, never blocking this call) so a retry shortly after succeeds (#348
  * decision 3).
  *
- * #536 rider: prefers the warm in-memory index (`getOrLoadWarmWordIndex`,
+ * #536 rider: prefers the warm in-memory index (`acquireWarmWordIndex`,
  * clients/mcp/analyze.ts) over a fresh disk read when one exists for this
  * cwd — a warm `pilens_analyze` call updates that live copy synchronously but
  * persists it to disk on a debounce (default 1500ms), so without this a query
@@ -239,9 +299,11 @@ function toSymbolSearchHit(result) {
  * nothing on this hot path.
  */
 export async function symbolSearch(query, cwd, limit = 20, options = {}) {
-    const snapshot = loadProjectSnapshot(cwd);
-    const index = getOrLoadWarmWordIndex(cwd) ?? deserializeWordIndex(snapshot?.wordIndex);
+    const warmLease = acquireWarmWordIndex(cwd);
+    const snapshot = loadProjectSnapshotWithoutWordIndex(cwd);
+    const index = warmLease.index;
     if (!index) {
+        warmLease.release();
         const priorStatus = getWordIndexBuildStatus(cwd);
         const status = priorStatus?.state === "refused"
             ? priorStatus
@@ -266,9 +328,16 @@ export async function symbolSearch(query, cwd, limit = 20, options = {}) {
     }
     // Boost well-connected files using the snapshot's reverse-dependency
     // (importedBy) counts; snapshot keys are normalized, index keys are raw.
-    const centrality = centralityFromReverseDeps(index, snapshot?.reverseDeps, (file) => normalizeMapKey(path.resolve(file)));
-    const fileFilter = buildSymbolSearchFileFilter(cwd, options);
-    const results = searchWordIndex(index, query, { limit, centrality, fileFilter });
+    let centrality;
+    let results;
+    try {
+        centrality = centralityFromReverseDeps(index, snapshot?.reverseDeps, (file) => normalizeMapKey(path.resolve(file)));
+        const fileFilter = buildSymbolSearchFileFilter(cwd, options);
+        results = searchWordIndex(index, query, { limit, centrality, fileFilter });
+    }
+    finally {
+        warmLease.release();
+    }
     const hits = results.map(toSymbolSearchHit);
     const { getCachedReviewGraph } = await import("./review-graph/builder.js");
     const graph = getCachedReviewGraph(cwd);

package/node_modules/pi-lens/dist/clients/lens-events.js

@@ -1,12 +1,17 @@
+import { logExtension } from "./extension-log.js";
+import { logBusEvent } from "./bus-events-logger.js";
+import { normalizeFilePath } from "./path-utils.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const LENS_EVENT_VERSION = 1;
 export const LENS_EVENT_NAMES = {
     analysisComplete: "pi-lens/analysis-complete",
     findings: "pi-lens/findings",
     turnFindings: "pi-lens/turn-findings",
 };
-let lensEventBus;
-export function initLensEvents(pi) {
-    lensEventBus = pi.events;
+const liveEmitter = createLiveBusEmitter();
+/** Keep deferred deliveries on the live extension activation. */
+export function initLensEventsGetter(getter) {
+    liveEmitter.wireGetter(getter);
 }
 function truncateText(value, maxChars) {
     if (value === undefined)
@@ -26,17 +31,66 @@ function normalizeDiagnostic(diagnostic) {
 function normalizeDiagnostics(diagnostics) {
     return diagnostics.map(normalizeDiagnostic);
 }
+// Dropped-emit observability (#1128 review): drops are legitimate (no bus
+// during startup/replacement windows) but must not be invisible. One line per
+// process — enough to notice a permanently-missing bus without spamming.
+let _droppedEmitLogged = false;
+// Emit-failure gating (H1, #1415 review): occurrence-scoped, matching every
+// other producer's `hasLoggedFailure` guard (see clients/bus-publish.ts) and
+// AGENTS.md's "one bus-stale degradation per occurrence" invariant. A success
+// re-arms it, so a later failure records a fresh degradation rather than
+// being silently absorbed by an earlier one.
+let hasLoggedFailure = false;
+/** Test-only: reset module state between test files. */
+export function _resetForTests() {
+    liveEmitter.reset();
+    _droppedEmitLogged = false;
+    hasLoggedFailure = false;
+}
 function emitLensEvent(eventName, payload) {
-    const emit = lensEventBus?.emit;
-    if (!emit)
-        return;
     setImmediate(() => {
+        const rawCwd = payload.cwd ?? process.cwd();
+        // M1: normalizeFilePath is a sync realpathSync.native on Windows — build
+        // the resolveLiveBusEmitter log entry lazily so the ready-path (the
+        // common case) never pays it. Only the stale-session branch needs it.
+        const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+            event: eventName,
+            cwd: normalizeFilePath(rawCwd),
+        }));
+        if (resolution.outcome === "stale-session")
+            return;
+        if (resolution.outcome === "unwired") {
+            if (!_droppedEmitLogged) {
+                _droppedEmitLogged = true;
+                logExtension({
+                    subsystem: "lens-events",
+                    level: "warn",
+                    message: `lens event dropped (no live bus): ${eventName} — further drops logged once per process`,
+                    metadata: { eventName },
+                });
+            }
+            return;
+        }
+        const cwd = normalizeFilePath(rawCwd);
         try {
-            emit.call(lensEventBus, eventName, payload);
+            resolution.emit(eventName, payload);
+            hasLoggedFailure = false;
+            logBusEvent({ event: eventName, outcome: "emitted", cwd });
         }
-        catch {
+        catch (err) {
+            logBusEvent({
+                event: eventName,
+                outcome: "emit_failed",
+                cwd,
+                error: String(err),
+                ctxSource: resolution.ctxSource,
+            });
+            if (!hasLoggedFailure) {
+                hasLoggedFailure = true;
+                recordStaleBusFailure(eventName, err);
+            }
             // Inter-extension events are observational. A listener must never break
-            // the pi-lens hook path or delay agent progress with error handling noise.
+            // the pi-lens hook path or delay agent progress.
         }
     });
 }