@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -1,10 +1,10 @@
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { normalizeLoggedPath } from "./path-utils.js";
-const LATENCY_LOG_DIR = getGlobalPiLensDir();
+const LATENCY_LOG_DIR = getGlobalPiLensLogDir();
 const LATENCY_LOG_FILE = path.join(LATENCY_LOG_DIR, "latency.log");
 const writer = createNdjsonLogger({
     filePath: LATENCY_LOG_FILE,
@@ -79,6 +79,11 @@ let recentPhases = [];
  * usage records. It reports no new work and therefore cannot own last-phase
  * stall attribution.
  *
+ * #2249: `concurrent_session_bind_rollup` is the same shape as
+ * `session_end_bus_rollup`/`path_attribution_verified_rollup` above — a
+ * zero-duration session-end summary of records already logged individually,
+ * not new work of its own.
+ *
  * #2044: `test_runner_failed_target_state` is a zero-duration decision after a
  * bounded filesystem probe. The surrounding turn-end test-selection phase owns
  * any real work, so this row must not replace it in stall attribution.
@@ -101,8 +106,11 @@ const LAST_PHASE_EXCLUDED = new Set([
     "lsp_scanner_coverage_gap",
     "lsp_notify_resync_deferred",
     "lsp_notify_write_late_landed",
+    "lsp_notify_stall_cpu_busy",
     "degradation_ledger",
     "path_attribution_verified_rollup",
+    "concurrent_session_bind_rollup",
+    "auxiliary_readiness",
 ]);
 /**
  * The last non-`loop_block` phase logged, or undefined if none yet. Carries its
@@ -147,8 +155,6 @@ export function _recentPhasesStorageLengthForTest() {
 export function _setRecentPhasesForTest(entries) {
     recentPhases = entries;
 }
-/** Bound on the closed-bracket ring below — same size discipline as `recentPhases`. */
-export const CLOSED_BRACKET_CAP = RECENT_PHASE_CAP;
 /**
  * Phases currently executing, keyed by their own start token (#1723 review
  * round: this replaces an earlier single-slot design that broke two ways.
@@ -172,7 +178,7 @@ export const CLOSED_BRACKET_CAP = RECENT_PHASE_CAP;
  */
 const liveBrackets = new Map();
 /**
- * Recently CLOSED brackets, newest first, bounded to `CLOSED_BRACKET_CAP`
+ * Recently CLOSED brackets, newest first, bounded to `RECENT_PHASE_CAP`
  * (#1723 review round, F3 — the decisive finding). `phaseFinished` runs
  * inside a `finally`, which resumes as a MICROTASK, while the host schedules
  * `turn_end` as a MACROTASK — and microtasks always fully drain before the
@@ -202,7 +208,7 @@ export function phaseStarted(phase) {
 }
 /**
  * Close a bracket: removes it from `liveBrackets` (one `Map.delete`, O(1))
- * and records it on the closed-bracket ring, bounded to `CLOSED_BRACKET_CAP`
+ * and records it on the closed-bracket ring, bounded to `RECENT_PHASE_CAP`
  * with the oldest entry dropped first — see the `closedBrackets` doc comment
  * above for why a closed history is load-bearing, not just nice-to-have
  * (#1723 review F3). `Map.delete` reports whether it actually removed
@@ -238,7 +244,7 @@ export function phaseFinished(token) {
             closedAt: new Date().toISOString(),
         },
         ...closedBrackets,
-    ].slice(0, CLOSED_BRACKET_CAP);
+    ].slice(0, RECENT_PHASE_CAP);
 }
 /**
  * The OLDEST phase still executing, if any — the longest-running open
@@ -259,7 +265,7 @@ export function getCurrentPhase() {
  * A candidate bracket is ignored outright if its OWN lifetime (`elapsedMs`)
  * is under this fraction of the window's length (#1723 review round 3, N4).
  * Overlap alone is not enough: the bounded closed-bracket ring can churn a
- * real culprit out (busy siblings filling `CLOSED_BRACKET_CAP`), leaving only
+ * real culprit out (busy siblings filling `RECENT_PHASE_CAP`), leaving only
  * a 1ms bracket that happens to have SOME positive overlap with an 18-second
  * window — reporting it would be a CONFIDENT WRONG ANSWER, worse than no
  * answer. 5%: a genuine cause's own duration should be a meaningful fraction
@@ -481,7 +487,7 @@ export function getPhaseForWindow(windowStartMs, windowEndMs) {
 /**
  * Test-only: the closed-bracket ring's actual storage length, mirroring
  * `_recentPhasesStorageLengthForTest` above — pins that `phaseFinished`'s
- * `.slice(0, CLOSED_BRACKET_CAP)` guard is intact independent of any
+ * `.slice(0, RECENT_PHASE_CAP)` guard is intact independent of any
  * read-side behavior (#1723 review: "ring unbounded" mutation).
  */
 export function _closedBracketsStorageLengthForTest() {
@@ -520,6 +526,156 @@ export function resetCurrentPhaseForSession() {
     liveBrackets.clear();
     closedBrackets = [];
 }
+/**
+ * Phases already written ONCE for the current session (#2526).
+ *
+ * Session-scoped telemetry bookkeeping, which is this module's own domain —
+ * the same reason `liveBrackets` and `recentPhases` live here rather than in
+ * each producer. A producer that is called many times per session but whose
+ * record is a SESSION fact (`config_resolved`: `loadLSPConfig` runs at session
+ * start, per served root, and on the first edit, all resolving the same
+ * config) asks here instead of keeping its own latch, so the "one row per
+ * session" a log reader counts against is a property of the logger rather than
+ * a convention each producer re-implements.
+ */
+const oncePerSessionPhases = new Set();
+/**
+ * The identity every once-per-session record of THIS session is stamped with
+ * (#2526 review round 2, F2).
+ *
+ * A line-oriented log reader cannot join two files by adjacency: sessionstart.
+ * log's start lines and latency.log's phase rows interleave differently, rotate
+ * independently, and (for the warm MCP server) can span days. The first round
+ * therefore SUBTRACTED row counts from start-line counts, which silently
+ * assumed the two counted the same population — they do not, and the
+ * mismatch both masked total silence and manufactured a permanent false
+ * deficit. An id makes the join explicit: `handleSessionStart` publishes it
+ * beside its expectation, the record carries it, and the analyzer matches.
+ *
+ * It is minted HERE, beside the claim set it identifies, so "which session is
+ * this record from" and "has this session already recorded" can never answer
+ * from different sessions.
+ *
+ * Minted at module load too, not only on re-arm: the warm MCP server resolves
+ * config through `ensureReady` without any session boundary of its own, and a
+ * record with no id at all would be unjoinable rather than merely unmatched.
+ */
+let sessionRecordSeq = 0;
+function mintSessionRecordId() {
+    sessionRecordSeq += 1;
+    return `${process.pid.toString(36)}-${Date.now().toString(36)}-${sessionRecordSeq.toString(36)}`;
+}
+let sessionRecordId = mintSessionRecordId();
+/**
+ * The current session's record identity — an opaque, process-local token.
+ *
+ * Deliberately NOT the host's session id: that is user-facing conversation
+ * identity pi-lens does not otherwise write to disk, and the join only needs
+ * "the same session", not "which conversation".
+ */
+export function currentSessionRecordId() {
+    return sessionRecordId;
+}
+/**
+ * The claim key. A phase is claimed per SCOPE (#2526 review round 2, F3):
+ * `config_resolved` is a fact about a (session, project root) pair, and the
+ * warm MCP server serves N roots from one process — keying on the phase name
+ * alone recorded the first root's documents and silently dropped every other
+ * root's, so a legacy config in project B could never surface its smell.
+ *
+ * `scope` is REQUIRED (#2526 review round 3, S3 — narrowed from optional):
+ * the one production caller always passes one, and an unscoped claim is the
+ * exact shape F3 found unsafe — a phase-only key recording the first caller
+ * and silently dropping every later one under a different scope. A future
+ * producer with no natural scope can pass a constant string; that is still an
+ * explicit choice, not a silently-defaulted one.
+ */
+function claimKey(phase, scope) {
+    return `${phase}\0${scope}`;
+}
+/**
+ * Claim the session's one record for `phase` within `scope`.
+ *
+ * Returns true exactly once per session and scope; every later call for the
+ * same pair returns false until {@link resetOncePerSessionPhases} re-arms it.
+ * Callers should claim BEFORE building the payload, so a claim that loses the
+ * race costs nothing.
+ */
+export function claimPhaseOncePerSession(phase, scope) {
+    const key = claimKey(phase, scope);
+    if (oncePerSessionPhases.has(key))
+        return false;
+    oncePerSessionPhases.add(key);
+    return true;
+}
+/**
+ * Release ONE scope's claim for `phase` — the narrow sibling of
+ * {@link releaseOncePerSessionPhase}, which releases every scope of a phase.
+ *
+ * #2518 review F1. A claim is a promise that this session's record for the
+ * (phase, scope) pair has already been written, which holds only while the
+ * state that record described is still there. When that state is DROPPED —
+ * the session-root registry evicting a root, taking its resolved LSP config
+ * with it — the next load for that scope is a genuine SECOND resolution, and
+ * its row is the only thing that says what the reloaded config was. So the
+ * claim is released with the state it described; a claim outliving its state
+ * silences the record for the rest of the session, which is catalog shape 17
+ * pointed at a positive-observability record.
+ *
+ * Bounded by the caller: releases are as frequent as the evictions that cause
+ * them, and those are counted (`lsp-session-root-evicted`).
+ */
+export function releasePhaseClaim(phase, scope) {
+    oncePerSessionPhases.delete(claimKey(phase, scope));
+}
+/**
+ * Release every scope's claim for ONE phase, without touching the others
+ * (#2526 review round 2, S1).
+ *
+ * A producer's own `resetForTests` needs its own phase re-armed, not a blanket
+ * clear of a shared session-scoped structure: the blanket call reached into
+ * claims other producers own and, worse, re-minted the session identity as a
+ * side effect of an unrelated module's reset.
+ */
+export function releaseOncePerSessionPhase(phase) {
+    const prefix = `${phase}\0`;
+    for (const key of oncePerSessionPhases) {
+        if (key.startsWith(prefix))
+            oncePerSessionPhases.delete(key);
+    }
+}
+/**
+ * Re-arm every once-per-session phase claim for a new session, and mint the
+ * new session's record identity.
+ *
+ * PLACEMENT (#2526 review round 2, F1): this is called from index.ts's
+ * `session_start` closure, from BEHIND the #473 concurrent-secondary gate,
+ * beside `resetCurrentPhaseForSession` — and NOT from inside
+ * `handleSessionStart`. index.ts resolves this session's config in
+ * `ensureLSPConfigInitialized` BEFORE it calls the handler, so a re-arm inside
+ * the handler fires between the session's own two resolutions: the ensure
+ * writes a row, the handler wipes the claim, and the deferred `loadLSPConfig`
+ * writes a second row for the same session. The first session of a process got
+ * two rows and every later one (whose ensure the process-lifetime
+ * `_lspConfigInitializedCwds` memo short-circuits) got one, which is
+ * unrecoverable for any per-session count.
+ *
+ * A latch that is never re-armed silences its record for the rest of the
+ * PROCESS (AGENTS.md catalog shape 17), which for a positive-observability
+ * record is the exact silence it exists to end — so the re-arm must exist; it
+ * just has to sit ahead of the session's first resolution rather than in the
+ * middle of them.
+ *
+ * The warm MCP server (`clients/mcp/session.ts` calls `handleSessionStart`
+ * directly, never through index.ts) therefore keeps ONE identity for the life
+ * of the process. That is the honest answer for it: a warm server has no
+ * session boundary, its "session" is the process, and F3's per-root scoping is
+ * what gives it one record per served root.
+ */
+export function resetOncePerSessionPhases() {
+    oncePerSessionPhases.clear();
+    sessionRecordId = mintSessionRecordId();
+}
 export function logLatency(entry) {
     const ts = new Date().toISOString();
     if (entry.type === "phase" &&

package/node_modules/pi-lens/dist/clients/ledger-bounds.js

@@ -9,8 +9,41 @@
  */
 /** The single truncation bound for every ledger field, and for the reasons callers build. */
 export const LEDGER_FIELD_MAX = 200;
+/**
+ * How many retained entries the ledger keeps per kind — and therefore the bound
+ * any producer of ledger-bound records sizes itself to.
+ *
+ * Moved here from `degradation-ledger.ts` (#2426) for the reason this module's
+ * doc comment already gives: `config-core/records.ts` bounds its collector to
+ * this number, and reading it off the LEDGER made the config core import a sink
+ * it is documented not to touch ("Pure: no state, no I/O, no ledger writes").
+ * That import also broke three suites that `vi.mock` the ledger wholesale — the
+ * exact failure mode this leaf exists to prevent — and closed seven import
+ * cycles once the config loaders started resolving through the core.
+ */
+export const DEGRADATION_ENTRIES_PER_KIND = 20;
 export function normalizeForLedger(value) {
-    return String(value ?? "unknown");
+    if (value === null || value === undefined)
+        return "unknown";
+    // A plain object or array has no `toString` of its own, so `String()`
+    // writes "[object Object]" — a ledger row that names nothing. Serialise
+    // those; everything else (Error, Date, URL, primitives, class instances)
+    // keeps its `String()` form. An object carrying its OWN `toString` goes
+    // through `String()` too, so a throwing one still raises into the
+    // ledger's corrupted-input failsafe (#2703 r1 F1) instead of being
+    // admitted as "{}". Circular input degrades to a fixed marker.
+    if (typeof value === "object" && !Object.hasOwn(value, "toString")) {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null || Array.isArray(value)) {
+            try {
+                return JSON.stringify(value) ?? "unknown";
+            }
+            catch {
+                return "[unserializable object]";
+            }
+        }
+    }
+    return String(value);
 }
 /** Bound a value to `LEDGER_FIELD_MAX`, marking the elision. */
 export function truncateForLedger(value) {

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

@@ -1,41 +1,44 @@
-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 { resetIgnoredConfigWarnCache, warnIgnoredConfigOnce, } from "./config-warn.js";
+import { errorClassName } from "./error-class.js";
 import * as path from "node:path";
 import { assignFlagConfigSection, flagConfigSectionKeys, flagValueFromConfig, getLensFlagSpec, GLOBAL_NON_FLAG_CONFIG_SECTIONS, LENS_FLAGS, readFlagConfigValue, } from "./lens-flag-registry.js";
+import { CANONICAL_GLOBAL_CONFIG_FILE, getPiLensGlobalConfigPath, GLOBAL_CONFIG_LOCATIONS, LEGACY_ROOT_LSP_KEYS, } from "./config-locations.js";
+// Re-exported so this module's own, pre-existing import sites (`./lens-config.js`
+// / `../lens-config.js`) keep working. The function itself now lives in
+// `config-locations.ts` (#2426 review round 3, S1) — see the doc comment there.
+export { getPiLensGlobalConfigPath } from "./config-locations.js";
+import { ignoredRecordCollector, readConfigDocument, reportConfigReadFailure, reportPiLensConfigRecords, resolveOnePiLensConfigDocument, } from "./config-resolve.js";
 import { findNestedProjectMutationValue, } from "./project-lens-config.js";
-export function getPiLensGlobalConfigPath(homeDir = os.homedir()) {
-    const override = process.env.PI_LENS_CONFIG_PATH;
-    if (override)
-        return path.resolve(override);
-    return path.join(homeDir, ".pi-lens", "config.json");
+/**
+ * The canonical global location, looked up rather than constructed, so a change
+ * to the shared table cannot leave this loader describing a file that is no
+ * longer canonical.
+ */
+function globalCanonicalLocation() {
+    const location = GLOBAL_CONFIG_LOCATIONS.find((candidate) => candidate.relativePath === CANONICAL_GLOBAL_CONFIG_FILE);
+    if (!location) {
+        throw new Error(`no canonical global config location named ${CANONICAL_GLOBAL_CONFIG_FILE}`);
+    }
+    return location;
 }
-const warnedInvalidGlobalConfigs = new Set();
 /**
  * Same warn-once-per-(path, reason) contract as project-lens-config.ts's
  * `warnInvalidConfigOnce` — a malformed global config value is logged once
- * and then treated as absent, rather than silently dropped (#792).
+ * and then treated as absent, rather than silently dropped (#792). Since #2418
+ * the latch, the log line, the durable ledger row, and the stable-coded
+ * notification all live in the one shared seam.
  */
-function warnInvalidGlobalConfigOnce(configPath, reason) {
-    const key = `${configPath}:${reason}`;
-    if (warnedInvalidGlobalConfigs.has(key))
-        return;
-    warnedInvalidGlobalConfigs.add(key);
-    const message = `ignoring invalid global config ${configPath}: ${reason}`;
-    logExtension({
+function warnInvalidGlobalConfigOnce(configPath, reason, code) {
+    warnIgnoredConfigOnce({
         subsystem: "lens-config",
-        level: "warn",
-        message,
-        metadata: { configPath, reason },
+        file: configPath,
+        reason,
+        ...(code === undefined ? {} : { code }),
     });
-    // 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() {
-    warnedInvalidGlobalConfigs.clear();
+    resetIgnoredConfigWarnCache("lens-config");
 }
 function asConfigObject(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -43,12 +46,82 @@ function asConfigObject(value) {
         : undefined;
 }
 export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath()) {
+    const location = globalCanonicalLocation();
+    // #2445: this used to be `JSON.parse(fs.readFileSync(...))` inside a bare
+    // `catch { return undefined; }`, so a malformed `~/.pi-lens/config.json`
+    // produced ZERO signal of its own — no log line, no ledger row, no
+    // notification. The only thing a user saw was the LSP loader's report of the
+    // SAME file, mislabelled "ignoring invalid LSP config", because that loader
+    // resolves the canonical global too. Both halves are fixed together: the
+    // read/parse failure is reported here, under `lens-config`, and
+    // `reportConfigReadFailure` derives the subsystem from the DOCUMENT so the
+    // LSP loader's report of this file lands under `lens-config` as well and the
+    // warn-once latch collapses the two into one honest notice.
+    const outcome = readConfigDocument(configPath);
+    if (outcome.status === "missing")
+        return undefined;
+    if (outcome.status === "error") {
+        reportConfigReadFailure({
+            file: configPath,
+            location,
+            tier: "global",
+            error: outcome.error,
+            sourceText: outcome.sourceText,
+        });
+        return undefined;
+    }
+    // Every notice this projection composes is BUFFERED and bounded once, at the
+    // end, through the SAME `ignoredRecordCollector` the project loader uses
+    // (#2426 review round 6, F3; round 7, F2). It used to report each one the
+    // moment it was composed, with no collector anywhere in this function, so
+    // the unknown-top-level-key scan below — whose count is the number of keys
+    // the user typed — put 100 notifications on screen for a 100-key
+    // `~/.pi-lens/config.json` while the project loader's identical scan of an
+    // identical file produced 19 and a count. Two changelog fragments already
+    // claimed one bound for every producer; this is the producer that did not
+    // have one.
+    //
+    // Round 6 gave it that bound by COPYING the project loader's, which left two
+    // spellings of one record literal differing only in a tier. Round 7 moved
+    // the seam into `config-resolve.ts`, which both loaders already import, and
+    // made the tier an argument. This loader never passes a `{ parseError }`:
+    // its read/parse failure is reported above by `reportConfigReadFailure`,
+    // before the projection starts.
+    //
+    // The flush is in a `finally` so a throw in the projection still delivers
+    // what was composed before it, on top of the whole-config record the catch
+    // adds.
+    const { note, records: notedRecords } = ignoredRecordCollector(configPath, "global");
     try {
-        const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        if (!parsed || typeof parsed !== "object")
+        const parsed = outcome.value;
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            // The other half of the same silence: a file that PARSES but is a list
+            // or a scalar is not a config either, and was dropped without a word.
+            note("top-level value must be an object");
             return undefined;
-        const raw = parsed;
-        const warnInvalid = (reason) => warnInvalidGlobalConfigOnce(configPath, reason);
+        }
+        // Through the #2425 core (#2426). The canonical global file is resolved as
+        // a single `global`-tier source against the canonical schema, so the depth
+        // bound, the prototype-key policy and the declared `lsp.*` types apply to
+        // `~/.pi-lens/config.json` exactly as they do to `.pi-lens.json`. The
+        // field-by-field projection below is unchanged and keeps owning the
+        // per-key prose its tests assert on — the core validates the SHAPE, this
+        // function still decides what a bad value is called.
+        const document = {
+            tier: "global",
+            file: configPath,
+            location,
+            value: parsed,
+        };
+        const resolved = resolveOnePiLensConfigDocument(document);
+        // EVERY record this document produced (#2426 review round 3, F1) — not
+        // filtered to what this loader "owns". `reportPiLensConfigRecords` derives
+        // the reporting subsystem per record; the warn-once latch collapses a
+        // duplicate report of the SAME record from the LSP loader's resolution of
+        // this same file (it resolves the canonical global too) into one notice.
+        reportPiLensConfigRecords(resolved.records);
+        const raw = resolved.value;
+        const warnInvalid = note;
         const config = {};
         for (const spec of LENS_FLAGS) {
             if (spec.readGlobal)
@@ -60,6 +133,25 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
             : undefined;
         if (ignore && ignore.length > 0)
             config.ignore = ignore;
+        const startup = asConfigObject(raw.startup);
+        if (startup) {
+            const startupConfig = {};
+            const mode = startup.mode;
+            const scans = asConfigObject(startup.scans);
+            if (mode === "quick" || mode === "full" || mode === "minimal")
+                startupConfig.mode = mode;
+            else if ("mode" in startup)
+                warnInvalid('startup.mode must be "quick", "full", or "minimal"');
+            if (scans) {
+                if (typeof scans.enabled === "boolean") {
+                    startupConfig.scans = { enabled: scans.enabled };
+                }
+                else if ("enabled" in scans)
+                    warnInvalid("startup.scans.enabled must be a boolean");
+            }
+            if (startupConfig.mode !== undefined || startupConfig.scans !== undefined)
+                config.startup = startupConfig;
+        }
         const dispatch = asConfigObject(raw.dispatch);
         if (dispatch) {
             const floor = dispatch.runnerTimeoutFloorMs;
@@ -127,9 +219,22 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
         // (`GLOBAL_NON_FLAG_CONFIG_SECTIONS`, which co-locates `$schema` and the
         // hand-parsed namespaces beside the registry). Adding a flag needs no
         // edit here; adding a namespace is a one-line edit in that one constant.
+        //
+        // `LEGACY_ROOT_LSP_KEYS` joins them for #2426 review round 4, F1. The four
+        // legacy root LSP keys are read out of THIS file by the LSP loader and
+        // their values are applied, exactly as they are in a project
+        // `.pi-lens.json` — where `PROJECT_FOREIGN_CONFIG_NAMESPACES` has
+        // tolerated them since #2426. The global scan never got the same
+        // treatment, so `~/.pi-lens/config.json` with a root `warmFiles` both
+        // honored the setting and called it a typo in the same session. Spread
+        // from the registry-derived list rather than restated: `lens-config.ts`
+        // already imports `config-locations.ts`, which derives it from
+        // `DEPRECATED_CONFIG_SURFACES`, so the accepted set and the removal
+        // schedule cannot drift apart and there is no second copy of the names.
         const knownGlobalConfigKeys = new Set([
             ...flagConfigSectionKeys(LENS_FLAGS),
             ...GLOBAL_NON_FLAG_CONFIG_SECTIONS,
+            ...LEGACY_ROOT_LSP_KEYS,
         ]);
         for (const key of Object.keys(raw)) {
             if (!knownGlobalConfigKeys.has(key)) {
@@ -138,9 +243,34 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
         }
         return config;
     }
-    catch {
+    catch (error) {
+        // #2426 review round 5, S-C. The other half of #2445's silence. The
+        // read/parse failure above now reports, but everything AFTER the parse —
+        // the resolution through the core and the field-by-field projection —
+        // still sat under a bare `catch { return undefined }`, so a throw in any
+        // of it dropped the WHOLE global config with no log line, no ledger row
+        // and no notification: pi-lens ran on defaults and said nothing, which is
+        // the exact defect #2445 was filed for.
+        //
+        // `PILENS_CFG_0008` ("config resolution failed; whole configuration
+        // ignored") rather than `0001`, and the ERROR CLASS only, never its
+        // message, which could quote the file — the same rule `resolveConfig`'s
+        // own guard follows for the same reason. Round 5 used `0005` here, which
+        // is registered as a per-FIELD rejection: a user matching on it would
+        // have expected one setting to be missing rather than the whole file
+        // (#2426 review round 6, S1). `errorClassName` (#2451) is the ONE
+        // implementation of "class name, never the message" — this loader
+        // already imports `config-warn.js` for the rest of the seam, so it could
+        // call `normalizeParseErrorReason({ classOnly: true })` directly, but
+        // calling the same leaf `config-warn.ts` itself delegates to keeps every
+        // caller of this guarantee, `config-core/` included, on ONE
+        // implementation rather than two that happen to agree today.
+        warnInvalidGlobalConfigOnce(configPath, `global config could not be interpreted (${errorClassName(error)}); configuration ignored`, "PILENS_CFG_0008");
         return undefined;
     }
+    finally {
+        reportPiLensConfigRecords(notedRecords());
+    }
 }
 export function getGlobalIgnorePatterns(configPath) {
     return loadPiLensGlobalConfig(configPath)?.ignore ?? [];

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

@@ -18,6 +18,7 @@ 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 { extensionsForLanguageToken } from "./language-registry.js";
 import { initLSPConfig } from "./lsp/config.js";
 import { getLSPService } from "./lsp/index.js";
 import { acquireWarmWordIndex } from "./mcp/analyze.js";
@@ -27,14 +28,19 @@ import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
 import { getTreeSitterRuntimeStatus, } from "./tree-sitter-shared.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 { analyzeFile } from "./mcp/analyze.js";
 export { createMcpHost } from "./mcp/host-shim.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 { createWarmIpcLineReader, createWarmIpcRequestQueue, ipcPathForCwd, readTurnEndStatus, WARM_TURN_END_SCHEMA_VERSION, } from "./mcp/ipc.js";
+export { analyzeFileFresh, canRebuildPiLens, resolveRebuildScript, runRebuild, summarizeScan, } from "./mcp/review.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";
+// Effective-config introspection (#2427). A facade rather than a wrapper for
+// the same reason the others are: the computation reaches into the config
+// resolution, the LSP registry and the dispatch plan at once, and putting that
+// composition here would make this file the fourth place that knows how a
+// server is selected. Adapters route to it; nobody re-derives it.
+export { effectiveConfig, isEffectiveFileViewError, } from "./effective-config.js";
 // --- Query wrappers (own the remaining internal reach-ins) -------------------
 /** Recent dispatch latency reports (latency.log schema), newest first. */
 export function recentLatency(limit = 5, fileFilter) {
@@ -163,42 +169,28 @@ export function ensureLspConfig(cwd) {
 export function resourceFootprint() {
     return getResourceFootprintSnapshot();
 }
-// Same language identifiers ast_grep_search's `lang` param accepts
-// (tools/shared.ts's LANGUAGES) mapped to source file extensions. Duplicated
-// here rather than imported — clients/ never reaches into tools/ (see
-// AGENTS.md's MCP-mirror layering note) — so this is symbol_search's own small
-// copy, scoped to what its `lang` filter needs (extension matching only, no
-// AST/LSP concerns).
-const SYMBOL_SEARCH_LANG_EXTENSIONS = {
-    bash: [".sh", ".bash"],
-    c: [".c", ".h"],
-    cpp: [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx"],
-    csharp: [".cs"],
-    css: [".css", ".scss", ".less"],
-    elixir: [".ex", ".exs"],
-    go: [".go"],
-    haskell: [".hs", ".lhs"],
-    html: [".html", ".htm"],
-    java: [".java"],
-    javascript: [".js", ".jsx", ".mjs", ".cjs"],
-    json: [".json", ".jsonc", ".json5"],
-    kotlin: [".kt", ".kts"],
-    lua: [".lua"],
-    nix: [".nix"],
-    php: [".php"],
-    python: [".py", ".pyi"],
-    ruby: [".rb", ".rake", ".gemspec"],
-    rust: [".rs"],
-    scala: [".scala", ".sc"],
-    solidity: [".sol"],
-    swift: [".swift"],
-    tsx: [".tsx"],
-    typescript: [".ts", ".mts", ".cts"],
-    yaml: [".yaml", ".yml"],
-};
-function fileMatchesLang(file, lang) {
-    const exts = SYMBOL_SEARCH_LANG_EXTENSIONS[lang];
-    if (!exts)
+/**
+ * symbol_search's `lang` filter.
+ *
+ * The extension table this used to consult was a NINTH hand-written language ->
+ * extensions map, kept here because `clients/` never reaches into `tools/`
+ * (AGENTS.md's MCP-mirror layering note) — and it had drifted from every other
+ * one (#2424 review, S2): `css` claimed `.scss`/`.less`, `json` claimed
+ * `.jsonc`, `php` omitted its four alias extensions, `ruby` omitted `.ru`, and
+ * `solidity` was not a language the registry (or any grammar, or the ast-grep
+ * napi matrix) knows at all.
+ *
+ * The layering constraint was never a reason to duplicate the DATA, only a
+ * reason not to import the tool's token list. `extensionsForLanguageToken`
+ * resolves the token against the canonical registry instead.
+ *
+ * Exported so `tests/clients/language-registry-drift.test.ts` guards the SEAM
+ * and not just the projection behind it: a future local table reintroduced
+ * here would satisfy a registry-only assertion but fail this one.
+ */
+export function symbolSearchFileMatchesLang(file, lang) {
+    const exts = extensionsForLanguageToken(lang);
+    if (exts.length === 0)
         return false;
     return exts.includes(path.extname(file).toLowerCase());
 }
@@ -223,7 +215,7 @@ function buildSymbolSearchFileFilter(cwd, options) {
     return (file) => {
         if (paths?.length && !fileMatchesPathGlobs(file, cwd, paths))
             return false;
-        if (lang && !fileMatchesLang(file, lang))
+        if (lang && !symbolSearchFileMatchesLang(file, lang))
             return false;
         return true;
     };

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

@@ -2,7 +2,7 @@ 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;
+const LENS_EVENT_VERSION = 1;
 export const LENS_EVENT_NAMES = {
     analysisComplete: "pi-lens/analysis-complete",
     findings: "pi-lens/findings",