pybao-cli 1.3.87 → 1.3.88

package/dist/{chunk-HWIU6J2T.js → chunk-6NN7AYG5.js}

@@ -2,20 +2,22 @@ import { createRequire as __pybCreateRequire } from "node:module";
 const require = __pybCreateRequire(import.meta.url);
 import {
   LspServerRegistry,
-  findNearestRoot
-} from "./chunk-KEALJIDY.js";
+  findNearestRoot,
+  getInstallNotices
+} from "./chunk-E7KPOGEP.js";
 import {
   levenshtein
 } from "./chunk-UZ34JEUK.js";
 import {
   getCwd
-} from "./chunk-KUIDN7FP.js";
+} from "./chunk-IKZIBMB2.js";
 
 // src/lsp/index.ts
 import { extname as extname2 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import * as http from "http";
+import { createHash as createHash2 } from "crypto";
 
 // src/tools/search/LspTool/client/generic.ts
 import { createMessageConnection, StreamMessageReader, StreamMessageWriter } from "vscode-jsonrpc/node.js";
@@ -27,6 +29,7 @@ var DiagnosticsEventBus = class {
   lastEventAt = /* @__PURE__ */ new Map();
   debounceTimers = /* @__PURE__ */ new Map();
   waiting = /* @__PURE__ */ new Map();
+  subscriptions = /* @__PURE__ */ new Map();
   constructor(options) {
     this.debounceMs = options?.debounceMs ?? 150;
   }
@@ -44,6 +47,12 @@ var DiagnosticsEventBus = class {
       for (const resolver of Array.from(waiters)) {
         resolver();
       }
+      const subs = this.subscriptions.get(uri);
+      if (subs) {
+        for (const handler of Array.from(subs)) {
+          handler(uri);
+        }
+      }
     }, this.debounceMs);
     this.debounceTimers.set(uri, timer);
   }
@@ -73,6 +82,17 @@ var DiagnosticsEventBus = class {
       }, timeoutMs);
     });
   }
+  subscribe(uri, handler) {
+    const subs = this.subscriptions.get(uri) ?? /* @__PURE__ */ new Set();
+    subs.add(handler);
+    this.subscriptions.set(uri, subs);
+    return () => {
+      const current = this.subscriptions.get(uri);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) this.subscriptions.delete(uri);
+    };
+  }
 };
 var GenericLspClient = class {
   constructor(serverCommand, serverArgs, cwd, rootPath, extraEnv, initializationOptions) {
@@ -296,7 +316,16 @@ var GenericLspClient = class {
   }
   async waitForReadiness(filePath, timeoutMs = 3e3) {
     const normalizedUri = this.normalizeUri(filePath);
+    let done = false;
+    const unsubscribe = this.diagnosticsBus.subscribe(normalizedUri, () => {
+      done = true;
+    });
     await this.diagnosticsBus.waitForIdle(normalizedUri, timeoutMs);
+    if (done) {
+      unsubscribe();
+    } else {
+      unsubscribe();
+    }
   }
   on(event, handler) {
     this.diagnosticEvents.on(event, handler);
@@ -352,6 +381,12 @@ var LspClientManager = class _LspClientManager {
   clients = /* @__PURE__ */ new Map();
   spawning = /* @__PURE__ */ new Map();
   broken = /* @__PURE__ */ new Set();
+  failures = /* @__PURE__ */ new Map();
+  readiness = /* @__PURE__ */ new Map();
+  prewarmByRoot = /* @__PURE__ */ new Map();
+  prewarmHits = /* @__PURE__ */ new Map();
+  spawnMetrics = /* @__PURE__ */ new Map();
+  requestMetrics = /* @__PURE__ */ new Map();
   constructor() {
   }
   static getInstance() {
@@ -367,6 +402,36 @@ var LspClientManager = class _LspClientManager {
     if (serverInfo?.languageId) return serverInfo.languageId;
     return LspServerRegistry.getInstance().getLanguageIdForExtension(ext);
   }
+  getPrewarmTtlMs() {
+    const override = Number.parseInt(process.env.PYB_LSP_PREWARM_TTL_MS ?? "", 10);
+    if (Number.isFinite(override) && override > 0) return override;
+    return 3e4;
+  }
+  getPrewarmTriggerCount() {
+    const override = Number.parseInt(process.env.PYB_LSP_PREWARM_TRIGGER_COUNT ?? "", 10);
+    if (Number.isFinite(override) && override > 0) return override;
+    return 2;
+  }
+  shouldPrewarm(rootPath) {
+    const now = this.now();
+    const last = this.prewarmByRoot.get(rootPath);
+    const ttlMs = this.getPrewarmTtlMs();
+    if (last !== void 0 && now - last < ttlMs) {
+      return false;
+    }
+    const nextHits = (this.prewarmHits.get(rootPath) ?? 0) + 1;
+    this.prewarmHits.set(rootPath, nextHits);
+    if (nextHits < this.getPrewarmTriggerCount()) {
+      return false;
+    }
+    this.prewarmHits.delete(rootPath);
+    this.prewarmByRoot.set(rootPath, now);
+    return true;
+  }
+  async maybeEnsureWorkspaceClients(rootPath) {
+    if (!this.shouldPrewarm(rootPath)) return;
+    await this.ensureWorkspaceClients(rootPath);
+  }
   async ensureWorkspaceClients(rootPath) {
     try {
       const files = await readdir(rootPath, { withFileTypes: true });
@@ -464,7 +529,7 @@ var LspClientManager = class _LspClientManager {
     const safeCwd = /[^\x00-\x7F]/.test(resolvedRoot) ? process.cwd() : resolvedRoot;
     let initOpts = serverInfo.initializationOptions;
     if (serverInfo.id === "pyright" || serverInfo.id === "ty") {
-      const { detectPythonVenv } = await import("./registry-OUOC3F5A.js");
+      const { detectPythonVenv } = await import("./registry-34E5OJNF.js");
       const pythonPath = detectPythonVenv(resolvedRoot);
       if (pythonPath) {
         initOpts = { ...initOpts ?? {}, pythonPath };
@@ -479,6 +544,8 @@ var LspClientManager = class _LspClientManager {
       initOpts
     );
     await nextClient.initialize();
+    nextClient.serverId = serverInfo.id;
+    nextClient.serverKey = key;
     this.clients.set(key, nextClient);
     return nextClient;
   }
@@ -489,19 +556,30 @@ var LspClientManager = class _LspClientManager {
     this.clients.clear();
     this.broken.clear();
     this.spawning.clear();
+    this.failures.clear();
+    this.readiness.clear();
+    this.prewarmByRoot.clear();
+    this.prewarmHits.clear();
+    this.spawnMetrics.clear();
+    this.requestMetrics.clear();
   }
   async workspaceSymbol(query, rootPath = getCwd(), options) {
     if (this.clients.size === 0) {
-      await this.ensureWorkspaceClients(rootPath);
+      await this.maybeEnsureWorkspaceClients(rootPath);
     }
     const results = [];
     for (const client of this.clients.values()) {
+      const serverId = client.serverId ?? "unknown";
+      this.recordRequestAttempt(serverId, "workspaceSymbol");
+      const startAt = this.now();
       try {
         const symbols = await client.workspaceSymbol(query);
         if (symbols && Array.isArray(symbols)) {
           results.push(...symbols);
         }
+        this.recordRequestSuccess(serverId, "workspaceSymbol", this.now() - startAt);
       } catch (e) {
+        this.recordRequestFailure(serverId, "workspaceSymbol", "error");
       }
     }
     if (results.length === 0 && query.length > 0) {
@@ -659,11 +737,67 @@ var LspClientManager = class _LspClientManager {
         diagnostics.push({ client: key, entries: snapshot });
       }
     }
+    const failures = Array.from(this.failures.entries()).map(([client, entry]) => ({
+      client,
+      reason: entry.reason,
+      count: entry.count,
+      until: entry.until,
+      last: entry.last
+    }));
+    const readiness = Array.from(this.readiness.entries()).map(([filePath, at]) => ({
+      filePath,
+      at
+    }));
+    const prewarms = Array.from(this.prewarmByRoot.entries()).map(([root, at]) => ({
+      root,
+      at
+    }));
+    const metrics = Array.from(this.spawnMetrics.entries()).map(([server, entry]) => {
+      const { avgLatency, p95Latency } = this.computeLatencyStats(entry.latencies);
+      const successRate = entry.attempts === 0 ? 0 : entry.successes / entry.attempts;
+      return {
+        server,
+        attempts: entry.attempts,
+        successes: entry.successes,
+        failures: entry.failures,
+        successRate,
+        latencyAvgMs: avgLatency,
+        latencyP95Ms: p95Latency,
+        failureReasons: { ...entry.failureReasons }
+      };
+    });
+    const regressionFactor = this.getRequestRegressionFactor();
+    const requestMetrics = Array.from(this.requestMetrics.values()).map((entry) => {
+      const { avgLatency, p95Latency } = this.computeLatencyStats(entry.latencies);
+      const successRate = entry.attempts === 0 ? 0 : entry.successes / entry.attempts;
+      const baselineAvg = entry.baseline?.avgMs ?? 0;
+      const baselineP95 = entry.baseline?.p95Ms ?? 0;
+      const regression = entry.baseline !== void 0 && (avgLatency > baselineAvg * regressionFactor || p95Latency > baselineP95 * regressionFactor);
+      return {
+        server: entry.serverId,
+        operation: entry.operation,
+        attempts: entry.attempts,
+        successes: entry.successes,
+        failures: entry.failures,
+        successRate,
+        latencyAvgMs: avgLatency,
+        latencyP95Ms: p95Latency,
+        baselineAvgMs: baselineAvg,
+        baselineP95Ms: baselineP95,
+        regression,
+        failureReasons: { ...entry.failureReasons }
+      };
+    });
     return {
       clients: Array.from(this.clients.keys()),
       spawning: Array.from(this.spawning.keys()),
       broken: Array.from(this.broken.values()),
-      diagnostics
+      diagnostics,
+      failures,
+      readiness,
+      prewarms,
+      metrics,
+      requestMetrics
     };
   }
   // New helper to expose waitForReadiness to clients who only have a manager
@@ -671,6 +805,7 @@ var LspClientManager = class _LspClientManager {
     const client = await this.getClientForFile(filePath);
     if (client) {
       await client.waitForReadiness(filePath, timeoutMs);
+      this.readiness.set(filePath, this.now());
     }
   }
   matchesServerFilters(filePath, serverInfo) {
@@ -708,43 +843,173 @@ var LspClientManager = class _LspClientManager {
     }
     return defaultRoot;
   }
+  now() {
+    return Date.now();
+  }
+  computeLatencyStats(latencies) {
+    const latencySamples = [...latencies].sort((a, b) => a - b);
+    const avgLatency = latencySamples.length === 0 ? 0 : latencySamples.reduce((sum, value) => sum + value, 0) / latencySamples.length;
+    const p95Index = latencySamples.length === 0 ? -1 : Math.ceil(latencySamples.length * 0.95) - 1;
+    const p95Latency = p95Index >= 0 ? latencySamples[p95Index] : 0;
+    return { avgLatency, p95Latency };
+  }
+  getMetricsEntry(serverId) {
+    let entry = this.spawnMetrics.get(serverId);
+    if (!entry) {
+      entry = {
+        attempts: 0,
+        successes: 0,
+        failures: 0,
+        latencies: [],
+        failureReasons: { prepare: 0, spawn: 0 }
+      };
+      this.spawnMetrics.set(serverId, entry);
+    }
+    return entry;
+  }
+  recordAttempt(serverId) {
+    const entry = this.getMetricsEntry(serverId);
+    entry.attempts += 1;
+  }
+  recordSuccess(serverId, latencyMs) {
+    const entry = this.getMetricsEntry(serverId);
+    entry.successes += 1;
+    entry.latencies.push(latencyMs);
+    if (entry.latencies.length > 50) {
+      entry.latencies.shift();
+    }
+  }
+  recordFailure(serverId, reason) {
+    const entry = this.getMetricsEntry(serverId);
+    entry.failures += 1;
+    entry.failureReasons[reason] += 1;
+  }
+  getRequestKey(serverId, operation) {
+    return `${serverId}::${operation}`;
+  }
+  getRequestEntry(serverId, operation) {
+    const key = this.getRequestKey(serverId, operation);
+    let entry = this.requestMetrics.get(key);
+    if (!entry) {
+      entry = {
+        serverId,
+        operation,
+        attempts: 0,
+        successes: 0,
+        failures: 0,
+        latencies: [],
+        failureReasons: { unavailable: 0, error: 0, timeout: 0, invalid: 0 }
+      };
+      this.requestMetrics.set(key, entry);
+    }
+    return entry;
+  }
+  getRequestBaselineSampleSize() {
+    return 10;
+  }
+  getRequestRegressionFactor() {
+    return 1.5;
+  }
+  recordRequestAttempt(serverId, operation) {
+    const entry = this.getRequestEntry(serverId, operation);
+    entry.attempts += 1;
+  }
+  recordRequestSuccess(serverId, operation, latencyMs) {
+    const entry = this.getRequestEntry(serverId, operation);
+    entry.successes += 1;
+    entry.latencies.push(latencyMs);
+    if (entry.latencies.length > 50) {
+      entry.latencies.shift();
+    }
+    if (!entry.baseline && entry.latencies.length >= this.getRequestBaselineSampleSize()) {
+      const { avgLatency, p95Latency } = this.computeLatencyStats(entry.latencies);
+      entry.baseline = {
+        avgMs: avgLatency,
+        p95Ms: p95Latency,
+        samples: entry.latencies.length
+      };
+    }
+  }
+  recordRequestFailure(serverId, operation, reason) {
+    const entry = this.getRequestEntry(serverId, operation);
+    entry.failures += 1;
+    entry.failureReasons[reason] += 1;
+  }
+  getBaseTtlMs(reason) {
+    const override = Number.parseInt(process.env.PYB_LSP_BROKEN_TTL_MS ?? "", 10);
+    if (Number.isFinite(override) && override > 0) return override;
+    return reason === "prepare" ? 5e3 : 1e4;
+  }
+  markBroken(key, reason) {
+    const prev = this.failures.get(key);
+    const count = prev ? prev.count + 1 : 1;
+    const base = this.getBaseTtlMs(reason);
+    const ttl = Math.min(base * Math.pow(2, count - 1), 6e4);
+    const until = this.now() + ttl;
+    this.failures.set(key, { count, until, reason, last: this.now() });
+    this.broken.add(key);
+  }
+  isWithinBrokenTtl(key) {
+    const entry = this.failures.get(key);
+    if (!entry) return false;
+    const active = this.now() < entry.until;
+    if (!active) {
+      this.failures.delete(key);
+      this.broken.delete(key);
+    }
+    return active;
+  }
   async getClientForServer(filePath, serverInfo, rootPath) {
     if (!this.matchesServerFilters(filePath, serverInfo)) {
       return null;
     }
     const resolvedRoot = rootPath ?? await this.resolveRootForServer(filePath, serverInfo);
+    const key = `${resolvedRoot}:${serverInfo.id}`;
+    if (this.isWithinBrokenTtl(key)) {
+      return null;
+    }
+    const existingSpawn = this.spawning.get(key);
+    if (existingSpawn) {
+      return existingSpawn;
+    }
+    const existingClient = this.clients.get(key);
+    if (existingClient) {
+      return existingClient;
+    }
+    this.recordAttempt(serverInfo.id);
     try {
       const ready = await serverInfo.prepare();
       if (!ready) {
+        this.recordFailure(serverInfo.id, "prepare");
+        this.markBroken(key, "prepare");
         return null;
       }
     } catch (e) {
+      this.recordFailure(serverInfo.id, "prepare");
+      this.markBroken(key, "prepare");
       return null;
     }
-    const key = `${resolvedRoot}:${serverInfo.id}`;
-    if (this.broken.has(key)) {
-      return null;
-    }
-    const existingSpawn = this.spawning.get(key);
-    if (existingSpawn) {
-      return existingSpawn;
-    }
-    let client = this.clients.get(key);
-    if (!client) {
-      const spawnPromise = (async () => {
-        try {
-          return await this.spawnClient(resolvedRoot, serverInfo, key);
-        } catch (error) {
-          this.broken.add(key);
-          return null;
-        } finally {
-          this.spawning.delete(key);
+    const spawnStart = this.now();
+    const spawnPromise = (async () => {
+      try {
+        const nextClient = await this.spawnClient(resolvedRoot, serverInfo, key);
+        if (nextClient) {
+          this.recordSuccess(serverInfo.id, this.now() - spawnStart);
+        } else {
+          this.recordFailure(serverInfo.id, "spawn");
+          this.markBroken(key, "spawn");
         }
-      })();
-      this.spawning.set(key, spawnPromise);
-      client = await spawnPromise;
-    }
-    return client;
+        return nextClient;
+      } catch (error) {
+        this.recordFailure(serverInfo.id, "spawn");
+        this.markBroken(key, "spawn");
+        return null;
+      } finally {
+        this.spawning.delete(key);
+      }
+    })();
+    this.spawning.set(key, spawnPromise);
+    return spawnPromise;
   }
 };
 
@@ -1159,63 +1424,39 @@ var initParser = async () => {
 // src/utils/tree-sitter/lsp-adapter.ts
 import { readFile as readFile2 } from "fs/promises";
 var SYMBOL_KIND_MAP2 = {
-  // TypeScript / JavaScript
   function_declaration: "Function",
+  function_expression: "Function",
+  arrow_function: "Function",
   method_definition: "Method",
   class_declaration: "Class",
   interface_declaration: "Interface",
+  enum_declaration: "Enum",
+  type_alias_declaration: "Type",
   variable_declarator: "Variable",
   export_statement: "Module",
-  // Python
   function_definition: "Function",
   class_definition: "Class",
-  // Bash
-  // function_definition is shared with Python/others
-  // C#
+  assignment: "Variable",
   namespace_declaration: "Namespace",
   method_declaration: "Method",
   struct_declaration: "Struct",
-  enum_declaration: "Enum",
   property_declaration: "Property",
-  // class_declaration shared
-  // interface_declaration shared
-  // Go
   type_declaration: "Class",
-  // often struct/interface
   field_declaration: "Field",
-  // function_declaration shared
-  // method_declaration shared
-  // Rust
   function_item: "Function",
   struct_item: "Struct",
   enum_item: "Enum",
   impl_item: "Class",
   trait_item: "Interface",
   mod_item: "Module",
-  // Java
-  // class_declaration shared
-  // method_declaration shared
-  // interface_declaration shared
-  // enum_declaration shared
-  // Scala
   object_definition: "Class",
   trait_definition: "Interface",
-  // class_definition shared with Python
-  // function_definition shared with Python
-  // Ruby
   module: "Module"
-  // class shared
-  // method shared
-  // PHP
-  // class_declaration shared
-  // method_declaration shared
-  // function_definition shared
 };
 var TreeSitterLspAdapter = class {
   static async getDocumentSymbols(filePath) {
     const langId = ParserRegistry.getLanguage(filePath);
     if (!langId) {
-      console.warn(`No language found for file: ${filePath}`);
       return [];
     }
     try {
@@ -1224,8 +1465,10 @@ var TreeSitterLspAdapter = class {
       const tree = parser.parse(content);
       return this.collectSymbols(tree.rootNode);
     } catch (error) {
-      console.error(`Error parsing file ${filePath}:`, error);
-      return [];
+      if (error instanceof Error) {
+        throw new Error(`Tree-sitter parse failed for ${filePath}: ${error.message}`);
+      }
+      throw new Error(`Tree-sitter parse failed for ${filePath}`);
     }
   }
   static collectSymbols(node) {
@@ -1259,7 +1502,7 @@ var TreeSitterLspAdapter = class {
     const nameNode = node.childForFieldName("name");
     if (nameNode) return nameNode.text;
     for (const child of node.namedChildren) {
-      if (child.type === "identifier" || child.type === "type_identifier") {
+      if (child.type === "identifier" || child.type === "type_identifier" || child.type === "property_identifier" || child.type === "field_identifier" || child.type === "scoped_identifier") {
         return child.text;
       }
     }
@@ -1269,25 +1512,121 @@ var TreeSitterLspAdapter = class {
 
 // src/utils/tree-sitter/scope-analyzer.ts
 import { Query } from "web-tree-sitter";
+import { readFile as readFile3 } from "fs/promises";
+import path3 from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
+import { createHash } from "crypto";
 var QUERIES = {
   python: `
     (function_definition name: (identifier) @name)
     (parameters (identifier) @param)
     (assignment left: (identifier) @var)
+    (for_statement left: (identifier) @var)
   `,
   typescript: `
     (function_declaration name: (identifier) @name)
+    (method_definition name: (property_identifier) @name)
     (variable_declarator name: (identifier) @var)
+    (variable_declarator name: (array_pattern (identifier) @var))
+    (variable_declarator name: (object_pattern (pair_pattern key: (property_identifier) value: (identifier) @var)))
+    (variable_declarator name: (object_pattern (pair_pattern key: (property_identifier) value: (assignment_pattern left: (identifier) @var))))
+    (variable_declarator name: (object_pattern (shorthand_property_identifier_pattern) @var))
     (required_parameter pattern: (identifier) @param)
+    (required_parameter pattern: (array_pattern (identifier) @param))
+    (required_parameter pattern: (object_pattern (shorthand_property_identifier_pattern) @param))
     (optional_parameter pattern: (identifier) @param)
+    (shorthand_property_identifier_pattern) @var
+    (catch_clause (identifier) @var)
+    (for_in_statement left: (identifier) @var)
+    (for_statement initializer: (lexical_declaration (variable_declarator name: (identifier) @var)))
   `
 };
+var SCOPE_NODE_TYPES = {
+  python: /* @__PURE__ */ new Set(["function_definition", "class_definition", "module"]),
+  typescript: /* @__PURE__ */ new Set([
+    "function_declaration",
+    "function",
+    "function_expression",
+    "arrow_function",
+    "method_definition",
+    "class_declaration",
+    "statement_block",
+    "program"
+  ])
+};
+var SCOPE_BOUNDARY_TYPES = {
+  python: /* @__PURE__ */ new Set(["function_definition", "class_definition"]),
+  typescript: /* @__PURE__ */ new Set([
+    "function_declaration",
+    "function",
+    "function_expression",
+    "arrow_function",
+    "method_definition",
+    "class_declaration",
+    "statement_block"
+  ])
+};
+var __filename = fileURLToPath5(import.meta.url);
+var __dirname2 = path3.dirname(__filename);
+async function loadScopeQuery(langKey) {
+  const queryPath = path3.join(__dirname2, "queries", langKey, "locals.scm");
+  try {
+    return await readFile3(queryPath, "utf-8");
+  } catch {
+    return QUERIES[langKey] ?? null;
+  }
+}
+var QUERY_PRIORITY_LANGUAGES = ["typescript", "python"];
+var SCOPE_CACHE = /* @__PURE__ */ new Map();
+var SCOPE_CACHE_TTL_MS = 30 * 1e3;
+function computeHash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function getScopeCacheKey(langKey, code, position) {
+  const hash = computeHash(code);
+  return `${langKey}:${hash}:${position.row}:${position.column}`;
+}
+function getCachedScope(key, now) {
+  const cached = SCOPE_CACHE.get(key);
+  if (!cached) return null;
+  if (now >= cached.expiresAt) {
+    SCOPE_CACHE.delete(key);
+    return null;
+  }
+  return cached.value;
+}
 var ScopeAnalyzer = class {
+  static async getQuerySource(langKey) {
+    return loadScopeQuery(langKey);
+  }
+  static async getQueryCoverage(langKey, code) {
+    const parser = await loadLanguage(langKey);
+    const queryStr = await loadScopeQuery(langKey);
+    if (!queryStr) return { total: 0, unique: 0, names: [] };
+    const language = parser.language;
+    if (!language) return { total: 0, unique: 0, names: [] };
+    const query = new Query(language, queryStr);
+    const tree = parser.parse(code);
+    const captures = query.captures(tree.rootNode);
+    const names = captures.map((c) => c.node.text);
+    const uniqueNames = Array.from(new Set(names));
+    return { total: captures.length, unique: uniqueNames.length, names: uniqueNames };
+  }
+  static isPriorityLanguage(langKey) {
+    return QUERY_PRIORITY_LANGUAGES.includes(langKey);
+  }
+  static getPriorityLanguages() {
+    return [...QUERY_PRIORITY_LANGUAGES];
+  }
   static async getScope(filename, code, position) {
     const langKey = ParserRegistry.getLanguage(filename);
     if (!langKey) {
       throw new Error(`Unsupported language for file: ${filename}`);
     }
+    const now = Date.now();
+    const cacheKey = getScopeCacheKey(langKey, code, position);
+    const cached = getCachedScope(cacheKey, now);
+    if (cached) return cached;
     const parser = await loadLanguage(langKey);
     const tree = parser.parse(code);
     const node = tree.rootNode.descendantForPosition(position);
@@ -1297,17 +1636,16 @@ var ScopeAnalyzer = class {
       ancestors.push(current);
       current = current.parent;
     }
-    const scopeNodes = ancestors.filter(
-      (n) => n.type === "function_definition" || n.type === "function_declaration" || n.type === "module" || // Python root
-      n.type === "program"
-      // TS root
-    );
+    const scopeNodes = ancestors.filter((n) => {
+      const types = SCOPE_NODE_TYPES[langKey];
+      return types ? types.has(n.type) : false;
+    });
     const result = {
       locals: [],
       closure: []
     };
     if (scopeNodes.length === 0) return result;
-    const queryStr = QUERIES[langKey];
+    const queryStr = await loadScopeQuery(langKey);
     if (!queryStr) return result;
     const language = parser.language;
     if (!language) return result;
@@ -1319,23 +1657,53 @@ var ScopeAnalyzer = class {
       for (const capture of captures) {
         const defNode = capture.node;
         let temp = defNode.parent;
-        if (temp && (temp.type === "function_definition" || temp.type === "function_declaration")) {
-          if (capture.name === "name") {
-            temp = temp.parent;
-          }
-        }
         let isDirect = true;
         while (temp && temp.id !== scopeNode.id) {
-          if (temp.type === "function_definition" || temp.type === "function_declaration") {
+          const boundaryTypes = SCOPE_BOUNDARY_TYPES[langKey];
+          if (boundaryTypes?.has(temp.type)) {
             isDirect = false;
             break;
           }
           temp = temp.parent;
         }
+        if (capture.name === "name") {
+          const boundaryTypes = SCOPE_BOUNDARY_TYPES[langKey];
+          if (boundaryTypes?.has(defNode.parent?.type ?? "")) {
+            temp = defNode.parent?.parent ?? null;
+            isDirect = true;
+            while (temp && temp.id !== scopeNode.id) {
+              if (boundaryTypes?.has(temp.type)) {
+                isDirect = false;
+                break;
+              }
+              temp = temp.parent;
+            }
+          }
+        }
         if (isDirect) {
           names.add(defNode.text);
         }
       }
+      if (i === 0 && scopeNode.type === "statement_block") {
+        const boundaryTypes = SCOPE_BOUNDARY_TYPES[langKey];
+        const parent = scopeNode.parent;
+        if (parent && boundaryTypes?.has(parent.type)) {
+          const parentCaptures = query.captures(parent);
+          for (const capture of parentCaptures) {
+            if (capture.name === "param") {
+              names.add(capture.node.text);
+            }
+          }
+        }
+        if (parent && (parent.type === "for_in_statement" || parent.type === "for_statement")) {
+          const parentCaptures = query.captures(parent);
+          for (const capture of parentCaptures) {
+            if (capture.name === "var") {
+              names.add(capture.node.text);
+            }
+          }
+        }
+      }
       if (i === 0) {
         result.locals = Array.from(names);
       } else {
@@ -1345,6 +1713,7 @@ var ScopeAnalyzer = class {
       }
     }
     result.closure = Array.from(new Set(result.closure));
+    SCOPE_CACHE.set(cacheKey, { value: result, expiresAt: now + SCOPE_CACHE_TTL_MS });
     return result;
   }
 };
@@ -1383,6 +1752,135 @@ ${formatTreeSitterSymbols(symbols)}` : "No symbols found.";
     fileCount: symbols.length > 0 ? 1 : 0
   };
 }
+var fastPathFailures = /* @__PURE__ */ new Map();
+var fastPathLastFallbackReason = /* @__PURE__ */ new Map();
+var scopeLastFallbackReason = /* @__PURE__ */ new Map();
+var scopeStrategyUsed = /* @__PURE__ */ new Map();
+var operationFallbackReasons = /* @__PURE__ */ new Map();
+var LSP_FALLBACK_BOUNDARY = /* @__PURE__ */ new Set(["documentSymbol"]);
+var FALLBACK_TOGGLES = [
+  { operation: "diagnostics", env: "PYB_LSP_FALLBACK_DIAGNOSTICS", defaultEnabled: false },
+  { operation: "findReferences", env: "PYB_LSP_FALLBACK_REFERENCES", defaultEnabled: false },
+  {
+    operation: "prepareCallHierarchy",
+    env: "PYB_LSP_FALLBACK_CALL_HIERARCHY",
+    defaultEnabled: false
+  },
+  {
+    operation: "incomingCalls",
+    env: "PYB_LSP_FALLBACK_CALL_HIERARCHY",
+    defaultEnabled: false
+  },
+  {
+    operation: "outgoingCalls",
+    env: "PYB_LSP_FALLBACK_CALL_HIERARCHY",
+    defaultEnabled: false
+  }
+];
+function isFallbackToggleEnabled(envKey, defaultEnabled) {
+  const raw = String(process.env[envKey] ?? "").trim().toLowerCase();
+  if (!raw) return defaultEnabled;
+  if (raw === "0" || raw === "false" || raw === "off" || raw === "no") return false;
+  if (raw === "1" || raw === "true" || raw === "on" || raw === "yes") return true;
+  return defaultEnabled;
+}
+function refreshFallbackBoundaryFromEnv() {
+  for (const toggle of FALLBACK_TOGGLES) {
+    if (isFallbackToggleEnabled(toggle.env, toggle.defaultEnabled)) {
+      LSP_FALLBACK_BOUNDARY.add(toggle.operation);
+    } else {
+      LSP_FALLBACK_BOUNDARY.delete(toggle.operation);
+    }
+  }
+}
+refreshFallbackBoundaryFromEnv();
+var FAST_PATH_CONFIG = {
+  exception: { windowMs: 5 * 60 * 1e3, threshold: 3 },
+  empty: { windowMs: 60 * 1e3, threshold: 2 },
+  timeout: { windowMs: 30 * 1e3, threshold: 1 }
+};
+var FAST_PATH_TIMEOUT_MS = 500;
+var FAST_PATH_CACHE_TTL_MS = 30 * 1e3;
+var fastPathSymbolCache = /* @__PURE__ */ new Map();
+function recordFastPathFailure(filePath, reason, now) {
+  let perFile = fastPathFailures.get(filePath);
+  if (!perFile) {
+    perFile = /* @__PURE__ */ new Map();
+    fastPathFailures.set(filePath, perFile);
+  }
+  const config = FAST_PATH_CONFIG[reason];
+  const existing = perFile.get(reason);
+  if (!existing || now - existing.firstAt > config.windowMs) {
+    perFile.set(reason, { count: 1, firstAt: now, lastAt: now });
+    return;
+  }
+  existing.count += 1;
+  existing.lastAt = now;
+}
+function clearFastPathFailures(filePath) {
+  fastPathFailures.delete(filePath);
+  fastPathLastFallbackReason.delete(filePath);
+}
+function recordOperationFallback(operation, filePath, reason) {
+  let perOperation = operationFallbackReasons.get(operation);
+  if (!perOperation) {
+    perOperation = /* @__PURE__ */ new Map();
+    operationFallbackReasons.set(operation, perOperation);
+  }
+  perOperation.set(filePath, reason);
+}
+function getOperationFallbackSnapshot(operation) {
+  const entries = operationFallbackReasons.get(operation);
+  if (!entries) return [];
+  return Array.from(entries.entries()).map(([filePath, reason]) => ({
+    filePath,
+    reason
+  }));
+}
+function computeContentHash(content) {
+  return createHash2("sha256").update(content).digest("hex");
+}
+function getCachedFastPathSymbols(filePath, hash, now) {
+  const cached = fastPathSymbolCache.get(filePath);
+  if (!cached) return null;
+  if (cached.hash !== hash || now >= cached.expiresAt) {
+    fastPathSymbolCache.delete(filePath);
+    return null;
+  }
+  return cached.symbols;
+}
+function setCachedFastPathSymbols(filePath, hash, symbols, now) {
+  fastPathSymbolCache.set(filePath, {
+    hash,
+    symbols,
+    expiresAt: now + FAST_PATH_CACHE_TTL_MS
+  });
+}
+function shouldSkipFastPath(filePath, now) {
+  const perFile = fastPathFailures.get(filePath);
+  if (!perFile) return null;
+  for (const [reason, state] of perFile.entries()) {
+    const config = FAST_PATH_CONFIG[reason];
+    if (now - state.firstAt <= config.windowMs && state.count >= config.threshold) {
+      return reason;
+    }
+  }
+  return null;
+}
+function withTimeout(promise, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error("Tree-sitter timeout"));
+    }, timeoutMs);
+    promise.then((result) => {
+      clearTimeout(timer);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
 function normalizeWorkspaceSymbol(sym) {
   if (!sym || typeof sym !== "object") return null;
   const range = sym.range ?? sym.location?.range;
@@ -1390,6 +1888,97 @@ function normalizeWorkspaceSymbol(sym) {
   const uri = sym.uri ?? sym.location?.uri;
   return { ...sym, range, uri };
 }
+function isIdentifierChar(char) {
+  return /[A-Za-z0-9_$']/.test(char);
+}
+function extractTokenAtPosition(lines, zeroBasedLine, zeroBasedCharacter) {
+  if (zeroBasedLine < 0 || zeroBasedLine >= lines.length) return null;
+  const line = lines[zeroBasedLine] ?? "";
+  if (zeroBasedCharacter < 0 || zeroBasedCharacter > line.length) return null;
+  const tokenRe = /[\w$'!]+|[+\-*/%&|^~<>=]+/g;
+  let match;
+  while ((match = tokenRe.exec(line)) !== null) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (zeroBasedCharacter >= start && zeroBasedCharacter < end) {
+      const token = match[0];
+      return token.length > 50 ? token.slice(0, 50) : token;
+    }
+  }
+  return null;
+}
+function findTokenOccurrencesInLines(token, lines) {
+  const results = [];
+  if (!token) return results;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const line = lines[lineIndex];
+    let fromIndex = 0;
+    while (fromIndex < line.length) {
+      const index = line.indexOf(token, fromIndex);
+      if (index === -1) break;
+      const before = index > 0 ? line[index - 1] : "";
+      const afterIndex = index + token.length;
+      const after = afterIndex < line.length ? line[afterIndex] : "";
+      if ((!before || !isIdentifierChar(before)) && (!after || !isIdentifierChar(after))) {
+        results.push({ line: lineIndex, start: index, end: afterIndex });
+      }
+      fromIndex = index + token.length;
+    }
+  }
+  return results;
+}
+function findSymbolAtPosition(symbols, line, character) {
+  let matched = null;
+  const visit = (node) => {
+    if (!node?.range) return;
+    const start = node.range.start;
+    const end = node.range.end;
+    const within = line > start.line || line === start.line && character >= start.character ? line < end.line || line === end.line && character <= end.character : false;
+    if (within) {
+      matched = node;
+      if (Array.isArray(node.children)) {
+        for (const child of node.children) {
+          visit(child);
+        }
+      }
+    }
+  };
+  for (const sym of symbols) visit(sym);
+  return matched;
+}
+async function getTreeSitterDiagnostics(filePath) {
+  const lang = ParserRegistry.getLanguage(filePath);
+  if (!lang) return [];
+  const parser = await loadLanguage(lang);
+  const content = await readFile4(filePath, "utf-8");
+  const tree = parser.parse(content);
+  if (!tree) return [];
+  const diagnostics = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    const shouldReport = node.type === "ERROR" || node.isMissing || node.hasError && node.childCount === 0;
+    if (shouldReport) {
+      const range = {
+        start: { line: node.startPosition.row, character: node.startPosition.column },
+        end: { line: node.endPosition.row, character: node.endPosition.column }
+      };
+      const key = `${range.start.line}:${range.start.character}:${range.end.line}:${range.end.character}:${node.type}`;
+      if (!seen.has(key)) {
+        diagnostics.push({
+          range,
+          message: `Syntax error near ${node.type}`,
+          severity: 1
+        });
+        seen.add(key);
+      }
+    }
+    for (const child of node.children) {
+      visit(child);
+    }
+  };
+  visit(tree.rootNode);
+  return diagnostics;
+}
 function sortWorkspaceSymbols(symbols) {
   return [...symbols].sort((a, b) => {
     const nameA = String(a?.name ?? "").toLowerCase();
@@ -1406,10 +1995,27 @@ function sortWorkspaceSymbols(symbols) {
     return charA - charB;
   });
 }
+function resolveScopeStrategy() {
+  const raw = String(process.env.PYB_GET_SCOPE_STRATEGY ?? "").trim().toLowerCase();
+  if (raw === "lsp") return "lsp";
+  return "tree-sitter";
+}
+function getDocumentSymbolFallbackSnapshot() {
+  return Array.from(fastPathLastFallbackReason.entries()).map(([filePath, reason]) => ({
+    filePath,
+    reason
+  }));
+}
+function getScopeFallbackSnapshot() {
+  return Array.from(scopeLastFallbackReason.entries()).map(([filePath, reason]) => ({
+    filePath,
+    reason
+  }));
+}
 function serveStatusWithProvider(statusProvider, options) {
   const host = options?.host ?? "127.0.0.1";
   const port = typeof options?.port === "number" ? options.port : 7337;
-  const path3 = options?.path ?? "/lsp/status";
+  const path4 = options?.path ?? "/lsp/status";
   const allowCors = options?.allowCors ?? true;
   const corsHeaders = allowCors ? {
     "Access-Control-Allow-Origin": "*",
@@ -1419,7 +2025,7 @@ function serveStatusWithProvider(statusProvider, options) {
   const server = http.createServer((req, res) => {
     const method = req.method ?? "GET";
     const url = new URL(req.url ?? "/", `http://${host}`);
-    if (url.pathname !== path3) {
+    if (url.pathname !== path4) {
       res.writeHead(404, corsHeaders);
       res.end("Not Found");
       return;
@@ -1439,66 +2045,103 @@ function serveStatusWithProvider(statusProvider, options) {
     res.end(JSON.stringify(status, null, 2));
   });
   server.port = port;
-  server.listen(port, host);
+  server.listen(port, host, () => {
+    const address = server.address();
+    if (address && typeof address === "object") {
+      ;
+      server.port = address.port;
+    }
+  });
   return server;
 }
 var LspAPI = {
   async run(input) {
     const rootPath = input.rootPath ?? getCwd();
-    const client = await LspClientManager.getInstance().getClient(
+    const manager = LspClientManager.getInstance();
+    const client = await manager.getClient(
       input.filePath,
       rootPath
     );
+    const ext = extname2(input.filePath);
+    const fallbackServer = LspServerRegistry.getInstance().getServerForExtension(ext);
+    const serverId = client ? client.serverId ?? fallbackServer?.id ?? "unknown" : fallbackServer?.id ?? "unknown";
+    const recordAttempt = (operation) => {
+      manager.recordRequestAttempt(serverId, operation);
+    };
+    const recordSuccess = (operation, startedAt) => {
+      manager.recordRequestSuccess(serverId, operation, Date.now() - startedAt);
+    };
+    const recordFailure = (operation, reason) => {
+      manager.recordRequestFailure(serverId, operation, reason);
+    };
     if (client) {
       try {
         switch (input.operation) {
           case "goToDefinition": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("goToDefinition");
+              recordFailure("goToDefinition", "invalid");
               return {
                 formatted: "Error performing goToDefinition: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("goToDefinition");
+            const startedAt = Date.now();
             const result = await client.goToDefinition(
               input.filePath,
               input.line,
               input.character
             );
+            recordSuccess("goToDefinition", startedAt);
             return formatGenericDefinitionResult(result);
           }
           case "findReferences": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("findReferences");
+              recordFailure("findReferences", "invalid");
               return {
                 formatted: "Error performing findReferences: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("findReferences");
+            const startedAt = Date.now();
             const result = await client.findReferences(
               input.filePath,
               input.line,
               input.character
             );
+            recordSuccess("findReferences", startedAt);
             return formatGenericReferencesResult(result);
           }
           case "hover": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("hover");
+              recordFailure("hover", "invalid");
               return {
                 formatted: "Error performing hover: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("hover");
+            const startedAt = Date.now();
             const result = await client.hover(
               input.filePath,
               input.line,
               input.character
             );
+            recordSuccess("hover", startedAt);
             return formatGenericHoverResult(result, input.line, input.character);
           }
           case "documentSymbol": {
+            recordAttempt("documentSymbol");
+            const startedAt = Date.now();
             const result = await client.documentSymbol(input.filePath);
+            recordSuccess("documentSymbol", startedAt);
             return formatGenericDocumentSymbolResult(result);
           }
           case "workspaceSymbol": {
@@ -1511,44 +2154,58 @@ var LspAPI = {
           }
           case "goToImplementation": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("goToImplementation");
+              recordFailure("goToImplementation", "invalid");
               return {
                 formatted: "Error performing goToImplementation: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("goToImplementation");
+            const startedAt = Date.now();
             const result = await client.goToImplementation(
               input.filePath,
               input.line,
               input.character
             );
+            recordSuccess("goToImplementation", startedAt);
             return formatGenericDefinitionResult(result);
           }
           case "prepareCallHierarchy": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("prepareCallHierarchy");
+              recordFailure("prepareCallHierarchy", "invalid");
               return {
                 formatted: "Error performing prepareCallHierarchy: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("prepareCallHierarchy");
+            const startedAt = Date.now();
             const result = await client.prepareCallHierarchy(
               input.filePath,
               input.line,
               input.character
             );
+            recordSuccess("prepareCallHierarchy", startedAt);
             return formatGenericCallHierarchyItemsResult(
               Array.isArray(result) ? result : []
             );
           }
           case "incomingCalls": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("incomingCalls");
+              recordFailure("incomingCalls", "invalid");
               return {
                 formatted: "Error performing incomingCalls: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("incomingCalls");
+            const startedAt = Date.now();
             const items = await client.prepareCallHierarchy(
               input.filePath,
               input.line,
@@ -1560,16 +2217,21 @@ var LspAPI = {
               )
             );
             const calls = callResults.flat().filter(Boolean);
+            recordSuccess("incomingCalls", startedAt);
             return formatGenericIncomingCallsResult(calls);
           }
           case "outgoingCalls": {
             if (input.line === void 0 || input.character === void 0) {
+              recordAttempt("outgoingCalls");
+              recordFailure("outgoingCalls", "invalid");
               return {
                 formatted: "Error performing outgoingCalls: Missing line/character",
                 resultCount: 0,
                 fileCount: 0
               };
             }
+            recordAttempt("outgoingCalls");
+            const startedAt = Date.now();
             const items = await client.prepareCallHierarchy(
               input.filePath,
               input.line,
@@ -1581,9 +2243,12 @@ var LspAPI = {
               )
             );
             const calls = callResults.flat().filter(Boolean);
+            recordSuccess("outgoingCalls", startedAt);
             return formatGenericOutgoingCallsResult(calls);
           }
           case "diagnostics": {
+            recordAttempt("diagnostics");
+            const startedAt = Date.now();
             if (input.waitForDiagnostics) {
               await client.waitForReadiness(
                 input.filePath,
@@ -1591,6 +2256,7 @@ var LspAPI = {
               );
             }
             const diagnostics = client.getDiagnostics(input.filePath);
+            recordSuccess("diagnostics", startedAt);
             return formatGenericDiagnosticsResult(diagnostics);
           }
           default: {
@@ -1602,6 +2268,8 @@ var LspAPI = {
           }
         }
       } catch (error) {
+        recordAttempt(input.operation);
+        recordFailure(input.operation, "error");
         const message = error instanceof Error ? error.message : String(error);
         return {
           formatted: `Error performing ${input.operation} with generic client: ${message}`,
@@ -1610,7 +2278,112 @@ var LspAPI = {
         };
       }
     }
-    const ext = extname2(input.filePath);
+    const fallbackOperation = input.operation;
+    recordAttempt(input.operation);
+    recordFailure(input.operation, "unavailable");
+    if (LSP_FALLBACK_BOUNDARY.has(fallbackOperation)) {
+      const lang = ParserRegistry.getLanguage(input.filePath);
+      if (!lang) {
+        recordOperationFallback(fallbackOperation, input.filePath, "unsupported");
+      } else {
+        recordOperationFallback(fallbackOperation, input.filePath, "lsp-unavailable");
+        if (fallbackOperation === "diagnostics") {
+          try {
+            const diagnostics = await getTreeSitterDiagnostics(input.filePath);
+            const formatted = formatGenericDiagnosticsResult(diagnostics);
+            return {
+              formatted: `Diagnostics fallback: ${formatted.formatted}`,
+              resultCount: formatted.resultCount,
+              fileCount: formatted.fileCount
+            };
+          } catch {
+            return {
+              formatted: `Diagnostics fallback: LSP unavailable for ${ext}. Static analysis not available.`,
+              resultCount: 0,
+              fileCount: 0
+            };
+          }
+        }
+        if (fallbackOperation === "findReferences") {
+          if (input.line !== void 0 && input.character !== void 0) {
+            try {
+              const content = await readFile4(input.filePath, "utf-8");
+              const lines = content.split("\n");
+              const token = extractTokenAtPosition(
+                lines,
+                input.line - 1,
+                input.character - 1
+              );
+              if (token) {
+                const occurrences = findTokenOccurrencesInLines(token, lines);
+                const uri = normalizeUri(input.filePath);
+                const refs = occurrences.map((entry) => ({
+                  uri,
+                  range: {
+                    start: { line: entry.line, character: entry.start },
+                    end: { line: entry.line, character: entry.end }
+                  }
+                }));
+                if (refs.length > 0) {
+                  const formatted = formatGenericReferencesResult(refs);
+                  return {
+                    formatted: `References fallback: ${formatted.formatted}`,
+                    resultCount: formatted.resultCount,
+                    fileCount: formatted.fileCount
+                  };
+                }
+              }
+            } catch {
+            }
+          }
+          return {
+            formatted: `References fallback: LSP unavailable for ${ext}. Returning 0 references.`,
+            resultCount: 0,
+            fileCount: 0
+          };
+        }
+        if (fallbackOperation === "prepareCallHierarchy") {
+          if (input.line !== void 0 && input.character !== void 0) {
+            try {
+              const symbols = await TreeSitterLspAdapter.getDocumentSymbols(input.filePath);
+              const symbol = findSymbolAtPosition(
+                symbols,
+                input.line - 1,
+                input.character - 1
+              );
+              if (symbol) {
+                const item = {
+                  name: symbol.name,
+                  kind: symbol.kind,
+                  uri: normalizeUri(input.filePath),
+                  range: symbol.range,
+                  selectionRange: symbol.range
+                };
+                const formatted = formatGenericCallHierarchyItemsResult([item]);
+                return {
+                  formatted: `Call hierarchy fallback: ${formatted.formatted}`,
+                  resultCount: formatted.resultCount,
+                  fileCount: formatted.fileCount
+                };
+              }
+            } catch {
+            }
+          }
+          return {
+            formatted: `Call hierarchy fallback: LSP unavailable for ${ext}. Returning 0 items.`,
+            resultCount: 0,
+            fileCount: 0
+          };
+        }
+        if (fallbackOperation === "incomingCalls" || fallbackOperation === "outgoingCalls") {
+          return {
+            formatted: `Call hierarchy fallback: LSP unavailable for ${ext}. Returning 0 items.`,
+            resultCount: 0,
+            fileCount: 0
+          };
+        }
+      }
+    }
     return {
       formatted: `No LSP server available for file type: ${ext}`,
       resultCount: 0,
@@ -1623,7 +2396,7 @@ var LspAPI = {
   async touchFile(filePath, options = {}) {
     const client = await LspClientManager.getInstance().getClientForFile(filePath);
     if (!client) return false;
-    const content = await readFile3(filePath, "utf-8");
+    const content = await readFile4(filePath, "utf-8");
     const languageId = getLanguageId(extname2(filePath));
     await client.didOpen(filePath, content, languageId);
     if (options.wait) {
@@ -1687,12 +2460,132 @@ var LspFacade = {
   async run(input) {
     const rootPath = input.rootPath ?? getCwd();
     if (input.operation === "documentSymbol") {
-      const lang = ParserRegistry.getLanguage(input.filePath);
-      if (lang) {
+      const flag = String(process.env.PYB_LSP_STRICT_FIRST ?? "").trim().toLowerCase();
+      const lspFirst = flag === "1" || flag === "true" || flag === "on" || flag === "yes";
+      if (lspFirst) {
         try {
-          const symbols = await TreeSitterLspAdapter.getDocumentSymbols(input.filePath);
-          return formatTreeSitterDocumentSymbolResult(symbols);
+          const lspSymbols = await LspAPI.documentSymbolRaw(input.filePath, rootPath);
+          if (lspSymbols && Array.isArray(lspSymbols) && lspSymbols.length > 0) {
+            return formatGenericDocumentSymbolResult(lspSymbols);
+          }
+          const now = Date.now();
+          const lang = ParserRegistry.getLanguage(input.filePath);
+          if (!lang) {
+            fastPathLastFallbackReason.set(input.filePath, "unsupported");
+          } else {
+            let contentHash = null;
+            try {
+              const content = await readFile4(input.filePath, "utf-8");
+              contentHash = computeContentHash(content);
+              const cached = getCachedFastPathSymbols(input.filePath, contentHash, now);
+              if (cached) {
+                clearFastPathFailures(input.filePath);
+                return formatTreeSitterDocumentSymbolResult(cached);
+              }
+            } catch {
+            }
+            try {
+              const symbols = await withTimeout(
+                TreeSitterLspAdapter.getDocumentSymbols(input.filePath),
+                FAST_PATH_TIMEOUT_MS
+              );
+              if (symbols.length > 0) {
+                clearFastPathFailures(input.filePath);
+                if (contentHash) {
+                  setCachedFastPathSymbols(input.filePath, contentHash, symbols, now);
+                }
+                return formatTreeSitterDocumentSymbolResult(symbols);
+              }
+              recordFastPathFailure(input.filePath, "empty", now);
+              fastPathLastFallbackReason.set(input.filePath, "empty");
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              const reason = message.toLowerCase().includes("timeout") ? "timeout" : "exception";
+              recordFastPathFailure(input.filePath, reason, now);
+              fastPathLastFallbackReason.set(input.filePath, reason);
+            }
+          }
         } catch {
+          const now = Date.now();
+          const lang = ParserRegistry.getLanguage(input.filePath);
+          if (!lang) {
+            fastPathLastFallbackReason.set(input.filePath, "unsupported");
+          } else {
+            let contentHash = null;
+            try {
+              const content = await readFile4(input.filePath, "utf-8");
+              contentHash = computeContentHash(content);
+              const cached = getCachedFastPathSymbols(input.filePath, contentHash, now);
+              if (cached) {
+                clearFastPathFailures(input.filePath);
+                return formatTreeSitterDocumentSymbolResult(cached);
+              }
+            } catch {
+            }
+            try {
+              const symbols = await withTimeout(
+                TreeSitterLspAdapter.getDocumentSymbols(input.filePath),
+                FAST_PATH_TIMEOUT_MS
+              );
+              if (symbols.length > 0) {
+                clearFastPathFailures(input.filePath);
+                if (contentHash) {
+                  setCachedFastPathSymbols(input.filePath, contentHash, symbols, now);
+                }
+                return formatTreeSitterDocumentSymbolResult(symbols);
+              }
+              recordFastPathFailure(input.filePath, "empty", now);
+              fastPathLastFallbackReason.set(input.filePath, "empty");
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              const reason = message.toLowerCase().includes("timeout") ? "timeout" : "exception";
+              recordFastPathFailure(input.filePath, reason, now);
+              fastPathLastFallbackReason.set(input.filePath, reason);
+            }
+          }
+        }
+      } else {
+        const lang = ParserRegistry.getLanguage(input.filePath);
+        const now = Date.now();
+        if (!lang) {
+          fastPathLastFallbackReason.set(input.filePath, "unsupported");
+        } else {
+          const skipReason = shouldSkipFastPath(input.filePath, now);
+          if (skipReason) {
+            fastPathLastFallbackReason.set(input.filePath, skipReason);
+          } else {
+            let contentHash = null;
+            try {
+              const content = await readFile4(input.filePath, "utf-8");
+              contentHash = computeContentHash(content);
+              const cached = getCachedFastPathSymbols(input.filePath, contentHash, now);
+              if (cached) {
+                clearFastPathFailures(input.filePath);
+                return formatTreeSitterDocumentSymbolResult(cached);
+              }
+            } catch {
+            }
+            try {
+              const symbols = await withTimeout(
+                TreeSitterLspAdapter.getDocumentSymbols(input.filePath),
+                FAST_PATH_TIMEOUT_MS
+              );
+              if (symbols.length > 0) {
+                clearFastPathFailures(input.filePath);
+                if (contentHash) {
+                  setCachedFastPathSymbols(input.filePath, contentHash, symbols, now);
+                }
+                return formatTreeSitterDocumentSymbolResult(symbols);
+              }
+              recordFastPathFailure(input.filePath, "empty", now);
+              fastPathLastFallbackReason.set(input.filePath, "empty");
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              const reason = message.toLowerCase().includes("timeout") ? "timeout" : "exception";
+              recordFastPathFailure(input.filePath, reason, now);
+              fastPathLastFallbackReason.set(input.filePath, reason);
+            }
+          }
         }
       }
     }
@@ -1713,7 +2606,13 @@ var LspFacade = {
         };
       }
       try {
-        const code = await readFile3(input.filePath, "utf-8");
+        const strategy = resolveScopeStrategy();
+        if (strategy === "lsp") {
+          scopeLastFallbackReason.set(input.filePath, "lsp-unavailable");
+        }
+        const effectiveStrategy = strategy === "lsp" ? "tree-sitter" : strategy;
+        scopeStrategyUsed.set(input.filePath, effectiveStrategy);
+        const code = await readFile4(input.filePath, "utf-8");
         const scope = await ScopeAnalyzer.getScope(input.filePath, code, {
           row: input.line - 1,
           column: input.character - 1
@@ -1820,9 +2719,50 @@ var LspFacade = {
     return serveStatusWithProvider(() => LspFacade.status(), options);
   },
   status() {
-    return LspAPI.status();
+    const base = LspAPI.status();
+    return {
+      ...base,
+      installNotices: getInstallNotices(),
+      fallbacks: {
+        documentSymbol: getDocumentSymbolFallbackSnapshot(),
+        getScope: getScopeFallbackSnapshot(),
+        diagnostics: getOperationFallbackSnapshot("diagnostics"),
+        findReferences: getOperationFallbackSnapshot("findReferences"),
+        prepareCallHierarchy: getOperationFallbackSnapshot("prepareCallHierarchy"),
+        incomingCalls: getOperationFallbackSnapshot("incomingCalls"),
+        outgoingCalls: getOperationFallbackSnapshot("outgoingCalls"),
+        boundary: Array.from(LSP_FALLBACK_BOUNDARY.values())
+      }
+    };
   }
 };
+function __resetLspFastPathStateForTests() {
+  fastPathFailures.clear();
+  fastPathLastFallbackReason.clear();
+  fastPathSymbolCache.clear();
+}
+function __resetLspOperationFallbackForTests() {
+  operationFallbackReasons.clear();
+}
+function __getLspFastPathFallbackReasonForTests(filePath) {
+  return fastPathLastFallbackReason.get(filePath) ?? null;
+}
+function __resetScopeStateForTests() {
+  scopeLastFallbackReason.clear();
+  scopeStrategyUsed.clear();
+}
+function __getScopeFallbackReasonForTests(filePath) {
+  return scopeLastFallbackReason.get(filePath) ?? null;
+}
+function __getScopeStrategyForTests(filePath) {
+  return scopeStrategyUsed.get(filePath) ?? null;
+}
+function __getFallbackBoundaryForTests() {
+  return Array.from(LSP_FALLBACK_BOUNDARY.values());
+}
+function __refreshLspFallbackBoundaryForTests() {
+  refreshFallbackBoundaryFromEnv();
+}
 
 export {
   formatDiagnosticsPretty,
@@ -1830,5 +2770,13 @@ export {
   loadLanguage,
   initParser,
   LspAPI,
-  LspFacade
+  LspFacade,
+  __resetLspFastPathStateForTests,
+  __resetLspOperationFallbackForTests,
+  __getLspFastPathFallbackReasonForTests,
+  __resetScopeStateForTests,
+  __getScopeFallbackReasonForTests,
+  __getScopeStrategyForTests,
+  __getFallbackBoundaryForTests,
+  __refreshLspFallbackBoundaryForTests
 };