@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

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;
+        },
+    };
+}

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,15 +16,16 @@
  * 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 { 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";
@@ -105,12 +106,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 +194,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 +213,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)),
+            tests: joinMessages(peekTestFindings(ctx.cacheManager, cwd)),
+            filesRegistered: registered,
+        }
+        : {
+            turnEnd: joinMessages(consumeTurnEndFindings(ctx.cacheManager, cwd)),
+            tests: joinMessages(consumeTestFindings(ctx.cacheManager, cwd)),
+            filesRegistered: registered,
+        };
     return {
-        turnEnd: joinMessages(consumeTurnEndFindings(ctx.cacheManager, cwd)),
-        tests: joinMessages(consumeTestFindings(ctx.cacheManager, cwd)),
-        filesRegistered: registered,
+        outcome,
+        commit: () => {
+            if (!deferredDelivery)
+                return;
+            consumeTurnEndFindings(ctx.cacheManager, cwd);
+            consumeTestFindings(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)),
+            tests: joinMessages(peekTestFindings(ctx.cacheManager, cwd)),
+            filesRegistered: 0,
+        };
+        const transaction = hasTurnEndFindings(cachedOutcome)
+            ? {
+                outcome: cachedOutcome,
+                commit: () => {
+                    consumeTurnEndFindings(ctx.cacheManager, cwd);
+                    consumeTestFindings(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;