Skip to content

πŸ™Œ 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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,