agentflow-core 0.5.2 → 0.6.0

package/dist/index.cjs

@@ -20,10 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  auditProcesses: () => auditProcesses,
   checkGuards: () => checkGuards,
   createGraphBuilder: () => createGraphBuilder,
   createTraceStore: () => createTraceStore,
+  discoverProcessConfig: () => discoverProcessConfig,
   findWaitingOn: () => findWaitingOn,
+  formatAuditReport: () => formatAuditReport,
   getChildren: () => getChildren,
   getCriticalPath: () => getCriticalPath,
   getDepth: () => getDepth,
@@ -638,7 +641,6 @@ function withGuards(builder, config) {
 // src/live.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
-var import_node_child_process = require("child_process");
 
 // src/loader.ts
 function toNodesMap(raw) {
@@ -963,18 +965,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,
@@ -1461,11 +1465,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);
@@ -1498,22 +1505,278 @@ 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");
 function globToRegex(pattern) {
   const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
   return new RegExp(`^${escaped}$`);
 }
 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);
       }
@@ -1523,7 +1786,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}`;
 }
@@ -1545,7 +1808,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;
@@ -1628,15 +1891,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) {
@@ -1684,6 +1951,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;
     },
@@ -1882,9 +2154,9 @@ function toTimeline(graph) {
 }
 
 // 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");
@@ -1942,7 +2214,7 @@ function sendTelegram(payload, botToken, chatId) {
     text: formatTelegram(payload),
     parse_mode: "Markdown"
   });
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const req = (0, import_node_https.request)(
       `https://api.telegram.org/bot${botToken}/sendMessage`,
       {
@@ -1951,7 +2223,7 @@ function sendTelegram(payload, botToken, chatId) {
       },
       (res) => {
         res.resume();
-        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve4();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve5();
         else reject(new Error(`Telegram API returned ${res.statusCode}`));
       }
     );
@@ -1964,7 +2236,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((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const req = doRequest(
       url,
       {
@@ -1973,7 +2245,7 @@ function sendWebhook(payload, url) {
       },
       (res) => {
         res.resume();
-        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve4();
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) resolve5();
         else reject(new Error(`Webhook returned ${res.statusCode}`));
       }
     );
@@ -1986,7 +2258,7 @@ function sendWebhook(payload, url) {
   });
 }
 function sendCommand(payload, cmd) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const env = {
       ...process.env,
       AGENTFLOW_ALERT_AGENT: payload.agentId,
@@ -1999,13 +2271,13 @@ function sendCommand(payload, cmd) {
     };
     (0, import_node_child_process3.exec)(cmd, { env, timeout: 3e4 }, (err) => {
       if (err) reject(err);
-      else resolve4();
+      else resolve5();
     });
   });
 }
 
 // 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) {
@@ -2030,9 +2302,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 {
@@ -2042,11 +2314,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 {
     }
   }
@@ -2274,20 +2546,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,
@@ -2295,7 +2567,7 @@ function parseWatchArgs(argv) {
     pollIntervalMs,
     alertConditions,
     notifyChannels,
-    stateFilePath: (0, import_node_path3.resolve)(stateFilePath),
+    stateFilePath: (0, import_node_path4.resolve)(stateFilePath),
     cooldownMs
   };
 }
@@ -2349,12 +2621,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(", ")}`);
   }
@@ -2433,10 +2705,13 @@ agentflow watch started`);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  auditProcesses,
   checkGuards,
   createGraphBuilder,
   createTraceStore,
+  discoverProcessConfig,
   findWaitingOn,
+  formatAuditReport,
   getChildren,
   getCriticalPath,
   getDepth,

package/dist/index.d.cts

@@ -494,6 +494,114 @@ declare function withGuards(builder: GraphBuilder, config?: GuardConfig): GraphB
 
 declare function startLive(argv: string[]): void;
 
+/**
+ * AgentFlow Process Audit — OS-level process health checks for agent systems.
+ *
+ * Detects stale PID files, orphan processes, systemd unit issues,
+ * and mismatches between declared state (PID files, workers.json)
+ * and actual OS process state.
+ *
+ * Linux-only (reads /proc). Returns structured results for programmatic
+ * use or terminal display.
+ *
+ * @module
+ */
+interface PidFileResult {
+    path: string;
+    pid: number | null;
+    alive: boolean;
+    /** Whether /proc/<pid>/cmdline contains the expected process name. */
+    matchesProcess: boolean;
+    stale: boolean;
+    reason: string;
+}
+interface SystemdUnitResult {
+    unit: string;
+    activeState: string;
+    subState: string;
+    mainPid: number;
+    restarts: number;
+    result: string;
+    crashLooping: boolean;
+    failed: boolean;
+}
+interface WorkerEntry {
+    name: string;
+    pid: number | null;
+    declaredStatus: string;
+    alive: boolean;
+    stale: boolean;
+}
+interface WorkersResult {
+    orchestratorPid: number | null;
+    orchestratorAlive: boolean;
+    startedAt: string;
+    workers: WorkerEntry[];
+}
+interface OsProcess {
+    pid: number;
+    cpu: string;
+    mem: string;
+    command: string;
+}
+interface ProcessAuditResult {
+    pidFile: PidFileResult | null;
+    systemd: SystemdUnitResult | null;
+    workers: WorkersResult | null;
+    osProcesses: OsProcess[];
+    orphans: OsProcess[];
+    problems: string[];
+}
+interface ProcessAuditConfig {
+    /** Path to the PID file (e.g. /home/user/.myapp/data/app.pid). */
+    pidFile?: string;
+    /** Path to workers.json or equivalent process registry. */
+    workersFile?: string;
+    /** Systemd unit name (e.g. "myapp.service"). Use `null` to skip. */
+    systemdUnit?: string | null;
+    /** Process name to match in `pgrep -a` and /proc/cmdline (e.g. "alfred", "myagent"). */
+    processName: string;
+}
+/**
+ * Scan directories for PID files (`*.pid`), worker registries (`workers.json`,
+ * `*-workers.json`), and infer a process name from the PID file name.
+ *
+ * Returns a config suitable for `auditProcesses()`, or null if nothing found.
+ *
+ * @example
+ * ```ts
+ * const config = discoverProcessConfig(['./data', '/var/run/myagent']);
+ * if (config) console.log(formatAuditReport(auditProcesses(config)));
+ * ```
+ */
+declare function discoverProcessConfig(dirs: string[]): ProcessAuditConfig | null;
+/**
+ * Run a full process health audit.
+ *
+ * Checks PID files, systemd units, worker registries, and OS process tables
+ * to detect stale processes, orphans, and state mismatches.
+ *
+ * @example
+ * ```ts
+ * import { auditProcesses, formatAuditReport } from 'agentflow-core';
+ *
+ * const result = auditProcesses({
+ *   processName: 'alfred',
+ *   pidFile: '/home/user/.alfred/data/alfred.pid',
+ *   workersFile: '/home/user/.alfred/data/workers.json',
+ *   systemdUnit: 'alfred.service',
+ * });
+ *
+ * console.log(formatAuditReport(result));
+ * ```
+ */
+declare function auditProcesses(config: ProcessAuditConfig): ProcessAuditResult;
+/**
+ * Format an audit result as a human-readable terminal report.
+ * Uses Unicode box-drawing characters and status icons.
+ */
+declare function formatAuditReport(result: ProcessAuditResult): string;
+
 /**
  * Load and deserialize execution graphs from JSON.
  *
@@ -743,4 +851,4 @@ interface AlertPayload {
     readonly dirs: readonly string[];
 }
 
-export { type Adapter, type AgentFlowConfig, type AlertCondition, type AlertPayload, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type RunConfig, type RunResult, type StartNodeOptions, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type Writer, checkGuards, createGraphBuilder, createTraceStore, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };
+export { type Adapter, type AgentFlowConfig, type AlertCondition, type AlertPayload, type DistributedTrace, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type GuardConfig, type GuardViolation, type MutableExecutionNode, type NodeStatus, type NodeType, type NotifyChannel, type OsProcess, type PidFileResult, type ProcessAuditConfig, type ProcessAuditResult, type RunConfig, type RunResult, type StartNodeOptions, type SystemdUnitResult, type TraceEvent, type TraceEventType, type TraceStore, type WatchConfig, type WorkerEntry, type WorkersResult, type Writer, auditProcesses, checkGuards, createGraphBuilder, createTraceStore, discoverProcessConfig, findWaitingOn, formatAuditReport, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree, getTraceTree, graphToJson, groupByTraceId, loadGraph, runTraced, startLive, startWatch, stitchTrace, toAsciiTree, toTimeline, withGuards };