@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/dist/clients/word-index-logger.js

@@ -21,11 +21,11 @@
  */
 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";
 import { normalizeFilePath } from "./path-utils.js";
-const WORD_INDEX_LOG_FILE = path.join(getGlobalPiLensDir(), "word-index.log");
+const WORD_INDEX_LOG_FILE = path.join(getGlobalPiLensLogDir(), "word-index.log");
 const writer = createNdjsonLogger({
     filePath: WORD_INDEX_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,
@@ -47,10 +47,3 @@ export function logWordIndex(entry) {
         cwd: normalizeFilePath(entry.cwd),
     });
 }
-export function getWordIndexLogPath() {
-    return WORD_INDEX_LOG_FILE;
-}
-/** Resolve once all enqueued word-index writes are on disk (tests/shutdown). */
-export function flushWordIndexLog() {
-    return writer.flush();
-}

package/node_modules/pi-lens/dist/clients/word-index-store.js

@@ -1,4 +1,4 @@
-import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
+import { createDeadline, yieldIfOverBudget, } from "./cooperative-budget.js";
 /**
  * Packed backing store for the word index's inverted postings (#2069).
  *
@@ -30,8 +30,8 @@ import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
 /**
  * Bytes of backing store per posting entry: one `fileId` lane and one `line`
  * lane, both `Int32`. This is the constant #2069's acceptance criterion is
- * written against, and {@link estimatePostingListBytes} is the arithmetic the
- * memory-sample record and the regression test both read.
+ * written against, and the arithmetic the memory-sample record and the
+ * regression test both read.
  */
 export const WORD_POSTING_ENTRY_BYTES = 8;
 /**
@@ -189,10 +189,6 @@ export class WordPostingList {
         return list;
     }
 }
-/** Estimated bytes one posting list holds, backing store plus fixed headers. */
-export function estimatePostingListBytes(list) {
-    return list.byteLength + WORD_POSTING_LIST_OVERHEAD_BYTES;
-}
 /**
  * Re-home every posting list into ONE shared `ArrayBuffer`, exactly sized.
  *
@@ -248,8 +244,20 @@ export function compactPostingsIntoArena(postings) {
  *
  * Each `adoptArena` copies and re-homes one list within a single synchronous
  * step, so readers never observe a partially written list.
+ *
+ * `options.deadline` and `options.beforeYield` are a test seam only (#2293):
+ * production always takes the default 8 ms wall-clock deadline. The #2117
+ * regression test used to prove the "grew during a yield" invariant by racing
+ * a real timer against a 40,000-list copy, which made the yield itself a
+ * scheduling accident — the copy sometimes finished inside the 8 ms budget
+ * and never yielded at all, so the test's own precondition went unmet under
+ * load. Injecting a deadline lets a test force a yield deterministically
+ * instead of hoping wall-clock crosses the budget; `beforeYield` runs
+ * in-line, immediately before the real cooperative pause, so a test can
+ * mutate a not-yet-adopted list at that exact point with no reliance on
+ * event-loop scheduling order.
  */
-export async function compactPostingsIntoArenaCooperatively(postings) {
+export async function compactPostingsIntoArenaCooperatively(postings, options) {
     // Snapshot (token, list, width) in one synchronous pass; the arena is sized
     // from these widths and only unchanged lists are adopted, so the sum of the
     // widths actually written can never exceed the arena length.
@@ -264,15 +272,17 @@ export async function compactPostingsIntoArenaCooperatively(postings) {
         return;
     const arena = new Int32Array(lanes);
     let offset = 0;
-    const deadline = createDeadline(8);
+    const deadline = options?.deadline ?? createDeadline(8);
     for (const plan of planned) {
         if (postings.get(plan.token) === plan.list &&
             plan.list.length * 2 === plan.width &&
             offset + plan.width <= arena.length) {
             offset = plan.list.adoptArena(arena, offset);
         }
-        if (deadline.expired())
+        if (deadline.expired()) {
+            await options?.beforeYield?.();
             await yieldIfOverBudget(deadline);
+        }
     }
 }
 /**
@@ -375,7 +385,8 @@ export class WordForwardEntry {
     }
     /** Pack a tokenizer tally. Insertion order is preserved. */
     static fromTally(tally) {
-        const tokenNames = new Array(tally.size);
+        const tokenNames = [];
+        tokenNames.length = tally.size;
         const lineCounts = new Int32Array(tally.size);
         let i = 0;
         for (const [token, count] of tally) {
@@ -390,7 +401,7 @@ export class WordForwardEntry {
  * Bytes per forward entry: one pointer-compressed slot for the shared token
  * string and one `Int32` count lane.
  */
-export const WORD_FORWARD_ENTRY_BYTES = 8;
+const WORD_FORWARD_ENTRY_BYTES = 8;
 /**
  * The word index's dense file-id space: canonical path key → integer id →
  * display path.

package/node_modules/pi-lens/dist/clients/word-index.js

@@ -725,17 +725,6 @@ async function updateWordIndexDocumentAsyncUnsafe(index, doc, shouldContinue) {
     commitWordIndexDocumentReplacement(index, doc, perTokenHits, docLength, startedAt);
     return true;
 }
-/** Bounds shared by every word-index build path — keep the walk off the
- * critical path on large repos: cap the file count, and skip files too large
- * to be hand-written source (generated/bundled output the source filter
- * didn't already exclude).
- *
- * Deprecated (#776): `collectWordIndexDocs` below no longer reads this
- * constant directly — it derives its cap from `getWordIndexMaxFilesDerived`
- * (project-scale.ts's `maxProjectFiles` knob), which reproduces this same
- * 6,000 default at the default base. Kept exported for tests/callers that
- * still reference the literal. */
-export const WORD_INDEX_MAX_FILES = 6000;
 export const WORD_INDEX_MAX_BYTES = 512 * 1024;
 /**
  * Collect the bounded `{path, content}` doc set `buildWordIndex` consumes —
@@ -748,9 +737,9 @@ export const WORD_INDEX_MAX_BYTES = 512 * 1024;
 export async function collectWordIndexDocs(root, shouldContinue = () => true, preflightFiles) {
     const { collectSourceFilesAsync } = await import("./source-filter.js");
     // #747 hardening: pass the cap INTO the walk — without it,
-    // `collectSourceFilesAsync` defaults to an unbounded traversal and the
-    // `WORD_INDEX_MAX_FILES` slice below only trims the result AFTER the whole
-    // tree (all of $HOME, on a misrooted cwd) has already been enumerated.
+    // `collectSourceFilesAsync` defaults to an unbounded traversal and any
+    // slice below would only trim the result AFTER the whole tree (all of
+    // $HOME, on a misrooted cwd) has already been enumerated.
     // #760: the walk is additionally bounded by source-filter's default
     // visited-entry budget (DEFAULT_MAX_SCAN_ENTRIES), so a mixed tree with few
     // source files among a huge pile of non-source files can't force a
@@ -811,7 +800,7 @@ export async function collectWordIndexDocs(root, shouldContinue = () => true, pr
 // Node's fs.promises.stat runs on libuv's threadpool (default 4 slots), so
 // real parallelism tops out there; the surplus workers are queue depth that
 // keeps the pool saturated without starving other threadpool consumers.
-export const WORD_INDEX_STAT_CONCURRENCY = 8;
+const WORD_INDEX_STAT_CONCURRENCY = 8;
 const WORD_INDEX_INCREMENTAL_CHURN_THRESHOLD = 0.3;
 // A ratio alone misclassifies one stale file in a three-file project as dense.
 // Below this absolute floor, per-document replacement is bounded and cheaper
@@ -888,7 +877,8 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
     const statConcurrency = Number.isFinite(requestedConcurrency) && requestedConcurrency > 0
         ? Math.max(1, Math.floor(requestedConcurrency))
         : WORD_INDEX_STAT_CONCURRENCY;
-    const statResults = new Array(walked.length);
+    const statResults = [];
+    statResults.length = walked.length;
     let cursor = 0;
     let superseded = false;
     const worker = async () => {
@@ -1091,7 +1081,11 @@ export async function refreshWordIndexIncrementally(index, root, shouldContinue
         timings,
     };
 }
-export const WORD_INDEX_QUERY_FILTER_KEYS = ["lang", "file", "ext"];
+const WORD_INDEX_QUERY_FILTER_KEYS = [
+    "lang",
+    "file",
+    "ext",
+];
 /** Thrown by {@link parseWordIndexQuery}/{@link buildWordIndexQueryFilter} for
  * an unrecognized `key:` prefix or an unrecognized `lang:` value — a query
  * typo fails loudly with the supported list instead of silently degrading
@@ -1391,6 +1385,22 @@ export function centralityFromReverseDeps(index, reverseDeps, normalizeKey = (fi
 }
 /** Persisted word-index serialization format version. Bump on breaking format changes. */
 export const WORD_INDEX_FORMAT_VERSION = 2;
+const WORD_INDEX_INT32_MAX = 2_147_483_647;
+// A file id and line fit in one exact Number key through this boundary.
+const WORD_INDEX_PACKED_FILE_ID_MAX = 4_194_303;
+function isCanonicalWordIndexNumber(value) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        Number.isSafeInteger(value) &&
+        !Object.is(value, -0));
+}
+function isCanonicalWordIndexToken(token) {
+    return (typeof token === "string" &&
+        token.length >= 2 &&
+        token === token.toLowerCase() &&
+        /^[a-z0-9_$]+$/.test(token) &&
+        !STOPWORDS.has(token));
+}
 const serializedWordIndexCaches = new WeakMap();
 let _lastSerializeWork;
 /** Test-only: work stats for the most recent {@link serializeWordIndex} call. */
@@ -1585,10 +1595,25 @@ export function deserializeWordIndex(data) {
         !Array.isArray(data.files) ||
         !Array.isArray(data.postings) ||
         !Array.isArray(data.docLengths) ||
-        !Array.isArray(data.fileMtimes) ||
-        data.fileMtimes.length !== data.files.length) {
+        !Array.isArray(data.fileMtimes)) {
         return null;
     }
+    let canonical = data.docLengths.length === data.files.length &&
+        data.fileMtimes.length === data.files.length;
+    let needsDeepSanitize = !Array.isArray(data.forward);
+    if (needsDeepSanitize)
+        canonical = false;
+    const fileKeys = new Set();
+    for (const file of data.files) {
+        if (typeof file !== "string")
+            return null;
+        const key = wordIndexKey(file);
+        if (fileKeys.has(key)) {
+            canonical = false;
+            needsDeepSanitize = true;
+        }
+        fileKeys.add(key);
+    }
     const docLengths = new PathKeyedMap(wordIndexKey);
     // Slot i of the wire `files` array becomes file id `fileIdBySlot[i]`. Two
     // slots whose spellings fold to one key share one id, exactly as a build
@@ -1596,33 +1621,94 @@ export function deserializeWordIndex(data) {
     // posting identities for one document.
     const fileTable = new WordIndexFileTable();
     const fileIdBySlot = data.files.map((file) => fileTable.intern(wordIndexKey(file), file));
+    const slotByFileId = new Map();
+    fileIdBySlot.forEach((fileId, slot) => {
+        if (!slotByFileId.has(fileId))
+            slotByFileId.set(fileId, slot);
+    });
     const fileMtimes = new PathKeyedMap(wordIndexKey);
     const fileSizes = new PathKeyedMap(wordIndexKey);
-    data.files.forEach((file, i) => docLengths.set(file, data.docLengths[i] ?? 0));
-    data.files.forEach((file, i) => fileMtimes.set(file, data.fileMtimes[i] ?? 0));
+    data.files.forEach((file, i) => {
+        const value = data.docLengths[i];
+        if (!isCanonicalWordIndexNumber(value) || value < 0)
+            canonical = false;
+        docLengths.set(file, isCanonicalWordIndexNumber(value) && value >= 0 ? value : 0);
+    });
+    data.files.forEach((file, i) => {
+        const value = data.fileMtimes[i];
+        if (typeof value !== "number" || !Number.isFinite(value))
+            canonical = false;
+        fileMtimes.set(file, typeof value === "number" && Number.isFinite(value) ? value : 0);
+    });
     // #1105: `fileSizes` is optional on the wire (pre-#1105 snapshots omit it).
     // Only populate when the array is present AND parallel to `files`; otherwise
     // leave it empty so the refresh gate re-reads every file once to repopulate,
     // rather than trusting a bogus/misaligned size. Never treated as "current".
     if (Array.isArray(data.fileSizes) &&
         data.fileSizes.length === data.files.length) {
-        data.files.forEach((file, i) => fileSizes.set(file, data.fileSizes?.[i] ?? 0));
+        data.files.forEach((file, i) => {
+            const value = data.fileSizes?.[i];
+            if (!isCanonicalWordIndexNumber(value) || value < 0)
+                canonical = false;
+            fileSizes.set(file, isCanonicalWordIndexNumber(value) && value >= 0 ? value : 0);
+        });
+    }
+    else {
+        canonical = false;
     }
     const postings = new Map();
-    for (const [token, flat] of data.postings) {
-        if (typeof token !== "string" || !Array.isArray(flat))
+    const postingTokens = new Set();
+    const postingFileCounts = new Map();
+    for (const posting of data.postings) {
+        if (!Array.isArray(posting) || posting.length !== 2) {
+            canonical = false;
+            needsDeepSanitize = true;
+            continue;
+        }
+        const [token, flat] = posting;
+        if (!isCanonicalWordIndexToken(token) ||
+            postingTokens.has(token) ||
+            !Array.isArray(flat) ||
+            flat.length === 0 ||
+            flat.length % 2 !== 0) {
+            canonical = false;
+            needsDeepSanitize = true;
             continue;
+        }
+        postingTokens.add(token);
         const lanes = [];
-        for (let i = 0; i + 1 < flat.length; i += 2) {
-            const fileId = fileIdBySlot[flat[i]];
+        const seenPairs = new Set();
+        const observedCounts = new Map();
+        for (let i = 0; i < flat.length; i += 2) {
+            const slot = flat[i];
             const line = flat[i + 1];
-            if (typeof fileId === "number" && typeof line === "number") {
-                lanes.push(fileId, line);
+            if (!isCanonicalWordIndexNumber(slot) ||
+                slot < 0 ||
+                slot >= fileIdBySlot.length ||
+                !isCanonicalWordIndexNumber(line) ||
+                line < 1 ||
+                line > WORD_INDEX_INT32_MAX) {
+                canonical = false;
+                needsDeepSanitize = true;
+                continue;
             }
+            const fileId = fileIdBySlot[slot];
+            const pairKey = fileId <= WORD_INDEX_PACKED_FILE_ID_MAX
+                ? fileId * (WORD_INDEX_INT32_MAX + 1) + line
+                : `${fileId}:${line}`;
+            if (seenPairs.has(pairKey)) {
+                canonical = false;
+                needsDeepSanitize = true;
+            }
+            seenPairs.add(pairKey);
+            lanes.push(fileId, line);
+            observedCounts.set(fileId, (observedCounts.get(fileId) ?? 0) + 1);
         }
-        if (lanes.length > 0) {
-            postings.set(token, WordPostingList.fromLanes(token, lanes));
-        }
+        if (lanes.length === 0)
+            continue;
+        const list = WordPostingList.fromLanes(token, lanes);
+        postings.set(token, list);
+        postingFileCounts.set(token, observedCounts);
     }
     // Every list above was sized exactly from the wire payload, so there is no
     // growth slack to release — but the per-list `ArrayBuffer` headers are the
@@ -1631,34 +1717,128 @@ export function deserializeWordIndex(data) {
     compactPostingsIntoArena(postings);
     let forward;
     if (Array.isArray(data.forward)) {
-        forward = new PathKeyedMap(wordIndexKey);
-        for (const entry of data.forward) {
-            if (!Array.isArray(entry) || entry.length !== 2)
+        const candidate = data.files.map(() => new Map());
+        const forwardTotals = new Map();
+        if (data.forward.length !== data.files.length)
+            canonical = false;
+        if (data.forward.length !== data.files.length)
+            needsDeepSanitize = true;
+        for (const [entryIndex, entry] of data.forward.entries()) {
+            if (!Array.isArray(entry) || entry.length !== 2) {
+                canonical = false;
+                needsDeepSanitize = true;
                 continue;
+            }
             const [fileIdx, tokenCounts] = entry;
-            const file = data.files[fileIdx];
-            if (typeof file !== "string" || !Array.isArray(tokenCounts))
+            if (!isCanonicalWordIndexNumber(fileIdx) ||
+                fileIdx !== entryIndex ||
+                fileIdx < 0 ||
+                fileIdx >= data.files.length ||
+                !Array.isArray(tokenCounts)) {
+                canonical = false;
+                needsDeepSanitize = true;
                 continue;
-            const perToken = new Map();
+            }
             for (const pair of tokenCounts) {
-                if (!Array.isArray(pair) || pair.length !== 2)
+                if (!Array.isArray(pair) ||
+                    pair.length !== 2 ||
+                    !isCanonicalWordIndexToken(pair[0]) ||
+                    !isCanonicalWordIndexNumber(pair[1]) ||
+                    pair[1] < 1 ||
+                    pair[1] > WORD_INDEX_INT32_MAX ||
+                    candidate[fileIdx].has(pair[0])) {
+                    canonical = false;
+                    needsDeepSanitize = true;
                     continue;
-                const [token, count] = pair;
-                if (typeof token === "string" && typeof count === "number") {
-                    // Point at the canonical instance the postings map holds, not
-                    // this document’s own JSON.parse allocation (#2069).
-                    perToken.set(postings.get(token)?.token ?? token, count);
                 }
+                candidate[fileIdx].set(pair[0], pair[1]);
+                forwardTotals.set(pair[0], (forwardTotals.get(pair[0]) ?? 0) + pair[1]);
             }
-            forward.set(file, WordForwardEntry.fromTally(perToken));
+        }
+        let forwardMatchesPostings = true;
+        for (const [token, list] of postings) {
+            if (forwardTotals.get(token) !== list.length) {
+                forwardMatchesPostings = false;
+            }
+            const observed = postingFileCounts.get(token);
+            if (!observed) {
+                forwardMatchesPostings = false;
+                continue;
+            }
+            for (const [fileId, count] of observed) {
+                const slot = slotByFileId.get(fileId);
+                if (slot === undefined || candidate[slot].get(token) !== count) {
+                    forwardMatchesPostings = false;
+                }
+            }
+        }
+        for (const token of forwardTotals.keys()) {
+            if (!postingTokens.has(token))
+                forwardMatchesPostings = false;
+        }
+        if (!forwardMatchesPostings)
+            canonical = false;
+        if (!forwardMatchesPostings)
+            needsDeepSanitize = true;
+        forward = new PathKeyedMap(wordIndexKey);
+        for (let i = 0; i < data.files.length; i += 1) {
+            forward.set(data.files[i], WordForwardEntry.fromTally(candidate[i]));
         }
     }
-    return {
+    else if (Object.prototype.hasOwnProperty.call(data, "forward")) {
+        canonical = false;
+        needsDeepSanitize = true;
+    }
+    if (needsDeepSanitize) {
+        const actualForwardCounts = data.files.map(() => new Map());
+        for (const [token, list] of postings) {
+            const seenPairs = new Set();
+            const sanitized = new WordPostingList(token, list.length);
+            for (let i = 0; i < list.length; i += 1) {
+                const fileId = list.fileIdAt(i);
+                const line = list.lineAt(i);
+                const pairKey = `${fileId}:${line}`;
+                if (seenPairs.has(pairKey))
+                    continue;
+                seenPairs.add(pairKey);
+                sanitized.push(fileId, line);
+                const slot = slotByFileId.get(fileId);
+                if (slot !== undefined) {
+                    const counts = actualForwardCounts[slot];
+                    counts.set(token, (counts.get(token) ?? 0) + 1);
+                }
+            }
+            postings.set(token, sanitized);
+        }
+        compactPostingsIntoArena(postings);
+        if (Array.isArray(data.forward)) {
+            forward = new PathKeyedMap(wordIndexKey);
+            for (let i = 0; i < data.files.length; i += 1) {
+                const canonicalSlot = slotByFileId.get(fileIdBySlot[i]) ?? i;
+                forward.set(data.files[i], WordForwardEntry.fromTally(actualForwardCounts[canonicalSlot]));
+            }
+        }
+    }
+    const expectedTotalTokens = [...docLengths.values()].reduce((total, length) => total + length, 0);
+    const totalTokens = isCanonicalWordIndexNumber(expectedTotalTokens)
+        ? expectedTotalTokens
+        : 0;
+    if (!isCanonicalWordIndexNumber(data.totalTokens) ||
+        data.totalTokens !== totalTokens) {
+        canonical = false;
+    }
+    if (typeof data.indexedFileCount !== "number" ||
+        data.indexedFileCount !== docLengths.size) {
+        canonical = false;
+    }
+    if (typeof data.truncated !== "boolean")
+        canonical = false;
+    const index = {
         postings,
         fileTable,
         docLengths,
-        totalTokens: typeof data.totalTokens === "number" ? data.totalTokens : 0,
-        docCount: data.files.length,
+        totalTokens,
+        docCount: docLengths.size,
         truncated: data.truncated === true,
         forward,
         fileMtimes,
@@ -1667,7 +1847,32 @@ export function deserializeWordIndex(data) {
         // starts from the exact post-compaction store count (#2117).
         postingStoreCount: countPostingBackingStores(postings),
         recompactFlight: createSingleFlight(),
+        // A deserialized index is a fresh object distinct from whichever index
+        // produced `data`. Without this, every per-edit dirty mark on a
+        // session-start reload (#2068) is a no-op against `undefined`, and
+        // serializeWordIndexIncrementally's `!dirty` branch then returns the
+        // stale cached wire view forever, silently dropping every later edit
+        // from the persisted snapshot.
+        dirtyFiles: new Set(),
     };
+    // Seed the wire cache from the snapshot just loaded so the FIRST persist
+    // of a reloaded session (session-start's `snapshotSaveSyncMs`, #2068) also
+    // takes the bounded incremental path instead of paying a full rebuild —
+    // mirrors exactly what one priming `serializeWordIndex` call would cache.
+    const tokensByFile = new Map();
+    if (forward) {
+        for (const file of data.files) {
+            tokensByFile.set(wordIndexKey(file), new Set(forward.get(file)?.keys() ?? []));
+        }
+    }
+    if (canonical) {
+        serializedWordIndexCaches.set(index, {
+            serialized: data,
+            slotByFileId,
+            tokensByFile,
+        });
+    }
+    return index;
 }
 const buildStatuses = new Map();
 export function getWordIndexBuildStatus(cwd) {

package/node_modules/pi-lens/dist/clients/workspace-topology.js

@@ -39,11 +39,18 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { PROJECT_CONFIG_BASENAMES } from "./config-locations.js";
 import { logLatency } from "./latency-logger.js";
 import { isAtOrAboveHomeDir, nameMatchesMarkerGlob, walkUpDirs, } from "./path-utils.js";
 /** Depth cap on any upward marker walk — mirrors `findNearestMarkerRoot`'s bound. */
 const MAX_WALK_DEPTH = 64;
-const PI_LENS_CONFIG_BASENAMES = [".pi-lens.json", "pi-lens.json"];
+/**
+ * The project config basenames, canonical first — the SHARED table, not a
+ * fourth copy of the pair (#2426 review round 2). `config-locations.ts` derives
+ * it from the one location table the resolver walks, so a change there cannot
+ * leave this marker index preferring a different file than the loaders do.
+ */
+const PI_LENS_CONFIG_BASENAMES = PROJECT_CONFIG_BASENAMES;
 /** Per-directory marker cache — the shared seam every consumer reads through. */
 const dirMarkerCache = new Map();
 /** Downstream memo clears that must follow the topology index reset. */

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

@@ -15,12 +15,15 @@ import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision,
 // presence of one is the repo's deliberate opt-in: it carries the author's
 // chosen severities/ignores, so we let zizmor findings BLOCK in that workspace
 // (advisory-only otherwise, like Opengrep's local-rules gate).
-export const LOCAL_ZIZMOR_CONFIG_NAMES = [
+const LOCAL_ZIZMOR_CONFIG_NAMES = [
     path.join(".github", "zizmor.yml"),
     path.join(".github", "zizmor.yaml"),
     "zizmor.yml",
     "zizmor.yaml",
 ];
+// Deliberately UNCEILINGED at $HOME (refs #2472 review round 3, F1): a
+// user-level `~/zizmor.yml` (or `~/.github/zizmor.yml`) is a legitimate
+// global config, not an escaped-workspace accident.
 export function findLocalZizmorConfig(startDir) {
     return findLocalToolConfig(startDir, LOCAL_ZIZMOR_CONFIG_NAMES);
 }