@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

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

@@ -5,7 +5,7 @@
  * doesn't — session-start warms the dominant-language LSP (so warm `analyze` is
  * LSP-complete), establishes the error-debt baseline + complexity baselines, and
  * kicks off knip/jscpd/type-coverage/dep/secrets scans; turn-end runs
- * knip/jscpd incrementally, dep-circular, tests, cascade, and the
+ * knip incrementally, dep-circular, tests, cascade, and the
  * actionable/code-quality aggregation.
  *
  * The handlers don't return findings — they emit them through the same
@@ -16,33 +16,47 @@
  * persistent RuntimeCoordinator + CacheManager (so baselines/turn-state survive
  * across calls, like a real session), and the bootstrap client bundle.
  */
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { AstGrepClient } from "../ast-grep-client.js";
 import { loadBootstrapClients } from "../bootstrap.js";
-import { CacheManager } from "../cache-manager.js";
+import { CacheManager, MCP_TURN_STATE_OWNER_ID, } from "../cache-manager.js";
 import { resetDispatchBaselines } from "../dispatch/integration.js";
 import { resetFormatService } from "../format-service.js";
 import { getLSPService, resetLSPService } from "../lsp/index.js";
-import { consumeSessionStartGuidance, consumeTestFindings, consumeTurnEndFindings, } from "../runtime-context.js";
+import { acknowledgeTestFindings, acknowledgeTurnEndFindings, consumeSessionStartGuidance, consumeTestFindings, consumeTurnEndFindings, peekTestFindings, peekTurnEndFindings, } from "../runtime-context.js";
 import { RuntimeCoordinator } from "../runtime-coordinator.js";
 import { handleSessionStart } from "../runtime-session.js";
 import { handleTurnEnd } from "../runtime-turn.js";
 import { createMcpHost } from "./host-shim.js";
 let contextPromise;
+let resolvedRuntime;
 /** Lazily build (once) the persistent session context shared across MCP calls. */
 export function getMcpSessionContext() {
-    contextPromise ??= (async () => ({
-        runtime: new RuntimeCoordinator(),
-        cacheManager: new CacheManager(),
-        astGrepClient: new AstGrepClient(),
-        clients: await loadBootstrapClients(),
-    }))();
+    contextPromise ??= (async () => {
+        const context = {
+            runtime: new RuntimeCoordinator(),
+            cacheManager: new CacheManager(),
+            astGrepClient: new AstGrepClient(),
+            clients: await loadBootstrapClients(),
+        };
+        resolvedRuntime = context.runtime;
+        return context;
+    })();
     return contextPromise;
 }
+/** Synchronous peek at the session runtime, for construction sites that cannot
+ * await (e.g. the MCP server's tool wiring). Returns undefined until a session
+ * context has actually been built — advisory validation then honestly skips
+ * the session-identity check instead of comparing against a phantom session. */
+export function peekMcpSessionRuntime() {
+    return resolvedRuntime;
+}
 /** Test hook — drop the cached context so a fresh one is built next call. */
 export function _resetMcpSessionContext() {
     contextPromise = undefined;
+    resolvedRuntime = undefined;
 }
 const noop = () => { };
 function joinMessages(consumed) {
@@ -105,12 +119,82 @@ export async function runSessionStart(cwd) {
         aliveLspClients: getLSPService().getAliveClientCount(),
     };
 }
+/**
+ * #1274: the delivery map used to be unbounded — every timed-out client and
+ * every distinct raw-cwd alias left an entry for the life of the process.
+ * Both bounds drop entries WITHOUT committing, which re-arms the findings in
+ * the cache: the safe direction, since an un-consumed finding is re-reported on
+ * a later Stop while a wrongly-consumed one is gone for good. The TTL is
+ * generous next to Claude Code's 60 s hook budget — it exists to bound the map,
+ * not to police clients.
+ */
+const TURN_END_DELIVERY_TTL_MS = 10 * 60_000;
+const TURN_END_DELIVERY_MAX = 8;
+const TURN_END_QUEUE_WAIT_MS = 5_000;
+/**
+ * A bounded, cancellable serial queue. A turn_end mutates shared runtime and
+ * cache state, so concurrent passes are unsafe; a disconnected/hung pass must
+ * nevertheless not accumulate an unbounded tail of Stop requests.
+ */
+class TurnEndQueue {
+    running = false;
+    pending = [];
+    enqueue(work, waitMs = TURN_END_QUEUE_WAIT_MS) {
+        if (this.pending.length >= 1) {
+            return Promise.reject(new Error("turn_end queue is busy"));
+        }
+        return new Promise((resolve, reject) => {
+            const item = {
+                work,
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    const index = this.pending.indexOf(item);
+                    if (index === -1)
+                        return;
+                    this.pending.splice(index, 1);
+                    reject(new Error("turn_end queue wait timed out"));
+                }, waitMs),
+            };
+            item.timer.unref();
+            this.pending.push(item);
+            this.drain();
+        });
+    }
+    drain() {
+        if (this.running)
+            return;
+        const item = this.pending.shift();
+        if (!item)
+            return;
+        clearTimeout(item.timer);
+        this.running = true;
+        void item
+            .work()
+            .then(item.resolve, item.reject)
+            .finally(() => {
+            this.running = false;
+            this.drain();
+        });
+    }
+    reset() {
+        for (const item of this.pending.splice(0)) {
+            clearTimeout(item.timer);
+            item.reject(new Error("turn_end queue reset"));
+        }
+        this.running = false;
+    }
+}
+const turnEndQueue = new TurnEndQueue();
+const pendingTurnEndDeliveries = new Map();
+/** In-flight Stop-hook passes, keyed by cwd — see `runTurnEndForIpc` (#1274). */
+const inFlightIpcTurnEnds = new Map();
 /**
  * Run pi-lens's real turn_end over the files edited this "turn". The handler
  * reads edited files from turn-state, so we register the caller-supplied files
  * first (a full-file range, importsChanged=true so dep/knip re-check broadly).
  */
-export async function runTurnEnd(cwd, files = []) {
+async function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
     const ctx = await getMcpSessionContext();
     const host = createMcpHost(undefined, cwd);
     let registered = 0;
@@ -123,9 +207,15 @@ export async function runTurnEnd(cwd, files = []) {
         catch {
             continue; // unreadable / deleted — skip
         }
-        ctx.cacheManager.addModifiedRange(abs, { start: 1, end: lineCount }, true, cwd, ctx.runtime.telemetrySessionId);
+        ctx.cacheManager.addModifiedRange(abs, { start: 1, end: lineCount }, true, cwd, MCP_TURN_STATE_OWNER_ID, "mcp");
         registered++;
     }
+    const owner = {
+        kind: "mcp",
+        id: MCP_TURN_STATE_OWNER_ID,
+        pid: process.pid,
+        lastSeen: new Date().toISOString(),
+    };
     await handleTurnEnd({
         ctxCwd: cwd,
         getFlag: host.getFlag,
@@ -136,12 +226,143 @@ export async function runTurnEnd(cwd, files = []) {
         deadCodeClients: ctx.clients.deadCodeClients,
         depChecker: ctx.clients.depChecker,
         testRunnerClient: ctx.clients.testRunnerClient,
+        owner,
         resetLSPService,
         resetFormatService,
     });
+    const outcome = deferredDelivery
+        ? {
+            turnEnd: joinMessages(peekTurnEndFindings(ctx.cacheManager, cwd, ctx.runtime, true)),
+            tests: joinMessages(peekTestFindings(ctx.cacheManager, cwd, ctx.runtime, true)),
+            filesRegistered: registered,
+        }
+        : {
+            turnEnd: joinMessages(consumeTurnEndFindings(ctx.cacheManager, cwd, ctx.runtime)),
+            tests: joinMessages(consumeTestFindings(ctx.cacheManager, cwd, ctx.runtime)),
+            filesRegistered: registered,
+        };
     return {
-        turnEnd: joinMessages(consumeTurnEndFindings(ctx.cacheManager, cwd)),
-        tests: joinMessages(consumeTestFindings(ctx.cacheManager, cwd)),
-        filesRegistered: registered,
+        outcome,
+        commit: () => {
+            if (!deferredDelivery)
+                return;
+            acknowledgeTurnEndFindings(ctx.cacheManager, cwd);
+            acknowledgeTestFindings(ctx.cacheManager, cwd);
+        },
     };
 }
+/**
+ * Run a normal MCP turn_end. Its caller owns the tool response, so the
+ * historical consume-on-return behavior remains unchanged.
+ */
+export function runTurnEnd(cwd, files = []) {
+    return turnEndQueue.enqueue(async () => (await runTurnEndNow(cwd, files)).outcome);
+}
+/** A result with no findings needs no durable delivery transaction. */
+function hasTurnEndFindings(outcome) {
+    return Boolean(outcome.turnEnd || outcome.tests);
+}
+/** Drop expired deliveries, then the oldest ones over the cap. Never commits. */
+function prunePendingTurnEndDeliveries(now = Date.now()) {
+    for (const [deliveryId, delivery] of pendingTurnEndDeliveries) {
+        if (now - delivery.createdAt >= TURN_END_DELIVERY_TTL_MS) {
+            pendingTurnEndDeliveries.delete(deliveryId);
+        }
+    }
+    // Map iteration is insertion-ordered, so the head is the oldest entry.
+    while (pendingTurnEndDeliveries.size > TURN_END_DELIVERY_MAX) {
+        const oldest = pendingTurnEndDeliveries.keys().next();
+        if (oldest.done)
+            break;
+        pendingTurnEndDeliveries.delete(oldest.value);
+    }
+}
+function pendingForCwd(cwd) {
+    for (const [deliveryId, delivery] of pendingTurnEndDeliveries) {
+        if (delivery.cwd === cwd)
+            return [deliveryId, delivery];
+    }
+    return undefined;
+}
+/**
+ * Run the Stop-hook pass as a durable delivery transaction. The result is
+ * acknowledged through a separate one-shot IPC request. Until that request
+ * arrives, the findings cache is deliberately left unconsumed; a client
+ * timeout, socket close, or server restart therefore leaves the result for a
+ * later Stop request instead of losing it between execution and reply.
+ */
+export function runTurnEndForIpc(cwd) {
+    // #1274: the Stop-hook request carries no files and no sessionId, so two
+    // overlapping ones are byte-identical and a second pass would be pure waste
+    // — worse, the queue only holds ONE waiter, so a third Stop is rejected
+    // outright. Identical in-flight requests share the one pass and one
+    // deliveryId; the ack is idempotent-by-capability, so the loser of the race
+    // simply finds the delivery already committed.
+    const inFlight = inFlightIpcTurnEnds.get(cwd);
+    if (inFlight)
+        return inFlight;
+    const run = runTurnEndForIpcNow(cwd).finally(() => {
+        inFlightIpcTurnEnds.delete(cwd);
+    });
+    inFlightIpcTurnEnds.set(cwd, run);
+    return run;
+}
+function runTurnEndForIpcNow(cwd) {
+    return turnEndQueue.enqueue(async () => {
+        prunePendingTurnEndDeliveries();
+        const pending = pendingForCwd(cwd);
+        if (pending) {
+            return {
+                outcome: pending[1].transaction.outcome,
+                deliveryId: pending[0],
+            };
+        }
+        const ctx = await getMcpSessionContext();
+        const cachedOutcome = {
+            turnEnd: joinMessages(peekTurnEndFindings(ctx.cacheManager, cwd, ctx.runtime, true)),
+            tests: joinMessages(peekTestFindings(ctx.cacheManager, cwd, ctx.runtime, true)),
+            filesRegistered: 0,
+        };
+        const transaction = hasTurnEndFindings(cachedOutcome)
+            ? {
+                outcome: cachedOutcome,
+                commit: () => {
+                    acknowledgeTurnEndFindings(ctx.cacheManager, cwd);
+                    acknowledgeTestFindings(ctx.cacheManager, cwd);
+                },
+            }
+            : await runTurnEndNow(cwd, [], true);
+        if (!hasTurnEndFindings(transaction.outcome)) {
+            return { outcome: transaction.outcome };
+        }
+        const deliveryId = crypto.randomUUID();
+        pendingTurnEndDeliveries.set(deliveryId, {
+            cwd,
+            transaction,
+            createdAt: Date.now(),
+        });
+        prunePendingTurnEndDeliveries();
+        return { outcome: transaction.outcome, deliveryId };
+    });
+}
+/** Commit exactly one admitted delivery capability. */
+export function acknowledgeTurnEnd(cwd, deliveryId) {
+    prunePendingTurnEndDeliveries();
+    const delivery = pendingTurnEndDeliveries.get(deliveryId);
+    if (!delivery || delivery.cwd !== cwd)
+        return false;
+    // #1274: commit BEFORE dropping the capability. Deleting first meant a
+    // throwing consume destroyed the only handle to the findings — precisely the
+    // loss this two-phase protocol exists to prevent, reintroduced on the error
+    // path. Leaving the entry in place on a throw keeps the delivery re-fetchable
+    // by a later Stop.
+    delivery.transaction.commit();
+    pendingTurnEndDeliveries.delete(deliveryId);
+    return true;
+}
+/** Test hook — drop pending requests so one failed test cannot wedge the rest. */
+export function _resetTurnEndChain() {
+    turnEndQueue.reset();
+    pendingTurnEndDeliveries.clear();
+    inFlightIpcTurnEnds.clear();
+}

package/node_modules/pi-lens/dist/clients/memory-sampler.js

@@ -0,0 +1,115 @@
+/**
+ * Periodic memory-attribution sample (#1123 item 2, expanded on top of item 1's
+ * loop_block windowing — the #1126 sizing study's "instrumentation the next
+ * report should add" list is this module's requirements).
+ *
+ * The #1126 sizing study diagnosed a 1.37 GB instance from code + serialized
+ * artifacts alone, because nothing recorded a per-subsystem trajectory over
+ * time — the same detection-without-attribution gap loop_block had before
+ * #1122/#1125. This module answers "what is resident right now, broken down
+ * by subsystem" as a single ndjson `memory_sample` `latency.log` line, emitted
+ * every `MEMORY_SAMPLE_TURN_INTERVAL` turns (cheap enough not to need finer
+ * throttling).
+ *
+ * HARD CONSTRAINT: every field here is an O(1) `Map`/array `.size`/`.length`
+ * read, or a `process.memoryUsage()` call — nothing here iterates a large
+ * structure's contents, and nothing takes a heap snapshot. `PI_LENS_DEBUG_HEAP`
+ * (item 4's memory sibling) is a SEPARATE, explicitly opt-in mechanism, out of
+ * scope here.
+ *
+ * WASM linear-memory byte length gap (documented, not silently dropped): the
+ * #1126 spec asked for `Module.wasmMemory.buffer.byteLength` off the
+ * web-tree-sitter parser runtime. Inspecting the installed web-tree-sitter
+ * 0.25.10 package (see `clients/tree-sitter-client.ts#getRuntimeStats`'s
+ * docstring) confirmed that value is not reachable through any public export
+ * — only through package-internal reflection or by overriding Emscripten's
+ * `wasmMemory` module option with a hand-built `WebAssembly.Memory` (a
+ * stability risk for an observability-only feature, given a memory-import
+ * mismatch would break structural analysis entirely). `process.memoryUsage()`
+ * `arrayBuffers` is used as the process-wide proxy instead — WASM linear
+ * memory backs an ArrayBuffer, so it is already included there.
+ */
+import { getSharedTreeSitterClient } from "./tree-sitter-shared.js";
+import { getReviewGraphWorkspaceCacheSnapshot } from "./review-graph/builder.js";
+import { getDispatchCascadeCacheStats } from "./dispatch/integration.js";
+/** Every N turns, emit one `memory_sample` latency.log line (#1123 item 2). */
+export const MEMORY_SAMPLE_TURN_INTERVAL = 10;
+/** True on turn 10, 20, 30, ... — never on turn 0 (nothing meaningful is
+ *  resident yet at session start). Pure so the cadence is unit-testable
+ *  without driving a real turn loop. */
+export function shouldEmitMemorySample(turnIndex) {
+    return turnIndex > 0 && turnIndex % MEMORY_SAMPLE_TURN_INTERVAL === 0;
+}
+/** PURE: reshape Node's `process.memoryUsage()` into this module's field
+ *  names — testable without touching the real process. */
+export function toMemoryProcessUsage(mem) {
+    return {
+        rssBytes: mem.rss,
+        heapUsedBytes: mem.heapUsed,
+        heapTotalBytes: mem.heapTotal,
+        externalBytes: mem.external,
+        arrayBuffersBytes: mem.arrayBuffers,
+    };
+}
+/**
+ * Live O(1)/O(bounded-cache-size) subsystem counters. Impure (reads
+ * process-global singletons) but every individual read is a `.size`/`.length`
+ * access — see the module docstring's hard constraint.
+ */
+export function collectMemorySampleSubsystems(wordIndex) {
+    const reviewGraph = getReviewGraphWorkspaceCacheSnapshot();
+    const treeSitterClient = getSharedTreeSitterClient();
+    const treeSitter = treeSitterClient
+        ? (() => {
+            const runtimeStats = treeSitterClient.getRuntimeStats();
+            const cacheStats = treeSitterClient.getParseCacheStats();
+            return {
+                ...runtimeStats,
+                treeCacheSize: cacheStats.size,
+                treeCacheMaxSize: cacheStats.maxSize,
+                treeCacheTotalBytes: cacheStats.totalBytes,
+            };
+        })()
+        : null;
+    const dispatchCaches = getDispatchCascadeCacheStats();
+    return {
+        reviewGraph,
+        wordIndex: wordIndex
+            ? {
+                docs: wordIndex.docLengths.size,
+                postings: wordIndex.postings.size,
+                forwardEntries: wordIndex.forward?.size ?? 0,
+            }
+            : null,
+        treeSitter,
+        dispatchCaches,
+    };
+}
+/** Assemble one full sample. `mem` is injectable for tests; defaults to a
+ *  live `process.memoryUsage()` read. */
+export function buildMemorySample(wordIndex, mem = process.memoryUsage()) {
+    return {
+        process: toMemoryProcessUsage(mem),
+        subsystems: collectMemorySampleSubsystems(wordIndex),
+    };
+}
+const toMb = (bytes) => Math.round(bytes / (1024 * 1024));
+/**
+ * PURE: one compact `/lens-health` line reusing the same sample the periodic
+ * latency.log emitter builds — RSS + heap/external, plus the two subsystem
+ * numbers most useful for spotting an attribution outlier at a glance: the
+ * tree-sitter tree-cache byte total (the only subsystem counter here that is
+ * ALREADY in bytes, so it's directly comparable to RSS) and the review-graph
+ * node/edge counts (the multiple-graph-copies question #1126 called out).
+ * Follows #1125's health-line style (a single summary line, no per-subsystem
+ * breakdown table — that's what latency.log's `memory_sample` is for).
+ */
+export function formatMemoryHealthLine(sample) {
+    const { process: proc, subsystems } = sample;
+    const treeCache = subsystems.treeSitter
+        ? `${toMb(subsystems.treeSitter.treeCacheTotalBytes)}MB (${subsystems.treeSitter.treeCacheSize} trees)`
+        : "n/a";
+    const graph = `${subsystems.reviewGraph.totalNodes}n/${subsystems.reviewGraph.totalEdges}e (${subsystems.reviewGraph.cacheEntries} cwd)`;
+    return (`Memory: RSS ${toMb(proc.rssBytes)}MB · heap ${toMb(proc.heapUsedBytes)}/${toMb(proc.heapTotalBytes)}MB` +
+        ` · external ${toMb(proc.externalBytes)}MB · tree-sitter cache ${treeCache} · review-graph ${graph}`);
+}

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

@@ -10,6 +10,7 @@
  * These are observational metrics — they inform the human in session summary,
  * they don't gate or interrupt the agent mid-task.
  */
+import { createSubsystemLogger } from "./extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // --- Client ---
@@ -18,7 +19,7 @@ export class MetricsClient {
     fileBaselines = new Map();
     constructor(verbose = false) {
         this.log = verbose
-            ? (msg) => console.error(`[metrics] ${msg}`)
+            ? createSubsystemLogger("metrics")
             : () => { };
     }
     /**

package/node_modules/pi-lens/dist/clients/metrics-history.js

@@ -10,6 +10,7 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "./file-utils.js";
+import { writeFileAtomic } from "./atomic-write.js";
 // --- Constants ---
 const HISTORY_FILE = "metrics-history.json";
 const MAX_HISTORY_PER_FILE = 20;
@@ -82,7 +83,7 @@ export function saveHistory(history) {
     }
     history.capturedAt = new Date().toISOString();
     const historyPath = path.join(historyDir, "metrics-history.json");
-    fs.writeFileSync(historyPath, JSON.stringify(history, null, 2));
+    writeFileAtomic(historyPath, JSON.stringify(history, null, 2));
 }
 // In-memory cache to avoid loading/saving on every capture
 let pendingHistory = null;

package/node_modules/pi-lens/dist/clients/model-provider.js

@@ -0,0 +1,53 @@
+/**
+ * Provider derivation for worklog/disposition attribution (#1448).
+ *
+ * The host reports `provider` and `model` as separate fields on its telemetry
+ * events (see `updateRuntimeIdentityFromEvent` in index.ts and the
+ * `tool_result` handler in clients/runtime-tool-result.ts) MOST of the time —
+ * so the common case needs no parsing at all. This parser exists only for the
+ * fallback: a model id supplied without an explicit provider.
+ *
+ * Derivation rule (conservative — returns "" rather than guess):
+ *   1. A single `/` or `:` separator splits the id into `<provider>/<rest>`
+ *      or `<provider>:<rest>` — e.g. "anthropic/claude-sonnet-4-5",
+ *      "openai:gpt-5". The left segment is lowercased and returned AS-IS
+ *      (no allowlist check) since an explicit separator is deliberate host
+ *      structure, not a guess.
+ *   2. No separator: match a known model-id PREFIX against a small table of
+ *      vendor naming conventions (claude- -> anthropic; gpt-, o1-, o3- ->
+ *      openai; gemini- -> google; llama- -> meta; mistral-, mixtral- ->
+ *      mistral; command- -> cohere). First match wins.
+ *   3. Anything else (unrecognized prefix, multiple separators, empty
+ *      string) is ambiguous -> "".
+ */
+const KNOWN_PREFIXES = [
+    ["claude-", "anthropic"],
+    ["gpt-", "openai"],
+    ["o1-", "openai"],
+    ["o3-", "openai"],
+    ["gemini-", "google"],
+    ["llama-", "meta"],
+    ["mistral-", "mistral"],
+    ["mixtral-", "mistral"],
+    ["command-", "cohere"],
+];
+export function deriveProviderFromModelId(modelId) {
+    const id = modelId?.trim().toLowerCase();
+    if (!id)
+        return "";
+    const separators = [...id].filter((c) => c === "/" || c === ":").length;
+    if (separators === 1) {
+        const sep = id.includes("/") ? "/" : ":";
+        const [providerPart, ...rest] = id.split(sep);
+        if (providerPart && rest.join(sep).length > 0)
+            return providerPart;
+        return "";
+    }
+    if (separators > 1)
+        return "";
+    for (const [prefix, provider] of KNOWN_PREFIXES) {
+        if (id.startsWith(prefix))
+            return provider;
+    }
+    return "";
+}

package/node_modules/pi-lens/dist/clients/module-report-lsp.js

@@ -15,6 +15,11 @@
  *     remaining wall-clock budget.
  *   - OPT-IN: disabled by default (budget 0) until validated in a real pi session;
  *     enable with PI_LENS_MODULE_REPORT_LSP_BUDGET_MS.
+ *
+ * PARKED BY DECISION (#1090, 2026-08-12): zero live importers by design —
+ * efe3d2a5 unwired module_report's LSP path (#256) and re-homed live
+ * enrichment to #236 (LSP-confirmed graph edges). Kept for that future
+ * implementation; do not re-flag in dead-code sweeps while #236 is open.
  */
 import { withinRemaining } from "./deadline-utils.js";
 import { uriToPath } from "./path-utils.js";