bgrun 3.12.0 → 3.12.1

package/package.json

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

package/scripts/bgr-startup.ps1

@@ -66,14 +66,14 @@ if ($Install) {
 
     Register-ScheduledTask `
         -TaskName "bgrun-guard" `
-        -Description "bgrun process manager — auto-starts all guarded processes on login" `
+        -Description "bgrun process manager - auto-starts all guarded processes on login" `
         -Action $action `
         -Trigger $trigger `
         -Settings $settings `
         -RunLevel Highest `
         -Force
 
-    Write-Log "✓ Task 'bgrun-guard' registered. Will start on next login."
+    Write-Log "[OK] Task 'bgrun-guard' registered. Will start on next login."
     Write-Log "  Script: $scriptPath"
     exit 0
 }
@@ -115,4 +115,4 @@ $guardProc = Start-Process -FilePath $BunPath `
     -WorkingDirectory $BgrunPath
 
 Write-Log "Guard PID: $($guardProc.Id)"
-Write-Log "✓ bgrun startup complete. Dashboard: $($dashboardProc.Id), Guard: $($guardProc.Id)"
+Write-Log "[OK] bgrun startup complete. Dashboard: $($dashboardProc.Id), Guard: $($guardProc.Id)"

package/scripts/bgrun-startup.ps1

@@ -0,0 +1,91 @@
+# bgrun-startup.ps1 — Persistent bgr-dashboard launcher
+# Ensures the bgrun dashboard survives terminal closures.
+# Individual services (geeksy, mm-dash, galaxy-canvas, etc.) are managed
+# by bgr-guard INSIDE the dashboard — this script only keeps the dashboard alive.
+#
+# Usage:
+#   .\bgrun-startup.ps1                  # Start bgr-dashboard
+#   .\bgrun-startup.ps1 -Install         # Register as logon scheduled task
+#   .\bgrun-startup.ps1 -Uninstall       # Remove scheduled task
+#   .\bgrun-startup.ps1 -Guard           # Run guard loop (auto-restart dashboard)
+
+param(
+    [switch]$Install,
+    [switch]$Uninstall,
+    [switch]$Guard
+)
+
+$TaskName = "bgrun-persistence"
+$ScriptPath = $MyInvocation.MyCommand.Path
+
+# ─── Install as Scheduled Task ────────────────────────────
+if ($Install) {
+    $action = New-ScheduledTaskAction `
+        -Execute "pwsh.exe" `
+        -Argument "-WindowStyle Hidden -NonInteractive -File `"$ScriptPath`" -Guard"
+    
+    $trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+    $settings = New-ScheduledTaskSettingsSet `
+        -AllowStartIfOnBatteries `
+        -DontStopIfGoingOnBatteries `
+        -StartWhenAvailable `
+        -RestartInterval (New-TimeSpan -Minutes 1) `
+        -RestartCount 3 `
+        -ExecutionTimeLimit (New-TimeSpan -Hours 0)  # No time limit
+
+    Register-ScheduledTask `
+        -TaskName $TaskName `
+        -Action $action `
+        -Trigger $trigger `
+        -Settings $settings `
+        -Description "Keeps bgr-dashboard alive across terminal closures. Dashboard's own bgr-guard handles individual services." `
+        -Force
+
+    Write-Host "✅ Scheduled task '$TaskName' registered for user $env:USERNAME"
+    Write-Host "   Runs at logon — keeps bgr-dashboard alive"
+    Write-Host "   To start immediately: schtasks /run /tn '$TaskName'"
+    exit 0
+}
+
+# ─── Uninstall ────────────────────────────────────────────
+if ($Uninstall) {
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+    Write-Host "🗑️  Scheduled task '$TaskName' removed"
+    exit 0
+}
+
+# ─── Guard mode: keep bgr-dashboard alive ─────────────────
+if ($Guard) {
+    Write-Host "🛡️  bgrun dashboard guard started at $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
+    
+    while ($true) {
+        try {
+            $dashboard = & bgrun --json 2>$null | ConvertFrom-Json | Where-Object { $_.name -eq 'bgr-dashboard' }
+            
+            if (-not $dashboard -or $dashboard.status -ne "running") {
+                Write-Host "[$(Get-Date -Format 'HH:mm:ss')] ⚠️  bgr-dashboard is DOWN — restarting..."
+                & bgrun --restart bgr-dashboard --force 2>$null
+                Start-Sleep -Seconds 3
+            }
+        } catch {
+            Write-Host "[$(Get-Date -Format 'HH:mm:ss')] ❌ Guard check failed: $_"
+        }
+        
+        Start-Sleep -Seconds 60
+    }
+    exit 0
+}
+
+# ─── Default: one-time start ──────────────────────────────
+Write-Host "🚀 Starting bgr-dashboard..."
+$dashboard = & bgrun --json 2>$null | ConvertFrom-Json | Where-Object { $_.name -eq 'bgr-dashboard' }
+if ($dashboard -and $dashboard.status -eq "running") {
+    Write-Host "  ✓ bgr-dashboard already running (PID $($dashboard.pid))"
+} else {
+    & bgrun --restart bgr-dashboard --force 2>$null
+    Start-Sleep -Seconds 2
+    Write-Host "  ✓ bgr-dashboard started"
+}
+Write-Host "`n✅ Done. Dashboard's bgr-guard handles individual services."
+Write-Host "   💡 Run with -Install to persist across terminal closures"
+

package/src/commands/details.ts

@@ -1,8 +1,8 @@
 
 import { error, announce } from "../logger";
-import { getProcess } from "../db";
+import { getProcess, updateProcessPid } from "../db";
 import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
-import { getProcessPorts } from "../platform";
+import { getProcessPorts, reconcileProcessPids } from "../platform";
 import chalk from "chalk";
 
 export async function showDetails(name: string) {
@@ -12,7 +12,21 @@ export async function showDetails(name: string) {
         return;
     }
 
-    const isRunning = await isProcessRunning(proc.pid, proc.command);
+    let isRunning = await isProcessRunning(proc.pid, proc.command);
+
+    // Reconcile stale PID: cmd.exe wrapper may have exited while bun.exe child lives
+    if (!isRunning && proc.pid > 0) {
+        const reconciled = await reconcileProcessPids(
+            [{ name: proc.name, pid: proc.pid, command: proc.command, workdir: proc.workdir }],
+            new Set([proc.pid]),
+        );
+        const newPid = reconciled.get(proc.name);
+        if (newPid) {
+            updateProcessPid(proc.name, newPid);
+            (proc as any).pid = newPid;
+            isRunning = true;
+        }
+    }
     const runtime = calculateRuntime(proc.timestamp);
     const envVars = parseEnvString(proc.env);
 

package/src/commands/list.ts

@@ -1,10 +1,10 @@
 import chalk from "chalk";
 import { renderProcessTable } from "../table";
 import type { ProcessTableRow } from "../table";
-import { getAllProcesses } from "../db";
+import { getAllProcesses, updateProcessPid } from "../db";
 import { announce } from "../logger";
 import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
-import { getProcessPorts, getProcessBatchResources } from "../platform";
+import { getProcessPorts, getProcessBatchResources, reconcileProcessPids } from "../platform";
 import { measure } from "measure-fn";
 
 function formatMemory(bytes: number): string {
@@ -24,12 +24,45 @@ export async function showAll(opts?: { json?: boolean; filter?: string }) {
         return envVars["BGR_GROUP"] === opts.filter;
     });
 
+    // ─── PID Reconciliation ──────────────────────────────────────────
+    // On Windows, the stored PID may be a dead cmd.exe wrapper while the
+    // actual bun.exe child is still running.  Detect dead PIDs up-front,
+    // reconcile them in one batch PowerShell call, and patch the DB so
+    // subsequent invocations are stable (no flicker).
+    const deadPids = new Set<number>();
+    const aliveCache = new Map<number, boolean>();
+
+    for (const proc of filtered) {
+        const alive = await isProcessRunning(proc.pid, proc.command);
+        aliveCache.set(proc.pid, alive);
+        if (!alive && proc.pid > 0) deadPids.add(proc.pid);
+    }
+
+    if (deadPids.size > 0) {
+        const reconciled = await reconcileProcessPids(
+            filtered.map(p => ({ name: p.name, pid: p.pid, command: p.command, workdir: p.workdir })),
+            deadPids,
+        );
+
+        for (const [name, newPid] of reconciled) {
+            updateProcessPid(name, newPid);
+            // Patch the in-memory record so the rest of this function sees
+            // the corrected PID without re-querying the DB.
+            const proc = filtered.find(p => p.name === name);
+            if (proc) {
+                (proc as any).pid = newPid;
+                aliveCache.set(newPid, true);
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+
     if (opts?.json) {
         // JSON output with filtered env variables
         const jsonData: any[] = [];
 
         for (const proc of filtered) {
-            const isRunning = await isProcessRunning(proc.pid, proc.command);
+            const isRunning = aliveCache.get(proc.pid) ?? await isProcessRunning(proc.pid, proc.command);
             const envVars = parseEnvString(proc.env);
 
             const ports = isRunning ? await getProcessPorts(proc.pid) : [];
@@ -54,7 +87,7 @@ export async function showAll(opts?: { json?: boolean; filter?: string }) {
     const resourceMap = await getProcessBatchResources(allPids);
 
     for (const proc of filtered) {
-        const isRunning = await isProcessRunning(proc.pid, proc.command);
+        const isRunning = aliveCache.get(proc.pid) ?? await isProcessRunning(proc.pid, proc.command);
         const runtime = calculateRuntime(proc.timestamp);
         const mem = isRunning ? (resourceMap.get(proc.pid)?.memory || 0) : 0;
 

package/src/commands/run.ts

@@ -1,6 +1,6 @@
 import type { CommandOptions } from "../types";
 import { getProcess, removeProcessByName, retryDatabaseOperation, insertProcess } from "../db";
-import { isProcessRunning, terminateProcess, getHomeDir, getShellCommand, killProcessOnPort, findChildPid, getProcessPorts, waitForPortFree } from "../platform";
+import { isProcessRunning, terminateProcess, getHomeDir, getShellCommand, killProcessOnPort, findChildPid, getProcessPorts, waitForPortFree, psExec } from "../platform";
 import { error, announce } from "../logger";
 import { validateDirectory, parseEnvString } from "../utils";
 import { parseConfigFile } from "../config";
@@ -95,12 +95,25 @@ 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
+        // IMPORTANT: Exclude the current bgrun process and dashboard to avoid self-kill
         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);
+                    const cmdKeyword = cmdToMatch.split(' ')[1] || cmdToMatch;
+                    // Skip sweep if keyword is too generic (would match unrelated processes)
+                    const GENERIC_KEYWORDS = ['dev', 'run', 'start', 'serve', 'build', 'test'];
+                    if (GENERIC_KEYWORDS.includes(cmdKeyword.toLowerCase())) {
+                        return; // Too dangerous — skip zombie sweep for generic commands
+                    }
+                    const currentPid = process.pid;
+                    const result = await psExec(
+                        `Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | Where-Object { $_.CommandLine -match '${cmdKeyword.replace(/'/g, "''")}' -and $_.ProcessId -ne ${currentPid} } | Select-Object -ExpandProperty ProcessId`,
+                        3000
+                    );
+                    const zombiePids = result.split('\n')
+                        .map((l: string) => parseInt(l.trim()))
+                        .filter((n: number) => !isNaN(n) && n > 0 && n !== currentPid);
                     for (const zPid of zombiePids) {
                         await $`taskkill /F /T /PID ${zPid}`.nothrow().quiet();
                     }
@@ -125,6 +138,11 @@ export async function handleRun(options: CommandOptions) {
     const finalCommand = command || existingProcess!.command;
     const finalDirectory = directory || (existingProcess?.workdir!);
     let finalEnv = env || (existingProcess ? parseEnvString(existingProcess.env) : {});
+    
+    // Default BGR_KEEP_ALIVE=true for new processes unless explicitly disabled
+    if (!('BGR_KEEP_ALIVE' in finalEnv)) {
+        finalEnv.BGR_KEEP_ALIVE = 'true';
+    }
 
     let finalConfigPath: string | undefined | null;
     if (configPath !== undefined) {

package/src/db.ts

@@ -18,10 +18,32 @@ export const ProcessSchema = z.object({
     stdout_path: z.string(),
     stderr_path: z.string(),
     timestamp: z.string().default(() => new Date().toISOString()),
+    group: z.string().default(''),
 });
 
 export type Process = z.infer<typeof ProcessSchema> & { id: number };
 
+export const TemplateSchema = z.object({
+    name: z.string(),
+    command: z.string(),
+    workdir: z.string().default(''),
+    env: z.string().default(''),
+    group: z.string().default(''),
+    created_at: z.string().default(() => new Date().toISOString()),
+});
+
+export type Template = z.infer<typeof TemplateSchema> & { id: number };
+
+export const HistorySchema = z.object({
+    process_name: z.string(),
+    event: z.string(), // 'start', 'stop', 'restart', 'crash', 'guard_on', 'guard_off'
+    pid: z.number().optional(),
+    timestamp: z.string().default(() => new Date().toISOString()),
+    metadata: z.string().default(''), // JSON string for extra info
+});
+
+export type History = z.infer<typeof HistorySchema> & { id: number };
+
 // =============================================================================
 // DATABASE INITIALIZATION
 // =============================================================================
@@ -48,9 +70,13 @@ if (!existsSync(dbPath) && existsSync(legacyDbPath)) {
 
 export const db = new Database(dbPath, {
     process: ProcessSchema,
+    template: TemplateSchema,
+    history: HistorySchema,
 }, {
     indexes: {
         process: ['name', 'timestamp', 'pid'],
+        template: ['name'],
+        history: ['process_name', 'timestamp'],
     },
 });
 
@@ -127,6 +153,95 @@ export function updateProcessEnv(name: string, envJson: string) {
     }
 }
 
+// =============================================================================
+// TEMPLATE FUNCTIONS
+// =============================================================================
+
+export function getAllTemplates() {
+    return db.template.select().all();
+}
+
+export function getTemplate(name: string) {
+    return db.template.select().where({ name }).limit(1).get() || null;
+}
+
+export function saveTemplate(data: {
+    name: string;
+    command: string;
+    workdir?: string;
+    env?: string;
+    group?: string;
+}) {
+    const existing = db.template.select().where({ name: data.name }).limit(1).get();
+    if (existing) {
+        db.template.update(existing.id, {
+            command: data.command,
+            workdir: data.workdir || '',
+            env: data.env || '',
+            group: data.group || '',
+        });
+    } else {
+        db.template.insert({
+            name: data.name,
+            command: data.command,
+            workdir: data.workdir || '',
+            env: data.env || '',
+            group: data.group || '',
+        });
+    }
+}
+
+export function deleteTemplate(name: string) {
+    const tmpl = db.template.select().where({ name }).limit(1).get();
+    if (tmpl) {
+        db.template.delete(tmpl.id);
+    }
+}
+
+// =============================================================================
+// HISTORY FUNCTIONS
+// =============================================================================
+
+export function getProcessHistory(name: string, limit = 50) {
+    return db.history.select()
+        .where({ process_name: name })
+        .orderBy('timestamp', 'desc')
+        .limit(limit)
+        .all();
+}
+
+export function addHistoryEntry(processName: string, event: string, pid?: number, metadata = {}) {
+    return db.history.insert({
+        process_name: processName,
+        event,
+        pid,
+        metadata: JSON.stringify(metadata),
+    });
+}
+
+export function getRecentHistory(limit = 100) {
+    return db.history.select()
+        .orderBy('timestamp', 'desc')
+        .limit(limit)
+        .all();
+}
+
+export function clearOldHistory(daysToKeep = 30) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - daysToKeep);
+    const cutoffStr = cutoff.toISOString();
+    
+    const oldEntries = db.history.select()
+        .where('timestamp', '<', cutoffStr)
+        .all();
+    
+    for (const entry of oldEntries) {
+        db.history.delete(entry.id);
+    }
+    
+    return oldEntries.length;
+}
+
 // =============================================================================
 // DEBUG / INFO
 // =============================================================================

package/src/guard.ts

@@ -18,6 +18,11 @@ import { getAllProcesses, getProcess } from './db';
 import { isProcessRunning, getProcessPorts, findChildPid } from './platform';
 import { handleRun } from './commands/run';
 import { parseEnvString } from './utils';
+import { createHmac } from 'crypto';
+
+// Webhook configuration via environment variables
+const WEBHOOK_URL = process.env.BGR_WEBHOOK_URL || '';
+const WEBHOOK_SECRET = process.env.BGR_WEBHOOK_SECRET || '';
 
 const DEFAULT_INTERVAL_MS = 30_000;
 const MAX_BACKOFF_MS = 5 * 60_000; // 5 minutes max
@@ -36,6 +41,42 @@ const state: GuardState = {
     lastSeenAlive: new Map(),
 };
 
+async function notifyWebhook(event: 'crash' | 'restart' | 'restart_failed', name: string, details: Record<string, any>) {
+    if (!WEBHOOK_URL) return;
+    try {
+        const payload = JSON.stringify({
+            event,
+            process: name,
+            timestamp: new Date().toISOString(),
+            ...details,
+        });
+
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'bgrun-guard/1.0',
+        };
+
+        // HMAC signature if secret is configured
+        if (WEBHOOK_SECRET) {
+            const sig = createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
+            headers['X-BGR-Signature'] = `sha256=${sig}`;
+        }
+
+        // Fire and forget with timeout
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        await fetch(WEBHOOK_URL, {
+            method: 'POST',
+            headers,
+            body: payload,
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+    } catch (err: any) {
+        console.error(`[guard] Webhook failed: ${err.message}`);
+    }
+}
+
 async function restartProcess(name: string): Promise<boolean> {
     try {
         await handleRun({
@@ -94,6 +135,9 @@ async function guardCycle(): Promise<void> {
 
                     console.log(`[guard] ⚠ "${proc.name}" (PID ${proc.pid}) is dead — restarting...`);
 
+                    // Notify crash detected
+                    notifyWebhook('crash', proc.name, { pid: proc.pid, isDashboard });
+
                     const success = await restartProcess(proc.name);
                     if (success) {
                         const count = (state.restartCounts.get(proc.name) || 0) + 1;
@@ -108,6 +152,12 @@ async function guardCycle(): Promise<void> {
                             console.log(`[guard] ✓ Restarted "${proc.name}" (#${count})`);
                         }
                         restarted++;
+
+                        // Notify restart success
+                        notifyWebhook('restart', proc.name, { pid: proc.pid, restartCount: count, backoffMs: backoff });
+                    } else {
+                        // Notify restart failed
+                        notifyWebhook('restart_failed', proc.name, { pid: proc.pid });
                     }
                 } else if (alive) {
                     // Track stability — if alive for STABILITY_WINDOW, reset counters
@@ -146,6 +196,7 @@ export async function startGuardLoop(intervalMs: number = DEFAULT_INTERVAL_MS) {
     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]    Webhook: ${WEBHOOK_URL || '(none — set BGR_WEBHOOK_URL to enable)'}`);
     console.log(`[guard]    Started: ${new Date().toLocaleString()}`);
     console.log(`[guard] ═══════════════════════════════════════════`);
 

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, isPortFree } from "./platform";
+import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree, isPortFree, findPidByPort } from "./platform";
 import { insertProcess, removeProcessByName, getProcess, retryDatabaseOperation, getDbInfo } from "./db";
 import dedent from "dedent";
 import chalk from "chalk";
@@ -26,6 +26,48 @@ if (!Bun.argv.includes("--_serve")) {
   }
 }
 
+/**
+ * Redirect console.log/warn/error to log files when running detached.
+ * The parent spawner passes file paths via BGR_STDOUT/BGR_STDERR env vars.
+ * Appends timestamped lines so `bgrun <name> --logs` shows real output.
+ */
+function redirectConsoleToFiles() {
+  const stdoutPath = Bun.env.BGR_STDOUT;
+  const stderrPath = Bun.env.BGR_STDERR;
+  if (!stdoutPath && !stderrPath) return; // Not detached, keep normal console
+
+  const { appendFileSync } = require('fs');
+
+  // Strip ANSI escape codes for clean log files
+  const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+  const timestamp = () => new Date().toISOString().replace('T', ' ').substring(0, 19);
+
+  if (stdoutPath) {
+    const origLog = console.log;
+    const origWarn = console.warn;
+    console.log = (...args: any[]) => {
+      const line = `[${timestamp()}] ${stripAnsi(args.map(String).join(' '))}\n`;
+      try { appendFileSync(stdoutPath, line); } catch { }
+      origLog.apply(console, args); // Also keep original (goes to /dev/null when detached, but useful if attached)
+    };
+    console.warn = (...args: any[]) => {
+      const line = `[${timestamp()}] WARN: ${stripAnsi(args.map(String).join(' '))}\n`;
+      try { appendFileSync(stdoutPath, line); } catch { }
+      origWarn.apply(console, args);
+    };
+  }
+
+  if (stderrPath) {
+    const origError = console.error;
+    console.error = (...args: any[]) => {
+      const line = `[${timestamp()}] ERROR: ${stripAnsi(args.map(String).join(' '))}\n`;
+      try { appendFileSync(stderrPath, line); } catch { }
+      origError.apply(console, args);
+    };
+  }
+}
+
 async function showHelp() {
   const usage = dedent`
     ${chalk.bold('bgrun — Bun Background Runner')}
@@ -120,6 +162,9 @@ async function run() {
   // Port is NOT passed explicitly — Melina auto-detects from BUN_PORT env
   // or defaults to 3000 with fallback to next available port.
   if (values['_serve']) {
+    // Redirect console output to log files when running detached
+    // The spawner passes paths via BGR_STDOUT/BGR_STDERR env vars
+    redirectConsoleToFiles();
     const { startServer } = await import("./server");
     await startServer();
     return;
@@ -127,6 +172,8 @@ async function run() {
 
   // Internal: actually run the guard loop (spawned by --guard)
   if (values['_guard-loop']) {
+    // Redirect console output to log files when running detached
+    redirectConsoleToFiles();
     const { startGuardLoop } = await import("./guard");
     const intervalStr = positionals[0];
     const intervalMs = intervalStr ? parseInt(intervalStr) * 1000 : undefined;
@@ -193,10 +240,13 @@ async function run() {
     await Bun.write(stderrPath, '');
 
     // Pass BUN_PORT env var only if user explicitly requested a port
-    const spawnEnv = { ...Bun.env };
+    const spawnEnv: Record<string, string> = { ...Bun.env } as any;
     if (requestedPort) {
       spawnEnv.BUN_PORT = requestedPort;
     }
+    // Pass log paths so the detached process can redirect its own console output
+    spawnEnv.BGR_STDOUT = stdoutPath;
+    spawnEnv.BGR_STDERR = stderrPath;
 
     // Resolve the target port: --port flag > BUN_PORT env > default 3000
     const targetPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
@@ -216,16 +266,18 @@ async function run() {
     const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
       env: spawnEnv,
       cwd: bgrDir,
-      stdout: Bun.file(stdoutPath),
-      stderr: Bun.file(stderrPath),
-    });
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true, // Windows: new process group outside parent's Job Object — survives terminal close
+    } as any);
 
     newProcess.unref();
 
-    // Resolve the actual child PID by traversing the process tree
-    // (cmd.exe → bun.exe), then detect which port it bound
+    // With detached: cmd.exe wrapper exits immediately, so findChildPid won't work.
+    // Instead, wait for the server to bind a port and find the PID from there.
     await sleep(2000); // Give the server time to start and bind a port
-    const actualPid = await findChildPid(newProcess.pid);
+    const resolvedPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
+    const actualPid = await findPidByPort(resolvedPort, 10000) ?? await findChildPid(newProcess.pid);
 
     // Detect the port the server actually bound to
     let actualPort: number | null = null;
@@ -310,15 +362,27 @@ async function run() {
     await Bun.write(stderrPath, '');
 
     const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
-      env: { ...Bun.env },
+      env: { ...Bun.env, BGR_STDOUT: stdoutPath, BGR_STDERR: stderrPath },
       cwd: bgrDir,
-      stdout: Bun.file(stdoutPath),
-      stderr: Bun.file(stderrPath),
-    });
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true, // Windows: new process group outside parent's Job Object — survives terminal close
+    } as any);
 
     newProcess.unref();
     await sleep(1000);
-    const actualPid = await findChildPid(newProcess.pid);
+    // With detached: cmd.exe exits immediately. Search for the guard by command line.
+    let actualPid = await findChildPid(newProcess.pid);
+    if (!(await isProcessRunning(actualPid))) {
+      // cmd.exe already died — search for the bun process running --_guard-loop
+      const { psExec: ps } = await import('./platform');
+      const result = ps(
+        `Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | Where-Object { $_.CommandLine -match '_guard-loop' } | Sort-Object -Property CreationDate -Descending | Select-Object -First 1 -ExpandProperty ProcessId`,
+        3000
+      );
+      const foundPid = parseInt(result.trim());
+      if (!isNaN(foundPid) && foundPid > 0) actualPid = foundPid;
+    }
 
     await retryDatabaseOperation(() =>
       insertProcess({
@@ -541,5 +605,10 @@ async function run() {
 }
 
 run().catch(err => {
-  error(err);
+  // BgrunError was already printed by error() — just exit
+  // For unexpected errors, print and exit
+  if (err.name !== 'BgrunError') {
+    console.error(err);
+  }
+  process.exit(1);
 });