@goodandready/dsh-approval-gate 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.23
+
+- Tech-debt: Версионирование схемы хранения сессионных вердиктов (`CURRENT_SCHEMA_VERSION = 3` в `lib/ledger.js`) с полной обратной совместимостью и бесшовной миграцией исторических форматов v1/v2/v3 (`migrateVerdictRecord`) (Refs: #73).
+- Feature: Поддержка двухтрековых маркеров (`Dual-Track Markers` в `lib/dualtrack.js`: `TRACK_TYPES.INTERNAL` vs `TRACK_TYPES.EXTERNAL`) для четкого разделения скрытых служебных шагов агента и пользовательских мутаций проекта (Refs: #92).
+- Feature: Сессионное переключение режимов гейта (`auto-approval` vs `manual` / `strict` / `hybrid` в `lib/session-modes.js`) на основе активного пресета сессии (`resolveSessionGateMode`, `applySessionModePolicy`, `SessionModeRegistry`) (Refs: #61).
+- Feature: Сбор доказательного досье (`Evidence Dossier` в `lib/dossier.js`: инструмент, diff, терминал, исходный промпт юзера) с безопасной санитизацией чувствительных токенов и защитой от переполнения памяти (Refs: #64).
+- Security: Детекция отклонения от траектории задачи (`Trajectory Drift Detection` в `lib/drift.js`: `TrajectoryTracker`) с перехватом несанкционированного сканирования сети, поиска учетных данных и системного зондирования вне рамок цели сессии (Refs: #68).
+
 ## 0.1.22
 
 - Feature: Наследование разрешений в иерархии субагентов через `parentSession lineage authority` (`LineageManager` в `lib/lineage.js`) с безопасным обходом дерева предков и защитой от циклических ссылок (Refs: #98).

package/lib/dossier.js

@@ -0,0 +1,122 @@
+// lib/dossier.js
+// Evidence Dossier Gathering (#64).
+// Assembles compact evidence packets for tool calls, diffs, terminal output, and user prompts.
+
+export const MAX_PROMPT_CHARS = 200;
+export const MAX_DIFF_CHARS = 400;
+export const MAX_OUTPUT_CHARS = 300;
+
+/**
+ * Truncates a string safely with ellipsis.
+ * @param {any} str
+ * @param {number} max
+ * @returns {string}
+ */
+function truncate(str, max) {
+  if (typeof str !== "string") return "";
+  const trimmed = str.trim();
+  if (trimmed.length <= max) return trimmed;
+  return trimmed.slice(0, max - 3) + "...";
+}
+
+/**
+ * Extracts a concise summary of arguments without sensitive credentials.
+ * @param {Record<string, any>} [args]
+ * @returns {Record<string, any>}
+ */
+function sanitizeArgs(args) {
+  if (!args || typeof args !== "object") return {};
+  const summary = {};
+  for (const [k, v] of Object.entries(args)) {
+    if (k.toLowerCase().includes("token") || k.toLowerCase().includes("secret") || k.toLowerCase().includes("password")) {
+      summary[k] = "[REDACTED]";
+    } else if (typeof v === "string") {
+      summary[k] = v.length > 80 ? v.slice(0, 77) + "..." : v;
+    } else if (typeof v === "number" || typeof v === "boolean") {
+      summary[k] = v;
+    } else if (Array.isArray(v)) {
+      summary[k] = `Array(${v.length})`;
+    } else if (typeof v === "object" && v !== null) {
+      summary[k] = `Object(${Object.keys(v).length})`;
+    }
+  }
+  return summary;
+}
+
+/**
+ * Builds an evidence dossier object for an execution (#64).
+ *
+ * @param {Object} params
+ * @param {Record<string, any>} [params.execution]
+ * @param {Record<string, any>} [params.decision]
+ * @param {Record<string, any>} [params.context]
+ * @param {string} [params.toolName]
+ * @param {string} [params.command]
+ * @param {Record<string, any>} [params.args]
+ * @param {string} [params.userPrompt]
+ * @param {string} [params.diffSnippet]
+ * @param {string} [params.terminalOutput]
+ * @param {string} [params.track]
+ * @param {string} [params.riskBucket]
+ * @returns {{
+ *   toolName: string,
+ *   command: string,
+ *   argsSummary: Record<string, any>,
+ *   userPrompt: string,
+ *   diffSnippet: string,
+ *   terminalOutput: string,
+ *   track: string,
+ *   riskBucket: string,
+ *   timestamp: number
+ * }}
+ */
+export function buildEvidenceDossier({
+  execution = {},
+  decision = {},
+  context = {},
+  toolName,
+  command,
+  args,
+  userPrompt,
+  diffSnippet,
+  terminalOutput,
+  track,
+  riskBucket,
+} = {}) {
+  const tool = String(toolName || execution?.name || execution?.toolName || "").trim();
+  const cmd = String(command || execution?.arguments?.command || execution?.command || "").trim();
+  const rawArgs = args || execution?.arguments || {};
+  const prompt = userPrompt || context?.userPrompt || context?.prompt || context?.goal || "";
+  const diff = diffSnippet || context?.diffSnippet || context?.diff || rawArgs?.diff || "";
+  const output = terminalOutput || context?.terminalOutput || context?.output || "";
+  const assignedTrack = track || decision?.track || context?.track || "external";
+  const assignedRisk = riskBucket || decision?.riskBucket || context?.riskBucket || "medium";
+
+  return {
+    toolName: tool,
+    command: cmd,
+    argsSummary: sanitizeArgs(rawArgs),
+    userPrompt: truncate(prompt, MAX_PROMPT_CHARS),
+    diffSnippet: truncate(diff, MAX_DIFF_CHARS),
+    terminalOutput: truncate(output, MAX_OUTPUT_CHARS),
+    track: assignedTrack,
+    riskBucket: assignedRisk,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Formats a single-line summary of an evidence dossier.
+ * @param {ReturnType<typeof buildEvidenceDossier>} dossier
+ * @returns {string}
+ */
+export function formatDossierSummary(dossier) {
+  if (!dossier) return "[Dossier: empty]";
+  const parts = [];
+  if (dossier.toolName) parts.push(`tool=${dossier.toolName}`);
+  if (dossier.track) parts.push(`track=${dossier.track}`);
+  if (dossier.riskBucket) parts.push(`risk=${dossier.riskBucket}`);
+  if (dossier.userPrompt) parts.push(`prompt="${dossier.userPrompt.slice(0, 30)}"`);
+  if (dossier.diffSnippet) parts.push(`diff="${dossier.diffSnippet.slice(0, 30)}"`);
+  return `[Dossier: ${parts.join(" ")}]`;
+}

package/lib/drift.js

@@ -0,0 +1,214 @@
+// lib/drift.js
+// Trajectory Drift Detection for dsh-approval-gate (#68).
+// Detects when agent deviates from session goal into port scanning, credential hunting, or out-of-scope probing.
+
+export const DRIFT_CATEGORIES = Object.freeze({
+  NETWORK_RECON: "network-recon",
+  CREDENTIAL_HUNT: "credential-hunt",
+  SYSTEM_PROBING: "system-probing",
+  OUT_OF_SCOPE: "out-of-scope",
+});
+
+const NETWORK_RECON_PATTERNS = [
+  /\b(?:nmap|masscan|zmap)\b/i,
+  /\bnetstat\s+-[antulp]+/i,
+  /\bss\s+-[antulp]+/i,
+  /\barp\s+-(?:a|n)\b/i,
+  /\b(?:tcpdump|tshark|wireshark)\b/i,
+  /\b(?:traceroute|tracepath)\b/i,
+];
+
+const NETWORK_GOAL_KEYWORDS = [
+  "network", "port", "scan", "packet", "interface", "traceroute", "traffic", "firewall", "diagnose"
+];
+
+const CREDENTIAL_HUNT_PATTERNS = [
+  /[\\/]\.ssh[\\/](?:id_rsa|id_ed25519|id_ecdsa|authorized_keys|known_hosts)/i,
+  /[\\/]\.aws[\\/]credentials/i,
+  /\/etc\/(?:shadow|gshadow|sudoers)/i,
+  /\bcat\s+[^\n]*(?:id_rsa|id_ed25519|\.ssh|\.aws\/credentials)/i,
+  /\bfind\s+[^\n]*-(?:name|iname)\s+['"]?\*?\.(?:pem|key|pfx|pkcs12)['"]?/i,
+];
+
+const CREDENTIAL_GOAL_KEYWORDS = [
+  "ssh", "key", "credential", "auth", "secret", "password", "token", "certificate", "cert", "deploy key"
+];
+
+const SYSTEM_PROBE_PATTERNS = [
+  /\bfind\s+\/(?:\s|$)[^\n]*-perm\s+-[0-9]+/i,
+  /\/proc\/(?:kallsyms|keys|sched_debug)/i,
+  /\b(?:linpeas|winpeas|chkrootkit|rkhunter)\b/i,
+  /\bls\s+-[la]*\s+\/root\b/i,
+];
+
+const SYSTEM_PROBE_GOAL_KEYWORDS = [
+  "kernel", "root", "audit", "security audit", "permission audit", "probe", "privilege"
+];
+
+/**
+ * Checks if text contains any of the given keywords.
+ * @param {string} text
+ * @param {string[]} keywords
+ * @returns {boolean}
+ */
+function containsKeyword(text, keywords) {
+  if (!text || typeof text !== "string") return false;
+  const lower = text.toLowerCase();
+  return keywords.some((kw) => lower.includes(kw));
+}
+
+/**
+ * Detects trajectory drift for an execution against session goal (#68).
+ *
+ * @param {string} [sessionId]
+ * @param {Record<string, any>} [execution]
+ * @param {Record<string, any>} [context]
+ * @param {{ goal?: string, allowedScopes?: string[] }} [goalInfo]
+ * @returns {{
+ *   hasDrift: boolean,
+ *   driftScore: number,
+ *   driftWarning: boolean,
+ *   category?: string,
+ *   reason?: string,
+ *   detail?: string
+ * }}
+ */
+export function detectTrajectoryDrift(sessionId, execution = {}, context = {}, goalInfo = {}) {
+  const goal = String(
+    goalInfo?.goal ||
+    context?.goal ||
+    context?.userPrompt ||
+    context?.prompt ||
+    ""
+  ).trim();
+
+  const command = String(
+    execution?.arguments?.command ||
+    execution?.command ||
+    ""
+  ).trim();
+
+  const targetPath = String(
+    execution?.arguments?.TargetFile ||
+    execution?.arguments?.targetPath ||
+    execution?.arguments?.path ||
+    execution?.arguments?.file ||
+    ""
+  ).trim();
+
+  const textToScan = `${command} ${targetPath}`.trim();
+  if (!textToScan) {
+    return { hasDrift: false, driftScore: 0, driftWarning: false };
+  }
+
+  // 1. Network reconnaissance check
+  if (NETWORK_RECON_PATTERNS.some((p) => p.test(textToScan))) {
+    if (!containsKeyword(goal, NETWORK_GOAL_KEYWORDS)) {
+      return {
+        hasDrift: true,
+        driftScore: 0.85,
+        driftWarning: true,
+        category: DRIFT_CATEGORIES.NETWORK_RECON,
+        reason: "trajectory-drift-detected",
+        detail: `Operation matches network reconnaissance without matching session goal (${goal.slice(0, 50) || "none"})`,
+      };
+    }
+  }
+
+  // 2. Credential hunting check
+  if (CREDENTIAL_HUNT_PATTERNS.some((p) => p.test(textToScan))) {
+    if (!containsKeyword(goal, CREDENTIAL_GOAL_KEYWORDS)) {
+      return {
+        hasDrift: true,
+        driftScore: 0.95,
+        driftWarning: true,
+        category: DRIFT_CATEGORIES.CREDENTIAL_HUNT,
+        reason: "trajectory-drift-detected",
+        detail: `Operation matches credential inspection without matching session goal (${goal.slice(0, 50) || "none"})`,
+      };
+    }
+  }
+
+  // 3. System probing check
+  if (SYSTEM_PROBE_PATTERNS.some((p) => p.test(textToScan))) {
+    if (!containsKeyword(goal, SYSTEM_PROBE_GOAL_KEYWORDS)) {
+      return {
+        hasDrift: true,
+        driftScore: 0.9,
+        driftWarning: true,
+        category: DRIFT_CATEGORIES.SYSTEM_PROBING,
+        reason: "trajectory-drift-detected",
+        detail: `Operation matches system probing/privilege reconnaissance outside session goal`,
+      };
+    }
+  }
+
+  // 4. Allowed scopes check
+  const allowedScopes = goalInfo?.allowedScopes || context?.allowedScopes;
+  if (Array.isArray(allowedScopes) && allowedScopes.length > 0 && targetPath) {
+    const normTarget = targetPath.replace(/\\/g, "/").toLowerCase();
+    const isWithinScope = allowedScopes.some((scope) => {
+      const normScope = String(scope).replace(/\\/g, "/").toLowerCase();
+      return normTarget.startsWith(normScope);
+    });
+    if (!isWithinScope && (normTarget.startsWith("/etc") || normTarget.startsWith("/root") || normTarget.includes("/.ssh"))) {
+      return {
+        hasDrift: true,
+        driftScore: 0.8,
+        driftWarning: true,
+        category: DRIFT_CATEGORIES.OUT_OF_SCOPE,
+        reason: "trajectory-drift-detected",
+        detail: `Access to ${targetPath} is outside declared session scopes`,
+      };
+    }
+  }
+
+  return { hasDrift: false, driftScore: 0, driftWarning: false };
+}
+
+/**
+ * Trajectory Tracker for sessions (#68).
+ */
+export class TrajectoryTracker {
+  constructor() {
+    /** @type {Map<string, { goal: string, allowedScopes: string[], stepCount: number }>} */
+    this.sessions = new Map();
+  }
+
+  setGoal(sessionId, goal, allowedScopes = []) {
+    const key = sessionId || "default";
+    this.sessions.set(key, {
+      goal: String(goal || ""),
+      allowedScopes: Array.isArray(allowedScopes) ? [...allowedScopes] : [],
+      stepCount: 0,
+    });
+  }
+
+  getGoal(sessionId) {
+    const key = sessionId || "default";
+    return this.sessions.get(key) || null;
+  }
+
+  recordStep(sessionId) {
+    const key = sessionId || "default";
+    const entry = this.sessions.get(key);
+    if (entry) {
+      entry.stepCount += 1;
+    }
+  }
+
+  detect(sessionId, execution, context = {}) {
+    const key = sessionId || "default";
+    const goalInfo = this.sessions.get(key) || {};
+    return detectTrajectoryDrift(key, execution, context, goalInfo);
+  }
+
+  clearSession(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  reset() {
+    this.sessions.clear();
+  }
+}

package/lib/dualtrack.js

@@ -0,0 +1,101 @@
+// lib/dualtrack.js
+// Dual-Track Markers for separating internal agent chores from external project mutations (#92).
+// Provides classification and predicates to differentiate internal sandbox actions from project changes.
+
+export const TRACK_TYPES = Object.freeze({
+  INTERNAL: "internal",
+  EXTERNAL: "external",
+});
+
+const INTERNAL_TOOL_NAMES = new Set([
+  "read_url_content",
+  "search_web",
+  "web_search",
+  "view_file",
+  "read_file",
+  "view",
+  "inspect_file",
+]);
+
+const INTERNAL_PATH_PATTERNS = [
+  /[\\/]\.dsh[\\/](?:tmp|trash|cache|sessions)[\\/]/i,
+  /[\\/]\.gemini[\\/]/i,
+  /[\\/]scratch[\\/]/i,
+  /[\\/]\.cache[\\/]/i,
+  /[\\/]tmp[\\/]/i,
+];
+
+const INTERNAL_COMMAND_REGEX = /^(?:git\s+(?:status|diff|rev-parse|branch|log)|npm\s+(?:view|help)|node\s+--version|echo\b|cat\s+[^\n]*\.(?:dsh|tmp|cache)|ls\s+-[la]*\s*(?:\.|$))/i;
+
+/**
+ * Classifies an operation into internal or external track (#92).
+ *
+ * @param {string} [toolName]
+ * @param {string} [command]
+ * @param {Record<string, any>} [args]
+ * @param {Record<string, any>} [context]
+ * @returns {'internal' | 'external'}
+ */
+export function classifyTrack(toolName, command, args = {}, context = {}) {
+  // Explicit overrides in context or args
+  if (context.track === TRACK_TYPES.INTERNAL || args?.track === TRACK_TYPES.INTERNAL || context.internal === true || args?.internal === true) {
+    return TRACK_TYPES.INTERNAL;
+  }
+  if (context.track === TRACK_TYPES.EXTERNAL || args?.track === TRACK_TYPES.EXTERNAL || context.external === true || args?.external === true) {
+    return TRACK_TYPES.EXTERNAL;
+  }
+
+  const tool = String(toolName || "").trim();
+  const cmd = String(command || (args && args.command) || "").trim();
+  const target = String((args && (args.TargetFile || args.targetPath || args.path || args.file)) || "").trim();
+
+  // Operations targeting internal scratch/temp paths are internal
+  if (target && INTERNAL_PATH_PATTERNS.some((p) => p.test(target))) {
+    return TRACK_TYPES.INTERNAL;
+  }
+
+  // Pure read-only knowledge tools are internal
+  if (INTERNAL_TOOL_NAMES.has(tool)) {
+    return TRACK_TYPES.INTERNAL;
+  }
+
+  // File mutations on project files are external
+  if (tool === "write_to_file" || tool === "replace_file_content" || tool === "create_file") {
+    return TRACK_TYPES.EXTERNAL;
+  }
+
+  // Shell command classification
+  if (cmd) {
+    if (INTERNAL_PATH_PATTERNS.some((p) => p.test(cmd))) {
+      return TRACK_TYPES.INTERNAL;
+    }
+    if (INTERNAL_COMMAND_REGEX.test(cmd)) {
+      return TRACK_TYPES.INTERNAL;
+    }
+  }
+
+  // Default for non-read commands or mutations
+  return TRACK_TYPES.EXTERNAL;
+}
+
+/**
+ * Checks whether track or decision is marked as internal.
+ * @param {string | { track?: string }} [trackOrDecision]
+ * @returns {boolean}
+ */
+export function isInternalTrack(trackOrDecision) {
+  if (!trackOrDecision) return false;
+  if (typeof trackOrDecision === "string") return trackOrDecision === TRACK_TYPES.INTERNAL;
+  return trackOrDecision.track === TRACK_TYPES.INTERNAL;
+}
+
+/**
+ * Checks whether track or decision is marked as external.
+ * @param {string | { track?: string }} [trackOrDecision]
+ * @returns {boolean}
+ */
+export function isExternalTrack(trackOrDecision) {
+  if (!trackOrDecision) return false;
+  if (typeof trackOrDecision === "string") return trackOrDecision === TRACK_TYPES.EXTERNAL;
+  return trackOrDecision.track === TRACK_TYPES.EXTERNAL;
+}

package/lib/engine.js

@@ -24,6 +24,10 @@ import { classifyMeasureKind } from "./measure-kinds.js";
 import { SnapshotManager } from "./snapshots.js";
 import { LineageManager } from "./lineage.js";
 import { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification } from "./escalation.js";
+import { classifyTrack } from "./dualtrack.js";
+import { applySessionModePolicy, SessionModeRegistry } from "./session-modes.js";
+import { buildEvidenceDossier } from "./dossier.js";
+import { TrajectoryTracker } from "./drift.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -39,29 +43,12 @@ export function isCriticalOperation(toolName, command, execution) {
   const tool = String(toolName || "").trim();
   if (!cmd && !tool) return false;
 
-  // 1. Root and privilege escalation
-  if (/^(sudo|su|doas)\b/i.test(cmd)) return true;
-  if (/\b(chmod\s+(-[a-zA-Z]*\s+)?777|chown\s+(-[a-zA-Z]*\s+)?root)\b/i.test(cmd)) return true;
-
-  // 2. Recursive or bulk destructive deletion
-  if (/\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+|--recursive\s+)/i.test(cmd)) return true;
-  if (/\b(shred|wipefs)\b/i.test(cmd)) return true;
-
-  // 3. Sensitive credentials and SSH access
+  if (/^(sudo|su|doas)\b/i.test(cmd) || /\b(chmod\s+(-[a-zA-Z]*\s+)?777|chown\s+(-[a-zA-Z]*\s+)?root)\b/i.test(cmd)) return true;
+  if (/\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+|--recursive\s+)/i.test(cmd) || /\b(shred|wipefs)\b/i.test(cmd)) return true;
   if (/(\.ssh\/(id_|authorized_keys|known_hosts)|\.gnupg\/|\/etc\/shadow)/i.test(cmd)) return true;
-
-  // 4. Raw disk and filesystem manipulation
-  if (/\b(mkfs|fdisk|parted)\b/i.test(cmd)) return true;
-  if (/\bdd\s+.*of=\/dev\/(sd[a-z]|nvme|vd[a-z]|hd[a-z]|loop)/i.test(cmd)) return true;
-
-  // 5. Remote shell piping and reverse shells
-  if (/curl\s+.*\|\s*(bash|sh|python|perl)/i.test(cmd)) return true;
-  if (/\b(nc|ncat|netcat)\s+.*-e\s+/i.test(cmd)) return true;
-  if (/>&\s*\/dev\/tcp\//i.test(cmd)) return true;
-
-  // 6. System halts and service shutdowns
-  if (/\b(shutdown|reboot|poweroff|halt|init\s+0)\b/i.test(cmd)) return true;
-  if (/systemctl\s+(stop|disable|mask)\s+(sshd|systemd|ufw|iptables)/i.test(cmd)) return true;
+  if (/\b(mkfs|fdisk|parted)\b/i.test(cmd) || /\bdd\s+.*of=\/dev\/(sd[a-z]|nvme|vd[a-z]|hd[a-z]|loop)/i.test(cmd)) return true;
+  if (/curl\s+.*\|\s*(bash|sh|python|perl)/i.test(cmd) || /\b(nc|ncat|netcat)\s+.*-e\s+/i.test(cmd) || />&\s*\/dev\/tcp\//i.test(cmd)) return true;
+  if (/\b(shutdown|reboot|poweroff|halt|init\s+0)\b/i.test(cmd) || /systemctl\s+(stop|disable|mask)\s+(sshd|systemd|ufw|iptables)/i.test(cmd)) return true;
 
   // 7. Protected file writes via tools
   if (tool === "write_to_file" || tool === "edit" || tool === "replace_file_content" || tool === "str_replace_editor") {
@@ -104,6 +91,8 @@ export class SecurityEngine {
     this.lineage = options.lineage !== undefined ? options.lineage : new LineageManager();
     this.enableRedundantSandboxRecovery = options.enableRedundantSandboxRecovery !== false;
     this.requireJustification = options.requireJustification === true;
+    this.sessionModes = options.sessionModes || new SessionModeRegistry(options.defaultSessionMode);
+    this.trajectoryTracker = options.trajectoryTracker !== undefined ? options.trajectoryTracker : new TrajectoryTracker();
   }
 
   /**
@@ -121,12 +110,7 @@ export class SecurityEngine {
 
       // Check Retry Exhaustion guard (#96)
       if (this.retryGuard && this.retryGuard.isExhausted(sessionId)) {
-        const exhHit = {
-          deny: true,
-          reason: "retry-exhaustion",
-          detail: "Retry exhaustion: consecutive blocked attempts exceeded threshold",
-          snippet: command || toolName,
-        };
+        const exhHit = { deny: true, reason: "retry-exhaustion", detail: "Retry exhaustion: consecutive blocked attempts exceeded threshold", snippet: command || toolName };
         const exhDecision = { verdict: "deny", stage: "P0", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
         if (this.ledger) this.ledger.record(sessionId, "exhaustion", { reason: "retry-exhaustion", tool: toolName });
         if (this.counters) this.counters.record(exhDecision, execution);
@@ -162,6 +146,10 @@ export class SecurityEngine {
 
       let decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
       this._enrichDecision(decision, execution, context);
+      if (this.sessionModes) {
+        const mode = this.sessionModes.getMode(sessionId, context?.preset || context?.sessionMode);
+        decision = applySessionModePolicy(mode, decision, { track: decision.track, riskBucket: decision.riskBucket, lockedAsk: decision.lockedAsk });
+      }
 
       // Post-decision hooks: ledger, retryGuard, cache
       if (decision.verdict === "deny") {
@@ -413,19 +401,8 @@ export class SecurityEngine {
     // If Circuit Breaker is tripped, force P4 Human Ask
     if (this.breaker.isTripped(sessionId)) {
       if (this.ledger) this.ledger.record(sessionId, "breaker", { reason: "circuit-breaker-tripped", tool: toolName });
-      const breakerHit = {
-        ask: true,
-        reason: "circuit-breaker-tripped",
-        detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required.",
-        snippet: command || toolName,
-      };
-      const res = {
-        verdict: "ask",
-        stage: "P4",
-        reason: "circuit-breaker-tripped",
-        detail: breakerHit.detail,
-        hit: breakerHit,
-      };
+      const breakerHit = { ask: true, reason: "circuit-breaker-tripped", detail: "Circuit breaker tripped due to repeated security denials. Manual confirmation required.", snippet: command || toolName };
+      const res = { verdict: "ask", stage: "P4", reason: "circuit-breaker-tripped", detail: breakerHit.detail, hit: breakerHit };
       this._applyLockedAskIfCritical(res, toolName, command, execution);
       return res;
     }
@@ -446,6 +423,17 @@ export class SecurityEngine {
       return res;
     }
 
+    // Trajectory Drift (#68)
+    if (this.trajectoryTracker) {
+      const drift = this.trajectoryTracker.detect(sessionId, execution, context);
+      if (drift && drift.hasDrift) {
+        const driftHit = { ask: true, reason: drift.reason, detail: drift.detail, snippet: command || toolName };
+        const res = { verdict: "ask", stage: "P4", reason: drift.reason, detail: drift.detail, drift, hit: driftHit };
+        this._applyLockedAskIfCritical(res, toolName, command, execution);
+        return res;
+      }
+    }
+
     // P2: Static Rules / Safe Allow (Bands Engine)
     if (bandVerdict === "allow" && !this.requireJustification) {
       this.breaker.resetConsecutive(sessionId);
@@ -556,16 +544,16 @@ export class SecurityEngine {
    */
   _enrichDecision(decision, execution, context) {
     if (!decision) return decision;
+    const command = execution && execution.arguments && execution.arguments.command;
+    if (!decision.track) decision.track = classifyTrack(execution?.name, command, execution?.arguments, context);
+    if (!decision.dossier) decision.dossier = buildEvidenceDossier({ execution, decision, context, toolName: execution?.name, command });
     if (!decision.riskBucket) decision.riskBucket = categorizeRiskBucket(execution, context);
     if (!decision.riskTags || !Array.isArray(decision.riskTags)) decision.riskTags = extractRiskTags(execution, context);
     if (!decision.measureKind) decision.measureKind = classifyMeasureKind(execution, context);
-    const command = execution && execution.arguments && execution.arguments.command;
-    if (command && isRmCommand(command)) {
-      decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
-    }
-    const callId = context?.callId || execution?.callId || execution?.id || context?.execution?.id || null;
-    const agentId = context?.agentId || context?.agent?.id || context?.session?.agentId || execution?.agentId || null;
-    const subagentId = context?.subagentId || context?.session?.subagentId || execution?.subagentId || null;
+    if (command && isRmCommand(command)) decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
+    const callId = context?.callId || execution?.callId || execution?.id || context?.execution?.id;
+    const agentId = context?.agentId || context?.agent?.id || context?.session?.agentId || execution?.agentId;
+    const subagentId = context?.subagentId || context?.session?.subagentId || execution?.subagentId;
     if (callId) decision.callId = callId;
     if (agentId) decision.agentId = agentId;
     if (subagentId) decision.subagentId = subagentId;
@@ -583,6 +571,9 @@ export class SecurityEngine {
   clearAllSnapshots() { return this.snapshotManager ? this.snapshotManager.clearAllSnapshots() : { cleared: 0 }; }
   getLineage(sessionId) { return this.lineage ? this.lineage.getLineage(sessionId) : [sessionId]; }
   registerLineage(child, parent, root) { return this.lineage ? this.lineage.registerLineage(child, parent, root) : false; }
+  setSessionGoal(sessionId, goal, scopes) { if (this.trajectoryTracker) this.trajectoryTracker.setGoal(sessionId, goal, scopes); }
+  getSessionGoal(sessionId) { return this.trajectoryTracker ? this.trajectoryTracker.getGoal(sessionId) : null; }
+  setSessionMode(sessionId, mode) { return this.sessionModes ? this.sessionModes.setMode(sessionId, mode) : null; }
+  getSessionMode(sessionId, preset) { return this.sessionModes ? this.sessionModes.getMode(sessionId, preset) : null; }
 }
 
-

package/lib/index.js

@@ -532,12 +532,7 @@ export function apply(ctx, config) {
 
 export { SecurityEngine } from "./engine.js";
 export { BandsEngine } from "./bands.js";
-export {
-  CircuitBreaker,
-  CIRCUIT_STATE_ACTIVE,
-  CIRCUIT_STATE_TRIPPED,
-  CIRCUIT_STATE_RESUMED,
-} from "./breaker.js";
+export { CircuitBreaker, CIRCUIT_STATE_ACTIVE, CIRCUIT_STATE_TRIPPED, CIRCUIT_STATE_RESUMED } from "./breaker.js";
 export { SessionGrantStore, DEFAULT_GRANT_TTL_MS, DEFAULT_GRANT_MAX_USES, matchGrantCriteria } from "./grants.js";
 export { canonicalizeCall, canonicalString, hashCall, sortKeys } from "./canonical.js";
 export { expandHome, resolveSafePath, isPathTraversal, canonicalizeFsPath } from "./paths.js";
@@ -550,7 +545,7 @@ export { isLoopbackHost, isLoopbackUrl, isLoopbackCommand } from "./loopback.js"
 export { computeFingerprint, computeFingerprintHash, normalizeCommandString } from "./fingerprint.js";
 export { VerdictCache, DEFAULT_CACHE_MAX_SIZE, DEFAULT_CACHE_TTL_MS } from "./cache.js";
 export { RetryExhaustionGuard, DEFAULT_MAX_RETRY_ATTEMPTS } from "./retry-exhaustion.js";
-export { QualityLedger, MAX_LEDGER_EVENTS_PER_SESSION } from "./ledger.js";
+export { QualityLedger, MAX_LEDGER_EVENTS_PER_SESSION, CURRENT_SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, migrateVerdictRecord } from "./ledger.js";
 export { AuditLogger, DEFAULT_AUDIT_LOG_RELATIVE, DEFAULT_MAX_AUDIT_BYTES, DEFAULT_MAX_AUDIT_LINES, DEFAULT_RETAIN_LINES, auditRotateContent } from "./audit-log.js";
 export { BlockCounters, categorizeReason } from "./counters.js";
 export { isCriticalOperation } from "./engine.js";
@@ -575,6 +570,7 @@ export { MEASURE_KINDS, classifyMeasureKind, isSystemLevelExecution, isWorkspace
 export { LineageManager } from "./lineage.js";
 export { generateAgentGuidance, injectAgentGuidance, extractGuidance, GUIDANCE_MARKER } from "./guidance.js";
 export { isRedundantSandboxRequest, buildRedundantSandboxRemediation, checkEscalationJustification, REDUNDANT_SANDBOX_REASON, MISSING_JUSTIFICATION_REASON, INSUFFICIENT_JUSTIFICATION_REASON } from "./escalation.js";
-
-
-
+export { TRACK_TYPES, classifyTrack, isInternalTrack, isExternalTrack } from "./dualtrack.js";
+export { GATE_MODES, PRESET_MODE_MAP, resolveSessionGateMode, applySessionModePolicy, SessionModeRegistry } from "./session-modes.js";
+export { buildEvidenceDossier, formatDossierSummary, MAX_PROMPT_CHARS, MAX_DIFF_CHARS, MAX_OUTPUT_CHARS } from "./dossier.js";
+export { DRIFT_CATEGORIES, detectTrajectoryDrift, TrajectoryTracker } from "./drift.js";

package/lib/ledger.js

@@ -1,164 +1,264 @@
-// 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();
-  }
-}
+// lib/ledger.js
+// Quality and Anomaly Ledger for dsh-approval-gate (#88, #73).
+// Tracks session health, consecutive denials, and execution anomalies with schema versioning.
+
+export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
+
+export const CURRENT_SCHEMA_VERSION = 3;
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([1, 2, 3]);
+
+/**
+ * Migrates a verdict record across schema versions (v1 -> v2 -> v3) (#73).
+ * - v1: { id, verdict, ruleId, timestamp, riskBucket }
+ * - v2: + { reviewDecision, bandVerdict, mitigation, auditSummary }
+ * - v3: + { track, dossier, driftScore, driftWarning, schema_version: 3 }
+ *
+ * @param {Record<string, any>} record
+ * @param {number} [targetVersion=CURRENT_SCHEMA_VERSION]
+ * @returns {Record<string, any>}
+ */
+export function migrateVerdictRecord(record, targetVersion = CURRENT_SCHEMA_VERSION) {
+  if (!record || typeof record !== "object") return record;
+
+  let currentVersion = record.schema_version;
+  if (!currentVersion) {
+    // Infer version from fields
+    if (record.reviewDecision !== undefined || record.bandVerdict !== undefined) {
+      currentVersion = 2;
+    } else {
+      currentVersion = 1;
+    }
+  }
+
+  let migrated = { ...record };
+
+  // v1 -> v2 migration
+  if (currentVersion < 2 && targetVersion >= 2) {
+    migrated.reviewDecision = migrated.reviewDecision || migrated.verdict || "allow";
+    migrated.bandVerdict = migrated.bandVerdict || migrated.verdict || "allow";
+    migrated.mitigation = migrated.mitigation || null;
+    migrated.auditSummary = migrated.auditSummary || null;
+    migrated.schema_version = 2;
+    currentVersion = 2;
+  }
+
+  // v2 -> v3 migration
+  if (currentVersion < 3 && targetVersion >= 3) {
+    migrated.track = migrated.track || "external";
+    migrated.dossier = migrated.dossier || null;
+    migrated.driftScore = typeof migrated.driftScore === "number" ? migrated.driftScore : 0;
+    migrated.driftWarning = Boolean(migrated.driftWarning);
+    migrated.schema_version = 3;
+    currentVersion = 3;
+  }
+
+  migrated.schema_version = currentVersion;
+  return migrated;
+}
+
+/**
+ * @typedef {Object} LedgerEvent
+ * @property {number} timestamp
+ * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+ * @property {string} reason
+ * @property {string} [detail]
+ * @property {string} [tool]
+ * @property {number} [schema_version]
+ */
+
+/**
+ * @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, track?: string, dossier?: any }} [details]
+   */
+  record(sessionId, type, details = {}) {
+    const ledger = this._getOrCreate(sessionId);
+    const now = Date.now();
+
+    const rawEvent = {
+      timestamp: now,
+      type,
+      reason: details.reason || "",
+      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
+      tool: details.tool || "",
+      track: details.track,
+      dossier: details.dossier,
+      schema_version: CURRENT_SCHEMA_VERSION,
+    };
+
+    const event = migrateVerdictRecord(rawEvent, CURRENT_SCHEMA_VERSION);
+
+    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 })),
+    };
+  }
+
+  /**
+   * Serializes session ledger state with current schema version (#73).
+   * @param {string} sessionId
+   * @returns {Record<string, any>}
+   */
+  serializeSession(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    return {
+      schema_version: CURRENT_SCHEMA_VERSION,
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      breakerTripped: ledger.breakerTripped,
+      retryExhausted: ledger.retryExhausted,
+      recentEvents: ledger.recentEvents.map((e) => migrateVerdictRecord(e, CURRENT_SCHEMA_VERSION)),
+    };
+  }
+
+  /**
+   * Restores session ledger state from serialized data with automatic migration (#73).
+   * @param {Record<string, any>} data
+   */
+  deserializeSession(data) {
+    if (!data || !data.sessionId) return;
+    const ledger = this._getOrCreate(data.sessionId);
+    ledger.totalDecisions = data.totalDecisions || 0;
+    ledger.allowedCount = data.allowedCount || 0;
+    ledger.deniedCount = data.deniedCount || 0;
+    ledger.askCount = data.askCount || 0;
+    ledger.anomalyCount = data.anomalyCount || 0;
+    ledger.consecutiveDenies = data.consecutiveDenies || 0;
+    ledger.breakerTripped = Boolean(data.breakerTripped);
+    ledger.retryExhausted = Boolean(data.retryExhausted);
+    ledger.recentEvents = Array.isArray(data.recentEvents)
+      ? data.recentEvents.map((e) => migrateVerdictRecord(e, CURRENT_SCHEMA_VERSION))
+      : [];
+  }
+
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}

package/lib/session-modes.js

@@ -0,0 +1,146 @@
+// lib/session-modes.js
+// Session-level Gate Mode Switching (#61).
+// Allows per-session mode switching between auto-approval, hybrid, manual, and strict modes.
+
+export const GATE_MODES = Object.freeze({
+  AUTO: "auto-approval",
+  MANUAL: "manual",
+  HYBRID: "hybrid",
+  STRICT: "strict",
+});
+
+export const PRESET_MODE_MAP = Object.freeze({
+  sandbox: GATE_MODES.AUTO,
+  test: GATE_MODES.AUTO,
+  auto: GATE_MODES.AUTO,
+  "auto-approval": GATE_MODES.AUTO,
+  prod: GATE_MODES.STRICT,
+  production: GATE_MODES.STRICT,
+  strict: GATE_MODES.STRICT,
+  manual: GATE_MODES.MANUAL,
+  dev: GATE_MODES.HYBRID,
+  development: GATE_MODES.HYBRID,
+  hybrid: GATE_MODES.HYBRID,
+  standard: GATE_MODES.HYBRID,
+});
+
+/**
+ * Resolves active gate mode for a session based on presets, context, or defaults.
+ *
+ * @param {string} [sessionId]
+ * @param {string} [sessionPreset]
+ * @param {Record<string, any>} [options]
+ * @returns {string}
+ */
+export function resolveSessionGateMode(sessionId, sessionPreset, options = {}) {
+  // 1. Explicit mode in options or context
+  if (options.mode && Object.values(GATE_MODES).includes(options.mode)) {
+    return options.mode;
+  }
+  if (options.sessionMode && Object.values(GATE_MODES).includes(options.sessionMode)) {
+    return options.sessionMode;
+  }
+
+  // 2. Preset mapping
+  const presetKey = String(sessionPreset || options.preset || "").toLowerCase().trim();
+  if (presetKey && PRESET_MODE_MAP[presetKey]) {
+    return PRESET_MODE_MAP[presetKey];
+  }
+
+  // 3. Fallback default
+  return options.defaultMode || GATE_MODES.HYBRID;
+}
+
+/**
+ * Applies session gate mode policy to a verdict decision (#61).
+ *
+ * @param {string} mode - Gate mode
+ * @param {Record<string, any>} decision - Original verdict decision
+ * @param {{ track?: string, riskBucket?: string, lockedAsk?: boolean, isRead?: boolean }} [meta]
+ * @returns {Record<string, any>}
+ */
+export function applySessionModePolicy(mode, decision, meta = {}) {
+  if (!decision) return decision;
+
+  const currentMode = mode || GATE_MODES.HYBRID;
+  const isLocked = Boolean(decision.lockedAsk || meta.lockedAsk);
+  const track = meta.track || decision.track || "external";
+  const riskBucket = meta.riskBucket || decision.riskBucket || "medium";
+
+  // Auto-approval mode: relaxes low-risk or internal chores that would otherwise ask
+  if (currentMode === GATE_MODES.AUTO && decision.verdict === "ask" && !isLocked) {
+    const isInternal = track === "internal";
+    const isLowRisk = riskBucket === "low" || riskBucket === "minimal";
+    if (isInternal || isLowRisk) {
+      return {
+        ...decision,
+        verdict: "allow",
+        autoApproved: true,
+        originalVerdict: "ask",
+        sessionMode: currentMode,
+        stage: "session-mode-auto",
+        autoReason: isInternal ? "auto-approve-internal-track" : "auto-approve-low-risk",
+      };
+    }
+  }
+
+  // Manual or strict mode: requires manual confirmation for external mutations or higher risk
+  if ((currentMode === GATE_MODES.MANUAL || currentMode === GATE_MODES.STRICT) && decision.verdict === "allow") {
+    const isSafeRead = Boolean(meta.isRead);
+    const isInternalSafe = track === "internal" && (riskBucket === "low" || riskBucket === "minimal");
+    if (!isSafeRead && !isInternalSafe) {
+      return {
+        ...decision,
+        verdict: "ask",
+        manualRequired: true,
+        originalVerdict: "allow",
+        sessionMode: currentMode,
+        stage: "session-mode-manual",
+        manualReason: currentMode === GATE_MODES.STRICT ? "strict-mode-enforcement" : "manual-mode-enforcement",
+      };
+    }
+  }
+
+  return {
+    ...decision,
+    sessionMode: currentMode,
+  };
+}
+
+/**
+ * Registry for maintaining per-session gate modes (#61).
+ */
+export class SessionModeRegistry {
+  constructor(defaultMode = GATE_MODES.HYBRID) {
+    this.defaultMode = defaultMode;
+    /** @type {Map<string, string>} */
+    this.sessionModes = new Map();
+  }
+
+  setMode(sessionId, mode) {
+    const key = sessionId || "default";
+    const resolved = PRESET_MODE_MAP[String(mode).toLowerCase().trim()] || mode;
+    if (Object.values(GATE_MODES).includes(resolved)) {
+      this.sessionModes.set(key, resolved);
+      return resolved;
+    }
+    return this.defaultMode;
+  }
+
+  getMode(sessionId, preset) {
+    const key = sessionId || "default";
+    if (this.sessionModes.has(key)) {
+      return this.sessionModes.get(key);
+    }
+    return resolveSessionGateMode(sessionId, preset, { defaultMode: this.defaultMode });
+  }
+
+  clearSession(sessionId) {
+    const key = sessionId || "default";
+    this.sessionModes.delete(key);
+  }
+
+  reset() {
+    this.sessionModes.clear();
+  }
+}

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.22",
-  "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"
-  },
-  "files": [
-    "lib",
-    "rules",
-    "cordis.patch.yml",
-    "README.md",
-    "README.zh.md",
-    "README.ru.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "license": "MIT",
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
-  },
-  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
-  "bugs": {
-    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "security",
-    "approval-gate",
-    "safety"
-  ]
-}
+{
+  "name": "@goodandready/dsh-approval-gate",
+  "version": "0.1.23",
+  "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"
+  },
+  "files": [
+    "lib",
+    "rules",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.ru.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-approval-gate.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-approval-gate#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-approval-gate/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "security",
+    "approval-gate",
+    "safety"
+  ]
+}