pi-lens 4.1.2 → 4.1.4

package/rules/tree-sitter-queries/python/python-cross-language-method.yml

@@ -9,7 +9,7 @@ defect_class: hallucination
 inline_tier: warning
 language: python
 
-message: "'{METHOD}' is not a Python method — likely a {LANG} idiom leaking in"
+message: "'{{METHOD}}' is not a Python method — likely a cross-language idiom leaking in"
 
 description: |
   A method name from another language is being called on a Python object.
@@ -27,7 +27,7 @@ query: |
     function: (attribute
       object: (_) @OBJ
       attribute: (identifier) @METHOD)
-    (#match? @METHOD "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"))
+    (#match? @METHOD "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"))
 
 metavars:
   - OBJ
@@ -35,7 +35,7 @@ metavars:
 
 post_filter: match_captures
 post_filter_params:
-  METHOD: "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"
+  METHOD: "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"
 
 has_fix: false
 

package/rules/tree-sitter-queries/python/python-hallucinated-import.yml

@@ -9,7 +9,7 @@ defect_class: hallucination
 inline_tier: blocking
 language: python
 
-message: "Hallucinated import — '{NAME}' does not exist in '{MODULE}'"
+message: "Hallucinated import — '{{NAME}}' does not exist in '{{MODULE}}'"
 
 description: |
   This import is from the wrong package. A name from one framework is being
@@ -32,7 +32,7 @@ metavars:
 
 post_filter: match_captures
 post_filter_params:
-  MODULE: "^(requests|flask|django|typing|collections|asyncio|json|unittest|pytest|urllib|sqlalchemy)$"
+  MODULE: "^(requests|flask|django|typing|collections|asyncio|json|unittest|pytest|urllib)$"
   NAME: "^(JSONResponse|HTMLResponse|RedirectResponse|StreamingResponse|Depends|Query|Path|Body|Header|Cookie|Form|File|UploadFile|FastAPI|APIRouter|HTTPException|BackgroundTasks|dataclass|fields|BaseModel|Field|validator|aiohttp|parse|stringify|fixture|TestCase|get|post|put|delete|Model|Session|Column|Integer|String)$"
 
 has_fix: false

package/rules/tree-sitter-queries/python/python-sql-injection.yml

@@ -18,8 +18,18 @@ description: |
   
   Suppressed:
   - cursor.execute(query, params) — parameterized query (safe)
-  - session.execute(select(...)) — SQLAlchemy ORM (safe by construction)
-  - cursor.execute(f"...") — f-string with literal-only interpolation (rare false positive)
+  - session.execute(...) — receiver conventionally named for a SQLAlchemy session
+  - x.execute(select(...)) — statement builder in argument position (safe by
+    construction)
+  - db.query(...) / db.execute(stmt) where `db: Session` and `Session` is proven
+    from a same-file `sqlalchemy.orm` / `sqlalchemy.ext.asyncio` import, and
+    `stmt` is bound exactly once to a builder call
+  - cursor.execute(sql.SQL("...").format(sql.Identifier(...))) where `sql` is
+    an unshadowed same-file psycopg or psycopg2 import and every format argument
+    is an Identifier
+
+  Other raw, dynamic, or ambiguous SQL remains diagnostic so this rule fails
+  closed when it cannot prove the safe API provenance.
   
   ✅ FIX: use placeholders and parameter binding instead of string composition.
 

package/scripts/analyze-pi-lens-logs.mjs

@@ -221,6 +221,35 @@ function createState(files) {
 				progress: [],
 			},
 		},
+		// #2526: the config stack's positive-observability rows. `resolved`
+		// counts `config_resolved` phase records; `legacyWithoutRecords` counts
+		// the rows that carry a deprecated document but produced no
+		// migration/notice record — the deprecation machinery gone silent.
+		//
+		// Round 2, F2: the session->row relation is a JOIN on the session id both
+		// sides carry, not a subtraction of two counts.
+		//
+		// Round 3, S1: the session-side half of the join is no longer a
+		// PREDICTION. `pendingSessions` holds every session id that published a
+		// `config_resolution_pending` mark — written by `loadLSPConfig` itself,
+		// at the instant a resolution is actually attempted, never by a
+		// `runtime-session.ts` handler guessing from `no-lsp`/subagent/warm-attach
+		// flags ahead of time. A session that never reaches that call (quick or
+		// minimal mode's second-and-later session in a process, for the same
+		// root) never gets a mark, so it is silently excluded rather than
+		// counted against. `resolvedSessions` holds every session id a
+		// resolution actually reported, from EITHER sink (the latency row or the
+		// sessionstart line — one call writes both, so this is one fact
+		// surviving an independent rotation of either log, not a second source
+		// of truth).
+		config: {
+			resolved: 0,
+			pendingSessions: new Map(),
+			resolvedSessions: new Set(),
+			legacyDocuments: 0,
+			legacyWithoutRecords: 0,
+			examples: [],
+		},
 		diagnostics: {
 			bySeverity: counter(),
 			byTool: counter(),
@@ -351,7 +380,44 @@ async function analyzeLatency(files, state) {
 			} else if (entry.type === "phase") {
 				const phase = entry.phase ?? "unknown";
 				state.latency.phaseCounts.inc(phase);
-				if (/_timeout$/.test(phase)) state.latency.phaseTimeouts.inc(phase);
+				if (phase.endsWith("_timeout")) state.latency.phaseTimeouts.inc(phase);
+				if (phase === "config_resolved") {
+					// #2526. Counted here rather than derived from phaseCounts so the
+					// legacy/record cross-check reads the same row it counts.
+					state.config.resolved += 1;
+					const md = entry.metadata ?? {};
+					// #2526 R2 F2 / #2552 R4: the join key is (session, root), not
+					// session alone — see `configJoinKey`'s doc comment. `entry.filePath`
+					// is this row's root (the same `configResolutionKey(cwd)` value the
+					// pending mark's `root=` carries); a row from a build that predates
+					// the session id carries none, and simply joins to nothing.
+					if (
+						typeof md.sessionId === "string" &&
+						md.sessionId.length > 0 &&
+						typeof entry.filePath === "string" &&
+						entry.filePath.length > 0
+					) {
+						state.config.resolvedSessions.add(
+							configJoinKey(md.sessionId, entry.filePath),
+						);
+					}
+					const documents = Array.isArray(md.documents) ? md.documents : [];
+					const legacy = documents.filter((doc) => doc?.legacy === true);
+					state.config.legacyDocuments += legacy.length;
+					// A deprecated document that produced NO record means the
+					// migration notices went silent — the user is on a removal
+					// schedule and is never told. Zero records with zero legacy
+					// documents is the correct canonical-only answer, not a smell.
+					if (legacy.length > 0 && Number(md.recordCount ?? 0) === 0) {
+						state.config.legacyWithoutRecords += 1;
+						pushTop(
+							state.config.examples,
+							summarizeConfigResolved(entry, "legacy document with 0 records"),
+							limit * 3,
+							byDuration,
+						);
+					}
+				}
 				if (
 					phase === "total" &&
 					(entry.durationMs ?? 0) >= thresholds.totalSlowMs
@@ -636,6 +702,40 @@ async function analyzeSessionStart(files, state) {
 				trackProject(state, cwd);
 			}
 
+			// #2526 R3 S1: this session's config-resolution PENDING mark, published
+			// by `loadLSPConfig` itself at the instant a resolution is actually
+			// attempted — never a start-line prediction from `no-lsp`/subagent/
+			// warm-attach flags. A session that never calls `loadLSPConfig` (quick
+			// or minimal mode's second-and-later session in a process, for the
+			// same root) never writes this line, and is correctly absent from the
+			// join rather than counted against.
+			//
+			// #2552 R4: `root=` is REQUIRED in the match — a warm MCP process keeps
+			// one session id for its whole life but marks once per served root
+			// (`configJoinKey`'s doc comment), so a line missing it cannot be
+			// attributed to a specific root and is left out of the join rather than
+			// guessed into a wrong one.
+			const pending =
+				/session_start config_resolution_pending session=(\S+) root=(.*)$/.exec(
+					message,
+				);
+			if (pending) {
+				const [, sessionId, root] = pending;
+				state.config.pendingSessions.set(configJoinKey(sessionId, root), {
+					ts: iso(ts),
+					sessionId,
+					root,
+				});
+			}
+			// The loader's own line is the second half of the join, so a rotated
+			// latency.log cannot manufacture a deficit on its own.
+			const resolvedSession =
+				/config resolved .*\bsession=(\S+) root=(.*)$/.exec(message);
+			if (resolvedSession) {
+				const [, sessionId, root] = resolvedSession;
+				state.config.resolvedSessions.add(configJoinKey(sessionId, root));
+			}
+
 			const total = /session_start total:\s*(\d+)ms/.exec(message);
 			if (total && Number(total[1]) >= thresholds.startupSlowMs) {
 				state.smellTotals.inc("slow-session-start");
@@ -899,6 +999,23 @@ function iso(date) {
 	return date?.toISOString?.() ?? "unknown";
 }
 
+/**
+ * The config-resolution join key (#2552 review round 4). A warm MCP process
+ * keeps ONE session id for its entire life but calls `loadLSPConfig` once per
+ * SERVED ROOT (#2526 review round 2, F3's premise, reintroduced one layer up
+ * here) — joining on session id alone let one root's row silently clear every
+ * OTHER root's deficit under the same session id. `root` is whatever string
+ * the producer already wrote (the pending mark's `root=`, or the row's own
+ * `filePath` — both come from the SAME `configResolutionKey(cwd)` call in
+ * `clients/lsp/config.ts`, which folds separators, canonicalizes, then folds
+ * again — `normalizeFilePath(path.resolve(normalizeFilePath(cwd)))`, in that
+ * order (#2518 review F6; resolving first breaks POSIX backslash names), so they compare equal without this script re-deriving any
+ * path normalization of its own).
+ */
+function configJoinKey(sessionId, root) {
+	return `${sessionId} ${root}`;
+}
+
 function counter() {
 	const map = new Map();
 	return {
@@ -985,6 +1102,33 @@ function summarizeLatency(entry) {
 	};
 }
 
+/**
+ * A `config_resolved` row (#2526), summarised for a smell example.
+ *
+ * Deliberately NOT `summarizeLatency`: that helper's metadata whitelist would
+ * drop every field this row carries, so the example would print a phase name
+ * and nothing a reader could act on.
+ */
+function summarizeConfigResolved(entry, note) {
+	const md = entry.metadata ?? {};
+	const documents = Array.isArray(md.documents) ? md.documents : [];
+	return {
+		ts: entry.ts,
+		durationMs: entry.durationMs,
+		phase: entry.phase,
+		project: projectOf(entry.filePath),
+		note,
+		documents: documents
+			.map(
+				(doc) =>
+					`${doc?.tier ?? "?"}:${doc?.file ?? "?"}${doc?.legacy ? " (legacy)" : ""}`,
+			)
+			.slice(0, 8),
+		recordCount: md.recordCount,
+		deniedServers: md.deniedServers,
+	};
+}
+
 function summarizeWorkspaceSweep(entry) {
 	const md = entry.metadata ?? {};
 	const bits = [];
@@ -1193,6 +1337,43 @@ function buildReport(state) {
 		`session_start background tasks >= ${thresholds.backgroundSlowMs}ms`,
 		state.session.slowTasks.slice(0, limit),
 	);
+	// #2526: config resolution has to prove it HAPPENED. Two shapes, one smell:
+	//
+	// (a) a session that has a `config_resolution_pending` mark and produced no
+	//     `config_resolved` row. Round 3, S1: the pending mark is written by
+	//     `loadLSPConfig` itself, at the instant a resolution is actually
+	//     attempted — never predicted from a handler's own flags ahead of time.
+	//     Round 2, F2 established the JOIN itself: on the session id both sides
+	//     carry, never a subtraction of two counts (subtracting counted quick
+	//     sessions' rows against full sessions' start lines — different
+	//     populations — which both masked total silence and charged
+	//     `--no-lsp`/subagent sessions with a permanent deficit they could never
+	//     clear).
+	//     Round 4, #2552 review: the join is on (session, root), not session
+	//     alone — a warm MCP process keeps one session id for its whole life but
+	//     marks once per SERVED ROOT (`configJoinKey`'s doc comment), so one
+	//     root's row must not clear another root's deficit under the same id.
+	// (b) a legacy document present with zero records — the deprecation
+	//     machinery went silent while the user is on a removal schedule.
+	const pendingConfigResolution = [...state.config.pendingSessions.entries()];
+	const unresolvedSessions = pendingConfigResolution.filter(
+		([key]) => !state.config.resolvedSessions.has(key),
+	);
+	for (const [, value] of unresolvedSessions.slice(0, limit * 3)) {
+		state.config.examples.push({
+			ts: value.ts,
+			session: value.sessionId,
+			root: value.root,
+			note: "session had a config_resolution_pending mark and produced no config_resolved row",
+		});
+	}
+	addSmell(
+		smells,
+		"config-resolution",
+		unresolvedSessions.length + state.config.legacyWithoutRecords,
+		`Sessions with a config_resolution_pending mark but no config_resolved row (${unresolvedSessions.length} of ${pendingConfigResolution.length}) or a legacy config document that produced no migration record (${state.config.legacyWithoutRecords})`,
+		state.config.examples.slice(0, limit),
+	);
 	addSmell(
 		smells,
 		"cascade-fallbacks",
@@ -1352,6 +1533,16 @@ function buildReport(state) {
 			rotations: state.session.rotations.toJSON(),
 			errors: state.session.errors.slice(0, limit),
 		},
+		// #2526: the positive-observability counters behind the
+		// `config-resolution` smell, so a reader can see WHY it fired (or that
+		// it correctly did not) without re-deriving the deficit.
+		config: {
+			resolved: state.config.resolved,
+			sessionsPendingResolution: pendingConfigResolution.length,
+			sessionsWithoutResolution: unresolvedSessions.length,
+			legacyDocuments: state.config.legacyDocuments,
+			legacyWithoutRecords: state.config.legacyWithoutRecords,
+		},
 		actionable: {
 			events: state.actionable.events.toJSON(),
 			reports: state.actionable.reports,

package/scripts/install-selftest.mjs

@@ -17,7 +17,9 @@
  * Force-imports the modules whose TOP-LEVEL bare imports are the documented
  * failure points, plus the bare specifiers directly, and checks the two
  * build-script-provided assets (ast-grep CLI binary + tree-sitter grammars)
- * that pnpm/bun skip by default. It runs no model and needs no credentials.
+ * that pnpm/bun skip by default. It also resolves the `pi.skills` manifest
+ * entries the way pi does, from the installed package root (#2587). It runs no
+ * model and needs no credentials.
  *
  * WHAT IT NO LONGER COVERS (#1926)
  * pi supplies `typebox` and `@earendil-works/pi-tui` from its own runtime, so
@@ -47,6 +49,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { HOST_PROVIDED_PACKAGES } from "./lib/host-provided-deps.mjs";
+import { collectSkillEntryPaths } from "./lib/skills-predicate.mjs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkgRoot = path.resolve(here, "..");
@@ -242,6 +245,56 @@ try {
 }
 record("tree-sitter grammars", "asset", hasCoreGrammar, grammarDetail);
 
+// --- 4. pi.skills manifest resolution, AS INSTALLED (#2587) ----------------
+// Guards the recurrence of #2587: a `pi.skills` entry that resolves outside the
+// installed package, so pi registers none of the shipped skills. This probe runs
+// from the INSTALLED package (`require.resolve("pi-lens/scripts/…")`), so it sees
+// the real layout — hoisted node_modules, pnpm's symlink store, bun, yarn — which
+// is exactly where `../../skills` escaped and where a static check on the source
+// tree cannot look. Replicates pi's own resolver, `PackageManager#collectFiles\
+// FromManifestEntries` in `@earendil-works/pi-coding-agent`
+// `dist/core/package-manager.js`: a non-glob entry is `resolve(packageRoot, entry)`
+// (verified identical in 0.78.1 / 0.84.1 / 0.85.1).
+//
+// #2626 review round 2 (F2): the "does this dir have a skill" walk used to be
+// a hand-rolled `countSkillFiles` here AND a second, differently-wrong one in
+// `clients/skills-resolver.ts`. Both now derive from the ONE structural
+// predicate in `./lib/skills-predicate.mjs`, which replicates pi's actual
+// `loadSkillsFromDirInternal` walk (see that module's header for the exact
+// discovery rules and the two documented scope gaps).
+{
+	const pkgJson = JSON.parse(
+		fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"),
+	);
+	const entries = pkgJson.pi?.skills ?? [];
+	if (entries.length === 0) {
+		record("pi.skills declared", "manifest", false, "pi.skills is empty");
+	}
+	for (const entry of entries) {
+		const label = `pi.skills "${entry}"`;
+		// pi globs entries containing * or ? through a different branch; this
+		// probe only replicates the non-glob one.
+		if (/[*?]/.test(entry)) {
+			record(label, "manifest", true, "glob entry — not probed");
+			continue;
+		}
+		const resolved = path.resolve(pkgRoot, entry);
+		if (resolved !== pkgRoot && !resolved.startsWith(pkgRoot + path.sep)) {
+			record(label, "manifest", false, `escapes the package: ${resolved}`);
+			continue;
+		}
+		const found = collectSkillEntryPaths(resolved).length;
+		record(
+			label,
+			"manifest",
+			found > 0,
+			found > 0
+				? `${found} SKILL.md under ${resolved}`
+				: `no SKILL.md under ${resolved}`,
+		);
+	}
+}
+
 // --- Report ----------------------------------------------------------------
 const pad = Math.max(...results.map((r) => r.name.length));
 let hardFail = 0;
@@ -249,7 +302,10 @@ let softFail = 0;
 for (const r of results) {
 	const soft = (r.kind === "asset" || r.kind === "tool") && allowSoft;
 	const status = r.ok ? "PASS" : soft ? "WARN" : "FAIL";
-	if (!r.ok) soft ? softFail++ : hardFail++;
+	if (!r.ok) {
+		if (soft) softFail++;
+		else hardFail++;
+	}
 	console.log(
 		`  [${status}] ${r.name.padEnd(pad)} ${r.detail ? "— " + r.detail : ""}`,
 	);

package/scripts/lib/skills-predicate.mjs

@@ -0,0 +1,129 @@
+// The ONE structural replica of pi's own skill-loading walk (#2626 review
+// round 2, F1/F2).
+//
+// Two independent detectors used to answer "does this directory tree hold a
+// skill pi would load" with two DIFFERENT, hand-rolled heuristics that both
+// diverged from pi's real resolver:
+//   - `clients/skills-resolver.ts` (a `SKILL.md` one level down only, no
+//     recursion, no root `.md` acceptance, no symlink-follow, no dot/
+//     node_modules skip)
+//   - `scripts/install-selftest.mjs`'s `countSkillFiles` (recursed
+//     UNBOUNDED — would double-count a `SKILL.md` sitting inside another
+//     skill's own resource subdirectory — with no dot/node_modules skip, no
+//     root `.md` acceptance, no symlink handling)
+// Neither matched `loadSkillsFromDirInternal` in
+// `@earendil-works/pi-coding-agent` `dist/core/skills.js` (mirrored by
+// `collectSkillEntries` in `dist/core/package-manager.js`, byte-identical
+// walk, confirmed against the 0.85.1 tarball). This module is the fold: BOTH
+// consumers now derive from `collectSkillEntryPaths` below.
+//
+// Discovery rules, replicated from `loadSkillsFromDirInternal` (verified
+// against the extracted 0.85.1 `skills.js`):
+//   1. If `dir` directly contains a (non-symlink-broken) `SKILL.md`, `dir` IS
+//      one skill root — return immediately, do NOT look at `dir`'s other
+//      entries or recurse into its subdirectories (a `SKILL.md` inside a
+//      skill's own reference/ subfolder is the skill's OWN resource, not a
+//      second skill).
+//   2. Otherwise, skip dot-prefixed entries and `node_modules`; recurse into
+//      every remaining subdirectory (same two rules, one level down); at the
+//      OUTERMOST call only (`isRoot`), a loose `*.md` file directly in `dir`
+//      also counts (pi's `includeRootFiles`, true only for the top call).
+//   3. A symlink is followed via `statSync` (broken symlink = skip) for BOTH
+//      the `SKILL.md` check and the directory/file classification in step 2.
+//
+// Deliberately NOT replicated (out of #2626's scope — packaging/path
+// resolution, not skill-content validation):
+//   - `.gitignore`/`.ignore`/`.fdignore` matching inside the skills tree.
+//   - frontmatter parsing: pi additionally requires a non-empty `description`
+//     field before a discovered file becomes a loaded skill. A `SKILL.md`
+//     file that exists but fails THAT validation is a content-authoring
+//     defect a maintainer would see in normal use, not a silent zero.
+// Both gaps mean this predicate can be a bit more OPTIMISTIC than pi's true
+// count in a pathological case (an ignored or description-less file still
+// counts as "found" here); it is never more PESSIMISTIC — every real skill
+// pi loads is found by this walk too — which is the direction #2626 cares
+// about (never claim "no skills" when pi would load one).
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Symlink-aware entry classification, mirroring `loadSkillsFromDirInternal`'s
+ * own `entry.isSymbolicLink() ? statSync(fullPath) : entry`.
+ * @param {string} fullPath
+ * @param {import("node:fs").Dirent} entry
+ * @returns {"file" | "dir" | "other"}
+ */
+export function resolvedEntryKind(fullPath, entry) {
+	if (entry.isSymbolicLink()) {
+		try {
+			const stats = fs.statSync(fullPath);
+			if (stats.isDirectory()) return "dir";
+			if (stats.isFile()) return "file";
+			return "other";
+		} catch {
+			return "other"; // broken symlink
+		}
+	}
+	if (entry.isDirectory()) return "dir";
+	if (entry.isFile()) return "file";
+	return "other";
+}
+
+/**
+ * The structural walk over an ALREADY-READ directory listing — split out
+ * from `collectSkillEntryPaths` so a caller that already has `entries` (a
+ * top-level ENOENT/EACCES distinction, say) is not forced into a second
+ * `readdirSync`.
+ * @param {string} dir
+ * @param {import("node:fs").Dirent[]} entries
+ * @param {boolean} isRoot
+ * @returns {string[]} absolute paths of every `SKILL.md` (or, at the root,
+ *   loose `.md`) file pi's own resolver would treat as a skill entry point.
+ */
+export function scanEntriesForSkills(dir, entries, isRoot) {
+	for (const entry of entries) {
+		if (
+			entry.name === "SKILL.md" &&
+			resolvedEntryKind(path.join(dir, entry.name), entry) === "file"
+		) {
+			return [path.join(dir, entry.name)];
+		}
+	}
+	const found = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") || entry.name === "node_modules") {
+			continue;
+		}
+		const fullPath = path.join(dir, entry.name);
+		const kind = resolvedEntryKind(fullPath, entry);
+		if (kind === "dir") {
+			found.push(...collectSkillEntryPaths(fullPath, false));
+			continue;
+		}
+		if (isRoot && kind === "file" && entry.name.endsWith(".md")) {
+			found.push(fullPath);
+		}
+	}
+	return found;
+}
+
+/**
+ * Every skill entry point under `dir`, recursively, per pi's discovery
+ * rules. Fail-closed: a `readdirSync` error at `dir` (absent, unreadable) or
+ * any recursed-into subdirectory returns `[]` for that branch rather than
+ * throwing — matching `loadSkillsFromDirInternal`'s own bare `try { … }
+ * catch {}` per directory.
+ * @param {string} dir
+ * @param {boolean} [isRoot]
+ * @returns {string[]}
+ */
+export function collectSkillEntryPaths(dir, isRoot = true) {
+	let entries;
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return scanEntriesForSkills(dir, entries, isRoot);
+}

package/scripts/rpc-load-check.mjs

@@ -61,7 +61,9 @@ function handle(line) {
 	if (m.type === "response" && m.command === "get_commands") {
 		const cmds = (m.data && m.data.commands) || [];
 		const lens = cmds.filter(
-			(c) => /^lens-/.test(c.name) || String(c.path || "").includes("pi-lens"),
+			(c) =>
+				String(c.name || "").startsWith("lens-") ||
+				String(c.path || "").includes("pi-lens"),
 		);
 		console.log(
 			`total commands: ${cmds.length}; pi-lens commands: ${lens.map((c) => c.name).join(", ") || "(none)"}`,