@herbertgao/pi-extensions 2026.9.6 → 2026.9.7

package/node_modules/pi-lens/dist/clients/map-with-concurrency.js

@@ -12,25 +12,29 @@
  *
  * Same shape as `ledger-bounds.ts` (#2426) for the degradation ledger's bound.
  *
- * NOT consolidated here: `lsp/client.ts` keeps its own file-local copy on
- * purpose (see its comment) — that is a documented decision, not drift.
+ * Callers that need results use the result-returning overload; callers that
+ * only need completion use the void overload. Keeping both forms here prevents
+ * per-caller worker-pool copies from drifting.
  */
-/**
- * Run `mapper` over `items` with at most `concurrency` in flight at once.
- */
-export async function mapWithConcurrency(items, concurrency, mapper) {
+export async function mapWithConcurrency(items, concurrency, mapper, signal) {
     if (items.length === 0)
-        return;
+        return [];
     let nextIndex = 0;
     const workerCount = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Map();
     const worker = async () => {
         while (true) {
+            if (signal?.aborted)
+                return;
             const index = nextIndex++;
             if (index >= items.length)
                 return;
-            await mapper(items[index]);
+            results.set(index, (await mapper(items[index])));
         }
     };
     const workers = Array.from({ length: workerCount }, () => worker());
     await Promise.all(workers);
+    return [...results.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, result]) => result);
 }

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

@@ -31,6 +31,8 @@ import { handleSessionStart } from "../runtime-session.js";
 import { handleTurnEnd } from "../runtime-turn.js";
 import { createMcpHost } from "./host-shim.js";
 import { startSituationalToolTelemetrySession } from "../situational-tool-telemetry.js";
+import { bounded } from "../deadline-utils.js";
+import { HOOK_WALL_BUDGET_MS } from "../hook-budgets.js";
 let contextPromise;
 let resolvedRuntime;
 /**
@@ -73,17 +75,20 @@ function joinMessages(consumed) {
         return undefined;
     return consumed.messages.map((message) => message.content).join("\n\n");
 }
+const degradedSessionStart = {
+    aliveLspClients: 0,
+};
 /**
  * Run pi-lens's real session_start. Much of the work (scans, baseline, LSP warm)
  * runs in the background, so the immediate return carries the synchronous
  * guidance + whatever baseline/LSP state is ready; query `pilens_diagnostics` /
  * `pilens_health` afterwards for the scan results as they land.
  */
-export async function runSessionStart(cwd) {
+async function runSessionStartImpl(cwd) {
     startSituationalToolTelemetrySession("mcp");
     const ctx = await getMcpSessionContext();
     const host = createMcpHost(undefined, cwd);
-    await handleSessionStart({
+    await bounded(handleSessionStart({
         ctxCwd: cwd,
         // The MCP server has no TUI keystroke latency to protect, so the
         // first-call-quick heuristic must not apply. Force "full" mode so
@@ -108,16 +113,33 @@ export async function runSessionStart(cwd) {
         cleanStaleTsBuildInfo: () => [],
         resetDispatchBaselines: (cwdArg) => resetDispatchBaselines(cwdArg ?? cwd),
         resetLSPService,
+    }), {
+        ms: HOOK_WALL_BUDGET_MS.session_start,
+        signal: undefined,
+        hook: "session_start",
+        label: "handleSessionStart",
     });
     const baseline = ctx.runtime.errorDebtBaseline;
     return {
-        guidance: joinMessages(consumeSessionStartGuidance(ctx.cacheManager, cwd)),
+        guidance: joinMessages(consumeSessionStartGuidance(ctx.cacheManager, cwd, "mcp")),
         errorDebtBaseline: baseline
             ? { testsPassed: baseline.testsPassed, buildPassed: baseline.buildPassed }
             : undefined,
         aliveLspClients: getLSPService().getAliveClientCount(),
     };
 }
+export function runSessionStart(cwd) {
+    return bounded(runSessionStartImpl(cwd), {
+        ms: HOOK_WALL_BUDGET_MS.session_start,
+        signal: undefined,
+        hook: "session_start",
+        label: "mcp-session-start",
+    }).then((outcome) => outcome ?? degradedSessionStart);
+}
+const degradedTurnEnd = {
+    outcome: { filesRegistered: 0 },
+    commit: () => { },
+};
 /**
  * #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.
@@ -193,7 +215,7 @@ const inFlightIpcTurnEnds = new Map();
  * 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).
  */
-async function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
+async function runTurnEndNowImpl(cwd, files = [], deferredDelivery = false) {
     const ctx = await getMcpSessionContext();
     const host = createMcpHost(undefined, cwd);
     let registered = 0;
@@ -216,6 +238,7 @@ async function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
         lastSeen: new Date().toISOString(),
     };
     await handleTurnEnd({
+        signal: undefined,
         ctxCwd: cwd,
         getFlag: host.getFlag,
         dbg: noop,
@@ -225,6 +248,7 @@ async function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
         deadCodeClients: ctx.clients.deadCodeClients,
         depChecker: ctx.clients.depChecker,
         testRunnerClient: ctx.clients.testRunnerClient,
+        host: "mcp",
         owner,
         resetLSPService,
         resetFormatService,
@@ -250,6 +274,14 @@ async function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
         },
     };
 }
+function runTurnEndNow(cwd, files = [], deferredDelivery = false) {
+    return bounded(runTurnEndNowImpl(cwd, files, deferredDelivery), {
+        ms: HOOK_WALL_BUDGET_MS.turn_end,
+        signal: undefined,
+        hook: "turn_end",
+        label: "mcp-turn-end",
+    }).then((transaction) => transaction ?? degradedTurnEnd);
+}
 /**
  * Run a normal MCP turn_end. Its caller owns the tool response, so the
  * historical consume-on-return behavior remains unchanged.

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

@@ -189,8 +189,17 @@ export function resetSinkRotations() {
         state.rotationCount = 0;
         state.rotationFailures = 0;
         state.rotationRetryAfterMs = 0;
+        state.optionConflictRecorded = false;
     }
 }
+/** Pure read-time view for the degradation ledger; never logs through this sink. */
+export function getSinkOptionConflicts() {
+    if (!ndjsonGlobalState)
+        return [];
+    return [...ndjsonGlobalState.writers.values()]
+        .filter((state) => state.optionConflictRecorded)
+        .map((state) => ({ file: state.file }));
+}
 function requireCurrentGlobalState() {
     if (ndjsonGlobalState)
         return ndjsonGlobalState;
@@ -213,12 +222,6 @@ function registerWriter(state) {
 function normalizeLogPath(file) {
     return normalizeFilePath(path.resolve(file));
 }
-function assertCompatibleWriterOptions(existing, maxBytes, backupPath) {
-    if (existing.maxBytes === maxBytes && existing.backupPath === backupPath)
-        return;
-    throw new Error(`createNdjsonLogger: incompatible options for shared path ${existing.file}; ` +
-        `the first writer's maxBytes/backupPath must be reused`);
-}
 function writeQueueItemSync(state, item) {
     if (item.kind === "truncate") {
         fs.writeFileSync(state.file, "");
@@ -298,7 +301,6 @@ function createWriterState(file, maxBytes, backupPath) {
     if (existing) {
         // A partially initialized global state from another graph still needs to
         // be enrolled, but it must never get a second queue or exit flusher.
-        assertCompatibleWriterOptions(existing, maxBytes, backupPath);
         if (!exitFlushers.has(existing.exitFlusher))
             registerWriter(existing);
         // A state adopted from a pre-#1970 module graph predates this field.
@@ -318,6 +320,20 @@ function createWriterState(file, maxBytes, backupPath) {
             existing.rotationFailures = 0;
         if (typeof existing.rotationRetryAfterMs !== "number")
             existing.rotationRetryAfterMs = 0;
+        if (typeof existing.optionConflictRecorded !== "boolean")
+            existing.optionConflictRecorded = false;
+        const optionsDiffer = existing.maxBytes !== maxBytes || existing.backupPath !== backupPath;
+        if (optionsDiffer) {
+            // A pre-#2505 graph can leave this writer unbounded. Adopt the incoming
+            // bound so reload restores rotation instead of preserving an unsafe gap.
+            if (existing.maxBytes === undefined && maxBytes !== undefined)
+                existing.maxBytes = maxBytes;
+            if (existing.backupPath === undefined && backupPath !== undefined)
+                existing.backupPath = backupPath;
+            // A rotation-policy disagreement must never abort extension loading.
+            // The ledger folds this bounded, per-path fact into health at read time.
+            existing.optionConflictRecorded = true;
+        }
         return existing;
     }
     const state = {};
@@ -337,6 +353,7 @@ function createWriterState(file, maxBytes, backupPath) {
     state.rotationCount = 0;
     state.rotationFailures = 0;
     state.rotationRetryAfterMs = 0;
+    state.optionConflictRecorded = false;
     globalState.writers.set(file, state);
     registerWriter(state);
     return state;

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

@@ -717,6 +717,7 @@ export async function settleObservedMutation(args) {
         return {
             settled: false,
             changedPaths: [],
+            unverifiablePaths: [],
             replayed: 0,
             scanned: 0,
             stoppedEarly: false,
@@ -730,6 +731,7 @@ export async function settleObservedMutation(args) {
         return {
             settled: false,
             changedPaths: [],
+            unverifiablePaths: [],
             replayed: 0,
             scanned: 0,
             stoppedEarly: false,
@@ -744,6 +746,7 @@ export async function settleObservedMutation(args) {
         return {
             settled: false,
             changedPaths: [],
+            unverifiablePaths: [],
             replayed: 0,
             scanned: 0,
             stoppedEarly: false,
@@ -771,6 +774,7 @@ export async function settleObservedMutation(args) {
         return {
             settled: false,
             changedPaths: [],
+            unverifiablePaths: [],
             replayed: 0,
             scanned: 0,
             stoppedEarly: true,
@@ -779,7 +783,9 @@ export async function settleObservedMutation(args) {
     }
     const captured = capture.value;
     seedLedger(captured.snapshot);
-    const changed = diffFileStats(pending.stats, captured.snapshot).filter((candidate) => args.isRecordable?.(candidate) !== false);
+    const diff = diffObservedStats(pending.stats, captured.snapshot);
+    const changed = diff.changed.filter((candidate) => args.isRecordable?.(candidate) !== false);
+    const unverifiablePaths = diff.unverifiable.filter((candidate) => args.isRecordable?.(candidate) !== false);
     // Two different ways the observation can fall short of what the tool named:
     // the ARM already truncated a wide directory (#2449 round 3, S3), or the
     // re-capture's own deadline cut its tail. Both mean the same thing to the
@@ -790,6 +796,19 @@ export async function settleObservedMutation(args) {
         : captured.stoppedEarly
             ? "capture-cut-short"
             : undefined;
+    if (unverifiablePaths.length > 0) {
+        // Hashless evidence is a bounded coverage gap, not a mutation. Keep it
+        // visible through the existing degradation record without replaying it.
+        noteObservedUnverifiable(args.toolName);
+        logLatency({
+            type: "phase",
+            toolName: args.toolName,
+            phase: "observed_mutation_coverage_unknown",
+            filePath: unverifiablePaths.slice(0, 5).join(","),
+            durationMs: Date.now() - started,
+            result: `unverifiable:${unverifiablePaths.length}`,
+        });
+    }
     if (changed.length === 0) {
         // An INCOMPLETE observation is not evidence of cleanliness — it is
         // evidence we stopped looking. Advancing the clean latch on it would
@@ -797,11 +816,12 @@ export async function settleObservedMutation(args) {
         // with a directory wider than the cap that is every single call.
         if (truncated)
             noteObservedUnverifiable(args.toolName);
-        else
+        else if (unverifiablePaths.length === 0)
             noteObservedClean(args.toolName);
         return {
             settled: true,
             changedPaths: [],
+            unverifiablePaths,
             replayed: 0,
             scanned: captured.snapshot.size,
             stoppedEarly: truncated,
@@ -860,12 +880,30 @@ export async function settleObservedMutation(args) {
     return {
         settled: true,
         changedPaths: changed,
+        unverifiablePaths,
         replayed,
         scanned: captured.snapshot.size,
         stoppedEarly: truncated,
         reason: cutReason,
     };
 }
+/**
+ * The observational net asks whether to look harder. An absent content hash
+ * therefore remains unverifiable even when cheap stat fields report a change.
+ * #2984: stat-only evidence must not grant ownership or replay a mutation.
+ */
+function diffObservedStats(before, after) {
+    const changed = new Set(diffFileStats(before, after));
+    const unverifiable = new Set();
+    for (const [key, stat] of after) {
+        const previous = before.get(key);
+        if (previous && (previous.hash === undefined || stat.hash === undefined)) {
+            changed.delete(key);
+            unverifiable.add(key);
+        }
+    }
+    return { changed: [...changed], unverifiable: [...unverifiable] };
+}
 async function readBytesSafe(filePath) {
     try {
         return await fs.promises.readFile(filePath);

package/node_modules/pi-lens/dist/clients/opaque-mutation-scan.js

@@ -124,6 +124,9 @@ export async function captureFileStatsForPaths(files, options = {}) {
     return { snapshot, stoppedEarly };
 }
 export async function captureFileStats(root, options = {}) {
+    if (options.forcedUnknownReason !== undefined) {
+        return { unknownReason: options.forcedUnknownReason, scannedCount: 0 };
+    }
     const budgetMs = options.budgetMs ?? 50;
     try {
         const walk = await collectSourceFilesWithBudgetAsync(root, {
@@ -150,13 +153,12 @@ export async function captureFileStats(root, options = {}) {
 }
 /** Paths added or whose size/mtime changed. Deletions are NOT reported. */
 export function diffFileStats(before, after) {
+    const contentChanged = new Set(diffFileContent(before, after));
     const changed = [];
     for (const [key, stat] of after) {
         const prev = before.get(key);
         // Content confirm: same mtime tick + same size but different bytes.
-        const contentConfirm = prev?.hash !== undefined &&
-            stat.hash !== undefined &&
-            prev.hash !== stat.hash;
+        const contentConfirm = contentChanged.has(key);
         if (!prev ||
             prev.mtimeMs !== stat.mtimeMs ||
             prev.size !== stat.size ||
@@ -166,6 +168,24 @@ export function diffFileStats(before, after) {
     }
     return changed;
 }
+/**
+ * Return paths confirmed different by hashes, plus files absent before and
+ * present after. A missing baseline entry is evidence of creation; a missing
+ * hash on an existing entry remains unknown.
+ */
+export function diffFileContent(before, after) {
+    const changed = [];
+    for (const [key, stat] of after) {
+        const previous = before.get(key);
+        if (previous === undefined ||
+            (previous.hash !== undefined &&
+                stat.hash !== undefined &&
+                previous.hash !== stat.hash)) {
+            changed.push(key);
+        }
+    }
+    return changed;
+}
 export class OpaqueBaselineStore {
     byCwd = new Map();
     evictions = 0;

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

@@ -54,7 +54,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { mkdtempSync } from "node:fs";
 import { resolveOpengrepConfig } from "./opengrep-config.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
 import { getScratchTreeDirNames } from "./scratch-tree-policy.js";
+import { realpathOrResolve } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { SecurityScanClient } from "./security-scan-client.js";
 const EMPTY_RESULT = {
@@ -92,12 +94,13 @@ export class OpengrepClient extends SecurityScanClient {
      * opengrep process (mirrors `GitleaksClient`/`JscpdClient`).
      */
     async scan(cwd) {
-        const targetDir = path.resolve(cwd);
+        const targetDir = realpathOrResolve(cwd);
         const scannedAt = new Date().toISOString();
         if (!(await this.ensureAvailable())) {
             return {
                 ...EMPTY_RESULT,
                 scannedAt,
+                reason: "not-installed",
                 summary: "opengrep not installed",
             };
         }
@@ -134,33 +137,76 @@ export class OpengrepClient extends SecurityScanClient {
             ], { cwd, timeout: SCAN_TIMEOUT_MS });
             if (result.error) {
                 this.log(`Scan error: ${result.error.message}`);
+                const reason = `${result.failure ?? "spawn-failed"}: ${result.error.message}`;
+                this.recordRefusal(cwd, reason, result.status);
                 return {
                     ...EMPTY_RESULT,
                     scannedAt,
-                    summary: result.error.message.slice(0, 200),
+                    reason: "spawn-failed",
+                    summary: reason.slice(0, 200),
                 };
             }
             if (!fs.existsSync(reportPath)) {
+                const reason = (result.stderr ?? "").trim().split("\n")[0] || "no report produced";
+                this.recordRefusal(cwd, reason, result.status);
                 return {
                     ...EMPTY_RESULT,
                     scannedAt,
-                    summary: (result.stderr ?? "").trim().split("\n")[0] || "no report produced",
+                    reason: "no-report",
+                    summary: reason,
                 };
             }
-            const findings = parseOpengrepReport(fs.readFileSync(reportPath, "utf-8"));
+            const raw = fs.readFileSync(reportPath, "utf-8");
+            const report = readOpengrepReport(raw);
+            if (report.verdict === "refused" || result.status !== 0) {
+                const reason = report.verdict === "refused"
+                    ? report.reason
+                    : `opengrep exited with status ${result.status}`;
+                this.recordRefusal(cwd, reason, result.status);
+                return {
+                    ...EMPTY_RESULT,
+                    scannedAt,
+                    reason: "refused",
+                    summary: reason.slice(0, 200),
+                };
+            }
+            if (report.partial) {
+                recordDegradationOnce({
+                    kind: "opengrep-partial-scan",
+                    subject: cwd,
+                    reason: report.partial.reason,
+                    metadata: { status: result.status },
+                });
+            }
             // #2154: the one opengrep site that parsed a scan of this root.
             return {
                 success: true,
-                analyzed: true,
-                findings,
+                // A warning-level partial report with no scanned paths proves that
+                // the producer went cold. A complete empty report still proves a
+                // genuine scan, so it remains authoritative for the id-only fallback.
+                analyzed: !report.partial || report.scanned.length > 0,
+                ...(report.scanned.length > 0
+                    ? {
+                        analyzedFiles: report.scanned.map((file) => realpathOrResolve(path.resolve(cwd, file))),
+                    }
+                    : {}),
+                ...(report.partial ? { partial: true } : {}),
+                ...(report.partial ? { summary: report.partial.reason } : {}),
+                ...(report.partial && report.scanned.length === 0
+                    ? { reason: "partial-no-paths" }
+                    : {}),
+                findings: report.findings,
                 scannedAt,
             };
         }
         catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.recordRefusal(cwd, reason, undefined);
             return {
                 ...EMPTY_RESULT,
                 scannedAt,
-                summary: err instanceof Error ? err.message.slice(0, 200) : String(err),
+                reason: "crashed",
+                summary: reason.slice(0, 200),
             };
         }
         finally {
@@ -172,6 +218,53 @@ export class OpengrepClient extends SecurityScanClient {
             }
         }
     }
+    recordRefusal(cwd, reason, status) {
+        recordDegradationOnce({
+            kind: "opengrep-scan-refused",
+            subject: cwd,
+            reason,
+            metadata: { status },
+        });
+    }
+}
+function readOpengrepReport(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { verdict: "refused", reason: "unparseable opengrep report" };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { verdict: "refused", reason: "unparseable opengrep report" };
+    const report = parsed;
+    if (!Array.isArray(report.results) && !Array.isArray(report.errors))
+        return { verdict: "refused", reason: "unparseable opengrep report" };
+    const errors = (Array.isArray(report.errors) ? report.errors : []).map((error) => {
+        if (typeof error === "string")
+            return { message: error };
+        if (!error || typeof error !== "object")
+            return { message: "unrecognised opengrep error entry" };
+        const entry = error;
+        const level = typeof entry.level === "string" ? entry.level : undefined;
+        const message = typeof entry.message === "string" ? entry.message : undefined;
+        return {
+            ...(level ? { level } : {}),
+            message: message ?? level ?? "unrecognised opengrep error entry",
+        };
+    });
+    const refusal = errors.find((error) => error.level !== "warn");
+    if (refusal)
+        return { verdict: "refused", reason: refusal.message };
+    const scanned = Array.isArray(report.paths?.scanned)
+        ? report.paths.scanned.filter((file) => typeof file === "string")
+        : [];
+    return {
+        verdict: "usable",
+        ...(errors[0] ? { partial: { reason: errors[0].message } } : {}),
+        findings: parseOpengrepReport(parsed),
+        scanned,
+    };
 }
 // --- Parser ---
 /**
@@ -185,15 +278,17 @@ export class OpengrepClient extends SecurityScanClient {
  * CLI surface has drifted in places, e.g. `--files-with-matches` requires
  * `--experimental` where semgrep's doesn't).
  */
-export function parseOpengrepReport(raw) {
-    if (!raw.trim())
-        return [];
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
+export function parseOpengrepReport(rawOrParsed) {
+    if (typeof rawOrParsed === "string" && !rawOrParsed.trim())
         return [];
+    let parsed = rawOrParsed;
+    if (typeof rawOrParsed === "string") {
+        try {
+            parsed = JSON.parse(rawOrParsed);
+        }
+        catch {
+            return [];
+        }
     }
     if (!parsed || typeof parsed !== "object")
         return [];