@usewhisper/mcp-server 2.10.0 → 2.11.0

package/dist/server.js

@@ -3914,6 +3914,21 @@ function classifyWorkspaceHealth(args) {
   if (ageHours > (args.max_staleness_hours ?? 168)) return "stale";
   return "healthy";
 }
+function resolveWorkspaceIdentity(args) {
+  const rootPath = canonicalizeWorkspacePath(args?.path, args?.cwd);
+  const derivedWorkspaceId = getWorkspaceIdForPath(rootPath);
+  const requestedWorkspaceId = args?.workspace_id?.trim();
+  if (requestedWorkspaceId && requestedWorkspaceId !== derivedWorkspaceId) {
+    throw new Error(
+      `workspace_id '${requestedWorkspaceId}' does not match canonical workspace '${derivedWorkspaceId}' for ${rootPath}.`
+    );
+  }
+  return {
+    workspace_id: derivedWorkspaceId,
+    root_path: rootPath,
+    identity_source: args?.path?.trim() ? "path_canonical" : "cwd_canonical"
+  };
+}
 function getWorkspaceId(workspaceId) {
   if (workspaceId?.trim()) return workspaceId.trim();
   const seed = `${canonicalizeWorkspacePath(process.cwd())}|${API_KEY.slice(0, 12) || "anon"}`;
@@ -3925,6 +3940,134 @@ function getWorkspaceIdForPath(path, workspaceId) {
   const seed = `${canonicalizeWorkspacePath(path)}|${API_KEY.slice(0, 12) || "anon"}`;
   return createHash("sha256").update(seed).digest("hex").slice(0, 20);
 }
+function normalizeLoosePath(value) {
+  if (!value || !String(value).trim()) return null;
+  return canonicalizeWorkspacePath(String(value));
+}
+function normalizeRepoName(value) {
+  if (!value || !String(value).trim()) return null;
+  return String(value).trim().replace(/\.git$/i, "").toLowerCase();
+}
+function parseGitHubRemote(remote) {
+  if (!remote) return null;
+  const normalized = remote.trim().replace(/\.git$/i, "");
+  const httpsMatch = normalized.match(/github\.com[/:]([^/:\s]+)\/([^/\s]+)$/i);
+  if (httpsMatch) {
+    return { owner: httpsMatch[1].toLowerCase(), repo: httpsMatch[2].toLowerCase() };
+  }
+  const sshMatch = normalized.match(/git@github\.com:([^/:\s]+)\/([^/\s]+)$/i);
+  if (sshMatch) {
+    return { owner: sshMatch[1].toLowerCase(), repo: sshMatch[2].toLowerCase() };
+  }
+  return null;
+}
+function getGitRemoteUrl(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "config", "--get", "remote.origin.url"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  return out || void 0;
+}
+function getGitBranch(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf-8" });
+  if (result.status !== 0) return void 0;
+  const out = String(result.stdout || "").trim();
+  return out || void 0;
+}
+function sourceStatusLooksReady(status) {
+  const normalized = String(status || "").trim().toLowerCase();
+  if (!normalized) return true;
+  if (["ready", "indexed", "completed", "complete", "active", "synced", "success"].includes(normalized)) return true;
+  if (["processing", "queued", "syncing", "pending", "creating", "indexing", "error", "failed"].includes(normalized)) {
+    return false;
+  }
+  return !normalized.includes("error") && !normalized.includes("fail") && !normalized.includes("queue");
+}
+function sourceMatchesWorkspacePath(source, rootPath) {
+  const config = source.config || {};
+  const candidates = [
+    config.path,
+    config.root_path,
+    config.workspace_path,
+    config.workspacePath,
+    config.local_path,
+    config.file_path,
+    config.directory
+  ].map((value) => normalizeLoosePath(typeof value === "string" ? value : null)).filter(Boolean);
+  return candidates.some((candidate) => candidate === rootPath || rootPath.startsWith(`${candidate}/`) || candidate.startsWith(`${rootPath}/`));
+}
+function sourceMatchesWorkspaceRepo(source, repoIdentity, branch) {
+  if (!repoIdentity) return false;
+  const config = source.config || {};
+  const owner = normalizeRepoName(config.owner || config.org || config.organization || null);
+  const repo = normalizeRepoName(config.repo || config.repository || config.name || null);
+  const sourceUrlRepo = parseGitHubRemote(typeof config.url === "string" ? config.url : null);
+  const branchValue = normalizeRepoName(config.branch || config.ref || config.default_branch || null);
+  const ownerMatches = owner === repoIdentity.owner || sourceUrlRepo?.owner === repoIdentity.owner;
+  const repoMatches = repo === repoIdentity.repo || sourceUrlRepo?.repo === repoIdentity.repo;
+  if (!ownerMatches || !repoMatches) return false;
+  if (!branchValue || !branch) return true;
+  return branchValue === normalizeRepoName(branch);
+}
+function classifyProjectRepoReadiness(args) {
+  const remoteIdentity = parseGitHubRemote(args.remote_url || null);
+  const matchedSources = args.sources.filter(
+    (source) => sourceMatchesWorkspacePath(source, args.root_path) || sourceMatchesWorkspaceRepo(source, remoteIdentity, args.branch || void 0)
+  );
+  if (matchedSources.length === 0) {
+    return {
+      retrieval_readiness: "project_bound_no_repo_source",
+      matched_sources: [],
+      matched_source_ids: [],
+      warnings: [`No verified local or GitHub source matches ${args.root_path}.`]
+    };
+  }
+  const readySources = matchedSources.filter((source) => sourceStatusLooksReady(source.status));
+  if (readySources.length === 0) {
+    return {
+      retrieval_readiness: "project_repo_source_stale",
+      matched_sources: matchedSources,
+      matched_source_ids: matchedSources.map((source) => source.id),
+      warnings: [
+        `Matching repo sources are present but not ready (${matchedSources.map((source) => `${source.name}:${source.status}`).join(", ")}).`
+      ]
+    };
+  }
+  return {
+    retrieval_readiness: "project_repo_source_ready",
+    matched_sources: readySources,
+    matched_source_ids: readySources.map((source) => source.id),
+    warnings: []
+  };
+}
+function classifyRepoGroundedQuery(args) {
+  const query = args.query.toLowerCase();
+  let score = 0;
+  if (/(^|[\s"'])where is\b|which file|what file|show me|wiring|handler|middleware|implementation|route|endpoint|function|class|module|repo|workspace|code/.test(query)) {
+    score += 1;
+  }
+  if (/\bauth\b|\burl\b|\bcookie\b|\bsession\b|\bapi\b/.test(query)) {
+    score += 1;
+  }
+  if (/[A-Za-z0-9/_-]+\.[A-Za-z0-9]+/.test(args.query) || /\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{2,}/.test(args.query)) {
+    score += 2;
+  }
+  if (/[A-Za-z_$][A-Za-z0-9_$-]*\(/.test(args.query) || /[A-Z][A-Za-z0-9]+/.test(args.query)) {
+    score += 1;
+  }
+  if ((args.chunk_types || []).some((chunkType) => ["code", "function", "class", "config", "schema", "api_spec"].includes(chunkType))) {
+    score += 2;
+  }
+  const changedTokens = new Set((args.changed_path_tokens || []).map((token) => token.toLowerCase()));
+  if (changedTokens.size > 0) {
+    const queryTokens = tokenizeQueryForLexicalRescue(args.query);
+    if (queryTokens.some((token) => changedTokens.has(token.toLowerCase()))) {
+      score += 1;
+    }
+  }
+  return score >= 2;
+}
 function clamp012(value) {
   if (Number.isNaN(value)) return 0;
   if (value < 0) return 0;
@@ -4066,8 +4209,9 @@ function getWorkspaceWarnings(args) {
   return [];
 }
 async function resolveWorkspaceTrust(args) {
-  const rootPath = canonicalizeWorkspacePath(args.path);
-  const workspaceId = getWorkspaceIdForPath(rootPath, args.workspace_id);
+  const identity = resolveWorkspaceIdentity({ path: args.path, workspace_id: args.workspace_id });
+  const rootPath = identity.root_path;
+  const workspaceId = identity.workspace_id;
   const state = loadState();
   const workspace = getWorkspaceState(state, workspaceId);
   let mutated = false;
@@ -4125,6 +4269,7 @@ async function resolveWorkspaceTrust(args) {
   return {
     workspace_id: workspaceId,
     root_path: rootPath,
+    identity_source: identity.identity_source,
     project_ref: projectRef,
     project_id: projectId,
     resolved_by: selected.resolved_by,
@@ -4156,6 +4301,98 @@ async function resolveProjectRef(explicit) {
     return void 0;
   }
 }
+function collectGitChangedPathTokens(searchPath) {
+  const root = searchPath || process.cwd();
+  const result = spawnSync("git", ["-C", root, "status", "--porcelain"], { encoding: "utf-8" });
+  if (result.status !== 0) return [];
+  const lines = String(result.stdout || "").split("\n").map((line) => line.trim()).filter(Boolean);
+  const tokens = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    const filePath = line.slice(3).split(" -> ").at(-1)?.trim();
+    if (!filePath) continue;
+    for (const token of filePath.split(/[\\/._-]+/).filter((part) => part.length >= 3)) {
+      tokens.add(token.toLowerCase());
+    }
+  }
+  return Array.from(tokens);
+}
+async function inspectProjectRepoSources(args) {
+  if (!args.project_ref) {
+    return {
+      retrieval_readiness: "no_project",
+      matched_sources: [],
+      matched_source_ids: [],
+      warnings: ["No Whisper project is bound to this workspace."]
+    };
+  }
+  try {
+    const sourceData = await whisper.listSources(args.project_ref);
+    const classified = classifyProjectRepoReadiness({
+      sources: sourceData.sources || [],
+      root_path: args.root_path,
+      remote_url: getGitRemoteUrl(args.root_path) || null,
+      branch: getGitBranch(args.root_path) || null
+    });
+    if (classified.retrieval_readiness === "project_bound_no_repo_source") {
+      return {
+        ...classified,
+        warnings: [`Project ${args.project_ref} has no verified local or GitHub source for ${args.root_path}.`]
+      };
+    }
+    if (classified.retrieval_readiness === "project_repo_source_stale") {
+      return {
+        ...classified,
+        warnings: [
+          `Project ${args.project_ref} has matching repo sources, but none are ready (${classified.matched_sources.map((source) => `${source.name}:${source.status}`).join(", ")}).`
+        ]
+      };
+    }
+    return classified;
+  } catch (error) {
+    return {
+      retrieval_readiness: "project_unverified",
+      matched_sources: [],
+      matched_source_ids: [],
+      warnings: [`Could not verify project sources for ${args.project_ref}: ${error.message}`]
+    };
+  }
+}
+async function resolveRepoGroundingPreflight(args) {
+  const trust = await resolveWorkspaceTrust({ path: args.path, workspace_id: args.workspace_id, project: args.project });
+  const repoGrounded = classifyRepoGroundedQuery({
+    query: args.query,
+    chunk_types: args.chunk_types,
+    changed_path_tokens: collectGitChangedPathTokens(trust.root_path)
+  });
+  const sourceVerification = await inspectProjectRepoSources({
+    project_ref: trust.project_ref,
+    root_path: trust.root_path
+  });
+  const warnings = [...trust.warnings, ...sourceVerification.warnings];
+  let retrievalReadiness = sourceVerification.retrieval_readiness;
+  let retrievalRoute = "none";
+  if (repoGrounded) {
+    retrievalRoute = sourceVerification.retrieval_readiness === "project_repo_source_ready" ? "project_repo" : "local_workspace_fallback";
+    if (retrievalRoute === "local_workspace_fallback") {
+      retrievalReadiness = "local_fallback";
+      warnings.push("Using live local workspace retrieval because project-backed repo retrieval is unavailable or unverified.");
+    }
+  }
+  const recommendedNextCalls = [...trust.recommended_next_calls];
+  if (sourceVerification.retrieval_readiness === "project_bound_no_repo_source" || sourceVerification.retrieval_readiness === "project_unverified") {
+    recommendedNextCalls.push("context.list_sources", "index.local_scan_ingest");
+  }
+  return {
+    repo_grounded: repoGrounded,
+    trust_state: trust,
+    retrieval_readiness: retrievalReadiness,
+    retrieval_route: retrievalRoute,
+    matched_sources: sourceVerification.matched_sources,
+    matched_source_ids: sourceVerification.matched_source_ids,
+    warnings: Array.from(new Set(warnings)),
+    recommended_next_calls: Array.from(new Set(recommendedNextCalls))
+  };
+}
 async function ingestSessionWithSyncFallback(params) {
   try {
     return await whisper.ingestSession({
@@ -4182,7 +4419,7 @@ function resolveMcpScope(params) {
     project: params?.project,
     userId: params?.user_id?.trim() || defaultMcpUserId(),
     sessionId: params?.session_id?.trim() || cachedMcpSessionId,
-    workspacePath: process.env.WHISPER_WORKSPACE_PATH || process.cwd()
+    workspacePath: canonicalizeWorkspacePath(params?.path || process.env.WHISPER_WORKSPACE_PATH || process.cwd())
   };
 }
 async function prepareAutomaticQuery(params) {
@@ -4418,6 +4655,7 @@ async function queryWithDegradedFallback(params) {
       include_graph: params.include_graph,
       user_id: params.user_id,
       session_id: params.session_id,
+      source_ids: params.source_ids,
       hybrid: true,
       rerank: true
     });
@@ -4432,6 +4670,7 @@ async function queryWithDegradedFallback(params) {
       include_graph: false,
       user_id: params.user_id,
       session_id: params.session_id,
+      source_ids: params.source_ids,
       hybrid: false,
       rerank: false,
       vector_weight: 0,
@@ -4471,9 +4710,15 @@ function collectCodeFiles(rootPath, allowedExts, maxFiles) {
 }
 function tokenizeQueryForLexicalRescue(query) {
   const stopWords = /* @__PURE__ */ new Set(["where", "what", "show", "find", "logic", "code", "file", "files", "handled", "handling"]);
-  return Array.from(new Set(
-    query.toLowerCase().split(/[^a-z0-9/_-]+/).map((token) => token.trim()).filter((token) => token.length >= 3 && !stopWords.has(token))
-  ));
+  const rawTokens = query.toLowerCase().split(/[^a-z0-9/._:-]+/).map((token) => token.trim()).filter(Boolean);
+  const expanded = /* @__PURE__ */ new Set();
+  for (const token of rawTokens) {
+    if (token.length >= 3 && !stopWords.has(token)) expanded.add(token);
+    for (const part of token.split(/[/:._-]+/).filter((value) => value.length >= 3 && !stopWords.has(value))) {
+      expanded.add(part);
+    }
+  }
+  return Array.from(expanded);
 }
 function buildLexicalRescueResults(args) {
   const tokens = tokenizeQueryForLexicalRescue(args.query);
@@ -4499,16 +4744,17 @@ ${doc.raw_content}`.toLowerCase();
 async function runSearchCodeSearch(args) {
   const topK = args.top_k ?? 10;
   const requestedThreshold = args.threshold ?? 0.2;
+  const semanticTopK = Math.min(args.documents.length || topK, Math.max(topK * 3, topK + 5));
   const semanticDocuments = args.documents.map((doc) => ({ id: doc.id, content: doc.content }));
   const defaultResponse = await args.semantic_search({
     query: args.query,
     documents: semanticDocuments,
-    top_k: topK,
+    top_k: semanticTopK,
     threshold: requestedThreshold
   });
   if (defaultResponse.results?.length) {
     return {
-      results: defaultResponse.results.map((result) => ({ ...result, search_mode: "semantic" })),
+      results: defaultResponse.results.slice(0, topK).map((result) => ({ ...result, search_mode: "semantic" })),
       mode: "semantic",
       threshold_used: requestedThreshold,
       fallback_used: false,
@@ -4520,12 +4766,12 @@ async function runSearchCodeSearch(args) {
     const adaptiveResponse = await args.semantic_search({
       query: args.query,
       documents: semanticDocuments,
-      top_k: topK,
+      top_k: semanticTopK,
       threshold: adaptiveThreshold
     });
     if (adaptiveResponse.results?.length) {
       return {
-        results: adaptiveResponse.results.map((result) => ({ ...result, search_mode: "adaptive_semantic" })),
+        results: adaptiveResponse.results.slice(0, topK).map((result) => ({ ...result, search_mode: "adaptive_semantic" })),
         mode: "adaptive_semantic",
         threshold_used: adaptiveThreshold,
         fallback_used: true,
@@ -4546,36 +4792,8 @@ async function runSearchCodeSearch(args) {
     fallback_reason: lexicalResults.length ? "Semantic ranking returned no matches; lexical rescue over local file paths and content was used." : "Semantic ranking returned no matches and lexical rescue found no strong candidates."
   };
 }
-async function runSearchCodeTool(args) {
-  const rootPath = canonicalizeWorkspacePath(args.path);
-  const workspace = await resolveWorkspaceTrust({ path: rootPath });
-  const allowedExts = args.file_types ? new Set(args.file_types) : CODE_EXTENSIONS;
-  const files = collectCodeFiles(rootPath, allowedExts, args.max_files ?? 150);
-  const sharedWarnings = [...workspace.warnings];
-  if (files.length === 0) {
-    return {
-      tool: "search_code",
-      query: args.query,
-      path: rootPath,
-      results: [],
-      count: 0,
-      warnings: sharedWarnings,
-      diagnostics: {
-        workspace_id: workspace.workspace_id,
-        root_path: workspace.root_path,
-        project_ref: workspace.project_ref,
-        project_id: workspace.project_id,
-        index_health: workspace.health,
-        grounded_to_workspace: workspace.grounded_to_workspace,
-        threshold_requested: args.threshold ?? 0.2,
-        threshold_used: null,
-        fallback_used: false,
-        fallback_reason: null,
-        search_mode: "semantic",
-        warnings: sharedWarnings
-      }
-    };
-  }
+function buildLocalWorkspaceDocuments(rootPath, allowedExts, maxFiles) {
+  const files = collectCodeFiles(rootPath, allowedExts, maxFiles);
   const documents = [];
   for (const filePath of files) {
     try {
@@ -4587,6 +4805,38 @@ async function runSearchCodeTool(args) {
     } catch {
     }
   }
+  return documents;
+}
+function extractRelevantSnippet(rawContent, query) {
+  const lines = rawContent.split("\n");
+  const tokens = tokenizeQueryForLexicalRescue(query);
+  let matchIndex = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    const lower = lines[index].toLowerCase();
+    if (tokens.some((token) => lower.includes(token))) {
+      matchIndex = index;
+      break;
+    }
+  }
+  if (matchIndex < 0) {
+    matchIndex = lines.findIndex((line) => line.trim().length > 0);
+  }
+  const start = Math.max(0, matchIndex < 0 ? 0 : matchIndex - 1);
+  const end = Math.min(lines.length, start + 4);
+  const snippet = lines.slice(start, end).join("\n").trim().slice(0, 500);
+  return {
+    snippet,
+    line_start: start + 1,
+    ...end > start + 1 ? { line_end: end } : {}
+  };
+}
+async function runLocalWorkspaceRetrieval(args) {
+  const identity = resolveWorkspaceIdentity({ path: args.path });
+  const workspace = await resolveWorkspaceTrust({ path: identity.root_path, project: args.project });
+  const allowedExts = args.file_types ? new Set(args.file_types) : CODE_EXTENSIONS;
+  const candidateFiles = collectCodeFiles(identity.root_path, allowedExts, args.max_files ?? 150);
+  const documents = buildLocalWorkspaceDocuments(identity.root_path, allowedExts, args.max_files ?? 150);
+  const sharedWarnings = [...workspace.warnings];
   const searchResult = await runSearchCodeSearch({
     query: args.query,
     documents,
@@ -4602,29 +4852,140 @@ async function runSearchCodeTool(args) {
   if (!workspace.grounded_to_workspace && workspace.health !== "unbound" && workspace.health !== "unindexed") {
     sharedWarnings.push("Local code search is live, but project-backed retrieval may disagree until the workspace is re-indexed.");
   }
+  const documentMap = new Map(documents.map((document) => [document.id, document]));
+  const localResults = searchResult.results.map((result) => {
+    const document = documentMap.get(result.id);
+    const snippet = extractRelevantSnippet(document?.raw_content || result.snippet || "", args.query);
+    return {
+      ...result,
+      snippet: snippet.snippet || result.snippet,
+      raw_snippet: snippet.snippet || result.snippet,
+      line_start: snippet.line_start,
+      ...snippet.line_end ? { line_end: snippet.line_end } : {},
+      retrieval_method: result.search_mode === "lexical_rescue" ? "lexical" : "semantic"
+    };
+  });
   return {
-    tool: "search_code",
-    query: args.query,
-    path: rootPath,
-    results: searchResult.results,
-    count: searchResult.results.length,
+    workspace,
+    documents,
+    results: localResults,
     warnings: sharedWarnings,
     diagnostics: {
       workspace_id: workspace.workspace_id,
       root_path: workspace.root_path,
       project_ref: workspace.project_ref,
       project_id: workspace.project_id,
+      identity_source: workspace.identity_source,
       index_health: workspace.health,
-      grounded_to_workspace: workspace.grounded_to_workspace,
+      grounded_to_workspace: true,
       threshold_requested: args.threshold ?? 0.2,
       threshold_used: searchResult.threshold_used,
       fallback_used: searchResult.fallback_used,
       fallback_reason: searchResult.fallback_reason,
       search_mode: searchResult.mode,
+      candidate_files_scanned: candidateFiles.length,
+      semantic_candidate_count: documents.length,
+      retrieval_route: "local_workspace",
       warnings: sharedWarnings
     }
   };
 }
+function isLikelyRepoBackedResult(result) {
+  const metadata = result.metadata || {};
+  const retrievalSource = String(result.retrieval_source || "").toLowerCase();
+  if (retrievalSource.includes("memory")) return false;
+  const pathCandidate = String(metadata.file_path || metadata.path || result.source || result.document || "");
+  if (/[\\/]/.test(pathCandidate) || /\.[a-z0-9]+$/i.test(pathCandidate)) return true;
+  const sourceType = String(metadata.source_type || metadata.connector_type || result.type || "").toLowerCase();
+  return ["local", "github", "code", "file", "repo"].some((token) => sourceType.includes(token));
+}
+function filterProjectRepoResults(results, matchedSourceIds) {
+  const scoped = results.filter((result) => {
+    const sourceId = String(result.metadata?.source_id || result.metadata?.sourceId || result.metadata?.source || "");
+    return matchedSourceIds.length === 0 || matchedSourceIds.includes(sourceId);
+  });
+  const repoResults = scoped.filter((result) => isLikelyRepoBackedResult(result));
+  return repoResults.length > 0 ? repoResults : scoped;
+}
+function localHitsToEvidence(workspaceId, hits) {
+  return hits.map(
+    (hit) => toEvidenceRef(
+      {
+        id: hit.id,
+        content: hit.raw_snippet,
+        score: hit.score,
+        retrieval_source: hit.retrieval_method,
+        metadata: {
+          file_path: hit.id,
+          snippet: hit.raw_snippet,
+          line_start: hit.line_start,
+          ...hit.line_end ? { line_end: hit.line_end } : {}
+        }
+      },
+      workspaceId,
+      hit.retrieval_method
+    )
+  );
+}
+function renderLocalWorkspaceContext(args) {
+  const lines = args.hits.map((hit, index) => {
+    const location = hit.line_end && hit.line_end !== hit.line_start ? `${hit.id}:${hit.line_start}-${hit.line_end}` : `${hit.id}:${hit.line_start}`;
+    return `${index + 1}. [${location}, score: ${hit.score.toFixed(2)}, mode: ${hit.search_mode}] ${hit.raw_snippet || hit.snippet || hit.id}`;
+  });
+  const header = `Found ${args.hits.length} local workspace result(s) (route=${args.route}, workspace=${args.diagnostics.workspace_id}, project=${args.project_ref || "none"}, user=${args.scope.userId}, session=${args.scope.sessionId}):`;
+  const warnings = args.warnings.length ? `
+
+[warnings]
+${args.warnings.join("\n")}` : "";
+  return `${header}
+
+${lines.join("\n\n")}${warnings}`;
+}
+async function runSearchCodeTool(args) {
+  const rootPath = canonicalizeWorkspacePath(args.path);
+  const allowedExts = args.file_types ? new Set(args.file_types) : CODE_EXTENSIONS;
+  const files = collectCodeFiles(rootPath, allowedExts, args.max_files ?? 150);
+  if (files.length === 0) {
+    const workspace = await resolveWorkspaceTrust({ path: rootPath });
+    const sharedWarnings = [...workspace.warnings];
+    return {
+      tool: "search_code",
+      query: args.query,
+      path: rootPath,
+      results: [],
+      count: 0,
+      warnings: sharedWarnings,
+      diagnostics: {
+        workspace_id: workspace.workspace_id,
+        root_path: workspace.root_path,
+        project_ref: workspace.project_ref,
+        project_id: workspace.project_id,
+        identity_source: workspace.identity_source,
+        index_health: workspace.health,
+        grounded_to_workspace: workspace.grounded_to_workspace,
+        threshold_requested: args.threshold ?? 0.2,
+        threshold_used: null,
+        fallback_used: false,
+        fallback_reason: null,
+        search_mode: "semantic",
+        candidate_files_scanned: 0,
+        semantic_candidate_count: 0,
+        retrieval_route: "local_workspace",
+        warnings: sharedWarnings
+      }
+    };
+  }
+  const localRetrieval = await runLocalWorkspaceRetrieval(args);
+  return {
+    tool: "search_code",
+    query: args.query,
+    path: rootPath,
+    results: localRetrieval.results,
+    count: localRetrieval.results.length,
+    warnings: localRetrieval.warnings,
+    diagnostics: localRetrieval.diagnostics
+  };
+}
 function getLocalAllowlistRoots() {
   const fromEnv = (process.env.WHISPER_LOCAL_ALLOWLIST || "").split(",").map((v) => v.trim()).filter(Boolean);
   if (fromEnv.length > 0) return fromEnv;
@@ -4900,21 +5261,23 @@ server.tool(
   },
   async ({ path, workspace_id, project }) => {
     try {
-      const rootPath = canonicalizeWorkspacePath(path);
-      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const identity = resolveWorkspaceIdentity({ path, workspace_id });
       const state = loadState();
-      const existed = Boolean(state.workspaces[workspaceId]);
-      const trust = await resolveWorkspaceTrust({ path: rootPath, workspace_id, project });
+      const existed = Boolean(state.workspaces[identity.workspace_id]);
+      const trust = await resolveWorkspaceTrust({ path: identity.root_path, workspace_id, project });
+      const preflight = await resolveRepoGroundingPreflight({ query: "workspace status", path, workspace_id, project });
       const payload = {
-        workspace_id: workspaceId,
+        workspace_id: identity.workspace_id,
         root_path: trust.root_path,
+        identity_source: trust.identity_source,
         project_ref: trust.project_ref,
         project_id: trust.project_id,
         created: !existed,
         resolved_by: trust.resolved_by,
         health: trust.health,
-        warnings: trust.warnings,
-        recommended_next_calls: trust.recommended_next_calls,
+        retrieval_readiness: preflight.retrieval_readiness,
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls,
         index_state: {
           last_indexed_at: trust.freshness.last_indexed_at,
           last_indexed_commit: trust.last_indexed_commit,
@@ -4937,15 +5300,23 @@ server.tool(
   async ({ workspace_id, path }) => {
     try {
       const trust = await resolveWorkspaceTrust({ path, workspace_id });
+      const repoVerification = await inspectProjectRepoSources({ project_ref: trust.project_ref, root_path: trust.root_path });
       const payload = {
         workspace_id: trust.workspace_id,
         root_path: trust.root_path,
+        identity_source: trust.identity_source,
         project_ref: trust.project_ref,
         project_id: trust.project_id,
         resolved_by: trust.resolved_by,
         health: trust.health,
-        warnings: trust.warnings,
-        recommended_next_calls: trust.recommended_next_calls,
+        retrieval_readiness: repoVerification.retrieval_readiness,
+        warnings: Array.from(/* @__PURE__ */ new Set([...trust.warnings, ...repoVerification.warnings])),
+        recommended_next_calls: Array.from(
+          /* @__PURE__ */ new Set([
+            ...trust.recommended_next_calls,
+            ...repoVerification.retrieval_readiness === "project_bound_no_repo_source" ? ["context.list_sources", "index.local_scan_ingest"] : []
+          ])
+        ),
         freshness: trust.freshness,
         coverage: trust.coverage,
         last_indexed_commit: trust.last_indexed_commit,
@@ -4970,8 +5341,9 @@ server.tool(
   },
   async ({ workspace_id, path, mode, max_files }) => {
     try {
-      const rootPath = canonicalizeWorkspacePath(path);
-      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
+      const identity = resolveWorkspaceIdentity({ path, workspace_id });
+      const rootPath = identity.root_path;
+      const workspaceId = identity.workspace_id;
       const state = loadState();
       const workspace = getWorkspaceState(state, workspaceId);
       const fileStats = countCodeFiles(rootPath, max_files);
@@ -5038,9 +5410,10 @@ server.tool(
 );
 server.tool(
   "context.get_relevant",
-  "Core retrieval. Task goes in, ranked context chunks come out with structured evidence (file:line ready).",
+  "Default grounded retrieval step for workspace/project questions. Call this before answering when you need ranked evidence with file:line citations instead of relying on model memory.",
   {
     question: z.string().describe("Task/question to retrieve context for"),
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
     workspace_id: z.string().optional(),
     project: z.string().optional(),
     top_k: z.number().optional().default(12),
@@ -5049,51 +5422,115 @@ server.tool(
     session_id: z.string().optional(),
     user_id: z.string().optional()
   },
-  async ({ question, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id }) => {
+  async ({ question, path, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id }) => {
     try {
-      const trust = await resolveWorkspaceTrust({ workspace_id, project });
-      if (trust.health === "unbound" || trust.health === "unindexed" || !trust.project_ref) {
+      const preflight = await resolveRepoGroundingPreflight({ query: question, path, workspace_id, project });
+      if (preflight.retrieval_route === "local_workspace_fallback") {
+        const localRetrieval = await runLocalWorkspaceRetrieval({
+          query: question,
+          path: preflight.trust_state.root_path,
+          project: preflight.trust_state.project_ref || project,
+          top_k
+        });
+        const evidence2 = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results);
         const payload2 = {
           question,
-          workspace_id: trust.workspace_id,
-          trust_state: trust,
+          workspace_id: preflight.trust_state.workspace_id,
+          root_path: preflight.trust_state.root_path,
+          identity_source: preflight.trust_state.identity_source,
+          trust_state: preflight.trust_state,
+          retrieval_readiness: preflight.retrieval_readiness,
+          retrieval_route: preflight.retrieval_route,
+          grounded_to_workspace: true,
+          total_results: evidence2.length,
+          context: evidence2.map((item) => `[${renderCitation(item)}] ${item.snippet || "Relevant local workspace context found."}`).join("\n"),
+          evidence: evidence2,
+          used_context_ids: evidence2.map((item) => item.source_id),
+          latency_ms: 0,
+          warnings: Array.from(/* @__PURE__ */ new Set([...preflight.warnings, ...localRetrieval.warnings])),
+          recommended_next_calls: preflight.recommended_next_calls
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      if (!preflight.trust_state.project_ref) {
+        const payload2 = {
+          question,
+          workspace_id: preflight.trust_state.workspace_id,
+          root_path: preflight.trust_state.root_path,
+          identity_source: preflight.trust_state.identity_source,
+          trust_state: preflight.trust_state,
+          retrieval_readiness: preflight.retrieval_readiness,
+          retrieval_route: "none",
           grounded_to_workspace: false,
           total_results: 0,
           context: "",
           evidence: [],
           used_context_ids: [],
           latency_ms: 0,
-          warnings: trust.warnings,
-          recommended_next_calls: trust.recommended_next_calls
+          warnings: preflight.warnings,
+          recommended_next_calls: preflight.recommended_next_calls
         };
         return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
       }
       const queryResult = await queryWithDegradedFallback({
-        project: trust.project_ref,
+        project: preflight.trust_state.project_ref,
         query: question,
         top_k,
-        include_memories,
+        include_memories: preflight.repo_grounded ? false : include_memories,
         include_graph,
         session_id,
-        user_id
+        user_id,
+        source_ids: preflight.repo_grounded ? preflight.matched_source_ids : void 0
       });
       const response = queryResult.response;
-      const evidence = (response.results || []).map((r) => toEvidenceRef(r, trust.workspace_id, "semantic"));
+      const rawResults = preflight.repo_grounded ? filterProjectRepoResults(response.results || [], preflight.matched_source_ids) : response.results || [];
+      if (preflight.repo_grounded && rawResults.length === 0) {
+        const localRetrieval = await runLocalWorkspaceRetrieval({
+          query: question,
+          path: preflight.trust_state.root_path,
+          project: preflight.trust_state.project_ref,
+          top_k
+        });
+        const evidence2 = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results);
+        const payload2 = {
+          question,
+          workspace_id: preflight.trust_state.workspace_id,
+          root_path: preflight.trust_state.root_path,
+          identity_source: preflight.trust_state.identity_source,
+          trust_state: preflight.trust_state,
+          retrieval_readiness: "local_fallback",
+          retrieval_route: "local_workspace_fallback",
+          grounded_to_workspace: true,
+          total_results: evidence2.length,
+          context: evidence2.map((item) => `[${renderCitation(item)}] ${item.snippet || "Relevant local workspace context found."}`).join("\n"),
+          evidence: evidence2,
+          used_context_ids: evidence2.map((item) => item.source_id),
+          latency_ms: 0,
+          warnings: Array.from(/* @__PURE__ */ new Set([...preflight.warnings, ...localRetrieval.warnings])),
+          recommended_next_calls: preflight.recommended_next_calls
+        };
+        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
+      }
+      const evidence = rawResults.map((r) => toEvidenceRef(r, preflight.trust_state.workspace_id, "semantic"));
       const payload = {
         question,
-        workspace_id: trust.workspace_id,
-        trust_state: trust,
-        grounded_to_workspace: trust.grounded_to_workspace,
-        total_results: response.meta?.total || evidence.length,
+        workspace_id: preflight.trust_state.workspace_id,
+        root_path: preflight.trust_state.root_path,
+        identity_source: preflight.trust_state.identity_source,
+        trust_state: preflight.trust_state,
+        retrieval_readiness: preflight.retrieval_readiness,
+        retrieval_route: preflight.repo_grounded ? "project_repo" : "none",
+        grounded_to_workspace: preflight.repo_grounded ? true : preflight.trust_state.grounded_to_workspace,
+        total_results: rawResults.length || response.meta?.total || evidence.length,
         context: response.context || "",
         evidence,
-        used_context_ids: (response.results || []).map((r) => String(r.id)),
+        used_context_ids: rawResults.map((r) => String(r.id)),
         latency_ms: response.meta?.latency_ms || 0,
         degraded_mode: queryResult.degraded_mode,
         degraded_reason: queryResult.degraded_reason,
         recommendation: queryResult.recommendation,
-        warnings: trust.warnings,
-        recommended_next_calls: trust.recommended_next_calls
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls
       };
       return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
     } catch (error) {
@@ -5106,38 +5543,53 @@ server.tool(
   "Verify whether a claim is supported by retrieved context. Returns supported/partial/unsupported with evidence.",
   {
     claim: z.string().describe("Claim to verify"),
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
     workspace_id: z.string().optional(),
     project: z.string().optional(),
     context_ids: z.array(z.string()).optional(),
     strict: z.boolean().optional().default(true)
   },
-  async ({ claim, workspace_id, project, context_ids, strict }) => {
+  async ({ claim, path, workspace_id, project, context_ids, strict }) => {
     try {
-      const trust = await resolveWorkspaceTrust({ workspace_id, project });
-      if (trust.health !== "healthy" || !trust.project_ref) {
+      const preflight = await resolveRepoGroundingPreflight({ query: claim, path, workspace_id, project });
+      let evidence = [];
+      if (preflight.retrieval_route === "local_workspace_fallback") {
+        const localRetrieval = await runLocalWorkspaceRetrieval({
+          query: claim,
+          path: preflight.trust_state.root_path,
+          project: preflight.trust_state.project_ref || project,
+          top_k: strict ? 8 : 12
+        });
+        evidence = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results).filter((item) => !context_ids || context_ids.length === 0 || context_ids.includes(item.source_id));
+      } else if (preflight.trust_state.project_ref) {
+        const response = await whisper.query({
+          project: preflight.trust_state.project_ref,
+          query: claim,
+          top_k: strict ? 8 : 12,
+          include_memories: preflight.repo_grounded ? false : true,
+          include_graph: true,
+          ...preflight.repo_grounded ? { source_ids: preflight.matched_source_ids } : {}
+        });
+        const filtered = (preflight.repo_grounded ? filterProjectRepoResults(response.results || [], preflight.matched_source_ids) : response.results || []).filter(
+          (r) => !context_ids || context_ids.length === 0 || context_ids.includes(String(r.id))
+        );
+        evidence = filtered.map((r) => toEvidenceRef(r, preflight.trust_state.workspace_id, "semantic"));
+      }
+      if (evidence.length === 0) {
         const payload2 = {
           verdict: "unsupported",
           confidence: 0,
           evidence: [],
-          trust_state: trust,
-          warnings: trust.warnings,
-          recommended_next_calls: trust.recommended_next_calls,
-          missing_requirements: trust.warnings.length ? trust.warnings : ["Workspace trust requirements were not met."],
-          explanation: "Verifier did not run because workspace grounding is insufficient."
+          trust_state: preflight.trust_state,
+          retrieval_readiness: preflight.retrieval_readiness,
+          retrieval_route: preflight.retrieval_route,
+          warnings: preflight.warnings,
+          recommended_next_calls: preflight.recommended_next_calls,
+          missing_requirements: preflight.warnings.length ? preflight.warnings : ["No repo-grounded evidence was available for verification."],
+          explanation: "Verifier did not find sufficient repo-grounded evidence."
         };
         return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
       }
-      const response = await whisper.query({
-        project: trust.project_ref,
-        query: claim,
-        top_k: strict ? 8 : 12,
-        include_memories: true,
-        include_graph: true
-      });
-      const filtered = (response.results || []).filter(
-        (r) => !context_ids || context_ids.length === 0 || context_ids.includes(String(r.id))
-      );
-      const evidence = filtered.map((r) => toEvidenceRef(r, trust.workspace_id, "semantic"));
       const directEvidence = evidence.filter((e) => e.score >= (strict ? 0.7 : 0.6));
       const weakEvidence = evidence.filter((e) => e.score >= (strict ? 0.45 : 0.35));
       let verdict = "unsupported";
@@ -5147,9 +5599,11 @@ server.tool(
         verdict,
         confidence: evidence.length ? Math.max(...evidence.map((e) => e.score)) : 0,
         evidence: verdict === "supported" ? directEvidence : weakEvidence,
-        trust_state: trust,
-        warnings: trust.warnings,
-        recommended_next_calls: trust.recommended_next_calls,
+        trust_state: preflight.trust_state,
+        retrieval_readiness: preflight.retrieval_readiness,
+        retrieval_route: preflight.retrieval_route,
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls,
         missing_requirements: verdict === "supported" ? [] : verdict === "partial" ? ["No direct evidence spans met strict threshold."] : ["No sufficient supporting evidence found for the claim."],
         explanation: verdict === "supported" ? "At least one direct evidence span supports the claim." : verdict === "partial" ? "Some related evidence exists, but direct support is incomplete." : "Retrieved context did not contain sufficient support."
       };
@@ -5164,6 +5618,7 @@ server.tool(
   "Answer a question only when evidence requirements are met. Fails closed with an abstain payload when not verifiable.",
   {
     question: z.string(),
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
     workspace_id: z.string().optional(),
     project: z.string().optional(),
     constraints: z.object({
@@ -5178,38 +5633,51 @@ server.tool(
       include_recent_decisions: z.boolean().optional().default(true)
     }).optional()
   },
-  async ({ question, workspace_id, project, constraints, retrieval }) => {
+  async ({ question, path, workspace_id, project, constraints, retrieval }) => {
     try {
       const requireCitations = constraints?.require_citations ?? true;
       const minEvidenceItems = constraints?.min_evidence_items ?? 2;
       const minConfidence = constraints?.min_confidence ?? 0.65;
       const maxStalenessHours = constraints?.max_staleness_hours ?? 168;
       const topK = retrieval?.top_k ?? 12;
-      const trust = await resolveWorkspaceTrust({ workspace_id, project, max_staleness_hours: maxStalenessHours });
-      if (trust.health !== "healthy" || !trust.project_ref) {
-        const reason = trust.health === "stale" || trust.health === "drifted" ? "stale_index" : "no_retrieval_hits";
+      const preflight = await resolveRepoGroundingPreflight({ query: question, path, workspace_id, project });
+      let evidence = [];
+      if (preflight.retrieval_route === "local_workspace_fallback") {
+        const localRetrieval = await runLocalWorkspaceRetrieval({
+          query: question,
+          path: preflight.trust_state.root_path,
+          project: preflight.trust_state.project_ref || project,
+          top_k: topK
+        });
+        evidence = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results);
+      } else if (preflight.trust_state.project_ref) {
+        const response = await whisper.query({
+          project: preflight.trust_state.project_ref,
+          query: question,
+          top_k: topK,
+          include_memories: preflight.repo_grounded ? false : true,
+          include_graph: true,
+          ...preflight.repo_grounded ? { source_ids: preflight.matched_source_ids } : {}
+        });
+        const filtered = preflight.repo_grounded ? filterProjectRepoResults(response.results || [], preflight.matched_source_ids) : response.results || [];
+        evidence = filtered.map((r) => toEvidenceRef(r, preflight.trust_state.workspace_id, "semantic"));
+      }
+      if (evidence.length === 0) {
+        const reason = preflight.trust_state.health === "stale" || preflight.trust_state.health === "drifted" ? "stale_index" : "no_retrieval_hits";
         const abstain = buildAbstain({
           reason,
-          message: trust.warnings[0] || "Workspace trust requirements were not met.",
+          message: preflight.warnings[0] || "Workspace trust requirements were not met.",
           closest_evidence: [],
           claims_evaluated: 1,
           evidence_items_found: 0,
           min_required: minEvidenceItems,
-          index_fresh: trust.health === "healthy",
-          warnings: trust.warnings,
-          trust_state: trust,
-          recommended_next_calls: trust.recommended_next_calls
+          index_fresh: preflight.trust_state.health === "healthy",
+          warnings: preflight.warnings,
+          trust_state: preflight.trust_state,
+          recommended_next_calls: preflight.recommended_next_calls
         });
         return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
       }
-      const response = await whisper.query({
-        project: trust.project_ref,
-        query: question,
-        top_k: topK,
-        include_memories: true,
-        include_graph: true
-      });
-      const evidence = (response.results || []).map((r) => toEvidenceRef(r, trust.workspace_id, "semantic"));
       const sorted = evidence.sort((a, b) => b.score - a.score);
       const confidence = sorted.length ? sorted[0].score : 0;
       if (sorted.length === 0) {
@@ -5220,10 +5688,10 @@ server.tool(
           claims_evaluated: 1,
           evidence_items_found: 0,
           min_required: minEvidenceItems,
-          index_fresh: trust.health === "healthy",
-          warnings: trust.warnings,
-          trust_state: trust,
-          recommended_next_calls: trust.recommended_next_calls
+          index_fresh: preflight.trust_state.health === "healthy",
+          warnings: preflight.warnings,
+          trust_state: preflight.trust_state,
+          recommended_next_calls: preflight.recommended_next_calls
         });
         return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
       }
@@ -5238,9 +5706,9 @@ server.tool(
           evidence_items_found: supportedEvidence.length,
           min_required: minEvidenceItems,
           index_fresh: true,
-          warnings: trust.warnings,
-          trust_state: trust,
-          recommended_next_calls: trust.recommended_next_calls
+          warnings: preflight.warnings,
+          trust_state: preflight.trust_state,
+          recommended_next_calls: preflight.recommended_next_calls
         });
         return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
       }
@@ -5253,9 +5721,11 @@ server.tool(
         answer: answerLines.join("\n"),
         citations,
         confidence,
-        trust_state: trust,
-        warnings: trust.warnings,
-        recommended_next_calls: trust.recommended_next_calls,
+        trust_state: preflight.trust_state,
+        retrieval_readiness: preflight.retrieval_readiness,
+        retrieval_route: preflight.retrieval_route,
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls,
         verification: {
           verdict,
           supported_claims: verdict === "supported" ? 1 : 0,
@@ -5271,10 +5741,11 @@ server.tool(
 );
 server.tool(
   "context.query",
-  "Search your knowledge base for relevant context. Returns packed context ready for LLM consumption. Supports hybrid vector+keyword search, memory inclusion, and knowledge graph traversal.",
+  "Use this when answering from project knowledge rather than general model memory. Retrieves packed context for a query using hybrid vector+keyword search with optional memory/graph expansion.",
   {
     project: z.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
     query: z.string().describe("What are you looking for?"),
+    path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
     top_k: z.number().optional().default(10).describe("Number of results"),
     chunk_types: z.array(z.string()).optional().describe("Filter: code, function, class, documentation, api_spec, schema, config, text"),
     include_memories: z.boolean().optional().describe("Include relevant memories. Omit to use automatic runtime defaults."),
@@ -5283,14 +5754,105 @@ server.tool(
     session_id: z.string().optional().describe("Session ID for memory scoping"),
     max_tokens: z.number().optional().describe("Max tokens for packed context")
   },
-  async ({ project, query, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens }) => {
+  async ({ project, query, path, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens }) => {
     try {
-      const resolvedProject = await resolveProjectRef(project);
-      if (!resolvedProject) {
+      const preflight = await resolveRepoGroundingPreflight({ query, path, project, chunk_types });
+      const resolvedProject = preflight.trust_state.project_ref || await resolveProjectRef(project);
+      if (!resolvedProject && !preflight.repo_grounded) {
         return { content: [{ type: "text", text: "Error: No project resolved. Set WHISPER_PROJECT or pass project." }] };
       }
-      const scope = resolveMcpScope({ project: resolvedProject, user_id, session_id });
-      const automaticMode = include_memories !== false && include_graph !== true && !(chunk_types && chunk_types.length > 0) && max_tokens === void 0 && runtimeClient;
+      const scope = resolveMcpScope({ project: resolvedProject, user_id, session_id, path: preflight.trust_state.root_path });
+      if (preflight.repo_grounded && preflight.retrieval_route === "local_workspace_fallback") {
+        const localRetrieval = await runLocalWorkspaceRetrieval({
+          query,
+          path: preflight.trust_state.root_path,
+          project: resolvedProject || project,
+          top_k
+        });
+        if (localRetrieval.results.length > 0) {
+          return {
+            content: [{
+              type: "text",
+              text: renderLocalWorkspaceContext({
+                query,
+                project_ref: resolvedProject || null,
+                scope,
+                route: "local_workspace_fallback",
+                hits: localRetrieval.results,
+                diagnostics: localRetrieval.diagnostics,
+                warnings: Array.from(/* @__PURE__ */ new Set([...preflight.warnings, ...localRetrieval.warnings]))
+              })
+            }]
+          };
+        }
+      }
+      if (preflight.repo_grounded && resolvedProject) {
+        const queryResult2 = await queryWithDegradedFallback({
+          project: resolvedProject,
+          query,
+          top_k,
+          include_memories: false,
+          include_graph,
+          user_id: user_id || scope.userId,
+          session_id: session_id || scope.sessionId,
+          source_ids: preflight.matched_source_ids
+        });
+        const repoResults = filterProjectRepoResults(queryResult2.response.results || [], preflight.matched_source_ids);
+        if (repoResults.length > 0) {
+          const scopedResponse = { ...queryResult2.response, results: repoResults };
+          const header2 = `Found ${repoResults.length} repo-grounded result(s) (${scopedResponse.meta.latency_ms}ms${scopedResponse.meta.cache_hit ? ", cached" : ""}, route=project_repo, workspace=${preflight.trust_state.workspace_id}, project=${resolvedProject}, user=${scope.userId}, session=${scope.sessionId}):
+
+`;
+          const suffix2 = [
+            `[diagnostics] identity_source=${preflight.trust_state.identity_source} retrieval_readiness=${preflight.retrieval_readiness} retrieval_route=project_repo`,
+            queryResult2.degraded_mode ? `[degraded_mode=true] ${queryResult2.degraded_reason}
+Recommendation: ${queryResult2.recommendation}` : "",
+            preflight.warnings.length ? `[warnings]
+${preflight.warnings.join("\n")}` : ""
+          ].filter(Boolean).join("\n\n");
+          return { content: [{ type: "text", text: `${header2}${scopedResponse.context}${suffix2 ? `
+
+${suffix2}` : ""}` }] };
+        }
+      }
+      if (preflight.repo_grounded) {
+        if (resolvedProject && include_memories !== false) {
+          const memoryRescue = await runContextQueryMemoryRescue({
+            project: resolvedProject,
+            query,
+            user_id: user_id ? scope.userId : void 0,
+            session_id: session_id ? scope.sessionId : void 0,
+            top_k
+          });
+          if (memoryRescue.results.length && memoryRescue.rescue_mode) {
+            return {
+              content: [{
+                type: "text",
+                text: `${renderContextQueryMemoryRescue({
+                  project: resolvedProject,
+                  query,
+                  scope,
+                  results: memoryRescue.results,
+                  rescue_mode: memoryRescue.rescue_mode
+                })}
+
+[diagnostics]
+retrieval_route=memory_only retrieval_readiness=${preflight.retrieval_readiness} workspace=${preflight.trust_state.workspace_id}`
+              }]
+            };
+          }
+        }
+        return {
+          content: [{
+            type: "text",
+            text: `No relevant repo-grounded context found.
+
+[diagnostics]
+workspace=${preflight.trust_state.workspace_id} identity_source=${preflight.trust_state.identity_source} retrieval_readiness=${preflight.retrieval_readiness} retrieval_route=${preflight.retrieval_route}`
+          }]
+        };
+      }
+      const automaticMode = !preflight.repo_grounded && include_memories !== false && include_graph !== true && !(chunk_types && chunk_types.length > 0) && max_tokens === void 0 && runtimeClient;
       if (automaticMode) {
         try {
           const prepared = await prepareAutomaticQuery({
@@ -5298,7 +5860,8 @@ server.tool(
             query,
             top_k,
             user_id,
-            session_id
+            session_id,
+            path: preflight.trust_state.root_path
           });
           if (!prepared.items.length) {
             const memoryRescue = include_memories !== false ? await runContextQueryMemoryRescue({
@@ -5351,8 +5914,8 @@ ${prepared.context}${warnings}`
             top_k,
             include_memories: include_memories === true,
             include_graph,
-            user_id: user_id || resolveMcpScope({ user_id }).userId,
-            session_id: session_id || resolveMcpScope({ session_id }).sessionId
+            user_id: user_id || scope.userId,
+            session_id: session_id || scope.sessionId
           });
           const response2 = queryResult2.response;
           if (response2.results.length === 0) {
@@ -5404,8 +5967,8 @@ ${automaticWarning}${suffix2}` }] };
         top_k,
         include_memories: include_memories === true,
         include_graph,
-        user_id: user_id || resolveMcpScope({ user_id }).userId,
-        session_id: session_id || resolveMcpScope({ session_id }).sessionId
+        user_id: user_id || scope.userId,
+        session_id: session_id || scope.sessionId
       });
       const response = queryResult.response;
       if (response.results.length === 0) {
@@ -5483,7 +6046,7 @@ server.tool(
 );
 server.tool(
   "memory.search",
-  "Search stored memories by semantic similarity. Recall facts, preferences, past decisions from previous interactions.",
+  "Call this before answering questions about user history (preferences, prior decisions, past tasks, or 'what did we discuss/search'). Returns memory context you would not otherwise know.",
   {
     project: z.string().optional().describe("Project name or slug"),
     query: z.string().describe("What to search for"),
@@ -6462,6 +7025,7 @@ var CODE_EXTENSIONS = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "
 function extractSignature(filePath, content) {
   const lines = content.split("\n");
   const signature = /* @__PURE__ */ new Set([`// File: ${filePath}`]);
+  signature.add(`relative_path:${filePath.replace(/\\/g, "/").toLowerCase()}`);
   for (const segment of filePath.split(/[\\/._-]+/).filter(Boolean)) {
     signature.add(`path:${segment}`);
   }
@@ -6477,29 +7041,39 @@ function extractSignature(filePath, content) {
     if (routeMatches) {
       for (const match of routeMatches.slice(0, 3)) signature.add(`route:${match.slice(0, 120)}`);
     }
+    const envKeyMatches = trimmed.match(/[A-Z][A-Z0-9_]{2,}/g);
+    if (envKeyMatches) {
+      for (const match of envKeyMatches.slice(0, 3)) signature.add(`env:${match}`);
+    }
     if (/^(import|from|require|use |pub use )/.test(trimmed)) {
       signature.add(trimmed.slice(0, 120));
       continue;
     }
     if (/^(export|async function|function|class|interface|type |const |let |def |pub fn |fn |struct |impl |enum )/.test(trimmed)) {
       signature.add(trimmed.slice(0, 120));
+      const exportMatch = trimmed.match(/export\s+(?:const|function|class|type|interface)\s+([A-Za-z0-9_$]+)/);
+      if (exportMatch?.[1]) signature.add(`export:${exportMatch[1]}`);
       continue;
     }
     if (trimmed.startsWith("@") || trimmed.startsWith("#[")) {
       signature.add(trimmed.slice(0, 80));
     }
   }
-  for (const line of lines.slice(60)) {
-    const trimmed = line.trim();
+  for (let index = 60; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
     if (/^(export (default |async )?function|export (default )?class|export const|export type|export interface|async function|function |class |def |pub fn |fn )/.test(trimmed)) {
       signature.add(trimmed.slice(0, 120));
+      const surrounding = lines.slice(index, Math.min(lines.length, index + 3)).map((line) => line.trim()).filter(Boolean);
+      for (const line of surrounding) signature.add(line.slice(0, 120));
       continue;
     }
     if (/^[A-Za-z0-9_$]+\s*[:=]\s*["'`][^"'`]{3,}["'`]/.test(trimmed)) {
       signature.add(trimmed.slice(0, 120));
     }
+    const exportMatch = trimmed.match(/export\s+(?:const|function|class|type|interface)\s+([A-Za-z0-9_$]+)/);
+    if (exportMatch?.[1]) signature.add(`export:${exportMatch[1]}`);
   }
-  return Array.from(signature).join("\n").slice(0, 2500);
+  return Array.from(signature).join("\n").slice(0, 3200);
 }
 server.tool(
   "code.search_semantic",
@@ -6766,7 +7340,7 @@ server.tool(
 );
 server.tool(
   "search",
-  "Search retrievable context by query, exact id, or both. Use `id` for exact fetch and `query` for semantic retrieval.",
+  "Primary retrieval alias. Call this whenever the user asks to find or recall context: use `query` for semantic retrieval, `id` for exact memory fetch, or both for hybrid recall.",
   {
     project: z.string().optional().describe("Project name or slug"),
     query: z.string().optional().describe("Semantic retrieval query"),
@@ -6996,7 +7570,7 @@ server.tool(
 );
 server.tool(
   "index",
-  "Index a new source or refresh a workspace. Use action='source' to add GitHub/web/pdf/local/slack/video. Use action='workspace' to refresh local workspace metadata.",
+  "Administrative indexing tool. Call this when retrieval is stale/missing or the user asks to connect new data. Use action='source' to add GitHub/web/pdf/local/slack/video, action='workspace' to refresh local workspace metadata.",
   {
     action: z.enum(["source", "workspace"]).default("source"),
     project: z.string().optional(),
@@ -7077,7 +7651,7 @@ server.tool(
 );
 server.tool(
   "remember",
-  "Store something the agent should keep across sessions: a fact, decision, preference, or instruction.",
+  "Call this whenever the user states a durable preference, decision, instruction, or personal/project fact that should persist across sessions. Save proactively without waiting for an explicit 'remember this'.",
   {
     project: z.string().optional(),
     content: z.string().describe("Memory content"),
@@ -7156,7 +7730,7 @@ server.tool(
 );
 server.tool(
   "learn",
-  "Unified learning tool for conversation memory, text ingestion, and source indexing. Prefer this over the older learning-adjacent compatibility tools.",
+  "Unified ingestion entrypoint. Call this when the user asks to import knowledge: mode='conversation' for chat logs, mode='text' for raw text, mode='source' for external sources to index. Prefer this over legacy compatibility tools.",
   {
     mode: z.enum(["conversation", "text", "source"]).describe("What kind of learning to perform"),
     project: z.string().optional(),
@@ -7289,6 +7863,8 @@ if (process.argv[1] && /server\.(mjs|cjs|js|ts)$/.test(process.argv[1])) {
 export {
   canonicalizeWorkspacePath,
   chooseWorkspaceProjectSource,
+  classifyProjectRepoReadiness,
+  classifyRepoGroundedQuery,
   classifyWorkspaceHealth,
   createMcpServer,
   createWhisperMcpClient,
@@ -7296,5 +7872,6 @@ export {
   extractSignature,
   renderScopedMcpConfig,
   resolveForgetQueryCandidates,
+  resolveWorkspaceIdentity,
   runSearchCodeSearch
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usewhisper/mcp-server",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "whisperContractVersion": "2026.03.10",
   "scripts": {
     "build": "tsup ../src/mcp/server.ts --format esm --out-dir dist",