bgrun 3.10.2 → 3.12.0

package/src/guard.ts

@@ -0,0 +1,157 @@
+/**
+ * BGR Standalone Process Guard
+ * 
+ * Runs as an independent process that monitors ALL guarded processes
+ * (BGR_KEEP_ALIVE=true) and the dashboard itself. If the dashboard
+ * crashes, the guard restarts it. If any guarded process dies, the 
+ * guard restarts it.
+ * 
+ * This is the "outer shell" — it cannot be killed by a dashboard crash.
+ * 
+ * Usage:
+ *   bgrun --guard              # Start guard as a managed bgrun process
+ *   bgrun --_guard-loop        # (Internal) Actually run the guard loop
+ *   bgrun --_guard-loop 30     # Check every 30 seconds
+ */
+
+import { getAllProcesses, getProcess } from './db';
+import { isProcessRunning, getProcessPorts, findChildPid } from './platform';
+import { handleRun } from './commands/run';
+import { parseEnvString } from './utils';
+
+const DEFAULT_INTERVAL_MS = 30_000;
+const MAX_BACKOFF_MS = 5 * 60_000; // 5 minutes max
+const CRASH_THRESHOLD = 5; // Start backoff after this many restarts
+const STABILITY_WINDOW_MS = 120_000; // 2 minutes stable = reset counter
+
+interface GuardState {
+    restartCounts: Map<string, number>;
+    nextRestartTime: Map<string, number>;
+    lastSeenAlive: Map<string, number>;
+}
+
+const state: GuardState = {
+    restartCounts: new Map(),
+    nextRestartTime: new Map(),
+    lastSeenAlive: new Map(),
+};
+
+async function restartProcess(name: string): Promise<boolean> {
+    try {
+        await handleRun({
+            action: 'run',
+            name,
+            force: true,
+            remoteName: '',
+        });
+        return true;
+    } catch (err: any) {
+        console.error(`[guard] ✗ Failed to restart "${name}": ${err.message}`);
+        return false;
+    }
+}
+
+function getBackoffMs(restartCount: number): number {
+    if (restartCount <= CRASH_THRESHOLD) return 0;
+    const exponent = restartCount - CRASH_THRESHOLD;
+    return Math.min(30_000 * Math.pow(2, exponent - 1), MAX_BACKOFF_MS);
+}
+
+async function guardCycle(): Promise<void> {
+    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) {
+            // Skip the guard process itself
+            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';
+
+            // Guard both: explicitly guarded processes AND the dashboard
+            if (!isGuarded && !isDashboard) continue;
+
+            checked++;
+
+            try {
+                const alive = await isProcessRunning(proc.pid, proc.command);
+
+                if (!alive && proc.pid > 0) {
+                    // Check backoff
+                    const nextRestart = state.nextRestartTime.get(proc.name) || 0;
+                    if (now < nextRestart) {
+                        const waitSecs = Math.round((nextRestart - now) / 1000);
+                        skipped++;
+                        continue;
+                    }
+
+                    console.log(`[guard] ⚠ "${proc.name}" (PID ${proc.pid}) is dead — 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] ✓ Restarted "${proc.name}" (#${count}). Crash loop: next check in ${Math.round(backoff / 1000)}s`);
+                        } else {
+                            console.log(`[guard] ✓ Restarted "${proc.name}" (#${count})`);
+                        }
+                        restarted++;
+                    }
+                } else if (alive) {
+                    // Track stability — if alive for STABILITY_WINDOW, reset counters
+                    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] ✓ "${proc.name}" stable for ${Math.round(STABILITY_WINDOW_MS / 1000)}s — reset counters`);
+                        }
+                    }
+                }
+            } catch (err: any) {
+                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: any) {
+        console.error(`[guard] Error in guard cycle: ${err.message}`);
+    }
+}
+
+export async function startGuardLoop(intervalMs: number = DEFAULT_INTERVAL_MS) {
+    const interval = intervalMs || DEFAULT_INTERVAL_MS;
+
+    console.log(`[guard] ═══════════════════════════════════════════`);
+    console.log(`[guard] 🛡️  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] ═══════════════════════════════════════════`);
+
+    // Run initial check immediately
+    await guardCycle();
+
+    // Then run on interval
+    setInterval(guardCycle, interval);
+}

package/src/index.ts

@@ -12,7 +12,7 @@ import type { CommandOptions } from "./types";
 import { error, announce } from "./logger";
 // startServer is dynamically imported only when --_serve is used
 // to avoid loading melina (which has side-effects) on every bgrun command
-import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree } from "./platform";
+import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree, isPortFree } from "./platform";
 import { insertProcess, removeProcessByName, getProcess, retryDatabaseOperation, getDbInfo } from "./db";
 import dedent from "dedent";
 import chalk from "chalk";
@@ -38,6 +38,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)
@@ -105,8 +106,10 @@ async function run() {
       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,
@@ -122,6 +125,15 @@ async function run() {
     return;
   }
 
+  // Internal: actually run the guard loop (spawned by --guard)
+  if (values['_guard-loop']) {
+    const { startGuardLoop } = await import("./guard");
+    const intervalStr = positionals[0];
+    const intervalMs = intervalStr ? parseInt(intervalStr) * 1000 : undefined;
+    await startGuardLoop(intervalMs);
+    return;
+  }
+
   // Dashboard: spawn the dashboard server as a bgr-managed process
   if (values.dashboard) {
     const dashboardName = 'bgr-dashboard';
@@ -186,6 +198,21 @@ async function run() {
       spawnEnv.BUN_PORT = requestedPort;
     }
 
+    // Resolve the target port: --port flag > BUN_PORT env > default 3000
+    const targetPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
+    if (!isNaN(targetPort) && targetPort > 0) {
+      // Auto-kill whatever occupies the target port so dashboard always reclaims it
+      const portFree = await isPortFree(targetPort);
+      if (!portFree) {
+        console.log(chalk.yellow(`  ⚡ Port ${targetPort} is occupied — reclaiming...`));
+        await killProcessOnPort(targetPort);
+        const freed = await waitForPortFree(targetPort, 5000);
+        if (!freed) {
+          console.log(chalk.red(`  ⚠ Could not free port ${targetPort} — dashboard may pick a fallback port`));
+        }
+      }
+    }
+
     const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
       env: spawnEnv,
       cwd: bgrDir,
@@ -246,6 +273,85 @@ async function run() {
     return;
   }
 
+  // Guard: spawn the standalone guard as a bgr-managed process
+  if (values.guard) {
+    const guardName = 'bgr-guard';
+    const homePath = getHomeDir();
+    const bgrDir = join(homePath, '.bgr');
+
+    // Check if guard is already running
+    const existing = getProcess(guardName);
+    if (existing && await isProcessRunning(existing.pid)) {
+      announce(
+        `Guard is already running (PID ${existing.pid})\n\n` +
+        `  Use ${chalk.yellow(`bgrun --stop ${guardName}`)} to stop it\n` +
+        `  Use ${chalk.yellow(`bgrun --guard --force`)} to restart`,
+        'BGR Guard'
+      );
+      return;
+    }
+
+    // Kill existing if force
+    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 = join(bgrDir, `${guardName}-out.txt`);
+    const stderrPath = join(bgrDir, `${guardName}-err.txt`);
+
+    await Bun.write(stdoutPath, '');
+    await Bun.write(stderrPath, '');
+
+    const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
+      env: { ...Bun.env },
+      cwd: bgrDir,
+      stdout: Bun.file(stdoutPath),
+      stderr: Bun.file(stderrPath),
+    });
+
+    newProcess.unref();
+    await sleep(1000);
+    const actualPid = await findChildPid(newProcess.pid);
+
+    await retryDatabaseOperation(() =>
+      insertProcess({
+        pid: actualPid,
+        workdir: bgrDir,
+        command,
+        name: guardName,
+        env: 'BGR_KEEP_ALIVE=false', // Guard doesn't guard itself
+        configPath: '',
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+      })
+    );
+
+    const msg = dedent`
+      ${chalk.bold('🛡️  BGR Standalone Guard launched')}
+      ${chalk.gray('─'.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
+
+      ${chalk.gray('─'.repeat(40))}
+        Process: ${chalk.white(guardName)}  |  PID: ${chalk.white(String(actualPid))}
+
+        ${chalk.yellow(`bgrun ${guardName} --logs`)}    View guard logs
+        ${chalk.yellow(`bgrun --stop ${guardName}`)}    Stop the guard
+    `;
+    announce(msg, 'BGR Guard');
+    return;
+  }
+
   if (values.version) {
     console.log(`bgrun version: ${await getVersion()}`);
     return;
@@ -435,6 +541,5 @@ async function run() {
 }
 
 run().catch(err => {
-  console.error(chalk.red(err));
-  process.exit(1);
+  error(err);
 });

package/src/log-rotation.ts

@@ -0,0 +1,93 @@
+/**
+ * Log rotation for bgrun process output files.
+ * 
+ * Ensures log files don't grow unbounded by:
+ * 1. Truncating on rotation (restart) — keeping last N lines
+ * 2. Size-based rotation — when file exceeds maxBytes, trim to last N lines
+ * 3. Periodic rotation check — runs on an interval in the dashboard
+ */
+
+import { existsSync, statSync, readFileSync, writeFileSync } from 'fs'
+
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024  // 10 MB
+const DEFAULT_KEEP_LINES = 5000             // Keep last 5000 lines on rotation
+const DEFAULT_CHECK_INTERVAL_MS = 60_000    // Check every 60s
+
+/** Rotate a single log file if it exceeds maxBytes */
+export function rotateLogFile(
+    filePath: string,
+    maxBytes: number = DEFAULT_MAX_BYTES,
+    keepLines: number = DEFAULT_KEEP_LINES,
+): boolean {
+    try {
+        if (!existsSync(filePath)) return false
+
+        const stat = statSync(filePath)
+        if (stat.size <= maxBytes) return false
+
+        // Read file, keep last N lines
+        const content = readFileSync(filePath, 'utf-8')
+        const lines = content.split('\n')
+
+        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)}) ---\n`
+        writeFileSync(filePath, header + truncated.join('\n'))
+
+        return true
+    } catch {
+        return false
+    }
+}
+
+/** Rotate all log files for all processes */
+export function rotateAllLogs(
+    getProcesses: () => Array<{ name: string; stdout_path: string; stderr_path: string }>,
+    maxBytes: number = DEFAULT_MAX_BYTES,
+    keepLines: number = DEFAULT_KEEP_LINES,
+): { rotated: string[]; checked: number } {
+    const processes = getProcesses()
+    const rotated: string[] = []
+    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 }
+}
+
+/** Start periodic log rotation */
+export function startLogRotation(
+    getProcesses: () => Array<{ name: string; stdout_path: string; stderr_path: string }>,
+    intervalMs: number = DEFAULT_CHECK_INTERVAL_MS,
+    maxBytes: number = DEFAULT_MAX_BYTES,
+    keepLines: number = DEFAULT_KEEP_LINES,
+): ReturnType<typeof setInterval> {
+    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: number): string {
+    if (bytes >= 1_000_000) return `${(bytes / 1_000_000).toFixed(1)}MB`
+    if (bytes >= 1_000) return `${(bytes / 1_000).toFixed(0)}KB`
+    return `${bytes}B`
+}

package/src/logger.ts

@@ -3,7 +3,7 @@ import chalk from "chalk";
 
 export function announce(message: string, title?: string) {
     console.log(
-        boxen(chalk.white(message), {
+        boxen(message, {
             padding: 1,
             margin: 1,
             borderColor: 'green',
@@ -14,9 +14,10 @@ export function announce(message: string, title?: string) {
     );
 }
 
-export function error(message: string) {
+export function error(message: string | Error) {
+    const text = message instanceof Error ? (message.stack || message.message) : String(message);
     console.error(
-        boxen(chalk.red(message), {
+        boxen(chalk.red(text), {
             padding: 1,
             margin: 1,
             borderColor: 'red',

package/src/platform.ts

@@ -31,7 +31,7 @@ export async function isProcessRunning(pid: number, command?: string): Promise<b
   // PID 0 means intentionally stopped — never alive
   if (pid <= 0) return false;
 
-  return plat.measure(`PID ${pid} alive?`, async () => {
+  return (await plat.measure(`PID ${pid} alive?`, async () => {
     try {
       // Docker container detection
       if (command && (command.includes('docker run') || command.includes('docker-compose up') || command.includes('docker compose up'))) {
@@ -48,7 +48,7 @@ export async function isProcessRunning(pid: number, command?: string): Promise<b
     } catch {
       return false;
     }
-  });
+  })) ?? false;
 }
 
 /**
@@ -224,8 +224,10 @@ export async function killProcessOnPort(port: number): Promise<void> {
         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
+          console.warn(`⚠ Port ${port} held by zombie PID ${pid} (process dead, socket stuck in kernel). Will clear on reboot or TCP timeout.`);
         }
-        // else: zombie socket — PID no longer exists but socket lingers in kernel
       }
     } else {
       // On Unix, use lsof
@@ -456,7 +458,7 @@ export async function findPidByPort(port: number, maxWaitMs = 8000): Promise<num
 }
 
 export async function readFileTail(filePath: string, lines?: number): Promise<string> {
-  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();
 
@@ -470,7 +472,7 @@ export async function readFileTail(filePath: string, lines?: number): Promise<st
     } catch (error) {
       throw new Error(`Error reading file: ${error}`);
     }
-  });
+  })) ?? '';
 }
 
 /**
@@ -484,56 +486,70 @@ export function copyFile(src: string, dest: string): void {
  * Get memory usage of a process in bytes
  */
 export async function getProcessMemory(pid: number): Promise<number> {
-  const map = await getProcessBatchMemory([pid]);
-  return map.get(pid) || 0;
+  const map = await getProcessBatchResources([pid]);
+  return map.get(pid)?.memory || 0;
 }
 
 /**
- * Get memory usage for a batch of PIDs in bytes.
- * Returns a Map of PID -> Memory (bytes).
+ * Get memory and CPU usage for a batch of PIDs.
+ * Returns a Map of PID -> { memory: bytes, cpu: number }.
+ * On Windows, CPU is cumulative time in seconds.
+ * On Unix, CPU is instantaneous percentage.
  * 
  * Optimization: Fetches ALL processes in one go and filters in-memory
  * to avoid spawning N subprocesses.
  */
-export async function getProcessBatchMemory(pids: number[]): Promise<Map<number, number>> {
+export async function getProcessBatchResources(pids: number[]): Promise<Map<number, { memory: number, cpu: number }>> {
   if (pids.length === 0) return new Map();
 
-  return await plat.measure(`Batch memory (${pids.length} PIDs)`, async () => {
-    const memoryMap = new Map<number, number>();
+  return await plat.measure(`Batch resources (${pids.length} PIDs)`, async () => {
+    const resourceMap = new Map<number, { memory: number, cpu: number }>();
     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('\n');
 
         for (const line of lines) {
           const trimmed = line.trim();
           if (!trimmed || trimmed.startsWith('Id') || trimmed.startsWith('--')) continue;
 
+          // Replace multiple spaces with a single space to parse correctly
           const parts = trimmed.split(/\s+/);
-          if (parts.length >= 2) {
-            const val1 = parseInt(parts[0]);
-            const val2 = parseInt(parts[parts.length - 1]);
+          if (parts.length >= 3) {
+            const pid = parseInt(parts[0]);
+            // CPU can sometimes be blank if process is just starting, handle that
+            let cpuStr = parts[1];
+            let memStr = parts[2];
+            if (parts.length === 2) {
+              // If CPU is missing, powershell might omit it and give just ID and WorkingSet
+              cpuStr = "0";
+              memStr = parts[1];
+            }
+
+            const cpu = parseFloat(cpuStr) || 0;
+            const memory = parseInt(memStr) || 0;
 
-            if (!isNaN(val1) && !isNaN(val2)) {
-              if (pidSet.has(val1)) memoryMap.set(val1, val2);
+            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('\n');
 
         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 });
           }
         }
       }
@@ -541,7 +557,7 @@ export async function getProcessBatchMemory(pids: number[]): Promise<Map<number,
       // silently fail
     }
 
-    return memoryMap;
+    return resourceMap;
   }) ?? new Map();
 }
 

package/src/server.ts

@@ -17,9 +17,17 @@ import path from 'path';
 import { getAllProcesses, getProcess } from './db';
 import { isProcessRunning } from './platform';
 import { handleRun } from './commands/run';
+import { parseEnvString } from './utils';
 
 const GUARD_INTERVAL_MS = 30_000; // Check every 30 seconds
-const GUARD_SKIP_NAMES = new Set(['bgr-dashboard']); // Don't try to restart ourselves
+const GUARD_SKIP_NAMES = new Set(['bgr-dashboard', 'bgr-guard']); // Don't try to restart ourselves or external guard
+
+// In-memory guard restart counter and timestamps (persists across module re-evaluations)
+const _g = globalThis as any;
+if (!_g.__bgrGuardRestartCounts) _g.__bgrGuardRestartCounts = new Map<string, number>();
+if (!_g.__bgrGuardNextRestartTime) _g.__bgrGuardNextRestartTime = new Map<string, number>();
+export const guardRestartCounts: Map<string, number> = _g.__bgrGuardRestartCounts;
+const guardNextRestartTime: Map<string, number> = _g.__bgrGuardNextRestartTime;
 
 export async function startServer() {
     // Dynamic import to avoid melina's side-effect console.log at bundle load time
@@ -38,6 +46,10 @@ export async function startServer() {
 
     // Start the built-in process guard
     startGuard();
+
+    // Start log rotation (prevents unbounded log file growth)
+    const { startLogRotation } = await import('./log-rotation');
+    startLogRotation(() => getAllProcesses());
 }
 
 /**
@@ -67,11 +79,15 @@ function startGuard() {
                 if (GUARD_SKIP_NAMES.has(proc.name)) continue;
 
                 // Only guard processes with BGR_KEEP_ALIVE=true
-                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; // Still in backoff period
+
                     console.log(`[guard] ⚠ Guarded process "${proc.name}" (PID ${proc.pid}) is dead, restarting...`);
                     try {
                         await handleRun({
@@ -80,10 +96,34 @@ function startGuard() {
                             force: true,
                             remoteName: '',
                         });
-                        console.log(`[guard] ✓ Restarted "${proc.name}"`);
+
+                        // Track restart count
+                        const prevCount = guardRestartCounts.get(proc.name) || 0;
+                        const newCount = prevCount + 1;
+                        guardRestartCounts.set(proc.name, newCount);
+
+                        // Exponential backoff if it crashes repeatedly (more than 5 times)
+                        if (newCount > 5) {
+                            const backoffSeconds = Math.min(30 * Math.pow(2, newCount - 6), 300); // 30s, 60s, 120s, up to 5 mins
+                            guardNextRestartTime.set(proc.name, Date.now() + (backoffSeconds * 1000));
+                            console.log(`[guard] ✓ Restarted "${proc.name}" (restart #${newCount}). Crash loop detected: next check delayed by ${backoffSeconds}s.`);
+                        } else {
+                            console.log(`[guard] ✓ Restarted "${proc.name}" (restart #${newCount})`);
+                        }
                     } catch (err: any) {
                         console.error(`[guard] ✗ Failed to restart "${proc.name}": ${err.message}`);
                     }
+                } else {
+                    // Reset counter if process has been stable (alive at least once during check)
+                    const prevCount = guardRestartCounts.get(proc.name) || 0;
+                    if (prevCount > 0) {
+                        const nextRestart = guardNextRestartTime.get(proc.name) || 0;
+                        if (Date.now() > nextRestart + 60_000) {
+                            // If it lived over 60s past its backoff threshold, consider it stable
+                            guardRestartCounts.delete(proc.name);
+                            guardNextRestartTime.delete(proc.name);
+                        }
+                    }
                 }
             }
         } catch (err: any) {

package/src/table.ts

@@ -34,12 +34,12 @@ export function getTerminalWidth(): number {
 }
 
 // Strip ANSI color codes for accurate length calculation
-function stripAnsi(str: string): string {
+export function stripAnsi(str: string): string {
   return str.replace(/\u001b\[[0-9;]*m/g, "");
 }
 
 // Default truncator: trims the end of a string
-function truncateString(str: string, maxLength: number): string {
+export function truncateString(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";
@@ -52,7 +52,7 @@ function truncateString(str: string, maxLength: number): string {
 }
 
 // Path truncator: trims the middle of a string
-function truncatePath(str: string, maxLength: number): string {
+export function truncatePath(str: string, maxLength: number): string {
   const stripped = stripAnsi(str);
   if (stripped.length <= maxLength) return str;
   const ellipsis = "…";