mergen-server 1.4.0

package/dist/routes/policy-nl.js

@@ -0,0 +1,169 @@
+import { Router } from "express";
+import { z } from "zod";
+import { randomUUID } from "crypto";
+function createPolicyNlRouter() {
+  const router = Router();
+  router.post("/policies/from-description", (req, res) => {
+    const body = z.object({ description: z.string().min(5).max(500) }).safeParse(req.body);
+    if (!body.success) {
+      res.status(400).json({ error: "description (string, 5-500 chars) required" });
+      return;
+    }
+    const result = parseNaturalLanguagePolicy(body.data.description);
+    res.json({ ok: true, ...result });
+  });
+  return router;
+}
+const DESTRUCTIVE_KEYWORDS = [
+  "terraform destroy",
+  "kubectl delete",
+  "rm -rf",
+  "drop table",
+  "drop database",
+  "truncate",
+  "delete all",
+  "wipe",
+  "nuke",
+  "format"
+];
+const SCHEMA_KEYWORDS = [
+  "migration",
+  "schema",
+  "alter table",
+  "add column",
+  "drop column",
+  "prisma migrate",
+  "db:migrate"
+];
+const KEYWORD_DOMAINS = [
+  { patterns: ["terraform", "infra", "infrastructure"], commands: ["terraform destroy", "terraform apply"], files: [".tf"] },
+  { patterns: ["database", "db", "postgres", "mysql", "sql"], commands: ["drop table", "drop database", "truncate table"], files: ["migration", "schema.sql"] },
+  { patterns: ["schema", "migration", "migrate"], commands: ["alter table", "db:migrate", "prisma migrate", "knex migrate"], files: ["migration"] },
+  { patterns: ["kubernetes", "k8s", "cluster", "kubectl"], commands: ["kubectl delete", "kubectl drain"], files: [] },
+  { patterns: ["auth", "authentication", "login", "jwt", "token"], commands: [], files: ["auth", "login", "jwt", "middleware"] },
+  { patterns: ["payment", "billing", "stripe", "checkout"], commands: [], files: ["payment", "billing", "stripe", "checkout"] },
+  { patterns: ["production", "prod"], commands: [], files: [] }
+];
+const DAY_MAP = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6
+};
+function parseNaturalLanguagePolicy(description) {
+  const lower = description.toLowerCase();
+  const notes = [];
+  const conditions = {};
+  let confidence = 0.5;
+  let action = "warn";
+  if (/\b(block|prevent|stop|deny|forbid|disallow|reject)\b/.test(lower)) {
+    action = "block";
+    confidence += 0.1;
+  } else if (/\b(warn|flag|alert|notify|hold|pause|review)\b/.test(lower)) {
+    action = "warn";
+    confidence += 0.1;
+  } else if (/\b(allow|permit|enable|pass|approve)\b/.test(lower)) {
+    action = "pass";
+    confidence += 0.05;
+  } else {
+    notes.push("Could not determine action (block/warn/pass) \u2014 defaulting to warn");
+  }
+  if (/\b(claude|cursor|agent|ai|bot|copilot|windsurf|automated|autonomous)\b/.test(lower)) {
+    conditions.actorType = "ai";
+    confidence += 0.05;
+  } else if (/\bhuman\b/.test(lower)) {
+    conditions.actorType = "human";
+    confidence += 0.05;
+  }
+  const envMatch = lower.match(/\b(production|prod|staging|stage|development|dev|test|testing)\b/);
+  if (envMatch) {
+    conditions.environments = [envMatch[1] === "stage" ? "staging" : envMatch[1] === "dev" ? "development" : envMatch[1]];
+    confidence += 0.1;
+  }
+  const daysFound = [];
+  for (const [name2, num] of Object.entries(DAY_MAP)) {
+    if (lower.includes(name2)) daysFound.push(num);
+  }
+  if (/\bweekend\b/.test(lower)) daysFound.push(0, 6);
+  if (/\bweekday\b/.test(lower)) daysFound.push(1, 2, 3, 4, 5);
+  if (daysFound.length > 0) {
+    conditions.daysOfWeek = [...new Set(daysFound)].sort();
+    confidence += 0.1;
+  }
+  const afterMatch = lower.match(/after\s+(\d{1,2})(am|pm)?/);
+  const beforeMatch = lower.match(/before\s+(\d{1,2})(am|pm)?/);
+  const betweenMatch = lower.match(/between\s+(\d{1,2})(am|pm)?\s+and\s+(\d{1,2})(am|pm)?/);
+  if (betweenMatch) {
+    const start = toHour(parseInt(betweenMatch[1]), betweenMatch[2]);
+    const end = toHour(parseInt(betweenMatch[3]), betweenMatch[4]);
+    conditions.hourWindow = [start, end];
+    confidence += 0.1;
+  } else if (afterMatch) {
+    const start = toHour(parseInt(afterMatch[1]), afterMatch[2]);
+    conditions.hourWindow = [start, 24];
+    confidence += 0.1;
+  } else if (beforeMatch) {
+    const end = toHour(parseInt(beforeMatch[1]), beforeMatch[2]);
+    conditions.hourWindow = [0, end];
+    confidence += 0.1;
+  }
+  const extractedCommands = [];
+  const extractedFiles = [];
+  for (const kw of DESTRUCTIVE_KEYWORDS) {
+    if (lower.includes(kw.split(" ")[0])) {
+      extractedCommands.push(kw);
+    }
+  }
+  for (const kw of SCHEMA_KEYWORDS) {
+    if (lower.includes(kw.split(" ")[0])) {
+      extractedCommands.push(kw);
+    }
+  }
+  for (const domain of KEYWORD_DOMAINS) {
+    if (domain.patterns.some((p) => lower.includes(p))) {
+      extractedCommands.push(...domain.commands);
+      if (domain.files) extractedFiles.push(...domain.files);
+    }
+  }
+  if (extractedCommands.length > 0) {
+    conditions.commands = [...new Set(extractedCommands)];
+    confidence += 0.15;
+  } else {
+    notes.push("Could not extract specific commands \u2014 you may need to add conditions.commands manually");
+    confidence -= 0.1;
+  }
+  if (extractedFiles.length > 0) {
+    conditions.files = [...new Set(extractedFiles)];
+  }
+  const actionWord = action;
+  const envWord = conditions.environments?.[0] ?? "";
+  const actorWord = conditions.actorType === "ai" ? "ai" : conditions.actorType === "human" ? "human" : "";
+  const domainWord = (conditions.commands?.[0] ?? "action").replace(/\s+/g, "_").replace(/[^a-z0-9_]/gi, "").slice(0, 20);
+  const id = [actionWord, actorWord, envWord, domainWord].filter(Boolean).join("_").toLowerCase().slice(0, 60) + "_" + randomUUID().slice(0, 4);
+  const name = description.slice(0, 60) + (description.length > 60 ? "\u2026" : "");
+  const envPhrase = conditions.environments ? ` in ${conditions.environments.join("/")}` : "";
+  const actorPhrase = conditions.actorType === "ai" ? " for AI agents" : conditions.actorType === "human" ? " for human operators" : "";
+  const reason = `Policy: ${actionWord === "block" ? "Blocked" : "Flagged"}${envPhrase}${actorPhrase} \u2014 ${description.slice(0, 120)}`;
+  if (Object.keys(conditions).length === 0) {
+    notes.push("No conditions could be extracted \u2014 this rule will match everything");
+    confidence = 0.2;
+  }
+  confidence = Math.min(0.95, Math.max(0.1, confidence));
+  return {
+    rule: { id, name, description, action, reason, conditions },
+    confidence: Math.round(confidence * 100) / 100,
+    notes
+  };
+}
+function toHour(h, meridiem) {
+  if (!meridiem) return h;
+  if (meridiem === "pm" && h < 12) return h + 12;
+  if (meridiem === "am" && h === 12) return 0;
+  return h;
+}
+export {
+  createPolicyNlRouter
+};

package/dist/routes/postmortem.js

@@ -0,0 +1,102 @@
+import express from "express";
+import { z } from "zod";
+import { fetchSlackThread } from "../intelligence/slack.js";
+import { draftPostmortemDoc } from "../intelligence/tools-runbook.js";
+import { generatePostmortem } from "../intelligence/postmortem-store.js";
+import { updateRunbookFromPostmortem } from "../intelligence/runbook-updater.js";
+import { getStores } from "../storage/store-registry.js";
+const BodySchema = z.object({
+  thread_url: z.string().url(),
+  service: z.string().optional(),
+  summary: z.string().optional(),
+  severity: z.enum(["sev1", "sev2", "sev3"]).optional(),
+  duration_minutes: z.number().int().min(1).max(1440).optional(),
+  affected_users: z.string().optional()
+});
+function createPostmortemRouter() {
+  const router = express.Router();
+  router.post("/postmortem/from-slack", async (req, res) => {
+    const parsed = BodySchema.safeParse(req.body);
+    if (!parsed.success) {
+      res.status(400).json({ error: "invalid request", details: parsed.error.flatten() });
+      return;
+    }
+    const { thread_url, service = "unknown", summary, severity, duration_minutes, affected_users } = parsed.data;
+    const slackThread = await fetchSlackThread(thread_url);
+    if (slackThread === null) {
+      res.status(422).json({
+        error: "Could not fetch Slack thread. Ensure MERGEN_SLACK_BOT_TOKEN is set with channels:history scope and the URL is a valid Slack thread link."
+      });
+      return;
+    }
+    const markdown = await draftPostmortemDoc({
+      service,
+      summary,
+      severity,
+      duration_minutes,
+      affected_users,
+      slack_thread: slackThread
+    });
+    const overrideEvent = await getStores().overrides.compileOverrideFromSlackThread(slackThread, service, req.tenantId);
+    const responsePayload = { markdown };
+    if (overrideEvent) {
+      responsePayload.overrideCompiled = true;
+      responsePayload.overrideId = overrideEvent.id;
+    } else {
+      responsePayload.overrideCompiled = false;
+    }
+    res.json(responsePayload);
+  });
+  const GenerateSchema = z.object({
+    pid: z.string().uuid(),
+    tag: z.string().min(1),
+    service: z.string().min(1),
+    rootCause: z.string().min(1),
+    fixCommand: z.string().nullable().optional(),
+    confidence: z.number().min(0).max(1),
+    mttrMs: z.number().int().min(0).nullable(),
+    resolvedAutonomously: z.boolean().default(false),
+    causallyCorrect: z.boolean().default(false),
+    evidence: z.array(z.string()).optional(),
+    fixHint: z.string().nullable().optional()
+  });
+  router.post("/postmortem/generate", async (req, res) => {
+    const parsed = GenerateSchema.safeParse(req.body);
+    if (!parsed.success) {
+      res.status(400).json({ error: "invalid request", details: parsed.error.flatten() });
+      return;
+    }
+    const input = parsed.data;
+    const pm = generatePostmortem({
+      pid: input.pid,
+      tag: input.tag,
+      service: input.service,
+      rootCause: input.rootCause,
+      fixCommand: input.fixCommand ?? null,
+      confidence: input.confidence,
+      mttrMs: input.mttrMs,
+      resolvedAutonomously: input.resolvedAutonomously,
+      causallyCorrect: input.causallyCorrect,
+      evidence: input.evidence,
+      fixHint: input.fixHint ?? null
+    });
+    let runbookUpdated = false;
+    try {
+      updateRunbookFromPostmortem(pm);
+      runbookUpdated = true;
+    } catch {
+    }
+    res.json({
+      pid: pm.pid,
+      tag: pm.tag,
+      service: pm.service,
+      mttrMs: pm.mttrMs,
+      causallyCorrect: pm.causallyCorrect,
+      runbookUpdated
+    });
+  });
+  return router;
+}
+export {
+  createPostmortemRouter
+};

package/dist/routes/pr-shadow.js

@@ -0,0 +1,47 @@
+import { Router } from "express";
+import { getPRShadowStats, getPRShadowResults } from "../sensor/pr-shadow-store.js";
+import { getUsageSnapshot } from "../intelligence/usage.js";
+const USEFUL_RATE_THRESHOLD = 40;
+const HELPFUL_RATE_THRESHOLD = 80;
+function createPRShadowRouter() {
+  const router = Router();
+  router.get("/pr-shadow/stats", (_req, res) => {
+    const stats = getPRShadowStats();
+    const usage = getUsageSnapshot();
+    const helpfulRate = usage.helpfulRate7d;
+    const helpfulRateOk = helpfulRate !== null && helpfulRate >= HELPFUL_RATE_THRESHOLD;
+    const usefulRateOk = stats.wouldHaveBeenUsefulRate !== null && stats.wouldHaveBeenUsefulRate >= USEFUL_RATE_THRESHOLD;
+    const readyForPRComments = helpfulRateOk && usefulRateOk;
+    res.json({
+      ok: true,
+      shadowMode: true,
+      prCommentsEnabled: process.env.MERGEN_PR_COMMENTS === "true",
+      readyForPRComments,
+      readyConditions: {
+        wouldHaveBeenUsefulRate: stats.wouldHaveBeenUsefulRate,
+        wouldHaveBeenUsefulRateThreshold: USEFUL_RATE_THRESHOLD,
+        wouldHaveBeenUsefulRateOk: usefulRateOk,
+        helpfulRate7d: helpfulRate,
+        helpfulRateThreshold: HELPFUL_RATE_THRESHOLD,
+        helpfulRateOk
+      },
+      ...stats,
+      nextSteps: readyForPRComments ? [
+        "Set MERGEN_PR_COMMENTS=true to enable Phase 2 PR comments.",
+        "Start with high-confidence incident matches only.",
+        "Monitor helpfulRate7d \u2014 disable if it drops below 70%."
+      ] : [
+        usefulRateOk ? `\u2713 wouldHaveBeenUsefulRate is ${stats.wouldHaveBeenUsefulRate}% \u2014 above threshold.` : `wouldHaveBeenUsefulRate is ${stats.wouldHaveBeenUsefulRate ?? "N/A"}% \u2014 needs ${USEFUL_RATE_THRESHOLD}%. Run mergen backfill github to populate the intent archive.`,
+        helpfulRateOk ? `\u2713 helpfulRate7d is ${helpfulRate}% \u2014 above threshold.` : `helpfulRate7d is ${helpfulRate ?? "N/A"}% \u2014 needs ${HELPFUL_RATE_THRESHOLD}%. Collect more explain_why feedback.`
+      ]
+    });
+  });
+  router.get("/pr-shadow/results", (req, res) => {
+    const limit = Math.min(200, Math.max(1, Number(req.query.limit ?? 50)));
+    res.json({ ok: true, results: getPRShadowResults(limit) });
+  });
+  return router;
+}
+export {
+  createPRShadowRouter
+};

package/dist/routes/rbac.js

@@ -0,0 +1,61 @@
+import { Router } from "express";
+import { z } from "zod";
+import { listMembers, upsertMember, removeMember, hasPermission, resolveRole } from "../sensor/rbac.js";
+import logger from "../sensor/logger.js";
+const RoleSchema = z.enum(["viewer", "responder", "admin"]);
+function createRbacRouter() {
+  const router = Router();
+  router.get("/rbac/members", (_req, res) => {
+    res.json({ ok: true, members: listMembers() });
+  });
+  router.post("/rbac/members", (req, res) => {
+    const caller = req.headers["x-mergen-member"] ?? "unknown";
+    if (!hasPermission(caller, "admin")) {
+      res.status(403).json({ error: "admin role required" });
+      return;
+    }
+    const parsed = z.object({ id: z.string().min(1), role: RoleSchema }).safeParse(req.body);
+    if (!parsed.success) {
+      res.status(400).json({ error: "id and role (viewer|responder|admin) are required" });
+      return;
+    }
+    const member = upsertMember(parsed.data.id, parsed.data.role);
+    logger.info({ caller, target: member.id, role: member.role }, "rbac: member added via API");
+    res.json({ ok: true, member });
+  });
+  router.put("/rbac/members/:id", (req, res) => {
+    const caller = req.headers["x-mergen-member"] ?? "unknown";
+    if (!hasPermission(caller, "admin")) {
+      res.status(403).json({ error: "admin role required" });
+      return;
+    }
+    const parsed = z.object({ role: RoleSchema }).safeParse(req.body);
+    if (!parsed.success) {
+      res.status(400).json({ error: "role (viewer|responder|admin) is required" });
+      return;
+    }
+    const member = upsertMember(req.params.id, parsed.data.role);
+    res.json({ ok: true, member });
+  });
+  router.delete("/rbac/members/:id", (req, res) => {
+    const caller = req.headers["x-mergen-member"] ?? "unknown";
+    if (!hasPermission(caller, "admin")) {
+      res.status(403).json({ error: "admin role required" });
+      return;
+    }
+    const removed = removeMember(req.params.id);
+    if (!removed) {
+      res.status(404).json({ error: "member not found" });
+      return;
+    }
+    res.json({ ok: true });
+  });
+  router.get("/rbac/me", (req, res) => {
+    const actor = req.headers["x-mergen-member"] ?? "unknown";
+    res.json({ ok: true, actor, role: resolveRole(actor) });
+  });
+  return router;
+}
+export {
+  createRbacRouter
+};

package/dist/routes/replay.js

@@ -0,0 +1,17 @@
+import { Router } from "express";
+import { buildReplay } from "../intelligence/replay.js";
+function createReplayRouter() {
+  const router = Router();
+  router.get("/replay/:traceId", async (req, res) => {
+    const result = await buildReplay(req.params.traceId);
+    res.json({
+      ok: true,
+      ...result,
+      note: result.entries.length === 0 ? `No gate-event or blunder-log entries found for trace id "${req.params.traceId}".` : `${result.entries.length} entrie(s) reconstructed for this trace.`
+    });
+  });
+  return router;
+}
+export {
+  createReplayRouter
+};

package/dist/routes/risk-report.js

@@ -0,0 +1,164 @@
+import { Router } from "express";
+import { getStores } from "../storage/store-registry.js";
+import { loadEnterprisePolicy } from "../intelligence/enterprise-policy-engine.js";
+import { isNonBlockingBlunderType } from "../sensor/agent-blunder-store.js";
+function createRiskReportRouter() {
+  const router = Router();
+  router.get("/risk-report", async (req, res) => {
+    const format = req.query.format;
+    const data = await computeRiskData(req.tenantId);
+    if (format === "md") {
+      res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+      res.setHeader("Content-Disposition", 'attachment; filename="mergen-risk-report.md"');
+      res.send(buildMarkdown(data));
+      return;
+    }
+    res.json({ ok: true, report: data });
+  });
+  return router;
+}
+const TYPE_DESCRIPTIONS = {
+  allowlist_block: "Command not on the approved allowlist",
+  injection_attempt: "Prompt injection detected in command payload",
+  rbac_block: "Actor missing required role for this action",
+  override_corpus_block: "Action previously overridden by a human decision",
+  pipeline_block: "Governance pipeline blocked the action",
+  planning_gate_block: "Planning gate: confidence or blast-radius check failed"
+};
+async function computeRiskData(tenantId) {
+  const [stats, blunders] = await Promise.all([
+    getStores().blunders.getStats(tenantId),
+    getStores().blunders.list(tenantId)
+  ]);
+  const overrides = await getStores().overrides.getOverrideSummary(tenantId);
+  const policy = loadEnterprisePolicy();
+  const breakdown = Object.entries(stats.byType).filter(([type]) => !isNonBlockingBlunderType(type)).map(([type, count]) => ({
+    type,
+    count,
+    description: TYPE_DESCRIPTIONS[type] ?? type
+  })).sort((a, b) => b.count - a.count);
+  const cmdCounts = /* @__PURE__ */ new Map();
+  for (const b of blunders) {
+    if (isNonBlockingBlunderType(b.blunderType)) continue;
+    if (b.command) {
+      const key = b.command.trim().slice(0, 80);
+      cmdCounts.set(key, (cmdCounts.get(key) ?? 0) + 1);
+    }
+  }
+  const topBlockedCommands = [...cmdCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([command, count]) => ({ command, count }));
+  let riskScore;
+  let riskRationale;
+  if (stats.last7Days <= 5) {
+    riskScore = "low";
+    riskRationale = `${stats.last7Days} blocked actions in the past 7 days \u2014 agent activity is within safe bounds.`;
+  } else if (stats.last7Days <= 20) {
+    riskScore = "medium";
+    riskRationale = `${stats.last7Days} blocked actions in the past 7 days \u2014 elevated agent activity. Review breakdown for patterns.`;
+  } else {
+    riskScore = "high";
+    riskRationale = `${stats.last7Days} blocked actions in the past 7 days \u2014 significant autonomous activity intercepted. Audit recommended.`;
+  }
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    windowDays: 30,
+    totalBlocked: stats.total,
+    last7Days: stats.last7Days,
+    last30Days: stats.last30Days,
+    breakdown,
+    topBlockedCommands,
+    activeRules: policy.enabled ? policy.rules.filter((r) => r.action === "block").length : 0,
+    overrideCorpusSize: overrides.length,
+    riskScore,
+    riskRationale
+  };
+}
+function buildMarkdown(d) {
+  const riskBadge = { low: "\u{1F7E2} LOW", medium: "\u{1F7E1} MEDIUM", high: "\u{1F534} HIGH" }[d.riskScore];
+  const breakdownTable = d.breakdown.length > 0 ? [
+    "| Type | Count | Description |",
+    "|------|------:|-------------|",
+    ...d.breakdown.map((r) => `| \`${r.type}\` | ${r.count} | ${r.description} |`)
+  ].join("\n") : "_No blocked actions recorded yet._";
+  const topCmdsSection = d.topBlockedCommands.length > 0 ? [
+    "| Command | Times Blocked |",
+    "|---------|-------------:|",
+    ...d.topBlockedCommands.map((c) => `| \`${c.command}\` | ${c.count} |`)
+  ].join("\n") : "_No commands blocked yet._";
+  return `# Mergen \u2014 AI Agent Security Risk Report
+
+**Generated:** ${d.generatedAt}
+**Risk Level:** ${riskBadge}
+
+---
+
+## Executive Summary
+
+> ${d.riskRationale}
+
+Mergen is the inline Execution and Security Gateway running on your engineering
+infrastructure. Every time an AI agent attempted a potentially harmful action,
+Mergen intercepted it **before the handler executed** \u2014 in under 1ms, with no
+LLM in the critical path.
+
+---
+
+## Blocked Actions
+
+| Metric | Value |
+|--------|------:|
+| Total intercepted (all time) | **${d.totalBlocked}** |
+| Intercepted \u2014 last 7 days | **${d.last7Days}** |
+| Intercepted \u2014 last 30 days | **${d.last30Days}** |
+| Active block rules | **${d.activeRules}** |
+| Override corpus entries | **${d.overrideCorpusSize}** |
+
+### Breakdown by Type
+
+${breakdownTable}
+
+### Top Blocked Commands
+
+${topCmdsSection}
+
+---
+
+## Enforcement Architecture
+
+Mergen applies three enforcement layers before any autonomous tool call executes:
+
+1. **Hard Safety Policies** \u2014 Immutable JSON rules evaluated in <1ms. No LLM.
+   No amount of agent persuasion bypasses them.
+2. **Override Corpus** \u2014 Every human override is encoded as binding enforcement
+   policy. ${d.overrideCorpusSize} entries active.
+3. **Confidence Gate** \u2014 Autonomous execution only proceeds above a
+   Platt-calibrated threshold set by your team.
+
+---
+
+## Audit Trail
+
+The Agent Blunder Log is **hash-chained and tamper-evident**. Every blocked
+action is recorded with a SHA-256 hash of its content plus the previous
+entry's hash. An external auditor can verify integrity at any time:
+
+\`\`\`
+GET /agent-blunders/verify
+\`\`\`
+
+---
+
+## Next Steps
+
+- Review the breakdown table for repeat offenders
+- Run \`mergen-server test-safety\` to verify the gate is holding against known bypass patterns
+- Share this report with your security team \u2014 data is sourced from your local
+  infrastructure only; nothing leaves your environment
+
+---
+
+_Mergen \u2014 Agent Execution Governance. All data stays on your infrastructure._
+`;
+}
+export {
+  createRiskReportRouter
+};

package/dist/routes/runbooks.js

@@ -0,0 +1,125 @@
+import fs from "fs";
+import path from "path";
+import { randomUUID } from "crypto";
+import { Router } from "express";
+import { DATA_DIR } from "../sensor/paths.js";
+import logger from "../sensor/logger.js";
+const LIBRARY_FILE = path.join(DATA_DIR, "runbooks", "library.json");
+const RUNBOOKS_DIR = path.join(DATA_DIR, "runbooks");
+function readLibrary() {
+  try {
+    if (!fs.existsSync(LIBRARY_FILE)) return [];
+    return JSON.parse(fs.readFileSync(LIBRARY_FILE, "utf8"));
+  } catch {
+    return [];
+  }
+}
+function writeLibrary(runbooks) {
+  try {
+    fs.mkdirSync(RUNBOOKS_DIR, { recursive: true });
+    const tmp = `${LIBRARY_FILE}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(runbooks, null, 2), "utf8");
+    fs.renameSync(tmp, LIBRARY_FILE);
+  } catch (err) {
+    logger.error({ err }, "runbooks: failed to persist library");
+  }
+}
+function getRunbookForTag(incidentTag) {
+  return readLibrary().find((r) => r.incidentTag === incidentTag && r.approved);
+}
+function createRunbooksRouter() {
+  const router = Router();
+  router.get("/runbooks", (_req, res) => {
+    const runbooks = readLibrary();
+    res.json({ ok: true, total: runbooks.length, runbooks });
+  });
+  router.get("/runbooks/:id", (req, res) => {
+    const runbook = readLibrary().find((r) => r.id === req.params["id"]);
+    if (!runbook) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    res.json({ ok: true, runbook });
+  });
+  router.post("/runbooks", (req, res) => {
+    const { name, incidentTag, steps, riskTier, requiredApprovers } = req.body;
+    if (!name || typeof name !== "string") {
+      res.status(400).json({ error: "name is required" });
+      return;
+    }
+    if (!incidentTag || typeof incidentTag !== "string") {
+      res.status(400).json({ error: "incidentTag is required" });
+      return;
+    }
+    if (!Array.isArray(steps) || steps.length === 0) {
+      res.status(400).json({ error: "steps must be a non-empty array" });
+      return;
+    }
+    const validTiers = ["RESTART", "DEPLOY", "FULL"];
+    if (!riskTier || !validTiers.includes(riskTier)) {
+      res.status(400).json({ error: "riskTier must be RESTART, DEPLOY, or FULL" });
+      return;
+    }
+    const now = Date.now();
+    const runbook = {
+      id: randomUUID(),
+      name: name.slice(0, 200),
+      incidentTag: incidentTag.slice(0, 100),
+      steps: steps.map((s) => String(s).slice(0, 500)),
+      riskTier,
+      requiredApprovers: typeof requiredApprovers === "number" && requiredApprovers > 0 ? requiredApprovers : 1,
+      approvals: [],
+      approved: false,
+      createdAt: now,
+      updatedAt: now
+    };
+    const library = readLibrary();
+    library.push(runbook);
+    writeLibrary(library);
+    logger.info({ id: runbook.id, name: runbook.name, incidentTag }, "runbooks: created");
+    res.status(201).json({ ok: true, runbook });
+  });
+  router.put("/runbooks/:id/approve", (req, res) => {
+    const { actor } = req.body;
+    if (!actor || typeof actor !== "string") {
+      res.status(400).json({ error: "actor is required" });
+      return;
+    }
+    const library = readLibrary();
+    const runbook = library.find((r) => r.id === req.params["id"]);
+    if (!runbook) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    if (runbook.approvals.some((a) => a.actor === actor)) {
+      res.status(409).json({ error: "actor has already approved this runbook" });
+      return;
+    }
+    runbook.approvals.push({ actor: actor.slice(0, 100), approvedAt: Date.now() });
+    runbook.approved = runbook.approvals.length >= runbook.requiredApprovers;
+    runbook.updatedAt = Date.now();
+    writeLibrary(library);
+    logger.info(
+      { id: runbook.id, actor, approved: runbook.approved, approvals: runbook.approvals.length },
+      "runbooks: approval recorded"
+    );
+    res.json({ ok: true, runbook });
+  });
+  router.delete("/runbooks/:id", (req, res) => {
+    const library = readLibrary();
+    const idx = library.findIndex((r) => r.id === req.params["id"]);
+    if (idx === -1) {
+      res.status(404).json({ error: "not found" });
+      return;
+    }
+    const [removed] = library.splice(idx, 1);
+    writeLibrary(library);
+    logger.info({ id: removed.id, name: removed.name }, "runbooks: deleted");
+    res.json({ ok: true });
+  });
+  return router;
+}
+export {
+  createRunbooksRouter,
+  getRunbookForTag
+};