π OpenHands: AI-Driven Development
Clean up dev stack process trees on shutdown (#475)
Xingyao Wange5711e74b2ac
diff --git a/__tests__/scripts/dev-process-utils.test.ts b/__tests__/scripts/dev-process-utils.test.tsnew file mode 100644index 0000000000..c46433901c--- /dev/null+++ b/__tests__/scripts/dev-process-utils.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vitest";++import {+ getProcessTreeSpawnOptions,+ isProcessRunning,+} from "../../scripts/dev-process-utils.mjs";++describe("dev process utils", () => {+ it("treats a signaled but unexited process as still running", () => {+ expect(+ isProcessRunning({+ exitCode: null,+ signalCode: null,+ killed: true,+ }),+ ).toBe(true);+ });++ it("treats exited or signaled processes as stopped", () => {+ expect(isProcessRunning({ exitCode: 0, signalCode: null })).toBe(false);+ expect(isProcessRunning({ exitCode: null, signalCode: "SIGTERM" })).toBe(+ false,+ );+ });++ it("sets detached mode according to the platform for process-group cleanup", () => {+ expect(getProcessTreeSpawnOptions({ cwd: "/tmp" })).toMatchObject({+ cwd: "/tmp",+ detached: process.platform !== "win32",+ });+ });+});diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjsindex a33ce2e969..43dd188d6f 100644--- a/scripts/dev-docker.mjs+++ b/scripts/dev-docker.mjs@@ -62,6 +62,7 @@ import {logService,logSuccess,main,+ registerShutdownHook,spawnService,} from "./dev-with-automation.mjs";import { validateLocalAgentServerPath } from "./dev-safe.mjs";@@ -260,6 +261,9 @@ function startAgentServerDocker(config) {// Best-effort cleanup of any leftover container from a previous run.spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "ignore" });+ registerShutdownHook(() => {+ spawnSync("docker", ["rm", "-f", CONTAINER_NAME], { stdio: "ignore" });+ });const home = homedir();const userSpec = getHostDockerUserSpec();diff --git a/scripts/dev-extra-backend.mjs b/scripts/dev-extra-backend.mjsindex f22bd7bc66..7a906aab2e 100644--- a/scripts/dev-extra-backend.mjs+++ b/scripts/dev-extra-backend.mjs@@ -12,6 +12,11 @@ import {formatMissingUvxGuidance,validateLocalAgentServerPath,} from "./dev-safe.mjs";+import {+ getProcessTreeSpawnOptions,+ isProcessRunning,+ signalProcessTree,+} from "./dev-process-utils.mjs";const DEFAULT_EXTRA_BACKEND_PORT = 18002;const DEFAULT_EXTRA_VSCODE_PORT = 18003;@@ -88,8 +93,11 @@ async function waitForServer(url, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {throw new Error(`Timed out waiting for agent-server at ${url}`);}-function spawnProcess(command, args, options) {- const child = spawn(command, args, { stdio: "inherit", ...options });+function spawnProcess(command, args, options = {}) {+ const child = spawn(command, args, getProcessTreeSpawnOptions({+ stdio: "inherit",+ ...options,+ }));child.once("error", (error) => {if (isEnoentError(error) && command === "uvx") {@@ -170,7 +178,14 @@ async function main() {}shuttingDown = true;- backend.kill(signal);+ signalProcessTree(backend, signal);++ setTimeout(() => {+ if (isProcessRunning(backend)) {+ signalProcessTree(backend, "SIGKILL");+ }+ process.exit(process.exitCode ?? 0);+ }, 3000);};process.on("SIGINT", () => shutdown("SIGINT"));diff --git a/scripts/dev-process-utils.mjs b/scripts/dev-process-utils.mjsnew file mode 100644index 0000000000..e46fc31ca3--- /dev/null+++ b/scripts/dev-process-utils.mjs@@ -0,0 +1,85 @@+import process from "node:process";++/**+ * Return true while Node still considers the child process active.+ *+ * Do not use ChildProcess#killed for cleanup decisions. In Node, `killed`+ * only means a signal was sent successfully; it does not mean the process has+ * exited. That distinction matters for dev launchers because uvx/npm/docker+ * wrappers can receive SIGTERM while their long-running child process keeps+ * serving on the original port.+ */+export function isProcessRunning(proc) {+ return proc.exitCode === null && proc.signalCode === null;+}++/**+ * Add spawn options needed for process-tree cleanup.+ *+ * On POSIX, `detached: true` makes the spawned service the leader of a new+ * process group. Later we can signal `-pid` to terminate that whole group,+ * including wrapper chains like:+ *+ * launcher -> uvx -> python agent-server+ * launcher -> npm -> sh -> Vite+ * launcher -> docker run -> container shim+ *+ * Windows does not support POSIX process groups, so callers fall back to+ * signaling the direct child process there.+ */+export function getProcessTreeSpawnOptions(options = {}) {+ return {+ ...options,+ detached: process.platform !== "win32",+ };+}++/**+ * Signal the whole spawned service tree when possible.+ *+ * POSIX `process.kill(-pid, signal)` targets the process group whose id is+ * `pid`; this only works because services are spawned with+ * `getProcessTreeSpawnOptions()`. Without the negative pid, shutdown would+ * often stop only the wrapper process and leave the actual server child+ * listening on its port.+ */+export function signalProcessTree(proc, signal) {+ if (!isProcessRunning(proc)) {+ return false;+ }++ try {+ if (process.platform === "win32" || !proc.pid) {+ proc.kill(signal);+ } else {+ process.kill(-proc.pid, signal);+ }+ return true;+ } catch (err) {+ if (err?.code === "ESRCH") {+ return false;+ }+ throw err;+ }+}++export function createShutdownHookRegistry(onError) {+ const hooks = new Set();++ return {+ add(hook) {+ hooks.add(hook);+ return () => hooks.delete(hook);+ },++ run() {+ for (const hook of hooks) {+ try {+ hook();+ } catch (err) {+ onError?.(err);+ }+ }+ },+ };+}diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex c19cf09c79..c6d401ca70 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -16,6 +16,12 @@ import process from "node:process";import { setTimeout as delay } from "node:timers/promises";import { pathToFileURL } from "node:url";+import {+ getProcessTreeSpawnOptions,+ isProcessRunning,+ signalProcessTree,+} from "./dev-process-utils.mjs";+const DEFAULT_BACKEND_PORT = 18000;const DEFAULT_VITE_PORT = 3001;const DEFAULT_WAIT_TIMEOUT_MS = 30_000;@@ -647,8 +653,11 @@ async function waitForServer(url, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {throw new Error(`Timed out waiting for agent-server at ${url}`);}-function spawnProcess(command, args, options) {- const child = spawn(command, args, { stdio: "inherit", ...options });+function spawnProcess(command, args, options = {}) {+ const child = spawn(command, args, getProcessTreeSpawnOptions({+ stdio: "inherit",+ ...options,+ }));child.once("error", (error) => {if (isEnoentError(error) && command === "uvx") {@@ -739,8 +748,20 @@ async function main() {}shuttingDown = true;- frontend?.kill(signal);- backend.kill(signal);+ if (frontend) {+ signalProcessTree(frontend, signal);+ }+ signalProcessTree(backend, signal);++ setTimeout(() => {+ if (frontend && isProcessRunning(frontend)) {+ signalProcessTree(frontend, "SIGKILL");+ }+ if (isProcessRunning(backend)) {+ signalProcessTree(backend, "SIGKILL");+ }+ process.exit(process.exitCode ?? 0);+ }, 3000);};process.on("SIGINT", () => shutdown("SIGINT"));diff --git a/scripts/dev-static.mjs b/scripts/dev-static.mjsindex e73eec0720..1beea74643 100644--- a/scripts/dev-static.mjs+++ b/scripts/dev-static.mjs@@ -51,6 +51,11 @@ import {isPortBusy,releaseStaleConversationLeases,} from "./dev-safe.mjs";+import {+ getProcessTreeSpawnOptions,+ isProcessRunning,+ signalProcessTree,+} from "./dev-process-utils.mjs";import { buildAutomationCommand, buildConfig } from "./dev-with-automation.mjs";const __dirname = dirname(fileURLToPath(import.meta.url));@@ -205,12 +210,12 @@ const processes = new Map();let shuttingDown = false;function spawnService(name, command, args, options = {}) {- const proc = spawn(command, args, {+ const proc = spawn(command, args, getProcessTreeSpawnOptions({stdio: ["ignore", "pipe", "pipe"],env: { ...process.env, ...options.env },cwd: options.cwd,shell: process.platform === "win32",- });+ }));const color = options.color || c.reset;@@ -442,13 +447,14 @@ function shutdown() {for (const [name, proc] of processes) {logService(name, "Stopping...", c.dim);- proc.kill("SIGTERM");+ signalProcessTree(proc, "SIGTERM");}setTimeout(() => {- for (const [, proc] of processes) {- if (!proc.killed) {- proc.kill("SIGKILL");+ for (const [name, proc] of processes) {+ if (isProcessRunning(proc)) {+ logService(name, "Force stopping...", c.dim);+ signalProcessTree(proc, "SIGKILL");}}process.exit(0);diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjsindex add73a96e5..e2de0d9b82 100644--- a/scripts/dev-with-automation.mjs+++ b/scripts/dev-with-automation.mjs@@ -55,6 +55,12 @@ import {findFreePorts,validateFrontendDependencies,} from "./dev-safe.mjs";+import {+ createShutdownHookRegistry,+ getProcessTreeSpawnOptions,+ isProcessRunning,+ signalProcessTree,+} from "./dev-process-utils.mjs";const __dirname = dirname(fileURLToPath(import.meta.url));const projectRoot = resolve(__dirname, "..");@@ -379,14 +385,21 @@ function ensureDirectories(config) {// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββconst processes = new Map();+const shutdownHooks = createShutdownHookRegistry((err) => {+ logService("cleanup", `Cleanup hook failed: ${err.message}`, c.yellow);+});++function registerShutdownHook(hook) {+ return shutdownHooks.add(hook);+}function spawnService(name, command, args, options = {}) {- const proc = spawn(command, args, {+ const proc = spawn(command, args, getProcessTreeSpawnOptions({stdio: ["ignore", "pipe", "pipe"],env: { ...process.env, ...options.env },cwd: options.cwd,shell: process.platform === "win32",- });+ }));const color = options.color || c.reset;@@ -533,15 +546,17 @@ function shutdown() {for (const [name, proc] of processes) {logService(name, "Stopping...", c.dim);- proc.kill("SIGTERM");+ signalProcessTree(proc, "SIGTERM");}setTimeout(() => {- for (const [, proc] of processes) {- if (!proc.killed) {- proc.kill("SIGKILL");+ for (const [name, proc] of processes) {+ if (isProcessRunning(proc)) {+ logService(name, "Force stopping...", c.dim);+ signalProcessTree(proc, "SIGKILL");}}+ shutdownHooks.run();process.exit(0);}, 3000);}@@ -853,6 +868,7 @@ export {buildConfig,generateRandomApiKey,main,+ registerShutdownHook,spawnService,commandExists,logService,