agentflow-core 0.5.1 → 0.6.0

package/dist/cli.cjs

@@ -98,7 +98,6 @@ var import_path3 = require("path");
 // src/live.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
-var import_node_child_process = require("child_process");
 
 // src/graph-query.ts
 function getChildren(graph, nodeId) {
@@ -515,18 +514,20 @@ function processJsonFile(file) {
         const w = info;
         const status2 = findStatus(w);
         const ts2 = findTimestamp(w) || findTimestamp(obj) || file.mtime;
-        const pid = w.pid;
+        const rawPid = w.pid;
+        const pid = typeof rawPid === "number" ? rawPid : Number(rawPid);
+        const validPid = Number.isFinite(pid) && pid > 0;
         let validatedStatus = status2;
         let pidAlive = true;
-        if (pid && (status2 === "running" || status2 === "ok")) {
+        if (validPid && (status2 === "running" || status2 === "ok")) {
           try {
-            (0, import_node_child_process.execSync)(`kill -0 ${pid} 2>/dev/null`, { stdio: "ignore" });
+            process.kill(pid, 0);
           } catch {
             pidAlive = false;
             validatedStatus = "error";
           }
         }
-        const pidLabel = pid ? pidAlive ? `pid: ${pid}` : `pid: ${pid} (dead)` : "";
+        const pidLabel = validPid ? pidAlive ? `pid: ${pid}` : `pid: ${pid} (dead)` : "";
         const detail2 = pidLabel || extractDetail(w);
         records.push({
           id: name,
@@ -1013,11 +1014,14 @@ function render(config) {
   writeLine(L, `  ${C.dim}Press Ctrl+C to exit${C.reset}`);
   flushLines(L);
 }
-function getDistDepth(dt, spanId) {
+function getDistDepth(dt, spanId, visited) {
   if (!spanId) return 0;
+  const seen = visited ?? /* @__PURE__ */ new Set();
+  if (seen.has(spanId)) return 0;
+  seen.add(spanId);
   const g = dt.graphs.get(spanId);
   if (!g || !g.parentSpanId) return 0;
-  return 1 + getDistDepth(dt, g.parentSpanId);
+  return 1 + getDistDepth(dt, g.parentSpanId, seen);
 }
 function startLive(argv) {
   const config = parseArgs(argv);
@@ -1050,10 +1054,266 @@ function startLive(argv) {
   });
 }
 
-// src/runner.ts
-var import_node_child_process2 = require("child_process");
+// src/process-audit.ts
+var import_node_child_process = require("child_process");
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function pidMatchesName(pid, name) {
+  try {
+    const cmdline = (0, import_node_fs2.readFileSync)(`/proc/${pid}/cmdline`, "utf8");
+    return cmdline.includes(name);
+  } catch {
+    return false;
+  }
+}
+function readPidFile(path) {
+  try {
+    const pid = parseInt((0, import_node_fs2.readFileSync)(path, "utf8").trim(), 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+function auditPidFile(config) {
+  if (!config.pidFile) return null;
+  const pid = readPidFile(config.pidFile);
+  if (pid === null) {
+    return {
+      path: config.pidFile,
+      pid: null,
+      alive: false,
+      matchesProcess: false,
+      stale: !(0, import_node_fs2.existsSync)(config.pidFile),
+      reason: (0, import_node_fs2.existsSync)(config.pidFile) ? "PID file exists but content is invalid" : "No PID file found"
+    };
+  }
+  const alive = isPidAlive(pid);
+  const matchesProcess = alive ? pidMatchesName(pid, config.processName) : false;
+  const stale = !alive || alive && !matchesProcess;
+  let reason;
+  if (alive && matchesProcess) {
+    reason = `PID ${pid} alive and matches ${config.processName}`;
+  } else if (alive && !matchesProcess) {
+    reason = `PID ${pid} alive but is NOT ${config.processName} (PID reused by another process)`;
+  } else {
+    reason = `PID ${pid} no longer exists`;
+  }
+  return { path: config.pidFile, pid, alive, matchesProcess, stale, reason };
+}
+function auditSystemd(config) {
+  if (config.systemdUnit === null || config.systemdUnit === void 0) return null;
+  const unit = config.systemdUnit;
+  try {
+    const raw = (0, import_node_child_process.execSync)(
+      `systemctl --user show ${unit} --property=ActiveState,SubState,MainPID,NRestarts,Result --no-pager 2>/dev/null`,
+      { encoding: "utf8", timeout: 5e3 }
+    );
+    const props = {};
+    for (const line of raw.trim().split("\n")) {
+      const [k, ...v] = line.split("=");
+      if (k) props[k.trim()] = v.join("=").trim();
+    }
+    const activeState = props["ActiveState"] ?? "unknown";
+    const subState = props["SubState"] ?? "unknown";
+    const mainPid = parseInt(props["MainPID"] ?? "0", 10);
+    const restarts = parseInt(props["NRestarts"] ?? "0", 10);
+    const result = props["Result"] ?? "unknown";
+    return {
+      unit,
+      activeState,
+      subState,
+      mainPid,
+      restarts,
+      result,
+      crashLooping: activeState === "activating" && subState === "auto-restart",
+      failed: activeState === "failed"
+    };
+  } catch {
+    return null;
+  }
+}
+function auditWorkers(config) {
+  if (!config.workersFile || !(0, import_node_fs2.existsSync)(config.workersFile)) return null;
+  try {
+    const data = JSON.parse((0, import_node_fs2.readFileSync)(config.workersFile, "utf8"));
+    const orchPid = data.pid ?? null;
+    const orchAlive = orchPid ? isPidAlive(orchPid) : false;
+    const workers = [];
+    for (const [name, info] of Object.entries(data.tools ?? {})) {
+      const w = info;
+      const wPid = w.pid ?? null;
+      const wAlive = wPid ? isPidAlive(wPid) : false;
+      workers.push({
+        name,
+        pid: wPid,
+        declaredStatus: w.status ?? "unknown",
+        alive: wAlive,
+        stale: w.status === "running" && !wAlive
+      });
+    }
+    return {
+      orchestratorPid: orchPid,
+      orchestratorAlive: orchAlive,
+      startedAt: data.started_at ?? "",
+      workers
+    };
+  } catch {
+    return null;
+  }
+}
+function getOsProcesses(processName) {
+  try {
+    const raw = (0, import_node_child_process.execSync)(`ps aux`, { encoding: "utf8", timeout: 5e3 });
+    return raw.split("\n").filter((line) => line.includes(processName) && !line.includes("process-audit") && !line.includes("grep")).map((line) => {
+      const parts = line.trim().split(/\s+/);
+      return {
+        pid: parseInt(parts[1] ?? "0", 10),
+        cpu: parts[2] ?? "0",
+        mem: parts[3] ?? "0",
+        command: parts.slice(10).join(" ")
+      };
+    }).filter((p) => !isNaN(p.pid) && p.pid > 0);
+  } catch {
+    return [];
+  }
+}
+function discoverProcessConfig(dirs) {
+  let pidFile;
+  let workersFile;
+  let processName = "";
+  for (const dir of dirs) {
+    if (!(0, import_node_fs2.existsSync)(dir)) continue;
+    let entries;
+    try {
+      entries = (0, import_node_fs2.readdirSync)(dir);
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      const fp = (0, import_node_path2.join)(dir, f);
+      try {
+        if (!(0, import_node_fs2.statSync)(fp).isFile()) continue;
+      } catch {
+        continue;
+      }
+      if (f.endsWith(".pid") && !pidFile) {
+        pidFile = fp;
+        if (!processName) {
+          processName = (0, import_node_path2.basename)(f, ".pid");
+        }
+      }
+      if ((f === "workers.json" || f.endsWith("-workers.json")) && !workersFile) {
+        workersFile = fp;
+        if (!processName && f !== "workers.json") {
+          processName = (0, import_node_path2.basename)(f, "-workers.json");
+        }
+      }
+    }
+  }
+  if (!processName && !pidFile && !workersFile) return null;
+  if (!processName) processName = "agent";
+  return { processName, pidFile, workersFile };
+}
+function auditProcesses(config) {
+  const pidFile = auditPidFile(config);
+  const systemd = auditSystemd(config);
+  const workers = auditWorkers(config);
+  const osProcesses = getOsProcesses(config.processName);
+  const knownPids = /* @__PURE__ */ new Set();
+  if (pidFile?.pid && !pidFile.stale) knownPids.add(pidFile.pid);
+  if (workers) {
+    if (workers.orchestratorPid) knownPids.add(workers.orchestratorPid);
+    for (const w of workers.workers) {
+      if (w.pid) knownPids.add(w.pid);
+    }
+  }
+  if (systemd?.mainPid) knownPids.add(systemd.mainPid);
+  const orphans = osProcesses.filter((p) => !knownPids.has(p.pid));
+  const problems = [];
+  if (pidFile?.stale) problems.push(`Stale PID file: ${pidFile.reason}`);
+  if (systemd?.crashLooping) problems.push("Systemd unit is crash-looping (auto-restart)");
+  if (systemd?.failed) problems.push("Systemd unit has failed");
+  if (systemd && systemd.restarts > 10) problems.push(`High systemd restart count: ${systemd.restarts}`);
+  if (pidFile?.pid && systemd?.mainPid && pidFile.pid !== systemd.mainPid) {
+    problems.push(`PID mismatch: file says ${pidFile.pid}, systemd says ${systemd.mainPid}`);
+  }
+  if (workers) {
+    for (const w of workers.workers) {
+      if (w.stale) problems.push(`Worker "${w.name}" (pid ${w.pid}) declares running but is dead`);
+    }
+  }
+  if (orphans.length > 0) problems.push(`${orphans.length} orphan process(es) not tracked by PID file or workers registry`);
+  return { pidFile, systemd, workers, osProcesses, orphans, problems };
+}
+function formatAuditReport(result) {
+  const lines = [];
+  lines.push("");
+  lines.push("\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557");
+  lines.push("\u2551            \u{1F50D}  P R O C E S S   A U D I T                      \u2551");
+  lines.push("\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D");
+  if (result.pidFile) {
+    const pf = result.pidFile;
+    const icon = pf.pid && pf.alive && pf.matchesProcess ? "\u2705" : pf.stale ? "\u26A0\uFE0F " : "\u2139\uFE0F ";
+    lines.push(`
+  PID File: ${pf.path}`);
+    lines.push(`  ${icon} ${pf.reason}`);
+  }
+  if (result.systemd) {
+    const sd = result.systemd;
+    const icon = sd.activeState === "active" ? "\u{1F7E2}" : sd.crashLooping ? "\u{1F7E1}" : sd.failed ? "\u{1F534}" : "\u26AA";
+    lines.push(`
+  Systemd: ${sd.unit}`);
+    lines.push(`  ${icon} State: ${sd.activeState} (${sd.subState})  Result: ${sd.result}`);
+    lines.push(`     Main PID: ${sd.mainPid || "none"}  Restarts: ${sd.restarts}`);
+  }
+  if (result.workers) {
+    const w = result.workers;
+    lines.push(`
+  Workers (orchestrator pid ${w.orchestratorPid ?? "unknown"} ${w.orchestratorAlive ? "\u2705" : "\u274C"})`);
+    for (const worker of w.workers) {
+      const icon = worker.declaredStatus === "running" && worker.alive ? "\u{1F7E2}" : worker.stale ? "\u{1F534} STALE" : "\u26AA";
+      lines.push(`  ${icon}  ${worker.name.padEnd(14)} pid=${String(worker.pid ?? "-").padEnd(8)} status=${worker.declaredStatus}`);
+    }
+  }
+  if (result.osProcesses.length > 0) {
+    lines.push(`
+  OS Processes (${result.osProcesses.length} total)`);
+    for (const p of result.osProcesses) {
+      lines.push(`    PID ${String(p.pid).padEnd(8)} CPU=${p.cpu.padEnd(6)} MEM=${p.mem.padEnd(6)} ${p.command.substring(0, 55)}`);
+    }
+  }
+  if (result.orphans.length > 0) {
+    lines.push(`
+  \u26A0\uFE0F  ${result.orphans.length} ORPHAN PROCESS(ES):`);
+    for (const p of result.orphans) {
+      lines.push(`     PID ${p.pid} \u2014 not tracked by PID file or workers registry`);
+    }
+  }
+  lines.push("");
+  if (result.problems.length === 0) {
+    lines.push("  \u2705 All checks passed \u2014 no process issues detected.");
+  } else {
+    lines.push(`  \u26A0\uFE0F  ${result.problems.length} issue(s):`);
+    for (const p of result.problems) {
+      lines.push(`     \u2022 ${p}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/runner.ts
+var import_node_child_process2 = require("child_process");
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
 
 // src/graph-builder.ts
 var import_crypto = require("crypto");
@@ -1289,12 +1549,12 @@ function globToRegex(pattern) {
 }
 function snapshotDir(dir, patterns) {
   const result = /* @__PURE__ */ new Map();
-  if (!(0, import_node_fs2.existsSync)(dir)) return result;
-  for (const entry of (0, import_node_fs2.readdirSync)(dir)) {
+  if (!(0, import_node_fs3.existsSync)(dir)) return result;
+  for (const entry of (0, import_node_fs3.readdirSync)(dir)) {
     if (!patterns.some((re) => re.test(entry))) continue;
-    const full = (0, import_node_path2.join)(dir, entry);
+    const full = (0, import_node_path3.join)(dir, entry);
     try {
-      const stat = (0, import_node_fs2.statSync)(full);
+      const stat = (0, import_node_fs3.statSync)(full);
       if (stat.isFile()) {
         result.set(full, stat.mtimeMs);
       }
@@ -1304,7 +1564,7 @@ function snapshotDir(dir, patterns) {
   return result;
 }
 function agentIdFromFilename(filePath) {
-  const base = (0, import_node_path2.basename)(filePath, ".json");
+  const base = (0, import_node_path3.basename)(filePath, ".json");
   const cleaned = base.replace(/-state$/, "");
   return `alfred-${cleaned}`;
 }
@@ -1326,7 +1586,7 @@ async function runTraced(config) {
   if (command.length === 0) {
     throw new Error("runTraced: command must not be empty");
   }
-  const resolvedTracesDir = (0, import_node_path2.resolve)(tracesDir);
+  const resolvedTracesDir = (0, import_node_path3.resolve)(tracesDir);
   const patterns = watchPatterns.map(globToRegex);
   const orchestrator = createGraphBuilder({ agentId, trigger });
   const { traceId, spanId } = orchestrator.traceContext;
@@ -1409,15 +1669,19 @@ async function runTraced(config) {
     childBuilder.endNode(childRootId);
     allGraphs.push(childBuilder.build());
   }
-  if (!(0, import_node_fs2.existsSync)(resolvedTracesDir)) {
-    (0, import_node_fs2.mkdirSync)(resolvedTracesDir, { recursive: true });
+  if (!(0, import_node_fs3.existsSync)(resolvedTracesDir)) {
+    (0, import_node_fs3.mkdirSync)(resolvedTracesDir, { recursive: true });
   }
   const ts = fileTimestamp();
   const tracePaths = [];
   for (const graph of allGraphs) {
     const filename = `${graph.agentId}-${ts}.json`;
-    const outPath = (0, import_node_path2.join)(resolvedTracesDir, filename);
-    (0, import_node_fs2.writeFileSync)(outPath, JSON.stringify(graphToJson(graph), null, 2), "utf-8");
+    const outPath = (0, import_node_path3.join)(resolvedTracesDir, filename);
+    const resolvedOut = (0, import_node_path3.resolve)(outPath);
+    if (!resolvedOut.startsWith(resolvedTracesDir + "/") && resolvedOut !== resolvedTracesDir) {
+      throw new Error(`Path traversal detected: agentId "${graph.agentId}" escapes traces directory`);
+    }
+    (0, import_node_fs3.writeFileSync)(outPath, JSON.stringify(graphToJson(graph), null, 2), "utf-8");
     tracePaths.push(outPath);
   }
   if (tracePaths.length > 0) {
@@ -1469,6 +1733,11 @@ function createTraceStore(dir) {
       await ensureDir();
       const json = graphToJson(graph);
       const filePath = (0, import_path.join)(dir, `${graph.id}.json`);
+      const resolvedBase = (0, import_path.resolve)(dir);
+      const resolvedPath = (0, import_path.resolve)(filePath);
+      if (!resolvedPath.startsWith(resolvedBase + "/") && resolvedPath !== resolvedBase) {
+        throw new Error(`Path traversal detected: "${graph.id}" escapes base directory`);
+      }
       await (0, import_promises.writeFile)(filePath, JSON.stringify(json, null, 2), "utf-8");
       return filePath;
     },
@@ -1742,11 +2011,11 @@ async function traceShow(argv) {
   let graph = await store.get(graphId);
   if (!graph) {
     const { readFile: readFile2 } = await import("fs/promises");
-    const { join: join5 } = await import("path");
+    const { join: join6 } = await import("path");
     const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
     try {
       const { loadGraph: loadGraph2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
-      const content = await readFile2(join5(dir, fname), "utf-8");
+      const content = await readFile2(join6(dir, fname), "utf-8");
       graph = loadGraph2(content);
     } catch {
     }
@@ -1771,11 +2040,11 @@ async function traceTimeline(argv) {
   let graph = await store.get(graphId);
   if (!graph) {
     const { readFile: readFile2 } = await import("fs/promises");
-    const { join: join5 } = await import("path");
+    const { join: join6 } = await import("path");
     const fname = graphId.endsWith(".json") ? graphId : `${graphId}.json`;
     try {
       const { loadGraph: loadGraph2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
-      const content = await readFile2(join5(dir, fname), "utf-8");
+      const content = await readFile2(join6(dir, fname), "utf-8");
       graph = loadGraph2(content);
     } catch {
     }
@@ -1856,9 +2125,9 @@ async function handleTrace(argv) {
 }
 
 // src/watch.ts
-var import_node_fs4 = require("fs");
+var import_node_fs5 = require("fs");
 var import_node_os = require("os");
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 
 // src/watch-alerts.ts
 var import_node_child_process3 = require("child_process");
@@ -1916,7 +2185,7 @@ function sendTelegram(payload, botToken, chatId) {
     text: formatTelegram(payload),
     parse_mode: "Markdown"
   });
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const req = (0, import_node_https.request)(
       `https://api.telegram.org/bot${botToken}/sendMessage`,
       {
@@ -1925,7 +2194,7 @@ function sendTelegram(payload, botToken, chatId) {
       },
       (res) => {
         res.resume();
-        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve6();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve7();
         else reject(new Error(`Telegram API returned ${res.statusCode}`));
       }
     );
@@ -1938,7 +2207,7 @@ function sendWebhook(payload, url) {
   const body = JSON.stringify(payload);
   const isHttps = url.startsWith("https");
   const doRequest = isHttps ? import_node_https.request : import_node_http.request;
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const req = doRequest(
       url,
       {
@@ -1947,7 +2216,7 @@ function sendWebhook(payload, url) {
       },
       (res) => {
         res.resume();
-        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve6();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve7();
         else reject(new Error(`Webhook returned ${res.statusCode}`));
       }
     );
@@ -1960,7 +2229,7 @@ function sendWebhook(payload, url) {
   });
 }
 function sendCommand(payload, cmd) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const env = {
       ...process.env,
       AGENTFLOW_ALERT_AGENT: payload.agentId,
@@ -1973,13 +2242,13 @@ function sendCommand(payload, cmd) {
     };
     (0, import_node_child_process3.exec)(cmd, { env, timeout: 3e4 }, (err) => {
       if (err) reject(err);
-      else resolve6();
+      else resolve7();
     });
   });
 }
 
 // src/watch-state.ts
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 function parseDuration(input) {
   const match = input.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
   if (!match) {
@@ -2004,9 +2273,9 @@ function emptyState() {
   return { version: 1, agents: {}, lastPollTime: 0 };
 }
 function loadWatchState(filePath) {
-  if (!(0, import_node_fs3.existsSync)(filePath)) return emptyState();
+  if (!(0, import_node_fs4.existsSync)(filePath)) return emptyState();
   try {
-    const raw = JSON.parse((0, import_node_fs3.readFileSync)(filePath, "utf8"));
+    const raw = JSON.parse((0, import_node_fs4.readFileSync)(filePath, "utf8"));
     if (raw.version !== 1 || typeof raw.agents !== "object") return emptyState();
     return raw;
   } catch {
@@ -2016,11 +2285,11 @@ function loadWatchState(filePath) {
 function saveWatchState(filePath, state) {
   const tmp = filePath + ".tmp";
   try {
-    (0, import_node_fs3.writeFileSync)(tmp, JSON.stringify(state, null, 2), "utf8");
-    (0, import_node_fs3.renameSync)(tmp, filePath);
+    (0, import_node_fs4.writeFileSync)(tmp, JSON.stringify(state, null, 2), "utf8");
+    (0, import_node_fs4.renameSync)(tmp, filePath);
   } catch {
     try {
-      (0, import_node_fs3.writeFileSync)(filePath, JSON.stringify(state, null, 2), "utf8");
+      (0, import_node_fs4.writeFileSync)(filePath, JSON.stringify(state, null, 2), "utf8");
     } catch {
     }
   }
@@ -2248,20 +2517,20 @@ function parseWatchArgs(argv) {
       recursive = true;
       i++;
     } else if (!arg.startsWith("-")) {
-      dirs.push((0, import_node_path3.resolve)(arg));
+      dirs.push((0, import_node_path4.resolve)(arg));
       i++;
     } else {
       i++;
     }
   }
-  if (dirs.length === 0) dirs.push((0, import_node_path3.resolve)("."));
+  if (dirs.length === 0) dirs.push((0, import_node_path4.resolve)("."));
   if (alertConditions.length === 0) {
     alertConditions.push({ type: "error" });
     alertConditions.push({ type: "recovery" });
   }
   notifyChannels.unshift({ type: "stdout" });
   if (!stateFilePath) {
-    stateFilePath = (0, import_node_path3.join)(dirs[0], ".agentflow-watch-state.json");
+    stateFilePath = (0, import_node_path4.join)(dirs[0], ".agentflow-watch-state.json");
   }
   return {
     dirs,
@@ -2269,7 +2538,7 @@ function parseWatchArgs(argv) {
     pollIntervalMs,
     alertConditions,
     notifyChannels,
-    stateFilePath: (0, import_node_path3.resolve)(stateFilePath),
+    stateFilePath: (0, import_node_path4.resolve)(stateFilePath),
     cooldownMs
   };
 }
@@ -2323,12 +2592,12 @@ Examples:
 }
 function startWatch(argv) {
   const config = parseWatchArgs(argv);
-  const valid = config.dirs.filter((d) => (0, import_node_fs4.existsSync)(d));
+  const valid = config.dirs.filter((d) => (0, import_node_fs5.existsSync)(d));
   if (valid.length === 0) {
     console.error(`No valid directories found: ${config.dirs.join(", ")}`);
     process.exit(1);
   }
-  const invalid = config.dirs.filter((d) => !(0, import_node_fs4.existsSync)(d));
+  const invalid = config.dirs.filter((d) => !(0, import_node_fs5.existsSync)(d));
   if (invalid.length > 0) {
     console.warn(`Skipping non-existent: ${invalid.join(", ")}`);
   }
@@ -2366,9 +2635,17 @@ agentflow watch started`);
       records.push(...recs);
     }
     const alerts = detectTransitions(state, records, config, now);
-    for (const alert of alerts) {
-      for (const channel of config.notifyChannels) {
-        await sendAlert(alert, channel);
+    const isBootstrap = pollCount === 1 && Object.keys(state.agents).length === 0;
+    if (isBootstrap) {
+      const suppressed = alerts.length;
+      if (suppressed > 0) {
+        console.log(`[bootstrap] Suppressed ${suppressed} initial alerts (baseline scan)`);
+      }
+    } else {
+      for (const alert of alerts) {
+        for (const channel of config.notifyChannels) {
+          await sendAlert(alert, channel);
+        }
       }
     }
     state = updateWatchState(state, records, alerts, now);
@@ -2412,6 +2689,7 @@ Commands:
   live   [dir...] [options]      Real-time terminal monitor (auto-detects any JSON/JSONL)
   watch  [dir...] [options]      Headless alert system \u2014 detects failures, sends notifications
   trace  <command> [options]     Inspect saved execution traces (list, show, timeline, stuck, loops)
+  audit  [options]               Audit OS processes \u2014 detect stale PIDs, orphans, systemd issues
 
 Run \`agentflow <command> --help\` for command-specific options.
 
@@ -2563,9 +2841,102 @@ async function runCommand(argv) {
     process.exit(1);
   }
 }
+function parseAuditArgs(argv) {
+  let processName = "";
+  let pidFile;
+  let workersFile;
+  let systemdUnit;
+  const discoverDirs = [];
+  const args = argv.slice(0);
+  if (args[0] === "audit") args.shift();
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      printAuditUsage();
+      process.exit(0);
+    } else if (arg === "--process" || arg === "-p") {
+      i++;
+      processName = args[i] ?? "";
+      i++;
+    } else if (arg === "--pid-file") {
+      i++;
+      pidFile = args[i];
+      i++;
+    } else if (arg === "--workers-file") {
+      i++;
+      workersFile = args[i];
+      i++;
+    } else if (arg === "--systemd") {
+      i++;
+      systemdUnit = args[i];
+      i++;
+    } else if (arg === "--no-systemd") {
+      systemdUnit = null;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      discoverDirs.push((0, import_path3.resolve)(arg));
+      i++;
+    } else {
+      i++;
+    }
+  }
+  if (!processName && !pidFile && !workersFile && discoverDirs.length > 0) {
+    const discovered = discoverProcessConfig(discoverDirs);
+    if (discovered) {
+      console.log(`Auto-discovered: process="${discovered.processName}"${discovered.pidFile ? ` pid-file=${discovered.pidFile}` : ""}${discovered.workersFile ? ` workers=${discovered.workersFile}` : ""}`);
+      return { ...discovered, systemdUnit };
+    }
+  }
+  if (!processName) {
+    console.error("Error: --process <name> is required, or provide directories for auto-discovery.");
+    console.error("Examples:");
+    console.error("  agentflow audit --process alfred --pid-file ./data/alfred.pid");
+    console.error("  agentflow audit ./data    # auto-discovers *.pid and workers.json");
+    process.exit(1);
+  }
+  return { processName, pidFile, workersFile, systemdUnit };
+}
+function printAuditUsage() {
+  console.log(
+    `
+AgentFlow Audit \u2014 OS-level process health check for agent systems.
+
+Detects stale PID files, orphan processes, systemd crash loops, and
+mismatches between declared state and actual OS process state.
+
+Usage:
+  agentflow audit [dir...] [options]
+  agentflow audit --process <name> [options]
+
+Arguments:
+  dir                         Directories to scan for auto-discovery of *.pid and workers.json
+
+Options:
+  -p, --process <name>        Process name to search for (e.g. "alfred", "myagent")
+  --pid-file <path>           Path to PID file
+  --workers-file <path>       Path to workers.json or process registry
+  --systemd <unit>            Systemd user unit name (e.g. "alfred.service")
+  --no-systemd                Skip systemd checks
+  -h, --help                  Show this help message
+
+Examples:
+  agentflow audit ./data                          # auto-discover from data directory
+  agentflow audit --process alfred --systemd alfred.service
+  agentflow audit --process myagent --pid-file /var/run/myagent.pid --workers-file ./workers.json
+  agentflow audit --process crewai --no-systemd
+`.trim()
+  );
+}
+function runAudit(argv) {
+  const config = parseAuditArgs(argv);
+  const result = auditProcesses(config);
+  console.log(formatAuditReport(result));
+  process.exit(result.problems.length > 0 ? 1 : 0);
+}
 async function main() {
   const argv = process.argv.slice(2);
-  const knownCommands = ["run", "live", "watch", "trace"];
+  const knownCommands = ["run", "live", "watch", "trace", "audit"];
   if (argv.length === 0 || !knownCommands.includes(argv[0]) && (argv.includes("--help") || argv.includes("-h"))) {
     printHelp();
     process.exit(0);
@@ -2584,6 +2955,9 @@ async function main() {
     case "trace":
       await handleTrace(argv);
       break;
+    case "audit":
+      runAudit(argv);
+      break;
     default:
       if (!subcommand?.startsWith("-")) {
         startLive(["live", ...argv]);