@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/README.md

@@ -213,11 +213,19 @@ Thanks goes to these wonderful people:
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pppobear"><img src="https://avatars.githubusercontent.com/u/21952175?v=4" width="100px;" alt=""/><br /><sub><b>pppobear</b></sub></a><br /><a href="#bug-pppobear" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/bcachet"><img src="https://avatars.githubusercontent.com/u/45542?v=4" width="100px;" alt=""/><br /><sub><b>Bertrand Cachet</b></sub></a><br /><a href="#code-bcachet" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/EarthChen"><img src="https://avatars.githubusercontent.com/u/20179425?v=4" width="100px;" alt=""/><br /><sub><b>earthchen</b></sub></a><br /><a href="#code-EarthChen" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Don-Yin"><img src="https://avatars.githubusercontent.com/u/65135356?v=4" width="100px;" alt=""/><br /><sub><b>Don Yin</b></sub></a><br /><a href="#code-Don-Yin" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ELA718"><img src="https://avatars.githubusercontent.com/u/193304463?v=4" width="100px;" alt=""/><br /><sub><b>ELA718</b></sub></a><br /><a href="#doc-ELA718" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/sujeito-operator/pilot"><img src="https://avatars.githubusercontent.com/u/313599463?v=4" width="100px;" alt=""/><br /><sub><b>Sujeito Operator</b></sub></a><br /><a href="#code-sujeito-operator" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.blahs.life/"><img src="https://avatars.githubusercontent.com/u/620336?v=4" width="100px;" alt=""/><br /><sub><b>Dan Blah</b></sub></a><br /><a href="#bug-danblah" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/3choBoomer"><img src="https://avatars.githubusercontent.com/u/521828?v=4" width="100px;" alt=""/><br /><sub><b>Nathan Cooke</b></sub></a><br /><a href="#code-3choBoomer" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/white-hat"><img src="https://avatars.githubusercontent.com/u/922988?v=4" width="100px;" alt=""/><br /><sub><b>Eli Stark</b></sub></a><br /><a href="#code-white-hat" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/marvtub"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark Faga</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aeturnal"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://marvinaziz.de/"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://aeturnal.io/"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/floatGray"><img src="https://avatars.githubusercontent.com/u/44295302?v=4" width="100px;" alt=""/><br /><sub><b>floatGray</b></sub></a><br /><a href="#code-floatGray" title="Code">💻</a></td>
     </tr>
   </tbody>

package/node_modules/pi-lens/config/ruff/core.toml

@@ -16,10 +16,52 @@ select = [
   "SIM",  # flake8-simplify (simplifiable constructs)
   "C4",   # flake8-comprehensions (unnecessary comprehension patterns)
   "PIE",  # flake8-pie (misc lints)
+  "S",    # flake8-bandit (Bandit-equivalent security checks; refs #1757)
 ]
 
+# C90 (mccabe cyclomatic complexity) — considered and NOT enabled (refs #1757).
+# Measured against `requests` (mature, well-styled: 2 hits over the default
+# threshold of 10, both genuinely complex) and `pandas` (379 hits) — the
+# signal is real complexity, not false positives, but the volume on a large
+# pre-existing codebase would drown the security signal `S` adds in the same
+# pass. C90 is a maintainability metric, not a Bandit-equivalent security
+# check, so it stays out of scope for this issue. Revisit as its own opt-in
+# if pi-lens grows a "code health" ruleset.
+
+# S sub-rules excluded below were triaged by running `ruff check --select S`
+# against tests/fixtures/real-bugs/python/silent-and-security.py (this repo's
+# own security fixture — 3/3 true positives: S110, S105, S307) and against the
+# `requests` and `pip` packages installed under a local Python 3.11 (394
+# combined S findings across two mature, widely-audited real-world
+# codebases) — chosen as the "2-3 real fixtures" because pi-lens's own repo
+# only has ~15 Python files, too small to expose over-firing sub-rules.
 ignore = [
   "E501",   # line too long — formatter handles this
   "B008",   # function call in default argument — common FastAPI/typer pattern
   "SIM108", # ternary operator — readability is subjective
+
+  # S101 assert: 354 of 394 S hits (90%) across requests+pip were bare
+  # `assert` statements — the risk `S101` warns about (asserts stripped under
+  # `python -O`) is real only for security-enforcement code, not general
+  # application or test code, where `assert` is idiomatic (pytest). Pure
+  # noise at this volume.
+  "S101",
+  # S311 suspicious-non-cryptographic-random-usage: every hit observed
+  # (e.g. pip/_internal/utils/filesystem.py building a temp-file suffix) was
+  # a non-security use of `random` — file names, jitter, sampling. Ruff
+  # cannot distinguish security-sensitive randomness from ordinary use.
+  "S311",
+  # S603 subprocess-without-shell-equals-true: fires on every list-argument
+  # `subprocess.run(...)`/`Popen(...)` call regardless of whether the
+  # arguments are attacker-controlled — this is the RECOMMENDED safe form
+  # (no shell=True), yet it was the rule's only trigger condition in every
+  # one of the 10 hits observed in pip. Bandit's own docs note this rule's
+  # high false-positive rate; excluded for the same reason upstream projects
+  # commonly disable it.
+  "S603",
+  # S607 start-process-with-partial-path: fires whenever a subprocess call
+  # names its executable by PATH lookup (`["rustc", "--version"]`) instead of
+  # an absolute path — standard practice for any CLI-wrapping code, and both
+  # observed hits in pip were exactly that pattern, not a real vulnerability.
+  "S607",
 ]

package/node_modules/pi-lens/dist/clients/actionable-warnings.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { hashText, normalizeMessage, stableFindingId, } from "./finding-identity.js";
 import { applyWorkspaceEdit } from "./lsp/edits.js";
 import { getLSPService } from "./lsp/index.js";
 import { normalizeMapKey } from "./path-utils.js";
@@ -14,19 +15,47 @@ let beforeWarningStateLockForTests = null;
 export function _setBeforeWarningStateLockForTests(hook) {
     beforeWarningStateLockForTests = hook;
 }
-function normalizeMessage(message) {
-    return message.replace(/\s+/g, " ").trim().toLowerCase();
-}
-function hashText(value, length = 10) {
-    return createHash("sha256").update(value).digest("hex").slice(0, length);
-}
-function relativeFile(filePath, cwd) {
-    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
-    return rel && !rel.startsWith("..") ? rel : normalizeMapKey(filePath);
-}
+/** #1816: was a local `relativeFile|tool|source|code|rule|normalizedMessage|
+ * line` hash, hand-rolled independently of `diagnostic-dispositions.ts`'s
+ * canonicalizing version — this is now the shared `finding-identity.js`
+ * builder (which DOES canonicalize both `cwd` and `filePath` through
+ * `normalizeMapKey` before relativizing, and hashes to 12 chars, matching
+ * dispositions). See `legacyActionableWarningId` below for the pre-#1816
+ * formula, kept only for on-disk suppression-store migration. */
 export function createActionableWarningId(args) {
+    return stableFindingId("aw:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [
+            args.tool,
+            args.source,
+            args.code,
+            args.rule,
+            normalizeMessage(args.message),
+            args.line,
+        ],
+    });
+}
+/** PRE-#1816 id formula (raw, non-canonicalized `relativeFile`; 10-char
+ * hash). `actionable-warning-state.json` is a keyed, persisted store — a
+ * warning suppressed under the old formula must not silently reappear as
+ * unsuppressed just because this module unified onto the canonical,
+ * 12-char id. `suppressionFor`/`updateWarningState` use this ONLY to look up
+ * and migrate a still-pending old entry forward; nothing ever WRITES under
+ * this id. Do not canonicalize this function — that would make it identical
+ * to `createActionableWarningId` and silently defeat the migration lookup
+ * for every path that actually needed canonicalizing (the #533 class this
+ * whole item exists to fix). Review-round F3 (#1816): this guard is only
+ * provable under a MIS-CASED path fixture — a fixture whose raw and
+ * canonical forms coincide (a bare mkdtempSync path) makes canonicalizing
+ * this function a no-op, so the regression test must seed under a mis-cased
+ * segment (see `actionable-warnings.test.ts`'s migration describe block) or
+ * the guard passes vacuously either way. */
+function legacyActionableWarningId(args) {
+    const rel = path.relative(args.cwd, args.filePath).replace(/\\/g, "/");
+    const legacyRelativeFile = rel && !rel.startsWith("..") ? rel : normalizeMapKey(args.filePath);
     const parts = [
-        relativeFile(args.filePath, args.cwd),
+        legacyRelativeFile,
         args.tool ?? "",
         args.source ?? "",
         String(args.code ?? ""),
@@ -34,7 +63,7 @@ export function createActionableWarningId(args) {
         normalizeMessage(args.message),
         String(args.line ?? ""),
     ];
-    return `aw:${hashText(parts.join("|"))}`;
+    return `aw:${hashText(parts.join("|"), 10)}`;
 }
 function actionSafety(action) {
     const kind = action.kind ?? "";
@@ -93,7 +122,28 @@ function updateWarningState(cwd, warnings) {
             const now = new Date().toISOString();
             state.warnings ??= {};
             for (const warning of warnings) {
-                const existing = state.warnings[warning.id] ?? {};
+                // #1816 migration: this warning may still be recorded under the
+                // pre-#1816 id (raw relativeFile, 10-char hash) from before this
+                // store unified onto the canonical id. Fold that entry forward
+                // onto the current id and drop the stale key, so a warning
+                // suppressed before the migration stays suppressed, and repeated
+                // re-encounters converge the store onto one id per warning
+                // instead of accumulating both forever.
+                //
+                // Review-round F1: this MUST read `warning.legacyId` — the value
+                // `suppressionFor` already computed from the exact identity args
+                // used at lookup time — and must NEVER re-derive a legacy id from
+                // `warning.rule`/`tool`/`source`/`code`. Those fields hold
+                // DISPLAY values that diverge from the id-construction args for
+                // LSP-origin records (see `ActionableWarningRecord.legacyId`'s
+                // doc comment), so a re-derivation here would compute a
+                // different legacy id than the one `suppressionFor` checked,
+                // permanently bifurcating the store.
+                const legacyId = warning.legacyId;
+                const legacyEntry = legacyId && legacyId !== warning.id
+                    ? state.warnings[legacyId]
+                    : undefined;
+                const existing = state.warnings[warning.id] ?? legacyEntry ?? {};
                 state.warnings[warning.id] = {
                     ...existing,
                     status: existing.status ?? "active",
@@ -101,6 +151,8 @@ function updateWarningState(cwd, warnings) {
                     lastSeenAt: now,
                     seenCount: (existing.seenCount ?? 0) + 1,
                 };
+                if (legacyEntry && legacyId)
+                    delete state.warnings[legacyId];
             }
             return state;
         },
@@ -115,36 +167,64 @@ function updateWarningState(cwd, warnings) {
         }),
     });
 }
-function suppressionFor(cwd, id) {
-    const entry = readSuppressionState(cwd).warnings?.[id];
+/** Looks up suppression under the current id, falling back to the pre-#1816
+ * id (see `legacyActionableWarningId`) so a warning suppressed before this
+ * migration doesn't silently reappear as unsuppressed. `args` is the exact
+ * identity shape both id builders take.
+ *
+ * Also RETURNS the `legacyId` it computed (review-round F1, #1816): the
+ * caller carries it onto the record's `legacyId` field so
+ * `updateWarningState` can migrate the SAME legacy id this lookup used,
+ * instead of re-deriving one from the record's own `rule`/`tool`/`source`/
+ * `code` fields later. Re-deriving is unsound for LSP-origin records —
+ * `recordFromLspDiagnostic` passes no `rule` into this function (LSP
+ * diagnostics don't have one), then sets `record.rule` afterward to
+ * `${source}:${code}` purely for display. Recomputing from that display
+ * value would silently compute a DIFFERENT legacy id than the one actually
+ * checked here, permanently bifurcating the store: a suppression written
+ * this turn under the current id would never be found again next turn. */
+function suppressionFor(cwd, id, args) {
+    const state = readSuppressionState(cwd);
+    const legacyId = legacyActionableWarningId({ cwd, ...args });
+    const entry = state.warnings?.[id] ??
+        (legacyId !== id ? state.warnings?.[legacyId] : undefined);
     return {
         suppressed: entry?.status === "suppressed",
         reason: entry?.reason,
+        legacyId,
     };
 }
 export function recordFromDispatchDiagnostic(diagnostic, cwd) {
-    if (diagnostic.semantic !== "warning" || diagnostic.severity !== "warning")
+    if (diagnostic.semantic !== "warning")
+        return undefined;
+    // #1777: the old gate demanded `severity === "warning"` exactly, which was
+    // invisible while the ast-grep runner collapsed every non-error tier to
+    // "warning". Now that hint and info survive the dispatch path, admit them:
+    // a fix is a fix, and the tier governs how loudly a finding renders, not
+    // whether its fix is worth offering. `error` still routes to the blocking
+    // path, so it stays out even when a runner leaves `semantic` at "warning".
+    if (diagnostic.severity === "error")
         return undefined;
     if (!diagnostic.fixable && !diagnostic.fixSuggestion)
         return undefined;
     const filePath = path.resolve(cwd, diagnostic.filePath);
-    const id = createActionableWarningId({
-        cwd,
+    const identityArgs = {
         filePath,
         tool: diagnostic.tool,
         code: diagnostic.code,
         rule: diagnostic.rule,
         message: diagnostic.message,
         line: diagnostic.line,
-    });
-    const suppression = suppressionFor(cwd, id);
+    };
+    const id = createActionableWarningId({ cwd, ...identityArgs });
+    const suppression = suppressionFor(cwd, id, identityArgs);
     return {
         id,
         filePath,
         displayPath: toRunnerDisplayPath(cwd, filePath),
         line: diagnostic.line,
         column: diagnostic.column,
-        severity: "warning",
+        severity: diagnostic.severity,
         tool: diagnostic.tool,
         code: diagnostic.code,
         rule: diagnostic.rule,
@@ -155,6 +235,7 @@ export function recordFromDispatchDiagnostic(diagnostic, cwd) {
         actions: [],
         suppressed: suppression.suppressed,
         suppressionReason: suppression.reason,
+        legacyId: suppression.legacyId,
         origin: "dispatch",
     };
 }
@@ -170,16 +251,16 @@ function recordFromLspDiagnostic(diag, filePath, cwd) {
     const column = diag.range.start.character + 1;
     const source = diag.source ?? "lsp";
     const code = diag.code === undefined ? undefined : String(diag.code);
-    const id = createActionableWarningId({
-        cwd,
+    const identityArgs = {
         filePath,
         tool: "lsp",
         source,
         code,
         message: diag.message,
         line,
-    });
-    const suppression = suppressionFor(cwd, id);
+    };
+    const id = createActionableWarningId({ cwd, ...identityArgs });
+    const suppression = suppressionFor(cwd, id, identityArgs);
     return {
         id,
         filePath,
@@ -195,6 +276,7 @@ function recordFromLspDiagnostic(diag, filePath, cwd) {
         actions: [],
         suppressed: suppression.suppressed,
         suppressionReason: suppression.reason,
+        legacyId: suppression.legacyId,
         origin: "lsp",
     };
 }
@@ -329,8 +411,13 @@ export async function buildActionableWarningsReport(args) {
     }
     const merged = mergeWarnings(records);
     updateWarningState(cwd, merged);
+    // legacyId is #1816 migration bookkeeping for updateWarningState above —
+    // strip it before the report leaves this function, so it never lands in
+    // the `.pi-lens/cache/actionable-warnings.json` cache file or any
+    // agent-facing rendering of a warning record.
+    const reportWarnings = merged.map(({ legacyId: _legacyId, ...rest }) => rest);
     const byFile = new Map();
-    for (const warning of merged) {
+    for (const warning of reportWarnings) {
         const arr = byFile.get(warning.filePath) ?? [];
         arr.push(warning);
         byFile.set(warning.filePath, arr);
@@ -342,9 +429,16 @@ export async function buildActionableWarningsReport(args) {
         warnings,
     }));
     const allActions = merged.flatMap((warning) => warning.actions);
+    const unsuppressed = merged.filter((warning) => !warning.suppressed);
+    const countTier = (tier) => unsuppressed.filter((warning) => warning.severity === tier).length;
     const summary = {
         warnings: merged.length,
-        unsuppressed: merged.filter((warning) => !warning.suppressed).length,
+        unsuppressed: unsuppressed.length,
+        byTier: {
+            warning: countTier("warning"),
+            info: countTier("info"),
+            hint: countTier("hint"),
+        },
         suppressed: merged.filter((warning) => warning.suppressed).length,
         files: files.length,
         actions: allActions.length,
@@ -586,8 +680,17 @@ export function formatActionableWarningsAdvisory(report) {
     const safe = report.summary.autoFixEligible > 0
         ? ` ${report.summary.autoFixEligible} appear to have conservative preferred quickfixes.`
         : "";
+    // #1777: hint and info are style opinions, so say how much of the count is
+    // opinion. The line appears only when a quiet tier is actually present —
+    // an all-warning turn already says everything in the count above.
+    const byTier = report.summary.byTier;
+    const quiet = byTier ? byTier.hint + byTier.info : 0;
+    const tierLine = quiet > 0
+        ? `${quiet} of those are hint/info tier — style opinions, worth fixing only while you are already in that code.`
+        : undefined;
     return [
         `🟡 Fixable warnings introduced this turn: ${report.summary.unsuppressed}.${safe}`,
+        tierLine,
         `Details written to .pi-lens/cache/actionable-warnings.json`,
         fileList ? `Files:\n${fileList}${more}` : undefined,
         "If continuing in these files, read that JSON and resolve warnings that are safe and relevant. Do not apply broad refactors unless requested.",

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))