@bugmole/cli 0.4.0

package/src/mcp/server.ts

@@ -0,0 +1,3064 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { URL } from "node:url";
+import * as readline from "node:readline";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { json, type ObjectStore } from "../storage/object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { ControlPlaneClient, isClaimableTask } from "../registry/control-plane-client.js";
+import { getEnvironmentContract, setEnvironmentContract } from "../runtime/environment.js";
+import {
+  completeCoordinatorJob,
+  extractAtomicCandidates,
+  getCoordinatorJob,
+  getDesignDNA,
+  inferDesignDNA,
+  listReferenceInputs,
+  measureReference,
+  normalizeReferenceInput,
+  reconcileCoordinatorJob,
+  registerReferenceInput,
+  runCoordinatorPipeline,
+  startCoordinatorJob,
+} from "../runtime/ui-reverse-engineering/coordinator.js";
+import {
+  addJourneyStep,
+  addJourneyTransition,
+  createJourney,
+  reuseJourneyStep,
+  stabilizeJourney,
+  nextJourneyTask,
+  readJourneyGraph,
+  removeJourneyItem,
+  nextJourneyTaskWithClarification,
+  updateJourney,
+  writeJourneyGraph,
+} from "../runtime/journey-editor.js";
+import {
+  writeBlockerResolution,
+} from "../runtime/blocker-resolution.js";
+
+interface McpRequest {
+  jsonrpc: "2.0";
+  id?: string | number;
+  method: string;
+  params?: any;
+}
+
+interface McpResponse {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+}
+
+export function formatMcpToolResult(value: unknown): {
+  content: Array<{ type: "text"; text: string }>;
+} {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(value ?? null),
+    }],
+  };
+}
+
+interface Tool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required?: string[];
+  };
+}
+
+interface Resource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+export type McpHttpServer = {
+  origin: string;
+  close(): Promise<void>;
+};
+
+interface Prompt {
+  name: string;
+  description?: string;
+  arguments?: Array<{
+    name: string;
+    description?: string;
+    required?: boolean;
+  }>;
+}
+
+function taskClient(cfg: any): ControlPlaneClient {
+  const registryUrl = process.env.BUGMOLE_REGISTRY_URL ?? cfg.registry?.url ?? "https://api.bugmole.com";
+  const apiKey = process.env.BUGMOLE_API_KEY ?? cfg.registry?.api_key;
+  if (!apiKey) throw new Error("BUGMOLE_API_KEY is required for agent task queue operations");
+  const projectId = cfg.project?.id;
+  if (!projectId) throw new Error("A project id is required for agent task queue operations");
+  return new ControlPlaneClient({ registryUrl, apiKey, projectId });
+}
+
+async function publishJourneyRevision(cfg: any, journeyId: string, status: "draft" | "published" = "draft") {
+  const apiKey = process.env.BUGMOLE_API_KEY ?? cfg.registry?.api_key;
+  if (!apiKey || !cfg.project?.id) return null;
+  const client = taskClient(cfg);
+  const journey = readJourneyGraph(cfg).journeys.find((item) => item.id === journeyId);
+  return client.saveJourneyRevision({
+    journeyId,
+    objectKey: `${projectPrefix(cfg.project.id)}/journeys/graph.json`,
+    expectedRevision: undefined,
+    appId: cfg.project.app_id ?? cfg.project.appId,
+    environmentId: cfg.project.environment_id ?? cfg.project.environmentId,
+    status,
+    sourceOfTruth: "canonical_flow",
+    stability: journey?.stability ?? "discovered",
+    linkedToGraph: journey?.linkedToGraph === true,
+    verificationRunId: journey?.verificationRunId,
+  });
+}
+
+export async function startMcpServer(cfg: any, options: { forceHttp?: boolean } = {}) {
+  // Handle boolean strings from env vars
+  const enabled =
+    cfg.mcp?.enabled === true || cfg.mcp?.enabled === "true" || cfg.mcp?.enabled === "1";
+  if (!enabled) {
+    console.log("[Bugmole MCP] MCP disabled");
+    return;
+  }
+
+  // Check if running in stdio mode (for Cursor integration)
+  // When stdin is not a TTY, we're in stdio mode
+  const isStdioMode = !process.stdin.isTTY && !options.forceHttp;
+
+  if (isStdioMode) {
+    return startStdioServer(cfg);
+  }
+
+  const host = cfg.mcp.host || "127.0.0.1";
+  const basePort = cfg.mcp.port === undefined || cfg.mcp.port === null
+    ? 3187
+    : Number(cfg.mcp.port);
+
+  // Try to find an available port, starting from the configured port
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // Health check
+    if (req.method === "GET" && req.url === "/health") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({
+        ok: true,
+        name: cfg.name ?? "Bugmole MCP",
+        projectId: cfg.project?.id ?? "default",
+        baseUrl: cfg.execution?.playwright?.base_url,
+      }));
+      return;
+    }
+
+    // MCP protocol endpoints
+    if (req.method === "POST" && req.url === "/mcp") {
+      await handleMcpRequest(req, res, cfg);
+      return;
+    }
+
+    // Initialize endpoint
+    if (req.method === "POST" && req.url === "/initialize") {
+      const response: McpResponse = {
+        jsonrpc: "2.0",
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+          },
+          serverInfo: {
+            name: "bugmole",
+            version: "1.0.0",
+          },
+        },
+      };
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify(response));
+      return;
+    }
+
+    // Tools list endpoint
+    if (req.method === "GET" && req.url === "/tools") {
+      const tools = getTools(cfg);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ tools }));
+      return;
+    }
+
+    // Resources list endpoint
+    if (req.method === "GET" && req.url === "/resources") {
+      const resources = getResources(cfg);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ resources }));
+      return;
+    }
+
+    // Prompts list endpoint
+    if (req.method === "GET" && req.url === "/prompts") {
+      const prompts = getPrompts(cfg);
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ prompts }));
+      return;
+    }
+
+    // 404 for unknown routes
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "not_found" }));
+  });
+
+  // Try to listen on the configured port, or find an available port
+  let port = basePort;
+  const maxAttempts = 10;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const errorHandler = (err: NodeJS.ErrnoException) => {
+          server.removeListener("error", errorHandler);
+          if (err.code === "EADDRINUSE") {
+            // Port is in use, try next port
+            reject(err);
+          } else {
+            reject(err);
+          }
+        };
+
+        server.once("error", errorHandler);
+        server.listen(port, host, () => {
+          server.removeListener("error", errorHandler);
+          resolve();
+        });
+      });
+
+      // Successfully bound to port
+      break;
+    } catch (error: any) {
+      if (error.code === "EADDRINUSE") {
+        if (attempt < maxAttempts - 1) {
+          // Try next port
+          port = basePort + attempt + 1;
+          // Close the server if it was created but failed to bind
+          try {
+            server.close();
+          } catch {
+            // Ignore errors when closing
+          }
+          continue;
+        } else {
+          // Last attempt failed, but don't crash - log and exit gracefully
+          console.error(
+            `[Bugmole MCP] Failed to start MCP server: could not find available port after ${maxAttempts} attempts (tried ${basePort}-${port})`,
+          );
+          process.exit(1);
+        }
+      } else {
+        // Different error, throw it
+        throw error;
+      }
+    }
+  }
+
+  if (port !== basePort) {
+    console.log(`[Bugmole MCP] Port ${basePort} was in use, using port ${port} instead`);
+  }
+
+  const address = server.address();
+  const actualPort = address && typeof address !== "string" ? address.port : port;
+  console.log(`[Bugmole MCP] MCP server listening on http://${host}:${actualPort}`);
+  console.log(`[Bugmole MCP] MCP endpoints:`);
+  console.log(`  POST /mcp - MCP protocol handler`);
+  console.log(`  POST /initialize - Initialize MCP session`);
+  console.log(`  GET /tools - List available tools`);
+  console.log(`  GET /resources - List available resources`);
+  console.log(`  GET /prompts - List available prompts`);
+  console.log(`  GET /health - Health check`);
+  return {
+    origin: `http://${host}:${actualPort}`,
+    close: async () => {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+    },
+  } satisfies McpHttpServer;
+}
+
+/**
+ * Start MCP server in stdio mode (for Cursor integration)
+ * Reads JSON-RPC requests from stdin and writes responses to stdout
+ */
+async function startStdioServer(cfg: any) {
+  // Suppress console.log and console.error in stdio mode to avoid polluting stdout
+  // All errors should go to stderr, and we'll restore console methods for critical errors
+  const originalLog = console.log;
+  const originalError = console.error;
+  const originalWarn = console.warn;
+
+  // Redirect all console output to stderr in stdio mode
+  // CRITICAL: Never write to stdout except for JSON-RPC responses
+  console.log = (...args: any[]) => {
+    process.stderr.write("[LOG] " + args.map(String).join(" ") + "\n");
+  };
+  console.error = (...args: any[]) => {
+    process.stderr.write("[ERROR] " + args.map(String).join(" ") + "\n");
+  };
+  console.warn = (...args: any[]) => {
+    process.stderr.write("[WARN] " + args.map(String).join(" ") + "\n");
+  };
+
+  // Create readline interface - output should NOT go through readline
+  // We'll write directly to stdout for JSON-RPC responses
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr, // Use stderr for readline output to avoid conflicts
+    terminal: false,
+  });
+
+  rl.on("line", async (line: string) => {
+    if (!line.trim()) return;
+
+    // Skip lines that don't look like JSON (e.g., npm output)
+    if (!line.trim().startsWith("{") && !line.trim().startsWith("[")) {
+      return;
+    }
+
+    let request: McpRequest;
+    let requestId: string | number | null = null;
+
+    try {
+      // Try to extract id first in case parsing fails
+      const parsed = JSON.parse(line);
+      requestId = parsed?.id ?? null;
+      request = parsed;
+    } catch (err) {
+      // For parse errors, we can't extract the id, so use null
+      // Only send error response if we have a valid JSON structure that failed to parse
+      // Ignore completely malformed input (like npm output)
+      if (line.trim().startsWith("{")) {
+        try {
+          // Try to extract id from malformed JSON as a last resort
+          const idMatch = line.match(/"id"\s*:\s*([^,}\]]+)/);
+          if (idMatch) {
+            const idValue = idMatch[1].trim().replace(/['"]/g, "");
+            requestId = isNaN(Number(idValue)) ? idValue : Number(idValue);
+          }
+        } catch {
+          // Ignore
+        }
+
+        const response: McpResponse = {
+          jsonrpc: "2.0",
+          id: requestId,
+          error: { code: -32700, message: "Parse error" },
+        };
+        process.stdout.write(JSON.stringify(response) + "\n");
+      }
+      return;
+    }
+
+    // Validate request structure
+    if (!request || typeof request !== "object") {
+      const response: McpResponse = {
+        jsonrpc: "2.0",
+        id: requestId,
+        error: { code: -32600, message: "Invalid Request" },
+      };
+      process.stdout.write(JSON.stringify(response) + "\n");
+      return;
+    }
+
+    if (!request.method) {
+      const response: McpResponse = {
+        jsonrpc: "2.0",
+        id: request.id ?? requestId,
+        error: { code: -32600, message: "Invalid Request: method is required" },
+      };
+      process.stdout.write(JSON.stringify(response) + "\n");
+      return;
+    }
+
+    // Handle notifications (requests without id) - don't send response
+    // In JSON-RPC 2.0, notifications don't have an id and don't get responses
+    if (request.id === undefined) {
+      // This is a notification, process it but don't send a response
+      try {
+        switch (request.method) {
+          case "notifications/initialized":
+            // MCP sends this after initialize - just acknowledge silently
+            break;
+          case "notifications/progress":
+            // Progress notifications - handle if needed
+            break;
+          default:
+            // Unknown notification, ignore silently
+            break;
+        }
+      } catch {
+        // Ignore errors in notifications - never send response
+      }
+      return; // Don't send response for notifications
+    }
+
+    // This is a request (has id), must send response
+    const response: McpResponse = {
+      jsonrpc: "2.0",
+      id: request.id,
+    };
+
+    try {
+      switch (request.method) {
+        case "initialize":
+          response.result = {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              tools: {},
+              resources: {},
+              prompts: {},
+            },
+            serverInfo: {
+              name: "bugmole",
+              version: "1.0.0",
+            },
+          };
+          break;
+
+        case "tools/list":
+          response.result = { tools: getTools(cfg) };
+          break;
+
+        case "tools/call":
+          response.result = formatMcpToolResult(await callTool(request.params, cfg));
+          break;
+
+        case "resources/list":
+          response.result = { resources: getResources(cfg) };
+          break;
+
+        case "resources/read":
+          response.result = await readResource(request.params, cfg);
+          break;
+
+        case "prompts/list":
+          response.result = { prompts: getPrompts(cfg) };
+          break;
+
+        case "prompts/get":
+          response.result = await getPrompt(request.params, cfg);
+          break;
+
+        default:
+          response.error = {
+            code: -32601,
+            message: `Method not found: ${request.method}`,
+          };
+      }
+    } catch (err: any) {
+      response.error = {
+        code: -32603,
+        message: err.message || "Internal error",
+        data: err.stack,
+      };
+    }
+
+    // Write JSON-RPC response to stdout (must have id for requests)
+    process.stdout.write(JSON.stringify(response) + "\n");
+  });
+
+  // Handle process errors gracefully
+  process.on("uncaughtException", (err) => {
+    originalError("[Bugmole MCP] Uncaught exception in stdio mode:", err);
+    process.exit(1);
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    originalError("[Bugmole MCP] Unhandled rejection in stdio mode:", reason);
+    process.exit(1);
+  });
+
+  // Restore console methods (though they're redirected to stderr)
+  // This is mainly for cleanup
+  console.log = originalLog;
+  console.error = originalError;
+  console.warn = originalWarn;
+}
+
+async function handleMcpRequest(req: http.IncomingMessage, res: http.ServerResponse, cfg: any) {
+  let body = "";
+  for await (const chunk of req) {
+    body += chunk.toString();
+  }
+
+  let request: McpRequest;
+  try {
+    request = JSON.parse(body);
+  } catch (err) {
+    const response: McpResponse = {
+      jsonrpc: "2.0",
+      error: { code: -32700, message: "Parse error" },
+    };
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify(response));
+    return;
+  }
+
+  if (
+    !request ||
+    typeof request !== "object" ||
+    Array.isArray(request) ||
+    typeof request.method !== "string" ||
+    !request.method
+  ) {
+    const response: McpResponse = {
+      jsonrpc: "2.0",
+      id: request && typeof request === "object" && !Array.isArray(request)
+        ? request.id ?? null
+        : null,
+      error: { code: -32600, message: "Invalid Request" },
+    };
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(response));
+    return;
+  }
+
+  const response: McpResponse = {
+    jsonrpc: "2.0",
+    id: request.id,
+  };
+
+  try {
+    switch (request.method) {
+      case "tools/list":
+        response.result = { tools: getTools(cfg) };
+        break;
+
+      case "tools/call":
+        response.result = formatMcpToolResult(await callTool(request.params, cfg));
+        break;
+
+      case "resources/list":
+        response.result = { resources: getResources(cfg) };
+        break;
+
+      case "resources/read":
+        response.result = await readResource(request.params, cfg);
+        break;
+
+      case "prompts/list":
+        response.result = { prompts: getPrompts(cfg) };
+        break;
+
+      case "prompts/get":
+        response.result = await getPrompt(request.params, cfg);
+        break;
+
+      default:
+        response.error = {
+          code: -32601,
+          message: `Method not found: ${request.method}`,
+        };
+    }
+  } catch (err: any) {
+    response.error = {
+      code: -32603,
+      message: err.message || "Internal error",
+      data: err.stack,
+    };
+  }
+
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify(response));
+}
+
+export function getTools(cfg: any): Tool[] {
+  return [
+    {
+      name: "bugmole_environment_set",
+      description: "Record how a project environment is accessed and started without storing credentials.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          environmentId: { type: "string" },
+          name: { type: "string" },
+          baseUrl: { type: "string" },
+          mockUrl: { type: "string" },
+          status: { type: "string", enum: ["active", "blocked", "planned"] },
+          access: {
+            type: "object",
+            properties: {
+              transport: { type: "string", enum: ["adb", "browser", "manual", "unknown"] },
+              deviceLabel: { type: "string" },
+              serialHint: { type: "string" },
+              appPackage: { type: "string" },
+              startCommand: { type: "string" },
+              notes: { type: "string" },
+            },
+          },
+          blockedReason: { type: "string" },
+        },
+        required: ["environmentId", "name", "access"],
+      },
+    },
+    {
+      name: "bugmole_environment_get",
+      description: "Read the non-secret access contract for a project environment before exploration.",
+      inputSchema: {
+        type: "object",
+        properties: { environmentId: { type: "string" } },
+        required: ["environmentId"],
+      },
+    },
+    {
+      name: "bugmole_ui_reference_register",
+      description: "Register a project-scoped UI mock/reference for parity and journey evidence.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: ["image", "figma", "pdf", "url", "html", "existing_app"] },
+          location: { type: "string" },
+          viewport: { type: "object" },
+          checksum: { type: "string" },
+          relatedJourneyIds: { type: "array", items: { type: "string" } },
+          appId: { type: "string" },
+          environmentId: { type: "string" },
+          metadata: { type: "object" },
+        },
+        required: ["kind", "location"],
+      },
+    },
+    {
+      name: "bugmole_ui_reference_list",
+      description: "List project-scoped registered UI mocks/references.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "bugmole_ui_re_start",
+      description: "Start a resumable UI reverse-engineering coordinator job with a project-scoped reference input.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: ["image", "figma", "pdf", "url", "html", "existing_app"] },
+          location: { type: "string", description: "Reference path, URL, Figma export, or current app location" },
+          viewport: { type: "object", description: "Optional reference viewport with width and height" }
+        },
+        required: ["kind", "location"]
+      }
+    },
+    {
+      name: "bugmole_ui_re_stage",
+      description: "Run one deterministic coordinator stage and persist its revisioned artifacts.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jobId: { type: "string" },
+          stage: { type: "string", enum: ["measure", "dna", "atoms", "reconcile", "complete"] },
+          mismatches: { type: "array", description: "Measured hierarchy or Design DNA mismatches to reconcile" }
+        },
+        required: ["jobId", "stage"]
+      }
+    },
+    {
+      name: "bugmole_ui_re_run",
+      description: "Run the deterministic Design DNA and Atomic Design coordinator pipeline for a job.",
+      inputSchema: {
+        type: "object",
+        properties: { jobId: { type: "string" } },
+        required: ["jobId"],
+      },
+    },
+    {
+      name: "bugmole_ui_re_status",
+      description: "Read a coordinator job and the current project Design DNA revision.",
+      inputSchema: {
+        type: "object",
+        properties: { jobId: { type: "string" } },
+        required: ["jobId"]
+      }
+    },
+    {
+      name: "bugmole_explore",
+      description:
+        "Start guided repository/application exploration. Inspect the project entrypoints, routes, specs, roles, and journey graph; after each phase check bugmole_journey_next and continue until the selected flow is exhausted or blocked.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          baseUrl: { type: "string", description: "Optional application base URL; resolved from the environment contract when omitted" },
+          maxDepth: {
+            type: "number",
+            description: "Maximum exploration depth",
+          },
+          projectId: { type: "string" },
+          appId: { type: "string" },
+          environmentId: { type: "string" },
+          accessMethod: { type: "string", enum: ["configured", "handoff", "manual", "unknown"] },
+          journeyId: { type: "string", description: "Existing flow to continue checking after exploration" },
+          actor: { type: "string", description: "Actor for a newly discovered flow" },
+        },
+        required: [],
+      },
+    },
+    {
+      name: "bugmole_record_discovery",
+      description:
+        "Incrementally persist concrete authenticated screens, action transitions, button/link behavior, and terminal-goal completion observed by the agent/browser into a selected flow. Always follow the returned nextTask with bugmole_journey_next.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          nodes: { type: "array", description: "Observed screen nodes with id, route, and signature" },
+          edges: { type: "array", description: "Observed action edges with from, to, action, and proof tokens" },
+          journeyId: { type: "string", description: "Named user journey to update" },
+          journeyName: { type: "string", description: "Human-readable journey name" },
+          actor: { type: "string", description: "Journey actor" },
+          nodeIds: { type: "array", items: { type: "string" }, description: "Optional ordered node IDs for this journey" },
+          edgeIds: { type: "array", items: { type: "string" }, description: "Optional ordered edge IDs for this journey" },
+          completedNodeIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Terminal goal screens whose user-facing action was completed and proven",
+          },
+          verifiedControlIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Buttons, links, and actions whose runtime behavior and destination were checked",
+          },
+          journeyRevision: { type: "number", description: "Optional expected revision for conflict-aware discovery updates" },
+        },
+        required: ["nodes", "edges"],
+      },
+    },
+    {
+      name: "bugmole_journey_list",
+      description: "Read the current project-scoped journey chart and all editable flows.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "bugmole_journey_get",
+      description: "Read one flow, its steps, transitions, revision, and next exploration guidance.",
+      inputSchema: {
+        type: "object",
+        properties: { journeyId: { type: "string" } },
+        required: ["journeyId"],
+      },
+    },
+    {
+      name: "bugmole_journey_create",
+      description: "Create a first-class editable user flow in the project journey chart.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          description: { type: "string" },
+          actor: { type: "string" },
+          startNodeId: { type: "string" },
+        },
+        required: ["name", "actor"],
+      },
+    },
+    {
+      name: "bugmole_journey_add_step",
+      description: "Add an observed or planned step to an editable user flow.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          node: { type: "object" },
+          afterNodeId: { type: "string" },
+        },
+        required: ["journeyId", "node"],
+      },
+    },
+    {
+      name: "bugmole_journey_add_transition",
+      description: "Add a directed action/condition transition between flow steps.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          from: { type: "string" },
+          to: { type: "string" },
+          edge: { type: "object" },
+        },
+        required: ["journeyId", "from", "to"],
+      },
+    },
+    {
+      name: "bugmole_journey_update",
+      description: "Edit journey metadata, a step, or a transition and create a new draft revision.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          journey: { type: "object" },
+          node: { type: "object" },
+          edge: { type: "object" },
+        },
+        required: ["journeyId"],
+      },
+    },
+    {
+      name: "bugmole_journey_remove",
+      description: "Remove a step or transition from an editable flow.",
+      inputSchema: {
+        type: "object",
+        properties: { journeyId: { type: "string" }, nodeId: { type: "string" }, edgeId: { type: "string" } },
+        required: ["journeyId"],
+      },
+    },
+    {
+      name: "bugmole_journey_reuse_step",
+      description: "Reuse a verified step from another canonical flow without duplicating its implementation.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          sourceJourneyId: { type: "string" },
+          stepId: { type: "string" },
+          alias: { type: "string" },
+        },
+        required: ["journeyId", "sourceJourneyId", "stepId"],
+      },
+    },
+    {
+      name: "bugmole_journey_stabilize",
+      description: "Mark a canonical flow stable only after a successful verification run and link it into the app graph.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          verificationRunId: { type: "string" },
+          verifiedAt: { type: "string" },
+        },
+        required: ["journeyId", "verificationRunId"],
+      },
+    },
+    {
+      name: "bugmole_journey_next",
+      description: "Check the flow chart and return the next unexplored route, branch, or blocker.",
+      inputSchema: {
+        type: "object",
+        properties: { journeyId: { type: "string" } },
+        required: ["journeyId"],
+      },
+    },
+    {
+      name: "bugmole_resolve_blocker",
+      description:
+        "Record the user's clarification for a project-scoped exploration blocker and retry the selected journey.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string" },
+          category: { type: "string" },
+          reason: { type: "string" },
+          route: { type: "string" },
+          nodeId: { type: "string" },
+          environmentId: { type: "string" },
+          question: { type: "string" },
+          resolution: { type: "string" },
+          expiresAt: { type: "string" },
+        },
+        required: ["journeyId", "category", "reason", "question", "resolution"],
+      },
+    },
+    {
+      name: "bugmole_plan",
+      description:
+        "Generate a workable journey plan only after guided exploration. Read bugmole://guidance/agent-testing and the roles, domain rules, blockers, and journey graph resources first; do not create a placeholder plan when discovery is incomplete.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          journeyId: { type: "string", description: "Journey identifier" },
+          actor: { type: "string", description: "Role/actor for the journey" },
+          revision: { type: "number", description: "Optional immutable journey revision" },
+        },
+        required: ["journeyId", "actor"],
+      },
+    },
+    {
+      name: "bugmole_run",
+      description: "Execute a journey plan and collect evidence",
+      inputSchema: {
+        type: "object",
+        properties: {
+          planId: { type: "string", description: "Plan file ID or path" },
+          journeyId: {
+            type: "string",
+            description: "Specific journey ID to run",
+          },
+        },
+        required: ["planId"],
+      },
+    },
+    {
+      name: "bugmole_propose_diff",
+      description: "Propose a minimal diff to a spec file based on execution results",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: { type: "string", description: "Path to spec file" },
+          evidence: { type: "object", description: "Execution evidence" },
+          failures: { type: "array", description: "List of failures" },
+        },
+        required: ["filePath", "evidence"],
+      },
+    },
+    {
+      name: "bugmole_review",
+      description: "Review a proposed diff for safety and correctness",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: { type: "string", description: "Path to spec file" },
+          changeSummary: { type: "string", description: "Change summary" },
+          diff: { type: "string", description: "Proposed diff" },
+          evidence: { type: "object", description: "Supporting evidence" },
+        },
+        required: ["filePath", "changeSummary", "diff"],
+      },
+    },
+    {
+      name: "bugmole_report",
+      description: "Generate a health report with evidence links and plan diffs",
+      inputSchema: {
+        type: "object",
+        properties: {
+          runId: { type: "string", description: "Run identifier" },
+          format: {
+            type: "string",
+            enum: ["json", "markdown"],
+            description: "Report format",
+          },
+        },
+      },
+    },
+    {
+      name: "bugmole_write_test_cases",
+      description:
+        "Validate and write test case assumptions for a discovered journey. Every case must reference a node (and optionally an edge) that exists in that journey at that revision — assumptions are grounded in the real graph, never invented.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          caseSet: {
+            type: "object",
+            description: "Case set object matching bugmole://spec/test-cases.schema.json",
+          },
+        },
+        required: ["caseSet"],
+      },
+    },
+    {
+      name: "bugmole_write_test_case_results",
+      description:
+        "Record what a run observed for test cases already written by bugmole_write_test_cases. Every result must name a caseId that exists in that case set at that revision. This is the only thing that moves a case off \"planned\" — assumptions never count as evidence.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          resultSet: {
+            type: "object",
+            description: "Result set matching bugmole://spec/test-case-results.schema.json",
+          },
+        },
+        required: ["resultSet"],
+      },
+    },
+    {
+      name: "bugmole_write_ui_audit",
+      description:
+        "Validate and write a structured application UI audit JSON artifact for dashboard consumption",
+      inputSchema: {
+        type: "object",
+        properties: {
+          audit: {
+            type: "object",
+            description: "Audit object matching bugmole://spec/app-ui-audit.schema.json",
+          },
+        },
+        required: ["audit"],
+      },
+    },
+    {
+      name: "bugmole_write_ui_parity_audit",
+      description:
+        "Validate and write a reference-versus-current UI parity audit JSON artifact for dashboard consumption",
+      inputSchema: {
+        type: "object",
+        properties: {
+          audit: {
+            type: "object",
+            description: "Audit object matching bugmole://spec/ui-parity-audit.schema.json",
+          },
+        },
+        required: ["audit"],
+      },
+    },
+    {
+      name: "bugmole_read_spec",
+      description: "Read a spec file (roles, domain_rules, blockers, plans, etc.)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: {
+            type: "string",
+            description: "Path to spec file relative to spec_dir",
+          },
+        },
+        required: ["filePath"],
+      },
+    },
+    {
+      name: "bugmole_write_spec",
+      description: "Write or update a spec file",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: {
+            type: "string",
+            description: "Path to spec file relative to spec_dir",
+          },
+          content: { type: "string", description: "File content" },
+        },
+        required: ["filePath", "content"],
+      },
+    },
+    {
+      name: "bugmole_report_progress",
+      description:
+        "Report progress on a long-running task. Use this periodically (every 2-3 minutes) to let the framework know you are still working. This prevents unnecessary nudges and allows the framework to track your progress. Only nudge if you have not reported progress for an extended period.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            enum: ["working", "blocked", "completed"],
+            description: "Current work status",
+          },
+          message: {
+            type: "string",
+            description: "Brief description of what you are currently working on",
+          },
+          details: {
+            type: "string",
+            description: "Optional additional details about your progress",
+          },
+          estimated_time_remaining: {
+            type: "string",
+            description: 'Optional estimate of time remaining (e.g., "5 minutes", "30 seconds")',
+          },
+        },
+        required: ["status", "message"],
+      },
+    },
+    {
+      name: "bugmole_task_next",
+      description: "Claim the highest-priority queued coding task for this project and return its full task context.",
+      inputSchema: {
+        type: "object",
+        properties: { workerId: { type: "string", description: "Stable coding-agent worker id" } },
+        required: ["workerId"],
+      },
+    },
+    {
+      name: "bugmole_task_create",
+      description:
+        "Queue a follow-up agent task. Use this to hand the next stage of work to the queue rather than stopping. The idempotencyKey must describe the work so re-proposing the same follow-up updates it instead of creating a duplicate.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          taskType: { type: "string", enum: ["code", "ui", "investigation"] },
+          priority: { type: "number" },
+          idempotencyKey: {
+            type: "string",
+            description: "Stable key for this unit of work, e.g. pipeline:<projectId>:<stage>:<journeyId>",
+          },
+          journeyId: { type: "string" },
+          stepId: { type: "string" },
+        },
+        required: ["title", "description", "idempotencyKey"],
+      },
+    },
+    {
+      name: "bugmole_task_update",
+      description: "Report progress, continuation steps, parity evidence, or a blocked/completed status for the claimed task.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          taskId: { type: "string" },
+          workerId: { type: "string" },
+          status: { type: "string", enum: ["running", "blocked", "completed", "error"] },
+          progressMessage: { type: "string" },
+          continuation: { type: "object" },
+          parityAuditId: { type: "string" },
+          parityMatchScore: { type: "number" },
+          completionSummary: { type: "string" },
+          changedFiles: { type: "array", items: { type: "string" } },
+          errorMessage: { type: "string" },
+        },
+        required: ["taskId", "workerId", "status"],
+      },
+    },
+    {
+      name: "bugmole_commit_response",
+      description:
+        "Finalize a Cursor task by committing structured response payload. This is the mandatory final step for all CURSOR_DRIVER tasks. Use the SIMPLEST possible JSON - only status and summary are required. Everything else is optional.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            enum: ["ok", "error"],
+            description: "Task completion status (REQUIRED)",
+          },
+          summary: {
+            type: "string",
+            description: "Short human-readable summary (REQUIRED)",
+          },
+          answer_markdown: {
+            type: "string",
+            description: "Optional: Full final answer in markdown format",
+          },
+          actions: {
+            type: "array",
+            description: "Optional: List of actions performed. Only include if you made changes.",
+            items: {
+              type: "object",
+              properties: {
+                type: {
+                  type: "string",
+                  enum: ["edit", "create", "delete", "command"],
+                },
+                target: { type: "string" },
+                details: { type: "string" },
+              },
+              required: ["type"],
+            },
+          },
+          artifacts: {
+            type: "array",
+            description: "Optional: Generated artifacts. Only include if you created artifacts.",
+            items: {
+              type: "object",
+              properties: {
+                type: {
+                  type: "string",
+                  enum: ["patch", "config", "command", "note"],
+                },
+                content: { type: "string" },
+              },
+              required: ["type"],
+            },
+          },
+          next_steps: {
+            type: "array",
+            description:
+            'CRITICAL: List of next steps as strings. REQUIRED if you mention "Next Steps", "TODO", or any future actions in your answer. Example: ["Run bugmole_explore with baseUrl=http://localhost:8000", "Create test plans"]. Only omit this field when EVERYTHING is 100% complete with NO remaining work.',
+            items: {
+              type: "string",
+            },
+          },
+        },
+        required: ["status", "summary"],
+      },
+    },
+  ];
+}
+
+export function getResources(cfg: any): Resource[] {
+  const specDir = cfg.runtime.spec_dir || "./spec";
+  const resources: Resource[] = [
+    {
+      uri: "bugmole://guidance/agent-testing",
+      name: "Guided Agent Testing Workflow",
+      description:
+        "Persistent instructions for repository exploration, continuous MCP guidance, planning, and execution handoff",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "bugmole://guidance/app-ui-audit",
+      name: "Application UI Audit",
+      description:
+        "Guidance for reproducing a user flow and auditing every interactive control with runtime and source evidence",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "bugmole://spec/app-ui-audit.schema.json",
+      name: "Application UI Audit Schema",
+      description: "Stable JSON contract for dashboard-consumable UI audit artifacts",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://spec/test-cases.schema.json",
+      name: "Test Case Assumptions Schema",
+      description: "Stable JSON contract for test case assumptions derived from a journey",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://spec/test-case-results.schema.json",
+      name: "Test Case Results Schema",
+      description: "Stable JSON contract for what a run observed for a case set — the only thing that moves a case off \"planned\"",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://guidance/ui-parity-audit",
+      name: "UI Parity Audit",
+      description:
+        "Guidance for comparing a supplied reference experience with the implemented app and producing parity scores",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "bugmole://guidance/ui-reverse-engineering",
+      name: "UI Reverse Engineering Coordinator",
+      description: "Measurement-first Atomic Design and Design DNA coordinator workflow",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "bugmole://spec/ui-reverse-engineering.schema.json",
+      name: "UI Reverse Engineering Schema",
+      description: "Stable coordinator job, provenance, confidence, and Atomic Design contract",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://spec/design-dna.schema.json",
+      name: "Design DNA Schema",
+      description: "Project-wide reusable design token genome",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://guidance/agent-task-queue",
+      name: "Agent Task Queue Workflow",
+      description: "How a coding agent claims, executes, verifies, and completes dashboard-created tasks",
+      mimeType: "text/markdown",
+    },
+    {
+      uri: "bugmole://spec/ui-parity-audit.schema.json",
+      name: "UI Parity Audit Schema",
+      description: "Stable JSON contract for dashboard-consumable reference/current parity results",
+      mimeType: "application/schema+json",
+    },
+    {
+      uri: "bugmole://spec/roles.yaml",
+      name: "Roles and Capabilities",
+      description: "Role and capability model",
+      mimeType: "application/x-yaml",
+    },
+    {
+      uri: "bugmole://spec/domain_rules.yaml",
+      name: "Domain Rules",
+      description: "Business prerequisites and invariants",
+      mimeType: "application/x-yaml",
+    },
+    {
+      uri: "bugmole://spec/blockers.yaml",
+      name: "Blocker Rules",
+      description: "UI blocker handling rules",
+      mimeType: "application/x-yaml",
+    },
+    {
+      uri: "bugmole://spec/journeys.graph.json",
+      name: "Journey Graph",
+      description: "Journey graph (screens + actions)",
+      mimeType: "application/json",
+    },
+    {
+      uri: "bugmole://spec/bugs.index.json",
+      name: "Bug Backlog",
+      description: "Bug backlog index",
+      mimeType: "application/json",
+    },
+  ];
+
+  // Add plan files dynamically
+  try {
+    const plansDir = path.join(specDir, "plans");
+    if (fs.existsSync(plansDir)) {
+      const planFiles = fs.readdirSync(plansDir).filter((f) => f.endsWith(".flow.yaml"));
+      for (const file of planFiles) {
+        resources.push({
+          uri: `bugmole://spec/plans/${file}`,
+          name: `Plan: ${file.replace(".flow.yaml", "")}`,
+          description: `Journey plan file: ${file}`,
+          mimeType: "application/x-yaml",
+        });
+      }
+    }
+  } catch (err) {
+    // Ignore errors reading plans directory
+  }
+
+  return resources;
+}
+
+export function getPrompts(cfg: any): Prompt[] {
+  return [
+    {
+      name: "guided_testing_workflow",
+      description:
+        "The required continuous-guidance loop for exploring a repository and producing a real executable QA plan",
+    },
+    {
+      name: "app_ui_audit",
+      description:
+        "Audit every interactive application control after reproducing a requested user flow",
+    },
+    {
+      name: "ui_parity_audit",
+      description:
+        "Compare a supplied reference experience with the implemented application and produce scored parity results",
+    },
+    {
+      name: "ui_reverse_engineering",
+      description:
+        "Orchestrate measurement-first Design DNA and Atomic Design reconstruction from reference inputs",
+    },
+    {
+      name: "agent_task_execution",
+      description: "Claim and complete the next dashboard-created coding task with required UI parity verification",
+    },
+    {
+      name: "file_authoring",
+      description: "Template for creating new spec files",
+      arguments: [
+        {
+          name: "filePath",
+          description: "Path to the file to create",
+          required: true,
+        },
+        {
+          name: "filePurpose",
+          description: "Purpose of the file",
+          required: true,
+        },
+        { name: "domain", description: "Application domain", required: false },
+        {
+          name: "actors",
+          description: "List of actors/roles",
+          required: false,
+        },
+      ],
+    },
+    {
+      name: "diff_proposal",
+      description: "Template for proposing spec file changes",
+      arguments: [
+        {
+          name: "filePath",
+          description: "Path to the file to modify",
+          required: true,
+        },
+        {
+          name: "filePurpose",
+          description: "Purpose of the file",
+          required: true,
+        },
+        { name: "evidence", description: "Execution evidence", required: true },
+        { name: "failures", description: "List of failures", required: true },
+      ],
+    },
+    {
+      name: "review_approval",
+      description: "Template for reviewing change proposals",
+      arguments: [
+        { name: "filePath", description: "Path to the file", required: true },
+        {
+          name: "filePurpose",
+          description: "Purpose of the file",
+          required: true,
+        },
+        {
+          name: "changeSummary",
+          description: "Proposed change summary",
+          required: true,
+        },
+        { name: "diff", description: "Proposed diff", required: true },
+        {
+          name: "evidence",
+          description: "Supporting evidence",
+          required: true,
+        },
+      ],
+    },
+  ];
+}
+
+export async function callTool(params: any, cfg: any): Promise<any> {
+  const { name, arguments: args } = params;
+
+  // Add error handling wrapper to prevent server crashes
+  try {
+    return await callToolInternal(name, args, cfg);
+  } catch (error: any) {
+    // Log error to stderr (stdio mode redirects console to stderr)
+    console.error(`[Bugmole MCP] Tool call error for ${name}:`, error.message);
+    if (error.stack) {
+      console.error(`[Bugmole MCP] Stack trace:`, error.stack);
+    }
+    // Re-throw so it gets properly formatted as JSON-RPC error
+    throw error;
+  }
+}
+
+export async function callToolInternal(name: string, args: any, cfg: any): Promise<any> {
+  switch (name) {
+    case "bugmole_ui_reference_register": {
+      return {
+        reference: await registerReferenceInput(cfg, {
+          kind: args.kind,
+          location: args.location,
+          viewport: args.viewport,
+          checksum: args.checksum,
+          relatedJourneyIds: args.relatedJourneyIds,
+          appId: args.appId,
+          environmentId: args.environmentId,
+          metadata: args.metadata,
+        }),
+      };
+    }
+
+    case "bugmole_environment_set":
+      return {
+        environment: await setEnvironmentContract(cfg, {
+          environmentId: args.environmentId,
+          name: args.name,
+          baseUrl: args.baseUrl,
+          mockUrl: args.mockUrl,
+          status: args.status,
+          access: args.access,
+          blockedReason: args.blockedReason,
+        }),
+      };
+
+    case "bugmole_environment_get": {
+      const environment = await getEnvironmentContract(cfg, args.environmentId);
+      return environment
+        ? { environment }
+        : { environment: null, message: "No environment access contract is registered yet." };
+    }
+
+    case "bugmole_ui_reference_list":
+      return { references: await listReferenceInputs(cfg) };
+
+    case "bugmole_ui_re_start": {
+      const input = normalizeReferenceInput({
+        kind: args.kind,
+        location: args.location,
+        viewport: args.viewport,
+      });
+      return await startCoordinatorJob(cfg, input);
+    }
+
+    case "bugmole_ui_re_stage": {
+      if (typeof args.jobId !== "string") throw new Error("jobId is required");
+      if (args.stage === "measure") return await measureReference(cfg, args.jobId);
+      if (args.stage === "dna") return await inferDesignDNA(cfg, args.jobId);
+      if (args.stage === "atoms") return await extractAtomicCandidates(cfg, args.jobId);
+      if (args.stage === "reconcile") return await reconcileCoordinatorJob(cfg, args.jobId, Array.isArray(args.mismatches) ? args.mismatches : []);
+      if (args.stage === "complete") return await completeCoordinatorJob(cfg, args.jobId);
+      throw new Error(`Unsupported coordinator stage: ${args.stage}`);
+    }
+
+    case "bugmole_ui_re_run":
+      if (typeof args.jobId !== "string") throw new Error("jobId is required");
+      return await runCoordinatorPipeline(cfg, args.jobId);
+
+    case "bugmole_ui_re_status": {
+      if (typeof args.jobId !== "string") throw new Error("jobId is required");
+      return {
+        job: await getCoordinatorJob(cfg, args.jobId),
+        designDNA: await getDesignDNA(cfg),
+      };
+    }
+
+    case "bugmole_explore": {
+      const { explore } = await import("../runtime/explorer.js");
+      return await explore(cfg, {
+        baseUrl: args.baseUrl,
+        maxDepth: args.maxDepth,
+        projectId: args.projectId,
+        appId: args.appId,
+        environmentId: args.environmentId,
+        accessMethod: args.accessMethod,
+        journeyId: args.journeyId,
+        actor: args.actor,
+      });
+    }
+
+    case "bugmole_journey_list": {
+      const graph = readJourneyGraph(cfg);
+      return {
+        graph,
+        journeys: graph.journeys,
+        nextSteps: graph.journeys.length
+          ? [`Call bugmole_journey_next for ${graph.journeys[0].id}`]
+          : ["Call bugmole_journey_create to create an editable flow"],
+      };
+    }
+
+    case "bugmole_journey_get": {
+      const graph = readJourneyGraph(cfg);
+      const journey = graph.journeys.find((item) => item.id === args.journeyId);
+      if (!journey) throw new Error(`Journey not found: ${args.journeyId}`);
+      return {
+        journey,
+        nodes: graph.nodes.filter((node) => journey.nodeIds.includes(node.id)),
+        edges: graph.edges.filter((edge) => journey.edgeIds.includes(edge.id)),
+        nextTask: nextJourneyTask(cfg, args.journeyId),
+      };
+    }
+
+    case "bugmole_journey_create": {
+      const result = await createJourney(cfg, {
+        id: args.id,
+        name: args.name,
+        description: args.description,
+        actor: args.actor,
+        startNodeId: args.startNodeId,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_add_step": {
+      const result = await addJourneyStep(cfg, {
+        journeyId: args.journeyId,
+        node: args.node,
+        afterNodeId: args.afterNodeId,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_add_transition": {
+      const result = await addJourneyTransition(cfg, {
+        journeyId: args.journeyId,
+        from: args.from,
+        to: args.to,
+        edge: args.edge,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_update": {
+      const result = await updateJourney(cfg, {
+        journeyId: args.journeyId,
+        journey: args.journey,
+        node: args.node,
+        edge: args.edge,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_remove": {
+      const result = await removeJourneyItem(cfg, {
+        journeyId: args.journeyId,
+        nodeId: args.nodeId,
+        edgeId: args.edgeId,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_reuse_step": {
+      const result = await reuseJourneyStep(cfg, {
+        journeyId: args.journeyId,
+        sourceJourneyId: args.sourceJourneyId,
+        stepId: args.stepId,
+        alias: args.alias,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id);
+      return { status: "success", ...result, revision, nextTask: nextJourneyTask(cfg, result.journey.id) };
+    }
+
+    case "bugmole_journey_stabilize": {
+      const result = await stabilizeJourney(cfg, {
+        journeyId: args.journeyId,
+        verificationRunId: args.verificationRunId,
+        verifiedAt: args.verifiedAt,
+      });
+      const revision = await publishJourneyRevision(cfg, result.journey.id, "published");
+      return { status: "success", ...result, revision };
+    }
+
+    case "bugmole_journey_next": {
+      return nextJourneyTaskWithClarification(cfg, args.journeyId);
+    }
+
+    case "bugmole_resolve_blocker": {
+      const environmentId = args.environmentId ??
+        cfg.project?.environment_id ??
+        cfg.project?.environmentId;
+      const resolution = await writeBlockerResolution(cfg, {
+        category: args.category,
+        reason: args.reason,
+        route: args.route,
+        nodeId: args.nodeId,
+        environmentId,
+        question: args.question,
+        resolution: args.resolution,
+        expiresAt: args.expiresAt,
+      });
+      const graph = readJourneyGraph(cfg);
+      const node = graph.nodes.find((item) =>
+        (args.nodeId && item.id === args.nodeId) ||
+        (args.route && item.route === args.route),
+      );
+      if (node) {
+        const runtimeProbe = (node as any).runtimeProbe ?? {};
+        (node as any).runtimeProbe = {
+          ...runtimeProbe,
+          status: "resolved",
+          resolutionId: resolution.resolutionId,
+          resolvedAt: resolution.updatedAt,
+        };
+        await writeJourneyGraph(cfg, graph);
+        await publishJourneyRevision(cfg, args.journeyId);
+      }
+      return {
+        status: "success",
+        resolution,
+        journeyId: args.journeyId,
+        nextTask: nextJourneyTask(cfg, args.journeyId),
+        nextSteps: [
+          "Verify the resolved blocker evidence",
+          `Call bugmole_journey_next with journeyId=${args.journeyId}`,
+        ],
+      };
+    }
+
+    case "bugmole_record_discovery": {
+      const specDir = cfg.runtime.spec_dir || "./spec";
+      const graphPath = path.join(specDir, "journeys.graph.json");
+      const graph = fs.existsSync(graphPath)
+        ? JSON.parse(fs.readFileSync(graphPath, "utf8"))
+        : { version: 2, journeys: [], nodes: [], edges: [] };
+      const nodes = Array.isArray(args.nodes) ? args.nodes : [];
+      const edges = Array.isArray(args.edges) ? args.edges : [];
+      const nodeMap = new Map((graph.nodes ?? []).map((node: any) => [node.id, node]));
+      const edgeMap = new Map((graph.edges ?? []).map((edge: any, index: number) => [edge.id || `edge_${index}`, edge]));
+      for (const node of nodes) {
+        if (typeof node?.id === "string" && typeof node?.route === "string") nodeMap.set(node.id, node);
+      }
+      for (const edge of edges) {
+        if (typeof edge?.from === "string" && typeof edge?.to === "string" && typeof edge?.action === "string") {
+          const edgeId = edge.id || `${edge.from}->${edge.to}:${edge.action}`;
+          edgeMap.set(edgeId, { ...edge, id: edgeId });
+        }
+      }
+      graph.nodes = [...nodeMap.values()];
+      graph.edges = [...edgeMap.values()];
+      graph.version = 2;
+      const journeyId = typeof args.journeyId === "string" && args.journeyId.trim()
+        ? args.journeyId.trim()
+        : "discovered-flow";
+      const existingJourney = Array.isArray(graph.journeys)
+        ? graph.journeys.find((journey: any) => journey.id === journeyId)
+        : undefined;
+      const selectedNodeIds = Array.isArray(args.nodeIds) && args.nodeIds.length
+        ? args.nodeIds.filter((nodeId: unknown) => nodeMap.has(nodeId))
+        : [
+            ...(Array.isArray(existingJourney?.nodeIds) ? existingJourney.nodeIds : []),
+            ...nodes.map((node: any) => node.id),
+          ];
+      const selectedEdgeIds = Array.isArray(args.edgeIds) && args.edgeIds.length
+        ? args.edgeIds.filter((edgeId: unknown) => edgeMap.has(edgeId))
+        : [
+            ...(Array.isArray(existingJourney?.edgeIds) ? existingJourney.edgeIds : []),
+            ...edges.map((edge: any) => edge.id || `${edge.from}->${edge.to}:${edge.action}`),
+          ];
+      const completedNodeIds = Array.isArray(args.completedNodeIds)
+        ? args.completedNodeIds.filter((nodeId: unknown): nodeId is string => typeof nodeId === "string" && nodeMap.has(nodeId))
+        : [];
+      const verifiedControlIds = Array.isArray(args.verifiedControlIds)
+        ? args.verifiedControlIds.filter((controlId: unknown): controlId is string => typeof controlId === "string")
+        : [];
+      const existingMetadata = existingJourney?.metadata ?? {};
+      const observedNodeIds = nodes
+        .map((node: any) => node?.id)
+        .filter((nodeId: unknown): nodeId is string => typeof nodeId === "string" && nodeMap.has(nodeId));
+      const observedEdgeIds = edges
+        .map((edge: any, index: number) => edge?.id || `${edge?.from}->${edge?.to}:${edge?.action ?? index}`)
+        .filter((edgeId: unknown): edgeId is string => typeof edgeId === "string" && edgeMap.has(edgeId));
+      const verificationMetadata = existingMetadata.flowScope === "path"
+        ? {
+            verificationStatus: completedNodeIds.length ? "completed" : "in-progress",
+            verifiedNodeIds: [...new Set([
+              ...(Array.isArray(existingMetadata.verifiedNodeIds) ? existingMetadata.verifiedNodeIds : []),
+              ...observedNodeIds,
+            ])],
+            verifiedEdgeIds: [...new Set([
+              ...(Array.isArray(existingMetadata.verifiedEdgeIds) ? existingMetadata.verifiedEdgeIds : []),
+              ...observedEdgeIds,
+            ])],
+            completedGoalIds: [...new Set([
+              ...(Array.isArray(existingMetadata.completedGoalIds) ? existingMetadata.completedGoalIds : []),
+              ...completedNodeIds,
+            ])],
+            verifiedControlIds: [...new Set([
+              ...(Array.isArray(existingMetadata.verifiedControlIds) ? existingMetadata.verifiedControlIds : []),
+              ...verifiedControlIds,
+            ])],
+          }
+        : {};
+      graph.journeys = [
+        ...(Array.isArray(graph.journeys) ? graph.journeys.filter((journey: any) => journey.id !== journeyId) : []),
+        {
+          id: journeyId,
+          name: typeof args.journeyName === "string" && args.journeyName.trim()
+            ? args.journeyName.trim()
+            : existingJourney?.name ?? "Discovered user flow",
+          description: existingJourney?.description ?? "Flow assembled from exploration and discovery.",
+          actor: typeof args.actor === "string" && args.actor.trim() ? args.actor.trim() : existingJourney?.actor ?? "user",
+          startNodeId: (selectedNodeIds[0] ?? graph.nodes[0]?.id),
+          nodeIds: [...new Set(selectedNodeIds)],
+          edgeIds: [...new Set(selectedEdgeIds)],
+          revision: (existingJourney?.revision ?? 0) + 1,
+          status: "draft",
+          // This path only ever handles exploration-discovered content
+          // (never the manual journey-editor tools), so it's safe to always
+          // mark it canonical/stable — see explorer.ts's matching comment.
+          sourceOfTruth: "canonical_flow",
+          stability: "stable",
+          linkedToGraph: true,
+          metadata: {
+            ...existingMetadata,
+            ...verificationMetadata,
+          },
+        },
+      ];
+      graph.metadata = {
+        ...(graph.metadata ?? {}),
+        lastAuthenticatedDiscoveryAt: new Date().toISOString(),
+        authenticatedDiscovery: true,
+      };
+      fs.mkdirSync(specDir, { recursive: true });
+      fs.writeFileSync(graphPath, JSON.stringify(graph, null, 2) + "\n", "utf8");
+      const store = createProjectObjectStore(cfg);
+      await store.put(
+        `${projectPrefix(cfg.project?.id ?? "default")}/journeys/graph.json`,
+        JSON.stringify(graph, null, 2) + "\n",
+        "application/json",
+      );
+      return {
+        status: "success",
+        screensRecorded: nodes.length,
+        actionsRecorded: edges.length,
+        journeyId,
+        journeyRevision: existingJourney?.revision ? existingJourney.revision + 1 : 1,
+        nextTask: nextJourneyTask(cfg, journeyId),
+        nextSteps: [
+          "Read bugmole://spec/journeys.graph.json and inspect the updated flow",
+          `Call bugmole_journey_next with journeyId=${journeyId}`,
+          "Perform and record the returned next task before planning",
+        ],
+      };
+    }
+
+    case "bugmole_plan": {
+      const { plan } = await import("../runtime/planner.js");
+      return await plan(cfg, {
+        journeyId: args.journeyId,
+        actor: args.actor,
+        revision: args.revision,
+      });
+    }
+
+    case "bugmole_run": {
+      const { execute } = await import("../runtime/executor.js");
+      return await execute(cfg, {
+        planId: args.planId,
+        journeyId: args.journeyId,
+      });
+    }
+
+    case "bugmole_propose_diff": {
+      const { proposeDiff } = await import("../runtime/diff-proposal.js");
+      return await proposeDiff(cfg, {
+        filePath: args.filePath,
+        evidence: args.evidence,
+        failures: args.failures,
+      });
+    }
+
+    case "bugmole_review": {
+      const { review } = await import("../runtime/reviewer.js");
+      return await review(cfg, {
+        filePath: args.filePath,
+        changeSummary: args.changeSummary,
+        diff: args.diff,
+        evidence: args.evidence,
+      });
+    }
+
+    case "bugmole_report": {
+      const { generateReport } = await import("../runtime/reporter.js");
+      return await generateReport(cfg, {
+        runId: args.runId,
+        format: args.format,
+      });
+    }
+
+    case "bugmole_write_test_cases": {
+      const caseSet = args.caseSet;
+      if (!caseSet || typeof caseSet !== "object" || Array.isArray(caseSet)) {
+        throw new Error("caseSet must be an object matching test-cases.schema.json");
+      }
+      if (caseSet.schemaVersion !== 1 || typeof caseSet.caseSetId !== "string" || !caseSet.caseSetId) {
+        throw new Error("caseSet.schemaVersion must be 1 and caseSet.caseSetId is required");
+      }
+      if (!/^[a-zA-Z0-9._-]+$/.test(caseSet.caseSetId)) {
+        throw new Error("caseSet.caseSetId may contain only letters, numbers, ., _, and -");
+      }
+      if (typeof caseSet.journeyId !== "string" || !Number.isInteger(caseSet.journeyRevision)) {
+        throw new Error("caseSet requires journeyId and an integer journeyRevision");
+      }
+      if (!Array.isArray(caseSet.cases) || caseSet.cases.length === 0) {
+        throw new Error("caseSet.cases must be a non-empty array");
+      }
+      // Ground every assumption in the real graph. Without this the tool
+      // would happily persist confident-sounding cases for steps that do
+      // not exist — the same failure mode as inventing routes.
+      const graph = readJourneyGraph(cfg);
+      const journey = graph.journeys.find((item) => item.id === caseSet.journeyId);
+      if (!journey) throw new Error(`Journey not found: ${caseSet.journeyId}`);
+      if (journey.revision !== caseSet.journeyRevision) {
+        throw new Error(
+          `caseSet.journeyRevision must match the selected journey revision (${journey.revision})`,
+        );
+      }
+      const allowedNodes = new Set(journey.nodeIds);
+      const allowedEdges = new Set(journey.edgeIds);
+      const seenCaseIds = new Set<string>();
+      for (const testCase of caseSet.cases) {
+        if (!testCase || typeof testCase !== "object") throw new Error("each case must be an object");
+        for (const field of ["caseId", "title", "nodeId", "intent"]) {
+          if (typeof testCase[field] !== "string" || !testCase[field].trim()) {
+            throw new Error(`each case requires a non-empty ${field}`);
+          }
+        }
+        if (!/^[a-zA-Z0-9._-]+$/.test(testCase.caseId)) {
+          throw new Error(`case ${testCase.caseId}: caseId may contain only letters, numbers, ., _, and -`);
+        }
+        if (seenCaseIds.has(testCase.caseId)) throw new Error(`duplicate caseId: ${testCase.caseId}`);
+        seenCaseIds.add(testCase.caseId);
+        if (!allowedNodes.has(testCase.nodeId)) {
+          throw new Error(
+            `case ${testCase.caseId}: nodeId "${testCase.nodeId}" is not a step of journey ${caseSet.journeyId}`,
+          );
+        }
+        if (testCase.edgeId !== undefined && !allowedEdges.has(testCase.edgeId)) {
+          throw new Error(
+            `case ${testCase.caseId}: edgeId "${testCase.edgeId}" is not a transition of journey ${caseSet.journeyId}`,
+          );
+        }
+        for (const field of ["steps", "expected"]) {
+          const value = testCase[field];
+          if (!Array.isArray(value) || value.length === 0
+            || value.some((item: unknown) => typeof item !== "string" || !item.trim())) {
+            throw new Error(`case ${testCase.caseId}: ${field} must be a non-empty array of strings`);
+          }
+        }
+        if (!["high", "medium", "low"].includes(testCase.confidence)) {
+          throw new Error(`case ${testCase.caseId}: confidence must be high, medium, or low`);
+        }
+        // An assumption with nothing behind it must say so rather than
+        // claiming certainty it hasn't earned.
+        const basis = Array.isArray(testCase.basis) ? testCase.basis.filter(Boolean) : [];
+        if (basis.length === 0 && testCase.confidence !== "low") {
+          throw new Error(
+            `case ${testCase.caseId}: a case with no basis must be confidence "low"`,
+          );
+        }
+      }
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+      const projectId = cfg.project?.id ?? "default";
+      const record = {
+        ...caseSet,
+        projectId,
+        generatedAt: caseSet.generatedAt ?? new Date().toISOString(),
+      };
+      const objectKey = `${projectPrefix(projectId)}/test-cases/${caseSet.caseSetId}.json`;
+      await store.put(objectKey, JSON.stringify(record, null, 2) + "\n", "application/json");
+      return {
+        status: "success",
+        caseSetId: caseSet.caseSetId,
+        journeyId: caseSet.journeyId,
+        caseCount: caseSet.cases.length,
+        objectKey,
+        nextSteps: [
+          `Plan the journey with bugmole_plan for "${caseSet.journeyId}" so these cases can be executed`,
+        ],
+      };
+    }
+
+    case "bugmole_write_test_case_results": {
+      const resultSet = args.resultSet;
+      if (!resultSet || typeof resultSet !== "object" || Array.isArray(resultSet)) {
+        throw new Error("resultSet must be an object matching test-case-results.schema.json");
+      }
+      if (resultSet.schemaVersion !== 1 || typeof resultSet.caseSetId !== "string" || !resultSet.caseSetId) {
+        throw new Error("resultSet.schemaVersion must be 1 and resultSet.caseSetId is required");
+      }
+      if (!/^[a-zA-Z0-9._-]+$/.test(resultSet.caseSetId)) {
+        throw new Error("resultSet.caseSetId may contain only letters, numbers, ., _, and -");
+      }
+      if (!Array.isArray(resultSet.results) || resultSet.results.length === 0) {
+        throw new Error("resultSet.results must be a non-empty array");
+      }
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+      const projectId = cfg.project?.id ?? "default";
+      // Ground every verdict in the case set it claims to judge. Without this
+      // a run could record a pass for a caseId nobody ever wrote, which is
+      // the same failure mode as inventing routes — except it would show up
+      // on the dashboard as proof.
+      const caseSetKey = `${projectPrefix(projectId)}/test-cases/${resultSet.caseSetId}.json`;
+      let storedCaseSet: any;
+      try {
+        storedCaseSet = JSON.parse(await store.getText(caseSetKey));
+      } catch {
+        throw new Error(
+          `No test cases found for caseSetId "${resultSet.caseSetId}" — write them with bugmole_write_test_cases first`,
+        );
+      }
+      if (Number.isInteger(resultSet.journeyRevision)
+        && resultSet.journeyRevision !== storedCaseSet.journeyRevision) {
+        throw new Error(
+          `resultSet.journeyRevision (${resultSet.journeyRevision}) does not match the case set revision `
+          + `(${storedCaseSet.journeyRevision}) — re-run against the current assumptions`,
+        );
+      }
+      const knownCaseIds = new Set((storedCaseSet.cases ?? []).map((item: any) => item.caseId));
+      const allowedStatuses = ["passed", "failed", "blocked", "needs_setup"];
+      const seen = new Set<string>();
+      for (const result of resultSet.results) {
+        if (!result || typeof result !== "object") throw new Error("each result must be an object");
+        if (typeof result.caseId !== "string" || !knownCaseIds.has(result.caseId)) {
+          throw new Error(`result caseId "${result.caseId}" is not a case of ${resultSet.caseSetId}`);
+        }
+        if (seen.has(result.caseId)) throw new Error(`duplicate result for caseId: ${result.caseId}`);
+        seen.add(result.caseId);
+        if (!allowedStatuses.includes(result.status)) {
+          throw new Error(`result ${result.caseId}: status must be one of ${allowedStatuses.join(", ")}`);
+        }
+        // A verdict with no detail is not reviewable, and "passed" with no
+        // detail is exactly the shape of a fabricated result.
+        if (typeof result.detail !== "string" || !result.detail.trim()) {
+          throw new Error(`result ${result.caseId}: detail is required — say what was observed`);
+        }
+      }
+      const record = {
+        ...resultSet,
+        projectId,
+        journeyId: storedCaseSet.journeyId,
+        journeyRevision: storedCaseSet.journeyRevision,
+        recordedAt: resultSet.recordedAt ?? new Date().toISOString(),
+      };
+      const objectKey = `${projectPrefix(projectId)}/test-case-results/${resultSet.caseSetId}.json`;
+      await store.put(objectKey, JSON.stringify(record, null, 2) + "\n", "application/json");
+      const counts = resultSet.results.reduce((acc: Record<string, number>, item: any) => {
+        acc[item.status] = (acc[item.status] ?? 0) + 1;
+        return acc;
+      }, {});
+      return {
+        status: "success",
+        caseSetId: resultSet.caseSetId,
+        journeyId: storedCaseSet.journeyId,
+        recorded: resultSet.results.length,
+        of: knownCaseIds.size,
+        counts,
+        objectKey,
+      };
+    }
+
+    case "bugmole_write_ui_audit": {
+      const audit = args.audit;
+      if (!audit || typeof audit !== "object" || Array.isArray(audit)) {
+        throw new Error("audit must be an object matching app-ui-audit.schema.json");
+      }
+      if (audit.schemaVersion !== 1 || typeof audit.auditId !== "string" || !audit.auditId) {
+        throw new Error("audit.schemaVersion must be 1 and audit.auditId is required");
+      }
+      if (
+        typeof audit.journeyId !== "string" ||
+        !Number.isInteger(audit.journeyRevision) ||
+        !["exhausted", "blocked"].includes(audit.flowStatus) ||
+        !Array.isArray(audit.exploredNodeIds) ||
+        !Array.isArray(audit.exploredEdgeIds)
+      ) {
+        throw new Error(
+          "audit requires journeyId, integer journeyRevision, flowStatus, exploredNodeIds, and exploredEdgeIds",
+        );
+      }
+      if (!/^[a-zA-Z0-9._-]+$/.test(audit.auditId)) {
+        throw new Error("audit.auditId may contain only letters, numbers, ., _, and -");
+      }
+      if (!Array.isArray(audit.screens) || !Array.isArray(audit.blockedVerification)) {
+        throw new Error("audit.screens and audit.blockedVerification must be arrays");
+      }
+      const journeyGraph = readJourneyGraph(cfg);
+      const journey = journeyGraph.journeys.find((item) => item.id === audit.journeyId);
+      if (!journey) throw new Error(`Journey not found: ${audit.journeyId}`);
+      if (journey.revision !== audit.journeyRevision) {
+        throw new Error(
+          `audit.journeyRevision must match the selected journey revision (${journey.revision})`,
+        );
+      }
+      const nextTask = await nextJourneyTaskWithClarification(cfg, audit.journeyId);
+      if (nextTask.status === "actionable") {
+        throw new Error("Cannot write an App Audit while the selected journey has an actionable next task");
+      }
+      if (audit.flowStatus !== nextTask.status) {
+        throw new Error(`audit.flowStatus must match the selected journey state (${nextTask.status})`);
+      }
+      const allowedNodes = new Set(journey.nodeIds);
+      const allowedEdges = new Set(journey.edgeIds);
+      if (audit.exploredNodeIds.some((id: unknown) => typeof id !== "string" || !allowedNodes.has(id))) {
+        throw new Error("audit.exploredNodeIds must reference nodes in the selected journey");
+      }
+      if (audit.exploredEdgeIds.some((id: unknown) => typeof id !== "string" || !allowedEdges.has(id))) {
+        throw new Error("audit.exploredEdgeIds must reference edges in the selected journey");
+      }
+      const controls = audit.screens.flatMap((screen: any) => screen?.controls ?? []);
+      const counts = {
+        total: controls.length,
+        implemented: controls.filter((control: any) => control.status === "Implemented").length,
+        partiallyImplemented: controls.filter(
+          (control: any) => control.status === "Partially implemented",
+        ).length,
+        notImplemented: controls.filter((control: any) => control.status === "Not implemented")
+          .length,
+      };
+      if (JSON.stringify(audit.summary) !== JSON.stringify(counts)) {
+        throw new Error(`audit.summary must match control status totals: ${JSON.stringify(counts)}`);
+      }
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+      for (const control of controls) {
+        if (
+          !control ||
+          typeof control.controlId !== "string" ||
+          typeof control.label !== "string" ||
+          !["Implemented", "Partially implemented", "Not implemented"].includes(control.status) ||
+          typeof control.destinationOrHandler !== "string" ||
+          !Array.isArray(control.evidence) ||
+          !Array.isArray(control.missingBehavior)
+        ) {
+          throw new Error(
+            "each control requires controlId, label, status, destinationOrHandler, evidence, and missingBehavior",
+          );
+        }
+        // Evidence integrity gate: a control claiming Implemented/Partially
+        // implemented status must back it with evidence that actually
+        // exists, not a self-reported description with no artifact behind
+        // it. Runtime evidence (as opposed to a source-code reference) is
+        // only meaningful if the storage key it names is real.
+        for (const evidence of control.evidence) {
+          if (
+            !evidence ||
+            typeof evidence !== "object" ||
+            !["runtime", "source"].includes(evidence.type) ||
+            typeof evidence.description !== "string"
+          ) {
+            throw new Error(
+              `control ${control.controlId} has a malformed evidence entry; each entry requires type ("runtime" or "source") and description`,
+            );
+          }
+          if (evidence.type === "runtime") {
+            if (typeof evidence.location !== "string" || !evidence.location.trim()) {
+              throw new Error(
+                `control ${control.controlId} claims runtime evidence without a location; runtime evidence must reference a stored artifact key`,
+              );
+            }
+            const exists = await store.has(evidence.location).catch(() => false);
+            if (!exists) {
+              throw new Error(
+                `control ${control.controlId} references runtime evidence at "${evidence.location}", but no artifact exists at that key`,
+              );
+            }
+          }
+        }
+      }
+      const projectId = cfg.project?.id ?? audit.projectId ?? "default";
+      const workspaceId =
+        cfg.project?.workspace_id ??
+        cfg.project?.workspaceId ??
+        audit.workspaceId ??
+        undefined;
+      const auditKey = `${projectPrefix(projectId)}/ui-audits/${audit.auditId}.json`;
+      const clarification = audit.clarification ?? nextTask.clarification;
+      const blockedVerification = [...audit.blockedVerification];
+      if (
+        audit.flowStatus === "blocked" &&
+        clarification &&
+        !blockedVerification.some((item: any) => item?.fingerprint === clarification.fingerprint)
+      ) {
+        blockedVerification.push({
+          description: "Authenticated runtime verification requires user clarification.",
+          reason: clarification.reason,
+          fingerprint: clarification.fingerprint,
+          question: clarification.question,
+          status: clarification.status,
+          ...(clarification.resolutionId ? { resolutionId: clarification.resolutionId } : {}),
+        });
+      }
+      const payload = {
+        ...audit,
+        projectId,
+        blockedVerification,
+        ...(clarification ? { clarification } : {}),
+        ...(workspaceId ? { workspaceId } : {}),
+      };
+      await store.put(auditKey, json(payload), "application/json");
+      return {
+        status: "success",
+        auditId: audit.auditId,
+        artifact: { key: auditKey, contentType: "application/json" },
+        schema: "bugmole://spec/app-ui-audit.schema.json",
+      };
+    }
+
+    case "bugmole_write_ui_parity_audit": {
+      const audit = args.audit;
+      if (!audit || typeof audit !== "object" || Array.isArray(audit)) {
+        throw new Error("audit must be an object matching ui-parity-audit.schema.json");
+      }
+      if (
+        audit.schemaVersion !== 1 ||
+        typeof audit.auditId !== "string" ||
+        !audit.auditId ||
+        !audit.reference ||
+        !audit.current ||
+        !audit.summary
+      ) {
+        throw new Error(
+          "audit requires schemaVersion 1, auditId, reference, current, and summary",
+        );
+      }
+      if (!/^[a-zA-Z0-9._-]+$/.test(audit.auditId)) {
+        throw new Error("audit.auditId may contain only letters, numbers, ., _, and -");
+      }
+      if (
+        !Array.isArray(audit.flowMatrix) ||
+        !Array.isArray(audit.comparisons) ||
+        !Array.isArray(audit.issues) ||
+        typeof audit.fixPrompt !== "string" ||
+        !Array.isArray(audit.blockedVerification)
+      ) {
+        throw new Error(
+          "audit.flowMatrix, comparisons, issues, blockedVerification, and fixPrompt are required",
+        );
+      }
+      const scoreFields = [
+        "visualDifferencePercent",
+        "interactionParityScore",
+        "apiParityScore",
+        "authenticationParityScore",
+      ];
+      for (const field of scoreFields) {
+        if (
+          typeof audit.summary[field] !== "number" ||
+          audit.summary[field] < 0 ||
+          audit.summary[field] > 100
+        ) {
+          throw new Error(`audit.summary.${field} must be a number from 0 to 100`);
+        }
+      }
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+      const projectId = cfg.project?.id ?? audit.projectId ?? "default";
+      const workspaceId =
+        cfg.project?.workspace_id ??
+        cfg.project?.workspaceId ??
+        audit.workspaceId ??
+        undefined;
+      const appId = cfg.project?.app_id ?? cfg.project?.appId ?? audit.appId ?? undefined;
+      const parityKey = `${projectPrefix(projectId)}/ui-parity-audits/${audit.auditId}.json`;
+      const payload = {
+        ...audit,
+        projectId,
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(appId ? { appId } : {}),
+      };
+      await store.put(parityKey, json(payload), "application/json");
+      const taskApiKey = process.env.BUGMOLE_API_KEY ?? cfg.registry?.api_key;
+      if (taskApiKey) {
+        const client = taskClient(cfg);
+        const issues = [
+          ...((audit.issues ?? []).filter((issue: any) =>
+            ["unresolved", "blocked", "missing_backend", "platform_limitation"].includes(issue.status))),
+          ...((audit.blockedVerification ?? []).map((blocked: any) => ({
+            issueId: `blocked:${blocked.description}`,
+            category: "platform",
+            status: "blocked",
+            severity: "high",
+            description: `${blocked.description}: ${blocked.reason}`,
+          }))),
+        ];
+        await Promise.all(issues.map((issue: any) => client.createTask({
+          title: `Resolve parity: ${String(issue.description).slice(0, 100)}`,
+          description: String(issue.description),
+          taskType: "ui",
+          priority: issue.severity === "high" ? 10 : issue.severity === "medium" ? 5 : 1,
+          idempotencyKey: `${audit.auditId}:${issue.issueId}`,
+        })));
+      }
+      return {
+        status: "success",
+        auditId: audit.auditId,
+        artifact: { key: parityKey, contentType: "application/json" },
+        schema: "bugmole://spec/ui-parity-audit.schema.json",
+      };
+    }
+
+    case "bugmole_read_spec":
+      return readSpecFile(args.filePath, cfg);
+
+    case "bugmole_write_spec":
+      return writeSpecFile(args.filePath, args.content, cfg);
+
+    case "bugmole_report_progress": {
+      // Store progress report for monitoring
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+
+      const progressId = `progress_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      const progressKey = `${projectPrefix(cfg.project?.id ?? "default")}/progress/${progressId}.json`;
+
+      const progressData = {
+        id: progressId,
+        timestamp: new Date().toISOString(),
+        status: args.status,
+        message: args.message,
+        details: args.details || "",
+        estimated_time_remaining: args.estimated_time_remaining || "",
+      };
+
+      await store.put(progressKey, json(progressData), "application/json");
+
+      return {
+        success: true,
+        progressId,
+        message: "Progress reported",
+      };
+    }
+
+    case "bugmole_task_next": {
+      const client = taskClient(cfg);
+      const listed = await client.listTasks();
+      const next = listed.tasks.find((task) => isClaimableTask(task));
+      if (!next) return { task: null, message: "No queued agent tasks are available." };
+      return client.claimTask(next.id, args.workerId);
+    }
+
+    case "bugmole_task_create": {
+      if (typeof args.idempotencyKey !== "string" || !args.idempotencyKey.trim()) {
+        throw new Error("idempotencyKey is required so a re-proposed follow-up cannot duplicate work");
+      }
+      const client = taskClient(cfg);
+      return client.createTask({
+        title: args.title,
+        description: args.description,
+        taskType: args.taskType,
+        priority: args.priority,
+        idempotencyKey: args.idempotencyKey.trim(),
+        journeyId: args.journeyId,
+      });
+    }
+
+    case "bugmole_task_update": {
+      const client = taskClient(cfg);
+      const update = { ...args };
+      delete update.taskId;
+      return client.updateTask(args.taskId, update);
+    }
+
+    case "bugmole_commit_response": {
+      // Store the committed response for external agent consumption
+      // This is the completion signal for CURSOR_DRIVER tasks
+      const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+      const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+
+      const commitId = `commit_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      const commitKey = `${projectPrefix(cfg.project?.id ?? "default")}/cursor-commits/${commitId}.json`;
+
+      // Validate and limit payload size to prevent tool call interruptions
+      // Large payloads can cause stdio buffer issues
+      const MAX_PAYLOAD_SIZE = 500000; // ~500KB limit for safety
+      const MAX_ANSWER_SIZE = 200000; // ~200KB for answer_markdown
+      const MAX_ARTIFACT_CONTENT = 100000; // ~100KB per artifact content
+
+      let answer_markdown = args.answer_markdown || "";
+      if (answer_markdown.length > MAX_ANSWER_SIZE) {
+        console.warn(
+          `[Bugmole MCP] answer_markdown is too large (${answer_markdown.length} chars), truncating to ${MAX_ANSWER_SIZE}`,
+        );
+        answer_markdown =
+          answer_markdown.substring(0, MAX_ANSWER_SIZE) + "\n\n... (truncated due to size limit)";
+      }
+
+      // Truncate artifact content if too large
+      const artifacts = (args.artifacts || []).map((artifact: any) => {
+        if (artifact.content && artifact.content.length > MAX_ARTIFACT_CONTENT) {
+          console.warn(
+            `[Bugmole MCP] Artifact content is too large (${artifact.content.length} chars), truncating`,
+          );
+          return {
+            ...artifact,
+            content:
+              artifact.content.substring(0, MAX_ARTIFACT_CONTENT) +
+              "\n\n... (truncated due to size limit)",
+          };
+        }
+        return artifact;
+      });
+
+      // Handle optional fields gracefully - provide defaults for arrays
+      // Normalize next_steps: convert string to array, null/undefined to empty array
+      // Check both next_steps and nextSteps (in case of camelCase)
+      const nextStepsArg = args.next_steps !== undefined ? args.next_steps : args.nextSteps;
+
+      // Log to file for debugging (since stdio mode redirects console.log to stderr)
+      const logFile = path.join(artifactsDir, "mcp_debug.log");
+      const logEntry = {
+        timestamp: new Date().toISOString(),
+        tool: "bugmole_commit_response",
+        allArgsKeys: Object.keys(args),
+        next_steps_received: args.next_steps,
+        nextSteps_received: args.nextSteps,
+        nextStepsArg: nextStepsArg,
+        nextStepsArgType: typeof nextStepsArg,
+        nextStepsArgIsArray: Array.isArray(nextStepsArg),
+        fullArgs: args,
+      };
+      try {
+        // Ensure directory exists
+        fs.mkdirSync(artifactsDir, { recursive: true });
+        fs.appendFileSync(logFile, JSON.stringify(logEntry, null, 2) + "\n---\n", "utf-8");
+        // Also log to console that we wrote the file
+        console.log("[Bugmole MCP] Debug log written to:", logFile);
+      } catch (e: any) {
+        // Log the error so we can see what went wrong
+        console.error("[Bugmole MCP] Failed to write debug log:", e.message, "path:", logFile);
+      }
+
+      console.log("[Bugmole MCP] All args keys:", Object.keys(args));
+      console.log(
+        "[Bugmole MCP] Received next_steps:",
+        JSON.stringify(nextStepsArg),
+        "type:",
+        typeof nextStepsArg,
+        "isArray:",
+        Array.isArray(nextStepsArg),
+        "args.next_steps:",
+        JSON.stringify(args.next_steps),
+        "args.nextSteps:",
+        JSON.stringify(args.nextSteps),
+      );
+
+      let next_steps: string[] = [];
+      if (nextStepsArg !== undefined && nextStepsArg !== null) {
+        if (Array.isArray(nextStepsArg)) {
+          next_steps = nextStepsArg.filter((s: any) => s && typeof s === "string");
+          console.log("[Bugmole MCP] Normalized next_steps from array:", next_steps);
+        } else if (typeof nextStepsArg === "string") {
+          // If agent passes a single string, convert to array
+          next_steps = [nextStepsArg];
+          console.log("[Bugmole MCP] Normalized next_steps from string:", next_steps);
+        } else {
+          console.warn(
+            "[Bugmole MCP] next_steps has unexpected type:",
+            typeof nextStepsArg,
+            "value:",
+            nextStepsArg,
+          );
+        }
+      } else if (nextStepsArg === undefined) {
+        console.log("[Bugmole MCP] next_steps is undefined, using empty array");
+
+        // Fallback: Try to extract next_steps from answer_markdown if it mentions "Next Steps"
+        if (
+          answer_markdown &&
+          (answer_markdown.includes("Next Steps") || answer_markdown.includes("next steps"))
+        ) {
+          console.log("[Bugmole MCP] Attempting to extract next_steps from answer_markdown");
+          // Try multiple patterns: ## Next Steps, ### Next Steps, **Next Steps**, etc.
+          // Handle emoji and various markdown formats
+          const nextStepsMatch =
+            answer_markdown.match(
+              /(?:##|###|\*\*)\s*[📋\s]*Next Steps\s*(?:\*\*)?\s*\n([\s\S]*?)(?=\n(?:##|###|---|$))/i,
+            ) || answer_markdown.match(/Next Steps\s*\n([\s\S]*?)(?=\n(?:##|###|---|$))/i);
+          if (nextStepsMatch) {
+            const nextStepsText = nextStepsMatch[1];
+            console.log(
+              "[Bugmole MCP] Extracted next steps text:",
+              nextStepsText.substring(0, 200),
+            );
+            // Extract numbered or bulleted items
+            const steps = nextStepsText
+              .split(/\n/)
+              .map((line: string) => line.trim())
+              .filter((line: string) => {
+                // Match numbered lists (1., 2., etc.) or bullet points (-, *, •)
+                // Skip sub-items (lines starting with - or spaces)
+                if (/^\s+[-*•]/.test(line)) return false;
+                return /^\d+\.\s/.test(line) || /^[-*•]\s/.test(line);
+              })
+              .map((line: string) => {
+                // Extract the step text (remove numbering/bullet and markdown)
+                // Handle "1. **Bold text**" format
+                const boldMatch = line.match(/^\d+\.\s*\*\*(.+?)\*\*/);
+                if (boldMatch) {
+                  return boldMatch[1].trim();
+                }
+                // Handle "1. Regular text" format
+                const numMatch = line.match(/^\d+\.\s+(.+)$/);
+                if (numMatch) {
+                  return numMatch[1].trim();
+                }
+                // Handle bullet points
+                const bulletMatch = line.match(/^[-*•]\s+(.+)$/);
+                if (bulletMatch) {
+                  return bulletMatch[1].trim();
+                }
+                // Fallback: remove numbering/bullet
+                return line
+                  .replace(/^\d+\.\s*/, "")
+                  .replace(/^[-*•]\s*/, "")
+                  .trim();
+              })
+              .filter((step: string) => step.length > 0 && !step.match(/^[-*•\s]*$/));
+
+            if (steps.length > 0) {
+              console.log("[Bugmole MCP] Extracted next_steps from answer_markdown:", steps);
+              next_steps = steps;
+            }
+          }
+        }
+      } else {
+        console.log("[Bugmole MCP] next_steps is null, using empty array");
+      }
+
+      console.log("[Bugmole MCP] Final next_steps to save:", next_steps);
+
+      // Ensure next_steps is always an array (never undefined)
+      const final_next_steps = Array.isArray(next_steps) ? next_steps : [];
+
+      const commitData = {
+        id: commitId,
+        timestamp: new Date().toISOString(),
+        payload: {
+          status: args.status,
+          summary: args.summary,
+          ...(answer_markdown ? { answer_markdown } : {}),
+          actions: Array.isArray(args.actions) ? args.actions : [],
+          artifacts: Array.isArray(artifacts) ? artifacts : [],
+          next_steps: final_next_steps, // Always include as array, never undefined
+        },
+      };
+
+      // Debug: Verify next_steps is in the payload
+      console.log("[Bugmole MCP] Commit payload keys:", Object.keys(commitData.payload));
+      console.log("[Bugmole MCP] Commit payload next_steps:", commitData.payload.next_steps);
+
+      // Debug: Log what we're about to save
+      console.log("[Bugmole MCP] Commit data payload keys:", Object.keys(commitData.payload));
+      console.log(
+        "[Bugmole MCP] Commit data next_steps value:",
+        JSON.stringify(commitData.payload.next_steps),
+      );
+      console.log(
+        "[Bugmole MCP] Commit data has next_steps:",
+        "next_steps" in commitData.payload,
+      );
+
+      // Check total payload size
+      const payloadString = JSON.stringify(commitData);
+      if (payloadString.length > MAX_PAYLOAD_SIZE) {
+        console.warn(
+          `[Bugmole MCP] Total payload size (${payloadString.length} chars) exceeds limit (${MAX_PAYLOAD_SIZE}), truncating answer_markdown further`,
+        );
+        // Further truncate answer_markdown to fit
+        const targetSize = MAX_PAYLOAD_SIZE - (payloadString.length - answer_markdown.length);
+        commitData.payload.answer_markdown = answer_markdown.substring(
+          0,
+          Math.max(0, targetSize - 1000),
+        );
+      }
+
+      await store.put(commitKey, json(commitData), "application/json");
+
+      // Return minimal response to avoid stdio buffer issues
+      // The full payload is stored in the file and will be read by the monitor
+      // Keep response under 1KB to ensure it doesn't get truncated
+      return {
+        success: true,
+        commitId,
+        message: "Committed",
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export async function readResource(params: any, cfg: any): Promise<any> {
+  const { uri } = params;
+  const specDir = cfg.runtime.spec_dir || "./spec";
+
+  // Parse bugmole:// URIs
+  if (uri === "bugmole://guidance/agent-testing") {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: [
+            "# Bugmole guided agent testing",
+            "",
+            "Subscribe to this MCP server for continuous guidance. Keep the MCP session open and use `bugmole_report_progress` every 2–3 minutes or after each exploration phase.",
+            "",
+            "Required sequence:",
+            "1. Read this resource and the roles, domain rules, blockers, and journey graph resources.",
+            "2. Inspect the repository structure, package/config files, application entrypoints, routes, and relevant source/spec files.",
+            "3. Call `bugmole_environment_get` for the selected environment. If it is missing or incomplete, call `bugmole_environment_set` with the safe base URL, mock/reference URL, device transport, device label, and reproducible start command before exploring.",
+            "4. For an ADB environment, verify the named device is reachable and follow the recorded start command; do not guess a generic browser URL. For Lumis android-local, the expected transport is Nokia via ADB and the mock/reference URL is `https://gcore.otlrs.com/lumis-consumer/`.",
+            "5. Call `bugmole_explore` with the environment ID; omit baseUrl when the environment contract provides it.",
+            "6. If an authenticated browser or device session is available, explore one concrete task and call `bugmole_record_discovery` with screens, transitions, proof tokens, `verifiedControlIds` for every button/link/action checked, and `completedNodeIds` after the terminal action actually succeeds.",
+            "7. After every exploration or discovery result, call `bugmole_journey_get` and `bugmole_journey_next` for the selected flow.",
+            "8. Perform the returned nextTask, add/edit the flow with `bugmole_journey_add_step` or `bugmole_journey_add_transition`, then call `bugmole_journey_next` again.",
+            "9. If the chart returns blocked, inspect its clarification question and check the remembered resolution. Ask the user when it is missing or stale; record their answer with `bugmole_resolve_blocker`, then retry the chart.",
+            "10. Continue this chart-check loop until every transition is runtime-verified, the terminal goal is completed, and `bugmole_journey_next` returns exhausted or an explicit blocked reason that cannot be resolved.",
+            "11. Once the flow is exhausted, write its test case assumptions: read `bugmole://spec/test-cases.schema.json` and call `bugmole_write_test_cases` with one case per step worth proving. Each case must name a real `nodeId` from that journey, state what it is trying to prove, and list observable expectations. Cite what each assumption is based on in `basis`; a case with nothing behind it must be `confidence: \"low\"` rather than a confident guess.",
+            "12. Confirm the selected actor exists in `roles.yaml`, then call `bugmole_plan` only after the flow is exhausted or documented as blocked.",
+            "13. After a run actually exercises those cases, record what it observed: read `bugmole://spec/test-case-results.schema.json` and call `bugmole_write_test_case_results` with one result per case you checked. This is the only thing that moves a case off \"planned\" — writing assumptions never counts as proof, so a flow whose cases were verified but never recorded reads as 0% covered. Say what you saw in `detail` (status code, element present or missing, assertion that failed), use \"failed\" when a check ran and the expectation did not hold, and \"blocked\" only when it could not be run at all. Do not record a result for a case you did not actually exercise.",
+            "14. Commit progress/results with `bugmole_commit_response`, always including the returned `nextSteps` until the workflow is complete.",
+            "",
+            "A plan with no discovered journey evidence, a generic fallback action, or an unchecked actionable flow task is incomplete and must not be published as ready to run.",
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+  if (uri === "bugmole://guidance/app-ui-audit") {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: [
+            "# Bugmole application UI audit",
+            "",
+            "Start by populating the component library, because this task is the only thing that does. Call `bugmole_ui_re_start` with kind `existing_app` and the application's base URL, then `bugmole_ui_re_stage` with stage `atoms`. That runs the Storybook/CSF source scan and records the catalogue the dashboard's component library and the step sheet's component chips read. If the project has no Storybook, the scan returns a blocked reason — report that reason as-is; do not invent components to fill the library.",
+            "",
+            "Then reproduce the requested user flow in the running product and audit every user-facing button, link, row, card, and other interactive control.",
+            "",
+            "For each screen, group and report every control with:",
+            "1. Visible label or action",
+            "2. Status: Implemented, Partially implemented, or Not implemented",
+            "3. Destination, callback, or handler",
+            "4. Runtime or source-code evidence",
+            "5. Missing backend, persistence, validation, or integration behavior",
+            "",
+            "Use these definitions:",
+            "- Implemented: the intended action works end-to-end.",
+            "- Partially implemented: the UI responds, but some persistence, backend, validation, or integration is incomplete.",
+            "- Not implemented: the control is dead, has a no-op handler, only shows a placeholder/mock message, or has no working destination.",
+            "",
+            "Include navigation controls, tabs, forms, selectable cards, external links, CTAs, menu rows, and controls that visually appear interactive. Do not count static text as a link unless it has a real handler.",
+            "",
+            "Verify findings at runtime where possible, then inspect the source code to catch hidden or unreachable controls. Ignore unreachable legacy branches unless they affect the active user flow.",
+            "",
+            "Report:",
+            "- A brief summary of totals by status",
+            "- A complete screen-by-screen grouping",
+            "- Evidence for each finding",
+            "- The highest-priority missing implementations",
+            "- Any blocked verification steps and why",
+            "",
+            "The canonical deliverable is JSON, not markdown. Read bugmole://spec/app-ui-audit.schema.json, build one object matching that schema, and call bugmole_write_ui_audit with the completed object. Do not omit screens with zero findings or blocked verification entries.",
+            "The tool writes the dashboard-consumable file under the project-scoped ui-audits artifact prefix and returns its artifact key. You may additionally create a visual artifact or canvas for a large human-readable presentation, but it does not replace the JSON file.",
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+  if (uri === "bugmole://guidance/ui-parity-audit") {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: [
+            "# Bugmole UI parity audit",
+            "",
+            "Use this task only after the user supplies a reference experience (URL, HTML, old app link, screenshots, or Figma) and the current application has already been implemented.",
+            "This task compares the reference and current implementation. It does not replace the application UI audit: do not produce a control-by-control implementation status report here.",
+            "",
+            "First create a flow matrix for every reachable reference screen, navigation path, interaction, state transition, authentication state, loading state, error state, and backend-dependent action.",
+            "",
+            "Explore the reference systematically, recording screens, actions, resulting behavior, navigation, unavailable or ambiguous behavior, and before/after screenshots for meaningful actions.",
+            "Audit the current implementation by mapping reference screens/actions to routes, components, and service/API callers. Verify guest, authenticated, loading, empty, error, logout, deep-link, callback, persistence, and API-error states. Confirm displayed data is live rather than fixture data.",
+            "Use Python with Pillow for the visual comparison. Capture the reference with a Playwright screenshot and the app with `adb exec-out screencap -p`. Normalize both to the same viewport, such as 390x844. Run `python scripts/ui-parity-diff.py --reference reference.png --actual actual.png --output-dir parity-output --width 390 --height 844 --threshold 16` to calculate `ImageChops.difference()`, count pixels whose channel difference exceeds the threshold, and generate a heatmap.",
+            "Save the resulting `diff.json` and `heatmap.png` paths in the parity artifact. The difference score is a percentage: 0% means identical pixels and higher percentages mean more visual difference. Treat status bars, navigation bars, viewport scaling, fonts, and image loading as diagnostic factors rather than automatically as product defects.",
+            "Separate visual, behavioral, backend, and authentication mismatches.",
+            "Fix confirmed issues in place when authorized, preserve live integrations and design tokens, rebuild, replay changed flows, recapture screenshots, rerun comparisons, and inspect runtime/auth/network/API logs.",
+            "",
+            "The canonical deliverable is JSON. Read bugmole://spec/ui-parity-audit.schema.json, create a complete object including the flow matrix, reference/current captures, difference percentages, changed/total pixel counts, heatmaps, issues, artifact paths, blocked verification, and a concise fixPrompt for any remaining work, then call bugmole_write_ui_parity_audit.",
+            "Tag each issue with the screenId of the comparison it was found on. The dashboard groups the bug list by step using this field; an issue left untagged is shown as ungrouped rather than guessed at.",
+            "The tool writes the dashboard-consumable file under the project-scoped ui-parity-audits artifact prefix. The dashboard displays only this JSON artifact.",
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+  if (uri === "bugmole://guidance/ui-reverse-engineering") {
+    return {
+      contents: [{
+        uri,
+        mimeType: "text/markdown",
+        text: [
+          "# Bugmole UI reverse-engineering coordinator",
+          "",
+          "Run the coordinator inside-out: normalize the reference, measure regions, infer or reuse the project Design DNA, extract atoms, compose molecules/organisms/templates/pages, then validate parity.",
+          "Design DNA is the project genome. Match its spacing, radius, elevation, color, motion, icon, and typography tokens before creating a new primitive. Any extension must include provenance, confidence, and a reason existing tokens cannot satisfy the screen.",
+          "Use bugmole_ui_re_start with an image, Figma export, PDF, URL, HTML, or existing-app input. Advance the resumable job with bugmole_ui_re_stage in this order: measure, dna, atoms, reconcile, complete.",
+          "When a reference is a URL, open it in the browser and capture the rendered reference before analyzing it. Associate the capture with the relevant journey steps; do not treat the URL string itself as screenshot evidence.",
+          "For each reachable journey node, try a reference capture first when the mockup is active and related. If it is archived or unrelated, capture the current app instead. If neither capture is possible, preserve the node and record an explicit blocked reason.",
+          "Use bugmole_ui_re_status after every stage. Treat low-confidence measurements and unavailable adapters as blocked evidence, not as invented facts.",
+          "Reuse canonical components and stable BEM names from the project playbook. Reconcile only the affected dependency branch after a mismatch.",
+          "For full reference-versus-current comparison, continue with bugmole_write_ui_parity_audit and include Design DNA token references and token-drift mismatches.",
+        ].join("\n"),
+      }],
+    };
+  }
+  if (uri === "bugmole://guidance/agent-task-queue") {
+    return {
+      contents: [{
+        uri,
+        mimeType: "text/markdown",
+        text: [
+          "# Bugmole agent task queue",
+          "",
+          "Call bugmole_task_next with a stable workerId before starting queued work.",
+          "Inspect the repository, implement the task, and report progress with bugmole_report_progress.",
+          "If the task includes journeyId and journeyRevision, load that exact project-scoped journeys/graph.json revision and follow its branches in order.",
+          "For taskType ui, read the parity guidance and schema, rerun affected flows, generate a fresh parity artifact, and include parityAuditId and parityMatchScore.",
+          "A UI task cannot be completed without fresh parity evidence. If parity is blocked, leave the task blocked with concrete next steps.",
+          "When finished, call bugmole_task_update with status completed, completionSummary, changedFiles, and required parity evidence.",
+          "",
+          "Finishing a task is not the end of the work. This queue drives an autonomous pipeline: explore, then define any missing actors in roles.yaml, then write test case assumptions with bugmole_write_test_cases, then bugmole_plan. If your task leaves an obvious next stage undone, queue it with bugmole_task_create before you complete, using a stable idempotencyKey of the form `pipeline:<projectId>:<stage>:<journeyId>` so it cannot duplicate an existing one.",
+          "The worker independently reconciles the same pipeline from the artifacts on disk, so a follow-up you skip is still picked up. Never invent a stage that the evidence does not support just to keep the pipeline moving, and never mark work completed that you did not actually finish — a blocked task with concrete next steps is more useful than a false completion.",
+        ].join("\n"),
+      }],
+    };
+  }
+  if (uri.startsWith("bugmole://spec/")) {
+    const filePath = uri.replace("bugmole://spec/", "");
+    const fullPath = path.join(specDir, filePath);
+
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Resource not found: ${uri}`);
+    }
+
+    const content = fs.readFileSync(fullPath, "utf-8");
+    const mimeType =
+      filePath.endsWith(".yaml") || filePath.endsWith(".yml")
+        ? "application/x-yaml"
+        : "application/json";
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType,
+          text: content,
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown resource URI: ${uri}`);
+}
+
+export async function getPrompt(params: any, cfg: any): Promise<any> {
+  const { name, arguments: args } = params;
+  const promptsDir = path.join(process.cwd(), "docs");
+
+  switch (name) {
+    case "guided_testing_workflow":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                "You are operating under Bugmole's guided testing workflow.",
+                "First read the bugmole://guidance/agent-testing resource.",
+                "Then inspect the repository's package/config files, application entrypoints, routes, and relevant spec files before choosing a journey.",
+                "Use bugmole_explore for source/application discovery when a runnable base URL exists. If you have an authenticated browser session, inspect the owner dashboard there and persist concrete observations with bugmole_record_discovery.",
+                "After every meaningful phase, call bugmole_report_progress, read the current journey chart, and call bugmole_journey_next.",
+                "Perform the returned flow task, record its concrete screen/transition evidence, and repeat the chart check until it returns exhausted or blocked.",
+                "Before bugmole_plan, verify that the journey graph has real nodes/actions, no actionable next task remains, and the actor exists in roles.yaml.",
+                "If discovery is incomplete, return a blocked status with concrete next_steps instead of creating a generic login-only plan.",
+                "After planning, read the generated plan resource, validate its steps against the discovered evidence, and only then hand it to the dashboard for execution.",
+              ].join("\n"),
+            },
+          },
+        ],
+      };
+    case "app_ui_audit":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                "You are performing Bugmole's application UI audit task.",
+            "First select the requested journey and reproduce its user flow in the running product.",
+            "Before auditing, call `bugmole_journey_next` and perform every actionable task, recording each screen, transition, and terminal goal completion. Do not audit a generic login or first screen.",
+            "If the flow is blocked, check the returned blocker fingerprint and remembered resolution. Ask the user for clarification when needed, record the answer with `bugmole_resolve_blocker`, and retry before proceeding.",
+            "Only call `bugmole_write_ui_audit` when the flow is exhausted or explicitly blocked. Include journeyId, journeyRevision, exploredNodeIds, exploredEdgeIds, and the matching flowStatus.",
+                "Then audit every user-facing button, link, row, card, and other interactive control on each screen in the flow.",
+                "For every control, report its visible label or action, status (Implemented, Partially implemented, or Not implemented), destination/callback/handler, runtime or source-code evidence, and missing backend, persistence, validation, or integration behavior.",
+                "Implemented means the intended action works end-to-end. Partially implemented means the UI responds but some persistence, backend, validation, or integration is incomplete. Not implemented means the control is dead, has a no-op handler, only shows a placeholder/mock message, or has no working destination.",
+                "Include navigation controls, tabs, forms, selectable cards, external links, CTAs, menu rows, and controls that visually appear interactive. Do not count static text as a link unless it has a real handler.",
+                "Verify findings at runtime where possible, then inspect source code for hidden or unreachable controls. Ignore unreachable legacy branches unless they affect the active flow.",
+                "Report status totals, complete screen-by-screen findings, evidence for each finding, highest-priority missing implementations, and blocked verification steps with reasons.",
+                "The canonical deliverable is JSON, not markdown. Read bugmole://spec/app-ui-audit.schema.json, construct one object matching it, and call bugmole_write_ui_audit. The tool writes the project-scoped JSON file and returns its artifact key.",
+                "A visual artifact or canvas may supplement a large audit, but it never replaces the required JSON file.",
+              ].join("\n"),
+            },
+          },
+        ],
+      };
+    case "ui_parity_audit":
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                "You are performing Bugmole's UI parity audit task.",
+                "The user has supplied a reference experience and the current application has already been implemented. Do not start by inventing a reference and do not duplicate the control-by-control app UI audit.",
+                "Read bugmole://guidance/ui-parity-audit and bugmole://spec/ui-parity-audit.schema.json first.",
+                "Create a flow matrix covering every reachable reference screen, navigation path, interaction, state transition, authentication state, loading state, error state, and backend-dependent action.",
+                "Systematically explore the reference and current app, capture before/after screenshots for meaningful actions, map reference actions to current routes/components/API callers, and verify guest, authenticated, loading, empty, error, logout, deep-link, callback, persistence, and API-error states.",
+                "Capture reference screens with Playwright and current app screens with `adb exec-out screencap -p`. Normalize both to 390x844 (or another explicitly recorded viewport), then run `python scripts/ui-parity-diff.py` with Pillow to compute thresholded `ImageChops.difference()` pixels and a heatmap. A 0% difference score means identical pixels; higher percentages mean more visual difference.",
+                "Record diff.json, normalized screenshots, and heatmap paths. Separate visual, behavioral, backend, and authentication parity.",
+                "Fix confirmed issues in place when authorized, rebuild, replay changed flows, recapture screenshots, rerun comparisons, and inspect runtime/auth/network/API logs.",
+                "The required final deliverable is a JSON object matching the parity schema. Include reference/current sources, flowMatrix, comparisons with differencePercent/changedPixels/totalPixels/heatmap, separate parity scores, issues (each tagged with the screenId it was found on, so the dashboard can group the bug list by step), artifact paths, blocked verification, and a concise fixPrompt. Call bugmole_write_ui_parity_audit so the dashboard can consume the JSON artifact.",
+              ].join("\n"),
+            },
+          },
+        ],
+      };
+    case "ui_reverse_engineering":
+      return {
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "You are Bugmole's UI Reverse Engineering Coordinator.",
+              "Read bugmole://guidance/ui-reverse-engineering and bugmole://spec/ui-reverse-engineering.schema.json first.",
+              "Use bugmole_ui_re_start for the supplied image, Figma export, PDF, URL, HTML, or existing-app input, then advance the same job through measure, dna, atoms, and complete stages.",
+              "Measure before inferring. Treat Design DNA as the project genome and reuse its tokens before introducing primitives. Record provenance and confidence for every decision.",
+          "Build and validate Atomic Design output inside-out: atoms, molecules, organisms, templates, then pages. Treat atoms and molecules as the reusable component playbook. The atomic stage scans the project for .storybook/main.* and CSF *.stories.* files, persists a Storybook component catalog, and maps each catalog entry into the atomic graph; use the discovered stories as the source of truth instead of inventing components.",
+              "When a mockup is supplied as a URL, browse to the URL and capture the rendered reference before extracting regions. Attach reference captures to the journey steps; if the reference is archived or unrelated, capture the current app instead, and report blocked capture attempts explicitly.",
+              "For existing applications, map reference regions to routes/components and use the parity workflow for current captures. Report blocked adapters and low-confidence findings explicitly.",
+            ].join("\n"),
+          },
+        }],
+      };
+    case "agent_task_execution":
+      return {
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "You are continuing a dashboard-created Bugmole agent task.",
+              "Read bugmole://guidance/agent-task-queue, then call bugmole_task_next with a stable workerId.",
+              "Implement the claimed task and report progress. For UI tasks, rerun parity after the fix and do not complete without a fresh parity audit id and match score.",
+              "Call bugmole_task_update with completed or blocked status and concrete evidence.",
+            ].join("\n"),
+          },
+        }],
+      };
+    case "file_authoring":
+      const authoringPath = path.join(promptsDir, "file-authoring-template.md");
+      if (fs.existsSync(authoringPath)) {
+        let template = fs.readFileSync(authoringPath, "utf-8");
+        // Replace template variables
+        if (args.filePath) template = template.replace(/<FILE_PATH>/g, args.filePath);
+        if (args.filePurpose) template = template.replace(/<FILE_PURPOSE>/g, args.filePurpose);
+        return {
+          messages: [{ role: "user", content: { type: "text", text: template } }],
+        };
+      }
+      throw new Error("File authoring template not found");
+
+    case "diff_proposal":
+      const diffPath = path.join(promptsDir, "diff-proposal-template.md");
+      if (fs.existsSync(diffPath)) {
+        let template = fs.readFileSync(diffPath, "utf-8");
+        if (args.filePath) template = template.replace(/<FILE_PATH>/g, args.filePath);
+        if (args.filePurpose) template = template.replace(/<FILE_PURPOSE>/g, args.filePurpose);
+        return {
+          messages: [{ role: "user", content: { type: "text", text: template } }],
+        };
+      }
+      throw new Error("Diff proposal template not found");
+
+    case "review_approval":
+      const reviewPath = path.join(promptsDir, "review-approval-template.md");
+      if (fs.existsSync(reviewPath)) {
+        let template = fs.readFileSync(reviewPath, "utf-8");
+        if (args.filePath) template = template.replace(/<FILE_PATH>/g, args.filePath);
+        if (args.filePurpose) template = template.replace(/<FILE_PURPOSE>/g, args.filePurpose);
+        return {
+          messages: [{ role: "user", content: { type: "text", text: template } }],
+        };
+      }
+      throw new Error("Review approval template not found");
+
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+}
+
+export function readSpecFile(filePath: string, cfg: any): any {
+  const specDir = cfg.runtime.spec_dir || "./spec";
+
+  // Try multiple path resolution strategies
+  const possiblePaths: string[] = [];
+
+  // If filePath is already absolute, try it first
+  if (path.isAbsolute(filePath)) {
+    possiblePaths.push(filePath);
+  }
+
+  // Standard: spec_dir + filePath
+  possiblePaths.push(path.join(specDir, filePath));
+
+  // Remove spec/ prefix if present (e.g., "spec/plans/file.yaml" -> "plans/file.yaml")
+  if (filePath.startsWith("spec/")) {
+    possiblePaths.push(path.join(specDir, filePath.replace(/^spec\//, "")));
+  }
+
+  // Try with resolved absolute paths
+  possiblePaths.push(path.resolve(specDir, filePath));
+  if (filePath.startsWith("spec/")) {
+    possiblePaths.push(path.resolve(specDir, filePath.replace(/^spec\//, "")));
+  }
+
+  // Try from current working directory
+  possiblePaths.push(path.join(process.cwd(), specDir, filePath));
+  if (filePath.startsWith("spec/")) {
+    possiblePaths.push(path.join(process.cwd(), specDir, filePath.replace(/^spec\//, "")));
+  }
+
+  // Try common project locations (if we're in ai-qa-framework but working on neko-coffee)
+  // This is a fallback for when MCP server runs from framework but spec is in project
+  const commonProjectDirs = [
+    process.env.CURSOR_PROJECT_DIRECTORY,
+    process.env.BUGMOLE_PROJECT_DIR,
+    process.cwd(),
+  ].filter(Boolean);
+
+  for (const projectDir of commonProjectDirs) {
+    if (projectDir) {
+      const projectSpecDir = path.join(projectDir, "spec");
+      possiblePaths.push(path.join(projectSpecDir, filePath));
+      if (filePath.startsWith("spec/")) {
+        possiblePaths.push(path.join(projectSpecDir, filePath.replace(/^spec\//, "")));
+      }
+      // Also try without spec/ prefix
+      if (!filePath.startsWith("spec/")) {
+        possiblePaths.push(path.join(projectSpecDir, filePath));
+      }
+    }
+  }
+
+  // Additional fallback: if we're in ai-qa-framework, try to find neko-coffee or other common project names
+  // This is a heuristic - look for parent directories and sibling directories that might contain the project
+  if (process.cwd().includes("ai-qa-framework")) {
+    const parentDir = path.dirname(process.cwd());
+    const commonProjectNames = ["neko-coffee", "kive", "neko-coffee-pos"];
+
+    // Try direct siblings first
+    for (const projectName of commonProjectNames) {
+      const potentialProjectDir = path.join(parentDir, projectName);
+      if (fs.existsSync(potentialProjectDir)) {
+        const projectSpecDir = path.join(potentialProjectDir, "spec");
+        possiblePaths.push(path.join(projectSpecDir, filePath));
+        if (filePath.startsWith("spec/")) {
+          possiblePaths.push(path.join(projectSpecDir, filePath.replace(/^spec\//, "")));
+        }
+        if (!filePath.startsWith("spec/")) {
+          possiblePaths.push(path.join(projectSpecDir, filePath));
+        }
+      }
+    }
+
+    // Also try nested paths like Projects/kive/neko-coffee
+    for (const projectName of commonProjectNames) {
+      // Try kive/neko-coffee structure
+      const kiveDir = path.join(parentDir, "kive");
+      if (fs.existsSync(kiveDir)) {
+        const potentialProjectDir = path.join(kiveDir, projectName);
+        if (fs.existsSync(potentialProjectDir)) {
+          const projectSpecDir = path.join(potentialProjectDir, "spec");
+          possiblePaths.push(path.join(projectSpecDir, filePath));
+          if (filePath.startsWith("spec/")) {
+            possiblePaths.push(path.join(projectSpecDir, filePath.replace(/^spec\//, "")));
+          }
+          if (!filePath.startsWith("spec/")) {
+            possiblePaths.push(path.join(projectSpecDir, filePath));
+          }
+        }
+      }
+    }
+
+    // Last resort: search common project locations more broadly
+    // Look for any directory containing 'neko-coffee' or 'kive' in the Projects folder
+    const projectsDir = parentDir;
+    if (fs.existsSync(projectsDir)) {
+      try {
+        const entries = fs.readdirSync(projectsDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const dirPath = path.join(projectsDir, entry.name);
+            // Check if this directory or its children might be the project
+            if (entry.name === "kive" || entry.name.includes("neko")) {
+              // Check for neko-coffee inside
+              try {
+                const subEntries = fs.readdirSync(dirPath, { withFileTypes: true });
+                for (const subEntry of subEntries) {
+                  if (
+                    subEntry.isDirectory() &&
+                    (subEntry.name.includes("neko") || subEntry.name.includes("coffee"))
+                  ) {
+                    const potentialProjectDir = path.join(dirPath, subEntry.name);
+                    const projectSpecDir = path.join(potentialProjectDir, "spec");
+                    if (fs.existsSync(projectSpecDir)) {
+                      possiblePaths.push(path.join(projectSpecDir, filePath));
+                      if (filePath.startsWith("spec/")) {
+                        possiblePaths.push(
+                          path.join(projectSpecDir, filePath.replace(/^spec\//, "")),
+                        );
+                      }
+                      if (!filePath.startsWith("spec/")) {
+                        possiblePaths.push(path.join(projectSpecDir, filePath));
+                      }
+                    }
+                  }
+                }
+              } catch {
+                // Ignore errors reading subdirectories
+              }
+            }
+          }
+        }
+      } catch {
+        // Ignore errors reading Projects directory
+      }
+    }
+  }
+
+  // Remove duplicates
+  const uniquePaths = Array.from(new Set(possiblePaths));
+
+  let fullPath: string | null = null;
+  for (const tryPath of uniquePaths) {
+    try {
+      if (fs.existsSync(tryPath)) {
+        fullPath = tryPath;
+        break;
+      }
+    } catch {
+      // Ignore errors checking paths
+    }
+  }
+
+  if (!fullPath) {
+    // Provide helpful error message with debug info
+    const debugInfo = {
+      filePath,
+      specDir,
+      cwd: process.cwd(),
+      specDirResolved: path.resolve(specDir),
+      specDirExists: fs.existsSync(specDir),
+      triedPaths: uniquePaths.slice(0, 5), // Show first 5 for brevity
+      env: {
+        CURSOR_PROJECT_DIRECTORY: process.env.CURSOR_PROJECT_DIRECTORY,
+        BUGMOLE_PROJECT_DIR: process.env.BUGMOLE_PROJECT_DIR,
+      },
+    };
+    throw new Error(
+      `Spec file not found: ${filePath}\n` +
+        `Tried ${uniquePaths.length} paths. First few: ${uniquePaths.slice(0, 3).join(", ")}\n` +
+        `Current working directory: ${process.cwd()}\n` +
+        `Spec dir from config: ${specDir} (resolved: ${path.resolve(specDir)})\n` +
+        `Hint: Make sure the spec files exist in the project directory, not the framework directory.`,
+    );
+  }
+
+  const content = fs.readFileSync(fullPath, "utf-8");
+  return {
+    content,
+    path: filePath,
+    fullPath: fullPath, // Include resolved path for debugging
+    size: content.length,
+  };
+}
+
+export function writeSpecFile(filePath: string, content: string, cfg: any): any {
+  const specDir = cfg.runtime.spec_dir || "./spec";
+  const fullPath = path.join(specDir, filePath);
+
+  // Ensure directory exists
+  const dir = path.dirname(fullPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Write file
+  fs.writeFileSync(fullPath, content, "utf-8");
+
+  return {
+    success: true,
+    path: filePath,
+    size: content.length,
+  };
+}