@usewhisper/mcp-server 2.12.0 → 2.14.0

package/dist/server.js

@@ -3785,6 +3785,9 @@ function buildMcpSearchPayload(input) {
     count: normalizedResults.length,
     degraded_mode: Boolean(input.degradedMode),
     degraded_reason: input.degradedReason ?? null,
+    semantic_status: input.semanticStatus ?? (input.degradedMode ? "failed" : "ok"),
+    fallback_mode: input.fallbackMode ?? (input.degradedMode ? "lexical_backend" : "none"),
+    recommended_fixes: input.recommendedFixes || [],
     warnings: input.warnings || []
   });
 }
@@ -3844,6 +3847,8 @@ var RETRIEVAL_READINESS_VALUES = [
   "local_fallback"
 ];
 var RETRIEVAL_ROUTE_VALUES = ["project_repo", "local_workspace_fallback", "memory_only", "none"];
+var STATUS_LABEL_VALUES = ["healthy", "degraded_auto_repairing", "needs_user_action", "blocked"];
+var STATUS_ACTION_VALUES = ["none", "run_auto_repair", "restart_client", "reauth", "add_source", "reindex"];
 var STATE_DIR = join(homedir(), ".whisper-mcp");
 var STATE_PATH = join(STATE_DIR, "state.json");
 var AUDIT_LOG_PATH = join(STATE_DIR, "forget-audit.log");
@@ -3876,6 +3881,7 @@ var ALIAS_TOOL_MAP = [
   { alias: "search", target: "context.query | memory.get" },
   { alias: "search_code", target: "code.search_semantic" },
   { alias: "grep", target: "code.search_text" },
+  { alias: "fix", target: "index.auto_repair" },
   { alias: "read", target: "local.file_read" },
   { alias: "explore", target: "local.tree" },
   { alias: "research", target: "research.oracle" },
@@ -3891,10 +3897,14 @@ var RECOMMENDED_NEXT_CALL_ALLOWLIST = /* @__PURE__ */ new Set([
   "context.list_projects",
   "index.workspace_status",
   "index.workspace_run",
+  "index.auto_repair",
+  "fix",
   "search_code",
   "grep",
   "context.list_sources",
+  "context.add_source",
   "index.local_scan_ingest",
+  "context.query",
   "context.get_relevant"
 ]);
 var UNTRUSTED_CODEBASE_HEALTH = /* @__PURE__ */ new Set(["unbound", "unindexed"]);
@@ -3902,12 +3912,85 @@ var UNTRUSTED_CODEBASE_PROJECT_READINESS = /* @__PURE__ */ new Set([
   "project_unverified",
   "project_bound_no_repo_source"
 ]);
+var RETRIEVAL_READINESS_RANK = {
+  no_project: 0,
+  project_unverified: 0,
+  project_bound_no_repo_source: 1,
+  project_repo_source_stale: 2,
+  local_fallback: 3,
+  project_repo_source_ready: 4
+};
+var ROOT_CAUSE_PRIMARY_ACTION = {
+  none: "none",
+  missing_api_key: "reauth",
+  no_project_bound: "add_source",
+  mode_mismatch_remote_local_ingest: "restart_client",
+  workspace_unindexed: "reindex",
+  project_bound_no_repo_source: "add_source",
+  project_unverified: "reauth",
+  project_repo_source_stale: "reindex",
+  semantic_backend_unavailable: "run_auto_repair",
+  local_fallback_active: "run_auto_repair"
+};
+var ROOT_CAUSE_NEXT_CALLS = {
+  none: [],
+  missing_api_key: [],
+  no_project_bound: ["context.list_projects"],
+  mode_mismatch_remote_local_ingest: [],
+  workspace_unindexed: ["index.workspace_run"],
+  project_bound_no_repo_source: ["context.add_source"],
+  project_unverified: [],
+  project_repo_source_stale: ["index.workspace_run"],
+  semantic_backend_unavailable: ["fix"],
+  local_fallback_active: ["fix"]
+};
 function sanitizeRecommendedNextCalls(nextCalls) {
   return Array.from(
     new Set(
       nextCalls.map((entry) => String(entry || "").trim()).filter((entry) => RECOMMENDED_NEXT_CALL_ALLOWLIST.has(entry))
     )
-  );
+  ).slice(0, 3);
+}
+function recommendedNextCallsAreAcyclic(nextCalls) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const nextCall of nextCalls) {
+    if (seen.has(nextCall)) return false;
+    seen.add(nextCall);
+  }
+  return true;
+}
+function retrievalReadinessRank(readiness) {
+  return RETRIEVAL_READINESS_RANK[readiness];
+}
+function isStrictlyBetterReadiness(from, to) {
+  return retrievalReadinessRank(to) > retrievalReadinessRank(from);
+}
+function statusActionForRootCause(rootCause) {
+  return ROOT_CAUSE_PRIMARY_ACTION[rootCause] || "none";
+}
+function recommendedNextCallsForRootCause(rootCause) {
+  return sanitizeRecommendedNextCalls(ROOT_CAUSE_NEXT_CALLS[rootCause] || []);
+}
+function statusLabelForAction(action) {
+  if (action === "none") return "healthy";
+  if (action === "run_auto_repair") return "degraded_auto_repairing";
+  if (action === "reauth") return "blocked";
+  return "needs_user_action";
+}
+function actionRequiredForAction(action) {
+  return action !== "none" && action !== "run_auto_repair";
+}
+function getRepoReadinessNextCalls(readiness) {
+  if (readiness === "project_bound_no_repo_source") {
+    return recommendedNextCallsForRootCause("project_bound_no_repo_source");
+  }
+  if (readiness === "project_unverified") {
+    return recommendedNextCallsForRootCause("project_unverified");
+  }
+  if (readiness === "project_repo_source_stale") {
+    return recommendedNextCallsForRootCause("project_repo_source_stale");
+  }
+  return [];
 }
 function resolveMcpRetrievalProfile(requested) {
   if (requested && MCP_RETRIEVAL_PROFILE_VALUES.includes(requested)) {
@@ -3915,6 +3998,156 @@ function resolveMcpRetrievalProfile(requested) {
   }
   return MCP_RETRIEVAL_PRECISION_V1_DEFAULT ? "precision_v1" : "legacy";
 }
+function statusContractForReadiness(args) {
+  if (args.root_cause_code && args.root_cause_code !== "none") {
+    const action = statusActionForRootCause(args.root_cause_code);
+    return {
+      status_label: statusLabelForAction(action),
+      status_action: action,
+      action_required: actionRequiredForAction(action)
+    };
+  }
+  if (args.force_repairing) {
+    return {
+      status_label: "degraded_auto_repairing",
+      status_action: "run_auto_repair",
+      action_required: false
+    };
+  }
+  if (args.semantic_status === "failed") {
+    return {
+      status_label: "degraded_auto_repairing",
+      status_action: "run_auto_repair",
+      action_required: false
+    };
+  }
+  if (args.workspace_health === "unindexed") {
+    return {
+      status_label: "needs_user_action",
+      status_action: "reindex",
+      action_required: true
+    };
+  }
+  if (args.retrieval_readiness === "project_unverified") {
+    return {
+      status_label: "blocked",
+      status_action: "reauth",
+      action_required: true
+    };
+  }
+  if (args.retrieval_readiness === "project_bound_no_repo_source") {
+    if ((args.runtime_mode || RUNTIME_MODE) === "remote") {
+      return {
+        status_label: "needs_user_action",
+        status_action: "add_source",
+        action_required: true
+      };
+    }
+    return {
+      status_label: "needs_user_action",
+      status_action: "reindex",
+      action_required: true
+    };
+  }
+  if (args.retrieval_readiness === "project_repo_source_stale") {
+    return {
+      status_label: "needs_user_action",
+      status_action: "reindex",
+      action_required: true
+    };
+  }
+  if (args.retrieval_readiness === "local_fallback") {
+    return {
+      status_label: "degraded_auto_repairing",
+      status_action: "run_auto_repair",
+      action_required: false
+    };
+  }
+  if (args.retrieval_readiness === "no_project") {
+    return {
+      status_label: "needs_user_action",
+      status_action: "add_source",
+      action_required: true
+    };
+  }
+  return {
+    status_label: "healthy",
+    status_action: "none",
+    action_required: false
+  };
+}
+function semanticStatusFromSearchMode(mode) {
+  if (mode === "semantic") return "ok";
+  if (mode === "adaptive_semantic") return "adaptive";
+  return "failed";
+}
+function fallbackModeFromSearchMode(mode) {
+  if (mode === "semantic") return "none";
+  if (mode === "adaptive_semantic") return "adaptive_threshold";
+  return "lexical_rescue";
+}
+function parsePositiveNumber(value, fallback = 0) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+function getWorkspaceSemanticFailureStats(workspaceId) {
+  const state = loadState();
+  const workspace = getWorkspaceState(state, workspaceId);
+  const failures = parsePositiveNumber(workspace.index_metadata?.semantic_failures, 0);
+  const attempts = parsePositiveNumber(workspace.index_metadata?.semantic_attempts, 0);
+  const rate = attempts > 0 ? failures / attempts : 0;
+  return { failures, attempts, rate };
+}
+function recordSemanticAttempt(workspaceId, failed) {
+  const state = loadState();
+  const workspace = getWorkspaceState(state, workspaceId);
+  if (!workspace.index_metadata) workspace.index_metadata = {};
+  const failures = parsePositiveNumber(workspace.index_metadata.semantic_failures, 0);
+  const attempts = parsePositiveNumber(workspace.index_metadata.semantic_attempts, 0);
+  workspace.index_metadata.semantic_attempts = attempts + 1;
+  workspace.index_metadata.semantic_failures = failed ? failures + 1 : failures;
+  saveState(state);
+}
+function computeTrustScore(args) {
+  let score = 100;
+  if (args.workspace_health === "unbound" || args.workspace_health === "unindexed") score -= 35;
+  if (args.workspace_health === "stale" || args.workspace_health === "drifted") score -= 18;
+  if (args.retrieval_readiness === "project_unverified") score -= 35;
+  if (args.retrieval_readiness === "project_bound_no_repo_source") score -= 32;
+  if (args.retrieval_readiness === "project_repo_source_stale") score -= 20;
+  if (args.retrieval_readiness === "local_fallback") score -= 10;
+  const failureRate = Math.max(0, Math.min(1, args.semantic_failure_rate || 0));
+  score -= Math.round(failureRate * 25);
+  return Math.max(0, Math.min(100, score));
+}
+function persistTrustScore(workspaceId, trustScore) {
+  const state = loadState();
+  const workspace = getWorkspaceState(state, workspaceId);
+  if (!workspace.index_metadata) workspace.index_metadata = {};
+  workspace.index_metadata.trust_score = Math.max(0, Math.min(100, Math.round(trustScore)));
+  saveState(state);
+}
+function shouldAutoHeal(args) {
+  if (args.retrieval_readiness === "project_unverified" || args.retrieval_readiness === "project_bound_no_repo_source") {
+    return true;
+  }
+  if ((args.semantic_attempts || 0) >= 3 && args.semantic_failure_rate >= 0.5) {
+    return true;
+  }
+  return args.trust_score < 60;
+}
+function resolveAutoRepairRootCause(args) {
+  if (args.restart_required) return "mode_mismatch_remote_local_ingest";
+  if (args.trust_health === "unindexed") return "workspace_unindexed";
+  if (args.project_readiness === "project_bound_no_repo_source") return "project_bound_no_repo_source";
+  if (args.project_readiness === "project_unverified") return "project_unverified";
+  if (args.project_readiness === "project_repo_source_stale") return "project_repo_source_stale";
+  if (args.semantic_attempts >= 3 && args.semantic_failure_rate >= 0.5) return "semantic_backend_unavailable";
+  if (args.retrieval_readiness === "local_fallback") return "local_fallback_active";
+  if (args.retrieval_readiness === "no_project") return "no_project_bound";
+  return "none";
+}
 function shouldAbstainForCodebaseTrust(args) {
   if (args.retrievalProfile !== "precision_v1" || !args.codebaseIntent) return false;
   return UNTRUSTED_CODEBASE_HEALTH.has(args.preflight.trust_state.health) || UNTRUSTED_CODEBASE_PROJECT_READINESS.has(args.preflight.project_retrieval_readiness);
@@ -4250,9 +4483,9 @@ async function resolveProjectDescriptor(projectRef) {
   }
 }
 function getWorkspaceRecommendedNextCalls(health) {
-  if (health === "unbound") return sanitizeRecommendedNextCalls(["index.workspace_resolve", "context.list_projects", "index.workspace_status"]);
-  if (health === "unindexed") return sanitizeRecommendedNextCalls(["index.workspace_status", "index.workspace_run", "search_code", "grep"]);
-  if (health === "stale" || health === "drifted") return sanitizeRecommendedNextCalls(["index.workspace_status", "index.workspace_run", "grep", "search_code"]);
+  if (health === "unbound") return sanitizeRecommendedNextCalls(["index.workspace_resolve"]);
+  if (health === "unindexed") return sanitizeRecommendedNextCalls(["index.workspace_run"]);
+  if (health === "stale" || health === "drifted") return sanitizeRecommendedNextCalls(["index.workspace_run"]);
   return [];
 }
 function getWorkspaceWarnings(args) {
@@ -4448,8 +4681,8 @@ async function resolveRepoGroundingPreflight(args) {
     }
   }
   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");
+  if (sourceVerification.retrieval_readiness !== "project_repo_source_ready" && sourceVerification.retrieval_readiness !== "no_project") {
+    recommendedNextCalls.push(...getRepoReadinessNextCalls(sourceVerification.retrieval_readiness));
   }
   return {
     repo_grounded: repoGrounded,
@@ -4478,53 +4711,32 @@ async function ingestSessionWithSyncFallback(params) {
     return whisper.ingestSession(params);
   }
 }
-function defaultMcpUserId() {
+function defaultMcpUserId(params) {
   const explicit = process.env.WHISPER_USER_ID?.trim();
   if (explicit) return explicit;
-  const seed = `${process.cwd()}|${DEFAULT_PROJECT || "default"}|${API_KEY.slice(0, 12) || "anon"}`;
+  const workspacePath = params?.workspacePath || canonicalizeWorkspacePath(process.cwd());
+  const projectRef = params?.project || DEFAULT_PROJECT || "default";
+  const seed = `${workspacePath}|${projectRef}|${API_KEY.slice(0, 12) || "anon"}`;
   return `mcp-user-${createHash("sha256").update(seed).digest("hex").slice(0, 12)}`;
 }
-function resolveMcpScope(params) {
+function resolveMcpScope(params, options) {
+  const workspacePath = canonicalizeWorkspacePath(params?.path || process.env.WHISPER_WORKSPACE_PATH || process.cwd());
+  const explicitSession = params?.session_id?.trim();
   return {
     project: params?.project,
-    userId: params?.user_id?.trim() || defaultMcpUserId(),
-    sessionId: params?.session_id?.trim() || cachedMcpSessionId,
-    workspacePath: canonicalizeWorkspacePath(params?.path || process.env.WHISPER_WORKSPACE_PATH || process.cwd())
+    userId: params?.user_id?.trim() || defaultMcpUserId({
+      project: params?.project,
+      workspacePath
+    }),
+    sessionId: explicitSession || (options?.include_default_session ? cachedMcpSessionId : void 0),
+    workspacePath
   };
 }
-async function prepareAutomaticQuery(params) {
-  if (!runtimeClient) {
-    throw new Error("Whisper runtime client unavailable.");
-  }
-  const scope = resolveMcpScope(params);
-  const key = [
-    params.project || DEFAULT_PROJECT || "",
-    scope.userId,
-    scope.sessionId,
-    scope.workspacePath || process.cwd(),
-    String(params.top_k || 10)
-  ].join("|");
-  let runtime = runtimeSessions.get(key);
-  if (!runtime) {
-    runtime = runtimeClient.createAgentRuntime({
-      project: params.project,
-      userId: scope.userId,
-      sessionId: scope.sessionId,
-      workspacePath: scope.workspacePath,
-      topK: params.top_k,
-      clientName: "whisper-mcp"
-    });
-    runtimeSessions.set(key, runtime);
-  }
-  return runtime.beforeTurn({
-    userMessage: params.query
-  });
-}
 function noteAutomaticSourceActivity(params) {
   if (!runtimeClient) return;
   const sourceIds = [...new Set((params.sourceIds || []).map((value) => String(value || "").trim()).filter(Boolean))];
   if (sourceIds.length === 0) return;
-  const scope = resolveMcpScope(params);
+  const scope = resolveMcpScope(params, { include_default_session: true });
   const key = [
     params.project || DEFAULT_PROJECT || "",
     scope.userId,
@@ -4556,7 +4768,7 @@ function buildAbstain(args) {
     warnings: args.warnings || [],
     trust_state: args.trust_state,
     recommended_next_calls: sanitizeRecommendedNextCalls(
-      args.recommended_next_calls || ["index.workspace_status", "index.workspace_run", "grep", "context.get_relevant"]
+      args.recommended_next_calls || ["index.workspace_status", "index.workspace_run", "fix", "context.query"]
     ),
     diagnostics: {
       claims_evaluated: args.claims_evaluated,
@@ -4611,6 +4823,415 @@ function countCodeFiles(searchPath, maxFiles = 5e3) {
   walk(searchPath);
   return { total, skipped };
 }
+function computeWorkspaceSnapshot(searchPath, maxFiles = 250) {
+  const files = collectCodeFiles(searchPath, CODE_EXTENSIONS, maxFiles);
+  const entries = files.slice(0, maxFiles).map((filePath) => {
+    try {
+      const st = statSync(filePath);
+      return `${relative(searchPath, filePath)}:${st.mtimeMs}:${st.size}`;
+    } catch {
+      return "";
+    }
+  }).filter(Boolean);
+  const sample = entries.join("|");
+  return {
+    hash: createHash("sha256").update(sample || searchPath).digest("hex").slice(0, 24),
+    entries
+  };
+}
+function computeSnapshotChangedFiles(previousEntries, nextEntries) {
+  if (!previousEntries || previousEntries.length === 0) return nextEntries.length;
+  const previousByPath = /* @__PURE__ */ new Map();
+  for (const entry of previousEntries) {
+    const idx = entry.indexOf(":");
+    if (idx <= 0) continue;
+    previousByPath.set(entry.slice(0, idx), entry.slice(idx + 1));
+  }
+  let changed = 0;
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of nextEntries) {
+    const idx = entry.indexOf(":");
+    if (idx <= 0) continue;
+    const relPath = entry.slice(0, idx);
+    const fingerprint = entry.slice(idx + 1);
+    seen.add(relPath);
+    if (previousByPath.get(relPath) !== fingerprint) changed += 1;
+  }
+  for (const relPath of previousByPath.keys()) {
+    if (!seen.has(relPath)) changed += 1;
+  }
+  return changed;
+}
+function shouldTriggerBackgroundRefresh(args) {
+  const nowMs = args.now_ms ?? Date.now();
+  const lastAutoRefreshAt = args.last_auto_refresh_at ? new Date(args.last_auto_refresh_at).getTime() : 0;
+  const debounceMs = 10 * 60 * 1e3;
+  const dueForDebounce = !lastAutoRefreshAt || Number.isNaN(lastAutoRefreshAt) || nowMs - lastAutoRefreshAt >= debounceMs;
+  if (!dueForDebounce) {
+    return { should_refresh: false, trigger_reason: null };
+  }
+  if (args.last_indexed_commit && args.current_head && args.last_indexed_commit !== args.current_head) {
+    return { should_refresh: true, trigger_reason: "head_changed" };
+  }
+  if (args.changed_files >= 20) {
+    return { should_refresh: true, trigger_reason: "delta_files_threshold" };
+  }
+  const ratio = args.indexed_files > 0 ? args.changed_files / args.indexed_files : 0;
+  if (ratio >= 0.02) {
+    return { should_refresh: true, trigger_reason: "delta_ratio_threshold" };
+  }
+  return { should_refresh: false, trigger_reason: null };
+}
+async function runBackgroundWorkspaceRefresh(args) {
+  const state = loadState();
+  const workspace = getWorkspaceState(state, args.workspace_id);
+  if (!workspace.index_metadata) workspace.index_metadata = {};
+  const fileStats = countCodeFiles(args.root_path, args.max_files || 1500);
+  const currentHead = getGitHead(args.root_path) || null;
+  const currentSnapshot = computeWorkspaceSnapshot(args.root_path);
+  const gitPendingCount = getGitPendingCount(args.root_path);
+  const changedFiles = gitPendingCount == null ? computeSnapshotChangedFiles(workspace.index_metadata.last_snapshot_entries, currentSnapshot.entries) : gitPendingCount;
+  const lastIndexedCommit = workspace.index_metadata.last_indexed_commit || null;
+  const refreshDecision = shouldTriggerBackgroundRefresh({
+    current_head: currentHead,
+    last_indexed_commit: lastIndexedCommit,
+    changed_files: changedFiles,
+    indexed_files: parsePositiveNumber(workspace.index_metadata.indexed_files, fileStats.total || 1),
+    last_auto_refresh_at: workspace.index_metadata.last_auto_refresh_at || null
+  });
+  const forceFullRequested = args.force_full === true;
+  if (!refreshDecision.should_refresh && !forceFullRequested) {
+    return { refreshed: false, mode: null, reason: null };
+  }
+  const mode = forceFullRequested ? "full" : "incremental";
+  workspace.root_path = args.root_path;
+  workspace.index_metadata.last_indexed_at = (/* @__PURE__ */ new Date()).toISOString();
+  workspace.index_metadata.last_auto_refresh_at = (/* @__PURE__ */ new Date()).toISOString();
+  workspace.index_metadata.last_indexed_commit = currentHead || void 0;
+  workspace.index_metadata.coverage = mode === "full" ? 1 : Math.max(0, Math.min(1, fileStats.total / Math.max(1, args.max_files || 1500)));
+  workspace.index_metadata.indexed_files = fileStats.total;
+  workspace.index_metadata.last_snapshot_hash = currentSnapshot.hash;
+  workspace.index_metadata.last_snapshot_entries = currentSnapshot.entries;
+  if (mode === "full") workspace.index_metadata.last_full_refresh_at = (/* @__PURE__ */ new Date()).toISOString();
+  saveState(state);
+  return {
+    refreshed: true,
+    mode,
+    reason: refreshDecision.trigger_reason || (forceFullRequested ? "manual_full_override" : mode === "full" ? "full_refresh_due" : "manual")
+  };
+}
+function buildSourceRepairHint(args) {
+  const remote = parseGitHubRemote(getGitRemoteUrl(args.root_path) || null);
+  if (remote) {
+    const branch = getGitBranch(args.root_path) || "main";
+    return {
+      command: `context.add_source --project ${args.project_ref || "<project>"} --type github --owner ${remote.owner} --repo ${remote.repo} --branch ${branch}`,
+      message: "Attach the matching GitHub source, then rerun fix."
+    };
+  }
+  return {
+    command: `context.add_source --project ${args.project_ref || "<project>"} --type local --path "${args.root_path}"`,
+    message: "Attach the local workspace as a source, then rerun fix."
+  };
+}
+async function attemptDeterministicSourceAttach(args) {
+  const remote = parseGitHubRemote(getGitRemoteUrl(args.root_path) || null);
+  if (remote) {
+    const branch = getGitBranch(args.root_path) || "main";
+    const result = await createSourceByType({
+      project: args.project,
+      type: "github",
+      name: `auto-repair:${remote.owner}/${remote.repo}`,
+      owner: remote.owner,
+      repo: remote.repo,
+      branch,
+      auto_index: true
+    });
+    const sourceId = result?.source_id || result?.id;
+    noteAutomaticSourceActivity({
+      project: args.project,
+      sourceIds: sourceId ? [String(sourceId)] : []
+    });
+    return { attached: true, detail: `github:${remote.owner}/${remote.repo}@${branch}` };
+  }
+  if (RUNTIME_MODE !== "remote") {
+    await createSourceByType({
+      project: args.project,
+      type: "local",
+      name: "auto-repair:local-workspace",
+      path: args.root_path,
+      auto_index: true,
+      max_files: 500
+    });
+    return { attached: true, detail: "local_workspace_source_attached" };
+  }
+  return { attached: false, detail: "deterministic_source_inputs_unavailable" };
+}
+async function runAutoRepairVerification(args) {
+  if (args.preflight.retrieval_route === "project_repo" && args.preflight.matched_source_ids.length > 0) {
+    try {
+      const queryResult = await queryWithDegradedFallback({
+        project: args.project,
+        query: "how does this project work",
+        top_k: 5,
+        include_memories: false,
+        include_graph: false,
+        source_ids: args.preflight.matched_source_ids
+      });
+      const resultCount = Array.isArray(queryResult.response?.results) ? queryResult.response.results.length : 0;
+      return {
+        passed: resultCount > 0,
+        route: "project_repo",
+        result_count: resultCount,
+        detail: resultCount > 0 ? "project_query_has_results" : "project_query_empty"
+      };
+    } catch (error) {
+      return {
+        passed: false,
+        route: "project_repo",
+        result_count: 0,
+        detail: `project_query_error:${String(error?.message || error)}`
+      };
+    }
+  }
+  if (args.preflight.retrieval_route === "local_workspace_fallback") {
+    try {
+      const local = await runLocalWorkspaceRetrieval({
+        query: "how does this project work",
+        path: args.preflight.trust_state.root_path,
+        project: args.project,
+        top_k: 5
+      });
+      return {
+        passed: local.results.length > 0,
+        route: "local_workspace_fallback",
+        result_count: local.results.length,
+        detail: local.results.length > 0 ? "local_query_has_results" : "local_query_empty"
+      };
+    } catch (error) {
+      return {
+        passed: false,
+        route: "local_workspace_fallback",
+        result_count: 0,
+        detail: `local_query_error:${String(error?.message || error)}`
+      };
+    }
+  }
+  return {
+    passed: false,
+    route: args.preflight.retrieval_route,
+    result_count: 0,
+    detail: "no_verifiable_retrieval_route"
+  };
+}
+async function runAutoRepairFlow(input) {
+  const actions_attempted = [];
+  const actions_succeeded = [];
+  const actions_failed = [];
+  const apply = input.apply !== false;
+  const repairScope = input.repair_scope || "safe";
+  const allowRestartHint = input.allow_restart_hint !== false;
+  let restartRequired = false;
+  if (!API_KEY) {
+    return {
+      root_cause_code: "missing_api_key",
+      actions_attempted,
+      actions_succeeded,
+      actions_failed: [...actions_failed, "validate_credentials:missing_api_key"],
+      restart_required: false,
+      verification_passed: false,
+      status_label: "blocked",
+      status_action: "reauth",
+      action_required: true,
+      diagnostics: {
+        message: "WHISPER_API_KEY is required."
+      }
+    };
+  }
+  actions_attempted.push("validate_credentials");
+  actions_succeeded.push("validate_credentials");
+  actions_attempted.push("resolve_project");
+  const resolvedProject = await resolveProjectRef(input.project);
+  if (!resolvedProject) {
+    actions_failed.push("resolve_project:no_project");
+    return {
+      root_cause_code: "no_project_bound",
+      actions_attempted,
+      actions_succeeded,
+      actions_failed,
+      restart_required: false,
+      verification_passed: false,
+      status_label: "needs_user_action",
+      status_action: "add_source",
+      action_required: true,
+      diagnostics: {
+        message: "No project resolved. Set WHISPER_PROJECT or pass project."
+      }
+    };
+  }
+  actions_succeeded.push("resolve_project");
+  actions_attempted.push("resolve_workspace_trust");
+  const beforePreflight = await resolveRepoGroundingPreflight({
+    query: "how does this project work",
+    path: input.path,
+    workspace_id: input.workspace_id,
+    project: resolvedProject
+  });
+  actions_succeeded.push("resolve_workspace_trust");
+  actions_attempted.push("runtime_mode_check");
+  if (allowRestartHint && RUNTIME_MODE === "remote" && (beforePreflight.project_retrieval_readiness === "project_bound_no_repo_source" || beforePreflight.retrieval_readiness === "local_fallback")) {
+    actions_failed.push("runtime_mode_check:remote_mode_blocks_local_repair");
+    restartRequired = true;
+  } else {
+    actions_succeeded.push("runtime_mode_check");
+  }
+  actions_attempted.push("refresh_workspace_index_metadata");
+  let refreshResult = null;
+  try {
+    if (apply) {
+      refreshResult = await runBackgroundWorkspaceRefresh({
+        workspace_id: beforePreflight.trust_state.workspace_id,
+        root_path: beforePreflight.trust_state.root_path,
+        force_full: repairScope === "full"
+      });
+    } else {
+      refreshResult = { refreshed: false, mode: null, reason: "dry_run" };
+    }
+    actions_succeeded.push("refresh_workspace_index_metadata");
+  } catch (error) {
+    actions_failed.push(`refresh_workspace_index_metadata:${String(error?.message || error)}`);
+  }
+  actions_attempted.push("repair_source_readiness");
+  let sourceRepair = {
+    applied: false,
+    attached: false,
+    detail: "not_required",
+    hint: null
+  };
+  if (beforePreflight.project_retrieval_readiness === "project_bound_no_repo_source") {
+    const hint = buildSourceRepairHint({
+      root_path: beforePreflight.trust_state.root_path,
+      project_ref: beforePreflight.trust_state.project_ref
+    });
+    sourceRepair = {
+      applied: apply && repairScope === "full",
+      attached: false,
+      detail: "manual_source_attach_required",
+      hint
+    };
+    if (apply && repairScope === "full") {
+      try {
+        const attach = await attemptDeterministicSourceAttach({
+          project: resolvedProject,
+          root_path: beforePreflight.trust_state.root_path
+        });
+        sourceRepair = {
+          applied: true,
+          attached: attach.attached,
+          detail: attach.detail,
+          hint
+        };
+        if (attach.attached) {
+          actions_succeeded.push("repair_source_readiness");
+        } else {
+          actions_failed.push(`repair_source_readiness:${attach.detail}`);
+        }
+      } catch (error) {
+        actions_failed.push(`repair_source_readiness:${String(error?.message || error)}`);
+      }
+    } else {
+      actions_failed.push("repair_source_readiness:manual_source_attach_required");
+    }
+  } else {
+    actions_succeeded.push("repair_source_readiness");
+  }
+  const afterPreflight = await resolveRepoGroundingPreflight({
+    query: "how does this project work",
+    path: beforePreflight.trust_state.root_path,
+    workspace_id: beforePreflight.trust_state.workspace_id,
+    project: resolvedProject
+  });
+  const semanticStats = getWorkspaceSemanticFailureStats(afterPreflight.trust_state.workspace_id);
+  const trustScore = computeTrustScore({
+    retrieval_readiness: afterPreflight.retrieval_readiness,
+    workspace_health: afterPreflight.trust_state.health,
+    semantic_failure_rate: semanticStats.rate
+  });
+  persistTrustScore(afterPreflight.trust_state.workspace_id, trustScore);
+  const autoHeal = shouldAutoHeal({
+    retrieval_readiness: afterPreflight.retrieval_readiness,
+    trust_score: trustScore,
+    semantic_failure_rate: semanticStats.rate,
+    semantic_attempts: semanticStats.attempts
+  });
+  actions_attempted.push("verification_query");
+  const verification = await runAutoRepairVerification({
+    project: resolvedProject,
+    preflight: afterPreflight
+  });
+  if (verification.passed) actions_succeeded.push("verification_query");
+  else actions_failed.push(`verification_query:${verification.detail}`);
+  const rootCause = resolveAutoRepairRootCause({
+    restart_required: restartRequired,
+    trust_health: beforePreflight.trust_state.health,
+    project_readiness: beforePreflight.project_retrieval_readiness,
+    retrieval_readiness: beforePreflight.retrieval_readiness,
+    semantic_failure_rate: semanticStats.rate,
+    semantic_attempts: semanticStats.attempts
+  });
+  const statusContract = statusContractForReadiness({
+    retrieval_readiness: afterPreflight.retrieval_readiness,
+    workspace_health: afterPreflight.trust_state.health,
+    root_cause_code: rootCause,
+    force_repairing: autoHeal && rootCause === "none"
+  });
+  const verificationPassed = verification.passed;
+  const effectiveStatusAction = statusContract.status_action;
+  const effectiveActionRequired = statusContract.action_required;
+  const transitionImproved = isStrictlyBetterReadiness(
+    beforePreflight.retrieval_readiness,
+    afterPreflight.retrieval_readiness
+  );
+  const explicitBlocker = effectiveActionRequired;
+  const recommendedNextCalls = sanitizeRecommendedNextCalls([
+    ...recommendedNextCallsForRootCause(rootCause),
+    ...afterPreflight.recommended_next_calls
+  ]);
+  return {
+    root_cause_code: rootCause,
+    actions_attempted,
+    actions_succeeded,
+    actions_failed,
+    restart_required: restartRequired,
+    verification_passed: verificationPassed,
+    status_label: statusContract.status_label,
+    status_action: effectiveStatusAction,
+    action_required: effectiveActionRequired,
+    recommended_next_calls: recommendedNextCalls,
+    diagnostics: {
+      runtime_mode: RUNTIME_MODE,
+      workspace_id: afterPreflight.trust_state.workspace_id,
+      root_path: afterPreflight.trust_state.root_path,
+      project_ref: afterPreflight.trust_state.project_ref,
+      retrieval_readiness_before: beforePreflight.retrieval_readiness,
+      retrieval_readiness_after: afterPreflight.retrieval_readiness,
+      project_retrieval_readiness_after: afterPreflight.project_retrieval_readiness,
+      retrieval_readiness_label: retrievalReadinessLabel(afterPreflight.retrieval_readiness),
+      retrieval_readiness_action: retrievalReadinessAction(afterPreflight.retrieval_readiness),
+      trust_score: trustScore,
+      semantic_failure_rate: semanticStats.rate,
+      semantic_attempts: semanticStats.attempts,
+      refresh: refreshResult,
+      source_repair: sourceRepair,
+      verification,
+      auto_heal_triggered: autoHeal,
+      transition_improved: transitionImproved,
+      explicit_blocker: explicitBlocker,
+      recommended_next_calls: recommendedNextCalls,
+      restart_hint: restartRequired ? "Set WHISPER_MCP_MODE=auto in MCP config and restart client." : null
+    }
+  };
+}
 function toTextResult(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
@@ -4677,42 +5298,6 @@ function resolveForgetQueryCandidates(rawResults, query) {
   }
   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");
@@ -4733,7 +5318,13 @@ async function queryWithDegradedFallback(params) {
       hybrid: true,
       rerank: true
     });
-    return { response, degraded_mode: false };
+    return {
+      response,
+      degraded_mode: false,
+      semantic_status: "ok",
+      fallback_mode: "none",
+      recommended_fixes: []
+    };
   } catch (error) {
     if (!likelyEmbeddingFailure(error)) throw error;
     const response = await whisper.query({
@@ -4756,7 +5347,13 @@ async function queryWithDegradedFallback(params) {
       response,
       degraded_mode: true,
       degraded_reason: "Embedding/graph path unavailable; lexical fallback used.",
-      recommendation: "Check embedding service health, then re-run for full hybrid quality."
+      recommendation: "Check embedding service health, then re-run for full hybrid quality.",
+      semantic_status: "failed",
+      fallback_mode: "lexical_backend",
+      recommended_fixes: [
+        "Run fix to auto-repair retrieval health.",
+        "If this persists, re-authenticate and reindex workspace sources."
+      ]
     };
   }
 }
@@ -4868,6 +5465,47 @@ 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."
   };
 }
+function retrievalReadinessLabel(readiness) {
+  if (readiness === "project_repo_source_ready") return "Project retrieval is healthy.";
+  if (readiness === "project_repo_source_stale") return "Project source exists but is not ready.";
+  if (readiness === "project_bound_no_repo_source") return "No matching project source is connected.";
+  if (readiness === "project_unverified") return "Project/source verification failed.";
+  if (readiness === "local_fallback") return "Using local fallback retrieval.";
+  if (readiness === "no_project") return "No project is bound to this workspace.";
+  return "Retrieval readiness is unknown.";
+}
+function retrievalReadinessAction(readiness) {
+  if (readiness === "project_repo_source_ready") return "none";
+  if (readiness === "project_repo_source_stale") return "Run fix or index.workspace_run to refresh workspace trust.";
+  if (readiness === "project_bound_no_repo_source") {
+    return RUNTIME_MODE === "remote" ? "Connect a repo source with context.add_source, then run fix." : "Run index.local_scan_ingest or fix.";
+  }
+  if (readiness === "project_unverified") return "Re-authenticate your API key and run fix.";
+  if (readiness === "local_fallback") return "Run fix to restore project-grounded retrieval.";
+  if (readiness === "no_project") return "Provide --project/WHISPER_PROJECT and run fix.";
+  return "Run fix.";
+}
+function buildRecommendedFixes(args) {
+  const fixes = /* @__PURE__ */ new Set();
+  if (args.semantic_status === "failed") {
+    fixes.add("Run fix to auto-repair retrieval health.");
+  }
+  if (args.fallback_mode === "lexical_rescue" || args.fallback_mode === "lexical_backend") {
+    fixes.add("Check embedding/vector service health and retry.");
+  }
+  if (args.retrieval_readiness === "project_bound_no_repo_source") {
+    fixes.add(
+      RUNTIME_MODE === "remote" ? "Add a matching source with context.add_source." : "Ingest local files with index.local_scan_ingest."
+    );
+  }
+  if (args.retrieval_readiness === "project_unverified") {
+    fixes.add("Re-authenticate (valid WHISPER_API_KEY) and rerun fix.");
+  }
+  if (args.retrieval_readiness === "project_repo_source_stale") {
+    fixes.add("Refresh workspace metadata via index.workspace_run.");
+  }
+  return [...fixes];
+}
 function buildLocalWorkspaceDocuments(rootPath, allowedExts, maxFiles) {
   const files = collectCodeFiles(rootPath, allowedExts, maxFiles);
   const documents = [];
@@ -5003,20 +5641,6 @@ function localHitsToEvidence(workspaceId, hits) {
     )
   );
 }
-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;
@@ -5024,12 +5648,21 @@ async function runSearchCodeTool(args) {
   if (files.length === 0) {
     const workspace = await resolveWorkspaceTrust({ path: rootPath });
     const sharedWarnings = [...workspace.warnings];
+    const semanticStatus = "ok";
+    const fallbackMode = "none";
     return {
       tool: "search_code",
       query: args.query,
       path: rootPath,
       results: [],
       count: 0,
+      semantic_status: semanticStatus,
+      fallback_mode: fallbackMode,
+      recommended_fixes: buildRecommendedFixes({
+        retrieval_readiness: workspace.project_ref ? "project_repo_source_ready" : "no_project",
+        semantic_status: semanticStatus,
+        fallback_mode: fallbackMode
+      }),
       warnings: sharedWarnings,
       diagnostics: {
         workspace_id: workspace.workspace_id,
@@ -5058,6 +5691,13 @@ async function runSearchCodeTool(args) {
     path: rootPath,
     results: localRetrieval.results,
     count: localRetrieval.results.length,
+    semantic_status: semanticStatusFromSearchMode(localRetrieval.diagnostics.search_mode),
+    fallback_mode: fallbackModeFromSearchMode(localRetrieval.diagnostics.search_mode),
+    recommended_fixes: buildRecommendedFixes({
+      retrieval_readiness: localRetrieval.workspace.project_ref ? "local_fallback" : "no_project",
+      semantic_status: semanticStatusFromSearchMode(localRetrieval.diagnostics.search_mode),
+      fallback_mode: fallbackModeFromSearchMode(localRetrieval.diagnostics.search_mode)
+    }),
     warnings: localRetrieval.warnings,
     diagnostics: localRetrieval.diagnostics
   };
@@ -5109,7 +5749,9 @@ function saveIngestManifest(manifest) {
 }
 async function ingestLocalPath(params) {
   if (RUNTIME_MODE === "remote") {
-    throw new Error("Local ingestion is disabled in remote mode. Set WHISPER_MCP_MODE=auto or local.");
+    throw new Error(
+      "Local ingestion is disabled in remote mode. Use context.add_source for remote projects, or run MCP with WHISPER_MCP_MODE=auto/local."
+    );
   }
   const rootPath = params.path || process.cwd();
   const gate = isPathAllowed(rootPath);
@@ -5309,7 +5951,8 @@ function renderScopedMcpConfig(project, source, client) {
     env: {
       WHISPER_API_KEY: "wctx_...",
       WHISPER_PROJECT: project,
-      WHISPER_SCOPE_SOURCE: source
+      WHISPER_SCOPE_SOURCE: source,
+      WHISPER_MCP_MODE: "auto"
     }
   };
   if (client === "json") {
@@ -5389,7 +6032,7 @@ server.tool(
         warnings: Array.from(/* @__PURE__ */ new Set([...trust.warnings, ...repoVerification.warnings])),
         recommended_next_calls: sanitizeRecommendedNextCalls([
           ...trust.recommended_next_calls,
-          ...repoVerification.retrieval_readiness === "project_bound_no_repo_source" ? ["context.list_sources", "index.local_scan_ingest"] : []
+          ...getRepoReadinessNextCalls(repoVerification.retrieval_readiness)
         ]),
         freshness: trust.freshness,
         coverage: trust.coverage,
@@ -5406,7 +6049,7 @@ server.tool(
 );
 server.tool(
   "index.workspace_run",
-  "Index workspace in full or incremental mode and update index metadata for freshness checks.",
+  "Refresh local workspace index metadata (coverage, commit, freshness) for trust checks. This does not upload files or create backend embeddings.",
   {
     workspace_id: z.string().optional(),
     path: z.string().optional(),
@@ -5415,6 +6058,7 @@ server.tool(
   },
   async ({ workspace_id, path, mode, max_files }) => {
     try {
+      const startAt = Date.now();
       const identity = resolveWorkspaceIdentity({ path, workspace_id });
       const rootPath = identity.root_path;
       const workspaceId = identity.workspace_id;
@@ -5423,11 +6067,17 @@ server.tool(
       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();
+      const snapshot = computeWorkspaceSnapshot(rootPath);
       workspace.root_path = rootPath;
       workspace.index_metadata = {
         last_indexed_at: now,
         last_indexed_commit: getGitHead(rootPath),
-        coverage: mode === "full" ? 1 : coverage
+        coverage: mode === "full" ? 1 : coverage,
+        indexed_files: fileStats.total,
+        last_auto_refresh_at: now,
+        ...mode === "full" ? { last_full_refresh_at: now } : {},
+        last_snapshot_hash: snapshot.hash,
+        last_snapshot_entries: snapshot.entries
       };
       saveState(state);
       const payload = {
@@ -5436,7 +6086,7 @@ server.tool(
         mode,
         indexed_files: fileStats.total,
         skipped_files: fileStats.skipped,
-        duration_ms: 0,
+        duration_ms: Date.now() - startAt,
         warnings: fileStats.total === 0 ? ["No code files discovered for indexing."] : [],
         index_metadata: workspace.index_metadata
       };
@@ -5448,7 +6098,7 @@ server.tool(
 );
 server.tool(
   "index.local_scan_ingest",
-  "Scan a local folder safely (allowlist + secret filters), ingest changed files, and persist incremental manifest.",
+  "Ingest local files into Whisper backend (chunk/embed/index) and persist incremental manifest. Requires WHISPER_MCP_MODE=auto or local.",
   {
     project: z.string().optional().describe("Project name or slug"),
     path: z.string().optional().describe("Local path to ingest. Defaults to current working directory."),
@@ -5482,9 +6132,264 @@ server.tool(
     }
   }
 );
+server.tool(
+  "index.auto_repair",
+  "Diagnose and apply deterministic retrieval/setup repairs. This is the canonical zero-stress repair path.",
+  {
+    path: z.string().optional(),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    apply: z.boolean().optional().default(true),
+    repair_scope: z.enum(["safe", "full"]).optional().default("safe"),
+    allow_restart_hint: z.boolean().optional().default(true)
+  },
+  async ({ path, workspace_id, project, apply, repair_scope, allow_restart_hint }) => {
+    try {
+      const payload = await runAutoRepairFlow({
+        path,
+        workspace_id,
+        project,
+        apply,
+        repair_scope,
+        allow_restart_hint
+      });
+      return toTextResult(payload);
+    } catch (error) {
+      return primaryToolError(error.message, "auto_repair_failed");
+    }
+  }
+);
+server.tool(
+  "fix",
+  "Primary alias for zero-stress setup/retrieval repair. Delegates to index.auto_repair.",
+  {
+    path: z.string().optional(),
+    workspace_id: z.string().optional(),
+    project: z.string().optional(),
+    apply: z.boolean().optional().default(true),
+    repair_scope: z.enum(["safe", "full"]).optional().default("safe"),
+    allow_restart_hint: z.boolean().optional().default(true)
+  },
+  async ({ path, workspace_id, project, apply, repair_scope, allow_restart_hint }) => {
+    try {
+      const payload = await runAutoRepairFlow({
+        path,
+        workspace_id,
+        project,
+        apply,
+        repair_scope,
+        allow_restart_hint
+      });
+      return toTextResult(payload);
+    } catch (error) {
+      return primaryToolError(error.message, "fix_failed");
+    }
+  }
+);
+async function runUnifiedContextRetrieval(params) {
+  const preflight = await resolveRepoGroundingPreflight({
+    query: params.question,
+    path: params.path,
+    workspace_id: params.workspace_id,
+    project: params.project,
+    chunk_types: params.chunk_types
+  });
+  const retrievalProfile = resolveMcpRetrievalProfile(params.retrieval_profile);
+  const backgroundRefresh = await runBackgroundWorkspaceRefresh({
+    workspace_id: preflight.trust_state.workspace_id,
+    root_path: preflight.trust_state.root_path,
+    force_full: false
+  });
+  if (shouldAbstainForCodebaseTrust({
+    retrievalProfile,
+    codebaseIntent: preflight.repo_grounded,
+    preflight
+  })) {
+    const abstainPayload = buildCodebaseTrustAbstainPayload({
+      query: params.question,
+      preflight,
+      retrievalProfile
+    });
+    return {
+      ...abstainPayload,
+      semantic_status: "failed",
+      fallback_mode: "none",
+      recommended_fixes: buildRecommendedFixes({
+        retrieval_readiness: preflight.retrieval_readiness,
+        semantic_status: "failed",
+        fallback_mode: "none"
+      }),
+      status_label: "blocked",
+      status_action: "reindex",
+      action_required: true,
+      diagnostics: {
+        retrieval_profile: retrievalProfile,
+        background_refresh: backgroundRefresh
+      }
+    };
+  }
+  const resolvedProject = preflight.trust_state.project_ref || await resolveProjectRef(params.project);
+  const scope = resolveMcpScope({
+    project: resolvedProject || params.project,
+    user_id: params.user_id,
+    session_id: params.session_id,
+    path: preflight.trust_state.root_path
+  });
+  const topK = params.top_k ?? 12;
+  let semanticStatus = "ok";
+  let fallbackMode = "none";
+  let contextText = "";
+  let evidence = [];
+  let warnings = [...preflight.warnings];
+  let retrievalReadiness = preflight.retrieval_readiness;
+  let retrievalRoute = preflight.retrieval_route;
+  let latencyMs = 0;
+  if (preflight.retrieval_route === "local_workspace_fallback") {
+    const localRetrieval = await runLocalWorkspaceRetrieval({
+      query: params.question,
+      path: preflight.trust_state.root_path,
+      project: resolvedProject || params.project,
+      top_k: topK
+    });
+    semanticStatus = semanticStatusFromSearchMode(localRetrieval.diagnostics.search_mode);
+    fallbackMode = fallbackModeFromSearchMode(localRetrieval.diagnostics.search_mode);
+    evidence = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results);
+    contextText = evidence.map((item) => `[${renderCitation(item)}] ${item.snippet || "Relevant context found."}`).join("\n");
+    warnings = Array.from(/* @__PURE__ */ new Set([...warnings, ...localRetrieval.warnings]));
+    retrievalReadiness = "local_fallback";
+    retrievalRoute = "local_workspace_fallback";
+  } else if (!resolvedProject) {
+    contextText = "";
+    evidence = [];
+    retrievalRoute = "none";
+  } else {
+    const queryResult = await queryWithDegradedFallback({
+      project: resolvedProject,
+      query: params.question,
+      top_k: topK,
+      include_memories: preflight.repo_grounded ? false : params.include_memories,
+      include_graph: params.include_graph,
+      session_id: params.session_id,
+      user_id: scope.userId,
+      source_ids: preflight.repo_grounded ? preflight.matched_source_ids : void 0,
+      retrieval_profile: retrievalProfile,
+      include_parent_content: params.include_parent_content
+    });
+    latencyMs = queryResult.response.meta?.latency_ms || 0;
+    semanticStatus = queryResult.semantic_status || "ok";
+    fallbackMode = queryResult.fallback_mode || "none";
+    const rawResults = preflight.repo_grounded ? filterProjectRepoResults(queryResult.response.results || [], preflight.matched_source_ids) : queryResult.response.results || [];
+    if (preflight.repo_grounded && rawResults.length === 0) {
+      const localRetrieval = await runLocalWorkspaceRetrieval({
+        query: params.question,
+        path: preflight.trust_state.root_path,
+        project: resolvedProject,
+        top_k: topK
+      });
+      semanticStatus = semanticStatusFromSearchMode(localRetrieval.diagnostics.search_mode);
+      fallbackMode = fallbackModeFromSearchMode(localRetrieval.diagnostics.search_mode);
+      evidence = localHitsToEvidence(preflight.trust_state.workspace_id, localRetrieval.results);
+      contextText = evidence.map((item) => `[${renderCitation(item)}] ${item.snippet || "Relevant context found."}`).join("\n");
+      warnings = Array.from(/* @__PURE__ */ new Set([...warnings, ...localRetrieval.warnings]));
+      retrievalReadiness = "local_fallback";
+      retrievalRoute = "local_workspace_fallback";
+    } else {
+      contextText = queryResult.response.context || "";
+      evidence = rawResults.map((r) => toEvidenceRef(r, preflight.trust_state.workspace_id, "semantic"));
+      if (queryResult.degraded_mode) {
+        warnings.push(queryResult.degraded_reason || "Lexical backend fallback active.");
+      }
+      retrievalRoute = preflight.repo_grounded ? "project_repo" : "none";
+    }
+  }
+  recordSemanticAttempt(preflight.trust_state.workspace_id, semanticStatus === "failed");
+  const semanticStats = getWorkspaceSemanticFailureStats(preflight.trust_state.workspace_id);
+  const trustScore = computeTrustScore({
+    retrieval_readiness: retrievalReadiness,
+    workspace_health: preflight.trust_state.health,
+    semantic_failure_rate: semanticStats.rate
+  });
+  persistTrustScore(preflight.trust_state.workspace_id, trustScore);
+  const autoHeal = shouldAutoHeal({
+    retrieval_readiness: retrievalReadiness,
+    trust_score: trustScore,
+    semantic_failure_rate: semanticStats.rate,
+    semantic_attempts: semanticStats.attempts
+  });
+  let autoRepairSummary = null;
+  if (autoHeal) {
+    try {
+      autoRepairSummary = await runAutoRepairFlow({
+        path: preflight.trust_state.root_path,
+        workspace_id: preflight.trust_state.workspace_id,
+        project: resolvedProject || params.project,
+        apply: true,
+        repair_scope: "safe",
+        allow_restart_hint: true
+      });
+      warnings.push("Auto-repair executed in safe mode.");
+    } catch (error) {
+      warnings.push(`Auto-repair failed: ${String(error?.message || error)}`);
+    }
+  }
+  const statusContract = statusContractForReadiness({
+    retrieval_readiness: retrievalReadiness,
+    workspace_health: preflight.trust_state.health,
+    semantic_status: semanticStatus,
+    force_repairing: autoHeal
+  });
+  const recommendedFixes = buildRecommendedFixes({
+    retrieval_readiness: retrievalReadiness,
+    semantic_status: semanticStatus,
+    fallback_mode: fallbackMode
+  });
+  const recommendedNextCalls = sanitizeRecommendedNextCalls([
+    ...preflight.recommended_next_calls,
+    ...semanticStatus === "failed" ? ["fix"] : []
+  ]);
+  const payload = {
+    question: params.question,
+    workspace_id: preflight.trust_state.workspace_id,
+    root_path: preflight.trust_state.root_path,
+    trust_state: preflight.trust_state,
+    retrieval_readiness: retrievalReadiness,
+    retrieval_readiness_label: retrievalReadinessLabel(retrievalReadiness),
+    retrieval_readiness_action: retrievalReadinessAction(retrievalReadiness),
+    retrieval_route: retrievalRoute,
+    context: contextText,
+    evidence,
+    total_results: evidence.length,
+    latency_ms: latencyMs,
+    semantic_status: semanticStatus,
+    fallback_mode: fallbackMode,
+    recommended_fixes: recommendedFixes,
+    status_label: statusContract.status_label,
+    status_action: statusContract.status_action,
+    action_required: statusContract.action_required,
+    warnings: Array.from(new Set(warnings)),
+    recommended_next_calls: recommendedNextCalls,
+    diagnostics: {
+      scope: {
+        project: resolvedProject || params.project || null,
+        user_id: scope.userId,
+        session_id: params.session_id || null
+      },
+      retrieval_profile: retrievalProfile,
+      trust_score: trustScore,
+      semantic_failure_rate: semanticStats.rate,
+      auto_heal_triggered: autoHeal,
+      auto_repair: autoRepairSummary,
+      background_refresh: backgroundRefresh
+    }
+  };
+  if (params.include_alias_warning) {
+    payload.warnings = Array.from(/* @__PURE__ */ new Set([...payload.warnings, "deprecated_alias_use_context.query"]));
+  }
+  return payload;
+}
 server.tool(
   "context.get_relevant",
-  "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.",
+  "Default grounded retrieval step for workspace/project questions. Returns ranked evidence with file:line citations and may abstain when workspace/repo trust is not ready.",
   {
     question: z.string().describe("Task/question to retrieve context for"),
     path: z.string().optional().describe("Workspace path. Defaults to current working directory."),
@@ -5500,131 +6405,23 @@ server.tool(
   },
   async ({ question, path, workspace_id, project, top_k, include_memories, include_graph, session_id, user_id, include_parent_content, retrieval_profile }) => {
     try {
-      const preflight = await resolveRepoGroundingPreflight({ query: question, path, workspace_id, project });
-      const retrievalProfile = resolveMcpRetrievalProfile(retrieval_profile);
-      if (shouldAbstainForCodebaseTrust({
-        retrievalProfile,
-        codebaseIntent: preflight.repo_grounded,
-        preflight
-      })) {
-        return toTextResult(buildCodebaseTrustAbstainPayload({
-          query: question,
-          preflight,
-          retrievalProfile
-        }));
-      }
-      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: 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: preflight.warnings,
-          recommended_next_calls: preflight.recommended_next_calls
-        };
-        return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }] };
-      }
-      const queryResult = await queryWithDegradedFallback({
-        project: preflight.trust_state.project_ref,
-        query: question,
+      const payload = await runUnifiedContextRetrieval({
+        question,
+        path,
+        workspace_id,
+        project,
         top_k,
-        include_memories: preflight.repo_grounded ? false : include_memories,
+        include_memories,
         include_graph,
         session_id,
         user_id,
-        source_ids: preflight.repo_grounded ? preflight.matched_source_ids : void 0,
-        retrieval_profile: retrievalProfile,
-        include_parent_content
+        include_parent_content,
+        retrieval_profile,
+        include_alias_warning: true
       });
-      const response = queryResult.response;
-      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: 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: 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: preflight.warnings,
-        recommended_next_calls: preflight.recommended_next_calls
-      };
-      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+      return toTextResult(payload);
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message, "context_get_relevant_failed");
     }
   }
 );
@@ -5831,7 +6628,7 @@ server.tool(
 );
 server.tool(
   "context.query",
-  "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.",
+  "Use this when answering from project knowledge rather than general model memory. Retrieves packed context and auto-falls back between repo, local, and memory routes based on trust/readiness.",
   {
     project: z.string().optional().describe("Project name or slug (optional if WHISPER_PROJECT is set)"),
     query: z.string().describe("What are you looking for?"),
@@ -5848,273 +6645,22 @@ server.tool(
   },
   async ({ project, query, path, top_k, chunk_types, include_memories, include_graph, user_id, session_id, max_tokens, include_parent_content, retrieval_profile }) => {
     try {
-      const preflight = await resolveRepoGroundingPreflight({ query, path, project, chunk_types });
-      const retrievalProfile = resolveMcpRetrievalProfile(retrieval_profile);
-      if (shouldAbstainForCodebaseTrust({
-        retrievalProfile,
-        codebaseIntent: preflight.repo_grounded,
-        preflight
-      })) {
-        return toTextResult(buildCodebaseTrustAbstainPayload({
-          query,
-          preflight,
-          retrievalProfile
-        }));
-      }
-      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, 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,
-          retrieval_profile: retrievalProfile,
-          include_parent_content
-        });
-        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({
-            project: resolvedProject,
-            query,
-            top_k,
-            user_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 ? 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 warnings = prepared.retrieval.warnings.length ? `
-
-[automatic_runtime]
-${prepared.retrieval.warnings.join("\n")}` : "";
-          const diagnostics = [
-            `focused_scope=${prepared.retrieval.focusedScopeApplied}`,
-            `fallback_used=${prepared.retrieval.fallbackUsed}`,
-            `deduped=${prepared.retrieval.dedupedCount}`,
-            `dropped_below_floor=${prepared.retrieval.droppedBelowFloor}`
-          ].join(" ");
-          const scopeLabel = `project=${prepared.scope.project} user=${prepared.scope.userId} session=${prepared.scope.sessionId}`;
-          return {
-            content: [{
-              type: "text",
-              text: `Found ${prepared.items.length} runtime-ranked items (${prepared.retrieval.durationMs}ms, ${scopeLabel}, ${diagnostics}):
-
-${prepared.context}${warnings}`
-            }]
-          };
-        } catch (error) {
-          const automaticWarning = `Automatic runtime unavailable: ${error.message}. Falling back to broad/manual query path.`;
-          const queryResult2 = await queryWithDegradedFallback({
-            project: resolvedProject,
-            query,
-            top_k,
-            include_memories: include_memories === true,
-            include_graph,
-            user_id: user_id || scope.userId,
-            session_id: session_id || scope.sessionId,
-            retrieval_profile: retrievalProfile,
-            include_parent_content
-          });
-          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 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 ? `
-
-[degraded_mode=true] ${queryResult2.degraded_reason}
-Recommendation: ${queryResult2.recommendation}` : "";
-          return { content: [{ type: "text", text: `${header2}${response2.context}
-
-[automatic_runtime]
-${automaticWarning}${suffix2}` }] };
-        }
-      }
-      const queryResult = await queryWithDegradedFallback({
-        project: resolvedProject,
-        query,
+      const payload = await runUnifiedContextRetrieval({
+        question: query,
+        path,
+        project,
         top_k,
-        include_memories: include_memories === true,
+        include_memories,
         include_graph,
-        user_id: user_id || scope.userId,
-        session_id: session_id || scope.sessionId,
-        retrieval_profile: retrievalProfile,
-        include_parent_content
+        user_id,
+        session_id,
+        include_parent_content,
+        retrieval_profile,
+        chunk_types
       });
-      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 header = `Found ${response.meta.total} results (${response.meta.latency_ms}ms${response.meta.cache_hit ? ", cached" : ""}, project=${resolvedProject}, user=${scope.userId}, session=${scope.sessionId}):
-
-`;
-      const suffix = queryResult.degraded_mode ? `
-
-[degraded_mode=true] ${queryResult.degraded_reason}
-Recommendation: ${queryResult.recommendation}` : "";
-      return { content: [{ type: "text", text: header + response.context + suffix }] };
+      return toTextResult(payload);
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message, "context_query_failed");
     }
   }
 );
@@ -6146,11 +6692,24 @@ server.tool(
       const jobId = result?.job_id;
       const mode = result?.mode;
       const semanticStatus = result?.semantic_status;
-      const typeLabel = memory_type || "factual";
-      const text = mode === "async" || jobId ? `Memory queued (job_id: ${jobId || result.id}, type: ${typeLabel}, user=${scope.userId}, session=${scope.sessionId}).` : `Memory stored (id: ${memoryId}, type: ${typeLabel}, user=${scope.userId}, session=${scope.sessionId}${semanticStatus ? `, semantic_status: ${semanticStatus}` : ""}).`;
-      return { content: [{ type: "text", text }] };
+      return primaryToolSuccess({
+        tool: "memory.add",
+        memory_id: memoryId || null,
+        job_id: jobId || null,
+        mode: mode || null,
+        semantic_status: semanticStatus || null,
+        memory_type: memory_type || "factual",
+        queued: mode === "async" || Boolean(jobId),
+        diagnostics: {
+          scope: {
+            project: scope.project || null,
+            user_id: scope.userId,
+            session_id: scope.sessionId || null
+          }
+        }
+      });
     } catch (error) {
-      return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      return primaryToolError(error.message);
     }
   }
 );
@@ -6192,7 +6751,14 @@ server.tool(
         user_id: scope.userId,
         session_id: scope.sessionId,
         results: normalizedResults,
-        count: normalizedResults.length
+        count: normalizedResults.length,
+        diagnostics: {
+          scope: {
+            project: scope.project || null,
+            user_id: scope.userId,
+            session_id: scope.sessionId || null
+          }
+        }
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -6456,11 +7022,12 @@ server.tool(
   },
   async ({ project, query, user_id, session_id, question_date, memory_types, top_k, include_relations }) => {
     try {
+      const scope = resolveMcpScope({ project, user_id, session_id });
       const results = await whisper.searchMemoriesSOTA({
-        project,
+        project: scope.project,
         query,
-        user_id,
-        session_id,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
         question_date,
         memory_types,
         top_k,
@@ -6470,10 +7037,19 @@ server.tool(
       return primaryToolSuccess({
         tool: "memory.search_sota",
         query,
+        user_id: scope.userId,
+        session_id: scope.sessionId || null,
         question_date: question_date || null,
         include_relations,
         results: normalizedResults,
-        count: normalizedResults.length
+        count: normalizedResults.length,
+        diagnostics: {
+          scope: {
+            project: scope.project || null,
+            user_id: scope.userId,
+            session_id: scope.sessionId || null
+          }
+        }
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -7509,7 +8085,10 @@ server.tool(
         context: response.context,
         results: response.results,
         degradedMode: queryResult.degraded_mode,
-        degradedReason: queryResult.degraded_reason
+        degradedReason: queryResult.degraded_reason,
+        semanticStatus: queryResult.semantic_status,
+        fallbackMode: queryResult.fallback_mode,
+        recommendedFixes: queryResult.recommended_fixes || []
       }));
     } catch (error) {
       return primaryToolError(error.message);
@@ -7773,7 +8352,16 @@ server.tool(
   },
   async ({ project, content, memory_type, user_id, session_id, agent_id, importance }) => {
     try {
-      const result = await whisper.addMemory({ project, content, memory_type, user_id, session_id, agent_id, importance });
+      const scope = resolveMcpScope({ project, user_id, session_id });
+      const result = await whisper.addMemory({
+        project: scope.project,
+        content,
+        memory_type,
+        user_id: scope.userId,
+        session_id: scope.sessionId,
+        agent_id,
+        importance
+      });
       const memoryId = result?.memory_id || (result.mode === "sync" ? result.id : null);
       const jobId = result?.job_id || (result.mode === "async" ? result.id : null);
       return primaryToolSuccess({
@@ -7784,7 +8372,14 @@ server.tool(
         mode: result?.mode || null,
         memory_type,
         stored: result.success === true,
-        queued: result?.mode === "async" || Boolean(jobId)
+        queued: result?.mode === "async" || Boolean(jobId),
+        diagnostics: {
+          scope: {
+            project: scope.project || null,
+            user_id: scope.userId,
+            session_id: scope.sessionId || null
+          }
+        }
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -7820,18 +8415,31 @@ server.tool(
         timestamp
       });
       const resolvedProject = await resolveProjectRef(project);
-      const result = await ingestSessionWithSyncFallback({
-        project: resolvedProject,
-        session_id,
+      const scope = resolveMcpScope({
+        project: resolvedProject || project,
         user_id,
+        session_id
+      });
+      const result = await ingestSessionWithSyncFallback({
+        project: scope.project,
+        session_id: scope.sessionId || session_id,
+        user_id: scope.userId,
         messages: normalizedMessages
       });
       return primaryToolSuccess({
         tool: "record",
-        session_id,
+        session_id: scope.sessionId || session_id,
+        user_id: scope.userId,
         messages_recorded: normalizedMessages.length,
         memories_created: result.memories_created,
-        relations_created: result.relations_created
+        relations_created: result.relations_created,
+        diagnostics: {
+          scope: {
+            project: scope.project || null,
+            user_id: scope.userId,
+            session_id: scope.sessionId || session_id
+          }
+        }
       });
     } catch (error) {
       return primaryToolError(error.message);
@@ -7962,6 +8570,14 @@ async function main() {
     console.error("Error: WHISPER_API_KEY environment variable is required");
     process.exit(1);
   }
+  const startupDiagnostics = {
+    runtime_mode: RUNTIME_MODE,
+    local_ingest_enabled: RUNTIME_MODE !== "remote",
+    startup_status: RUNTIME_MODE === "remote" ? "degraded_auto_repairing" : "healthy",
+    startup_action: RUNTIME_MODE === "remote" ? "restart_client" : "none",
+    warning: RUNTIME_MODE === "remote" ? "Local ingest is disabled in remote mode. Set WHISPER_MCP_MODE=auto and restart MCP to enable local repair paths." : null
+  };
+  console.error(`[whisper-context-mcp] startup_diagnostics=${JSON.stringify(startupDiagnostics)}`);
   console.error("[whisper-context-mcp] Breaking change: canonical namespaced tool names are active. Run with --print-tool-map for migration mapping.");
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -7974,20 +8590,35 @@ export {
   RECOMMENDED_NEXT_CALL_ALLOWLIST,
   RETRIEVAL_READINESS_VALUES,
   RETRIEVAL_ROUTE_VALUES,
+  STATUS_ACTION_VALUES,
+  STATUS_LABEL_VALUES,
   WORKSPACE_HEALTH_VALUES,
   canonicalizeWorkspacePath,
   chooseWorkspaceProjectSource,
   classifyProjectRepoReadiness,
   classifyRepoGroundedQuery,
   classifyWorkspaceHealth,
+  computeSnapshotChangedFiles,
+  computeTrustScore,
   createMcpServer,
   createWhisperMcpClient,
   createWhisperMcpRuntimeClient,
+  defaultMcpUserId,
   extractSignature,
+  fallbackModeFromSearchMode,
+  isStrictlyBetterReadiness,
+  recommendedNextCallsAreAcyclic,
+  recommendedNextCallsForRootCause,
   renderScopedMcpConfig,
   resolveForgetQueryCandidates,
+  resolveMcpScope,
   resolveWorkspaceIdentity,
+  retrievalReadinessRank,
   runSearchCodeSearch,
   sanitizeRecommendedNextCalls,
-  shouldAbstainForCodebaseTrust
+  semanticStatusFromSearchMode,
+  shouldAbstainForCodebaseTrust,
+  shouldTriggerBackgroundRefresh,
+  statusActionForRootCause,
+  statusContractForReadiness
 };