@mushi-mushi/mcp 0.20.0 → 0.20.2

package/dist/index.js

@@ -8,6 +8,72 @@ import { join } from "path";
 import { homedir } from "os";
 import { createLogger as createLogger2, DEFAULT_API_ENDPOINT } from "@mushi-mushi/core";
 
+// src/stdout-guard.ts
+import { Console } from "console";
+var GUARDED_CONSOLE_METHODS = [
+  "log",
+  "info",
+  "debug",
+  "dir",
+  "dirxml",
+  "table",
+  "group",
+  "groupCollapsed",
+  "groupEnd",
+  "count",
+  "countReset",
+  "time",
+  "timeEnd",
+  "timeLog",
+  "trace",
+  "assert",
+  "warn",
+  "error"
+];
+var installed = false;
+function installStdoutGuard() {
+  if (installed) return false;
+  if (typeof process !== "undefined" && process.env?.MUSHI_MCP_STDOUT_GUARD === "off") {
+    return false;
+  }
+  if (typeof process === "undefined" || typeof process.stderr?.write !== "function" || typeof console === "undefined") {
+    return false;
+  }
+  try {
+    const stderrConsole = new Console({
+      stdout: process.stderr,
+      stderr: process.stderr,
+      // Colour codes would land in the client's log pane as escape noise.
+      colorMode: false
+    });
+    const target = console;
+    const source = stderrConsole;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      const fn = source[method];
+      if (typeof fn === "function") {
+        target[method] = fn.bind(stderrConsole);
+      }
+    }
+  } catch {
+    const write = (...args) => process.stderr.write(
+      args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ") + "\n"
+    );
+    const target = console;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      target[method] = write;
+    }
+  }
+  installed = true;
+  return true;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
 // src/catalog.ts
 var ALL_SCOPES = ["mcp:read", "mcp:write"];
 var TOOL_CATALOG = [
@@ -170,7 +236,7 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: 'Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent (default uses the in-repo worker). Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixAttemptId }; poll get_fix_timeline for progress and merge_fix when CI is green. Write; NOT idempotent \u2014 each call starts a new attempt. Report must be classified \u2014 run triage_issue if not.',
+    description: 'Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent (default uses the in-repo worker). Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixId, status } (fixId is the dispatch id; get_fix_timeline accepts it immediately); poll get_fix_timeline for progress and merge_fix when CI is green. Write; pass the same idempotencyKey to retry safely \u2014 without it each call starts a new attempt. Report must be classified \u2014 run triage_issue if not.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
@@ -305,6 +371,14 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Analyze this bug report end-to-end and tell me what to do."
   },
+  {
+    name: "triage_next_steps",
+    title: "What should I work on now?",
+    description: 'Prioritised "do this next" list for the project: blocked auto-fixes first (with the unblock action), then in-flight fixes to shepherd to merge, then user-felt classified reports by severity, with robot/cron chores (dependency bumps) last. Returns { steps: [{ priority, action, reason, tool, args }], summary }. Read-only. Call this first when the user asks "what needs my attention / what should I triage or fix".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What should I triage or fix right now?"
+  },
   // ── Lessons / evolution loop ─────────────────────────────────────────────
   {
     name: "query_lessons",
@@ -375,7 +449,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_byok_keys",
     title: "List your API key pool",
-    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | firecrawl | browserbase | cursor). Returns { keys: [{ id, provider, label, priority, status, cooldownUntil }] } \u2014 metadata only, never the raw secret. Read-only. Use to see which keys are active vs rate-limited/exhausted; use add_byok_key to add one.",
+    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | firecrawl | browserbase | cursor). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle \u2014 never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
@@ -383,11 +457,27 @@ var TDD_TOOL_CATALOG = [
   {
     name: "add_byok_key",
     title: "Add an API key",
-    description: "Add a BYOK API key to the project pool for a provider (anthropic | openai | firecrawl | browserbase | cursor), with a label and priority for failover ordering. The raw key is stored encrypted in Supabase Vault and never returned. Returns { id, provider, label }. Write; NOT idempotent \u2014 adds a new row each call. Use to register a backup/rotated key; use list_byok_keys to review the pool.",
+    description: "Add and immediately validate a BYOK API key for anthropic | openai | firecrawl | browserbase | cursor. The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."
   },
+  {
+    name: "test_byok_key",
+    title: "Test an API key",
+    description: "Re-test one pooled BYOK credential by key id. A successful provider probe activates the key; auth, quota, and network failures keep it out of the runtime pool. Returns the sanitized validation result and updated key metadata. Write; idempotent.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    useCase: "Re-test a quarantined OpenAI key after fixing its account quota."
+  },
+  {
+    name: "remove_byok_key",
+    title: "Remove an API key",
+    description: "Permanently remove one pooled BYOK credential by key id from the authenticated project, including its Vault secret. Write; destructive; idempotent.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
+    useCase: "Remove a rotated or compromised provider key from the runtime pool."
+  },
   {
     name: "list_pending_review_stories",
     title: "List QA stories pending review",
@@ -530,24 +620,29 @@ var TDD_TOOL_CATALOG = [
   }
 ];
 var USE_MUSHI_INTENTS = {
+  // NOTE: every name below MUST be a registered TOOL (scopes.test.ts guards
+  // this). 2026-08-16 audit P0-3 found phantom names (get_report,
+  // get_dashboard, list_qa_stories) and prompts listed as tools
+  // (summarize_report_for_fix, mushi_setup) — agents routed here then
+  // failed the call and gave up.
   fix: {
     label: "Fix a bug",
     tools: [
       "get_recent_reports",
-      "get_report",
-      "summarize_report_for_fix",
+      "get_report_detail",
+      "triage_issue",
       "dispatch_fix",
       "start_skill_pipeline",
       "checkin_pipeline_step",
       "get_pipeline_run"
     ],
-    hint: "Call get_recent_reports to find the top unresolved bug, then summarize_report_for_fix before dispatching."
+    hint: "Call get_recent_reports to find the top unresolved bug, then triage_issue before dispatching."
   },
   status: {
     label: "Check project status",
     tools: [
-      "get_dashboard",
       "triage_next_steps",
+      "get_account_overview",
       "get_usage",
       "get_backend_health",
       "activation_status"
@@ -557,18 +652,19 @@ var USE_MUSHI_INTENTS = {
   setup: {
     label: "Set up Mushi",
     tools: [
-      "mushi_setup",
+      "diagnose_setup",
       "activation_status",
       "get_backend_health",
       "list_byok_keys",
-      "add_byok_key"
+      "add_byok_key",
+      "test_byok_key",
+      "remove_byok_key"
     ],
-    hint: "Call mushi_setup first \u2014 it diagnoses setup gaps and returns the next command to run."
+    hint: "Call diagnose_setup first \u2014 it diagnoses setup gaps and returns the next action to take."
   },
   qa: {
     label: "Run / review QA tests",
     tools: [
-      "list_qa_stories",
       "run_qa_story",
       "list_qa_story_runs",
       "get_qa_story_run",
@@ -576,7 +672,7 @@ var USE_MUSHI_INTENTS = {
       "approve_qa_story",
       "improve_qa_story"
     ],
-    hint: "Call list_qa_stories to see what test coverage exists; run_qa_story to trigger a run."
+    hint: "Call list_qa_story_runs to see recent coverage and outcomes; run_qa_story to trigger a run."
   },
   pipeline: {
     label: "Run an agent pipeline / skill",
@@ -591,12 +687,7 @@ var USE_MUSHI_INTENTS = {
   },
   audit: {
     label: "Audit / health check",
-    tools: [
-      "run_fullstack_audit",
-      "get_backend_health",
-      "get_dashboard",
-      "get_usage"
-    ],
+    tools: ["run_fullstack_audit", "get_backend_health", "get_account_overview", "get_usage"],
     hint: "Call run_fullstack_audit for a full-stack health scorecard."
   }
 };
@@ -759,8 +850,10 @@ var TOOL_FEATURE_MAP = {
   start_skill_pipeline: "skills",
   get_pipeline_run: "skills",
   checkin_pipeline_step: "skills",
-  list_byok_keys: "skills",
-  add_byok_key: "skills",
+  list_byok_keys: "setup",
+  add_byok_key: "setup",
+  test_byok_key: "setup",
+  remove_byok_key: "setup",
   // audit
   run_fullstack_audit: "audit",
   get_backend_health: "audit",
@@ -966,7 +1059,40 @@ function wrapUntrustedJson(value, role) {
 }
 
 // src/server.ts
+installStdoutGuard();
 var NO_ARG_INPUT = {};
+var DEFAULT_API_TIMEOUT_MS = 15e3;
+var MIN_API_TIMEOUT_MS = 250;
+var MAX_API_TIMEOUT_MS = 3e5;
+function resolveTimeoutMsFromEnv() {
+  const raw = process.env?.MUSHI_MCP_TIMEOUT_MS?.trim();
+  if (!raw) return DEFAULT_API_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
+  return Math.min(Math.max(parsed, MIN_API_TIMEOUT_MS), MAX_API_TIMEOUT_MS);
+}
+function bareMessage(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  return raw.replace(/^\[[A-Z0-9_]+\]\s*/, "");
+}
+var IDEMPOTENCY_NAMESPACE = "mushi.mcp.submit_fix_result.v1";
+async function stableUuidFrom(...parts) {
+  const input = parts.join("");
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input))
+  );
+  const bytes = digest.slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function withTimeoutSignal(callerSignal, timeoutSignal) {
+  if (!callerSignal) return timeoutSignal;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function") return anyFn.call(AbortSignal, [callerSignal, timeoutSignal]);
+  return timeoutSignal;
+}
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -980,6 +1106,7 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : resolveTimeoutMsFromEnv();
   const apiLog = createLogger({
     scope: "mushi:mcp:api",
     level: process.env.MUSHI_LOG_LEVEL ?? "info",
@@ -997,22 +1124,66 @@ function createMushiServer(config) {
   async function apiCall(path, options) {
     const requestId = crypto.randomUUID().slice(0, 12);
     const started = Date.now();
-    const res = await doFetch(`${apiEndpoint}${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
-        // still send it for endpoints still behind plain `jwtAuth` (legacy)
-        // and for transparent proxies that strip X-Mushi-* headers.
-        "Authorization": `Bearer ${apiKey}`,
-        "X-Mushi-Api-Key": apiKey,
-        "X-Request-Id": requestId,
-        ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
-        ...options?.headers ?? {}
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    let res;
+    try {
+      res = await doFetch(`${apiEndpoint}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
+          // still send it for endpoints still behind plain `jwtAuth` (legacy)
+          // and for transparent proxies that strip X-Mushi-* headers.
+          Authorization: `Bearer ${apiKey}`,
+          "X-Mushi-Api-Key": apiKey,
+          "X-Request-Id": requestId,
+          ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
+          ...options?.headers ?? {}
+        },
+        // After the spread so a caller-supplied `signal` is merged, not lost.
+        signal: withTimeoutSignal(options?.signal, timeoutSignal)
+      });
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    function classifyTransportError(err) {
+      const durationMs2 = Date.now() - started;
+      if (timeoutSignal.aborted) {
+        apiLog.warn("api.timeout", { path, requestId, durationMs: durationMs2, timeoutMs });
+        return new MushiApiError(
+          504,
+          "MUSHI_TIMEOUT",
+          `Timed out after ${timeoutMs}ms waiting for ${path}. The Mushi API accepted the connection but did not answer in time \u2014 retry, or raise the budget with MUSHI_MCP_TIMEOUT_MS (ms) in your MCP env block if you self-host and cold starts are slow. Endpoint: ${apiEndpoint}`
+        );
       }
-    });
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError") {
+        apiLog.warn("api.aborted", { path, requestId, durationMs: durationMs2 });
+        return new MushiApiError(
+          499,
+          "REQUEST_ABORTED",
+          `The request to ${path} was aborted by the caller after ${durationMs2}ms.`
+        );
+      }
+      apiLog.warn("api.unreachable", {
+        path,
+        requestId,
+        durationMs: durationMs2,
+        err: bareMessage(err)
+      });
+      return new MushiApiError(
+        503,
+        "NETWORK_ERROR",
+        `Could not reach the Mushi API at ${apiEndpoint}${path} \u2014 ${bareMessage(err)}. This is a connectivity failure, not an API rejection: check that you are online, that MUSHI_API_ENDPOINT points at your \`.../functions/v1/api\` URL, and that no proxy/VPN is blocking it.`
+      );
+    }
     const durationMs = Date.now() - started;
-    const text = await res.text();
     let body = null;
     if (text) {
       try {
@@ -1042,6 +1213,7 @@ function createMushiServer(config) {
     apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  let resolvedAccountProjectId = null;
   async function resolveProjectId(explicitId) {
     if (explicitId) {
       if (projectId && explicitId !== projectId) {
@@ -1054,12 +1226,12 @@ function createMushiServer(config) {
       return explicitId;
     }
     if (projectId) return projectId;
+    if (resolvedAccountProjectId) return resolvedAccountProjectId;
     try {
-      const data = await apiCall(
-        "/v1/admin/mcp/account-overview"
-      );
+      const data = await apiCall("/v1/admin/mcp/account-overview");
       if (data.total === 1 && data.projects[0]) {
-        return data.projects[0].id;
+        resolvedAccountProjectId = data.projects[0].id;
+        return resolvedAccountProjectId;
       }
       if (data.total === 0) {
         throw new MushiApiError(
@@ -1075,11 +1247,27 @@ function createMushiServer(config) {
         `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
       );
     } catch (err) {
-      if (err instanceof MushiApiError) throw err;
+      if (err instanceof MushiApiError) {
+        if (err.code === "MUSHI_TIMEOUT" || err.code === "NETWORK_ERROR") {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `Could not resolve which project to use because the Mushi API is unreachable: ${bareMessage(err)} This is a connectivity problem \u2014 setting MUSHI_PROJECT_ID would only skip the lookup, not fix the tool call that follows it.`
+          );
+        }
+        if (err.status === 401 || err.status === 403) {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `The API key was rejected while resolving the project: ${bareMessage(err)} Mint a fresh key in the console (Settings \u2192 API keys) and update MUSHI_API_KEY, or re-run \`mushi login\`. This is an authentication problem, not a missing project id.`
+          );
+        }
+        throw err;
+      }
       throw new MushiApiError(
         400,
         "MISSING_PROJECT_ID",
-        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+        `projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly. (Project lookup failed with: ${bareMessage(err)})`
       );
     }
   }
@@ -1168,9 +1356,12 @@ function createMushiServer(config) {
       params.set("limit", String(Math.min(args.limit ?? 20, 100)));
       const pid = await resolveProjectId(args.project_id);
       const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
-      const data = await apiCall(`/v1/admin/reports?${params}`, {
-        headers: extraHeaders
-      });
+      const data = await apiCall(
+        `/v1/admin/reports?${params}`,
+        {
+          headers: extraHeaders
+        }
+      );
       return jsonResult(data);
     }
   );
@@ -1193,7 +1384,10 @@ function createMushiServer(config) {
       return {
         ...res,
         resource_links: [
-          { uri: `project://reports/${args.reportId}`, title: `Report ${args.reportId.slice(0, 8)}\u2026` }
+          {
+            uri: `project://reports/${args.reportId}`,
+            title: `Report ${args.reportId.slice(0, 8)}\u2026`
+          }
         ]
       };
     }
@@ -1297,17 +1491,20 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`, {
         headers
       });
-      return wrappedJsonResult({
-        report,
-        // Paste-ready fix prompt composed server-side by composeFixPacket()
-        // (diagnosis + repro + suggested fix + relevant code + blast radius).
-        // Hand this straight to the editing agent — no second LLM key needed.
-        fixPrompt: report.fix_packet ?? null,
-        reproductionSteps: report.reproduction_steps ?? [],
-        component: report.component,
-        rootCause: report.stage2_analysis?.rootCause,
-        bugOntologyTags: report.bug_ontology_tags
-      }, "fix context");
+      return wrappedJsonResult(
+        {
+          report,
+          // Paste-ready fix prompt composed server-side by composeFixPacket()
+          // (diagnosis + repro + suggested fix + relevant code + blast radius).
+          // Hand this straight to the editing agent — no second LLM key needed.
+          fixPrompt: report.fix_packet ?? null,
+          reproductionSteps: report.reproduction_steps ?? [],
+          component: report.component,
+          rootCause: report.stage2_analysis?.rootCause,
+          bugOntologyTags: report.bug_ontology_tags
+        },
+        "fix context"
+      );
     }
   );
   server.registerTool(
@@ -1356,7 +1553,9 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      const data = await apiCall(
+        `/v1/admin/graph/traverse?${params}`
+      );
       return jsonResult(data);
     }
   );
@@ -1367,7 +1566,9 @@ function createMushiServer(config) {
       description: descOf("get_graph_neighborhood"),
       annotations: annotationsFor("get_graph_neighborhood"),
       inputSchema: {
-        seed: z.string().describe("Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"),
+        seed: z.string().describe(
+          "Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"
+        ),
         depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
       },
       outputSchema: {
@@ -1380,7 +1581,9 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      const data = await apiCall(
+        `/v1/admin/graph/traverse?${params}`
+      );
       return jsonResult(data);
     }
   );
@@ -1390,7 +1593,9 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      inputSchema: {
+        nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).")
+      },
       outputSchema: {
         node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
       }
@@ -1412,7 +1617,8 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
+      if (!pid)
+        throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
@@ -1430,7 +1636,8 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
+      if (!pid)
+        throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
       const q = new URLSearchParams({ from: args.fromSha, to: args.toSha });
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
@@ -1453,12 +1660,19 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for list_gate_findings");
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for list_gate_findings"
+        );
       const q = new URLSearchParams();
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      const data = await apiCall(
+        `/v1/admin/inventory/${pid}/findings${suffix}`
+      );
       return jsonResult(data);
     }
   );
@@ -1468,19 +1682,33 @@ function createMushiServer(config) {
       title: titleOf("suggest_fix"),
       description: descOf("suggest_fix"),
       annotations: annotationsFor("suggest_fix"),
-      inputSchema: { reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for") },
+      inputSchema: {
+        reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for")
+      },
       outputSchema: {
         reportId: z.string().describe("The report this slice was read from"),
         rootCause: z.unknown().describe("Stage-2 root-cause hint, or null if not yet classified"),
         suggestedFix: z.unknown().describe("Stage-2 suggested fix, or null if not yet classified"),
         reproductionSteps: z.unknown().describe("Reproduction steps recorded on the report (array; [] if none)"),
         summary: z.unknown().describe("One-line report summary, or null"),
-        component: z.unknown().describe("Component/page the bug was attributed to, or null")
+        component: z.unknown().describe("Component/page the bug was attributed to, or null"),
+        note: z.string().optional().describe("Present when no Stage-2 analysis exists \u2014 explains why and what to call instead")
       }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       const s2 = report.stage2_analysis;
+      if (!s2 || s2.rootCause == null && s2.suggestedFix == null) {
+        return jsonResult({
+          reportId: args.reportId,
+          rootCause: null,
+          suggestedFix: null,
+          reproductionSteps: report.reproduction_steps ?? [],
+          summary: report.summary ?? null,
+          component: report.component ?? null,
+          note: "No Stage-2 analysis exists for this report (it was classified by the fast Stage-1 path, which does not produce root-cause/fix hints). Use triage_issue for the full review packet, or dispatch_fix \u2014 the fix worker does its own grounded analysis."
+        });
+      }
       return jsonResult({
         reportId: args.reportId,
         rootCause: s2?.rootCause ?? null,
@@ -1497,7 +1725,11 @@ function createMushiServer(config) {
       title: titleOf("run_nl_query"),
       description: descOf("run_nl_query"),
       annotations: annotationsFor("run_nl_query"),
-      inputSchema: { question: z.string().describe('Question in plain English, e.g. "Which components had the most critical bugs this week?"') }
+      inputSchema: {
+        question: z.string().describe(
+          'Question in plain English, e.g. "Which components had the most critical bugs this week?"'
+        )
+      }
     },
     async (args) => {
       const data = await apiCall("/v1/admin/query", {
@@ -1514,7 +1746,9 @@ function createMushiServer(config) {
       description: descOf("diagnose_setup"),
       annotations: annotationsFor("diagnose_setup"),
       inputSchema: {
-        mode: z.enum(["full", "ingest", "dispatch"]).optional().describe("full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."),
+        mode: z.enum(["full", "ingest", "dispatch"]).optional().describe(
+          "full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."
+        ),
         project_id: z.string().optional().describe("Project UUID for dispatch checks (defaults to configured project)."),
         projectId: z.string().optional().describe("Alias for project_id.")
       },
@@ -1552,7 +1786,11 @@ function createMushiServer(config) {
       }
       if (mode === "dispatch") {
         if (!resolvedId) {
-          throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required for dispatch mode");
+          throw new MushiApiError(
+            400,
+            "MISSING_PROJECT",
+            "project_id is required for dispatch mode"
+          );
         }
         const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
         const failed = data.checks.filter((c) => !c.ready);
@@ -1686,7 +1924,12 @@ function createMushiServer(config) {
     async (args) => {
       const query = args.query ?? "";
       const hits = searchMushiDocs(query, args.limit ?? 8);
-      const results = hits.map(({ title, path, excerpt, score }) => ({ title, path, excerpt, score }));
+      const results = hits.map(({ title, path, excerpt, score }) => ({
+        title,
+        path,
+        excerpt,
+        score
+      }));
       return jsonResult({ query, results });
     }
   );
@@ -1836,7 +2079,9 @@ function createMushiServer(config) {
       } : { error: String(reportRes.reason) };
       return jsonText({
         evidence,
-        reporter_thread: timeline ?? { error: String(timelineRes.reason) }
+        reporter_thread: timeline ?? {
+          error: String(timelineRes.reason)
+        }
       });
     }
   );
@@ -1871,27 +2116,54 @@ function createMushiServer(config) {
       const includeLogs = args.include_logs !== false;
       const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
         apiCall(`/v1/admin/reports/${args.report_id}`, { headers }),
-        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, { headers }),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, {
+          headers
+        }),
         apiCall(`/v1/admin/reports/similarity`, {
           method: "POST",
           headers,
           body: JSON.stringify({ report_id: args.report_id })
         }).catch(() => null),
-        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(() => null),
-        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(() => null),
-        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(() => null) : Promise.resolve(null)
+        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(
+          () => null
+        ),
+        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(
+          () => null
+        ),
+        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(
+          () => null
+        ) : Promise.resolve(null)
       ]);
       const report = reportRes.status === "fulfilled" ? reportRes.value : null;
       const severity = report ? report.severity : "unknown";
       const category = report ? report.category : "unknown";
       const status = report ? report.status : "unknown";
       const actions = [];
-      if (status === "new" || status === "classified") {
+      const processingError = report ? report.processing_error : null;
+      const attempts = report ? report.fix_attempts ?? [] : [];
+      const lastAttempt = attempts.length > 0 ? attempts[attempts.length - 1] : null;
+      const lastAttemptStatus = lastAttempt ? String(lastAttempt.status ?? "") : "";
+      const autofixBlocked = typeof processingError === "string" && processingError.startsWith("autofix_blocked:") || lastAttemptStatus.startsWith("skipped") || lastAttemptStatus === "failed";
+      if (autofixBlocked && status !== "fixing" && status !== "fixed") {
+        const blockReason = typeof processingError === "string" && processingError || String(lastAttempt?.error ?? "previous fix attempt was skipped or failed");
+        actions.push({
+          action: "unblock_autofix",
+          reason: `Auto-fix is blocked: ${blockReason}. Resolve the blocker (settings/integration/budget), then re-dispatch.`,
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+        actions.push({
+          action: "redispatch_after_unblock",
+          reason: "Once the blocker above is resolved, dispatch a fresh fix attempt.",
+          tool: "dispatch_fix",
+          args: { reportId: args.report_id }
+        });
+      } else if (status === "new" || status === "classified") {
         actions.push({
           action: "dispatch_fix",
-          reason: "Report is classified but no fix has been attempted",
+          reason: "Report is classified and no fix has been attempted",
           tool: "dispatch_fix",
-          args: { reportId: args.report_id, agent: "cursor_cloud" }
+          args: { reportId: args.report_id }
         });
       } else if (status === "fixing") {
         actions.push({
@@ -1946,7 +2218,10 @@ function createMushiServer(config) {
       return {
         ...res,
         resource_links: [
-          { uri: `project://reports/${args.report_id}`, title: `Report ${args.report_id.slice(0, 8)}\u2026` },
+          {
+            uri: `project://reports/${args.report_id}`,
+            title: `Report ${args.report_id.slice(0, 8)}\u2026`
+          },
           ...pid ? [{ uri: `project://dashboard`, title: "Project dashboard" }] : []
         ]
       };
@@ -1965,7 +2240,9 @@ function createMushiServer(config) {
         filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
         linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
         summary: z.string().describe("One-line human summary of what the fix changed"),
-        idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+        idempotencyKey: z.string().uuid().optional().describe(
+          "Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows. Omit it and a stable key is derived from reportId + branch + prUrl, so a retried submission carries the identical key instead of a fresh random one."
+        )
       },
       outputSchema: {
         ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
@@ -1973,27 +2250,123 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
+      const idemKey = args.idempotencyKey ?? await stableUuidFrom(
+        IDEMPOTENCY_NAMESPACE,
+        args.reportId,
+        args.branch,
+        args.prUrl ?? ""
+      );
       const created = await apiCall("/v1/admin/fixes", {
         method: "POST",
         headers: { "Idempotency-Key": idemKey },
         body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
       });
-      await apiCall(`/v1/admin/fixes/${created.fixId}`, {
-        method: "PATCH",
-        body: JSON.stringify({
-          status: "completed",
-          branch: args.branch,
-          pr_url: args.prUrl,
-          files_changed: args.filesChanged,
-          lines_changed: args.linesChanged,
-          summary: args.summary,
-          completed_at: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      });
+      try {
+        await apiCall(`/v1/admin/fixes/${created.fixId}`, {
+          method: "PATCH",
+          body: JSON.stringify({
+            status: "completed",
+            branch: args.branch,
+            pr_url: args.prUrl,
+            files_changed: args.filesChanged,
+            lines_changed: args.linesChanged,
+            summary: args.summary,
+            completed_at: (/* @__PURE__ */ new Date()).toISOString()
+          })
+        });
+      } catch (err) {
+        const status = err instanceof MushiApiError ? err.status : 500;
+        throw new MushiApiError(
+          status,
+          "FIX_PATCH_FAILED",
+          `Fix row ${created.fixId} was created for report ${args.reportId}, but marking it completed failed: ${bareMessage(err)} \u2014 the fix row exists and is still in its initial (pending) state, so no work is lost. Preferred repair: PATCH /v1/admin/fixes/${created.fixId} with {"status":"completed"} to finish this exact row. Re-running submit_fix_result re-sends the same derived Idempotency-Key (reportId + branch + prUrl) rather than a fresh one, so it dedupes wherever the API honours that header \u2014 retry only with identical arguments.`
+        );
+      }
       return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
+  server.registerTool(
+    "triage_next_steps",
+    {
+      title: titleOf("triage_next_steps"),
+      description: descOf("triage_next_steps"),
+      annotations: annotationsFor("triage_next_steps"),
+      inputSchema: {
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      },
+      outputSchema: {
+        steps: z.array(
+          z.object({
+            priority: z.number(),
+            action: z.string(),
+            reason: z.string(),
+            tool: z.string().optional(),
+            args: z.record(z.string(), z.unknown()).optional()
+          })
+        ),
+        summary: z.string()
+      }
+    },
+    async (args) => {
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(
+        "/v1/admin/reports?limit=100",
+        { headers: extraHeaders }
+      );
+      const reports = data.reports ?? [];
+      const isCron = (r) => typeof r.reporter_token_hash === "string" && r.reporter_token_hash.startsWith("cron:");
+      const isBlocked = (r) => typeof r.processing_error === "string" && r.processing_error.startsWith("autofix_blocked:");
+      const label = (r) => String(r.title ?? r.summary ?? r.description ?? "").slice(0, 90);
+      const steps = [];
+      let priority = 1;
+      const blocked = reports.filter(isBlocked);
+      if (blocked.length > 0) {
+        steps.push({
+          priority: priority++,
+          action: `Unblock auto-fix (${blocked.length} report${blocked.length === 1 ? "" : "s"} blocked)`,
+          reason: String(blocked[0].processing_error).slice(0, 200),
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+      }
+      const fixing = reports.filter((r) => r.status === "fixing");
+      for (const r of fixing.slice(0, 2)) {
+        steps.push({
+          priority: priority++,
+          action: `Shepherd in-flight fix: ${label(r)}`,
+          reason: "A fix branch/PR is open \u2014 check CI and merge when green.",
+          tool: "get_report_timeline",
+          args: { report_id: r.id }
+        });
+      }
+      const openUserReports = reports.filter((r) => (r.status === "new" || r.status === "classified") && !isCron(r) && !isBlocked(r)).sort((a, b) => {
+        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+        return (rank[String(a.severity)] ?? 4) - (rank[String(b.severity)] ?? 4);
+      });
+      for (const r of openUserReports.slice(0, Math.max(0, 4 - steps.length))) {
+        steps.push({
+          priority: priority++,
+          action: `Triage [${r.severity}] ${label(r)}`,
+          reason: "User-felt report awaiting triage \u2014 review the packet, then dispatch or dismiss.",
+          tool: "triage_issue",
+          args: { report_id: r.id }
+        });
+      }
+      const chores = reports.filter((r) => r.status === "classified" && isCron(r) && !isBlocked(r));
+      if (chores.length > 0 && steps.length < 5) {
+        steps.push({
+          priority: priority++,
+          action: `Batch ${chores.length} maintenance chore${chores.length === 1 ? "" : "s"} (dependency bumps)`,
+          reason: "Robot-filed modernization reports \u2014 batch-dispatch or dismiss in one sitting; do not let them crowd out user bugs.",
+          tool: "get_recent_reports",
+          args: { status: "classified" }
+        });
+      }
+      const summary = steps.length === 0 ? "Inbox is clear \u2014 no blocked fixes, no open user reports, no chores. Nothing needs your attention." : `${steps.length} prioritised step${steps.length === 1 ? "" : "s"}: ` + steps.map((s) => s.action).join(" \u2192 ");
+      return jsonResult({ steps, summary });
+    }
+  );
   server.registerTool(
     "dispatch_fix",
     {
@@ -2003,8 +2376,12 @@ function createMushiServer(config) {
       inputSchema: {
         reportId: z.string().uuid().describe("Report UUID to fix"),
         agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
-        idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
-        inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")
+        idempotencyKey: z.string().uuid().optional().describe(
+          "Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."
+        ),
+        inventoryActionNodeId: z.string().uuid().optional().describe(
+          "Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR."
+        )
       },
       outputSchema: {
         fixId: z.string(),
@@ -2026,7 +2403,7 @@ function createMushiServer(config) {
         } catch {
         }
       }
-      const data = await apiCall("/v1/admin/fixes/dispatch", {
+      const dispatch = await apiCall("/v1/admin/fixes/dispatch", {
         method: "POST",
         headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
         body: JSON.stringify({
@@ -2036,7 +2413,12 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonResult(data);
+      if (!dispatch?.dispatchId) {
+        throw new Error(
+          `Dispatch response missing dispatchId \u2014 got: ${JSON.stringify(dispatch).slice(0, 300)}`
+        );
+      }
+      return jsonResult({ fixId: dispatch.dispatchId, status: dispatch.status ?? "queued" });
     }
   );
   server.registerTool(
@@ -2077,11 +2459,19 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for test_gen_from_report");
-      const data = await apiCall(`/v1/admin/inventory/${pid}/test-gen/from-report/${args.reportId}`, {
-        method: "POST",
-        body: JSON.stringify({})
-      });
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for test_gen_from_report"
+        );
+      const data = await apiCall(
+        `/v1/admin/inventory/${pid}/test-gen/from-report/${args.reportId}`,
+        {
+          method: "POST",
+          body: JSON.stringify({})
+        }
+      );
       return jsonText(data);
     }
   );
@@ -2160,7 +2550,22 @@ function createMushiServer(config) {
       annotations: annotationsFor("transition_status"),
       inputSchema: {
         reportId: z.string().describe("Report UUID"),
-        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "resolved", "verified", "reopened", "dismissed"]).describe("Target status"),
+        status: z.enum([
+          "pending",
+          "classified",
+          // Workflow states added 20260520600000 but missing from this
+          // enum ever since (2026-08-16 audit P2-2) — agents could not
+          // mark a report as being looked at.
+          "triaged",
+          "in_progress",
+          "grouped",
+          "fixing",
+          "fixed",
+          "resolved",
+          "verified",
+          "reopened",
+          "dismissed"
+        ]).describe("Target status (resolved is stored as fixed)"),
         reason: z.string().optional().describe("Reason for the transition (audit trail)")
       }
     },
@@ -2184,7 +2589,12 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for setup_repo_for_mushi");
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for setup_repo_for_mushi"
+        );
       const data = await apiCall(`/v1/admin/projects/${pid}/repo/bootstrap`, {
         method: "POST",
         body: JSON.stringify({})
@@ -2249,23 +2659,45 @@ function createMushiServer(config) {
     "project://stats",
     { description: "Report counts, category breakdown, severity distribution" },
     async () => ({
-      contents: [{ uri: "project://stats", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2) }]
+      contents: [
+        {
+          uri: "project://stats",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
     "project_settings",
     "project://settings",
-    { description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets" },
+    {
+      description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets"
+    },
     async () => ({
-      contents: [{ uri: "project://settings", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2) }]
+      contents: [
+        {
+          uri: "project://settings",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
     "project_dashboard",
     "project://dashboard",
-    { description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)" },
+    {
+      description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)"
+    },
     async () => ({
-      contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
+      contents: [
+        {
+          uri: "project://dashboard",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2)
+        }
+      ]
     })
   );
   server.registerTool(
@@ -2280,14 +2712,16 @@ function createMushiServer(config) {
       }
     },
     async ({ limit, range }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.registerTool(
@@ -2303,18 +2737,20 @@ function createMushiServer(config) {
       }
     },
     async ({ external_user_id, points, reason }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall("/v1/admin/rewards/bonus-points", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ external_user_id, points, reason })
-          }),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall("/v1/admin/rewards/bonus-points", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ external_user_id, points, reason })
+            }),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.registerTool(
@@ -2330,18 +2766,20 @@ function createMushiServer(config) {
       }
     },
     async ({ external_user_id, tier_slug, reason }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall("/v1/admin/rewards/set-tier", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ external_user_id, tier_slug, reason })
-          }),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall("/v1/admin/rewards/set-tier", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ external_user_id, tier_slug, reason })
+            }),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.resource(
@@ -2351,11 +2789,13 @@ function createMushiServer(config) {
       description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp."
     },
     async () => ({
-      contents: [{
-        uri: "privacy://status",
-        mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/privacy-status"), null, 2)
-      }]
+      contents: [
+        {
+          uri: "privacy://status",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/privacy-status"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -2365,15 +2805,19 @@ function createMushiServer(config) {
       description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling."
     },
     async () => ({
-      contents: [{
-        uri: "evolution://history",
-        mimeType: "application/json",
-        text: projectId ? JSON.stringify(
-          await apiCall(`/v1/admin/projects/${encodeURIComponent(projectId)}/evolution-history`),
-          null,
-          2
-        ) : JSON.stringify({ ok: false, error: "project_id required" })
-      }]
+      contents: [
+        {
+          uri: "evolution://history",
+          mimeType: "application/json",
+          text: projectId ? JSON.stringify(
+            await apiCall(
+              `/v1/admin/projects/${encodeURIComponent(projectId)}/evolution-history`
+            ),
+            null,
+            2
+          ) : JSON.stringify({ ok: false, error: "project_id required" })
+        }
+      ]
     })
   );
   server.resource(
@@ -2383,11 +2827,13 @@ function createMushiServer(config) {
       description: "Live health status of every configured BYOK channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Orchestrators should check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run."
     },
     async () => ({
-      contents: [{
-        uri: "project://integration-health",
-        mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
-      }]
+      contents: [
+        {
+          uri: "project://integration-health",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -2399,11 +2845,13 @@ function createMushiServer(config) {
     async () => {
       const path = projectId ? `/v1/admin/inventory/${projectId}` : "/v1/admin/inventory";
       return {
-        contents: [{
-          uri: "inventory://current",
-          mimeType: "application/json",
-          text: JSON.stringify(await apiCall(path), null, 2)
-        }]
+        contents: [
+          {
+            uri: "inventory://current",
+            mimeType: "application/json",
+            text: JSON.stringify(await apiCall(path), null, 2)
+          }
+        ]
       };
     }
   );
@@ -2432,11 +2880,13 @@ function createMushiServer(config) {
     async () => {
       const qs = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
       return {
-        contents: [{
-          uri: "mushi://activation",
-          mimeType: "application/json",
-          text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), null, 2)
-        }]
+        contents: [
+          {
+            uri: "mushi://activation",
+            mimeType: "application/json",
+            text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), null, 2)
+          }
+        ]
       };
     }
   );
@@ -2445,11 +2895,12 @@ function createMushiServer(config) {
     "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
     { reportId: z.string().describe("The report UUID to summarize") },
     ({ reportId }) => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
 1. Call get_fix_context for reportId "${reportId}".
 2. Call get_blast_radius if the report has a component node id.
 3. Call get_similar_bugs with the component or summary as the query.
@@ -2462,8 +2913,9 @@ Then produce a markdown fix plan with exactly these sections:
 - Confidence (low/medium/high) with a one-line justification
 
 Lead with the fix. Skip the preamble.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -2471,11 +2923,12 @@ Lead with the fix. Skip the preamble.`
     "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
     { fixId: z.string().describe("The fix_attempt UUID to explain") },
     ({ fixId }) => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a release engineer. Use the Mushi MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a release engineer. Use the Mushi MCP tools:
 1. Call get_fix_timeline for fixId "${fixId}" to see the full PDCA journey.
 
 Then write a short verdict in this format:
@@ -2484,8 +2937,9 @@ Then write a short verdict in this format:
 - **If iterate:** bullet list of the smallest next patch
 
 No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -2493,11 +2947,12 @@ No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
     'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
     {},
     () => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
 1. Read the project://dashboard resource for the PDCA snapshot.
 2. Call get_recent_reports with status="classified", limit=10.
 
@@ -2505,8 +2960,9 @@ Then output exactly 5 bullets, in priority order, each formatted as:
 \`**Action** \u2014 why it matters \u2014 suggested tool call\`
 
 Prefer items that are bottlenecks or critical severity. Skip filler.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -2514,11 +2970,12 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
     "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
     {},
     () => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a Mushi onboarding copilot. Use the MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a Mushi onboarding copilot. Use the MCP tools:
 1. Read mushi://activation for unified setup posture.
 2. Read project://integration-health if GitHub or Sentry looks blocked.
 3. Call diagnose_setup if the resource is unavailable.
@@ -2530,8 +2987,9 @@ Then output:
 - **If still stuck:** one diagnostic command (e.g. mushi doctor --fix)
 
 Be specific. No generic advice.`
+          }
         }
-      }]
+      ]
     })
   );
   server.registerTool(
@@ -2552,7 +3010,15 @@ Be specific. No generic advice.`
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
       const data = await apiCall(
         `/v1/admin/inventory/${projectId2}/map-from-live`,
-        { method: "POST", body: JSON.stringify({ base_url: baseUrl, max_pages: maxPages, provider, cursor_cloud_refine: cursorCloudRefine }) }
+        {
+          method: "POST",
+          body: JSON.stringify({
+            base_url: baseUrl,
+            max_pages: maxPages,
+            provider,
+            cursor_cloud_refine: cursorCloudRefine
+          })
+        }
       );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
@@ -2580,7 +3046,9 @@ Be specific. No generic advice.`
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
         projectId: z.string().describe("Project UUID that owns the inventory story"),
-        storyNodeId: z.string().describe("User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"),
+        storyNodeId: z.string().describe(
+          "User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"
+        ),
         automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
         baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
         openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
@@ -2594,10 +3062,14 @@ Be specific. No generic advice.`
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
-      const data = await apiCall(
-        `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
-        { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
-      );
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`, {
+        method: "POST",
+        body: JSON.stringify({
+          automation_mode: automationMode,
+          base_url: baseUrl,
+          open_pr: openPr
+        })
+      });
       return jsonResult(data);
     }
   );
@@ -2612,10 +3084,10 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(
-        "/v1/admin/pdca/improve-qa-stories",
-        { method: "POST", body: JSON.stringify({ project_id: projectId2 }) }
-      );
+      const data = await apiCall("/v1/admin/pdca/improve-qa-stories", {
+        method: "POST",
+        body: JSON.stringify({ project_id: projectId2 })
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2649,7 +3121,9 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(`/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`);
+      const data = await apiCall(
+        `/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`
+      );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2662,16 +3136,60 @@ Be specific. No generic advice.`
       inputSchema: {
         projectId: z.string().describe("Project id"),
         provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
-        key: z.string().min(10).describe("The API key value to add"),
+        key: z.string().min(8).max(4096).describe("The API key value to add"),
         label: z.string().optional().describe("Human-readable label for this key"),
-        priority: z.number().int().min(1).max(999).optional().describe("Priority for ordering (lower = higher priority)")
+        priority: z.number().int().min(0).max(1e4).optional().describe("Priority for ordering (lower = higher priority)"),
+        baseUrl: z.string().url().max(2048).optional().describe("Allow-listed OpenAI-compatible HTTPS base URL")
       }
     },
-    async ({ projectId: projectId2, provider, key, label, priority }) => {
-      const data = await apiCall(
-        "/v1/admin/byok/keys",
-        { method: "POST", body: JSON.stringify({ project_id: projectId2, provider_slug: provider, key, label, priority }) }
-      );
+    async ({ projectId: projectId2, provider, key, label, priority, baseUrl }) => {
+      const data = await apiCall("/v1/admin/byok/keys", {
+        method: "POST",
+        body: JSON.stringify({
+          project_id: projectId2,
+          provider_slug: provider,
+          key,
+          label,
+          priority,
+          base_url: baseUrl
+        })
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "test_byok_key",
+    {
+      title: titleOf("test_byok_key", TDD_TOOL_CATALOG),
+      description: descOf("test_byok_key", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("test_byok_key", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        keyId: z.string().uuid().describe("Pooled BYOK key id")
+      }
+    },
+    async ({ keyId }) => {
+      const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}/test`, {
+        method: "POST"
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "remove_byok_key",
+    {
+      title: titleOf("remove_byok_key", TDD_TOOL_CATALOG),
+      description: descOf("remove_byok_key", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("remove_byok_key", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        keyId: z.string().uuid().describe("Pooled BYOK key UUID from list_byok_keys")
+      }
+    },
+    async ({ keyId }) => {
+      const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}`, {
+        method: "DELETE"
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2686,7 +3204,9 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/pending-review`);
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/stories/pending-review`
+      );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2723,13 +3243,10 @@ Be specific. No generic advice.`
       }
     },
     async ({ reportId, message, authorName }) => {
-      const data = await apiCall(
-        `/v1/sync/reports/${reportId}/reply`,
-        {
-          method: "POST",
-          body: JSON.stringify({ message, author_name: authorName })
-        }
-      );
+      const data = await apiCall(`/v1/sync/reports/${reportId}/reply`, {
+        method: "POST",
+        body: JSON.stringify({ message, author_name: authorName })
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2808,10 +3325,10 @@ Be specific. No generic advice.`
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
-      const data = await apiCall(
-        `/v1/admin/projects/${pid}/audit`,
-        { method: "POST", body: "{}" }
-      );
+      const data = await apiCall(`/v1/admin/projects/${pid}/audit`, {
+        method: "POST",
+        body: "{}"
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2907,17 +3424,19 @@ Be specific. No generic advice.`
       inputSchema: {
         root_skill_slug: z.string().describe('Root skill slug to run, e.g. "workflow-fix-and-ship"'),
         report_id: z.string().optional().describe("Report UUID to attach the pipeline to"),
-        mode: z.enum(["handoff", "cloud"]).optional().describe("handoff (default): get context packet for local agent. cloud: auto-dispatch via Cursor Cloud."),
+        mode: z.enum(["handoff", "cloud"]).optional().describe(
+          "handoff (default): get context packet for local agent. cloud: auto-dispatch via Cursor Cloud."
+        ),
         project_id: z.string().optional().describe("Project UUID. Falls back to the configured project.")
       }
     },
     async (args) => {
       const resolvedProjectId = args.project_id ?? projectId;
       if (!resolvedProjectId) return jsonText({ error: "No project_id provided or configured." });
-      const data = await apiCall(
-        "/v1/admin/skills/pipelines",
-        { method: "POST", body: JSON.stringify({ ...args, project_id: resolvedProjectId }) }
-      );
+      const data = await apiCall("/v1/admin/skills/pipelines", {
+        method: "POST",
+        body: JSON.stringify({ ...args, project_id: resolvedProjectId })
+      });
       return jsonText(data);
     }
   );
@@ -2953,10 +3472,10 @@ Be specific. No generic advice.`
     },
     async (args) => {
       const { run_id, step_index, ...body } = args;
-      await apiCall(
-        `/v1/admin/skills/pipelines/${run_id}/steps/${step_index}/checkin`,
-        { method: "POST", body: JSON.stringify(body) }
-      );
+      await apiCall(`/v1/admin/skills/pipelines/${run_id}/steps/${step_index}/checkin`, {
+        method: "POST",
+        body: JSON.stringify(body)
+      });
       return jsonText({ ok: true, message: `Step ${step_index} \u2192 ${args.status}` });
     }
   );
@@ -3124,7 +3643,11 @@ Be specific. No generic advice.`
       if (args.compare) qs.set("compare", args.compare);
       if (args.fix_id) qs.set("fix_id", args.fix_id);
       if (!qs.toString()) {
-        throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
+        throw new MushiApiError(
+          400,
+          "BAD_REQUEST",
+          "Provide paths, source=last_push, compare, or fix_id"
+        );
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
       return jsonResult(data);
@@ -3176,7 +3699,7 @@ Be specific. No generic advice.`
         "### First step",
         `Call \`${cluster.tools[0]}\` to get started.`,
         "",
-        "> Tip: call any tool by name \u2014 `use_mushi` is a read-only helper that never calls other tools itself. All 68 tools remain available."
+        "> Tip: call any tool by name \u2014 `use_mushi` is a read-only helper that never calls other tools itself. All 71 tools remain available."
       ].join("\n");
       return { content: [{ type: "text", text: orientation }] };
     }
@@ -3185,11 +3708,7 @@ Be specific. No generic advice.`
   const featureFilter = config.features ?? "all";
   if (grantedScopes !== void 0 || featureFilter !== "all") {
     const toolRegistry = server._registeredTools;
-    const allSpecs = [
-      ...TOOL_CATALOG,
-      ...TDD_TOOL_CATALOG,
-      ...CODEBASE_TOOL_CATALOG
-    ];
+    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG, ...CODEBASE_TOOL_CATALOG];
     for (const spec of allSpecs) {
       if (grantedScopes !== void 0 && !grantedScopes.includes(spec.scope)) {
         toolRegistry[spec.name]?.remove();
@@ -3263,28 +3782,30 @@ Be specific. No generic advice.`
 
 // src/index.ts
 import * as Sentry from "@sentry/node";
-var _writeStderr = (...args) => process.stderr.write(
-  args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") + "\n"
-);
-console.log = _writeStderr;
-console.warn = _writeStderr;
+installStdoutGuard();
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
 var log = createLogger2({ scope: "mushi:mcp", level: "info", destination: "stderr" });
+function resolveCliConfigPath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const appData = process.env.APPDATA;
+  const base = xdg && xdg.length > 0 ? xdg : process.platform === "win32" && appData && appData.length > 0 ? appData : join(homedir(), ".config");
+  return join(base, "mushi", "config.json");
+}
 function readCliConfig() {
+  const configPath = resolveCliConfigPath();
   try {
-    const xdg = process.env.XDG_CONFIG_HOME;
-    const appData = process.env.APPDATA;
-    const base = xdg && xdg.length > 0 ? xdg : process.platform === "win32" && appData && appData.length > 0 ? appData : join(homedir(), ".config");
-    const raw = readFileSync(join(base, "mushi", "config.json"), "utf8");
+    const raw = readFileSync(configPath, "utf8");
     const parsed = JSON.parse(raw);
     return {
       apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
       projectId: typeof parsed.projectId === "string" ? parsed.projectId : void 0,
-      endpoint: typeof parsed.endpoint === "string" ? parsed.endpoint : void 0
+      endpoint: typeof parsed.endpoint === "string" ? parsed.endpoint : void 0,
+      path: configPath,
+      found: true
     };
   } catch {
-    return {};
+    return { path: configPath, found: false };
   }
 }
 var CLI_CONFIG = readCliConfig();
@@ -3303,11 +3824,49 @@ if (MCP_SENTRY_DSN) {
     tracesSampleRate: 0
   });
 }
+function missingApiKeyReport() {
+  const envState = process.env.MUSHI_API_KEY === void 0 ? "not set" : process.env.MUSHI_API_KEY.trim() === "" ? "set but empty" : "set";
+  const cliState = !CLI_CONFIG.found ? "no file at this path" : CLI_CONFIG.apiKey ? "present" : 'file exists but has no "apiKey" field';
+  return [
+    "",
+    "[mushi-mcp] FATAL: no API key \u2014 the MCP server cannot serve a single tool call.",
+    "",
+    "  Sources checked, in precedence order:",
+    `    1. env MUSHI_API_KEY        \u2192 ${envState}`,
+    `    2. CLI config file          \u2192 ${cliState}`,
+    `       ${CLI_CONFIG.path}`,
+    "",
+    "  Fix either one:",
+    "    \u2022 Run `mushi login` (writes the config file above), or",
+    '    \u2022 Add the key to the "env" block of your MCP client config',
+    "      (.cursor/mcp.json \xB7 claude_desktop_config.json \xB7 .vscode/mcp.json):",
+    "",
+    '        { "mcpServers": { "mushi-mushi": {',
+    '            "command": "npx", "args": ["-y", "@mushi-mushi/mcp"],',
+    '            "env": { "MUSHI_API_KEY": "mushi_\u2026", "MUSHI_PROJECT_ID": "<uuid>" } } } }',
+    "",
+    "      A key exported in your shell does NOT reach the server: MCP clients",
+    "      spawn this process with only the env block they are given.",
+    "",
+    "  Other env vars this server reads:",
+    `    MUSHI_API_ENDPOINT  ${process.env.MUSHI_API_ENDPOINT?.trim() ? "= " + process.env.MUSHI_API_ENDPOINT.trim() : `unset \u2192 ${API_ENDPOINT}`}`,
+    `    MUSHI_PROJECT_ID    ${PROJECT_ID ? "= " + PROJECT_ID : "unset (account mode)"}`,
+    "    MUSHI_SCOPES        optional CSV: mcp:read,mcp:write",
+    '    MUSHI_FEATURES      optional CSV of tool groups, or "all"',
+    "    MUSHI_MCP_TIMEOUT_MS  optional per-request timeout in ms (default 15000)",
+    "",
+    "  Mint a key: Console \u2192 Settings \u2192 API keys.",
+    ""
+  ].join("\n");
+}
 async function main() {
   if (!API_KEY) {
-    log.fatal(
-      "No API key found \u2014 set MUSHI_API_KEY, or run `mushi login` so the CLI config can supply it."
-    );
+    process.stderr.write(missingApiKeyReport());
+    log.fatal("No API key found \u2014 set MUSHI_API_KEY, or run `mushi login`.", {
+      cliConfigPath: CLI_CONFIG.path,
+      cliConfigFound: CLI_CONFIG.found,
+      endpoint: API_ENDPOINT
+    });
     process.exit(1);
   }
   if (!process.env.MUSHI_API_KEY && CLI_CONFIG.apiKey) {
@@ -3354,6 +3913,7 @@ async function main() {
     if (pollTimer) clearInterval(pollTimer);
     void transport.close().finally(() => process.exit(exitCode));
   };
+  setActiveShutdown(shutdown);
   process.stdin.on("end", () => shutdown(0));
   process.stdin.on("close", () => shutdown(0));
   process.on("SIGINT", () => shutdown(0));
@@ -3400,6 +3960,49 @@ async function main() {
     pollTimer.unref();
   }
 }
+var activeShutdown;
+var setActiveShutdown = (fn) => {
+  activeShutdown = fn;
+};
+var exitNow = (code) => {
+  if (activeShutdown) activeShutdown(code);
+  else process.exit(code);
+};
+var CRASH_WINDOW_MS = 1e4;
+var CRASH_LIMIT = 20;
+var crashTimes = [];
+function isCrashLooping() {
+  const now = Date.now();
+  crashTimes = crashTimes.filter((t) => now - t < CRASH_WINDOW_MS);
+  crashTimes.push(now);
+  return crashTimes.length >= CRASH_LIMIT;
+}
+process.on("unhandledRejection", (reason) => {
+  log.error("unhandledRejection \u2014 server kept alive", {
+    err: reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason),
+    stack: reason instanceof Error ? reason.stack?.split("\n").slice(0, 5).join(" | ") : void 0
+  });
+  if (isCrashLooping()) {
+    log.fatal("too many unhandled rejections in 10s \u2014 exiting so the client can respawn");
+    exitNow(1);
+  }
+});
+process.on("uncaughtException", (err) => {
+  if (err?.code === "EPIPE" || err?.code === "ERR_STREAM_DESTROYED" || err?.code === "ERR_STREAM_WRITE_AFTER_END") {
+    log.info("stdio pipe closed by the client \u2014 shutting down", { code: err.code });
+    exitNow(0);
+    return;
+  }
+  log.error("uncaughtException \u2014 server kept alive", {
+    err: `${err?.name ?? "Error"}: ${err?.message ?? String(err)}`,
+    code: err?.code,
+    stack: err?.stack?.split("\n").slice(0, 5).join(" | ")
+  });
+  if (isCrashLooping()) {
+    log.fatal("too many uncaught exceptions in 10s \u2014 exiting so the client can respawn");
+    exitNow(1);
+  }
+});
 main().catch((err) => {
   log.fatal("MCP server crashed", { err: String(err) });
   process.exit(1);