mergen-server 1.4.0

package/dist/intelligence/git-adr-sync.js

@@ -0,0 +1,207 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { DATA_DIR } from "../sensor/paths.js";
+import { adrStore } from "../sensor/adr-store.js";
+import { getStores } from "../storage/store-registry.js";
+import logger from "../sensor/logger.js";
+const SYSTEM_TENANT = process.env.MERGEN_SYSTEM_TENANT_ID;
+const STATE_FILE = path.join(DATA_DIR, "git-adr-sync.json");
+const POLL_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+const CONSTRAINT_KEYWORDS = [
+  "never ",
+  "don't ",
+  "do not ",
+  "avoid ",
+  "block:",
+  "constraint:",
+  "decided:",
+  "adr:",
+  "policy:",
+  "rule:",
+  "freeze",
+  "hold off",
+  "should not",
+  "must not",
+  "compliance",
+  "settlement window",
+  "batch window",
+  "maintenance window",
+  "we won't",
+  "not during",
+  "unsafe during"
+];
+const INCIDENT_TAG_HINTS = [
+  [/pool|connection.?limit|max.?conn/i, "infra_db_connection_pool"],
+  [/oom|out.of.memory|heap|memory.?leak/i, "oom_kill"],
+  [/rate.?limit|throttl/i, "rate_limit_cascade"],
+  [/auth|token|session|oauth|jwt/i, "auth_token_not_persisted"],
+  [/cache|redis|memcach/i, "cache_invalidation"],
+  [/deploy|rollout|release|image/i, "deploy_config_drift"],
+  [/cert|tls|ssl|https/i, "cert_expiry"],
+  [/disk|storage|volume|space/i, "disk_pressure"],
+  [/scale|replica|pod.?count|instance/i, "infra_scaling"],
+  [/migration|schema|alter.?table/i, "db_migration_lock"],
+  [/friday|settlement|batch|weekend|end.of.day/i, "batch_window_conflict"]
+];
+const OVERRIDE_REASON_HINTS = [
+  [/friday|settlement|batch|weekend|end.of.day|window/i, "batch-window"],
+  [/cost|budget|billing|expensive/i, "cost-constraint"],
+  [/cab|freeze|compliance|approval|change.control/i, "compliance-hold"],
+  [/replica|read.only|primary/i, "prefer-read-replica"],
+  [/maintenance|scheduled|downtime/i, "maintenance-window"],
+  [/wrong.diag|misidentif|incorrect.root/i, "wrong-diagnosis"],
+  [/wrong.fix|bad.command|revert/i, "wrong-fix"]
+];
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+    }
+  } catch {
+  }
+  return { processedShas: [], processedAdrIds: [], lastSyncAt: 0 };
+}
+function saveState(state) {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    state.processedShas = state.processedShas.slice(-2e3);
+    state.processedAdrIds = state.processedAdrIds.slice(-500);
+    const tmp = `${STATE_FILE}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
+    fs.renameSync(tmp, STATE_FILE);
+  } catch (err) {
+    logger.warn({ err }, "git-adr-sync: failed to persist state");
+  }
+}
+function inferTag(text) {
+  for (const [pattern, tag] of INCIDENT_TAG_HINTS) {
+    if (pattern.test(text)) return tag;
+  }
+  return "operational_constraint";
+}
+function inferReason(text) {
+  for (const [pattern, reason] of OVERRIDE_REASON_HINTS) {
+    if (pattern.test(text)) return reason;
+  }
+  return "on-call-discretion";
+}
+function extractCommand(text) {
+  const backtick = text.match(/`([^`]{4,200})`/);
+  if (backtick) return backtick[1].trim();
+  const shellLine = text.split("\n").find(
+    (l) => /^(kubectl|docker|systemctl|service|npm|yarn|make|helm|psql)\s/i.test(l.trim())
+  );
+  if (shellLine) return shellLine.trim().slice(0, 500);
+  return text.slice(0, 100).trim();
+}
+function isConstraintText(text) {
+  const lower = text.toLowerCase();
+  return CONSTRAINT_KEYWORDS.some((kw) => lower.includes(kw));
+}
+async function scanGitLog(state) {
+  let added = 0;
+  const processed = new Set(state.processedShas);
+  try {
+    const raw = execSync(
+      "git log --no-merges --format=%H%x1F%s%x1F%b%x1E -n 500 2>/dev/null",
+      { encoding: "utf8", timeout: 1e4, stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const records = raw.split("").filter(Boolean);
+    for (const record of records) {
+      const [sha, subject, body = ""] = record.split("");
+      if (!sha) continue;
+      const cleanSha = sha.trim();
+      if (processed.has(cleanSha)) continue;
+      processed.add(cleanSha);
+      const fullText = `${subject ?? ""}
+${body}`;
+      if (!isConstraintText(fullText)) continue;
+      const sentences = fullText.split(/[.!?\n]/).map((s) => s.trim()).filter(Boolean);
+      for (const sentence of sentences) {
+        if (!isConstraintText(sentence)) continue;
+        const tag = inferTag(sentence);
+        const reason = inferReason(sentence);
+        const command = extractCommand(fullText);
+        try {
+          await getStores().overrides.recordOverride(
+            {
+              incidentTag: tag,
+              proposedCommand: command,
+              overrideReason: reason,
+              service: "unknown",
+              environment: "production",
+              note: sentence.slice(0, 200),
+              manualAction: `git commit ${cleanSha.slice(0, 8)}: ${(subject ?? "").slice(0, 100)}`,
+              actor: "git-adr-sync"
+            },
+            SYSTEM_TENANT
+          );
+          added++;
+        } catch {
+        }
+        break;
+      }
+    }
+    state.processedShas = [...processed];
+  } catch (err) {
+    logger.debug({ err: err.message }, "git-adr-sync: git log unavailable");
+  }
+  return added;
+}
+async function syncAdrStore(state) {
+  let added = 0;
+  const processed = new Set(state.processedAdrIds);
+  const adrs = adrStore.list().filter((adr) => adr.status === "accepted");
+  for (const adr of adrs) {
+    if (processed.has(adr.id)) continue;
+    processed.add(adr.id);
+    const fullText = [adr.decision, adr.consequences, adr.rationale].join("\n");
+    if (!isConstraintText(fullText)) continue;
+    const tag = inferTag(fullText);
+    const reason = inferReason(fullText);
+    const command = extractCommand(fullText);
+    try {
+      await getStores().overrides.recordOverride(
+        {
+          incidentTag: tag,
+          proposedCommand: command,
+          overrideReason: reason,
+          service: "unknown",
+          environment: "production",
+          note: `${adr.id}: ${adr.title}`.slice(0, 200),
+          manualAction: adr.decision.slice(0, 500),
+          actor: "adr-store-sync"
+        },
+        SYSTEM_TENANT
+      );
+      added++;
+    } catch {
+    }
+  }
+  state.processedAdrIds = [...processed];
+  return added;
+}
+async function sync() {
+  const state = loadState();
+  const gitAdded = await scanGitLog(state);
+  const adrAdded = await syncAdrStore(state);
+  state.lastSyncAt = Date.now();
+  saveState(state);
+  const total = gitAdded + adrAdded;
+  if (total > 0) {
+    logger.info({ gitAdded, adrAdded }, "git-adr-sync: new operational constraints added to corpus");
+  } else {
+    logger.debug("git-adr-sync: sync complete \u2014 no new constraints found");
+  }
+}
+function startGitAdrSync() {
+  logger.info("git-adr-sync: starting \u2014 scanning git history and ADR store for operational constraints");
+  void sync();
+  setInterval(() => {
+    void sync();
+  }, POLL_INTERVAL_MS).unref();
+}
+export {
+  startGitAdrSync
+};

package/dist/intelligence/hitl-hold.js

@@ -0,0 +1,460 @@
+import fs from "fs";
+import { recordHitlDecision } from "./gate-analytics.js";
+import { loadEnterprisePolicy } from "./enterprise-policy-engine.js";
+import { computeBlastRadius } from "./blast-radius.js";
+import { findSimilarDecisions } from "./decision-similarity.js";
+import { findSimilarIncidents } from "./incident-similarity.js";
+import { getStores } from "../storage/store-registry.js";
+import { HITL_HOLDS_FILE, DATA_DIR, zeroRetentionMode } from "../sensor/paths.js";
+import logger from "../sensor/logger.js";
+const HOLD_TIMEOUT_MS = 15 * 60 * 1e3;
+function _loadQuorumRules() {
+  const raw = process.env.MERGEN_HITL_QUORUM_RULES ?? "";
+  return raw.split(",").map((s) => s.trim()).filter(Boolean).map((s) => {
+    const lastColon = s.lastIndexOf(":");
+    if (lastColon === -1) return null;
+    const pattern = s.slice(0, lastColon).trim();
+    const required = parseInt(s.slice(lastColon + 1).trim(), 10);
+    if (!pattern || !Number.isFinite(required) || required < 2) return null;
+    return { pattern, required };
+  }).filter((r) => r !== null);
+}
+const _quorumRules = _loadQuorumRules();
+function _quorumRequired(commandArg, toolName) {
+  const haystack = `${toolName} ${commandArg}`.toLowerCase();
+  for (const rule of _quorumRules) {
+    if (haystack.includes(rule.pattern.toLowerCase())) return rule.required;
+  }
+  return 1;
+}
+const _pendingHolds = /* @__PURE__ */ new Map();
+function _persistHolds() {
+  if (zeroRetentionMode()) return;
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    const now = Date.now();
+    const active = [..._pendingHolds.entries()].filter(([, h]) => now < h.heldAt + HOLD_TIMEOUT_MS).map(([token, h]) => ({
+      token,
+      toolName: h.toolName,
+      policyReason: h.policyReason,
+      triggeredRules: h.triggeredRules,
+      heldAt: h.heldAt,
+      expiresAt: h.heldAt + HOLD_TIMEOUT_MS,
+      quorumRequired: h.quorumRequired,
+      approvedBy: [...h.approvedBy]
+    }));
+    const tmp = `${HITL_HOLDS_FILE}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify({ version: 1, holds: active }), "utf8");
+    fs.renameSync(tmp, HITL_HOLDS_FILE);
+  } catch (err) {
+    logger.warn({ err }, "tool-guard: hold persist failed");
+  }
+}
+function denyStaleHoldsOnStartup() {
+  if (zeroRetentionMode() || !fs.existsSync(HITL_HOLDS_FILE)) return;
+  try {
+    const raw = JSON.parse(fs.readFileSync(HITL_HOLDS_FILE, "utf8"));
+    if (raw?.version !== 1 || !Array.isArray(raw.holds)) return;
+    const now = Date.now();
+    const stale = raw.holds.filter((h) => h.expiresAt > now);
+    if (stale.length === 0) return;
+    logger.warn(
+      { count: stale.length, tokens: stale.map((h) => h.token) },
+      "tool-guard: denying stale HITL holds from previous server run \u2014 the MCP client must resubmit these tool calls."
+    );
+    try {
+      fs.unlinkSync(HITL_HOLDS_FILE);
+    } catch {
+    }
+  } catch (err) {
+    logger.warn({ err }, "tool-guard: failed to load stale holds file");
+  }
+}
+function approveToolCall(token, approverId = "operator") {
+  const hold = _pendingHolds.get(token);
+  if (!hold) return false;
+  hold.approvedBy.add(approverId);
+  const approvedCount = hold.approvedBy.size;
+  const required = hold.quorumRequired;
+  if (approvedCount < required) {
+    void _fireQuorumProgress(token, hold, approvedCount, required);
+    _persistHolds();
+    logger.info({ token, approverId, approvedCount, required }, "tool-guard: quorum partial approval");
+    return true;
+  }
+  clearTimeout(hold.timeoutHandle);
+  if (hold.reminderHandle) clearTimeout(hold.reminderHandle);
+  if (hold.escalationHandle) clearTimeout(hold.escalationHandle);
+  _pendingHolds.delete(token);
+  _persistHolds();
+  recordHitlDecision(hold.triggeredRules, "approve", hold.heldAt);
+  logger.info({ token, toolName: hold.toolName, approvedBy: [...hold.approvedBy] }, "tool-guard: HITL approved (quorum met)");
+  const constraintNote = hold.approvedConstraints ? `
+Approved with constraints: ${JSON.stringify(hold.approvedConstraints)}` : "";
+  hold.resolve({
+    content: [{ type: "text", text: `\u2705 Tool call \`${hold.toolName}\` approved by operator (${approvedCount}/${required}).${constraintNote}` }]
+  });
+  return true;
+}
+function approveToolCallConstrained(token, constraints, approverId = "operator") {
+  const hold = _pendingHolds.get(token);
+  if (!hold) return { ok: false, error: "token not found or already expired" };
+  if (typeof constraints !== "object" || Array.isArray(constraints) || Object.keys(constraints).length === 0) {
+    return { ok: false, error: "constraints must be a non-empty object" };
+  }
+  hold.approvedConstraints = constraints;
+  hold.approvedBy.add(approverId);
+  const approvedCount = hold.approvedBy.size;
+  const required = hold.quorumRequired;
+  if (approvedCount < required) {
+    void _fireQuorumProgress(token, hold, approvedCount, required);
+    _persistHolds();
+    logger.info({ token, approverId, approvedCount, required }, "tool-guard: quorum partial approval (with constraints)");
+    return { ok: true };
+  }
+  clearTimeout(hold.timeoutHandle);
+  if (hold.reminderHandle) clearTimeout(hold.reminderHandle);
+  if (hold.escalationHandle) clearTimeout(hold.escalationHandle);
+  _pendingHolds.delete(token);
+  _persistHolds();
+  recordHitlDecision(hold.triggeredRules, "approve", hold.heldAt);
+  logger.info({ token, toolName: hold.toolName, constraints, approvedBy: [...hold.approvedBy] }, "tool-guard: HITL approved with constraints (quorum met)");
+  hold.resolve({
+    content: [{
+      type: "text",
+      text: `\u2705 Tool call \`${hold.toolName}\` approved with constraints by ${approverId} (${approvedCount}/${required}).
+Constraints: ${JSON.stringify(constraints)}
+The action must be scoped to these constraints before execution.`
+    }]
+  });
+  return { ok: true };
+}
+function denyToolCall(token) {
+  const hold = _pendingHolds.get(token);
+  if (!hold) return false;
+  clearTimeout(hold.timeoutHandle);
+  if (hold.reminderHandle) clearTimeout(hold.reminderHandle);
+  if (hold.escalationHandle) clearTimeout(hold.escalationHandle);
+  _pendingHolds.delete(token);
+  _persistHolds();
+  recordHitlDecision(hold.triggeredRules, "deny", hold.heldAt);
+  logger.info({ token, toolName: hold.toolName }, "tool-guard: HITL denied");
+  hold.resolve({
+    content: [{
+      type: "text",
+      text: [
+        `\u274C Tool call \`${hold.toolName}\` denied by operator.`,
+        ``,
+        `**Why:** ${hold.policyReason}`,
+        ``,
+        `**What to do instead:** ${hold.suggestedAlt}`
+      ].join("\n")
+    }],
+    isError: true
+  });
+  return true;
+}
+function getPendingHolds() {
+  const now = Date.now();
+  return [..._pendingHolds.entries()].map(([token, h]) => ({
+    token,
+    toolName: h.toolName,
+    commandArg: h.commandArg,
+    policyReason: h.policyReason,
+    suggestedAlt: h.suggestedAlt,
+    triggeredRules: h.triggeredRules,
+    heldAt: h.heldAt,
+    waitingSec: Math.round((now - h.heldAt) / 1e3),
+    quorumRequired: h.quorumRequired,
+    approvedCount: h.approvedBy.size
+  }));
+}
+function escapeMrkdwn(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\*/g, "\uFF0A").replace(/_/g, "\uFF3F").replace(/~/g, "\uFF5E").replace(/`/g, "\uFF40").replace(/@/g, "\uFF20");
+}
+async function fireHitlWebhook(token, toolName, argsSnapshot, reason, port, opts) {
+  const webhookUrl = process.env.MERGEN_HITL_WEBHOOK_URL;
+  if (!webhookUrl) {
+    const baseUrl2 = (process.env.MERGEN_PUBLIC_URL ?? "").replace(/\/$/, "") || `http://127.0.0.1:${port}`;
+    logger.warn(
+      { token, toolName },
+      `tool-guard: HITL triggered but MERGEN_HITL_WEBHOOK_URL is not set \u2014 resolve manually: POST ${baseUrl2}/hitl/approve?token=${token}`
+    );
+    return;
+  }
+  const baseUrl = (process.env.MERGEN_PUBLIC_URL ?? "").replace(/\/$/, "") || `http://127.0.0.1:${port}`;
+  const approveUrl = `${baseUrl}/hitl/approve?token=${token}`;
+  const denyUrl = `${baseUrl}/hitl/deny?token=${token}`;
+  const constrainedUrl = `${baseUrl}/hitl/approve-constrained?token=${token}`;
+  const policy = loadEnterprisePolicy();
+  const matchedRules = policy.rules.filter((r) => opts.triggeredRules.includes(r.id));
+  const blast = computeBlastRadius(opts.commandArg || toolName);
+  const rulesText = matchedRules.length > 0 ? matchedRules.map((r) => `\u2022 *${r.name}*: ${r.description}`).join("\n") : `\u2022 ${reason}`;
+  const blastText = [
+    `Scope: \`${blast.scope}\``,
+    `Reversible: ${blast.reversible ? "Yes" : "*No*"}`,
+    blast.dataAtRisk ? "*Data at risk*" : null,
+    blast.summary
+  ].filter(Boolean).join("  \xB7  ");
+  const safeToolName = escapeMrkdwn(toolName);
+  const safeArgsSnippet = escapeMrkdwn(argsSnapshot.slice(0, 200));
+  const quorumText = opts.quorumRequired > 1 ? `*Quorum required: ${opts.quorumRequired} approvers*` : null;
+  let similarityText = null;
+  try {
+    const [overrides, shadowEntries] = await Promise.all([
+      getStores().overrides.getAllOverrides(),
+      getStores().shadowLog.getShadowEntries()
+    ]);
+    const similarity = findSimilarDecisions(opts.commandArg || toolName, null, overrides, shadowEntries);
+    if (similarity.totalConsidered > 0) {
+      const icon = similarity.recommendation === "hold" ? "\u26A0\uFE0F" : "\u2139\uFE0F";
+      similarityText = `${icon} ${escapeMrkdwn(similarity.rationale)}`;
+    }
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: decision-memory similarity lookup failed");
+  }
+  let relatedIncidentsText = null;
+  try {
+    const related = findSimilarIncidents({ commandText: opts.commandArg || toolName });
+    if (related.length > 0) {
+      relatedIncidentsText = related.map((r) => `\u2022 ${escapeMrkdwn(r.hypothesis)} _(${r.daysAgo}d ago \xB7 ${Math.round(r.confidence * 100)}% match)_`).join("\n");
+    }
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: incident-similarity lookup failed");
+  }
+  const payload = {
+    text: `\u26A0\uFE0F *Mergen HITL Gate* \u2014 \`${safeToolName}\` is awaiting approval`,
+    blocks: [
+      {
+        type: "header",
+        text: { type: "plain_text", text: "\u26A0\uFE0F Mergen HITL Gate \u2014 Approval Required", emoji: true }
+      },
+      {
+        type: "section",
+        fields: [
+          { type: "mrkdwn", text: `*Tool*
+\`${safeToolName}\`` },
+          { type: "mrkdwn", text: `*Args*
+\`${safeArgsSnippet}\`` }
+        ]
+      },
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: `*Why flagged*
+${rulesText}` }
+      },
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: `*Blast radius*
+${blastText}` }
+      },
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: `*Suggested alternative*
+${opts.suggestedAlt}` }
+      },
+      ...similarityText ? [{
+        type: "section",
+        text: { type: "mrkdwn", text: `*Similar past actions*
+${similarityText}` }
+      }] : [],
+      ...relatedIncidentsText ? [{
+        type: "section",
+        text: { type: "mrkdwn", text: `*Related incidents*
+${relatedIncidentsText}` }
+      }] : [],
+      ...quorumText ? [{
+        type: "section",
+        text: { type: "mrkdwn", text: quorumText }
+      }] : [],
+      {
+        type: "actions",
+        elements: [
+          { type: "button", style: "primary", text: { type: "plain_text", text: "\u25B6\uFE0F Approve", emoji: true }, url: approveUrl },
+          { type: "button", style: "danger", text: { type: "plain_text", text: "\u{1F6AB} Deny", emoji: true }, url: denyUrl },
+          { type: "button", text: { type: "plain_text", text: "\u{1F512} Approve with Constraints", emoji: true }, url: constrainedUrl }
+        ]
+      },
+      {
+        type: "context",
+        elements: [{ type: "mrkdwn", text: `Token \`${token}\` \xB7 Slack reminder at 5 min \xB7 PagerDuty/Slack escalation at 10 min \xB7 auto-cancel at 15 min` }]
+      }
+    ],
+    mergen: { type: "hitl_gate", token, toolName, reason, approveUrl, denyUrl, constrainedUrl, quorumRequired: opts.quorumRequired }
+  };
+  try {
+    const resp = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!resp.ok) {
+      logger.warn({ status: resp.status, webhookUrl }, "tool-guard: HITL webhook returned non-2xx");
+    }
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: HITL webhook fire failed");
+  }
+}
+async function _fireQuorumProgress(token, hold, approvedCount, required) {
+  const webhookUrl = process.env.MERGEN_HITL_WEBHOOK_URL;
+  if (!webhookUrl) return;
+  try {
+    await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `\u2705 *Quorum progress*: ${approvedCount}/${required} approvers for \`${escapeMrkdwn(hold.toolName)}\`. Token: \`${token}\``,
+        mergen: { type: "hitl_quorum_progress", token, approvedCount, required }
+      }),
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: quorum progress webhook failed");
+  }
+}
+async function fireHitlReminder(token, toolName, minutesRemaining) {
+  const webhookUrl = process.env.MERGEN_HITL_WEBHOOK_URL;
+  if (!webhookUrl) return;
+  try {
+    await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `\u26A0\uFE0F *Reminder:* HITL approval still pending for \`${escapeMrkdwn(toolName)}\` \u2014 ${minutesRemaining} minutes remaining. Token: \`${token}\``,
+        mergen: { type: "hitl_reminder", token, toolName }
+      }),
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: HITL reminder webhook failed");
+  }
+}
+async function fireDelegationChain(token, toolName) {
+  const secondaryUrl = process.env.MERGEN_HITL_SECONDARY_WEBHOOK;
+  if (!secondaryUrl) return;
+  try {
+    await fetch(secondaryUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `\u{1F534} *Delegation escalation* \u2014 HITL approval for \`${escapeMrkdwn(toolName)}\` has not been responded to after 5 minutes. Escalating to secondary on-call. Token: \`${token}\``,
+        mergen: { type: "hitl_delegation", token, toolName }
+      }),
+      signal: AbortSignal.timeout(5e3)
+    });
+    logger.info({ token, toolName }, "tool-guard: HITL delegation chain fired to secondary webhook");
+  } catch (err) {
+    logger.warn({ err, token }, "tool-guard: HITL delegation chain webhook failed");
+  }
+}
+async function fireHitlEscalation(token, toolName) {
+  const pdSecret = process.env.MERGEN_PAGERDUTY_SECRET;
+  const webhookUrl = process.env.MERGEN_HITL_WEBHOOK_URL;
+  if (pdSecret) {
+    try {
+      await fetch("https://events.pagerduty.com/v2/enqueue", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          routing_key: pdSecret,
+          event_action: "trigger",
+          payload: {
+            summary: `Mergen HITL gate: unanswered approval for \`${toolName}\` (token: ${token})`,
+            severity: "warning",
+            source: "mergen-hitl",
+            custom_details: { token, toolName }
+          }
+        }),
+        signal: AbortSignal.timeout(8e3)
+      });
+      logger.info({ token, toolName }, "tool-guard: HITL escalation sent to PagerDuty");
+    } catch (err) {
+      logger.warn({ err, token }, "tool-guard: PagerDuty escalation failed");
+    }
+    return;
+  }
+  if (webhookUrl) {
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `\u{1F6A8} *URGENT:* HITL approval for \`${escapeMrkdwn(toolName)}\` pending 10 min. 5 min until auto-cancel. Token: \`${token}\``,
+          mergen: { type: "hitl_escalation", token, toolName }
+        }),
+        signal: AbortSignal.timeout(5e3)
+      });
+    } catch (err) {
+      logger.warn({ err, token }, "tool-guard: HITL escalation webhook failed");
+    }
+  }
+}
+function holdToolCall(opts) {
+  const { token, toolName, argsSnapshot, reason, triggeredRules, heldAt, commandArg, suggestedAlt, port } = opts;
+  const quorumRequired = _quorumRequired(commandArg, toolName);
+  void fireHitlWebhook(token, toolName, argsSnapshot, reason, port, {
+    triggeredRules,
+    commandArg,
+    suggestedAlt,
+    quorumRequired
+  });
+  return new Promise((resolve) => {
+    const timeoutHandle = setTimeout(() => {
+      const hold = _pendingHolds.get(token);
+      if (hold?.reminderHandle) clearTimeout(hold.reminderHandle);
+      if (hold?.escalationHandle) clearTimeout(hold.escalationHandle);
+      _pendingHolds.delete(token);
+      _persistHolds();
+      logger.info({ token, toolName }, "tool-guard: HITL approval window expired");
+      resolve({
+        content: [{
+          type: "text",
+          text: [
+            `\u23F0 HITL approval window expired (15 min) for \`${toolName}\`. Tool call cancelled.`,
+            ``,
+            `**Why:** ${reason}`,
+            ``,
+            `**What to do instead:** ${suggestedAlt}`
+          ].join("\n")
+        }],
+        isError: true
+      });
+    }, HOLD_TIMEOUT_MS);
+    timeoutHandle.unref();
+    const reminderHandle = setTimeout(() => {
+      void fireHitlReminder(token, toolName, 10);
+      void fireDelegationChain(token, toolName);
+    }, 5 * 60 * 1e3);
+    reminderHandle.unref();
+    const escalationHandle = setTimeout(() => {
+      void fireHitlEscalation(token, toolName);
+    }, 10 * 60 * 1e3);
+    escalationHandle.unref();
+    _pendingHolds.set(token, {
+      toolName,
+      argsSnapshot,
+      policyReason: reason,
+      suggestedAlt,
+      triggeredRules,
+      heldAt,
+      commandArg,
+      resolve,
+      timeoutHandle,
+      reminderHandle,
+      escalationHandle,
+      quorumRequired,
+      approvedBy: /* @__PURE__ */ new Set()
+    });
+    _persistHolds();
+  });
+}
+export {
+  HOLD_TIMEOUT_MS,
+  approveToolCall,
+  approveToolCallConstrained,
+  denyStaleHoldsOnStartup,
+  denyToolCall,
+  getPendingHolds,
+  holdToolCall
+};