@mushi-mushi/mcp 0.20.1 → 0.21.0

package/dist/index.js

@@ -1,13 +1,79 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createRequire } from "module";
 import { readFileSync } from "fs";
 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 = [
@@ -149,6 +215,14 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Why is Mushi setup broken \u2014 one call, clear next step."
   },
+  {
+    name: "check_sdk_version",
+    title: "Check SDK freshness",
+    description: "Compare a published @mushi-mushi/* package version against the catalog (GET /v1/sdk/latest-version). Returns { package, current, latest, outdated } and, when outdated, suggestedActions (Sentry-style, max 1) pointing at search_mushi_docs plus the mushi-sdk-upgrade skill. Read-only. Use when Dependabot or mushi upgrade --check reports a drift, or before dispatching a fix that assumes a current SDK. Does not bump the pin \u2014 that stays a human/Dependabot change.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is this project on the current Mushi SDK?"
+  },
   {
     name: "search_mushi_docs",
     title: "Search Mushi documentation",
@@ -170,7 +244,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 +379,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",
@@ -546,24 +628,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"
@@ -573,7 +660,8 @@ var USE_MUSHI_INTENTS = {
   setup: {
     label: "Set up Mushi",
     tools: [
-      "mushi_setup",
+      "diagnose_setup",
+      "check_sdk_version",
       "activation_status",
       "get_backend_health",
       "list_byok_keys",
@@ -581,12 +669,11 @@ var USE_MUSHI_INTENTS = {
       "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",
@@ -594,7 +681,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",
@@ -609,7 +696,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."
   }
 };
@@ -725,6 +812,7 @@ var TOOL_FEATURE_MAP = {
   inventory_current: "admin",
   // setup
   diagnose_setup: "setup",
+  check_sdk_version: "setup",
   activation_status: "setup",
   project_integration_health: "setup",
   setup_repo_for_mushi: "setup",
@@ -834,7 +922,7 @@ function toolMatchesFeatures(toolName, filter) {
 }
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { createLogger } from "@mushi-mushi/core";
 
@@ -981,7 +1069,40 @@ function wrapUntrustedJson(value, role) {
 }
 
 // src/server.ts
-var NO_ARG_INPUT = {};
+installStdoutGuard();
+var NO_ARG_INPUT = z.object({});
+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}`);
@@ -995,6 +1116,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",
@@ -1012,22 +1134,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 {
@@ -1057,6 +1223,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) {
@@ -1069,10 +1236,12 @@ function createMushiServer(config) {
       return explicitId;
     }
     if (projectId) return projectId;
+    if (resolvedAccountProjectId) return resolvedAccountProjectId;
     try {
       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(
@@ -1088,11 +1257,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)})`
       );
     }
   }
@@ -1159,7 +1344,7 @@ function createMushiServer(config) {
       title: titleOf("get_recent_reports"),
       description: descOf("get_recent_reports"),
       annotations: annotationsFor("get_recent_reports"),
-      inputSchema: {
+      inputSchema: z.object({
         status: z.string().optional().describe("Filter by status: new, classified, grouped, fixing, fixed, dismissed"),
         category: z.string().optional().describe("Filter by category: bug, slow, visual, confusing, other"),
         severity: z.string().optional().describe("Filter by severity: critical, high, medium, low"),
@@ -1167,11 +1352,11 @@ function createMushiServer(config) {
         project_id: z.string().optional().describe(
           "Project UUID \u2014 defaults to the server-configured project. Useful when you have multiple projects and want to query a specific one by its ID. Get IDs by calling list_projects or get_account_overview first."
         )
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         reports: z.array(z.unknown()),
         total: z.number()
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams();
@@ -1196,11 +1381,11 @@ function createMushiServer(config) {
       title: titleOf("get_report_detail"),
       description: descOf("get_report_detail"),
       annotations: annotationsFor("get_report_detail"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("The report UUID"),
         project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
-      },
-      outputSchema: { report: z.unknown() }
+      }),
+      outputSchema: z.object({ report: z.unknown() })
     },
     async (args) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -1223,7 +1408,7 @@ function createMushiServer(config) {
       title: titleOf("get_report_timeline"),
       description: descOf("get_report_timeline"),
       annotations: annotationsFor("get_report_timeline"),
-      inputSchema: { reportId: z.string().describe("The report UUID") }
+      inputSchema: z.object({ reportId: z.string().describe("The report UUID") })
     },
     async (args) => jsonText(await apiCall(`/v1/sync/reports/${args.reportId}/timeline`))
   );
@@ -1243,14 +1428,14 @@ function createMushiServer(config) {
       title: titleOf("search_reports"),
       description: descOf("search_reports"),
       annotations: annotationsFor("search_reports"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Natural-language search text or component path"),
         limit: z.number().optional().describe("Max results (default 10, max 50)"),
         threshold: z.number().optional().describe("Similarity threshold 0..1, default 0.2")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown())
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/reports/similarity", {
@@ -1271,13 +1456,13 @@ function createMushiServer(config) {
       title: titleOf("get_similar_bugs"),
       description: descOf("get_similar_bugs"),
       annotations: annotationsFor("get_similar_bugs"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Component name, page path, or bug description"),
         limit: z.number().optional().describe("Max results (default 5, max 20)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown())
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/reports/similarity", {
@@ -1298,18 +1483,18 @@ function createMushiServer(config) {
       title: titleOf("get_fix_context"),
       description: descOf("get_fix_context"),
       annotations: annotationsFor("get_fix_context"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("The report UUID to fix"),
         project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         report: z.unknown(),
         fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
         bugOntologyTags: z.unknown()
-      }
+      })
     },
     async (args) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -1338,10 +1523,10 @@ function createMushiServer(config) {
       title: titleOf("get_fix_timeline"),
       description: descOf("get_fix_timeline"),
       annotations: annotationsFor("get_fix_timeline"),
-      inputSchema: {
+      inputSchema: z.object({
         fixId: z.string().describe("fix_attempt UUID"),
         project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
-      }
+      })
     },
     async (args) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -1354,7 +1539,7 @@ function createMushiServer(config) {
       title: titleOf("get_blast_radius"),
       description: descOf("get_blast_radius"),
       annotations: annotationsFor("get_blast_radius"),
-      inputSchema: { nodeId: z.string().describe("Graph node UUID") }
+      inputSchema: z.object({ nodeId: z.string().describe("Graph node UUID") })
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
   );
@@ -1364,14 +1549,14 @@ function createMushiServer(config) {
       title: titleOf("get_knowledge_graph"),
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
-      inputSchema: {
+      inputSchema: z.object({
         seed: z.string().describe("Starting graph node id or human-readable label to traverse from"),
         depth: z.number().optional().describe("BFS hops outward from seed \u2014 clamped to 4 in the handler (default 2)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
         edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams({
@@ -1390,16 +1575,16 @@ function createMushiServer(config) {
       title: titleOf("get_graph_neighborhood"),
       description: descOf("get_graph_neighborhood"),
       annotations: annotationsFor("get_graph_neighborhood"),
-      inputSchema: {
+      inputSchema: z.object({
         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: {
+      }),
+      outputSchema: z.object({
         nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
         edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams({
@@ -1418,12 +1603,12 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: {
+      inputSchema: z.object({
         nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
@@ -1436,9 +1621,9 @@ function createMushiServer(config) {
       title: titleOf("get_inventory"),
       description: descOf("get_inventory"),
       annotations: annotationsFor("get_inventory"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to the server-configured project when omitted")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -1453,11 +1638,11 @@ function createMushiServer(config) {
       title: titleOf("diff_inventory"),
       description: descOf("diff_inventory"),
       annotations: annotationsFor("diff_inventory"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         fromSha: z.string().describe("Older commit SHA (the baseline to diff from)"),
         toSha: z.string().describe("Newer commit SHA (the candidate to diff to)")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -1473,15 +1658,15 @@ function createMushiServer(config) {
       title: titleOf("list_gate_findings"),
       description: descOf("list_gate_findings"),
       annotations: annotationsFor("list_gate_findings"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         gate: z.string().optional().describe("Filter to one gate id: dead-handler | mock-leak | crawl | status-claim"),
         severity: z.string().optional().describe("Minimum severity to include: low | medium | high | critical")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         runs: z.array(z.unknown()).describe("Recent gate_runs rows, newest first"),
         findings: z.array(z.unknown()).describe("gate_findings rows for those runs")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -1507,21 +1692,35 @@ function createMushiServer(config) {
       title: titleOf("suggest_fix"),
       description: descOf("suggest_fix"),
       annotations: annotationsFor("suggest_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         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,
@@ -1538,11 +1737,11 @@ function createMushiServer(config) {
       title: titleOf("run_nl_query"),
       description: descOf("run_nl_query"),
       annotations: annotationsFor("run_nl_query"),
-      inputSchema: {
+      inputSchema: z.object({
         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", {
@@ -1558,14 +1757,14 @@ function createMushiServer(config) {
       title: titleOf("diagnose_setup"),
       description: descOf("diagnose_setup"),
       annotations: annotationsFor("diagnose_setup"),
-      inputSchema: {
+      inputSchema: z.object({
         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.")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         mode: z.string(),
         ready: z.boolean(),
         summary: z.string(),
@@ -1573,7 +1772,7 @@ function createMushiServer(config) {
         ingest: z.unknown().optional(),
         dispatch: z.unknown().optional(),
         connection: z.unknown().optional()
-      }
+      })
     },
     async (args) => {
       const mode = args.mode ?? "full";
@@ -1712,17 +1911,71 @@ function createMushiServer(config) {
       });
     }
   );
+  server.registerTool(
+    "check_sdk_version",
+    {
+      title: titleOf("check_sdk_version"),
+      description: descOf("check_sdk_version"),
+      annotations: annotationsFor("check_sdk_version"),
+      inputSchema: z.object({
+        package: z.string().optional().describe(
+          "npm package name (default @mushi-mushi/web). Examples: @mushi-mushi/web, @mushi-mushi/node, @mushi-mushi/core."
+        ),
+        current: z.string().optional().describe("Installed version from package.json, if known (e.g. 1.27.0).")
+      }),
+      outputSchema: z.object({
+        package: z.string(),
+        latest: z.string().optional(),
+        current: z.string().optional(),
+        outdated: z.boolean().optional(),
+        suggestedActions: z.array(
+          z.object({
+            type: z.literal("tool_call"),
+            toolName: z.string(),
+            arguments: z.record(z.string(), z.unknown()),
+            reason: z.string()
+          })
+        ).optional()
+      })
+    },
+    async (args) => {
+      const pkg = args.package?.trim() || "@mushi-mushi/web";
+      const query = new URLSearchParams({ package: pkg }).toString();
+      const data = await apiCall(
+        `/v1/sdk/latest-version?${query}`
+      );
+      const latest = data.latest ?? data.version;
+      const current = args.current;
+      const outdated = current && latest ? current !== latest : void 0;
+      return jsonResult({
+        package: data.package ?? pkg,
+        latest,
+        current,
+        outdated,
+        ...outdated ? {
+          suggestedActions: [
+            {
+              type: "tool_call",
+              toolName: "search_mushi_docs",
+              arguments: { query: `${pkg} upgrade mushi-sdk-upgrade` },
+              reason: "Read current upgrade notes, then apply the mushi-sdk-upgrade skill. This tool does not bump the pin."
+            }
+          ]
+        } : {}
+      });
+    }
+  );
   server.registerTool(
     "search_mushi_docs",
     {
       title: titleOf("search_mushi_docs"),
       description: descOf("search_mushi_docs"),
       annotations: annotationsFor("search_mushi_docs"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Keywords to search official Mushi docs (guides, MCP, inventory, QA)."),
         limit: z.number().int().min(1).max(20).optional().describe("Max results (default 8).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         query: z.string(),
         results: z.array(
           z.object({
@@ -1732,7 +1985,7 @@ function createMushiServer(config) {
             score: z.number()
           })
         )
-      }
+      })
     },
     async (args) => {
       const query = args.query ?? "";
@@ -1753,11 +2006,11 @@ function createMushiServer(config) {
       description: descOf("list_projects"),
       annotations: annotationsFor("list_projects"),
       inputSchema: NO_ARG_INPUT,
-      outputSchema: {
+      outputSchema: z.object({
         projects: z.array(z.unknown()),
         total: z.number().optional(),
         _multi_project_hint: z.string().optional()
-      }
+      })
     },
     async () => {
       const data = await apiCall("/v1/admin/mcp/projects");
@@ -1774,7 +2027,7 @@ function createMushiServer(config) {
       description: descOf("get_account_overview"),
       annotations: annotationsFor("get_account_overview"),
       inputSchema: NO_ARG_INPUT,
-      outputSchema: {
+      outputSchema: z.object({
         projects: z.array(z.unknown()),
         total: z.number(),
         active_project_id: z.string().nullable(),
@@ -1782,7 +2035,7 @@ function createMushiServer(config) {
         resourceCount: z.number().optional(),
         promptCount: z.number().optional(),
         multi_project_hint: z.string()
-      }
+      })
     },
     async () => {
       const data = await apiCall("/v1/admin/mcp/account-overview");
@@ -1804,9 +2057,9 @@ function createMushiServer(config) {
       title: titleOf("get_project_context"),
       description: descOf("get_project_context"),
       annotations: annotationsFor("get_project_context"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1828,13 +2081,13 @@ function createMushiServer(config) {
       title: titleOf("get_pipeline_logs"),
       description: descOf("get_pipeline_logs"),
       annotations: annotationsFor("get_pipeline_logs"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
         service: z.enum(["fix-worker", "qa-story-runner", "pipeline", "all"]).optional().describe("Pipeline service to filter (default: all)."),
         since: z.string().optional().describe("ISO-8601 timestamp \u2014 return only entries after this time."),
         limit: z.number().optional().describe("Max entries to return (default 50, max 200)."),
         level: z.enum(["info", "warn", "error", "fatal"]).optional().describe("Minimum severity level (default: warn).")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1854,9 +2107,9 @@ function createMushiServer(config) {
       title: titleOf("get_report_evidence"),
       description: descOf("get_report_evidence"),
       annotations: annotationsFor("get_report_evidence"),
-      inputSchema: {
+      inputSchema: z.object({
         report_id: z.string().describe("Report UUID.")
-      }
+      })
     },
     async (args) => {
       const [reportRes, timelineRes] = await Promise.allSettled([
@@ -1904,12 +2157,12 @@ function createMushiServer(config) {
       title: titleOf("triage_issue"),
       description: descOf("triage_issue"),
       annotations: annotationsFor("triage_issue"),
-      inputSchema: {
+      inputSchema: z.object({
         report_id: z.string().uuid().describe("Report UUID to triage."),
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
         include_logs: z.boolean().optional().describe("Include recent pipeline logs in triage packet (default: true).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         report_id: z.string(),
         severity: z.unknown(),
         category: z.unknown(),
@@ -1922,7 +2175,7 @@ function createMushiServer(config) {
         recent_logs: z.unknown().nullable(),
         recommended_actions: z.array(z.unknown()),
         triage_summary: z.string()
-      }
+      })
     },
     async (args) => {
       const { projectId: pid, headers } = await projectScopeHeaders(args.project_id);
@@ -1952,12 +2205,31 @@ function createMushiServer(config) {
       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({
@@ -2027,7 +2299,7 @@ function createMushiServer(config) {
       title: titleOf("submit_fix_result"),
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to attach this external fix attempt to"),
         branch: z.string().describe("Git branch name where the fix was implemented"),
         prUrl: z.string().optional().describe("GitHub pull request URL, if a PR was opened"),
@@ -2035,43 +2307,136 @@ function createMushiServer(config) {
         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"
+          "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: {
+      }),
+      outputSchema: z.object({
         ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
         fixId: z.string().describe("UUID of the new fix_attempt row")
-      }
+      })
     },
     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: z.object({
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      }),
+      outputSchema: z.object({
+        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",
     {
       title: titleOf("dispatch_fix"),
       description: descOf("dispatch_fix"),
       annotations: annotationsFor("dispatch_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         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(
@@ -2080,19 +2445,19 @@ function createMushiServer(config) {
         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: {
+      }),
+      outputSchema: z.object({
         fixId: z.string(),
         status: z.string()
-      }
+      })
     },
-    async (args, extra) => {
-      if (extra?.sendNotification && extra?._meta?.progressToken) {
+    async (args, ctx) => {
+      if (ctx?.mcpReq.notify && ctx?.mcpReq._meta?.progressToken) {
         try {
-          await extra.sendNotification({
+          await ctx.mcpReq.notify({
             method: "notifications/progress",
             params: {
-              progressToken: extra._meta.progressToken,
+              progressToken: ctx.mcpReq._meta.progressToken,
               progress: 0,
               total: 100,
               message: "Dispatching Mushi fix orchestrator\u2026"
@@ -2101,7 +2466,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({
@@ -2111,7 +2476,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(
@@ -2120,13 +2490,13 @@ function createMushiServer(config) {
       title: titleOf("trigger_judge"),
       description: descOf("trigger_judge"),
       annotations: annotationsFor("trigger_judge"),
-      inputSchema: {
+      inputSchema: z.object({
         limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
         projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/judge/run", {
@@ -2145,10 +2515,10 @@ function createMushiServer(config) {
       title: titleOf("test_gen_from_report"),
       description: descOf("test_gen_from_report"),
       annotations: annotationsFor("test_gen_from_report"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to turn into a Playwright PR"),
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -2174,16 +2544,16 @@ function createMushiServer(config) {
       title: titleOf("merge_fix"),
       description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         fixId: z.string().describe("Fix attempt UUID whose GitHub PR should be squash-merged"),
         mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method (default squash)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         merged: z.boolean().optional().describe("True when GitHub accepted the merge in this call"),
         alreadyMerged: z.boolean().optional().describe("True when the PR was already merged (idempotent no-op)"),
         reportId: z.string().describe("Report UUID linked to this fix attempt"),
         reportStatus: z.string().describe("Report workflow status after merge bookkeeping")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/merge`, {
@@ -2199,14 +2569,14 @@ function createMushiServer(config) {
       title: titleOf("refresh_ci"),
       description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
-      inputSchema: {
+      inputSchema: z.object({
         fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         check_run_status: z.string().nullable().describe("GitHub check run status after refresh"),
         check_run_conclusion: z.string().nullable().describe("success | failure | neutral | null while pending"),
         check_run_updated_at: z.string().nullable().describe("ISO timestamp when CI status was last persisted")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
@@ -2219,13 +2589,13 @@ function createMushiServer(config) {
       title: titleOf("reopen_report"),
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to move back to reopened status"),
         note: z.string().optional().describe("Operator note recorded on the reopen transition")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         report: z.unknown().describe("Updated report row with status=reopened")
-      }
+      })
     },
     async (args) => {
       const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
@@ -2241,11 +2611,16 @@ function createMushiServer(config) {
       title: titleOf("transition_status"),
       description: descOf("transition_status"),
       annotations: annotationsFor("transition_status"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID"),
         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",
@@ -2253,9 +2628,9 @@ function createMushiServer(config) {
           "verified",
           "reopened",
           "dismissed"
-        ]).describe("Target status"),
+        ]).describe("Target status (resolved is stored as fixed)"),
         reason: z.string().optional().describe("Reason for the transition (audit trail)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/reports/${args.reportId}`, {
@@ -2271,9 +2646,9 @@ function createMushiServer(config) {
       title: titleOf("setup_repo_for_mushi"),
       description: descOf("setup_repo_for_mushi"),
       annotations: annotationsFor("setup_repo_for_mushi"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -2296,12 +2671,12 @@ function createMushiServer(config) {
       title: titleOf("query_lessons"),
       description: descOf("query_lessons"),
       annotations: annotationsFor("query_lessons"),
-      inputSchema: {
+      inputSchema: z.object({
         diff_text: z.string().describe("The PR diff, code snippet, or description of the change being made."),
         max_tokens: z.number().optional().describe("Maximum tokens for returned lessons context (default 3000, max 8000)."),
         top_k: z.number().optional().describe("Max number of lessons to return (default 15, max 50)."),
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2323,14 +2698,14 @@ function createMushiServer(config) {
       title: titleOf("list_lessons"),
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
-      inputSchema: {
+      inputSchema: z.object({
         severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter to one severity level"),
         limit: z.number().optional().describe("Max lessons to return (default 50, max 200)"),
         project_id: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2342,7 +2717,7 @@ function createMushiServer(config) {
       return wrappedJsonResult({ lessons }, "lesson text");
     }
   );
-  server.resource(
+  server.registerResource(
     "project_stats",
     "project://stats",
     { description: "Report counts, category breakdown, severity distribution" },
@@ -2356,7 +2731,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_settings",
     "project://settings",
     {
@@ -2372,7 +2747,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_dashboard",
     "project://dashboard",
     {
@@ -2394,10 +2769,10 @@ function createMushiServer(config) {
       title: titleOf("list_top_contributors"),
       description: descOf("list_top_contributors"),
       annotations: annotationsFor("list_top_contributors"),
-      inputSchema: {
+      inputSchema: z.object({
         limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
         range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
-      }
+      })
     },
     async ({ limit, range }) => ({
       content: [
@@ -2418,11 +2793,11 @@ function createMushiServer(config) {
       title: titleOf("award_bonus_points"),
       description: descOf("award_bonus_points"),
       annotations: annotationsFor("award_bonus_points"),
-      inputSchema: {
+      inputSchema: z.object({
         external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
         points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
         reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
-      }
+      })
     },
     async ({ external_user_id, points, reason }) => ({
       content: [
@@ -2447,11 +2822,11 @@ function createMushiServer(config) {
       title: titleOf("set_tier"),
       description: descOf("set_tier"),
       annotations: annotationsFor("set_tier"),
-      inputSchema: {
+      inputSchema: z.object({
         external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
         tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
         reason: z.string().max(200).optional().describe("Optional reason for manual override")
-      }
+      })
     },
     async ({ external_user_id, tier_slug, reason }) => ({
       content: [
@@ -2470,7 +2845,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "privacy_status",
     "privacy://status",
     {
@@ -2486,7 +2861,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "evolution_history",
     "evolution://history",
     {
@@ -2508,7 +2883,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_integration_health",
     "project://integration-health",
     {
@@ -2524,7 +2899,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "inventory_current",
     "inventory://current",
     {
@@ -2549,9 +2924,9 @@ function createMushiServer(config) {
       title: titleOf("activation_status"),
       description: descOf("activation_status"),
       annotations: annotationsFor("activation_status"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to the configured project).")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2559,7 +2934,7 @@ function createMushiServer(config) {
       return jsonResult(await apiCall(`/v1/admin/activation${qs}`));
     }
   );
-  server.resource(
+  server.registerResource(
     "activation_status",
     "mushi://activation",
     {
@@ -2578,10 +2953,12 @@ function createMushiServer(config) {
       };
     }
   );
-  server.prompt(
+  server.registerPrompt(
     "summarize_report_for_fix",
-    "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") },
+    {
+      description: "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.",
+      argsSchema: z.object({ reportId: z.string().describe("The report UUID to summarize") })
+    },
     ({ reportId }) => ({
       messages: [
         {
@@ -2606,10 +2983,12 @@ Lead with the fix. Skip the preamble.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "explain_judge_result",
-    "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") },
+    {
+      description: "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
+      argsSchema: z.object({ fixId: z.string().describe("The fix_attempt UUID to explain") })
+    },
     ({ fixId }) => ({
       messages: [
         {
@@ -2630,10 +3009,12 @@ No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "triage_next_steps",
-    'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
-    {},
+    {
+      description: 'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
+      argsSchema: z.object({})
+    },
     () => ({
       messages: [
         {
@@ -2653,10 +3034,12 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "mushi_setup",
-    "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
-    {},
+    {
+      description: "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
+      argsSchema: z.object({})
+    },
     () => ({
       messages: [
         {
@@ -2686,13 +3069,13 @@ Be specific. No generic advice.`
       title: titleOf("map_user_stories", TDD_TOOL_CATALOG),
       description: descOf("map_user_stories", TDD_TOOL_CATALOG),
       annotations: annotationsFor("map_user_stories", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id to map stories for"),
         baseUrl: z.string().url().describe("Live app URL to crawl"),
         maxPages: z.number().int().min(1).max(50).optional().describe("Max pages to crawl (default 20)"),
         provider: z.enum(["firecrawl", "browserbase"]).optional().describe("Crawl provider (default: firecrawl)"),
         cursorCloudRefine: z.boolean().optional().describe("Dispatch Cursor Cloud agent to refine and open a PR")
-      }
+      })
     },
     async ({ projectId: projectId2, baseUrl, maxPages, provider, cursorCloudRefine }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
@@ -2717,9 +3100,9 @@ Be specific. No generic advice.`
       title: titleOf("get_map_run_status", TDD_TOOL_CATALOG),
       description: descOf("get_map_run_status", TDD_TOOL_CATALOG),
       annotations: annotationsFor("get_map_run_status", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(`/v1/admin/inventory/${projectId2}/map-runs`);
@@ -2732,7 +3115,7 @@ Be specific. No generic advice.`
       title: titleOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         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)"
@@ -2740,13 +3123,13 @@ Be specific. No generic advice.`
         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)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         qaStoryId: z.string().describe("UUID of the inserted qa_stories row"),
         prUrl: z.string().nullable().describe("GitHub PR URL when openPr=true and GitHub is connected"),
         approvalStatus: z.string().describe("pending_review | approved \u2014 follows automationMode and project defaults"),
         needsHumanReview: z.boolean().describe("True when the story requires operator approval before scheduled runs")
-      }
+      })
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
@@ -2767,9 +3150,9 @@ Be specific. No generic advice.`
       title: titleOf("improve_qa_story", TDD_TOOL_CATALOG),
       description: descOf("improve_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("improve_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project id (omit to run across all projects)")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall("/v1/admin/pdca/improve-qa-stories", {
@@ -2785,10 +3168,10 @@ Be specific. No generic advice.`
       title: titleOf("run_qa_story", TDD_TOOL_CATALOG),
       description: descOf("run_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("run_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         qaStoryId: z.string().describe("qa_story id to run")
-      }
+      })
     },
     async ({ projectId: projectId2, qaStoryId }) => {
       const data = await apiCall(
@@ -2804,9 +3187,9 @@ Be specific. No generic advice.`
       title: titleOf("list_byok_keys", TDD_TOOL_CATALOG),
       description: descOf("list_byok_keys", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_byok_keys", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(
@@ -2821,14 +3204,14 @@ Be specific. No generic advice.`
       title: titleOf("add_byok_key", TDD_TOOL_CATALOG),
       description: descOf("add_byok_key", TDD_TOOL_CATALOG),
       annotations: annotationsFor("add_byok_key", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
         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(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, baseUrl }) => {
       const data = await apiCall("/v1/admin/byok/keys", {
@@ -2851,10 +3234,10 @@ Be specific. No generic advice.`
       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: {
+      inputSchema: z.object({
         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`, {
@@ -2869,10 +3252,10 @@ Be specific. No generic advice.`
       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: {
+      inputSchema: z.object({
         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)}`, {
@@ -2887,9 +3270,9 @@ Be specific. No generic advice.`
       title: titleOf("list_pending_review_stories", TDD_TOOL_CATALOG),
       description: descOf("list_pending_review_stories", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_pending_review_stories", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(
@@ -2904,11 +3287,11 @@ Be specific. No generic advice.`
       title: titleOf("approve_qa_story", TDD_TOOL_CATALOG),
       description: descOf("approve_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("approve_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         qaStoryId: z.string().describe("QA story id to approve or reject"),
         status: z.enum(["approved", "rejected"]).describe("New approval status")
-      }
+      })
     },
     async ({ projectId: projectId2, qaStoryId, status }) => {
       const data = await apiCall(
@@ -2924,11 +3307,11 @@ Be specific. No generic advice.`
       title: titleOf("reply_to_reporter", TDD_TOOL_CATALOG),
       description: descOf("reply_to_reporter", TDD_TOOL_CATALOG),
       annotations: annotationsFor("reply_to_reporter", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report id to reply to"),
         message: z.string().min(1).max(1e4).describe("Message text to send to the reporter"),
         authorName: z.string().optional().describe('Display name for the admin sender (default: "Mushi Admin")')
-      }
+      })
     },
     async ({ reportId, message, authorName }) => {
       const data = await apiCall(`/v1/sync/reports/${reportId}/reply`, {
@@ -2944,10 +3327,10 @@ Be specific. No generic advice.`
       title: titleOf("list_qa_story_runs", TDD_TOOL_CATALOG),
       description: descOf("list_qa_story_runs", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_qa_story_runs", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         storyId: z.string().describe("QA story id (uuid)"),
         limit: z.number().int().min(1).max(50).optional().default(10).describe("Max runs to return (default 10)")
-      }
+      })
     },
     async ({ storyId, limit }) => {
       const data = await apiCall(
@@ -2962,10 +3345,10 @@ Be specific. No generic advice.`
       title: titleOf("get_qa_story_run", TDD_TOOL_CATALOG),
       description: descOf("get_qa_story_run", TDD_TOOL_CATALOG),
       annotations: annotationsFor("get_qa_story_run", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         storyId: z.string().describe("QA story id (uuid)"),
         runId: z.string().describe("Run id (uuid) to fetch detail for")
-      }
+      })
     },
     async ({ storyId, runId }) => {
       const data = await apiCall(
@@ -2988,9 +3371,9 @@ Be specific. No generic advice.`
       title: titleOf("test_notification_channel", TDD_TOOL_CATALOG),
       description: descOf("test_notification_channel", TDD_TOOL_CATALOG),
       annotations: annotationsFor("test_notification_channel", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         kind: z.enum(["slack", "discord"]).describe("Notification channel kind to test")
-      }
+      })
     },
     async ({ kind }) => {
       const data = await apiCall(
@@ -3006,9 +3389,9 @@ Be specific. No generic advice.`
       title: titleOf("run_fullstack_audit"),
       description: descOf("run_fullstack_audit"),
       annotations: annotationsFor("run_fullstack_audit"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID to audit. Defaults to the configured project.")
-      }
+      })
     },
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
@@ -3026,10 +3409,10 @@ Be specific. No generic advice.`
       title: titleOf("get_backend_health"),
       description: descOf("get_backend_health"),
       annotations: annotationsFor("get_backend_health"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID. Defaults to the configured project."),
         include_logs: z.boolean().optional().describe("Whether to include recent backend error logs (default: true).")
-      }
+      })
     },
     async ({ project_id, include_logs = true }) => {
       const pid = project_id ?? config.projectId;
@@ -3053,9 +3436,9 @@ Be specific. No generic advice.`
       title: titleOf("get_usage"),
       description: descOf("get_usage"),
       annotations: annotationsFor("get_usage"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
-      }
+      })
     },
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
@@ -3070,12 +3453,12 @@ Be specific. No generic advice.`
       title: titleOf("list_skills"),
       description: descOf("list_skills"),
       annotations: annotationsFor("list_skills"),
-      inputSchema: {
+      inputSchema: z.object({
         category: z.string().optional().describe("Filter by category: workflow, debug, test, audit, enhance, \u2026"),
         search: z.string().optional().describe("Free-text search across slug, title, description"),
         page: z.number().optional().describe("Page number (default 1)"),
         limit: z.number().optional().describe("Max results per page (default 200, max 200)")
-      }
+      })
     },
     async (args) => {
       const qs = new URLSearchParams();
@@ -3094,9 +3477,9 @@ Be specific. No generic advice.`
       title: titleOf("get_skill"),
       description: descOf("get_skill"),
       annotations: annotationsFor("get_skill"),
-      inputSchema: {
+      inputSchema: z.object({
         slug: z.string().describe('Skill slug, e.g. "workflow-fix-and-ship"')
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/skills/${args.slug}`);
@@ -3109,14 +3492,14 @@ Be specific. No generic advice.`
       title: titleOf("start_skill_pipeline"),
       description: descOf("start_skill_pipeline"),
       annotations: annotationsFor("start_skill_pipeline"),
-      inputSchema: {
+      inputSchema: z.object({
         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."
         ),
         project_id: z.string().optional().describe("Project UUID. Falls back to the configured project.")
-      }
+      })
     },
     async (args) => {
       const resolvedProjectId = args.project_id ?? projectId;
@@ -3134,9 +3517,9 @@ Be specific. No generic advice.`
       title: titleOf("get_pipeline_run"),
       description: descOf("get_pipeline_run"),
       annotations: annotationsFor("get_pipeline_run"),
-      inputSchema: {
+      inputSchema: z.object({
         run_id: z.string().describe("Pipeline run UUID")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/skills/pipelines/${args.run_id}`);
@@ -3149,14 +3532,14 @@ Be specific. No generic advice.`
       title: titleOf("checkin_pipeline_step"),
       description: descOf("checkin_pipeline_step"),
       annotations: annotationsFor("checkin_pipeline_step"),
-      inputSchema: {
+      inputSchema: z.object({
         run_id: z.string().describe("Pipeline run UUID"),
         step_index: z.number().describe("Step index (0-based)"),
         status: z.enum(["running", "passed", "failed", "skipped"]).describe("Step status"),
         notes: z.string().optional().describe("Optional notes or output summary"),
         pr_url: z.string().optional().describe("PR URL opened during this step"),
         agent_ref: z.string().optional().describe("Cursor agentId or external agent reference")
-      }
+      })
     },
     async (args) => {
       const { run_id, step_index, ...body } = args;
@@ -3173,13 +3556,13 @@ Be specific. No generic advice.`
       title: titleOf("ask_codebase", CODEBASE_TOOL_CATALOG),
       description: descOf("ask_codebase", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("ask_codebase", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         question: z.string().describe("Plain-English question about the repo"),
         thread_id: z.string().optional().describe("Optional thread UUID to continue a conversation"),
         file_path: z.string().optional().describe("Optional file path focus"),
         symbol_name: z.string().optional().describe("Optional symbol name focus")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3207,12 +3590,12 @@ Be specific. No generic advice.`
       title: titleOf("get_file_summary", CODEBASE_TOOL_CATALOG),
       description: descOf("get_file_summary", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_file_summary", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         file_path: z.string().describe("Indexed file path"),
         symbol_name: z.string().optional().describe("Optional symbol name within the file"),
         force: z.boolean().optional().describe("Bypass cache and regenerate")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3230,10 +3613,10 @@ Be specific. No generic advice.`
       title: titleOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
       description: descOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_codebase_tour", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         force: z.boolean().optional().describe("Bypass cache and regenerate")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3249,17 +3632,17 @@ Be specific. No generic advice.`
       title: titleOf("search_codebase", CODEBASE_TOOL_CATALOG),
       description: descOf("search_codebase", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         query: z.string().describe("Plain-English search query against indexed source files"),
         k: z.number().int().min(1).max(20).optional().describe("Max hits to return (default 8, max 20)"),
         scope_prefix: z.string().optional().describe("Optional repo subdirectory prefix to limit search scope")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown()).describe("Ranked file/symbol hits with paths, line ranges, and similarity"),
         query: z.string().describe("Normalized query string that was searched"),
         mode: z.string().optional().describe("semantic (embeddings) or name (path/symbol match)")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3284,11 +3667,11 @@ Be specific. No generic advice.`
       title: titleOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
       description: descOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_codebase_domains", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         force: z.boolean().optional().describe("Bypass cache and regenerate"),
         scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3307,20 +3690,20 @@ Be specific. No generic advice.`
       title: titleOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       description: descOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         paths: z.array(z.string()).optional().describe("Changed repo-relative file paths to analyze"),
         source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths instead of manual paths"),
         compare: z.string().optional().describe("GitHub compare range base...head when source=compare"),
         fix_id: z.string().optional().describe("Fix attempt UUID \u2014 uses that PR's changed files when source=fix")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         changed_paths: z.array(z.string()).describe("Resolved set of changed paths analyzed"),
         source: z.string().describe("How changed_paths were resolved (manual, last_push, compare, fix, \u2026)"),
         affected_file_paths: z.array(z.string()).describe("Indexed files that import or depend on changed paths"),
         affected_node_ids: z.array(z.string()).describe("Codebase graph node ids impacted by the change"),
         meta: z.unknown().nullable().optional().describe("Extra resolution metadata when auto-sourced")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3347,9 +3730,9 @@ Be specific. No generic advice.`
       title: titleOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
       description: descOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -3363,11 +3746,11 @@ Be specific. No generic advice.`
     {
       title: titleOf("use_mushi"),
       description: descOf("use_mushi"),
-      inputSchema: {
+      inputSchema: z.object({
         intent: z.string().optional().describe(
           'What you are trying to accomplish with Mushi, e.g. "fix the top bug", "check project health", "run QA tests", "set up Mushi". Leave blank for a general orientation.'
         )
-      },
+      }),
       annotations: annotationsFor("use_mushi")
     },
     async (args) => {
@@ -3470,28 +3853,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();
@@ -3510,11 +3895,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) {
@@ -3543,24 +3966,33 @@ async function main() {
     hasProjectId: !!PROJECT_ID,
     scopes: SCOPES.join(",")
   });
-  const server = createMushiServer({
-    version: VERSION,
-    apiEndpoint: API_ENDPOINT,
-    apiKey: API_KEY,
-    projectId: PROJECT_ID || void 0,
-    scopes: SCOPES,
-    features: FEATURES
-  });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  let server;
+  const handle = serveStdio(
+    (ctx) => {
+      server = createMushiServer({
+        version: VERSION,
+        apiEndpoint: API_ENDPOINT,
+        apiKey: API_KEY,
+        projectId: PROJECT_ID || void 0,
+        scopes: SCOPES,
+        features: FEATURES
+      });
+      log.debug("[mushi-mcp] server instance created", { era: ctx.era });
+      return server;
+    },
+    {
+      onerror: (err) => log.error("stdio transport error", { err: String(err) })
+    }
+  );
   let shuttingDown = false;
   let pollTimer;
   const shutdown = (exitCode) => {
     if (shuttingDown) return;
     shuttingDown = true;
     if (pollTimer) clearInterval(pollTimer);
-    void transport.close().finally(() => process.exit(exitCode));
+    void handle.close().finally(() => process.exit(exitCode));
   };
+  setActiveShutdown(shutdown);
   process.stdin.on("end", () => shutdown(0));
   process.stdin.on("close", () => shutdown(0));
   process.on("SIGINT", () => shutdown(0));
@@ -3590,7 +4022,7 @@ async function main() {
         const data = await res.json();
         const updatedAt = data?.data?.updatedAt ?? null;
         if (updatedAt && updatedAt !== lastInventoryAt) {
-          if (lastInventoryAt !== null) {
+          if (lastInventoryAt !== null && server) {
             await server.server.sendResourceUpdated({ uri: "inventory://current" });
             log.info("inventory://current updated \u2014 notified subscribers", { updatedAt });
           }
@@ -3607,6 +4039,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);