bgrun 3.10.2 → 3.11.0

package/dist/index.js

@@ -27,7 +27,7 @@ function getHomeDir() {
 async function isProcessRunning(pid, command) {
   if (pid <= 0)
     return false;
-  return plat.measure(`PID ${pid} alive?`, async () => {
+  return await plat.measure(`PID ${pid} alive?`, async () => {
     try {
       if (command && (command.includes("docker run") || command.includes("docker-compose up") || command.includes("docker compose up"))) {
         return await isDockerContainerRunning(command);
@@ -42,7 +42,7 @@ async function isProcessRunning(pid, command) {
     } catch {
       return false;
     }
-  });
+  }) ?? false;
 }
 async function isDockerContainerRunning(command) {
   try {
@@ -155,6 +155,8 @@ async function killProcessOnPort(port) {
         if (alive) {
           await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
           console.log(`Killed process ${pid} using port ${port}`);
+        } else {
+          console.warn(`\u26A0 Port ${port} held by zombie PID ${pid} (process dead, socket stuck in kernel). Will clear on reboot or TCP timeout.`);
         }
       }
     } else {
@@ -210,7 +212,7 @@ async function findChildPid(parentPid) {
   return currentPid;
 }
 async function readFileTail(filePath, lines) {
-  return plat.measure(`Read tail ${lines ?? "all"}L`, async () => {
+  return await plat.measure(`Read tail ${lines ?? "all"}L`, async () => {
     try {
       const content = await Bun.file(filePath).text();
       if (!lines) {
@@ -223,17 +225,17 @@ async function readFileTail(filePath, lines) {
     } catch (error) {
       throw new Error(`Error reading file: ${error}`);
     }
-  });
+  }) ?? "";
 }
-async function getProcessBatchMemory(pids) {
+async function getProcessBatchResources(pids) {
   if (pids.length === 0)
     return new Map;
-  return await plat.measure(`Batch memory (${pids.length} PIDs)`, async () => {
-    const memoryMap = new Map;
+  return await plat.measure(`Batch resources (${pids.length} PIDs)`, async () => {
+    const resourceMap = new Map;
     const pidSet = new Set(pids);
     try {
       if (isWindows()) {
-        const result = await $`powershell -Command "Get-Process | Select-Object Id, WorkingSet"`.nothrow().quiet().text();
+        const result = await $`powershell -Command "Get-Process | Select-Object Id, CPU, WorkingSet"`.nothrow().quiet().text();
         const lines = result.trim().split(`
 `);
         for (const line of lines) {
@@ -241,33 +243,41 @@ async function getProcessBatchMemory(pids) {
           if (!trimmed || trimmed.startsWith("Id") || trimmed.startsWith("--"))
             continue;
           const parts = trimmed.split(/\s+/);
-          if (parts.length >= 2) {
-            const val1 = parseInt(parts[0]);
-            const val2 = parseInt(parts[parts.length - 1]);
-            if (!isNaN(val1) && !isNaN(val2)) {
-              if (pidSet.has(val1))
-                memoryMap.set(val1, val2);
+          if (parts.length >= 3) {
+            const pid = parseInt(parts[0]);
+            let cpuStr = parts[1];
+            let memStr = parts[2];
+            if (parts.length === 2) {
+              cpuStr = "0";
+              memStr = parts[1];
+            }
+            const cpu = parseFloat(cpuStr) || 0;
+            const memory = parseInt(memStr) || 0;
+            if (!isNaN(pid) && !isNaN(memory)) {
+              if (pidSet.has(pid))
+                resourceMap.set(pid, { memory, cpu });
             }
           }
         }
       } else {
-        const result = await $`ps -eo pid,rss`.nothrow().quiet().text();
+        const result = await $`ps -eo pid,pcpu,rss`.nothrow().quiet().text();
         const lines = result.trim().split(`
 `);
         for (let i = 1;i < lines.length; i++) {
           const line = lines[i].trim();
           if (!line)
             continue;
-          const [pidStr, rssStr] = line.split(/\s+/);
+          const [pidStr, cpuStr, rssStr] = line.split(/\s+/);
           const pid = parseInt(pidStr);
-          const rss = parseInt(rssStr);
+          const cpu = parseFloat(cpuStr) || 0;
+          const rss = parseInt(rssStr) || 0;
           if (pidSet.has(pid)) {
-            memoryMap.set(pid, rss * 1024);
+            resourceMap.set(pid, { memory: rss * 1024, cpu });
           }
         }
       }
     } catch (e) {}
-    return memoryMap;
+    return resourceMap;
   }) ?? new Map;
 }
 async function getProcessPorts(pid) {
@@ -528,7 +538,7 @@ var init_db = __esm(() => {
 import boxen from "boxen";
 import chalk2 from "chalk";
 function announce(message, title) {
-  console.log(boxen(chalk2.white(message), {
+  console.log(boxen(message, {
     padding: 1,
     margin: 1,
     borderColor: "green",
@@ -538,7 +548,8 @@ function announce(message, title) {
   }));
 }
 function error(message) {
-  console.error(boxen(chalk2.red(message), {
+  const text = message instanceof Error ? message.stack || message.message : String(message);
+  console.error(boxen(chalk2.red(text), {
     padding: 1,
     margin: 1,
     borderColor: "red",
@@ -581,6 +592,95 @@ async function parseConfigFile(configPath) {
   return flattenConfig(parsedConfig);
 }
 
+// src/deps.ts
+var exports_deps = {};
+__export(exports_deps, {
+  getUnmetDeps: () => getUnmetDeps,
+  getDependencies: () => getDependencies,
+  buildDepGraph: () => buildDepGraph
+});
+function getDependencies(envStr) {
+  const env = parseEnvString(envStr);
+  const raw = env.BGR_DEPENDS_ON || "";
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+async function buildDepGraph() {
+  const processes = getAllProcesses();
+  const nodeMap = new Map;
+  for (const proc of processes) {
+    const deps = getDependencies(proc.env);
+    const alive = await isProcessRunning(proc.pid, proc.command);
+    nodeMap.set(proc.name, {
+      name: proc.name,
+      dependsOn: deps,
+      dependedBy: [],
+      running: alive,
+      pid: proc.pid
+    });
+  }
+  for (const node of nodeMap.values()) {
+    for (const dep of node.dependsOn) {
+      const depNode = nodeMap.get(dep);
+      if (depNode) {
+        depNode.dependedBy.push(node.name);
+      }
+    }
+  }
+  const inDegree = new Map;
+  for (const node of nodeMap.values()) {
+    inDegree.set(node.name, node.dependsOn.filter((d) => nodeMap.has(d)).length);
+  }
+  const queue = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0)
+      queue.push(name);
+  }
+  const order = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    order.push(current);
+    const node = nodeMap.get(current);
+    for (const dependent of node.dependedBy) {
+      const newDegree = (inDegree.get(dependent) || 0) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0)
+        queue.push(dependent);
+    }
+  }
+  const hasCycle = order.length < nodeMap.size;
+  const cycleNodes = hasCycle ? [...nodeMap.keys()].filter((n) => !order.includes(n)) : undefined;
+  return {
+    nodes: [...nodeMap.values()],
+    order,
+    hasCycle,
+    cycleNodes
+  };
+}
+async function getUnmetDeps(name) {
+  const proc = getProcess(name);
+  if (!proc)
+    return [];
+  const deps = getDependencies(proc.env);
+  const unmet = [];
+  for (const depName of deps) {
+    const depProc = getProcess(depName);
+    if (!depProc) {
+      unmet.push(depName);
+      continue;
+    }
+    const alive = await isProcessRunning(depProc.pid, depProc.command);
+    if (!alive) {
+      unmet.push(depName);
+    }
+  }
+  return unmet;
+}
+var init_deps = __esm(() => {
+  init_db();
+  init_platform();
+  init_utils();
+});
+
 // src/commands/run.ts
 var {$: $2 } = globalThis.Bun;
 var {sleep: sleep2 } = globalThis.Bun;
@@ -589,6 +689,21 @@ import { createMeasure as createMeasure2 } from "measure-fn";
 async function handleRun(options) {
   const { command, directory, env, name, configPath, force, fetch, stdout, stderr } = options;
   const existingProcess = name ? getProcess(name) : null;
+  if (name && existingProcess) {
+    const { getUnmetDeps: getUnmetDeps2 } = await Promise.resolve().then(() => (init_deps(), exports_deps));
+    const unmet = await getUnmetDeps2(name);
+    if (unmet.length > 0) {
+      await run.measure(`Start ${unmet.length} dependencies for "${name}"`, async () => {
+        for (const depName of unmet) {
+          const depProc = getProcess(depName);
+          if (depProc) {
+            announce(`\uD83D\uDCE6 Starting dependency "${depName}" for "${name}"`, "Dependency");
+            await handleRun({ action: "run", name: depName, force: true, remoteName: "" });
+          }
+        }
+      });
+    }
+  }
   if (existingProcess) {
     const finalDirectory2 = directory || existingProcess.workdir;
     validateDirectory(finalDirectory2);
@@ -732,10 +847,82 @@ var init_run = __esm(() => {
   run = createMeasure2("run");
 });
 
+// src/log-rotation.ts
+var exports_log_rotation = {};
+__export(exports_log_rotation, {
+  startLogRotation: () => startLogRotation,
+  rotateLogFile: () => rotateLogFile,
+  rotateAllLogs: () => rotateAllLogs
+});
+import { existsSync as existsSync7, statSync as statSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
+function rotateLogFile(filePath, maxBytes = DEFAULT_MAX_BYTES, keepLines = DEFAULT_KEEP_LINES) {
+  try {
+    if (!existsSync7(filePath))
+      return false;
+    const stat = statSync3(filePath);
+    if (stat.size <= maxBytes)
+      return false;
+    const content = readFileSync2(filePath, "utf-8");
+    const lines = content.split(`
+`);
+    if (lines.length <= keepLines)
+      return false;
+    const truncated = lines.slice(-keepLines);
+    const header = `--- [bgrun] Log rotated at ${new Date().toISOString()} (was ${lines.length} lines, ${formatBytes(stat.size)}) ---
+`;
+    writeFileSync(filePath, header + truncated.join(`
+`));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function rotateAllLogs(getProcesses, maxBytes = DEFAULT_MAX_BYTES, keepLines = DEFAULT_KEEP_LINES) {
+  const processes = getProcesses();
+  const rotated = [];
+  let checked = 0;
+  for (const proc of processes) {
+    if (proc.stdout_path) {
+      checked++;
+      if (rotateLogFile(proc.stdout_path, maxBytes, keepLines)) {
+        rotated.push(`${proc.name}/stdout`);
+      }
+    }
+    if (proc.stderr_path) {
+      checked++;
+      if (rotateLogFile(proc.stderr_path, maxBytes, keepLines)) {
+        rotated.push(`${proc.name}/stderr`);
+      }
+    }
+  }
+  return { rotated, checked };
+}
+function startLogRotation(getProcesses, intervalMs = DEFAULT_CHECK_INTERVAL_MS, maxBytes = DEFAULT_MAX_BYTES, keepLines = DEFAULT_KEEP_LINES) {
+  console.log(`[logs] Log rotation active: max ${formatBytes(maxBytes)}/file, keep ${keepLines} lines, check every ${intervalMs / 1000}s`);
+  return setInterval(() => {
+    const { rotated } = rotateAllLogs(getProcesses, maxBytes, keepLines);
+    if (rotated.length > 0) {
+      console.log(`[logs] Rotated ${rotated.length} log(s): ${rotated.join(", ")}`);
+    }
+  }, intervalMs);
+}
+function formatBytes(bytes) {
+  if (bytes >= 1e6)
+    return `${(bytes / 1e6).toFixed(1)}MB`;
+  if (bytes >= 1000)
+    return `${(bytes / 1000).toFixed(0)}KB`;
+  return `${bytes}B`;
+}
+var DEFAULT_MAX_BYTES, DEFAULT_KEEP_LINES = 5000, DEFAULT_CHECK_INTERVAL_MS = 60000;
+var init_log_rotation = __esm(() => {
+  DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+});
+
 // src/server.ts
 var exports_server = {};
 __export(exports_server, {
-  startServer: () => startServer
+  startServer: () => startServer,
+  guardRestartCounts: () => guardRestartCounts
 });
 import path2 from "path";
 async function startServer() {
@@ -749,6 +936,8 @@ async function startServer() {
     ...explicitPort !== undefined && { port: explicitPort }
   });
   startGuard();
+  const { startLogRotation: startLogRotation2 } = await Promise.resolve().then(() => (init_log_rotation(), exports_log_rotation));
+  startLogRotation2(() => getAllProcesses());
 }
 function startGuard() {
   console.log(`[guard] \u2713 Built-in process guard started (checking every ${GUARD_INTERVAL_MS / 1000}s)`);
@@ -760,17 +949,15 @@ function startGuard() {
       for (const proc of processes) {
         if (GUARD_SKIP_NAMES.has(proc.name))
           continue;
-        const env = proc.env ? typeof proc.env === "string" ? (() => {
-          try {
-            return JSON.parse(proc.env);
-          } catch {
-            return {};
-          }
-        })() : proc.env : {};
+        const env = proc.env ? parseEnvString(proc.env) : {};
         if (env.BGR_KEEP_ALIVE !== "true")
           continue;
         const alive = await isProcessRunning(proc.pid, proc.command);
         if (!alive) {
+          const now = Date.now();
+          const nextRestart = guardNextRestartTime.get(proc.name) || 0;
+          if (now < nextRestart)
+            continue;
           console.log(`[guard] \u26A0 Guarded process "${proc.name}" (PID ${proc.pid}) is dead, restarting...`);
           try {
             await handleRun({
@@ -779,10 +966,28 @@ function startGuard() {
               force: true,
               remoteName: ""
             });
-            console.log(`[guard] \u2713 Restarted "${proc.name}"`);
+            const prevCount = guardRestartCounts.get(proc.name) || 0;
+            const newCount = prevCount + 1;
+            guardRestartCounts.set(proc.name, newCount);
+            if (newCount > 5) {
+              const backoffSeconds = Math.min(30 * Math.pow(2, newCount - 6), 300);
+              guardNextRestartTime.set(proc.name, Date.now() + backoffSeconds * 1000);
+              console.log(`[guard] \u2713 Restarted "${proc.name}" (restart #${newCount}). Crash loop detected: next check delayed by ${backoffSeconds}s.`);
+            } else {
+              console.log(`[guard] \u2713 Restarted "${proc.name}" (restart #${newCount})`);
+            }
           } catch (err) {
             console.error(`[guard] \u2717 Failed to restart "${proc.name}": ${err.message}`);
           }
+        } else {
+          const prevCount = guardRestartCounts.get(proc.name) || 0;
+          if (prevCount > 0) {
+            const nextRestart = guardNextRestartTime.get(proc.name) || 0;
+            if (Date.now() > nextRestart + 60000) {
+              guardRestartCounts.delete(proc.name);
+              guardNextRestartTime.delete(proc.name);
+            }
+          }
         }
       }
     } catch (err) {
@@ -790,12 +995,139 @@ function startGuard() {
     }
   }, GUARD_INTERVAL_MS);
 }
-var GUARD_INTERVAL_MS = 30000, GUARD_SKIP_NAMES;
+var GUARD_INTERVAL_MS = 30000, GUARD_SKIP_NAMES, _g, guardRestartCounts, guardNextRestartTime;
 var init_server = __esm(() => {
   init_db();
   init_platform();
   init_run();
-  GUARD_SKIP_NAMES = new Set(["bgr-dashboard"]);
+  init_utils();
+  GUARD_SKIP_NAMES = new Set(["bgr-dashboard", "bgr-guard"]);
+  _g = globalThis;
+  if (!_g.__bgrGuardRestartCounts)
+    _g.__bgrGuardRestartCounts = new Map;
+  if (!_g.__bgrGuardNextRestartTime)
+    _g.__bgrGuardNextRestartTime = new Map;
+  guardRestartCounts = _g.__bgrGuardRestartCounts;
+  guardNextRestartTime = _g.__bgrGuardNextRestartTime;
+});
+
+// src/guard.ts
+var exports_guard = {};
+__export(exports_guard, {
+  startGuardLoop: () => startGuardLoop
+});
+async function restartProcess(name) {
+  try {
+    await handleRun({
+      action: "run",
+      name,
+      force: true,
+      remoteName: ""
+    });
+    return true;
+  } catch (err) {
+    console.error(`[guard] \u2717 Failed to restart "${name}": ${err.message}`);
+    return false;
+  }
+}
+function getBackoffMs(restartCount) {
+  if (restartCount <= CRASH_THRESHOLD)
+    return 0;
+  const exponent = restartCount - CRASH_THRESHOLD;
+  return Math.min(30000 * Math.pow(2, exponent - 1), MAX_BACKOFF_MS);
+}
+async function guardCycle() {
+  try {
+    const processes = getAllProcesses();
+    if (processes.length === 0)
+      return;
+    const now = Date.now();
+    let checked = 0;
+    let restarted = 0;
+    let skipped = 0;
+    for (const proc of processes) {
+      if (proc.name === "bgr-guard")
+        continue;
+      const env = proc.env ? parseEnvString(proc.env) : {};
+      const isGuarded = env.BGR_KEEP_ALIVE === "true";
+      const isDashboard = proc.name === "bgr-dashboard";
+      if (!isGuarded && !isDashboard)
+        continue;
+      checked++;
+      try {
+        const alive = await isProcessRunning(proc.pid, proc.command);
+        if (!alive && proc.pid > 0) {
+          const nextRestart = state.nextRestartTime.get(proc.name) || 0;
+          if (now < nextRestart) {
+            const waitSecs = Math.round((nextRestart - now) / 1000);
+            skipped++;
+            continue;
+          }
+          console.log(`[guard] \u26A0 "${proc.name}" (PID ${proc.pid}) is dead \u2014 restarting...`);
+          const success = await restartProcess(proc.name);
+          if (success) {
+            const count = (state.restartCounts.get(proc.name) || 0) + 1;
+            state.restartCounts.set(proc.name, count);
+            state.lastSeenAlive.delete(proc.name);
+            const backoff = getBackoffMs(count);
+            if (backoff > 0) {
+              state.nextRestartTime.set(proc.name, now + backoff);
+              console.log(`[guard] \u2713 Restarted "${proc.name}" (#${count}). Crash loop: next check in ${Math.round(backoff / 1000)}s`);
+            } else {
+              console.log(`[guard] \u2713 Restarted "${proc.name}" (#${count})`);
+            }
+            restarted++;
+          }
+        } else if (alive) {
+          const count = state.restartCounts.get(proc.name) || 0;
+          if (count > 0) {
+            const lastSeen = state.lastSeenAlive.get(proc.name);
+            if (!lastSeen) {
+              state.lastSeenAlive.set(proc.name, now);
+            } else if (now - lastSeen > STABILITY_WINDOW_MS) {
+              state.restartCounts.delete(proc.name);
+              state.nextRestartTime.delete(proc.name);
+              state.lastSeenAlive.delete(proc.name);
+              console.log(`[guard] \u2713 "${proc.name}" stable for ${Math.round(STABILITY_WINDOW_MS / 1000)}s \u2014 reset counters`);
+            }
+          }
+        }
+      } catch (err) {
+        console.error(`[guard] Error checking "${proc.name}": ${err.message}`);
+      }
+    }
+    if (restarted > 0) {
+      console.log(`[guard] Cycle: ${checked} checked, ${restarted} restarted, ${skipped} in backoff`);
+    }
+  } catch (err) {
+    console.error(`[guard] Error in guard cycle: ${err.message}`);
+  }
+}
+async function startGuardLoop(intervalMs = DEFAULT_INTERVAL_MS) {
+  const interval = intervalMs || DEFAULT_INTERVAL_MS;
+  console.log(`[guard] \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`);
+  console.log(`[guard] \uD83D\uDEE1\uFE0F  BGR Standalone Guard started`);
+  console.log(`[guard]    Check interval: ${interval / 1000}s`);
+  console.log(`[guard]    Crash backoff threshold: ${CRASH_THRESHOLD} restarts`);
+  console.log(`[guard]    Stability window: ${STABILITY_WINDOW_MS / 1000}s`);
+  console.log(`[guard]    Monitoring: BGR_KEEP_ALIVE=true + bgr-dashboard`);
+  console.log(`[guard]    Started: ${new Date().toLocaleString()}`);
+  console.log(`[guard] \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`);
+  await guardCycle();
+  setInterval(guardCycle, interval);
+}
+var DEFAULT_INTERVAL_MS = 30000, MAX_BACKOFF_MS, CRASH_THRESHOLD = 5, STABILITY_WINDOW_MS = 120000, state;
+var init_guard = __esm(() => {
+  init_db();
+  init_platform();
+  init_run();
+  init_utils();
+  MAX_BACKOFF_MS = 5 * 60000;
+  state = {
+    restartCounts: new Map,
+    nextRestartTime: new Map,
+    lastSeenAlive: new Map
+  };
 });
 
 // src/index.ts
@@ -1009,11 +1341,11 @@ async function showAll(opts) {
   }
   const tableData = [];
   const allPids = filtered.map((p) => p.pid);
-  const memoryMap = await getProcessBatchMemory(allPids);
+  const resourceMap = await getProcessBatchResources(allPids);
   for (const proc of filtered) {
     const isRunning = await isProcessRunning(proc.pid, proc.command);
     const runtime = calculateRuntime(proc.timestamp);
-    const mem = isRunning ? memoryMap.get(proc.pid) || 0 : 0;
+    const mem = isRunning ? resourceMap.get(proc.pid)?.memory || 0 : 0;
     const ports = isRunning ? await getProcessPorts(proc.pid) : [];
     tableData.push({
       id: proc.id,
@@ -1470,6 +1802,7 @@ async function showHelp() {
       bgrun                     List all processes
       bgrun [name]             Show details for a process
       bgrun --dashboard        Launch web dashboard (managed by bgrun)
+      bgrun --guard            Launch standalone process guard
       bgrun --restart [name]   Restart a process
       bgrun --restart-all      Restart ALL registered processes
       bgrun --stop [name]      Stop a process (keep in registry)
@@ -1535,8 +1868,10 @@ async function run2() {
       stdout: { type: "string" },
       stderr: { type: "string" },
       dashboard: { type: "boolean" },
+      guard: { type: "boolean" },
       debug: { type: "boolean" },
       _serve: { type: "boolean" },
+      "_guard-loop": { type: "boolean" },
       port: { type: "string" }
     },
     strict: false,
@@ -1547,6 +1882,13 @@ async function run2() {
     await startServer2();
     return;
   }
+  if (values["_guard-loop"]) {
+    const { startGuardLoop: startGuardLoop2 } = await Promise.resolve().then(() => (init_guard(), exports_guard));
+    const intervalStr = positionals[0];
+    const intervalMs = intervalStr ? parseInt(intervalStr) * 1000 : undefined;
+    await startGuardLoop2(intervalMs);
+    return;
+  }
   if (values.dashboard) {
     const dashboardName = "bgr-dashboard";
     const homePath3 = getHomeDir();
@@ -1593,6 +1935,18 @@ async function run2() {
     if (requestedPort) {
       spawnEnv.BUN_PORT = requestedPort;
     }
+    const targetPort = parseInt(requestedPort || Bun.env.BUN_PORT || "3000");
+    if (!isNaN(targetPort) && targetPort > 0) {
+      const portFree = await isPortFree(targetPort);
+      if (!portFree) {
+        console.log(chalk8.yellow(`  \u26A1 Port ${targetPort} is occupied \u2014 reclaiming...`));
+        await killProcessOnPort(targetPort);
+        const freed = await waitForPortFree(targetPort, 5000);
+        if (!freed) {
+          console.log(chalk8.red(`  \u26A0 Could not free port ${targetPort} \u2014 dashboard may pick a fallback port`));
+        }
+      }
+    }
     const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
       env: spawnEnv,
       cwd: bgrDir2,
@@ -1641,6 +1995,69 @@ async function run2() {
     announce(msg, "BGR Dashboard");
     return;
   }
+  if (values.guard) {
+    const guardName = "bgr-guard";
+    const homePath3 = getHomeDir();
+    const bgrDir2 = join3(homePath3, ".bgr");
+    const existing = getProcess(guardName);
+    if (existing && await isProcessRunning(existing.pid)) {
+      announce(`Guard is already running (PID ${existing.pid})
+
+  Use ${chalk8.yellow(`bgrun --stop ${guardName}`)} to stop it
+  Use ${chalk8.yellow(`bgrun --guard --force`)} to restart`, "BGR Guard");
+      return;
+    }
+    if (existing) {
+      if (await isProcessRunning(existing.pid)) {
+        await terminateProcess(existing.pid);
+      }
+      await retryDatabaseOperation(() => removeProcessByName(guardName));
+    }
+    const { resolve } = __require("path");
+    const scriptPath = resolve(process.argv[1]);
+    const spawnCommand = `bun run ${scriptPath} --_guard-loop`;
+    const command = `bgrun --_guard-loop`;
+    const stdoutPath = join3(bgrDir2, `${guardName}-out.txt`);
+    const stderrPath = join3(bgrDir2, `${guardName}-err.txt`);
+    await Bun.write(stdoutPath, "");
+    await Bun.write(stderrPath, "");
+    const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
+      env: { ...Bun.env },
+      cwd: bgrDir2,
+      stdout: Bun.file(stdoutPath),
+      stderr: Bun.file(stderrPath)
+    });
+    newProcess.unref();
+    await sleep3(1000);
+    const actualPid = await findChildPid(newProcess.pid);
+    await retryDatabaseOperation(() => insertProcess({
+      pid: actualPid,
+      workdir: bgrDir2,
+      command,
+      name: guardName,
+      env: "BGR_KEEP_ALIVE=false",
+      configPath: "",
+      stdout_path: stdoutPath,
+      stderr_path: stderrPath
+    }));
+    const msg = dedent`
+      ${chalk8.bold("\uD83D\uDEE1\uFE0F  BGR Standalone Guard launched")}
+      ${chalk8.gray("\u2500".repeat(40))}
+
+        Monitors: All processes with BGR_KEEP_ALIVE=true
+        Also watches: bgr-dashboard (auto-restart if it dies)
+        Check interval: 30 seconds
+        Backoff: Exponential after 5 rapid crashes
+
+      ${chalk8.gray("\u2500".repeat(40))}
+        Process: ${chalk8.white(guardName)}  |  PID: ${chalk8.white(String(actualPid))}
+
+        ${chalk8.yellow(`bgrun ${guardName} --logs`)}    View guard logs
+        ${chalk8.yellow(`bgrun --stop ${guardName}`)}    Stop the guard
+    `;
+    announce(msg, "BGR Guard");
+    return;
+  }
   if (values.version) {
     console.log(`bgrun version: ${await getVersion()}`);
     return;
@@ -1813,6 +2230,5 @@ async function run2() {
   }
 }
 run2().catch((err) => {
-  console.error(chalk8.red(err));
-  process.exit(1);
+  error(err);
 });