@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/dist/clients/mcp/analyze.js

@@ -13,16 +13,19 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { CacheManager } from "../cache-manager.js";
+import { CacheManager, MCP_TURN_STATE_OWNER_ID } from "../cache-manager.js";
 import { CASCADE_GRAPH_KINDS, dispatchLintWithResult, getLatencyReports, } from "../dispatch/integration.js";
 import { FactStore } from "../dispatch/fact-store.js";
 import { detectFileKind } from "../file-kinds.js";
 import { getDiagnosticTracker } from "../diagnostic-tracker.js";
 import { getLSPService } from "../lsp/index.js";
+import { PathKeyedMap } from "../path-keyed-map.js";
+import { normalizeMapKey } from "../path-utils.js";
 import { loadProjectSnapshot } from "../project-snapshot.js";
 import { buildOrUpdateGraph } from "../review-graph/service.js";
 import { recordDiagnostics } from "../widget-state.js";
 import { deserializeWordIndex, removeWordIndexDocument, scheduleWordIndexPersist, updateWordIndexDocument, WORD_INDEX_MAX_BYTES, } from "../word-index.js";
+import { logWordIndex } from "../word-index-logger.js";
 import { createMcpHost } from "./host-shim.js";
 // #536: module-scoped FactStore for the warm-analyze graph seam, mirroring the
 // per-edit cascade path's own module-level `sessionFacts` singleton
@@ -43,7 +46,59 @@ const warmGraphFacts = new FactStore();
 // nothing usable" (index missing or pre-phase-2/no-forward-map), distinct from
 // "never checked" (key absent) — avoids re-attempting a snapshot load with no
 // forward index on every single analyze call.
-const warmWordIndexes = new Map();
+const DEFAULT_WORD_INDEX_IDLE_EVICT_MS = 20 * 60_000;
+const DEFAULT_WORD_INDEX_MAX_WARM_ROOTS = 8;
+const warmWordIndexes = new PathKeyedMap(normalizeMapKey);
+function positiveEnv(name, fallback) {
+    const parsed = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function idleEvictMs() {
+    return positiveEnv("PI_LENS_WORD_INDEX_IDLE_EVICT_MS", DEFAULT_WORD_INDEX_IDLE_EVICT_MS);
+}
+function maxWarmRoots() {
+    return positiveEnv("PI_LENS_WORD_INDEX_MAX_WARM_ROOTS", DEFAULT_WORD_INDEX_MAX_WARM_ROOTS);
+}
+function clearWarmWordIndexTimer(entry) {
+    if (entry.timer)
+        clearTimeout(entry.timer);
+    entry.timer = undefined;
+}
+function evictWarmWordIndex(key, entry, reason) {
+    if (entry.leases > 0 || warmWordIndexes.get(key) !== entry)
+        return false;
+    clearWarmWordIndexTimer(entry);
+    warmWordIndexes.delete(key);
+    logWordIndex({
+        phase: "warm_cache_evicted",
+        cwd: key,
+        trigger: "mcp",
+        reason,
+    });
+    return true;
+}
+function scheduleWarmWordIndexIdleEviction(key, entry) {
+    clearWarmWordIndexTimer(entry);
+    const generation = ++entry.generation;
+    const timer = setTimeout(() => {
+        entry.timer = undefined;
+        if (warmWordIndexes.get(key) !== entry || entry.generation !== generation)
+            return;
+        if (!evictWarmWordIndex(key, entry, "idle"))
+            scheduleWarmWordIndexIdleEviction(key, entry);
+    }, idleEvictMs());
+    timer.unref?.();
+    entry.timer = timer;
+}
+function enforceWarmWordIndexLruCap() {
+    while (warmWordIndexes.size > maxWarmRoots()) {
+        const victim = [...warmWordIndexes.entries()]
+            .filter(([, entry]) => entry.leases === 0)
+            .sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+        if (!victim || !evictWarmWordIndex(victim[0], victim[1], "lru"))
+            return;
+    }
+}
 /**
  * Look up (loading from the persisted snapshot on first use per cwd) the warm
  * in-memory word index this analyze facade keeps mutated in place. Exported so
@@ -52,26 +107,57 @@ const warmWordIndexes = new Map();
  * following a warm `pilens_analyze` call in the SAME process would read a
  * stale on-disk snapshot until the debounced persist (default 1500ms) flushes.
  */
-export function getOrLoadWarmWordIndex(cwd) {
+export function acquireWarmWordIndex(cwd) {
     const key = path.resolve(cwd);
-    if (warmWordIndexes.has(key))
-        return warmWordIndexes.get(key);
-    const snapshot = loadProjectSnapshot(key);
-    const index = deserializeWordIndex(snapshot?.wordIndex) ?? undefined;
-    // Same phase-2 rule as updateWordIndexForCascade: no forward index ⇒ no
-    // incremental primitive available, so don't cache it as "usable" — this
-    // call site's whole point is the incremental single-doc update.
-    const usable = index?.forward ? index : undefined;
-    warmWordIndexes.set(key, usable);
-    return usable;
+    let entry = warmWordIndexes.get(key);
+    if (!entry) {
+        const snapshot = loadProjectSnapshot(key);
+        const index = deserializeWordIndex(snapshot?.wordIndex) ?? undefined;
+        entry = {
+            index: index?.forward ? index : undefined,
+            timer: undefined,
+            leases: 0,
+            lastUsedAt: Date.now(),
+            generation: 0,
+        };
+        warmWordIndexes.set(key, entry);
+    }
+    entry.leases++;
+    entry.lastUsedAt = Date.now();
+    scheduleWarmWordIndexIdleEviction(key, entry);
+    enforceWarmWordIndexLruCap();
+    let released = false;
+    return {
+        index: entry.index,
+        release() {
+            if (released)
+                return;
+            released = true;
+            entry.leases = Math.max(0, entry.leases - 1);
+            entry.lastUsedAt = Date.now();
+            if (warmWordIndexes.get(key) === entry) {
+                scheduleWarmWordIndexIdleEviction(key, entry);
+                enforceWarmWordIndexLruCap();
+            }
+        },
+    };
 }
 /**
  * Test-only reset — the module-level warm cache otherwise survives across
  * unrelated test cases in the same vitest worker.
  */
 export function _resetWarmWordIndexCacheForTests() {
+    for (const entry of warmWordIndexes.values())
+        clearWarmWordIndexTimer(entry);
     warmWordIndexes.clear();
 }
+export function _getWarmWordIndexCacheStateForTests() {
+    return {
+        size: warmWordIndexes.size,
+        keys: [...warmWordIndexes.keys()],
+        timers: [...warmWordIndexes.values()].flatMap((entry) => entry.timer ? [entry.timer] : []),
+    };
+}
 // Generous warm-up budgets: a cold language server needs to spawn AND publish
 // diagnostics. The per-edit dispatch runner caps these tightly (spawn budget +
 // 2500ms) for latency; a review tool prioritises completeness, so we pre-warm
@@ -153,6 +239,10 @@ export async function analyzeFile(filePath, cwd, options = {}) {
     }
     const reportsBefore = getLatencyReports().length;
     const start = Date.now();
+    // No telemetryModel/telemetryProvider here (#1448): this MCP facade has no
+    // RuntimeCoordinator to hold a host-reported identity (see the module doc
+    // above), so any worklog entries this dispatch produces get a blank
+    // model/provider — that's correct, not a gap.
     const result = await dispatchLintWithResult(absPath, cwd, host, undefined, undefined, {
         blockingOnly: options.blockingOnly ?? false,
     });
@@ -167,11 +257,11 @@ export async function analyzeFile(filePath, cwd, options = {}) {
     }
     if (options.registerTurnState) {
         // Full-file range, importsChanged=true (conservative → dep/knip re-check
-        // broadly). No sessionId — leaving it unset avoids turn_end's stale-session
-        // eviction. Best-effort.
+        // broadly). Clear any stale pi session ID because the MCP Stop route owns
+        // this workspace-scoped worklist independently. Best-effort.
         try {
             const lineCount = fs.readFileSync(absPath, "utf8").split("\n").length;
-            new CacheManager().addModifiedRange(absPath, { start: 1, end: lineCount }, true, cwd);
+            new CacheManager().addModifiedRange(absPath, { start: 1, end: lineCount }, true, cwd, options.ownerId ?? MCP_TURN_STATE_OWNER_ID, "mcp");
         }
         catch {
             // unreadable — skip turn-state registration
@@ -215,24 +305,30 @@ export async function analyzeFile(filePath, cwd, options = {}) {
         // INTERNALLY (PathKeyedMap), so this edit-form key and the build path's
         // walk-derived key converge on the same entry regardless of casing/
         // separator — the old duplicate-orphan hazard is gone at the map layer.
-        const warmIndex = getOrLoadWarmWordIndex(cwd);
-        if (warmIndex) {
-            try {
-                const content = fs.readFileSync(absPath, "utf8");
-                const byteLength = Buffer.byteLength(content, "utf-8");
-                if (byteLength > WORD_INDEX_MAX_BYTES) {
-                    removeWordIndexDocument(warmIndex, absPath);
+        const warmLease = acquireWarmWordIndex(cwd);
+        const warmIndex = warmLease.index;
+        try {
+            if (warmIndex) {
+                try {
+                    const content = fs.readFileSync(absPath, "utf8");
+                    const byteLength = Buffer.byteLength(content, "utf-8");
+                    if (byteLength > WORD_INDEX_MAX_BYTES) {
+                        removeWordIndexDocument(warmIndex, absPath);
+                    }
+                    else {
+                        updateWordIndexDocument(warmIndex, { path: absPath, content });
+                    }
+                    scheduleWordIndexPersist(cwd, warmIndex);
                 }
-                else {
-                    updateWordIndexDocument(warmIndex, { path: absPath, content });
+                catch {
+                    // unreadable/deleted, or an update failure — best-effort, same as the
+                    // graph update above.
                 }
-                scheduleWordIndexPersist(cwd, warmIndex);
-            }
-            catch {
-                // unreadable/deleted, or an update failure — best-effort, same as the
-                // graph update above.
             }
         }
+        finally {
+            warmLease.release();
+        }
     }
     // dispatchForFile appended a latency report during the call above. Match the
     // newly-added report for this exact path; fall back to the most recent new
@@ -243,8 +339,7 @@ export async function analyzeFile(filePath, cwd, options = {}) {
     const lspRunner = latencyReport?.runners.find((runner) => runner.runnerId === "lsp");
     const lsp = lspRunner
         ? {
-            ran: lspRunner.status !== "skipped" &&
-                lspRunner.status !== "when_skipped",
+            ran: lspRunner.status !== "skipped" && lspRunner.status !== "when_skipped",
             status: lspRunner.status,
             diagnosticCount: lspRunner.diagnosticCount,
             durationMs: lspRunner.durationMs,

package/node_modules/pi-lens/dist/clients/mcp/ipc.js

@@ -6,16 +6,19 @@
  * connects to it to get LSP-complete diagnostics from the warm process instead
  * of running its own cold analysis.
  *
- * This module is the CLIENT + the shared path derivation only — deliberately
- * light (node:net + type-only result), so the bin can try the warm path WITHOUT
- * loading the dispatch graph. The server side lives in mcp/server.ts (which
- * already holds the analysis engine). If the warm path is unavailable, the
- * client resolves `undefined` and the caller falls back to cold local analysis.
+ * This module is the CLIENT + the shared path derivation + the one-shot line
+ * reader the server wires into its socket (deliberately light: node:net +
+ * type-only result, so the bin can try the warm path WITHOUT loading the
+ * dispatch graph). The analysis engine lives in mcp/server.ts. If the warm
+ * path is unavailable, the client resolves `undefined` and the caller falls
+ * back to cold local analysis.
  */
 import * as crypto from "node:crypto";
+import * as fs from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { writeFileAtomic } from "../atomic-write.js";
 export const WARM_DIAGNOSTICS_SCHEMA_VERSION = 1;
 export const WARM_CODE_ACTION_LOOKUP_LIMIT = 6;
 /**
@@ -25,19 +28,23 @@ export const WARM_CODE_ACTION_LOOKUP_LIMIT = 6;
  * the same project they meet. Mismatch → the client just falls back to cold.
  */
 export function ipcPathForCwd(cwd) {
-    const root = path.resolve(cwd).toLowerCase();
-    // sha256 (not for security — just a stable short id for the IPC socket/pipe
-    // name keyed by cwd; sha256 over sha1 keeps SonarCloud's weak-hash check quiet)
-    const hash = crypto
-        .createHash("sha256")
-        .update(root)
-        .digest("hex")
-        .slice(0, 16);
+    const hash = workspaceHash(cwd);
     if (process.platform === "win32") {
         return `\\\\.\\pipe\\pi-lens-mcp-${hash}`;
     }
     return path.join(os.tmpdir(), `pi-lens-mcp-${hash}.sock`);
 }
+/**
+ * The single stable per-workspace id both endpoint derivations key on. Every
+ * per-workspace side-channel name (socket/pipe, turn-end status file) must come
+ * from HERE, so the hook process and the server process cannot drift apart.
+ */
+function workspaceHash(cwd) {
+    const root = path.resolve(cwd).toLowerCase();
+    // sha256 (not for security — just a stable short id for the IPC socket/pipe
+    // name keyed by cwd; sha256 over sha1 keeps SonarCloud's weak-hash check quiet)
+    return crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
 /** PID-scoped endpoint used by pi sessions. The legacy MCP analyze endpoint
  * remains workspace-scoped for compatibility with the PostToolUse hook. */
 export function diagnosticsIpcPathForCwd(cwd, pid) {
@@ -50,15 +57,16 @@ export function contentHash(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
 /**
- * Shared one-shot request/response transport for the warm-attach IPC routes
- * (#822): connect to the incumbent's PID-scoped endpoint, write one JSON
- * line, read one JSON line back, classify. The per-route `validate` callback
- * returns a failure reason for an on-time but unusable reply (schema skew,
- * staleness) or `undefined` to accept it; transport failures map uniformly to
- * timeout/ipc-error. One transport, N routes — the diagnostics and
- * code-action clients cannot drift apart.
+ * Shared one-shot request/response transport for the tagged IPC routes (#822):
+ * connect to `endpoint`, write one JSON line, read one JSON line back,
+ * classify. The endpoint is PID-scoped for the warm-attach routes and
+ * workspace-scoped for the hook bin's turn-end route. The per-route `validate`
+ * callback returns a failure reason for an on-time but unusable reply (schema
+ * skew, staleness) or `undefined` to accept it; transport failures map
+ * uniformly to timeout/ipc-error. One transport, N routes — the clients cannot
+ * drift apart.
  */
-function requestOverWarmIpc(cwd, incumbentPid, timeoutMs, buildRequest, validate) {
+function requestOverWarmIpc(endpoint, timeoutMs, buildRequest, validate) {
     return new Promise((resolve) => {
         let settled = false;
         const finish = (value) => {
@@ -70,7 +78,7 @@ function requestOverWarmIpc(cwd, incumbentPid, timeoutMs, buildRequest, validate
             resolve(value);
         };
         const deadlineAt = Date.now() + timeoutMs;
-        const socket = net.createConnection(diagnosticsIpcPathForCwd(cwd, incumbentPid));
+        const socket = net.createConnection(endpoint);
         socket.setEncoding("utf8");
         let buffer = "";
         const timer = setTimeout(() => finish({ available: false, reason: "timeout" }), timeoutMs);
@@ -108,7 +116,7 @@ function requestOverWarmIpc(cwd, incumbentPid, timeoutMs, buildRequest, validate
 }
 export function requestWarmDiagnostics(cwd, incumbentPid, file, content, timeoutMs) {
     const expectedHash = contentHash(content);
-    return requestOverWarmIpc(cwd, incumbentPid, timeoutMs, (deadlineAt) => ({
+    return requestOverWarmIpc(diagnosticsIpcPathForCwd(cwd, incumbentPid), timeoutMs, (deadlineAt) => ({
         route: "diagnostics",
         version: WARM_DIAGNOSTICS_SCHEMA_VERSION,
         file,
@@ -131,7 +139,7 @@ export function requestWarmDiagnostics(cwd, incumbentPid, file, content, timeout
     });
 }
 export function requestWarmCodeActions(cwd, incumbentPid, file, expectedContentHash, ranges, timeoutMs) {
-    return requestOverWarmIpc(cwd, incumbentPid, timeoutMs, (deadlineAt) => ({
+    return requestOverWarmIpc(diagnosticsIpcPathForCwd(cwd, incumbentPid), timeoutMs, (deadlineAt) => ({
         route: "code-actions",
         version: WARM_DIAGNOSTICS_SCHEMA_VERSION,
         file,
@@ -154,6 +162,99 @@ export function requestWarmCodeActions(cwd, incumbentPid, file, expectedContentH
         return undefined;
     });
 }
+// v2 adds an explicit receipt acknowledgement. A v1 server must reject rather
+// than consume a pass without the new delivery contract.
+export const WARM_TURN_END_SCHEMA_VERSION = 2;
+/**
+ * Ask the warm server to run pi-lens's real turn-end pass. Execution and
+ * delivery are separate: the first one-shot connection returns a capability,
+ * then a second one-shot connection acknowledges receipt. If the client
+ * deadline or either connection loses, the server leaves the durable finding
+ * cache untouched for a later Stop. 55 s expires inside Claude Code's 60 s hook
+ * timeout.
+ */
+export async function requestWarmTurnEnd(cwd, timeoutMs = 55_000) {
+    const startedAt = Date.now();
+    const first = await requestOverWarmIpc(ipcPathForCwd(cwd), timeoutMs, () => ({
+        route: "turn-end",
+        version: WARM_TURN_END_SCHEMA_VERSION,
+        cwd,
+    }), (result) => result.route === "turn-end" &&
+        result.version === WARM_TURN_END_SCHEMA_VERSION
+        ? undefined
+        : "schema-mismatch");
+    if (!first.available || !first.response.deliveryId)
+        return first;
+    const remainingMs = timeoutMs - (Date.now() - startedAt);
+    if (remainingMs <= 0)
+        return { available: false, reason: "timeout" };
+    const ack = await requestOverWarmIpc(ipcPathForCwd(cwd), remainingMs, () => ({
+        route: "turn-end-ack",
+        version: WARM_TURN_END_SCHEMA_VERSION,
+        cwd,
+        deliveryId: first.response.deliveryId,
+    }), (result) => result.route === "turn-end-ack" && result.acknowledged === true
+        ? undefined
+        : "ipc-error");
+    return ack.available
+        ? { available: true, response: first.response }
+        : { available: false, reason: ack.reason };
+}
+/** Per-workspace status file, keyed by the same hash as the IPC endpoint. */
+export function turnEndStatusPathForCwd(cwd) {
+    return path.join(os.tmpdir(), `pi-lens-turn-end-${workspaceHash(cwd)}.json`);
+}
+export function readTurnEndStatus(cwd) {
+    try {
+        const raw = fs.readFileSync(turnEndStatusPathForCwd(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return undefined;
+        return {
+            ran: typeof parsed.ran === "number" ? parsed.ran : 0,
+            skipped: typeof parsed.skipped === "number" ? parsed.skipped : 0,
+            lastSkipReason: parsed.lastSkipReason,
+            lastRunAt: parsed.lastRunAt,
+            lastSkipAt: parsed.lastSkipAt,
+        };
+    }
+    catch {
+        // never written, unreadable, or corrupt — "no turn-end activity recorded"
+        return undefined;
+    }
+}
+/**
+ * Append one turn-end outcome from the hook process. Never throws.
+ *
+ * Read-modify-write against a shared per-workspace tmpdir file: two Stop
+ * hooks for the same workspace can race this concurrently (separate
+ * processes, no lock). `writeFileAtomic` only closes the *publication* half
+ * of that — it guarantees this write's own staging+rename can't torn-read
+ * (parse-fail and reset counters) or hit a Windows sharing violation against
+ * a concurrent writer's rename. It does NOT fix the read-modify-write race
+ * itself: two overlapping calls can still both read the same `previous` and
+ * publish from it, silently dropping one increment. That's accepted here —
+ * this is bounded best-effort telemetry (self-heals, errors already
+ * swallowed below), and a lock on this path isn't worth it.
+ */
+export function recordTurnEndOutcome(cwd, outcome) {
+    try {
+        const now = new Date().toISOString();
+        const previous = readTurnEndStatus(cwd) ?? { ran: 0, skipped: 0 };
+        const next = outcome.ran
+            ? { ...previous, ran: previous.ran + 1, lastRunAt: now }
+            : {
+                ...previous,
+                skipped: previous.skipped + 1,
+                lastSkipReason: outcome.reason,
+                lastSkipAt: now,
+            };
+        writeFileAtomic(turnEndStatusPathForCwd(cwd), `${JSON.stringify(next)}\n`);
+    }
+    catch {
+        // telemetry only — a read-only tmpdir must not break the Stop hook
+    }
+}
 /**
  * Ask the warm server to analyze a file. Resolves the server's result, or
  * `undefined` on ANY failure (no server, refused, stale socket, timeout, bad
@@ -200,3 +301,35 @@ export function requestWarmAnalyze(cwd, file, timeoutMs = 30_000) {
         socket.on("close", () => finish(undefined));
     });
 }
+/**
+ * One-shot line reader for the warm IPC socket (#1219). The clients write
+ * exactly one newline-terminated request per connection and read one reply, so
+ * the server must dispatch at most one line and ignore anything after it — a
+ * `data` handler that keeps re-reading the same buffered line re-dispatches
+ * the request on stray bytes. Returns the handler to attach to the socket's
+ * `data` event.
+ */
+export function createWarmIpcLineReader(onLine) {
+    let buffer = "";
+    let dispatched = false;
+    return (chunk) => {
+        if (dispatched)
+            return;
+        buffer += chunk;
+        const newline = buffer.indexOf("\n");
+        if (newline === -1)
+            return;
+        dispatched = true;
+        onLine(buffer.slice(0, newline));
+    };
+}
+export function createWarmIpcRequestQueue() {
+    let chain = Promise.resolve();
+    return {
+        enqueue(work) {
+            const next = chain.then(work);
+            chain = next.catch(() => undefined);
+            return next;
+        },
+    };
+}