@goodandready/dsh-approval-gate 0.1.24 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.25
+
+- Security: Асинхронная гонка решения (`raceHumanDecision` в `lib/race-decision.js`) между подтверждением человека и настраиваемым таймером хоста с гарантированной защитой от зависания сессий и fail-closed обработкой `lockedAsk` (Refs: #50).
+- Feature: Перехват открытого диалога подтверждения через LLM Pre-emption Claim (`RaceHumanHandle.claim` в `lib/race-decision.js`) с автоматическим закрытием модального окна при быстром утвердительном вердикте модели (Refs: #51).
+- Feature: HMR-перезагрузка правил на лету (`RulesHmrWatcher` в `lib/rules-hmr.js`) на стандартном `fs.watch` Node.js с дебаунсом и атомарной перекомпиляцией правил в памяти без перезапуска демона dsh (Refs: #43).
+- Security: Маппинг сетевых политик на официальные режимы песочницы DSH (`resolveNetworkPolicy`, `checkNetworkAccess` в `lib/network-sandbox.js`: `read-only` -> `deny-all`, `workspace-write` -> `whitelist-only`, `danger-full-access` -> `allow-all`) (Refs: #41).
+- Security: Встроенный локальный HTTP/CONNECT forward proxy (`LocalEgressProxy` в `lib/forward-proxy.js`) для надежного перехвата сетевого egress подпроцессов bash (`HTTP_PROXY`, `ALL_PROXY`) и блокировки несанкционированных хостов (Refs: #39).
+
 ## 0.1.24
 
 - Security: Жесткое исключение критических категорий из механизма авто-обучения (`canLearnOperation` в `lib/learning.js`) с гарантированным запретом запоминания деструктивных операций (`rm`), секретов (`.env`, `.ssh`), эскалации прав (`sudo`) и системных путей (Refs: #81).

package/lib/engine.js

@@ -31,6 +31,9 @@ import { TrajectoryTracker } from "./drift.js";
 import { ConfirmationLearner } from "./learning.js";
 import { findSemanticallyEquivalentRule } from "./similarity.js";
 import { IndependentReviewer } from "./reviewer.js";
+import { raceHumanDecision, RaceHumanHandle } from "./race-decision.js";
+import { RulesHmrWatcher } from "./rules-hmr.js";
+import { checkNetworkAccess, resolveNetworkPolicy } from "./network-sandbox.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -98,6 +101,8 @@ export class SecurityEngine {
     this.trajectoryTracker = options.trajectoryTracker !== undefined ? options.trajectoryTracker : new TrajectoryTracker();
     this.learner = options.learner !== undefined ? options.learner : new ConfirmationLearner(options);
     this.reviewer = options.reviewer || new IndependentReviewer(options);
+    this.hmrWatcher = options.hmrWatcher || new RulesHmrWatcher(options);
+    this.egressProxy = options.egressProxy || null;
   }
 
   /**
@@ -522,9 +527,7 @@ export class SecurityEngine {
     if (decision && decision.verdict === "ask" && isCriticalOperation(toolName, command, execution)) {
       decision.lockedAsk = true;
       decision.lockedReason = "critical-operation";
-      if (decision.hit) {
-        decision.hit.lockedAsk = true;
-      }
+      if (decision.hit) decision.hit.lockedAsk = true;
     }
   }
 
@@ -582,5 +585,9 @@ export class SecurityEngine {
   recordConfirmation(sessionId, execution) { return this.learner ? this.learner.recordConfirmation(sessionId, execution) : null; }
   getLearnedRules(sessionId) { return this.learner ? this.learner.getLearnedRules(sessionId) : []; }
   reviewWithIndependentModel(execution, context) { return this.reviewer ? this.reviewer.review(execution, context) : null; }
+  raceDecision(humanPromise, opts) { return raceHumanDecision(humanPromise, opts); }
+  createRaceHandle(opts) { return new RaceHumanHandle(opts); }
+  checkNetwork(dest, sandboxMode, opts) { return checkNetworkAccess(dest, sandboxMode, opts); }
+  resolveNetworkPolicy(mode, opts) { return resolveNetworkPolicy(mode, opts); }
 }
 

package/lib/forward-proxy.js

@@ -0,0 +1,218 @@
+// lib/forward-proxy.js
+// Local HTTP/CONNECT Forward Proxy for Bash Network Egress Interception (#39).
+// Binds to 127.0.0.1 and intercepts egress traffic from child processes (curl, python, node).
+// Enforces sandbox network policies and blocks unauthorized hosts via HTTP and CONNECT tunnels.
+
+import http from "node:http";
+import net from "node:net";
+import { checkNetworkAccess, parseDestination } from "./network-sandbox.js";
+
+/**
+ * Embedded forward proxy for intercepting subprocess egress (#39).
+ */
+export class LocalEgressProxy {
+  /**
+   * @param {{
+   *   port?: number,
+   *   sandboxMode?: string,
+   *   whitelist?: string[],
+   *   auditLogger?: any,
+   *   logger?: any,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.port = typeof options.port === "number" ? options.port : 0;
+    this.sandboxMode = options.sandboxMode || "workspace-write";
+    this.whitelist = Array.isArray(options.whitelist) ? [...options.whitelist] : [];
+    this.auditLogger = options.auditLogger || null;
+    this.logger = options.logger || null;
+
+    this.server = null;
+    this.listeningPort = 0;
+    this.activeSockets = new Set();
+  }
+
+  /**
+   * Starts the forward proxy server.
+   * @returns {Promise<{ host: string, port: number }>}
+   */
+  async start() {
+    if (this.server) {
+      return { host: "127.0.0.1", port: this.listeningPort };
+    }
+
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer((req, res) => {
+        this._handleHttpRequest(req, res);
+      });
+
+      this.server.on("connect", (req, clientSocket, head) => {
+        this._handleConnectTunnel(req, clientSocket, head);
+      });
+
+      this.server.on("connection", (socket) => {
+        this.activeSockets.add(socket);
+        socket.once("close", () => this.activeSockets.delete(socket));
+      });
+
+      this.server.on("error", (err) => {
+        if (this.logger) this.logger.error?.("LocalEgressProxy server error:", err);
+        reject(err);
+      });
+
+      this.server.listen(this.port, "127.0.0.1", () => {
+        const addr = this.server.address();
+        this.listeningPort = typeof addr === "object" && addr ? addr.port : this.port;
+        resolve({ host: "127.0.0.1", port: this.listeningPort });
+      });
+    });
+  }
+
+  /**
+   * Stops the forward proxy and closes all active sockets.
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (!this.server) return;
+
+    return new Promise((resolve) => {
+      for (const socket of this.activeSockets) {
+        try {
+          socket.destroy();
+        } catch (_e) {}
+      }
+      this.activeSockets.clear();
+
+      this.server.close(() => {
+        this.server = null;
+        this.listeningPort = 0;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Returns proxy environment variables to inject into child processes.
+   * @returns {{ HTTP_PROXY: string, HTTPS_PROXY: string, ALL_PROXY: string, NO_PROXY: string }}
+   */
+  getEnv() {
+    if (!this.listeningPort) return {};
+    const proxyUrl = `http://127.0.0.1:${this.listeningPort}`;
+    return {
+      HTTP_PROXY: proxyUrl,
+      HTTPS_PROXY: proxyUrl,
+      ALL_PROXY: proxyUrl,
+      NO_PROXY: "127.0.0.1,localhost",
+    };
+  }
+
+  /**
+   * Checks whether access to destination is allowed under proxy rules.
+   * @param {string} destination
+   * @returns {ReturnType<typeof checkNetworkAccess>}
+   */
+  checkAccess(destination) {
+    return checkNetworkAccess(destination, this.sandboxMode, {
+      whitelist: this.whitelist,
+    });
+  }
+
+  /**
+   * @private
+   */
+  _handleHttpRequest(req, res) {
+    const dest = req.url || req.headers.host || "";
+    const access = this.checkAccess(dest);
+
+    if (!access.allowed) {
+      this._recordBlockedEgress(access.hostname, "HTTP", access.reason);
+      res.writeHead(403, { "Content-Type": "text/plain", "X-Proxy-Blocked": "unauthorized-egress" });
+      res.end(`403 Forbidden: Egress to ${access.hostname} blocked by security sandbox (${access.reason})\n`);
+      return;
+    }
+
+    // Forward HTTP request
+    try {
+      const u = new URL(req.url);
+      const options = {
+        hostname: u.hostname,
+        port: Number(u.port) || 80,
+        path: `${u.pathname}${u.search}`,
+        method: req.method,
+        headers: req.headers,
+      };
+
+      const proxyReq = http.request(options, (proxyRes) => {
+        res.writeHead(proxyRes.statusCode || 200, proxyRes.headers);
+        proxyRes.pipe(res);
+      });
+
+      proxyReq.on("error", (err) => {
+        res.writeHead(502, { "Content-Type": "text/plain" });
+        res.end(`502 Bad Gateway: ${err.message}\n`);
+      });
+
+      req.pipe(proxyReq);
+    } catch (err) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end(`400 Bad Request: ${err.message}\n`);
+    }
+  }
+
+  /**
+   * @private
+   */
+  _handleConnectTunnel(req, clientSocket, head) {
+    const dest = req.url || "";
+    const access = this.checkAccess(dest);
+
+    if (!access.allowed) {
+      this._recordBlockedEgress(access.hostname, "CONNECT", access.reason);
+      clientSocket.write("HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain\r\n\r\nBlocked by security sandbox\n");
+      clientSocket.destroy();
+      return;
+    }
+
+    const { hostname, port } = parseDestination(dest);
+    const targetPort = port || 443;
+
+    const serverSocket = net.connect(targetPort, hostname, () => {
+      clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      if (head && head.length > 0) {
+        serverSocket.write(head);
+      }
+      serverSocket.pipe(clientSocket);
+      clientSocket.pipe(serverSocket);
+    });
+
+    serverSocket.on("error", (_err) => {
+      try {
+        clientSocket.write("HTTP/1.1 502 Bad Gateway\r\n\r\n");
+        clientSocket.destroy();
+      } catch (_e) {}
+    });
+
+    clientSocket.on("error", (_err) => {
+      try {
+        serverSocket.destroy();
+      } catch (_e) {}
+    });
+  }
+
+  /**
+   * @private
+   */
+  _recordBlockedEgress(host, protocol, reason) {
+    if (this.auditLogger && typeof this.auditLogger.appendAuditLine === "function") {
+      this.auditLogger.appendAuditLine({
+        sessionId: "egress-proxy",
+        decision: {
+          verdict: "deny",
+          stage: "P0",
+          reason: `egress-proxy-blocked: ${reason}`,
+          detail: `${protocol} to ${host}`,
+        },
+      });
+    }
+  }
+}

package/lib/index.js

@@ -578,3 +578,7 @@ export { DEFAULT_MIN_CONFIRMATIONS, DEFAULT_MAX_LEARNED_RULES, EXCLUSION_REASONS
 export { canonicalizeCommand, isSemanticallyEquivalent, findSemanticallyEquivalentRule, validateSemanticSimilarity } from "./similarity.js";
 export { SAFETY_REVIEWER_SYSTEM_PROMPT, DEFAULT_REVIEWER_AGENT_ID, assertSeparationOfDuties, IndependentReviewer } from "./reviewer.js";
 export { DEFAULT_EVAL_CORPUS, runEvaluation, formatEvaluationReport } from "./eval-runner.js";
+export { DEFAULT_HUMAN_TIMEOUT_MS, RACE_WINNERS, RaceHumanHandle, raceHumanDecision } from "./race-decision.js";
+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";

package/lib/network-sandbox.js

@@ -0,0 +1,147 @@
+// lib/network-sandbox.js
+// Mapping Network Egress Policies to DSH Sandbox Modes (#41).
+// Controls outbound socket and HTTP connections based on shell.sandboxMode.
+
+import { isLoopbackHost } from "./loopback.js";
+
+export const NETWORK_POLICIES = Object.freeze({
+  DENY_ALL: "deny-all",
+  WHITELIST_ONLY: "whitelist-only",
+  ALLOW_ALL: "allow-all",
+});
+
+export const SANDBOX_NETWORK_MAP = Object.freeze({
+  "read-only": NETWORK_POLICIES.DENY_ALL,
+  readonly: NETWORK_POLICIES.DENY_ALL,
+  isolated: NETWORK_POLICIES.DENY_ALL,
+  "workspace-write": NETWORK_POLICIES.WHITELIST_ONLY,
+  standard: NETWORK_POLICIES.WHITELIST_ONLY,
+  hybrid: NETWORK_POLICIES.WHITELIST_ONLY,
+  "danger-full-access": NETWORK_POLICIES.ALLOW_ALL,
+  full: NETWORK_POLICIES.ALLOW_ALL,
+});
+
+/**
+ * Resolves network egress policy from DSH sandbox mode (#41).
+ *
+ * @param {string} [sandboxMode]
+ * @param {Record<string, any>} [options]
+ * @returns {"deny-all" | "whitelist-only" | "allow-all"}
+ */
+export function resolveNetworkPolicy(sandboxMode, options = {}) {
+  if (options.policy && Object.values(NETWORK_POLICIES).includes(options.policy)) {
+    return options.policy;
+  }
+  const mode = String(sandboxMode || "").toLowerCase().trim();
+  return SANDBOX_NETWORK_MAP[mode] || options.defaultPolicy || NETWORK_POLICIES.WHITELIST_ONLY;
+}
+
+/**
+ * Normalizes a destination host / URL to hostname and port.
+ * @param {string} destination
+ * @returns {{ hostname: string, port: number }}
+ */
+export function parseDestination(destination) {
+  if (!destination || typeof destination !== "string") {
+    return { hostname: "", port: 80 };
+  }
+  const clean = destination.trim();
+  try {
+    if (clean.includes("://")) {
+      const u = new URL(clean);
+      return { hostname: u.hostname.toLowerCase(), port: Number(u.port) || (u.protocol === "https:" ? 443 : 80) };
+    }
+  } catch (_e) {}
+
+  // host:port format
+  if (clean.includes(":")) {
+    const [h, p] = clean.split(":");
+    return { hostname: h.toLowerCase(), port: Number(p) || 80 };
+  }
+
+  return { hostname: clean.toLowerCase(), port: 80 };
+}
+
+/**
+ * Checks whether outbound network access to destination is allowed (#41).
+ *
+ * @param {string} destination - Host, host:port, or full URL
+ * @param {string} [sandboxMode] - Active DSH sandbox mode
+ * @param {{
+ *   whitelist?: string[],
+ *   allowLoopback?: boolean,
+ *   policy?: string,
+ * }} [options]
+ * @returns {{
+ *   allowed: boolean,
+ *   policy: string,
+ *   destination: string,
+ *   hostname: string,
+ *   reason?: string
+ * }}
+ */
+export function checkNetworkAccess(destination, sandboxMode, options = {}) {
+  const policy = resolveNetworkPolicy(sandboxMode, options);
+  const { hostname } = parseDestination(destination);
+
+  // 1. Loopback check (allowed by default for internal services unless explicitly blocked)
+  const isLoopback = isLoopbackHost(hostname);
+  if (isLoopback && options.allowLoopback !== false) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "loopback-allowed",
+    };
+  }
+
+  // 2. Deny-all policy (read-only sandbox mode)
+  if (policy === NETWORK_POLICIES.DENY_ALL) {
+    return {
+      allowed: false,
+      policy,
+      destination,
+      hostname,
+      reason: "sandbox-read-only-network-denied",
+    };
+  }
+
+  // 3. Allow-all policy (danger-full-access sandbox mode)
+  if (policy === NETWORK_POLICIES.ALLOW_ALL) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "danger-full-access-unrestricted",
+    };
+  }
+
+  // 4. Whitelist-only policy (workspace-write / standard sandbox mode)
+  const whitelist = Array.isArray(options.whitelist) ? options.whitelist : [];
+  const isWhitelisted = whitelist.some((entry) => {
+    const entryHost = String(entry).toLowerCase().trim();
+    if (entryHost === hostname) return true;
+    if (entryHost.startsWith("*.") && hostname.endsWith(entryHost.slice(1))) return true;
+    return false;
+  });
+
+  if (isWhitelisted) {
+    return {
+      allowed: true,
+      policy,
+      destination,
+      hostname,
+      reason: "whitelist-allowed",
+    };
+  }
+
+  return {
+    allowed: false,
+    policy,
+    destination,
+    hostname,
+    reason: "not-in-network-whitelist",
+  };
+}

package/lib/race-decision.js

@@ -0,0 +1,180 @@
+// lib/race-decision.js
+// Asynchronous Race Decision & Pre-emption Claim (#50, #51).
+// Races human decision against host timeout and enables fast LLM pre-emption claim.
+
+export const DEFAULT_HUMAN_TIMEOUT_MS = 60000;
+
+export const RACE_WINNERS = Object.freeze({
+  HUMAN: "human",
+  TIMEOUT: "timeout",
+  CLAIM: "claim",
+});
+
+/**
+ * Handle coordinating human decision, host timeout, and pre-emption claims (#50, #51).
+ */
+export class RaceHumanHandle {
+  /**
+   * @param {{
+   *   timeoutMs?: number,
+   *   timeoutAction?: "allow" | "deny" | "ask",
+   *   lockedAsk?: boolean,
+   *   onClaim?: (verdict: string, reason: string) => void,
+   *   onTimeout?: () => void,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.timeoutMs = typeof options.timeoutMs === "number" ? options.timeoutMs : DEFAULT_HUMAN_TIMEOUT_MS;
+    this.timeoutAction = options.timeoutAction || "deny";
+    this.lockedAsk = Boolean(options.lockedAsk);
+    this.onClaim = options.onClaim || null;
+    this.onTimeout = options.onTimeout || null;
+
+    this.settled = false;
+    this.winner = null;
+    this.startTime = Date.now();
+    this.timer = null;
+
+    this._resolve = null;
+    this._reject = null;
+
+    this.promise = new Promise((resolve, reject) => {
+      this._resolve = resolve;
+      this._reject = reject;
+    });
+
+    if (this.timeoutMs > 0 && this.timeoutMs < Infinity) {
+      this.timer = setTimeout(() => {
+        this._handleTimeout();
+      }, this.timeoutMs);
+    }
+  }
+
+  isSettled() {
+    return this.settled;
+  }
+
+  /**
+   * Pre-empts open human confirmation dialog when fast LLM or reviewer arrives at confident verdict (#51).
+   *
+   * @param {"allow" | "deny" | "ask"} outcome
+   * @param {string} [reason="pre-emption-claim"]
+   * @returns {{ claimed: boolean, reason?: string, winner?: string }}
+   */
+  claim(outcome, reason = "pre-emption-claim") {
+    if (this.settled) {
+      return { claimed: false, reason: "already-settled", winner: this.winner };
+    }
+
+    // Critical lockedAsk operations cannot be auto-claimed as allow
+    if (this.lockedAsk && outcome === "allow") {
+      return { claimed: false, reason: "locked-ask-cannot-be-claimed-as-allow" };
+    }
+
+    this._settle(RACE_WINNERS.CLAIM, {
+      winner: RACE_WINNERS.CLAIM,
+      verdict: outcome,
+      reason,
+      elapsedMs: Date.now() - this.startTime,
+    });
+
+    if (typeof this.onClaim === "function") {
+      this.onClaim(outcome, reason);
+    }
+
+    return { claimed: true, verdict: outcome, reason };
+  }
+
+  /**
+   * Resolves decision from human approval input.
+   * @param {Record<string, any> | string} decision
+   */
+  resolveHuman(decision) {
+    if (this.settled) return false;
+    const verdict = typeof decision === "string" ? decision : (decision?.verdict || "allow");
+    this._settle(RACE_WINNERS.HUMAN, {
+      winner: RACE_WINNERS.HUMAN,
+      verdict,
+      decision: typeof decision === "object" ? decision : { verdict },
+      elapsedMs: Date.now() - this.startTime,
+    });
+    return true;
+  }
+
+  /**
+   * Aborts the race decision handle.
+   * @param {string} [reason="aborted"]
+   */
+  abort(reason = "aborted") {
+    if (this.settled) return false;
+    this._settle(RACE_WINNERS.TIMEOUT, {
+      winner: RACE_WINNERS.TIMEOUT,
+      verdict: "deny",
+      reason,
+      elapsedMs: Date.now() - this.startTime,
+    });
+    return true;
+  }
+
+  /**
+   * @private
+   */
+  _handleTimeout() {
+    if (this.settled) return;
+
+    // Locked ask operations must fail closed on timeout
+    const resolvedVerdict = this.lockedAsk ? "deny" : this.timeoutAction;
+
+    if (typeof this.onTimeout === "function") {
+      this.onTimeout();
+    }
+
+    this._settle(RACE_WINNERS.TIMEOUT, {
+      winner: RACE_WINNERS.TIMEOUT,
+      verdict: resolvedVerdict,
+      reason: "host-timeout-expired",
+      elapsedMs: Date.now() - this.startTime,
+    });
+  }
+
+  /**
+   * @private
+   */
+  _settle(winner, result) {
+    if (this.settled) return;
+    this.settled = true;
+    this.winner = winner;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this._resolve) {
+      this._resolve(result);
+    }
+  }
+}
+
+/**
+ * Races human decision against host timeout and optional fast claims (#50, #51).
+ *
+ * @param {Promise<any>} humanPromise
+ * @param {ConstructorParameters<typeof RaceHumanHandle>[0]} [options]
+ * @returns {Promise<{
+ *   winner: "human" | "timeout" | "claim",
+ *   verdict: string,
+ *   elapsedMs: number,
+ *   reason?: string,
+ *   decision?: any
+ * }>}
+ */
+export async function raceHumanDecision(humanPromise, options = {}) {
+  const handle = new RaceHumanHandle(options);
+
+  if (humanPromise && typeof humanPromise.then === "function") {
+    humanPromise
+      .then((res) => handle.resolveHuman(res))
+      .catch((err) => handle.abort(err?.message || "human-error"));
+  }
+
+  return handle.promise;
+}

package/lib/rules-hmr.js

@@ -0,0 +1,132 @@
+// lib/rules-hmr.js
+// Hot Module Reloading for Security Rules (#43).
+// Watches .dsh/rules.yaml and declarative rule definitions using Node.js stdlib fs watchers.
+// Recompiles rules in-memory atomically without dropping active sessions or restarting dsh.
+
+import fs from "node:fs";
+
+export const DEFAULT_HMR_DEBOUNCE_MS = 150;
+
+/**
+ * Manages atomic hot reload watchers for rule definitions (#43).
+ */
+export class RulesHmrWatcher {
+  /**
+   * @param {{ debounceMs?: number, logger?: any }} [options]
+   */
+  constructor(options = {}) {
+    this.debounceMs = options.debounceMs || DEFAULT_HMR_DEBOUNCE_MS;
+    this.logger = options.logger || null;
+    /** @type {Map<string, fs.FSWatcher>} */
+    this.watchers = new Map();
+    /** @type {NodeJS.Timeout | null} */
+    this.debounceTimer = null;
+    this.reloading = false;
+  }
+
+  /**
+   * Attaches file watchers for declarative rules files.
+   *
+   * @param {any} rulesEngine - Instance of DeclarativeRulesEngine
+   * @param {string[]} filePaths - Files or directories to watch
+   * @param {(info: { path: string, timestamp: number }) => void} [onReload]
+   * @returns {number} Count of successfully watched paths
+   */
+  watch(rulesEngine, filePaths = [], onReload = null) {
+    if (!rulesEngine || !Array.isArray(filePaths)) return 0;
+    let watchedCount = 0;
+
+    for (const targetPath of filePaths) {
+      if (!targetPath || typeof targetPath !== "string") continue;
+      if (this.watchers.has(targetPath)) continue;
+
+      try {
+        if (!fs.existsSync(targetPath)) continue;
+
+        const watcher = fs.watch(targetPath, { persistent: false }, (eventType, filename) => {
+          this._handleFileChange(rulesEngine, targetPath, onReload);
+        });
+
+        watcher.on("error", (err) => {
+          if (this.logger) this.logger.warn?.(`RulesHmrWatcher error on ${targetPath}:`, err);
+          this.unwatch(targetPath);
+        });
+
+        this.watchers.set(targetPath, watcher);
+        watchedCount += 1;
+      } catch (err) {
+        if (this.logger) this.logger.warn?.(`Failed to watch ${targetPath}:`, err);
+      }
+    }
+
+    return watchedCount;
+  }
+
+  /**
+   * Unwatches a specific file path.
+   * @param {string} targetPath
+   */
+  unwatch(targetPath) {
+    const watcher = this.watchers.get(targetPath);
+    if (watcher) {
+      try {
+        watcher.close();
+      } catch (_e) {}
+      this.watchers.delete(targetPath);
+    }
+  }
+
+  /**
+   * Closes all active file watchers.
+   */
+  close() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    for (const [p, watcher] of this.watchers.entries()) {
+      try {
+        watcher.close();
+      } catch (_e) {}
+    }
+    this.watchers.clear();
+  }
+
+  /**
+   * @private
+   */
+  _handleFileChange(rulesEngine, targetPath, onReload) {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this._triggerReload(rulesEngine, targetPath, onReload);
+    }, this.debounceMs);
+  }
+
+  /**
+   * @private
+   */
+  _triggerReload(rulesEngine, targetPath, onReload) {
+    if (this.reloading) return;
+    this.reloading = true;
+
+    try {
+      if (typeof rulesEngine.reload === "function") {
+        rulesEngine.reload();
+      } else if (typeof rulesEngine.loadRules === "function") {
+        rulesEngine.loadRules();
+      }
+
+      if (typeof onReload === "function") {
+        onReload({ path: targetPath, timestamp: Date.now() });
+      }
+    } catch (err) {
+      if (this.logger) this.logger.error?.(`Failed to reload rules for ${targetPath}:`, err);
+    } finally {
+      this.reloading = false;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-approval-gate",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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",