bgrun 3.10.0 → 3.10.1

package/dashboard/app/globals.css

@@ -898,6 +898,19 @@ tr.animate-in:nth-child(10) {
     border: 1px solid var(--info-border);
 }
 
+a.port-link {
+    text-decoration: none;
+    transition: all var(--transition-fast);
+}
+
+a.port-link:hover {
+    text-decoration: underline;
+    background: rgba(56, 189, 248, 0.15);
+    /* Slightly brighter info-bg on hover */
+    color: #7dd3fc;
+    /* Brighter info color */
+}
+
 .command {
     font-family: var(--font-mono);
     font-size: 0.75rem;

package/dashboard/app/page.client.tsx

@@ -164,7 +164,7 @@ function ProcessRow({ p, animate }: { p: ProcessData; animate?: boolean }) {
             <td className="pid">{String(p.pid)}</td>
             <td>
                 {p.port
-                    ? <span className="port-num">:{p.port}</span>
+                    ? <a className="port-num port-link" href={`http://localhost:${p.port}`} target="_blank" rel="noopener" title={`Open localhost:${p.port}`} onClick={(e: Event) => e.stopPropagation()}>:{p.port}</a>
                     : <span style={{ color: 'var(--text-muted)' }}>–</span>
                 }
             </td>
@@ -228,7 +228,7 @@ function ProcessCard({ p }: { p: ProcessData }) {
             </div>
             <div className="card-details">
                 <div className="card-detail"><span className="card-label">PID</span><span>{p.pid}</span></div>
-                <div className="card-detail"><span className="card-label">Port</span><span>{p.port ? `:${p.port}` : '–'}</span></div>
+                <div className="card-detail"><span className="card-label">Port</span>{p.port ? <a className="port-link" href={`http://localhost:${p.port}`} target="_blank" rel="noopener" onClick={(e: Event) => e.stopPropagation()}>:{p.port}</a> : <span>–</span>}</div>
                 <div className="card-detail"><span className="card-label">Memory</span><span>{p.memory > 0 ? formatMemory(p.memory) : '–'}</span></div>
                 <div className="card-detail"><span className="card-label">Runtime</span><span>{formatRuntime(p.runtime)}</span></div>
             </div>
@@ -845,7 +845,7 @@ export default function mount(): () => void {
             const metaItems = [
                 { label: 'Status', value: proc.running ? '● Running' : '○ Stopped' },
                 { label: 'PID', value: String(proc.pid) },
-                { label: 'Port', value: proc.port ? `:${proc.port}` : '–' },
+                { label: 'Port', value: proc.port ? `:${proc.port}` : '–', href: proc.port ? `http://localhost:${proc.port}` : undefined },
                 { label: 'Runtime', value: formatRuntime(proc.runtime) },
                 { label: 'Command', value: proc.command },
                 { label: 'Directory', value: proc.directory || '–' },
@@ -853,10 +853,13 @@ export default function mount(): () => void {
                 { label: 'Group', value: proc.group || '–' },
             ];
 
-            const items = metaItems.map(m => (
+            const items = metaItems.map((m: any) => (
                 <div className="meta-item">
                     <span className="meta-label">{m.label}</span>
-                    <span className="meta-value">{m.value}</span>
+                    {m.href
+                        ? <a className="meta-value port-link" href={m.href} target="_blank" rel="noopener">{m.value}</a>
+                        : <span className="meta-value">{m.value}</span>
+                    }
                 </div>
             ) as unknown as Node);
             meta.replaceChildren(...items);

package/dist/index.js

@@ -80,36 +80,24 @@ async function getChildPids(pid) {
 }
 async function terminateProcess(pid, force = false) {
   await plat.measure(`Terminate PID ${pid}`, async (m) => {
-    const children = await m("Get children", () => getChildPids(pid)) ?? [];
-    for (const childPid of children) {
-      try {
-        if (isWindows()) {
-          if (force) {
-            await $`taskkill /F /PID ${childPid}`.nothrow().quiet();
-          } else {
-            await $`taskkill /PID ${childPid}`.nothrow().quiet();
-          }
-        } else {
-          const signal = force ? "KILL" : "TERM";
-          await $`kill -${signal} ${childPid}`.nothrow();
+    try {
+      if (isWindows()) {
+        await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
+      } else {
+        const children = await m("Get children", () => getChildPids(pid)) ?? [];
+        const signal = force ? "KILL" : "TERM";
+        for (const childPid of children) {
+          try {
+            await $`kill -${signal} ${childPid}`.nothrow();
+          } catch {}
         }
-      } catch {}
-    }
-    await Bun.sleep(500);
-    if (await isProcessRunning(pid)) {
-      try {
-        if (isWindows()) {
-          if (force) {
-            await $`taskkill /F /PID ${pid}`.nothrow().quiet();
-          } else {
-            await $`taskkill /PID ${pid}`.nothrow().quiet();
-          }
-        } else {
-          const signal = force ? "KILL" : "TERM";
+        await Bun.sleep(500);
+        if (await isProcessRunning(pid)) {
           await $`kill -${signal} ${pid}`.nothrow();
         }
-      } catch {}
-    }
+      }
+    } catch {}
+    await Bun.sleep(300);
   });
 }
 async function isPortFree(port) {
@@ -118,9 +106,13 @@ async function isPortFree(port) {
       const result = await $`netstat -ano | findstr :${port}`.nothrow().quiet().text();
       for (const line of result.split(`
 `)) {
-        const match = line.match(new RegExp(`:(${port})\\s+.*LISTENING`));
-        if (match)
-          return false;
+        const match = line.match(new RegExp(`:(${port})\\s+.*LISTENING\\s+(\\d+)`));
+        if (match) {
+          const pid = parseInt(match[2]);
+          if (pid > 0 && await isProcessRunning(pid)) {
+            return false;
+          }
+        }
       }
       return true;
     } else {
@@ -159,8 +151,11 @@ async function killProcessOnPort(port) {
         }
       }
       for (const pid of pids) {
-        await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
-        console.log(`Killed process ${pid} using port ${port}`);
+        const alive = await isProcessRunning(pid);
+        if (alive) {
+          await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
+          console.log(`Killed process ${pid} using port ${port}`);
+        }
       }
     } else {
       const result = await $`lsof -ti :${port}`.nothrow().text();
@@ -326,6 +321,87 @@ var init_platform = __esm(() => {
   plat = createMeasure("platform");
 });
 
+// src/utils.ts
+import * as fs2 from "fs";
+import chalk from "chalk";
+function parseEnvString(envString) {
+  const env = {};
+  envString.split(",").forEach((pair) => {
+    const [key, value] = pair.split("=");
+    if (key && value)
+      env[key] = value;
+  });
+  return env;
+}
+function calculateRuntime(startTime) {
+  const start = new Date(startTime).getTime();
+  const now = new Date().getTime();
+  const diffInMinutes = Math.floor((now - start) / (1000 * 60));
+  return `${diffInMinutes} minutes`;
+}
+async function getVersion() {
+  try {
+    const { join } = await import("path");
+    const pkgPath = join(import.meta.dir, "../package.json");
+    const pkg = await Bun.file(pkgPath).json();
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function validateDirectory(directory) {
+  if (!directory || !fs2.existsSync(directory)) {
+    console.log(chalk.red("\u274C Error: 'directory' must be a valid path."));
+    process.exit(1);
+  }
+}
+function tailFile(path, prefix, colorFn, lines) {
+  let position = 0;
+  let lastPartial = "";
+  if (!fs2.existsSync(path)) {
+    return () => {};
+  }
+  const fd = fs2.openSync(path, "r");
+  const printNewContent = () => {
+    try {
+      const stats = fs2.statSync(path);
+      if (stats.size <= position)
+        return;
+      const buffer = Buffer.alloc(stats.size - position);
+      fs2.readSync(fd, buffer, 0, buffer.length, position);
+      let content = buffer.toString();
+      content = lastPartial + content;
+      lastPartial = "";
+      const lineArray = content.split(/\r?\n/);
+      if (!content.endsWith(`
+`)) {
+        lastPartial = lineArray.pop() || "";
+      }
+      lineArray.forEach((line) => {
+        if (line) {
+          console.log(colorFn(prefix + line));
+        }
+      });
+      position = stats.size;
+    } catch (e) {}
+  };
+  const watcher = fs2.watch(path, { persistent: true }, (event) => {
+    if (event === "change") {
+      printNewContent();
+    }
+  });
+  printNewContent();
+  return () => {
+    watcher.close();
+    try {
+      fs2.closeSync(fd);
+    } catch {}
+  };
+}
+var init_utils = __esm(() => {
+  init_platform();
+});
+
 // src/db.ts
 var exports_db = {};
 __export(exports_db, {
@@ -441,111 +517,6 @@ var init_db = __esm(() => {
   });
 });
 
-// src/server.ts
-var exports_server = {};
-__export(exports_server, {
-  startServer: () => startServer
-});
-import path2 from "path";
-async function startServer() {
-  const { start } = await import("melina");
-  const appDir = path2.join(import.meta.dir, "../dashboard/app");
-  const explicitPort = process.env.BUN_PORT ? parseInt(process.env.BUN_PORT, 10) : undefined;
-  await start({
-    appDir,
-    defaultTitle: "bgrun Dashboard - Process Manager",
-    globalCss: path2.join(appDir, "globals.css"),
-    ...explicitPort !== undefined && { port: explicitPort }
-  });
-}
-var init_server = () => {};
-
-// src/index.ts
-import { parseArgs } from "util";
-
-// src/utils.ts
-init_platform();
-import * as fs2 from "fs";
-import chalk from "chalk";
-function parseEnvString(envString) {
-  const env = {};
-  envString.split(",").forEach((pair) => {
-    const [key, value] = pair.split("=");
-    if (key && value)
-      env[key] = value;
-  });
-  return env;
-}
-function calculateRuntime(startTime) {
-  const start = new Date(startTime).getTime();
-  const now = new Date().getTime();
-  const diffInMinutes = Math.floor((now - start) / (1000 * 60));
-  return `${diffInMinutes} minutes`;
-}
-async function getVersion() {
-  try {
-    const { join } = await import("path");
-    const pkgPath = join(import.meta.dir, "../package.json");
-    const pkg = await Bun.file(pkgPath).json();
-    return pkg.version || "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-function validateDirectory(directory) {
-  if (!directory || !fs2.existsSync(directory)) {
-    console.log(chalk.red("\u274C Error: 'directory' must be a valid path."));
-    process.exit(1);
-  }
-}
-function tailFile(path, prefix, colorFn, lines) {
-  let position = 0;
-  let lastPartial = "";
-  if (!fs2.existsSync(path)) {
-    return () => {};
-  }
-  const fd = fs2.openSync(path, "r");
-  const printNewContent = () => {
-    try {
-      const stats = fs2.statSync(path);
-      if (stats.size <= position)
-        return;
-      const buffer = Buffer.alloc(stats.size - position);
-      fs2.readSync(fd, buffer, 0, buffer.length, position);
-      let content = buffer.toString();
-      content = lastPartial + content;
-      lastPartial = "";
-      const lineArray = content.split(/\r?\n/);
-      if (!content.endsWith(`
-`)) {
-        lastPartial = lineArray.pop() || "";
-      }
-      lineArray.forEach((line) => {
-        if (line) {
-          console.log(colorFn(prefix + line));
-        }
-      });
-      position = stats.size;
-    } catch (e) {}
-  };
-  const watcher = fs2.watch(path, { persistent: true }, (event) => {
-    if (event === "change") {
-      printNewContent();
-    }
-  });
-  printNewContent();
-  return () => {
-    watcher.close();
-    try {
-      fs2.closeSync(fd);
-    } catch {}
-  };
-}
-
-// src/commands/run.ts
-init_db();
-init_platform();
-
 // src/logger.ts
 import boxen from "boxen";
 import chalk2 from "chalk";
@@ -570,6 +541,7 @@ function error(message) {
   }));
   process.exit(1);
 }
+var init_logger = () => {};
 
 // src/config.ts
 function formatEnvKey(key) {
@@ -607,8 +579,6 @@ var {$: $2 } = globalThis.Bun;
 var {sleep: sleep2 } = globalThis.Bun;
 import { join as join2 } from "path";
 import { createMeasure as createMeasure2 } from "measure-fn";
-var homePath2 = getHomeDir();
-var run = createMeasure2("run");
 async function handleRun(options) {
   const { command, directory, env, name, configPath, force, fetch, stdout, stderr } = options;
   const existingProcess = name ? getProcess(name) : null;
@@ -662,6 +632,22 @@ async function handleRun(options) {
         }
       });
     }
+    const cmdToMatch = existingProcess.command;
+    if (cmdToMatch) {
+      await run.measure("Zombie sweep", async () => {
+        try {
+          const result = await $2`powershell -Command "Get-Process -Name bun -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match '${cmdToMatch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").split(" ")[1] || cmdToMatch}' } | Select-Object -ExpandProperty Id"`.nothrow().text();
+          const zombiePids = result.split(`
+`).map((l) => parseInt(l.trim())).filter((n) => !isNaN(n) && n > 0);
+          for (const zPid of zombiePids) {
+            await $2`taskkill /F /T /PID ${zPid}`.nothrow().quiet();
+          }
+          if (zombiePids.length > 0) {
+            announce(`\uD83E\uDDF9 Swept ${zombiePids.length} zombie process(es)`, "Zombie Cleanup");
+          }
+        } catch {}
+      });
+    }
     await retryDatabaseOperation(() => removeProcessByName(name));
   } else {
     if (!directory || !name || !command) {
@@ -729,6 +715,77 @@ async function handleRun(options) {
   }));
   announce(`${existingProcess ? "\uD83D\uDD04 Restarted" : "\uD83D\uDE80 Launched"} process "${name}" with PID ${actualPid}`, "Process Started");
 }
+var homePath2, run;
+var init_run = __esm(() => {
+  init_db();
+  init_platform();
+  init_logger();
+  init_utils();
+  homePath2 = getHomeDir();
+  run = createMeasure2("run");
+});
+
+// src/server.ts
+var exports_server = {};
+__export(exports_server, {
+  startServer: () => startServer
+});
+import path2 from "path";
+async function startServer() {
+  const { start } = await import("melina");
+  const appDir = path2.join(import.meta.dir, "../dashboard/app");
+  const explicitPort = process.env.BUN_PORT ? parseInt(process.env.BUN_PORT, 10) : undefined;
+  await start({
+    appDir,
+    defaultTitle: "bgrun Dashboard - Process Manager",
+    globalCss: path2.join(appDir, "globals.css"),
+    ...explicitPort !== undefined && { port: explicitPort }
+  });
+  startGuard();
+}
+function startGuard() {
+  console.log(`[guard] \u2713 Built-in process guard started (checking every ${GUARD_INTERVAL_MS / 1000}s)`);
+  setInterval(async () => {
+    try {
+      const processes = getAllProcesses();
+      if (processes.length === 0)
+        return;
+      for (const proc of processes) {
+        if (GUARD_SKIP_NAMES.has(proc.name))
+          continue;
+        const alive = await isProcessRunning(proc.pid, proc.command);
+        if (!alive) {
+          console.log(`[guard] \u26A0 Process "${proc.name}" (PID ${proc.pid}) is dead, restarting...`);
+          try {
+            await handleRun({
+              action: "run",
+              name: proc.name,
+              force: true,
+              remoteName: ""
+            });
+            console.log(`[guard] \u2713 Restarted "${proc.name}"`);
+          } catch (err) {
+            console.error(`[guard] \u2717 Failed to restart "${proc.name}": ${err.message}`);
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[guard] Error in guard loop: ${err.message}`);
+    }
+  }, GUARD_INTERVAL_MS);
+}
+var GUARD_INTERVAL_MS = 30000, GUARD_SKIP_NAMES;
+var init_server = __esm(() => {
+  init_db();
+  init_platform();
+  init_run();
+  GUARD_SKIP_NAMES = new Set(["bgr-dashboard"]);
+});
+
+// src/index.ts
+init_utils();
+init_run();
+import { parseArgs } from "util";
 
 // src/commands/list.ts
 import chalk4 from "chalk";
@@ -898,6 +955,8 @@ function renderProcessTable(processes, options) {
 
 // src/commands/list.ts
 init_db();
+init_logger();
+init_utils();
 init_platform();
 function formatMemory(bytes) {
   if (bytes === 0)
@@ -974,6 +1033,7 @@ async function showAll(opts) {
 // src/commands/cleanup.ts
 init_db();
 init_platform();
+init_logger();
 import * as fs3 from "fs";
 async function handleDelete(name) {
   const process2 = getProcess(name);
@@ -1093,6 +1153,9 @@ async function handleDeleteAll() {
 // src/commands/watch.ts
 init_db();
 init_platform();
+init_logger();
+init_utils();
+init_run();
 import * as fs4 from "fs";
 import path from "path";
 import chalk5 from "chalk";
@@ -1282,6 +1345,7 @@ SIGINT received...`));
 
 // src/commands/logs.ts
 init_db();
+init_logger();
 init_platform();
 import chalk6 from "chalk";
 import * as fs5 from "fs";
@@ -1326,7 +1390,9 @@ async function showLogs(name, logType = "both", lines) {
 }
 
 // src/commands/details.ts
+init_logger();
 init_db();
+init_utils();
 init_platform();
 import chalk7 from "chalk";
 async function showDetails(name) {
@@ -1363,6 +1429,7 @@ ${Object.entries(envVars).map(([key, value]) => `${chalk7.cyan.bold(key)} = ${ch
 }
 
 // src/index.ts
+init_logger();
 init_platform();
 init_db();
 import dedent from "dedent";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bgrun",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "description": "bgrun — A lightweight process manager for Bun",
   "type": "module",
   "main": "./src/api.ts",
@@ -57,4 +57,4 @@
   "engines": {
     "bun": ">=1.0.0"
   }
-}
+}

package/src/commands/run.ts

@@ -76,6 +76,24 @@ export async function handleRun(options: CommandOptions) {
             });
         }
 
+        // Zombie sweep: kill any remaining bun processes matching this command
+        // This catches orphaned children that survived taskkill when the parent shell exited
+        const cmdToMatch = existingProcess.command;
+        if (cmdToMatch) {
+            await run.measure('Zombie sweep', async () => {
+                try {
+                    const result = await $`powershell -Command "Get-Process -Name bun -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match '${cmdToMatch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').split(' ')[1] || cmdToMatch}' } | Select-Object -ExpandProperty Id"`.nothrow().text();
+                    const zombiePids = result.split('\n').map((l: string) => parseInt(l.trim())).filter((n: number) => !isNaN(n) && n > 0);
+                    for (const zPid of zombiePids) {
+                        await $`taskkill /F /T /PID ${zPid}`.nothrow().quiet();
+                    }
+                    if (zombiePids.length > 0) {
+                        announce(`🧹 Swept ${zombiePids.length} zombie process(es)`, 'Zombie Cleanup');
+                    }
+                } catch { /* best effort */ }
+            });
+        }
+
         await retryDatabaseOperation(() =>
             removeProcessByName(name!)
         );

package/src/platform.ts

@@ -112,51 +112,38 @@ async function getChildPids(pid: number): Promise<number[]> {
  */
 export async function terminateProcess(pid: number, force: boolean = false): Promise<void> {
   await plat.measure(`Terminate PID ${pid}`, async (m) => {
-    // First, kill children
-    const children = await m('Get children', () => getChildPids(pid)) ?? [];
-
-    for (const childPid of children) {
-      try {
-        if (isWindows()) {
-          if (force) {
-            await $`taskkill /F /PID ${childPid}`.nothrow().quiet();
-          } else {
-            await $`taskkill /PID ${childPid}`.nothrow().quiet();
-          }
-        } else {
-          const signal = force ? 'KILL' : 'TERM';
-          await $`kill -${signal} ${childPid}`.nothrow();
+    try {
+      if (isWindows()) {
+        // Always use /T (tree kill) on Windows to kill the entire process tree
+        // This prevents grandchild processes from surviving as zombies
+        await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
+      } else {
+        // On Unix, kill children first, then parent
+        const children = await m('Get children', () => getChildPids(pid)) ?? [];
+        const signal = force ? 'KILL' : 'TERM';
+        for (const childPid of children) {
+          try {
+            await $`kill -${signal} ${childPid}`.nothrow();
+          } catch { /* already dead */ }
         }
-      } catch {
-        // Ignore errors for already-dead processes
-      }
-    }
-
-    // Wait a bit for graceful shutdown
-    await Bun.sleep(500);
-
-    // Then kill the parent if still running
-    if (await isProcessRunning(pid)) {
-      try {
-        if (isWindows()) {
-          if (force) {
-            await $`taskkill /F /PID ${pid}`.nothrow().quiet();
-          } else {
-            await $`taskkill /PID ${pid}`.nothrow().quiet();
-          }
-        } else {
-          const signal = force ? 'KILL' : 'TERM';
+        await Bun.sleep(500);
+        if (await isProcessRunning(pid)) {
           await $`kill -${signal} ${pid}`.nothrow();
         }
-      } catch {
-        // Ignore errors
       }
+    } catch {
+      // Ignore errors for already-dead processes
     }
+
+    // Wait for process to fully exit
+    await Bun.sleep(300);
   });
 }
 
 /**
  * Check if a port is free by attempting to bind to it.
+ * On Windows, also checks whether the process holding the port is actually alive
+ * (zombie sockets from dead processes don't block new binds on 0.0.0.0).
  */
 export async function isPortFree(port: number): Promise<boolean> {
   try {
@@ -165,14 +152,22 @@ export async function isPortFree(port: number): Promise<boolean> {
       const result = await $`netstat -ano | findstr :${port}`.nothrow().quiet().text();
       for (const line of result.split('\n')) {
         // Only match exact port (avoid :35560 matching :3556)
-        const match = line.match(new RegExp(`:(${port})\\s+.*LISTENING`));
-        if (match) return false;
+        const match = line.match(new RegExp(`:(${port})\\s+.*LISTENING\\s+(\\d+)`));
+        if (match) {
+          const pid = parseInt(match[2]);
+          // If the PID behind the socket is dead, it's a zombie socket
+          // A new process can still bind to the port on 0.0.0.0
+          if (pid > 0 && await isProcessRunning(pid)) {
+            return false; // Real process holding the port
+          }
+          // else: zombie socket — consider port free
+        }
       }
       return true;
     } else {
       const result = await $`ss -tln sport = :${port}`.nothrow().quiet().text();
       // If output has more than the header line, port is in use
-      const lines = result.trim().split('\n').filter(l => l.trim());
+      const lines = result.trim().split('\n').filter((l: string) => l.trim());
       return lines.length <= 1;
     }
   } catch {
@@ -202,6 +197,8 @@ export async function waitForPortFree(port: number, timeoutMs: number = 5000): P
 /**
  * Kill processes using a specific port.
  * Force-kills all processes bound to the port and verifies they're gone.
+ * On Windows, filters out zombie PIDs (sockets orphaned by dead processes)
+ * since taskkill can't kill those — they require a reboot or TCP stack reset.
  */
 export async function killProcessOnPort(port: number): Promise<void> {
   try {
@@ -221,9 +218,14 @@ export async function killProcessOnPort(port: number): Promise<void> {
       }
 
       for (const pid of pids) {
-        // Force kill with /F /T (tree kill to get children too)
-        await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
-        console.log(`Killed process ${pid} using port ${port}`);
+        // Check if the process actually exists before trying to kill it
+        // This avoids the zombie PID issue where sockets linger after process death
+        const alive = await isProcessRunning(pid);
+        if (alive) {
+          await $`taskkill /F /T /PID ${pid}`.nothrow().quiet();
+          console.log(`Killed process ${pid} using port ${port}`);
+        }
+        // else: zombie socket — PID no longer exists but socket lingers in kernel
       }
     } else {
       // On Unix, use lsof

package/src/server.ts

@@ -1,14 +1,25 @@
 /**
- * BGR Dashboard Server
+ * BGR Dashboard Server + Built-in Process Guard
  * 
  * Uses Melina.js to serve the dashboard app with file-based routing.
  * All API endpoints and page rendering are handled by the dashboard/app/ directory.
  * 
+ * v3.0: Built-in guard loop — the dashboard now monitors ALL registered
+ * processes and auto-restarts any that die. This eliminates the need for
+ * external guard scripts. The dashboard itself survives because bgrun
+ * registers it as a managed process on launch.
+ * 
  * Port selection is handled entirely by Melina:
  *   - If BUN_PORT env var is set → uses that (explicit, will fail if busy)
  *   - Otherwise → defaults to 3000, falls back to next available if busy
  */
 import path from 'path';
+import { getAllProcesses, getProcess } from './db';
+import { isProcessRunning } from './platform';
+import { handleRun } from './commands/run';
+
+const GUARD_INTERVAL_MS = 30_000; // Check every 30 seconds
+const GUARD_SKIP_NAMES = new Set(['bgr-dashboard']); // Don't try to restart ourselves
 
 export async function startServer() {
     // Dynamic import to avoid melina's side-effect console.log at bundle load time
@@ -24,4 +35,55 @@ export async function startServer() {
         globalCss: path.join(appDir, 'globals.css'),
         ...(explicitPort !== undefined && { port: explicitPort }),
     });
+
+    // Start the built-in process guard
+    startGuard();
+}
+
+/**
+ * Built-in Process Guard
+ * 
+ * Runs as a background loop inside the dashboard process.
+ * Every GUARD_INTERVAL_MS, it checks all registered bgrun processes.
+ * If any process is dead (PID not running), it auto-restarts it using
+ * handleRun with force=true (same as `bgrun --restart <name>`).
+ * 
+ * Why here and not as a separate process?
+ * - No external dependency — the dashboard IS the guardian
+ * - If the dashboard is running, all processes are monitored
+ * - If the dashboard dies, `bgrun --dashboard` will restart everything
+ * - Zero configuration — just works
+ */
+function startGuard() {
+    console.log(`[guard] ✓ Built-in process guard started (checking every ${GUARD_INTERVAL_MS / 1000}s)`);
+
+    setInterval(async () => {
+        try {
+            const processes = getAllProcesses();
+            if (processes.length === 0) return;
+
+            for (const proc of processes) {
+                // Skip the dashboard itself
+                if (GUARD_SKIP_NAMES.has(proc.name)) continue;
+
+                const alive = await isProcessRunning(proc.pid, proc.command);
+                if (!alive) {
+                    console.log(`[guard] ⚠ Process "${proc.name}" (PID ${proc.pid}) is dead, restarting...`);
+                    try {
+                        await handleRun({
+                            action: 'run',
+                            name: proc.name,
+                            force: true,
+                            remoteName: '',
+                        });
+                        console.log(`[guard] ✓ Restarted "${proc.name}"`);
+                    } catch (err: any) {
+                        console.error(`[guard] ✗ Failed to restart "${proc.name}": ${err.message}`);
+                    }
+                }
+            }
+        } catch (err: any) {
+            console.error(`[guard] Error in guard loop: ${err.message}`);
+        }
+    }, GUARD_INTERVAL_MS);
 }