@goodandready/dsh-approval-gate 0.1.12 → 0.1.14

package/lib/inspect.js

@@ -1,26 +1,22 @@
+// lib/inspect.js
+// Pure command and path inspector for dsh-approval-gate.
+// Resolves: #133, #125, #126, #103, #90, #65, #40
+// No Cordis imports: unit tests run this without the harness.
+
 import { checkEnvExfiltration } from "./inspect-env.js";
 export { checkEnvExfiltration } from "./inspect-env.js";
-import { DYNAMIC_MARKER, HEREDOC_OPS, REDIR_OPS, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
+import { DYNAMIC_MARKER, SPLIT_OPS, tokenize, readCommandSubstitution, readBacktick, readParameterExpansion } from "./tokenizer.js";
 import { expandHome, isProtectedConfigPath, resolveSafePath, isPathTraversal, canonicalizeFsPath, normalizeSeparators } from "./paths.js";
 import { askMessage, denyMessage, sessionTag } from "./messages.js";
+import { inspectGitCommand } from "./parsers/git.js";
+import { extractRedirects, inspectRedirectSecurity, inspectSilentErrors, inspectPipelines, isDevicePath } from "./parsers/shell-cmds.js";
+import { isLoopbackCommand } from "./loopback.js";
+import { isReviewerAgent, extractFilePath, DEFAULT_BASH_TOOL, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
 
 export { DYNAMIC_MARKER, tokenize, splitSubcommands } from "./tokenizer.js";
 export { askMessage, denyMessage, sessionTag } from "./messages.js";
 export { expandHome, isProtectedConfigPath, resolveSafePath, isPathTraversal, canonicalizeFsPath, normalizeSeparators } from "./paths.js";
-
-// Pure command/path inspector for dsh-approval-gate.
-// No Cordis imports: unit tests run this without the harness.
-
-export const DEFAULT_BASH_TOOL = "bash";
-export const DEFAULT_FILE_WRITE_TOOLS = Object.freeze([
-  "write",
-  "edit",
-  "Write",
-  "Edit",
-  "str_replace_editor",
-  "str_replace",
-  "apply_patch",
-]);
+export { DEFAULT_BASH_TOOL, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
 
 const PREFIXES = new Set(["then", "do", "{", "}", "!"]);
 const SHELLS = new Set(["bash", "sh", "dash", "zsh", "ksh", "ash"]);
@@ -36,6 +32,11 @@ const SYSTEMCTL_DENY = new Set([
 ]);
 const SERVICE_DENY = new Set(["stop", "restart", "force-stop", "force-reload"]);
 
+const DESTRUCTIVE_CMDS = new Set([
+  "rm", "chmod", "chown", "kill", "pkill", "systemctl", "service",
+  "git", "dd", "mkfs", "tee", "install", "mv", "cp", "sed",
+]);
+
 export function basename(path) {
   const parts = String(path).replace(/\\/g, "/").split("/");
   return parts[parts.length - 1] || "";
@@ -47,23 +48,11 @@ export function isProtectedPath(path, env = process.env) {
 }
 
 function wordsOf(seg) {
-  return seg.filter(function (t) { return t.kind === "word"; }).map(function (t) { return t.value; });
+  return seg.filter((t) => t.kind === "word").map((t) => t.value);
 }
 
 function wordTokensOf(seg) {
-  return seg.filter(function (t) { return t.kind === "word"; });
-}
-
-function redirectsOf(seg) {
-  const paths = [];
-  for (let i = 0; i < seg.length; i += 1) {
-    const t = seg[i];
-    if (t.kind === "op" && REDIR_OPS.has(t.value)) {
-      const next = seg[i + 1];
-      if (next && next.kind === "word") paths.push({ path: next.value, dynamic: Boolean(next.dynamic), operator: t.value });
-    }
-  }
-  return paths;
+  return seg.filter((t) => t.kind === "word");
 }
 
 function splitSegments(tokens) {
@@ -82,7 +71,7 @@ function splitSegments(tokens) {
 }
 
 function stripPrefixes(argv) {
-  const out = argv.filter(function (a) { return a !== "}" && a !== ";"; });
+  const out = argv.filter((a) => a !== "}" && a !== ";");
   while (out.length) {
     const head = out[0];
     if (PREFIXES.has(head)) { out.shift(); continue; }
@@ -106,7 +95,7 @@ function hasLetterFlag(argv, letter) {
 }
 
 function deny(reason, snippet) {
-  return { deny: true, ask: false, reason: reason, detail: reason, snippet: String(snippet || reason).slice(0, 160) };
+  return { deny: true, ask: false, reason, detail: reason, snippet: String(snippet || reason).slice(0, 160) };
 }
 
 function allow() {
@@ -114,7 +103,7 @@ function allow() {
 }
 
 function ask(reason, detail, snippet) {
-  return { deny: false, ask: true, reason: reason, detail: detail || reason, snippet: String(snippet || "").slice(0, 160) };
+  return { deny: false, ask: true, reason, detail: detail || reason, snippet: String(snippet || "").slice(0, 160) };
 }
 
 function scriptAfterDashC(rest) {
@@ -137,28 +126,6 @@ function skipWrapper(rest, arity) {
   return rest.slice(i);
 }
 
-function gitOperation(rest) {
-  const takesValue = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace"]);
-  let i = 0;
-  while (i < rest.length && rest[i].startsWith("-")) {
-    const flag = rest[i];
-    if (flag === "--") { i += 1; break; }
-    if (takesValue.has(flag)) i += 2;
-    else if (flag.startsWith("--") && flag.includes("=")) i += 1;
-    else if (flag.length > 2 && flag[1] !== "-") i += 1;
-    else i += 1;
-  }
-  return { verb: rest[i], args: rest.slice(i + 1) };
-}
-
-function isDevicePath(path) {
-  if (typeof path !== "string" || !path.startsWith("/dev/")) return false;
-  const device = path.slice(5);
-  if (["null", "zero", "full", "random", "urandom", "stdin", "stdout", "stderr", "tty"].includes(device)) return false;
-  if (/^(?:sd[a-z]+|hd[a-z]+|vd[a-z]+|xvd[a-z]+|nvme\d+n\d+(?:p\d+)?|mmcblk\d+(?:p\d+)?|loop\d+)$/i.test(device)) return true;
-  return device.startsWith("mapper/") || device.startsWith("disk/by-id/") || device.startsWith("disk/by-uuid/");
-}
-
 function inspectInterpreterPayload(cmd, payload) {
   const code = String(payload || "");
   const executesProcess = /(?:\bos\.system\s*\(|\bsubprocess\.(?:run|Popen|call|check_call|check_output)\s*\(|\bchild_process\.(?:exec|execSync|spawn|spawnSync)\s*\(|\b(?:exec|spawn)\s*\()/i.test(code);
@@ -187,7 +154,7 @@ function inspectArgv(argv, depth, hasHeredoc, config = {}) {
   }
 
   if (cmd === "env") {
-    const sub = rest.filter(a => !a.startsWith("-") && !a.includes("="));
+    const sub = rest.filter((a) => !a.startsWith("-") && !a.includes("="));
     if (sub.length > 0) {
       return inspectArgv(sub, depth, hasHeredoc, config);
     }
@@ -203,30 +170,38 @@ function inspectArgv(argv, depth, hasHeredoc, config = {}) {
 
   if (cmd === "eval") return deny("eval", argv.join(" "));
   if (KILL_CMDS.has(cmd)) return deny("process-signal", argv.join(" "));
-  if (cmd === "rm" && (hasLetterFlag(argv, "r") || hasLetterFlag(argv, "R") || rest.indexOf("--recursive") !== -1)) {
+  if (cmd === "rm" && (hasLetterFlag(argv, "r") || hasLetterFlag(argv, "R") || rest.includes("--recursive"))) {
     return deny("recursive-rm", argv.join(" "));
   }
   if (cmd === "systemctl") {
-    const verb = rest.find(function (a) { return a[0] !== "-"; });
+    const verb = rest.find((a) => a[0] !== "-");
     if (verb && SYSTEMCTL_DENY.has(verb)) return deny("service-control", argv.join(" "));
   }
   if (cmd === "service") {
     const verb = rest.length >= 2 ? rest[1] : "";
     if (SERVICE_DENY.has(verb)) return deny("service-control", argv.join(" "));
   }
-  if (cmd === "curl" && rest.some(function (a) {
-    return a.includes(DYNAMIC_MARKER) && /\b(?:authorization|proxy-authorization)\s*:\s*(?:bearer|token)\s+/i.test(a);
-  })) {
-    return ask("credential-in-argv", "expanded authorization values become curl process arguments", argv.join(" "));
+
+  // Network commands & loopback bypass (#40)
+  if (cmd === "curl" || cmd === "wget") {
+    const loopback = isLoopbackCommand(argv);
+    if (!loopback.isLoopback && rest.some((a) => a.includes(DYNAMIC_MARKER) && /\b(?:authorization|proxy-authorization)\s*:\s*(?:bearer|token)\s+/i.test(a))) {
+      return ask("credential-in-argv", "expanded authorization values become curl process arguments", argv.join(" "));
+    }
   }
+
+  // Git inspection via specialized parser (#125, #103)
   if (cmd === "git") {
-    const operation = gitOperation(rest);
-    if (operation.verb === "clean" && operation.args.some(function (a) {
-      return a === "-f" || a === "--force" || (a[0] === "-" && a[1] !== "-" && a.indexOf("f") !== -1);
-    })) return deny("git-clean", argv.join(" "));
-    if (operation.verb === "reset" && operation.args.indexOf("--hard") !== -1) return deny("git-reset-hard", argv.join(" "));
+    const git = inspectGitCommand(argv);
+    if (git.isDestructive) {
+      return deny(git.reason, argv.join(" "));
+    }
+    if (git.verb === "push") {
+      return ask("git-remote-push", git.detail || "Publishing commits to a remote repository via git push requires confirmation", argv.join(" "));
+    }
   }
-  if (cmd === "find" && rest.indexOf("-delete") !== -1) return deny("find-delete", argv.join(" "));
+
+  if (cmd === "find" && rest.includes("-delete")) return deny("find-delete", argv.join(" "));
   if (DB_CLIENTS.has(cmd) && DESTRUCTIVE_SQL.test(rest.join(" "))) {
     return deny("destructive-sql", argv.join(" "));
   }
@@ -236,95 +211,52 @@ function inspectArgv(argv, depth, hasHeredoc, config = {}) {
       if (a.startsWith("of=") && (isDevicePath(a.slice(3)) || isProtectedPath(a.slice(3)))) return deny("device-write", a);
     }
   }
+
+  // File mutations & chmod/chown protection (#65)
   if (cmd === "tee" || cmd === "install" || cmd === "cp" || cmd === "mv" || cmd === "truncate" || cmd === "chmod" || cmd === "chown") {
     for (const a of rest) {
       if (a[0] !== "-" && isProtectedPath(a)) return deny("secret-write", argv.join(" "));
     }
-    if ((cmd === "chmod" || cmd === "chown") && (hasLetterFlag(argv, "R") || hasLetterFlag(argv, "r") || rest.indexOf("--recursive") !== -1)) {
-      for (const a of rest) {
-        if (a === "/" || a === "/etc" || a === "/var" || a === "/usr" || a === "/root" || a === "/boot") {
-          return deny("device-write", argv.join(" "));
+    if (cmd === "chmod" || cmd === "chown") {
+      const isRecursive = hasLetterFlag(argv, "R") || hasLetterFlag(argv, "r") || rest.includes("--recursive");
+      if (isRecursive) {
+        for (const a of rest) {
+          if (a === "/" || a === "/etc" || a === "/var" || a === "/usr" || a === "/root" || a === "/boot") {
+            return deny("device-write", argv.join(" "));
+          }
         }
+        return deny("chmod-chown", argv.join(" "));
       }
     }
   }
-  if (cmd === "sed" && (hasLetterFlag(argv, "i") || rest.some(function (a) { return a === "--in-place" || a.startsWith("--in-place="); }))) {
+
+  if (cmd === "sed" && (hasLetterFlag(argv, "i") || rest.some((a) => a === "--in-place" || a.startsWith("--in-place=")))) {
     for (const a of rest) {
       if (a[0] !== "-" && isProtectedPath(a)) return deny("secret-write", argv.join(" "));
     }
   }
+
   if (SHELLS.has(cmd) || cmd === "source" || cmd === ".") {
     const script = scriptAfterDashC(rest);
     if (typeof script === "string") {
       if (depth > 4) return deny("nested-shell", script);
       return inspectBashCommand(script, depth + 1, config);
     }
-    const scriptFile = rest.find(function (a) { return a && a[0] !== "-"; });
+    const scriptFile = rest.find((a) => a && a[0] !== "-");
     if (scriptFile) return ask("script-file", "shell script contents are not available to the guard", scriptFile);
     if (!hasHeredoc) return ask("shell-stdin", "shell input is not fully available to the guard", argv.join(" "));
   }
-  if (INTERPRETERS.has(cmd) && rest.some(function (a) { return a === "-c" || a === "-e"; })) {
-    const idx = rest.findIndex(function (a) { return a === "-c" || a === "-e"; });
+
+  if (INTERPRETERS.has(cmd) && rest.some((a) => a === "-c" || a === "-e")) {
+    const idx = rest.findIndex((a) => a === "-c" || a === "-e");
     return inspectInterpreterPayload(cmd, rest[idx + 1] || "");
   }
+
   if (/\.sh$/i.test(cmd) || (cmd.includes("/") && /\.(?:bash|zsh|ksh)$/i.test(cmd))) {
     return ask("script-file", "script contents are not available to the guard", argv[0]);
   }
-  return allow();
-}
 
-function hasDangerousPipeline(tokens) {
-  let segment = [];
-  let pipelineHasDownloader = false;
-  let inPipeline = false;
-  function inspectSegment() {
-    return commandNameFromSegment(segment);
-  }
-  for (const token of tokens) {
-    if (token.kind === "op" && SPLIT_OPS.has(token.value)) {
-      const cmd = inspectSegment();
-      if (inPipeline && (SHELLS.has(cmd) || INTERPRETERS.has(cmd)) && pipelineHasDownloader) return true;
-      const continues = token.value === "|" || token.value === "|&";
-      if (continues) {
-        pipelineHasDownloader = pipelineHasDownloader || cmd === "curl" || cmd === "wget";
-        inPipeline = true;
-      } else {
-        pipelineHasDownloader = false;
-        inPipeline = false;
-      }
-      segment = [];
-      continue;
-    }
-    segment.push(token);
-  }
-  const cmd = inspectSegment();
-  return inPipeline && pipelineHasDownloader && (SHELLS.has(cmd) || INTERPRETERS.has(cmd));
-}
-
-function hasDestructiveSqlPipeline(tokens) {
-  let pipelineHasDestructiveSql = false;
-  let inPipeline = false;
-  let segment = [];
-  for (const token of tokens) {
-    if (token.kind === "op" && SPLIT_OPS.has(token.value)) {
-      const cmd = commandNameFromSegment(segment);
-      if (inPipeline && DB_CLIENTS.has(cmd) && pipelineHasDestructiveSql) return true;
-      const continues = token.value === "|" || token.value === "|&";
-      if (continues) {
-        const segText = wordsOf(segment).join(" ");
-        pipelineHasDestructiveSql = pipelineHasDestructiveSql || DESTRUCTIVE_SQL.test(segText);
-        inPipeline = true;
-      } else {
-        pipelineHasDestructiveSql = false;
-        inPipeline = false;
-      }
-      segment = [];
-      continue;
-    }
-    segment.push(token);
-  }
-  const cmd = commandNameFromSegment(segment);
-  return inPipeline && pipelineHasDestructiveSql && DB_CLIENTS.has(cmd);
+  return allow();
 }
 
 function executableTokenOf(seg) {
@@ -392,10 +324,10 @@ function inspectPipelineHeredocs(tokens, depth, config = {}) {
   let segment = [];
   function finishGroup() {
     if (segment.length) group.push(segment);
-    const hasShell = group.some(function (part) { return SHELLS.has(commandNameFromSegment(part)); });
+    const hasShell = group.some((part) => SHELLS.has(commandNameFromSegment(part)));
     if (hasShell) {
       for (const part of group) {
-        for (const heredoc of part.filter(function (t) { return t.kind === "heredoc"; })) {
+        for (const heredoc of part.filter((t) => t.kind === "heredoc")) {
           const nested = inspectBashCommand(heredoc.body, depth + 1, config);
           if (nested.deny || nested.ask) return nested;
         }
@@ -446,17 +378,27 @@ export function inspectBashCommand(command, depth = 0, config = {}) {
   if (depth > 8) return ask("unparseable", "nesting-depth", String(command || ""));
   if (typeof command !== "string") return ask("unknown-format", "command is not a string", "non-string command");
   if (command.trim() === "") return allow();
+
   const tok = tokenize(command);
   const tokens = tok.tokens || [];
+
   if (!tok.ok) {
     const knownDanger = inspectUnparsedDanger(command);
     if (knownDanger) return knownDanger;
   }
-  if (hasDangerousPipeline(tokens)) return deny("curl-pipe", command);
-  if (hasDestructiveSqlPipeline(tokens)) return deny("destructive-sql", command);
+
+  // Pipeline inspection (#126)
+  const pipeCheck = inspectPipelines(tokens);
+  if (pipeCheck.dangerousPipeline) {
+    return deny(pipeCheck.reason, command);
+  }
+
   const pipelineHeredocHit = inspectPipelineHeredocs(tokens, depth, config);
   if (pipelineHeredocHit.deny || pipelineHeredocHit.ask) return pipelineHeredocHit;
 
+  // Silent error guard check (#90)
+  const silentHit = inspectSilentErrors(command);
+
   const segs = splitSegments(tokens);
   for (const seg of segs) {
     const rawWords = wordsOf(seg);
@@ -465,11 +407,16 @@ export function inspectBashCommand(command, depth = 0, config = {}) {
       return deny("env-dump-leak", envHit.detail || command);
     }
     const wordTokens = wordTokensOf(seg);
-    const heredocs = seg.filter(function (t) { return t.kind === "heredoc"; });
+    const heredocs = seg.filter((t) => t.kind === "heredoc");
     const argv = stripPrefixes(wordsOf(seg));
     const commandToken = executableTokenOf(seg);
     const commandName = commandNameFromSegment(seg);
 
+    // Silent error guard triggered on mutating system commands (#90)
+    if (silentHit.masked && (config.silentErrorGuard || DESTRUCTIVE_CMDS.has(commandName))) {
+      return ask("silent-error-masked", silentHit.detail, command);
+    }
+
     for (const token of wordTokens) {
       for (const substitution of token.substitutions || []) {
         const nested = substitution.kind === "parameter-expansion"
@@ -479,25 +426,23 @@ export function inspectBashCommand(command, depth = 0, config = {}) {
       }
     }
 
-    for (const redirect of redirectsOf(seg)) {
-      if (redirect.dynamic) return ask("dynamic-redirect", "expanded redirect target cannot be verified", redirect.path);
-      const baseDir = (config && config.workspaceDir) || process.cwd();
-      const norm = normalizeSeparators(redirect.path);
-      const isRel = !/^(?:\/|[A-Za-z]:\/|\/\/)/.test(norm);
-      const isExempt = !isRel && (/^\/dev\/(?:null|zero|stdout|stderr|fd\/\d+)$/.test(norm) || /^(?:\/tmp|\/var\/tmp)(?:\/|$)/i.test(norm));
-      if (!isExempt && isPathTraversal(redirect.path, baseDir)) {
-        return deny("path-traversal", redirect.path);
-      }
-      if (isProtectedPath(redirect.path)) return deny("secret-write", redirect.path);
+    // Redirects security inspection (#126)
+    const redirects = extractRedirects(seg);
+    const redirectHit = inspectRedirectSecurity(redirects, {
+      workspaceDir: config.workspaceDir,
+      env: config.env,
+    });
+    if (redirectHit) {
+      return redirectHit.deny ? deny(redirectHit.reason, redirectHit.path) : ask(redirectHit.reason, redirectHit.detail, redirectHit.path);
     }
 
     if (commandToken && commandToken.dynamic && !commandToken.value.includes("=")) {
       return ask("dynamic-command", "expanded command name cannot be verified", commandToken.value);
     }
 
-    const dynamicArgs = wordTokens.some(function (t) {
-      return t.dynamic && (!commandToken || t !== commandToken) && !t.value.includes("=");
-    });
+    const dynamicArgs = wordTokens.some((t) => (
+      t.dynamic && (!commandToken || t !== commandToken) && !t.value.includes("=")
+    ));
     if (dynamicArgs && ["rm", "find", "git", "systemctl", "service", "tee", "install", "cp", "mv", "truncate", "sed", "dd"].includes(commandName)) {
       return ask("dynamic-arguments", "expanded command arguments cannot be verified", commandName);
     }
@@ -536,16 +481,6 @@ export function inspectBashCommand(command, depth = 0, config = {}) {
   return allow();
 }
 
-function pathFromArgs(args) {
-  if (typeof args === "string") return args;
-  if (!args || typeof args !== "object") return null;
-  const keys = ["path", "file_path", "filePath", "file", "filename", "target", "to"];
-  for (const k of keys) {
-    if (typeof args[k] === "string") return args[k];
-  }
-  return null;
-}
-
 export function inspectExecution(execution, config) {
   if (!config) config = {};
   const toolName = config.toolName || DEFAULT_BASH_TOOL;
@@ -553,14 +488,22 @@ export function inspectExecution(execution, config) {
   const name = execution && execution.name;
   const args = execution ? execution.arguments : undefined;
 
+  // Reviewer agent read-only mode isolation (#65)
+  if (isReviewerAgent(execution, config)) {
+    if (name === toolName || fileTools.has(name)) {
+      return deny("reviewer-read-only", `Reviewer agent is strictly isolated in read-only mode; tool ${name} is prohibited`);
+    }
+  }
+
   if (name === toolName) {
     const command = args && typeof args === "object" ? args.command : undefined;
     if (command === undefined || command === null || command === "") return allow();
     if (typeof command !== "string") return ask("unknown-format", "command is not a string", "non-string command");
     return inspectBashCommand(command, 0, config);
   }
+
   if (typeof name === "string" && fileTools.has(name)) {
-    const path = pathFromArgs(args);
+    const path = extractFilePath(args);
     if (!path) return ask("unknown-write-target", "file write target could not be identified", name);
     if (config.workspaceDir) {
       const safeCheck = resolveSafePath(path, config.workspaceDir);
@@ -573,6 +516,6 @@ export function inspectExecution(execution, config) {
       if (isProtectedPath(path)) return deny("secret-write", path);
     }
   }
-  return allow();
-}
 
+  return allow();
+}

package/lib/ledger.js

@@ -0,0 +1,164 @@
+// lib/ledger.js
+// Quality and Anomaly Ledger for dsh-approval-gate (#88).
+// Tracks session health, consecutive denials, and execution anomalies.
+
+export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
+
+/**
+ * @typedef {Object} LedgerEvent
+ * @property {number} timestamp
+ * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+ * @property {string} reason
+ * @property {string} [detail]
+ * @property {string} [tool]
+ */
+
+/**
+ * @typedef {Object} SessionLedger
+ * @property {string} sessionId
+ * @property {number} totalDecisions
+ * @property {number} allowedCount
+ * @property {number} deniedCount
+ * @property {number} askCount
+ * @property {number} anomalyCount
+ * @property {number} consecutiveDenies
+ * @property {boolean} breakerTripped
+ * @property {boolean} retryExhausted
+ * @property {LedgerEvent[]} recentEvents
+ */
+
+export class QualityLedger {
+  constructor() {
+    /** @type {Map<string, SessionLedger>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let ledger = this.sessions.get(key);
+    if (!ledger) {
+      ledger = {
+        sessionId: key,
+        totalDecisions: 0,
+        allowedCount: 0,
+        deniedCount: 0,
+        askCount: 0,
+        anomalyCount: 0,
+        consecutiveDenies: 0,
+        breakerTripped: false,
+        retryExhausted: false,
+        recentEvents: [],
+      };
+      this.sessions.set(key, ledger);
+    }
+    return ledger;
+  }
+
+  /**
+   * Record a decision or system event in the ledger.
+   *
+   * @param {string} sessionId
+   * @param {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+   * @param {{ reason?: string, detail?: string, tool?: string }} [details]
+   */
+  record(sessionId, type, details = {}) {
+    const ledger = this._getOrCreate(sessionId);
+    const now = Date.now();
+
+    const event = {
+      timestamp: now,
+      type,
+      reason: details.reason || "",
+      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
+      tool: details.tool || "",
+    };
+
+    ledger.recentEvents.push(event);
+    if (ledger.recentEvents.length > MAX_LEDGER_EVENTS_PER_SESSION) {
+      ledger.recentEvents.shift();
+    }
+
+    if (type === "allow") {
+      ledger.totalDecisions += 1;
+      ledger.allowedCount += 1;
+      ledger.consecutiveDenies = 0;
+    } else if (type === "deny") {
+      ledger.totalDecisions += 1;
+      ledger.deniedCount += 1;
+      ledger.consecutiveDenies += 1;
+      if (ledger.consecutiveDenies > 1) {
+        ledger.anomalyCount += 1;
+      }
+    } else if (type === "ask") {
+      ledger.totalDecisions += 1;
+      ledger.askCount += 1;
+    } else if (type === "exhaustion") {
+      ledger.retryExhausted = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "breaker") {
+      ledger.breakerTripped = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "error") {
+      ledger.anomalyCount += 1;
+    }
+  }
+
+  /**
+   * Returns a quality summary for the session.
+   *
+   * @param {string} sessionId
+   * @returns {{
+   *   sessionId: string,
+   *   totalDecisions: number,
+   *   allowedCount: number,
+   *   deniedCount: number,
+   *   askCount: number,
+   *   anomalyCount: number,
+   *   consecutiveDenies: number,
+   *   qualityScore: number,
+   *   degradationWarning: boolean,
+   *   recentEvents: LedgerEvent[]
+   * }}
+   */
+  getSummary(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    const total = ledger.totalDecisions;
+
+    // Quality score: 1.0 down towards 0.0 based on denial & anomaly ratio
+    let score = 1.0;
+    if (total > 0) {
+      const penalty = (ledger.deniedCount * 0.2 + ledger.anomalyCount * 0.3) / total;
+      score = Math.max(0, Math.min(1.0, 1.0 - penalty));
+    }
+
+    const degradationWarning = ledger.consecutiveDenies >= 2 ||
+      ledger.retryExhausted ||
+      ledger.breakerTripped ||
+      (total >= 3 && ledger.deniedCount / total >= 0.5);
+
+    return {
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      qualityScore: Number(score.toFixed(2)),
+      degradationWarning,
+      recentEvents: ledger.recentEvents.map((e) => ({ ...e })),
+    };
+  }
+
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}