patchwork-os 0.2.0-alpha.0

package/dist/extensionClient.js

@@ -0,0 +1,1253 @@
+import { WebSocket } from "ws";
+import { BRIDGE_PROTOCOL_VERSION } from "./version.js";
+import { safeSend, waitForDrain } from "./wsUtils.js";
+/** Thrown when an extension request times out — distinguishable from "no results" (null). */
+export class ExtensionTimeoutError extends Error {
+    method;
+    constructor(method) {
+        super(`Extension request ${method} timed out`);
+        this.name = "ExtensionTimeoutError";
+        this.method = method;
+    }
+}
+const REQUEST_TIMEOUT = 10_000;
+export class ExtensionClient {
+    logger;
+    ws = null;
+    connected = false;
+    pendingRequests = new Map();
+    nextId = 0;
+    // Windowed circuit breaker — opens only if ≥3 timeouts occur within 30 seconds.
+    // A single slow LSP response no longer trips the breaker; sustained failure does.
+    static CIRCUIT_WINDOW_MS = 30_000;
+    static CIRCUIT_THRESHOLD = 3;
+    extensionSuspendedUntil = 0;
+    extensionFailureTimes = []; // timestamps of recent timeouts
+    extensionHalfOpen = false;
+    _circuitOpenCount = 0;
+    _lastCircuitOpenedAt = null;
+    // State pushed by extension via notifications
+    latestDiagnostics = new Map();
+    /** Parallel timestamp map — tracks when each file's diagnostics were last updated. */
+    latestDiagnosticsUpdatedAt = new Map();
+    static DIAGNOSTICS_TTL_MS = 3_600_000; // 1 hour
+    latestSelection = null;
+    latestActiveFile = null;
+    lastDiagnosticsUpdate = 0;
+    // AI comment cache (pushed by extension)
+    latestAIComments = new Map();
+    // Debug state (pushed by extension via notifications)
+    latestDebugState = null;
+    // LSP readiness state — pushed by extension when language servers finish indexing.
+    // Used by lspWithRetry to skip retry delays for languages known to be ready.
+    lspReadyLanguages = new Set();
+    // Connection quality — round-trip latency pushed by extension via rttUpdate notification.
+    lastRttMs = null;
+    // Extension package version reported in hello (npm package, not protocol version)
+    extensionPackageVersion = null;
+    // Callbacks for forwarding notifications to Claude Code
+    onDiagnosticsChanged = null;
+    onAICommentsChanged = null;
+    onFileChanged = null;
+    onExtensionDisconnected = null;
+    onDebugSessionChanged = null;
+    // Listener set for diagnostics (used by watchDiagnostics long-poll)
+    diagnosticsListeners = new Set();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /** Invoke a callback safely — log and swallow errors to prevent bridge crash */
+    safeCallback(fn, ...args) {
+        if (!fn)
+            return;
+        try {
+            fn(...args);
+        }
+        catch (err) {
+            this.logger.error(`Callback error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    handleExtensionConnection(ws) {
+        // Replace existing connection
+        if (this.ws) {
+            this.logger.info("Replacing existing extension connection");
+            // Null out this.ws *before* rejectAllPending so that any synchronous retry
+            // triggered from a reject handler sees "not connected" and backs off,
+            // rather than accidentally sending on the old (about-to-be-terminated) socket.
+            const oldWs = this.ws;
+            this.ws = null;
+            this.connected = false;
+            this.rejectAllPending("Extension reconnected");
+            oldWs.removeAllListeners();
+            if (oldWs.readyState === WebSocket.OPEN) {
+                oldWs.terminate();
+            }
+            // Clear stale diagnostics listeners — the old socket's close event will
+            // never fire (listeners removed above), so handleDisconnect won't run for
+            // it. Without this, stale watchDiagnostics closures accumulate unboundedly
+            // across reconnects and fire on every diagnostic update.
+            this.diagnosticsListeners.clear();
+        }
+        this.ws = ws;
+        this.connected = true;
+        // Don't clear cached diagnostics/selection/file state — extension pushes
+        // fresh data on connect, so stale values are harmless for a few seconds.
+        // Clear LSP readiness — extension will re-send on reconnect
+        this.lspReadyLanguages.clear();
+        // Reset circuit breaker — fresh connection deserves a clean slate
+        this.extensionSuspendedUntil = 0;
+        this.extensionFailureTimes = [];
+        this.extensionHalfOpen = false;
+        this.lastRttMs = null;
+        this.logger.info("Extension client connected");
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString("utf-8"));
+                // Response to our request
+                if (msg.id !== undefined && msg.id !== null && !msg.method) {
+                    const pending = this.pendingRequests.get(msg.id);
+                    if (pending) {
+                        this.pendingRequests.delete(msg.id);
+                        clearTimeout(pending.timer);
+                        if (msg.error) {
+                            pending.reject(new Error(msg.error.message));
+                        }
+                        else {
+                            pending.resolve(msg.result);
+                        }
+                    }
+                    else {
+                        this.logger.debug(`Orphaned extension response for id=${msg.id} (likely timed out)`);
+                    }
+                    return;
+                }
+                // Push notification from extension
+                if (msg.method) {
+                    this.handleNotification(msg.method, msg.params);
+                }
+            }
+            catch (err) {
+                this.logger.error(`Extension message parse error: ${err}`);
+            }
+        });
+        // Guard against double close/error cleanup
+        let disconnected = false;
+        const handleDisconnect = (reason) => {
+            if (disconnected)
+                return;
+            disconnected = true;
+            this.connected = false;
+            this.ws = null;
+            this.rejectAllPending(reason);
+            // Clear diagnostics listeners — stale watchDiagnostics closures must not
+            // accumulate across reconnects (they hold references to old AbortSignals).
+            this.diagnosticsListeners.clear();
+            // Clear LSP readiness — language servers may need to re-index after reconnect
+            this.lspReadyLanguages.clear();
+            this.logger.info(`Extension disconnected: ${reason}`);
+            this.safeCallback(this.onExtensionDisconnected);
+        };
+        ws.on("close", () => handleDisconnect("Connection closed"));
+        ws.on("error", (err) => {
+            this.logger.error(`Extension WS error: ${err.message}`);
+            // Set disconnected flag before terminate() so any synchronous close event
+            // emitted by terminate() sees the guard as already set.
+            handleDisconnect(`Error: ${err.message}`);
+            ws.terminate();
+        });
+    }
+    handleNotification(method, params) {
+        if (typeof params !== "object" || params === null) {
+            this.logger.debug(`Ignoring notification ${method} with invalid params`);
+            return;
+        }
+        const p = params;
+        switch (method) {
+            case "extension/diagnosticsChanged": {
+                const file = p.file;
+                const diagnostics = p.diagnostics;
+                if (typeof file !== "string" || !Array.isArray(diagnostics)) {
+                    this.logger.debug("Ignoring malformed diagnosticsChanged notification");
+                    return;
+                }
+                let sanitized;
+                if (diagnostics.length === 0) {
+                    this.latestDiagnostics.delete(file);
+                    this.latestDiagnosticsUpdatedAt.delete(file);
+                    sanitized = [];
+                }
+                else {
+                    // Sanitize: extract only known-safe fields to prevent prototype pollution
+                    // when these objects are later spread or merged.
+                    const safe = diagnostics.map((d) => {
+                        if (typeof d !== "object" || d === null)
+                            return d;
+                        const diag = d;
+                        return {
+                            file: typeof diag.file === "string"
+                                ? diag.file.slice(0, 4096)
+                                : undefined,
+                            line: typeof diag.line === "number" ? diag.line : undefined,
+                            column: typeof diag.column === "number" ? diag.column : undefined,
+                            endLine: typeof diag.endLine === "number" ? diag.endLine : undefined,
+                            endColumn: typeof diag.endColumn === "number" ? diag.endColumn : undefined,
+                            severity: typeof diag.severity === "string"
+                                ? diag.severity.slice(0, 32)
+                                : undefined,
+                            message: typeof diag.message === "string"
+                                ? diag.message.slice(0, 4096)
+                                : undefined,
+                            source: typeof diag.source === "string"
+                                ? diag.source.slice(0, 256)
+                                : undefined,
+                            code: typeof diag.code === "string" || typeof diag.code === "number"
+                                ? diag.code
+                                : undefined,
+                        };
+                    });
+                    sanitized = safe;
+                    this.latestDiagnostics.set(file, sanitized);
+                    this.latestDiagnosticsUpdatedAt.set(file, Date.now());
+                    // Cap diagnostics cache at 500 entries
+                    if (this.latestDiagnostics.size > 500) {
+                        const firstKey = this.latestDiagnostics.keys().next().value;
+                        if (firstKey !== undefined) {
+                            this.latestDiagnostics.delete(firstKey);
+                            this.latestDiagnosticsUpdatedAt.delete(firstKey);
+                        }
+                    }
+                }
+                // Update timestamp and forward sanitized data to Claude Code
+                this.lastDiagnosticsUpdate = Date.now();
+                this.safeCallback(this.onDiagnosticsChanged, file, sanitized);
+                for (const fn of [...this.diagnosticsListeners])
+                    this.safeCallback(fn, file, sanitized);
+                break;
+            }
+            case "extension/selectionChanged": {
+                if (typeof p.file !== "string" ||
+                    typeof p.startLine !== "number" ||
+                    typeof p.endLine !== "number" ||
+                    typeof p.startColumn !== "number" ||
+                    typeof p.endColumn !== "number" ||
+                    typeof p.selectedText !== "string") {
+                    this.logger.debug("Ignoring malformed selectionChanged notification");
+                    return;
+                }
+                this.latestSelection = {
+                    file: p.file.slice(0, 4096),
+                    startLine: p.startLine,
+                    endLine: p.endLine,
+                    startColumn: p.startColumn,
+                    endColumn: p.endColumn,
+                    selectedText: p.selectedText.slice(0, 65536),
+                };
+                break;
+            }
+            case "extension/activeFileChanged": {
+                if (typeof p.file !== "string") {
+                    this.logger.debug("Ignoring malformed activeFileChanged notification");
+                    return;
+                }
+                this.latestActiveFile = p.file.slice(0, 4096);
+                break;
+            }
+            case "extension/aiCommentsChanged": {
+                const comments = p.comments;
+                if (!Array.isArray(comments)) {
+                    this.logger.debug("Ignoring malformed aiCommentsChanged notification");
+                    return;
+                }
+                // Valid severity values — defined once outside the loop.
+                const VALID_SEVERITIES = new Set([
+                    "fix",
+                    "todo",
+                    "question",
+                    "warn",
+                    "task",
+                ]);
+                this.latestAIComments.clear();
+                for (const c of comments) {
+                    const entry = c;
+                    if (typeof entry.file !== "string")
+                        continue;
+                    // Sanitize: extract only known-safe fields (mirrors diagnostics sanitization)
+                    // to prevent prototype pollution if the extension sends unexpected properties.
+                    const safe = {
+                        file: entry.file,
+                        line: typeof entry.line === "number" ? entry.line : 0,
+                        comment: typeof entry.comment === "string" ? entry.comment : "",
+                        syntax: typeof entry.syntax === "string" ? entry.syntax : "",
+                        fullLine: typeof entry.fullLine === "string" ? entry.fullLine : "",
+                        ...(typeof entry.severity === "string" &&
+                            VALID_SEVERITIES.has(entry.severity) && {
+                            severity: entry.severity,
+                        }),
+                    };
+                    const existing = this.latestAIComments.get(safe.file) || [];
+                    existing.push(safe);
+                    this.latestAIComments.set(safe.file, existing);
+                }
+                // Cap at 200 files
+                if (this.latestAIComments.size > 200) {
+                    const firstKey = this.latestAIComments.keys().next().value;
+                    if (firstKey !== undefined)
+                        this.latestAIComments.delete(firstKey);
+                }
+                // Collect the sanitized entries from latestAIComments and pass those
+                // to the callback — not the raw wire data (BUG-5 fix)
+                const sanitizedComments = [];
+                for (const entries of this.latestAIComments.values()) {
+                    sanitizedComments.push(...entries);
+                }
+                this.safeCallback(this.onAICommentsChanged, sanitizedComments);
+                break;
+            }
+            case "extension/fileChanged": {
+                const id = p.id;
+                const type = p.type;
+                const file = p.file;
+                if (typeof id === "string" &&
+                    typeof type === "string" &&
+                    typeof file === "string") {
+                    this.safeCallback(this.onFileChanged, id, type, file);
+                }
+                break;
+            }
+            case "extension/hello": {
+                const extVer = typeof p.extensionVersion === "string"
+                    ? p.extensionVersion
+                    : "unknown";
+                const pkgVer = typeof p.packageVersion === "string" ? p.packageVersion : null;
+                if (pkgVer)
+                    this.extensionPackageVersion = pkgVer;
+                this.logger.info(`Extension hello: protocolVersion=${extVer}${pkgVer ? `, packageVersion=${pkgVer}` : ""}`);
+                const extMajor = Number.parseInt(extVer.split(".")[0] ?? "", 10);
+                const bridgeMajor = Number.parseInt(BRIDGE_PROTOCOL_VERSION.split(".")[0] ?? "", 10);
+                if (Number.isNaN(extMajor)) {
+                    this.logger.debug(`Extension protocol version "${extVer}" is not a recognized semver format, skipping version check`);
+                }
+                else if (extMajor !== bridgeMajor) {
+                    this.logger.warn(`Extension protocol major version mismatch: bridge=${BRIDGE_PROTOCOL_VERSION}, extension=${extVer}. Consider updating.`);
+                }
+                break;
+            }
+            case "extension/lspReady": {
+                const languageId = p.languageId;
+                if (typeof languageId !== "string" || languageId.length > 64) {
+                    this.logger.debug("Ignoring malformed lspReady notification");
+                    return;
+                }
+                this.lspReadyLanguages.add(languageId);
+                this.logger.info(`LSP ready: ${languageId}`);
+                break;
+            }
+            case "extension/fileSaved":
+                this.logger.debug(`[extensionClient] received extension/fileSaved for: ${typeof p.file === "string" ? p.file : "(unknown)"}`);
+                if (typeof p.file === "string") {
+                    this.safeCallback(this.onFileChanged, p.file, "save", p.file);
+                }
+                break;
+            case "extension/debugSessionChanged": {
+                if (typeof p.hasActiveSession !== "boolean") {
+                    this.logger.debug("Ignoring malformed debugSessionChanged notification");
+                    return;
+                }
+                // Extract only known-safe fields rather than casting the raw wire object.
+                const raw = p;
+                const state = {
+                    hasActiveSession: typeof raw.hasActiveSession === "boolean"
+                        ? raw.hasActiveSession
+                        : false,
+                    isPaused: typeof raw.isPaused === "boolean" ? raw.isPaused : false,
+                    sessionId: typeof raw.sessionId === "string" ? raw.sessionId : undefined,
+                    sessionName: typeof raw.sessionName === "string" ? raw.sessionName : undefined,
+                    sessionType: typeof raw.sessionType === "string" ? raw.sessionType : undefined,
+                    pausedAt: raw.pausedAt &&
+                        typeof raw.pausedAt === "object" &&
+                        !Array.isArray(raw.pausedAt)
+                        ? {
+                            file: typeof raw.pausedAt.file ===
+                                "string"
+                                ? raw.pausedAt
+                                    .file
+                                : "",
+                            line: typeof raw.pausedAt.line ===
+                                "number"
+                                ? raw.pausedAt
+                                    .line
+                                : 0,
+                            column: typeof raw.pausedAt.column ===
+                                "number"
+                                ? raw.pausedAt
+                                    .column
+                                : 0,
+                        }
+                        : undefined,
+                    callStack: Array.isArray(raw.callStack)
+                        ? raw.callStack.reduce((acc, f) => {
+                            if (typeof f === "object" && f !== null && !Array.isArray(f)) {
+                                const frame = f;
+                                acc.push({
+                                    id: typeof frame.id === "number" ? frame.id : 0,
+                                    name: typeof frame.name === "string" ? frame.name : "",
+                                    file: typeof frame.file === "string" ? frame.file : "",
+                                    line: typeof frame.line === "number" ? frame.line : 0,
+                                    column: typeof frame.column === "number" ? frame.column : 0,
+                                });
+                            }
+                            return acc;
+                        }, [])
+                        : undefined,
+                    scopes: Array.isArray(raw.scopes)
+                        ? raw.scopes.reduce((acc, s) => {
+                            if (typeof s === "object" && s !== null && !Array.isArray(s)) {
+                                const scope = s;
+                                acc.push({
+                                    name: typeof scope.name === "string" ? scope.name : "",
+                                    variables: Array.isArray(scope.variables)
+                                        ? scope.variables.reduce((vacc, v) => {
+                                            if (typeof v === "object" && v !== null) {
+                                                const vv = v;
+                                                vacc.push({
+                                                    name: typeof vv.name === "string" ? vv.name : "",
+                                                    value: typeof vv.value === "string" ? vv.value : "",
+                                                    type: typeof vv.type === "string" ? vv.type : "",
+                                                });
+                                            }
+                                            return vacc;
+                                        }, [])
+                                        : [],
+                                });
+                            }
+                            return acc;
+                        }, [])
+                        : undefined,
+                    breakpoints: Array.isArray(raw.breakpoints)
+                        ? raw.breakpoints.reduce((acc, b) => {
+                            if (typeof b === "object" && b !== null) {
+                                const bp = b;
+                                acc.push({
+                                    file: typeof bp.file === "string" ? bp.file : "",
+                                    line: typeof bp.line === "number" ? bp.line : 0,
+                                    condition: typeof bp.condition === "string"
+                                        ? bp.condition
+                                        : undefined,
+                                    enabled: typeof bp.enabled === "boolean" ? bp.enabled : true,
+                                });
+                            }
+                            return acc;
+                        }, [])
+                        : [],
+                };
+                this.latestDebugState = state;
+                this.safeCallback(this.onDebugSessionChanged, state);
+                break;
+            }
+            case "extension/rttUpdate": {
+                const latencyMs = p.latencyMs;
+                if (typeof latencyMs === "number" &&
+                    latencyMs >= 0 &&
+                    latencyMs < 10_000) {
+                    this.lastRttMs = latencyMs;
+                }
+                break;
+            }
+            default:
+                this.logger.debug(`Unknown extension notification: ${method}`);
+        }
+    }
+    static MAX_PENDING_REQUESTS = 100;
+    async request(method, params, timeoutMs, signal) {
+        if (this.pendingRequests.size >= ExtensionClient.MAX_PENDING_REQUESTS) {
+            throw new Error(`Too many pending extension requests (${ExtensionClient.MAX_PENDING_REQUESTS})`);
+        }
+        // Exponential backoff — fast-fail if extension is repeatedly timing out
+        const now = Date.now();
+        if (now < this.extensionSuspendedUntil) {
+            throw new ExtensionTimeoutError(method);
+        }
+        // Half-open: backoff expired but failures still in window — allow one probe through.
+        // Only applicable after the circuit has actually opened (extensionSuspendedUntil > 0).
+        if (this.extensionSuspendedUntil > 0 &&
+            this.extensionFailureTimes.length > 0 &&
+            !this.extensionHalfOpen) {
+            this.extensionHalfOpen = true;
+            this.logger.debug(`Extension circuit breaker half-open — probing with ${method}`);
+        }
+        if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("Extension not connected");
+        }
+        if (signal?.aborted) {
+            throw new Error("Request aborted");
+        }
+        // Wait for backpressure to clear before sending
+        await waitForDrain(this.ws, this.logger, "Extension backpressure");
+        // Re-check after drain wait — socket may have closed or circuit breaker may have tripped
+        if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("Extension disconnected during drain wait");
+        }
+        // NOTE: This guard is the only safety net for requests that disconnect during waitForDrain.
+        // At this point the request is not yet in pendingRequests, so rejectAllPending() would not catch it.
+        if (Date.now() < this.extensionSuspendedUntil) {
+            throw new ExtensionTimeoutError(method);
+        }
+        const timeout = timeoutMs ?? REQUEST_TIMEOUT;
+        const id = this.nextId++;
+        if (this.nextId >= Number.MAX_SAFE_INTEGER)
+            this.nextId = 0;
+        const inner = new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                signal?.removeEventListener("abort", onAbort);
+                this.logger.warn(`Extension request ${method} timed out after ${timeout}ms`);
+                settle(() => reject(new ExtensionTimeoutError(method)));
+            }, timeout);
+            // Re-check abort after the async drain wait — signal may have fired during that gap.
+            // If already aborted, addEventListener would never fire so we must check here.
+            if (signal?.aborted) {
+                clearTimeout(timer);
+                settle(() => reject(new Error("Request aborted")));
+                return;
+            }
+            // Wire AbortSignal to cancel the pending request.
+            // IMPORTANT: pendingRequests.set must happen before addEventListener so that
+            // if the signal fires synchronously during addEventListener (or in the tiny
+            // window between the two calls), onAbort finds the entry and deletes it
+            // cleanly.  Without this ordering the entry would be inserted after onAbort
+            // ran, leaving an orphaned entry with no timeout and no resolution path.
+            const onAbort = () => {
+                this.pendingRequests.delete(id);
+                clearTimeout(timer);
+                settle(() => reject(new Error("Request aborted")));
+            };
+            this.pendingRequests.set(id, {
+                resolve: (value) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    settle(() => resolve(value));
+                },
+                reject: (reason) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    settle(() => reject(reason));
+                },
+                timer,
+                removeAbortListener: signal
+                    ? () => signal.removeEventListener("abort", onAbort)
+                    : undefined,
+            });
+            if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            const data = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                try {
+                    this.ws.send(data);
+                }
+                catch (err) {
+                    this.pendingRequests.delete(id);
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", onAbort);
+                    settle(() => reject(new Error(`Failed to send extension request: ${err}`)));
+                }
+            }
+            else {
+                this.pendingRequests.delete(id);
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                settle(() => reject(new Error("Extension disconnected before send")));
+            }
+        });
+        try {
+            const result = await inner;
+            // Success — reset circuit breaker and half-open state
+            if (this.extensionFailureTimes.length > 0) {
+                this.logger.info("Extension backoff reset — connection recovered", {
+                    openCount: this._circuitOpenCount,
+                });
+            }
+            this.extensionFailureTimes = [];
+            this.extensionSuspendedUntil = 0;
+            this.extensionHalfOpen = false;
+            return result;
+        }
+        catch (err) {
+            if (err instanceof ExtensionTimeoutError) {
+                this.extensionHalfOpen = false;
+                // Sliding window: prune failures older than CIRCUIT_WINDOW_MS, then record this one
+                const now = Date.now();
+                this.extensionFailureTimes = this.extensionFailureTimes.filter((t) => now - t < ExtensionClient.CIRCUIT_WINDOW_MS);
+                this.extensionFailureTimes.push(now);
+                const failures = this.extensionFailureTimes.length;
+                this.logger.warn(`Extension timed out (${failures} failure${failures === 1 ? "" : "s"} in ${ExtensionClient.CIRCUIT_WINDOW_MS / 1_000}s window)`);
+                // Only open the circuit after CIRCUIT_THRESHOLD failures in the window.
+                // A single slow LSP response no longer trips the breaker.
+                if (failures >= ExtensionClient.CIRCUIT_THRESHOLD) {
+                    // Full jitter (AWS-recommended): random in [1, cap] — prevents rhythmic
+                    // retry storms when bridge and extension restart simultaneously.
+                    const capMs = Math.min(1_000 * 2 ** (failures - 1), 60_000);
+                    const backoffMs = Math.floor(Math.random() * capMs) + 1;
+                    this.extensionSuspendedUntil = now + backoffMs;
+                    this._circuitOpenCount++;
+                    this._lastCircuitOpenedAt = new Date();
+                    this.logger.warn(`Extension circuit open (${failures} failures) — suspending for ${Math.round(backoffMs / 100) / 10}s`, { openCount: this._circuitOpenCount });
+                    // Fast-fail all other in-flight requests immediately when the circuit
+                    // opens. Without this, each queued request waits its own REQUEST_TIMEOUT
+                    // (10s) independently, so a tool handler chaining N extension calls
+                    // would hang for up to N×10s after the extension becomes unresponsive.
+                    // The timed-out request itself is already removed from pendingRequests
+                    // by its timer callback before reaching this catch block, so calling
+                    // rejectAllPending here cannot double-reject it.
+                    this.rejectAllPending(`Extension circuit open after ${failures} failures — fast-failing pending requests`);
+                }
+            }
+            throw err;
+        }
+    }
+    /** Like request() but returns null on disconnect instead of rejecting.
+     *  ExtensionTimeoutError is NOT caught — callers must handle it to distinguish
+     *  timeout from genuine "no results" (null). */
+    async requestOrNull(method, params, timeoutMs, signal) {
+        return this.request(method, params, timeoutMs, signal).catch((err) => {
+            if (err instanceof ExtensionTimeoutError)
+                throw err;
+            return null;
+        });
+    }
+    rejectAllPending(reason) {
+        for (const [_id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.removeAbortListener?.();
+            pending.reject(new Error(reason));
+        }
+        this.pendingRequests.clear();
+    }
+    /**
+    /**
+     * Detect an extension error-object response. Extension handlers by convention
+     * return `{ error: string }` (sometimes with `success: false`) on failure
+     * instead of throwing. This predicate identifies that shape so tryRequest
+     * can convert it to null.
+     */
+    isErrorResponse(r) {
+        if (r === null || typeof r !== "object")
+            return false;
+        const obj = r;
+        if ("error" in obj && typeof obj.error === "string")
+            return true;
+        if (obj.success === false && typeof obj.error === "string")
+            return true;
+        return false;
+    }
+    /**
+     * Safer shorthand for requestOrNull — converts extension error-object responses
+     * (see isErrorResponse) to null so consumers can distinguish "no result" from
+     * "corrupt data". Use this for any handler whose success and failure paths
+     * return different shapes. Does NOT guarantee the happy-path shape matches T;
+     * for that, do a runtime shape check in the client method.
+     */
+    async tryRequest(method, params, timeout, signal) {
+        const raw = await this.requestOrNull(method, params, timeout, signal);
+        if (this.isErrorResponse(raw))
+            return null;
+        return raw;
+    }
+    /**
+     * Shape-validated request — handles shape-wrap bugs where the extension
+     * handler returns a different structural shape than the client expects
+     * (e.g. `{ folders, count }` vs `WorkspaceFolder[]`).
+     *
+     * Combines error-object detection from tryRequest with a runtime validator.
+     * If `validate` returns null, the response shape did not match and the
+     * client should return null — preventing silent data corruption downstream.
+     *
+     * Use for any handler whose success shape is non-trivial. Prefer over
+     * proxy<T> when the response is an object with specific required fields.
+     */
+    async validatedRequest(method, params, validate, timeout, signal) {
+        const raw = await this.requestOrNull(method, params, timeout, signal);
+        if (raw === null)
+            return null;
+        if (this.isErrorResponse(raw))
+            return null;
+        return validate(raw);
+    }
+    async getDiagnostics(file) {
+        return this.tryRequest("extension/getDiagnostics", { file });
+    }
+    async getSelection() {
+        // Extension returns { error: "No active editor" } when no editor is active.
+        return this.tryRequest("extension/getSelection");
+    }
+    async getOpenFiles() {
+        return this.tryRequest("extension/getOpenFiles");
+    }
+    async isDirty(file) {
+        return this.tryRequest("extension/isDirty", { file });
+    }
+    // handler returns { content, isDirty, languageId, lineCount, version, source } | { success:false, error } — validatedRequest
+    async getFileContent(file) {
+        return this.validatedRequest("extension/getFileContent", { file }, (r) => {
+            const o = r;
+            return typeof o.content === "string" ? r : null;
+        });
+    }
+    // handler returns true (boolean) on success — bare requestOrNull, caller checks === true
+    async openFile(file, line) {
+        const result = await this.requestOrNull("extension/openFile", {
+            file,
+            line,
+        });
+        return result === true;
+    }
+    async saveFile(file) {
+        // Extension handler returns `true` on successful save,
+        // `{ success: false, error: "..." }` on error paths.
+        // Normalize both shapes so the caller can distinguish "saved ok" from
+        // "not saved + here is why" from "no response".
+        const result = await this.requestOrNull("extension/saveFile", { file });
+        if (result === true)
+            return { saved: true };
+        if (result === null)
+            return null;
+        if (typeof result === "object") {
+            const r = result;
+            return {
+                saved: r.success === true,
+                ...(typeof r.error === "string" && { error: r.error }),
+            };
+        }
+        return null;
+    }
+    async closeTab(file) {
+        // Extension returns { success: true, promptedToSave } on close,
+        // { success: false, error } when the tab cannot be found.
+        const result = await this.requestOrNull("extension/closeTab", { file });
+        if (result === null || typeof result !== "object")
+            return null;
+        const r = result;
+        return {
+            success: r.success === true,
+            ...(typeof r.promptedToSave === "boolean" && {
+                promptedToSave: r.promptedToSave,
+            }),
+            ...(typeof r.error === "string" && { error: r.error }),
+        };
+    }
+    async getAIComments() {
+        return this.tryRequest("extension/getAIComments");
+    }
+    // --- LSP Semantic Features ---
+    // handler returns array of { file, line, column, endLine, endColumn } | null — tryRequest
+    async goToDefinition(file, line, column, signal) {
+        return this.tryRequest("extension/goToDefinition", { file, line, column }, undefined, signal);
+    }
+    // handler returns { references: [...], count } — validated
+    async findReferences(file, line, column, signal) {
+        return this.validatedRequest("extension/findReferences", { file, line, column }, (r) => {
+            const o = r;
+            return Array.isArray(o.references) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { found: true, implementations, count } | null — validatedRequest
+    async findImplementations(file, line, column, signal) {
+        return this.validatedRequest("extension/findImplementations", { file, line, column }, (r) => {
+            const o = r;
+            return typeof o.found === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { found: true, locations } | null — validatedRequest
+    async goToTypeDefinition(file, line, column, signal) {
+        return this.validatedRequest("extension/goToTypeDefinition", { file, line, column }, (r) => {
+            const o = r;
+            return typeof o.found === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { found: true, locations } | null — validatedRequest
+    async goToDeclaration(file, line, column, signal) {
+        return this.validatedRequest("extension/goToDeclaration", { file, line, column }, (r) => {
+            const o = r;
+            return typeof o.found === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { contents: string[], range? } | null — validated
+    async getHover(file, line, column, signal) {
+        return this.validatedRequest("extension/getHover", { file, line, column }, (r) => {
+            const o = r;
+            return Array.isArray(o.contents) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { actions: [{title, kind?, isPreferred}] } — validated
+    async getCodeActions(file, startLine, startColumn, endLine, endColumn, signal) {
+        return this.validatedRequest("extension/getCodeActions", { file, startLine, startColumn, endLine, endColumn }, (r) => {
+            const o = r;
+            return Array.isArray(o.actions) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { applied: boolean, title?, command?, error?, available? } — validatedRequest
+    async applyCodeAction(file, startLine, startColumn, endLine, endColumn, actionTitle, signal) {
+        return this.validatedRequest("extension/applyCodeAction", { file, startLine, startColumn, endLine, endColumn, actionTitle }, (r) => {
+            const o = r;
+            return typeof o.applied === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { title, changes, ... } | { error } — tryRequest (error-obj on failure)
+    async previewCodeAction(file, startLine, startColumn, endLine, endColumn, actionTitle, signal) {
+        return this.tryRequest("extension/previewCodeAction", { file, startLine, startColumn, endLine, endColumn, actionTitle }, 15_000, signal);
+    }
+    // handler returns { success, newName?, affectedFiles?, totalEdits?, error? } — rich contract, caller needs success field
+    async renameSymbol(file, line, column, newName, signal) {
+        // Rename can be slow on large projects
+        return this.validatedRequest("extension/renameSymbol", { file, line, column, newName }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        }, 15_000, signal);
+    }
+    async searchSymbols(query, maxResults, signal) {
+        return this.requestOrNull("extension/searchSymbols", { query, maxResults }, undefined, signal);
+    }
+    // handler returns { canRename: boolean, range?, placeholder?, reason? } — validatedRequest
+    async prepareRename(file, line, column, signal) {
+        return this.validatedRequest("extension/prepareRename", { file, line, column }, (r) => {
+            const o = r;
+            return typeof o.canRename === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { formatted: boolean, editCount? } or { formatted: false, reason? } — validated
+    async formatRange(file, startLine, endLine, signal) {
+        return this.validatedRequest("extension/formatRange", { file, startLine, endLine }, (r) => {
+            const o = r;
+            return typeof o.formatted === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { activeSignature, activeParameter, signatures } | null — tryRequest
+    async signatureHelp(file, line, column, signal) {
+        return this.tryRequest("extension/signatureHelp", { file, line, column }, undefined, signal);
+    }
+    // handler returns { ranges: [...] } — validatedRequest
+    async foldingRanges(file, signal) {
+        return this.validatedRequest("extension/foldingRanges", { file }, (r) => {
+            const o = r;
+            return Array.isArray(o.ranges) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { ranges: [...] } — validatedRequest
+    async selectionRanges(file, line, column, signal) {
+        return this.validatedRequest("extension/selectionRanges", { file, line, column }, (r) => {
+            const o = r;
+            return Array.isArray(o.ranges) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { watching: true, id, pattern } — tryRequest
+    async watchFiles(id, pattern) {
+        return this.tryRequest("extension/watchFiles", { id, pattern });
+    }
+    // handler returns { unwatched: true, id } — tryRequest
+    async unwatchFiles(id) {
+        return this.tryRequest("extension/unwatchFiles", { id });
+    }
+    async captureScreenshot() {
+        return this.validatedRequest("extension/captureScreenshot", {}, (r) => {
+            const o = r;
+            return typeof o.base64 === "string" && typeof o.mimeType === "string"
+                ? r
+                : null;
+        });
+    }
+    // --- Terminal Features ---
+    // handler returns { terminals, count, outputCaptureAvailable } — validatedRequest
+    async listTerminals() {
+        return this.validatedRequest("extension/listTerminals", undefined, (r) => {
+            const o = r;
+            return Array.isArray(o.terminals) ? r : null;
+        });
+    }
+    // handler returns { available: boolean, ... } — validatedRequest
+    async getTerminalOutput(name, index, lines) {
+        return this.validatedRequest("extension/getTerminalOutput", { name, index, lines }, (r) => {
+            const o = r;
+            return typeof o.available === "boolean" ? r : null;
+        });
+    }
+    // handler returns { success: boolean, terminalName? } — validatedRequest
+    async disposeTerminal(name, index) {
+        return this.validatedRequest("extension/disposeTerminal", { name, index }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // --- File Operations ---
+    // handler returns { success: boolean, filePath, isDirectory, created } | { success: false, error } — validatedRequest
+    async createFile(filePath, content, isDirectory, overwrite, openAfterCreate) {
+        return this.validatedRequest("extension/createFile", { filePath, content, isDirectory, overwrite, openAfterCreate }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { success: boolean, filePath, deleted } | { success: false, error } — validatedRequest
+    async deleteFile(filePath, recursive, useTrash) {
+        return this.validatedRequest("extension/deleteFile", { filePath, recursive, useTrash }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { success: boolean, oldPath, newPath, renamed } | { success: false, error } — validatedRequest
+    async renameFile(oldPath, newPath, overwrite) {
+        return this.validatedRequest("extension/renameFile", { oldPath, newPath, overwrite }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // --- Text Editing ---
+    // handler returns { success: boolean, editCount, saved } | { success: false, error } — validatedRequest
+    async editText(filePath, edits, save) {
+        return this.validatedRequest("extension/editText", { filePath, edits, save }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { success: boolean, saved, source } | { success: false, error } — validatedRequest
+    async replaceBlock(filePath, oldContent, newContent, save) {
+        return this.validatedRequest("extension/replaceBlock", { filePath, oldContent, newContent, save }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { symbols: FlatSymbol[], count } — validated
+    async getDocumentSymbols(file, signal) {
+        return this.validatedRequest("extension/getDocumentSymbols", { file }, (r) => {
+            const o = r;
+            return Array.isArray(o.symbols) ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { symbol, incoming?, outgoing? } | null — validated
+    async getCallHierarchy(file, line, column, direction, maxResults, signal) {
+        return this.validatedRequest("extension/getCallHierarchy", { file, line, column, direction, maxResults }, (r) => {
+            const o = r;
+            return typeof o.symbol === "object" && o.symbol !== null ? r : null;
+        }, 15_000, signal);
+    }
+    // --- Code Actions (format, fix, organize) ---
+    async formatDocument(file) {
+        // Extension returns { error: "..." } when the format command fails.
+        // tryRequest unwraps to null so consumers' `!== null` check falls through
+        // to their CLI formatter fallback instead of reporting false success.
+        return this.tryRequest("extension/formatDocument", { file }, 15_000);
+    }
+    async fixAllLintErrors(file) {
+        // Extension returns { error: "..." } on command failure. tryRequest
+        // unwraps to null so consumers fall through to their CLI fallback.
+        return this.tryRequest("extension/fixAllLintErrors", { file }, 15_000);
+    }
+    // handler returns { success: true, actionsApplied } | { error } — tryRequest (error-obj on failure)
+    async organizeImports(file) {
+        return this.tryRequest("extension/organizeImports", { file }, 15_000);
+    }
+    // --- Terminal Control ---
+    // handler returns { success: true, name, index } — validatedRequest
+    async createTerminal(name, cwd, env, show) {
+        return this.validatedRequest("extension/createTerminal", { name, cwd, env, show }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { success: boolean, terminalName? } | { success: false, error, availableTerminals } — validatedRequest
+    async sendTerminalCommand(text, name, index, addNewline) {
+        return this.validatedRequest("extension/sendTerminalCommand", { text, name, index, addNewline }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        });
+    }
+    // handler returns { matched: boolean, matchedLine?, elapsed?, terminalName, timedOut?, error? } — validatedRequest
+    async waitForTerminalOutput(pattern, name, index, timeoutMs) {
+        const requestTimeout = (timeoutMs ?? 30_000) + 5_000;
+        return this.validatedRequest("extension/waitForTerminalOutput", { pattern, name, index, timeoutMs }, (r) => {
+            const o = r;
+            return typeof o.matched === "boolean" ? r : null;
+        }, requestTimeout);
+    }
+    // handler returns { success: boolean, exitCode?, output, terminalName, timedOut?, error? } — validatedRequest
+    async executeInTerminal(command, name, index, timeoutMs, show) {
+        // Add 5s overhead beyond the command timeout so the bridge doesn't cut the extension off early
+        const requestTimeout = (timeoutMs ?? 30_000) + 5_000;
+        return this.validatedRequest("extension/executeInTerminal", { command, name, index, timeoutMs, show }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        }, requestTimeout);
+    }
+    // --- Debug ---
+    async getDebugState() {
+        return this.validatedRequest("extension/getDebugState", {}, (r) => typeof r.hasActiveSession === "boolean"
+            ? r
+            : null);
+    }
+    // handler returns { result, type?, variablesReference? } — validatedRequest
+    async evaluateInDebugger(expression, frameId, context, signal) {
+        return this.validatedRequest("extension/evaluateInDebugger", { expression, frameId, context }, (r) => {
+            const o = r;
+            return "result" in o ? r : null;
+        }, 15_000, signal);
+    }
+    // handler returns { set: number, file } — validatedRequest
+    async setDebugBreakpoints(file, breakpoints, signal) {
+        return this.validatedRequest("extension/setDebugBreakpoints", { file, breakpoints }, (r) => {
+            const o = r;
+            return typeof o.set === "number" ? r : null;
+        }, undefined, signal);
+    }
+    // handler returns { started: boolean } — validatedRequest
+    async startDebugging(configName, signal) {
+        return this.validatedRequest("extension/startDebugging", { configName }, (r) => {
+            const o = r;
+            return typeof o.started === "boolean" ? r : null;
+        }, 15_000, signal);
+    }
+    // handler returns { stopped: boolean, message? } | { stopped: false, error } — validatedRequest
+    async stopDebugging(signal) {
+        return this.validatedRequest("extension/stopDebugging", undefined, (r) => {
+            const o = r;
+            return typeof o.stopped === "boolean" ? r : null;
+        }, undefined, signal);
+    }
+    // --- Decorations ---
+    // handler returns { applied: number, editorsUpdated: number } — validatedRequest
+    async setDecorations(id, file, decorations) {
+        return this.validatedRequest("extension/setDecorations", { id, file, decorations }, (r) => {
+            const o = r;
+            return typeof o.applied === "number" ? r : null;
+        });
+    }
+    // handler returns { cleared: number } — validatedRequest
+    async clearDecorations(id) {
+        return this.validatedRequest("extension/clearDecorations", { id }, (r) => {
+            const o = r;
+            return typeof o.cleared === "number" ? r : null;
+        });
+    }
+    // --- VS Code Commands ---
+    // handler returns { result, _warning? } — validatedRequest
+    async executeVSCodeCommand(command, args) {
+        return this.validatedRequest("extension/executeVSCodeCommand", { command, args }, (r) => {
+            const o = r;
+            return "result" in o ? r : null;
+        });
+    }
+    async listVSCodeCommands(filter) {
+        return this.validatedRequest("extension/listVSCodeCommands", { filter }, (r) => {
+            const o = r;
+            return Array.isArray(o.commands)
+                ? r
+                : null;
+        });
+    }
+    // --- Workspace Settings ---
+    // handler returns { section, settings } — validatedRequest
+    async getWorkspaceSettings(section, target) {
+        return this.validatedRequest("extension/getWorkspaceSettings", { section, target }, (r) => {
+            const o = r;
+            return typeof o.settings === "object" && o.settings !== null ? r : null;
+        });
+    }
+    // handler returns { set: true, key, target } — validatedRequest
+    async setWorkspaceSetting(key, value, target) {
+        return this.validatedRequest("extension/setWorkspaceSetting", { key, value, target }, (r) => {
+            const o = r;
+            return typeof o.set === "boolean" ? r : null;
+        });
+    }
+    // --- Clipboard ---
+    // handler returns { text, byteLength, truncated } — validatedRequest
+    async readClipboard() {
+        return this.validatedRequest("extension/readClipboard", undefined, (r) => {
+            const o = r;
+            return typeof o.text === "string" ? r : null;
+        });
+    }
+    // handler returns { written: boolean, byteLength? } | { written: false, error } — validatedRequest
+    async writeClipboard(text) {
+        return this.validatedRequest("extension/writeClipboard", { text }, (r) => {
+            const o = r;
+            return typeof o.written === "boolean" ? r : null;
+        });
+    }
+    // --- Inlay Hints ---
+    // handler returns { hints: [...], count, capped? } — validated
+    async getInlayHints(file, startLine, endLine) {
+        return this.validatedRequest("extension/getInlayHints", { file, startLine, endLine }, (r) => {
+            const o = r;
+            return Array.isArray(o.hints) ? r : null;
+        });
+    }
+    // --- Type Hierarchy ---
+    // handler returns { found: boolean, root?, supertypes, subtypes, direction } — validated
+    async getTypeHierarchy(file, line, column, direction, maxResults, signal) {
+        return this.validatedRequest("extension/getTypeHierarchy", { file, line, column, direction, maxResults }, (r) => {
+            const o = r;
+            return typeof o.found === "boolean" ? r : null;
+        }, 15_000, signal);
+    }
+    // --- Code Lens ---
+    // handler returns { lenses: [...], count } — validated
+    async getCodeLens(file, signal) {
+        return this.validatedRequest("extension/getCodeLens", { file }, (r) => {
+            const o = r;
+            return Array.isArray(o.lenses) ? r : null;
+        }, undefined, signal);
+    }
+    // --- Semantic Tokens ---
+    // handler returns { tokens: [...], count, capped, legend: { tokenTypes, tokenModifiers } } — validated
+    async getSemanticTokens(file, startLine, endLine, maxTokens, signal) {
+        return this.validatedRequest("extension/getSemanticTokens", { file, startLine, endLine, maxTokens }, (r) => {
+            const o = r;
+            return Array.isArray(o.tokens) ? r : null;
+        }, 15_000, signal);
+    }
+    // --- Document Links ---
+    async getDocumentLinks(file, signal) {
+        return this.requestOrNull("extension/getDocumentLinks", { file }, undefined, signal);
+    }
+    // --- Tasks ---
+    // handler returns { tasks: [...] } — validatedRequest
+    async listTasks(type) {
+        return this.validatedRequest("extension/listTasks", type ? { type } : undefined, (r) => {
+            const o = r;
+            return Array.isArray(o.tasks) ? r : null;
+        }, 15_000);
+    }
+    // handler returns { success: boolean, name, exitCode? } | { success: false, error, timedOut? } — validatedRequest
+    async runTask(name, type, timeoutMs) {
+        const requestTimeout = (timeoutMs ?? 60_000) + 5_000;
+        return this.validatedRequest("extension/runTask", { name, type, timeoutMs }, (r) => {
+            const o = r;
+            return typeof o.success === "boolean" ? r : null;
+        }, requestTimeout);
+    }
+    // --- Workspace Folders ---
+    async getWorkspaceFolders() {
+        // Extension returns { folders: [...], count: N } — unwrap to array.
+        // Back-compat with legacy extension versions that returned the array directly.
+        return this.validatedRequest("extension/getWorkspaceFolders", undefined, (raw) => {
+            if (typeof raw === "object" && raw !== null && "folders" in raw) {
+                const folders = raw.folders;
+                return Array.isArray(folders) ? folders : null;
+            }
+            return Array.isArray(raw) ? raw : null;
+        });
+    }
+    // --- Notebook ---
+    // handler not yet implemented in extension — bare requestOrNull returns null until implemented
+    async getNotebookCells(file) {
+        return this.requestOrNull("extension/getNotebookCells", { file });
+    }
+    // handler not yet implemented in extension — bare requestOrNull returns null until implemented
+    async runNotebookCell(file, cellIndex, timeoutMs) {
+        const requestTimeout = (timeoutMs ?? 30_000) + 5_000;
+        return this.requestOrNull("extension/runNotebookCell", { file, cellIndex, timeoutMs }, requestTimeout);
+    }
+    // handler not yet implemented in extension — bare requestOrNull returns null until implemented
+    async getNotebookOutput(file, cellIndex) {
+        return this.requestOrNull("extension/getNotebookOutput", {
+            file,
+            cellIndex,
+        });
+    }
+    // --- Diagnostics Helpers ---
+    getCachedDiagnostics(file) {
+        const now = Date.now();
+        const ttl = ExtensionClient.DIAGNOSTICS_TTL_MS;
+        if (file) {
+            const updatedAt = this.latestDiagnosticsUpdatedAt.get(file);
+            if (updatedAt !== undefined && now - updatedAt > ttl) {
+                this.latestDiagnostics.delete(file);
+                this.latestDiagnosticsUpdatedAt.delete(file);
+                return [];
+            }
+            return this.latestDiagnostics.get(file) ?? [];
+        }
+        // Evict stale entries across entire map on a full scan
+        for (const [f, updatedAt] of this.latestDiagnosticsUpdatedAt) {
+            if (now - updatedAt > ttl) {
+                this.latestDiagnostics.delete(f);
+                this.latestDiagnosticsUpdatedAt.delete(f);
+            }
+        }
+        return Array.from(this.latestDiagnostics.values()).flat();
+    }
+    addDiagnosticsListener(listener) {
+        this.diagnosticsListeners.add(listener);
+        return () => this.diagnosticsListeners.delete(listener);
+    }
+    /** Notify the extension about Claude Code connection state changes */
+    notifyClaudeConnectionState(connected, stats) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        void safeSend(this.ws, JSON.stringify({
+            jsonrpc: "2.0",
+            method: "bridge/claudeConnectionChanged",
+            params: { connected, ...(stats !== undefined && { stats }) },
+        }), this.logger);
+    }
+    /** Push a Claude task output chunk to the VS Code output channel. Best-effort. */
+    notifyTaskOutput(taskId, chunk) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        void safeSend(this.ws, JSON.stringify({
+            jsonrpc: "2.0",
+            method: "bridge/claudeTaskOutput",
+            params: { taskId, chunk },
+        }), this.logger);
+    }
+    /** Push a Claude task completion status to the VS Code output channel. Best-effort. */
+    notifyTaskDone(taskId, status) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        void safeSend(this.ws, JSON.stringify({
+            jsonrpc: "2.0",
+            method: "bridge/claudeTaskOutput",
+            params: { taskId, done: true, status },
+        }), this.logger);
+    }
+    getCircuitBreakerState() {
+        const now = Date.now();
+        // Prune stale entries so callers always see the active window count,
+        // not the raw array which may include expired timestamps.
+        const activeFailures = this.extensionFailureTimes.filter((t) => now - t < ExtensionClient.CIRCUIT_WINDOW_MS);
+        return {
+            suspended: now < this.extensionSuspendedUntil,
+            suspendedUntil: this.extensionSuspendedUntil,
+            failures: activeFailures.length,
+            openCount: this._circuitOpenCount,
+            lastOpenedAt: this._lastCircuitOpenedAt?.toISOString() ?? null,
+        };
+    }
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Push a server-initiated notification to the connected extension.
+     * Non-fatal: silently drops if extension is not connected or send fails.
+     */
+    sendPush(method, params) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        void safeSend(this.ws, JSON.stringify({ jsonrpc: "2.0", method, params }), this.logger);
+    }
+    disconnect() {
+        if (this.ws) {
+            // Remove listeners before closing so the async "close" event does not
+            // re-trigger handleDisconnect → onExtensionDisconnected during shutdown.
+            this.ws.removeAllListeners();
+            this.ws.close(1000, "Bridge shutting down");
+            this.ws = null;
+        }
+        this.connected = false;
+        this.rejectAllPending("Bridge shutting down");
+    }
+}
+//# sourceMappingURL=extensionClient.js.map