@episoda/cli 0.2.175 → 0.2.176

package/dist/daemon/daemon-process.js

@@ -2187,6 +2187,7 @@ var require_websocket_client = __commonJS({
       constructor() {
         this.eventHandlers = /* @__PURE__ */ new Map();
         this.reconnectAttempts = 0;
+        this.autoReconnectEnabled = true;
         this.url = "";
         this.token = "";
         this.isConnected = false;
@@ -2235,7 +2236,7 @@ var require_websocket_client = __commonJS({
           clearTimeout(this.reconnectTimeout);
           this.reconnectTimeout = void 0;
         }
-        return new Promise((resolve6, reject) => {
+        return new Promise((resolve7, reject) => {
           const connectionTimeout = setTimeout(() => {
             if (this.ws) {
               this.ws.terminate();
@@ -2266,7 +2267,7 @@ var require_websocket_client = __commonJS({
                 daemonPid: this.daemonPid
               });
               this.startHeartbeat();
-              resolve6();
+              resolve7();
             });
             this.ws.on("pong", () => {
               if (this.heartbeatTimeoutTimer) {
@@ -2288,7 +2289,7 @@ var require_websocket_client = __commonJS({
             this.ws.on("close", (code, reason) => {
               console.log(`[EpisodaClient] WebSocket closed: ${code} ${reason.toString()}`);
               this.isConnected = false;
-              const willReconnect = !this.isDisconnecting;
+              const willReconnect = !this.isDisconnecting && this.autoReconnectEnabled;
               this.emit({
                 type: "disconnected",
                 code,
@@ -2312,6 +2313,19 @@ var require_websocket_client = __commonJS({
           }
         });
       }
+      /**
+       * Enable/disable automatic reconnect scheduling.
+       *
+       * This lets daemon startup/handshake own retry policy without competing
+       * with client-side reconnect loops.
+       */
+      setAutoReconnect(enabled) {
+        this.autoReconnectEnabled = enabled;
+        if (!enabled && this.reconnectTimeout) {
+          clearTimeout(this.reconnectTimeout);
+          this.reconnectTimeout = void 0;
+        }
+      }
       /**
        * Disconnect from the server
        * @param intentional - If true, prevents automatic reconnection (user-initiated disconnect)
@@ -2397,13 +2411,13 @@ var require_websocket_client = __commonJS({
           console.warn("[EpisodaClient] Cannot send - WebSocket not connected");
           return false;
         }
-        return new Promise((resolve6) => {
+        return new Promise((resolve7) => {
           this.ws.send(JSON.stringify(message), (error) => {
             if (error) {
               console.error("[EpisodaClient] Failed to send message:", error);
-              resolve6(false);
+              resolve7(false);
             } else {
-              resolve6(true);
+              resolve7(true);
             }
           });
         });
@@ -2526,7 +2540,12 @@ var require_websocket_client = __commonJS({
         if (this.rateLimitBackoffUntil && Date.now() < this.rateLimitBackoffUntil) {
           const waitTime = this.rateLimitBackoffUntil - Date.now();
           console.log(`[EpisodaClient] Rate limited, waiting ${Math.round(waitTime / 1e3)}s before retry`);
-          this.reconnectAttempts++;
+          this.emit({
+            type: "reconnect_scheduled",
+            attempt: this.reconnectAttempts + 1,
+            delayMs: waitTime,
+            strategy: "rate_limited"
+          });
           this.reconnectTimeout = setTimeout(() => {
             this.rateLimitBackoffUntil = void 0;
             this.scheduleReconnect();
@@ -2534,6 +2553,7 @@ var require_websocket_client = __commonJS({
           return;
         }
         let delay;
+        let strategy = "connection_lost";
         let shouldRetry = true;
         const isCloudMode = this.environment === "cloud";
         const MAX_CLOUD_AUTH_FAILURES = 3;
@@ -2545,20 +2565,28 @@ var require_websocket_client = __commonJS({
           } else {
             delay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts), MAX_CLOUD_RECONNECT_DELAY);
             delay = applyJitter(delay);
+            strategy = "cloud";
             const delayStr = delay >= 6e4 ? `${Math.round(delay / 6e4)}m` : `${Math.round(delay / 1e3)}s`;
             console.log(`[EpisodaClient] Cloud mode: reconnecting in ${delayStr}... (attempt ${this.reconnectAttempts + 1}, never giving up)`);
           }
         } else if (this.isGracefulShutdown && this.reconnectAttempts < 7) {
           delay = Math.min(500 * Math.pow(2, this.reconnectAttempts), 5e3);
           delay = applyJitter(delay);
+          strategy = "graceful_shutdown";
           console.log(`[EpisodaClient] Server restarting, reconnecting in ${delay}ms (attempt ${this.reconnectAttempts + 1}/7)`);
         } else {
           delay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts), MAX_LOCAL_RECONNECT_DELAY);
           delay = applyJitter(delay);
+          strategy = "connection_lost";
           const delayStr = delay >= 6e4 ? `${Math.round(delay / 6e4)}m` : `${Math.round(delay / 1e3)}s`;
           console.log(`[EpisodaClient] Connection lost, retrying in ${delayStr}... (attempt ${this.reconnectAttempts + 1}, retrying until connected)`);
         }
         if (!shouldRetry) {
+          this.emit({
+            type: "reconnect_exhausted",
+            attempts: this.reconnectAttempts,
+            reason: `retry_exhausted_after_${this.consecutiveAuthFailures}_auth_failures`
+          });
           this.emit({
             type: "disconnected",
             code: 1006,
@@ -2567,9 +2595,20 @@ var require_websocket_client = __commonJS({
           });
           return;
         }
-        this.reconnectAttempts++;
+        const reconnectAttempt = this.reconnectAttempts + 1;
+        this.reconnectAttempts = reconnectAttempt;
+        this.emit({
+          type: "reconnect_scheduled",
+          attempt: reconnectAttempt,
+          delayMs: delay,
+          strategy
+        });
         this.reconnectTimeout = setTimeout(() => {
           console.log("[EpisodaClient] Attempting reconnection...");
+          this.emit({
+            type: "reconnect_attempt",
+            attempt: reconnectAttempt
+          });
           this.connect(this.url, this.token, this.machineId, {
             hostname: this.hostname,
             osPlatform: this.osPlatform,
@@ -2582,6 +2621,11 @@ var require_websocket_client = __commonJS({
             containerId: this.containerId
           }).then(() => {
             console.log("[EpisodaClient] Reconnection successful");
+            this.emit({
+              type: "reconnect_result",
+              attempt: reconnectAttempt,
+              success: true
+            });
             this.reconnectAttempts = 0;
             this.isGracefulShutdown = false;
             this.firstDisconnectTime = void 0;
@@ -2589,6 +2633,12 @@ var require_websocket_client = __commonJS({
             this.consecutiveAuthFailures = 0;
           }).catch((error) => {
             console.error("[EpisodaClient] Reconnection failed:", error.message);
+            this.emit({
+              type: "reconnect_result",
+              attempt: reconnectAttempt,
+              success: false,
+              error: error instanceof Error ? error.message : String(error)
+            });
           });
         }, delay);
       }
@@ -2996,7 +3046,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@episoda/cli",
-      version: "0.2.175",
+      version: "0.2.176",
       description: "CLI tool for Episoda local development workflow orchestration",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -3255,6 +3305,16 @@ function touchProject(projectPath) {
     writeProjects(data);
   }
 }
+function pruneMissingProjectPaths() {
+  const data = readProjects();
+  const initialLength = data.projects.length;
+  data.projects = data.projects.filter((project) => fs2.existsSync(project.path));
+  const removedCount = initialLength - data.projects.length;
+  if (removedCount > 0) {
+    writeProjects(data);
+  }
+  return removedCount;
+}
 
 // src/daemon/daemon-manager.ts
 var path3 = __toESM(require("path"));
@@ -3301,10 +3361,10 @@ var IPCServer = class {
     this.server = net.createServer((socket) => {
       this.handleConnection(socket);
     });
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       this.server.listen(socketPath, () => {
         fs3.chmodSync(socketPath, 384);
-        resolve6();
+        resolve7();
       });
       this.server.on("error", reject);
     });
@@ -3315,12 +3375,12 @@ var IPCServer = class {
   async stop() {
     if (!this.server) return;
     const socketPath = getSocketPath();
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       this.server.close(() => {
         if (fs3.existsSync(socketPath)) {
           fs3.unlinkSync(socketPath);
         }
-        resolve6();
+        resolve7();
       });
     });
   }
@@ -3389,8 +3449,24 @@ var import_child_process2 = require("child_process");
 var import_util = require("util");
 var import_core5 = __toESM(require_dist());
 var execAsync = (0, import_util.promisify)(import_child_process2.exec);
+async function isGitRepository(projectPath) {
+  try {
+    await execAsync("git rev-parse --git-dir", { cwd: projectPath, timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function cleanupStaleCommits(projectPath) {
   try {
+    if (!await isGitRepository(projectPath)) {
+      return {
+        success: true,
+        deleted_count: 0,
+        kept_count: 0,
+        message: "Skipping cleanup: project path is not a git repository"
+      };
+    }
     const machineId = await getMachineId();
     const config = await (0, import_core5.loadConfig)();
     if (!config?.access_token) {
@@ -3404,7 +3480,10 @@ async function cleanupStaleCommits(projectPath) {
     try {
       await execAsync("git fetch origin", { cwd: projectPath, timeout: 3e4 });
     } catch (fetchError) {
-      console.warn("[EP950] Could not fetch origin:", fetchError);
+      const fetchMessage = fetchError instanceof Error ? fetchError.message : String(fetchError);
+      if (!fetchMessage.includes("not a git repository")) {
+        console.warn("[EP950] Could not fetch origin:", fetchError);
+      }
     }
     let currentBranch = "";
     try {
@@ -3546,7 +3625,7 @@ function getDownloadUrl() {
   return platformUrls[arch4] || null;
 }
 async function downloadFile(url, destPath) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const followRedirect = (currentUrl, redirectCount = 0) => {
       if (redirectCount > 5) {
         reject(new Error("Too many redirects"));
@@ -3576,7 +3655,7 @@ async function downloadFile(url, destPath) {
         response.pipe(file);
         file.on("finish", () => {
           file.close();
-          resolve6();
+          resolve7();
         });
         file.on("error", (err) => {
           fs4.unlinkSync(destPath);
@@ -3990,10 +4069,10 @@ var TunnelManager = class extends import_events.EventEmitter {
       const isTracked = Array.from(this.tunnelStates.values()).some((s) => s.info.pid === pid);
       console.log(`[Tunnel] EP904: Found cloudflared PID ${pid} on port ${port} (tracked: ${isTracked})`);
       this.killByPid(pid, "SIGTERM");
-      await new Promise((resolve6) => setTimeout(resolve6, 500));
+      await new Promise((resolve7) => setTimeout(resolve7, 500));
       if (this.isProcessRunning(pid)) {
         this.killByPid(pid, "SIGKILL");
-        await new Promise((resolve6) => setTimeout(resolve6, 200));
+        await new Promise((resolve7) => setTimeout(resolve7, 200));
       }
       killed.push(pid);
     }
@@ -4027,7 +4106,7 @@ var TunnelManager = class extends import_events.EventEmitter {
           if (!this.tunnelStates.has(moduleUid)) {
             console.log(`[Tunnel] EP877: Found orphaned process PID ${pid} for ${moduleUid}, killing...`);
             this.killByPid(pid, "SIGTERM");
-            await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+            await new Promise((resolve7) => setTimeout(resolve7, 1e3));
             if (this.isProcessRunning(pid)) {
               this.killByPid(pid, "SIGKILL");
             }
@@ -4042,7 +4121,7 @@ var TunnelManager = class extends import_events.EventEmitter {
         if (!trackedPids.includes(pid) && !cleaned.includes(pid)) {
           console.log(`[Tunnel] EP877: Found untracked cloudflared process PID ${pid}, killing...`);
           this.killByPid(pid, "SIGTERM");
-          await new Promise((resolve6) => setTimeout(resolve6, 500));
+          await new Promise((resolve7) => setTimeout(resolve7, 500));
           if (this.isProcessRunning(pid)) {
             this.killByPid(pid, "SIGKILL");
           }
@@ -4132,7 +4211,7 @@ var TunnelManager = class extends import_events.EventEmitter {
         return { success: false, error: `Failed to get cloudflared: ${errorMessage}` };
       }
     }
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       const tunnelInfo = {
         moduleUid,
         url: previewUrl || "",
@@ -4198,7 +4277,7 @@ var TunnelManager = class extends import_events.EventEmitter {
             moduleUid,
             url: tunnelInfo.url
           });
-          resolve6({ success: true, url: tunnelInfo.url });
+          resolve7({ success: true, url: tunnelInfo.url });
         }
       };
       process2.stderr?.on("data", (data) => {
@@ -4225,7 +4304,7 @@ var TunnelManager = class extends import_events.EventEmitter {
             onStatusChange?.("error", errorMsg);
             this.emitEvent({ type: "error", moduleUid, error: errorMsg });
           }
-          resolve6({ success: false, error: errorMsg });
+          resolve7({ success: false, error: errorMsg });
         } else if (wasConnected) {
           if (currentState && !currentState.intentionallyStopped) {
             console.log(`[Tunnel] EP948: Named tunnel ${moduleUid} crashed unexpectedly, attempting reconnect...`);
@@ -4256,7 +4335,7 @@ var TunnelManager = class extends import_events.EventEmitter {
           this.emitEvent({ type: "error", moduleUid, error: error.message });
         }
         if (!connected) {
-          resolve6({ success: false, error: error.message });
+          resolve7({ success: false, error: error.message });
         }
       });
       setTimeout(() => {
@@ -4279,7 +4358,7 @@ var TunnelManager = class extends import_events.EventEmitter {
             onStatusChange?.("error", errorMsg);
             this.emitEvent({ type: "error", moduleUid, error: errorMsg });
           }
-          resolve6({ success: false, error: errorMsg });
+          resolve7({ success: false, error: errorMsg });
         }
       }, TUNNEL_TIMEOUTS.NAMED_TUNNEL_CONNECT);
     });
@@ -4340,7 +4419,7 @@ var TunnelManager = class extends import_events.EventEmitter {
     if (orphanPid && this.isProcessRunning(orphanPid)) {
       console.log(`[Tunnel] EP877: Killing orphaned process ${orphanPid} for ${moduleUid} before starting new tunnel`);
       this.killByPid(orphanPid, "SIGTERM");
-      await new Promise((resolve6) => setTimeout(resolve6, 500));
+      await new Promise((resolve7) => setTimeout(resolve7, 500));
       if (this.isProcessRunning(orphanPid)) {
         this.killByPid(orphanPid, "SIGKILL");
       }
@@ -4349,7 +4428,7 @@ var TunnelManager = class extends import_events.EventEmitter {
     const killedOnPort = await this.killCloudflaredOnPort(port);
     if (killedOnPort.length > 0) {
       console.log(`[Tunnel] EP904: Pre-start port cleanup killed ${killedOnPort.length} process(es) on port ${port}`);
-      await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+      await new Promise((resolve7) => setTimeout(resolve7, 1e3));
     }
     const cleanup = await this.cleanupOrphanedProcesses();
     if (cleanup.cleaned > 0) {
@@ -4389,7 +4468,7 @@ var TunnelManager = class extends import_events.EventEmitter {
       if (orphanPid && this.isProcessRunning(orphanPid)) {
         console.log(`[Tunnel] EP877: Stopping orphaned process ${orphanPid} for ${moduleUid} via PID file`);
         this.killByPid(orphanPid, "SIGTERM");
-        await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+        await new Promise((resolve7) => setTimeout(resolve7, 1e3));
         if (this.isProcessRunning(orphanPid)) {
           this.killByPid(orphanPid, "SIGKILL");
         }
@@ -4405,16 +4484,16 @@ var TunnelManager = class extends import_events.EventEmitter {
     const tunnel = state.info;
     if (tunnel.process && !tunnel.process.killed) {
       tunnel.process.kill("SIGTERM");
-      await new Promise((resolve6) => {
+      await new Promise((resolve7) => {
         const timeout = setTimeout(() => {
           if (tunnel.process && !tunnel.process.killed) {
             tunnel.process.kill("SIGKILL");
           }
-          resolve6();
+          resolve7();
         }, 3e3);
         tunnel.process.once("exit", () => {
           clearTimeout(timeout);
-          resolve6();
+          resolve7();
         });
       });
     }
@@ -4701,15 +4780,15 @@ async function writeToStdinWithBackpressure(process2, data, drainTimeoutMs, labe
   if (!stdin || stdin.destroyed) {
     throw new Error(`[${label}] stdin not available. session=${sessionId}`);
   }
-  await new Promise((resolve6, reject) => {
+  await new Promise((resolve7, reject) => {
     const ok = stdin.write(data);
     if (ok) {
-      resolve6();
+      resolve7();
       return;
     }
     const onDrain = () => {
       cleanup();
-      resolve6();
+      resolve7();
     };
     const onError = (err) => {
       cleanup();
@@ -4730,18 +4809,18 @@ async function writeToStdinWithBackpressure(process2, data, drainTimeoutMs, labe
   });
 }
 function waitForProcessExit(process2, alive, timeoutMs) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     if (!process2 || !alive) {
-      resolve6(true);
+      resolve7(true);
       return;
     }
     const onExit = () => {
       clearTimeout(timer);
-      resolve6(true);
+      resolve7(true);
     };
     const timer = setTimeout(() => {
       process2.removeListener("exit", onExit);
-      resolve6(false);
+      resolve7(false);
     }, timeoutMs);
     process2.once("exit", onExit);
   });
@@ -5737,10 +5816,10 @@ var CodexPersistentRuntime = class {
   }
   waitForThreadId(timeoutMs) {
     if (this._agentSessionId) return Promise.resolve(this._agentSessionId);
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       const onId = (id) => {
         clearTimeout(timer);
-        resolve6(id);
+        resolve7(id);
       };
       const timer = setTimeout(() => {
         this.threadIdWaiters = this.threadIdWaiters.filter((w) => w !== onId);
@@ -5771,12 +5850,12 @@ var CodexPersistentRuntime = class {
   sendRequest(method, params, timeoutMs = INIT_TIMEOUT_MS) {
     const id = this.nextId++;
     const msg = { jsonrpc: "2.0", id, method, params };
-    return new Promise(async (resolve6, reject) => {
+    return new Promise(async (resolve7, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`JSON-RPC timeout: ${method}`));
       }, timeoutMs);
-      this.pending.set(id, { resolve: resolve6, reject, timeout });
+      this.pending.set(id, { resolve: resolve7, reject, timeout });
       try {
         await this.writeToStdin(JSON.stringify(msg) + "\n");
       } catch (err) {
@@ -5926,11 +6005,11 @@ var UnifiedAgentRuntime = class {
     if (!this.currentTurn && this.impl.turnState === "idle") {
       return this.dispatchTurn(message, callbacks);
     }
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       this.queuedTurns.push({
         message,
         callbacks,
-        resolve: resolve6,
+        resolve: resolve7,
         reject
       });
     });
@@ -7443,13 +7522,13 @@ async function getChildProcessRssMb(pid) {
   if (!pid || pid <= 0) return null;
   try {
     if (typeof import_child_process9.execFile !== "function") return null;
-    const stdout = await new Promise((resolve6, reject) => {
+    const stdout = await new Promise((resolve7, reject) => {
       (0, import_child_process9.execFile)("ps", ["-o", "rss=", "-p", String(pid)], { timeout: 1e3 }, (err, out) => {
         if (err) {
           reject(err);
           return;
         }
-        resolve6(String(out));
+        resolve7(String(out));
       });
     });
     const kb = Number(String(stdout).trim());
@@ -7552,8 +7631,8 @@ var AgentControlPlane = class {
   async withConfigLock(fn) {
     const previousLock = this.configWriteLock;
     let releaseLock;
-    this.configWriteLock = new Promise((resolve6) => {
-      releaseLock = resolve6;
+    this.configWriteLock = new Promise((resolve7) => {
+      releaseLock = resolve7;
     });
     try {
       await previousLock;
@@ -8782,7 +8861,7 @@ var WorktreeManager = class _WorktreeManager {
                 const lockContent = fs14.readFileSync(lockPath, "utf-8").trim();
                 const lockPid = parseInt(lockContent, 10);
                 if (!isNaN(lockPid) && this.isProcessRunning(lockPid)) {
-                  await new Promise((resolve6) => setTimeout(resolve6, retryInterval));
+                  await new Promise((resolve7) => setTimeout(resolve7, retryInterval));
                   continue;
                 }
               } catch {
@@ -8796,7 +8875,7 @@ var WorktreeManager = class _WorktreeManager {
           } catch {
             continue;
           }
-          await new Promise((resolve6) => setTimeout(resolve6, retryInterval));
+          await new Promise((resolve7) => setTimeout(resolve7, retryInterval));
           continue;
         }
         throw err;
@@ -9586,6 +9665,7 @@ function getInstallCommand(cwd) {
 var fs34 = __toESM(require("fs"));
 var http2 = __toESM(require("http"));
 var os15 = __toESM(require("os"));
+var import_child_process19 = require("child_process");
 
 // src/daemon/ipc-router.ts
 var os14 = __toESM(require("os"));
@@ -10319,7 +10399,7 @@ async function handleExec(command, projectPath) {
     env = {}
   } = command;
   const effectiveTimeout = Math.min(Math.max(timeout, 1e3), MAX_TIMEOUT);
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     let timedOut = false;
@@ -10327,7 +10407,7 @@ async function handleExec(command, projectPath) {
     const done = (result) => {
       if (resolved) return;
       resolved = true;
-      resolve6(result);
+      resolve7(result);
     };
     try {
       const proc = (0, import_child_process11.spawn)(cmd, {
@@ -10431,18 +10511,18 @@ var import_core12 = __toESM(require_dist());
 // src/utils/port-check.ts
 var net2 = __toESM(require("net"));
 async function isPortInUse(port) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     const server = net2.createServer();
     server.once("error", (err) => {
       if (err.code === "EADDRINUSE") {
-        resolve6(true);
+        resolve7(true);
       } else {
-        resolve6(false);
+        resolve7(false);
       }
     });
     server.once("listening", () => {
       server.close();
-      resolve6(false);
+      resolve7(false);
     });
     server.listen(port);
   });
@@ -10845,7 +10925,7 @@ var DevServerRegistry = class {
     return killed;
   }
   wait(ms) {
-    return new Promise((resolve6) => setTimeout(resolve6, ms));
+    return new Promise((resolve7) => setTimeout(resolve7, ms));
   }
   killWsServerOnPort(wsPort, worktreePath) {
     const killed = [];
@@ -11419,7 +11499,7 @@ var DevServerRunner = class extends import_events2.EventEmitter {
     return Math.min(delay, DEV_SERVER_CONSTANTS.MAX_RESTART_DELAY_MS);
   }
   async checkHealth(port) {
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       const req = http.request(
         {
           hostname: "localhost",
@@ -11428,18 +11508,18 @@ var DevServerRunner = class extends import_events2.EventEmitter {
           method: "HEAD",
           timeout: DEV_SERVER_CONSTANTS.HEALTH_CHECK_TIMEOUT_MS
         },
-        () => resolve6(true)
+        () => resolve7(true)
       );
-      req.on("error", () => resolve6(false));
+      req.on("error", () => resolve7(false));
       req.on("timeout", () => {
         req.destroy();
-        resolve6(false);
+        resolve7(false);
       });
       req.end();
     });
   }
   async checkWsHealth(wsPort) {
-    return new Promise((resolve6) => {
+    return new Promise((resolve7) => {
       const req = http.request(
         {
           hostname: "127.0.0.1",
@@ -11449,14 +11529,14 @@ var DevServerRunner = class extends import_events2.EventEmitter {
           timeout: DEV_SERVER_CONSTANTS.HEALTH_CHECK_TIMEOUT_MS
         },
         (res) => {
-          resolve6(res.statusCode === 200);
+          resolve7(res.statusCode === 200);
           res.resume();
         }
       );
-      req.on("error", () => resolve6(false));
+      req.on("error", () => resolve7(false));
       req.on("timeout", () => {
         req.destroy();
-        resolve6(false);
+        resolve7(false);
       });
       req.end();
     });
@@ -11484,7 +11564,7 @@ var DevServerRunner = class extends import_events2.EventEmitter {
     return false;
   }
   wait(ms) {
-    return new Promise((resolve6) => setTimeout(resolve6, ms));
+    return new Promise((resolve7) => setTimeout(resolve7, ms));
   }
   getLogsDir() {
     const logsDir = path25.join((0, import_core12.getConfigDir)(), "logs");
@@ -11683,7 +11763,7 @@ var PreviewManager = class extends import_events3.EventEmitter {
       for (let attempt = 1; attempt <= MAX_TUNNEL_RETRIES; attempt++) {
         if (attempt > 1) {
           console.log(`[PreviewManager] Retrying tunnel for ${moduleUid} (attempt ${attempt}/${MAX_TUNNEL_RETRIES})...`);
-          await new Promise((resolve6) => setTimeout(resolve6, 2e3));
+          await new Promise((resolve7) => setTimeout(resolve7, 2e3));
         }
         tunnelResult = await this.tunnel.startTunnel({
           moduleUid,
@@ -11815,7 +11895,7 @@ var PreviewManager = class extends import_events3.EventEmitter {
     }
     console.log(`[PreviewManager] Restarting preview for ${moduleUid}`);
     await this.stopPreview(moduleUid);
-    await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+    await new Promise((resolve7) => setTimeout(resolve7, 1e3));
     return this.startPreview({
       moduleUid,
       worktreePath: state.worktreePath,
@@ -12756,7 +12836,7 @@ async function killProcessOnPort(port) {
       } catch {
       }
     }
-    await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+    await new Promise((resolve7) => setTimeout(resolve7, 1e3));
     for (const pid of pids) {
       try {
         (0, import_child_process15.execSync)(`kill -0 ${pid} 2>/dev/null`, { encoding: "utf8" });
@@ -12765,7 +12845,7 @@ async function killProcessOnPort(port) {
       } catch {
       }
     }
-    await new Promise((resolve6) => setTimeout(resolve6, 500));
+    await new Promise((resolve7) => setTimeout(resolve7, 500));
     const stillInUse = await isPortInUse(port);
     if (stillInUse) {
       console.error(`[DevServer] EP929: Port ${port} still in use after kill attempts`);
@@ -12785,7 +12865,7 @@ async function waitForPort(port, timeoutMs = 3e4) {
     if (await isPortInUse(port)) {
       return true;
     }
-    await new Promise((resolve6) => setTimeout(resolve6, checkInterval));
+    await new Promise((resolve7) => setTimeout(resolve7, checkInterval));
   }
   return false;
 }
@@ -12857,7 +12937,7 @@ async function handleProcessExit(moduleUid, code, signal) {
   const delay = calculateRestartDelay(serverInfo.restartCount);
   console.log(`[DevServer] EP932: Restarting ${moduleUid} in ${delay}ms (attempt ${serverInfo.restartCount + 1}/${MAX_RESTART_ATTEMPTS})`);
   writeToLog(serverInfo.logFile || "", `Scheduling restart in ${delay}ms (attempt ${serverInfo.restartCount + 1})`, false);
-  await new Promise((resolve6) => setTimeout(resolve6, delay));
+  await new Promise((resolve7) => setTimeout(resolve7, delay));
   if (!activeServers.has(moduleUid)) {
     console.log(`[DevServer] EP932: Server ${moduleUid} was removed during restart delay, aborting restart`);
     return;
@@ -12982,7 +13062,7 @@ async function stopDevServer(moduleUid) {
       writeToLog(serverInfo.logFile, `Stopping server (manual stop)`, false);
     }
     serverInfo.process.kill("SIGTERM");
-    await new Promise((resolve6) => setTimeout(resolve6, 2e3));
+    await new Promise((resolve7) => setTimeout(resolve7, 2e3));
     if (!serverInfo.process.killed) {
       serverInfo.process.kill("SIGKILL");
     }
@@ -13000,7 +13080,7 @@ async function restartDevServer(moduleUid) {
     writeToLog(logFile, `Manual restart requested`, false);
   }
   await stopDevServer(moduleUid);
-  await new Promise((resolve6) => setTimeout(resolve6, 1e3));
+  await new Promise((resolve7) => setTimeout(resolve7, 1e3));
   if (await isPortInUse(port)) {
     await killProcessOnPort(port);
   }
@@ -13062,7 +13142,6 @@ var IPCRouter = class {
     });
     this.ipcServer.on("add-project", async (params) => {
       const { projectId, projectPath } = params;
-      addProject(projectId, projectPath);
       const MAX_RETRIES = 3;
       const INITIAL_DELAY = 1e3;
       let lastError = "";
@@ -13075,6 +13154,7 @@ var IPCRouter = class {
             lastError = "Connection established but not healthy";
             return { success: false, connected: false, error: lastError };
           }
+          addProject(projectId, projectPath);
           return { success: true, connected: true };
         } catch (error) {
           lastError = error instanceof Error ? error.message : String(error);
@@ -13082,7 +13162,7 @@ var IPCRouter = class {
           if (attempt < MAX_RETRIES) {
             const delay = INITIAL_DELAY * Math.pow(2, attempt - 1);
             console.log(`[Daemon] Retrying in ${delay / 1e3}s...`);
-            await new Promise((resolve6) => setTimeout(resolve6, delay));
+            await new Promise((resolve7) => setTimeout(resolve7, delay));
             await this.host.disconnectProject(projectPath);
           }
         }
@@ -13522,6 +13602,8 @@ var UpdateManager = class _UpdateManager {
       const child = (0, import_child_process17.spawn)("node", [this.daemonEntryFile], {
         detached: true,
         stdio: ["ignore", logFd, logFd],
+        cwd: configDir,
+        // Keep daemon process context stable across restarts.
         env: { ...process.env, EPISODA_DAEMON_MODE: "1" }
       });
       if (!child.pid) {
@@ -14234,45 +14316,54 @@ var DaemonCore = class {
 // src/daemon/connection-manager.ts
 var ConnectionManager = class {
   constructor() {
+    // Single source-of-truth for project connectivity.
     this.connections = /* @__PURE__ */ new Map();
-    // projectPath -> connection
-    this.liveConnections = /* @__PURE__ */ new Set();
-    // projectPath
-    this.pendingConnections = /* @__PURE__ */ new Set();
   }
-  // projectPath
+  // projectPath -> connection
   hasConnection(projectPath) {
     return this.connections.has(projectPath);
   }
   hasLiveConnection(projectPath) {
-    return this.liveConnections.has(projectPath);
+    return this.getState(projectPath) === "connected";
   }
   hasPendingConnection(projectPath) {
-    return this.pendingConnections.has(projectPath);
+    const state = this.getState(projectPath);
+    return state === "connecting" || state === "authenticating";
   }
   isConnectionHealthy(projectPath) {
-    return this.connections.has(projectPath) && this.liveConnections.has(projectPath);
+    return this.getState(projectPath) === "connected" && this.isWebSocketOpen(projectPath);
   }
   getConnection(projectPath) {
     return this.connections.get(projectPath);
   }
   setConnection(projectPath, connection) {
-    this.connections.set(projectPath, connection);
+    const stateful = {
+      ...connection,
+      state: connection.state || "connecting",
+      lastTransitionAt: connection.lastTransitionAt || Date.now()
+    };
+    this.connections.set(projectPath, stateful);
   }
   deleteConnection(projectPath) {
     this.connections.delete(projectPath);
   }
   addLiveConnection(projectPath) {
-    this.liveConnections.add(projectPath);
+    this.setState(projectPath, "connected");
   }
   removeLiveConnection(projectPath) {
-    this.liveConnections.delete(projectPath);
+    const state = this.getState(projectPath);
+    if (state === "connected") {
+      this.setState(projectPath, "disconnected");
+    }
   }
   addPendingConnection(projectPath) {
-    this.pendingConnections.add(projectPath);
+    this.setState(projectPath, "connecting");
   }
   removePendingConnection(projectPath) {
-    this.pendingConnections.delete(projectPath);
+    const state = this.getState(projectPath);
+    if (state === "connecting" || state === "authenticating") {
+      this.setState(projectPath, "disconnected");
+    }
   }
   isWebSocketOpen(projectPath) {
     const connection = this.connections.get(projectPath);
@@ -14283,10 +14374,18 @@ var ConnectionManager = class {
     return this.connections.size;
   }
   liveConnectionCount() {
-    return this.liveConnections.size;
+    let count = 0;
+    for (const connection of this.connections.values()) {
+      if (connection.state === "connected") count++;
+    }
+    return count;
   }
   pendingConnectionCount() {
-    return this.pendingConnections.size;
+    let count = 0;
+    for (const connection of this.connections.values()) {
+      if (connection.state === "connecting" || connection.state === "authenticating") count++;
+    }
+    return count;
   }
   entries() {
     return this.connections.entries();
@@ -14295,12 +14394,24 @@ var ConnectionManager = class {
     this.connections.clear();
   }
   clearLiveConnections() {
-    this.liveConnections.clear();
+    for (const [projectPath, connection] of this.connections.entries()) {
+      if (connection.state === "connected") {
+        this.setState(projectPath, "disconnected");
+      }
+    }
   }
   clearPendingConnections() {
-    this.pendingConnections.clear();
+    for (const [projectPath, connection] of this.connections.entries()) {
+      if (connection.state === "connecting" || connection.state === "authenticating") {
+        this.setState(projectPath, "disconnected");
+      }
+    }
   }
   async restoreConnections(connectProject) {
+    const pruned = pruneMissingProjectPaths();
+    if (pruned > 0) {
+      console.log(`[Daemon] Pruned ${pruned} stale project tracking entr${pruned === 1 ? "y" : "ies"} before restore`);
+    }
     const projects = getAllProjects();
     for (const project of projects) {
       try {
@@ -14310,19 +14421,31 @@ var ConnectionManager = class {
       }
     }
   }
+  getState(projectPath) {
+    return this.connections.get(projectPath)?.state || null;
+  }
+  setState(projectPath, state, error) {
+    const connection = this.connections.get(projectPath);
+    if (!connection) return;
+    connection.state = state;
+    connection.lastTransitionAt = Date.now();
+    connection.lastError = error;
+  }
   /**
-   * Wait for auth_success or auth_error after a successful WebSocket connect().
+   * Wait for auth_success or fail-fast auth/transport errors after connect().
    *
    * This keeps auth timeout lifecycle in the connection subsystem and ensures
    * handlers are removed deterministically on every exit path.
    */
   async waitForAuthentication(client, timeoutMs = 3e4) {
-    await new Promise((resolve6, reject) => {
+    await new Promise((resolve7, reject) => {
       let settled = false;
       const cleanup = () => {
         clearTimeout(timeout);
         client.off("auth_success", authHandler);
-        client.off("auth_error", errorHandler);
+        client.off("auth_error", authErrorHandler);
+        client.off("error", serverErrorHandler);
+        client.off("disconnected", disconnectedHandler);
       };
       const timeout = setTimeout(() => {
         if (settled) return;
@@ -14334,17 +14457,41 @@ var ConnectionManager = class {
         if (settled) return;
         settled = true;
         cleanup();
-        resolve6();
+        resolve7();
       };
-      const errorHandler = (message) => {
+      const authErrorHandler = (message) => {
         if (settled) return;
         settled = true;
         cleanup();
         const errorMsg = message;
         reject(new Error(errorMsg.message || "Authentication failed"));
       };
+      const serverErrorHandler = (message) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        const errorMsg = message;
+        const code = errorMsg.code || "SERVER_ERROR";
+        if (code === "TOO_SOON" && typeof errorMsg.retryAfter === "number") {
+          reject(new Error(`Authentication deferred by server (${code}, retryAfter=${errorMsg.retryAfter}s)`));
+          return;
+        }
+        reject(new Error(errorMsg.message || `Authentication failed (${code})`));
+      };
+      const disconnectedHandler = (message) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        const event = message;
+        const code = typeof event.code === "number" ? event.code : -1;
+        const reason = event.reason || "connection closed";
+        const suffix = event.willReconnect ? ", reconnect scheduled" : "";
+        reject(new Error(`Connection closed before authentication (code=${code}, reason=${reason}${suffix})`));
+      };
       client.on("auth_success", authHandler);
-      client.on("auth_error", errorHandler);
+      client.on("auth_error", authErrorHandler);
+      client.on("error", serverErrorHandler);
+      client.on("disconnected", disconnectedHandler);
     });
   }
 };
@@ -14911,6 +15058,8 @@ var Daemon = class _Daemon {
     // EP1003: Prevents race conditions between server-orchestrated tunnel commands
     this.tunnelOperationLocks = /* @__PURE__ */ new Map();
     // moduleUid -> operation promise
+    // EP1426: Single in-flight connect attempt per project path.
+    this.connectProjectInFlight = /* @__PURE__ */ new Map();
     // EP1210-7: Health HTTP endpoint for external monitoring
     this.healthServer = null;
     // EP1267: Cloud disconnect watchdog
@@ -14948,6 +15097,14 @@ var Daemon = class _Daemon {
     this.agentEventSeq.set(sessionId, next);
     return next;
   }
+  logReliabilityMetric(metric, fields) {
+    console.log(`[Daemon][Metric] ${JSON.stringify({
+      metric,
+      machineId: this.machineId || "unknown",
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      ...fields
+    })}`);
+  }
   /**
    * Start the daemon
    */
@@ -15144,8 +15301,8 @@ var Daemon = class _Daemon {
       }
     }
     let releaseLock;
-    const lockPromise = new Promise((resolve6) => {
-      releaseLock = resolve6;
+    const lockPromise = new Promise((resolve7) => {
+      releaseLock = resolve7;
     });
     this.tunnelOperationLocks.set(moduleUid, lockPromise);
     try {
@@ -15162,6 +15319,25 @@ var Daemon = class _Daemon {
    * EP1366: Made public for IPCRouterHost interface
    */
   async connectProject(projectId, projectPath) {
+    const existing = this.connectProjectInFlight.get(projectPath);
+    if (existing) {
+      console.log(`[Daemon] Connection attempt already in progress for ${projectPath}, joining existing attempt`);
+      return existing;
+    }
+    const attempt = this.connectProjectInternal(projectId, projectPath);
+    this.connectProjectInFlight.set(projectPath, attempt);
+    try {
+      await attempt;
+    } finally {
+      if (this.connectProjectInFlight.get(projectPath) === attempt) {
+        this.connectProjectInFlight.delete(projectPath);
+      }
+    }
+  }
+  async connectProjectInternal(projectId, projectPath) {
+    const initialState = this.connectionManager.getState(projectPath);
+    const isReconnectAttempt = initialState !== null;
+    const connectAttemptStartedAt = Date.now();
     if (this.connectionManager.hasConnection(projectPath)) {
       if (this.connectionManager.hasLiveConnection(projectPath)) {
         console.log(`[Daemon] Already connected to ${projectPath}`);
@@ -15172,7 +15348,7 @@ var Daemon = class _Daemon {
         const maxWait = 35e3;
         const startTime = Date.now();
         while (this.connectionManager.hasPendingConnection(projectPath) && Date.now() - startTime < maxWait) {
-          await new Promise((resolve6) => setTimeout(resolve6, 500));
+          await new Promise((resolve7) => setTimeout(resolve7, 500));
         }
         if (this.connectionManager.hasLiveConnection(projectPath)) {
           console.log(`[Daemon] Pending connection succeeded for ${projectPath}`);
@@ -15183,6 +15359,12 @@ var Daemon = class _Daemon {
       console.warn(`[Daemon] Stale connection detected for ${projectPath}, forcing reconnection`);
       await this.disconnectProject(projectPath);
     }
+    this.logReliabilityMetric("ws_connect_attempt", {
+      projectId,
+      projectPath,
+      reconnect: isReconnectAttempt,
+      previousState: initialState
+    });
     const config = await (0, import_core22.loadConfig)();
     if (!config || !config.access_token) {
       throw new Error("No access token found. Please run: episoda auth");
@@ -15197,12 +15379,15 @@ var Daemon = class _Daemon {
     }
     console.log(`[Daemon] Connecting to ${wsEndpoint.wsUrl} for project ${projectId} (source: ${wsEndpoint.source})...`);
     const client = new import_core22.EpisodaClient();
+    client.setAutoReconnect(false);
     const gitExecutor = new import_core22.GitExecutor();
     const connection = {
       projectId,
       projectPath,
       client,
-      gitExecutor
+      gitExecutor,
+      state: "connecting",
+      lastTransitionAt: Date.now()
     };
     this.connectionManager.setConnection(projectPath, connection);
     this.connectionManager.addPendingConnection(projectPath);
@@ -15540,6 +15725,7 @@ var Daemon = class _Daemon {
       }
     });
     client.on("auth_success", async (message) => {
+      client.setAutoReconnect(true);
       console.log(`[Daemon] Authenticated for project ${projectId}`);
       touchProject(projectPath);
       this.connectionManager.addLiveConnection(projectPath);
@@ -15653,9 +15839,59 @@ var Daemon = class _Daemon {
         console.error("[Daemon] EP1237: Error handling agent_reconciliation_commands:", error instanceof Error ? error.message : error);
       }
     });
+    client.on("reconnect_scheduled", (event) => {
+      const reconnectEvent = event;
+      this.logReliabilityMetric("ws_transport_reconnect_scheduled", {
+        projectId,
+        projectPath,
+        attempt: reconnectEvent.attempt,
+        delayMs: reconnectEvent.delayMs,
+        strategy: reconnectEvent.strategy
+      });
+    });
+    client.on("reconnect_attempt", (event) => {
+      const reconnectEvent = event;
+      this.logReliabilityMetric("ws_transport_reconnect_attempt", {
+        projectId,
+        projectPath,
+        attempt: reconnectEvent.attempt
+      });
+    });
+    client.on("reconnect_result", (event) => {
+      const reconnectEvent = event;
+      this.logReliabilityMetric("ws_transport_reconnect_result", {
+        projectId,
+        projectPath,
+        attempt: reconnectEvent.attempt,
+        success: reconnectEvent.success,
+        error: reconnectEvent.error
+      });
+    });
+    client.on("reconnect_exhausted", (event) => {
+      const reconnectEvent = event;
+      this.logReliabilityMetric("ws_transport_reconnect_exhausted", {
+        projectId,
+        projectPath,
+        attempts: reconnectEvent.attempts,
+        reason: reconnectEvent.reason
+      });
+      this.logReliabilityMetric("manual_reconnect_needed", {
+        source: "daemon",
+        projectId,
+        projectPath,
+        reason: reconnectEvent.reason
+      });
+    });
     client.on("disconnected", (event) => {
       const disconnectEvent = event;
       console.log(`[Daemon] Connection closed for ${projectId}: code=${disconnectEvent.code}, willReconnect=${disconnectEvent.willReconnect}`);
+      this.logReliabilityMetric("ws_transport_disconnect", {
+        projectId,
+        projectPath,
+        code: disconnectEvent.code,
+        reason: disconnectEvent.reason,
+        willReconnect: disconnectEvent.willReconnect
+      });
       this.connectionManager.removeLiveConnection(projectPath);
       if (this.connectionManager.liveConnectionCount() === 0) {
         this.lastDisconnectAt = this.lastDisconnectAt || Date.now();
@@ -15693,10 +15929,36 @@ var Daemon = class _Daemon {
         containerId
       });
       console.log(`[Daemon] Successfully connected to project ${projectId}`);
+      this.connectionManager.setState(projectPath, "authenticating");
       await this.connectionManager.waitForAuthentication(client, 3e4);
       console.log(`[Daemon] Authentication complete for project ${projectId}`);
+      this.logReliabilityMetric("ws_connect_result", {
+        projectId,
+        projectPath,
+        reconnect: isReconnectAttempt,
+        success: true,
+        durationMs: Date.now() - connectAttemptStartedAt
+      });
     } catch (error) {
       console.error(`[Daemon] Failed to connect to ${projectId}:`, error);
+      this.logReliabilityMetric("ws_connect_result", {
+        projectId,
+        projectPath,
+        reconnect: isReconnectAttempt,
+        success: false,
+        durationMs: Date.now() - connectAttemptStartedAt,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      try {
+        await client.disconnect(true);
+      } catch {
+      }
+      client.clearAllHandlers();
+      this.connectionManager.setState(
+        projectPath,
+        "disconnected",
+        error instanceof Error ? error.message : String(error)
+      );
       this.connectionManager.deleteConnection(projectPath);
       this.connectionManager.removePendingConnection(projectPath);
       throw error;
@@ -16128,14 +16390,13 @@ var Daemon = class _Daemon {
       console.log(`[Daemon] EP1002: ${installCmd.description} (detected from ${installCmd.detectedFrom})`);
       console.log(`[Daemon] EP1002: Running: ${installCmd.command.join(" ")}`);
       try {
-        const { execSync: execSync11 } = await import("child_process");
-        execSync11(installCmd.command.join(" "), {
-          cwd: worktreePath,
-          stdio: "inherit",
-          timeout: 10 * 60 * 1e3,
-          // 10 minute timeout
-          env: { ...process.env, CI: "true" }
-        });
+        await this.runForegroundCommand(
+          installCmd.command[0],
+          installCmd.command.slice(1),
+          worktreePath,
+          { ...process.env, CI: "true" },
+          10 * 60 * 1e3
+        );
         installSucceeded = true;
         console.log(`[Daemon] EP1002: Dependencies installed successfully`);
       } catch (installError) {
@@ -16151,13 +16412,12 @@ var Daemon = class _Daemon {
       const bootstrapCmd = buildCmd;
       console.log(`[Daemon] EP1386: Bootstrapping packages after dependency install (${bootstrapCmd})`);
       try {
-        const { execSync: execSync11 } = await import("child_process");
-        execSync11(bootstrapCmd, {
-          cwd: worktreePath,
-          stdio: "inherit",
-          timeout: 10 * 60 * 1e3,
-          env: { ...process.env, CI: "true" }
-        });
+        await this.runShellForegroundCommand(
+          bootstrapCmd,
+          worktreePath,
+          { ...process.env, CI: "true" },
+          10 * 60 * 1e3
+        );
         console.log("[Daemon] EP1386: Package bootstrap completed");
       } catch (buildError) {
         const errorMsg = buildError instanceof Error ? buildError.message : String(buildError);
@@ -16177,6 +16437,74 @@ var Daemon = class _Daemon {
     await this.updateModuleWorktreeStatus(moduleUid, "ready", worktreePath);
     console.log(`[Daemon] EP1002: Worktree setup complete for ${moduleUid}`);
   }
+  async runForegroundCommand(command, args, cwd, env, timeoutMs) {
+    await new Promise((resolve7, reject) => {
+      const commandLabel = `${command} ${args.join(" ")}`.trim();
+      const child = (0, import_child_process19.spawn)(command, args, {
+        cwd,
+        env,
+        stdio: "inherit",
+        shell: false
+      });
+      let settled = false;
+      let timedOut = false;
+      const timeoutSeconds = Math.round(timeoutMs / 1e3);
+      const termGraceMs = 5e3;
+      let termTimer = null;
+      let killTimer = null;
+      const finish = (error) => {
+        if (settled) return;
+        settled = true;
+        if (termTimer) clearTimeout(termTimer);
+        if (killTimer) clearTimeout(killTimer);
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve7();
+      };
+      termTimer = setTimeout(() => {
+        timedOut = true;
+        try {
+          child.kill("SIGTERM");
+        } catch {
+        }
+        killTimer = setTimeout(() => {
+          if (settled) return;
+          try {
+            child.kill("SIGKILL");
+          } catch {
+          }
+          finish(
+            new Error(`Command timed out after ${timeoutSeconds}s (terminated with SIGKILL fallback): ${commandLabel}`)
+          );
+        }, termGraceMs);
+      }, timeoutMs);
+      child.on("error", (error) => {
+        finish(error);
+      });
+      child.on("exit", (code, signal) => {
+        if (timedOut) {
+          finish(
+            new Error(`Command timed out after ${timeoutSeconds}s (exit code=${code ?? "null"}, signal=${signal ?? "none"}): ${commandLabel}`)
+          );
+          return;
+        }
+        if (code === 0) {
+          finish();
+          return;
+        }
+        finish(new Error(`Command failed (code=${code ?? "null"}, signal=${signal ?? "none"}): ${commandLabel}`));
+      });
+    });
+  }
+  async runShellForegroundCommand(command, cwd, env, timeoutMs) {
+    if (process.platform === "win32") {
+      await this.runForegroundCommand("cmd", ["/d", "/s", "/c", command], cwd, env, timeoutMs);
+      return;
+    }
+    await this.runForegroundCommand("sh", ["-lc", command], cwd, env, timeoutMs);
+  }
   // EP1003: startTunnelForModule removed - server now orchestrates via tunnel_start commands
   // EP1003: autoStartTunnelsForProject removed - server now orchestrates via reconciliation
   // Recovery flow: daemon sends reconciliation_report → server processes and sends commands