@usewhisper/mcp-server 2.9.0 → 2.11.0

package/dist/server.js

@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { execSync, spawnSync } from "child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from "fs";
-import { join, relative, extname } from "path";
+import { join, relative, extname, normalize as normalizePath, resolve as resolvePath } from "path";
 import { homedir } from "os";
 import { createHash, randomUUID } from "crypto";
 
@@ -3879,17 +3879,195 @@ function ensureStateDir() {
     mkdirSync(STATE_DIR, { recursive: true });
   }
 }
+function canonicalizeWorkspacePath(path, cwd = process.cwd()) {
+  const basePath = path?.trim() ? path.trim() : cwd;
+  const absolute = resolvePath(cwd, basePath);
+  const normalized = normalizePath(absolute).replace(/\\/g, "/");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function chooseWorkspaceProjectSource(args) {
+  const explicitProject = args.explicitProject?.trim();
+  if (explicitProject) {
+    return { project_ref: explicitProject, resolved_by: "explicit_project" };
+  }
+  const workspaceProjectRef = args.workspaceProjectRef?.trim();
+  if (workspaceProjectRef) {
+    return { project_ref: workspaceProjectRef, resolved_by: "workspace_binding" };
+  }
+  const defaultProject = args.defaultProject?.trim();
+  if (defaultProject) {
+    return { project_ref: defaultProject, resolved_by: "env_default" };
+  }
+  return { project_ref: null, resolved_by: "unresolved" };
+}
+function classifyWorkspaceHealth(args) {
+  if (!args.project_ref) return "unbound";
+  if (!args.last_indexed_at || (args.coverage ?? 0) <= 0) return "unindexed";
+  const nowMs = args.now_ms ?? Date.now();
+  const lastIndexedMs = new Date(args.last_indexed_at).getTime();
+  const ageHours = Number.isFinite(lastIndexedMs) ? (nowMs - lastIndexedMs) / (60 * 60 * 1e3) : Number.POSITIVE_INFINITY;
+  const pendingChanges = args.pending_changes ?? 0;
+  const drifted = pendingChanges > 0 || Boolean(
+    args.last_indexed_commit && args.current_commit && args.last_indexed_commit !== args.current_commit
+  );
+  if (drifted) return "drifted";
+  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 = `${process.cwd()}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  const seed = `${canonicalizeWorkspacePath(process.cwd())}|${API_KEY.slice(0, 12) || "anon"}`;
   return createHash("sha256").update(seed).digest("hex").slice(0, 20);
 }
 function getWorkspaceIdForPath(path, workspaceId) {
   if (workspaceId?.trim()) return workspaceId.trim();
   if (!path) return getWorkspaceId(void 0);
-  const seed = `${path}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12)}`;
+  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;
@@ -3978,7 +4156,10 @@ function getWorkspaceState(state, workspaceId) {
       annotations: [],
       session_summaries: [],
       events: [],
-      index_metadata: {}
+      index_metadata: {},
+      root_path: void 0,
+      project_ref: void 0,
+      project_id: void 0
     };
   }
   return state.workspaces[workspaceId];
@@ -3988,17 +4169,126 @@ function computeChecksum(value) {
 }
 var cachedProjectRef = DEFAULT_PROJECT || void 0;
 var cachedMcpSessionId = process.env.WHISPER_SESSION_ID || `mcp_${randomUUID().slice(0, 12)}`;
+async function resolveProjectDescriptor(projectRef) {
+  try {
+    const resolved = await whisper.resolveProject(projectRef);
+    const resolvedRef = resolved.slug || resolved.name || resolved.id || projectRef;
+    cachedProjectRef = resolvedRef;
+    return { project_ref: resolvedRef, project_id: resolved.id || null };
+  } catch {
+    cachedProjectRef = projectRef;
+    return { project_ref: projectRef, project_id: null };
+  }
+}
+function getWorkspaceRecommendedNextCalls(health) {
+  if (health === "unbound") return ["index.workspace_resolve", "context.list_projects", "index.workspace_status"];
+  if (health === "unindexed") return ["index.workspace_status", "index.workspace_run", "search_code", "grep"];
+  if (health === "stale" || health === "drifted") return ["index.workspace_status", "index.workspace_run", "grep", "search_code"];
+  return [];
+}
+function getWorkspaceWarnings(args) {
+  if (args.health === "unbound") {
+    return [`Workspace ${args.rootPath} is not bound to a Whisper project.`];
+  }
+  if (args.health === "unindexed") {
+    return [`Workspace ${args.rootPath} is bound to ${args.projectRef}, but no usable local index metadata exists yet.`];
+  }
+  if (args.health === "stale") {
+    const age = args.freshness.age_hours == null ? "unknown" : `${Math.round(args.freshness.age_hours)}h`;
+    return [`Workspace index for ${args.projectRef} is stale (${age} old).`];
+  }
+  if (args.health === "drifted") {
+    const reasons = [];
+    if (args.pendingChanges && args.pendingChanges > 0) reasons.push(`${args.pendingChanges} pending local changes`);
+    if (args.lastIndexedCommit && args.currentCommit && args.lastIndexedCommit !== args.currentCommit) {
+      reasons.push(`indexed commit ${args.lastIndexedCommit.slice(0, 12)} differs from current ${args.currentCommit.slice(0, 12)}`);
+    }
+    const suffix = reasons.length ? `: ${reasons.join("; ")}` : "";
+    return [`Workspace state drifted since the last index${suffix}.`];
+  }
+  return [];
+}
+async function resolveWorkspaceTrust(args) {
+  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;
+  if (workspace.root_path !== rootPath) {
+    workspace.root_path = rootPath;
+    mutated = true;
+  }
+  const selected = chooseWorkspaceProjectSource({
+    explicitProject: args.project,
+    workspaceProjectRef: workspace.project_ref,
+    defaultProject: DEFAULT_PROJECT || null
+  });
+  let projectRef = null;
+  let projectId = workspace.project_id || null;
+  if (selected.project_ref) {
+    const resolved = await resolveProjectDescriptor(selected.project_ref);
+    projectRef = resolved.project_ref;
+    projectId = resolved.project_id;
+    if (workspace.project_ref !== projectRef || (workspace.project_id || null) !== projectId) {
+      workspace.project_ref = projectRef;
+      workspace.project_id = projectId || void 0;
+      mutated = true;
+    }
+  }
+  if (mutated) saveState(state);
+  const lastIndexedAt = workspace.index_metadata?.last_indexed_at || null;
+  const ageHours = lastIndexedAt ? (Date.now() - new Date(lastIndexedAt).getTime()) / (60 * 60 * 1e3) : null;
+  const currentCommit = getGitHead(rootPath) || null;
+  const pendingChanges = getGitPendingCount(rootPath);
+  const lastIndexedCommit = workspace.index_metadata?.last_indexed_commit || null;
+  const coverage = workspace.index_metadata?.coverage ?? 0;
+  const health = classifyWorkspaceHealth({
+    project_ref: projectRef,
+    coverage,
+    last_indexed_at: lastIndexedAt,
+    last_indexed_commit: lastIndexedCommit,
+    current_commit: currentCommit,
+    pending_changes: pendingChanges ?? null,
+    max_staleness_hours: args.max_staleness_hours ?? 168
+  });
+  const freshness = {
+    stale: health === "stale",
+    age_hours: ageHours,
+    last_indexed_at: lastIndexedAt
+  };
+  const warnings = getWorkspaceWarnings({
+    health,
+    rootPath,
+    projectRef,
+    currentCommit,
+    lastIndexedCommit,
+    pendingChanges: pendingChanges ?? null,
+    freshness
+  });
+  return {
+    workspace_id: workspaceId,
+    root_path: rootPath,
+    identity_source: identity.identity_source,
+    project_ref: projectRef,
+    project_id: projectId,
+    resolved_by: selected.resolved_by,
+    health,
+    warnings,
+    recommended_next_calls: getWorkspaceRecommendedNextCalls(health),
+    freshness,
+    coverage,
+    last_indexed_commit: lastIndexedCommit,
+    current_commit: currentCommit,
+    pending_changes: pendingChanges ?? null,
+    grounded_to_workspace: health === "healthy"
+  };
+}
 async function resolveProjectRef(explicit) {
   if (explicit?.trim()) {
     const requestedRef = explicit.trim();
-    try {
-      const resolved = await whisper.resolveProject(requestedRef);
-      cachedProjectRef = resolved.slug || resolved.name || resolved.id;
-      return cachedProjectRef;
-    } catch {
-      cachedProjectRef = requestedRef;
-      return requestedRef;
-    }
+    const resolved = await resolveProjectDescriptor(requestedRef);
+    return resolved.project_ref;
   }
   if (cachedProjectRef) return cachedProjectRef;
   try {
@@ -4011,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({
@@ -4037,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) {
@@ -4101,7 +4483,9 @@ function buildAbstain(args) {
     reason: args.reason,
     message: args.message,
     closest_evidence: args.closest_evidence,
-    recommended_next_calls: ["index.workspace_status", "index.workspace_run", "symbol_search", "context.get_relevant"],
+    warnings: args.warnings || [],
+    trust_state: args.trust_state,
+    recommended_next_calls: args.recommended_next_calls || ["index.workspace_status", "index.workspace_run", "grep", "context.get_relevant"],
     diagnostics: {
       claims_evaluated: args.claims_evaluated,
       evidence_items_found: args.evidence_items_found,
@@ -4177,6 +4561,86 @@ function formatCanonicalMemoryResults(rawResults) {
     };
   });
 }
+function normalizeLooseText(value) {
+  return String(value || "").trim().toLowerCase().replace(/\s+/g, " ");
+}
+function resolveForgetQueryCandidates(rawResults, query) {
+  const normalizedQuery = normalizeLooseText(query);
+  const candidates = normalizeCanonicalResults(rawResults).map((result) => {
+    const memory = result?.memory || result;
+    const metadata = memory?.metadata || {};
+    return {
+      id: String(memory?.id || "").trim(),
+      content: normalizeLooseText(memory?.content),
+      normalized_content: normalizeLooseText(metadata?.normalized_content),
+      canonical_content: normalizeLooseText(metadata?.canonical_content),
+      similarity: typeof result?.similarity === "number" ? result.similarity : typeof result?.score === "number" ? result.score : 0
+    };
+  }).filter((candidate) => candidate.id);
+  const exactMatches = candidates.filter(
+    (candidate) => candidate.id.toLowerCase() === normalizedQuery || candidate.content === normalizedQuery || candidate.normalized_content === normalizedQuery || candidate.canonical_content === normalizedQuery
+  );
+  if (exactMatches.length > 0) {
+    return { memory_ids: [...new Set(exactMatches.map((candidate) => candidate.id))], resolved_by: "exact" };
+  }
+  const substringMatches = candidates.filter((candidate) => {
+    const haystacks = [candidate.content, candidate.normalized_content, candidate.canonical_content].filter(Boolean);
+    return haystacks.some(
+      (value) => value.includes(normalizedQuery) || normalizedQuery.length >= 12 && normalizedQuery.includes(value)
+    );
+  });
+  if (substringMatches.length === 1) {
+    return { memory_ids: [substringMatches[0].id], resolved_by: "substring" };
+  }
+  if (substringMatches.length > 1) {
+    return {
+      memory_ids: [],
+      resolved_by: "ambiguous",
+      warning: "Query matched multiple memories by recognizable text. Use memory_id or a more specific query."
+    };
+  }
+  const ranked = [...candidates].sort((a, b) => b.similarity - a.similarity);
+  if (ranked[0] && ranked[0].similarity >= 0.9 && (!ranked[1] || ranked[0].similarity - ranked[1].similarity >= 0.08)) {
+    return { memory_ids: [ranked[0].id], resolved_by: "high_confidence" };
+  }
+  return { memory_ids: [], resolved_by: "none", warning: "Query did not resolve to a reliable memory match. No memories were changed." };
+}
+async function searchMemoriesForContextQuery(args) {
+  return whisper.searchMemoriesSOTA({
+    project: args.project,
+    query: args.query,
+    user_id: args.user_id,
+    session_id: args.session_id,
+    top_k: args.top_k ?? 5,
+    include_relations: false,
+    include_pending: true
+  });
+}
+async function runContextQueryMemoryRescue(args) {
+  const scoped = await searchMemoriesForContextQuery(args);
+  const scopedResults = formatCanonicalMemoryResults(scoped);
+  if (scopedResults.length > 0) {
+    return { results: scopedResults, rescue_mode: "scoped" };
+  }
+  if (args.user_id || args.session_id) {
+    return { results: [], rescue_mode: null };
+  }
+  const broad = await searchMemoriesForContextQuery({
+    project: args.project,
+    query: args.query,
+    top_k: args.top_k
+  });
+  return { results: formatCanonicalMemoryResults(broad), rescue_mode: formatCanonicalMemoryResults(broad).length > 0 ? "project_broad" : null };
+}
+function renderContextQueryMemoryRescue(args) {
+  const lines = args.results.map(
+    (result, index) => `${index + 1}. [${result.memory_type || "memory"}, score: ${result.similarity ?? "n/a"}] ${result.content}`
+  );
+  const scopeLabel = args.rescue_mode === "project_broad" ? `project=${args.project}, project_broad_memory_rescue=true` : `project=${args.project}, user=${args.scope.userId}, session=${args.scope.sessionId}, scoped_memory_rescue=true`;
+  return `Found ${args.results.length} memory result(s) (${scopeLabel}):
+
+${lines.join("\n\n")}`;
+}
 function likelyEmbeddingFailure(error) {
   const message = String(error?.message || error || "").toLowerCase();
   return message.includes("embedding") || message.includes("vector") || message.includes("timeout") || message.includes("timed out") || message.includes("temporarily unavailable");
@@ -4191,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
     });
@@ -4205,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,
@@ -4218,6 +4684,308 @@ async function queryWithDegradedFallback(params) {
     };
   }
 }
+function collectCodeFiles(rootPath, allowedExts, maxFiles) {
+  const files = [];
+  function collect(dir) {
+    if (files.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) collect(full);
+      else if (entry.isFile()) {
+        const ext = extname(entry.name).replace(".", "");
+        if (allowedExts.has(ext)) files.push(full);
+      }
+    }
+  }
+  collect(rootPath);
+  return files;
+}
+function tokenizeQueryForLexicalRescue(query) {
+  const stopWords = /* @__PURE__ */ new Set(["where", "what", "show", "find", "logic", "code", "file", "files", "handled", "handling"]);
+  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);
+  if (tokens.length === 0) return [];
+  const scored = args.documents.map((doc) => {
+    const haystack = `${doc.id}
+${doc.content}
+${doc.raw_content}`.toLowerCase();
+    const tokenHits = tokens.filter((token) => haystack.includes(token));
+    const uniqueHits = tokenHits.length;
+    const exactPhraseBonus = haystack.includes(args.query.toLowerCase()) ? 0.25 : 0;
+    const score = uniqueHits === 0 ? 0 : Math.min(0.95, uniqueHits / tokens.length + exactPhraseBonus);
+    return {
+      id: doc.id,
+      score,
+      content: doc.content,
+      snippet: doc.content.split("\n").find((line) => line.trim().length > 10)?.slice(0, 200) || doc.id,
+      search_mode: "lexical_rescue"
+    };
+  });
+  return scored.filter((result) => result.score > 0).sort((a, b) => b.score - a.score).slice(0, args.top_k);
+}
+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: semanticTopK,
+    threshold: requestedThreshold
+  });
+  if (defaultResponse.results?.length) {
+    return {
+      results: defaultResponse.results.slice(0, topK).map((result) => ({ ...result, search_mode: "semantic" })),
+      mode: "semantic",
+      threshold_used: requestedThreshold,
+      fallback_used: false,
+      fallback_reason: null
+    };
+  }
+  const adaptiveThreshold = Math.max(0.05, Math.min(requestedThreshold, requestedThreshold / 2));
+  if (adaptiveThreshold < requestedThreshold) {
+    const adaptiveResponse = await args.semantic_search({
+      query: args.query,
+      documents: semanticDocuments,
+      top_k: semanticTopK,
+      threshold: adaptiveThreshold
+    });
+    if (adaptiveResponse.results?.length) {
+      return {
+        results: adaptiveResponse.results.slice(0, topK).map((result) => ({ ...result, search_mode: "adaptive_semantic" })),
+        mode: "adaptive_semantic",
+        threshold_used: adaptiveThreshold,
+        fallback_used: true,
+        fallback_reason: `No results at threshold ${requestedThreshold}; lowered to ${adaptiveThreshold}.`
+      };
+    }
+  }
+  const lexicalResults = buildLexicalRescueResults({
+    query: args.query,
+    documents: args.documents,
+    top_k: topK
+  });
+  return {
+    results: lexicalResults,
+    mode: "lexical_rescue",
+    threshold_used: null,
+    fallback_used: true,
+    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."
+  };
+}
+function buildLocalWorkspaceDocuments(rootPath, allowedExts, maxFiles) {
+  const files = collectCodeFiles(rootPath, allowedExts, maxFiles);
+  const documents = [];
+  for (const filePath of files) {
+    try {
+      const stat = statSync(filePath);
+      if (stat.size > 500 * 1024) continue;
+      const content = readFileSync(filePath, "utf-8");
+      const relPath = relative(rootPath, filePath).replace(/\\/g, "/");
+      documents.push({ id: relPath, content: extractSignature(relPath, content), raw_content: content });
+    } 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,
+    top_k: args.top_k,
+    threshold: args.threshold,
+    semantic_search: (params) => whisper.semanticSearch(params)
+  });
+  if (searchResult.mode === "lexical_rescue") {
+    sharedWarnings.push("Local lexical rescue was used because semantic search returned no matches.");
+  } else if (searchResult.mode === "adaptive_semantic") {
+    sharedWarnings.push(searchResult.fallback_reason || "Adaptive semantic thresholding was used.");
+  }
+  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 {
+    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: 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;
@@ -4297,7 +5065,8 @@ async function ingestLocalPath(params) {
   }
   collect(rootPath);
   const manifest = loadIngestManifest();
-  const workspaceId = getWorkspaceIdForPath(rootPath);
+  const canonicalRootPath = canonicalizeWorkspacePath(rootPath);
+  const workspaceId = getWorkspaceIdForPath(canonicalRootPath);
   if (!manifest[workspaceId]) manifest[workspaceId] = { last_run_at: (/* @__PURE__ */ new Date(0)).toISOString(), files: {} };
   const docs = [];
   const skipped = [];
@@ -4333,6 +5102,10 @@ async function ingestLocalPath(params) {
   }
   manifest[workspaceId].last_run_at = (/* @__PURE__ */ new Date()).toISOString();
   saveIngestManifest(manifest);
+  const state = loadState();
+  const workspace = getWorkspaceState(state, workspaceId);
+  workspace.root_path = canonicalRootPath;
+  saveState(state);
   appendFileSync(
     AUDIT_LOG_PATH,
     `${(/* @__PURE__ */ new Date()).toISOString()} local_ingest workspace=${workspaceId} root_hash=${createHash("sha256").update(rootPath).digest("hex").slice(0, 16)} files=${docs.length}
@@ -4488,22 +5261,27 @@ server.tool(
   },
   async ({ path, workspace_id, project }) => {
     try {
-      const workspaceId = getWorkspaceIdForPath(path, workspace_id);
+      const identity = resolveWorkspaceIdentity({ path, workspace_id });
       const state = loadState();
-      const existed = Boolean(state.workspaces[workspaceId]);
-      const workspace = getWorkspaceState(state, workspaceId);
-      const resolvedProject = await resolveProjectRef(project);
-      const resolvedBy = project?.trim() ? "explicit_project" : DEFAULT_PROJECT ? "env_default" : resolvedProject ? "auto_first_project" : "unresolved";
-      saveState(state);
+      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,
-        project_id: resolvedProject || null,
+        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: resolvedBy,
+        resolved_by: trust.resolved_by,
+        health: trust.health,
+        retrieval_readiness: preflight.retrieval_readiness,
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls,
         index_state: {
-          last_indexed_at: workspace.index_metadata?.last_indexed_at || null,
-          last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
-          coverage: workspace.index_metadata?.coverage ?? 0
+          last_indexed_at: trust.freshness.last_indexed_at,
+          last_indexed_commit: trust.last_indexed_commit,
+          coverage: trust.coverage
         }
       };
       return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
@@ -4521,24 +5299,30 @@ server.tool(
   },
   async ({ workspace_id, path }) => {
     try {
-      const rootPath = path || process.cwd();
-      const workspaceId = getWorkspaceIdForPath(rootPath, workspace_id);
-      const state = loadState();
-      const workspace = getWorkspaceState(state, workspaceId);
-      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
-      const ageHours = lastIndexedAt ? (Date.now() - new Date(lastIndexedAt).getTime()) / (60 * 60 * 1e3) : null;
-      const stale = ageHours === null ? true : ageHours > 168;
+      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: workspaceId,
-        freshness: {
-          stale,
-          age_hours: ageHours,
-          last_indexed_at: lastIndexedAt || null
-        },
-        coverage: workspace.index_metadata?.coverage ?? 0,
-        last_indexed_commit: workspace.index_metadata?.last_indexed_commit || null,
-        current_commit: getGitHead(rootPath) || null,
-        pending_changes: getGitPendingCount(rootPath)
+        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,
+        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,
+        current_commit: trust.current_commit,
+        pending_changes: trust.pending_changes,
+        grounded_to_workspace: trust.grounded_to_workspace
       };
       return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
     } catch (error) {
@@ -4557,13 +5341,15 @@ server.tool(
   },
   async ({ workspace_id, path, mode, max_files }) => {
     try {
-      const rootPath = path || process.cwd();
-      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);
       const coverage = Math.max(0, Math.min(1, fileStats.total / Math.max(1, max_files)));
       const now = (/* @__PURE__ */ new Date()).toISOString();
+      workspace.root_path = rootPath;
       workspace.index_metadata = {
         last_indexed_at: now,
         last_indexed_commit: getGitHead(rootPath),
@@ -4572,6 +5358,7 @@ server.tool(
       saveState(state);
       const payload = {
         workspace_id: workspaceId,
+        root_path: rootPath,
         mode,
         indexed_files: fileStats.total,
         skipped_files: fileStats.skipped,
@@ -4623,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),
@@ -4634,45 +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 workspaceId = getWorkspaceId(workspace_id);
-      const resolvedProject = await resolveProjectRef(project);
-      if (!resolvedProject) {
+      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: 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: workspaceId,
+          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,
-          warning: "No project resolved. Set WHISPER_PROJECT or create one in your account."
+          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: resolvedProject,
+        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, workspaceId, "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: workspaceId,
-        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
+        recommendation: queryResult.recommendation,
+        warnings: preflight.warnings,
+        recommended_next_calls: preflight.recommended_next_calls
       };
       return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
     } catch (error) {
@@ -4685,36 +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 workspaceId = getWorkspaceId(workspace_id);
-      const resolvedProject = await resolveProjectRef(project);
-      if (!resolvedProject) {
+      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: [],
-          missing_requirements: ["No project resolved. Set WHISPER_PROJECT or create one in your account."],
-          explanation: "Verifier could not run because no project is configured."
+          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: resolvedProject,
-        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, workspaceId, "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";
@@ -4724,6 +5599,11 @@ server.tool(
         verdict,
         confidence: evidence.length ? Math.max(...evidence.map((e) => e.score)) : 0,
         evidence: verdict === "supported" ? directEvidence : weakEvidence,
+        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."
       };
@@ -4738,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({
@@ -4752,41 +5633,53 @@ 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 workspaceId = getWorkspaceId(workspace_id);
       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 resolvedProject = await resolveProjectRef(project);
-      if (!resolvedProject) {
+      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: "no_retrieval_hits",
-          message: "No project resolved. Set WHISPER_PROJECT or create one in your account.",
+          reason,
+          message: preflight.warnings[0] || "Workspace trust requirements were not met.",
           closest_evidence: [],
           claims_evaluated: 1,
           evidence_items_found: 0,
           min_required: minEvidenceItems,
-          index_fresh: true
+          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: resolvedProject,
-        query: question,
-        top_k: topK,
-        include_memories: true,
-        include_graph: true
-      });
-      const evidence = (response.results || []).map((r) => toEvidenceRef(r, workspaceId, "semantic"));
       const sorted = evidence.sort((a, b) => b.score - a.score);
       const confidence = sorted.length ? sorted[0].score : 0;
-      const state = loadState();
-      const workspace = getWorkspaceState(state, workspaceId);
-      const lastIndexedAt = workspace.index_metadata?.last_indexed_at;
-      const indexFresh = !lastIndexedAt || Date.now() - new Date(lastIndexedAt).getTime() <= maxStalenessHours * 60 * 60 * 1e3;
       if (sorted.length === 0) {
         const abstain = buildAbstain({
           reason: "no_retrieval_hits",
@@ -4795,24 +5688,15 @@ server.tool(
           claims_evaluated: 1,
           evidence_items_found: 0,
           min_required: minEvidenceItems,
-          index_fresh: indexFresh
+          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 supportedEvidence = sorted.filter((e) => e.score >= minConfidence);
       const verdict = supportedEvidence.length >= 1 ? "supported" : "partial";
-      if (!indexFresh) {
-        const abstain = buildAbstain({
-          reason: "stale_index",
-          message: "Index freshness requirement not met. Re-index before answering.",
-          closest_evidence: sorted.slice(0, 3),
-          claims_evaluated: 1,
-          evidence_items_found: supportedEvidence.length,
-          min_required: minEvidenceItems,
-          index_fresh: false
-        });
-        return { content: [{ type: "text", text: JSON.stringify(abstain, null, 2) }] };
-      }
       if (requireCitations && (verdict !== "supported" || supportedEvidence.length < minEvidenceItems)) {
         const abstain = buildAbstain({
           reason: "insufficient_evidence",
@@ -4821,7 +5705,10 @@ server.tool(
           claims_evaluated: 1,
           evidence_items_found: supportedEvidence.length,
           min_required: minEvidenceItems,
-          index_fresh: true
+          index_fresh: true,
+          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) }] };
       }
@@ -4834,6 +5721,11 @@ server.tool(
         answer: answerLines.join("\n"),
         citations,
         confidence,
+        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,
@@ -4849,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."),
@@ -4861,13 +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 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({
@@ -4875,9 +5860,31 @@ 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({
+              project: resolvedProject,
+              query,
+              user_id: user_id ? scope2.userId : void 0,
+              session_id: session_id ? scope2.sessionId : void 0,
+              top_k
+            }) : { results: [], rescue_mode: null };
+            if (memoryRescue.results.length && memoryRescue.rescue_mode) {
+              return {
+                content: [{
+                  type: "text",
+                  text: renderContextQueryMemoryRescue({
+                    project: resolvedProject,
+                    query,
+                    scope: scope2,
+                    results: memoryRescue.results,
+                    rescue_mode: memoryRescue.rescue_mode
+                  })
+                }]
+              };
+            }
             return { content: [{ type: "text", text: "No relevant context found." }] };
           }
           const warnings = prepared.retrieval.warnings.length ? `
@@ -4907,18 +5914,41 @@ ${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) {
+            const memoryRescue = include_memories !== false ? await runContextQueryMemoryRescue({
+              project: resolvedProject,
+              query,
+              user_id: user_id ? scope.userId : void 0,
+              session_id: session_id ? scope.sessionId : void 0,
+              top_k
+            }) : { results: [], rescue_mode: null };
+            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
+                  })}
+
+[automatic_runtime]
+${automaticWarning}`
+                }]
+              };
+            }
             return { content: [{ type: "text", text: `No relevant context found.
 
 [automatic_runtime]
 ${automaticWarning}` }] };
           }
-          const scope2 = resolveMcpScope({ user_id, session_id });
-          const header2 = `Found ${response2.meta.total} results (${response2.meta.latency_ms}ms${response2.meta.cache_hit ? ", cached" : ""}, project=${resolvedProject}, user=${scope2.userId}, session=${scope2.sessionId}):
+          const header2 = `Found ${response2.meta.total} results (${response2.meta.latency_ms}ms${response2.meta.cache_hit ? ", cached" : ""}, project=${resolvedProject}, user=${scope.userId}, session=${scope.sessionId}):
 
 `;
           const suffix2 = queryResult2.degraded_mode ? `
@@ -4937,14 +5967,34 @@ ${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) {
+        const memoryRescue = include_memories !== false ? await runContextQueryMemoryRescue({
+          project: resolvedProject,
+          query,
+          user_id: user_id ? scope.userId : void 0,
+          session_id: session_id ? scope.sessionId : void 0,
+          top_k
+        }) : { results: [], rescue_mode: null };
+        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
+              })
+            }]
+          };
+        }
         return { content: [{ type: "text", text: "No relevant context found." }] };
       }
-      const scope = resolveMcpScope({ user_id, session_id });
       const header = `Found ${response.meta.total} results (${response.meta.latency_ms}ms${response.meta.cache_hit ? ", cached" : ""}, project=${resolvedProject}, user=${scope.userId}, session=${scope.sessionId}):
 
 `;
@@ -4996,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"),
@@ -5587,6 +6637,7 @@ server.tool(
         return { content: [{ type: "text", text: "Error: target.memory_id or target.query is required." }] };
       }
       const affectedIds = [];
+      let queryResolution = null;
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const actor = process.env.WHISPER_AGENT_ID || process.env.USERNAME || "api_key_principal";
       const resolvedProject = await resolveProjectRef(project);
@@ -5645,24 +6696,18 @@ server.tool(
           project: resolvedProject,
           query: target.query || "",
           top_k: 25,
-          include_relations: false
-        });
-        const normalizedQuery = String(target.query || "").trim().toLowerCase();
-        const exactMatches = (search.results || []).filter((r) => {
-          const memory = r?.memory || r;
-          const content = String(memory?.content || "").trim().toLowerCase();
-          const memoryId = String(memory?.id || "").trim().toLowerCase();
-          const metadata = memory?.metadata || {};
-          const normalizedContent = String(metadata?.normalized_content || "").trim().toLowerCase();
-          const canonicalContent = String(metadata?.canonical_content || "").trim().toLowerCase();
-          return memoryId === normalizedQuery || content === normalizedQuery || normalizedContent === normalizedQuery || canonicalContent === normalizedQuery;
+          include_relations: false,
+          include_pending: true
         });
-        const memoryIds = exactMatches.map((r) => String(r?.memory?.id || "")).filter(Boolean);
+        const resolved = resolveForgetQueryCandidates(search, target.query || "");
+        queryResolution = resolved.resolved_by;
+        const memoryIds = resolved.memory_ids;
         if (memoryIds.length === 0) {
           const payload2 = {
             status: "completed",
             affected_ids: affectedIds,
-            warning: "Query did not resolve to an exact memory match. No memories were changed."
+            warning: resolved.warning || "Query did not resolve to a reliable memory match. No memories were changed.",
+            resolved_by: resolved.resolved_by
           };
           return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
         }
@@ -5684,6 +6729,7 @@ server.tool(
       const payload = {
         status: "completed",
         affected_ids: affectedIds,
+        ...queryResolution ? { resolved_by: queryResolution } : {},
         audit: {
           audit_id: audit.audit_id,
           actor: audit.actor,
@@ -5978,30 +7024,56 @@ var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".next"
 var CODE_EXTENSIONS = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "py", "go", "rs", "java", "cpp", "c", "cs", "rb", "php", "swift", "kt", "sql", "prisma", "graphql", "json", "yaml", "yml", "toml", "env"]);
 function extractSignature(filePath, content) {
   const lines = content.split("\n");
-  const signature = [`// File: ${filePath}`];
+  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}`);
+  }
   const head = lines.slice(0, 60);
   for (const line of head) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
+    const urlMatches = trimmed.match(/https?:\/\/[^\s"'`]+/g);
+    if (urlMatches) {
+      for (const match of urlMatches.slice(0, 2)) signature.add(`url:${match.slice(0, 120)}`);
+    }
+    const routeMatches = trimmed.match(/\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{2,}/g);
+    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.push(trimmed.slice(0, 120));
+      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.push(trimmed.slice(0, 120));
+      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.push(trimmed.slice(0, 80));
+      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.push(trimmed.slice(0, 120));
+      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 signature.join("\n").slice(0, 2e3);
+  return Array.from(signature).join("\n").slice(0, 3200);
 }
 server.tool(
   "code.search_semantic",
@@ -6015,91 +7087,21 @@ server.tool(
     max_files: z.number().optional().default(150).describe("Max files to scan. For large codebases, narrow with file_types instead of raising this.")
   },
   async ({ query, path: searchPath, file_types, top_k, threshold, max_files }) => {
-    const rootPath = searchPath || process.cwd();
-    const allowedExts = file_types ? new Set(file_types) : CODE_EXTENSIONS;
-    const files = [];
-    function collect(dir) {
-      if (files.length >= (max_files ?? 300)) return;
-      let entries;
-      try {
-        entries = readdirSync(dir, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      for (const entry of entries) {
-        if (files.length >= (max_files ?? 300)) break;
-        if (SKIP_DIRS.has(entry.name)) continue;
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-          collect(full);
-        } else if (entry.isFile()) {
-          const ext = extname(entry.name).replace(".", "");
-          if (allowedExts.has(ext)) files.push(full);
-        }
-      }
-    }
-    collect(rootPath);
-    if (files.length === 0) {
-      return { content: [{ type: "text", text: `No code files found in ${rootPath}` }] };
-    }
-    const documents = [];
-    for (const filePath of files) {
-      try {
-        const stat = statSync(filePath);
-        if (stat.size > 500 * 1024) continue;
-        const content = readFileSync(filePath, "utf-8");
-        const relPath = relative(rootPath, filePath);
-        const signature = extractSignature(relPath, content);
-        documents.push({ id: relPath, content: signature });
-      } catch {
-      }
-    }
-    if (documents.length === 0) {
-      return { content: [{ type: "text", text: "Could not read any files." }] };
-    }
-    let response;
     try {
-      response = await whisper.semanticSearch({
-        query,
-        documents,
-        top_k: top_k ?? 10,
-        threshold: threshold ?? 0.2
+      return primaryToolSuccess({
+        ...await runSearchCodeTool({
+          query,
+          path: searchPath,
+          file_types,
+          top_k,
+          threshold,
+          max_files
+        }),
+        tool: "code.search_semantic"
       });
     } catch (error) {
-      return { content: [{ type: "text", text: `Semantic search failed: ${error.message}` }] };
-    }
-    if (!response.results || response.results.length === 0) {
-      return { content: [{ type: "text", text: `No semantically relevant files found for: "${query}"
-
-Searched ${documents.length} files in ${rootPath}.
-
-Try lowering the threshold or rephrasing your query.` }] };
-    }
-    const lines = [
-      `Semantic search: "${query}"`,
-      `Searched ${documents.length} files \u2192 ${response.results.length} relevant (${response.latency_ms}ms)
-`
-    ];
-    for (const result of response.results) {
-      lines.push(`\u{1F4C4} ${result.id}  (score: ${result.score})`);
-      if (result.snippet) {
-        lines.push(`   ${result.snippet}`);
-      }
-      if (result.score > 0.5) {
-        try {
-          const fullPath = join(rootPath, result.id);
-          const content = readFileSync(fullPath, "utf-8");
-          const excerpt = content.split("\n").slice(0, 30).join("\n");
-          lines.push(`
-\`\`\`
-${excerpt}
-\`\`\``);
-        } catch {
-        }
-      }
-      lines.push("");
+      return primaryToolError(`Semantic search failed: ${error.message}`);
     }
-    return { content: [{ type: "text", text: lines.join("\n") }] };
   }
 );
 function* walkDir(dir, fileTypes) {
@@ -6338,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"),
@@ -6416,72 +7418,15 @@ server.tool(
     max_files: z.number().optional().default(150)
   },
   async ({ query, path, file_types, top_k, threshold, max_files }) => {
-    const rootPath = path || process.cwd();
-    const allowedExts = file_types ? new Set(file_types) : CODE_EXTENSIONS;
-    const files = [];
-    function collect(dir) {
-      if (files.length >= (max_files ?? 150)) return;
-      let entries;
-      try {
-        entries = readdirSync(dir, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      for (const entry of entries) {
-        if (files.length >= (max_files ?? 150)) break;
-        if (SKIP_DIRS.has(entry.name)) continue;
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) collect(full);
-        else if (entry.isFile()) {
-          const ext = extname(entry.name).replace(".", "");
-          if (allowedExts.has(ext)) files.push(full);
-        }
-      }
-    }
-    collect(rootPath);
-    if (files.length === 0) {
-      return primaryToolSuccess({
-        tool: "search_code",
-        query,
-        path: rootPath,
-        results: [],
-        count: 0
-      });
-    }
-    const documents = [];
-    for (const filePath of files) {
-      try {
-        const stat = statSync(filePath);
-        if (stat.size > 500 * 1024) continue;
-        const content = readFileSync(filePath, "utf-8");
-        const relPath = relative(rootPath, filePath);
-        documents.push({ id: relPath, content: extractSignature(relPath, content) });
-      } catch {
-      }
-    }
     try {
-      const response = await whisper.semanticSearch({
-        query,
-        documents,
-        top_k: top_k ?? 10,
-        threshold: threshold ?? 0.2
-      });
-      if (!response.results?.length) {
-        return primaryToolSuccess({
-          tool: "search_code",
-          query,
-          path: rootPath,
-          results: [],
-          count: 0
-        });
-      }
-      return primaryToolSuccess({
-        tool: "search_code",
+      return primaryToolSuccess(await runSearchCodeTool({
         query,
-        path: rootPath,
-        results: response.results,
-        count: response.results.length
-      });
+        path,
+        file_types,
+        top_k,
+        threshold,
+        max_files
+      }));
     } catch (error) {
       return primaryToolError(`Semantic search failed: ${error.message}`);
     }
@@ -6625,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(),
@@ -6706,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"),
@@ -6785,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(),
@@ -6916,8 +7861,17 @@ if (process.argv[1] && /server\.(mjs|cjs|js|ts)$/.test(process.argv[1])) {
   main().catch(console.error);
 }
 export {
+  canonicalizeWorkspacePath,
+  chooseWorkspaceProjectSource,
+  classifyProjectRepoReadiness,
+  classifyRepoGroundedQuery,
+  classifyWorkspaceHealth,
   createMcpServer,
   createWhisperMcpClient,
   createWhisperMcpRuntimeClient,
-  renderScopedMcpConfig
+  extractSignature,
+  renderScopedMcpConfig,
+  resolveForgetQueryCandidates,
+  resolveWorkspaceIdentity,
+  runSearchCodeSearch
 };