mergen-server 1.4.0

package/dist/intelligence/tools-utility.js

@@ -0,0 +1,430 @@
+import { z } from "zod";
+import { store } from "../sensor/buffer.js";
+import { getUsageSnapshot } from "./usage.js";
+import { getLicenseState } from "./license.js";
+import { layer3Store } from "../sensor/layer3-store.js";
+import { trackCall, buildCreditBar, setLastClearAt, withTierGate, entitlementLines, executionUsageLines } from "./tools-state.js";
+import { getTierForTool } from "./tool-manifest.js";
+import { saveSessionToHistory } from "../sensor/session-history.js";
+import { adrStore } from "../sensor/adr-store.js";
+import { confidenceStore, formatConfidenceReport } from "./confidence-report.js";
+import { generateRollbackPlan } from "./rollback.js";
+function registerUtilityTools(server) {
+  server.registerTool(
+    "get_status",
+    {
+      description: "Returns your current plan, credit usage, billing status, and next reset date. Use this to check how many incidents remain this month before calling that tool."
+    },
+    async () => {
+      const snap = getUsageSnapshot();
+      const licState = getLicenseState();
+      const lines = [
+        `## Mergen Status`,
+        "",
+        `**Plan:** ${snap.planName}`,
+        `**Period:** ${snap.month}  |  **Resets:** ${new Date(snap.resetsAt).toUTCString()}`,
+        ""
+      ];
+      if (snap.included === null) {
+        lines.push(`**Credits:** ${snap.used} used  (unlimited plan)`);
+      } else {
+        const bar = buildCreditBar(snap.used, snap.included);
+        lines.push(`**Credits:** ${snap.used} / ${snap.included} used  ${bar}`);
+        lines.push(`**Remaining:** ${snap.remaining}`);
+        if (snap.lowCredits)
+          lines.push(`\u26A0 **Low credits** \u2014 only ${snap.remaining} call(s) left at no extra charge.`);
+      }
+      if (snap.overage > 0) {
+        const rate = `$${(snap.overageCentsPerCredit / 100).toFixed(2)}/call`;
+        lines.push(
+          "",
+          `**Overage:** ${snap.overage} call(s) \xD7 ${rate} = **$${(snap.estimatedOverageCents / 100).toFixed(2)}** estimated`,
+          `**Billing status:** ${snap.billingStatus === "confirmed" ? "\u2705 confirmed" : "\u23F3 pending (will be sent to LemonSqueezy within 5 s)"}`
+        );
+      }
+      lines.push(...entitlementLines());
+      lines.push(...executionUsageLines());
+      if (licState?.customerEmail) {
+        lines.push("", `**Account:** ${licState.customerEmail}  |  Last validated: ${licState.validatedAt?.slice(0, 10)}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.registerTool(
+    "clear_buffer",
+    { description: "Clears all events from the in-memory buffer. The current session is archived to disk before clearing so it can be replayed later via get_session_replay." },
+    async () => {
+      const events = store.serialize();
+      saveSessionToHistory(events, "mcp-clear");
+      const was = store.size();
+      store.clear();
+      setLastClearAt(Date.now());
+      return { content: [{ type: "text", text: `Cleared ${was} event(s) from buffer. Session archived to history.` }] };
+    }
+  );
+  server.registerTool(
+    "mark_capture_start",
+    {
+      description: "Records the current timestamp as a capture-start point for this debug session. Call this BEFORE the user reproduces a bug. Then pass the returned `since` value to get_recent_logs and get_network_activity to see only what happened during reproduction. Workflow: (1) mark_capture_start \u2192 get timestamp T; (2) user reproduces bug; (3) get_recent_logs(since: T) + get_network_activity(since: T).",
+      inputSchema: {}
+    },
+    async () => {
+      const ts = Date.now();
+      const iso = new Date(ts).toISOString();
+      return {
+        content: [{
+          type: "text",
+          text: `Capture started at ${iso} (since: ${ts}).
+
+Now ask the user to reproduce the bug, then call:
+  get_recent_logs(since: ${ts})
+  get_network_activity(since: ${ts})`
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "export_session",
+    {
+      description: "Exports the current session \u2014 all buffered events, signals, and the latest analysis \u2014 as a structured JSON file in the current working directory. Use this to share a bug context with teammates or attach to a GitHub issue. Returns the file path and a human-readable summary.",
+      inputSchema: {
+        label: z.string().optional().describe("Optional filename label (default: session-<ISO timestamp>)")
+      }
+    },
+    async ({ label }) => {
+      const { writeFileSync } = await import("fs");
+      const { resolve } = await import("path");
+      const ts = Date.now();
+      const name = label ?? `session-${new Date(ts).toISOString().slice(0, 19).replace(/:/g, "-")}`;
+      const outPath = resolve(process.cwd(), `${name}.mergen-report.json`);
+      const logs = store.getLogs(200);
+      const network = store.getNetwork(200);
+      const context = store.getContext(20);
+      const testResults = store.getTestResults(50);
+      const diagnostics = store.getDiagnostics(50);
+      const signals = store.getSignals();
+      const report = {
+        exported_at: new Date(ts).toISOString(),
+        label: name,
+        summary: {
+          total_events: store.size(),
+          logs: logs.length,
+          network_events: network.length,
+          errors: logs.filter((l) => l.level === "error").length,
+          warnings: logs.filter((l) => l.level === "warn").length,
+          network_errors: network.filter((n) => n.status >= 400 || n.status === 0).length,
+          signals: signals.length,
+          test_failures: testResults.filter((t) => t.status === "fail").length
+        },
+        signals,
+        logs,
+        network,
+        context,
+        test_results: testResults,
+        diagnostics
+      };
+      writeFileSync(outPath, JSON.stringify(report, null, 2), "utf8");
+      const s = report.summary;
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `## Session Exported`,
+            "",
+            `**File:** \`${outPath}\``,
+            "",
+            `**Summary:**`,
+            `- ${s.logs} log events (${s.errors} errors, ${s.warnings} warnings)`,
+            `- ${s.network_events} network events (${s.network_errors} failures)`,
+            `- ${s.signals} active signals`,
+            `- ${s.test_failures} test failure(s)`,
+            "",
+            `Share with your team: \`cat ${outPath} | pbcopy\``
+          ].join("\n")
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "get_diagnostics",
+    {
+      description: "Returns recent editor diagnostic events (TypeScript/ESLint errors and warnings) captured from VS Code. Use this to correlate compile-time errors with runtime crashes.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(200).optional().describe("Max events (default 50)"),
+        severity: z.enum(["error", "warning", "info", "hint"]).optional().describe("Filter by severity"),
+        since: z.number().int().optional().describe("Only return events after this Unix ms timestamp")
+      }
+    },
+    async ({ limit = 50, severity, since }) => {
+      trackCall("get_diagnostics");
+      const events = store.getDiagnostics(limit, severity, since);
+      if (events.length === 0) {
+        return { content: [{ type: "text", text: "No editor diagnostics captured yet. Make sure the VS Code extension is installed and the Mergen server is running." }] };
+      }
+      const lines = [`## Editor Diagnostics (${events.length} events)`, ""];
+      for (const e of events) {
+        const icon = e.severity === "error" ? "\u{1F534}" : e.severity === "warning" ? "\u{1F7E1}" : "\u{1F535}";
+        lines.push(`${icon} **${e.severity.toUpperCase()}** \`${e.file}:${e.line}:${e.column}\``);
+        lines.push(`   ${e.source ? `[${e.source}] ` : ""}${e.message}${e.code ? ` (${e.code})` : ""}`);
+        lines.push(`   _${new Date(e.timestamp).toISOString()}_`, "");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.registerTool(
+    "get_test_results",
+    {
+      description: "Returns recent test results streamed from Vitest/Jest reporters. Shows failing tests with error messages and stack traces.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(200).optional().describe("Max events (default 50)"),
+        status: z.enum(["pass", "fail", "skip", "todo"]).optional().describe("Filter by test status"),
+        since: z.number().int().optional().describe("Only return events after this Unix ms timestamp")
+      }
+    },
+    async ({ limit = 50, status, since }) => {
+      trackCall("get_test_results");
+      const events = store.getTestResults(limit, status, since);
+      if (events.length === 0) {
+        return { content: [{ type: "text", text: "No test results captured yet. Add the Mergen reporter to your vitest.config.ts or jest.config.js." }] };
+      }
+      const byStatus = { pass: 0, fail: 0, skip: 0, todo: 0 };
+      for (const e of events) byStatus[e.status]++;
+      const lines = [
+        `## Test Results (${events.length} tests)`,
+        `\u2705 ${byStatus.pass} passed \xB7 \u274C ${byStatus.fail} failed \xB7 \u23ED ${byStatus.skip} skipped`,
+        ""
+      ];
+      const failing = events.filter((e) => e.status === "fail");
+      if (failing.length > 0) {
+        lines.push("### Failing tests:", "");
+        for (const e of failing) {
+          lines.push(`\u274C **${e.name}**`, `   File: \`${e.file}\``);
+          if (e.error) {
+            lines.push(`   Error: ${e.error.message}`);
+            if (e.error.stack) lines.push(`   \`\`\`
+   ${e.error.stack.slice(0, 500)}
+   \`\`\``);
+          }
+          lines.push("");
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.registerTool(
+    "create_ticket",
+    {
+      description: "Creates a pre-filled bug ticket in Linear or Jira from the current hypothesis. Auto-fills: title (hypothesis summary), description, reproduction steps, affected SHA, CODEOWNERS, and a link to the Mergen dashboard. Requires LINEAR_API_KEY + LINEAR_TEAM_ID or JIRA_BASE_URL + JIRA_API_TOKEN + JIRA_EMAIL + JIRA_PROJECT_KEY env vars.",
+      inputSchema: {
+        provider: z.enum(["linear", "jira"]).describe("Ticket system to create in"),
+        pid: z.string().optional().describe("Hypothesis pid to use (defaults to current top hypothesis)")
+      }
+    },
+    withTierGate(getTierForTool("create_ticket"), async ({ provider, pid }) => {
+      trackCall("create_ticket");
+      const port = process.env.PORT ?? "3000";
+      try {
+        const { default: http } = await import("http");
+        const body = JSON.stringify({ pid });
+        const resp = await new Promise((resolve, reject) => {
+          const req = http.request(
+            {
+              hostname: "127.0.0.1",
+              port: Number(port),
+              path: `/tickets/${provider}`,
+              method: "POST",
+              headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
+            },
+            (res) => {
+              let d = "";
+              res.on("data", (c) => {
+                d += c;
+              });
+              res.on("end", () => resolve(d));
+            }
+          );
+          req.on("error", reject);
+          req.write(body);
+          req.end();
+        });
+        const parsed = JSON.parse(resp);
+        if (!parsed.ok) {
+          return { content: [{ type: "text", text: `Failed to create ${provider} ticket: ${parsed.error ?? "unknown error"}` }] };
+        }
+        return {
+          content: [{
+            type: "text",
+            text: `\u2705 ${provider === "linear" ? "Linear" : "Jira"} ticket created!
+
+URL: ${parsed.url}
+ID: ${parsed.id ?? parsed.key}`
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error creating ticket: ${err instanceof Error ? err.message : String(err)}
+
+Make sure the Mergen server is running and the API keys are configured.` }] };
+      }
+    })
+  );
+  server.registerTool(
+    "get_snapshots",
+    {
+      description: "Returns diagnostic snapshots captured when a breakpoint was hit. Each snapshot bundles the triggering event with the 20 most recent console events, 10 most recent network events, and the latest DOM/storage context snapshot. Download a full snapshot bundle via GET /snapshots/:id. Use after set_breakpoint fires to replay the exact state offline.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(50).optional().describe("Max snapshots to return (default 10)")
+      }
+    },
+    async ({ limit }) => {
+      trackCall("get_snapshots");
+      const snaps = layer3Store.listSnapshots().slice(0, limit ?? 10);
+      if (snaps.length === 0) {
+        return { content: [{ type: "text", text: "No snapshots captured yet. Set a breakpoint with set_breakpoint, then trigger the condition in your browser." }] };
+      }
+      const lines = snaps.map((s) => {
+        const ts = new Date(s.capturedAt).toISOString();
+        const errSummary = s.recentLogs.filter((e) => e.level === "error").length;
+        const netFails = s.recentNetwork.filter((n) => n.status >= 400 || n.status === 0).length;
+        return [
+          `Snapshot ${s.id} @ ${ts}`,
+          `  Trigger: [${s.trigger.eventType}] ${s.trigger.summary}`,
+          `  Breakpoint: ${s.trigger.breakpointId}`,
+          `  Context: ${s.recentLogs.length} logs (${errSummary} errors), ${s.recentNetwork.length} network (${netFails} failures)`,
+          `  Stack: ${s.stack ? s.stack.split("\n")[0] : "none"}`,
+          `  Download: GET /snapshots/${s.id}`
+        ].join("\n");
+      });
+      return { content: [{ type: "text", text: `${snaps.length} snapshot(s):
+
+${lines.join("\n\n")}` }] };
+    }
+  );
+  server.registerTool(
+    "inject_logpoint",
+    {
+      description: "Injects a temporary log statement into the running browser page without restarting or redeploying. The logpoint attaches to a DOM element and fires on a given event, evaluating a JS expression. Results stream back via the ingest pipeline as console events. Use to add ad-hoc diagnostics to production-like sessions without modifying source code.",
+      inputSchema: {
+        selector: z.string().describe('CSS selector of the element to attach to (e.g. "#login-btn", "form.checkout")'),
+        event: z.string().describe('DOM event to listen for (e.g. "click", "submit", "change")'),
+        expression: z.string().describe(`JS expression to evaluate and log when the event fires (e.g. "document.querySelector('input[name=email]').value")`)
+      }
+    },
+    withTierGate(getTierForTool("inject_logpoint"), async ({ selector, event, expression }) => {
+      trackCall("inject_logpoint");
+      const id = layer3Store.injectLog(selector, event, expression);
+      return { content: [{ type: "text", text: `Logpoint injected (id: ${id}).
+Waiting for "${event}" on "${selector}".
+Expression: ${expression}
+Results will appear in get_recent_logs within seconds of the event firing.` }] };
+    })
+  );
+  server.registerTool(
+    "remove_logpoint",
+    {
+      description: "Removes a previously injected logpoint by its id.",
+      inputSchema: {
+        id: z.string().describe("Logpoint id returned by inject_logpoint")
+      }
+    },
+    withTierGate(getTierForTool("remove_logpoint"), async ({ id }) => {
+      trackCall("remove_logpoint");
+      const removed = layer3Store.removeInjectedLog(id);
+      return { content: [{ type: "text", text: removed ? `Logpoint ${id} removed.` : `Logpoint ${id} not found (may have already fired and auto-removed).` }] };
+    })
+  );
+  server.registerTool(
+    "search_adrs",
+    {
+      description: "Search Architectural Decision Records (ADRs) to understand why the system is built the way it is. Call this before modifying any module that has an associated ADR \u2014 it will surface the constraints and trade-offs that must remain intact. Returns matching ADRs with decision, rationale, and consequences.",
+      inputSchema: {
+        query: z.string().optional().describe("Keyword to filter ADRs (searches title, decision, rationale, alternatives). Omit to list all.")
+      }
+    },
+    async ({ query }) => {
+      trackCall("search_adrs");
+      const results = adrStore.list(query);
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: query ? `No ADRs matched "${query}".` : "No ADRs on record." }] };
+      }
+      const lines = [`## Architectural Decision Records (${results.length} found)`, ""];
+      for (const adr of results) {
+        lines.push(`### ${adr.id}: ${adr.title}`);
+        lines.push(`**Status:** ${adr.status}  |  **Date:** ${adr.date}`, "");
+        lines.push(`**Decision:** ${adr.decision}`, "");
+        if (adr.alternatives.length > 0) {
+          lines.push("**Alternatives rejected:**");
+          for (const alt of adr.alternatives) lines.push(`  - ${alt}`);
+          lines.push("");
+        }
+        lines.push(`**Rationale:** ${adr.rationale}`, "");
+        if (adr.consequences) lines.push(`**Consequences:** ${adr.consequences}`, "");
+        lines.push("---", "");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.registerTool(
+    "report_confidence",
+    {
+      description: 'File a pre-implementation confidence report before making any changes. This is the "Confidence Reporting" step of the structured agent workflow: declare your confidence score (0\u20131), what you are assuming, what you do not know, and which files you plan to modify. The report is stored and queryable via GET /confidence-reports. If confidence < 0.6, halt and present an impact report to the engineer before proceeding.',
+      inputSchema: {
+        confidence: z.number().min(0).max(1).describe("Confidence score from 0.0 (uncertain) to 1.0 (fully confident)"),
+        scope: z.string().min(1).max(300).describe("What this implementation covers"),
+        assumptions: z.array(z.string().max(500)).default([]).describe("Things treated as true without verification"),
+        unknowns: z.array(z.string().max(500)).default([]).describe("Open questions that could affect correctness"),
+        filesModified: z.array(z.string().max(500)).default([]).describe("Source files that will be changed"),
+        rationale: z.string().max(1e3).optional().describe("Explanation for the confidence score")
+      }
+    },
+    async ({ confidence, scope, assumptions, unknowns, filesModified, rationale }) => {
+      trackCall("report_confidence");
+      const report = confidenceStore.add({ confidence, scope, assumptions, unknowns, filesModified, rationale: rationale ?? "" });
+      const text = formatConfidenceReport(report);
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "plan_rollback",
+    {
+      description: "Generate a rollback plan BEFORE implementation starts. Provide the list of files you will modify and any commands you plan to execute. Returns: rollback procedure, whether auto-rollback is feasible, estimated recovery time, and the anticipated inverse commands. Review this plan alongside report_confidence before proceeding. The plan is also stored in the confidence report if one was filed for the same scope.",
+      inputSchema: {
+        files: z.array(z.string()).min(1).describe("Files that will be modified"),
+        commands: z.array(z.string()).optional().describe("Execution commands that will be run (kubectl, helm, npm, etc.)"),
+        featureFlag: z.string().optional().describe("Feature flag name that can disable this change at runtime")
+      }
+    },
+    async ({ files, commands, featureFlag }) => {
+      trackCall("plan_rollback");
+      const plan = generateRollbackPlan({ files, commands, featureFlag });
+      const lines = [
+        "## Rollback Plan",
+        "",
+        `**Files to modify:** ${plan.filesModified.length}`
+      ];
+      for (const f of plan.filesModified) lines.push(`  - \`${f}\``);
+      lines.push("");
+      if (plan.featureFlag) {
+        lines.push(`**Feature flag:** \`${plan.featureFlag}\` (fastest rollback path)`);
+        lines.push("");
+      }
+      lines.push(`**Can auto-rollback:** ${plan.canAutoRollback ? "Yes" : "No \u2014 manual intervention required"}`);
+      lines.push(`**Estimated recovery time:** ~${Math.round(plan.estimatedRollbackMs / 1e3)}s`);
+      lines.push("");
+      if (plan.anticipatedRollbackCommands.length > 0) {
+        lines.push("**Anticipated rollback commands:**");
+        for (const cmd of plan.anticipatedRollbackCommands) lines.push(`  \`${cmd}\``);
+        lines.push("");
+      }
+      lines.push("**Rollback procedure:**");
+      for (const step of plan.rollbackProcedure) lines.push(`  ${step}`);
+      if (!plan.canAutoRollback) {
+        lines.push("");
+        lines.push("> \u26A0 This change cannot be rolled back automatically. Ensure the engineer is available to intervene if regression is detected.");
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+export {
+  registerUtilityTools
+};

package/dist/intelligence/tools-validate.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { store } from "../sensor/buffer.js";
+import { getRecords, recordVerdict, updateCalibrationNote, getRealVerdictCount, isCorpusSeeded, classifyVerdict } from "./calibration.js";
+import { layer4Store } from "../sensor/layer4-store.js";
+import { closeSession } from "./session-metrics.js";
+import { trackCall } from "./tools-state.js";
+function _registerValidateFix(server) {
+  server.registerTool(
+    "validate_fix",
+    {
+      description: "Check whether a code fix actually resolved the issue. Pass the pid from reconstruct_context and the Unix ms timestamp from just before the fix was applied. Compares console error counts and network error counts before vs after. Returns RESOLVED (0 errors after), PARTIAL (\u226550% reduction), REGRESSED (more errors), or UNRESOLVED. Automatically records the verdict to the calibration corpus so future diagnoses improve. ALWAYS call this after applying a fix \u2014 even if you are confident it worked.",
+      inputSchema: {
+        pid: z.string().describe("Prediction id (pid) from reconstruct_context \u2014 identifies the hypothesis being validated"),
+        since: z.number().int().describe("Unix ms timestamp from just before the fix was applied \u2014 used as the before/after boundary"),
+        window_ms: z.number().int().min(5e3).max(3e5).optional().describe("How many ms of pre-fix history to compare against (default 60000 = 1 minute)")
+      }
+    },
+    async ({ pid, since, window_ms = 6e4 }) => {
+      trackCall("validate_fix");
+      const windowStart = since - window_ms;
+      const records = getRecords();
+      const prediction = records.find((r) => r.pid === pid);
+      const logsBefore = store.getLogs(200, "error", windowStart).filter((e) => e.timestamp < since);
+      const netBefore = store.getNetwork(200, void 0, windowStart).filter(
+        (e) => e.timestamp < since && (e.status >= 400 || !!e.error)
+      );
+      const logsAfter = store.getLogs(200, "error", since);
+      const netAfter = store.getNetwork(200, void 0, since).filter((e) => e.status >= 400 || !!e.error);
+      const errsBefore = logsBefore.length + netBefore.length;
+      const errsAfter = logsAfter.length + netAfter.length;
+      const verdict = classifyVerdict(errsBefore, errsAfter);
+      let status;
+      if (verdict === "correct") {
+        status = errsBefore === 0 ? "CLEAN \u2014 no errors before or after" : "RESOLVED";
+      } else if (verdict === "partial") {
+        status = "PARTIAL";
+      } else {
+        status = errsAfter > errsBefore ? "REGRESSED" : "UNRESOLVED";
+      }
+      if (prediction && !prediction.verdict) {
+        recordVerdict(pid, verdict);
+        if (prediction.errorFingerprint) {
+          layer4Store.linkFix(prediction.errorFingerprint, pid, prediction.tag, verdict);
+        }
+        const outcome = verdict === "correct" ? "resolved" : verdict === "partial" ? "partial" : "unresolved";
+        closeSession(pid, outcome);
+      }
+      const tag = prediction?.tag ?? "unknown";
+      const verdictEmoji = verdict === "correct" ? "\u2705" : verdict === "partial" ? "\u26A0\uFE0F" : "\u274C";
+      const lines = [
+        `## Fix Validation \u2014 \`${tag}\``,
+        "",
+        `**Status: ${verdictEmoji} ${status}**`,
+        "",
+        `| | Before fix | After fix |`,
+        `|---|---|---|`,
+        `| Console errors | ${logsBefore.length} | ${logsAfter.length} |`,
+        `| Network errors | ${netBefore.length}  | ${netAfter.length}  |`,
+        `| **Total** | **${errsBefore}** | **${errsAfter}** |`,
+        "",
+        prediction ? `Verdict \`${verdict}\` recorded for detector \`${prediction.tag}\`.` : `No prediction record found for pid \`${pid}\` \u2014 calibration not updated.`
+      ];
+      if (verdict === "wrong") {
+        lines.push(
+          "",
+          "### \u274C Diagnosis was incorrect",
+          "",
+          `The fix did not reduce errors \u2014 the \`${tag}\` hypothesis appears to have been wrong.`,
+          "",
+          "**What this means:**",
+          "- This verdict has been recorded. Future diagnoses for this pattern will be recalibrated downward.",
+          "- The causal chain may have been incomplete \u2014 only the first hypothesis was tested.",
+          "",
+          "**Next steps:**",
+          "1. Call `reconstruct_context` again \u2014 the wrong-verdict feedback improves the next analysis.",
+          "2. Check if errors changed in character (new error type appearing post-fix may reveal the real cause).",
+          "3. If you know what the actual root cause was, the calibration record is already saved \u2014 no additional action needed."
+        );
+      } else if (verdict === "partial") {
+        lines.push(
+          "",
+          "> \u26A0\uFE0F **Partial resolution** \u2014 errors reduced but not eliminated. The hypothesis may be correct but the fix incomplete, or there are multiple overlapping causes. Call `reconstruct_context` to check remaining signals."
+        );
+      }
+      if (logsAfter.length > 0) {
+        lines.push("", "### Remaining console errors:");
+        for (const e of logsAfter.slice(0, 5)) {
+          const msg = e.args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ").slice(0, 150);
+          lines.push(`- \`${new Date(e.timestamp).toISOString().slice(11, 19)}\` ${msg}`);
+        }
+      }
+      if (netAfter.length > 0) {
+        lines.push("", "### Remaining network errors:");
+        for (const n of netAfter.slice(0, 5)) {
+          lines.push(`- \`${new Date(n.timestamp).toISOString().slice(11, 19)}\` ${n.method} ${n.url} \u2192 ${n.status || "ERR"}`);
+        }
+      }
+      const realVerdicts = getRealVerdictCount();
+      const provisional = isCorpusSeeded() || realVerdicts < 10;
+      if (prediction && verdict !== "wrong") {
+        lines.push(
+          "",
+          "---",
+          "",
+          "### \u{1F4DD} Optional: record why (for future reference)",
+          "",
+          `Root cause \`${tag}\` is recorded. If you know *why* this pattern occurred \u2014 a constraint, a workaround, or context that would help future-you \u2014 call:`,
+          "",
+          `\`\`\``,
+          `record_fix_rationale(pid: "${pid}", rationale: "your note here")`,
+          `\`\`\``,
+          "",
+          "This is skippable at zero cost \u2014 ignore it and nothing breaks. If answered, the note surfaces wherever past incidents for this detector are shown."
+        );
+      }
+      if (provisional) {
+        const countLabel = realVerdicts === 0 ? "no local verdicts yet" : `${realVerdicts} local verdict${realVerdicts !== 1 ? "s" : ""} recorded`;
+        lines.push(
+          "",
+          `> \u26A0\uFE0F **Provisional accuracy** \u2014 ${countLabel} in this environment. The published 94% figure is from built-in priors, not measurements on your stack. Treat confidence scores as estimates until you have 10+ real verdicts. Autopilot applies a more conservative effective threshold during this period (the untrained classifier holds blended confidence below the execution gate).`
+        );
+      } else {
+        lines.push(
+          "",
+          `> \u2705 **${realVerdicts} local verdicts recorded** \u2014 confidence estimates are calibrated from your environment's actual incident history.`
+        );
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+function registerValidateFix(server) {
+  _registerValidateFix(server);
+}
+function registerValidateTools(server) {
+  _registerValidateFix(server);
+  server.registerTool(
+    "record_fix_rationale",
+    {
+      description: "Record WHY a root cause was correct \u2014 the constraint, workaround, or context that would help future-you. Call this immediately after validate_fix returns RESOLVED or PARTIAL. The note is stored on the calibration record and surfaced wherever past incidents for this detector are shown. Completely optional \u2014 if skipped, nothing breaks and you will not be reminded again for this incident.",
+      inputSchema: {
+        pid: z.string().describe("Prediction id (pid) from reconstruct_context / validate_fix"),
+        rationale: z.string().min(1).max(500).describe("Free-text note: why did this root cause occur? What constraint or context is worth remembering?")
+      }
+    },
+    async ({ pid, rationale }) => {
+      trackCall("record_fix_rationale");
+      const saved = updateCalibrationNote(pid, rationale);
+      return {
+        content: [{
+          type: "text",
+          text: saved ? `\u2705 Rationale recorded for prediction \`${pid}\`. It will appear in \`get_detector_calibration\` output for future incidents of the same type.` : `\u274C Prediction \`${pid}\` not found \u2014 rationale not saved. Check that the pid is from a recent \`reconstruct_context\` call.`
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "watch_for_fix",
+    {
+      description: "Start watching source files for changes so validate_fix runs automatically on each save. Returns immediately \u2014 validation happens in the background 2 seconds after any file changes. Results appear in the dashboard at http://127.0.0.1:3000/dashboard and in the next validate_fix call. Best practice: call right after reconstruct_context, before editing any files. Only one watch is active at a time \u2014 starting a new one stops the previous.",
+      inputSchema: {
+        pid: z.string().describe("Prediction id from reconstruct_context"),
+        since: z.number().int().describe("Unix ms timestamp from just before you started editing \u2014 the before/after boundary"),
+        paths: z.array(z.string()).min(1).max(50).describe('File or directory paths to watch for changes (e.g. ["src/auth/token.ts", "src/api/"])')
+      }
+    },
+    async ({ pid, since, paths }) => {
+      trackCall("watch_for_fix");
+      const { startFileWatch } = await import("../sensor/fs-watcher.js");
+      startFileWatch({ pid, since, paths });
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Watching ${paths.length} path${paths.length !== 1 ? "s" : ""} for changes.`,
+            "",
+            `Paths: ${paths.slice(0, 5).join(", ")}${paths.length > 5 ? ` +${paths.length - 5} more` : ""}`,
+            `Prediction: \`${pid}\``,
+            "",
+            `**Next steps:**`,
+            `1. Tell the user: "Apply your fix and save the file."`,
+            `2. After they save, call \`validate_fix(pid: "${pid}", since: ${since})\` to get the RESOLVED/PARTIAL/REGRESSED verdict.`,
+            `3. Report the verdict clearly: "\u2705 RESOLVED \u2014 0 errors after fix" or "\u274C UNRESOLVED \u2014 N errors remain".`,
+            `4. If RESOLVED, call \`stop_file_watch()\`. If not, show remaining errors and suggest next steps.`,
+            "",
+            `Dashboard: http://127.0.0.1:3000/dashboard (shows live validation state)`
+          ].join("\n")
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "stop_file_watch",
+    {
+      description: "Stop the active file watch. Called automatically when a fix is confirmed resolved. Call manually when switching to a different issue or ending a debug session.",
+      inputSchema: {}
+    },
+    async () => {
+      trackCall("stop_file_watch");
+      const { stopFileWatch, getWatchState } = await import("../sensor/fs-watcher.js");
+      const state = getWatchState();
+      stopFileWatch();
+      return {
+        content: [{
+          type: "text",
+          text: state ? `Stopped watching ${state.paths.length} path${state.paths.length !== 1 ? "s" : ""}.` : "No active file watch."
+        }]
+      };
+    }
+  );
+}
+export {
+  registerValidateFix,
+  registerValidateTools
+};

package/dist/intelligence/tools.js

@@ -0,0 +1 @@
+export * from '../__stubs__/closed-source.js';

package/dist/intelligence/trace-context.js

@@ -0,0 +1,11 @@
+import { randomUUID } from "crypto";
+function getTraceId() {
+  return process.env.MERGEN_TRACE_ID || randomUUID();
+}
+function traceEnv() {
+  return { MERGEN_TRACE_ID: getTraceId() };
+}
+export {
+  getTraceId,
+  traceEnv
+};