pi-lens 4.3.0 → 4.4.0

package/dist/clients/lsp/workspace-sweep-hold.js

@@ -1,184 +0,0 @@
-/**
- * #1618: a full workspace sweep (`LSPService.runWorkspaceDiagnostics`, the
- * engine behind `lens_diagnostics mode=full`) grants itself a wall-clock
- * ceiling (`FULL_SCAN_WALL_CLOCK_MS`, see {@link getFullScanWallClockMs})
- * that can outlive the detached LSP idle-reset timer armed by
- * `clients/runtime-turn.ts`'s `handleTurnEnd` on a file-less turn. Nothing
- * previously stopped that timer from firing mid-sweep and destroying the
- * very service the sweep was actively touching — every file the sweep had
- * not yet reached then failed with zero trace and got mislabeled as budget
- * exhaustion.
- *
- * This module is the shared hold: `runWorkspaceDiagnostics` acquires it for
- * its own lifetime (try/finally, so a throw or an aborted sweep still
- * releases it) and the idle-reset timer consults it before firing. Holds are
- * tracked as TOKENS (acquire-time-stamped), not a bare counter — two
- * overlapping `lens_diagnostics mode=full` calls (or a sweep started while
- * another is still finishing) must each be free to release independently
- * without the other's hold being dropped early.
- *
- * A leaked hold that never re-arms idle reset is the inverse defect (state
- * that must re-arm cannot hide behind a stuck guard), so this module screens
- * against it on TWO axes, matching the repo's own session-boundary +
- * bounded-lifetime conventions:
- *   1. `clearWorkspaceSweepHoldForSessionStart` — `resetLSPService({reason:
- *      "session_start"})` clears every held token unconditionally. A session
- *      boundary means no in-flight sweep from a PRIOR generation is still
- *      meaningful to wait on.
- *   2. `reapStaleHolds` (internal, called from every liveness check) —
- *      force-releases any token older than {@link getWorkspaceSweepMaxHoldAgeMs},
- *      derived from the sweep's own wall-clock ceiling plus a safety margin.
- *      A real sweep is either done or self-aborted well within that window
- *      (`tools/lens-diagnostics.ts` races `FULL_SCAN_WALL_CLOCK_MS`), so a
- *      token still held past it can only be a bug — never a legitimate long
- *      sweep — and gets force-released with its own distinct log record.
- *
- * `getFullScanWallClockMs` also lives here (rather than duplicated between
- * `tools/lens-diagnostics.ts` and `clients/runtime-turn.ts`) so the idle-reset
- * delay on every path (base AND the subagent/budget-shortened paths) can be
- * DERIVED from the sweep's own ceiling instead of the constants drifting
- * apart again (#1618 acceptance criterion 6).
- */
-import { logLatency } from "../latency-logger.js";
-import { getProcessSingleton } from "../process-singletons.js";
-/** Extra headroom beyond the sweep's own wall-clock ceiling before an
- *  idle-reset delay (or the max-hold-age failsafe) trusts that a real sweep
- *  must be done. Single source for both derivations below AND for every
- *  idle-reset path `clients/runtime-turn.ts` derives (base, subagent, and
- *  budget-shortened) — never a second independently-tunable literal. */
-export const SWEEP_IDLE_SAFETY_MARGIN_MS = 60_000;
-const WORKSPACE_SWEEP_HOLD_FAMILY = "lsp.workspace-sweep-hold";
-const WORKSPACE_SWEEP_HOLD_VERSION = 1;
-function state() {
-    return getProcessSingleton(WORKSPACE_SWEEP_HOLD_FAMILY, WORKSPACE_SWEEP_HOLD_VERSION, () => ({ holds: new Map(), nextHoldId: 1, idleWaiters: [] }));
-}
-function flushIdleWaitersIfEmpty() {
-    const current = state();
-    if (current.holds.size > 0)
-        return;
-    if (current.idleWaiters.length === 0)
-        return;
-    const waiters = current.idleWaiters;
-    current.idleWaiters = [];
-    for (const waiter of waiters) {
-        try {
-            waiter();
-        }
-        catch {
-            // Best-effort — a waiter failure must never propagate into the
-            // releasing/reaping call stack.
-        }
-    }
-}
-/**
- * A held token past this age can only be a bug (leaked release, a sweep that
- * hung outside its own abort signal, …) — a legitimate sweep is done or
- * self-aborted well before it. Derived, not a separate literal, so it can't
- * drift out of sync with `getFullScanWallClockMs` the way the idle-reset
- * timer and the sweep's own ceiling once did.
- */
-export function getWorkspaceSweepMaxHoldAgeMs() {
-    return getFullScanWallClockMs() + SWEEP_IDLE_SAFETY_MARGIN_MS;
-}
-function reapStaleHolds() {
-    const current = state();
-    if (current.holds.size === 0)
-        return;
-    const maxAgeMs = getWorkspaceSweepMaxHoldAgeMs();
-    const now = Date.now();
-    for (const [holdId, acquiredAt] of current.holds) {
-        const ageMs = now - acquiredAt;
-        if (ageMs <= maxAgeMs)
-            continue;
-        current.holds.delete(holdId);
-        logLatency({
-            type: "phase",
-            phase: "lsp_workspace_sweep_hold_force_released",
-            filePath: "",
-            durationMs: ageMs,
-            metadata: { holdId, maxHoldAgeMs: maxAgeMs },
-        });
-    }
-    flushIdleWaitersIfEmpty();
-}
-/**
- * Acquire the hold for one `runWorkspaceDiagnostics` call. Returns a release
- * function; callers MUST call it from a `finally` block so an overlapping or
- * throwing sweep still releases its hold. Idempotent — calling the returned
- * function more than once past the first call, or after the hold was already
- * force-released (session reset / max-age reap), is a no-op.
- */
-export function acquireWorkspaceSweepHold() {
-    const current = state();
-    const holdId = current.nextHoldId++;
-    current.holds.set(holdId, Date.now());
-    return () => {
-        if (!state().holds.delete(holdId))
-            return;
-        flushIdleWaitersIfEmpty();
-    };
-}
-/** True while at least one `runWorkspaceDiagnostics` sweep is in flight.
- *  Reaps stale holds first, so a leaked/hung hold can't permanently read as
- *  "active" past its own max age. */
-export function isWorkspaceSweepActive() {
-    reapStaleHolds();
-    return state().holds.size > 0;
-}
-/**
- * Run `cb` once the hold count next returns to zero. Runs synchronously and
- * immediately when no sweep is active right now — the common case, and the
- * one every non-sweep idle-reset arm/fire takes.
- */
-export function runWhenWorkspaceSweepIdle(cb) {
-    reapStaleHolds();
-    const current = state();
-    if (current.holds.size === 0) {
-        cb();
-        return;
-    }
-    current.idleWaiters.push(cb);
-}
-/**
- * `resetLSPService({reason: "session_start"})` calls this: a session
- * boundary means no hold from a PRIOR generation is still meaningful to wait
- * on, so every held token is cleared unconditionally (state that must
- * re-arm at session_start cannot hide behind a leaked/stuck guard from the
- * generation before it). Only logs when there was actually something to
- * clear — the common case (no sweep in flight at session boundary) stays
- * silent.
- */
-export function clearWorkspaceSweepHoldForSessionStart() {
-    const current = state();
-    if (current.holds.size === 0)
-        return;
-    logLatency({
-        type: "phase",
-        phase: "lsp_workspace_sweep_hold_session_reset",
-        filePath: "",
-        durationMs: 0,
-        metadata: { clearedHolds: current.holds.size },
-    });
-    current.holds.clear();
-    flushIdleWaitersIfEmpty();
-}
-/** Test-only: reset the process-singleton hold state between tests. */
-export function _resetWorkspaceSweepHoldForTests() {
-    const current = state();
-    current.holds.clear();
-    current.idleWaiters = [];
-    current.nextHoldId = 1;
-}
-/**
- * Wall-clock ceiling for one `lens_diagnostics mode=full` scan
- * (`runWorkspaceDiagnostics` plus its concurrent project-runner/analyzer
- * work). Single source for `tools/lens-diagnostics.ts` (the sweep caller),
- * `clients/runtime-turn.ts` (every idle-reset path, whose delay must outlive
- * it), and this module's own max-hold-age failsafe — lazy env read, never
- * memoized, matching this codebase's house style so a test can flip the
- * override mid-run.
- */
-export function getFullScanWallClockMs() {
-    const raw = Number(process.env.PI_LENS_LENS_DIAGNOSTICS_FULL_TIMEOUT_MS);
-    return Number.isFinite(raw) && raw > 0 ? raw : 300_000; // 5 min default
-}

package/dist/clients/lsp-budget.js

@@ -1,186 +0,0 @@
-/**
- * Cross-process LSP budget (#449 slice 2 — PROTOTYPE).
- *
- * Slice 1 (#472/#474/#475, `clients/instance-registry.ts` +
- * `clients/instance-reaper.ts`) made every concurrent pi-lens process visible
- * to every other one via `~/.pi-lens/instances.json`. This module is the
- * first thing that DOES something with that visibility: a machine-wide cap
- * on total live LSP server processes. When a NEW session starts and the
- * machine is already over budget, it degrades its OWN spawn plan — it never
- * touches another instance's already-running servers.
- *
- * Deliberately NOT a clearinghouse: no negotiation, no reservation, no
- * cross-process locking. Each session reads the registry once at
- * `session_start`, decides locally, and moves on — a "position limit," per
- * the issue's own framing, not shared ownership of anyone else's servers.
- *
- * Degrade mechanism chosen for this first slice: skip spawning AUXILIARY LSP
- * servers (role:"auxiliary" in clients/lsp/server.ts — opengrep, ast-grep,
- * zizmor, typos, marksman) for the remainder of THIS session, keeping only
- * the primary language server per file. Auxiliaries are cross-cutting
- * scanners layered on top of (not required for) core diagnostics, so this is
- * the cheapest, highest-signal thing to shed under machine-wide pressure.
- * The cached decision also shortens this session's idle reset and lets
- * pull-capable servers skip their push fallback. All three degrade mechanisms
- * read the same session-boundary snapshot; pressure never changes mid-touch.
- *
- * Ceiling default (`DEFAULT_LSP_BUDGET_CEILING = 16`): a rough RAM-budget
- * back-of-envelope, not a measured figure (#620's CPU/RSS sampling had not
- * landed as of this prototype) — assume ~250MB average RSS per live LSP
- * child process (typescript-language-server/pyright cold-index spikes
- * higher, short-lived auxiliaries like typos-lsp are much lighter, so this
- * is a rough blend) against a soft target of ~4GB machine-wide dedicated to
- * the LSP fleet: 4000MB / 250MB ≈ 16. Deliberately conservative-permissive
- * for a first cut — the goal is to catch the "25 concurrent node.exe, several
- * at 600MB-2GB RSS" pathological pile-up this was written in response to
- * (dogfooding note, 2026-07-12/13), not to micromanage the common 2-4-agent
- * case. `PI_LENS_LSP_BUDGET_CEILING` overrides it once real-world data (#620)
- * says otherwise.
- *
- * Kill switch: `PI_LENS_CROSS_PROCESS_BUDGET=0` disables this module
- * entirely (every session always spawns its full fleet, today's behavior) —
- * lazy env read, never memoized, matching the house style
- * (session-lifecycle.ts / runtime-config.ts).
- */
-import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.js";
-import { realIsPidAlive, STALE_HEARTBEAT_MS } from "./instance-reaper.js";
-import { logLatency } from "./latency-logger.js";
-/** See the module docstring for the derivation. */
-export const DEFAULT_LSP_BUDGET_CEILING = 16;
-export const DEFAULT_LSP_BUDGET_IDLE_TIMEOUT_MS = 60_000;
-/** `PI_LENS_CROSS_PROCESS_BUDGET=0` disables the budget check entirely —
- *  lazy env read (house style), never memoized so tests can flip it mid-run. */
-export function isCrossProcessBudgetEnabled() {
-    return process.env.PI_LENS_CROSS_PROCESS_BUDGET !== "0";
-}
-/** `PI_LENS_LSP_BUDGET_CEILING` overrides {@link DEFAULT_LSP_BUDGET_CEILING}.
- *  Non-finite/non-positive overrides are ignored (NaN-guard house style, see
- *  clients/runtime-config.ts) — falls back to the default rather than
- *  silently producing a ceiling of 0 (which would degrade every session). */
-export function getLspBudgetCeiling() {
-    const raw = Number(process.env.PI_LENS_LSP_BUDGET_CEILING);
-    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LSP_BUDGET_CEILING;
-}
-/** Optional aggregate host + LSP-child RSS ceiling. Undefined means disabled. */
-export function getLspBudgetRssCeilingBytes() {
-    const raw = Number(process.env.PI_LENS_LSP_BUDGET_RSS_MB);
-    return Number.isFinite(raw) && raw > 0 ? raw * 1024 * 1024 : undefined;
-}
-export function getLspBudgetIdleTimeoutMs() {
-    const raw = Number(process.env.PI_LENS_LSP_BUDGET_IDLE_TIMEOUT_MS);
-    return Number.isFinite(raw) && raw > 0
-        ? raw
-        : DEFAULT_LSP_BUDGET_IDLE_TIMEOUT_MS;
-}
-/**
- * PURE decision function — no I/O. Mirrors `decideOrphanReaping`'s shape
- * (clients/instance-reaper.ts) for the same reason: injectable liveness
- * predicate, fully unit-testable with fake registry data, zero real
- * process.kill/spawn/fs calls.
- *
- * Liveness is counted, not just registry presence, because a dead-parent
- * instance's `lspChildren` entries are exactly the orphan reaper's target —
- * counting them here would double-penalize new sessions for load that's
- * already being cleaned up (or was already cleaned up and the entry just
- * hasn't been pruned from this snapshot yet).
- */
-export function decideLspBudget(registry, isPidAlive, ceiling, rssCeilingBytes, now = Date.now()) {
-    const liveInstances = registry.filter((instance) => isPidAlive(instance.pid));
-    const totalLiveLspServers = liveInstances.reduce((sum, instance) => sum + instance.lspChildren.length, 0);
-    const hasCompleteFreshSamples = rssCeilingBytes !== undefined &&
-        liveInstances.length > 0 &&
-        liveInstances.every((instance) => {
-            const heartbeatMs = Date.parse(instance.heartbeatAt);
-            return (Number.isFinite(heartbeatMs) &&
-                now - heartbeatMs <= STALE_HEARTBEAT_MS &&
-                Number.isFinite(instance.rssBytes) &&
-                instance.lspChildren.every((child) => Number.isFinite(child.rssBytes)));
-        });
-    const totalRssBytes = hasCompleteFreshSamples
-        ? liveInstances.reduce((sum, instance) => sum +
-            instance.rssBytes +
-            instance.lspChildren.reduce((childSum, child) => childSum + (child.rssBytes ?? 0), 0), 0)
-        : undefined;
-    const rssPressure = totalRssBytes !== undefined &&
-        rssCeilingBytes !== undefined &&
-        totalRssBytes >= rssCeilingBytes;
-    const overBudget = totalLiveLspServers >= ceiling || rssPressure;
-    return {
-        totalLiveLspServers,
-        ceiling,
-        totalRssBytes,
-        rssCeilingBytes,
-        rssPressure,
-        overBudget,
-        degradeAuxiliary: overBudget,
-        shortenIdleTimeout: overBudget,
-        preferPullOnly: overBudget,
-    };
-}
-// --- Module-scope decision cache, read by clients/dispatch/auxiliary-lsp.ts ---
-//
-// session_start fires this check fire-and-forget (must never block session
-// start on a registry read) and stashes the result here; the auxiliary-LSP
-// enablement gate reads it synchronously on every dispatch. Default (before
-// the async check resolves, or if it's never run — e.g. the kill switch, or
-// a process that never reached session_start) is "don't degrade" — fail
-// toward today's behavior, exactly like the concurrent-session guard.
-let cachedDecision;
-/** True once the budget check has run this process and found the machine
- *  over the configured ceiling. Read by
- *  `clients/dispatch/auxiliary-lsp.ts#enabledAuxiliaryLspServerIds`. Never
- *  throws; absent-decision (not yet checked, or disabled) reads as `false`. */
-export function shouldDegradeAuxiliaryLsp() {
-    return cachedDecision?.degradeAuxiliary ?? false;
-}
-export function shouldShortenLspIdleTimeout() {
-    return cachedDecision?.shortenIdleTimeout ?? false;
-}
-export function shouldPreferPullOnlyDiagnostics() {
-    return cachedDecision?.preferPullOnly ?? false;
-}
-/** Test-only: reset the module-scope cache between tests. */
-export function _resetLspBudgetDecisionForTests() {
-    cachedDecision = undefined;
-}
-/**
- * Fire-and-forget budget check for `session_start`. Reads the instance
- * registry, decides via {@link decideLspBudget}, and caches the result for
- * `shouldDegradeAuxiliaryLsp` to read on subsequent dispatch calls. Never
- * throws — a failed check just leaves the cache at its "don't degrade"
- * default, matching every other best-effort registry consumer in this
- * codebase (registerInstance/sweepOrphans).
- *
- */
-export async function checkCrossProcessLspBudget(testOverrides = {}) {
-    if (!isCrossProcessBudgetEnabled() || !isInstanceRegistryEnabled())
-        return;
-    try {
-        const registry = testOverrides.registry ?? (await readInstanceRegistry());
-        if (registry.length === 0)
-            return; // nothing to be over budget against
-        const ceiling = getLspBudgetCeiling();
-        const decision = decideLspBudget(registry, testOverrides.isPidAlive ?? realIsPidAlive, ceiling, getLspBudgetRssCeilingBytes());
-        cachedDecision = decision;
-        if (decision.overBudget) {
-            logLatency({
-                type: "phase",
-                phase: "cross_process_lsp_budget_degraded",
-                filePath: "",
-                durationMs: 0,
-                metadata: {
-                    totalLiveLspServers: decision.totalLiveLspServers,
-                    ceiling: decision.ceiling,
-                    totalRssBytes: decision.totalRssBytes,
-                    rssCeilingBytes: decision.rssCeilingBytes,
-                    rssPressure: decision.rssPressure,
-                    instanceCount: registry.length,
-                },
-            });
-        }
-    }
-    catch {
-        // Best-effort observability-driven check — never throw out of
-        // session_start over this.
-    }
-}

package/dist/clients/lsp-document-symbols.js

@@ -1,110 +0,0 @@
-import { getLSPService } from "./lsp/index.js";
-// Grounded against this repo's workspace-native TypeScript 7.0.2 server
-// (`tsc --lsp --stdio`) on 2026-07-30: 20 already-open documentSymbol calls
-// measured p50 3.70 ms / p95 5.28 ms. Keep generous headroom for slower hosts.
-const LSP_DOCUMENT_SYMBOL_TIMEOUT_MS = 150;
-export const SYMBOL_KIND_NAMES = {
-    1: "file",
-    2: "module",
-    3: "namespace",
-    4: "package",
-    5: "class",
-    6: "method",
-    7: "property",
-    8: "field",
-    9: "constructor",
-    10: "enum",
-    11: "interface",
-    12: "function",
-    13: "variable",
-    14: "constant",
-    15: "string",
-    16: "number",
-    17: "boolean",
-    18: "array",
-    19: "object",
-    20: "key",
-    21: "null",
-    22: "enum-member",
-    23: "struct",
-    24: "event",
-    25: "operator",
-    26: "type-parameter",
-};
-export function lspSymbolKindName(kind) {
-    return SYMBOL_KIND_NAMES[kind] ?? `lsp-symbol-${kind}`;
-}
-export async function getOpenDocumentSymbols(filePath, timeoutMs = LSP_DOCUMENT_SYMBOL_TIMEOUT_MS) {
-    const spawned = await getLSPService().getWarmClientForFile(filePath);
-    if (!spawned ||
-        !spawned.client.isDocumentOpen(filePath) ||
-        !spawned.client.getOperationSupport().documentSymbol) {
-        return undefined;
-    }
-    let timer;
-    try {
-        return await Promise.race([
-            spawned.client.documentSymbol(filePath),
-            new Promise((resolve) => {
-                timer = setTimeout(() => resolve(undefined), timeoutMs);
-            }),
-        ]);
-    }
-    catch {
-        return undefined;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-    }
-}
-function symbolRange(symbol) {
-    return symbol.range ?? symbol.location?.range;
-}
-export function findDocumentSymbolAtLine(symbols, oneBasedLine) {
-    const line = oneBasedLine - 1;
-    let best;
-    let bestSpan = Number.POSITIVE_INFINITY;
-    const visit = (items, ancestry) => {
-        for (const symbol of items) {
-            const range = symbolRange(symbol);
-            if (range && range.start.line <= line && range.end.line >= line) {
-                const nextAncestry = [...ancestry, symbol];
-                const span = range.end.line - range.start.line;
-                if (span <= bestSpan) {
-                    best = { symbol, ancestry };
-                    bestSpan = span;
-                }
-                if (symbol.children)
-                    visit(symbol.children, nextAncestry);
-            }
-        }
-    };
-    visit(symbols, []);
-    return best;
-}
-/**
- * Full owner chain for a FLAT SymbolInformation result: hierarchical results
- * carry ancestry directly, but native-ts7 (measured: TypeScript 7.0.2 via
- * tsc --lsp) returns flat symbols whose only containment signal is the
- * immediate `containerName`. Walk containerName links through the full result
- * so nested owners qualify completely (Outer.Inner.method, #951 review) —
- * cycle-guarded and depth-capped.
- */
-export function containerNameChain(symbol, allSymbols) {
-    const chain = [];
-    const seen = new Set();
-    let container = symbol.containerName;
-    while (container && !seen.has(container) && chain.length < 10) {
-        chain.unshift(container);
-        seen.add(container);
-        container = allSymbols?.find((candidate) => candidate.name === container)?.containerName;
-    }
-    return chain;
-}
-export function qualifiedLspSymbolName(located, allSymbols) {
-    const owners = located.ancestry.length > 0
-        ? located.ancestry.map((entry) => entry.name)
-        : containerNameChain(located.symbol, allSymbols);
-    return [...owners, located.symbol.name].join(".");
-}

package/dist/clients/lsp-lazy.js

@@ -1,9 +0,0 @@
-/** Shared lazy LSP service seam (#1394). */
-import { createLazyImport } from "./lazy-import.js";
-const lazyLsp = createLazyImport(() => import("./lsp/index.js"));
-export function warmLspService() {
-    return lazyLsp.get();
-}
-export function loadLspService() {
-    return warmLspService();
-}