@herbertgao/pi-extensions 2026.9.1 → 2026.9.3

package/node_modules/pi-lens/dist/clients/project-scan-policy.js

@@ -1,55 +1,7 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
-import { isGeneratedArtifactDirectoryName, isGeneratedOrArtifact, } from "./generated-artifacts.js";
-import { collectSourceFiles, collectSourceFilesAsync, collectSourceFilesWithBudgetAsync, } from "./source-filter.js";
-export function shouldSkipProjectPath(filePath, options) {
-    const isDirectory = options.isDirectory === true;
-    const matcher = options.ignoreMatcher ?? getProjectIgnoreMatcher(options.rootDir);
-    if (matcher.isIgnored(filePath, isDirectory))
-        return true;
-    const name = path.basename(filePath);
-    if (isDirectory) {
-        if (isExcludedDirName(name))
-            return true;
-        return (options.includeGenerated !== true &&
-            isGeneratedArtifactDirectoryName(name));
-    }
-    return (options.includeGenerated !== true &&
-        isGeneratedOrArtifact(filePath, {
-            readContentHeader: options.inspectGeneratedHeaders !== false,
-            includeDeclarations: options.includeDeclarationFiles !== true,
-        }));
-}
-export function shouldScanProjectSourceFile(filePath, options) {
-    try {
-        if (!fs.statSync(filePath).isFile())
-            return false;
-    }
-    catch {
-        return false;
-    }
-    return !shouldSkipProjectPath(filePath, {
-        ...options,
-        isDirectory: false,
-    });
-}
-export function collectProjectSourceFiles(rootDir, options) {
-    return collectSourceFiles(rootDir, options);
-}
-/**
- * Async, chunked-yield twin of {@link collectProjectSourceFiles}. Produces the
- * exact same file list (it shares `classifyEntry` with the sync collector) but
- * yields to the event loop every N entries so a large-tree walk on a hot hook
- * tick (e.g. the per-edit cascade graph rebuild) never holds the loop in one
- * synchronous burst. Prefer this on the per-edit / per-cascade path.
- */
-export function collectProjectSourceFilesAsync(rootDir, options) {
-    return collectSourceFilesAsync(rootDir, options);
-}
+import { collectSourceFilesWithBudgetAsync, } from "./source-filter.js";
 /**
- * Budget-aware twin of {@link collectProjectSourceFilesAsync} (#760): same
- * walk, but returns `{ files, entryBudgetExceeded }` so a caller on a hot
+ * Budget-aware source walk (#760): the same walk as
+ * `collectProjectSourceFiles`, but returns `{ files, entryBudgetExceeded }` so a caller on a hot
  * path (e.g. the per-edit cascade graph rebuild) can observe that the walk
  * stopped at its `maxScanEntries` entry budget and got a truncated
  * best-effort list rather than a complete enumeration.

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

@@ -455,7 +455,7 @@ class Summary {
         return false;
     }
 }
-export function getPythonProvenanceSummary(root) {
+function getPythonProvenanceSummary(root) {
     const cached = SUMMARY_BY_ROOT.get(root);
     if (cached)
         return cached;

package/node_modules/pi-lens/dist/clients/read-guard-logger.js

@@ -3,6 +3,7 @@ import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 import { normalizeFilePath } from "./path-utils.js";
+import { getTurnId } from "./turn-context.js";
 const READ_GUARD_LOG_DIR = getGlobalPiLensLogDir();
 const READ_GUARD_LOG_FILE = path.join(READ_GUARD_LOG_DIR, "read-guard.log");
 const READ_GUARD_LOG_BACKUP_FILE = path.join(READ_GUARD_LOG_DIR, "read-guard.log.1");
@@ -18,7 +19,7 @@ const VERBOSE_READ_GUARD_LOG = process.env.PI_LENS_READ_GUARD_VERBOSE === "1" ||
 const LOG_ALLOWED_EDITS = process.env.PI_LENS_READ_GUARD_LOG_ALLOWS === "1";
 const SNAPSHOT_LOG_SETTING = (process.env.PI_LENS_READ_GUARD_LOG_SNAPSHOTS ?? "1").toLowerCase();
 const LOG_SNAPSHOT_VALIDATION = !["0", "false", "off"].includes(SNAPSHOT_LOG_SETTING);
-export const MAX_EDIT_BATCH_ITEMS = 100;
+const MAX_EDIT_BATCH_ITEMS = 100;
 let generatedCorrelationCounter = 0;
 export function sanitizeCorrelationId(value) {
     if (typeof value !== "string" && typeof value !== "number")
@@ -236,6 +237,7 @@ export function logReadGuardEvent(entry) {
     writer.log({
         ts: new Date().toISOString(),
         ...logEntry,
+        turnId: getTurnId(),
         filePath: normalizeFilePath(logEntry.filePath),
         metadata,
     });

package/node_modules/pi-lens/dist/clients/read-guard.js

@@ -1396,8 +1396,11 @@ export class ReadGuard {
             return filePath.endsWith(suffix);
         }
         if (pattern.includes("*")) {
-            // Convert glob to regex
-            const regex = new RegExp(`^${pattern.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/\*/g, ".*")}$`);
+            // Adjacent stars are equivalent to one star in this dialect. Collapse
+            // them before compiling so a non-match cannot backtrack over every
+            // nullable `.*` group (#2622).
+            const collapsedPattern = pattern.replace(/\*+/g, "*");
+            const regex = new RegExp(`^${collapsedPattern.replace(/\\/g, "\\\\").replace(/\./g, "\\.").replace(/\*/g, ".*")}$`);
             return regex.test(filePath);
         }
         return filePath === pattern;

package/node_modules/pi-lens/dist/clients/recent-touches.js

@@ -37,7 +37,7 @@ import { getProjectDataDir } from "./file-utils.js";
 import { normalizeFilePath } from "./path-utils.js";
 export const RECENT_TOUCHES_MAX_ENTRIES = 50;
 /** Freshness window for the CHILD session_start consumer (15 minutes). */
-export const RECENT_TOUCHES_FRESHNESS_MS = 15 * 60 * 1000;
+const RECENT_TOUCHES_FRESHNESS_MS = 15 * 60 * 1000;
 function recentTouchesPath(cwd) {
     return path.join(getProjectDataDir(cwd), "recent-touches.json");
 }
@@ -46,7 +46,7 @@ function recentTouchesPath(cwd) {
 // INTO the same nudge pipeline, so one switch governs the whole path
 // (producer, both consumers) as specified in the issue.
 let _enabledCache;
-export function isRecentTouchesEnabled() {
+function isRecentTouchesEnabled() {
     if (_enabledCache === undefined) {
         _enabledCache = process.env.PI_LENS_AGENT_NUDGE !== "0";
     }

package/node_modules/pi-lens/dist/clients/review-graph/builder.js

@@ -92,8 +92,6 @@ const MAIN_KINDS = new Set([
 // so a repo heavy in JSON/YAML/Markdown doesn't trip the cap on files the graph
 // would have filtered out anyway (the cap is on the walk, not on noise). #250.
 const MAIN_KIND_EXTENSIONS = Array.from(MAIN_KINDS).flatMap((kind) => KIND_EXTENSIONS[kind] ?? []);
-/** The bounded, source-filtered extension set shared by graph cache readers. */
-export const REVIEW_GRAPH_SOURCE_EXTENSIONS = MAIN_KIND_EXTENSIONS;
 const CHANGED_SYMBOLS_PREFIX = "session.reviewGraph.changedSymbols:";
 const extractorCache = new Map();
 const REVIEW_GRAPH_MAX_WARM_WORKSPACES = 8;
@@ -407,7 +405,7 @@ export function estimateReviewGraphStoreBytes(totalNodes, totalEdges) {
 // cleared). Bounding only the cache left the full graph resident on the fact, so
 // both sites go through `retainedGraph` below, memoized per graph instance so the
 // two sites share ONE bounded object instead of trimming twice (#2255 review F2).
-export const GRAPH_MAX_IN_MEMORY_BYTES_DEFAULT = 512 * 1024 * 1024;
+const GRAPH_MAX_IN_MEMORY_BYTES_DEFAULT = 512 * 1024 * 1024;
 function graphMaxInMemoryBytes() {
     const raw = Number(process.env.PI_LENS_GRAPH_MAX_IN_MEMORY_BYTES);
     return Number.isFinite(raw) && raw > 0
@@ -967,7 +965,7 @@ function diffSignatureMaps(previous, next) {
 // `RUNTIME_CONFIG.reviewGraph.maxFiles` constant as the fallback — the ratio
 // table reproduces that same 1,000-file default at the default base, so this
 // is behavior-neutral when nothing is configured.
-export function getReviewGraphMaxFiles(cwd) {
+function getReviewGraphMaxFiles(cwd) {
     const override = Number.parseInt(process.env.PI_LENS_REVIEW_GRAPH_MAX_FILES ?? "", 10);
     return Number.isFinite(override) && override > 0
         ? override
@@ -3481,7 +3479,7 @@ function addTreeSitterFile(graph, cwd, filePath, languageId, extracted, ignoredI
  * SymbolInformation results (including native TypeScript 7) recover the same
  * containment through `containerName` when the owner is present in the result.
  */
-export function addLspFallbackSymbols(graph, filePath, languageId, symbols) {
+function addLspFallbackSymbols(graph, filePath, languageId, symbols) {
     const normalized = normalizeMapKey(filePath);
     const fileNodeId = `file:${normalized}`;
     let added = 0;

package/node_modules/pi-lens/dist/clients/review-graph/import-resolvers.js

@@ -90,7 +90,7 @@ function resolveDart(cwd, filePath, source) {
 // JS/TS extension from the specifier before re-appending candidate extensions
 // lets that universal pattern resolve to the real source file. Exported so
 // builder.ts's warm `localImportToFile` shares the exact same regex (#694).
-export const JS_TS_EXT_RE = /\.(mjs|cjs|mts|cts|jsx?|tsx?)$/i;
+const JS_TS_EXT_RE = /\.(mjs|cjs|mts|cts|jsx?|tsx?)$/i;
 /**
  * Ordered candidate list for resolving a relative JS/TS import specifier
  * (already resolved to an absolute base path) to an on-disk file, with

package/node_modules/pi-lens/dist/clients/review-graph-logger.js

@@ -4,6 +4,7 @@ import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 import { normalizeFilePath } from "./path-utils.js";
+import { getTurnId } from "./turn-context.js";
 const REVIEW_GRAPH_LOG_DIR = getGlobalPiLensLogDir();
 const REVIEW_GRAPH_LOG_FILE = path.join(REVIEW_GRAPH_LOG_DIR, "review-graph.log");
 // Bounded like every other global sink (#2505) — see sessionstart-logger.
@@ -64,6 +65,7 @@ export function logReviewGraph(entry) {
         ...entry,
         cwd: normalizeFilePath(entry.cwd),
         pid: process.pid,
+        turnId: getTurnId(),
     });
 }
 export function getReviewGraphLogPath() {

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

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { createAvailabilityChecker, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
 import { isFileKind } from "./file-kinds.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
+import { resolveToolCwd } from "./tool-cwd.js";
 import { ruffConfigArgs } from "./tool-policy.js";
 // --- Client ---
 const ruffAvailability = createAvailabilityChecker("ruff", ".exe");
@@ -44,8 +45,11 @@ export class RuffClient {
     }
     /**
      * Async auto-fix variant for pipeline use (non-blocking spawn).
-     * `cwd` is the dispatch language root (used for config discovery); when
-     * omitted it defaults to the file's directory.
+     * `cwd` is the dispatch language root. It is the seam's starting point,
+     * not the answer: `resolveToolCwd` walks from the file to the nearest
+     * `pyproject.toml`/`ruff.toml`/`.ruff.toml` at or above it, capped inside
+     * `cwd` (and at `$HOME` when there is none), so a file in a nested package
+     * gets that package's config rather than the workspace-root one.
      */
     async fixFileAsync(filePath, cwd) {
         if (!(await this.ensureAvailable())) {
@@ -67,15 +71,20 @@ export class RuffClient {
         }
         try {
             const before = await fs.promises.readFile(absolutePath, "utf-8");
+            // #2894: the root ruff resolves its config from now comes from the
+            // shared seam, not a local `cwd ?? path.dirname(file)`. `tool-policy.ts`
+            // requires the lint runner (`ruff.ts`, on `resolveRunnerCwd`) and this
+            // autofix path to consume the SAME policy; deriving the root two
+            // different ways is how they drift, and the hand-rolled form ignored a
+            // nested `pyproject.toml` whenever the caller passed a workspace root.
+            const ruffCwd = resolveToolCwd("runner", "ruff", absolutePath, {
+                ...(cwd !== undefined && { cwd }),
+            });
             // Shared config-args seam (#1247): the lint runner consumes the same
             // builder, so `check --fix` can never drift to ruff's default rule
             // set when the project lacks its own config and the package-owned
             // core.toml fallback applies.
-            const configArgs = ruffConfigArgs(cwd ?? path.dirname(absolutePath));
-            const spawnOpts = {
-                timeout: 10000,
-                cwd: cwd ?? path.dirname(absolutePath),
-            };
+            const configArgs = ruffConfigArgs(ruffCwd);
             const pre = await safeSpawnAsync(this.ruffCommand, [
                 "check",
                 "--output-format",
@@ -84,12 +93,12 @@ export class RuffClient {
                 "py310",
                 ...configArgs,
                 absolutePath,
-            ], spawnOpts);
+            ], { timeout: 10000, cwd: ruffCwd });
             const beforeDiags = pre.stdout?.trim()
                 ? this.parseOutput(pre.stdout, absolutePath)
                 : [];
             const fixableCount = beforeDiags.filter((d) => d.fixable).length;
-            const fix = await safeSpawnAsync(this.ruffCommand, ["check", "--fix", ...configArgs, absolutePath], { timeout: 15000, cwd: cwd ?? path.dirname(absolutePath) });
+            const fix = await safeSpawnAsync(this.ruffCommand, ["check", "--fix", ...configArgs, absolutePath], { timeout: 15000, cwd: ruffCwd });
             if (fix.error) {
                 return {
                     success: false,

package/node_modules/pi-lens/dist/clients/runtime-agent-end.js

@@ -19,7 +19,7 @@ import { getAutofixPolicyForFile, hasBiomeConfig, hasDetektConfig, hasEslintConf
  * path at all (they match on `ownerSessionId`), so this only trades a little
  * extra staleness for guaranteed eventual formatting. (#791)
  */
-export const DEFERRED_FORMAT_STALE_AFTER_MS = 10 * 60_000;
+const DEFERRED_FORMAT_STALE_AFTER_MS = 10 * 60_000;
 const DEFERRED_FORMAT_CONCURRENCY = 3;
 function recordProjectChange(args) {
     // One mutation seam (#2000 phase 1): bump + receipt + change-log live in
@@ -39,6 +39,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
     // to fall back to "claim as orphaned" (see claimDeferredFormatFiles).
     const { claimed, staleClaimed, deferredToOwner, droppedOrphans } = runtime.claimDeferredMutations(currentSessionId, Date.now(), staleAfterMs, ctxCwd ?? runtime.projectRoot);
     const records = [...claimed, ...staleClaimed];
+    const scheduledTurnId = records[0]?.queuedTurnId;
     const requeuedKinds = new Set();
     // S2d (gap 4, #1432 review): the aggregate `agent_end_deferred_mutation_drain`
     // row only carried a coalesced `requeuedKinds` set with no reason, per-call
@@ -65,6 +66,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             toolName: "agent_end",
             filePath: ctxCwd ?? runtime.projectRoot,
             phase: "agent_end_deferred_mutation_requeue",
+            turnId: pending[0]?.queuedTurnId,
             durationMs: 0,
             metadata: {
                 reason,
@@ -170,6 +172,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
             toolName: "agent_end",
             filePath: ctxCwd ?? runtime.projectRoot,
             phase: "agent_end_deferred_format_stale_claim",
+            turnId: scheduledTurnId,
             durationMs: 0,
             metadata: {
                 fileCount: staleClaimed.length,
@@ -307,6 +310,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_format_start",
+        turnId: scheduledTurnId,
         durationMs: 0,
         metadata: {
             fileCount: records.length,
@@ -491,6 +495,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                 toolName: "agent_end",
                 filePath,
                 phase: "deferred_format_file",
+                turnId: record.queuedTurnId,
                 durationMs: Date.now() - fileStart,
                 metadata: {
                     changed: result.formatChanged,
@@ -635,6 +640,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
                     toolName: "agent_end",
                     filePath: ctxCwd ?? runtime.projectRoot,
                     phase: "actionable_warnings_autofix",
+                    turnId: scheduledTurnId,
                     durationMs: Date.now() - fixStart,
                     metadata: {
                         considered: fixSummary.considered,
@@ -657,6 +663,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_mutation_drain",
+        turnId: scheduledTurnId,
         durationMs: Date.now() - startedAt,
         metadata: {
             autofixRecords: autofixRecords.length,
@@ -671,6 +678,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         filePath: ctxCwd ?? runtime.projectRoot,
         durationMs: Date.now() - startedAt,
         result: "deferred_format_complete",
+        turnId: scheduledTurnId,
         metadata: {
             queued: summary.queued,
             formatted: summary.formatted,
@@ -685,6 +693,7 @@ export async function handleAgentEnd({ ctxCwd, getFlag, getFlagSource, notify, d
         toolName: "agent_end",
         filePath: ctxCwd ?? runtime.projectRoot,
         phase: "agent_end_deferred_format_done",
+        turnId: scheduledTurnId,
         durationMs: Date.now() - startedAt,
         metadata: {
             formatted: summary.formatted,

package/node_modules/pi-lens/dist/clients/runtime-coordinator.js

@@ -11,6 +11,7 @@ import { ReadGuard } from "./read-guard.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { TurnSummaryCollector } from "./turn-summary.js";
 import { deriveProviderFromModelId } from "./model-provider.js";
+import { beginTurnContext, setTurnContextSession } from "./turn-context.js";
 /**
  * Bounded receipt ring capacity (defect shape 9: bound the axis that grows —
  * per-mutation receipts are unbounded across a long session). Oldest receipts
@@ -259,6 +260,7 @@ export class RuntimeCoordinator {
         // by resetForSession().
         this._turnStartProjectSeq = this._projectSeq;
         this._turnIndex += 1;
+        beginTurnContext(this._telemetrySessionId);
         this._writeIndex = 0;
         this._reportedThisTurn.clear();
         this._writtenThisTurn.clear();
@@ -362,6 +364,7 @@ export class RuntimeCoordinator {
     setTelemetryIdentity(identity) {
         if (identity.sessionId && identity.sessionId.trim()) {
             this._telemetrySessionId = identity.sessionId.trim();
+            setTurnContextSession(this._telemetrySessionId);
         }
         const model = identity.model?.trim();
         const provider = identity.provider?.trim();
@@ -1029,6 +1032,7 @@ export class RuntimeCoordinator {
             existing.toolNames.add(toolName);
             existing.kinds.add(kind);
             existing.queuedTurnIndex = this._turnIndex;
+            existing.queuedTurnId = `${this._telemetrySessionId}:${this._turnIndex}`;
             existing.ownerSessionId = ownerSessionId;
             existing.originCwd = resolvedOriginCwd;
             return addedKind;
@@ -1042,6 +1046,7 @@ export class RuntimeCoordinator {
             toolNames: new Set([toolName]),
             kinds: new Set([kind]),
             queuedTurnIndex: this._turnIndex,
+            queuedTurnId: `${this._telemetrySessionId}:${this._turnIndex}`,
             ownerSessionId,
             originCwd: resolvedOriginCwd,
         });

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

@@ -5,7 +5,7 @@ import { rotateMessageEndAttribution } from "./message-end-attribution.js";
 import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
 import { deadCodeIssueCount } from "./dead-code-client.js";
 import { logDeadCodeScan } from "./dead-code-logger.js";
-import { incrementDegradationCount, resetDegradationLedger, } from "./degradation-ledger.js";
+import { incrementDegradationCount, recordDegradationOnce, resetDegradationLedger, } from "./degradation-ledger.js";
 import { getDiagnosticTracker } from "./diagnostic-tracker.js";
 import { resetPsScriptAnalyzerAvailability } from "./dispatch/runners/psscriptanalyzer.js";
 import { resetInstallRetryLatches } from "./dispatch/runners/utils/availability-policy.js";
@@ -42,6 +42,7 @@ import { resetSafeSpawnWindowsCommandCache } from "./safe-spawn.js";
 import { resetAnalyzerBootstrapSessionState, } from "./bootstrap.js";
 import { getSlowFsVerdict, isSlowFs, slowFsDegradationNotice, } from "./slow-fs.js";
 import { countRecentSmells, formatSmellsSessionStartLine, resetSmellsSessionState, } from "./smells-rollup.js";
+import { resetSituationalToolTelemetry } from "./situational-tool-telemetry.js";
 import { findNearestProjectRoot, getStartupScanMaxEntries, isStartupScanVerdictFresh, resolveStartupScanContext, } from "./startup-scan.js";
 import { getSubagentIdentity, isSubagentSession, subagentLightModeNotice, } from "./subagent-mode.js";
 import { TrivyClient } from "./trivy-client.js";
@@ -256,11 +257,14 @@ function logProjectSnapshotProbe(args) {
         args.dbg(`project_snapshot: miss reason=${args.missReason}`);
     }
 }
-function resolveStartupMode() {
+function resolveStartupMode(projectConfig, globalConfig) {
     const envMode = (process.env.PI_LENS_STARTUP_MODE ?? "").trim().toLowerCase();
     if (envMode === "full" || envMode === "minimal" || envMode === "quick") {
         return envMode;
     }
+    const configMode = projectConfig?.startup?.mode ?? globalConfig?.startup?.mode;
+    if (configMode)
+        return configMode;
     if (isPrintMode()) {
         return "quick";
     }
@@ -813,6 +817,15 @@ function scheduleStartupScans(deps, runtime, sessionGeneration, analysisRoot, sn
 /** The scan bodies, once the analyzers they need are resolved. */
 function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analysisRoot, snapshotRoot, languageProfile, dbg) {
     const { todoScanner, cacheManager, knipClient, jscpdClient, deadCodeClients, govulncheckClient, gitleaksClient, trivyClient, opengrepClient, astGrepClient, depChecker, } = deps;
+    const analyzerEnabled = (flag) => !deps.getFlag(flag);
+    if (!analyzerEnabled("no-complexity")) {
+        dbg("session_start complexity: skipped (disabled by config)");
+        recordDegradationOnce({
+            kind: "startup-analyzer-disabled",
+            subject: "complexity",
+            reason: "skipped (disabled by config)",
+        });
+    }
     // Some background scans are CPU-heavy and arrive on the event loop
     // just as the user is most likely typing (right after /new). Defer
     // those by a few seconds so the perceptible 50-100ms sync bursts they
@@ -869,7 +882,7 @@ function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analy
         scanNames.push("knip", "jscpd", "ast-grep exports", "project index");
     }
     dbg(`session_start: launching background scans (${scanNames.join(", ")})`);
-    runTask("todo", async () => {
+    void runTask("todo", async () => {
         if (!runtime.isCurrentSession(sessionGeneration))
             return;
         // The original implementation called todoScanner.scanDirectory(), which
@@ -906,9 +919,19 @@ function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analy
     const isSubagent = isSubagentSession();
     const skipHeavyweightScans = isSlowFs(analysisRoot) || isSubagent;
     const runHeavyweightTask = (name, task) => {
+        const flag = `no-${name}`;
+        if (name !== "opengrep" && name !== "trivy" && !analyzerEnabled(flag)) {
+            dbg(`session_start ${name}: skipped (disabled by config)`);
+            recordDegradationOnce({
+                kind: "startup-analyzer-disabled",
+                subject: name,
+                reason: "skipped (disabled by config)",
+            });
+            return;
+        }
         if (skipHeavyweightScans)
             return;
-        runTask(name, task);
+        void runTask(name, task);
     };
     if (skipHeavyweightScans) {
         dbg(`session_start: skipping knip/jscpd/madge/dead-code/govulncheck/gitleaks/trivy/opengrep (${isSubagent ? "subagent" : "slow-fs"})`);
@@ -1239,7 +1262,7 @@ function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analy
     // racing its independently deferred timer. Otherwise a slow graph build leaves
     // `runtime.callGraph` unset at this task's start and loses the model for the
     // entire session (#1070).
-    runTask("codebase-model", async () => {
+    void runTask("codebase-model", async () => {
         await callGraphTask;
         if (!runtime.isCurrentSession(sessionGeneration))
             return;
@@ -1258,7 +1281,7 @@ function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analy
             `${model.totalTokens} tokens, top symbols: ${top3 || "(none)"}`);
     });
     // ast-grep — export scan for duplicate detection
-    runTask("ast-grep-exports", async () => {
+    void runTask("ast-grep-exports", async () => {
         if (await astGrepClient.ensureAvailable()) {
             if (!runtime.isCurrentSession(sessionGeneration))
                 return;
@@ -1275,7 +1298,7 @@ function scheduleStartupScansWithClients(deps, runtime, sessionGeneration, analy
     // word-index — identifier inverted index + BM25 for ranked symbol search
     // (#162). Load -> rebuild-if-stale -> persist lifecycle (#348), shared with
     // the quick-mode cold-start warmup pass below.
-    runTask("word-index", async () => {
+    void runTask("word-index", async () => {
         await buildOrRefreshWordIndex({
             runtime,
             sessionGeneration,
@@ -1339,17 +1362,16 @@ function scheduleDeferredToolProbesWithClients(deps, languageProfile, startupDef
 /**
  * Session-start orientation prepended as a context message (gated by the
  * context-injection toggle). Deliberately lean: it names the high-value tools
- * and the one non-obvious behaviour (mode=all resurfaces stale blocking errors)
+ * and the distinction between cached reporting and active verification
  * — per-tool argument detail lives in each tool's own registered description, so
  * re-documenting it here would just pay the tokens twice every session.
  */
 export const SESSION_START_GUIDANCE = [
     "📌 pi-lens active — automated checks run on every edit/write; blocking errors (including pre-existing) show inline and must be fixed.\n" +
         "Key tools (see each tool's own description for args):\n" +
-        "• lens_diagnostics — session-wide diagnostic state; mode=all resurfaces stale blocking errors that dropped from turn context.\n" +
+        "• lens_diagnostics — source=session reads cache; empty cache ≠ clean; use source=lsp scope=paths for changed files with absent or stale findings.\n" +
         "• symbol_search → module_report → read_symbol/read_enclosing — ranked identifier search, then navigable outline/callback handles + exact body reads; cheaper than reading a whole file before editing.\n" +
-        "• lsp_diagnostics — probe LSP for errors in a file/folder/workspace.\n" +
-        "• Situational (activate via pi_lens_activate_tools): lsp_navigation, ast_grep_search, ast_grep_replace, ast_grep_dump.",
+        "• Situational (activate via pi_lens_activate_tools): lsp_navigation, ast_grep_search, ast_grep_replace. Use ast_grep_search with dump=true to inspect AST nodes.",
 ];
 export async function handleSessionStart(deps) {
     resetDegradationLedger();
@@ -1423,7 +1445,7 @@ export async function handleSessionStart(deps) {
     //   entirely — but only when PI_LENS_STARTUP_MODE is unset in the env
     //   (an explicit env var still takes highest precedence).
     // Tunable: PI_LENS_WARMUP_DELAY_MS adjusts the warmup delay.
-    let startupMode = resolveStartupMode();
+    let startupMode = resolveStartupMode(deps.projectConfig, deps.globalConfig);
     // SAFETY: these two flags are process-lifetime state pi-lens stashes on
     // `globalThis` so a second extension instance in the same process sees the
     // first one's warmup. There is no ambient declaration for them, and adding
@@ -1433,7 +1455,9 @@ export async function handleSessionStart(deps) {
     const isFirstSessionOfProcess = !processGlobals.__piLensFirstSessionDone;
     if (isFirstSessionOfProcess &&
         process.env.PI_LENS_COLD_START_QUICK !== "0" &&
-        !process.env.PI_LENS_STARTUP_MODE) {
+        !process.env.PI_LENS_STARTUP_MODE &&
+        !deps.projectConfig?.startup?.mode &&
+        !deps.globalConfig?.startup?.mode) {
         // Apply host-provided override (e.g. MCP server forces "full") before
         // falling back to the TUI quick-mode heuristic.
         startupMode = deps.startupModeOverride ?? "quick";
@@ -1790,6 +1814,15 @@ export async function handleSessionStart(deps) {
     // #1123 item 3: a fresh session can re-report smells that a prior session
     // already surfaced once (see `checkSmellsAndNoteOnce`'s once-per-session gate).
     resetSmellsSessionState();
+    // #2800 item 8: the situational-tool dead-weight observation (which tools
+    // this session never activated or called) is session-scoped, so its sets
+    // and once-latch re-arm here beside the other registered resets. Both hosts
+    // open the session's row through startSituationalToolTelemetrySession()
+    // BEFORE this handler runs, and a repeated MCP session_start refresh
+    // legitimately re-runs this handler — so the reset only acts when no
+    // telemetry session is open; clearing a live session here would wipe the
+    // calls recorded before the refresh.
+    resetSituationalToolTelemetry();
     // #1782: re-arm the workspace-diagnostics cache session clock. Entries
     // written before this instant assert findings from a session that is over,
     // so they must revalidate before they can be served as current again.
@@ -2271,7 +2304,10 @@ export async function handleSessionStart(deps) {
     else {
         dbg("session_start: no language defaults selected for pre-install");
     }
-    const startupScansWillRun = allowBootstrapTasks && startupScan.canWarmCaches;
+    const startupScansEnabled = deps.projectConfig?.startup?.scans?.enabled ??
+        deps.globalConfig?.startup?.scans?.enabled ??
+        true;
+    const startupScansWillRun = allowBootstrapTasks && startupScan.canWarmCaches && startupScansEnabled;
     const jstsHeavyScansWillRun = startupScansWillRun && canRunStartupHeavyScans(languageProfile, "jsts");
     if (allowBootstrapTasks) {
         scheduleDeferredToolProbes(deps, languageProfile, startupDefaults, jstsHeavyScansWillRun, dbg);
@@ -2326,6 +2362,14 @@ export async function handleSessionStart(deps) {
     if (!allowBootstrapTasks) {
         dbg("session_start: skipping startup background scans (startup mode)");
     }
+    else if (!startupScansEnabled) {
+        dbg("session_start: skipping startup background scans (disabled by config)");
+        recordDegradationOnce({
+            kind: "startup-analyzer-disabled",
+            subject: "startup-scans",
+            reason: "skipped (disabled by config)",
+        });
+    }
     else if (!startupScan.canWarmCaches) {
         dbg(`session_start: skipping heavy scans (${startupScan.reason ?? "unknown"})`);
         dbg(`session_start: skipping TODO scan (${startupScan.reason ?? "unknown"})`);

package/node_modules/pi-lens/dist/clients/runtime-tool-call.js

@@ -773,7 +773,8 @@ async function handleToolCallImpl(deps) {
     // is the client's own answer, hoisted into `tree-sitter-shared.ts` where it
     // needs nothing but the extension registry; `ComplexityClient.isSupportedFile`
     // delegates to it, so this is not a second copy.
-    if (!isExternalOrVendor &&
+    if (!getFlag("no-complexity") &&
+        !isExternalOrVendor &&
         filePath &&
         !runtime.complexityBaselines.has(filePath) &&
         isComplexitySupportedFile(filePath)) {
@@ -803,6 +804,15 @@ async function handleToolCallImpl(deps) {
             });
         }
     }
+    else if (getFlag("no-complexity") &&
+        filePath &&
+        isComplexitySupportedFile(filePath)) {
+        recordDegradationOnce({
+            kind: "startup-analyzer-disabled",
+            subject: "complexity",
+            reason: "skipped (disabled by config)",
+        });
+    }
     // --- Read-Before-Edit Guard: check edits ---
     // write = full replacement; no prior read needed (you're starting fresh).
     // edit = partial modification; guard enforced to prevent blind overwrites.

package/node_modules/pi-lens/dist/clients/runtime-tool-result.js

@@ -21,7 +21,7 @@ import { replayThroughMutationBridge, storedLineHashesFor, } from "./observed-mu
 import { getAmbientAbortSignal } from "./safe-spawn.js";
 import { resolveToolCallCorrelationId } from "./tool-event.js";
 import { boundedIndexesForCount, createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent, } from "./read-guard-logger.js";
-import { notifyExternalFileChange } from "./lsp/index.js";
+import { notifyExternalFileChange, resyncGitChangedFiles, } from "./lsp/index.js";
 import { runPipeline } from "./pipeline.js";
 import { renderPostAutofixNotice, } from "./post-autofix-notice.js";
 import { syncGitGuardRecord } from "./git-guard.js";
@@ -897,6 +897,9 @@ export async function handleToolResult(deps) {
                     durationMs: Date.now() - started,
                     result: `changed:${opaquePaths.length}`,
                 });
+                void resyncGitChangedFiles(opaquePaths).catch((err) => {
+                    dbg(`git-change LSP resync failed: ${err}`);
+                });
             }
         }
         // wp iterates opaquePaths VERBATIM (already normalizeMapKey keys), so the