@codewithjuber/forgekit 0.8.0

package/src/cortex_hook.js

@@ -0,0 +1,197 @@
+// forge cortex hooks — the AMBIENT layer. Turns raw Claude Code hook events (edits, bash
+// runs, user prompts) into the correction episodes the orchestrator consumes, with zero
+// commands from the developer. Signal detection is PURE (over a normalized event log) so
+// it's unit-testable; the shell hooks just append events and call processSession on Stop.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { recordContradiction, recordMistake } from "./cortex.js";
+import { contentHash, slug } from "./util.js";
+
+const sessionFile = (root, sid) =>
+  join(root, ".forge", "sessions", `${String(sid).replace(/[^A-Za-z0-9_-]/g, "_")}.jsonl`);
+
+/** Append one normalized event to a session's log (called by capture hooks). */
+export function appendSessionEvent(root, sid, event) {
+  if (!event) return;
+  const path = sessionFile(root, sid);
+  mkdirSync(join(root, ".forge", "sessions"), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(event)}\n`);
+}
+
+export function readSession(root, sid) {
+  const path = sessionFile(root, sid);
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line)); // a single corrupt line must not lose the whole session log
+    } catch {}
+  }
+  return out;
+}
+
+export function clearSession(root, sid) {
+  const path = sessionFile(root, sid);
+  if (existsSync(path)) rmSync(path);
+}
+
+const REVERT_RE = /\bgit\s+(revert|reset\s+--hard|checkout\s+--|restore)\b/;
+const TEST_RE = /\b(npm\s+(run\s+)?test|node\s+--test|jest|vitest|pytest|go\s+test|cargo\s+test)\b/;
+// Negation must be corrective, not incidental ("no problem"); require a corrective verb.
+const NEG_RE = /\b(undo|revert|that'?s\s+wrong|not\s+what|you\s+broke|regression|wrong\s+again)\b/i;
+
+// A cheap signature of a failing test's output. Line numbers, hex addresses,
+// timings, and temp paths are normalized out so "the same failure" hashes the same across runs
+// even as surrounding noise shifts — this is what lets us catch a same-error doom loop.
+function outputSignature(text) {
+  const norm = String(text)
+    .toLowerCase()
+    .replace(/0x[0-9a-f]+/g, "0xADDR")
+    .replace(/\b\d+(\.\d+)?(ms|s)\b/g, "T")
+    .replace(/:\d+:\d+/g, ":L:C")
+    .replace(/\b\d+\b/g, "N")
+    .replace(/\/tmp\/\S+/g, "/tmp/X")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 800);
+  return norm ? contentHash(norm).slice(0, 12) : "";
+}
+
+/** Normalize a raw hook payload into a compact event, or null if it carries no signal. */
+export function classifyEvent(hook) {
+  const tool = hook.tool_name;
+  const inp = hook.tool_input ?? {};
+  if (tool === "Edit" || tool === "Write" || tool === "MultiEdit") {
+    return { type: "edit", file: inp.file_path ?? "" };
+  }
+  if (tool === "Bash") {
+    const exitCode = hook.exitCode;
+    const failed = typeof exitCode === "number" && exitCode !== 0;
+    const out = hook.tool_response?.stdout ?? hook.tool_response ?? hook.output ?? "";
+    return {
+      type: "bash",
+      command: inp.command ?? "",
+      exitCode,
+      // Only carry a signature for FAILED runs — that's all the doom-loop check needs.
+      ...(failed && out ? { outputSig: outputSignature(out) } : {}),
+    };
+  }
+  if (hook.hook_event_name === "UserPromptSubmit" || typeof hook.prompt === "string") {
+    return { type: "prompt", text: hook.prompt ?? "" };
+  }
+  return null;
+}
+
+/**
+ * Scan a session's normalized events and emit correction episodes. Signals are grouped
+ * PER FILE so the cross-family gate works (a lone thrash never fires; test-fail-then-pass
+ * on a file that was also edited does). Reverts become contradiction episodes.
+ * @returns {{kind:string, context:object, signals?:{signal:string}[], episodeId:string, nowDay:number}[]}
+ */
+export function detectEpisodes(events, { nowDay = 0 } = {}) {
+  const sig = new Map(); // file -> Set(signal)
+  const editCount = new Map();
+  const recentEdits = [];
+  const contradictions = [];
+  let sawTestFail = false;
+  let failFiles = new Set();
+  const add = (file, s) => {
+    if (!file) return;
+    if (!sig.has(file)) sig.set(file, new Set());
+    sig.get(file).add(s);
+  };
+
+  for (const e of events) {
+    if (e.type === "edit" && e.file) {
+      const n = (editCount.get(e.file) ?? 0) + 1;
+      editCount.set(e.file, n);
+      if (n >= 2) add(e.file, "S2"); // edited again this session = self-correction
+      if (n >= 3) add(e.file, "S3"); // thrash
+      recentEdits.push(e.file);
+      if (sawTestFail) failFiles.add(e.file);
+    } else if (e.type === "bash") {
+      if (TEST_RE.test(e.command)) {
+        if (typeof e.exitCode === "number" && e.exitCode !== 0) sawTestFail = true;
+        else if (e.exitCode === 0 && sawTestFail) {
+          for (const f of failFiles) add(f, "S1"); // fail → edit → pass, same files
+          sawTestFail = false;
+          failFiles = new Set();
+        }
+      }
+      if (REVERT_RE.test(e.command)) contradictions.push({ files: recentEdits.slice(-3) });
+    } else if (e.type === "prompt" && NEG_RE.test(e.text)) {
+      const f = recentEdits.at(-1);
+      if (f) add(f, "S5"); // weak; never fires alone (gate), needs a co-occurring signal
+    }
+  }
+
+  let seq = 0;
+  const episodes = [];
+  for (const [file, signals] of sig) {
+    episodes.push({
+      kind: "mistake",
+      context: { files: [file], symbols: [] },
+      signals: [...signals].map((s) => ({ signal: s })),
+      episodeId: `ep_m${seq++}_${slug(file)}`,
+      nowDay,
+    });
+  }
+  for (const c of contradictions) {
+    episodes.push({
+      kind: "contradiction",
+      context: { files: c.files, symbols: [] },
+      episodeId: `ep_c${seq++}`,
+      nowDay,
+    });
+  }
+  return episodes;
+}
+
+/**
+ * Doom-loop breaker (self-correction #5). The shell guard catches the SAME action repeated;
+ * this catches the subtler loop the paper names — different edits that keep producing the SAME
+ * test failure. When one failure signature recurs ≥ `threshold` times, the agent is stuck: halt
+ * and escalate with a diagnosis rather than burning more attempts. Pure + advisory.
+ * @returns {{loop:boolean, signature?:string, count?:number, files?:string[]}}
+ */
+export function detectDoomLoop(events, { threshold = 3 } = {}) {
+  const counts = new Map(); // outputSig -> occurrences
+  const filesAround = new Map(); // outputSig -> Set(files edited between failures)
+  let editsSinceFail = [];
+  for (const e of events) {
+    if (e.type === "edit" && e.file) {
+      editsSinceFail.push(e.file);
+    } else if (e.type === "bash" && e.outputSig) {
+      counts.set(e.outputSig, (counts.get(e.outputSig) ?? 0) + 1);
+      const set = filesAround.get(e.outputSig) ?? new Set();
+      for (const f of editsSinceFail) set.add(f);
+      filesAround.set(e.outputSig, set);
+      editsSinceFail = [];
+    }
+  }
+  let worst = null;
+  for (const [sig, count] of counts) {
+    if (count >= threshold && (!worst || count > worst.count)) {
+      worst = { signature: sig, count, files: [...(filesAround.get(sig) ?? [])] };
+    }
+  }
+  return worst ? { loop: true, ...worst } : { loop: false };
+}
+
+/** The advisory string for a detected doom loop (empty when there's no loop). */
+export function doomLoopAdvisory(events, opts = {}) {
+  const r = detectDoomLoop(events, opts);
+  if (!r.loop) return "";
+  const where = r.files.length ? ` around ${r.files.slice(0, 5).join(", ")}` : "";
+  return `Forge Cortex — doom loop: the SAME test failure has recurred ${r.count}× this session${where}. Different edits aren't fixing it. Stop, find the root cause (re-read the failing assertion and the code it exercises), or ask a human — don't keep patching.`;
+}
+
+/** Drive the orchestrator from a session's events (called by the Stop hook). */
+export function processSession(root, events, nowDay = 0) {
+  return detectEpisodes(events, { nowDay }).map((ep) =>
+    ep.kind === "contradiction"
+      ? recordContradiction(root, ep)
+      : recordMistake(root, { ...ep, signals: ep.signals ?? [] }),
+  );
+}

package/src/cortex_hook_main.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// forge cortex hook entrypoint — invoked by the shell hooks with the hook JSON on stdin.
+// FAIL-SAFE BY CONSTRUCTION: any error is swallowed and the process exits 0, so Cortex can
+// never block or break a tool call or a session. It is advisory memory, nothing more.
+//
+//   modes:  capture         (PostToolUse Edit|Write|Bash) — log a signal event
+//           prompt          (UserPromptSubmit)            — log a user-utterance event
+//           preflight       (UserPromptSubmit)            — inject the substrate pre-action advisory
+//           pre-edit        (PreToolUse Edit|Write)       — advise on lessons/risk before an edit
+//           stop            (Stop)                        — distill the session into lessons
+//           session-start   (SessionStart)               — inject learned lessons as context
+import { applyDistillation, lessonsForContext, startupBlock } from "./cortex.js";
+import {
+  appendSessionEvent,
+  classifyEvent,
+  clearSession,
+  doomLoopAdvisory,
+  processSession,
+  readSession,
+} from "./cortex_hook.js";
+import { load } from "./lessons_store.js";
+import { enforceDecision, substrateCheck, substrateContext } from "./substrate.js";
+import { epochDay } from "./util.js";
+
+// Opt-in: distill newly-created lessons into real prose via a cheap model call. Off by
+// default (deterministic template is used); fail-safe (any error → keep the template).
+async function enrichCreated(root, results) {
+  if (process.env.ENABLE_CORTEX_DISTILL !== "1") return;
+  const created = results.filter((r) => r?.action === "created" && r.id);
+  if (!created.length) return;
+  const { distill } = await import("./cortex_distill.js");
+  for (const r of created) {
+    const lesson = load(root).find((l) => l.id === r.id);
+    if (!lesson) continue;
+    const better = distill({
+      context: lesson.trigger,
+      signals: lesson.provenance?.signals ?? [],
+    });
+    if (better) applyDistillation(root, r.id, better);
+  }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const mode = process.argv[2];
+  let hook = {};
+  try {
+    hook = JSON.parse((await readStdin()) || "{}");
+  } catch {
+    return; // no/garbled payload → nothing to do
+  }
+  const root = hook.cwd || process.cwd();
+  const sid = hook.session_id || "default";
+  const today = epochDay();
+
+  if (mode === "capture" || mode === "prompt") {
+    appendSessionEvent(root, sid, classifyEvent(hook));
+  } else if (mode === "stop") {
+    const events = readSession(root, sid);
+    if (events.length) {
+      const results = processSession(root, events, today);
+      clearSession(root, sid);
+      await enrichCreated(root, results);
+    }
+  } else if (mode === "session-start") {
+    const block = startupBlock(root, today);
+    if (block) emit("SessionStart", block);
+  } else if (mode === "pre-edit") {
+    // A doom loop (the same failure recurring) is the loudest thing to say — it means "stop",
+    // so it takes precedence over lesson/risk advice.
+    const loop = doomLoopAdvisory(readSession(root, sid));
+    const advice = loop || (await preEditAdvisory(root, hook.tool_input?.file_path, today));
+    if (advice) emit("PreToolUse", advice);
+  } else if (mode === "preflight") {
+    // Ambient cognitive substrate: assumption gate + (when an atlas is already cached)
+    // model routing, blast-radius, memory, and minimality — surfaced before the agent acts.
+    // allowBuild:false keeps it cheap and never writes .forge/ from a hook; advisory only.
+    if (typeof hook.prompt === "string" && hook.prompt.trim()) {
+      const result = substrateCheck(root, hook.prompt, { allowBuild: false });
+      // Best-effort metrics recording — fills the cost dashboard pipeline without
+      // blocking the hook. A failing write is silently swallowed.
+      try {
+        const { record } = await import("./metrics.js");
+        record(root, { stage: "gate", outcome: result.gate?.halted ? "halt" : "pass" });
+        if (result.route?.key) {
+          record(root, { stage: "route", tier: result.route.tier });
+        }
+      } catch {}
+      const gate = enforceDecision(result);
+      if (gate.block) {
+        process.stdout.write(JSON.stringify({ decision: "block", reason: gate.reason }));
+        return;
+      }
+      const advisory = substrateContext(result);
+      if (advisory) emit("UserPromptSubmit", advisory);
+    }
+  }
+}
+
+function emit(hookEventName, additionalContext) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName, additionalContext },
+    }),
+  );
+}
+
+// Advisory before an edit: surface matching lessons (cheap), and — only if none matched —
+// a one-line high-risk note from the predictor. Advisory only, never blocks. Low-nag by
+// design: nothing is emitted unless there's a real lesson or genuinely high risk.
+async function preEditAdvisory(root, file, today) {
+  if (!file) return "";
+  const { block, selected } = lessonsForContext(
+    root,
+    { files: [file], symbols: [], keywords: [file] },
+    { nowDay: today, budget: 3 },
+  );
+  if (selected.length) return block; // learned lessons for this file win
+  const { featuresForEdit } = await import("./cortex_features.js");
+  const { riskFor } = await import("./predictor.js");
+  const { band } = riskFor(featuresForEdit(root, { file }, { nowDay: today }), {
+    mode: "heuristic",
+  });
+  return band === "high"
+    ? `Forge Cortex — ${file} looks high-risk (churn / prior mistakes here). Re-read and check impact before editing.`
+    : "";
+}
+
+main()
+  .catch((err) => {
+    if (process.env.FORGE_DEBUG === "1")
+      process.stderr.write(`forge cortex: ${err?.message ?? err}\n`);
+  })
+  .finally(() => process.exit(0));

package/src/cortex_mcp.js

@@ -0,0 +1,352 @@
+// forge cortex MCP — a minimal, zero-dependency MCP server (JSON-RPC 2.0 over stdio,
+// newline-delimited) that exposes this repo's LEARNED LESSONS to any MCP-capable tool
+// (Cursor, Codex, Gemini, Zed…). Claude gets lessons live via hooks; this is how the other
+// tools query them on demand. Launched as `forge cortex-mcp`, so the path resolves anywhere.
+import { readFileSync } from "node:fs";
+import { argv } from "node:process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { lessonsForContext, summary } from "./cortex.js";
+import { report as costReport } from "./cost_report.js";
+import { dashData } from "./dash.js";
+import { diagnose } from "./diagnose.js";
+import { doctor } from "./doctor.js";
+import { assessTask, clarifyBlock, preflightRepo } from "./preflight.js";
+import { routeTask } from "./route.js";
+import { decompose } from "./scope.js";
+import { predictImpact, substrateCheck } from "./substrate.js";
+import { epochDay } from "./util.js";
+
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const root = process.env.FORGE_ROOT || process.cwd();
+const today = epochDay;
+
+const TOOLS = [
+  {
+    name: "cortex_lessons",
+    description:
+      "Lessons Forge Cortex learned from past mistakes on THIS repo, for the given files/symbols. Background context — verify before acting, don't blindly obey.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description: "file paths in play",
+        },
+        symbols: {
+          type: "array",
+          items: { type: "string" },
+          description: "symbol names in play",
+        },
+      },
+    },
+  },
+  {
+    name: "cortex_status",
+    description: "Summary of learned lessons on this repo (counts by state, top by confidence).",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "preflight_check",
+    description:
+      "BEFORE starting a task, check what it names that the repo doesn't define — the things you'd otherwise ASSUME. Returns a clarify list or an all-clear. Ask instead of assuming.",
+    inputSchema: {
+      type: "object",
+      properties: { task: { type: "string", description: "the task/prompt" } },
+      required: ["task"],
+    },
+  },
+  {
+    name: "route_task",
+    description:
+      "Recommend the cheapest CAPABLE model for a task by code-task complexity (files, fan-out, churn, past mistakes, ambiguity). Advisory — don't burn a top model on a trivial task.",
+    inputSchema: {
+      type: "object",
+      properties: { task: { type: "string" } },
+      required: ["task"],
+    },
+  },
+
+  {
+    name: "assumption_gate",
+    description:
+      "Score specification completeness before work starts. Returns shouldAsk, risk, missing dimensions, and concrete questions.",
+    inputSchema: {
+      type: "object",
+      properties: { task: { type: "string", description: "the task/prompt" } },
+      required: ["task"],
+    },
+  },
+  {
+    name: "predict_impact",
+    description:
+      "Predict blast radius for a symbol or file using Forge atlas reverse-dependency traversal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: "string", description: "symbol name, qualified name, or file" },
+        threshold: { type: "number", description: "confidence threshold, default 0.1" },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "substrate_check",
+    description:
+      "Full Forge cognitive-substrate pre-action check: assumption gate, route, impact, scope, memory, minimality, and verification checklist.",
+    inputSchema: {
+      type: "object",
+      properties: { task: { type: "string", description: "the task/prompt" } },
+      required: ["task"],
+    },
+  },
+  {
+    name: "scope_files",
+    description:
+      "Decompose files into INDEPENDENT clusters (run as separate sessions) vs coupled, and surface coupled files you didn't name (the 'forgot the related module' guard).",
+    inputSchema: {
+      type: "object",
+      properties: { files: { type: "array", items: { type: "string" } } },
+      required: ["files"],
+    },
+  },
+  {
+    name: "forge_cost",
+    description:
+      "Cost report — measured stage factors (gate, cache, route, context) from .forge/metrics.jsonl with multiplicative composition.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "forge_dash_data",
+    description:
+      "Dashboard JSON payload — ledger stats, metrics, atlas info. Same data forge dash serves at /api/data.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "forge_brain",
+    description: "Project memory index — list all remembered facts stored in .forge/brain/.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "forge_ledger_query",
+    description:
+      "Query the proof-carrying memory ledger with a natural language query. Returns ranked matching claims.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "what you are about to do or looking for" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "forge_diagnose",
+    description:
+      "Doom-loop check — record a failure and check if the same signature has recurred (3x = escalation). Prevents thrashing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        errorText: { type: "string", description: "the error message" },
+        file: { type: "string", description: "file where the error occurred" },
+        symbol: { type: "string", description: "symbol involved" },
+      },
+      required: ["errorText"],
+    },
+  },
+  {
+    name: "forge_doctor",
+    description:
+      "Health check — verify installed tools, guards, MCP auth, config drift, and system state.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "forge_provider_status",
+    description:
+      "Provider detection — which API provider is active (auto-detected or configured), env vars set, and health checks.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function callTool(name, args = {}) {
+  if (name === "cortex_lessons") {
+    const files = args.files ?? [];
+    const symbols = args.symbols ?? [];
+    const { block } = lessonsForContext(
+      root,
+      { files, symbols, keywords: [...files, ...symbols] },
+      { nowDay: today() },
+    );
+    return block || "No lessons recorded for these files/symbols yet.";
+  }
+  if (name === "cortex_status") return JSON.stringify(summary(root, today()), null, 2);
+  if (name === "preflight_check") {
+    const r = preflightRepo(root, String(args.task ?? ""));
+    return clarifyBlock(r) || "All clear — everything this task names is grounded in the codebase.";
+  }
+  if (name === "route_task") {
+    const rec = routeTask(root, String(args.task ?? ""));
+    return `Recommended: ${rec.model.name} (${rec.tier}). complexity ${rec.score.toFixed(2)}${rec.reasons.length ? ` — ${rec.reasons.join(", ")}` : ""}.`;
+  }
+
+  if (name === "assumption_gate")
+    return JSON.stringify(assessTask(String(args.task ?? "")), null, 2);
+  if (name === "predict_impact")
+    return JSON.stringify(
+      predictImpact(root, String(args.target ?? ""), { threshold: Number(args.threshold ?? 0.1) }),
+      null,
+      2,
+    );
+  if (name === "substrate_check")
+    return JSON.stringify(substrateCheck(root, String(args.task ?? "")), null, 2);
+  if (name === "scope_files") {
+    const d = decompose(root, args.files ?? []);
+    return JSON.stringify(d, null, 2);
+  }
+  if (name === "forge_cost") return JSON.stringify(costReport(root), null, 2);
+  if (name === "forge_dash_data") return JSON.stringify(dashData(root), null, 2);
+  if (name === "forge_brain") {
+    try {
+      const { brainStore, list, buildIndex } = await import("./brain.js");
+      const store = brainStore(root);
+      const idx = buildIndex(store);
+      const items = list(store);
+      return JSON.stringify({ items, indexed: idx.indexed, overflow: idx.overflow }, null, 2);
+    } catch {
+      return "No brain store found — run `forge remember` to start.";
+    }
+  }
+  if (name === "forge_ledger_query") {
+    try {
+      const { loadClaims, repoLedger } = await import("./ledger_store.js");
+      const { retrieve, claimText } = await import("./ledger.js");
+      const { claimSim, simLabel } = await import("./embed.js");
+      const dir = repoLedger(root);
+      const q = String(args.query ?? "");
+      const claims = loadClaims(dir);
+      const sim = claimSim(root, q, claims, claimText);
+      const ranked = retrieve(q, claims, { nowDay: today(), budget: 8, sim });
+      return JSON.stringify(
+        {
+          sim: simLabel(sim),
+          results: ranked.map((r) => ({
+            id: r.claim.id,
+            kind: r.claim.kind,
+            score: r.score,
+            text: claimText(r.claim).slice(0, 200),
+          })),
+        },
+        null,
+        2,
+      );
+    } catch {
+      return "No ledger claims found.";
+    }
+  }
+  if (name === "forge_diagnose") {
+    const r = diagnose(root, {
+      errorText: String(args.errorText ?? ""),
+      file: args.file,
+      symbol: args.symbol,
+    });
+    return JSON.stringify(r, null, 2);
+  }
+  if (name === "forge_doctor") {
+    const { results, failed } = doctor({ targetRoot: root });
+    return JSON.stringify({ results, failed }, null, 2);
+  }
+  if (name === "forge_provider_status") {
+    const { activeProvider, providerStatus, listDetectedProviders } = await import(
+      "./providers.js"
+    );
+    const prov = activeProvider(root);
+    const status = providerStatus(root);
+    const detected = listDetectedProviders();
+    return JSON.stringify(
+      {
+        active: {
+          name: prov.name,
+          type: prov.type,
+          label: prov.label || prov.name,
+          baseUrl: prov.baseUrl,
+          autoDetected: Boolean(prov._autoDetected),
+          source: prov._source || null,
+        },
+        checks: status.checks,
+        availableProviders: detected,
+        envScan: status.envScan,
+      },
+      null,
+      2,
+    );
+  }
+  return null;
+}
+
+/** Handle one JSON-RPC message; returns a response object, or null for notifications. */
+export async function handle(msg) {
+  const { id, method, params } = msg;
+  if (id === undefined || String(method).startsWith("notifications/")) return null;
+  if (method === "initialize") {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: {
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "forge-cortex", version: PKG_VERSION },
+      },
+    };
+  }
+  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+  if (method === "tools/call") {
+    const text = await callTool(params?.name, params?.arguments);
+    if (text === null) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32602, message: `unknown tool: ${params?.name}` },
+      };
+    }
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { content: [{ type: "text", text }] },
+    };
+  }
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code: -32601, message: `unknown method: ${method}` },
+  };
+}
+
+export function serve(input = process.stdin, output = process.stdout) {
+  const rl = createInterface({ input });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return; // ignore malformed frames
+    }
+    handle(msg)
+      .then((res) => {
+        if (res) output.write(`${JSON.stringify(res)}\n`);
+      })
+      .catch(() => {});
+  });
+}
+
+// Only start the server when run directly (`forge cortex-mcp` / `node src/cortex_mcp.js`),
+// not when imported by tests.
+if (argv[1] && fileURLToPath(import.meta.url) === argv[1]) serve();