@mushi-mushi/mcp 0.20.0 → 0.20.2

package/dist/server.js

@@ -3,14 +3,14 @@ import {
   TDD_TOOL_CATALOG,
   TOOL_CATALOG,
   USE_MUSHI_INTENTS
-} from "./chunk-OZJEY3QR.js";
+} from "./chunk-RVZIKP4X.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EANW5YTI.js";
 import {
   DEPRECATED_TOOL_ALIASES,
   toolMatchesFeatures
-} from "./chunk-VBXXUK5G.js";
+} from "./chunk-ZSVRLSW5.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -143,8 +143,107 @@ function wrapUntrustedJson(value, role) {
   return wrapUntrusted(serialised, role);
 }
 
+// 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/server.ts
+installStdoutGuard();
 var NO_ARG_INPUT = {};
+var DEFAULT_API_TIMEOUT_MS = 15e3;
+var MIN_API_TIMEOUT_MS = 250;
+var MAX_API_TIMEOUT_MS = 3e5;
+function resolveTimeoutMsFromEnv() {
+  const raw = process.env?.MUSHI_MCP_TIMEOUT_MS?.trim();
+  if (!raw) return DEFAULT_API_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
+  return Math.min(Math.max(parsed, MIN_API_TIMEOUT_MS), MAX_API_TIMEOUT_MS);
+}
+function bareMessage(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  return raw.replace(/^\[[A-Z0-9_]+\]\s*/, "");
+}
+var IDEMPOTENCY_NAMESPACE = "mushi.mcp.submit_fix_result.v1";
+async function stableUuidFrom(...parts) {
+  const input = parts.join("");
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input))
+  );
+  const bytes = digest.slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function withTimeoutSignal(callerSignal, timeoutSignal) {
+  if (!callerSignal) return timeoutSignal;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function") return anyFn.call(AbortSignal, [callerSignal, timeoutSignal]);
+  return timeoutSignal;
+}
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -158,6 +257,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",
@@ -175,22 +275,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 {
@@ -220,6 +364,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) {
@@ -232,12 +377,12 @@ function createMushiServer(config) {
       return explicitId;
     }
     if (projectId) return projectId;
+    if (resolvedAccountProjectId) return resolvedAccountProjectId;
     try {
-      const data = await apiCall(
-        "/v1/admin/mcp/account-overview"
-      );
+      const data = await apiCall("/v1/admin/mcp/account-overview");
       if (data.total === 1 && data.projects[0]) {
-        return data.projects[0].id;
+        resolvedAccountProjectId = data.projects[0].id;
+        return resolvedAccountProjectId;
       }
       if (data.total === 0) {
         throw new MushiApiError(
@@ -253,11 +398,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)})`
       );
     }
   }
@@ -346,9 +507,12 @@ function createMushiServer(config) {
       params.set("limit", String(Math.min(args.limit ?? 20, 100)));
       const pid = await resolveProjectId(args.project_id);
       const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
-      const data = await apiCall(`/v1/admin/reports?${params}`, {
-        headers: extraHeaders
-      });
+      const data = await apiCall(
+        `/v1/admin/reports?${params}`,
+        {
+          headers: extraHeaders
+        }
+      );
       return jsonResult(data);
     }
   );
@@ -371,7 +535,10 @@ function createMushiServer(config) {
       return {
         ...res,
         resource_links: [
-          { uri: `project://reports/${args.reportId}`, title: `Report ${args.reportId.slice(0, 8)}\u2026` }
+          {
+            uri: `project://reports/${args.reportId}`,
+            title: `Report ${args.reportId.slice(0, 8)}\u2026`
+          }
         ]
       };
     }
@@ -475,17 +642,20 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`, {
         headers
       });
-      return wrappedJsonResult({
-        report,
-        // Paste-ready fix prompt composed server-side by composeFixPacket()
-        // (diagnosis + repro + suggested fix + relevant code + blast radius).
-        // Hand this straight to the editing agent — no second LLM key needed.
-        fixPrompt: report.fix_packet ?? null,
-        reproductionSteps: report.reproduction_steps ?? [],
-        component: report.component,
-        rootCause: report.stage2_analysis?.rootCause,
-        bugOntologyTags: report.bug_ontology_tags
-      }, "fix context");
+      return wrappedJsonResult(
+        {
+          report,
+          // Paste-ready fix prompt composed server-side by composeFixPacket()
+          // (diagnosis + repro + suggested fix + relevant code + blast radius).
+          // Hand this straight to the editing agent — no second LLM key needed.
+          fixPrompt: report.fix_packet ?? null,
+          reproductionSteps: report.reproduction_steps ?? [],
+          component: report.component,
+          rootCause: report.stage2_analysis?.rootCause,
+          bugOntologyTags: report.bug_ontology_tags
+        },
+        "fix context"
+      );
     }
   );
   server.registerTool(
@@ -534,7 +704,9 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      const data = await apiCall(
+        `/v1/admin/graph/traverse?${params}`
+      );
       return jsonResult(data);
     }
   );
@@ -545,7 +717,9 @@ function createMushiServer(config) {
       description: descOf("get_graph_neighborhood"),
       annotations: annotationsFor("get_graph_neighborhood"),
       inputSchema: {
-        seed: z.string().describe("Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"),
+        seed: z.string().describe(
+          "Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"
+        ),
         depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
       },
       outputSchema: {
@@ -558,7 +732,9 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      const data = await apiCall(
+        `/v1/admin/graph/traverse?${params}`
+      );
       return jsonResult(data);
     }
   );
@@ -568,7 +744,9 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      inputSchema: {
+        nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).")
+      },
       outputSchema: {
         node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
       }
@@ -590,7 +768,8 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
+      if (!pid)
+        throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
@@ -608,7 +787,8 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
+      if (!pid)
+        throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
       const q = new URLSearchParams({ from: args.fromSha, to: args.toSha });
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
@@ -631,12 +811,19 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for list_gate_findings");
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for list_gate_findings"
+        );
       const q = new URLSearchParams();
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      const data = await apiCall(
+        `/v1/admin/inventory/${pid}/findings${suffix}`
+      );
       return jsonResult(data);
     }
   );
@@ -646,19 +833,33 @@ function createMushiServer(config) {
       title: titleOf("suggest_fix"),
       description: descOf("suggest_fix"),
       annotations: annotationsFor("suggest_fix"),
-      inputSchema: { reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for") },
+      inputSchema: {
+        reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for")
+      },
       outputSchema: {
         reportId: z.string().describe("The report this slice was read from"),
         rootCause: z.unknown().describe("Stage-2 root-cause hint, or null if not yet classified"),
         suggestedFix: z.unknown().describe("Stage-2 suggested fix, or null if not yet classified"),
         reproductionSteps: z.unknown().describe("Reproduction steps recorded on the report (array; [] if none)"),
         summary: z.unknown().describe("One-line report summary, or null"),
-        component: z.unknown().describe("Component/page the bug was attributed to, or null")
+        component: z.unknown().describe("Component/page the bug was attributed to, or null"),
+        note: z.string().optional().describe("Present when no Stage-2 analysis exists \u2014 explains why and what to call instead")
       }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       const s2 = report.stage2_analysis;
+      if (!s2 || s2.rootCause == null && s2.suggestedFix == null) {
+        return jsonResult({
+          reportId: args.reportId,
+          rootCause: null,
+          suggestedFix: null,
+          reproductionSteps: report.reproduction_steps ?? [],
+          summary: report.summary ?? null,
+          component: report.component ?? null,
+          note: "No Stage-2 analysis exists for this report (it was classified by the fast Stage-1 path, which does not produce root-cause/fix hints). Use triage_issue for the full review packet, or dispatch_fix \u2014 the fix worker does its own grounded analysis."
+        });
+      }
       return jsonResult({
         reportId: args.reportId,
         rootCause: s2?.rootCause ?? null,
@@ -675,7 +876,11 @@ function createMushiServer(config) {
       title: titleOf("run_nl_query"),
       description: descOf("run_nl_query"),
       annotations: annotationsFor("run_nl_query"),
-      inputSchema: { question: z.string().describe('Question in plain English, e.g. "Which components had the most critical bugs this week?"') }
+      inputSchema: {
+        question: z.string().describe(
+          'Question in plain English, e.g. "Which components had the most critical bugs this week?"'
+        )
+      }
     },
     async (args) => {
       const data = await apiCall("/v1/admin/query", {
@@ -692,7 +897,9 @@ function createMushiServer(config) {
       description: descOf("diagnose_setup"),
       annotations: annotationsFor("diagnose_setup"),
       inputSchema: {
-        mode: z.enum(["full", "ingest", "dispatch"]).optional().describe("full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."),
+        mode: z.enum(["full", "ingest", "dispatch"]).optional().describe(
+          "full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."
+        ),
         project_id: z.string().optional().describe("Project UUID for dispatch checks (defaults to configured project)."),
         projectId: z.string().optional().describe("Alias for project_id.")
       },
@@ -730,7 +937,11 @@ function createMushiServer(config) {
       }
       if (mode === "dispatch") {
         if (!resolvedId) {
-          throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required for dispatch mode");
+          throw new MushiApiError(
+            400,
+            "MISSING_PROJECT",
+            "project_id is required for dispatch mode"
+          );
         }
         const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
         const failed = data.checks.filter((c) => !c.ready);
@@ -864,7 +1075,12 @@ function createMushiServer(config) {
     async (args) => {
       const query = args.query ?? "";
       const hits = searchMushiDocs(query, args.limit ?? 8);
-      const results = hits.map(({ title, path, excerpt, score }) => ({ title, path, excerpt, score }));
+      const results = hits.map(({ title, path, excerpt, score }) => ({
+        title,
+        path,
+        excerpt,
+        score
+      }));
       return jsonResult({ query, results });
     }
   );
@@ -1014,7 +1230,9 @@ function createMushiServer(config) {
       } : { error: String(reportRes.reason) };
       return jsonText({
         evidence,
-        reporter_thread: timeline ?? { error: String(timelineRes.reason) }
+        reporter_thread: timeline ?? {
+          error: String(timelineRes.reason)
+        }
       });
     }
   );
@@ -1049,27 +1267,54 @@ function createMushiServer(config) {
       const includeLogs = args.include_logs !== false;
       const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
         apiCall(`/v1/admin/reports/${args.report_id}`, { headers }),
-        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, { headers }),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, {
+          headers
+        }),
         apiCall(`/v1/admin/reports/similarity`, {
           method: "POST",
           headers,
           body: JSON.stringify({ report_id: args.report_id })
         }).catch(() => null),
-        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(() => null),
-        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(() => null),
-        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(() => null) : Promise.resolve(null)
+        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(
+          () => null
+        ),
+        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(
+          () => null
+        ),
+        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(
+          () => null
+        ) : Promise.resolve(null)
       ]);
       const report = reportRes.status === "fulfilled" ? reportRes.value : null;
       const severity = report ? report.severity : "unknown";
       const category = report ? report.category : "unknown";
       const status = report ? report.status : "unknown";
       const actions = [];
-      if (status === "new" || status === "classified") {
+      const processingError = report ? report.processing_error : null;
+      const attempts = report ? report.fix_attempts ?? [] : [];
+      const lastAttempt = attempts.length > 0 ? attempts[attempts.length - 1] : null;
+      const lastAttemptStatus = lastAttempt ? String(lastAttempt.status ?? "") : "";
+      const autofixBlocked = typeof processingError === "string" && processingError.startsWith("autofix_blocked:") || lastAttemptStatus.startsWith("skipped") || lastAttemptStatus === "failed";
+      if (autofixBlocked && status !== "fixing" && status !== "fixed") {
+        const blockReason = typeof processingError === "string" && processingError || String(lastAttempt?.error ?? "previous fix attempt was skipped or failed");
+        actions.push({
+          action: "unblock_autofix",
+          reason: `Auto-fix is blocked: ${blockReason}. Resolve the blocker (settings/integration/budget), then re-dispatch.`,
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+        actions.push({
+          action: "redispatch_after_unblock",
+          reason: "Once the blocker above is resolved, dispatch a fresh fix attempt.",
+          tool: "dispatch_fix",
+          args: { reportId: args.report_id }
+        });
+      } else if (status === "new" || status === "classified") {
         actions.push({
           action: "dispatch_fix",
-          reason: "Report is classified but no fix has been attempted",
+          reason: "Report is classified and no fix has been attempted",
           tool: "dispatch_fix",
-          args: { reportId: args.report_id, agent: "cursor_cloud" }
+          args: { reportId: args.report_id }
         });
       } else if (status === "fixing") {
         actions.push({
@@ -1124,7 +1369,10 @@ function createMushiServer(config) {
       return {
         ...res,
         resource_links: [
-          { uri: `project://reports/${args.report_id}`, title: `Report ${args.report_id.slice(0, 8)}\u2026` },
+          {
+            uri: `project://reports/${args.report_id}`,
+            title: `Report ${args.report_id.slice(0, 8)}\u2026`
+          },
           ...pid ? [{ uri: `project://dashboard`, title: "Project dashboard" }] : []
         ]
       };
@@ -1143,7 +1391,9 @@ function createMushiServer(config) {
         filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
         linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
         summary: z.string().describe("One-line human summary of what the fix changed"),
-        idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+        idempotencyKey: z.string().uuid().optional().describe(
+          "Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows. Omit it and a stable key is derived from reportId + branch + prUrl, so a retried submission carries the identical key instead of a fresh random one."
+        )
       },
       outputSchema: {
         ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
@@ -1151,27 +1401,123 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
+      const idemKey = args.idempotencyKey ?? await stableUuidFrom(
+        IDEMPOTENCY_NAMESPACE,
+        args.reportId,
+        args.branch,
+        args.prUrl ?? ""
+      );
       const created = await apiCall("/v1/admin/fixes", {
         method: "POST",
         headers: { "Idempotency-Key": idemKey },
         body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
       });
-      await apiCall(`/v1/admin/fixes/${created.fixId}`, {
-        method: "PATCH",
-        body: JSON.stringify({
-          status: "completed",
-          branch: args.branch,
-          pr_url: args.prUrl,
-          files_changed: args.filesChanged,
-          lines_changed: args.linesChanged,
-          summary: args.summary,
-          completed_at: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      });
+      try {
+        await apiCall(`/v1/admin/fixes/${created.fixId}`, {
+          method: "PATCH",
+          body: JSON.stringify({
+            status: "completed",
+            branch: args.branch,
+            pr_url: args.prUrl,
+            files_changed: args.filesChanged,
+            lines_changed: args.linesChanged,
+            summary: args.summary,
+            completed_at: (/* @__PURE__ */ new Date()).toISOString()
+          })
+        });
+      } catch (err) {
+        const status = err instanceof MushiApiError ? err.status : 500;
+        throw new MushiApiError(
+          status,
+          "FIX_PATCH_FAILED",
+          `Fix row ${created.fixId} was created for report ${args.reportId}, but marking it completed failed: ${bareMessage(err)} \u2014 the fix row exists and is still in its initial (pending) state, so no work is lost. Preferred repair: PATCH /v1/admin/fixes/${created.fixId} with {"status":"completed"} to finish this exact row. Re-running submit_fix_result re-sends the same derived Idempotency-Key (reportId + branch + prUrl) rather than a fresh one, so it dedupes wherever the API honours that header \u2014 retry only with identical arguments.`
+        );
+      }
       return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
+  server.registerTool(
+    "triage_next_steps",
+    {
+      title: titleOf("triage_next_steps"),
+      description: descOf("triage_next_steps"),
+      annotations: annotationsFor("triage_next_steps"),
+      inputSchema: {
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      },
+      outputSchema: {
+        steps: z.array(
+          z.object({
+            priority: z.number(),
+            action: z.string(),
+            reason: z.string(),
+            tool: z.string().optional(),
+            args: z.record(z.string(), z.unknown()).optional()
+          })
+        ),
+        summary: z.string()
+      }
+    },
+    async (args) => {
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(
+        "/v1/admin/reports?limit=100",
+        { headers: extraHeaders }
+      );
+      const reports = data.reports ?? [];
+      const isCron = (r) => typeof r.reporter_token_hash === "string" && r.reporter_token_hash.startsWith("cron:");
+      const isBlocked = (r) => typeof r.processing_error === "string" && r.processing_error.startsWith("autofix_blocked:");
+      const label = (r) => String(r.title ?? r.summary ?? r.description ?? "").slice(0, 90);
+      const steps = [];
+      let priority = 1;
+      const blocked = reports.filter(isBlocked);
+      if (blocked.length > 0) {
+        steps.push({
+          priority: priority++,
+          action: `Unblock auto-fix (${blocked.length} report${blocked.length === 1 ? "" : "s"} blocked)`,
+          reason: String(blocked[0].processing_error).slice(0, 200),
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+      }
+      const fixing = reports.filter((r) => r.status === "fixing");
+      for (const r of fixing.slice(0, 2)) {
+        steps.push({
+          priority: priority++,
+          action: `Shepherd in-flight fix: ${label(r)}`,
+          reason: "A fix branch/PR is open \u2014 check CI and merge when green.",
+          tool: "get_report_timeline",
+          args: { report_id: r.id }
+        });
+      }
+      const openUserReports = reports.filter((r) => (r.status === "new" || r.status === "classified") && !isCron(r) && !isBlocked(r)).sort((a, b) => {
+        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+        return (rank[String(a.severity)] ?? 4) - (rank[String(b.severity)] ?? 4);
+      });
+      for (const r of openUserReports.slice(0, Math.max(0, 4 - steps.length))) {
+        steps.push({
+          priority: priority++,
+          action: `Triage [${r.severity}] ${label(r)}`,
+          reason: "User-felt report awaiting triage \u2014 review the packet, then dispatch or dismiss.",
+          tool: "triage_issue",
+          args: { report_id: r.id }
+        });
+      }
+      const chores = reports.filter((r) => r.status === "classified" && isCron(r) && !isBlocked(r));
+      if (chores.length > 0 && steps.length < 5) {
+        steps.push({
+          priority: priority++,
+          action: `Batch ${chores.length} maintenance chore${chores.length === 1 ? "" : "s"} (dependency bumps)`,
+          reason: "Robot-filed modernization reports \u2014 batch-dispatch or dismiss in one sitting; do not let them crowd out user bugs.",
+          tool: "get_recent_reports",
+          args: { status: "classified" }
+        });
+      }
+      const summary = steps.length === 0 ? "Inbox is clear \u2014 no blocked fixes, no open user reports, no chores. Nothing needs your attention." : `${steps.length} prioritised step${steps.length === 1 ? "" : "s"}: ` + steps.map((s) => s.action).join(" \u2192 ");
+      return jsonResult({ steps, summary });
+    }
+  );
   server.registerTool(
     "dispatch_fix",
     {
@@ -1181,8 +1527,12 @@ function createMushiServer(config) {
       inputSchema: {
         reportId: z.string().uuid().describe("Report UUID to fix"),
         agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
-        idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
-        inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")
+        idempotencyKey: z.string().uuid().optional().describe(
+          "Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."
+        ),
+        inventoryActionNodeId: z.string().uuid().optional().describe(
+          "Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR."
+        )
       },
       outputSchema: {
         fixId: z.string(),
@@ -1204,7 +1554,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({
@@ -1214,7 +1564,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(
@@ -1255,11 +1610,19 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for test_gen_from_report");
-      const data = await apiCall(`/v1/admin/inventory/${pid}/test-gen/from-report/${args.reportId}`, {
-        method: "POST",
-        body: JSON.stringify({})
-      });
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for test_gen_from_report"
+        );
+      const data = await apiCall(
+        `/v1/admin/inventory/${pid}/test-gen/from-report/${args.reportId}`,
+        {
+          method: "POST",
+          body: JSON.stringify({})
+        }
+      );
       return jsonText(data);
     }
   );
@@ -1338,7 +1701,22 @@ function createMushiServer(config) {
       annotations: annotationsFor("transition_status"),
       inputSchema: {
         reportId: z.string().describe("Report UUID"),
-        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "resolved", "verified", "reopened", "dismissed"]).describe("Target status"),
+        status: z.enum([
+          "pending",
+          "classified",
+          // Workflow states added 20260520600000 but missing from this
+          // enum ever since (2026-08-16 audit P2-2) — agents could not
+          // mark a report as being looked at.
+          "triaged",
+          "in_progress",
+          "grouped",
+          "fixing",
+          "fixed",
+          "resolved",
+          "verified",
+          "reopened",
+          "dismissed"
+        ]).describe("Target status (resolved is stored as fixed)"),
         reason: z.string().optional().describe("Reason for the transition (audit trail)")
       }
     },
@@ -1362,7 +1740,12 @@ function createMushiServer(config) {
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for setup_repo_for_mushi");
+      if (!pid)
+        throw new MushiApiError(
+          400,
+          "MISSING_PROJECT",
+          "projectId is required for setup_repo_for_mushi"
+        );
       const data = await apiCall(`/v1/admin/projects/${pid}/repo/bootstrap`, {
         method: "POST",
         body: JSON.stringify({})
@@ -1427,23 +1810,45 @@ function createMushiServer(config) {
     "project://stats",
     { description: "Report counts, category breakdown, severity distribution" },
     async () => ({
-      contents: [{ uri: "project://stats", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2) }]
+      contents: [
+        {
+          uri: "project://stats",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
     "project_settings",
     "project://settings",
-    { description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets" },
+    {
+      description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets"
+    },
     async () => ({
-      contents: [{ uri: "project://settings", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2) }]
+      contents: [
+        {
+          uri: "project://settings",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
     "project_dashboard",
     "project://dashboard",
-    { description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)" },
+    {
+      description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)"
+    },
     async () => ({
-      contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
+      contents: [
+        {
+          uri: "project://dashboard",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2)
+        }
+      ]
     })
   );
   server.registerTool(
@@ -1458,14 +1863,16 @@ function createMushiServer(config) {
       }
     },
     async ({ limit, range }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.registerTool(
@@ -1481,18 +1888,20 @@ function createMushiServer(config) {
       }
     },
     async ({ external_user_id, points, reason }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall("/v1/admin/rewards/bonus-points", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ external_user_id, points, reason })
-          }),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall("/v1/admin/rewards/bonus-points", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ external_user_id, points, reason })
+            }),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.registerTool(
@@ -1508,18 +1917,20 @@ function createMushiServer(config) {
       }
     },
     async ({ external_user_id, tier_slug, reason }) => ({
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          await apiCall("/v1/admin/rewards/set-tier", {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ external_user_id, tier_slug, reason })
-          }),
-          null,
-          2
-        )
-      }]
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            await apiCall("/v1/admin/rewards/set-tier", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ external_user_id, tier_slug, reason })
+            }),
+            null,
+            2
+          )
+        }
+      ]
     })
   );
   server.resource(
@@ -1529,11 +1940,13 @@ function createMushiServer(config) {
       description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp."
     },
     async () => ({
-      contents: [{
-        uri: "privacy://status",
-        mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/privacy-status"), null, 2)
-      }]
+      contents: [
+        {
+          uri: "privacy://status",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/privacy-status"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -1543,15 +1956,19 @@ function createMushiServer(config) {
       description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling."
     },
     async () => ({
-      contents: [{
-        uri: "evolution://history",
-        mimeType: "application/json",
-        text: projectId ? JSON.stringify(
-          await apiCall(`/v1/admin/projects/${encodeURIComponent(projectId)}/evolution-history`),
-          null,
-          2
-        ) : JSON.stringify({ ok: false, error: "project_id required" })
-      }]
+      contents: [
+        {
+          uri: "evolution://history",
+          mimeType: "application/json",
+          text: projectId ? JSON.stringify(
+            await apiCall(
+              `/v1/admin/projects/${encodeURIComponent(projectId)}/evolution-history`
+            ),
+            null,
+            2
+          ) : JSON.stringify({ ok: false, error: "project_id required" })
+        }
+      ]
     })
   );
   server.resource(
@@ -1561,11 +1978,13 @@ function createMushiServer(config) {
       description: "Live health status of every configured BYOK channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Orchestrators should check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run."
     },
     async () => ({
-      contents: [{
-        uri: "project://integration-health",
-        mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
-      }]
+      contents: [
+        {
+          uri: "project://integration-health",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
+        }
+      ]
     })
   );
   server.resource(
@@ -1577,11 +1996,13 @@ function createMushiServer(config) {
     async () => {
       const path = projectId ? `/v1/admin/inventory/${projectId}` : "/v1/admin/inventory";
       return {
-        contents: [{
-          uri: "inventory://current",
-          mimeType: "application/json",
-          text: JSON.stringify(await apiCall(path), null, 2)
-        }]
+        contents: [
+          {
+            uri: "inventory://current",
+            mimeType: "application/json",
+            text: JSON.stringify(await apiCall(path), null, 2)
+          }
+        ]
       };
     }
   );
@@ -1610,11 +2031,13 @@ function createMushiServer(config) {
     async () => {
       const qs = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
       return {
-        contents: [{
-          uri: "mushi://activation",
-          mimeType: "application/json",
-          text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), null, 2)
-        }]
+        contents: [
+          {
+            uri: "mushi://activation",
+            mimeType: "application/json",
+            text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), null, 2)
+          }
+        ]
       };
     }
   );
@@ -1623,11 +2046,12 @@ function createMushiServer(config) {
     "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
     { reportId: z.string().describe("The report UUID to summarize") },
     ({ reportId }) => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
 1. Call get_fix_context for reportId "${reportId}".
 2. Call get_blast_radius if the report has a component node id.
 3. Call get_similar_bugs with the component or summary as the query.
@@ -1640,8 +2064,9 @@ Then produce a markdown fix plan with exactly these sections:
 - Confidence (low/medium/high) with a one-line justification
 
 Lead with the fix. Skip the preamble.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -1649,11 +2074,12 @@ Lead with the fix. Skip the preamble.`
     "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
     { fixId: z.string().describe("The fix_attempt UUID to explain") },
     ({ fixId }) => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a release engineer. Use the Mushi MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a release engineer. Use the Mushi MCP tools:
 1. Call get_fix_timeline for fixId "${fixId}" to see the full PDCA journey.
 
 Then write a short verdict in this format:
@@ -1662,8 +2088,9 @@ Then write a short verdict in this format:
 - **If iterate:** bullet list of the smallest next patch
 
 No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -1671,11 +2098,12 @@ No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
     'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
     {},
     () => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
 1. Read the project://dashboard resource for the PDCA snapshot.
 2. Call get_recent_reports with status="classified", limit=10.
 
@@ -1683,8 +2111,9 @@ Then output exactly 5 bullets, in priority order, each formatted as:
 \`**Action** \u2014 why it matters \u2014 suggested tool call\`
 
 Prefer items that are bottlenecks or critical severity. Skip filler.`
+          }
         }
-      }]
+      ]
     })
   );
   server.prompt(
@@ -1692,11 +2121,12 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
     "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
     {},
     () => ({
-      messages: [{
-        role: "user",
-        content: {
-          type: "text",
-          text: `You are a Mushi onboarding copilot. Use the MCP tools:
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are a Mushi onboarding copilot. Use the MCP tools:
 1. Read mushi://activation for unified setup posture.
 2. Read project://integration-health if GitHub or Sentry looks blocked.
 3. Call diagnose_setup if the resource is unavailable.
@@ -1708,8 +2138,9 @@ Then output:
 - **If still stuck:** one diagnostic command (e.g. mushi doctor --fix)
 
 Be specific. No generic advice.`
+          }
         }
-      }]
+      ]
     })
   );
   server.registerTool(
@@ -1730,7 +2161,15 @@ Be specific. No generic advice.`
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
       const data = await apiCall(
         `/v1/admin/inventory/${projectId2}/map-from-live`,
-        { method: "POST", body: JSON.stringify({ base_url: baseUrl, max_pages: maxPages, provider, cursor_cloud_refine: cursorCloudRefine }) }
+        {
+          method: "POST",
+          body: JSON.stringify({
+            base_url: baseUrl,
+            max_pages: maxPages,
+            provider,
+            cursor_cloud_refine: cursorCloudRefine
+          })
+        }
       );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
@@ -1758,7 +2197,9 @@ Be specific. No generic advice.`
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
         projectId: z.string().describe("Project UUID that owns the inventory story"),
-        storyNodeId: z.string().describe("User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"),
+        storyNodeId: z.string().describe(
+          "User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"
+        ),
         automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
         baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
         openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
@@ -1772,10 +2213,14 @@ Be specific. No generic advice.`
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
-      const data = await apiCall(
-        `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
-        { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
-      );
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`, {
+        method: "POST",
+        body: JSON.stringify({
+          automation_mode: automationMode,
+          base_url: baseUrl,
+          open_pr: openPr
+        })
+      });
       return jsonResult(data);
     }
   );
@@ -1790,10 +2235,10 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(
-        "/v1/admin/pdca/improve-qa-stories",
-        { method: "POST", body: JSON.stringify({ project_id: projectId2 }) }
-      );
+      const data = await apiCall("/v1/admin/pdca/improve-qa-stories", {
+        method: "POST",
+        body: JSON.stringify({ project_id: projectId2 })
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -1827,7 +2272,9 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(`/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`);
+      const data = await apiCall(
+        `/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`
+      );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -1840,16 +2287,60 @@ Be specific. No generic advice.`
       inputSchema: {
         projectId: z.string().describe("Project id"),
         provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
-        key: z.string().min(10).describe("The API key value to add"),
+        key: z.string().min(8).max(4096).describe("The API key value to add"),
         label: z.string().optional().describe("Human-readable label for this key"),
-        priority: z.number().int().min(1).max(999).optional().describe("Priority for ordering (lower = higher priority)")
+        priority: z.number().int().min(0).max(1e4).optional().describe("Priority for ordering (lower = higher priority)"),
+        baseUrl: z.string().url().max(2048).optional().describe("Allow-listed OpenAI-compatible HTTPS base URL")
       }
     },
-    async ({ projectId: projectId2, provider, key, label, priority }) => {
-      const data = await apiCall(
-        "/v1/admin/byok/keys",
-        { method: "POST", body: JSON.stringify({ project_id: projectId2, provider_slug: provider, key, label, priority }) }
-      );
+    async ({ projectId: projectId2, provider, key, label, priority, baseUrl }) => {
+      const data = await apiCall("/v1/admin/byok/keys", {
+        method: "POST",
+        body: JSON.stringify({
+          project_id: projectId2,
+          provider_slug: provider,
+          key,
+          label,
+          priority,
+          base_url: baseUrl
+        })
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "test_byok_key",
+    {
+      title: titleOf("test_byok_key", TDD_TOOL_CATALOG),
+      description: descOf("test_byok_key", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("test_byok_key", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        keyId: z.string().uuid().describe("Pooled BYOK key id")
+      }
+    },
+    async ({ keyId }) => {
+      const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}/test`, {
+        method: "POST"
+      });
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "remove_byok_key",
+    {
+      title: titleOf("remove_byok_key", TDD_TOOL_CATALOG),
+      description: descOf("remove_byok_key", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("remove_byok_key", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        keyId: z.string().uuid().describe("Pooled BYOK key UUID from list_byok_keys")
+      }
+    },
+    async ({ keyId }) => {
+      const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}`, {
+        method: "DELETE"
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -1864,7 +2355,9 @@ Be specific. No generic advice.`
       }
     },
     async ({ projectId: projectId2 }) => {
-      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/pending-review`);
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/stories/pending-review`
+      );
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -1901,13 +2394,10 @@ Be specific. No generic advice.`
       }
     },
     async ({ reportId, message, authorName }) => {
-      const data = await apiCall(
-        `/v1/sync/reports/${reportId}/reply`,
-        {
-          method: "POST",
-          body: JSON.stringify({ message, author_name: authorName })
-        }
-      );
+      const data = await apiCall(`/v1/sync/reports/${reportId}/reply`, {
+        method: "POST",
+        body: JSON.stringify({ message, author_name: authorName })
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -1986,10 +2476,10 @@ Be specific. No generic advice.`
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
-      const data = await apiCall(
-        `/v1/admin/projects/${pid}/audit`,
-        { method: "POST", body: "{}" }
-      );
+      const data = await apiCall(`/v1/admin/projects/${pid}/audit`, {
+        method: "POST",
+        body: "{}"
+      });
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     }
   );
@@ -2085,17 +2575,19 @@ Be specific. No generic advice.`
       inputSchema: {
         root_skill_slug: z.string().describe('Root skill slug to run, e.g. "workflow-fix-and-ship"'),
         report_id: z.string().optional().describe("Report UUID to attach the pipeline to"),
-        mode: z.enum(["handoff", "cloud"]).optional().describe("handoff (default): get context packet for local agent. cloud: auto-dispatch via Cursor Cloud."),
+        mode: z.enum(["handoff", "cloud"]).optional().describe(
+          "handoff (default): get context packet for local agent. cloud: auto-dispatch via Cursor Cloud."
+        ),
         project_id: z.string().optional().describe("Project UUID. Falls back to the configured project.")
       }
     },
     async (args) => {
       const resolvedProjectId = args.project_id ?? projectId;
       if (!resolvedProjectId) return jsonText({ error: "No project_id provided or configured." });
-      const data = await apiCall(
-        "/v1/admin/skills/pipelines",
-        { method: "POST", body: JSON.stringify({ ...args, project_id: resolvedProjectId }) }
-      );
+      const data = await apiCall("/v1/admin/skills/pipelines", {
+        method: "POST",
+        body: JSON.stringify({ ...args, project_id: resolvedProjectId })
+      });
       return jsonText(data);
     }
   );
@@ -2131,10 +2623,10 @@ Be specific. No generic advice.`
     },
     async (args) => {
       const { run_id, step_index, ...body } = args;
-      await apiCall(
-        `/v1/admin/skills/pipelines/${run_id}/steps/${step_index}/checkin`,
-        { method: "POST", body: JSON.stringify(body) }
-      );
+      await apiCall(`/v1/admin/skills/pipelines/${run_id}/steps/${step_index}/checkin`, {
+        method: "POST",
+        body: JSON.stringify(body)
+      });
       return jsonText({ ok: true, message: `Step ${step_index} \u2192 ${args.status}` });
     }
   );
@@ -2302,7 +2794,11 @@ Be specific. No generic advice.`
       if (args.compare) qs.set("compare", args.compare);
       if (args.fix_id) qs.set("fix_id", args.fix_id);
       if (!qs.toString()) {
-        throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
+        throw new MushiApiError(
+          400,
+          "BAD_REQUEST",
+          "Provide paths, source=last_push, compare, or fix_id"
+        );
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
       return jsonResult(data);
@@ -2354,7 +2850,7 @@ Be specific. No generic advice.`
         "### First step",
         `Call \`${cluster.tools[0]}\` to get started.`,
         "",
-        "> Tip: call any tool by name \u2014 `use_mushi` is a read-only helper that never calls other tools itself. All 68 tools remain available."
+        "> Tip: call any tool by name \u2014 `use_mushi` is a read-only helper that never calls other tools itself. All 71 tools remain available."
       ].join("\n");
       return { content: [{ type: "text", text: orientation }] };
     }
@@ -2363,11 +2859,7 @@ Be specific. No generic advice.`
   const featureFilter = config.features ?? "all";
   if (grantedScopes !== void 0 || featureFilter !== "all") {
     const toolRegistry = server._registeredTools;
-    const allSpecs = [
-      ...TOOL_CATALOG,
-      ...TDD_TOOL_CATALOG,
-      ...CODEBASE_TOOL_CATALOG
-    ];
+    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG, ...CODEBASE_TOOL_CATALOG];
     for (const spec of allSpecs) {
       if (grantedScopes !== void 0 && !grantedScopes.includes(spec.scope)) {
         toolRegistry[spec.name]?.remove();
@@ -2440,5 +2932,6 @@ Be specific. No generic advice.`
 }
 export {
   MushiApiError,
-  createMushiServer
+  createMushiServer,
+  resolveTimeoutMsFromEnv
 };