pi-lens 3.8.67 → 3.8.69

package/dist/clients/module-report.js

@@ -297,7 +297,7 @@ function coldImports(imports, languageId, absPath, projectRoot) {
         warnings,
     };
 }
-function toEntry(sym, displayPath, normalizedPath, graph, maxRefs, projectRoot) {
+function toEntry(sym, normalizedPath, graph, maxRefs, projectRoot) {
     const startLine = sym.line;
     const endLine = sym.endLine ?? sym.line;
     const symbolNodeId = `${normalizedPath}:${sym.name}`;
@@ -311,14 +311,14 @@ function toEntry(sym, displayPath, normalizedPath, graph, maxRefs, projectRoot)
         : undefined;
     // A private/protected member of an exported class is reachable but NOT part
     // of the public API, so it must not count as `exported` for the api/internal
-    // split, the "exported" flag, or read ranking (#258). The extractor's
-    // sym.isExported is untouched (the review graph still sees the full surface);
-    // this gating is local to the report's presentation.
+    // split or read ranking (#258). The extractor's sym.isExported is untouched
+    // (the review graph still sees the full surface); this gating is local to
+    // the report's presentation.
     const nonPublic = sym.visibility === "private" || sym.visibility === "protected";
     const exported = (sym.isExported || !!node?.exported) && !nonPublic;
+    // `flags` carries only non-derivable signals — "exported" is NOT pushed here
+    // since it duplicates the `exported` boolean field below (#512).
     const flags = [];
-    if (exported)
-        flags.push("exported");
     if (sym.isAsync)
         flags.push("async");
     if (fanout !== undefined && fanout >= 4)
@@ -346,7 +346,6 @@ function toEntry(sym, displayPath, normalizedPath, graph, maxRefs, projectRoot)
         // outline (~200 tok total). Omit when there's nothing to report.
         ...(flags.length > 0 ? { flags } : {}),
         usedBy: usedBy && usedBy.length > 0 ? usedBy : undefined,
-        read: readArgsFor(displayPath, startLine, endLine),
     };
 }
 // Nest members under their container by line-range containment (#301), mirroring
@@ -399,8 +398,8 @@ function summarizeEntries(entries) {
         exported: entry.exported,
         ...(entry.visibility ? { visibility: entry.visibility } : {}),
         ...(entry.signature ? { signature: entry.signature } : {}),
+        ...(entry.doc ? { doc: entry.doc } : {}),
         ...(entry.flags ? { flags: entry.flags } : {}),
-        read: entry.read,
         ...(entry.members
             ? {
                 members: entry.members.map((member) => ({
@@ -411,7 +410,7 @@ function summarizeEntries(entries) {
                     exported: member.exported,
                     ...(member.visibility ? { visibility: member.visibility } : {}),
                     ...(member.signature ? { signature: member.signature } : {}),
-                    read: member.read,
+                    ...(member.doc ? { doc: member.doc } : {}),
                 })),
             }
             : {}),
@@ -483,7 +482,8 @@ function rankRecommendedReads(entries, callbacks = [], limit = 5, focus) {
             return {
                 reason: reasons.join(", ") || "public surface",
                 symbol: entry.name,
-                ...entry.read,
+                startLine: entry.startLine,
+                endLine: entry.endLine,
             };
         }
         const reasons = [];
@@ -500,7 +500,8 @@ function rankRecommendedReads(entries, callbacks = [], limit = 5, focus) {
         return {
             reason: reasons.join(", ") || item.callback.kind,
             symbol: item.callback.name,
-            ...item.callback.read,
+            startLine: item.callback.startLine,
+            endLine: item.callback.endLine,
         };
     });
 }
@@ -1030,7 +1031,7 @@ function callbackRulesFor(languageId) {
 function callbackSupportFor(languageId) {
     return languageId && CALLBACK_RULES[languageId] ? "tuned" : "generic";
 }
-function extractCallbacks(root, entries, filePath, languageId, warnings) {
+function extractCallbacks(root, entries, languageId, warnings) {
     if (!root)
         return [];
     const rules = callbackRulesFor(languageId);
@@ -1073,7 +1074,6 @@ function extractCallbacks(root, entries, filePath, languageId, warnings) {
                     signature: firstLine(node.text),
                     ...(owner ? { parentChain: [owner] } : {}),
                     ...(cls.flags ? { flags: cls.flags } : {}),
-                    read: readArgsFor(filePath, startLine, endLine),
                 });
             }
         }
@@ -1158,14 +1158,14 @@ export async function moduleReport(file, cwd, options) {
     // Flat entries first — ranking and cold-import resolution both read the full
     // list. `entries` is mutated by nestEntries (members attached); `topLevel` is
     // the api/internal split surface.
-    const entries = outlineSymbols.map((sym) => toEntry(sym, absPath, normalizedPath, graph, maxRefs, cwd));
+    const entries = outlineSymbols.map((sym) => toEntry(sym, normalizedPath, graph, maxRefs, cwd));
     const topLevel = nestEntries(entries);
     const api = topLevel.filter((entry) => entry.exported);
     const internal = topLevel.filter((entry) => !entry.exported);
     let callbacks = [];
     const warnings = [...(extractionWarnings ?? [])];
     try {
-        callbacks = extractCallbacks(root, entries, absPath, languageId, warnings);
+        callbacks = extractCallbacks(root, entries, languageId, warnings);
     }
     catch (err) {
         const message = diagnosticMessage(err);
@@ -1196,6 +1196,18 @@ export async function moduleReport(file, cwd, options) {
         }
         : warmImports;
     const hasGraphNode = graph?.fileNodes.has(normalizedPath) ?? false;
+    // #511: distinguish two very different reasons `usedBy`/`semantic` degrade to
+    // "none". A graph that doesn't exist at all (`!graph`) is an honest, expected
+    // cold start — the edit pipeline hasn't warmed this workspace yet. But a graph
+    // that DOES exist and just doesn't have a node for THIS file (e.g. the file was
+    // added/renamed after the graph was last persisted) is silently
+    // indistinguishable from "no who-uses-this data exists" unless we say so. Make
+    // the second case actionable: a rebuild (pilens_rebuild) would populate it.
+    if (graph && !hasGraphNode) {
+        warnings.push("who-uses-this is unavailable for this file: the cached review graph " +
+            "exists but has no node for it (likely added/changed after the graph " +
+            "was last built). Run pilens_rebuild to refresh it.");
+    }
     // Cross-file blast radius (#304): opt-in, read-only over the CACHED graph. Only
     // computed when requested AND the file is in a warm graph — a cold cache omits
     // the section entirely (never builds, same #256 contract as the rest of this
@@ -1205,6 +1217,11 @@ export async function moduleReport(file, cwd, options) {
         : undefined;
     const view = options?.view ?? "default";
     const summaryView = view === "summary";
+    // "compact" computes the same full data as "default" — it's a rendering
+    // instruction for the caller (renderCompactModuleReport), not a data tier —
+    // so it only needs to echo back on the report; it never gates section content
+    // the way summaryView does.
+    const compactView = view === "compact";
     let importsProvenance = "none";
     if (coldImportResult) {
         importsProvenance = "syntax";
@@ -1232,7 +1249,9 @@ export async function moduleReport(file, cwd, options) {
         callbackSupport: callbackSupportFor(languageId),
         recommendedReads: rankRecommendedReads(entries, callbacks, 5, options?.focus),
         ...(summaryView ? { view: "summary" } : {}),
+        ...(compactView ? { view: "compact" } : {}),
         ...(blastRadius && !summaryView ? { blastRadius } : {}),
+        ...(graph ? { graphBuiltAt: graph.builtAt } : {}),
         provenance: {
             symbols: languageId ? "syntax" : "none",
             imports: importsProvenance,
@@ -1267,6 +1286,132 @@ export async function moduleReport(file, cwd, options) {
     });
     return report;
 }
+// --- Compact (line-oriented text) rendering (#512 slice 4) ------------------
+//
+// An opt-in `view: "compact"` alternative to the JSON report: one line per
+// symbol/callback instead of a repeated-keys JSON object, at roughly a quarter
+// of the token cost for the same information. Purely a rendering step over the
+// already-built ModuleReport — it changes no data, only presentation, so a
+// caller that wants JSON just skips this function. Default view stays JSON
+// (this is opt-in for dogfooding, not a default flip).
+function padRange(startLine, endLine, width) {
+    return `${startLine}-${endLine}`.padEnd(width);
+}
+const KIND_ABBREV = {
+    function: "fn",
+    method: "fn",
+    class: "class",
+    interface: "iface",
+    type: "type",
+    variable: "var",
+    property: "prop",
+};
+function compactKind(kind) {
+    return KIND_ABBREV[kind] ?? kind;
+}
+function compactUsedBySuffix(usedBy) {
+    if (!usedBy || usedBy.length === 0)
+        return "";
+    const counts = new Map();
+    for (const u of usedBy)
+        counts.set(u.file, (counts.get(u.file) ?? 0) + 1);
+    const parts = [...counts.entries()].map(([file, n]) => n > 1 ? `${file}×${n}` : file);
+    return `  used-by: ${parts.join(", ")}`;
+}
+function compactEntryLine(entry, width) {
+    const range = padRange(entry.startLine, entry.endLine, width);
+    const kind = compactKind(entry.kind).padEnd(6);
+    const sig = entry.signature ? `${entry.name}${entry.signature}` : entry.name;
+    const flagsSuffix = entry.flags && entry.flags.length > 0 ? `  [${entry.flags.join(", ")}]` : "";
+    const docSuffix = entry.doc ? `  — ${entry.doc}` : "";
+    const usedBySuffix = compactUsedBySuffix(entry.usedBy);
+    return `  ${range}${kind}${sig}${flagsSuffix}${usedBySuffix}${docSuffix}`;
+}
+function compactMemberLines(entry, width, indent) {
+    if (!entry.members || entry.members.length === 0)
+        return [];
+    return entry.members.map((m) => `${indent}${compactEntryLine(m, width).slice(2)}`);
+}
+function compactCallbackLine(callback, width) {
+    const range = padRange(callback.startLine, callback.endLine, width);
+    const kind = callback.kind.padEnd(20);
+    const flagsSuffix = callback.flags && callback.flags.length > 0
+        ? `  [${callback.flags.join(", ")}]`
+        : "";
+    const ownerSuffix = callback.parentChain?.length
+        ? `  (in ${callback.parentChain.join(".")})`
+        : "";
+    return `  ${range}${kind}${callback.name}${flagsSuffix}${ownerSuffix}`;
+}
+/**
+ * Render a ModuleReport as the line-oriented compact text view (#512 slice 4):
+ * one line per symbol/member/callback instead of a JSON object per entry.
+ * Example:
+ * ```
+ * clients/agent-nudge.ts jsts 266L — 8 symbols, 5 exported | imports: bus-publish, latency-logger
+ * API:
+ *   77-81    fn  _resetAgentNudgeForTests()  — Test-only: clear accumulator state.
+ * INTERNAL:
+ *   95-104   fn  isValidPayload(data: unknown)
+ * CALLBACKS:
+ *   164-172  event_handler  events.on@164  [lifecycle]  (in wireAgentNudgeSubscriber)
+ * ```
+ * Purely presentational over an already-built report — call `moduleReport`
+ * first (with `view: "compact"` or any other view) and pass its result here.
+ */
+export function renderCompactModuleReport(report) {
+    if (!report.available) {
+        return `${report.path} — unavailable${report.error ? `: ${report.error}` : ""}`;
+    }
+    const allEntries = [...report.api, ...report.internal];
+    const allRanges = allEntries.flatMap((e) => [
+        e,
+        ...(e.members ?? []),
+    ]);
+    const width = Math.max(5, ...allRanges.map((e) => `${e.startLine}-${e.endLine}`.length), ...report.callbacks.map((c) => `${c.startLine}-${c.endLine}`.length)) + 2;
+    const importsList = [...report.imports.internal, ...report.imports.external];
+    const importsSuffix = importsList.length > 0
+        ? ` | imports: ${importsList
+            .slice(0, 6)
+            .map((i) => baseNameNoExt(i))
+            .join(", ")}${importsList.length > 6 ? ", …" : ""}`
+        : "";
+    const lines = [
+        `${report.path} ${report.language ?? "?"} ${report.lineCount ?? "?"}L — ` +
+            `${report.summary.symbols} symbols, ${report.summary.exports} exported${importsSuffix}`,
+    ];
+    if (report.api.length > 0) {
+        lines.push("API:");
+        for (const entry of report.api) {
+            lines.push(compactEntryLine(entry, width));
+            lines.push(...compactMemberLines(entry, width, "    "));
+        }
+    }
+    if (report.internal.length > 0) {
+        lines.push("INTERNAL:");
+        for (const entry of report.internal) {
+            lines.push(compactEntryLine(entry, width));
+            lines.push(...compactMemberLines(entry, width, "    "));
+        }
+    }
+    if (report.callbacks.length > 0) {
+        lines.push("CALLBACKS:");
+        for (const callback of report.callbacks) {
+            lines.push(compactCallbackLine(callback, width));
+        }
+    }
+    if (report.recommendedReads.length > 0) {
+        lines.push("RECOMMENDED:");
+        for (const r of report.recommendedReads) {
+            lines.push(`  ${padRange(r.startLine, r.endLine, width)}${r.symbol ?? ""}  — ${r.reason}`);
+        }
+    }
+    return lines.join("\n");
+}
+function baseNameNoExt(p) {
+    const base = p.split(/[\\/]/).pop() ?? p;
+    return base.replace(/\.[^./\\]+$/, "");
+}
 /**
  * Return the verbatim body of a single symbol. Unlike moduleReport (which shows
  * shape, not content), this delivers the actual source lines — so the host can
@@ -1339,7 +1484,7 @@ export async function readSymbol(file, symbolName, cwd) {
     let callback;
     const callbackWarnings = [...(extractionWarnings ?? [])];
     try {
-        callback = extractCallbacks(root, owners, absPath, languageId, callbackWarnings).find((candidate) => candidate.name === symbolName);
+        callback = extractCallbacks(root, owners, languageId, callbackWarnings).find((candidate) => candidate.name === symbolName);
     }
     catch (err) {
         const message = `Callback extraction failed: ${diagnosticMessage(err)}`;
@@ -1460,7 +1605,7 @@ function enclosingOutline(selected, symbols, callbacks, filters, filePath) {
             endLine: callback.endLine,
             signature: callback.signature,
             parentChain: callback.parentChain,
-            read: callback.read,
+            read: readArgsFor(filePath, callback.startLine, callback.endLine),
         });
     }
     return items
@@ -1521,7 +1666,7 @@ export async function readEnclosing(file, line, cwd, options) {
     const warnings = [...(extractionWarnings ?? [])];
     let callbacks = [];
     try {
-        callbacks = extractCallbacks(root, owners, absPath, languageId, warnings);
+        callbacks = extractCallbacks(root, owners, languageId, warnings);
     }
     catch (err) {
         const message = `Callback extraction failed: ${diagnosticMessage(err)}`;

package/dist/clients/path-utils.js

@@ -124,6 +124,31 @@ export function pathToUri(filePath) {
 export function normalizeMapKey(filePath) {
     return normalizeFilePath(filePath);
 }
+/**
+ * Cheap, syntactic-only Map key normalization: slash-fold + (on Windows)
+ * lowercase. No `realpathSync` / filesystem I/O.
+ *
+ * `normalizeMapKey` (via `normalizeFilePath`) calls `realpathSync.native()` to
+ * get canonical on-disk casing — correct for maps that key long-lived state
+ * shared across call sites (e.g. LSP/read-guard caches), but expensive when
+ * the *point* of the cache is to avoid filesystem calls in the first place:
+ * for a candidate path that does NOT exist (the common case for sibling-probe
+ * memos), `normalizeFilePath` walks up the directory tree doing its own
+ * `existsSync` calls to resolve the nearest existing ancestor — measured at
+ * ~11x slower than the single `existsSync` probe such a cache is trying to
+ * save (refs #191).
+ *
+ * Safe to use ONLY for ephemeral, single-process, single-walk caches whose
+ * keys are produced by this process's own `path.join`/`path.resolve` calls
+ * within the same run (so separators and casing are already consistent
+ * modulo simple slash direction) — never for state shared across processes,
+ * persisted, or compared against externally-supplied paths where symlink /
+ * real-casing resolution actually matters.
+ */
+export function normalizeEphemeralMapKey(filePath) {
+    const slashed = filePath.replace(/\\/g, "/");
+    return process.platform === "win32" ? slashed.toLowerCase() : slashed;
+}
 /**
  * Compare two file paths for equality, handling Windows case-insensitivity
  * and mixed separators (backslash vs forward slash).

package/dist/clients/persist-debounce.js

@@ -0,0 +1,63 @@
+/**
+ * Generalized debounced-persist coalescing scheduler (#348 phase 2), factored
+ * out of the review graph's #260 circuit-breaker so a second warm cache
+ * (the word index) doesn't grow a parallel copy of the same discipline:
+ *   1. Coalesce: a burst of edits schedules ONE write after a quiet window,
+ *      instead of one write per edit.
+ *   2. Best-effort teardown flush: a process-exit hook flushes any pending
+ *      writes synchronously so a debounced payload is never silently lost.
+ *
+ * What stayed OUT of this module (left to each caller, deliberately not
+ * generalized): the actual serialize+write. The review graph writes its own
+ * cache file (tmp+rename, size-cap check, git-stamp) while the word index
+ * merges into the shared project-snapshot file via `saveProjectSnapshot`
+ * (preserving unrelated fields, honoring the seq-laundering guard). Those
+ * writers are different enough (different files, different merge semantics)
+ * that forcing them through one write function would either leak
+ * graph-specific concerns into the snapshot path or vice versa. The
+ * scheduler only owns "when", never "how".
+ */
+/**
+ * Build a debounce scheduler over `write(key, payload)`. `debounceMs()` is
+ * read fresh on every schedule call (not captured once) so a test that
+ * flips its env override mid-run takes effect immediately, same as the
+ * graph's `graphPersistDebounceMs()`.
+ */
+export function createDebounceScheduler(args) {
+    const { write, debounceMs } = args;
+    const pending = new Map();
+    const timers = new Map();
+    function flush(key) {
+        const payload = pending.get(key);
+        if (payload === undefined)
+            return;
+        pending.delete(key);
+        const timer = timers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+            timers.delete(key);
+        }
+        write(key, payload);
+    }
+    function flushAll() {
+        for (const key of [...pending.keys()])
+            flush(key);
+    }
+    function schedule(key, payload) {
+        pending.set(key, payload);
+        const debounce = debounceMs();
+        const existing = timers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        if (debounce === 0) {
+            flush(key);
+            return;
+        }
+        const timer = setTimeout(() => flush(key), debounce);
+        // Don't keep the event loop alive solely for a debounced write.
+        if (typeof timer.unref === "function")
+            timer.unref();
+        timers.set(key, timer);
+    }
+    return { schedule, flush, flushAll };
+}

package/dist/clients/pipeline.js

@@ -27,6 +27,8 @@ import { detectFileKind, getFileKindLabel } from "./file-kinds.js";
 import { detectFileChangedAfterCommand, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
 import { logLatency } from "./latency-logger.js";
 import { emitLensAnalysisComplete } from "./lens-events.js";
+import { publishFilesTouched } from "./bus-publish.js";
+import { publishDiagnostics, wasPreviouslyReportedDirty, } from "./diagnostics-publish.js";
 import { getLSPService } from "./lsp/index.js";
 import { clearGraphCache } from "./review-graph/builder.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
@@ -651,6 +653,23 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
         dbg(`LSP resync after autofix error: ${err}`);
     }
 }
+/** Maps a dispatch `Diagnostic` (clients/dispatch/types.ts) to the #502 bus payload shape. */
+function toPilensDiagnosticEntry(d) {
+    const entry = {
+        severity: d.severity,
+        message: d.message,
+        tool: d.tool,
+    };
+    if (d.rule !== undefined)
+        entry.ruleId = d.rule;
+    if (d.line !== undefined)
+        entry.line = d.line;
+    if (d.column !== undefined)
+        entry.col = d.column;
+    if (d.fixable !== undefined)
+        entry.fixable = d.fixable;
+    return entry;
+}
 function buildAllClearOutput(_dispatchResult, elapsed, filePath) {
     const kind = detectFileKind(filePath);
     const langLabel = kind ? getFileKindLabel(kind) : path.extname(filePath);
@@ -766,8 +785,21 @@ export async function runPipeline(ctx, deps) {
         formattersUsed = formatResult.formattersUsed;
         formatFailures = formatResult.formatFailures;
         fileContent = formatResult.fileContent;
-        if (formatChanged)
-            piChangedFiles.add(path.resolve(filePath));
+        if (formatChanged) {
+            const absPath = path.resolve(filePath);
+            piChangedFiles.add(absPath);
+            publishFilesTouched({
+                reason: "format",
+                paths: [absPath],
+                cwd,
+                dbg,
+                fixes: formattersUsed.map((tool) => ({
+                    path: absPath,
+                    tool,
+                    kind: "format",
+                })),
+            });
+        }
     }
     else if (formatDeferred) {
         dbg(`autoformat: deferred until agent_end for ${filePath}`);
@@ -783,6 +815,23 @@ export async function runPipeline(ctx, deps) {
     for (const changedFile of autofixChangedFiles) {
         piChangedFiles.add(path.resolve(changedFile));
     }
+    if (autofixChangedFiles.length > 0) {
+        // autofixTools entries are "tool:count" (e.g. "ruff:3"); runAutofix runs
+        // against ONE target filePath per call, so every tool that fired in this
+        // batch applies to every file the batch changed — best-effort attribution
+        // (not per-file precision) since the underlying tool runners don't report
+        // per-changed-file breakdown. Good enough for the "was this hunk
+        // mechanical" use case the fix-provenance field exists for.
+        const absChangedFiles = autofixChangedFiles.map((f) => path.resolve(f));
+        const toolNames = autofixTools.map((t) => t.split(":")[0]);
+        publishFilesTouched({
+            reason: "autofix",
+            paths: absChangedFiles,
+            cwd,
+            dbg,
+            fixes: absChangedFiles.flatMap((p) => toolNames.map((tool) => ({ path: p, tool, kind: "autofix" }))),
+        });
+    }
     if (fixRefresh) {
         try {
             fileContent = nodeFs.readFileSync(filePath, "utf-8");
@@ -820,6 +869,30 @@ export async function runPipeline(ctx, deps) {
         writeIndex: ctx.telemetry?.writeIndex ?? 0,
     });
     recordDiagnostics(filePath, dispatchResult.diagnostics);
+    // #502: emit the write batch's FINAL diagnostic state immediately after
+    // recordDiagnostics commits it — this call site runs after format,
+    // autofix, and dispatch have all completed for this batch (see the phase
+    // order above), so dispatchResult.diagnostics IS the latest post-batch
+    // picture, not an intermediate runner result. Full-replace semantics: we
+    // always pass the complete current set for this file, including an
+    // explicit `[]` on the transition from a previously-reported-dirty state
+    // to clean (see clients/diagnostics-publish.ts for the contract).
+    {
+        const absPath = path.resolve(filePath);
+        const wasDirty = wasPreviouslyReportedDirty(absPath);
+        if (dispatchResult.diagnostics.length > 0 || wasDirty) {
+            publishDiagnostics({
+                cwd,
+                files: [
+                    {
+                        path: absPath,
+                        diagnostics: dispatchResult.diagnostics.map(toPilensDiagnosticEntry),
+                    },
+                ],
+                dbg,
+            });
+        }
+    }
     const hasBlockers = dispatchResult.hasBlockers;
     const actionableWarnings = dispatchResult.warnings
         .map((diagnostic) => recordFromDispatchDiagnostic(diagnostic, cwd))
@@ -910,6 +983,9 @@ export async function runPipeline(ctx, deps) {
             turnSeq: ctx.telemetry?.turnIndex,
             writeSeq: ctx.telemetry?.writeIndex,
             seqState: ctx.seqState,
+            fileContent,
+            wordIndex: ctx.wordIndex,
+            onWordIndexUpdated: ctx.onWordIndexUpdated,
         }).catch((err) => {
             dbg(`cascade compute failed for ${filePath}: ${err}`);
             return {
@@ -958,5 +1034,9 @@ export async function runPipeline(ctx, deps) {
             : undefined,
         actionableWarnings,
         codeQualityWarnings,
+        diagnostics: dispatchResult.diagnostics,
+        formattersUsed,
+        fixedCount,
+        autofixTools,
     };
 }

package/dist/clients/project-diagnostics/extractors.js

@@ -56,14 +56,38 @@ const EXTRACTORS = [
         adapt: (cwd, r) => deadCodeResultToProjectDiagnostics(cwd, r),
     },
 ];
+/**
+ * #533: which trigger warms each extractor's cache, surfaced in the "cold"
+ * honesty note so the note is actionable (names what to do), matching the
+ * #511/#514 house shape. Keep in sync with `EXTRACTORS` — one line per id.
+ */
+const WARM_TRIGGER = {
+    knip: "runs at session-start",
+    jscpd: "runs at session-start",
+    madge: "runs at session-start",
+    gitleaks: "runs at session-start",
+    govulncheck: "runs at session-start (Go projects only)",
+    trivy: "runs at session-start",
+    "dead-code": "runs at session-start (Python projects only)",
+};
+/** All registered extractor ids, in registry order — exported for tools/tests
+ *  that need to enumerate "what could this section include" without reaching
+ *  into the private `EXTRACTORS` table. */
+export const PROJECT_DIAGNOSTIC_EXTRACTOR_IDS = EXTRACTORS.map((e) => e.id);
+export function warmTriggerFor(extractorId) {
+    return WARM_TRIGGER[extractorId] ?? "runs at session-start";
+}
 /**
  * Read every registered analyzer's cached result and adapt it to project
- * diagnostics. Returns the merged diagnostics plus the ids of the analyzers that
- * actually contributed (for the snapshot's `runners` list). Cache-only: no scans.
+ * diagnostics. Returns the merged diagnostics, the ids of the analyzers that
+ * actually contributed findings (for the snapshot's `runners` list), and the
+ * ids of analyzers with NO cache entry at all yet (`cold`) — distinct from an
+ * analyzer that ran and found nothing. Cache-only: no scans.
  */
 export function extractCachedProjectDiagnostics(cacheManager, cwd) {
     const diagnostics = [];
     const runners = [];
+    const cold = [];
     for (const extractor of EXTRACTORS) {
         let data;
         for (const key of extractor.cacheKeys) {
@@ -73,13 +97,15 @@ export function extractCachedProjectDiagnostics(cacheManager, cwd) {
                 break;
             }
         }
-        if (data === undefined)
+        if (data === undefined) {
+            cold.push(extractor.id);
             continue;
+        }
         const adapted = extractor.adapt(cwd, data);
         if (adapted.length > 0) {
             diagnostics.push(...adapted);
             runners.push(extractor.id);
         }
     }
-    return { diagnostics, runners };
+    return { diagnostics, runners, cold };
 }

package/dist/clients/project-snapshot.js

@@ -123,8 +123,13 @@ export function saveRuntimeProjectSnapshot(args) {
             snapshot.reverseDeps = existing.reverseDeps ?? {};
             // The word index is built by its own session task, which may not have
             // finished when another task triggers a save — keep the prior index
-            // rather than clobbering it with undefined.
-            if (!snapshot.wordIndex && existing.wordIndex) {
+            // rather than clobbering it with undefined. #348: only carry it forward
+            // when `existing` was built AT THIS SAME seq — otherwise a stale
+            // snapshot's leftover index (already correctly rejected as stale by
+            // isProjectSnapshotFresh on load, seq mismatch) would get silently
+            // re-stamped with the CURRENT seq by this save, "laundering" a stale
+            // index into looking fresh before the word-index task even runs.
+            if (!snapshot.wordIndex && existing.wordIndex && existing.seq === snapshot.seq) {
                 snapshot.wordIndex = existing.wordIndex;
             }
         }