agent-guardrails 0.3.1 → 0.3.3

package/README.md

@@ -523,6 +523,58 @@ The first recommended MCP flow is:
 
 `suggest_task_contract` and `run_guardrail_check` still exist as lower-level MCP tools, but they are not the preferred first-run chat flow.
 
+## Daemon Mode / 守护进程模式
+
+Run guardrails automatically in the background while you code:
+
+```bash
+# Start the daemon (background mode)
+agent-guardrails start
+
+# Check daemon status
+agent-guardrails status
+
+# Stop the daemon
+agent-guardrails stop
+
+# Run in foreground (useful for debugging or Docker)
+agent-guardrails start --foreground
+```
+
+### How It Works
+
+The daemon monitors file changes and automatically runs guardrail checks:
+- Watches `src/`, `lib/`, `tests/` by default
+- Debounces checks (5 second interval)
+- Logs to `.agent-guardrails/daemon.log`
+
+### Configuration (`.agent-guardrails/daemon.json`)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `watchPaths` | `["src/", "lib/", "tests/"]` | Paths to monitor |
+| `ignorePatterns` | `["node_modules", ".git", ...]` | Patterns to ignore |
+| `checkInterval` | `5000` | Debounce interval (ms) |
+| `blockOnHighRisk` | `true` | Block on high-risk findings |
+| `autoFix` | `false` | Auto-fix issues when possible |
+
+### Use Cases
+
+- **Local development**: Get instant feedback while coding
+- **CI/CD integration**: Run in containers with `--foreground`
+- **Team guardrails**: Shared daemon config in repo
+
+### Daemon vs Manual Check
+
+| Daemon Mode | Manual Check |
+|-------------|--------------|
+| Continuous monitoring | One-time check |
+| Automatic on file change | Run when you want |
+| Background process | Foreground process |
+| Best for active development | Best for pre-commit/CI |
+
+---
+
 ## CLI Fallback Quick Start
 
 If you want the shortest manual path, copy this:

package/lib/check/detectors/oss.js

@@ -1,5 +1,6 @@
 import { createFinding } from "../finding.js";
 import { normalizeChangeType } from "../../utils.js";
+import { execFileSync } from "node:child_process";
 
 function toBoolean(value) {
   if (value === true || value === false) {
@@ -461,5 +462,63 @@ export const ossDetectors = [
         }));
       }
     }
+  },
+  {
+    name: "secrets-safety",
+    run({ context, addFinding, t }) {
+      const { repoRoot, changedFiles } = context;
+      if (!changedFiles || changedFiles.length === 0) return;
+
+      const patterns = [
+        { regex: /(?:api[_-]?key|apikey)\s*[=:]\s*["'][^"']{8,}["']/i, label: "API key" },
+        { regex: /(?:password|passwd|pwd)\s*[=:]\s*["'][^"']{6,}["']/i, label: "Password" },
+        { regex: /Bearer\s+[A-Za-z0-9\-._~+/]+=*/i, label: "Bearer token" },
+        { regex: /-----BEGIN(?:\s+(?:RSA|EC|DSA|OPENSSH|PRIVATE))?[\s-]*PRIVATE KEY-----/, label: "Private key" },
+        { regex: /(?:secret|token)\s*[=:]\s*["'][A-Za-z0-9\-._~+/]{16,}["']/i, label: "Secret/token" }
+      ];
+
+      const testLike = /\.(test|spec)\.(js|ts|mjs|cjs|jsx|tsx)$|__tests__|fixtures|mock/i;
+      let matched = false;
+
+      for (const filePath of changedFiles) {
+        if (testLike.test(filePath)) continue;
+        let content;
+        try {
+          content = execFileSync(
+            "git",
+            ["diff", "--cached", "--", filePath],
+            { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+          );
+          if (!content.trim()) {
+            content = execFileSync(
+              "git",
+              ["diff", "--", filePath],
+              { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+            );
+          }
+        } catch {
+          continue;
+        }
+        const addedLines = content.split("\n").filter((line) => /^\+/.test(line) && !/^\+\+\+/.test(line));
+        for (const { regex, label } of patterns) {
+          for (const line of addedLines) {
+            if (regex.test(line)) {
+              matched = true;
+              addFinding(createFinding({
+                severity: "warning",
+                category: "risk",
+                code: "secrets-safety",
+                message: t("findings.secretsSafetyDetected", { file: filePath, type: label }),
+                action: t("actions.moveSecretToEnv"),
+                files: [filePath]
+              }));
+              break;
+            }
+          }
+          if (matched) break;
+        }
+        if (matched) break;
+      }
+    }
   }
 ];

package/lib/cli.js

@@ -5,7 +5,8 @@ import { runSetup } from "./commands/setup.js";
 import { createTranslator, supportedLocales } from "./i18n.js";
 import { runPlan } from "./commands/plan.js";
 import { runGenerateAgentsMd } from "./commands/agents-md.js";
-import { supportedAdapters, supportedPresets } from "./utils.js";
+import { startDaemon, stopDaemon, showDaemonStatus } from "./commands/daemon.js";
+import { supportedAdapters, supportedPresets, readOwnPackageJson } from "./utils.js";
 
 function parseArgs(argv) {
   const positional = [];
@@ -43,14 +44,26 @@ ${t("cli.usage")}
   agent-guardrails setup [targetDir] --agent <name> [--preset <name>] [--lang <locale>] [--json] [--write-repo-config]
   agent-guardrails plan --task "<task description>" [--intended-files "src/service.js,tests/service.test.js"] [--allowed-change-types "implementation-only"] [--allow-paths "src/,tests/"] [--required-commands "npm test"] [--evidence ".agent-guardrails/evidence/current-task.md"] [--risk-level high] [--lang <locale>] [--print-only]
   agent-guardrails check [--contract-path <path>] [--base-ref <ref>] [--commands-run "npm test"] [--review] [--lang <locale>] [--json]
+  agent-guardrails start [--foreground] - ${t("cli.startSummary")}
+  agent-guardrails stop    - ${t("cli.stopSummary")}
+  agent-guardrails status  - ${t("cli.statusSummary")}
   agent-guardrails generate-agents [targetDir] [--preset <name>] [--lang <locale>]
   agent-guardrails mcp
+  agent-guardrails --version
+
+${t("cli.globalOptions")}
+  --version, -v    ${t("cli.versionSummary") ?? "Show version number"}
+  --help, -h       ${t("cli.helpSummary") ?? "Show this help"}
+  --lang <locale>  ${t("cli.langSummary") ?? "Language for output (en, zh-CN)"}
 
 ${t("cli.commands")}
   init            ${t("cli.initSummary")}
   setup           ${t("cli.setupSummary")}
   plan            ${t("cli.planSummary")}
   check           ${t("cli.checkSummary")}
+  start           ${t("cli.startSummary")}
+  stop            ${t("cli.stopSummary")}
+  status          ${t("cli.statusSummary")}
   generate-agents Generate AGENTS.md for Harness Engineering
   mcp             ${t("cli.mcpSummary")}
 
@@ -70,6 +83,12 @@ export async function runCli(argv) {
   const [command, ...rest] = positional;
   const locale = flags.lang ?? null;
 
+  if (flags.version || flags.v) {
+    const pkg = readOwnPackageJson();
+    console.log(`agent-guardrails v${pkg.version}`);
+    return;
+  }
+
   if (!command || command === "help" || flags.help) {
     printHelp(locale);
     return;
@@ -100,6 +119,21 @@ export async function runCli(argv) {
     return;
   }
 
+  if (command === "start") {
+    await startDaemon(process.cwd(), { locale, foreground: flags.foreground || false });
+    return;
+  }
+
+  if (command === "stop") {
+    stopDaemon(process.cwd(), { locale });
+    return;
+  }
+
+  if (command === "status") {
+    showDaemonStatus(process.cwd(), { locale });
+    return;
+  }
+
   if (command === "generate-agents" || command === "gen-agents") {
     await runGenerateAgentsMd({ positional: rest, flags, locale });
     return;

package/lib/commands/check.js

@@ -475,6 +475,11 @@ function printTextResult(result, t, { reviewMode = false } = {}) {
   if (result.failures.length === 0) {
     console.log(`\n${t("check.allPassed")}`);
   }
+
+  if (result.runtime?.costHints?.entries?.length > 0) {
+    console.log(`\n${t("check.costAwareness")}`);
+    console.log(result.runtime.costHints.entries.map((entry) => `- ${t(entry.key, entry.vars)}`).join("\n"));
+  }
 }
 
 function printJsonResult(result) {

package/lib/commands/daemon.js

@@ -0,0 +1,323 @@
+/**
+ * Agent Guardrails Daemon Mode
+ *
+ * Event-driven file watcher — zero resource usage when idle.
+ *
+ * Usage:
+ *   agent-guardrails start [--foreground]   - Start daemon (--foreground for terminal)
+ *   agent-guardrails stop                   - Stop daemon
+ *   agent-guardrails status                 - Show status
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { createTranslator } from "../i18n.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DAEMON_PID_FILE = ".agent-guardrails/daemon.pid";
+const DAEMON_LOG_FILE = ".agent-guardrails/daemon.log";
+const DAEMON_CONFIG_FILE = ".agent-guardrails/daemon.json";
+const DAEMON_INFO_FILE = ".agent-guardrails/daemon-info.json";
+
+/**
+ * 默认守护配置
+ */
+const DEFAULT_DAEMON_CONFIG = {
+  enabled: true,
+  watchPaths: ["src/", "lib/", "tests/"],
+  ignorePatterns: ["node_modules", ".git", "dist", "coverage"],
+  checkInterval: 5000,
+  notifications: {
+    sound: false,
+    desktop: false
+  },
+  autoFix: false,
+  blockOnHighRisk: true
+};
+
+/**
+ * 获取守护配置
+ */
+export function getDaemonConfig(repoRoot) {
+  const configPath = path.join(repoRoot, DAEMON_CONFIG_FILE);
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, "utf8");
+      return { ...DEFAULT_DAEMON_CONFIG, ...JSON.parse(content) };
+    } catch {
+      // 配置解析失败，使用默认
+    }
+  }
+
+  return DEFAULT_DAEMON_CONFIG;
+}
+
+/**
+ * 写入守护配置
+ */
+export function writeDaemonConfig(repoRoot, config) {
+  const configPath = path.join(repoRoot, DAEMON_CONFIG_FILE);
+  const dir = path.dirname(configPath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
+}
+
+/**
+ * 检查守护进程是否运行
+ */
+export function isDaemonRunning(repoRoot) {
+  const pidFile = path.join(repoRoot, DAEMON_PID_FILE);
+
+  if (!fs.existsSync(pidFile)) {
+    return { running: false };
+  }
+
+  try {
+    const pid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+
+    if (Number.isNaN(pid)) {
+      return { running: false };
+    }
+
+    // 跨平台检查进程
+    let running = false;
+    try {
+      if (process.platform === "win32") {
+        const result = spawnSync("tasklist", ["/FI", `PID eq ${pid}`], {
+          encoding: "utf8",
+          timeout: 5000
+        });
+        // 精确匹配 PID，避免 "123" 匹配 "1234"
+        running = new RegExp(`\\b${pid}\\b`).test(result.stdout);
+      } else {
+        process.kill(pid, 0);
+        running = true;
+      }
+    } catch {
+      running = false;
+    }
+
+    if (!running) {
+      fs.unlinkSync(pidFile);
+      return { running: false };
+    }
+
+    // 读取守护进程信息
+    const infoFile = path.join(repoRoot, DAEMON_INFO_FILE);
+    let info = {};
+    if (fs.existsSync(infoFile)) {
+      try {
+        info = JSON.parse(fs.readFileSync(infoFile, "utf8"));
+      } catch {
+        // ignore
+      }
+    }
+
+    return {
+      running: true,
+      pid,
+      startTime: info.startTime,
+      checksRun: info.checksRun || 0,
+      lastCheck: info.lastCheck
+    };
+  } catch {
+    return { running: false };
+  }
+}
+
+/**
+ * 事件驱动等待 PID 文件出现（替代 busy-wait 轮询）
+ */
+async function waitForPidFile(pidFile, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    if (fs.existsSync(pidFile)) {
+      try { resolve(fs.readFileSync(pidFile, "utf8").trim()); } catch { resolve(null); }
+      return;
+    }
+
+    const dir = path.dirname(pidFile);
+    let watcher;
+    const timer = setTimeout(() => {
+      if (watcher) watcher.close();
+      // 最终检查一次
+      if (fs.existsSync(pidFile)) {
+        try { resolve(fs.readFileSync(pidFile, "utf8").trim()); } catch { resolve(null); }
+      } else {
+        resolve(null);
+      }
+    }, timeoutMs);
+
+    try {
+      watcher = fs.watch(dir, (eventType) => {
+        if (eventType === "rename" && fs.existsSync(pidFile)) {
+          clearTimeout(timer);
+          watcher.close();
+          try { resolve(fs.readFileSync(pidFile, "utf8").trim()); } catch { resolve(null); }
+        }
+      });
+    } catch {
+      clearTimeout(timer);
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * 启动守护进程
+ */
+export async function startDaemon(repoRoot, options = {}) {
+  const locale = options.locale || null;
+  const foreground = options.foreground || false;
+  const { t } = createTranslator(locale);
+
+  // 检查是否已运行
+  const status = isDaemonRunning(repoRoot);
+  if (status.running && !foreground) {
+    console.log(`\n${t("daemon.alreadyRunning")}`);
+    console.log(`  PID: ${status.pid}`);
+    console.log(`  ${t("daemon.startTime")}: ${status.startTime || "unknown"}`);
+    console.log(`\n  ${t("daemon.useStop")}`);
+    return { success: false, reason: "already_running", status };
+  }
+
+  const config = getDaemonConfig(repoRoot);
+
+  // 前台模式 — 直接调用 worker.run()
+  if (foreground) {
+    const { run } = await import("../daemon/worker.js");
+    return run({ repoRoot, config, foreground: true, locale });
+  }
+
+  // 后台模式 — spawn worker.js 子进程
+  console.log(`\n${t("daemon.starting")}\n`);
+
+  const workerPath = path.resolve(__dirname, "..", "daemon", "worker.js");
+  const pidFile = path.join(repoRoot, DAEMON_PID_FILE);
+
+  const child = spawn(process.execPath, [
+    workerPath,
+    "--repo-root", repoRoot,
+    "--config", JSON.stringify(config)
+  ], {
+    detached: true,
+    stdio: "ignore",
+    cwd: repoRoot
+  });
+
+  child.unref();
+
+  // 事件驱动等待 PID 文件（替代 busy-wait）
+  const pid = await waitForPidFile(pidFile, 5000);
+
+  if (pid) {
+    console.log(`${t("daemon.started")}`);
+    console.log(`  PID: ${pid}`);
+    console.log(`\n${t("daemon.logFile")}: ${DAEMON_LOG_FILE}`);
+    console.log(`${t("daemon.configFile")}: ${DAEMON_CONFIG_FILE}`);
+    console.log(`\n${t("daemon.useStop")}`);
+    console.log(`${t("daemon.useStatus")}`);
+    return { success: true, pid: parseInt(pid, 10) };
+  } else {
+    console.log(`${t("daemon.startFailed")}`);
+    return { success: false, reason: "timeout" };
+  }
+}
+
+/**
+ * 停止守护进程
+ */
+export async function stopDaemon(repoRoot, options = {}) {
+  const locale = options.locale || null;
+  const { t } = createTranslator(locale);
+
+  const status = isDaemonRunning(repoRoot);
+
+  if (!status.running) {
+    console.log(`\n${t("daemon.notRunning")}`);
+    return { success: false, reason: "not_running" };
+  }
+
+  console.log(`\n${t("daemon.stopping")}`);
+  console.log(`  PID: ${status.pid}`);
+
+  try {
+    if (process.platform === "win32") {
+      // 先尝试 taskkill /T（终止进程树，给 SIGTERM handler 机会）
+      spawnSync("taskkill", ["/PID", status.pid.toString(), "/T"], {
+        encoding: "utf8",
+        timeout: 5000
+      });
+      // 等待进程退出
+      const { setTimeout: delay } = await import("node:timers/promises");
+      await delay(1000);
+      // 如果还活着，强制终止
+      if (isDaemonRunning(repoRoot).running) {
+        spawnSync("taskkill", ["/PID", status.pid.toString(), "/F", "/T"], {
+          encoding: "utf8",
+          timeout: 5000
+        });
+      }
+    } else {
+      process.kill(status.pid, "SIGTERM");
+    }
+
+    // 清理文件
+    const pidFile = path.join(repoRoot, DAEMON_PID_FILE);
+    if (fs.existsSync(pidFile)) {
+      fs.unlinkSync(pidFile);
+    }
+
+    console.log(`\n${t("daemon.stopped")}`);
+    return { success: true };
+  } catch (error) {
+    console.log(`\n${t("daemon.stopFailed")}: ${error.message}`);
+    return { success: false, reason: error.message };
+  }
+}
+
+/**
+ * 显示守护进程状态
+ */
+export function showDaemonStatus(repoRoot, options = {}) {
+  const locale = options.locale || null;
+  const { t } = createTranslator(locale);
+
+  const status = isDaemonRunning(repoRoot);
+  const config = getDaemonConfig(repoRoot);
+
+  console.log(`\n${t("daemon.status")}\n`);
+
+  if (status.running) {
+    console.log(`  ${t("daemon.state")}: ${t("daemon.running")}`);
+    console.log(`  PID: ${status.pid}`);
+    console.log(`  ${t("daemon.startTime")}: ${status.startTime || "unknown"}`);
+    console.log(`  ${t("daemon.checksRun")}: ${status.checksRun}`);
+    console.log(`  ${t("daemon.lastCheck")}: ${status.lastCheck || "never"}`);
+  } else {
+    console.log(`  ${t("daemon.state")}: ${t("daemon.stopped")}`);
+  }
+
+  console.log(`\n  ${t("daemon.config")}:`);
+  console.log(`    ${t("daemon.watchPaths")}: ${config.watchPaths.join(", ")}`);
+  console.log(`    ${t("daemon.checkInterval")}: ${config.checkInterval}ms`);
+  console.log(`    ${t("daemon.blockOnHighRisk")}: ${config.blockOnHighRisk ? "yes" : "no"}`);
+
+  console.log(`\n  ${t("daemon.commands")}:`);
+  if (status.running) {
+    console.log(`    agent-guardrails stop     - ${t("daemon.stopDesc")}`);
+  } else {
+    console.log(`    agent-guardrails start   - ${t("daemon.startDesc")}`);
+  }
+  console.log(`    agent-guardrails status  - ${t("daemon.statusDesc")}`);
+
+  return status;
+}

package/lib/daemon/worker.js

@@ -0,0 +1,266 @@
+/**
+ * Agent Guardrails Daemon Worker
+ *
+ * Core daemon logic shared by foreground and background modes.
+ * Event-driven — no polling when idle.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+export function parseArgs(argv = process.argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === "--foreground") {
+      args.foreground = true;
+    } else if (flag === "--repo-root" && argv[i + 1]) {
+      args.repoRoot = argv[++i];
+    } else if (flag === "--config" && argv[i + 1]) {
+      try { args.config = JSON.parse(argv[++i]); } catch { /* ignore */ }
+    }
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+export function createLogger(logFile, foreground = false) {
+  function ensureDir() {
+    const dir = path.dirname(logFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  function log(message) {
+    const ts = new Date().toISOString();
+    const line = `[${ts}] ${message}`;
+    if (foreground) {
+      console.log(line);
+    } else {
+      try {
+        ensureDir();
+        fs.appendFileSync(logFile, line + "\n");
+      } catch { /* ignore write errors */ }
+    }
+  }
+
+  return { log };
+}
+
+// ---------------------------------------------------------------------------
+// Info store — tracks daemon state on disk
+// ---------------------------------------------------------------------------
+
+export function createInfoStore(infoFile, startTime) {
+  const state = {
+    pid: process.pid,
+    startTime,
+    checksRun: 0,
+    lastCheck: null
+  };
+
+  function save() {
+    const dir = path.dirname(infoFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(infoFile, JSON.stringify(state, null, 2));
+  }
+
+  return {
+    incrementChecks() { state.checksRun++; },
+    updateLastCheck() { state.lastCheck = new Date().toISOString(); },
+    save
+  };
+}
+
+// ---------------------------------------------------------------------------
+// File watcher — chokidar with fs.watch fallback
+// ---------------------------------------------------------------------------
+
+function createFallbackWatcher(repoRoot, config, onChange, log) {
+  const watchers = new Map();
+  let closed = false;
+
+  function watchDir(dir) {
+    if (closed) return;
+    try {
+      const w = fs.watch(dir, { recursive: false }, (_eventType, filename) => {
+        if (!filename) return;
+        onChange(path.join(dir, filename));
+      });
+      watchers.set(dir, w);
+    } catch { /* skip directories we can't watch */ }
+  }
+
+  function scanDirs(baseDir, depth) {
+    if (closed || depth > 10) return;
+    try {
+      const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (config.ignorePatterns.some((p) => entry.name.includes(p))) continue;
+        const fullPath = path.join(baseDir, entry.name);
+        if (entry.isDirectory()) {
+          watchDir(fullPath);
+          scanDirs(fullPath, depth + 1);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  for (const watchPath of config.watchPaths) {
+    const absolute = path.resolve(repoRoot, watchPath);
+    if (fs.existsSync(absolute)) {
+      watchDir(absolute);
+      scanDirs(absolute, 0);
+    }
+  }
+
+  return {
+    close() {
+      closed = true;
+      for (const [, w] of watchers) w.close();
+      watchers.clear();
+    },
+    ready: Promise.resolve()
+  };
+}
+
+async function createChokidarWatcher(repoRoot, config, onChange, log) {
+  const chokidar = await import("chokidar");
+  const watcher = chokidar.watch(config.watchPaths, {
+    cwd: repoRoot,
+    ignored: config.ignorePatterns,
+    persistent: true,
+    ignoreInitial: true
+  });
+
+  watcher.on("change", (filePath) => onChange(filePath));
+  watcher.on("add", (filePath) => onChange(filePath));
+
+  return new Promise((resolve) => {
+    watcher.on("ready", () => {
+      resolve({
+        close: () => watcher.close(),
+        ready: Promise.resolve()
+      });
+    });
+  });
+}
+
+export async function createWatcher(repoRoot, config, onChange, log) {
+  try {
+    log("Attempting to use chokidar for file watching...");
+    const watcher = await createChokidarWatcher(repoRoot, config, onChange, log);
+    log("chokidar initialized successfully");
+    return watcher;
+  } catch {
+    log("chokidar unavailable, falling back to fs.watch");
+    return createFallbackWatcher(repoRoot, config, onChange, log);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check runner — direct import, no npx
+// ---------------------------------------------------------------------------
+
+export async function createCheckRunner(repoRoot, config, log, t) {
+  let isCheckRunning = false;
+  let checkTimeout = null;
+  let runCount = 0;
+
+  const { executeCheck } = await import("../commands/check.js");
+
+  function scheduleCheck() {
+    if (checkTimeout) clearTimeout(checkTimeout);
+    checkTimeout = setTimeout(runCheck, config.checkInterval);
+  }
+
+  function runCheck() {
+    if (isCheckRunning) {
+      log(t("daemon.checkSkipped"));
+      return;
+    }
+    isCheckRunning = true;
+    runCount++;
+    log(`Running guardrail check (#${runCount})...`);
+
+    executeCheck({
+      repoRoot,
+      flags: { json: false },
+      suppressExitCode: true
+    })
+      .then((result) => {
+        const ok = result?.ok;
+        log(ok ? "Check passed" : "Check completed with issues");
+      })
+      .catch((err) => {
+        log(`Check error: ${err.message}`);
+      })
+      .finally(() => {
+        isCheckRunning = false;
+      });
+  }
+
+  return { scheduleCheck };
+}
+
+// ---------------------------------------------------------------------------
+// Main worker entry
+// ---------------------------------------------------------------------------
+
+export async function run({ repoRoot, config, foreground = false, locale = null }) {
+  const { createTranslator } = await import("../i18n.js");
+  const { t } = createTranslator(locale);
+
+  const startTime = new Date().toISOString();
+  const logFile = path.join(repoRoot, ".agent-guardrails", "daemon.log");
+  const infoFile = path.join(repoRoot, ".agent-guardrails", "daemon-info.json");
+  const pidFile = path.join(repoRoot, ".agent-guardrails", "daemon.pid");
+
+  const { log } = createLogger(logFile, foreground);
+  const info = createInfoStore(infoFile, startTime);
+  const { scheduleCheck } = await createCheckRunner(repoRoot, config, log, t);
+
+  // Cleanup handler
+  let watcher = null;
+  function cleanup() {
+    log("Shutting down...");
+    if (watcher) watcher.close();
+    try { if (fs.existsSync(pidFile)) fs.unlinkSync(pidFile); } catch { /* ignore */ }
+    try { if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile); } catch { /* ignore */ }
+  }
+
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+  process.on("SIGINT", () => { console.log(""); cleanup(); process.exit(0); });
+
+  // Write PID file
+  const dir = path.dirname(pidFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(pidFile, process.pid.toString());
+
+  log(`Daemon started with PID ${process.pid}`);
+  log(`Working directory: ${repoRoot}`);
+  log(`Watch paths: ${config.watchPaths.join(", ")}`);
+  log(`Check interval: ${config.checkInterval}ms (debounce, not polling)`);
+  if (!foreground) log("Press Ctrl+C or run 'agent-guardrails stop' to stop\n");
+  info.save();
+
+  // Start file watcher
+  watcher = await createWatcher(repoRoot, config, (filePath) => {
+    log(`File changed: ${filePath}`);
+    info.incrementChecks();
+    info.updateLastCheck();
+    info.save();
+    scheduleCheck();
+  }, log);
+
+  log("File watcher ready");
+
+  // Keep process alive
+  return new Promise(() => { /* never resolve */ });
+}

package/lib/i18n.js

@@ -3,14 +3,21 @@ const resources = {
     cli: {
       usage: "Usage:",
       commands: "Commands:",
+      globalOptions: "Global Options:",
       supportedPresets: "Supported presets:",
       supportedAdapters: "Supported adapters:",
       supportedLocales: "Supported locales:",
+      versionSummary: "Show version number",
+      helpSummary: "Show this help message",
+      langSummary: "Language for output (en, zh-CN)",
       initSummary: "Seed guardrail files into a repository",
       setupSummary: "Auto-initialize a repo, generate MCP config, and point an agent at the runtime",
       planSummary: "Print a bounded implementation brief and write a richer task contract by default",
       checkSummary: "Validate scope, consistency, correctness, risk, and production-profile rules for the current change",
       mcpSummary: "Expose the runtime through a stdio MCP server",
+      startSummary: "Start daemon mode for automatic background checking",
+      stopSummary: "Stop the daemon process",
+      statusSummary: "Show daemon status and configuration",
       unknownCommand: "Unknown command \"{command}\""
     },
     errors: {
@@ -247,7 +254,8 @@ const resources = {
       mentionObservability: "Mention metrics, logging, tracing, or monitoring changes in the evidence note.",
       mentionPerfValidation: "Call out how concurrency, load, performance, or reliability was validated.",
       extendExistingTarget: "Extend the existing target first: {value}",
-      preserveExistingStructure: "Preserve the current structure or explicitly widen the task contract before restructuring it."
+      preserveExistingStructure: "Preserve the current structure or explicitly widen the task contract before restructuring it.",
+      moveSecretToEnv: "Move the secret to an environment variable or a secrets manager, and add the variable name to a .env.example file."
     },
     check: {
       title: "Agent Guardrails Check",
@@ -305,7 +313,15 @@ const resources = {
       nextActions: "Next actions:",
       finishCommand: "Finish-time command: {value}",
       action: "Action: {value}",
-      findingSeverity: "[{severity}] {message}"
+      findingSeverity: "[{severity}] {message}",
+      costAwareness: "Cost awareness:",
+      costSizeSmall: "Change size: Small ({totalFiles} files, {sourceFiles} source)",
+      costSizeMedium: "Change size: Medium ({totalFiles} files, {sourceFiles} source)",
+      costSizeLarge: "Change size: Large ({totalFiles} files, {sourceFiles} source)",
+      costSizeVeryLarge: "Change size: Very large ({totalFiles} files, {sourceFiles} source)",
+      costTokenEstimate: "Estimated token cost: {low}-{high}",
+      costLargeChangeWarning: "Large change detected — consider splitting into smaller tasks to reduce token usage and review burden.",
+      costFixCostHint: "Fix cost: {errorCount} error(s), {warningCount} warning(s) need to be resolved."
     },
     findings: {
       missingRequiredFile: "Required file is missing: {path}",
@@ -336,7 +352,17 @@ const resources = {
       criticalPathTouchedWithoutRollback: "Critical path changed without rollback notes: {files}",
       performanceSensitiveAreaTouched: "Performance-sensitive area changed: {files}",
       observabilityRequirementsUnaddressed: "Observability requirements were declared, but the evidence note does not mention them.",
-      concurrencyRequirementsUnaddressed: "Concurrency or performance requirements were declared, but the evidence note does not mention validation for them."
+      concurrencyRequirementsUnaddressed: "Concurrency or performance requirements were declared, but the evidence note does not mention validation for them.",
+      secretsSafetyDetected: "Potential {type} detected in added lines of {file}. Move secrets to environment variables or a secrets manager."
+    },
+    recovery: {
+      revertOrNarrowScope: "Recovery: revert out-of-scope changes or update the task contract to include them.",
+      runOrSkipCommands: "Recovery: run the missing required commands, or explicitly skip them with justification in evidence.",
+      writeEvidenceFile: "Recovery: create the required evidence file and document what was done and any residual risk.",
+      revertOrAddReviewNotes: "Recovery: revert the protected-area changes or add detailed review notes explaining the rationale.",
+      moveSecretsToEnv: "Recovery: move detected secrets to environment variables or a secrets manager immediately.",
+      revertOrWidenContract: "Recovery: revert the unexpected change-type changes or update the task contract accordingly.",
+      addTestsOrAcknowledge: "Recovery: add tests for the changed source files, or document why tests are deferred."
     },
     roughIntent: {
       analyzing: "Analyzing your intent...",
@@ -364,19 +390,63 @@ const resources = {
       actionConfirm: "✅ Confirm",
       actionModify: "✏️ Modify scope",
       actionCancel: "❌ Cancel"
+    },
+    daemon: {
+      starting: "Starting daemon...",
+      foregroundMode: "foreground mode",
+      started: "✅ Daemon started successfully!",
+      startFailed: "❌ Failed to start daemon",
+      alreadyRunning: "Daemon is already running!",
+      stopping: "Stopping daemon...",
+      stopped: "✅ Daemon stopped.",
+      stopFailed: "❌ Failed to stop daemon",
+      notRunning: "Daemon is not running.",
+      status: "Daemon Status",
+      state: "State",
+      running: "Running",
+      config: "Configuration",
+      watchPaths: "Watch paths",
+      checkInterval: "Check interval",
+      blockOnHighRisk: "Block on high risk",
+      commands: "Commands",
+      startTime: "Started at",
+      checksRun: "Checks run",
+      lastCheck: "Last check",
+      logFile: "Log file",
+      configFile: "Config file",
+      useStop: "Use 'agent-guardrails stop' to stop.",
+      useStatus: "Use 'agent-guardrails status' to check status.",
+      startDesc: "Start the daemon",
+      stopDesc: "Stop the daemon",
+      statusDesc: "Show daemon status",
+      configUpdated: "✅ Daemon configuration updated!",
+      startDescLong: "Start the daemon in background mode",
+      stopDesc: "Stop the daemon",
+      stopDescLong: "Stop the daemon",
+      statusDesc: "Show daemon status",
+      statusDescLong: "Show daemon status and configuration",
+      chokidarFallback: "chokidar unavailable, falling back to fs.watch (less reliable on some platforms)",
+      checkSkipped: "Check already in progress, skipped"
     }
   },
   "zh-CN": {
     cli: {
       usage: "用法：",
       commands: "命令：",
+      globalOptions: "全局选项：",
       supportedPresets: "支持的 preset：",
       supportedAdapters: "支持的 adapter：",
       supportedLocales: "支持的语言：",
+      versionSummary: "显示版本号",
+      helpSummary: "显示帮助信息",
+      langSummary: "输出语言 (en, zh-CN)",
       initSummary: "向仓库写入 guardrail 文件",
       planSummary: "输出受约束的实现简报，并默认写入更丰富的任务契约",
       checkSummary: "校验当前改动的范围、一致性、正确性、风险和生产画像规则",
       mcpSummary: "通过 stdio MCP server 暴露运行时能力",
+      startSummary: "启动守护进程，自动后台检查",
+      stopSummary: "停止守护进程",
+      statusSummary: "查看守护进程状态和配置",
       unknownCommand: "未知命令 \"{command}\""
     },
     errors: {
@@ -538,7 +608,8 @@ const resources = {
       mentionObservability: "在证据说明里说明 metrics、logging、tracing 或 monitoring 的变化。",
       mentionPerfValidation: "说明并发、负载、性能或可靠性是如何验证的。",
       extendExistingTarget: "优先扩展现有目标：{value}",
-      preserveExistingStructure: "尽量保持当前结构，除非先显式放宽任务契约。"
+      preserveExistingStructure: "尽量保持当前结构，除非先显式放宽任务契约。",
+      moveSecretToEnv: "将密钥移至环境变量或密钥管理器，并在 .env.example 中记录变量名。"
     },
     check: {
       title: "Agent Guardrails 检查结果",
@@ -589,7 +660,15 @@ const resources = {
       nextActions: "下一步：",
       finishCommand: "收尾命令：{value}",
       action: "处理建议：{value}",
-      findingSeverity: "[{severity}] {message}"
+      findingSeverity: "[{severity}] {message}",
+      costAwareness: "成本感知：",
+      costSizeSmall: "变更规模：小（{totalFiles} 个文件，{sourceFiles} 个源码）",
+      costSizeMedium: "变更规模：中（{totalFiles} 个文件，{sourceFiles} 个源码）",
+      costSizeLarge: "变更规模：大（{totalFiles} 个文件，{sourceFiles} 个源码）",
+      costSizeVeryLarge: "变更规模：非常大（{totalFiles} 个文件，{sourceFiles} 个源码）",
+      costTokenEstimate: "预估 token 成本：{low}-{high}",
+      costLargeChangeWarning: "检测到大范围变更 — 建议拆分为更小的任务以降低 token 消耗和审查负担。",
+      costFixCostHint: "修复成本：{errorCount} 个错误、{warningCount} 个警告需要解决。"
     },
     findings: {
       missingRequiredFile: "缺少必需文件：{path}",
@@ -621,7 +700,17 @@ const resources = {
       performanceSensitiveAreaTouched: "触及性能敏感区域：{files}",
       observabilityRequirementsUnaddressed: "任务声明了可观测性要求，但证据中没有体现。",
       concurrencyRequirementsUnaddressed: "任务声明了并发或性能要求，但证据中没有体现相关验证。",
-      protectedAreaDefaultAction: "收窄任务契约，或为 {path} 补充更明确的 review 说明。"
+      protectedAreaDefaultAction: "收窄任务契约，或为 {path} 补充更明确的 review 说明。",
+      secretsSafetyDetected: "在 {file} 的新增行中检测到可能的 {type}。请将密钥移至环境变量或密钥管理器。"
+    },
+    recovery: {
+      revertOrNarrowScope: "恢复建议：撤回超出范围的变更，或更新任务契约以包含这些文件。",
+      runOrSkipCommands: "恢复建议：执行缺失的必需命令，或在证据中说明跳过原因。",
+      writeEvidenceFile: "恢复建议：创建必需的证据文件，记录已执行的操作和残余风险。",
+      revertOrAddReviewNotes: "恢复建议：撤回保护区域的变更，或添加详细的 review 说明。",
+      moveSecretsToEnv: "恢复建议：立即将检测到的密钥移至环境变量或密钥管理器。",
+      revertOrWidenContract: "恢复建议：撤回意外的改动类型变更，或更新任务契约。",
+      addTestsOrAcknowledge: "恢复建议：为变更的源码添加测试，或说明推迟测试的原因。"
     },
     roughIntent: {
       analyzing: "正在分析你的意图...",
@@ -649,6 +738,41 @@ const resources = {
       actionConfirm: "✅ 确认，继续",
       actionModify: "✏️ 修改范围",
       actionCancel: "❌ 取消"
+    },
+    daemon: {
+      starting: "正在启动守护进程...",
+      foregroundMode: "前台模式",
+      started: "✅ 守护进程启动成功！",
+      startFailed: "❌ 守护进程启动失败",
+      alreadyRunning: "守护进程已在运行中！",
+      stopping: "正在停止守护进程...",
+      stopped: "✅ 守护进程已停止。",
+      stopFailed: "❌ 停止守护进程失败",
+      notRunning: "守护进程未运行。",
+      status: "守护进程状态",
+      state: "状态",
+      running: "运行中",
+      config: "配置",
+      watchPaths: "监控路径",
+      checkInterval: "检查间隔",
+      blockOnHighRisk: "高风险时阻断",
+      commands: "命令",
+      startTime: "启动时间",
+      checksRun: "已运行检查",
+      lastCheck: "上次检查",
+      logFile: "日志文件",
+      configFile: "配置文件",
+      useStop: "使用 'agent-guardrails stop' 停止。",
+      useStatus: "使用 'agent-guardrails status' 查看状态。",
+      startDesc: "启动守护进程",
+      stopDesc: "停止守护进程",
+      statusDesc: "查看守护进程状态",
+      configUpdated: "✅ 守护进程配置已更新！",
+      startDescLong: "在后台启动守护进程",
+      stopDescLong: "停止守护进程",
+      statusDescLong: "显示守护进程状态和配置",
+      chokidarFallback: "chokidar 不可用，降级使用 fs.watch（部分平台可靠性较低）",
+      checkSkipped: "检查正在进行中，已跳过"
     }
   }
 };

package/lib/mcp/server.js

@@ -181,13 +181,13 @@ const TOOL_DEFINITIONS = [
         },
         mode: {
           type: "string",
-          enum": ["suggest", "auto", "strict"],
-          "description": "suggest = return suggestion for confirmation, auto = auto-accept if confidence >= 0.6, strict = always require confirmation"
+          enum: ["suggest", "auto", "strict"],
+          description: "suggest = return suggestion for confirmation, auto = auto-accept if confidence >= 0.6, strict = always require confirmation"
         },
         locale: {
           type: "string",
-          enum": ["en", "zh-CN"],
-          "description": "Language for the response text."
+          enum: ["en", "zh-CN"],
+          description: "Language for the response text."
         }
       },
       required: ["task"],

package/lib/runtime/service.js

@@ -748,10 +748,103 @@ export function prepareFinishCheck({ repoRoot, session = null, commandsRun = [],
   };
 }
 
+function buildCostHints(result) {
+  const totalFiles = (result.changedFiles || []).length;
+  const sourceFiles = (result.sourceFiles || []).length;
+  const hasErrors = result.findings.some((f) => f.severity === "error");
+  const hasWarnings = result.findings.some((f) => f.severity === "warning");
+
+  const lowEstimate = totalFiles * 50;
+  const highEstimate = sourceFiles * 1500 + (totalFiles - sourceFiles) * 200;
+
+  let sizeLevel;
+  if (totalFiles <= 3) {
+    sizeLevel = "Small";
+  } else if (totalFiles <= 8) {
+    sizeLevel = "Medium";
+  } else if (totalFiles <= 15) {
+    sizeLevel = "Large";
+  } else {
+    sizeLevel = "VeryLarge";
+  }
+
+  const entries = [];
+
+  entries.push({
+    key: `check.costSize${sizeLevel}`,
+    vars: { totalFiles, sourceFiles }
+  });
+
+  entries.push({
+    key: "check.costTokenEstimate",
+    vars: { low: formatTokens(lowEstimate), high: formatTokens(highEstimate) }
+  });
+
+  if (totalFiles > 8) {
+    entries.push({ key: "check.costLargeChangeWarning", vars: {} });
+  }
+
+  if (hasErrors || hasWarnings) {
+    const errorCount = result.findings.filter((f) => f.severity === "error").length;
+    const warningCount = result.findings.filter((f) => f.severity === "warning").length;
+    entries.push({
+      key: "check.costFixCostHint",
+      vars: { errorCount, warningCount }
+    });
+  }
+
+  return {
+    sizeLevel,
+    tokenEstimate: { low: lowEstimate, high: highEstimate },
+    entries
+  };
+}
+
+function formatTokens(count) {
+  if (count >= 1000) return `${Math.round(count / 1000)}k`;
+  return String(count);
+}
+
+const RECOVERY_MAP = {
+  "path-scope-violation": "recovery.revertOrNarrowScope",
+  "task-scope-violation": "recovery.revertOrNarrowScope",
+  "intended-file-violation": "recovery.revertOrNarrowScope",
+  "missing-required-commands": "recovery.runOrSkipCommands",
+  "missing-evidence": "recovery.writeEvidenceFile",
+  "protected-area-touched": "recovery.revertOrAddReviewNotes",
+  "secrets-safety": "recovery.moveSecretsToEnv",
+  "change-type-violation": "recovery.revertOrWidenContract",
+  "test-coverage-missing": "recovery.addTestsOrAcknowledge"
+};
+
+function buildRecoveryGuidance(result, t) {
+  const findings = result.findings || [];
+  const errorFindings = findings.filter((f) => f.severity === "error");
+  if (errorFindings.length === 0) return [];
+
+  const guidance = [];
+  const seen = new Set();
+
+  for (const finding of errorFindings) {
+    const key = RECOVERY_MAP[finding.code];
+    if (key && !seen.has(key)) {
+      seen.add(key);
+      guidance.push(t(key));
+    }
+  }
+
+  return guidance;
+}
+
 export function summarizeReviewRisks(result, locale = null) {
   const { t, locale: resolvedLocale } = createTranslator(locale ?? "en");
   const nextActions = [];
 
+  const recoveryGuidance = buildRecoveryGuidance(result, t);
+  if (recoveryGuidance.length > 0) {
+    nextActions.push(...recoveryGuidance);
+  }
+
   if (result.missingRequiredCommands.length > 0) {
     nextActions.push(t("runtime.reviewRunMissingCommands", { value: result.missingRequiredCommands.join(", ") }));
   }
@@ -935,6 +1028,7 @@ export function summarizeReviewRisks(result, locale = null) {
     verdict,
     deployReadiness,
     postDeployMaintenance,
+    costHints: buildCostHints(result),
     topRisks: [
       ...result.review.scopeIssues,
       ...result.review.validationIssues,

package/lib/utils.js

@@ -362,3 +362,16 @@ export function normalizeChangeType(value) {
 
   return normalized;
 }
+
+/**
+ * Read the agent-guardrails package.json version
+ */
+export function readOwnPackageJson() {
+  const packageJsonPath = path.join(import.meta.dirname, "..", "package.json");
+  try {
+    const content = fs.readFileSync(packageJsonPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return { version: "unknown", name: "agent-guardrails" };
+  }
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "agent-guardrails",
-  "version": "0.3.1",
+  "version": "0.3.3",
+  "mcpName": "io.github.logi-cmd/agent-guardrails",
   "description": "Production guardrails for AI coding agents",
   "type": "module",
   "files": [
@@ -46,12 +47,23 @@
     "ai",
     "agent",
     "guardrails",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "code-review",
+    "merge-gate",
     "cli",
     "developer-tools",
     "codex",
     "cursor",
     "claude-code",
-    "openhands"
+    "windsurf",
+    "openhands",
+    "ai-safety",
+    "llm-guardrails"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "optionalDependencies": {
+    "chokidar": "^3.6.0"
+  }
 }