@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -63,4 +63,35 @@ export class RustClient {
     isRustFile(filePath) {
         return path.extname(filePath).toLowerCase() === ".rs";
     }
+    /** Forget the memoized cargo path and latched availability verdict — #2455. */
+    resetAvailability() {
+        this.availability.reset();
+    }
+}
+/**
+ * The one `RustClient` this process owns (#2455 fix round 4, F2).
+ *
+ * Same shape as `go-client.ts`'s `goClient`, and the same round-2 defect: the
+ * runner (`dispatch/runners/rust-clippy.ts`) and `bootstrap.ts` each built
+ * their own instance, so `resetRustAvailability` re-armed one latch while
+ * `handleSessionStart`'s "Active tools" line read the other's never-expiring
+ * probe-class "missing" verdict. One instance, in the module that owns the
+ * class; `tests/clients/toolchain-client-singleton.test.ts` holds the line.
+ */
+export const rustClient = new RustClient();
+/**
+ * Forget `rustClient`'s memoized cargo path and latched availability verdict —
+ * #2455. Same #1496/#1535 shape as `resetZizmorTokenAvailability`; wired into
+ * `handleSessionStart` beside it (`clients/runtime-session.ts`) so a Rust
+ * toolchain installed mid-process is observed by the next session instead of
+ * staying "missing" for the rest of the process's life.
+ *
+ * This module — not `rust-clippy.ts` — because the reset must sit beside the
+ * single instance it clears (#2455 fix round 4, F2). `rust-clippy.ts`'s
+ * `clippyAvailabilityByCargo` is a separate, already-covered latch: it rides
+ * `createCwdCachedProbe`'s shared `availabilityGeneration` counter (see
+ * `runner-helpers.ts`'s `resetDispatchAvailabilityState`), not this reset.
+ */
+export function resetRustAvailability() {
+    rustClient.resetAvailability();
 }

package/node_modules/pi-lens/dist/clients/safe-spawn.js

@@ -16,6 +16,7 @@
 import { spawn, spawnSync, } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { BoundedFifoMap } from "./bounded-cache.js";
 import { logLatency } from "./latency-logger.js";
 import { recordDegradation } from "./degradation-ledger.js";
 import { logExtension } from "./extension-log.js";
@@ -570,23 +571,21 @@ function resolveWindowsPathEntry(entry, effectiveCwd, env) {
  * cache is also count-bounded with oldest-entry eviction because a long-lived
  * process can encounter unbounded cwd/environment combinations.
  */
-const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
+export const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
 const WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS = 1000;
-const windowsCommandCache = new Map();
+const windowsCommandCache = new BoundedFifoMap(WINDOWS_COMMAND_CACHE_MAX_ENTRIES);
 /** Reset after session replacement or a successful managed install. */
 export function resetSafeSpawnWindowsCommandCache() {
     windowsCommandCache.clear();
     loggedSpawnClassifications.clear();
 }
 function cacheWindowsCommandResult(key, resolved) {
-    if (windowsCommandCache.size >= WINDOWS_COMMAND_CACHE_MAX_ENTRIES) {
-        // Resolution entries are session-scoped and cheap to recompute. Evict the
-        // oldest insertion first so a long-lived process cannot retain every cwd /
-        // environment it has ever touched.
-        const oldest = windowsCommandCache.keys().next().value;
-        if (oldest !== undefined)
-            windowsCommandCache.delete(oldest);
-    }
+    // Resolution entries are session-scoped and cheap to recompute. The
+    // caller always deletes any stale entry for `key` before reaching here
+    // (see resolveWindowsCommandForEnvironment), so this can only grow the
+    // map; BoundedFifoMap evicts the oldest insertion first once the map
+    // exceeds capacity, so a long-lived process cannot retain every cwd /
+    // environment it has ever touched.
     windowsCommandCache.set(key, { resolved, checkedAt: Date.now() });
 }
 function getPathExts(env) {
@@ -848,6 +847,30 @@ const EXIT_PIPE_IDLE_MAX_WAIT_MS = 2000;
  * - Kills the process on timeout (preventing zombies)
  * - Supports cancellation via AbortSignal
  *
+ * ## Why this bound is NOT `bounded()` — the one documented exception (#2523)
+ *
+ * #2523 slice 2 folded every other "deadline AND abort signal" implementation
+ * in the tree onto `clients/deadline-utils.ts#bounded`. This one stays, and it
+ * is not a copy of the same idea:
+ *
+ * `bounded()` ABANDONS a promise — it stops waiting and lets the work run on
+ * unobserved, which is safe precisely because everything it wraps is in-process
+ * (a dynamic import, an LSP round trip, a `stat`). This function's work is a
+ * CHILD PROCESS, and abandoning one leaks it. So its timer does not settle a
+ * race at all: `timeoutId` sets `timedOut`, then runs `killTree()` — SIGTERM,
+ * an escalation timer, SIGKILL, and on Windows a `taskkill /T` of the whole
+ * tree — and the promise settles only when the child's own `close` arrives (or
+ * the escalation gives up). The result it produces carries the teardown
+ * EVIDENCE (`timeoutTeardown`, #2010): which signal killed it, whether the
+ * tree actually died, how long it took. Replacing that with `bounded()` would
+ * return `undefined` at the deadline and leave a live `vitest`/`gradle` behind
+ * — the orphan class #2504 measured as 59 concurrent spawns starving a turn.
+ *
+ * The rule the exception preserves: a bound that can CANCEL its work must
+ * cancel it. `bounded()` is for work that cannot be cancelled; this is not
+ * that. Anything wrapping THIS function still gets `bounded()` around its own
+ * await if it needs one.
+ *
  * @example
  * const result = await safeSpawnAsync("npm", ["test"], { timeout: 30000 });
  * if (result.error) console.error("Failed:", result.error);

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

@@ -6,8 +6,14 @@
  */
 // --- Constants ---
 // ANSI escape codes for colors and formatting
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is the literal ANSI escape-sequence lead byte this pattern strips, not accidental input.
 const ANSI_ESCAPE = /\x1b\[[0-9;]*m/g;
-const ANSI_ESCAPE_EXTENDED = /\x1b\[[0-9;]*[A-Za-z]/g;
+// Full ECMA-48 CSI grammar (parameter bytes 0-9;? , intermediate bytes
+// space-/, final byte @-~) — matches every CSI sequence ANSI_ESCAPE does
+// plus non-SGR ones (cursor moves, private-mode `?` sequences like
+// `\x1b[?25l`, etc.), not just the `m`-terminated color codes.
+// oxlint-disable-next-line no-control-regex -- ESC (\x1b) is the literal ANSI escape-sequence lead byte this pattern strips, not accidental input.
+const ANSI_ESCAPE_EXTENDED = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 // Common error patterns from different tools
 const ERROR_INDICATORS = [
     /\berror\b/i,
@@ -37,17 +43,6 @@ const DETAIL_PATTERNS = [
 export function stripAnsi(text) {
     return text.replace(ANSI_ESCAPE, "").replace(ANSI_ESCAPE_EXTENDED, "");
 }
-/**
- * Normalize whitespace in a string.
- * Collapses multiple spaces/tabs to single space, trims lines.
- */
-export function normalizeWhitespace(text) {
-    return text
-        .split(/\r?\n/)
-        .map((line) => line.replace(/\s+/g, " ").trim())
-        .filter((line) => line.length > 0)
-        .join("\n");
-}
 /**
  * Check if a line contains error indicators.
  */

package/node_modules/pi-lens/dist/clients/scan-utils.js

@@ -1,59 +1,4 @@
-import { isExcludedDirName, isTestFile } from "./file-utils.js";
-import { collectSourceFiles, collectSourceFilesAsync, isBuildArtifact, } from "./source-filter.js";
-/**
- * Common parsing logic for ast-grep JSON output (handles both array and NDJSON).
- */
-// biome-ignore lint/suspicious/noExplicitAny: ast-grep JSON output is untyped
-export function parseAstGrepJson(raw) {
-    if (!raw)
-        return [];
-    const trimmed = raw.trim();
-    if (trimmed.startsWith("[")) {
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch {
-            return [];
-        }
-    }
-    return trimmed.split("\n").flatMap((l) => {
-        try {
-            return [JSON.parse(l)];
-        }
-        catch {
-            return [];
-        }
-    });
-}
-/**
- * Check if a file should be ignored based on project type and common patterns.
- *
- * @deprecated Use `isBuildArtifact()` from `source-filter.js` instead for artifact
- * detection, or compose your own filter using `collectSourceFiles()`. This function
- * is kept for backward compatibility.
- */
-export function shouldIgnoreFile(filePath, isTsProject) {
-    const relPath = filePath.replace(/\\/g, "/");
-    // Use new source-filter module for artifact detection
-    if (isTsProject && isBuildArtifact(filePath))
-        return true;
-    // Legacy: simple JS check for non-TS projects (hand-written JS)
-    const isJs = relPath.endsWith(".js") ||
-        relPath.endsWith(".mjs") ||
-        relPath.endsWith(".cjs");
-    if (isTsProject && isJs)
-        return true;
-    // Ignore test scripts and common test patterns
-    if (isTestFile(filePath))
-        return true;
-    // Ignore hidden directories and common build outputs
-    const pathParts = relPath.split("/").filter(Boolean);
-    for (const segment of pathParts.slice(0, -1)) {
-        if (isExcludedDirName(segment))
-            return true;
-    }
-    return false;
-}
+import { collectSourceFiles, collectSourceFilesAsync, } from "./source-filter.js";
 /**
  * Recursively find source files in a directory, respecting common excludes.
  *

package/node_modules/pi-lens/dist/clients/scratch-tree-policy.js

@@ -54,6 +54,7 @@
  *     fully in scope.
  */
 import { EXCLUDED_DIRS, getExcludedDirGlobs } from "./file-utils.js";
+import { escapeRegExp } from "./string-utils.js";
 /** Directory-name entries only — drops glob entries (e.g. `*.dSYM`) that a
  * bare directory-name/regex exclude can't express. */
 function literalExcludedDirNames() {
@@ -68,9 +69,6 @@ function literalExcludedDirNames() {
 export function getScratchTreeGlobPatterns() {
     return getExcludedDirGlobs();
 }
-function escapeRegExp(literal) {
-    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 /** Bare directory names, for tools (opengrep/semgrep `--exclude`) that treat a
  * slash-free pattern as "this directory name, anywhere in the tree". */
 export function getScratchTreeDirNames() {

package/node_modules/pi-lens/dist/clients/security-scan-client.js

@@ -71,6 +71,7 @@ export class SecurityScanClient {
     logDurableAbsence(evidence, elapsedMs = 0) {
         logAvailabilityDecision({
             tool: this.toolName,
+            producer: "security-scan",
             verdict: "unavailable",
             outcome: "missing",
             cause: "not-found",
@@ -154,6 +155,7 @@ export class SecurityScanClient {
             this.log(`${this.toolName} found: ${probe.stdout.trim().split("\n")[0]}`);
             logAvailabilityDecision({
                 tool: this.toolName,
+                producer: "security-scan",
                 verdict: "available",
                 outcome: "success",
                 cause: "ok",
@@ -185,6 +187,7 @@ export class SecurityScanClient {
             : 0;
         logAvailabilityDecision({
             tool: this.toolName,
+            producer: "security-scan",
             verdict: "unavailable",
             outcome,
             cause,

package/node_modules/pi-lens/dist/clients/session-lifecycle.js

@@ -91,7 +91,7 @@ export function getActivePrimaryRoot() {
  * `concurrent-secondary`: skip the destructive resets and the expensive
  * battery, leave the registered primary's ctx/session id/root untouched. The
  * root still gets served — `initLSPConfig` registers session roots lazily,
- * per file (`clients/lsp/session-roots.ts:48`), not from this handler.
+ * per file (`clients/lsp/session-roots.ts`), not from this handler.
  *
  * Ordering note: the root check sits BELOW the `priorCtxActive === true`
  * branch so a live sibling still reports the more specific

package/node_modules/pi-lens/dist/clients/session-start-observability.js

@@ -1,10 +1,42 @@
 import { logLatency } from "./latency-logger.js";
+import { getProcessSingleton } from "./process-singletons.js";
 /**
  * The complete observability path for a concurrent secondary. It deliberately
  * emits one bind record only: secondary sessions skip every primary reset and
  * hydration phase.
  */
+// #2249: bounded per-session rollup of declined binds, counted at this shared
+// seam so every decline the process's PRIMARY has seen this session —
+// `concurrent-secondary` and `secondary-root` alike — is summarized in one row
+// at session end instead of requiring a reader to hand-count
+// `concurrent_session_bind` lines. Process-singleton backed (AGENTS.md catalog
+// shape 25), NOT a module-scope `let` like the other `*_rollup` counters
+// (bus-events-logger.ts, path-attribution-telemetry.ts): a `let` here exists
+// once per module EVALUATION, not once per process, and #2146 measured one pid
+// evaluating this exact graph nine times — a bare `let` would only ever see
+// the binds routed through its own copy, undercounting every rollup that
+// isn't reached through the first evaluation. `decideSessionStart` never
+// returns a declined classification outside `concurrent-secondary`/
+// `secondary-root` (session-lifecycle.ts), so those two are the whole
+// contract; `unclassified` is a bounded third bucket for the legacy callers
+// this function's `classification?` param still accepts.
+const BIND_ROLLUP_FAMILY = "concurrent-session-bind-rollup";
+const BIND_ROLLUP_VERSION = 1;
+function bindRollupCounts() {
+    return getProcessSingleton(BIND_ROLLUP_FAMILY, BIND_ROLLUP_VERSION, () => ({
+        "concurrent-secondary": 0,
+        "secondary-root": 0,
+        unclassified: 0,
+    }));
+}
+function bindRollupKey(classification) {
+    return classification === "concurrent-secondary" ||
+        classification === "secondary-root"
+        ? classification
+        : "unclassified";
+}
 export function logConcurrentSessionBind(args) {
+    bindRollupCounts()[bindRollupKey(args.classification)] += 1;
     logLatency({
         type: "phase",
         filePath: "<pi-lens>",
@@ -13,3 +45,50 @@ export function logConcurrentSessionBind(args) {
         metadata: args,
     });
 }
+/** Snapshot of the current rollup counters, keyed by classification.
+ *  Non-mutating — for tests/observability, mirroring
+ *  `getBusEventRollupCounts`/`getVerifiedPathAttributionGuessCount`. */
+export function getConcurrentSessionBindRollupCounts() {
+    return { ...bindRollupCounts() };
+}
+/**
+ * Log one `concurrent_session_bind_rollup` row summarizing this session's
+ * declined binds by classification, then clear the counters. Call from
+ * index.ts's `session_shutdown` handler at the same primary-only placement as
+ * `emitBusEventRollupAtSessionEnd`/`emitVerifiedPathAttributionRollup` — a
+ * concurrent secondary's own shutdown returns before reaching that point, and
+ * the counters are process-wide state a still-live secondary would still need.
+ * A no-op when nothing was ever declined this session, matching those same
+ * rollups' "no noise on an ordinary session" shape.
+ */
+export function emitConcurrentSessionBindRollupAtSessionEnd(cwd) {
+    const counts = bindRollupCounts();
+    const total = counts["concurrent-secondary"] +
+        counts["secondary-root"] +
+        counts.unclassified;
+    if (total === 0)
+        return;
+    logLatency({
+        type: "phase",
+        filePath: cwd,
+        phase: "concurrent_session_bind_rollup",
+        durationMs: 0,
+        metadata: { ...counts },
+    });
+    resetConcurrentSessionBindRollupCounts();
+}
+/**
+ * Session-boundary reset (AGENTS.md catalog shape 17). Call from index.ts's
+ * `session_start` handler on the PRIMARY continuation path only — never from
+ * a declined bind's own `session_start`, which is exactly what increments
+ * these counters, so resetting there would erase every prior sibling's tally
+ * from the same primary session. Covers the case a primary session never
+ * reaches `session_shutdown` (a crash, a forced kill) and the process's next
+ * primary must still start from zero. Also exported for tests.
+ */
+export function resetConcurrentSessionBindRollupCounts() {
+    const counts = bindRollupCounts();
+    counts["concurrent-secondary"] = 0;
+    counts["secondary-root"] = 0;
+    counts.unclassified = 0;
+}

package/node_modules/pi-lens/dist/clients/session-summary.js

@@ -1,30 +1,6 @@
 /**
  * Session Summary — generates turn_end and session-end summaries
  */
-export function formatSessionSummary(stats) {
-    if (stats.totalShown === 0)
-        return "";
-    const lines = [
-        "## Diagnostic Summary",
-        "",
-        `Shown to agent: ${stats.totalShown}`,
-        `Auto-fixed: ${stats.totalAutoFixed} (${pct(stats.totalAutoFixed, stats.totalShown)}%)`,
-        `Fixed by agent: ${stats.totalAgentFixed} (${pct(stats.totalAgentFixed, stats.totalShown)}%)`,
-        "",
-    ];
-    if (stats.topViolations.length > 0) {
-        lines.push("Top violations:");
-        for (const { ruleId, count } of stats.topViolations.slice(0, 5)) {
-            lines.push(`  - ${ruleId} (${count}x)`);
-        }
-    }
-    return lines.join("\n");
-}
-function pct(part, total) {
-    if (total === 0)
-        return "0";
-    return Math.round((part / total) * 100).toString();
-}
 export function formatSlopScoreSummary(summary) {
     if (summary.totalRuleDiagnostics === 0 || summary.totalKlocWritten <= 0) {
         return "";

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

@@ -1,10 +1,19 @@
 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 { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-export const SESSIONSTART_LOG_FILE = path.join(getGlobalPiLensDir(), "sessionstart.log");
+export const SESSIONSTART_LOG_FILE = path.join(getGlobalPiLensLogDir(), "sessionstart.log");
 // All ordinary writers share this queue, preserving their in-process order.
-const writer = createNdjsonLogger({ filePath: SESSIONSTART_LOG_FILE });
+// Bounded like every other global sink (#2505): an unbounded sink has no
+// size check on the write path at all, so it grows until the
+// once-per-process session-start sweep happens to look at it — which, in a
+// long-lived process (the warm MCP server), may be never.
+const writer = createNdjsonLogger({
+    filePath: SESSIONSTART_LOG_FILE,
+    maxBytes: getMaxLogSizeMB() * 1024 * 1024,
+    backupPath: `${SESSIONSTART_LOG_FILE}.1`,
+});
 export function logSessionStart(message) {
     if (isTestMode())
         return;

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

@@ -8,8 +8,13 @@ import { findLocalToolConfig } from "./path-utils.js";
 // ast-grep's root config marker. The `ast-grep lsp` server is workspace-gated:
 // it only operates in a project that has an `sgconfig.y[a]ml` at (or above) the
 // file. These are the names ast-grep itself looks for as root markers.
-export const SGCONFIG_NAMES = ["sgconfig.yml", "sgconfig.yaml"];
-/** Nearest `sgconfig.y[a]ml` walking up from `startDir`, or undefined if none. */
+const SGCONFIG_NAMES = ["sgconfig.yml", "sgconfig.yaml"];
+/**
+ * Nearest `sgconfig.y[a]ml` walking up from `startDir`, or undefined if none.
+ * Deliberately UNCEILINGED at $HOME (refs #2472 review round 3, F1): ast-grep
+ * itself resolves `~/sgconfig.yml` as a legitimate global root config, not an
+ * escaped-workspace accident.
+ */
 export function findLocalSgconfig(startDir) {
     return findLocalToolConfig(startDir, SGCONFIG_NAMES);
 }
@@ -60,10 +65,6 @@ export function getAstGrepRuleSources(projectRoot = process.cwd()) {
         return true;
     });
 }
-/** Compatibility export retained for callers that only need ordered dirs. */
-export function shippedRuleDirsInPrecedenceOrder(projectRoot = process.cwd()) {
-    return getAstGrepRuleSources(projectRoot).map((source) => source.dir);
-}
 function findYamlFiles(dir) {
     const files = [];
     let entries;

package/node_modules/pi-lens/dist/clients/shared-checkout-guard.js

@@ -115,7 +115,7 @@ function isCleanDryRun(argsAfterVerb) {
  * replacement for the forbidden `git stash`. Blocking it would push
  * operators back toward stash.
  */
-export const WORKTREE_MUTATING_GIT_MATCHER = {
+const WORKTREE_MUTATING_GIT_MATCHER = {
     id: "worktree-mutating",
     indirectAlwaysMatches: false,
     // `git checkout --help` opens documentation and changes nothing. This

package/node_modules/pi-lens/dist/clients/skills-resolver.js

@@ -0,0 +1,105 @@
+/**
+ * Resolves the skills directory the `resources_discover` handler (#205)
+ * registers, and reports the one condition that pi previously loaded with NO
+ * visible signal: `<packageRoot>/skills` is absent, unreadable, or holds no
+ * skill pi's own loader would find (#2626).
+ *
+ * `resolvePackagePath(import.meta.url, "skills")`-equivalent resolution
+ * (`clients/package-root.ts`'s `getPackageRoot`) is correct for both the
+ * source and compiled `dist/` layouts — it walks up from the loaded entry
+ * file to the nearest `package.json`. It goes wrong silently, not loudly,
+ * when that walk lands somewhere with no `skills/` beside it: `skills/`
+ * missing from an installed package, or the entry file copied out of the
+ * package tree by a managed extension cache so the nearest `package.json`
+ * is the cache's own. Either way `resources_discover` used to hand pi a
+ * path that does not exist, `pi` registered zero skills, and nothing — no
+ * extension error, no stderr line — said so (investigated on #2587).
+ *
+ * #2626 review round 2, F1: the FIRST version of this fix inverted the
+ * acceptance criterion — it returned `[]` (no skills registered) whenever
+ * its own predicate disagreed with pi's real loader, which is worse than
+ * the bug it fixed on every layout the predicate got wrong (dropping skills
+ * pi WOULD have loaded, a regression vs. pre-fix `master`). The acceptance
+ * criteria ask for a RECORD, never a changed return value: this module
+ * returns `[skillsDir]` UNCONDITIONALLY, exactly like the pre-fix handler —
+ * pi's own `loadSkills`/`collectSkillEntries` already treat a nonexistent
+ * path as zero skills from that entry, gracefully, so handing it a path
+ * that turns out to be empty is exactly as safe as `master`'s behavior
+ * always was. The health check below is PURELY observational.
+ *
+ * #2636 review F4: the ENOENT/EACCES classification shell below used to be
+ * hand-rolled here, character-identical to the ast-grep/tree-sitter sites
+ * #2636 fixed for the same silent-zero shape — now shared via
+ * `bundled-resource-health.ts`, with `scanEntriesForSkills` supplied as this
+ * module's own "what counts as found" predicate.
+ */
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as fs from "node:fs";
+import { scanEntriesForSkills } from "../scripts/lib/skills-predicate.mjs";
+import { classifyBundledResourceDir, describeBundledResourceHealth, reportBundledResourceDirHealth, } from "./bundled-resource-health.js";
+import { logLatency } from "./latency-logger.js";
+import { getPackageRoot } from "./package-root.js";
+/** The ledger kind this module records under (`clients/degradation-ledger.ts`). */
+const SKILLS_DIR_MISSING_KIND = "skills-dir-missing";
+/**
+ * Read `skillsDir` and classify it, sharing `classifyBundledResourceDir`'s
+ * ENOENT/EACCES/empty shell but counting pi-LOADABLE skill entry points
+ * (`scanEntriesForSkills`), not a bare directory listing — a `skills/`
+ * holding only a stray `.gitkeep` must read "empty", not "healthy".
+ */
+function checkSkillsHealth(skillsDir) {
+    return classifyBundledResourceDir(skillsDir, (dir) => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        return scanEntriesForSkills(dir, entries, true).length;
+    });
+}
+/**
+ * Resolve the skill path for `resources_discover`. ALWAYS returns
+ * `[skillsDir]` (see the module doc for why — F1). When `skillsDir` is
+ * absent, unreadable, or holds no skill pi's loader would find, records ONE
+ * bounded `skills-dir-missing` degradation and a single `notifyUserDegradation`
+ * warning, both naming the resolved path and the entry file's directory.
+ *
+ * Either way, one `skills_resolved` phase/latency record is written so an
+ * empty ledger (no `skills-dir-missing` row) is distinguishable from
+ * "`resources_discover` never ran at all" (#2626 review F5) — the SAME
+ * silent-zero shape one level up the call stack.
+ */
+export function resolveSkillPaths(importMetaUrl) {
+    const packageRoot = getPackageRoot(importMetaUrl);
+    const skillsDir = path.join(packageRoot, "skills");
+    const health = checkSkillsHealth(skillsDir);
+    logLatency({
+        type: "phase",
+        phase: "skills_resolved",
+        filePath: skillsDir,
+        durationMs: 0,
+        metadata: {
+            status: health.status,
+            entryCount: health.status === "healthy" ? health.entryCount : 0,
+        },
+    });
+    if (health.status !== "healthy") {
+        const entryDir = path.dirname(fileURLToPath(importMetaUrl));
+        const reason = `${describeBundledResourceHealth(health, skillsDir, `no SKILL.md (or loadable .md) found under ${skillsDir}`)} (entry loaded from ${entryDir})`;
+        // #2626 review F3: the notify-once gate previously re-derived "have we
+        // already recorded this" by scanning `getDegradationSummary()` and
+        // comparing the RAW `skillsDir` against subjects the ledger stores
+        // `truncateForLedger`-ed — a mismatch on any subject over
+        // `LEDGER_FIELD_MAX` (200 chars, an ordinary length for a managed-cache
+        // path) renotified on every call. `reportBundledResourceDirHealth`
+        // reads `incrementDegradationCount`'s own return value for the rising
+        // edge, computed after the SAME truncation the ledger stores by, so
+        // there is no separate key to keep in sync.
+        // #2636 review round 2, F1: the shipped notify sentence ("registers
+        // zero skills") is user-visible product text #2626 chose deliberately
+        // — it names the exact SYMPTOM this whole issue exists to surface, so
+        // the shared helper's generic "<label> unavailable" template must
+        // never silently replace it. Passed explicitly rather than inferred
+        // from `label` so this stays a per-caller decision, not a convention
+        // the next caller has to remember.
+        reportBundledResourceDirHealth(SKILLS_DIR_MISSING_KIND, skillsDir, health, "skills", reason, `pi-lens: registers zero skills — ${reason}.`);
+    }
+    return [skillsDir];
+}

package/node_modules/pi-lens/dist/clients/smells-rollup.js

@@ -55,14 +55,14 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 /** Bounded tail-read budget PER source log file — never a full-file scan. */
 export const SMELLS_TAIL_BYTES_PER_FILE = 64 * 1024;
-export const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
+const SMELLS_ROLLING_WINDOW_MS = 24 * 60 * 60_000;
 /** Re-check cadence at `turn_end`, mirroring `memory-sampler.ts`'s pattern —
  *  cheap enough (bounded ~128KB I/O) not to need finer throttling, but a
  *  fixed interval keeps it from running on every single turn. */
-export const SMELLS_TURN_CHECK_INTERVAL = 20;
+const SMELLS_TURN_CHECK_INTERVAL = 20;
 /** Trivial threshold constants (#1123 item 3's explicit design ask). Counts
  *  strictly below these never surface anywhere. */
 export const SMELLS_THRESHOLDS = {
@@ -159,7 +159,7 @@ function isOpengrepRespawn(entry) {
  * `2 * SMELLS_TAIL_BYTES_PER_FILE` regardless of how large the (size-rotated,
  * up to ~10MB) source files are. `root` is injectable for tests.
  */
-export function countRecentSmells(root = getGlobalPiLensDir(), sessionStartMs) {
+export function countRecentSmells(root = getGlobalPiLensLogDir(), sessionStartMs) {
     const sinceMs = sessionStartMs ?? Date.now() - SMELLS_ROLLING_WINDOW_MS;
     const busTail = tailReadText(path.join(root, "bus-events.log"), SMELLS_TAIL_BYTES_PER_FILE);
     const latencyTail = tailReadText(path.join(root, "latency.log"), SMELLS_TAIL_BYTES_PER_FILE);

package/node_modules/pi-lens/dist/clients/startup-scan.js

@@ -16,7 +16,7 @@ import { isAtOrAboveHomeDir } from "./path-utils.js";
 import { getStartupScanMaxSourceFilesDerived } from "./project-scale.js";
 import { shouldRecurseIntoDir, walkTreeStackAsync, walkTreeStackSync, } from "./source-walker.js";
 import { getDirectoryMarkers, registerWorkspaceTopologyReset, } from "./workspace-topology.js";
-export const PROJECT_ROOT_MARKERS = [
+const PROJECT_ROOT_MARKERS = [
     ".git",
     "package.json",
     "pyproject.toml",
@@ -24,16 +24,8 @@ export const PROJECT_ROOT_MARKERS = [
     "go.mod",
     "composer.json",
 ];
-// Deprecated (#776): no longer read directly below — `computeStartupScanContext`
-// / `resolveStartupScanContextAsync` now default `maxSourceFiles` to
-// `getStartupScanMaxSourceFilesDerived(cwd)` (project-scale.ts's
-// `maxProjectFiles` knob), which reproduces this same 2,000 value at the
-// default base. Kept exported for tests/callers that still reference the
-// literal.
-export const MAX_STARTUP_SOURCE_FILES = 2000;
 // #758: hard ceiling on the number of directory entries the startup source
 // count walk will visit before it gives up and declares the tree too big to
-// warm. The source-file early-exit (MAX_STARTUP_SOURCE_FILES) only fires when
 // a project has MANY source files — a repo with FEW source files but a huge
 // pile of non-source files (e.g. a game mod: 300 scripts among 84k data files)
 // never trips it, so the pre-#758 walk traversed the entire tree, dominated by
@@ -77,7 +69,7 @@ export const _resetStartupScanMaxEntriesForTests = _maxEntries._resetForTests;
  *
  * The content-derived reasons `too-many-source-files` and `too-many-entries`
  * (#758) are the ones that are TTL'd. They can go stale on their own: the repo
- * can shrink below `MAX_STARTUP_SOURCE_FILES` (or below the entry ceiling)
+ * can shrink below the source-file cap (or below the entry ceiling)
  * between sessions, and nothing else would notice
  * — the seq-based freshness check that guards every other
  * `project-snapshot.json` field never fires for them, because pi-lens never

package/node_modules/pi-lens/dist/clients/string-utils.js

@@ -18,3 +18,16 @@
 export function compareOrdinal(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+/**
+ * Escape a string for safe interpolation into a `RegExp` source, so every
+ * regex metacharacter it contains is matched literally instead of taking on
+ * its regex meaning. This is the ONE runtime copy (#2558) — string-utils.ts
+ * is a leaf (no imports of its own), so importing it never creates a cycle.
+ * Before #2558 this same body was hand-copied under this name (and as
+ * `escapeRegExpChar`/`escapeRegExpLiteral`) into ~8 production modules and 3
+ * test helpers; fold new call sites onto this export instead of re-copying
+ * it.
+ */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}