@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/ndjson-logger.js

@@ -160,6 +160,41 @@ export function resetSinkWriteFailures() {
     for (const state of ndjsonGlobalState.writers.values())
         state.writeFailures = 0;
 }
+/**
+ * Snapshot of mid-session rotations, one entry per sink that has rotated
+ * at least once (#2505). Pure in-memory read — no I/O — so a caller
+ * (`degradation-ledger.ts`) can fold this into a durable ledger entry the
+ * same way it folds `getSinkWriteFailures()`, without this module importing
+ * the ledger back (see `NdjsonWriterState.rotationCount`'s doc comment).
+ */
+export function getSinkRotations() {
+    if (!ndjsonGlobalState)
+        return [];
+    const result = [];
+    for (const state of ndjsonGlobalState.writers.values()) {
+        if (state.rotationCount > 0 || state.rotationFailures > 0) {
+            result.push({
+                file: state.file,
+                rotationCount: state.rotationCount,
+                failureCount: state.rotationFailures,
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Session-boundary reset (catalog shape 17), same shape as
+ * `resetSinkWriteFailures`. Wired into `resetDegradationLedger()`.
+ */
+export function resetSinkRotations() {
+    if (!ndjsonGlobalState)
+        return;
+    for (const state of ndjsonGlobalState.writers.values()) {
+        state.rotationCount = 0;
+        state.rotationFailures = 0;
+        state.rotationRetryAfterMs = 0;
+    }
+}
 function requireCurrentGlobalState() {
     if (ndjsonGlobalState)
         return ndjsonGlobalState;
@@ -191,10 +226,14 @@ function assertCompatibleWriterOptions(existing, maxBytes, backupPath) {
 function writeQueueItemSync(state, item) {
     if (item.kind === "truncate") {
         fs.writeFileSync(state.file, "");
+        noteTruncated(state);
     }
     else {
-        rotateIfNeeded(state);
-        fs.appendFileSync(state.file, item.line);
+        // One line, so the batch cap has nothing to cap: the plan is only
+        // ever "rotate first if this line no longer fits".
+        const plan = planBoundedWrite(state, [item.line]);
+        fs.appendFileSync(state.file, plan.joined);
+        noteWriteSucceeded(state, plan.bytes);
     }
 }
 /**
@@ -269,6 +308,20 @@ function createWriterState(file, maxBytes, backupPath) {
         // A state adopted from a pre-#1970 module graph predates this field.
         if (typeof existing.writeFailures !== "number")
             existing.writeFailures = 0;
+        // A state adopted from a pre-#2505 module graph predates these fields.
+        // (`knownSize` itself needs no adoption shim: its type is
+        // `number | undefined`, so a value that is neither is unreachable —
+        // #2515 review S2.)
+        if (typeof existing.writesSinceStatSync !== "number")
+            existing.writesSinceStatSync = 0;
+        if (typeof existing.lastStatSyncMs !== "number")
+            existing.lastStatSyncMs = 0;
+        if (typeof existing.rotationCount !== "number")
+            existing.rotationCount = 0;
+        if (typeof existing.rotationFailures !== "number")
+            existing.rotationFailures = 0;
+        if (typeof existing.rotationRetryAfterMs !== "number")
+            existing.rotationRetryAfterMs = 0;
         return existing;
     }
     const state = {};
@@ -282,6 +335,12 @@ function createWriterState(file, maxBytes, backupPath) {
     state.ensuredDir = false;
     state.exitFlusher = () => flushStateSync(state);
     state.writeFailures = 0;
+    state.knownSize = undefined;
+    state.writesSinceStatSync = 0;
+    state.lastStatSyncMs = 0;
+    state.rotationCount = 0;
+    state.rotationFailures = 0;
+    state.rotationRetryAfterMs = 0;
     globalState.writers.set(file, state);
     registerWriter(state);
     return state;
@@ -305,32 +364,191 @@ async function ensureDirAsync(state) {
         // telemetry is best-effort
     }
 }
-function rotateIfNeeded(state) {
-    if (state.maxBytes === undefined)
+// Rotation-check cadence (#2505): the real `fs.statSync` reconciliation below
+// is throttled to at most once per this many writes OR this many elapsed ms,
+// whichever comes first — never once per individual write. Between
+// reconciliations, `state.knownSize` (updated cheaply, no I/O, after every
+// successful write) is trusted. A short window in both axes bounds how far a
+// concurrent writer to the same global log (another pi-lens process sharing
+// ~/.pi-lens) can drift `knownSize` from the real file before the next
+// reconciliation self-heals it.
+const ROTATION_STAT_RESYNC_WRITES = 25;
+const ROTATION_STAT_RESYNC_MS = 2_000;
+/** Reconcile `state.knownSize` with a real stat, gated by the cadence above. */
+function syncKnownSizeIfDue(state, now) {
+    const due = state.knownSize === undefined ||
+        state.writesSinceStatSync >= ROTATION_STAT_RESYNC_WRITES ||
+        now - state.lastStatSyncMs >= ROTATION_STAT_RESYNC_MS;
+    if (!due)
         return;
+    state.writesSinceStatSync = 0;
+    state.lastStatSyncMs = now;
+    try {
+        state.knownSize = fs.statSync(state.file).size;
+    }
+    catch {
+        // No file yet (first write) or a transient stat error — treat as
+        // empty; the next successful write/rotate re-establishes the truth.
+        state.knownSize = 0;
+    }
+}
+/**
+ * A rotation attempt that FAILS (an unwritable backup path, or the Windows
+ * sharing violation another process holding the file open produces) must not
+ * be re-attempted by every subsequent write: that is a syscall storm that
+ * never succeeds. After a failure the next attempt is deferred by this many
+ * ms. The sink keeps writing during the window — dropping lines would be a
+ * worse trade than an oversized file — and the failure is reported through
+ * `getSinkRotations()` as `log-sink-rotate-failed`, so an unbounded log is
+ * visible in `pilens_health` instead of silent (#2505 review F2).
+ */
+const ROTATION_FAILURE_BACKOFF_MS = 10_000;
+/**
+ * Move the active file aside, and report whether that actually happened.
+ *
+ * The in-memory size check that gets us here is deliberately cheap and
+ * therefore fallible: another process writing the SAME global log (a pi
+ * session and the warm MCP server share one global read-guard.log) moves the
+ * real file under us, so a cached size can be stale in either direction.
+ * Believing a stale-HIGH size is destructive, not merely wasteful — it
+ * force-removes the other process backup and renames that process freshly
+ * rotated (tiny) file on top of it, losing real log data. So the decision is
+ * CONFIRMED against a real stat here, on the rare path where a rotation is
+ * believed due, instead of on the hot path where every write would pay for
+ * it (#2505 review F4).
+ */
+function rotateNow(state, incomingBytes, now) {
+    if (state.maxBytes === undefined)
+        return false;
+    if (now < state.rotationRetryAfterMs)
+        return false;
+    let actualSize;
+    try {
+        actualSize = fs.statSync(state.file).size;
+    }
+    catch {
+        // No file yet — nothing to rotate, and the next write creates it.
+        state.knownSize = 0;
+        state.writesSinceStatSync = 0;
+        state.lastStatSyncMs = now;
+        return false;
+    }
+    state.knownSize = actualSize;
+    state.writesSinceStatSync = 0;
+    state.lastStatSyncMs = now;
+    // The real file disagrees with the cached belief: nothing to do. This is
+    // the cross-process case above, and declining here is exactly what
+    // preserves the other process backup.
+    if (actualSize === 0)
+        return false;
+    if (actualSize + incomingBytes < state.maxBytes)
+        return false;
+    const backup = state.backupPath ?? `${state.file}.1`;
     try {
-        const size = fs.statSync(state.file).size;
-        if (size < state.maxBytes)
-            return;
-        const backup = state.backupPath ?? `${state.file}.1`;
         runBestEffort(() => fs.rmSync(backup, { force: true }));
         fs.renameSync(state.file, backup);
     }
     catch {
-        // no file yet, or rename raced — nothing to rotate
+        // The rename failed and the file is still there at `actualSize` (which
+        // `knownSize` now holds — no guessing, the stat above just confirmed
+        // it). Counted rather than swallowed so `log-sink-rotate-failed` can
+        // surface an unbounded sink, and backed off so the next write does not
+        // re-run the same failing syscall.
+        state.rotationFailures += 1;
+        state.rotationRetryAfterMs = now + ROTATION_FAILURE_BACKOFF_MS;
+        return false;
     }
+    state.knownSize = 0;
+    state.rotationCount += 1;
+    state.rotationRetryAfterMs = 0;
+    return true;
+}
+function takeAll(lines) {
+    const joined = lines.join("");
+    return { count: lines.length, joined, bytes: Buffer.byteLength(joined) };
+}
+/**
+ * Decide what this append writes, rotating first when the file already on
+ * disk leaves no room. Two things have to hold, and the pre-#2505 write path
+ * did neither:
+ *
+ *  1. The bound is checked against the size this write PRODUCES, not only
+ *     the size already on disk — otherwise the write that crosses the bound
+ *     is always allowed through and only the NEXT one rotates (one write
+ *     late), which on a long-lived or idle-tailed session (the warm MCP
+ *     server never re-runs the session-start sweep in `log-cleanup.ts`) may
+ *     be a long time or never.
+ *  2. The batch ITSELF is capped at the bound. Rotation only ever moves
+ *     PRE-EXISTING content aside, so an oversized batch written whole into
+ *     an empty (or just-rotated) file lands past the bound with nothing left
+ *     to rotate away: a 500-line drain against a 1KB bound landed at ~107KB,
+ *     106x over, with zero rotations. Capping makes the drain loop come back
+ *     around for the remainder instead.
+ *
+ * A single NDJSON line is atomic and cannot be split, so at least one line
+ * is always taken: the enforced invariant is "the bound plus at most one
+ * line", never "the bound plus an unbounded batch".
+ */
+function planBoundedWrite(state, lines) {
+    if (state.maxBytes === undefined || lines.length === 0)
+        return takeAll(lines);
+    const now = Date.now();
+    syncKnownSizeIfDue(state, now);
+    state.writesSinceStatSync += 1;
+    const firstBytes = Buffer.byteLength(lines[0] ?? "");
+    let known = state.knownSize ?? 0;
+    if (known > 0 && known + firstBytes >= state.maxBytes) {
+        rotateNow(state, firstBytes, now);
+        known = state.knownSize ?? 0;
+        if (known > 0 && known + firstBytes >= state.maxBytes) {
+            // Rotation is unavailable (a failing rename, or its backoff window).
+            // Capping cannot bound a file that cannot be rotated — it would only
+            // shred each drain into one append per line for the rest of the
+            // window. Write the whole batch; the reason the bound is not holding
+            // is reported through `log-sink-rotate-failed`.
+            return takeAll(lines);
+        }
+    }
+    let bytes = 0;
+    let count = 0;
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line);
+        if (count > 0 && known + bytes + lineBytes >= state.maxBytes)
+            break;
+        bytes += lineBytes;
+        count += 1;
+    }
+    if (count === lines.length)
+        return takeAll(lines);
+    return { count, joined: lines.slice(0, count).join(""), bytes };
+}
+/** Cheap in-memory bookkeeping after a write actually lands (#2505). */
+function noteWriteSucceeded(state, bytes) {
+    if (state.maxBytes === undefined)
+        return;
+    state.knownSize = (state.knownSize ?? 0) + bytes;
+}
+/** The file is now definitively empty — no guessing needed (#2505). */
+function noteTruncated(state) {
+    if (state.maxBytes === undefined)
+        return;
+    state.knownSize = 0;
+    state.writesSinceStatSync = 0;
+    state.lastStatSyncMs = Date.now();
 }
 async function writeQueueItemAsync(state, item) {
     if (item.kind === "truncate") {
         await fs.promises.writeFile(state.file, "");
+        noteTruncated(state);
     }
     else {
         // Rotation is deliberately synchronous here. This function is only
         // reached from the already-deferred drain, and keeping stat/rm/rename
         // in one synchronous section prevents flushSync from racing a late
         // async rename after it has written new data.
-        rotateIfNeeded(state);
-        await fs.promises.appendFile(state.file, item.line);
+        const plan = planBoundedWrite(state, [item.line]);
+        await fs.promises.appendFile(state.file, plan.joined);
+        noteWriteSucceeded(state, plan.bytes);
     }
 }
 /** See `applyQueueItemSync`'s doc comment for the reopen-and-retry-once shape. */
@@ -363,20 +581,29 @@ async function drainLoop(state) {
             ? state.queue.findIndex((queued) => queued.kind === "truncate")
             : 0;
         const pendingEnd = truncateIndex === -1 ? state.queue.length : truncateIndex;
-        const pending = item.kind === "truncate" ? [item] : state.queue.slice(0, pendingEnd);
+        const offered = item.kind === "truncate" ? [item] : state.queue.slice(0, pendingEnd);
+        // Rotation and the batch cap are decided synchronously, BEFORE this
+        // batch is published as in-flight: rotation stays inside the already-
+        // deferred drain (only the append remains async), so no awaited
+        // rotation step can run after flushSync has written to the active file.
+        const plan = item.kind === "truncate"
+            ? null
+            : planBoundedWrite(state, offered.map((queued) => queued.line));
+        // Only the lines the plan actually takes belong to THIS write. A batch
+        // that would itself cross `maxBytes` is cut at the bound and the loop
+        // comes back around for the remainder (#2505) — writing it whole would
+        // sail past a bound that rotation cannot recover, because rotation only
+        // moves pre-existing content aside.
+        const pending = plan === null ? offered : offered.slice(0, plan.count);
         state.inFlightBatch = pending;
         const writeBatch = async () => {
-            if (item.kind === "truncate") {
+            if (plan === null) {
                 await fs.promises.writeFile(state.file, "");
+                noteTruncated(state);
             }
             else {
-                // Rotation is kept synchronous inside the deferred drain. The
-                // append remains async, but no awaited rotation step can run after
-                // flushSync has written to the active file.
-                rotateIfNeeded(state);
-                await fs.promises.appendFile(state.file, pending
-                    .map((queued) => queued.line)
-                    .join(""));
+                await fs.promises.appendFile(state.file, plan.joined);
+                noteWriteSucceeded(state, plan.bytes);
             }
         };
         try {

package/node_modules/pi-lens/dist/clients/observed-mutation-sources.js

@@ -0,0 +1,101 @@
+/**
+ * What pi-lens ALREADY tracks, and where an observed change is replayed to
+ * (#2430).
+ *
+ * The observational net has to answer one question in three places — the
+ * `tool_call` pre-snapshot, the `tool_result` diff, and the `agent_settled`
+ * sweep — and the answer must be the same set every time, or a file drifts in
+ * and out of coverage depending on which seam asked. This module is that single
+ * source: the read-guard's read/write set, the widget's diagnostic files, and
+ * the documents open on any live language server rooted at the workspace.
+ *
+ * There is deliberately NO workspace walk here. The whole point of #2430 item 3
+ * is that the turn-boundary net costs a bounded number of stats over files
+ * pi-lens has already seen; a walk would make the settle boundary pay for the
+ * project's size on every run.
+ *
+ * The replay recorder is the mutation bridge. Nothing in this module writes
+ * bookkeeping itself: an observed change goes through exactly the seam an
+ * in-process producer uses, so the read-guard stamp, the `turn-state.json`
+ * entry, the attributed change-log receipt and the deferred format at
+ * `agent_settled` are the SAME code path a `write` takes.
+ */
+import { getLSPService } from "./lsp/index.js";
+import { getMutationBridge } from "./mutation-bridge.js";
+import { getFileDiagnosticSummaries } from "./widget-state.js";
+/**
+ * Files pi-lens has read, written, diagnosed, or opened on a language server.
+ *
+ * Order is deliberate and the cap is applied ACROSS the whole union: the
+ * read-guard set is the most direct evidence the agent is working on a file,
+ * so it is added first and a truncating cap never drops it in favour of a
+ * cascade neighbour some server happened to open.
+ */
+export function collectTrackedPaths(args) {
+    const tracked = new Set();
+    const add = (paths) => {
+        for (const filePath of paths) {
+            if (tracked.size >= args.limit)
+                return;
+            if (typeof filePath === "string" && filePath.length > 0)
+                tracked.add(filePath);
+        }
+    };
+    try {
+        add(args.readGuard?.getTrackedPaths?.() ?? []);
+    }
+    catch {
+        // A guard mid-eviction contributes nothing; the sweep stays advisory.
+    }
+    try {
+        add(getFileDiagnosticSummaries().map((summary) => summary.filePath));
+    }
+    catch {
+        // Widget state is display state; it must never break the net.
+    }
+    if (args.cwd) {
+        try {
+            add(getLSPService().getOpenDocumentPaths(args.cwd));
+        }
+        catch {
+            // No pool, or a client torn down mid-enumeration.
+        }
+    }
+    return [...tracked];
+}
+/**
+ * Read-guard stored per-line hashes for a file, newest record first.
+ *
+ * This is the "content diff against the read-guard's stored content" #2430
+ * asks for: #505 already keeps an FNV-1a hash per line for every read, so a
+ * post-mutation re-hash names exactly the lines that changed without pi-lens
+ * having to have kept the bytes.
+ */
+export function storedLineHashesFor(readGuard, filePath) {
+    try {
+        const history = readGuard?.getReadHistory?.(filePath) ?? [];
+        for (let index = history.length - 1; index >= 0; index -= 1) {
+            const hashes = history[index]?.lineHashes;
+            if (hashes && Object.keys(hashes).length > 0)
+                return hashes;
+        }
+    }
+    catch {
+        // No history is the same answer as no hashes: derive no ranges.
+    }
+    return undefined;
+}
+/**
+ * Replay an observed change through the mutation bridge.
+ *
+ * Returns `false` when the bridge is not mounted (pi-lens not activated, or a
+ * unit test that never registered one) or when the bridge itself declined the
+ * entry — out of scope, ignored, or a bookkeeping failure. A `false` is a real
+ * answer the caller acts on: it does NOT count as evidence the tool was clean.
+ */
+export function replayThroughMutationBridge(entry) {
+    const bridge = getMutationBridge();
+    if (!bridge)
+        return false;
+    return bridge.recordMutation(entry);
+}