agent-guardrails 0.3.1 → 0.3.4

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,278 @@
+/**
+ * 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");
+
+        // 保存结构化结果供 MCP 读取
+        try {
+          const resultFile = path.join(repoRoot, ".agent-guardrails", "daemon-result.json");
+          const dir = path.dirname(resultFile);
+          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(resultFile, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            ok: !!ok,
+            result
+          }, null, 2));
+        } catch { /* ignore */ }
+      })
+      .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

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { executeCheck } from "../commands/check.js";
 import {
   finishAgentNativeLoop,
@@ -181,18 +183,32 @@ 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"],
       additionalProperties: false
     }
+  },
+  {
+    name: "read_daemon_status",
+    description: "Read the latest daemon check result and status. Returns daemon running state, check count, and the structured result of the most recent guardrail check. Call this after code changes to check if the daemon detected any issues.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the repository root."
+        }
+      },
+      additionalProperties: false
+    }
   }
 ];
 
@@ -428,6 +444,35 @@ async function callTool(name, args, defaultRepoRoot) {
     });
   }
 
+  if (name === "read_daemon_status") {
+    const repoRoot = args.repoRoot || defaultRepoRoot;
+    const { isDaemonRunning, getDaemonConfig } = await import("../commands/daemon.js");
+    const status = isDaemonRunning(repoRoot);
+    const config = getDaemonConfig(repoRoot);
+
+    const resultPath = path.join(repoRoot, ".agent-guardrails", "daemon-result.json");
+    let lastResult = null;
+    try {
+      if (fs.existsSync(resultPath)) {
+        lastResult = JSON.parse(fs.readFileSync(resultPath, "utf8"));
+      }
+    } catch { /* ignore */ }
+
+    return createJsonResult({
+      running: status.running,
+      pid: status.pid || null,
+      startTime: status.startTime || null,
+      checksRun: status.checksRun || 0,
+      lastCheck: status.lastCheck || null,
+      config: {
+        watchPaths: config.watchPaths,
+        checkInterval: config.checkInterval,
+        blockOnHighRisk: config.blockOnHighRisk
+      },
+      lastResult
+    });
+  }
+
   throw createError(-32601, `Unknown tool "${name}".`);
 }
 

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.4",
+  "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"
+  }
 }