Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): e2e killGracefully must reap the vite tree, not just the pnpm shim (#2784)

Nick Gomez39c972cda5fa
diff --git a/packages/app/tests/integration/kill-gracefully-tree.test.ts b/packages/app/tests/integration/kill-gracefully-tree.test.ts
new file mode 100644
index 000000000..1e81cf98c
--- /dev/null
+++ b/packages/app/tests/integration/kill-gracefully-tree.test.ts
@@ -0,0 +1,155 @@
+/**
+ * killGracefully must reap the spawned process TREE, not just the direct
+ * child. The e2e fixtures spawn `pnpm run dev` — a shim whose real server
+ * (vite) is a descendant. SIGKILL is never relayed, so a shim-only kill
+ * orphans a live Vite that keeps the port bound and its file-watchers on the
+ * contentDir while teardown rmSyncs that directory under it — the
+ * teardown/cleanup race behind the docs-open F0 hard-fail class (content-dir
+ * subpaths vanishing mid-run for a live worker's server).
+ *
+ * The tree shape here mirrors the fixture's: a shell parent (stand-in for
+ * the pnpm shim) with a long-lived child (stand-in for vite). `sh -c
+ * 'sleep 300; true'` — the trailing `true` stops sh from exec-ing sleep
+ * directly, forcing a real two-process tree.
+ */
+
+import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
+import { setTimeout as wait } from 'node:timers/promises';
+import { afterEach, describe, expect, test } from 'vitest';
+import { killGracefully } from '../stress/_helpers/server-process.ts';
+
+// Best-effort sweep so an assertion failure BEFORE a test's killGracefully
+// call cannot orphan a detached sleep tree for its full 300s.
+const spawned: ChildProcess[] = [];
+afterEach(() => {
+ for (const proc of spawned) {
+ if (proc.pid !== undefined) {
+ try {
+ process.kill(-proc.pid, 'SIGKILL');
+ } catch {
+ /* tree already gone */
+ }
+ }
+ }
+ spawned.length = 0;
+});
+
+function isAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ESRCH') return false;
+ // EPERM means the pid exists but belongs to another user — alive.
+ if ((err as NodeJS.ErrnoException).code === 'EPERM') return true;
+ throw err;
+ }
+}
+
+/** Poll `pgrep -P <pid>` until the shell's child appears. */
+async function waitForChildPid(parentPid: number, timeoutMs = 5000): Promise<number> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ try {
+ const out = execFileSync('pgrep', ['-P', String(parentPid)], { encoding: 'utf8' }).trim();
+ if (out) return Number.parseInt(out.split('\n')[0] as string, 10);
+ } catch (err) {
+ // pgrep exits 1 while no child exists yet; a missing binary is a real
+ // environment problem and must fail loudly, not read as "no child".
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') throw err;
+ }
+ await wait(50);
+ }
+ throw new Error(`no child of ${parentPid} appeared within ${timeoutMs}ms`);
+}
+
+function spawnTree(): ChildProcess {
+ const proc = spawn('sh', ['-c', 'sleep 300; true'], {
+ // Mirrors the fixtures' spawn: own process group so the group-kill path
+ // is the one under test.
+ detached: true,
+ stdio: 'ignore',
+ });
+ spawned.push(proc);
+ return proc;
+}
+
+describe('killGracefully process-tree reaping', () => {
+ test('kills both the direct child and its descendant', async () => {
+ const proc = spawnTree();
+ expect(proc.pid).toBeDefined();
+ const childPid = await waitForChildPid(proc.pid as number);
+ expect(isAlive(childPid)).toBe(true);
+
+ await killGracefully(proc, 2_000);
+
+ expect(proc.exitCode !== null || proc.signalCode !== null).toBe(true);
+ // The descendant must not survive as an orphan. Poll briefly: group
+ // signal delivery is immediate, but give the scheduler a beat.
+ const deadline = Date.now() + 2_000;
+ while (isAlive(childPid) && Date.now() < deadline) {
+ await wait(25);
+ }
+ expect(isAlive(childPid)).toBe(false);
+ });
+
+ test('sweeps surviving descendants when the direct child already exited', async () => {
+ // Reproduces the shim-crashed-but-server-lives shape: kill only the
+ // shell with a non-relayed SIGKILL, leaving the sleep orphaned in the
+ // group, then assert killGracefully's early-exit path sweeps it.
+ const proc = spawnTree();
+ const parentPid = proc.pid as number;
+ const childPid = await waitForChildPid(parentPid);
+
+ process.kill(parentPid, 'SIGKILL');
+ await new Promise<void>((resolve) => proc.once('exit', () => resolve()));
+ expect(isAlive(childPid)).toBe(true);
+
+ await killGracefully(proc, 2_000);
+
+ const deadline = Date.now() + 2_000;
+ while (isAlive(childPid) && Date.now() < deadline) {
+ await wait(25);
+ }
+ expect(isAlive(childPid)).toBe(false);
+ });
+
+ test('escalates to SIGKILL when the tree ignores SIGTERM', async () => {
+ // `trap "" TERM` alone is not enough: group-SIGTERM would kill the inner
+ // sleep, letting the script run to completion and exit cleanly without
+ // ever forcing escalation. The respawn loop keeps the TERM-ignoring
+ // shell alive past the timeout, so only the SIGKILL branch can end it.
+ const proc = spawn('sh', ['-c', 'trap "" TERM; while :; do sleep 1; done'], {
+ detached: true,
+ stdio: 'ignore',
+ });
+ spawned.push(proc);
+ await waitForChildPid(proc.pid as number);
+
+ await killGracefully(proc, 300);
+
+ expect(proc.signalCode).toBe('SIGKILL');
+ // The whole group must be gone: kill(-pid, 0) reports ESRCH once the
+ // last member (the current inner sleep) is reaped.
+ const pid = proc.pid as number;
+ const deadline = Date.now() + 2_000;
+ let groupGone = false;
+ while (!groupGone && Date.now() < deadline) {
+ try {
+ process.kill(-pid, 0);
+ } catch (err) {
+ groupGone = (err as NodeJS.ErrnoException).code === 'ESRCH';
+ if (!groupGone) throw err;
+ }
+ if (!groupGone) await wait(25);
+ }
+ expect(groupGone).toBe(true);
+ });
+
+ test('is a no-op on a fully-exited tree (no ESRCH escape)', async () => {
+ const proc = spawn('sh', ['-c', 'true'], { detached: true, stdio: 'ignore' });
+ await new Promise<void>((resolve) => proc.once('exit', () => resolve()));
+ // Must not throw — the group is gone and both kill paths report ESRCH.
+ await killGracefully(proc, 500);
+ });
+});
diff --git a/packages/app/tests/stress/_helpers/fixtures.ts b/packages/app/tests/stress/_helpers/fixtures.ts
index d9da475b9..732e6d8c8 100644
--- a/packages/app/tests/stress/_helpers/fixtures.ts
+++ b/packages/app/tests/stress/_helpers/fixtures.ts
@@ -431,6 +431,9 @@ export const test = base.extend<TestFixtures, WorkerFixtures>({
// (below) rather than a silence flag.
const proc = spawn('pnpm', ['run', 'dev', '--host', '127.0.0.1'], {
cwd: APP_PACKAGE_ROOT,
+ // Own process group so killGracefully's group-kill reaches vite
+ // through the pnpm shim (see signalTree in server-process.ts).
+ detached: true,
env: {
...process.env,
...workerServerEnv,
diff --git a/packages/app/tests/stress/_helpers/global-warm-cache.ts b/packages/app/tests/stress/_helpers/global-warm-cache.ts
index e1bbe1428..04c648cf3 100644
--- a/packages/app/tests/stress/_helpers/global-warm-cache.ts
+++ b/packages/app/tests/stress/_helpers/global-warm-cache.ts
@@ -97,6 +97,9 @@ async function buildSeedOnce(key: string): Promise<void> {
const log = openServerLog('warm-cache');
const proc = spawn('pnpm', ['run', 'dev', '--host', '127.0.0.1'], {
cwd: APP_PACKAGE_ROOT,
+ // Own process group so killGracefully's group-kill reaches vite
+ // through the pnpm shim (see signalTree in server-process.ts).
+ detached: true,
env: {
...process.env,
VITE_PORT: String(port),
diff --git a/packages/app/tests/stress/_helpers/server-process.ts b/packages/app/tests/stress/_helpers/server-process.ts
index 27ec21f33..f8873d7c6 100644
--- a/packages/app/tests/stress/_helpers/server-process.ts
+++ b/packages/app/tests/stress/_helpers/server-process.ts
@@ -34,7 +34,7 @@ import { SYSTEM_DOC_NAME } from '@inkeep/open-knowledge-core';
import * as Y from 'yjs';
const HELPERS_DIR = dirname(fileURLToPath(import.meta.url));
-/** `packages/app/` — every e2e fixture spawns `bun run dev` from here. */
+/** `packages/app/` — every e2e fixture spawns `pnpm run dev` from here. */
export const APP_PACKAGE_ROOT = resolve(HELPERS_DIR, '..', '..', '..');
/**
@@ -189,25 +189,71 @@ export async function waitForHttpReady(baseURL: string, timeoutMs: number): Prom
);
}
-export async function killGracefully(proc: ChildProcess, timeoutMs = 5000): Promise<void> {
- if (proc.exitCode !== null || proc.signalCode !== null) return;
- const exited = new Promise<void>((resolve) => proc.once('exit', () => resolve()));
- // ESRCH races: the process can exit between the exitCode check above and
- // either kill() call. Swallow ESRCH so cleanup teardown does not replace
- // the real test result (and the post-use rmSync still runs).
+/**
+ * Group-kill half of the tree contract: `kill(-pid)` + ESRCH-swallow, the one
+ * place that discipline lives. While any member lives, POSIX reserves the
+ * pgid, so this cannot hit a recycled pid; with no members it reports ESRCH
+ * and does nothing. Returns false when the group no longer exists.
+ */
+function killGroup(pid: number, signal: NodeJS.Signals): boolean {
try {
- proc.kill('SIGTERM');
+ process.kill(-pid, signal);
+ return true;
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ESRCH') throw err;
+ return false;
+ }
+}
+
+/**
+ * Signal the spawned process TREE, not just the direct child. The dev-server
+ * spawns are `pnpm run dev` — a shim whose actual server (vite) is a
+ * descendant. SIGTERM to the shim is usually relayed, but SIGKILL never is
+ * (the OS reaps the shim instantly), so a shim-only kill orphans a live Vite
+ * that keeps the port bound and its file-watchers on the contentDir while
+ * teardown rmSyncs that directory under it. Spawning `detached: true` gives
+ * the child its own process group (pgid == pid), and `kill(-pid)` reaches
+ * every descendant. A non-group child falls back to the direct kill: its pid
+ * is not a pgid, so the group attempt reports ESRCH.
+ *
+ * Returns false when nothing was signalled (tree already gone).
+ */
+function signalTree(proc: ChildProcess, signal: NodeJS.Signals): boolean {
+ const pid = proc.pid;
+ if (pid === undefined) return false;
+ if (killGroup(pid, signal)) return true;
+ try {
+ proc.kill(signal);
+ return true;
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== 'ESRCH') throw err;
+ return false;
+ }
+}
+
+export async function killGracefully(proc: ChildProcess, timeoutMs = 5000): Promise<void> {
+ if (proc.exitCode !== null || proc.signalCode !== null) {
+ // The direct child already exited, but its group can still hold live
+ // descendants (e.g. the pnpm shim crashed while Vite kept running).
+ if (proc.pid !== undefined) killGroup(proc.pid, 'SIGKILL');
return;
}
+ const exited = new Promise<void>((resolve) => proc.once('exit', () => resolve()));
+ // ESRCH races: the process can exit between the exitCode check above and
+ // either kill() call. Swallow ESRCH so cleanup teardown does not replace
+ // the real test result (and the post-use rmSync still runs).
+ if (!signalTree(proc, 'SIGTERM')) return;
await Promise.race([exited, wait(timeoutMs)]);
if (proc.exitCode === null && proc.signalCode === null) {
- try {
- proc.kill('SIGKILL');
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code !== 'ESRCH') throw err;
- }
+ // signalTree may report the tree already gone (the child exited during
+ // the timeout window); `exited` was armed before the first signal, so
+ // the await below cannot hang either way. The group-SIGKILL inside
+ // signalTree already reaped any descendants — no further sweep needed.
+ signalTree(proc, 'SIGKILL');
await exited;
+ } else if (proc.pid !== undefined) {
+ // Graceful path: the shim exited on SIGTERM, but its relayed SIGTERM
+ // does not always reach grandchildren — sweep the group.
+ killGroup(proc.pid, 'SIGKILL');
}
}