pi-lens 3.8.68 → 3.8.69

package/dist/clients/instance-reaper.js

@@ -15,7 +15,52 @@
  * a command-line marker fallback for the case where the pid itself was
  * recycled or the mid-tree pid link is broken (e.g. a dead node-wrapper whose
  * native-exe grandchild is still alive under a different, unrecorded pid).
+ *
+ * #525 root cause: a parent instance was ONLY ever considered dead via
+ * `isPidAlive(instance.pid)` — a raw `process.kill(pid, 0)` check. Unlike
+ * child pids (which get a command-line/marker identity check via
+ * `matchProcess` to guard against a recycled pid), the PARENT pid had no
+ * identity verification at all, because `InstanceEntry` never recorded the
+ * parent's own command line. Windows recycles pids far more aggressively than
+ * POSIX (no zombie/wait-reaping semantics holding a dead pid "reserved"), so
+ * over a long enough window (observed: ~13h) a dead parent's pid is very
+ * plausibly reassigned to a live, unrelated process — `isPidAlive` then
+ * (correctly, per its own conservative contract) reports "alive", and the
+ * stale instance is never reaped, no matter how old its heartbeat is.
+ *
+ * The #525 fix is deliberately ASYMMETRIC by consequence:
+ *
+ * - **Heartbeat staleness (`STALE_HEARTBEAT_MS`) cleans REGISTRY ENTRIES,
+ *   never kills.** A stale-heartbeat-but-pid-alive instance goes into
+ *   `staleInstances` (entry dropped from instances.json) with ZERO process
+ *   kills and its children still marker-protected. Why: the heartbeat call
+ *   sites are runtime-turn.ts (per turn end) and quiet-window.ts (per run
+ *   settle) ONLY — no timer exists. A pi session left OPEN but UNUSED
+ *   overnight fires neither, so its heartbeat legitimately goes >6h stale
+ *   while the session and its warm LSP fleet are genuinely alive. Killing on
+ *   staleness would take that fleet down under the idle session — and
+ *   `matchProcess` would NOT save it (its children really ARE that
+ *   instance's LSP servers; identity verification guards against pid reuse,
+ *   not against misclassifying a live parent). Removing just the entry is
+ *   safe: the idle session's next turn re-registers via `registerInstance`.
+ * - **Process kills require a pid-confirmed-DEAD parent** (`deadInstances`),
+ *   exactly as before #525. Only then are its children classified for
+ *   kill/marker-search.
+ *
+ * This still fixes both observed #525 cases: the 13h-stale test-fixture
+ * entry AND the recycled-parent-pid case (a dead parent whose pid now
+ * belongs to an unrelated live process — `isPidAlive` lies, but the stale
+ * heartbeat gets the ENTRY dropped, which is all the pollution fix needs).
  */
+/**
+ * A pid-ALIVE instance whose heartbeat is older than this gets its registry
+ * ENTRY removed — it is NEVER kill-eligible on staleness alone (see the
+ * module docstring's asymmetry note: an overnight-idle-but-alive session
+ * legitimately exceeds this threshold because heartbeats only fire at turn
+ * end / run settle, so staleness must clean records, not kill processes).
+ * 6 hours comfortably catches the observed 13h-stale pollution case.
+ */
+export const STALE_HEARTBEAT_MS = 6 * 60 * 60 * 1000;
 import { spawn as nodeSpawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -24,9 +69,39 @@ import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-reg
 import { logLatency } from "./latency-logger.js";
 const isWindows = process.platform === "win32";
 /**
- * Markers claimed by any LIVE instance's children. A marker search kills by
- * command-line match, so a marker that a live session also uses must never
- * be searched — killing it would take down the live session's server.
+ * KILL eligibility: pid-confirmed-dead ONLY. Heartbeat staleness must never
+ * make an instance kill-eligible — an overnight-idle-but-alive session
+ * legitimately goes >STALE_HEARTBEAT_MS stale (heartbeats fire only at turn
+ * end / run settle; no timer exists), and killing its genuine live LSP
+ * children would pass `matchProcess` identity verification (they really are
+ * that instance's servers — the matcher guards against pid reuse, not
+ * against misclassifying a live parent). See the module docstring (#525).
+ */
+function isInstanceKillEligible(instance, isPidAlive) {
+    return !isPidAlive(instance.pid);
+}
+/**
+ * REGISTRY-ENTRY staleness: heartbeat older than `STALE_HEARTBEAT_MS` (or
+ * unparseable — missing data must never keep a polluted entry alive
+ * forever). Drives entry removal ONLY, never kills (#525). This is what
+ * cleans the recycled-parent-pid case: `isPidAlive` lies for a long-dead
+ * parent whose pid the OS reassigned to an unrelated live process, but the
+ * stale heartbeat still gets the ENTRY dropped.
+ */
+function isInstanceEntryStale(instance, now) {
+    const heartbeatMs = Date.parse(instance.heartbeatAt);
+    if (Number.isNaN(heartbeatMs))
+        return true;
+    return now - heartbeatMs > STALE_HEARTBEAT_MS;
+}
+/**
+ * Markers claimed by any pid-ALIVE instance's children. A marker search
+ * kills by command-line match, so a marker that a live session also uses
+ * must never be searched — killing it would take down the live session's
+ * server. Protection is deliberately keyed on pid-liveness ALONE, regardless
+ * of heartbeat staleness (#525): a stale-heartbeat-but-alive instance (e.g.
+ * overnight-idle) must keep its children protected — protection stays
+ * conservative even where entry cleanup does not.
  * Markers are per-process-unique by construction (sgconfig.ts embeds the
  * pid), so this is defense in depth against non-unique markers ever
  * reappearing (#472: the original shared baseline.sgconfig.yml would have
@@ -89,23 +164,38 @@ function classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMa
  * @param matchProcess - optional identity verification (e.g. confirm the
  *   live pid's command line still matches what we recorded) to guard against
  *   a recycled pid coincidentally matching. If omitted, liveness alone is used.
+ * @param now - epoch ms "now", for heartbeat-staleness comparison (#525).
+ *   Injectable for deterministic tests; defaults to `Date.now()`. The two
+ *   signals are ASYMMETRIC by consequence: pid-confirmed-dead ⇒
+ *   `deadInstances` (kill-eligible + entry removal); pid-alive but heartbeat
+ *   older than `STALE_HEARTBEAT_MS` ⇒ `staleInstances` (entry removal ONLY —
+ *   never kills, never loses marker protection; the parent may be an
+ *   overnight-idle-but-alive session). See the module docstring.
  */
-export function decideOrphanReaping(registry, isPidAlive, matchProcess) {
+export function decideOrphanReaping(registry, isPidAlive, matchProcess, now = Date.now()) {
     const deadInstances = [];
+    const staleInstances = [];
     const childrenToKill = [];
     const markerSearches = [];
+    // Marker protection is pid-liveness ONLY — a stale-heartbeat-but-alive
+    // instance keeps its children protected (conservative on the kill side).
     const liveMarkers = collectLiveMarkers(registry, isPidAlive);
     for (const instance of registry) {
-        if (isPidAlive(instance.pid)) {
-            continue; // parent still alive — leave its children alone entirely
+        if (isInstanceKillEligible(instance, isPidAlive)) {
+            // pid-confirmed-dead: entry removal + children classified for kills.
+            deadInstances.push(instance);
+            classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, {
+                childrenToKill,
+                markerSearches,
+            });
         }
-        deadInstances.push(instance);
-        classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, {
-            childrenToKill,
-            markerSearches,
-        });
+        else if (isInstanceEntryStale(instance, now)) {
+            // pid-alive but stale heartbeat: record cleanup only — NO kills.
+            staleInstances.push(instance);
+        }
+        // else: alive + fresh heartbeat — leave it alone entirely.
     }
-    return { deadInstances, childrenToKill, markerSearches };
+    return { deadInstances, staleInstances, childrenToKill, markerSearches };
 }
 // --- Impure liveness / identity / kill helpers ---
 /** `process.kill(pid, 0)` liveness check: ESRCH ⇒ dead, anything else
@@ -362,10 +452,16 @@ export async function sweepOrphans() {
                 // best-effort — a failed marker search just misses that orphan this sweep
             }
         }
-        if (decision.deadInstances.length > 0) {
+        // Entry removal covers BOTH sets: pid-dead instances AND stale-heartbeat
+        // (pid-alive) instances — the latter is record cleanup only (#525);
+        // nothing belonging to a stale instance was killed above.
+        if (decision.deadInstances.length > 0 || decision.staleInstances.length > 0) {
             try {
-                const deadPids = new Set(decision.deadInstances.map((i) => i.pid));
-                await pruneDeadInstances(deadPids);
+                const prunePids = new Set([
+                    ...decision.deadInstances.map((i) => i.pid),
+                    ...decision.staleInstances.map((i) => i.pid),
+                ]);
+                await pruneDeadInstances(prunePids);
             }
             catch {
                 // best-effort — a stale registry entry is re-evaluated next sweep
@@ -379,6 +475,7 @@ export async function sweepOrphans() {
                 durationMs: Date.now() - startedAt,
                 metadata: {
                     deadInstances: decision.deadInstances.length,
+                    staleInstances: decision.staleInstances.length,
                     killed: killedCount,
                     serverIds: killedServerIds,
                     markerSearches: decision.markerSearches.length,
@@ -393,7 +490,8 @@ export async function sweepOrphans() {
         // The sweep must never throw out of session_start.
     }
 }
-/** Drop dead-parent instances from the registry. Re-reads immediately before
+/** Drop dead-parent AND stale-heartbeat (#525, record-cleanup-only)
+ *  instances from the registry. Re-reads immediately before
  *  writing (rather than reusing the earlier `readInstanceRegistry()` snapshot)
  *  to narrow — not eliminate — the last-writer-wins race already accepted for
  *  slice 1's read-modify-write model. */

package/dist/clients/jscpd-client.js

@@ -11,7 +11,7 @@ import * as fs from "node:fs";
 import { mkdtempSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getExcludedDirGlobs, getProjectIgnoreGlobs, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
+import { getExcludedDirGlobs, getGlobalPiLensDir, getProjectIgnoreGlobs, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
 import { findNodeToolBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 const EMPTY_RESULT = {
@@ -107,7 +107,7 @@ export class JscpdClient {
     async doEnsureAvailable() {
         // Fast path: check local install before any spawn
         const isWin = process.platform === "win32";
-        const localBase = path.join(os.homedir(), ".pi-lens", "tools", "node_modules", ".bin", "jscpd");
+        const localBase = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin", "jscpd");
         const localCandidates = isWin
             ? [`${localBase}.cmd`, `${localBase}.exe`, localBase]
             : [localBase];

package/dist/clients/lens-config.js

@@ -38,6 +38,10 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
         const contextInjection = contextInjectionRaw && typeof contextInjectionRaw === "object"
             ? contextInjectionRaw
             : undefined;
+        const turnSummaryRaw = raw.turnSummary;
+        const turnSummary = turnSummaryRaw && typeof turnSummaryRaw === "object"
+            ? turnSummaryRaw
+            : undefined;
         const formatMode = format?.mode === "immediate" || format?.mode === "deferred"
             ? format.mode
             : undefined;
@@ -93,6 +97,13 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
                         : undefined,
                 }
                 : undefined,
+            turnSummary: turnSummary
+                ? {
+                    enabled: typeof turnSummary.enabled === "boolean"
+                        ? turnSummary.enabled
+                        : undefined,
+                }
+                : undefined,
         };
     }
     catch {
@@ -114,6 +125,9 @@ export function getGlobalImmediateFormatDefault(configPath) {
 export function getGlobalContextInjectionEnabled(configPath) {
     return (loadPiLensGlobalConfig(configPath)?.contextInjection?.enabled !== false);
 }
+export function getGlobalTurnSummaryEnabled(configPath) {
+    return loadPiLensGlobalConfig(configPath)?.turnSummary?.enabled === true;
+}
 export function resolvePiLensFlag(name, value, config) {
     if (value)
         return value;
@@ -138,5 +152,8 @@ export function resolvePiLensFlag(name, value, config) {
     if (name === "no-lens-context") {
         return config?.contextInjection?.enabled === false;
     }
+    if (name === "lens-turn-summary") {
+        return config?.turnSummary?.enabled === true;
+    }
     return value;
 }

package/dist/clients/lens-engine.js

@@ -17,18 +17,19 @@ import { getDiagnosticTracker } from "./diagnostic-tracker.js";
 import { getLatencyReports, } from "./dispatch/integration.js";
 import { initLSPConfig } from "./lsp/config.js";
 import { getLSPService } from "./lsp/index.js";
+import { getOrLoadWarmWordIndex } from "./mcp/analyze.js";
 import { scanProjectDiagnostics } from "./project-diagnostics/scanner.js";
 import * as path from "node:path";
 import { normalizeMapKey } from "./path-utils.js";
 import { loadProjectSnapshot } from "./project-snapshot.js";
-import { centralityFromReverseDeps, deserializeWordIndex, searchWordIndex, } from "./word-index.js";
+import { centralityFromReverseDeps, deserializeWordIndex, searchWordIndex, triggerBackgroundWordIndexBuild, } from "./word-index.js";
 // --- Facades (re-exported so adapters import only this module) ---------------
 export { analyzeFile, } from "./mcp/analyze.js";
 export { createMcpHost } from "./mcp/host-shim.js";
 export { ipcPathForCwd, requestWarmAnalyze, } from "./mcp/ipc.js";
 export { analyzeFileFresh, resolveRebuildScript, runRebuild, summarizeScan, } from "./mcp/review.js";
 export { runSessionStart, runTurnEnd, } from "./mcp/session.js";
-export { moduleReport, readSymbol, } from "./module-report.js";
+export { moduleReport, readEnclosing, readSymbol, renderCompactModuleReport, } from "./module-report.js";
 // --- Query wrappers (own the remaining internal reach-ins) -------------------
 /** Recent dispatch latency reports (latency.log schema), newest first. */
 export function recentLatency(limit = 5, fileFilter) {
@@ -56,24 +57,57 @@ export function diagnosticStats() {
 export function ensureLspConfig(cwd) {
     return initLSPConfig(cwd);
 }
+function toSymbolSearchHit(result) {
+    const line = result.lines[0] ?? 1;
+    return {
+        file: result.file,
+        score: result.score,
+        hits: result.hits,
+        startLine: line,
+        endLine: line,
+    };
+}
 /**
- * Ranked identifier search over the persisted word index (#162). Stateless:
- * loads the index from the project snapshot (built by the session scan, in
- * either the pi extension or the MCP session), so it works without a warm
- * runtime. Returns `available: false` when no index exists yet.
+ * Ranked identifier search over the persisted word index (#162). Mostly
+ * stateless: loads the index from the project snapshot (built by the session
+ * scan, in either the pi extension or the MCP session), so it works without a
+ * warm runtime. Returns `available: false` when no index exists yet — and
+ * kicks off a single bounded background build for this workspace (deduped per
+ * cwd, never blocking this call) so a retry shortly after succeeds (#348
+ * decision 3).
+ *
+ * #536 rider: prefers the warm in-memory index (`getOrLoadWarmWordIndex`,
+ * clients/mcp/analyze.ts) over a fresh disk read when one exists for this
+ * cwd — a warm `pilens_analyze` call updates that live copy synchronously but
+ * persists it to disk on a debounce (default 1500ms), so without this a query
+ * immediately following an analyze in the SAME process would read stale
+ * on-disk state until the debounce flushes. Falls back to the stateless disk
+ * read exactly as before when no warm copy is cached (nothing has called
+ * pilens_analyze yet this process, or #348 phase 2's forward-index isn't
+ * available) — this function's public contract (available/hint/results shape)
+ * is unchanged either way.
  */
 export function symbolSearch(query, cwd, limit = 20) {
     const snapshot = loadProjectSnapshot(cwd);
-    const index = deserializeWordIndex(snapshot?.wordIndex);
-    if (!index)
-        return { available: false, query, results: [] };
+    const index = getOrLoadWarmWordIndex(cwd) ?? deserializeWordIndex(snapshot?.wordIndex);
+    if (!index) {
+        triggerBackgroundWordIndexBuild(cwd);
+        return {
+            available: false,
+            query,
+            results: [],
+            hint: "Word index is building in the background for this workspace — retry this query shortly.",
+        };
+    }
     // Boost well-connected files using the snapshot's reverse-dependency
     // (importedBy) counts; snapshot keys are normalized, index keys are raw.
     const centrality = centralityFromReverseDeps(index, snapshot?.reverseDeps, (file) => normalizeMapKey(path.resolve(file)));
+    const results = searchWordIndex(index, query, { limit, centrality });
     return {
         available: true,
         query,
-        results: searchWordIndex(index, query, { limit, centrality }),
+        results: results.map(toSymbolSearchHit),
+        snapshotGeneratedAt: snapshot?.generatedAt,
     };
 }
 // symbolImpact was removed (#304 follow-up): the transitive blast radius is now

package/dist/clients/lsp/cascade-tier.js

@@ -0,0 +1,254 @@
+/**
+ * Tier-aware cascade-lane wait policy (#458, re-scope №2).
+ *
+ * The cascade/deferred lane (`computeCascadeForFile`'s neighbor-touch fan-out
+ * in `clients/dispatch/integration.ts`) actively opens neighbor files against
+ * their LSP client and waits up to a per-touch budget (~1000ms cold-snapshot /
+ * 2000ms warm) for `textDocument/publishDiagnostics` before deciding the
+ * neighbor is clean. For a Tier-3 server — one that is `push-only` AND known
+ * to publish NOTHING on a clean→clean transition (see
+ * docs/lsp-capability-matrix.md; today that's typescript-language-server, the
+ * lone core-set instance) — that wait can never distinguish "clean" from
+ * "still analyzing"; it always burns its full budget. Dogfooding measured
+ * ~221 such `lsp_diagnostics_timeout` events/day.
+ *
+ * pi 0.80.6's `agent_settled` quiet window (#483, `clients/quiet-window.ts`)
+ * gives the cascade lane a place to resolve that ambiguity OUT of the
+ * per-touch budget: fire the touch (didOpen/didChange still happens, so the
+ * server starts real work), record it as outstanding, and reconcile against
+ * whatever landed in the client's diagnostics cache by the time the agent run
+ * goes idle. A touch nothing arrived for by then is recorded `unresolved` —
+ * never silently treated as `clean` (the #240 doctrine: a missing answer is
+ * not an affirmative answer).
+ *
+ * This module is deliberately NOT hardcoded to server names for the "should
+ * this file skip its in-lane wait" question: it reads the live capability
+ * snapshot's `workspaceDiagnosticsSupport.mode` (from
+ * `detectWorkspaceDiagnosticsSupport`, cached at `initialize`) and combines it
+ * with the `silentOnClean` marker on that server's `DiagnosticStrategy`
+ * (`server-strategies.ts`) — the same per-server behavioral-knowledge table
+ * the rest of the LSP layer already uses. A server with no live snapshot yet,
+ * or whose mode isn't `push-only`, or that isn't marked `silentOnClean`, is
+ * NOT tier-3 — the caller keeps today's full in-lane wait. Fail-safe is
+ * always "wait like before".
+ *
+ * #524/#529/#541: a server id can now be backed by more than one actual
+ * binary — "typescript" is classic typescript-language-server OR TS7's
+ * native `tsc --lsp --stdio` (PR #526). PR #526 initially routed the
+ * native-ts7 variant through the fail-safe "waits" path because
+ * `silentOnClean` had only been measured against the classic server. The
+ * #529/#540 clean-signal probe (`scripts/probe-clean-signal.mjs`) has since
+ * measured native-ts7 directly (2026-07-11, `typescript7-clean` fixture,
+ * repeated local runs): silent on clean transitions, same as classic. Per
+ * the maintainer's decision (2026-07-11, prefer fast cascade waits),
+ * `silentOnClean` now applies to BOTH variants — the snapshot's
+ * `launchVariant` marker is no longer consulted here. The safety net for a
+ * future TS7 build that starts publishing on clean is the nightly
+ * clean-signal drift check (#529/#540/#541), which now compares native rows
+ * against this marker too and emits a `marked-not-silent` warning if they
+ * diverge.
+ */
+import { logCascade } from "../cascade-logger.js";
+import { logLatency } from "../latency-logger.js";
+import { normalizeMapKey } from "../path-utils.js";
+import { registerQuietWindowTask } from "../quiet-window.js";
+import { getServersForFileWithConfig } from "./config.js";
+import { getStrategy } from "./server-strategies.js";
+// --- Kill switch (lazy, memoized — house style per clients/runtime-config.ts /
+// clients/quiet-window.ts's isQuietWindowEnabled) ---
+let _enabledCache;
+/** `PI_LENS_TIER_AWARE_CASCADE=0` disables the whole feature: every cascade
+ * touch waits in-lane exactly as it did before #458, no outstanding-touch
+ * bookkeeping, no reconcile task registered. */
+export function isTierAwareCascadeEnabled() {
+    if (_enabledCache !== undefined)
+        return _enabledCache;
+    _enabledCache = process.env.PI_LENS_TIER_AWARE_CASCADE !== "0";
+    return _enabledCache;
+}
+/** Test-only: clear the memoized kill-switch read. */
+export function _resetTierAwareCascadeEnabledForTests() {
+    _enabledCache = undefined;
+}
+/**
+ * Classify whether `filePath`'s PRIMARY language server is a cascade-lane
+ * Tier-3 (push-only, silent-on-clean) server. Ambiguous or missing capability
+ * data is always `"waits"` (today's behavior) — this function must never be
+ * the reason a real answer gets missed.
+ */
+export function classifyCascadeWaitTier(lspService, filePath, snapshots) {
+    void lspService; // kept in the signature for call-site clarity/typing only
+    const servers = getServersForFileWithConfig(filePath).filter((s) => s.role !== "auxiliary");
+    const primary = servers[0];
+    if (!primary)
+        return "waits";
+    const snapshot = snapshots.find((s) => s.serverId === primary.id);
+    if (!snapshot)
+        return "waits"; // no live snapshot yet — fail-safe
+    const mode = snapshot.workspaceDiagnosticsSupport?.mode;
+    if (mode !== "push-only")
+        return "waits"; // pull servers are always affirmative
+    const strategy = getStrategy(primary.id);
+    if (strategy.silentOnClean !== true)
+        return "waits"; // 2*/unknown push-only
+    // #524/#529/#541: `silentOnClean` on a server-id-keyed strategy used to be
+    // proven only against the classic variant; the native-ts7 `tsc --lsp
+    // --stdio` binary is now probe-measured silent too (#529/#540, 2026-07-11),
+    // so it inherits the same verdict as classic — no `launchVariant` branch
+    // needed here anymore. The nightly clean-signal drift check is the
+    // regression watch if a future TS7 build changes this.
+    return "tier3-silent";
+}
+// Keyed by normalized file path. A later touch for the same file simply
+// replaces the earlier entry (only the most recent touch matters — an
+// older touch's diagnostics, if they ever arrive, are still a strict superset
+// concern the newer touch already re-supersedes via didOpen/didChange).
+const _outstandingTouches = new Map();
+/**
+ * Record a Tier-3 cascade touch that skipped its in-lane wait. Called right
+ * after the (still-performed) didOpen/didChange notify, before returning
+ * without waiting. `touchedAt` must be sampled BEFORE the notify (see the
+ * field doc) so the reconcile comparison can never misread a publish that
+ * raced the record as pre-touch.
+ */
+export function recordOutstandingCascadeTouch(entry) {
+    _outstandingTouches.set(normalizeMapKey(entry.filePath), entry);
+}
+/** Test-only: clear the outstanding-touch registry between test cases. */
+export function _resetOutstandingCascadeTouchesForTests() {
+    _outstandingTouches.clear();
+}
+/** Test-only: peek at the registry without mutating it. */
+export function _getOutstandingCascadeTouchesForTests() {
+    return [..._outstandingTouches.values()];
+}
+/**
+ * Reconcile every outstanding Tier-3 touch against the LSP client's current
+ * diagnostics cache. For each:
+ *   - If the client holds a PER-FILE diagnostics entry for the touched file
+ *     whose publish timestamp (`getAllDiagnostics()`'s `ts` — the max of the
+ *     push/pull timestamps for that file, client.ts) is newer than the
+ *     touch's pre-notify `touchedAt`, something published for THAT FILE since
+ *     the touch — record `resolved-found` (diagnostics present) or
+ *     `resolved-clean` (empty, but PROVEN empty by an actual publish for that
+ *     file after the touch). A client-WIDE signal is deliberately not used:
+ *     it advances on any file's publish, so it could falsely "prove" a silent
+ *     neighbor clean when a sibling neighbor published (#240).
+ *   - If nothing published for the file by settle time, record `unresolved` —
+ *     per the #240 doctrine this is NEVER treated as clean.
+ *
+ * Client lookup is WARM-ONLY (`getWarmClientForFile`): the quiet window must
+ * never resurrect an idle-reaped server (a full tsserver spawn + cold index)
+ * just to write a log line. A warm-miss ⇒ `unresolved`.
+ *
+ * Always drains the whole registry (each entry is independently resolved;
+ * one entry's client lookup failing doesn't block the rest) and never
+ * throws — callers (the quiet-window task) must be fail-safe.
+ */
+export async function reconcileOutstandingCascadeTouches(lspService) {
+    const outcomes = [];
+    const entries = [..._outstandingTouches.entries()];
+    _outstandingTouches.clear();
+    for (const [key, touch] of entries) {
+        const ageMs = Date.now() - touch.touchedAt;
+        try {
+            const spawned = await lspService.getWarmClientForFile(touch.filePath);
+            if (!spawned || spawned.client.serverId !== touch.serverId) {
+                outcomes.push({
+                    filePath: touch.filePath,
+                    serverId: touch.serverId,
+                    outcome: "unresolved",
+                    ageMs,
+                });
+                continue;
+            }
+            const entry = spawned.client
+                .getAllDiagnostics()
+                .get(normalizeMapKey(touch.filePath));
+            if (!entry || entry.ts <= touch.touchedAt) {
+                // No per-file publish since the touch (or ever) — a missing answer
+                // is not a clean answer.
+                outcomes.push({
+                    filePath: touch.filePath,
+                    serverId: touch.serverId,
+                    outcome: "unresolved",
+                    ageMs,
+                });
+                continue;
+            }
+            outcomes.push({
+                filePath: touch.filePath,
+                serverId: touch.serverId,
+                outcome: entry.diags.length > 0 ? "resolved-found" : "resolved-clean",
+                ageMs,
+                diagnosticCount: entry.diags.length,
+            });
+        }
+        catch (err) {
+            outcomes.push({
+                filePath: touch.filePath,
+                serverId: touch.serverId,
+                outcome: "unresolved",
+                ageMs,
+            });
+            logLatency({
+                type: "phase",
+                phase: "cascade_tier3_reconcile_error",
+                filePath: key,
+                durationMs: 0,
+                metadata: { error: String(err) },
+            });
+        }
+    }
+    return outcomes;
+}
+let _reconcileTaskRegistered = false;
+/**
+ * Register the Tier-3 reconcile task with the quiet-window scheduler
+ * (`clients/quiet-window.ts`). Idempotent — safe to call more than once
+ * (e.g. multiple extension activations in tests).
+ */
+export function registerCascadeTierReconcileTask(getLspService) {
+    if (_reconcileTaskRegistered)
+        return;
+    _reconcileTaskRegistered = true;
+    registerQuietWindowTask("cascade_tier3_reconcile", async () => {
+        if (!isTierAwareCascadeEnabled())
+            return;
+        if (_outstandingTouches.size === 0)
+            return;
+        const outcomes = await reconcileOutstandingCascadeTouches(getLspService());
+        if (outcomes.length === 0)
+            return;
+        let resolvedFound = 0;
+        let resolvedClean = 0;
+        let unresolved = 0;
+        let ageSumMs = 0;
+        for (const o of outcomes) {
+            if (o.outcome === "resolved-found")
+                resolvedFound++;
+            else if (o.outcome === "resolved-clean")
+                resolvedClean++;
+            else
+                unresolved++;
+            ageSumMs += o.ageMs;
+        }
+        const avgAgeMs = Math.round(ageSumMs / outcomes.length);
+        logCascade({
+            phase: "cascade_tier3_reconcile",
+            filePath: "<quiet-window>",
+            metadata: {
+                count: outcomes.length,
+                resolvedFound,
+                resolvedClean,
+                unresolved,
+                avgAgeMs,
+                outcomes,
+            },
+        });
+    });
+}
+/** Test-only: undo registerCascadeTierReconcileTask's idempotency guard. */
+export function _resetCascadeTierReconcileRegistrationForTests() {
+    _reconcileTaskRegistered = false;
+}

package/dist/clients/lsp/client.js

@@ -934,7 +934,7 @@ async function resolveCodeActionBestEffort(state, action) {
 // --- Client Factory ---
 export async function createLSPClient(options) {
     installCrashGuard();
-    const { serverId, process: lspProcess, root, initialization, initializeTimeoutMs = INITIALIZE_TIMEOUT_MS, } = options;
+    const { serverId, process: lspProcess, root, initialization, initializeTimeoutMs = INITIALIZE_TIMEOUT_MS, launchVariant, } = options;
     // #449/#472: register this LSP child in the cross-process instance registry
     // as soon as we have a live pid — BEFORE `initialize` completes, not after.
     // Registering early means a child that dies/hangs during initialize (the
@@ -1044,6 +1044,7 @@ export async function createLSPClient(options) {
         advertisedCommands: new Set(),
         serverEditsAllowed: 0,
         serverId,
+        launchVariant,
         root,
         lspProcess,
         // two-phase: the flush closure needs `state` (below)
@@ -1206,6 +1207,9 @@ export async function createLSPClient(options) {
         getRawCapabilityKeys() {
             return state.rawCapabilityKeys ?? [];
         },
+        getLaunchVariant() {
+            return state.launchVariant;
+        },
         async executeCommand(command, args) {
             return runServerCommand(state, command, args);
         },

package/dist/clients/lsp/index.js

@@ -611,6 +611,7 @@ export class LSPService {
                 root,
                 initialization: mergedInit,
                 initializeTimeoutMs: server.initializeTimeoutMs,
+                launchVariant: spawned.launchVariant,
             });
             const wsDiag = typeof client.getWorkspaceDiagnosticsSupport === "function"
                 ? client.getWorkspaceDiagnosticsSupport()
@@ -1245,6 +1246,7 @@ export class LSPService {
                     workspaceDiagnosticsSupport: client.getWorkspaceDiagnosticsSupport(),
                     advertisedCommands: client.getAdvertisedCommands(),
                     rawCapabilityKeys: client.getRawCapabilityKeys?.() ?? [],
+                    launchVariant: client.getLaunchVariant?.(),
                 });
             }
             return snapshots;
@@ -1261,6 +1263,7 @@ export class LSPService {
                 workspaceDiagnosticsSupport: client.getWorkspaceDiagnosticsSupport(),
                 advertisedCommands: client.getAdvertisedCommands(),
                 rawCapabilityKeys: client.getRawCapabilityKeys?.() ?? [],
+                launchVariant: client.getLaunchVariant?.(),
             });
         }
         return snapshots;

package/dist/clients/lsp/server-strategies.js

@@ -74,6 +74,16 @@ export const SERVER_DIAGNOSTIC_STRATEGIES = {
         debounceMs: 50,
         aggregateWaitMs: 1000,
         expectSemanticSecondPush: false,
+        // Tier 3 (#458): typescript-language-server publishes nothing on a
+        // clean→clean edit (docs/lsp-capability-matrix.md). Measured for the
+        // classic server manually (2026-07-08) AND for TS7's native
+        // `tsc --lsp --stdio` variant (PR #526) via the #529/#540
+        // clean-signal probe (2026-07-11, `typescript7-clean` fixture) —
+        // both silent. It's the lone core-set tier-3 server, which is
+        // exactly why the cascade lane's in-lane wait is worth skipping for
+        // it specifically. Applies to BOTH variants (#541); the nightly
+        // clean-signal drift check is the regression watch.
+        silentOnClean: true,
     },
     "rust-analyzer": {
         seedFirstPush: false,