@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/advisory-provenance.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { logLatency } from "./latency-logger.js";
 import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
 import { resolveRunnerPath } from "./dispatch/runner-context.js";
+import { MTIME_DRIFT_TOLERANCE_MS } from "./blocker-freshness.js";
 export const MAX_ADVISORY_AFFECTED_FILES = 256;
 export function advisoryPathKey(filePath, cwd) {
     return normalizeMapKey(path.resolve(cwd, filePath));
@@ -199,9 +200,34 @@ export function validateAdvisoryProvenance(record, cwd, runtime) {
 export const MAX_FINDING_PATH_STATS = MAX_ADVISORY_AFFECTED_FILES;
 /** How many dead paths a single drop record names before it stops. */
 const MAX_LOGGED_DEAD_PATHS = 3;
-export function findingPathExistence(resolvedPath) {
+/**
+ * One stat, one verdict. With `scannedAtMs` supplied, a surviving file whose
+ * mtime is newer than the scan reports `stale`.
+ *
+ * The boundary is `mtime > scannedAt + MTIME_DRIFT_TOLERANCE_MS`: a file
+ * scanned AT `scannedAt`, or written within the tolerance window of the scan
+ * timestamp being captured, reads live; genuinely past it reads stale.
+ *
+ * #1708: a bare +1ms tolerance — the convention `reconcileProjectDiagnosticsSnapshot`
+ * (clients/project-diagnostics/cache.ts:98) still uses, and the one this gate
+ * originally cited-but-withheld ("over-demoting costs a line number,
+ * under-demoting replays a false coordinate — the cheaper error wins the
+ * tie") — was not enough: on Windows a file's mtime can LEAD the immediately
+ * following `Date.now()` read by up to ~11.4ms, the same host skew
+ * `MTIME_DRIFT_TOLERANCE_MS` (`blocker-freshness.ts`) was raised to 50ms for
+ * (#1491/#1498). At +1ms this gate still demoted a real STOP-blocker (a
+ * trivy secret, #1628) to ACTION NEEDED, flaking
+ * tests/clients/runtime-turn-secrets-disposition.test.ts. Reusing the shared
+ * constant — rather than a second hand-tuned number — keeps one source of
+ * truth for the measured skew.
+ */
+export function findingPathFreshness(resolvedPath, scannedAtMs) {
     try {
-        fs.statSync(resolvedPath);
+        const stat = fs.statSync(resolvedPath);
+        if (scannedAtMs !== undefined &&
+            stat.mtimeMs > scannedAtMs + MTIME_DRIFT_TOLERANCE_MS) {
+            return "stale";
+        }
         return "live";
     }
     catch (error) {
@@ -211,14 +237,37 @@ export function findingPathExistence(resolvedPath) {
         return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "unknown";
     }
 }
+/** Existence-only probe. Retained for callers that have no scan timestamp. */
+export function findingPathExistence(resolvedPath) {
+    return findingPathFreshness(resolvedPath);
+}
+/**
+ * Parse a scan timestamp into epoch ms, or `undefined` when it cannot be
+ * trusted. `undefined` disables the staleness arm — never demote on a bad
+ * clock.
+ */
+export function parseScannedAtMs(scannedAt) {
+    if (scannedAt === undefined || scannedAt === null || scannedAt === "") {
+        return undefined;
+    }
+    const ms = typeof scannedAt === "number" ? scannedAt : Date.parse(scannedAt);
+    return Number.isFinite(ms) ? ms : undefined;
+}
 /**
- * Partition findings into `{live, dropped}` by whether the path each one names
- * still exists. Pure apart from the `fs.statSync` probe, which is injectable so
- * the partition rules are unit-testable without a filesystem.
+ * Partition findings into `{live, stale, dropped}` by what the path each one
+ * names looks like now. Pure apart from the `fs.statSync` probe, which is
+ * injectable so the partition rules are unit-testable without a filesystem.
+ *
+ * The stat memo lives in local `Map`s built fresh on every call — per delivery,
+ * never per process. A module-level cache here would be the process-lifetime
+ * latch shape: it would pin the first verdict for a path and re-serve it for
+ * every later turn, which is the very defect this gate exists to close.
  */
 export function partitionFindingsByCitedPath(args) {
     const limit = args.maxUniquePaths ?? MAX_FINDING_PATH_STATS;
-    const probe = args.existence ?? findingPathExistence;
+    const probe = args.existence ?? findingPathFreshness;
+    const scannedAtMs = parseScannedAtMs(args.scannedAt);
+    const onMissing = args.onMissing ?? "drop";
     // Two dedup layers, cheapest first. `rawVerdicts` collapses findings that
     // cite the IDENTICAL string with zero filesystem work — the dominant case
     // (#1460's live record: 126 findings over a handful of distinct `file`
@@ -232,8 +281,10 @@ export function partitionFindingsByCitedPath(args) {
     const rawVerdicts = new Map();
     const verdicts = new Map();
     const live = [];
+    const stale = [];
     const dropped = [];
     const deadPaths = [];
+    const stalePaths = [];
     let truncated = false;
     for (const finding of args.findings) {
         const cited = args.citedPath(finding);
@@ -261,20 +312,38 @@ export function partitionFindingsByCitedPath(args) {
                     verdict = "live";
                 }
                 else {
-                    verdict = probe(resolved);
+                    verdict = probe(resolved, scannedAtMs);
+                    // A store that treats deletion as evidence-loss rather than
+                    // remediation-loss folds `missing` into the demote arm here, so
+                    // every downstream list and record sees one consistent verdict.
+                    if (verdict === "missing" && onMissing === "demote") {
+                        verdict = "stale";
+                    }
                     verdicts.set(key, verdict);
                     if (verdict === "missing")
                         deadPaths.push(resolved);
+                    else if (verdict === "stale")
+                        stalePaths.push(resolved);
                 }
             }
             rawVerdicts.set(cited, verdict);
         }
         if (verdict === "missing")
             dropped.push(finding);
+        else if (verdict === "stale")
+            stale.push(finding);
         else
             live.push(finding);
     }
-    return { live, dropped, deadPaths, statCount: verdicts.size, truncated };
+    return {
+        live,
+        stale,
+        dropped,
+        deadPaths,
+        stalePaths,
+        statCount: verdicts.size,
+        truncated,
+    };
 }
 /**
  * Delivery-seam wrapper: partition, then emit one bounded `finding_dead_path_drop`
@@ -285,27 +354,71 @@ export function partitionFindingsByCitedPath(args) {
  * store per delivery, with a capped path sample; never one per finding.
  */
 export function dropFindingsForMissingPaths(args) {
+    // No `scannedAt` — existence-only, so `partition.stale` is always empty.
+    const partition = partitionFindingsByCitedPath(args);
+    emitDeadPathDropRecord(args.store, args.cwd, partition);
+    return partition.live;
+}
+/**
+ * Delivery-seam wrapper with the #1622 freshness verdict. Emits at most one
+ * `finding_dead_path_drop` and one `finding_stale_line_demote` record per store
+ * per delivery, each with a capped path sample; never one per finding.
+ *
+ * Callers that have no scan timestamp keep using `dropFindingsForMissingPaths`.
+ */
+export function gateFindingsByPathFreshness(args) {
     const partition = partitionFindingsByCitedPath(args);
+    emitDeadPathDropRecord(args.store, args.cwd, partition);
+    emitStaleLineDemoteRecord(args.store, args.cwd, args.scannedAt, partition);
+    return { live: partition.live, stale: partition.stale };
+}
+function emitDeadPathDropRecord(store, cwd, partition) {
     if (partition.dropped.length === 0)
-        return partition.live;
+        return;
     logLatency({
         type: "phase",
         phase: "finding_dead_path_drop",
-        filePath: args.cwd,
+        filePath: cwd,
         durationMs: 0,
         metadata: {
-            store: args.store,
+            store,
             droppedDeadPaths: partition.dropped.length,
             deadPathCount: partition.deadPaths.length,
             deliveredCount: partition.live.length,
             statCount: partition.statCount,
             samplePaths: partition.deadPaths
                 .slice(0, MAX_LOGGED_DEAD_PATHS)
-                .map((deadPath) => toProjectRelativePath(deadPath, args.cwd)),
+                .map((deadPath) => toProjectRelativePath(deadPath, cwd)),
+            ...(partition.truncated ? { truncated: true } : {}),
+        },
+    });
+}
+/**
+ * #1622 criterion 5: the demote path gets the same record shape as the drop
+ * path. Before this, a stale-line replay window was reconstructible only by
+ * proxy — the blocker payload is written nowhere.
+ */
+function emitStaleLineDemoteRecord(store, cwd, scannedAt, partition) {
+    if (partition.stale.length === 0)
+        return;
+    logLatency({
+        type: "phase",
+        phase: "finding_stale_line_demote",
+        filePath: cwd,
+        durationMs: 0,
+        metadata: {
+            store,
+            demotedStalePaths: partition.stale.length,
+            stalePathCount: partition.stalePaths.length,
+            deliveredCount: partition.live.length,
+            statCount: partition.statCount,
+            samplePaths: partition.stalePaths
+                .slice(0, MAX_LOGGED_DEAD_PATHS)
+                .map((stalePath) => toProjectRelativePath(stalePath, cwd)),
+            ...(scannedAt === undefined ? {} : { scannedAt: String(scannedAt) }),
             ...(partition.truncated ? { truncated: true } : {}),
         },
     });
-    return partition.live;
 }
 export function provenanceStamp(provenance) {
     if (!isWellFormed(provenance))

package/node_modules/pi-lens/dist/clients/agent-nudge.js

@@ -68,12 +68,17 @@ function recordTouchedEvent(payload, getReadGuard) {
             // recorded via the cross-process feed, now also reported by this
             // session's own bus, upgrades to "local".
             existing.origin = "local";
+            // #1464: a fresh touch invalidates any content already delivered for
+            // this path (the default deferred format at agent_end, a cascade
+            // autofix) — those bytes no longer describe the file.
+            existing.contentDelivered = false;
         }
         else {
             _touched.set(mapKey, {
                 displayPath: rawPath,
                 reasons: new Set([payload.reason]),
                 origin: "local",
+                contentDelivered: false,
             });
         }
     }
@@ -112,16 +117,47 @@ export function recordCrossProcessTouches(entries) {
             existing.reasons.add(entry.reason);
             // "local" is sticky (see AccumulatedFileOrigin) — never downgrade an
             // already-local entry back to cross-process.
+            // #1464: a foreign process touching this file invalidates whatever
+            // content this session's write path already delivered for it.
+            existing.contentDelivered = false;
         }
         else {
             _touched.set(mapKey, {
                 displayPath: entry.path,
                 reasons: new Set([entry.reason]),
                 origin: "cross-process",
+                contentDelivered: false,
             });
         }
     }
 }
+/**
+ * Record the write path's authoritative-content attachment outcome for one
+ * path (#1464).
+ *
+ * `attached` is the SAME boolean that drove the attachment in
+ * `handleToolResult` (clients/runtime-tool-result.ts) — this module never
+ * re-derives it from config, byte counts, or the aggregate budget. `true`
+ * means the post-fix bytes went out in the write's own tool result and the
+ * agent already holds them, so "re-read before editing" is noise. `false` is
+ * the size cap and the per-command aggregate budget degrading an attachment
+ * to a re-read warning: there the nudge is the whole signal, and calling this
+ * with `false` re-arms a path an earlier per-file decision had suppressed
+ * (the bash multi-file case, where the outer budget loop overrides the inner
+ * per-file "attached").
+ *
+ * Marks an EXISTING accumulator entry only. `publishFilesTouched` fires
+ * synchronously inside the `runPipeline` call this decision belongs to (pi's
+ * event bus is a plain `EventEmitter`), so the entry is already there for any
+ * path the relevance filter admitted; a path with no entry has nothing to
+ * suppress. Deferred-edit autofix at `agent_end` never reaches here — it
+ * attaches nothing, so it keeps nudging.
+ */
+export function noteAuthoritativeContentAttachment(filePath, attached) {
+    const entry = _touched.get(normalizeMapKey(filePath));
+    if (entry)
+        entry.contentDelivered = attached;
+}
 /**
  * Subscribe to `pilens:files:touched` on pi's shared event bus. Called once
  * at extension factory time from index.ts, mirroring `wireBusEmitter`'s
@@ -191,17 +227,29 @@ export function wireAgentNudgeSubscriber(args) {
  * very first call of a fresh `agent_start` — so the accumulator surviving
  * across run boundaries is exactly what makes that cross-run delivery work.
  * Empty accumulator ⇒ returns undefined ⇒ zero bytes injected.
+ *
+ * #1464: paths whose post-fix content the write path already attached to its
+ * OWN tool result are dropped from the batch here (see
+ * `noteAuthoritativeContentAttachment`) — the agent holds those bytes, so
+ * "re-read before editing" would spend context to re-fetch what it has. A
+ * batch that is ENTIRELY such paths injects nothing.
  */
 export function consumeAgentNudge(dbg) {
-    const entries = Array.from(_touched.values());
+    const drained = Array.from(_touched.values());
     _touched.clear();
     const filesFiltered = _relevanceFilteredCount;
     _relevanceFilteredCount = 0;
     if (!isAgentNudgeEnabled())
         return undefined;
-    if (entries.length === 0)
+    if (drained.length === 0)
         return undefined;
     try {
+        // #1464: a write whose post-fix bytes were attached to its own tool
+        // result already told the agent everything this nudge would. Drop those
+        // paths from the message but keep counting them, so over-suppression is
+        // visible in telemetry instead of only in the absence of complaints.
+        const entries = drained.filter((e) => !e.contentDelivered);
+        const filesContentDelivered = drained.length - entries.length;
         const filesTotal = entries.length;
         const shown = entries.slice(0, MAX_NAMES_SHOWN);
         const remaining = filesTotal - shown.length;
@@ -225,15 +273,6 @@ export function consumeAgentNudge(dbg) {
             : names.join(", ");
         const crossProcessCount = entries.filter((e) => e.origin === "cross-process").length;
         const localCount = filesTotal - crossProcessCount;
-        // Three-way attribution (see the function doc): never assign a local
-        // file to another instance — a mixed batch keeps the local base framing
-        // and calls out the cross-process portion by exact count.
-        const attribution = localCount === 0
-            ? "by an automatic run outside your turn"
-            : crossProcessCount === 0
-                ? "after your last turn"
-                : `after your last turn (${crossProcessCount} of them by an automatic run outside it)`;
-        const message = `pi-lens: ${filesTotal} file(s) were ${verbLabel} ${attribution}: ${nameList} — working-tree changes to these are expected; re-read before editing.`;
         logLatency({
             type: "phase",
             filePath: "<pi-lens>",
@@ -246,6 +285,10 @@ export function consumeAgentNudge(dbg) {
                 // never read/edited) — NOT the display overflow, which is
                 // filesTotal - filesShown.
                 filesFiltered,
+                // #1464: drops because the write's own tool result already carried
+                // the post-fix bytes. A third, distinct count: these paths passed
+                // the relevance filter and were accumulated, then suppressed here.
+                filesContentDelivered,
                 reasonMix: Array.from(allReasons),
                 // #492: origin mix so cross-process pickup rate is observable
                 // alongside the existing relevance-filter metric.
@@ -253,6 +296,19 @@ export function consumeAgentNudge(dbg) {
                 originCrossProcess: crossProcessCount,
             },
         });
+        // Everything drained was delivered in a write's own tool result — the
+        // row above records that it happened, and zero bytes get injected.
+        if (filesTotal === 0)
+            return undefined;
+        // Three-way attribution (see the function doc): never assign a local
+        // file to another instance — a mixed batch keeps the local base framing
+        // and calls out the cross-process portion by exact count.
+        const attribution = localCount === 0
+            ? "by an automatic run outside your turn"
+            : crossProcessCount === 0
+                ? "after your last turn"
+                : `after your last turn (${crossProcessCount} of them by an automatic run outside it)`;
+        const message = `pi-lens: ${filesTotal} file(s) were ${verbLabel} ${attribution}: ${nameList} — working-tree changes to these are expected; re-read before editing.`;
         return {
             messages: [
                 {

package/node_modules/pi-lens/dist/clients/ast-grep-client.js

@@ -176,9 +176,12 @@ export class AstGrepClient {
      * Each path is scanned independently; results are merged.
      */
     async tempScanDetailed(dir, ruleYaml, options = {}) {
-        // Keep tests and older embedders that replace the runner with the historic
-        // match-only seam working. The production SgRunner always has the detailed
-        // method, so failures cannot be mistaken for an empty result there.
+        // SAFETY: keep tests and older embedders that replace the runner with the
+        // historic match-only seam working. The cast only makes
+        // `tempScanDetailedAsync` OPTIONAL on the runner surface — it claims
+        // nothing about the method existing. The call site below checks for it
+        // before invoking, and the production SgRunner always has it, so a
+        // failure there cannot be mistaken for an empty result.
         const detailed = this.runner.tempScanDetailedAsync;
         if (detailed) {
             return detailed.call(this.runner, dir, "agent-rule", ruleYaml, 30_000, options);
@@ -568,12 +571,15 @@ message: found
             return "";
         const errors = diags.filter((d) => d.severity === "error");
         const warnings = diags.filter((d) => d.severity === "warning");
+        const infos = diags.filter((d) => d.severity === "info");
         const hints = diags.filter((d) => d.severity === "hint");
         let output = `[ast-grep] ${diags.length} structural issue(s)`;
         if (errors.length)
             output += ` — ${errors.length} error(s)`;
         if (warnings.length)
             output += ` — ${warnings.length} warning(s)`;
+        if (infos.length)
+            output += ` — ${infos.length} info(s)`;
         if (hints.length)
             output += ` — ${hints.length} hint(s)`;
         output += ":\n";

package/node_modules/pi-lens/dist/clients/atomic-write.js

@@ -38,7 +38,7 @@
  *     cycles still lose updates: each writer publishes the state it computed
  *     from the snapshot it read, and last-rename-wins silently discards the
  *     other's mutation. Callers needing this must serialize themselves (see
- *     `lspChildRemovalTail` in `instance-registry.ts`).
+ *     `registryChildMutationTail` in `instance-registry.ts`).
  *   - **No ordering.** Nothing sequences concurrent writers, within or across
  *     processes. The winner is whichever `rename` lands last, which is not
  *     necessarily the write that started or finished last.
@@ -143,7 +143,10 @@ export function writeFileAtomic(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
     const tmpPath = stagePathFor(targetPath);
     try {
-        fs.writeFileSync(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
+        fs.writeFileSync(tmpPath, data, {
+            encoding: typeof data === "string" ? "utf-8" : undefined,
+            mode: options?.mode,
+        });
         fs.renameSync(tmpPath, targetPath);
     }
     catch (err) {
@@ -167,7 +170,10 @@ export async function writeFileAtomicAsync(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
     const tmpPath = stagePathFor(targetPath);
     try {
-        await fs.promises.writeFile(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
+        await fs.promises.writeFile(tmpPath, data, {
+            encoding: typeof data === "string" ? "utf-8" : undefined,
+            mode: options?.mode,
+        });
         await fs.promises.rename(tmpPath, targetPath);
     }
     catch (err) {