@runa-ai/runa-cli 0.5.64 → 0.5.65

package/dist/commands/dev/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../../src/commands/dev/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqOpC,eAAO,MAAM,UAAU,SAuBnB,CAAC"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../../src/commands/dev/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8OpC,eAAO,MAAM,UAAU,SAuBnB,CAAC"}

package/dist/commands/dev/helpers/stale-process-detector.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AI HINT: Stale Process Detection & Recovery
+ *
+ * Purpose: Detect and recover stale node/next processes holding ports
+ * Pattern: lsof → classify → health check → terminate if stale
+ *
+ * Security:
+ * - Uses secureExeca('lsof', ...) for safe binary execution
+ * - Only auto-kills node/next processes (never foreign like postgres)
+ * - Health check prevents killing healthy running servers
+ *
+ * Flow:
+ * Port EADDRINUSE
+ *   -> lsof to identify process
+ *     -> No process: port-free (race condition resolved)
+ *     -> Non-node (postgres etc): foreign-process (error, no auto-kill)
+ *     -> node/next:
+ *       -> HTTP health check
+ *         -> Healthy: healthy-running (error, don't kill)
+ *         -> Not responding: stale -> auto-kill -> stale-killed
+ */
+export type StaleRecoveryResult = {
+    status: 'port-free';
+} | {
+    status: 'stale-killed';
+    pid: number;
+    name: string;
+} | {
+    status: 'healthy-running';
+    pid: number;
+    name: string;
+} | {
+    status: 'foreign-process';
+    pid: number;
+    name: string;
+} | {
+    status: 'detection-failed';
+    reason: string;
+};
+interface ProcessInfo {
+    pid: number;
+    name: string;
+    command: string;
+}
+interface StaleLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+}
+/**
+ * Find process listening on a given port via lsof.
+ * Returns null if no process found or lsof fails.
+ */
+export declare function findProcessOnPort(port: number): Promise<ProcessInfo | null>;
+/**
+ * Check if a process is a node/next process safe to auto-kill.
+ */
+export declare function isNodeOrNextProcess(name: string, command: string): boolean;
+/**
+ * Check if a server on the given port is responding to HTTP requests.
+ * A healthy response means the server is actively serving (don't kill it).
+ */
+export declare function isServerHealthy(port: number): Promise<boolean>;
+/**
+ * Orchestrate stale process detection and recovery.
+ *
+ * Called when port is in use but no PID file exists.
+ * Identifies the process, classifies it, and recovers if safe.
+ */
+export declare function detectAndRecoverStaleProcess(port: number, logger: StaleLogger): Promise<StaleRecoveryResult>;
+export {};
+//# sourceMappingURL=stale-process-detector.d.ts.map

package/dist/commands/dev/helpers/stale-process-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-process-detector.d.ts","sourceRoot":"","sources":["../../../../src/commands/dev/helpers/stale-process-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAaD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAsCjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAc1E;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBpE;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAoC9B"}

package/dist/commands/dev/machine.d.ts

@@ -32,6 +32,9 @@ interface ProcessCheckInput {
     replace: boolean;
     skipApp: boolean;
 }
+interface ProcessCheckOutput {
+    staleProcessRecovered: boolean;
+}
 interface AppStartInput {
     repoRoot: string;
     appDir: string;
@@ -59,7 +62,7 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
     type: "error.platform";
     error: Error;
 }, {
-    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").DepsInstallOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").EnvCheckOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").SupabaseStartOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, ProcessCheckInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<AppStartOutput, AppStartInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, ShutdownInput, import("xstate").EventObject>> | undefined;
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").DepsInstallOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").EnvCheckOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<import("../build/actors/setup.js").SupabaseStartOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<ProcessCheckOutput, ProcessCheckInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<AppStartOutput, AppStartInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, ShutdownInput, import("xstate").EventObject>> | undefined;
 }, {
     src: "depsInstall";
     logic: import("xstate").PromiseActorLogic<import("../build/actors/setup.js").DepsInstallOutput, import("../build/actors/setup.js").SetupInput, import("xstate").EventObject>;
@@ -74,7 +77,7 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
     id: string | undefined;
 } | {
     src: "processCheck";
-    logic: import("xstate").PromiseActorLogic<void, ProcessCheckInput, import("xstate").EventObject>;
+    logic: import("xstate").PromiseActorLogic<ProcessCheckOutput, ProcessCheckInput, import("xstate").EventObject>;
     id: string | undefined;
 } | {
     src: "appStart";

package/dist/commands/dev/machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAU1D,OAAO,KAAK,EAAE,UAAU,EAAY,QAAQ,EAAa,MAAM,YAAY,CAAC;AAgG5E,UAAU,iBAAiB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AA+ED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACnC;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AA8CD,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;CACb;AAoBD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAcD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8MrB,CAAC;AAMH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;AAM1D;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAa1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAE7D"}
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAW1D,OAAO,KAAK,EAAE,UAAU,EAAY,QAAQ,EAAa,MAAM,YAAY,CAAC;AAgG5E,UAAU,iBAAiB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAiCD,UAAU,kBAAkB;IAC1B,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAwFD,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACnC;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AA8CD,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;CACb;AAoBD,UAAU,eAAe;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAcD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuNrB,CAAC;AAMH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;AAM1D;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAa1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAE7D"}

package/dist/commands/dev/types.d.ts

@@ -24,6 +24,8 @@ export interface DevContext {
     appPid: number | null;
     /** Whether Supabase was started */
     supabaseStarted: boolean;
+    /** Whether a stale process was recovered during port check */
+    staleProcessRecovered: boolean;
     /** Start time for duration tracking */
     startTime: number;
     /** Error message if failed */

package/dist/commands/dev/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,QAAQ,IAAI,SAAS,EACrB,SAAS,IAAI,UAAU,EACvB,cAAc,IAAI,eAAe,EAClC,MAAM,eAAe,CAAC;AAGvB,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AACjC,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AACnC,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAM7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,eAAe,EAAE,OAAO,CAAC;IACzB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAMD,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAM7C;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAQ3D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/commands/dev/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,QAAQ,IAAI,SAAS,EACrB,SAAS,IAAI,UAAU,EACvB,cAAc,IAAI,eAAe,EAClC,MAAM,eAAe,CAAC;AAGvB,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC;AACjC,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AACnC,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAM7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mCAAmC;IACnC,eAAe,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,qBAAqB,EAAE,OAAO,CAAC;IAC/B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAMD,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAM7C;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAQ3D"}

package/dist/index.js

@@ -1161,7 +1161,7 @@ var CLI_VERSION, HAS_ADMIN_COMMAND;
 var init_version = __esm({
   "src/version.ts"() {
     init_esm_shims();
-    CLI_VERSION = "0.5.64";
+    CLI_VERSION = "0.5.65";
     HAS_ADMIN_COMMAND = false;
   }
 });
@@ -8370,6 +8370,88 @@ var guards2 = {
   shouldSkipApp
 };
 
+// src/commands/dev/helpers/stale-process-detector.ts
+init_esm_shims();
+var SAFE_TO_KILL_NAMES = ["node", "next-server", "next-router-worker", "tsx", "ts-node"];
+async function findProcessOnPort(port) {
+  try {
+    const result = await secureExeca("lsof", ["-i", `:${port}`, "-sTCP:LISTEN", "-P", "-n"], {
+      reject: false
+    });
+    const stdout = String(result.stdout ?? "");
+    if (result.exitCode !== 0 || !stdout) {
+      return null;
+    }
+    const lines = stdout.trim().split("\n");
+    if (lines.length < 2) return null;
+    const dataLine = lines[1];
+    const parts = dataLine.split(/\s+/);
+    if (parts.length < 2) return null;
+    const name = parts[0];
+    const pid = parseInt(parts[1], 10);
+    if (Number.isNaN(pid) || pid <= 0) return null;
+    let command = "";
+    try {
+      const psResult = await secureExeca("lsof", ["-p", `${pid}`, "-Fn"], { reject: false });
+      command = String(psResult.stdout ?? "");
+    } catch {
+    }
+    return { pid, name, command };
+  } catch {
+    return null;
+  }
+}
+function isNodeOrNextProcess(name, command) {
+  const lowerName = name.toLowerCase();
+  if (!SAFE_TO_KILL_NAMES.some((safe) => lowerName === safe)) {
+    return false;
+  }
+  if (lowerName === "node") {
+    return command.toLowerCase().includes("next");
+  }
+  return true;
+}
+async function isServerHealthy(port) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2e3);
+    const response = await fetch(`http://localhost:${port}/`, {
+      signal: controller.signal,
+      method: "GET"
+    });
+    clearTimeout(timeout);
+    return response.status > 0;
+  } catch {
+    return false;
+  }
+}
+async function detectAndRecoverStaleProcess(port, logger16) {
+  const processInfo = await findProcessOnPort(port);
+  if (!processInfo) {
+    return { status: "port-free" };
+  }
+  const { pid, name, command } = processInfo;
+  logger16.info(`Found process on port ${port}: ${name} (PID: ${pid})`);
+  if (!isNodeOrNextProcess(name, command)) {
+    return { status: "foreign-process", pid, name };
+  }
+  const healthy = await isServerHealthy(port);
+  if (healthy) {
+    return { status: "healthy-running", pid, name };
+  }
+  logger16.info(`Stale process detected (${name}, PID: ${pid}). Recovering...`);
+  try {
+    await terminateAppProcessByPid({ pid, logger: logger16 });
+    logger16.info(`Stale process terminated (PID: ${pid})`);
+    return { status: "stale-killed", pid, name };
+  } catch (error) {
+    return {
+      status: "detection-failed",
+      reason: `Failed to terminate PID ${pid}: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
 // src/commands/dev/types.ts
 init_esm_shims();
 function createOutput2(context) {
@@ -8488,36 +8570,68 @@ function checkPortAvailable(port) {
     server.listen(port);
   });
 }
-var processCheckActor = fromPromise(async ({ input: input3 }) => {
-  const pidFile = path12__default.join(input3.repoRoot, input3.tmpDir, "app.pid");
-  let pidFileContent = null;
-  try {
-    pidFileContent = readFileSync(pidFile, "utf-8").trim();
-  } catch {
-  }
-  if (pidFileContent) {
-    const pid = parseInt(pidFileContent, 10);
-    if (!Number.isNaN(pid) && isProcessAlive(pid)) {
-      if (input3.replace) {
-        await terminateAppProcessByPid({
-          pid,
-          logger: { info: console.log, warn: console.warn }
-        });
-      } else {
-        throw new Error(
-          `runa dev is already running (PID: ${pid}). Use --replace to restart, or stop the existing process first.`
-        );
-      }
-    }
+var processCheckActor = fromPromise(
+  async ({ input: input3 }) => {
+    const pidFile = path12__default.join(input3.repoRoot, input3.tmpDir, "app.pid");
+    let staleProcessRecovered = false;
+    let pidFileContent = null;
     try {
-      unlinkSync(pidFile);
+      pidFileContent = readFileSync(pidFile, "utf-8").trim();
     } catch {
     }
+    if (pidFileContent) {
+      const pid = parseInt(pidFileContent, 10);
+      if (!Number.isNaN(pid) && isProcessAlive(pid)) {
+        if (input3.replace) {
+          await terminateAppProcessByPid({
+            pid,
+            logger: { info: console.log, warn: console.warn }
+          });
+        } else {
+          throw new Error(
+            `runa dev is already running (PID: ${pid}). Use --replace to restart, or stop the existing process first.`
+          );
+        }
+      }
+      try {
+        unlinkSync(pidFile);
+      } catch {
+      }
+    }
+    if (!input3.skipApp) {
+      try {
+        await checkPortAvailable(input3.port);
+      } catch (portError) {
+        if (portError instanceof Error && portError.message.includes("already in use")) {
+          const logger16 = { info: console.log, warn: console.warn };
+          const result = await detectAndRecoverStaleProcess(input3.port, logger16);
+          switch (result.status) {
+            case "port-free":
+              break;
+            case "stale-killed":
+              staleProcessRecovered = true;
+              await new Promise((r) => setTimeout(r, 500));
+              await checkPortAvailable(input3.port);
+              break;
+            case "healthy-running":
+              throw new Error(
+                `Port ${input3.port} is in use by a running server (${result.name}, PID: ${result.pid}). Use --port <number> or --replace to restart.`
+              );
+            case "foreign-process":
+              throw new Error(
+                `Port ${input3.port} is in use by ${result.name} (PID: ${result.pid}). Stop it manually before running runa dev.`
+              );
+            case "detection-failed":
+              throw portError;
+          }
+        } else {
+          throw portError;
+        }
+      }
+    }
+    return { staleProcessRecovered };
   }
-  if (!input3.skipApp) {
-    await checkPortAvailable(input3.port);
-  }
-});
+);
 var appStartActor = fromPromise(
   async ({ input: input3 }) => {
     const { repoRoot, appDir, port, tmpDir, stream, bundler } = input3;
@@ -8593,6 +8707,7 @@ var devMachine = setup({
       hasDatabase: detectDatabase(repoRoot),
       appPid: null,
       supabaseStarted: false,
+      staleProcessRecovered: false,
       startTime: Date.now(),
       error: null
     };
@@ -8621,7 +8736,15 @@ var devMachine = setup({
           replace: context.input.replace,
           skipApp: context.input.skipApp
         }),
-        onDone: { target: "setup" },
+        onDone: {
+          target: "setup",
+          actions: assign({
+            staleProcessRecovered: ({ event }) => {
+              const output3 = event.output;
+              return output3?.staleProcessRecovered ?? false;
+            }
+          })
+        },
         onError: {
           target: "failed",
           actions: assign({
@@ -8821,6 +8944,9 @@ function handleStateChange2(snapshot2, prevState, logger16, port) {
   if (handler) {
     handler(logger16, { port });
   }
+  if (prevState === "processCheck" && state2.startsWith("setup") && snapshot2.context.staleProcessRecovered) {
+    logger16.success("  Stale process recovered. Port is now available.");
+  }
 }
 function printSummary2(logger16, output3) {
   if (output3.success) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runa-ai/runa-cli",
-  "version": "0.5.64",
+  "version": "0.5.65",
   "private": false,
   "description": "AI-powered DevOps CLI",
   "type": "module",
@@ -53,7 +53,7 @@
     "typescript": "5.9.3",
     "xstate": "5.28.0",
     "zod": "4.3.6",
-    "@runa-ai/runa": "0.5.64",
+    "@runa-ai/runa": "0.5.65",
     "@runa-ai/runa-xstate-test-plugin": "0.5.58"
   },
   "engines": {