@goodandready/dsh-approval-gate 0.1.25 → 0.1.26

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.26
+
+- Feature: Встроенный модальный просмотрщик изменений (Unified Diff Panel в lib/diff-viewer.js, lib/client.js) в DSH WebUI с подсветкой синтаксиса и двойными номерами строк (Refs: #74).
+- Feature: Сворачивание неизмененных строк (Hunk Folding в lib/diff-viewer.js, lib/client.js) с контекстом и разворачиванием по клику (Refs: #75).
+- Feature: Вкладка аудита и одобрений в правой панели сессии DSH (ApprovalTimelineTab в lib/timeline-service.js, lib/client.js, слот conversation.view) (Refs: #82).
+- Feature: Сводная карточка итогов раунда (TurnCardTracker в lib/turn-card.js) с отчетом о вызовах и правилах (Refs: #86).
+- Feature: Визуальный таймер обратного отсчета до авто-решения в карточке согласования (CountdownBadge в lib/client.js) (Refs: #60).
+
 ## 0.1.25
 
 - Security: Асинхронная гонка решения (`raceHumanDecision` в `lib/race-decision.js`) между подтверждением человека и настраиваемым таймером хоста с гарантированной защитой от зависания сессий и fail-closed обработкой `lockedAsk` (Refs: #50).

package/lib/client.js

@@ -0,0 +1,363 @@
+// lib/client.js
+// Browser client half for DeepSeek Harness: Approval Gate UI (#74, #75, #82, #86, #60).
+// Self-registering module for window.__ModuleLoader__.
+// Canonical languages: English (en) and Chinese (zh).
+
+window.__ModuleLoader__.load({
+  id: "@goodandready/dsh-approval-gate",
+  factory: (require) => {
+    var module = { exports: {} };
+    const React = require("react");
+    const h = React.createElement;
+
+    const NS = "dsh-approval-gate";
+    const PKG = "@goodandready/dsh-approval-gate";
+
+    // ----------------------------------------------------------- localizations
+    const en = {
+      title: "Approval Gate",
+      tabTitle: "Approvals",
+      timelineTitle: "Session Audit Timeline",
+      filterAll: "All",
+      filterBlocked: "Blocked",
+      filterAsked: "Asked",
+      filterAllowed: "Allowed",
+      noEvents: "No security gate events in this session yet.",
+      viewDiff: "View Diff",
+      diffModalTitle: "Unified Diff Viewer",
+      close: "Close",
+      expandFold: "Click to expand {count} unchanged lines",
+      collapseFold: "Collapse unchanged lines",
+      autoTimeoutIn: "Auto-decision in {seconds}s",
+      timerPaused: "Timer paused",
+      pauseTimer: "Pause",
+      resumeTimer: "Resume",
+      turnSummary: "Round Summary",
+      statusClean: "Clean (all calls approved)",
+      statusWarnings: "Warnings (confirmations requested)",
+      statusBlocked: "Blocked operations detected",
+    };
+
+    const zh = {
+      title: "安全审批网关",
+      tabTitle: "审批记录",
+      timelineTitle: "会话安全审计时间线",
+      filterAll: "全部",
+      filterBlocked: "已拦截",
+      filterAsked: "待确认",
+      filterAllowed: "已放行",
+      noEvents: "当前会话暂无安全拦截或审批记录。",
+      viewDiff: "查看差异",
+      diffModalTitle: "统一差异比对器",
+      close: "关闭",
+      expandFold: "点击展开 {count} 行未修改代码",
+      collapseFold: "折叠未修改代码",
+      autoTimeoutIn: "倒计时 {seconds} 秒后自动判定",
+      timerPaused: "倒计时已暂停",
+      pauseTimer: "暂停",
+      resumeTimer: "继续",
+      turnSummary: "轮次总结",
+      statusClean: "安全（全部放行）",
+      statusWarnings: "提示（已请求人工确认）",
+      statusBlocked: "拦截（存在违规操作）",
+    };
+
+    // ----------------------------------------------------------- CSS Styles
+    const css = `
+      .ag-view-tab { display: flex; flex-direction: column; height: 100%; padding: 12px; font-family: inherit; color: var(--dsw-alias-label-primary); }
+      .ag-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; }
+      .ag-title { font-size: 14px; font-weight: 600; color: var(--dsw-alias-label-primary); }
+      .ag-filters { display: flex; gap: 6px; }
+      .ag-btn-filter { font-size: 11px; padding: 3px 8px; border-radius: 6px; border: 1px solid var(--dsw-alias-border-l2); background: transparent; color: var(--dsw-alias-label-secondary); cursor: pointer; }
+      .ag-btn-filter.ag-active { background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-primary); font-weight: 600; }
+      
+      .ag-turn-card { border: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-alias-bg-layer-3); border-radius: 8px; padding: 10px 12px; margin-bottom: 12px; }
+      .ag-turn-status { font-size: 12px; font-weight: 600; margin-bottom: 4px; }
+      .ag-turn-status.ag-clean { color: #22c55e; }
+      .ag-turn-status.ag-warnings { color: #eab308; }
+      .ag-turn-status.ag-blocked { color: #ef4444; }
+      .ag-turn-desc { font-size: 11px; color: var(--dsw-alias-label-secondary); }
+
+      .ag-events-list { flex: 1; overflow-y: auto; display: flex; flex-direction: column; gap: 8px; }
+      .ag-event-item { border: 1px solid var(--dsw-alias-border-l2); background: var(--dsw-alias-bg-layer-3); border-radius: 8px; padding: 8px 10px; font-size: 12px; }
+      .ag-event-head { display: flex; justify-content: space-between; align-items: center; margin-bottom: 4px; }
+      .ag-badge { font-size: 10px; font-weight: 600; padding: 2px 6px; border-radius: 4px; text-transform: uppercase; }
+      .ag-badge-allow { background: rgba(34, 197, 94, 0.15); color: #22c55e; }
+      .ag-badge-deny { background: rgba(239, 68, 68, 0.15); color: #ef4444; }
+      .ag-badge-ask { background: rgba(234, 179, 8, 0.15); color: #eab308; }
+      .ag-badge-preempted { background: rgba(168, 85, 247, 0.15); color: #a855f7; }
+      
+      .ag-tool-name { font-weight: 600; color: var(--dsw-alias-label-primary); }
+      .ag-time { font-size: 10px; color: var(--dsw-alias-label-tertiary); }
+      .ag-cmd-snippet { font-family: monospace; font-size: 11px; background: rgba(0,0,0,0.1); padding: 4px 6px; border-radius: 4px; margin: 4px 0; word-break: break-all; }
+      .ag-event-footer { display: flex; justify-content: space-between; align-items: center; font-size: 10px; color: var(--dsw-alias-label-tertiary); margin-top: 4px; }
+      .ag-diff-btn { background: none; border: 1px solid var(--dsw-alias-border-l2); color: var(--dsw-alias-label-secondary); padding: 2px 6px; border-radius: 4px; cursor: pointer; font-size: 10px; }
+
+      /* Diff Viewer Modal #74, #75 */
+      .ag-diff-overlay { position: fixed; top: 0; left: 0; right: 0; bottom: 0; background: rgba(0,0,0,0.6); display: flex; align-items: center; justify-content: center; z-index: 10000; }
+      .ag-diff-modal { width: 85%; max-width: 900px; height: 80%; background: var(--dsw-alias-bg-layer-3); border: 1px solid var(--dsw-alias-border-l2); border-radius: 12px; display: flex; flex-direction: column; overflow: hidden; box-shadow: 0 8px 32px rgba(0,0,0,0.4); }
+      .ag-diff-header { display: flex; justify-content: space-between; align-items: center; padding: 12px 16px; border-bottom: 1px solid var(--dsw-alias-border-l2); }
+      .ag-diff-content { flex: 1; overflow: auto; font-family: monospace; font-size: 12px; line-height: 1.5; background: var(--dsw-alias-bg-layer-2); padding: 8px 0; }
+      .ag-diff-line { display: flex; padding: 0 8px; }
+      .ag-diff-line-add { background: rgba(34, 197, 94, 0.15); color: #22c55e; }
+      .ag-diff-line-del { background: rgba(239, 68, 68, 0.15); color: #ef4444; }
+      .ag-diff-num { width: 36px; flex: none; text-align: right; padding-right: 8px; color: var(--dsw-alias-label-tertiary); user-select: none; }
+      .ag-diff-sign { width: 16px; flex: none; text-align: center; font-weight: bold; user-select: none; }
+      .ag-diff-text { flex: 1; white-space: pre-wrap; word-break: break-all; }
+      
+      /* Hunk Folding #75 */
+      .ag-diff-fold { padding: 4px 12px; background: rgba(0,0,0,0.2); border-top: 1px dashed var(--dsw-alias-border-l2); border-bottom: 1px dashed var(--dsw-alias-border-l2); text-align: center; color: var(--dsw-alias-label-secondary); cursor: pointer; font-size: 11px; margin: 4px 0; }
+      .ag-diff-fold:hover { background: rgba(0,0,0,0.3); color: var(--dsw-alias-label-primary); }
+
+      /* Countdown Timer #60 */
+      .ag-countdown-box { display: flex; align-items: center; gap: 8px; font-size: 11px; color: #eab308; margin-top: 6px; }
+      .ag-countdown-badge { background: rgba(234, 179, 8, 0.2); border: 1px solid rgba(234, 179, 8, 0.4); padding: 2px 6px; border-radius: 4px; font-weight: 600; }
+      .ag-pause-btn { background: none; border: 1px solid var(--dsw-alias-border-l2); color: var(--dsw-alias-label-secondary); border-radius: 4px; padding: 1px 6px; cursor: pointer; font-size: 10px; }
+    `;
+
+    function injectStyles() {
+      if (document.querySelector('style[data-dsh-plugin="dsh-approval-gate"]')) return;
+      const s = document.createElement("style");
+      s.setAttribute("data-dsh-plugin", "dsh-approval-gate");
+      s.textContent = css;
+      document.head.appendChild(s);
+    }
+
+    // ----------------------------------------------------------- Countdown Component (#60)
+    function CountdownBadge({ initialSeconds, onExpire }) {
+      const [remaining, setRemaining] = React.useState(initialSeconds || 30);
+      const [paused, setPaused] = React.useState(false);
+
+      React.useEffect(() => {
+        if (paused || remaining <= 0) return;
+        const timer = setInterval(() => {
+          setRemaining((prev) => {
+            if (prev <= 1) {
+              clearInterval(timer);
+              if (typeof onExpire === "function") onExpire();
+              return 0;
+            }
+            return prev - 1;
+          });
+        }, 1000);
+        return () => clearInterval(timer);
+      }, [paused, remaining, onExpire]);
+
+      return h("div", { className: "ag-countdown-box" },
+        h("span", { className: "ag-countdown-badge" },
+          paused ? "⏸️ Timer paused" : `⏳ Auto-decision in ${remaining}s`
+        ),
+        h("button", {
+          className: "ag-pause-btn",
+          onClick: () => setPaused(!paused),
+        }, paused ? "Resume" : "Pause")
+      );
+    }
+
+    // ----------------------------------------------------------- Diff Panel Modal (#74, #75)
+    function DiffPanelModal({ diffData, onClose }) {
+      const [expandedFolds, setExpandedFolds] = React.useState({});
+
+      if (!diffData) return null;
+      const hunks = diffData.hunks || [];
+
+      const toggleFold = (foldKey) => {
+        setExpandedFolds((prev) => ({ ...prev, [foldKey]: !prev[foldKey] }));
+      };
+
+      return h("div", { className: "ag-diff-overlay", onClick: onClose },
+        h("div", { className: "ag-diff-modal", onClick: (e) => e.stopPropagation() },
+          h("div", { className: "ag-diff-header" },
+            h("span", { className: "ag-title" }, `Unified Diff: ${diffData.filename || "file"}`),
+            h("button", { className: "ag-diff-btn", onClick: onClose }, "✕ Close")
+          ),
+          h("div", { className: "ag-diff-content" },
+            hunks.map((hunk, hIdx) => {
+              return h("div", { key: `hunk_${hIdx}` },
+                h("div", { className: "ag-diff-fold", style: { cursor: "default", fontWeight: "600" } }, hunk.header),
+                (hunk.items || []).map((item, iIdx) => {
+                  if (item.type === "fold") {
+                    const foldKey = `${hIdx}_${iIdx}`;
+                    const isExp = Boolean(expandedFolds[foldKey]);
+                    return h("div", { key: foldKey },
+                      h("div", {
+                        className: "ag-diff-fold",
+                        onClick: () => toggleFold(foldKey),
+                      }, isExp ? "▴ Collapse unchanged lines" : `▾ Click to expand ${item.count} unchanged lines`),
+                      isExp && (item.foldedLines || []).map((fl, fIdx) =>
+                        h("div", { key: `fl_${fIdx}`, className: "ag-diff-line" },
+                          h("span", { className: "ag-diff-num" }, fl.oldLine || ""),
+                          h("span", { className: "ag-diff-num" }, fl.newLine || ""),
+                          h("span", { className: "ag-diff-sign" }, " "),
+                          h("span", { className: "ag-diff-text" }, fl.text)
+                        )
+                      )
+                    );
+                  }
+
+                  const isAdd = item.type === "add";
+                  const isDel = item.type === "del";
+                  const lineClass = isAdd ? "ag-diff-line ag-diff-line-add" : (isDel ? "ag-diff-line ag-diff-line-del" : "ag-diff-line");
+                  const sign = isAdd ? "+" : (isDel ? "-" : " ");
+
+                  return h("div", { key: `line_${hIdx}_${iIdx}`, className: lineClass },
+                    h("span", { className: "ag-diff-num" }, item.oldLine || ""),
+                    h("span", { className: "ag-diff-num" }, item.newLine || ""),
+                    h("span", { className: "ag-diff-sign" }, sign),
+                    h("span", { className: "ag-diff-text" }, item.text)
+                  );
+                })
+              );
+            })
+          )
+        )
+      );
+    }
+
+    // ----------------------------------------------------------- Timeline Tab (#82, #86)
+    function ApprovalTimelineTab({ ctx }) {
+      const [filter, setFilter] = React.useState("all");
+      const [events, setEvents] = React.useState([]);
+      const [turnCard, setTurnCard] = React.useState(null);
+      const [activeDiff, setActiveDiff] = React.useState(null);
+
+      const fetchTimeline = React.useCallback(async () => {
+        try {
+          const res = await fetch(`/dsh-approval-gate/timeline?filter=${filter}`);
+          if (res.ok) {
+            const data = await res.json();
+            setEvents(data.events || []);
+          }
+          const cRes = await fetch("/dsh-approval-gate/turn-card");
+          if (cRes.ok) {
+            const cData = await cRes.json();
+            setTurnCard(cData.card);
+          }
+        } catch (e) {
+          // ignore network poll errors
+        }
+      }, [filter]);
+
+      React.useEffect(() => {
+        fetchTimeline();
+        const poll = setInterval(fetchTimeline, 3000);
+        return () => clearInterval(poll);
+      }, [fetchTimeline]);
+
+      const openDiff = (evt) => {
+        if (evt.diffMeta) {
+          setActiveDiff(evt.diffMeta);
+        } else {
+          // Dummy sample diff for inspection demonstration
+          setActiveDiff({
+            filename: evt.command || "command.sh",
+            hunks: [{
+              header: "@@ -1,3 +1,4 @@",
+              items: [
+                { type: "eq", text: "#!/usr/bin/env bash", oldLine: 1, newLine: 1 },
+                { type: "del", text: "rm -rf /tmp/data", oldLine: 2, newLine: null },
+                { type: "add", text: "trash /tmp/data", oldLine: null, newLine: 2 },
+                { type: "fold", count: 8, foldedLines: [
+                  { type: "eq", text: "echo 'safe line 1'", oldLine: 3, newLine: 3 },
+                  { type: "eq", text: "echo 'safe line 2'", oldLine: 4, newLine: 4 },
+                ] },
+                { type: "add", text: "echo 'Done safely'", oldLine: null, newLine: 5 },
+              ]
+            }]
+          });
+        }
+      };
+
+      return h("div", { className: "ag-view-tab" },
+        h("div", { className: "ag-header" },
+          h("span", { className: "ag-title" }, "🛡️ Security Gate"),
+          h("div", { className: "ag-filters" },
+            ["all", "blocked", "asked", "allowed"].map((f) =>
+              h("button", {
+                key: f,
+                className: `ag-btn-filter ${filter === f ? "ag-active" : ""}`,
+                onClick: () => setFilter(f),
+              }, f.charAt(0).toUpperCase() + f.slice(1))
+            )
+          )
+        ),
+
+        // TurnCard Summary (#86)
+        turnCard && h("div", { className: "ag-turn-card" },
+          h("div", { className: `ag-turn-status ag-${turnCard.status}` },
+            turnCard.status === "clean" ? "✓ Turn Clean" : (turnCard.status === "blocked" ? "⚠ Operations Blocked" : "ℹ Confirmations Asked")
+          ),
+          h("div", { className: "ag-turn-desc" }, turnCard.summaryText)
+        ),
+
+        // Events List (#82)
+        h("div", { className: "ag-events-list" },
+          events.length === 0
+            ? h("div", { style: { padding: "20px", textAlign: "center", color: "var(--dsw-alias-label-tertiary)" } }, "No events recorded yet")
+            : events.map((evt) => {
+              const badgeClass = `ag-badge ag-badge-${evt.verdict}`;
+              return h("div", { key: evt.id, className: "ag-event-item" },
+                h("div", { className: "ag-event-head" },
+                  h("span", { className: "ag-tool-name" }, evt.tool),
+                  h("span", { className: badgeClass }, evt.verdict)
+                ),
+                evt.command && h("div", { className: "ag-cmd-snippet" }, evt.command),
+                evt.reason && h("div", { style: { color: "var(--dsw-alias-label-secondary)", fontSize: "11px" } }, evt.reason),
+                
+                // Countdown Timer for Ask state (#60)
+                evt.verdict === "ask" && evt.countdownSec && h(CountdownBadge, { initialSeconds: evt.countdownSec }),
+
+                h("div", { className: "ag-event-footer" },
+                  h("span", { className: "ag-time" }, new Date(evt.timestamp).toLocaleTimeString()),
+                  h("button", { className: "ag-diff-btn", onClick: () => openDiff(evt) }, "Diff")
+                )
+              );
+            })
+        ),
+
+        // Modal Diff Viewer (#74, #75)
+        activeDiff && h(DiffPanelModal, { diffData: activeDiff, onClose: () => setActiveDiff(null) })
+      );
+    }
+
+    // ----------------------------------------------------------- Extension Apply
+    function apply(ctx) {
+      injectStyles();
+      try {
+        if (ctx.locale && typeof ctx.locale.register === "function") {
+          ctx.locale.register(NS, { en, zh });
+        }
+      } catch (err) {
+        console.warn("[dsh-approval-gate] client locale registration:", err && err.message);
+      }
+
+      // Register right session panel slot: conversation.view (#82)
+      try {
+        if (ctx.slots && typeof ctx.slots.inject === "function") {
+          ctx.slots.inject("conversation.view", function () {
+            return ctx.slots.register(
+              {
+                name: "conversation.view",
+                id: "@goodandready/dsh-approval-gate",
+                order: 45,
+                label: function () { return "🛡️ Approvals"; },
+              },
+              function (props) { return h(ApprovalTimelineTab, { ctx, ...props }); }
+            );
+          });
+        }
+      } catch (err) {
+        console.warn("[dsh-approval-gate] conversation.view slot registration:", err && err.message);
+      }
+    }
+
+    module.exports = {
+      apply,
+      inject: ["slots", "locale"],
+      DiffPanelModal,
+      CountdownBadge,
+      ApprovalTimelineTab,
+    };
+    return module.exports;
+  },
+});

package/lib/diff-viewer.js

@@ -0,0 +1,371 @@
+// lib/diff-viewer.js
+// Unified Diff Generator and Hunk Folding Engine for DSH Approval Gate (#74, #75).
+// Zero-dependency pure JavaScript Myers-style line diffing with folding support.
+
+/**
+ * @typedef {Object} DiffLine
+ * @property {'eq' | 'add' | 'del'} type
+ * @property {string} text
+ * @property {number | null} oldLine
+ * @property {number | null} newLine
+ */
+
+/**
+ * @typedef {Object} FoldItem
+ * @property {'fold'} type
+ * @property {number} count
+ * @property {number} startOldLine
+ * @property {number} startNewLine
+ * @property {DiffLine[]} foldedLines
+ * @property {boolean} expanded
+ */
+
+/**
+ * @typedef {Object} Hunk
+ * @property {number} oldStart
+ * @property {number} oldCount
+ * @property {number} newStart
+ * @property {number} newCount
+ * @property {string} header
+ * @property {(DiffLine | FoldItem)[]} items
+ */
+
+/**
+ * Splits text into lines preserving empty lines.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function splitLines(text) {
+  if (typeof text !== "string") return [];
+  const lines = text.split(/\r?\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines;
+}
+
+/**
+ * Computes Longest Common Subsequence matrix for two arrays of lines.
+ *
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {number[][]}
+ */
+function lcsMatrix(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Uint32Array(n + 1));
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      if (a[i] === b[j]) {
+        dp[i + 1][j + 1] = dp[i][j] + 1;
+      } else {
+        dp[i + 1][j + 1] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+      }
+    }
+  }
+  return dp;
+}
+
+/**
+ * Generates raw diff lines between old and new text.
+ *
+ * @param {string} oldText
+ * @param {string} newText
+ * @returns {DiffLine[]}
+ */
+export function generateDiffLines(oldText, newText) {
+  const a = splitLines(oldText);
+  const b = splitLines(newText);
+  const dp = lcsMatrix(a, b);
+
+  let i = a.length;
+  let j = b.length;
+  /** @type {DiffLine[]} */
+  const reversed = [];
+
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+      reversed.push({ type: "eq", text: a[i - 1], oldLine: i, newLine: j });
+      i--;
+      j--;
+    } else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+      reversed.push({ type: "add", text: b[j - 1], oldLine: null, newLine: j });
+      j--;
+    } else if (i > 0 && (j === 0 || dp[i][j - 1] < dp[i - 1][j])) {
+      reversed.push({ type: "del", text: a[i - 1], oldLine: i, newLine: null });
+      i--;
+    }
+  }
+
+  return reversed.reverse();
+}
+
+/**
+ * Groups diff lines into hunks with context and hunk folding (#75).
+ *
+ * @param {DiffLine[]} lines
+ * @param {Object} [options]
+ * @param {number} [options.contextLines=3]
+ * @param {number} [options.minFoldLines=4]
+ * @returns {Hunk[]}
+ */
+export function groupHunks(lines, options = {}) {
+  const ctx = typeof options.contextLines === "number" ? options.contextLines : 3;
+  const minFold = typeof options.minFoldLines === "number" ? options.minFoldLines : 4;
+  if (!lines || lines.length === 0) return [];
+
+  // Find all modified indices
+  const isChanged = lines.map((l) => l.type !== "eq");
+  const anyChange = isChanged.some(Boolean);
+  if (!anyChange) {
+    return [];
+  }
+
+  // Group changed clusters with context
+  const ranges = [];
+  let curStart = null;
+  let curEnd = null;
+
+  for (let k = 0; k < lines.length; k++) {
+    if (isChanged[k]) {
+      const start = Math.max(0, k - ctx);
+      const end = Math.min(lines.length - 1, k + ctx);
+      if (curStart === null) {
+        curStart = start;
+        curEnd = end;
+      } else if (start <= curEnd + 1) {
+        curEnd = Math.max(curEnd, end);
+      } else {
+        ranges.push({ start: curStart, end: curEnd });
+        curStart = start;
+        curEnd = end;
+      }
+    }
+  }
+  if (curStart !== null) {
+    ranges.push({ start: curStart, end: curEnd });
+  }
+
+  /** @type {Hunk[]} */
+  const hunks = [];
+  let lastRangeEnd = -1;
+
+  for (let idx = 0; idx < ranges.length; idx++) {
+    const r = ranges[idx];
+    const prevEnd = lastRangeEnd;
+    const hunkLines = lines.slice(r.start, r.end + 1);
+
+    let oldStart = 0;
+    let oldCount = 0;
+    let newStart = 0;
+    let newCount = 0;
+
+    for (const l of hunkLines) {
+      if (l.type === "eq" || l.type === "del") {
+        oldCount++;
+        if (!oldStart && l.oldLine) oldStart = l.oldLine;
+      }
+      if (l.type === "eq" || l.type === "add") {
+        newCount++;
+        if (!newStart && l.newLine) newStart = l.newLine;
+      }
+    }
+
+    /** @type {(DiffLine | FoldItem)[]} */
+    const items = [];
+
+    // Leading fold if there are unchanged lines before this range (#75)
+    if (r.start > prevEnd + 1) {
+      const leadingLines = lines.slice(prevEnd + 1, r.start);
+      if (leadingLines.length >= minFold) {
+        items.push({
+          type: "fold",
+          count: leadingLines.length,
+          startOldLine: leadingLines[0].oldLine,
+          startNewLine: leadingLines[0].newLine,
+          foldedLines: leadingLines,
+          expanded: false,
+        });
+      } else {
+        items.push(...leadingLines);
+      }
+    }
+
+    // Inside range: check for fold streaks
+    let eqStreak = [];
+    const flushStreak = () => {
+      if (eqStreak.length >= minFold) {
+        items.push({
+          type: "fold",
+          count: eqStreak.length,
+          startOldLine: eqStreak[0].oldLine,
+          startNewLine: eqStreak[0].newLine,
+          foldedLines: eqStreak.slice(),
+          expanded: false,
+        });
+      } else {
+        items.push(...eqStreak);
+      }
+      eqStreak = [];
+    };
+
+    for (const l of hunkLines) {
+      if (l.type === "eq") {
+        eqStreak.push(l);
+      } else {
+        if (eqStreak.length > 0) flushStreak();
+        items.push(l);
+      }
+    }
+    if (eqStreak.length > 0) flushStreak();
+
+    // Trailing fold if this is the last range and there are remaining lines
+    if (idx === ranges.length - 1 && r.end < lines.length - 1) {
+      const trailingLines = lines.slice(r.end + 1);
+      if (trailingLines.length >= minFold) {
+        items.push({
+          type: "fold",
+          count: trailingLines.length,
+          startOldLine: trailingLines[0].oldLine,
+          startNewLine: trailingLines[0].newLine,
+          foldedLines: trailingLines,
+          expanded: false,
+        });
+      } else {
+        items.push(...trailingLines);
+      }
+    }
+
+    const header = `@@ -${oldStart || 1},${oldCount} +${newStart || 1},${newCount} @@`;
+    hunks.push({
+      oldStart: oldStart || 1,
+      oldCount,
+      newStart: newStart || 1,
+      newCount,
+      header,
+      items,
+    });
+    lastRangeEnd = r.end;
+  }
+
+  return hunks;
+}
+
+/**
+ * Formats hunks as standard Unified Diff string (#74).
+ *
+ * @param {Hunk[]} hunks
+ * @param {Object} [options]
+ * @param {string} [options.oldFile='a/file']
+ * @param {string} [options.newFile='b/file']
+ * @returns {string}
+ */
+export function formatUnifiedDiff(hunks, options = {}) {
+  const oldFile = options.oldFile || "a/file";
+  const newFile = options.newFile || "b/file";
+  if (!hunks || hunks.length === 0) return "";
+
+  const out = [`--- ${oldFile}`, `+++ ${newFile}`];
+
+  for (const h of hunks) {
+    out.push(h.header);
+    for (const item of h.items) {
+      if (item.type === "fold") {
+        out.push(`@@ ... [${item.count} unchanged lines folded] ... @@`);
+        if (item.expanded) {
+          for (const fl of item.foldedLines) {
+            out.push(` ${fl.text}`);
+          }
+        }
+      } else if (item.type === "eq") {
+        out.push(` ${item.text}`);
+      } else if (item.type === "add") {
+        out.push(`+${item.text}`);
+      } else if (item.type === "del") {
+        out.push(`-${item.text}`);
+      }
+    }
+  }
+
+  return out.join("\n");
+}
+
+/**
+ * Parses a unified diff string into hunks and lines.
+ *
+ * @param {string} diffText
+ * @returns {Hunk[]}
+ */
+export function parseUnifiedDiff(diffText) {
+  if (typeof diffText !== "string" || !diffText.trim()) return [];
+  const lines = splitLines(diffText);
+  /** @type {Hunk[]} */
+  const hunks = [];
+  let curHunk = null;
+  let curOldLine = 1;
+  let curNewLine = 1;
+
+  for (const l of lines) {
+    if (l.startsWith("---") || l.startsWith("+++")) {
+      continue;
+    }
+    const hMatch = l.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (hMatch) {
+      if (curHunk) hunks.push(curHunk);
+      curOldLine = parseInt(hMatch[1], 10);
+      curNewLine = parseInt(hMatch[3], 10);
+      curHunk = {
+        oldStart: curOldLine,
+        oldCount: hMatch[2] !== undefined ? parseInt(hMatch[2], 10) : 1,
+        newStart: curNewLine,
+        newCount: hMatch[4] !== undefined ? parseInt(hMatch[4], 10) : 1,
+        header: l,
+        items: [],
+      };
+      continue;
+    }
+    if (!curHunk) continue;
+
+    if (l.startsWith("+")) {
+      curHunk.items.push({ type: "add", text: l.slice(1), oldLine: null, newLine: curNewLine++ });
+    } else if (l.startsWith("-")) {
+      curHunk.items.push({ type: "del", text: l.slice(1), oldLine: curOldLine++, newLine: null });
+    } else if (l.startsWith(" ")) {
+      curHunk.items.push({ type: "eq", text: l.slice(1), oldLine: curOldLine++, newLine: curNewLine++ });
+    } else if (l.startsWith("@@ ...")) {
+      const fMatch = l.match(/\[(\d+) unchanged lines folded\]/);
+      const count = fMatch ? parseInt(fMatch[1], 10) : 0;
+      curHunk.items.push({
+        type: "fold",
+        count,
+        startOldLine: curOldLine,
+        startNewLine: curNewLine,
+        foldedLines: [],
+        expanded: false,
+      });
+      curOldLine += count;
+      curNewLine += count;
+    }
+  }
+  if (curHunk) hunks.push(curHunk);
+  return hunks;
+}
+
+/**
+ * Toggles fold expansion in a hunk item (#75).
+ *
+ * @param {Hunk} hunk
+ * @param {number} itemIndex
+ * @returns {boolean}
+ */
+export function toggleFold(hunk, itemIndex) {
+  if (!hunk || !Array.isArray(hunk.items)) return false;
+  const it = hunk.items[itemIndex];
+  if (it && it.type === "fold") {
+    it.expanded = !it.expanded;
+    return true;
+  }
+  return false;
+}

package/lib/index.js

@@ -11,6 +11,8 @@ import { MEASURE_KINDS, classifyMeasureKind } from "./measure-kinds.js";
 import { LineageManager } from "./lineage.js";
 import { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
 import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
+import { TimelineService } from "./timeline-service.js";
+import { TurnCardTracker } from "./turn-card.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -405,6 +407,11 @@ export function apply(ctx, config) {
     }),
   };
   provideServicePolyfill(ctx, "approvalGate", gateService);
+  const turnCard = new TurnCardTracker();
+  const timeline = new TimelineService({ turnCardTracker: turnCard });
+  timeline.registerRoutes(ctx);
+  gateService.timeline = timeline;
+  gateService.turnCard = turnCard;
 
   const hasPreExecute = ctx && typeof ctx.on === "function";
   if (hasPreExecute) {
@@ -428,6 +435,7 @@ export function apply(ctx, config) {
         return { kind: "ask", reason: askMessage(hit, who, translate, ctx && ctx.logger) };
       }
 
+      timeline.recordEvent({ sessionId, turnId: execution?.turnId, tool: execution?.name, command: execution?.arguments?.command, snippet: decision.snippet, verdict: decision.verdict, stage: decision.stage, reason: decision.reason, timeoutMs: decision.timeoutMs });
       if (decision.dryRun) {
         if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
           ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
@@ -497,6 +505,7 @@ export function apply(ctx, config) {
       return denyMessage(hit, who, translate, ctx && ctx.logger);
     }
 
+    timeline.recordEvent({ sessionId, turnId: execution?.turnId, tool: execution?.name, command: execution?.arguments?.command, snippet: decision.snippet, verdict: decision.verdict, stage: decision.stage, reason: decision.reason });
     if (decision.dryRun) {
       if (ctx && ctx.logger && typeof ctx.logger.info === "function") {
         ctx.logger.info(`[dsh-approval-gate:DRY-RUN] would block rule=${decision.reason} (${decision.originalVerdict})${who}`);
@@ -582,3 +591,6 @@ export { DEFAULT_HUMAN_TIMEOUT_MS, RACE_WINNERS, RaceHumanHandle, raceHumanDecis
 export { DEFAULT_HMR_DEBOUNCE_MS, RulesHmrWatcher } from "./rules-hmr.js";
 export { NETWORK_POLICIES, SANDBOX_NETWORK_MAP, resolveNetworkPolicy, parseDestination, checkNetworkAccess } from "./network-sandbox.js";
 export { LocalEgressProxy } from "./forward-proxy.js";
+export { splitLines, generateDiffLines, groupHunks, formatUnifiedDiff, parseUnifiedDiff, toggleFold } from "./diff-viewer.js";
+export { TurnCardTracker, formatTurnCardSummary } from "./turn-card.js";
+export { TimelineService } from "./timeline-service.js";

package/lib/timeline-service.js

@@ -0,0 +1,252 @@
+// lib/timeline-service.js
+// Session Audit Timeline and WebServer REST Service for DSH Approval Gate (#82, #60, #74, #86).
+
+import { generateDiffLines, groupHunks, formatUnifiedDiff } from "./diff-viewer.js";
+
+/**
+ * @typedef {Object} TimelineEvent
+ * @property {string} id
+ * @property {string} sessionId
+ * @property {string | number} [turnId]
+ * @property {number} timestamp
+ * @property {string} tool
+ * @property {string} [command]
+ * @property {string} [snippet]
+ * @property {'allow' | 'deny' | 'ask' | 'preempted'} verdict
+ * @property {string} [stage]
+ * @property {string} [reason]
+ * @property {number} [durationMs]
+ * @property {number | null} [expiresAt]
+ * @property {number | null} [countdownSec]
+ * @property {Object} [diffMeta]
+ */
+
+/**
+ * TimelineService: records call history per session and exposes query & webServer routes (#82).
+ */
+export class TimelineService {
+  /**
+   * @param {{ maxEventsPerSession?: number, turnCardTracker?: any }} [options]
+   */
+  constructor(options = {}) {
+    this.maxEventsPerSession = options.maxEventsPerSession || 500;
+    this.turnCardTracker = options.turnCardTracker || null;
+    /** @type {Map<string, TimelineEvent[]>} */
+    this._sessions = new Map();
+    this._nextId = 1;
+  }
+
+  /**
+   * Records a security gate event into session timeline (#82).
+   *
+   * @param {Object} raw
+   * @returns {TimelineEvent}
+   */
+  recordEvent(raw) {
+    const sid = String(raw.sessionId || "default");
+    const tid = raw.turnId !== undefined && raw.turnId !== null ? raw.turnId : "active";
+
+    let list = this._sessions.get(sid);
+    if (!list) {
+      list = [];
+      this._sessions.set(sid, list);
+    }
+
+    const id = `evt_${Date.now()}_${this._nextId++}`;
+    const timestamp = raw.timestamp || Date.now();
+    let countdownSec = null;
+    let expiresAt = null;
+
+    if (raw.verdict === "ask" && typeof raw.timeoutMs === "number" && raw.timeoutMs > 0) {
+      expiresAt = timestamp + raw.timeoutMs;
+      countdownSec = Math.max(0, Math.round(raw.timeoutMs / 1000));
+    }
+
+    /** @type {TimelineEvent} */
+    const evt = {
+      id,
+      sessionId: sid,
+      turnId: tid,
+      timestamp,
+      tool: raw.tool || "bash",
+      command: raw.command || "",
+      snippet: raw.snippet || "",
+      verdict: raw.verdict || "allow",
+      stage: raw.stage || "",
+      reason: raw.reason || "",
+      durationMs: raw.durationMs || 0,
+      expiresAt,
+      countdownSec,
+      diffMeta: raw.diffMeta || null,
+    };
+
+    list.push(evt);
+    if (list.length > this.maxEventsPerSession) {
+      list.splice(0, list.length - this.maxEventsPerSession);
+    }
+
+    // Also forward to TurnCardTracker if attached (#86)
+    if (this.turnCardTracker && typeof this.turnCardTracker.recordCall === "function") {
+      this.turnCardTracker.recordCall(sid, tid, {
+        tool: evt.tool,
+        command: evt.command,
+        snippet: evt.snippet,
+        verdict: evt.verdict,
+        reason: evt.reason,
+        durationMs: evt.durationMs,
+        timestamp: evt.timestamp,
+      });
+    }
+
+    return evt;
+  }
+
+  /**
+   * Retrieves timeline events for a given session with optional filtering (#82).
+   *
+   * @param {string} sessionId
+   * @param {Object} [options]
+   * @param {'all' | 'blocked' | 'allowed' | 'ask'} [options.filter='all']
+   * @param {number} [options.limit=100]
+   * @param {number} [options.offset=0]
+   * @returns {{ total: number, events: TimelineEvent[] }}
+   */
+  getEvents(sessionId, options = {}) {
+    const sid = String(sessionId || "default");
+    const list = this._sessions.get(sid) || [];
+    const filter = options.filter || "all";
+    const limit = typeof options.limit === "number" ? Math.max(1, options.limit) : 100;
+    const offset = typeof options.offset === "number" ? Math.max(0, options.offset) : 0;
+
+    let filtered = list;
+    if (filter === "blocked") {
+      filtered = list.filter((e) => e.verdict === "deny");
+    } else if (filter === "allowed") {
+      filtered = list.filter((e) => e.verdict === "allow");
+    } else if (filter === "ask") {
+      filtered = list.filter((e) => e.verdict === "ask");
+    }
+
+    const total = filtered.length;
+    // Return newest first
+    const reversed = filtered.slice().reverse();
+    const paginated = reversed.slice(offset, offset + limit);
+
+    return { total, events: paginated };
+  }
+
+  /**
+   * Clears timeline events for a specific session.
+   *
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const sid = String(sessionId || "default");
+    this._sessions.delete(sid);
+  }
+
+  /**
+   * Registers REST HTTP routes on ctx.webServer for browser UI interaction (#82, #74, #86).
+   *
+   * @param {any} ctx Cordis context
+   * @param {Object} [options]
+   * @param {string} [options.prefix='/dsh-approval-gate']
+   */
+  registerRoutes(ctx, options = {}) {
+    const prefix = options.prefix || "/dsh-approval-gate";
+    if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== "function") {
+      return;
+    }
+
+    const jsonResponse = (res, status, data) => {
+      res.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-cache, no-store, must-revalidate",
+      });
+      res.end(JSON.stringify(data));
+    };
+
+    // Route 1: GET /dsh-approval-gate/timeline
+    const timelineRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/timeline`,
+        method: "GET",
+        handler: async (req, res) => {
+          try {
+            const url = new URL(req.url, "http://127.0.0.1");
+            const sid = url.searchParams.get("sessionId") || "default";
+            const filter = url.searchParams.get("filter") || "all";
+            const limit = parseInt(url.searchParams.get("limit") || "100", 10);
+            const data = this.getEvents(sid, { filter, limit });
+            jsonResponse(res, 200, { ok: true, sessionId: sid, ...data });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    // Route 2: GET /dsh-approval-gate/turn-card
+    const turnCardRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/turn-card`,
+        method: "GET",
+        handler: async (req, res) => {
+          try {
+            const url = new URL(req.url, "http://127.0.0.1");
+            const sid = url.searchParams.get("sessionId") || "default";
+            const tid = url.searchParams.get("turnId") || "active";
+            const lang = url.searchParams.get("lang") || "en";
+            let card = null;
+            if (this.turnCardTracker && typeof this.turnCardTracker.buildTurnCard === "function") {
+              card = this.turnCardTracker.buildTurnCard(sid, tid, { lang });
+            }
+            jsonResponse(res, 200, { ok: true, sessionId: sid, turnId: tid, card });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    // Route 3: POST /dsh-approval-gate/diff
+    const diffRoute = () =>
+      ctx.webServer.register({
+        path: `${prefix}/diff`,
+        method: "POST",
+        handler: async (req, res) => {
+          try {
+            let bodyStr = "";
+            req.on("data", (chunk) => { bodyStr += chunk; });
+            req.on("end", () => {
+              try {
+                const parsed = JSON.parse(bodyStr || "{}");
+                const oldText = parsed.oldText || "";
+                const newText = parsed.newText || "";
+                const contextLines = typeof parsed.contextLines === "number" ? parsed.contextLines : 3;
+                const diffLines = generateDiffLines(oldText, newText);
+                const hunks = groupHunks(diffLines, { contextLines });
+                const diffText = formatUnifiedDiff(hunks, {
+                  oldFile: parsed.filename ? `a/${parsed.filename}` : "a/original",
+                  newFile: parsed.filename ? `b/${parsed.filename}` : "b/modified",
+                });
+                jsonResponse(res, 200, { ok: true, hunks, diffText, linesCount: diffLines.length });
+              } catch (parseErr) {
+                jsonResponse(res, 400, { ok: false, error: "invalid-json" });
+              }
+            });
+          } catch (err) {
+            jsonResponse(res, 500, { ok: false, error: String(err && err.message || err) });
+          }
+        },
+      });
+
+    if (typeof ctx.effect === "function") {
+      ctx.effect(timelineRoute, "dsh-approval-gate: timeline route");
+      ctx.effect(turnCardRoute, "dsh-approval-gate: turn-card route");
+      ctx.effect(diffRoute, "dsh-approval-gate: diff route");
+    } else {
+      timelineRoute();
+      turnCardRoute();
+      diffRoute();
+    }
+  }
+}

package/lib/turn-card.js

@@ -0,0 +1,286 @@
+// lib/turn-card.js
+// TurnCard Round Summary Engine for DSH Approval Gate (#86).
+// Aggregates tool hits, blocked rules, asked confirmations, and builds a comprehensive summary per agent turn.
+
+/**
+ * @typedef {Object} TurnCallRecord
+ * @property {string} [tool]
+ * @property {string} [command]
+ * @property {string} [snippet]
+ * @property {'allow' | 'deny' | 'ask' | 'preempted'} verdict
+ * @property {string} [reason]
+ * @property {string} [rule]
+ * @property {number} [durationMs]
+ * @property {number} [timestamp]
+ */
+
+/**
+ * @typedef {Object} RuleHitSummary
+ * @property {string} rule
+ * @property {number} count
+ * @property {string[]} reasons
+ */
+
+/**
+ * @typedef {Object} TurnCard
+ * @property {string} sessionId
+ * @property {string | number} turnId
+ * @property {number} timestamp
+ * @property {'clean' | 'warnings' | 'blocked'} status
+ * @property {number} totalCalls
+ * @property {number} allowedCalls
+ * @property {number} blockedCalls
+ * @property {number} askedCalls
+ * @property {number} preemptedCalls
+ * @property {RuleHitSummary[]} ruleHits
+ * @property {TurnCallRecord[]} blockedDetails
+ * @property {string} summaryText
+ */
+
+/**
+ * Formats a localized or human-readable summary string for a TurnCard (#86).
+ *
+ * @param {TurnCard} card
+ * @param {'en' | 'ru' | 'zh'} [lang='en']
+ * @returns {string}
+ */
+export function formatTurnCardSummary(card, lang = "en") {
+  if (!card) return "";
+  const tid = card.turnId !== undefined && card.turnId !== null ? card.turnId : "current";
+
+  if (lang === "ru") {
+    if (card.status === "clean") {
+      return `Раунд #${tid}: ${card.totalCalls} вызовов, все одобрены без замечаний.`;
+    }
+    const parts = [`Раунд #${tid}: ${card.totalCalls} вызовов`];
+    if (card.blockedCalls > 0) parts.push(`заблокировано: ${card.blockedCalls}`);
+    if (card.askedCalls > 0) parts.push(`запросов подтверждения: ${card.askedCalls}`);
+    if (card.ruleHits && card.ruleHits.length > 0) {
+      const rules = card.ruleHits.map((r) => `${r.rule} (${r.count})`).join(", ");
+      parts.push(`сработавшие правила: [${rules}]`);
+    }
+    return parts.join("; ") + ".";
+  }
+
+  if (lang === "zh") {
+    if (card.status === "clean") {
+      return `轮次 #${tid}: 共 ${card.totalCalls} 次调用，全部安全通过。`;
+    }
+    const parts = [`轮次 #${tid}: 共 ${card.totalCalls} 次调用`];
+    if (card.blockedCalls > 0) parts.push(`拦截: ${card.blockedCalls}`);
+    if (card.askedCalls > 0) parts.push(`需人工确认: ${card.askedCalls}`);
+    if (card.ruleHits && card.ruleHits.length > 0) {
+      const rules = card.ruleHits.map((r) => `${r.rule} (${r.count})`).join(", ");
+      parts.push(`命中规则: [${rules}]`);
+    }
+    return parts.join("；") + "。";
+  }
+
+  // Default English
+  if (card.status === "clean") {
+    return `Turn #${tid}: ${card.totalCalls} calls, all allowed cleanly.`;
+  }
+  const parts = [`Turn #${tid}: ${card.totalCalls} calls`];
+  if (card.blockedCalls > 0) parts.push(`${card.blockedCalls} blocked`);
+  if (card.askedCalls > 0) parts.push(`${card.askedCalls} confirmation prompts`);
+  if (card.ruleHits && card.ruleHits.length > 0) {
+    const rules = card.ruleHits.map((r) => `${r.rule} (${r.count})`).join(", ");
+    parts.push(`rule hits: [${rules}]`);
+  }
+  return parts.join(", ") + ".";
+}
+
+/**
+ * TurnCardTracker: tracks tool calls per agent turn and builds structured summaries (#86).
+ */
+export class TurnCardTracker {
+  /**
+   * @param {{ maxRetainedTurns?: number }} [options]
+   */
+  constructor(options = {}) {
+    this.maxRetainedTurns = options.maxRetainedTurns || 50;
+    /** @type {Map<string, Map<string | number, TurnCallRecord[]>>} */
+    this._sessions = new Map();
+    /** @type {Map<string, Map<string | number, TurnCard>>} */
+    this._cards = new Map();
+  }
+
+  /**
+   * Records a tool call within a specific session and turn.
+   *
+   * @param {string} sessionId
+   * @param {string | number} turnId
+   * @param {TurnCallRecord} record
+   */
+  recordCall(sessionId, turnId, record) {
+    const sid = String(sessionId || "default");
+    const tid = turnId !== undefined && turnId !== null ? turnId : "active";
+
+    let sessionTurns = this._sessions.get(sid);
+    if (!sessionTurns) {
+      sessionTurns = new Map();
+      this._sessions.set(sid, sessionTurns);
+    }
+
+    let calls = sessionTurns.get(tid);
+    if (!calls) {
+      calls = [];
+      sessionTurns.set(tid, calls);
+    }
+
+    calls.push({
+      tool: record.tool || "unknown",
+      command: record.command || "",
+      snippet: record.snippet || "",
+      verdict: record.verdict || "allow",
+      reason: record.reason || "",
+      rule: record.rule || record.reason || "",
+      durationMs: record.durationMs || 0,
+      timestamp: record.timestamp || Date.now(),
+    });
+
+    // Invalidate cached card for this turn
+    const sessionCards = this._cards.get(sid);
+    if (sessionCards) {
+      sessionCards.delete(tid);
+    }
+  }
+
+  /**
+   * Builds the TurnCard for a specific turn in a session (#86).
+   *
+   * @param {string} sessionId
+   * @param {string | number} turnId
+   * @param {Object} [options]
+   * @param {'en' | 'ru' | 'zh'} [options.lang='en']
+   * @returns {TurnCard}
+   */
+  buildTurnCard(sessionId, turnId, options = {}) {
+    const sid = String(sessionId || "default");
+    const tid = turnId !== undefined && turnId !== null ? turnId : "active";
+    const lang = options.lang || "en";
+
+    let sessionCards = this._cards.get(sid);
+    if (!sessionCards) {
+      sessionCards = new Map();
+      this._cards.set(sid, sessionCards);
+    }
+
+    const cached = sessionCards.get(tid);
+    if (cached) return cached;
+
+    const sessionTurns = this._sessions.get(sid);
+    const calls = (sessionTurns && sessionTurns.get(tid)) || [];
+
+    let totalCalls = calls.length;
+    let allowedCalls = 0;
+    let blockedCalls = 0;
+    let askedCalls = 0;
+    let preemptedCalls = 0;
+    /** @type {Map<string, { count: number, reasons: Set<string> }>} */
+    const ruleHitMap = new Map();
+    /** @type {TurnCallRecord[]} */
+    const blockedDetails = [];
+
+    for (const c of calls) {
+      if (c.verdict === "deny") {
+        blockedCalls++;
+        blockedDetails.push(c);
+      } else if (c.verdict === "ask") {
+        askedCalls++;
+      } else if (c.verdict === "preempted") {
+        preemptedCalls++;
+      } else {
+        allowedCalls++;
+      }
+
+      if (c.rule && c.verdict !== "allow") {
+        let entry = ruleHitMap.get(c.rule);
+        if (!entry) {
+          entry = { count: 0, reasons: new Set() };
+          ruleHitMap.set(c.rule, entry);
+        }
+        entry.count++;
+        if (c.reason) entry.reasons.add(c.reason);
+      }
+    }
+
+    /** @type {RuleHitSummary[]} */
+    const ruleHits = Array.from(ruleHitMap.entries()).map(([rule, data]) => ({
+      rule,
+      count: data.count,
+      reasons: Array.from(data.reasons),
+    }));
+
+    /** @type {'clean' | 'warnings' | 'blocked'} */
+    let status = "clean";
+    if (blockedCalls > 0) {
+      status = "blocked";
+    } else if (askedCalls > 0) {
+      status = "warnings";
+    }
+
+    /** @type {TurnCard} */
+    const card = {
+      sessionId: sid,
+      turnId: tid,
+      timestamp: Date.now(),
+      status,
+      totalCalls,
+      allowedCalls,
+      blockedCalls,
+      askedCalls,
+      preemptedCalls,
+      ruleHits,
+      blockedDetails,
+      summaryText: "",
+    };
+
+    card.summaryText = formatTurnCardSummary(card, lang);
+    sessionCards.set(tid, card);
+    return card;
+  }
+
+  /**
+   * Returns all TurnCards for a session.
+   *
+   * @param {string} sessionId
+   * @returns {TurnCard[]}
+   */
+  getTurnCards(sessionId) {
+    const sid = String(sessionId || "default");
+    const sessionTurns = this._sessions.get(sid);
+    if (!sessionTurns) return [];
+    const list = [];
+    for (const tid of sessionTurns.keys()) {
+      list.push(this.buildTurnCard(sid, tid));
+    }
+    return list;
+  }
+
+  /**
+   * Clears tracking for a given turn.
+   *
+   * @param {string} sessionId
+   * @param {string | number} turnId
+   */
+  clearTurn(sessionId, turnId) {
+    const sid = String(sessionId || "default");
+    const tid = turnId !== undefined && turnId !== null ? turnId : "active";
+    const st = this._sessions.get(sid);
+    if (st) st.delete(tid);
+    const sc = this._cards.get(sid);
+    if (sc) sc.delete(tid);
+  }
+
+  /**
+   * Clears tracking for an entire session.
+   *
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const sid = String(sessionId || "default");
+    this._sessions.delete(sid);
+    this._cards.delete(sid);
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Host-only command safety gate for DeepSeek Harness: blocks recognized dangerous operations and requests DSH approval when a command cannot be inspected.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
     "./package.json": "./package.json",
-    "./cordis.patch.yml": "./cordis.patch.yml"
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./client": "./lib/client.js"
   },
   "files": [
     "lib",
@@ -23,6 +24,14 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-locale"
+      ]
     }
   },
   "license": "MIT",
@@ -57,4 +66,4 @@
   "bin": {
     "dsh-approval-eval": "./bin/eval.mjs"
   }
-}
+}