@mushi-mushi/mcp 0.20.1 → 0.20.2

package/dist/index.js

@@ -8,6 +8,72 @@ import { join } from "path";
 import { homedir } from "os";
 import { createLogger as createLogger2, DEFAULT_API_ENDPOINT } from "@mushi-mushi/core";
 
+// src/stdout-guard.ts
+import { Console } from "console";
+var GUARDED_CONSOLE_METHODS = [
+  "log",
+  "info",
+  "debug",
+  "dir",
+  "dirxml",
+  "table",
+  "group",
+  "groupCollapsed",
+  "groupEnd",
+  "count",
+  "countReset",
+  "time",
+  "timeEnd",
+  "timeLog",
+  "trace",
+  "assert",
+  "warn",
+  "error"
+];
+var installed = false;
+function installStdoutGuard() {
+  if (installed) return false;
+  if (typeof process !== "undefined" && process.env?.MUSHI_MCP_STDOUT_GUARD === "off") {
+    return false;
+  }
+  if (typeof process === "undefined" || typeof process.stderr?.write !== "function" || typeof console === "undefined") {
+    return false;
+  }
+  try {
+    const stderrConsole = new Console({
+      stdout: process.stderr,
+      stderr: process.stderr,
+      // Colour codes would land in the client's log pane as escape noise.
+      colorMode: false
+    });
+    const target = console;
+    const source = stderrConsole;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      const fn = source[method];
+      if (typeof fn === "function") {
+        target[method] = fn.bind(stderrConsole);
+      }
+    }
+  } catch {
+    const write = (...args) => process.stderr.write(
+      args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ") + "\n"
+    );
+    const target = console;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      target[method] = write;
+    }
+  }
+  installed = true;
+  return true;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
 // src/catalog.ts
 var ALL_SCOPES = ["mcp:read", "mcp:write"];
 var TOOL_CATALOG = [
@@ -170,7 +236,7 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: 'Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent (default uses the in-repo worker). Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixAttemptId }; poll get_fix_timeline for progress and merge_fix when CI is green. Write; NOT idempotent \u2014 each call starts a new attempt. Report must be classified \u2014 run triage_issue if not.',
+    description: 'Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent (default uses the in-repo worker). Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixId, status } (fixId is the dispatch id; get_fix_timeline accepts it immediately); poll get_fix_timeline for progress and merge_fix when CI is green. Write; pass the same idempotencyKey to retry safely \u2014 without it each call starts a new attempt. Report must be classified \u2014 run triage_issue if not.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
@@ -305,6 +371,14 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Analyze this bug report end-to-end and tell me what to do."
   },
+  {
+    name: "triage_next_steps",
+    title: "What should I work on now?",
+    description: 'Prioritised "do this next" list for the project: blocked auto-fixes first (with the unblock action), then in-flight fixes to shepherd to merge, then user-felt classified reports by severity, with robot/cron chores (dependency bumps) last. Returns { steps: [{ priority, action, reason, tool, args }], summary }. Read-only. Call this first when the user asks "what needs my attention / what should I triage or fix".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What should I triage or fix right now?"
+  },
   // ── Lessons / evolution loop ─────────────────────────────────────────────
   {
     name: "query_lessons",
@@ -546,24 +620,29 @@ var TDD_TOOL_CATALOG = [
   }
 ];
 var USE_MUSHI_INTENTS = {
+  // NOTE: every name below MUST be a registered TOOL (scopes.test.ts guards
+  // this). 2026-08-16 audit P0-3 found phantom names (get_report,
+  // get_dashboard, list_qa_stories) and prompts listed as tools
+  // (summarize_report_for_fix, mushi_setup) — agents routed here then
+  // failed the call and gave up.
   fix: {
     label: "Fix a bug",
     tools: [
       "get_recent_reports",
-      "get_report",
-      "summarize_report_for_fix",
+      "get_report_detail",
+      "triage_issue",
       "dispatch_fix",
       "start_skill_pipeline",
       "checkin_pipeline_step",
       "get_pipeline_run"
     ],
-    hint: "Call get_recent_reports to find the top unresolved bug, then summarize_report_for_fix before dispatching."
+    hint: "Call get_recent_reports to find the top unresolved bug, then triage_issue before dispatching."
   },
   status: {
     label: "Check project status",
     tools: [
-      "get_dashboard",
       "triage_next_steps",
+      "get_account_overview",
       "get_usage",
       "get_backend_health",
       "activation_status"
@@ -573,7 +652,7 @@ var USE_MUSHI_INTENTS = {
   setup: {
     label: "Set up Mushi",
     tools: [
-      "mushi_setup",
+      "diagnose_setup",
       "activation_status",
       "get_backend_health",
       "list_byok_keys",
@@ -581,12 +660,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 +672,7 @@ var USE_MUSHI_INTENTS = {
       "approve_qa_story",
       "improve_qa_story"
     ],
-    hint: "Call list_qa_stories to see what test coverage exists; run_qa_story to trigger a run."
+    hint: "Call list_qa_story_runs to see recent coverage and outcomes; run_qa_story to trigger a run."
   },
   pipeline: {
     label: "Run an agent pipeline / skill",
@@ -609,7 +687,7 @@ var USE_MUSHI_INTENTS = {
   },
   audit: {
     label: "Audit / health check",
-    tools: ["run_fullstack_audit", "get_backend_health", "get_dashboard", "get_usage"],
+    tools: ["run_fullstack_audit", "get_backend_health", "get_account_overview", "get_usage"],
     hint: "Call run_fullstack_audit for a full-stack health scorecard."
   }
 };
@@ -981,7 +1059,40 @@ function wrapUntrustedJson(value, role) {
 }
 
 // src/server.ts
+installStdoutGuard();
 var NO_ARG_INPUT = {};
+var DEFAULT_API_TIMEOUT_MS = 15e3;
+var MIN_API_TIMEOUT_MS = 250;
+var MAX_API_TIMEOUT_MS = 3e5;
+function resolveTimeoutMsFromEnv() {
+  const raw = process.env?.MUSHI_MCP_TIMEOUT_MS?.trim();
+  if (!raw) return DEFAULT_API_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
+  return Math.min(Math.max(parsed, MIN_API_TIMEOUT_MS), MAX_API_TIMEOUT_MS);
+}
+function bareMessage(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  return raw.replace(/^\[[A-Z0-9_]+\]\s*/, "");
+}
+var IDEMPOTENCY_NAMESPACE = "mushi.mcp.submit_fix_result.v1";
+async function stableUuidFrom(...parts) {
+  const input = parts.join("");
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input))
+  );
+  const bytes = digest.slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function withTimeoutSignal(callerSignal, timeoutSignal) {
+  if (!callerSignal) return timeoutSignal;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function") return anyFn.call(AbortSignal, [callerSignal, timeoutSignal]);
+  return timeoutSignal;
+}
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -995,6 +1106,7 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : resolveTimeoutMsFromEnv();
   const apiLog = createLogger({
     scope: "mushi:mcp:api",
     level: process.env.MUSHI_LOG_LEVEL ?? "info",
@@ -1012,22 +1124,66 @@ function createMushiServer(config) {
   async function apiCall(path, options) {
     const requestId = crypto.randomUUID().slice(0, 12);
     const started = Date.now();
-    const res = await doFetch(`${apiEndpoint}${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
-        // still send it for endpoints still behind plain `jwtAuth` (legacy)
-        // and for transparent proxies that strip X-Mushi-* headers.
-        Authorization: `Bearer ${apiKey}`,
-        "X-Mushi-Api-Key": apiKey,
-        "X-Request-Id": requestId,
-        ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
-        ...options?.headers ?? {}
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    let res;
+    try {
+      res = await doFetch(`${apiEndpoint}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
+          // still send it for endpoints still behind plain `jwtAuth` (legacy)
+          // and for transparent proxies that strip X-Mushi-* headers.
+          Authorization: `Bearer ${apiKey}`,
+          "X-Mushi-Api-Key": apiKey,
+          "X-Request-Id": requestId,
+          ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
+          ...options?.headers ?? {}
+        },
+        // After the spread so a caller-supplied `signal` is merged, not lost.
+        signal: withTimeoutSignal(options?.signal, timeoutSignal)
+      });
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    function classifyTransportError(err) {
+      const durationMs2 = Date.now() - started;
+      if (timeoutSignal.aborted) {
+        apiLog.warn("api.timeout", { path, requestId, durationMs: durationMs2, timeoutMs });
+        return new MushiApiError(
+          504,
+          "MUSHI_TIMEOUT",
+          `Timed out after ${timeoutMs}ms waiting for ${path}. The Mushi API accepted the connection but did not answer in time \u2014 retry, or raise the budget with MUSHI_MCP_TIMEOUT_MS (ms) in your MCP env block if you self-host and cold starts are slow. Endpoint: ${apiEndpoint}`
+        );
       }
-    });
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError") {
+        apiLog.warn("api.aborted", { path, requestId, durationMs: durationMs2 });
+        return new MushiApiError(
+          499,
+          "REQUEST_ABORTED",
+          `The request to ${path} was aborted by the caller after ${durationMs2}ms.`
+        );
+      }
+      apiLog.warn("api.unreachable", {
+        path,
+        requestId,
+        durationMs: durationMs2,
+        err: bareMessage(err)
+      });
+      return new MushiApiError(
+        503,
+        "NETWORK_ERROR",
+        `Could not reach the Mushi API at ${apiEndpoint}${path} \u2014 ${bareMessage(err)}. This is a connectivity failure, not an API rejection: check that you are online, that MUSHI_API_ENDPOINT points at your \`.../functions/v1/api\` URL, and that no proxy/VPN is blocking it.`
+      );
+    }
     const durationMs = Date.now() - started;
-    const text = await res.text();
     let body = null;
     if (text) {
       try {
@@ -1057,6 +1213,7 @@ function createMushiServer(config) {
     apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  let resolvedAccountProjectId = null;
   async function resolveProjectId(explicitId) {
     if (explicitId) {
       if (projectId && explicitId !== projectId) {
@@ -1069,10 +1226,12 @@ function createMushiServer(config) {
       return explicitId;
     }
     if (projectId) return projectId;
+    if (resolvedAccountProjectId) return resolvedAccountProjectId;
     try {
       const data = await apiCall("/v1/admin/mcp/account-overview");
       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 +1247,27 @@ function createMushiServer(config) {
         `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
       );
     } catch (err) {
-      if (err instanceof MushiApiError) throw err;
+      if (err instanceof MushiApiError) {
+        if (err.code === "MUSHI_TIMEOUT" || err.code === "NETWORK_ERROR") {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `Could not resolve which project to use because the Mushi API is unreachable: ${bareMessage(err)} This is a connectivity problem \u2014 setting MUSHI_PROJECT_ID would only skip the lookup, not fix the tool call that follows it.`
+          );
+        }
+        if (err.status === 401 || err.status === 403) {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `The API key was rejected while resolving the project: ${bareMessage(err)} Mint a fresh key in the console (Settings \u2192 API keys) and update MUSHI_API_KEY, or re-run \`mushi login\`. This is an authentication problem, not a missing project id.`
+          );
+        }
+        throw err;
+      }
       throw new MushiApiError(
         400,
         "MISSING_PROJECT_ID",
-        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+        `projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly. (Project lookup failed with: ${bareMessage(err)})`
       );
     }
   }
@@ -1516,12 +1691,24 @@ function createMushiServer(config) {
         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,
@@ -1952,12 +2139,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({
@@ -2035,7 +2241,7 @@ 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: {
@@ -2044,27 +2250,123 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
+      const idemKey = args.idempotencyKey ?? await stableUuidFrom(
+        IDEMPOTENCY_NAMESPACE,
+        args.reportId,
+        args.branch,
+        args.prUrl ?? ""
+      );
       const created = await apiCall("/v1/admin/fixes", {
         method: "POST",
         headers: { "Idempotency-Key": idemKey },
         body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
       });
-      await apiCall(`/v1/admin/fixes/${created.fixId}`, {
-        method: "PATCH",
-        body: JSON.stringify({
-          status: "completed",
-          branch: args.branch,
-          pr_url: args.prUrl,
-          files_changed: args.filesChanged,
-          lines_changed: args.linesChanged,
-          summary: args.summary,
-          completed_at: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      });
+      try {
+        await apiCall(`/v1/admin/fixes/${created.fixId}`, {
+          method: "PATCH",
+          body: JSON.stringify({
+            status: "completed",
+            branch: args.branch,
+            pr_url: args.prUrl,
+            files_changed: args.filesChanged,
+            lines_changed: args.linesChanged,
+            summary: args.summary,
+            completed_at: (/* @__PURE__ */ new Date()).toISOString()
+          })
+        });
+      } catch (err) {
+        const status = err instanceof MushiApiError ? err.status : 500;
+        throw new MushiApiError(
+          status,
+          "FIX_PATCH_FAILED",
+          `Fix row ${created.fixId} was created for report ${args.reportId}, but marking it completed failed: ${bareMessage(err)} \u2014 the fix row exists and is still in its initial (pending) state, so no work is lost. Preferred repair: PATCH /v1/admin/fixes/${created.fixId} with {"status":"completed"} to finish this exact row. Re-running submit_fix_result re-sends the same derived Idempotency-Key (reportId + branch + prUrl) rather than a fresh one, so it dedupes wherever the API honours that header \u2014 retry only with identical arguments.`
+        );
+      }
       return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
+  server.registerTool(
+    "triage_next_steps",
+    {
+      title: titleOf("triage_next_steps"),
+      description: descOf("triage_next_steps"),
+      annotations: annotationsFor("triage_next_steps"),
+      inputSchema: {
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      },
+      outputSchema: {
+        steps: z.array(
+          z.object({
+            priority: z.number(),
+            action: z.string(),
+            reason: z.string(),
+            tool: z.string().optional(),
+            args: z.record(z.string(), z.unknown()).optional()
+          })
+        ),
+        summary: z.string()
+      }
+    },
+    async (args) => {
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(
+        "/v1/admin/reports?limit=100",
+        { headers: extraHeaders }
+      );
+      const reports = data.reports ?? [];
+      const isCron = (r) => typeof r.reporter_token_hash === "string" && r.reporter_token_hash.startsWith("cron:");
+      const isBlocked = (r) => typeof r.processing_error === "string" && r.processing_error.startsWith("autofix_blocked:");
+      const label = (r) => String(r.title ?? r.summary ?? r.description ?? "").slice(0, 90);
+      const steps = [];
+      let priority = 1;
+      const blocked = reports.filter(isBlocked);
+      if (blocked.length > 0) {
+        steps.push({
+          priority: priority++,
+          action: `Unblock auto-fix (${blocked.length} report${blocked.length === 1 ? "" : "s"} blocked)`,
+          reason: String(blocked[0].processing_error).slice(0, 200),
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+      }
+      const fixing = reports.filter((r) => r.status === "fixing");
+      for (const r of fixing.slice(0, 2)) {
+        steps.push({
+          priority: priority++,
+          action: `Shepherd in-flight fix: ${label(r)}`,
+          reason: "A fix branch/PR is open \u2014 check CI and merge when green.",
+          tool: "get_report_timeline",
+          args: { report_id: r.id }
+        });
+      }
+      const openUserReports = reports.filter((r) => (r.status === "new" || r.status === "classified") && !isCron(r) && !isBlocked(r)).sort((a, b) => {
+        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+        return (rank[String(a.severity)] ?? 4) - (rank[String(b.severity)] ?? 4);
+      });
+      for (const r of openUserReports.slice(0, Math.max(0, 4 - steps.length))) {
+        steps.push({
+          priority: priority++,
+          action: `Triage [${r.severity}] ${label(r)}`,
+          reason: "User-felt report awaiting triage \u2014 review the packet, then dispatch or dismiss.",
+          tool: "triage_issue",
+          args: { report_id: r.id }
+        });
+      }
+      const chores = reports.filter((r) => r.status === "classified" && isCron(r) && !isBlocked(r));
+      if (chores.length > 0 && steps.length < 5) {
+        steps.push({
+          priority: priority++,
+          action: `Batch ${chores.length} maintenance chore${chores.length === 1 ? "" : "s"} (dependency bumps)`,
+          reason: "Robot-filed modernization reports \u2014 batch-dispatch or dismiss in one sitting; do not let them crowd out user bugs.",
+          tool: "get_recent_reports",
+          args: { status: "classified" }
+        });
+      }
+      const summary = steps.length === 0 ? "Inbox is clear \u2014 no blocked fixes, no open user reports, no chores. Nothing needs your attention." : `${steps.length} prioritised step${steps.length === 1 ? "" : "s"}: ` + steps.map((s) => s.action).join(" \u2192 ");
+      return jsonResult({ steps, summary });
+    }
+  );
   server.registerTool(
     "dispatch_fix",
     {
@@ -2101,7 +2403,7 @@ function createMushiServer(config) {
         } catch {
         }
       }
-      const data = await apiCall("/v1/admin/fixes/dispatch", {
+      const dispatch = await apiCall("/v1/admin/fixes/dispatch", {
         method: "POST",
         headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
         body: JSON.stringify({
@@ -2111,7 +2413,12 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonResult(data);
+      if (!dispatch?.dispatchId) {
+        throw new Error(
+          `Dispatch response missing dispatchId \u2014 got: ${JSON.stringify(dispatch).slice(0, 300)}`
+        );
+      }
+      return jsonResult({ fixId: dispatch.dispatchId, status: dispatch.status ?? "queued" });
     }
   );
   server.registerTool(
@@ -2246,6 +2553,11 @@ function createMushiServer(config) {
         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,7 +2565,7 @@ 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)")
       }
     },
@@ -3470,28 +3782,30 @@ Be specific. No generic advice.`
 
 // src/index.ts
 import * as Sentry from "@sentry/node";
-var _writeStderr = (...args) => process.stderr.write(
-  args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") + "\n"
-);
-console.log = _writeStderr;
-console.warn = _writeStderr;
+installStdoutGuard();
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
 var log = createLogger2({ scope: "mushi:mcp", level: "info", destination: "stderr" });
+function resolveCliConfigPath() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const appData = process.env.APPDATA;
+  const base = xdg && xdg.length > 0 ? xdg : process.platform === "win32" && appData && appData.length > 0 ? appData : join(homedir(), ".config");
+  return join(base, "mushi", "config.json");
+}
 function readCliConfig() {
+  const configPath = resolveCliConfigPath();
   try {
-    const xdg = process.env.XDG_CONFIG_HOME;
-    const appData = process.env.APPDATA;
-    const base = xdg && xdg.length > 0 ? xdg : process.platform === "win32" && appData && appData.length > 0 ? appData : join(homedir(), ".config");
-    const raw = readFileSync(join(base, "mushi", "config.json"), "utf8");
+    const raw = readFileSync(configPath, "utf8");
     const parsed = JSON.parse(raw);
     return {
       apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
       projectId: typeof parsed.projectId === "string" ? parsed.projectId : void 0,
-      endpoint: typeof parsed.endpoint === "string" ? parsed.endpoint : void 0
+      endpoint: typeof parsed.endpoint === "string" ? parsed.endpoint : void 0,
+      path: configPath,
+      found: true
     };
   } catch {
-    return {};
+    return { path: configPath, found: false };
   }
 }
 var CLI_CONFIG = readCliConfig();
@@ -3510,11 +3824,49 @@ if (MCP_SENTRY_DSN) {
     tracesSampleRate: 0
   });
 }
+function missingApiKeyReport() {
+  const envState = process.env.MUSHI_API_KEY === void 0 ? "not set" : process.env.MUSHI_API_KEY.trim() === "" ? "set but empty" : "set";
+  const cliState = !CLI_CONFIG.found ? "no file at this path" : CLI_CONFIG.apiKey ? "present" : 'file exists but has no "apiKey" field';
+  return [
+    "",
+    "[mushi-mcp] FATAL: no API key \u2014 the MCP server cannot serve a single tool call.",
+    "",
+    "  Sources checked, in precedence order:",
+    `    1. env MUSHI_API_KEY        \u2192 ${envState}`,
+    `    2. CLI config file          \u2192 ${cliState}`,
+    `       ${CLI_CONFIG.path}`,
+    "",
+    "  Fix either one:",
+    "    \u2022 Run `mushi login` (writes the config file above), or",
+    '    \u2022 Add the key to the "env" block of your MCP client config',
+    "      (.cursor/mcp.json \xB7 claude_desktop_config.json \xB7 .vscode/mcp.json):",
+    "",
+    '        { "mcpServers": { "mushi-mushi": {',
+    '            "command": "npx", "args": ["-y", "@mushi-mushi/mcp"],',
+    '            "env": { "MUSHI_API_KEY": "mushi_\u2026", "MUSHI_PROJECT_ID": "<uuid>" } } } }',
+    "",
+    "      A key exported in your shell does NOT reach the server: MCP clients",
+    "      spawn this process with only the env block they are given.",
+    "",
+    "  Other env vars this server reads:",
+    `    MUSHI_API_ENDPOINT  ${process.env.MUSHI_API_ENDPOINT?.trim() ? "= " + process.env.MUSHI_API_ENDPOINT.trim() : `unset \u2192 ${API_ENDPOINT}`}`,
+    `    MUSHI_PROJECT_ID    ${PROJECT_ID ? "= " + PROJECT_ID : "unset (account mode)"}`,
+    "    MUSHI_SCOPES        optional CSV: mcp:read,mcp:write",
+    '    MUSHI_FEATURES      optional CSV of tool groups, or "all"',
+    "    MUSHI_MCP_TIMEOUT_MS  optional per-request timeout in ms (default 15000)",
+    "",
+    "  Mint a key: Console \u2192 Settings \u2192 API keys.",
+    ""
+  ].join("\n");
+}
 async function main() {
   if (!API_KEY) {
-    log.fatal(
-      "No API key found \u2014 set MUSHI_API_KEY, or run `mushi login` so the CLI config can supply it."
-    );
+    process.stderr.write(missingApiKeyReport());
+    log.fatal("No API key found \u2014 set MUSHI_API_KEY, or run `mushi login`.", {
+      cliConfigPath: CLI_CONFIG.path,
+      cliConfigFound: CLI_CONFIG.found,
+      endpoint: API_ENDPOINT
+    });
     process.exit(1);
   }
   if (!process.env.MUSHI_API_KEY && CLI_CONFIG.apiKey) {
@@ -3561,6 +3913,7 @@ async function main() {
     if (pollTimer) clearInterval(pollTimer);
     void transport.close().finally(() => process.exit(exitCode));
   };
+  setActiveShutdown(shutdown);
   process.stdin.on("end", () => shutdown(0));
   process.stdin.on("close", () => shutdown(0));
   process.on("SIGINT", () => shutdown(0));
@@ -3607,6 +3960,49 @@ async function main() {
     pollTimer.unref();
   }
 }
+var activeShutdown;
+var setActiveShutdown = (fn) => {
+  activeShutdown = fn;
+};
+var exitNow = (code) => {
+  if (activeShutdown) activeShutdown(code);
+  else process.exit(code);
+};
+var CRASH_WINDOW_MS = 1e4;
+var CRASH_LIMIT = 20;
+var crashTimes = [];
+function isCrashLooping() {
+  const now = Date.now();
+  crashTimes = crashTimes.filter((t) => now - t < CRASH_WINDOW_MS);
+  crashTimes.push(now);
+  return crashTimes.length >= CRASH_LIMIT;
+}
+process.on("unhandledRejection", (reason) => {
+  log.error("unhandledRejection \u2014 server kept alive", {
+    err: reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason),
+    stack: reason instanceof Error ? reason.stack?.split("\n").slice(0, 5).join(" | ") : void 0
+  });
+  if (isCrashLooping()) {
+    log.fatal("too many unhandled rejections in 10s \u2014 exiting so the client can respawn");
+    exitNow(1);
+  }
+});
+process.on("uncaughtException", (err) => {
+  if (err?.code === "EPIPE" || err?.code === "ERR_STREAM_DESTROYED" || err?.code === "ERR_STREAM_WRITE_AFTER_END") {
+    log.info("stdio pipe closed by the client \u2014 shutting down", { code: err.code });
+    exitNow(0);
+    return;
+  }
+  log.error("uncaughtException \u2014 server kept alive", {
+    err: `${err?.name ?? "Error"}: ${err?.message ?? String(err)}`,
+    code: err?.code,
+    stack: err?.stack?.split("\n").slice(0, 5).join(" | ")
+  });
+  if (isCrashLooping()) {
+    log.fatal("too many uncaught exceptions in 10s \u2014 exiting so the client can respawn");
+    exitNow(1);
+  }
+});
 main().catch((err) => {
   log.fatal("MCP server crashed", { err: String(err) });
   process.exit(1);