repowisestage 0.0.46 → 0.0.48

package/dist/bin/repowise.js

@@ -721,6 +721,200 @@ var init_registry = __esm({
   }
 });
 
+// ../listener/dist/lsp/installer.js
+import { promises as fs } from "fs";
+import { join as join14, dirname as dirname5 } from "path";
+import { spawn as spawn3 } from "child_process";
+function getLspInstallDir() {
+  return join14(getConfigDir(), "lsp-servers");
+}
+function getLspBinDir() {
+  return join14(getLspInstallDir(), "node_modules", ".bin");
+}
+async function ensureNpmLspInstalled(config2) {
+  if (!config2.npmPackage)
+    return { installed: false, skipped: "no-npm-package" };
+  const installDir = getLspInstallDir();
+  const binPath = join14(installDir, "node_modules", ".bin", config2.command);
+  if (await pathExists(binPath)) {
+    return { installed: false, skipped: "already-present" };
+  }
+  try {
+    await fs.mkdir(installDir, { recursive: true });
+    const pkgJsonPath = join14(installDir, "package.json");
+    if (!await pathExists(pkgJsonPath)) {
+      await fs.writeFile(pkgJsonPath, JSON.stringify({ name: "repowise-lsp-servers", private: true, version: "0.0.0" }, null, 2), "utf-8");
+    }
+    await runNpmInstall(installDir, config2.npmPackage);
+    if (!await pathExists(binPath)) {
+      return {
+        installed: false,
+        error: `npm install completed but ${config2.command} still not at ${binPath}`
+      };
+    }
+    return { installed: true };
+  } catch (err) {
+    return {
+      installed: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function resolveNpmCommand() {
+  const nodeDir = dirname5(process.execPath);
+  for (const candidate of [join14(nodeDir, "npm"), join14(nodeDir, "npm.cmd")]) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  for (const candidate of ["/opt/homebrew/bin/npm", "/usr/local/bin/npm", "/usr/bin/npm"]) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return "npm";
+}
+async function runNpmInstall(cwd, pkg2) {
+  const npmCmd = await resolveNpmCommand();
+  const nodeDir = dirname5(process.execPath);
+  const augmentedPath = process.env.PATH ? `${nodeDir}:${process.env.PATH}` : nodeDir;
+  return new Promise((resolve4, reject) => {
+    const child = spawn3(npmCmd, ["install", "--no-audit", "--no-fund", "--silent", pkg2], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, PATH: augmentedPath }
+    });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => reject(err));
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve4();
+      } else {
+        reject(new Error(`npm install ${pkg2} exited ${(code ?? -1).toString()}: ${sanitizeNpmStderr(stderr)}`));
+      }
+    });
+  });
+}
+function sanitizeNpmStderr(raw) {
+  const truncated = raw.split("\n").slice(0, 3).join(" ").trim();
+  return truncated.replace(/(https?:\/\/)[^@\s/]*@/g, (_match, scheme) => `${scheme}<redacted>@`);
+}
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectRepoLanguages(repoRoot) {
+  const found = /* @__PURE__ */ new Set();
+  let inspected = 0;
+  const MAX_INSPECT = 200;
+  async function inspect(dir) {
+    if (inspected >= MAX_INSPECT)
+      return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (inspected >= MAX_INSPECT)
+        return;
+      if (name.startsWith("."))
+        continue;
+      if (name === "node_modules" || name === "dist" || name === "build")
+        continue;
+      const lang = detectLanguage(name);
+      if (lang) {
+        found.add(lang);
+        inspected += 1;
+      }
+    }
+  }
+  await inspect(repoRoot);
+  let topEntries = [];
+  try {
+    topEntries = await fs.readdir(repoRoot);
+  } catch {
+    return found;
+  }
+  for (const name of topEntries) {
+    if (name.startsWith("."))
+      continue;
+    if (name === "node_modules" || name === "dist" || name === "build")
+      continue;
+    const sub = join14(repoRoot, name);
+    try {
+      const stat7 = await fs.stat(sub);
+      if (stat7.isDirectory())
+        await inspect(sub);
+    } catch {
+    }
+  }
+  return found;
+}
+async function prepareLspServersForRepos(repos) {
+  const detected = /* @__PURE__ */ new Set();
+  for (const r of repos) {
+    if (!r.localPath)
+      continue;
+    try {
+      const stat7 = await fs.stat(r.localPath);
+      if (!stat7.isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    try {
+      const langs = await detectRepoLanguages(r.localPath);
+      for (const l of langs)
+        detected.add(l);
+    } catch {
+    }
+  }
+  const results = [];
+  for (const language of detected) {
+    const configs = LSP_REGISTRY[language];
+    const npmConfig = configs.find((c) => c.npmPackage);
+    if (!npmConfig) {
+      results.push({
+        language,
+        installed: false,
+        alreadyPresent: false,
+        skippedNoNpmPackage: true,
+        hint: configs[0]?.installHint
+      });
+      continue;
+    }
+    const outcome = await ensureNpmLspInstalled(npmConfig);
+    results.push({
+      language,
+      installed: outcome.installed,
+      alreadyPresent: outcome.skipped === "already-present",
+      skippedNoNpmPackage: false,
+      error: outcome.error
+    });
+  }
+  return results;
+}
+var init_installer = __esm({
+  "../listener/dist/lsp/installer.js"() {
+    "use strict";
+    init_config_dir();
+    init_registry();
+  }
+});
+
 // ../../packages/shared/src/types/typed-resolution.ts
 function typedResolutionKey(filePath, propertyName, line, column) {
   return `${filePath}\0${propertyName}\0${line.toString()}\0${column.toString()}`;
@@ -1122,6 +1316,7 @@ var init_sidecar_client = __esm({
 // ../listener/dist/lsp/lsp-tools.js
 var lsp_tools_exports = {};
 __export(lsp_tools_exports, {
+  emptyLspResult: () => emptyLspResult,
   lspCallHierarchy: () => lspCallHierarchy,
   lspDefinition: () => lspDefinition,
   lspDocumentSymbol: () => lspDocumentSymbol,
@@ -1132,7 +1327,8 @@ __export(lsp_tools_exports, {
   lspWorkspaceSymbol: () => lspWorkspaceSymbol
 });
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { relative as pathRelative, resolve as pathResolve3 } from "path";
+import { relative as pathRelative, resolve as pathResolve3, join as pathJoin } from "path";
+import { existsSync } from "fs";
 import { execSync } from "child_process";
 function probeBinary(command) {
   if (process.env["VITEST"])
@@ -1142,8 +1338,12 @@ function probeBinary(command) {
     return cached;
   let found = false;
   try {
-    execSync(`which ${command}`, { stdio: "ignore", timeout: 200 });
-    found = true;
+    if (existsSync(pathJoin(getLspBinDir(), command))) {
+      found = true;
+    } else {
+      execSync(`which ${command}`, { stdio: "ignore", timeout: 200 });
+      found = true;
+    }
   } catch {
     found = false;
   }
@@ -1158,6 +1358,25 @@ function pickAvailableConfig(configs, isAvailable) {
   }
   return null;
 }
+function emptyLspResult(reason, details) {
+  if (reason === "unsupported-language") {
+    return {
+      ok: false,
+      reason,
+      isError: true,
+      error: "unsupported-language" + (details?.language ? `: ${details.language}` : "") + " \u2014 no LSP server registered for this file extension.",
+      hint: "RepoWise auto-installs LSP servers for known languages (TS/JS, Python, Go, Rust, Ruby, etc.). For an unsupported language fall back to graph-only tools: `find_symbol`, `find_callers`, `find_references`, `get_call_graph`."
+    };
+  }
+  const triedFrag = details?.tried && details.tried.length > 0 ? ` (tried: ${details.tried.join(", ")})` : "";
+  return {
+    ok: false,
+    reason,
+    isError: true,
+    error: `no-server-available${triedFrag} \u2014 the LSP binary for this language isn't on PATH or in the listener's install dir.`,
+    hint: "The listener auto-installs npm-based LSP servers (pyright, typescript-language-server, etc.) on boot. If the install failed, check listener stderr for the underlying npm error. Non-npm servers (gopls, rust-analyzer, sourcekit-lsp, ruby-lsp) need manual install \u2014 see the listener log for the per-language hint. Until then, use graph-only tools (`find_symbol`, `find_callers`, etc.) for this file."
+  };
+}
 function toOneIndexed(pos) {
   return { line: pos.line + 1, column: pos.character + 1 };
 }
@@ -1220,13 +1439,13 @@ function normalizeLocations(raw, repoRoot) {
 async function getSession(deps, file) {
   const language = detectLanguage(file);
   if (!language)
-    return { ok: false, reason: "unsupported-language" };
+    return emptyLspResult("unsupported-language");
   const configs = LSP_REGISTRY[language];
   const config2 = pickAvailableConfig(configs, deps.binaryAvailable);
   if (!config2) {
-    const tried = configs.map((c) => c.command).join(", ");
-    console.warn(`[lsp:${language}] no server available on PATH \u2014 tried: ${tried}`);
-    return { ok: false, reason: "no-server-available" };
+    const tried = configs.map((c) => c.command);
+    console.warn(`[lsp:${language}] no server available on PATH \u2014 tried: ${tried.join(", ")}`);
+    return emptyLspResult("no-server-available", { language, tried });
   }
   const session = await deps.workspaces.getOrOpen({
     repoRoot: deps.repoRoot,
@@ -1239,7 +1458,7 @@ async function getSession(deps, file) {
 async function lspDefinition(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/definition", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1249,7 +1468,7 @@ async function lspDefinition(deps, req) {
 async function lspReferences(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/references", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position),
@@ -1260,7 +1479,7 @@ async function lspReferences(deps, req) {
 async function lspHover(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/hover", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1303,7 +1522,7 @@ function normalizeHoverContents(contents) {
 async function lspCallHierarchy(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const limit = req.limit ?? 200;
   const prepared = await got.session.client.request("textDocument/prepareCallHierarchy", {
     textDocument: { uri: got.uri },
@@ -1342,7 +1561,7 @@ async function lspCallHierarchy(deps, req) {
 async function lspImplementation(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/implementation", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1352,7 +1571,7 @@ async function lspImplementation(deps, req) {
 async function lspTypeHierarchy(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const limit = req.limit ?? 200;
   const prepared = await got.session.client.request("textDocument/prepareTypeHierarchy", {
     textDocument: { uri: got.uri },
@@ -1388,8 +1607,11 @@ async function lspTypeHierarchy(deps, req) {
 }
 async function lspWorkspaceSymbol(deps, req) {
   const sessions = deps.workspaces.activeSessions().filter((s) => !req.language || s.language === req.language);
-  if (sessions.length === 0)
-    return { ok: false, reason: "no-server-available" };
+  if (sessions.length === 0) {
+    return emptyLspResult("no-server-available", {
+      language: req.language
+    });
+  }
   const symbols = [];
   for (const session of sessions) {
     const raw = await session.client.request("workspace/symbol", { query: req.query });
@@ -1417,7 +1639,7 @@ async function lspWorkspaceSymbol(deps, req) {
 async function lspDocumentSymbol(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const raw = await got.session.client.request("textDocument/documentSymbol", {
     textDocument: { uri: got.uri }
   });
@@ -1465,6 +1687,7 @@ var init_lsp_tools = __esm({
   "../listener/dist/lsp/lsp-tools.js"() {
     "use strict";
     init_registry();
+    init_installer();
     binaryProbeCache = /* @__PURE__ */ new Map();
   }
 });
@@ -3042,196 +3265,8 @@ var LspClient = class extends EventEmitter {
   }
 };
 
-// ../listener/dist/lsp/installer.js
-init_config_dir();
-init_registry();
-import { promises as fs } from "fs";
-import { join as join14, dirname as dirname5 } from "path";
-import { spawn as spawn3 } from "child_process";
-function getLspInstallDir() {
-  return join14(getConfigDir(), "lsp-servers");
-}
-function getLspBinDir() {
-  return join14(getLspInstallDir(), "node_modules", ".bin");
-}
-async function ensureNpmLspInstalled(config2) {
-  if (!config2.npmPackage)
-    return { installed: false, skipped: "no-npm-package" };
-  const installDir = getLspInstallDir();
-  const binPath = join14(installDir, "node_modules", ".bin", config2.command);
-  if (await pathExists(binPath)) {
-    return { installed: false, skipped: "already-present" };
-  }
-  try {
-    await fs.mkdir(installDir, { recursive: true });
-    const pkgJsonPath = join14(installDir, "package.json");
-    if (!await pathExists(pkgJsonPath)) {
-      await fs.writeFile(pkgJsonPath, JSON.stringify({ name: "repowise-lsp-servers", private: true, version: "0.0.0" }, null, 2), "utf-8");
-    }
-    await runNpmInstall(installDir, config2.npmPackage);
-    if (!await pathExists(binPath)) {
-      return {
-        installed: false,
-        error: `npm install completed but ${config2.command} still not at ${binPath}`
-      };
-    }
-    return { installed: true };
-  } catch (err) {
-    return {
-      installed: false,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-async function resolveNpmCommand() {
-  const nodeDir = dirname5(process.execPath);
-  for (const candidate of [join14(nodeDir, "npm"), join14(nodeDir, "npm.cmd")]) {
-    try {
-      await fs.access(candidate);
-      return candidate;
-    } catch {
-    }
-  }
-  for (const candidate of ["/opt/homebrew/bin/npm", "/usr/local/bin/npm", "/usr/bin/npm"]) {
-    try {
-      await fs.access(candidate);
-      return candidate;
-    } catch {
-    }
-  }
-  return "npm";
-}
-async function runNpmInstall(cwd, pkg2) {
-  const npmCmd = await resolveNpmCommand();
-  const nodeDir = dirname5(process.execPath);
-  const augmentedPath = process.env.PATH ? `${nodeDir}:${process.env.PATH}` : nodeDir;
-  return new Promise((resolve4, reject) => {
-    const child = spawn3(npmCmd, ["install", "--no-audit", "--no-fund", "--silent", pkg2], {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, PATH: augmentedPath }
-    });
-    let stderr = "";
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on("error", (err) => reject(err));
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve4();
-      } else {
-        reject(new Error(`npm install ${pkg2} exited ${(code ?? -1).toString()}: ${sanitizeNpmStderr(stderr)}`));
-      }
-    });
-  });
-}
-function sanitizeNpmStderr(raw) {
-  const truncated = raw.split("\n").slice(0, 3).join(" ").trim();
-  return truncated.replace(/(https?:\/\/)[^@\s/]*@/g, (_match, scheme) => `${scheme}<redacted>@`);
-}
-async function pathExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function detectRepoLanguages(repoRoot) {
-  const found = /* @__PURE__ */ new Set();
-  let inspected = 0;
-  const MAX_INSPECT = 200;
-  async function inspect(dir) {
-    if (inspected >= MAX_INSPECT)
-      return;
-    let entries;
-    try {
-      entries = await fs.readdir(dir);
-    } catch {
-      return;
-    }
-    for (const name of entries) {
-      if (inspected >= MAX_INSPECT)
-        return;
-      if (name.startsWith("."))
-        continue;
-      if (name === "node_modules" || name === "dist" || name === "build")
-        continue;
-      const lang = detectLanguage(name);
-      if (lang) {
-        found.add(lang);
-        inspected += 1;
-      }
-    }
-  }
-  await inspect(repoRoot);
-  let topEntries = [];
-  try {
-    topEntries = await fs.readdir(repoRoot);
-  } catch {
-    return found;
-  }
-  for (const name of topEntries) {
-    if (name.startsWith("."))
-      continue;
-    if (name === "node_modules" || name === "dist" || name === "build")
-      continue;
-    const sub = join14(repoRoot, name);
-    try {
-      const stat7 = await fs.stat(sub);
-      if (stat7.isDirectory())
-        await inspect(sub);
-    } catch {
-    }
-  }
-  return found;
-}
-async function prepareLspServersForRepos(repos) {
-  const detected = /* @__PURE__ */ new Set();
-  for (const r of repos) {
-    if (!r.localPath)
-      continue;
-    try {
-      const stat7 = await fs.stat(r.localPath);
-      if (!stat7.isDirectory())
-        continue;
-    } catch {
-      continue;
-    }
-    try {
-      const langs = await detectRepoLanguages(r.localPath);
-      for (const l of langs)
-        detected.add(l);
-    } catch {
-    }
-  }
-  const results = [];
-  for (const language of detected) {
-    const configs = LSP_REGISTRY[language];
-    const npmConfig = configs.find((c) => c.npmPackage);
-    if (!npmConfig) {
-      results.push({
-        language,
-        installed: false,
-        alreadyPresent: false,
-        skippedNoNpmPackage: true,
-        hint: configs[0]?.installHint
-      });
-      continue;
-    }
-    const outcome = await ensureNpmLspInstalled(npmConfig);
-    results.push({
-      language,
-      installed: outcome.installed,
-      alreadyPresent: outcome.skipped === "already-present",
-      skippedNoNpmPackage: false,
-      error: outcome.error
-    });
-  }
-  return results;
-}
-
 // ../listener/dist/lsp/workspace-session.js
+init_installer();
 function keyOf(args) {
   return `${args.repoRoot}\0${args.language}`;
 }
@@ -4321,8 +4356,8 @@ var TOOL_CATALOG = [
   },
   {
     name: "search_pattern",
-    description: "Regex-match symbol names across the graph.",
-    whenToUse: 'Use when the user asks for a pattern rather than a literal substring \u2014 e.g. "anything ending in `Repository`", "every `handle*` function". For plain substring search use `find_symbol`.',
+    description: "JavaScript-flavor regex match against symbol names. Uses `new RegExp(pattern, flags)` \u2014 no Python-only constructs (`(?P<name>...)`, `(?i)`-style inline flags, `\\A` / `\\Z` anchors).",
+    whenToUse: 'Use when the user asks for a pattern rather than a literal substring \u2014 e.g. "anything ending in `Repository`", "every `handle*` function". For plain substring search use `find_symbol`. For case-insensitive matching set `flags: "i"`, NOT a `(?i)` prefix.',
     inputSchema: {
       type: "object",
       properties: {
@@ -4789,16 +4824,31 @@ function listEdges(graphJson, req) {
     freshness: freshnessEnvelope(graph)
   };
 }
+function detectCommonRegexMistake(pattern) {
+  if (/\(\?P</.test(pattern)) {
+    return "Python named groups `(?P<name>\u2026)` aren't supported. Use `(?<name>\u2026)` (JS named-group syntax) or just `(\u2026)`.";
+  }
+  if (/^\(\?[ims]+\)/.test(pattern)) {
+    return 'Python-style inline flags `(?i)` aren\'t supported. Pass them as the `flags` parameter, e.g. `flags: "i"`.';
+  }
+  if (/\\A|\\Z/.test(pattern)) {
+    return "Python anchors `\\A` / `\\Z` are valid JS regex but match LITERAL `A` / `Z`, not start-of-string / end-of-string. Use `^` / `$` (JS anchors) with the `m` flag for multiline.";
+  }
+  return void 0;
+}
 var MAX_PATTERN_LENGTH = 200;
 var REDOS_PATTERN = /(\([^)]*[+*]\)|\[[^\]]*[+*]\])[+*?]/;
 function searchPattern(graphJson, req) {
   const graph = graphJson;
   if (!req.pattern || req.pattern.length > MAX_PATTERN_LENGTH) {
+    const reason = !req.pattern ? "Empty pattern \u2014 pass a non-empty regex string." : `Pattern exceeds ${MAX_PATTERN_LENGTH.toString()} chars (${req.pattern.length.toString()} chars). Use a tighter expression or filter via \`kind\` / \`language\` / \`file\`.`;
     return {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      unsafePattern: true
+      unsafePattern: true,
+      error: reason,
+      isError: true
     };
   }
   if (REDOS_PATTERN.test(req.pattern)) {
@@ -4806,19 +4856,26 @@ function searchPattern(graphJson, req) {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      unsafePattern: true
+      unsafePattern: true,
+      error: "Pattern rejected by ReDoS guard \u2014 nested quantifiers like `(a+)+` or `[\u2026]*+` can cause catastrophic backtracking. Flatten the quantifiers or split into multiple calls.",
+      isError: true
     };
   }
   const flags = (req.flags ?? "").replace(/g/g, "");
   let re;
   try {
     re = new RegExp(req.pattern, flags);
-  } catch {
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const hint = detectCommonRegexMistake(req.pattern);
     return {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      invalidPattern: true
+      invalidPattern: true,
+      error: msg,
+      ...hint ? { hint } : {},
+      isError: true
     };
   }
   const kinds = normaliseFilter(req.kind);
@@ -4854,10 +4911,12 @@ function searchPattern(graphJson, req) {
       return bScore - aScore;
     return a.id.localeCompare(b.id);
   });
+  const proactiveHint = matches.length === 0 ? detectCommonRegexMistake(req.pattern) : void 0;
   return {
     matches: matches.slice(0, limit),
     coverage: coverageEnvelope(graph, matches.length),
-    freshness: freshnessEnvelope(graph)
+    freshness: freshnessEnvelope(graph),
+    ...proactiveHint ? { hint: proactiveHint } : {}
   };
 }
 function batchQuery(graphJson, req) {
@@ -4866,29 +4925,94 @@ function batchQuery(graphJson, req) {
   const allQueries = req.queries ?? [];
   const queries = allQueries.slice(0, BATCH_CAP);
   const droppedCount = Math.max(0, allQueries.length - queries.length);
-  const results = queries.map((q) => {
+  const results = queries.map((rawQ) => {
+    const q = rawQ;
+    const toolName = q.tool ?? "";
+    const params = q.params ?? q.arguments;
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+      return {
+        ok: false,
+        tool: toolName,
+        error: "params required (object) \u2014 pass `params` or `arguments` per sub-query"
+      };
+    }
+    const args = params;
     try {
-      switch (q.tool) {
+      switch (toolName) {
         case "find_symbol":
-          return { ok: true, tool: q.tool, result: findSymbol(graph, q.params) };
+          return { ok: true, tool: toolName, result: findSymbol(graph, args) };
         case "get_symbol":
-          return { ok: true, tool: q.tool, result: getSymbol(graph, q.params) };
+          return { ok: true, tool: toolName, result: getSymbol(graph, args) };
         case "get_impact":
-          return { ok: true, tool: q.tool, result: getImpact(graph, q.params) };
+          return { ok: true, tool: toolName, result: getImpact(graph, args) };
         case "list_edges":
-          return { ok: true, tool: q.tool, result: listEdges(graph, q.params) };
+          return { ok: true, tool: toolName, result: listEdges(graph, args) };
         case "search_pattern":
-          return { ok: true, tool: q.tool, result: searchPattern(graph, q.params) };
+          return {
+            ok: true,
+            tool: toolName,
+            result: searchPattern(graph, args)
+          };
+        // The 7 graph tools below were advertised by the schema's
+        // whenToUse but missing from the switch — Claude calling
+        // batch_query with `find_callers` etc. used to hit the
+        // "unsupported sub-query tool" branch and bail. Wired up here
+        // so the catalog promise matches the implementation.
+        case "find_callers":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findCallers(graph, args)
+          };
+        case "find_references":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findReferences(graph, args)
+          };
+        case "get_deps":
+          return { ok: true, tool: toolName, result: getDeps(graph, args) };
+        case "get_call_graph":
+          return {
+            ok: true,
+            tool: toolName,
+            result: getCallGraph(graph, args)
+          };
+        case "find_tests_for_symbol":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findTestsForSymbol(graph, args)
+          };
+        case "get_todos":
+          return { ok: true, tool: toolName, result: getTodos(graph, args) };
+        case "get_freshness":
+          return { ok: true, tool: toolName, result: getFreshness(graph) };
+        default:
+          return {
+            ok: false,
+            tool: toolName,
+            error: `unsupported sub-query tool: ${String(toolName)}`,
+            hint: `Supported tools: find_symbol, get_symbol, get_impact, list_edges, search_pattern, find_callers, find_references, get_deps, get_call_graph, find_tests_for_symbol, get_todos, get_freshness.`
+          };
       }
     } catch (err) {
       return {
         ok: false,
-        tool: q.tool,
+        tool: toolName,
         error: err instanceof Error ? err.message : String(err)
       };
     }
   });
-  return { results, freshness: freshnessEnvelope(graph), droppedCount };
+  const failedCount = results.filter((r) => !r.ok).length;
+  const isError = queries.length > 0 && failedCount === queries.length;
+  return {
+    results,
+    freshness: freshnessEnvelope(graph),
+    droppedCount,
+    failedCount,
+    ...isError ? { isError: true } : {}
+  };
 }
 function findCallers(graphJson, req) {
   const graph = graphJson;
@@ -5121,7 +5245,14 @@ function handleRequest(req, res, options, sessions, secretCtx) {
         sessions.set(sessionId, { repoId: body.repoId });
         return sendJson(res, 200, { sessionId });
       });
-    }).catch((err) => sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) }));
+    }).catch((err) => {
+      const rawMsg = err instanceof Error ? err.message : String(err);
+      const safeMsg = stripAbsolutePaths(rawMsg);
+      if (err?.code === "ENOENT") {
+        return sendJson(res, 404, { error: "unknown_repo" });
+      }
+      sendJson(res, 500, { error: safeMsg });
+    });
     return;
   }
   if (method === "POST" && url === "/mcp/disconnect") {
@@ -5137,62 +5268,73 @@ function handleRequest(req, res, options, sessions, secretCtx) {
     }).catch((err) => sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) }));
     return;
   }
-  function validationError(msg) {
-    return { __validationError: msg };
+  function validationError(error, hint) {
+    return { __validationError: { error, hint } };
   }
   function isValidationError(v) {
     return typeof v === "object" && v !== null && "__validationError" in v;
   }
+  const HINT_USE_FIND_SYMBOL_FIRST = "To get a valid `id`, call `find_symbol` (fuzzy name match) or `search_pattern` (regex) first; pass the resulting `matches[].id` here.";
   const toolDispatch = {
     "/mcp/tools/find_symbol": (g, b) => {
-      if (typeof b["query"] !== "string")
-        return validationError("query required (string)");
+      if (typeof b["query"] !== "string") {
+        return validationError("query required (string)", "Pass a name or substring to fuzzy-match against. For regex use `search_pattern`.");
+      }
       return findSymbol(g, b);
     },
     "/mcp/tools/get_symbol": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getSymbol(g, b);
     },
     "/mcp/tools/get_impact": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getImpact(g, b);
     },
     "/mcp/tools/list_edges": (g, b) => listEdges(g, b),
     "/mcp/tools/search_pattern": (g, b) => {
-      if (typeof b["pattern"] !== "string")
-        return validationError("pattern required (string)");
+      if (typeof b["pattern"] !== "string") {
+        return validationError("pattern required (string)", "Pattern is a JavaScript regex string (no Python `(?P<>` / `(?i)` syntax). For literal substring search use `find_symbol` instead.");
+      }
       return searchPattern(g, b);
     },
     "/mcp/tools/batch_query": (g, b) => {
-      if (!Array.isArray(b["queries"]))
-        return validationError("queries required (array)");
+      if (!Array.isArray(b["queries"])) {
+        return validationError("queries required (array)", "Pass an array of `{tool, params}` (or `{tool, arguments}`) objects. Up to 10 sub-queries per batch. See the schema for valid `tool` values.");
+      }
       return batchQuery(g, b);
     },
     "/mcp/tools/find_callers": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findCallers(g, b);
     },
     "/mcp/tools/find_references": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findReferences(g, b);
     },
     "/mcp/tools/get_deps": (g, b) => {
-      if (typeof b["file"] !== "string")
-        return validationError("file required (string)");
+      if (typeof b["file"] !== "string") {
+        return validationError("file required (string)", "Pass a repo-relative file path (e.g., `src/main.py`, NOT an absolute path or symbol id).");
+      }
       return getDeps(g, b);
     },
     "/mcp/tools/get_call_graph": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getCallGraph(g, b);
     },
     "/mcp/tools/find_tests_for_symbol": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findTestsForSymbol(g, b);
     },
     "/mcp/tools/get_todos": (g, b) => getTodos(g, b),
@@ -5253,11 +5395,11 @@ function handleRequest(req, res, options, sessions, secretCtx) {
       const root = getRepoIdToRoot().get(session.repoId) ?? fallbackRoot;
       if (!root) {
         return {
-          ok: false,
-          status: 400,
-          body: {
+          ok: true,
+          value: {
             error: "unknown_repo",
-            message: `no workspace root registered for repoId ${session.repoId}`
+            hint: `LSP tool dispatch needs a workspace root for repoId ${session.repoId}, but none is registered. This usually means the listener hasn't yet reconciled the repo's localPath. Use graph-only tools (find_symbol, find_callers, etc.) until reconcile completes.`,
+            isError: true
           }
         };
       }
@@ -5271,11 +5413,25 @@ function handleRequest(req, res, options, sessions, secretCtx) {
     dispatchSessionTool(req, res, url, sessions, options.mcpLogger, async (session, body) => {
       const graph = options.graphCache.peek(session.repoId);
       if (!graph) {
-        return { ok: false, status: 503, body: { error: "graph_not_loaded" } };
+        return {
+          ok: true,
+          value: {
+            error: "graph_not_loaded",
+            hint: "The graph for this repo is still downloading or has been invalidated. Retry in a few seconds; if the problem persists, the listener may not have completed the initial sync.",
+            isError: true
+          }
+        };
       }
       const raw = handler(graph, body);
       if (isValidationError(raw)) {
-        return { ok: false, status: 400, body: { error: raw.__validationError } };
+        return {
+          ok: true,
+          value: {
+            error: raw.__validationError.error,
+            hint: raw.__validationError.hint,
+            isError: true
+          }
+        };
       }
       const resolved = await Promise.race([
         raw instanceof Promise ? raw : Promise.resolve(raw),
@@ -5305,6 +5461,7 @@ function dispatchSessionTool(req, res, url, sessions, logger, handler) {
         latencyMs: Date.now() - startedAt,
         error: "unknown_session"
       });
+      logToStdout("rejected", tool, null, Date.now() - startedAt, "unknown_session");
       return sendJson(res, 404, { error: "unknown_session" });
     }
     try {
@@ -5319,8 +5476,10 @@ function dispatchSessionTool(req, res, url, sessions, logger, handler) {
           status: "ok",
           latencyMs: Date.now() - startedAt
         });
+        logToStdout("ok", tool, session.repoId, Date.now() - startedAt);
         return sendJson(res, 200, result.value);
       }
+      const rejectErr = typeof result.body["error"] === "string" ? result.body["error"] : "tool_rejected";
       recordLog(logger, {
         ts: new Date(startedAt).toISOString(),
         sessionId: body.sessionId,
@@ -5329,8 +5488,9 @@ function dispatchSessionTool(req, res, url, sessions, logger, handler) {
         args: redactArgs(body),
         status: "rejected",
         latencyMs: Date.now() - startedAt,
-        error: typeof result.body["error"] === "string" ? result.body["error"] : "tool_rejected"
+        error: rejectErr
       });
+      logToStdout("rejected", tool, session.repoId, Date.now() - startedAt, rejectErr);
       return sendJson(res, result.status, result.body);
     } catch (err) {
       const isTimeout = err instanceof ToolTimeoutError;
@@ -5346,13 +5506,20 @@ function dispatchSessionTool(req, res, url, sessions, logger, handler) {
         latencyMs: Date.now() - startedAt,
         error: safeMsg
       });
+      logToStdout("error", tool, session.repoId, Date.now() - startedAt, safeMsg);
       if (isTimeout) {
-        return sendJson(res, 504, { error: "tool-timeout", tool });
+        return sendJson(res, 200, {
+          error: `tool-timeout: ${tool} exceeded its execution budget`,
+          hint: "The tool was killed at its per-tool timeout. Try a narrower query (smaller limit, depth, or filter) or split into multiple calls.",
+          isError: true,
+          tool
+        });
       }
-      return sendJson(res, 500, {
-        error: "tool_error",
-        tool,
-        message: safeMsg
+      return sendJson(res, 200, {
+        error: `tool_error: ${safeMsg}`,
+        hint: "The tool threw an unexpected exception. This is a server-side bug \u2014 file an issue with the tool name and the error text.",
+        isError: true,
+        tool
       });
     }
   }).catch((err) => {
@@ -5365,6 +5532,11 @@ function recordLog(logger, entry) {
     return;
   void logger.append(entry);
 }
+function logToStdout(status2, tool, repoId, latencyMs, error) {
+  const repoFrag = repoId ? `repo=${repoId}` : "repo=\u2014";
+  const errFrag = error ? ` error=${error}` : "";
+  console.log(`[mcp] ${status2} ${tool} ${repoFrag} ${latencyMs}ms${errFrag}`);
+}
 var REDACT_FIELDS = /* @__PURE__ */ new Set([
   "query",
   "pattern",
@@ -6044,6 +6216,9 @@ async function runAutoConfig(opts) {
   return results;
 }
 
+// ../listener/dist/main.js
+init_installer();
+
 // ../listener/dist/typed-resolution/resolver-loop.js
 init_src();
 init_registry();
@@ -7727,11 +7902,11 @@ async function writeClaudeSubagentHook(repoRoot, contextFolder) {
 }
 
 // src/lib/gitignore.ts
-import { readFileSync as readFileSync2, writeFileSync, existsSync } from "fs";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync2 } from "fs";
 import { join as join32 } from "path";
 function ensureGitignore(repoRoot, entry) {
   const gitignorePath = join32(repoRoot, ".gitignore");
-  if (existsSync(gitignorePath)) {
+  if (existsSync2(gitignorePath)) {
     const content = readFileSync2(gitignorePath, "utf-8");
     const lines = content.split("\n").map((l) => l.trim());
     if (lines.includes(entry) || lines.includes(entry + "/")) {
@@ -10521,6 +10696,7 @@ async function mcpShim(opts) {
   const stderr = opts.stderr ?? process.stderr;
   const maxBytes = opts.maxRequestBytes ?? DEFAULT_MAX;
   const postJson = opts.postJson ?? defaultPostJson;
+  const getJson = opts.getJson ?? defaultGetJson;
   const sessionState = { sessionId: null };
   const rl = createInterface2({ input: stdin, crlfDelay: Infinity });
   for await (const rawLine of rl) {
@@ -10566,6 +10742,7 @@ async function mcpShim(opts) {
         opts.repoId,
         parsed,
         postJson,
+        getJson,
         headers,
         sessionState
       );
@@ -10608,7 +10785,7 @@ function writeJson(stream, value) {
   stream.write(`${JSON.stringify(value)}
 `);
 }
-async function routeMessage(endpoint, repoId, message, postJson, headers, sessionState) {
+async function routeMessage(endpoint, repoId, message, postJson, getJson, headers, sessionState) {
   const msg = message;
   const rpcId = msg.id;
   const method = msg.method;
@@ -10624,41 +10801,28 @@ async function routeMessage(endpoint, repoId, message, postJson, headers, sessio
     };
   }
   if (method === "tools/list") {
-    const tools = [
-      "find_symbol",
-      "get_symbol",
-      "get_impact",
-      "list_edges",
-      "search_pattern",
-      "batch_query",
-      "find_callers",
-      "find_references",
-      "get_deps",
-      "get_call_graph",
-      "find_tests_for_symbol",
-      "get_todos",
-      "get_freshness",
-      "lsp_definition",
-      "lsp_references",
-      "lsp_hover",
-      "lsp_workspace_symbol",
-      "lsp_document_symbol",
-      "lsp_call_hierarchy",
-      "lsp_implementation",
-      "lsp_type_hierarchy"
-    ].map((name) => ({ name, description: "", inputSchema: { type: "object" } }));
+    const catalog = await getJson(`${endpoint}/mcp/tools`, headers);
+    const tools = (catalog.tools ?? []).map((t) => ({
+      name: t.name,
+      description: [t.description, t.whenToUse].filter((s) => s && s.length > 0).join("\n\n"),
+      inputSchema: t.inputSchema ?? { type: "object" }
+    }));
     return { jsonrpc: "2.0", id: rpcId, result: { tools } };
   }
-  if (!sessionState.sessionId) {
+  async function connect() {
     const connectResp = await postJson(`${endpoint}/mcp/connect`, { repoId }, headers);
-    if (!connectResp.sessionId) {
+    return connectResp.sessionId ?? null;
+  }
+  if (!sessionState.sessionId) {
+    const sid = await connect();
+    if (!sid) {
       return {
         jsonrpc: "2.0",
         id: rpcId,
         error: { code: -32002, message: "failed to establish MCP session" }
       };
     }
-    sessionState.sessionId = connectResp.sessionId;
+    sessionState.sessionId = sid;
   }
   if (method === "tools/call") {
     const params = msg.params ?? {};
@@ -10672,12 +10836,35 @@ async function routeMessage(endpoint, repoId, message, postJson, headers, sessio
         error: { code: -32602, message: "tools/call missing name" }
       };
     }
-    const result = await postJson(
-      `${endpoint}/mcp/tools/${name}`,
-      { sessionId: sessionState.sessionId, ...args },
-      headers
-    );
-    return { jsonrpc: "2.0", id: rpcId, result };
+    const callTool = (sid) => postJson(`${endpoint}/mcp/tools/${name}`, { sessionId: sid, ...args }, headers);
+    let result;
+    try {
+      result = await callTool(sessionState.sessionId);
+    } catch (err) {
+      const detail = err.message;
+      const isStaleSession = /HTTP (401|404)/.test(detail) || /session/i.test(detail) || /unknown_session/i.test(detail);
+      if (!isStaleSession) throw err;
+      sessionState.sessionId = null;
+      const fresh = await connect();
+      if (!fresh) {
+        return {
+          jsonrpc: "2.0",
+          id: rpcId,
+          error: { code: -32002, message: "failed to establish MCP session (after retry)" }
+        };
+      }
+      sessionState.sessionId = fresh;
+      result = await callTool(fresh);
+    }
+    const inner = result ?? {};
+    return {
+      jsonrpc: "2.0",
+      id: rpcId,
+      result: {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        ...inner.isError === true ? { isError: true } : {}
+      }
+    };
   }
   return {
     jsonrpc: "2.0",
@@ -10702,6 +10889,19 @@ async function defaultPostJson(url, body, headers = { "content-type": "applicati
   }
   return await res.json();
 }
+async function defaultGetJson(url, headers = {}) {
+  const res = await fetch(url, { method: "GET", headers });
+  if (!res.ok) {
+    let detail = "";
+    try {
+      const errBody = await res.json();
+      detail = errBody.message ?? errBody.error ?? "";
+    } catch {
+    }
+    throw new Error(`HTTP ${res.status.toString()}${detail ? `: ${detail}` : ""}`);
+  }
+  return await res.json();
+}
 
 // src/commands/mcp-serve.ts
 import { createInterface as createInterface3 } from "readline";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repowisestage",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "type": "module",
   "description": "AI-optimized codebase context generator",
   "bin": {