Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Stop OK test cleanup signalling processes it does not hold (#4938)

Nick Gomez7f2461dd60d1
diff --git a/.github/scripts/retry-transient.held-leader.test.mjs b/.github/scripts/retry-transient.held-leader.test.mjs
new file mode 100644
index 000000000..98a212a62
--- /dev/null
+++ b/.github/scripts/retry-transient.held-leader.test.mjs
@@ -0,0 +1,236 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter, once } from 'node:events';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { installSignalBoundary } from '../../test-support/held-signal-boundary.test-helper.ts';
+import { createOwnedTreeController, runWithRetry } from './retry-transient.mjs';
+
+const ATTEMPT_TIMEOUT_MS = 3_000;
+const DESCENDANT_LIFETIME_S = 8;
+const CLOSE_LIVENESS_BOUND_MS = 30_000;
+
+let boundary;
+const children = [];
+
+afterEach(async () => {
+ boundary?.restore();
+ boundary = undefined;
+ for (const child of children) {
+ if (child.exitCode === null && child.signalCode === null) await once(child, 'exit');
+ }
+ children.length = 0;
+});
+
+describe.skipIf(process.platform === 'win32')('runWithRetry owned-tree cleanup', () => {
+ test('an attempt whose shell exited while a descendant still holds its output sends nothing to the reaped shell group and reports the failed cleanup', async () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ const held = boundary;
+ const closes = [];
+ const spawnFn = (...args) => {
+ const child = held.hold(spawn(...args));
+ children.push(child);
+ closes.push(once(child, 'close'));
+ return child;
+ };
+ expect(process.kill).toBe(held.send);
+
+ const result = await runWithRetry({
+ command: [`sleep ${DESCENDANT_LIFETIME_S} & exit 0`],
+ shell: true,
+ maxAttempts: 1,
+ attemptTimeoutMs: ATTEMPT_TIMEOUT_MS,
+ cleanupGraceMs: 200,
+ cleanupReserveMs: 400,
+ spawnFn,
+ log: () => {},
+ signalSource: new EventEmitter(),
+ });
+ const [leader] = children;
+ await Promise.race([
+ Promise.all(closes),
+ new Promise((resolve) => setTimeout(resolve, CLOSE_LIVENESS_BOUND_MS)),
+ ]);
+
+ expect({
+ leaderExitedOnItsOwn: leader?.exitCode === 0 && leader?.signalCode === null,
+ refused: held.refused,
+ reportedFailure: result.ok === false,
+ }).toEqual({ leaderExitedOnItsOwn: true, refused: [], reportedFailure: true });
+ }, 60_000);
+});
+
+describe('createOwnedTreeController signals only while the attempt leader is unreaped', () => {
+ const LEADER_PID = 4321;
+ const PROBES_WHILE_MEMBERS_REMAIN = 3;
+ const GROUP_DRAIN_LIVENESS_BOUND_MS = 5_000;
+ const closeNeverObserved = { graceMs: 1, cleanupReserveMs: 1, waitForClose: async () => false };
+ const closeObserved = { graceMs: 1, cleanupReserveMs: 1, waitForClose: async () => true };
+ let backstop;
+
+ beforeEach(() => {
+ backstop = installSignalBoundary({ deliverToHeldChildren: false });
+ });
+
+ afterEach(() => {
+ backstop.restore();
+ });
+
+ const attemptLeader = (state = {}) => ({
+ pid: LEADER_PID,
+ exitCode: null,
+ signalCode: null,
+ ...state,
+ });
+
+ const posixController = (onSend = () => {}) => {
+ const sends = [];
+ const controller = createOwnedTreeController({
+ platform: 'linux',
+ killFn: (target, signal) => {
+ if (signal === 0) return;
+ sends.push([target, signal]);
+ onSend(signal);
+ },
+ sleepFn: async () => {},
+ pollIntervalMs: 1,
+ });
+ return { controller, sends };
+ };
+
+ const drainingGroupController = () => {
+ const sends = [];
+ const probedTargets = [];
+ const controller = createOwnedTreeController({
+ platform: 'linux',
+ killFn: (target, signal) => {
+ if (signal !== 0) {
+ sends.push([target, signal]);
+ return;
+ }
+ probedTargets.push(target);
+ if (probedTargets.length > PROBES_WHILE_MEMBERS_REMAIN) {
+ throw Object.assign(new Error('kill ESRCH'), { code: 'ESRCH' });
+ }
+ },
+ sleepFn: async () => {},
+ pollIntervalMs: 1,
+ });
+ return { controller, sends, probedTargets };
+ };
+
+ const win32Controller = (onTaskkill = () => {}) => {
+ const taskkills = [];
+ const controller = createOwnedTreeController({
+ platform: 'win32',
+ taskkillFn: async (args) => {
+ taskkills.push(args);
+ onTaskkill();
+ return { ok: true };
+ },
+ });
+ return { controller, taskkills };
+ };
+
+ test("an exited leader whose group still has members draws no signal, and a close that never comes is reported as 'tree-outlived-leader'", async () => {
+ const { controller, sends } = posixController();
+
+ const result = await controller.cleanup(attemptLeader({ exitCode: 0 }), closeNeverObserved);
+
+ expect({ result, sends, reachedProcessKill: backstop.refused }).toEqual({
+ result: { ok: false, reason: 'tree-outlived-leader' },
+ sends: [],
+ reachedProcessKill: [],
+ });
+ });
+
+ test("an exited leader whose output closed while its group still has members draws no signal, and is reported as 'tree-outlived-leader'", async () => {
+ const { controller, sends } = posixController();
+
+ const result = await controller.cleanup(
+ attemptLeader({ signalCode: 'SIGTERM' }),
+ closeObserved,
+ );
+
+ expect({ result, sends, reachedProcessKill: backstop.refused }).toEqual({
+ result: { ok: false, reason: 'tree-outlived-leader' },
+ sends: [],
+ reachedProcessKill: [],
+ });
+ });
+
+ test("a held leader's group gets SIGTERM, and once that SIGTERM reaped the leader a group that persists gets no SIGKILL and is reported as 'tree-outlived-leader'", async () => {
+ const leader = attemptLeader();
+ const { controller, sends } = posixController((signal) => {
+ if (signal === 'SIGTERM') leader.signalCode = 'SIGTERM';
+ });
+
+ const result = await controller.cleanup(leader, closeNeverObserved);
+
+ expect({ result, sends, reachedProcessKill: backstop.refused }).toEqual({
+ result: { ok: false, reason: 'tree-outlived-leader' },
+ sends: [[-LEADER_PID, 'SIGTERM']],
+ reachedProcessKill: [],
+ });
+ });
+
+ test.each([
+ { close: 'observed', waitForClose: async () => true, ok: true, reason: 'clean' },
+ {
+ close: 'never observed',
+ waitForClose: async () => false,
+ ok: false,
+ reason: 'close-not-observed',
+ },
+ ])(
+ 'an exited leader whose group drains on its own inside the grace window draws no signal, and a close that is $close settles it as $reason',
+ async ({ waitForClose, ok, reason }) => {
+ const { controller, sends, probedTargets } = drainingGroupController();
+
+ const result = await controller.cleanup(attemptLeader({ exitCode: 0 }), {
+ graceMs: GROUP_DRAIN_LIVENESS_BOUND_MS,
+ cleanupReserveMs: 1,
+ waitForClose,
+ });
+
+ expect({
+ result,
+ sends,
+ probedTheLeaderGroupUntilItDrained:
+ probedTargets.length > PROBES_WHILE_MEMBERS_REMAIN &&
+ probedTargets.every((target) => target === -LEADER_PID),
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ result: { ok, reason },
+ sends: [],
+ probedTheLeaderGroupUntilItDrained: true,
+ reachedProcessKill: [],
+ });
+ },
+ );
+
+ test("on win32 an exited leader gets no taskkill, and a close that never comes is reported as 'tree-outlived-leader'", async () => {
+ const { controller, taskkills } = win32Controller();
+
+ const result = await controller.cleanup(attemptLeader({ exitCode: 1 }), closeNeverObserved);
+
+ expect({ result, taskkills, reachedProcessKill: backstop.refused }).toEqual({
+ result: { ok: false, reason: 'tree-outlived-leader' },
+ taskkills: [],
+ reachedProcessKill: [],
+ });
+ });
+
+ test('on win32 a held leader is tree-killed by its own pid, and the forced taskkill is skipped once the graceful one reaped the leader', async () => {
+ const leader = attemptLeader();
+ const { controller, taskkills } = win32Controller(() => {
+ leader.exitCode = 1;
+ });
+
+ const result = await controller.cleanup(leader, closeNeverObserved);
+
+ expect({ result, taskkills, reachedProcessKill: backstop.refused }).toEqual({
+ result: { ok: false, reason: 'tree-outlived-leader' },
+ taskkills: [['/PID', String(LEADER_PID), '/T']],
+ reachedProcessKill: [],
+ });
+ });
+});
diff --git a/.github/scripts/retry-transient.mjs b/.github/scripts/retry-transient.mjs
index b8cb7a003..48e4cee37 100644
--- a/.github/scripts/retry-transient.mjs
+++ b/.github/scripts/retry-transient.mjs
@@ -386,6 +386,10 @@ function sendGroupSignal(pid, signal, killFn) {
}
}
+function hasExited(leader) {
+ return leader.exitCode !== null || leader.signalCode !== null;
+}
+
function defaultTaskkill(args) {
return new Promise((resolve) => {
const child = spawn('taskkill', args, { stdio: 'ignore', windowsHide: true });
@@ -409,13 +413,20 @@ export function createOwnedTreeController({
pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
} = {}) {
if (platform === 'win32') {
+ const closedOrOutlived = async (graceMs, waitForClose) =>
+ (await waitForClose(graceMs))
+ ? { ok: true, reason: 'clean' }
+ : { ok: false, reason: 'tree-outlived-leader' };
return {
- async cleanup(pid, { graceMs, waitForClose }) {
+ async cleanup(leader, { graceMs, waitForClose }) {
+ const { pid } = leader;
if (await waitForClose(0)) return { ok: true, reason: 'clean' };
+ if (hasExited(leader)) return closedOrOutlived(graceMs, waitForClose);
const graceful = await taskkillFn(['/PID', String(pid), '/T']);
if (graceful.ok && (await waitForClose(graceMs))) {
return { ok: true, reason: 'clean' };
}
+ if (hasExited(leader)) return closedOrOutlived(graceMs, waitForClose);
const forced = await taskkillFn(['/PID', String(pid), '/T', '/F']);
if (!forced.ok) return { ok: false, reason: 'taskkill-failure' };
if (!(await waitForClose(graceMs))) {
@@ -425,8 +436,24 @@ export function createOwnedTreeController({
},
};
}
+ const settleExitedLeader = async (pid, drainWindowMs, cleanupReserveMs, waitForClose) => {
+ const drained = await waitUntil(
+ () => !processGroupExists(pid, killFn),
+ drainWindowMs,
+ pollIntervalMs,
+ sleepFn,
+ );
+ if (!drained) return { ok: false, reason: 'tree-outlived-leader' };
+ return (await waitForClose(cleanupReserveMs))
+ ? { ok: true, reason: 'clean' }
+ : { ok: false, reason: 'close-not-observed' };
+ };
return {
- async cleanup(pid, { graceMs, cleanupReserveMs, waitForClose }) {
+ async cleanup(leader, { graceMs, cleanupReserveMs, waitForClose }) {
+ const { pid } = leader;
+ if (hasExited(leader)) {
+ return settleExitedLeader(pid, graceMs, cleanupReserveMs, waitForClose);
+ }
if (!processGroupExists(pid, killFn)) {
return (await waitForClose(graceMs))
? { ok: true, reason: 'clean' }
@@ -442,6 +469,9 @@ export function createOwnedTreeController({
sleepFn,
);
if (!goneAfterTerm) {
+ if (hasExited(leader)) {
+ return settleExitedLeader(pid, cleanupReserveMs, cleanupReserveMs, waitForClose);
+ }
if (!sendGroupSignal(pid, 'SIGKILL', killFn)) {
return { ok: false, reason: 'signal-send-failure' };
}
@@ -568,7 +598,7 @@ async function runAttempt({
const waitForClose = (timeoutMs) => waitForPromise(closePromise, timeoutMs);
let cleanup = { ok: true, reason: 'clean' };
if (child.pid) {
- cleanup = await treeController.cleanup(child.pid, {
+ cleanup = await treeController.cleanup(child, {
graceMs: cleanupGraceMs,
cleanupReserveMs,
waitForClose,
diff --git a/.github/scripts/retry-transient.test.mjs b/.github/scripts/retry-transient.test.mjs
index 085ea20f7..c6b3624d3 100644
--- a/.github/scripts/retry-transient.test.mjs
+++ b/.github/scripts/retry-transient.test.mjs
@@ -1,6 +1,7 @@
import { spawn, spawnSync } from 'node:child_process';
-import { EventEmitter } from 'node:events';
+import { EventEmitter, once } from 'node:events';
import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { PassThrough } from 'node:stream';
@@ -10,6 +11,7 @@ import {
createFuseFailure,
FUSE_FAILURE_MARKER,
} from '../../packages/desktop/scripts/packaging-diagnostics.mjs';
+import { installSignalBoundary } from '../../test-support/held-signal-boundary.test-helper.ts';
import {
classifyEvidence,
computeRetryDelayMs,
@@ -1099,26 +1101,89 @@ describe('deadlines and cancellation', () => {
});
test.runIf(process.platform !== 'win32')(
- 'reaps a real grandchild before the next attempt starts',
+ "a real grandchild that outlives the exited leader of its attempt is reported as 'tree-outlived-leader', which stops the run before the next attempt starts, and no signal reaches the group of that reaped leader",
async (ctx) => {
const helper = join(scratch, 'tree-helper.mjs');
const count = join(scratch, 'tree-count');
const pidFile = join(scratch, 'grandchild-pid');
const overlap = join(scratch, 'tree-overlap');
+ const lifelinePath = join(scratch, 'lifeline.sock');
writeFileSync(count, '0');
+ const lifelines = [];
+ const lifelineServer = createServer((socket) => lifelines.push(socket));
+ let lifelineReleased = false;
+ const releaseLifeline = () => {
+ if (lifelineReleased) return;
+ lifelineReleased = true;
+ for (const socket of lifelines) socket.destroy();
+ lifelineServer.close();
+ };
+ const grandchild = `process.on("SIGTERM",()=>{});const lifeline=require("net").connect(${JSON.stringify(lifelinePath)});lifeline.on("close",()=>process.exit(0));lifeline.on("error",()=>process.exit(0));setTimeout(()=>process.exit(0),${childSelfExitMs})`;
writeFileSync(
helper,
- `import { spawn } from 'node:child_process';import { readFileSync,writeFileSync } from 'node:fs';const [count,pidFile,overlap]=process.argv.slice(2);const n=+readFileSync(count,'utf8')+1;writeFileSync(count,String(n));if(n===1){const child=spawn(process.execPath,['-e','process.on("SIGTERM",()=>{});setTimeout(()=>{},${childSelfExitMs})'],{stdio:'ignore'});writeFileSync(pidFile,String(child.pid));console.error('socket hang up');process.exit(1)}const pid=+readFileSync(pidFile,'utf8');try{process.kill(pid,0);writeFileSync(overlap,'alive');process.exit(1)}catch{process.exit(0)}`,
+ `import { spawn } from 'node:child_process';import { readFileSync,writeFileSync } from 'node:fs';const [count,pidFile,overlap]=process.argv.slice(2);const n=+readFileSync(count,'utf8')+1;writeFileSync(count,String(n));if(n===1){const child=spawn(process.execPath,['-e',${JSON.stringify(grandchild)}],{stdio:'ignore'});writeFileSync(pidFile,String(child.pid));console.error('socket hang up');process.exit(1)}const pid=+readFileSync(pidFile,'utf8');try{process.kill(pid,0);writeFileSync(overlap,'alive');process.exit(1)}catch{process.exit(0)}`,
);
- const result = await run({
- command: [process.execPath, helper, count, pidFile, overlap],
- cleanupGraceMs: 30,
- });
- expect(result).toMatchObject({ ok: true, attempts: 2 });
- expect(existsSync(overlap)).toBe(false);
- await assertChildRanThenDied(ctx, pidFile);
+ const boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ try {
+ expect(process.kill).toBe(boundary.send);
+ lifelineServer.listen(lifelinePath);
+ await once(lifelineServer, 'listening');
+ const result = await run({
+ command: [process.execPath, helper, count, pidFile, overlap],
+ cleanupGraceMs: 30,
+ spawnFn: (...args) => boundary.hold(spawn(...args)),
+ });
+ const grandchildPid = existsSync(pidFile) ? Number(readFileSync(pidFile, 'utf8')) : NaN;
+ const inProcessTable = (pid) => {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+ };
+ const grandchildAliveWhenTheRunReturned =
+ Number.isInteger(grandchildPid) && grandchildPid > 1 && inProcessTable(grandchildPid);
+
+ expect({
+ result: {
+ ok: result.ok,
+ reason: result.reason,
+ cleanup: result.cleanup,
+ attempts: result.attempts,
+ },
+ attemptsStarted: readFileSync(count, 'utf8'),
+ overlapObserved: existsSync(overlap),
+ refused: boundary.refused,
+ grandchildAliveWhenTheRunReturned,
+ }).toEqual({
+ result: {
+ ok: false,
+ reason: 'cleanup-failure',
+ cleanup: 'tree-outlived-leader',
+ attempts: 1,
+ },
+ attemptsStarted: '1',
+ overlapObserved: false,
+ refused: [],
+ grandchildAliveWhenTheRunReturned: true,
+ });
+
+ await vi.waitFor(
+ () =>
+ expect(
+ lifelines.length,
+ `grandchild ${grandchildPid} never connected to the lifeline at ${lifelinePath}, so closing that lifeline cannot be what ends it`,
+ ).toBeGreaterThan(0),
+ { timeout: readinessTimeoutDefaultMs, interval: 10 },
+ );
+ releaseLifeline();
+ await assertChildRanThenDied(ctx, pidFile);
+ } finally {
+ boundary.restore();
+ releaseLifeline();
+ }
},
- 5_000,
);
test.runIf(process.platform !== 'win32')(
@@ -1153,6 +1218,8 @@ describe('deadlines and cancellation', () => {
);
});
+const heldLeader = () => ({ pid: 4321, exitCode: null, signalCode: null });
+
describe('POSIX owned-tree cleanup reasons', () => {
const options = { graceMs: 1, cleanupReserveMs: 1, waitForClose: async () => false };
@@ -1172,7 +1239,9 @@ describe('POSIX owned-tree cleanup reasons', () => {
sleepFn: async () => {},
pollIntervalMs: 1,
});
- expect(await controller.cleanup(4321, { ...options, waitForClose: async () => true })).toEqual({
+ expect(
+ await controller.cleanup(heldLeader(), { ...options, waitForClose: async () => true }),
+ ).toEqual({
ok: true,
reason: 'clean',
});
@@ -1201,7 +1270,9 @@ describe('POSIX owned-tree cleanup reasons', () => {
sleepFn: async () => {},
pollIntervalMs: 1,
});
- expect(await controller.cleanup(4321, { ...options, waitForClose: async () => true })).toEqual({
+ expect(
+ await controller.cleanup(heldLeader(), { ...options, waitForClose: async () => true }),
+ ).toEqual({
ok: true,
reason: 'clean',
});
@@ -1218,7 +1289,7 @@ describe('POSIX owned-tree cleanup reasons', () => {
if (signal !== 0) throw Object.assign(new Error('denied'), { code: 'EPERM' });
},
});
- expect(await controller.cleanup(4321, options)).toEqual({
+ expect(await controller.cleanup(heldLeader(), options)).toEqual({
ok: false,
reason: 'signal-send-failure',
});
@@ -1231,7 +1302,7 @@ describe('POSIX owned-tree cleanup reasons', () => {
sleepFn: async () => {},
pollIntervalMs: 1,
});
- expect(await controller.cleanup(4321, options)).toEqual({
+ expect(await controller.cleanup(heldLeader(), options)).toEqual({
ok: false,
reason: 'tree-survived-kill',
});
@@ -1244,10 +1315,12 @@ describe('POSIX owned-tree cleanup reasons', () => {
throw Object.assign(new Error('gone'), { code: 'ESRCH' });
},
});
- expect(await controller.cleanup(4321, options)).toEqual({
- ok: false,
- reason: 'close-not-observed',
- });
+ expect(await controller.cleanup({ pid: 4321, exitCode: 0, signalCode: null }, options)).toEqual(
+ {
+ ok: false,
+ reason: 'close-not-observed',
+ },
+ );
});
});
@@ -1288,7 +1361,7 @@ describe('Windows owned-tree adapter', () => {
},
sleepFn: () => Promise.resolve(),
});
- const cleaned = await controller.cleanup(4321, {
+ const cleaned = await controller.cleanup(heldLeader(), {
graceMs: 50,
waitForClose: async () => calls.length > 1,
});
@@ -1305,7 +1378,7 @@ describe('Windows owned-tree adapter', () => {
taskkillFn: async () => ({ ok: false }),
});
expect(
- await controller.cleanup(4321, {
+ await controller.cleanup(heldLeader(), {
graceMs: 1,
waitForClose: async () => false,
}),
@@ -1318,7 +1391,7 @@ describe('Windows owned-tree adapter', () => {
taskkillFn: async () => ({ ok: true }),
});
expect(
- await controller.cleanup(4321, {
+ await controller.cleanup(heldLeader(), {
graceMs: 1,
waitForClose: async () => false,
}),
diff --git a/AGENTS.md b/AGENTS.md
index 54fa460db..78979a35b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,7 +49,7 @@ pnpm run dev
## Process safety
-Never signal a pid you did not spawn. No literal `0`, `1`, or `-1`, numeric fallback, or unvalidated parsed number may reach `process.kill` or the reaper. Validate lock-file PIDs with `isValidLockPid()`. Gate: `ok/no-sentinel-signal-target`.
+Never signal a pid you did not spawn. Signal a held `ChildProcess` before it exits (its group only then); never a pid from a file, `ps` or stdout, a `?? <n>` fallback or literal `0`/`1`/`-1`. Gate: `ok/no-sentinel-signal-target`.
## Comment policy
diff --git a/knip.config.ts b/knip.config.ts
index 6a38348d8..8b615429f 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -143,11 +143,15 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
- ignoreDependencies: ['yjs'],
+ ignoreDependencies: [
+ 'yjs',
+ ],
},
'packages/desktop': {
entry: [
diff --git a/lint-plugins/ok-rules/README.md b/lint-plugins/ok-rules/README.md
index 61464ffb3..d3280fc37 100644
--- a/lint-plugins/ok-rules/README.md
+++ b/lint-plugins/ok-rules/README.md
@@ -639,18 +639,17 @@ Rule: [`lint-plugins/ok-rules/rules/no-unconverted-git-pathspec.mjs`](rules/no-u
### `no-sentinel-signal-target`
-Owned-process signalling. `process.kill(target, signal)` — and the desktop test-support reaper seam `signalOwnedGroup` / `signalOwnedPids` / `reapOwnedTree` when no sender is injected (that seam is not on `main` yet — it lives on the unmerged `feat/ok-update-relaunch-substrate` branch, and the rule covers it ahead of time so the gate is in place the day it lands) — never receive a target that is (a) a literal `0`, `1` or `-1`, (b) a `?? <n>` / `|| <n>` fallback to a number, or (c) an unvalidated parse of text — `Number(...)`, `parseInt(...)`, `parseFloat(...)`, or the `Number.` spellings of the latter two. A signal-`0` liveness probe (`process.kill(pid, 0)`) sends nothing and is exempt, whatever the target.
+Owned-process signalling. `process.kill(target, signal)` — and the desktop test-support reaper seam `signalOwnedGroup` / `signalOwnedPids` / `reapOwnedTree` when no sender is injected (that seam is not on `main` yet — it lives on the unmerged `feat/ok-update-relaunch-substrate` branch, and the rule covers it ahead of time so the gate is in place the day it lands) — never receive a target that is (a) a literal `0`, `1` or `-1`, (b) a `?? <n>` / `|| <n>` fallback to a number, or (c) a parse of text — `Number(...)`, `parseInt(...)`, `parseFloat(...)`, or the `Number.` spellings of the latter two. A signal-`0` liveness probe (`process.kill(pid, 0)`) sends nothing and is exempt, whatever the target.
**Why.** On POSIX, `kill(0, sig)` signals the caller's whole process group, `kill(-1, sig)` every process the user owns, and `kill(-pid, sig)` a group. On 2026-09-20 and 21 a desktop unit test killed every process on a developer's Mac three times, Terminal included: it called `signalOwnedGroup(1, 'SIGKILL')` to prove a guard refused it, a mutation loop had weakened the guard to `pid > 0`, and `process.kill(-1, …)` went through. The mutation loop was killed before its own revert step, so the mutant stayed on disk and every later run of the suite repeated the kill. The same sentinel shape was already live on `main`: `process.kill(pid ?? 0, 'SIGKILL')` in a test reaper, and `process.kill(Number(readFileSync(pidFile)), 'SIGKILL')` in a `finally` — an empty pidfile parses to `0`. Both shipped green: nothing in `pnpm lint` or `pnpm check` looked at what a kill was fed. Canonical prose: the "Never signal a pid you did not spawn" STOP rule in the workspace `AGENTS.md`, an internal guide the public mirror does not carry; this rule encodes its decidable subset and the two are kept in step by the fixture test.
**Sanctioned shapes.** Every shape in this list works on this head and needs no seam; only the injected sender below waits on one.
- **Signal the handle you spawned** — `child.kill(signal)`.
-- **Or a pid you took from that handle** — `child.pid`, wrapped or negated for its group. Negation reaches a group only if you spawned it detached, since `-pid` addresses the group whose pgid is that pid and an ordinary child leads none; on a non-detached child it raises `ESRCH`, which a `catch {}` around the kill turns into a surviving process.
-- **Negation is not laundering.** `-<expr>` is judged by exactly the same tests as `<expr>`, so `-(pid ?? 0)` fires just as `pid ?? 0` does, and only a pid already taken from a handle or already validated survives the minus sign.
+- **Or a pid you took from that handle** — `child.pid`, wrapped or negated for its group, only while the handle has not reported exit, checked in the same turn as the signal. Negation reaches a group only if you spawned it detached, since `-pid` addresses the group whose pgid is that pid and an ordinary child leads none; on a non-detached child it raises `ESRCH`, which a `catch {}` around the kill turns into a surviving process.
+- **Negation is not laundering.** `-<expr>` is judged by exactly the same tests as `<expr>`, so a negated `?? <n>` fallback fires just as the bare fallback does, and only a pid already taken from a handle survives the minus sign.
- **Filter a nullable pid out of a list** instead of substituting a sentinel.
-- **Validate a pid parsed from a file or a `ps` row** with `isValidLockPid()` from `@inkeep/open-knowledge-server` before signalling it.
-- **Worked exemplar, on this head.** `spawnDeck`'s reaper in [`ok-bin-child-spawn-path.test.ts`](../../packages/desktop/tests/integration/ok-bin-child-spawn-path.test.ts) signals an `isValidLockPid`-validated `ps` row with `process.kill(pid, 'SIGKILL')` and takes its group down with `process.kill(-shellPid, 'SIGKILL')`, the negation sound there because that child came from `spawnDetachedInteractiveChild`. That reaper is itself one of the sites the **Direct `process.kill` of spawned-child pids in tests outside the seam** bullet below schedules for seam migration: sanctioned to write on this head, expected to move once the seam lands, and not a defect in the meantime.
+- **A pid parsed from a file or a `ps` row is not a signal target**, because `isValidLockPid()` checks its range, not its owner. Stop that process through its owner, or report it.
**The reaper seam is what is absent.** `signalOwnedGroup`, `signalOwnedPids`, `reapOwnedTree` and `recordingSignalSender` have no definition on this head, so the seam's own sanctioned shape — an injected sender — is the one thing you cannot write here yet. Once the seam lands, a guard test that must feed it a sentinel passes `recordingSignalSender().send` — not the recorder itself — in the sender slot, which is the third argument to `signalOwnedGroup` and `signalOwnedPids` but the fourth to `reapOwnedTree`, and asserts the recorded calls. The rule stops firing only when a real sender value occupies that slot: passing `undefined` or `void 0` explicitly injects nothing and still fires, and passing `process.kill` itself is no escape either.
@@ -658,8 +657,8 @@ The rule does NOT catch:
- **A sentinel held in a variable** (`const target = 1; process.kill(target, …)`) or a `ps`-parsed pid that reaches a kill through an untyped variable — data flow the untyped AST cannot see, left to the STOP rule and review.
- **A guard weakened inside the seam** — that is what the seam's injected sender exists for, since the mutant then fails a test instead of the host.
-- **Direct `process.kill` of spawned-child pids in tests outside the seam** — 27 such sites exist on `main` and a structural rule routing them through the seam waits until the seam itself lands on `main`.
-- **Anything `oxlint.config.ts` excludes from selection** — `ignorePatterns` drops `/reports/**` and `/specs/**` before any rule sees them, and naming such a file positionally on the command line does not override it. Those two trees hold 110 executable `.ts`/`.mjs`/`.js` files, 5 of which call `process.kill` today; they are the local spike-harness class of script this incident came from, and no oxlint rule reaches them. See [§3 of the authoring guide](#3-scope-it-if-it-is-not-workspace-wide) for the measurement.
+- **Whether a pid taken from a handle is signalled while that handle is still unreaped**: a handle's pid, negated or not, passes whatever the child's state (fixture n2, n3, n12); lifecycle is data flow the AST cannot see, left to the STOP rule and review until a seam that takes held, unreaped handles lands on `main`.
+- **Anything `oxlint.config.ts` excludes from selection** — `ignorePatterns` drops `/reports/**` and `/specs/**` before any rule sees them, and naming such a file positionally on the command line does not override it. Those two trees hold 164 executable `.ts`/`.mjs`/`.js` files, 4 of which call `process.kill` today; they are the local spike-harness class of script this incident came from, and no oxlint rule reaches them. See [§3 of the authoring guide](#3-scope-it-if-it-is-not-workspace-wide) for the measurement.
**Unscoped** (workspace-wide in the scope table's sense — it carries no `RULE_SCOPES` entry and sits in `UNSCOPED_RULES` in [`scope.mjs`](scope.mjs), so nothing here narrows it; selection still excludes the trees named just above): a fabricated signal target is wrong in every package, and in test code most of all.
diff --git a/lint-plugins/ok-rules/__fixtures__/no-sentinel-signal-target.fixture.tsx b/lint-plugins/ok-rules/__fixtures__/no-sentinel-signal-target.fixture.tsx
index 2ccdd73a9..286e35fb1 100644
--- a/lint-plugins/ok-rules/__fixtures__/no-sentinel-signal-target.fixture.tsx
+++ b/lint-plugins/ok-rules/__fixtures__/no-sentinel-signal-target.fixture.tsx
@@ -17,11 +17,14 @@
// P16 Number.parseFloat(...), P17 parseFloat(...)
//
// Negatives (0 fires): the signal-0 liveness probe on pid 1 (boundary pair with
-// P2), an `as number`-wrapped spawned pid, a group kill of a spawned pid
-// (`-(child.pid as number)` and bare `-spawnedPid`), the ChildProcess handle, `kill` on
-// a non-`process` object, the method in a type declaration, the seam with an injected
-// recorder — including one threaded past an explicit `undefined` pollMs — a
-// null-filtered pid list, a validated parsed pid, and `?? -1` outside a kill.
+// P2), the ChildProcess handle, `kill` on a non-`process` object, the method in a
+// type declaration, the seam with an injected recorder — including one threaded
+// past an explicit `undefined` pollMs — a null-filtered pid list, and `?? -1`
+// outside a kill. Two blind spots also pass, and neither is a sanctioned target:
+// an `as number`-wrapped spawned pid and a group kill of a spawned pid
+// (`-(child.pid as number)` and bare `-spawnedPid`) pass because the rule does not
+// check that the child is unreaped, a lifecycle blind spot; and a range-checked
+// parsed pid held in a variable passes as data flow the rule cannot see.
// Exact-equality (`toBe(20)` plus the per-branch counts) catches false-negative
// regressions and false-positive widenings alike.
@@ -80,7 +83,7 @@ export const p20 = reapOwnedTree(1, 500, undefined, undefined);
// (1) Signal 0 sends nothing — the liveness probe, even on pid 1 (boundary pair with P2).
export const n1 = process.kill(1, 0);
-// (2-3) A spawned pid behind TS wrappers, singly and as its own process group.
+// (2-3) A spawned pid behind TS wrappers, singly and as its own process group. It passes because the rule does not check that the child is unreaped: a lifecycle blind spot, not a sanctioned target.
export const n2 = process.kill(child.pid as number, 'SIGKILL');
export const n3 = process.kill(-(child.pid as number), 'SIGTERM');
// (4) The ChildProcess handle signals exactly that child.
@@ -99,12 +102,12 @@ export const n9 = signalOwnedPids(
[descendant, spawnedPid, ...(supervisor === null ? [] : [supervisor])],
'SIGKILL',
);
-// (10) A parsed pid validated before it is signalled.
+// (10) A range-checked parsed pid reaching a kill through a variable: data flow the rule cannot see, not a sanctioned target.
const parsed = Number(readFileSync(pidFile, 'utf8'));
export const n10 = isValidLockPid(parsed) ? process.kill(parsed, 'SIGKILL') : false;
// (11) `?? -1` outside a kill — an index, not a signal target.
export const n11 = BODY[hit?.start ?? -1];
-// (12) The same group kill without the TS wrapper — a bare negated spawned pid.
+// (12) The same group kill without the TS wrapper — a bare negated spawned pid. It passes because the rule does not check that the child is unreaped: a lifecycle blind spot, not a sanctioned target.
export const n12 = process.kill(-spawnedPid, 'SIGKILL');
// (13) The seam's injected recorder threaded past an explicit `undefined` pollMs.
export const n13 = reapOwnedTree(1, 500, undefined, sender.send);
diff --git a/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs b/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
index 796802653..a48561083 100644
--- a/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
+++ b/lint-plugins/ok-rules/rules/no-sentinel-signal-target.mjs
@@ -2,9 +2,9 @@ import { docsUrl } from '../docs.mjs';
const URL = docsUrl('no-sentinel-signal-target');
-const LITERAL_MESSAGE = `Signal target is a literal 0, 1 or -1 — on POSIX that addresses the caller's whole process group, init, or every process the user owns, never a child. Signal only a pid you spawned — the ChildProcess handle, or its pid taken from that handle, negated for the group only if you spawned it detached. See ${URL}`;
+const LITERAL_MESSAGE = `Signal target is a literal 0, 1 or -1 — on POSIX that addresses the caller's whole process group, init, or every process the user owns, never a child. Signal only a pid you spawned, and only while it has not exited — the ChildProcess handle, or its pid taken from that handle, negated for the group only if you spawned it detached. See ${URL}`;
const FALLBACK_MESSAGE = `A \`?? <n>\` / \`|| <n>\` fallback fabricates a signal target when the pid is missing, and \`kill(0, …)\` reaches the caller's own process group. Filter the nullable pid out instead of substituting a sentinel. See ${URL}`;
-const PARSED_MESSAGE = `A pid parsed from text reaches \`process.kill\` unvalidated — an empty pidfile yields \`0\` or \`NaN\` depending on the parser, and a stale one yields a pid that now belongs to some other process. Validate it with \`isValidLockPid()\` from @inkeep/open-knowledge-server before signalling. See ${URL}`;
+const PARSED_MESSAGE = `A pid parsed from text reaches \`process.kill\` — an empty pidfile yields \`0\` or \`NaN\` depending on the parser, and a stale pid names whatever process holds the number now. \`isValidLockPid()\` checks only its range, not who owns it. Signal the \`ChildProcess\` you spawned instead; if you hold no handle for the process it names, stop that process through its owner, or report it. See ${URL}`;
const SEAM_SENDER_INDEX = new Map([
['signalOwnedGroup', 2],
@@ -104,7 +104,7 @@ export const noSentinelSignalTarget = {
type: 'problem',
docs: {
description:
- 'process.kill and the owned-process reaper never receive a literal, fallback-fabricated or unvalidated-parsed pid.',
+ 'process.kill and the owned-process reaper never receive a literal, fallback-fabricated or parsed pid.',
url: URL,
},
},
diff --git a/packages/app/scripts/measure-sweep.sh b/packages/app/scripts/measure-sweep.sh
index 1faed9e7b..8770c95bd 100755
--- a/packages/app/scripts/measure-sweep.sh
+++ b/packages/app/scripts/measure-sweep.sh
@@ -144,12 +144,12 @@ cleanup() {
local ec=$?
if [[ -n "$SERVER_PID" ]] && kill -0 "$SERVER_PID" 2>/dev/null; then
echo "[measure-sweep] stopping server (pid $SERVER_PID)…" >&2
- kill -TERM "$SERVER_PID" 2>/dev/null || true
+ kill -TERM %1 2>/dev/null || true
for _ in 1 2 3 4 5 6 7 8 9 10; do
kill -0 "$SERVER_PID" 2>/dev/null || break
sleep 0.5
done
- kill -0 "$SERVER_PID" 2>/dev/null && kill -KILL "$SERVER_PID" 2>/dev/null || true
+ kill -0 "$SERVER_PID" 2>/dev/null && kill -KILL %1 2>/dev/null || true
fi
if [[ "$KEEP_SCRATCH" -eq 1 ]]; then
echo "[measure-sweep] scratch kept at $SCRATCH" >&2
diff --git a/packages/app/scripts/perf-prod.sh b/packages/app/scripts/perf-prod.sh
index 3655d5930..dfc90c1fb 100755
--- a/packages/app/scripts/perf-prod.sh
+++ b/packages/app/scripts/perf-prod.sh
@@ -157,15 +157,15 @@ cleanup() {
local ec=$?
if [[ -n "${SERVER_PID:-}" ]] && kill -0 "$SERVER_PID" 2>/dev/null; then
echo "[perf-prod] Stopping server (pid $SERVER_PID)…"
- kill -TERM "$SERVER_PID" 2>/dev/null || true
+ kill -TERM %1 2>/dev/null || true
fi
for _ in 1 2 3 4 5 6 7 8 9 10; do
- if ! kill -0 "${SERVER_PID:-0}" 2>/dev/null && [[ ! -f "$SERVER_LOCK" ]]; then break; fi
+ if ! kill -0 "$SERVER_PID" 2>/dev/null && [[ ! -f "$SERVER_LOCK" ]]; then break; fi
sleep 0.5
done
if [[ -n "${SERVER_PID:-}" ]] && kill -0 "$SERVER_PID" 2>/dev/null; then
echo "[perf-prod] WARN: pid $SERVER_PID did not exit on SIGTERM; sending SIGKILL" >&2
- kill -KILL "$SERVER_PID" 2>/dev/null || true
+ kill -KILL %1 2>/dev/null || true
fi
if [[ $ec -ne 0 ]]; then
echo "[perf-prod] Script exited non-zero ($ec). Log:" >&2
diff --git a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
index 8a60e5826..a28cc2b18 100644
--- a/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
+++ b/packages/app/tests/integration/bug3-source-mode-writeback.test.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
index 6fcdc23f2..4fc2c11f9 100644
--- a/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
+++ b/packages/app/tests/integration/indented-jsx-byte-sacred.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { normalizeBridge } from '@inkeep/open-knowledge-core';
import { updateYFragment } from '@tiptap/y-tiptap';
diff --git a/packages/app/tests/integration/interior-edit-freshness.test.ts b/packages/app/tests/integration/interior-edit-freshness.test.ts
index 40b5cdfd6..9f2f6feb6 100644
--- a/packages/app/tests/integration/interior-edit-freshness.test.ts
+++ b/packages/app/tests/integration/interior-edit-freshness.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
index 93666af70..2a085742b 100644
--- a/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
+++ b/packages/app/tests/integration/keystroke-cadence-danger-space.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/kill-gracefully-errno.test.ts b/packages/app/tests/integration/kill-gracefully-errno.test.ts
index 7dd019133..3ef1559fc 100644
--- a/packages/app/tests/integration/kill-gracefully-errno.test.ts
+++ b/packages/app/tests/integration/kill-gracefully-errno.test.ts
@@ -39,7 +39,7 @@ afterEach(() => {
describe('killGroup errno policy', () => {
test('reports success when the group signal lands', () => {
const kill = vi.spyOn(process, 'kill').mockReturnValue(true);
- expect(killGroup(9_001, 'SIGTERM')).toBe(true);
+ expect(killGroup(fakeChild({ pid: 9_001, kill: () => true }), 'SIGTERM')).toBe(true);
expect(kill).toHaveBeenCalledWith(-9_001, 'SIGTERM');
});
@@ -47,7 +47,7 @@ describe('killGroup errno policy', () => {
vi.spyOn(process, 'kill').mockImplementation(() => {
throw errnoError('ESRCH');
});
- expect(killGroup(9_001, 'SIGTERM')).toBe(false);
+ expect(killGroup(fakeChild({ pid: 9_001, kill: () => true }), 'SIGTERM')).toBe(false);
expect(warn).not.toHaveBeenCalled();
});
@@ -55,14 +55,14 @@ describe('killGroup errno policy', () => {
vi.spyOn(process, 'kill').mockImplementation(() => {
throw errnoError('EPERM');
});
- expect(killGroup(9_001, 'SIGKILL')).toBe(false);
+ expect(killGroup(fakeChild({ pid: 9_001, kill: () => true }), 'SIGKILL')).toBe(false);
});
test('warns on EPERM so a genuinely leaked tree still leaves a trace', () => {
vi.spyOn(process, 'kill').mockImplementation(() => {
throw errnoError('EPERM');
});
- killGroup(9_001, 'SIGKILL');
+ killGroup(fakeChild({ pid: 9_001, kill: () => true }), 'SIGKILL');
expect(warn).toHaveBeenCalledTimes(1);
expect(String(warn.mock.calls[0]?.[0])).toContain('EPERM');
});
@@ -74,7 +74,7 @@ describe('killGroup errno policy', () => {
vi.spyOn(process, 'kill').mockImplementation(() => {
throw err;
});
- expect(() => killGroup(9_001, 'SIGTERM')).toThrow(err);
+ expect(() => killGroup(fakeChild({ pid: 9_001, kill: () => true }), 'SIGTERM')).toThrow(err);
},
);
@@ -82,12 +82,40 @@ describe('killGroup errno policy', () => {
'refuses pid %p instead of signalling our own process group',
(pid) => {
const kill = vi.spyOn(process, 'kill').mockReturnValue(true);
- expect(killGroup(pid, 'SIGKILL')).toBe(false);
+ expect(killGroup(fakeChild({ pid, kill: () => true }), 'SIGKILL')).toBe(false);
expect(kill).not.toHaveBeenCalled();
},
);
});
+describe('killGroup signals the group only of a child that has not exited', () => {
+ test.each([
+ ['exits with a code', { exitCode: 0, signalCode: null }],
+ ['is killed by a signal', { exitCode: null, signalCode: 'SIGKILL' }],
+ ] as const)(
+ 'signals the group of a running child, and sends nothing once that child %s',
+ (_label, exit) => {
+ const sent: unknown[][] = [];
+ vi.spyOn(process, 'kill').mockImplementation((...args) => {
+ sent.push(args);
+ return true;
+ });
+ expect(vi.isMockFunction(process.kill)).toBe(true);
+ const proc = fakeChild({ pid: 424_242, kill: () => true });
+
+ const whileRunning = killGroup(proc, 'SIGTERM');
+ Object.assign(proc, exit);
+ const afterExit = killGroup(proc, 'SIGKILL');
+
+ expect({ whileRunning, afterExit, sent }).toEqual({
+ whileRunning: true,
+ afterExit: false,
+ sent: [[-424_242, 'SIGTERM']],
+ });
+ },
+ );
+});
+
describe('signalTree errno policy', () => {
beforeEach(() => {
vi.spyOn(process, 'kill').mockImplementation(() => {
@@ -186,11 +214,86 @@ describe('killGracefully under a kill surface that reports EPERM everywhere', ()
await expect(killGracefully(proc, 500)).resolves.toBeUndefined();
});
- test('still sweeps the group when the direct child has already exited', async () => {
- const kill = vi.spyOn(process, 'kill').mockReturnValue(true);
- const proc = fakeChild({ kill: () => true });
- (proc as unknown as { exitCode: number | null }).exitCode = 0;
- await killGracefully(proc, 500);
- expect(kill).toHaveBeenCalledWith(-424_242, 'SIGKILL');
+ test.each([
+ ['exited with a code', { exitCode: 0, signalCode: null }],
+ ['was killed by a signal', { exitCode: null, signalCode: 'SIGTERM' }],
+ ] as const)(
+ 'sends nothing to the process group once the direct child %s, because its group id is no longer reserved',
+ async (_label, exit) => {
+ const kill = vi.spyOn(process, 'kill').mockReturnValue(true);
+ const proc = fakeChild({ kill: () => true });
+ Object.assign(proc, exit);
+ await killGracefully(proc, 500);
+ expect(kill.mock.calls.filter(([, signal]) => signal !== 0)).toEqual([]);
+ },
+ );
+});
+
+describe('killGracefully drains the group of an exited leader until its probe answers ESRCH', () => {
+ const LEADER_PID = 424_242;
+ const PROBES_WHILE_MEMBERS_REMAIN = 3;
+
+ function recordProbes(answer: (probe: number) => Error) {
+ const sends: unknown[][] = [];
+ const probedTargets: number[] = [];
+ vi.spyOn(process, 'kill').mockImplementation((target, signal) => {
+ if (signal !== 0) {
+ sends.push([target, signal]);
+ return true;
+ }
+ probedTargets.push(target);
+ throw answer(probedTargets.length);
+ });
+ expect(vi.isMockFunction(process.kill)).toBe(true);
+ return { sends, probedTargets };
+ }
+
+ function exitedLeader(): ChildProcess {
+ const proc = fakeChild({ pid: LEADER_PID, kill: () => true });
+ Object.assign(proc, { exitCode: 0, signalCode: null });
+ return proc;
+ }
+
+ function leaderReported(): boolean {
+ return warn.mock.calls.some(([message]) =>
+ new RegExp(`(^|\\D)${LEADER_PID}(\\D|$)`).test(String(message)),
+ );
+ }
+
+ test('keeps probing through EPERM answers and reports nothing once the group answers ESRCH', async () => {
+ const { sends, probedTargets } = recordProbes((probe) =>
+ errnoError(probe > PROBES_WHILE_MEMBERS_REMAIN ? 'ESRCH' : 'EPERM'),
+ );
+
+ await killGracefully(exitedLeader(), 500);
+
+ expect({
+ sends,
+ probedTheLeaderGroupUntilItDrained:
+ probedTargets.length > PROBES_WHILE_MEMBERS_REMAIN &&
+ probedTargets.every((target) => target === -LEADER_PID),
+ leaderReported: leaderReported(),
+ }).toEqual({ sends: [], probedTheLeaderGroupUntilItDrained: true, leaderReported: false });
+ });
+
+ test('reports the leader when its group still answers EPERM at the bound', async () => {
+ const { sends, probedTargets } = recordProbes(() => errnoError('EPERM'));
+
+ await killGracefully(exitedLeader(), 500);
+
+ expect({
+ sends,
+ probedMoreThanOnce: probedTargets.length > 1,
+ leaderReported: leaderReported(),
+ }).toEqual({ sends: [], probedMoreThanOnce: true, leaderReported: true });
});
+
+ test.each(['EACCES', 'EINVAL', 'ENOSYS', undefined])(
+ 'rethrows %s from the probe rather than reading it as a drained group',
+ async (code) => {
+ const err = code === undefined ? new Error('not an errno at all') : errnoError(code);
+ recordProbes(() => err);
+ await expect(killGracefully(exitedLeader(), 500)).rejects.toThrow(err);
+ },
+ );
});
diff --git a/packages/app/tests/integration/kill-gracefully-tree.test.ts b/packages/app/tests/integration/kill-gracefully-tree.test.ts
index c321f4837..0d678315e 100644
--- a/packages/app/tests/integration/kill-gracefully-tree.test.ts
+++ b/packages/app/tests/integration/kill-gracefully-tree.test.ts
@@ -1,118 +1,234 @@
-import { type ChildProcess, execFileSync, spawn } from 'node:child_process';
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
+import { once } from 'node:events';
import { setTimeout as wait } from 'node:timers/promises';
-import { afterEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ installSignalBoundary,
+ type SignalBoundary,
+} from '../../../../test-support/held-signal-boundary.test-helper';
import { killGracefully } from '../stress/_helpers/server-process.ts';
-const spawned: ChildProcess[] = [];
+const DESCENDANT_REPORT_BOUND_MS = 10_000;
+const DESCENDANT_EXIT_BOUND_MS = 5_000;
+const GROUP_EXIT_BOUND_MS = 2_000;
+
+const DESCENDANT = `sh -c 'echo DESC=$$; exec cat <&3 >/dev/null'`;
+const TERM_IGNORING_DESCENDANT = `sh -c 'trap "" TERM; echo DESC=$$; exec cat <&3 >/dev/null'`;
+
+interface LifelineTree {
+ proc: ChildProcess;
+ output: () => string;
+}
+
+let boundary: SignalBoundary;
+const trees: ChildProcess[] = [];
+
+beforeEach(() => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+});
+
afterEach(() => {
- for (const proc of spawned) {
- if (proc.pid !== undefined) {
+ for (const proc of trees) {
+ if (proc.pid !== undefined && proc.exitCode === null && proc.signalCode === null) {
try {
process.kill(-proc.pid, 'SIGKILL');
} catch {}
}
+ proc.stdio[3]?.destroy();
}
- spawned.length = 0;
+ trees.length = 0;
+ boundary.restore();
+ vi.restoreAllMocks();
});
-function isAlive(pid: number): boolean {
- try {
- process.kill(pid, 0);
- return true;
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code === 'ESRCH') return false;
- if ((err as NodeJS.ErrnoException).code === 'EPERM') return true;
- throw err;
- }
+function spawnLifelineTree(script: string): LifelineTree {
+ const proc = boundary.hold(
+ spawn('sh', ['-c', script], {
+ detached: true,
+ stdio: ['ignore', 'pipe', 'ignore', 'pipe'],
+ }),
+ );
+ trees.push(proc);
+ let output = '';
+ proc.stdout?.on('data', (chunk: Buffer) => {
+ output += chunk.toString('utf8');
+ });
+ return { proc, output: () => output };
}
-async function waitForChildPid(parentPid: number, timeoutMs = 5000): Promise<number> {
- const deadline = Date.now() + timeoutMs;
+function pidOf(proc: ChildProcess): number {
+ if (proc.pid === undefined) throw new Error('the tree was spawned without a pid');
+ return proc.pid;
+}
+
+async function awaitOutput(tree: LifelineTree, pattern: RegExp): Promise<RegExpExecArray> {
+ const deadline = Date.now() + DESCENDANT_REPORT_BOUND_MS;
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) {
- if ((err as NodeJS.ErrnoException).code === 'ENOENT') throw err;
- }
- await wait(50);
+ const match = pattern.exec(tree.output());
+ if (match !== null) return match;
+ await wait(25);
}
- throw new Error(`no child of ${parentPid} appeared within ${timeoutMs}ms`);
+ throw new Error(`the tree never printed ${pattern}; output so far: ${tree.output()}`);
}
-function spawnTree(): ChildProcess {
- const proc = spawn('sh', ['-c', 'sleep 300; true'], {
- detached: true,
- stdio: 'ignore',
- });
- spawned.push(proc);
- return proc;
+async function reportedDescendant(tree: LifelineTree): Promise<number> {
+ return Number((await awaitOutput(tree, /DESC=(\d+)/))[1]);
+}
+
+function isGroupMember(pid: number, pgid: number): boolean {
+ const res = spawnSync('ps', ['-o', 'pgid=,stat=', '-p', String(pid)], { encoding: 'utf8' });
+ const [group, stat] = (res.stdout ?? '').trim().split(/\s+/);
+ return Number(group) === pgid && stat !== undefined && !stat.startsWith('Z');
}
-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);
+async function until(predicate: () => boolean, boundMs: number): Promise<boolean> {
+ const deadline = Date.now() + boundMs;
+ while (!predicate()) {
+ if (Date.now() >= deadline) return false;
+ await wait(25);
+ }
+ return true;
+}
- await killGracefully(proc, 2_000);
+async function exited(proc: ChildProcess): Promise<void> {
+ if (proc.exitCode === null && proc.signalCode === null) await once(proc, 'exit');
+}
- expect(proc.exitCode !== null || proc.signalCode !== null).toBe(true);
- const deadline = Date.now() + 2_000;
- while (isAlive(childPid) && Date.now() < deadline) {
- await wait(25);
- }
- expect(isAlive(childPid)).toBe(false);
+function captureConsoleText(): () => string {
+ const lines: string[] = [];
+ const record = (...args: unknown[]) => {
+ lines.push(args.map((arg) => (arg instanceof Error ? arg.message : String(arg))).join(' '));
+ };
+ vi.spyOn(console, 'warn').mockImplementation(record);
+ vi.spyOn(console, 'error').mockImplementation(record);
+ return () => lines.join('\n');
+}
+
+async function settle(run: () => Promise<void>): Promise<string> {
+ try {
+ await run();
+ return '';
+ } catch (error) {
+ return error instanceof Error ? error.message : String(error);
+ }
+}
+
+function mentionsAny(text: string, pids: readonly number[]): boolean {
+ return pids.some((pid) => new RegExp(`(^|\\D)${pid}(\\D|$)`).test(text));
+}
+
+describe('killGracefully signals only a tree whose leader it still holds', () => {
+ test('stops a live tree through its group, then sends nothing once the leader has exited', async () => {
+ const tree = spawnLifelineTree(`${DESCENDANT} & wait`);
+ const leaderPid = pidOf(tree.proc);
+ const descendantPid = await reportedDescendant(tree);
+ expect(isGroupMember(descendantPid, leaderPid)).toBe(true);
+ expect(process.kill).toBe(boundary.send);
+
+ await killGracefully(tree.proc, GROUP_EXIT_BOUND_MS);
+
+ expect({
+ refused: boundary.refused,
+ leaderExited: tree.proc.exitCode !== null || tree.proc.signalCode !== null,
+ descendantGone: await until(
+ () => !isGroupMember(descendantPid, leaderPid),
+ DESCENDANT_EXIT_BOUND_MS,
+ ),
+ }).toEqual({ refused: [], leaderExited: true, descendantGone: true });
});
- test('sweeps surviving descendants when the direct child already exited', async () => {
- const proc = spawnTree();
- const parentPid = proc.pid as number;
- const childPid = await waitForChildPid(parentPid);
+ test('a descendant that outlives its already-exited leader is reaped or reported, never reached through the stale group id', async () => {
+ const tree = spawnLifelineTree(`${DESCENDANT} & wait`);
+ const leaderPid = pidOf(tree.proc);
+ const descendantPid = await reportedDescendant(tree);
+ tree.proc.kill('SIGKILL');
+ await exited(tree.proc);
+ expect(isGroupMember(descendantPid, leaderPid)).toBe(true);
+ const consoleText = captureConsoleText();
+ expect(process.kill).toBe(boundary.send);
- process.kill(parentPid, 'SIGKILL');
- await new Promise<void>((resolve) => proc.once('exit', () => resolve()));
- expect(isAlive(childPid)).toBe(true);
+ const failure = await settle(() => killGracefully(tree.proc, GROUP_EXIT_BOUND_MS));
- await killGracefully(proc, 2_000);
+ const reported = mentionsAny(`${consoleText()}\n${failure}`, [leaderPid, descendantPid]);
+ expect({
+ refused: boundary.refused,
+ descendantReapedOrReported:
+ reported ||
+ (await until(() => !isGroupMember(descendantPid, leaderPid), DESCENDANT_EXIT_BOUND_MS)),
+ }).toEqual({ refused: [], descendantReapedOrReported: true });
+ });
- const deadline = Date.now() + 2_000;
- while (isAlive(childPid) && Date.now() < deadline) {
- await wait(25);
- }
- expect(isAlive(childPid)).toBe(false);
+ test('a descendant that ignores SIGTERM and outlives the leader SIGTERM stopped is reaped or reported, never reached through the stale group id', async () => {
+ const tree = spawnLifelineTree(`${TERM_IGNORING_DESCENDANT} & wait`);
+ const leaderPid = pidOf(tree.proc);
+ const descendantPid = await reportedDescendant(tree);
+ expect(isGroupMember(descendantPid, leaderPid)).toBe(true);
+ const consoleText = captureConsoleText();
+ expect(process.kill).toBe(boundary.send);
+
+ const failure = await settle(() => killGracefully(tree.proc, GROUP_EXIT_BOUND_MS));
+
+ const reported = mentionsAny(`${consoleText()}\n${failure}`, [leaderPid, descendantPid]);
+ expect({
+ refused: boundary.refused,
+ leaderExited: tree.proc.exitCode !== null || tree.proc.signalCode !== null,
+ descendantReapedOrReported:
+ reported ||
+ (await until(() => !isGroupMember(descendantPid, leaderPid), DESCENDANT_EXIT_BOUND_MS)),
+ }).toEqual({ refused: [], leaderExited: true, descendantReapedOrReported: true });
});
- test('escalates to SIGKILL when the tree ignores SIGTERM', async () => {
- 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);
+ test('escalates to SIGKILL while the leader is still held when the tree ignores SIGTERM', async () => {
+ const tree = spawnLifelineTree('trap "" TERM; echo READY; while :; do sleep 1; done');
+ const leaderPid = pidOf(tree.proc);
+ await awaitOutput(tree, /READY/);
+ expect(process.kill).toBe(boundary.send);
- await killGracefully(proc, 300);
+ await killGracefully(tree.proc, 300);
- expect(proc.signalCode).toBe('SIGKILL');
- const pid = proc.pid as number;
- const deadline = Date.now() + 2_000;
+ expect(tree.proc.signalCode).toBe('SIGKILL');
let groupGone = false;
+ const deadline = Date.now() + GROUP_EXIT_BOUND_MS;
while (!groupGone && Date.now() < deadline) {
try {
- process.kill(-pid, 0);
+ process.kill(-leaderPid, 0);
} catch (err) {
- groupGone = (err as NodeJS.ErrnoException).code === 'ESRCH';
- if (!groupGone) throw err;
+ const code = (err as NodeJS.ErrnoException).code;
+ groupGone = code === 'ESRCH';
+ if (!groupGone && code !== 'EPERM') throw err;
}
if (!groupGone) await wait(25);
}
- expect(groupGone).toBe(true);
+ expect({ refused: boundary.refused, groupGone }).toEqual({ refused: [], groupGone: true });
+ });
+
+ test('sends nothing to the group of a tree that has fully exited', async () => {
+ const tree = spawnLifelineTree('exit 0');
+ await exited(tree.proc);
+ expect(process.kill).toBe(boundary.send);
+
+ await killGracefully(tree.proc, 500);
+
+ expect(boundary.refused).toEqual([]);
});
- 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()));
- await killGracefully(proc, 500);
+ test('reports no survivor when the leader exits on SIGTERM and its group drains', async () => {
+ const tree = spawnLifelineTree(`${DESCENDANT} & wait`);
+ const leaderPid = pidOf(tree.proc);
+ const descendantPid = await reportedDescendant(tree);
+ expect(isGroupMember(descendantPid, leaderPid)).toBe(true);
+ const consoleText = captureConsoleText();
+ expect(process.kill).toBe(boundary.send);
+
+ const failure = await settle(() => killGracefully(tree.proc, DESCENDANT_REPORT_BOUND_MS));
+
+ expect({
+ leaderStoppedBy: tree.proc.signalCode,
+ groupDrained: await until(
+ () => !isGroupMember(descendantPid, leaderPid),
+ DESCENDANT_EXIT_BOUND_MS,
+ ),
+ survivorReported: mentionsAny(`${consoleText()}\n${failure}`, [leaderPid, descendantPid]),
+ }).toEqual({ leaderStoppedBy: 'SIGTERM', groupDrained: true, survivorReported: false });
});
});
diff --git a/packages/app/tests/integration/producer-guard-wiring.test.ts b/packages/app/tests/integration/producer-guard-wiring.test.ts
index 867598d34..878d5196b 100644
--- a/packages/app/tests/integration/producer-guard-wiring.test.ts
+++ b/packages/app/tests/integration/producer-guard-wiring.test.ts
@@ -1,3 +1,4 @@
+
import { setTimeout as wait } from 'node:timers/promises';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
diff --git a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
index 0970ac12f..4ada3cf26 100644
--- a/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
+++ b/packages/app/tests/integration/qa-039-reconciliation-counters-http.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterEach, describe, expect, test } from 'vitest';
import { agentWriteMd, createTestServer, type TestServer } from './test-harness';
diff --git a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
index b632185e1..cbe2b705f 100644
--- a/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
+++ b/packages/app/tests/integration/qa-045-restore-after-gc.test.ts
@@ -1,3 +1,4 @@
+
import { execFileSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { join } from 'node:path';
diff --git a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
index c530ce4ba..89bc9b4d9 100644
--- a/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
+++ b/packages/app/tests/integration/qa-050-rollback-undo-shipped-path.test.ts
@@ -1,3 +1,4 @@
+
import { randomUUID } from 'node:crypto';
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
import type * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-after-rollback.test.ts b/packages/app/tests/integration/undo-after-rollback.test.ts
index d3767adc9..a78aeb0e4 100644
--- a/packages/app/tests/integration/undo-after-rollback.test.ts
+++ b/packages/app/tests/integration/undo-after-rollback.test.ts
@@ -1,3 +1,4 @@
+
import { ROLLBACK_ORIGIN } from '@inkeep/open-knowledge-server';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
diff --git a/packages/app/tests/integration/undo-recycle-reset.test.ts b/packages/app/tests/integration/undo-recycle-reset.test.ts
index b076f955c..e7cc69c3f 100644
--- a/packages/app/tests/integration/undo-recycle-reset.test.ts
+++ b/packages/app/tests/integration/undo-recycle-reset.test.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
diff --git a/packages/app/tests/integration/undo-rederive-survival.test.ts b/packages/app/tests/integration/undo-rederive-survival.test.ts
index 7935e35f8..9ddcd0730 100644
--- a/packages/app/tests/integration/undo-rederive-survival.test.ts
+++ b/packages/app/tests/integration/undo-rederive-survival.test.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter } from '@inkeep/open-knowledge-core';
import { Plugin, PluginKey } from '@tiptap/pm/state';
import { updateYFragment, yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
diff --git a/packages/app/tests/meta/worker-server-boot-verdict.test.ts b/packages/app/tests/meta/worker-server-boot-verdict.test.ts
index a4bbf1b9a..01887b712 100644
--- a/packages/app/tests/meta/worker-server-boot-verdict.test.ts
+++ b/packages/app/tests/meta/worker-server-boot-verdict.test.ts
@@ -44,6 +44,14 @@ interface VerdictRun {
bodiesRan: string[];
bootFailureInjected: boolean;
workersRefusingGroupSignals: string[];
+ groupSignalsOtherThanProbes: RefusedSignal[];
+}
+
+interface RefusedSignal {
+ caller?: number;
+ worker?: string;
+ pid: number;
+ signal?: string | number;
}
interface DeclaredResult {
@@ -134,6 +142,9 @@ async function runVerdictCases(cases: string[], retries: number): Promise<Verdic
}
const reportPath = join(runDir, 'results.json');
+ const workerGroupRefusals = linesOf(join(runDir, 'refused-signals.jsonl'))
+ .map((line) => JSON.parse(line) as RefusedSignal)
+ .filter((refusal) => refusal.pid < 0 && refusal.worker !== undefined);
return {
cases,
exitCode,
@@ -149,10 +160,10 @@ async function runVerdictCases(cases: string[], retries: number): Promise<Verdic
.map((entry) => entry.slice('body-ran.'.length))
.sort(),
bootFailureInjected: existsSync(join(runDir, 'boot-failure-injected')),
- workersRefusingGroupSignals: linesOf(join(runDir, 'refused-signals.jsonl')).flatMap((line) => {
- const refusal = JSON.parse(line) as { pid: number; worker?: string };
- return refusal.pid < 0 && refusal.worker !== undefined ? [refusal.worker] : [];
- }),
+ workersRefusingGroupSignals: workerGroupRefusals.flatMap((refusal) =>
+ refusal.worker === undefined ? [] : [refusal.worker],
+ ),
+ groupSignalsOtherThanProbes: workerGroupRefusals.filter((refusal) => refusal.signal !== 0),
};
}
@@ -224,8 +235,12 @@ function requireRefusedDevServerReaps(run: VerdictRun): void {
).not.toEqual([]);
expect(
run.workersRefusingGroupSignals,
- `verdict run [${run.cases.join(', ')}] ran its boot attempts in Playwright workers ${bootAttemptWorkers.join(', ')}, and each of them reaps its exited dev server by signalling that server's process group, so each must have recorded that signal as refused; a worker missing here reaped outside the refusal preload and could have signalled a real process group`,
+ `verdict run [${run.cases.join(', ')}] ran its boot attempts in Playwright workers ${bootAttemptWorkers.join(', ')}, and each of them reaps its exited dev server by probing that server's process group with signal 0, never signalling it, so each must have recorded that probe as refused; a worker missing here reaped outside the refusal preload and could have signalled a real process group`,
).toEqual(expect.arrayContaining(bootAttemptWorkers));
+ expect(
+ run.groupSignalsOtherThanProbes,
+ `verdict run [${run.cases.join(', ')}] reaps only dev servers whose leader has already exited, so every process-group call its workers made must be a signal-0 probe; any other signal was sent to a group whose leader teardown no longer held`,
+ ).toEqual([]);
}
const REPORTER_ERROR_MARKER = 'Error in reporter';
diff --git a/packages/app/tests/stress/_helpers/server-process.ts b/packages/app/tests/stress/_helpers/server-process.ts
index 77f69815b..7f760a51f 100644
--- a/packages/app/tests/stress/_helpers/server-process.ts
+++ b/packages/app/tests/stress/_helpers/server-process.ts
@@ -167,20 +167,32 @@ function tolerateDuringTeardown(err: unknown, attempt: string): false {
throw err;
}
-export function killGroup(pid: number, signal: NodeJS.Signals): boolean {
- if (!Number.isInteger(pid) || pid <= 1) return false;
+export function killGroup(proc: ChildProcess, signal: NodeJS.Signals): boolean {
+ if (proc.pid === undefined || !Number.isInteger(proc.pid) || proc.pid <= 1) return false;
+ if (proc.exitCode !== null || proc.signalCode !== null) return false;
try {
- process.kill(-pid, signal);
+ process.kill(-proc.pid, signal);
return true;
} catch (err) {
- return tolerateDuringTeardown(err, `kill(-${pid}, ${signal})`);
+ return tolerateDuringTeardown(err, `kill(-${proc.pid}, ${signal})`);
+ }
+}
+
+function groupStillHasMembers(pid: number): boolean {
+ try {
+ process.kill(-pid, 0);
+ return true;
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException).code;
+ if (code === 'ESRCH') return false;
+ if (code === 'EPERM') return true;
+ throw err;
}
}
export function signalTree(proc: ChildProcess, signal: NodeJS.Signals): boolean {
- const pid = proc.pid;
- if (pid === undefined) return false;
- if (killGroup(pid, signal)) return true;
+ if (proc.pid === undefined) return false;
+ if (killGroup(proc, signal)) return true;
let emitted: Error | undefined;
const capture = (err: Error) => {
@@ -197,18 +209,29 @@ export function signalTree(proc: ChildProcess, signal: NodeJS.Signals): boolean
return signalled;
}
+const GROUP_DRAIN_POLL_INTERVAL_MS = 25;
+
export async function killGracefully(proc: ChildProcess, timeoutMs = 5000): Promise<void> {
- if (proc.exitCode !== null || proc.signalCode !== null) {
- if (proc.pid !== undefined) killGroup(proc.pid, 'SIGKILL');
- return;
- }
- const exited = new Promise<void>((resolve) => proc.once('exit', () => resolve()));
- if (!signalTree(proc, 'SIGTERM')) return;
- await Promise.race([exited, wait(timeoutMs)]);
+ const deadline = Date.now() + timeoutMs;
if (proc.exitCode === null && proc.signalCode === null) {
- signalTree(proc, 'SIGKILL');
- await exited;
- } else if (proc.pid !== undefined) {
- killGroup(proc.pid, 'SIGKILL');
+ const exited = new Promise<void>((resolve) => proc.once('exit', () => resolve()));
+ if (!signalTree(proc, 'SIGTERM')) return;
+ await Promise.race([exited, wait(timeoutMs)]);
+ if (proc.exitCode === null && proc.signalCode === null) {
+ signalTree(proc, 'SIGKILL');
+ await exited;
+ return;
+ }
+ }
+ const pid = proc.pid;
+ if (pid === undefined) return;
+ while (groupStillHasMembers(pid)) {
+ if (Date.now() >= deadline) {
+ console.warn(
+ `[e2e teardown] leader ${pid} has exited but its process group still has members after ${timeoutMs}ms; not signalling a group whose leader this teardown no longer holds`,
+ );
+ return;
+ }
+ await wait(GROUP_DRAIN_POLL_INTERVAL_MS);
}
}
diff --git a/packages/cli/src/mcp/keepalive-orphan-reaping.test.ts b/packages/cli/src/mcp/keepalive-orphan-reaping.test.ts
index e6e0b30ef..b33332f18 100644
--- a/packages/cli/src/mcp/keepalive-orphan-reaping.test.ts
+++ b/packages/cli/src/mcp/keepalive-orphan-reaping.test.ts
@@ -21,13 +21,6 @@ function isAlive(pid: number): boolean {
}
}
-function killQuietly(pid: number | undefined): void {
- if (pid === undefined) return;
- try {
- process.kill(pid, 'SIGKILL');
- } catch {}
-}
-
function diagnoseStuckChild(childPid: number, errPath: string): string {
let ppid: string;
try {
@@ -94,7 +87,7 @@ describe('ok mcp orphan reaping (PRD-6917)', () => {
stdio: 'ignore',
});
keeper.unref();
- cleanups.push(() => killQuietly(keeper.pid));
+ cleanups.push(() => keeper.kill('SIGKILL'));
const parentScript = join(dir, 'parent.mjs');
writeFileSync(
@@ -122,7 +115,7 @@ describe('ok mcp orphan reaping (PRD-6917)', () => {
stdio: ['ignore', 'pipe', 'pipe'],
env: process.env,
});
- cleanups.push(() => killQuietly(parent.pid));
+ cleanups.push(() => parent.kill('SIGKILL'));
let stdoutBuf = '';
parent.stdout.on('data', (chunk) => {
@@ -132,7 +125,6 @@ describe('ok mcp orphan reaping (PRD-6917)', () => {
const match = stdoutBuf.match(/CHILDPID:(\d+)/);
expect(gotPid && match).toBeTruthy();
const childPid = Number(match?.[1]);
- cleanups.push(() => killQuietly(childPid));
const cameUp = await pollUntil(() => isAlive(childPid), STARTUP_BUDGET_MS, 100);
expect(
@@ -144,7 +136,7 @@ describe('ok mcp orphan reaping (PRD-6917)', () => {
const diedWhileParented = await pollUntil(() => !isAlive(childPid), 3_000, 250);
expect(diedWhileParented).toBe(false);
- killQuietly(parent.pid);
+ parent.kill('SIGKILL');
const exited = await pollUntil(() => !isAlive(childPid), EXIT_BUDGET_MS, 250);
expect(
diff --git a/packages/cli/tests/integration/detached-spawn-lifetime.test.ts b/packages/cli/tests/integration/detached-spawn-lifetime.test.ts
index 14cc0f7aa..0d7d157ed 100644
--- a/packages/cli/tests/integration/detached-spawn-lifetime.test.ts
+++ b/packages/cli/tests/integration/detached-spawn-lifetime.test.ts
@@ -78,8 +78,9 @@ server.listen(0, '127.0.0.1', () => {
writeFileSync(${JSON.stringify(stateFile)}, JSON.stringify({ pid: process.pid, port: addr.port }));
});
-// Idle for 30s (well past the test deadline). Tests SIGKILL us in cleanup.
await wait(30_000);
+server.close();
+process.exit(0);
`,
'utf-8',
);
@@ -126,22 +127,16 @@ setTimeout(() => process.exit(0), 300);
}
expect(state.pid).not.toBe(mcpPid);
- try {
- expect(isProcessAlive(state.pid)).toBe(true);
- const probe1 = await fetchTo(state.port);
- expect(probe1.status).toBe(200);
- expect(probe1.body).toBe(GRANDCHILD_MARKER);
-
- await wait(5_000);
-
- expect(isProcessAlive(state.pid)).toBe(true);
- const probe2 = await fetchTo(state.port);
- expect(probe2.status).toBe(200);
- expect(probe2.body).toBe(GRANDCHILD_MARKER);
- } finally {
- try {
- process.kill(state.pid, 'SIGKILL');
- } catch {}
- }
+ expect(isProcessAlive(state.pid)).toBe(true);
+ const probe1 = await fetchTo(state.port);
+ expect(probe1.status).toBe(200);
+ expect(probe1.body).toBe(GRANDCHILD_MARKER);
+
+ await wait(5_000);
+
+ expect(isProcessAlive(state.pid)).toBe(true);
+ const probe2 = await fetchTo(state.port);
+ expect(probe2.status).toBe(200);
+ expect(probe2.body).toBe(GRANDCHILD_MARKER);
}, 20_000);
});
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index fc267cbea..fb0ba5a7c 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/desktop/playwright.packaged.config.ts b/packages/desktop/playwright.packaged.config.ts
index 6845a9d0e..09a082fe6 100644
--- a/packages/desktop/playwright.packaged.config.ts
+++ b/packages/desktop/playwright.packaged.config.ts
@@ -20,6 +20,9 @@ import { ONE_LAUNCH_AND_ITS_READINESS_VERDICT_MS } from './tests/smoke/_helpers/
* here would fail on a perfectly good DMG.
*/
+/* WARN: desktopLaunchOptions sets OK_IDLE_SHUTDOWN to
+ PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS on every packaged launch, so a spec
+ added here must never leave its server without a /collab client that long. */
/**
* The FR5a subset: launch, project creation, and first-launch MCP wiring. This
* is the smallest set that proves a DMG boots, reaches the renderer, and can
diff --git a/packages/desktop/src/main/probe-spawn.test.ts b/packages/desktop/src/main/probe-spawn.test.ts
index 6d89ce130..9822f06a4 100644
--- a/packages/desktop/src/main/probe-spawn.test.ts
+++ b/packages/desktop/src/main/probe-spawn.test.ts
@@ -4,7 +4,16 @@ import { randomUUID } from 'node:crypto';
import { rmSync } from 'node:fs';
import { homedir } from 'node:os';
import { TERMINAL_CLI_IDS, TERMINAL_CLIS } from '@inkeep/open-knowledge-core';
-import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ afterAll,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ type MockInstance,
+ test,
+ vi,
+} from 'vitest';
import {
createScratchHomeWithOkBin,
firstShellOnDisk,
@@ -207,14 +216,27 @@ function onlySpawnedProbe(): { spawned: ChildProcess; pid: number } {
return { spawned, pid };
}
+function deliverOnlyToTheHeldProbeGroup(target: number, signal?: string | number): true {
+ const spawned: ChildProcess | undefined = spawnMock.mock.results.at(-1)?.value;
+ if (
+ spawned?.pid !== undefined &&
+ target === -spawned.pid &&
+ spawned.exitCode === null &&
+ spawned.signalCode === null
+ ) {
+ spawned.kill(signal as NodeJS.Signals | number | undefined);
+ }
+ return true;
+}
+
describe.skipIf(process.platform === 'win32')('realProbeSpawn detached group kill', () => {
test('signals the detached probe process group with SIGKILL while the probe is still alive', async () => {
- const groupKill = vi.spyOn(process, 'kill');
+ const groupKill = vi.spyOn(process, 'kill').mockImplementation(deliverOnlyToTheHeldProbeGroup);
spawnMock.mockClear();
probeLog.warn.mockClear();
const child = realProbeSpawn('/bin/sh', ['-c', 'sleep 5']);
+ const { spawned, pid } = onlySpawnedProbe();
try {
- const { pid } = onlySpawnedProbe();
const exited = new Promise<void>((resolve) => child.onExit(() => resolve()));
child.kill();
await exited;
@@ -226,7 +248,7 @@ describe.skipIf(process.platform === 'win32')('realProbeSpawn detached group kil
expect(probeLog.warn).not.toHaveBeenCalled();
} finally {
groupKill.mockRestore();
- child.kill();
+ if (spawned.exitCode === null && spawned.signalCode === null) child.kill();
}
});
@@ -234,24 +256,20 @@ describe.skipIf(process.platform === 'win32')('realProbeSpawn detached group kil
spawnMock.mockClear();
probeLog.warn.mockClear();
const child = realProbeSpawn('/bin/sh', ['-c', 'exit 0']);
+ let groupKill: MockInstance<typeof process.kill> | undefined;
try {
- const { spawned, pid } = onlySpawnedProbe();
+ const { spawned } = onlySpawnedProbe();
const childKill = vi.spyOn(spawned, 'kill');
await new Promise<void>((resolve) => child.onExit(() => resolve()));
- let groupGone = false;
- try {
- process.kill(-pid, 'SIGKILL');
- } catch (err) {
- groupGone = (err as NodeJS.ErrnoException).code === 'ESRCH';
- }
- expect(groupGone, 'precondition: the probe group is really gone before the pin runs').toBe(
- true,
- );
+ groupKill = vi.spyOn(process, 'kill').mockImplementation(() => {
+ throw Object.assign(new Error('kill ESRCH'), { code: 'ESRCH' });
+ });
child.kill();
expect(probeLog.warn).not.toHaveBeenCalled();
expect(childKill).not.toHaveBeenCalled();
} finally {
child.kill();
+ groupKill?.mockRestore();
}
});
@@ -324,7 +342,7 @@ describe('realProbeSpawn win32 spawn-site placement', () => {
test('keeps the kill on the child itself and off any process group when the stubbed platform is win32', () => {
withPlatform('win32', () => {
- const groupKill = vi.spyOn(process, 'kill');
+ const groupKill = vi.spyOn(process, 'kill').mockImplementation(() => true);
spawnMock.mockClear();
const child = realProbeSpawn('/bin/sh', ['-c', 'sleep 5']);
try {
@@ -408,7 +426,7 @@ describe.skipIf(process.platform === 'win32')('the production CLI-presence probe
test('terminates a hung probe through the production kill when the probe timer fires', async () => {
spawnMock.mockClear();
- const groupKill = vi.spyOn(process, 'kill');
+ const groupKill = vi.spyOn(process, 'kill').mockImplementation(deliverOnlyToTheHeldProbeGroup);
try {
const outcome = await runLoginShellProbe(realProbeSpawn, shell, realProbeTimers, 100, [
'-c',
diff --git a/packages/desktop/tests/integration/detached-lifecycle.test.ts b/packages/desktop/tests/integration/detached-lifecycle.test.ts
index 193797c63..a9bb6e200 100644
--- a/packages/desktop/tests/integration/detached-lifecycle.test.ts
+++ b/packages/desktop/tests/integration/detached-lifecycle.test.ts
@@ -93,9 +93,8 @@ describe('detached-server lifecycle integration', () => {
});
child.unref();
- let lock: ServerLockMetadata | null = null;
try {
- lock = await waitForLock(lockDir);
+ const lock = await waitForLock(lockDir);
expect(lock.port).toBeGreaterThan(0);
expect(lock.pid).toBe(child.pid as number);
@@ -112,12 +111,8 @@ describe('detached-server lifecycle integration', () => {
expect(pgid).not.toBe(myPgid);
}
} finally {
- if (lock !== null) {
- try {
- process.kill(lock.pid, 'SIGKILL');
- } catch {}
- await wait(200);
- }
+ child.kill('SIGKILL');
+ await wait(200);
}
}, 60_000);
@@ -164,7 +159,7 @@ describe('detached-server lifecycle integration', () => {
});
child.unref();
- process.kill(child.pid as number, 'SIGKILL');
+ child.kill('SIGKILL');
const deadline = Date.now() + 10_000;
while (exitRecord === null && Date.now() < deadline) {
@@ -204,7 +199,7 @@ describe('detached-server lifecycle integration', () => {
});
child.unref();
- if (killWith !== null) process.kill(child.pid as number, killWith);
+ if (killWith !== null) child.kill(killWith);
const recordPath = join(lockDir, SERVER_EXIT_LOG);
const deadline = Date.now() + 10_000;
diff --git a/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts b/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
index d67a30447..8e5cd6011 100644
--- a/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
+++ b/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
@@ -1,4 +1,5 @@
-import { spawn } from 'node:child_process';
+import { type ChildProcess, spawn } from 'node:child_process';
+import { once } from 'node:events';
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
@@ -47,7 +48,7 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
let notesDir: string;
let filePath: string;
let tempProjectDir: string;
- let serverPid: number | null = null;
+ let server: ChildProcess | null = null;
beforeEach(async () => {
userDir = await mkdtemp(resolve(tmpdir(), 'ok-ephemeral-it-'));
@@ -61,13 +62,11 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
});
afterEach(async () => {
- if (serverPid !== null && isProcessAlive(serverPid)) {
- try {
- process.kill(serverPid, 'SIGKILL');
- } catch {}
- await wait(200);
+ if (server !== null && server.exitCode === null && server.signalCode === null) {
+ server.kill('SIGKILL');
+ await once(server, 'exit');
}
- serverPid = null;
+ server = null;
await rm(userDir, { recursive: true, force: true });
await rm(tempProjectDir, { recursive: true, force: true });
});
@@ -102,8 +101,8 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
},
);
child.unref();
- serverPid = child.pid ?? null;
- expect(serverPid).not.toBeNull();
+ server = child;
+ expect(child.pid).toBeDefined();
const lockDir = join(tempProjectDir, '.ok', 'local');
const lock = await waitForLock(lockDir);
@@ -120,7 +119,7 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
const config = (await res.json()) as { singleFile?: boolean };
expect(config.singleFile).toBe(true);
- process.kill(lock.pid, 'SIGTERM');
+ child.kill('SIGTERM');
const releaseDeadline = Date.now() + LOCK_POLL_TIMEOUT_MS;
let released = false;
let exited = false;
@@ -133,7 +132,7 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
}
expect(released).toBe(true);
expect(exited).toBe(true);
- serverPid = null;
+ server = null;
await rm(tempProjectDir, { recursive: true, force: true });
expect(existsSync(tempProjectDir)).toBe(false);
diff --git a/packages/desktop/tests/integration/ok-bin-child-spawn-path.test.ts b/packages/desktop/tests/integration/ok-bin-child-spawn-path.test.ts
index 727103133..84982a19c 100644
--- a/packages/desktop/tests/integration/ok-bin-child-spawn-path.test.ts
+++ b/packages/desktop/tests/integration/ok-bin-child-spawn-path.test.ts
@@ -39,6 +39,7 @@ import {
findFreePort,
realSpawnSlidev,
type SlidevProcess,
+ signalSlidevChild,
} from '../../src/main/slidev-server.ts';
import { buildShellEnv } from '../../src/utility/pty-host.ts';
import {
@@ -308,22 +309,9 @@ function spawnDeck(
.map((line) => line.trim().split(/\s+/).map(Number))
.filter((row) => row.length === 3 && row[1] === shellPid);
const reap = () => {
- for (const [pid] of descendants()) {
- if (!isValidLockPid(pid)) {
- console.warn(
- `[spawnDeck] skipped a ps row under ppid ${shellPid}: pid column parsed to ${JSON.stringify(pid)}, which isValidLockPid rejects`,
- );
- continue;
- }
- try {
- process.kill(pid, 'SIGKILL');
- } catch {}
- }
- try {
- process.kill(-shellPid, 'SIGKILL');
- } catch {}
+ child.kill('SIGKILL');
};
- return { shellPid, descendants, reap };
+ return { child, shellPid, descendants, reap };
}
const FISH_SHELL_CANDIDATES = [
@@ -387,12 +375,18 @@ describe.skipIf(!existsSync('/bin/bash'))('Slidev launch process-group containme
timeout: 5_000,
});
const [deck] = shippedRun.descendants();
+ if (deck === undefined) throw new Error('the deck under the bash shell left the ps table');
expect(
- deck?.[2],
+ deck[2],
"bash turns job control on from -i alone and then setpgid()s the deck into its own group, where signalSlidevChild's process.kill(-pid) cannot reach it",
).toBe(shippedRun.shellPid);
- const deckPid = deck?.[0] ?? 0;
- process.kill(-shippedRun.shellPid, 'SIGKILL');
+ const deckPid = deck[0];
+ if (shippedRun.child.exitCode !== null || shippedRun.child.signalCode !== null) {
+ throw new Error(
+ 'the bash shell exited before the group kill, so its process group is no longer held',
+ );
+ }
+ await signalSlidevChild(shippedRun.child, 'SIGKILL');
await vi.waitFor(
() => {
expect(() => process.kill(deckPid, 0)).toThrow();
@@ -475,12 +469,18 @@ describe('Slidev launch process-group containment on fish', () => {
timeout: FISH_DECK_APPEAR_TIMEOUT_MS,
});
const [deck] = shippedRun.descendants();
+ if (deck === undefined) throw new Error(`the deck under ${fish} left the ps table`);
expect(
- deck?.[2],
+ deck[2],
`a config.fish carrying 'status job-control full' survives into ${fish} -i -c, where it setpgid()s the deck into its own group and signalSlidevChild's process.kill(-pid) cannot reach it, so the opt-out has to land after startup files rather than in the env layer`,
).toBe(shippedRun.shellPid);
- const deckPid = deck?.[0] ?? 0;
- process.kill(-shippedRun.shellPid, 'SIGKILL');
+ const deckPid = deck[0];
+ if (shippedRun.child.exitCode !== null || shippedRun.child.signalCode !== null) {
+ throw new Error(
+ `${fish} exited before the group kill, so its process group is no longer held`,
+ );
+ }
+ await signalSlidevChild(shippedRun.child, 'SIGKILL');
await vi.waitFor(
() => {
expect(() => process.kill(deckPid, 0)).toThrow();
diff --git a/packages/desktop/tests/smoke/_helpers/electron-cleanup.reap-servers.test.ts b/packages/desktop/tests/smoke/_helpers/electron-cleanup.reap-servers.test.ts
new file mode 100644
index 000000000..3f9fa0bc8
--- /dev/null
+++ b/packages/desktop/tests/smoke/_helpers/electron-cleanup.reap-servers.test.ts
@@ -0,0 +1,472 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ installSignalBoundary,
+ type SignalBoundary,
+} from '../../../../../test-support/held-signal-boundary.test-helper';
+import { DETACHED_SERVER_RELEASE_BOUND_MS, reapDetachedServers } from './electron-cleanup';
+
+const PID_BEYOND_ANY_KERNEL_LIMIT = 4_194_319;
+const SECOND_PID_BEYOND_ANY_KERNEL_LIMIT = 4_194_337;
+const STAND_IN_LIFETIME_MS = 5_000;
+const LOCK_READY_BOUND_MS = 20_000;
+const REAP_LIVENESS_BOUND_MS = 120_000;
+
+const STAND_IN_SERVER = [
+ "const fs = require('node:fs');",
+ "const path = require('node:path');",
+ 'const [lockPath, logPath, lifetimeMs] = process.argv.slice(1);',
+ 'fs.mkdirSync(path.dirname(lockPath), { recursive: true });',
+ "fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, hostname: 'stand-in', kind: 'interactive', port: 0, startedAt: new Date().toISOString() }));",
+ 'const release = (line) => {',
+ " fs.appendFileSync(logPath, line + '\\n');",
+ ' try { fs.unlinkSync(lockPath); } catch {}',
+ ' process.exit(0);',
+ '};',
+ "for (const name of ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR1', 'SIGUSR2']) process.on(name, () => release('signal:' + name));",
+ "setTimeout(() => release('released'), Number(lifetimeMs));",
+].join('\n');
+
+const LIFELINE_STAND_IN_SERVER = [
+ "const fs = require('node:fs');",
+ "const path = require('node:path');",
+ 'const [lockPath, logPath] = process.argv.slice(1);',
+ 'fs.mkdirSync(path.dirname(lockPath), { recursive: true });',
+ "fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, hostname: 'stand-in', kind: 'interactive', port: 0, startedAt: new Date().toISOString() }));",
+ 'const release = (line) => {',
+ " try { fs.appendFileSync(logPath, line + '\\n'); } catch {}",
+ " try { if (JSON.parse(fs.readFileSync(lockPath, 'utf8')).pid === process.pid) fs.unlinkSync(lockPath); } catch {}",
+ ' process.exit(0);',
+ '};',
+ "for (const name of ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR1', 'SIGUSR2']) process.on(name, () => release('signal:' + name));",
+ "process.stdin.on('end', () => release('lifeline-closed'));",
+ 'process.stdin.resume();',
+].join('\n');
+
+let root: string;
+let boundary: SignalBoundary;
+let standIns: ChildProcess[];
+
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'ok-reap-servers-'));
+ standIns = [];
+ boundary = installSignalBoundary({ deliverToHeldChildren: false });
+});
+
+afterEach(async () => {
+ boundary.restore();
+ vi.restoreAllMocks();
+ for (const standIn of standIns) {
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+ }
+ rmSync(root, { recursive: true, force: true });
+});
+
+function seedLock(dir: string, lock: Record<string, unknown>): string {
+ const local = join(dir, '.ok', 'local');
+ mkdirSync(local, { recursive: true });
+ const lockPath = join(local, 'server.lock');
+ writeFileSync(lockPath, JSON.stringify(lock));
+ return lockPath;
+}
+
+function settle(run: () => unknown): Promise<{ value: unknown; error: unknown }> {
+ return Promise.resolve()
+ .then(run)
+ .then(
+ (value) => ({ value, error: undefined }),
+ (error: unknown) => ({ value: undefined, error }),
+ );
+}
+
+function spawnStandIn(lockPath: string, logPath: string): ChildProcess {
+ const standIn = spawn(
+ process.execPath,
+ ['-e', STAND_IN_SERVER, lockPath, logPath, String(STAND_IN_LIFETIME_MS)],
+ { stdio: 'ignore' },
+ );
+ standIns.push(standIn);
+ return standIn;
+}
+
+async function waitForLockNaming(lockPath: string, pid: number): Promise<void> {
+ const deadline = Date.now() + LOCK_READY_BOUND_MS;
+ while (Date.now() < deadline) {
+ if (existsSync(lockPath)) {
+ try {
+ if ((JSON.parse(readFileSync(lockPath, 'utf8')) as { pid?: unknown }).pid === pid) return;
+ } catch {}
+ }
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ }
+ throw new Error(`the stand-in server never wrote a lock naming pid ${pid} at ${lockPath}`);
+}
+
+function logLines(logPath: string): string[] {
+ if (!existsSync(logPath)) return [];
+ return readFileSync(logPath, 'utf8').split('\n').filter(Boolean);
+}
+
+function captureConsoleText(): () => string[] {
+ const lines: string[] = [];
+ const record = (...args: unknown[]) => {
+ lines.push(args.map((arg) => (arg instanceof Error ? arg.message : String(arg))).join(' '));
+ };
+ vi.spyOn(console, 'warn').mockImplementation(record);
+ vi.spyOn(console, 'error').mockImplementation(record);
+ vi.spyOn(console, 'log').mockImplementation(record);
+ return () => lines;
+}
+
+function describeOutcome(outcome: { value: unknown; error: unknown }): string {
+ if (outcome.error !== undefined) {
+ return outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+ }
+ return outcome.value === undefined ? '' : JSON.stringify(outcome.value);
+}
+
+describe('reapDetachedServers — signals only what it holds', () => {
+ test(
+ 'a server.lock naming a process this code never spawned draws no signal, at every depth the reaper searches',
+ async () => {
+ seedLock(root, {
+ pid: PID_BEYOND_ANY_KERNEL_LIMIT,
+ hostname: 'a-different-host.example',
+ startedAt: '2001-01-01T00:00:00.000Z',
+ kind: 'interactive',
+ port: 1,
+ });
+ seedLock(join(root, 'a', 'b', 'c'), { pid: SECOND_PID_BEYOND_ANY_KERNEL_LIMIT });
+ expect(process.kill).toBe(boundary.send);
+
+ await settle(() => reapDetachedServers([root]));
+
+ expect(boundary.refused).toEqual([]);
+ },
+ REAP_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ 'a live process named by a server.lock is neither signalled nor assumed stopped: it stops on its own or the reaper reports it',
+ async () => {
+ const lockPath = join(root, '.ok', 'local', 'server.lock');
+ const logPath = join(root, 'stand-in.log');
+ const standIn = spawnStandIn(lockPath, logPath);
+ if (standIn.pid === undefined) await once(standIn, 'spawn');
+ const standInPid = standIn.pid;
+ if (standInPid === undefined) throw new Error('the stand-in server never received a pid');
+ await waitForLockNaming(lockPath, standInPid);
+ expect(standIn.exitCode === null && standIn.signalCode === null).toBe(true);
+ const consoleText = captureConsoleText();
+ expect(process.kill).toBe(boundary.send);
+
+ const outcome = await settle(() => reapDetachedServers([root]));
+
+ const standInLogAtReturn = logLines(logPath);
+ const exitedAtReturn = standIn.exitCode !== null || standIn.signalCode !== null;
+ const reportText = [...consoleText(), describeOutcome(outcome)].join('\n');
+ const reported = reportText.includes(String(standInPid)) || reportText.includes(lockPath);
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: [
+ ...logLines(logPath).filter((line) => line.startsWith('signal:')),
+ ...(standIn.signalCode === null ? [] : [`signal:${standIn.signalCode}`]),
+ ],
+ stoppedOnItsOwnOrReported:
+ standInLogAtReturn.includes('released') || exitedAtReturn || reported,
+ }).toEqual({
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ stoppedOnItsOwnOrReported: true,
+ });
+ },
+ REAP_LIVENESS_BOUND_MS,
+ );
+});
+
+function captureWarnings(): () => string[] {
+ const lines: string[] = [];
+ vi.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+ lines.push(args.map((arg) => (arg instanceof Error ? arg.message : String(arg))).join(' '));
+ });
+ return () => lines;
+}
+
+function mentionsPid(text: string, pid: number): boolean {
+ return new RegExp(`(^|\\D)${pid}(\\D|$)`).test(text);
+}
+
+function probeErrorCode(pid: number): string | undefined {
+ try {
+ process.kill(pid, 0);
+ return undefined;
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code;
+ }
+}
+
+describe('reapDetachedServers — reports what outlives the release bound, never signals it', () => {
+ const lifelines: ChildProcess[] = [];
+
+ afterEach(async () => {
+ for (const standIn of lifelines) {
+ standIn.stdin?.end();
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+ }
+ lifelines.length = 0;
+ });
+
+ function spawnLifelineStandIn(lockPath: string, logPath: string): ChildProcess {
+ const standIn = spawn(process.execPath, ['-e', LIFELINE_STAND_IN_SERVER, lockPath, logPath], {
+ stdio: ['pipe', 'ignore', 'ignore'],
+ });
+ lifelines.push(standIn);
+ return standIn;
+ }
+
+ async function startLifelineStandIn(): Promise<{
+ standIn: ChildProcess;
+ standInPid: number;
+ lockPath: string;
+ logPath: string;
+ }> {
+ const lockPath = join(root, '.ok', 'local', 'server.lock');
+ const logPath = join(root, 'stand-in.log');
+ const standIn = spawnLifelineStandIn(lockPath, logPath);
+ if (standIn.pid === undefined) await once(standIn, 'spawn');
+ const standInPid = standIn.pid;
+ if (standInPid === undefined) throw new Error('the stand-in server never received a pid');
+ await waitForLockNaming(lockPath, standInPid);
+ return { standIn, standInPid, lockPath, logPath };
+ }
+
+ function signalsThatReached(standIn: ChildProcess, logPath: string): string[] {
+ return [
+ ...logLines(logPath).filter((line) => line.startsWith('signal:')),
+ ...(standIn.signalCode === null ? [] : [`signal:${standIn.signalCode}`]),
+ ];
+ }
+
+ test(
+ 'a server.lock whose pid a probe reports as not running is stale: the reaper returns no survivor for it and warns nothing about it',
+ async () => {
+ const staleLockPaths = [
+ seedLock(root, { pid: PID_BEYOND_ANY_KERNEL_LIMIT }),
+ seedLock(join(root, 'a', 'b', 'c'), { pid: SECOND_PID_BEYOND_ANY_KERNEL_LIMIT }),
+ ];
+ const warnings = captureWarnings();
+ expect(process.kill).toBe(boundary.send);
+
+ const survivors = await reapDetachedServers([root]);
+
+ expect({
+ probes: [PID_BEYOND_ANY_KERNEL_LIMIT, SECOND_PID_BEYOND_ANY_KERNEL_LIMIT].map(
+ probeErrorCode,
+ ),
+ survivors,
+ warningsNamingAStaleLock: warnings().filter(
+ (line) =>
+ staleLockPaths.some((lockPath) => line.includes(lockPath)) ||
+ mentionsPid(line, PID_BEYOND_ANY_KERNEL_LIMIT) ||
+ mentionsPid(line, SECOND_PID_BEYOND_ANY_KERNEL_LIMIT),
+ ),
+ refused: boundary.refused,
+ }).toEqual({
+ probes: ['ESRCH', 'ESRCH'],
+ survivors: [],
+ warningsNamingAStaleLock: [],
+ refused: [],
+ });
+ },
+ REAP_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ 'a live server that outlives the release bound is returned and warned with its pid and exact lock path, and is never signalled',
+ async () => {
+ const lockPath = join(root, '.ok', 'local', 'server.lock');
+ const logPath = join(root, 'stand-in.log');
+ const staleLockPath = seedLock(join(root, 'stale-project'), {
+ pid: PID_BEYOND_ANY_KERNEL_LIMIT,
+ });
+ const standIn = spawnLifelineStandIn(lockPath, logPath);
+ if (standIn.pid === undefined) await once(standIn, 'spawn');
+ const standInPid = standIn.pid;
+ if (standInPid === undefined) throw new Error('the stand-in server never received a pid');
+ await waitForLockNaming(lockPath, standInPid);
+ const warnings = captureWarnings();
+ expect(process.kill).toBe(boundary.send);
+
+ let survivors: unknown;
+ let aliveWhenTheReaperReturned = false;
+ try {
+ survivors = await reapDetachedServers([root]);
+ aliveWhenTheReaperReturned = standIn.exitCode === null && standIn.signalCode === null;
+ } finally {
+ standIn.stdin?.end();
+ }
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ releaseBoundIsExported: typeof DETACHED_SERVER_RELEASE_BOUND_MS === 'number',
+ aliveWhenTheReaperReturned,
+ survivors,
+ warnedWithPidAndLockPath: warnings().some(
+ (line) => line.includes(lockPath) && mentionsPid(line, standInPid),
+ ),
+ staleLockReported: warnings().some(
+ (line) => line.includes(staleLockPath) || mentionsPid(line, PID_BEYOND_ANY_KERNEL_LIMIT),
+ ),
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: [
+ ...logLines(logPath).filter((line) => line.startsWith('signal:')),
+ ...(standIn.signalCode === null ? [] : [`signal:${standIn.signalCode}`]),
+ ],
+ }).toEqual({
+ releaseBoundIsExported: true,
+ aliveWhenTheReaperReturned: true,
+ survivors: [{ lockPath, pid: standInPid }],
+ warnedWithPidAndLockPath: true,
+ staleLockReported: false,
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ REAP_LIVENESS_BOUND_MS + DETACHED_SERVER_RELEASE_BOUND_MS,
+ );
+
+ test.each<[string, (lockText: string) => string]>([
+ ['empty', () => ''],
+ ['short of its last byte', (lockText) => lockText.slice(0, -1)],
+ ])(
+ 'a live server whose lock reads %s mid-rewrite after the reaper collected it is still returned and warned as a survivor, and is never signalled',
+ async (_torn, tear) => {
+ const { standIn, standInPid, lockPath, logPath } = await startLifelineStandIn();
+ const tornText = tear(readFileSync(lockPath, 'utf8'));
+ const warnings = captureWarnings();
+ expect(process.kill).toBe(boundary.send);
+
+ let survivors: unknown;
+ let probedBeforeTheTear = false;
+ let lockTextWhenTheReaperReturned: string | undefined;
+ let aliveWhenTheReaperReturned = false;
+ try {
+ const reaping = reapDetachedServers([root]);
+ probedBeforeTheTear = boundary.probes.some((probe) => probe.target === standInPid);
+ writeFileSync(lockPath, tornText);
+ survivors = await reaping;
+ lockTextWhenTheReaperReturned = readFileSync(lockPath, 'utf8');
+ aliveWhenTheReaperReturned = standIn.exitCode === null && standIn.signalCode === null;
+ } finally {
+ standIn.stdin?.end();
+ }
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ probedBeforeTheTear,
+ lockTextWhenTheReaperReturned,
+ aliveWhenTheReaperReturned,
+ survivors,
+ warnedWithPidAndLockPath: warnings().some(
+ (line) => line.includes(lockPath) && mentionsPid(line, standInPid),
+ ),
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ probedBeforeTheTear: true,
+ lockTextWhenTheReaperReturned: tornText,
+ aliveWhenTheReaperReturned: true,
+ survivors: [{ lockPath, pid: standInPid }],
+ warnedWithPidAndLockPath: true,
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ REAP_LIVENESS_BOUND_MS + DETACHED_SERVER_RELEASE_BOUND_MS,
+ );
+
+ test(
+ 'a lock that a server left torn when it exited is dropped once the probe finds no process: no survivor and no warning, though the lock stays on disk',
+ async () => {
+ const { standIn, standInPid, lockPath, logPath } = await startLifelineStandIn();
+ const warnings = captureWarnings();
+ expect(process.kill).toBe(boundary.send);
+
+ let survivors: unknown;
+ try {
+ const reaping = reapDetachedServers([root]);
+ writeFileSync(lockPath, '');
+ standIn.stdin?.end();
+ survivors = await reaping;
+ } finally {
+ standIn.stdin?.end();
+ }
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ standInLog: logLines(logPath),
+ lockLeftOnDisk: existsSync(lockPath),
+ survivors,
+ warningsNamingTheLock: warnings().filter(
+ (line) => line.includes(lockPath) || mentionsPid(line, standInPid),
+ ),
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ standInLog: ['lifeline-closed'],
+ lockLeftOnDisk: true,
+ survivors: [],
+ warningsNamingTheLock: [],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ REAP_LIVENESS_BOUND_MS + DETACHED_SERVER_RELEASE_BOUND_MS,
+ );
+
+ test(
+ 'a lock that reads empty mid-rewrite at the instant the reaper collects is still kept, and the live server it names once readable is returned and warned as a survivor, and never signalled',
+ async () => {
+ const { standIn, standInPid, lockPath, logPath } = await startLifelineStandIn();
+ const lockText = readFileSync(lockPath, 'utf8');
+ const warnings = captureWarnings();
+ expect(process.kill).toBe(boundary.send);
+
+ let survivors: unknown;
+ let aliveWhenTheReaperReturned = false;
+ try {
+ writeFileSync(lockPath, '');
+ const reaping = reapDetachedServers([root]);
+ writeFileSync(lockPath, lockText);
+ survivors = await reaping;
+ aliveWhenTheReaperReturned = standIn.exitCode === null && standIn.signalCode === null;
+ } finally {
+ standIn.stdin?.end();
+ }
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ aliveWhenTheReaperReturned,
+ survivors,
+ warnedWithPidAndLockPath: warnings().some(
+ (line) => line.includes(lockPath) && mentionsPid(line, standInPid),
+ ),
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ aliveWhenTheReaperReturned: true,
+ survivors: [{ lockPath, pid: standInPid }],
+ warnedWithPidAndLockPath: true,
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ REAP_LIVENESS_BOUND_MS + DETACHED_SERVER_RELEASE_BOUND_MS,
+ );
+});
diff --git a/packages/desktop/tests/smoke/_helpers/electron-cleanup.settle.test.ts b/packages/desktop/tests/smoke/_helpers/electron-cleanup.settle.test.ts
new file mode 100644
index 000000000..c4f5ba60f
--- /dev/null
+++ b/packages/desktop/tests/smoke/_helpers/electron-cleanup.settle.test.ts
@@ -0,0 +1,679 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { EventEmitter, once } from 'node:events';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ installSignalBoundary,
+ type SignalBoundary,
+} from '../../../../../test-support/held-signal-boundary.test-helper';
+import {
+ AppCleanupIncompleteError,
+ type CloseAppBoundedOpts,
+ cleanupIncompleteReport,
+ closeAppBounded,
+ closeAppsThenAwaitServerRelease,
+ type ServerLockRecord,
+ SMOKE_SERVER_RELEASE_WINDOW_MS,
+} from './electron-cleanup';
+import { PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS } from './launch-desktop';
+
+const APP_PID = 4_194_327;
+const GRACEFUL_MS = 50;
+const REAP_MS = 250;
+const SURVIVOR_WINDOW_MS = 400;
+const STAND_IN_RELEASE_LIVENESS_BOUND_MS = 20_000;
+const LOCK_READY_BOUND_MS = 20_000;
+const WATCH_LIVENESS_BOUND_MS = 20_000;
+const WATCH_INTERVAL_MS = 10;
+const ROW_LIVENESS_BOUND_MS = 120_000;
+
+const STAND_IN_SERVER = [
+ "const fs = require('node:fs');",
+ "const path = require('node:path');",
+ 'const [lockPath, logPath] = process.argv.slice(1);',
+ 'fs.mkdirSync(path.dirname(lockPath), { recursive: true });',
+ "fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, hostname: 'stand-in', kind: 'interactive', port: 0, startedAt: new Date().toISOString() }));",
+ 'const exitLeavingTheLock = (line) => {',
+ " try { fs.appendFileSync(logPath, line + '\\n'); } catch {}",
+ ' process.exit(0);',
+ '};',
+ "for (const name of ['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR1', 'SIGUSR2']) process.on(name, () => exitLeavingTheLock('signal:' + name));",
+ "process.stdin.on('end', () => exitLeavingTheLock('lifeline-closed'));",
+ 'process.stdin.resume();',
+].join('\n');
+
+type CloseAndAwaitOutcome = Awaited<ReturnType<typeof closeAppsThenAwaitServerRelease>>;
+
+type GroupKill = NonNullable<CloseAppBoundedOpts['kill']>;
+
+interface AppDouble extends EventEmitter {
+ pid: number;
+ exitCode: number | null;
+ signalCode: NodeJS.Signals | null;
+ stdio: { destroyed: boolean }[];
+ closeEmitted: boolean;
+}
+
+function appHasExited(app: AppDouble): boolean {
+ return app.exitCode !== null || app.signalCode !== null;
+}
+
+function closeOnceStdioIsShut(app: AppDouble): void {
+ if (app.closeEmitted || !appHasExited(app)) return;
+ if (app.stdio.some((slot) => !slot.destroyed)) return;
+ app.closeEmitted = true;
+ app.emit('close', app.exitCode, app.signalCode);
+}
+
+function appDouble(stdio: 'held-by-its-server' | 'its-own'): AppDouble {
+ const app = new EventEmitter() as AppDouble;
+ app.pid = APP_PID;
+ app.exitCode = null;
+ app.signalCode = null;
+ app.closeEmitted = false;
+ app.stdio =
+ stdio === 'held-by-its-server'
+ ? [{ destroyed: false }, { destroyed: false }, { destroyed: false }]
+ : [];
+ return app;
+}
+
+function releaseStdio(app: AppDouble): void {
+ for (const slot of app.stdio) slot.destroyed = true;
+ closeOnceStdioIsShut(app);
+}
+
+interface RecordedGroupKill {
+ target: number;
+ signal: NodeJS.Signals | string;
+ whileHeld: boolean;
+}
+
+function groupKillRecorder(app: AppDouble): { sent: RecordedGroupKill[]; kill: GroupKill } {
+ const sent: RecordedGroupKill[] = [];
+ const kill: GroupKill = (target, signal) => {
+ const whileHeld = !appHasExited(app);
+ sent.push({ target, signal, whileHeld });
+ if (!whileHeld) return;
+ app.signalCode = signal as NodeJS.Signals;
+ app.emit('exit', null, signal);
+ closeOnceStdioIsShut(app);
+ };
+ return { sent, kill };
+}
+
+let root: string;
+let boundary: SignalBoundary;
+let standIns: ChildProcess[];
+
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'ok-settle-servers-'));
+ standIns = [];
+ boundary = installSignalBoundary({ deliverToHeldChildren: false });
+});
+
+afterEach(async () => {
+ boundary.restore();
+ vi.restoreAllMocks();
+ for (const standIn of standIns) {
+ standIn.stdin?.end();
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+ }
+ rmSync(root, { recursive: true, force: true });
+});
+
+async function waitForLockNaming(lockPath: string, pid: number): Promise<void> {
+ const deadline = Date.now() + LOCK_READY_BOUND_MS;
+ while (Date.now() < deadline) {
+ if (existsSync(lockPath)) {
+ try {
+ if ((JSON.parse(readFileSync(lockPath, 'utf8')) as { pid?: unknown }).pid === pid) return;
+ } catch {}
+ }
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ }
+ throw new Error(`the stand-in server never wrote a lock naming pid ${pid} at ${lockPath}`);
+}
+
+async function startStandInServer(): Promise<{
+ standIn: ChildProcess;
+ pid: number;
+ lockPath: string;
+ logPath: string;
+}> {
+ const lockPath = join(root, '.ok', 'local', 'server.lock');
+ const logPath = join(root, 'stand-in.log');
+ const standIn = spawn(process.execPath, ['-e', STAND_IN_SERVER, lockPath, logPath], {
+ stdio: ['pipe', 'ignore', 'ignore'],
+ });
+ standIns.push(standIn);
+ if (standIn.pid === undefined) await once(standIn, 'spawn');
+ const pid = standIn.pid;
+ if (pid === undefined) throw new Error('the stand-in server never received a pid');
+ await waitForLockNaming(lockPath, pid);
+ return { standIn, pid, lockPath, logPath };
+}
+
+function signalsThatReached(standIn: ChildProcess, logPath: string): string[] {
+ const logged = existsSync(logPath)
+ ? readFileSync(logPath, 'utf8')
+ .split('\n')
+ .filter((line) => line.startsWith('signal:'))
+ : [];
+ return [...logged, ...(standIn.signalCode === null ? [] : [`signal:${standIn.signalCode}`])];
+}
+
+function probedSince(from: number | undefined, pid: number): boolean {
+ return from !== undefined && boundary.probes.slice(from).some((probe) => probe.target === pid);
+}
+
+async function watchFor(condition: () => boolean, stopWatching: () => boolean): Promise<boolean> {
+ const deadline = Date.now() + WATCH_LIVENESS_BOUND_MS;
+ while (!condition()) {
+ if (stopWatching() || Date.now() >= deadline) return false;
+ await new Promise((resolve) => setTimeout(resolve, WATCH_INTERVAL_MS));
+ }
+ return true;
+}
+
+function whatTheCallReturned(outcome: { value: unknown; error: unknown }): unknown {
+ if (outcome.error !== undefined) {
+ return {
+ threw: outcome.error instanceof Error ? outcome.error.message : String(outcome.error),
+ };
+ }
+ const value = outcome.value as Partial<CloseAndAwaitOutcome> | undefined;
+ return {
+ unclosed: value?.unclosed,
+ survivors: value?.survivors,
+ closedAfterServerRelease: value?.closedAfterServerRelease,
+ };
+}
+
+function track(
+ run: () => Promise<CloseAndAwaitOutcome>,
+ sequence: string[],
+): { settled: Promise<{ value: unknown; error: unknown }>; hasReturned: () => boolean } {
+ let returned = false;
+ const settled = Promise.resolve()
+ .then(run)
+ .then(
+ (value) => ({ value, error: undefined }),
+ (error: unknown) => ({ value: undefined, error }),
+ )
+ .then((outcome) => {
+ returned = true;
+ sequence.push('call returned');
+ return outcome;
+ });
+ return { settled, hasReturned: () => returned };
+}
+
+function observeApp(app: AppDouble, sequence: string[]): () => number | undefined {
+ let probesWhenTheAppExited: number | undefined;
+ app.once('exit', () => {
+ probesWhenTheAppExited = boundary.probes.length;
+ sequence.push('app exited');
+ });
+ app.once('close', () => {
+ sequence.push('app closed');
+ });
+ return () => probesWhenTheAppExited;
+}
+
+describe('closeAppsThenAwaitServerRelease — closes the apps, waits for the servers under their dirs to release, then looks once more for each close', () => {
+ test(
+ "an app whose close can only follow its server's exit is closed once that server releases inside the window, and is not reported",
+ async () => {
+ expect(typeof closeAppsThenAwaitServerRelease).toBe('function');
+ const { standIn, pid, logPath } = await startStandInServer();
+ const app = appDouble('held-by-its-server');
+ const sequence: string[] = [];
+ const probesWhenTheAppExited = observeApp(app, sequence);
+ standIn.once('exit', () => {
+ sequence.push('server exited');
+ releaseStdio(app);
+ });
+ const { sent, kill } = groupKillRecorder(app);
+ expect(process.kill).toBe(boundary.send);
+
+ const { settled, hasReturned } = track(
+ () =>
+ closeAppsThenAwaitServerRelease([app as unknown as ChildProcess], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: STAND_IN_RELEASE_LIVENESS_BOUND_MS,
+ kill,
+ platform: 'linux',
+ }),
+ sequence,
+ );
+ let reaperWatchedTheLiveServerAfterTheAppDied = false;
+ try {
+ reaperWatchedTheLiveServerAfterTheAppDied = await watchFor(
+ () => probedSince(probesWhenTheAppExited(), pid),
+ hasReturned,
+ );
+ } finally {
+ standIn.stdin?.end();
+ }
+ const outcome = await settled;
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ reaperWatchedTheLiveServerAfterTheAppDied,
+ returned: whatTheCallReturned(outcome),
+ sequence,
+ groupKills: sent,
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ reaperWatchedTheLiveServerAfterTheAppDied: true,
+ returned: { unclosed: [], survivors: [], closedAfterServerRelease: [APP_PID] },
+ sequence: ['app exited', 'server exited', 'app closed', 'call returned'],
+ groupKills: [{ target: -APP_PID, signal: 'SIGKILL', whileHeld: true }],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ ROW_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ "a server that outlives the window is reported as a survivor and never signalled, and its app's unclosed failure is the one the first close attempt raised",
+ async () => {
+ expect(typeof closeAppsThenAwaitServerRelease).toBe('function');
+ const { standIn, pid, lockPath, logPath } = await startStandInServer();
+ const app = appDouble('held-by-its-server');
+ const sequence: string[] = [];
+ observeApp(app, sequence);
+ standIn.once('exit', () => {
+ sequence.push('server exited');
+ releaseStdio(app);
+ });
+ const { sent, kill } = groupKillRecorder(app);
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ expect(process.kill).toBe(boundary.send);
+
+ let outcome: { value: unknown; error: unknown };
+ let sequenceWhenTheCallReturned: string[];
+ let serverAliveWhenTheCallReturned: boolean;
+ let firstPassFailure: unknown;
+ try {
+ outcome = await track(
+ () =>
+ closeAppsThenAwaitServerRelease([app as unknown as ChildProcess], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: SURVIVOR_WINDOW_MS,
+ kill,
+ platform: 'linux',
+ }),
+ sequence,
+ ).settled;
+ sequenceWhenTheCallReturned = [...sequence];
+ serverAliveWhenTheCallReturned = standIn.exitCode === null && standIn.signalCode === null;
+ firstPassFailure = await closeAppBounded(app as unknown as ChildProcess, {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).then(
+ () => undefined,
+ (error: unknown) => error,
+ );
+ } finally {
+ standIn.stdin?.end();
+ }
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+ const unclosed = (outcome.value as Partial<CloseAndAwaitOutcome> | undefined)?.unclosed;
+
+ expect({
+ returned: whatTheCallReturned(outcome),
+ firstPassRaisedAnAppCleanupIncompleteError:
+ firstPassFailure instanceof AppCleanupIncompleteError,
+ unclosedIsThatSameFailure: unclosed?.length === 1 && unclosed[0] === firstPassFailure,
+ serverAliveWhenTheCallReturned,
+ sequenceWhenTheCallReturned,
+ groupKills: sent,
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ returned: {
+ unclosed: [firstPassFailure],
+ survivors: [{ lockPath, pid }],
+ closedAfterServerRelease: [],
+ },
+ firstPassRaisedAnAppCleanupIncompleteError: true,
+ unclosedIsThatSameFailure: true,
+ serverAliveWhenTheCallReturned: true,
+ sequenceWhenTheCallReturned: ['app exited', 'call returned'],
+ groupKills: [{ target: -APP_PID, signal: 'SIGKILL', whileHeld: true }],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ ROW_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ 'an app that closes on the group kill leaves nothing to look at again, and the call still returns only after its server released on its own',
+ async () => {
+ expect(typeof closeAppsThenAwaitServerRelease).toBe('function');
+ const { standIn, pid, logPath } = await startStandInServer();
+ const app = appDouble('its-own');
+ const sequence: string[] = [];
+ const probesWhenTheAppExited = observeApp(app, sequence);
+ standIn.once('exit', () => {
+ sequence.push('server exited');
+ });
+ const { sent, kill } = groupKillRecorder(app);
+ expect(process.kill).toBe(boundary.send);
+
+ const { settled, hasReturned } = track(
+ () =>
+ closeAppsThenAwaitServerRelease([app as unknown as ChildProcess], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: STAND_IN_RELEASE_LIVENESS_BOUND_MS,
+ kill,
+ platform: 'linux',
+ }),
+ sequence,
+ );
+ let reaperWatchedTheLiveServerAfterTheAppDied = false;
+ try {
+ reaperWatchedTheLiveServerAfterTheAppDied = await watchFor(
+ () => probedSince(probesWhenTheAppExited(), pid),
+ hasReturned,
+ );
+ } finally {
+ standIn.stdin?.end();
+ }
+ const outcome = await settled;
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ reaperWatchedTheLiveServerAfterTheAppDied,
+ returned: whatTheCallReturned(outcome),
+ sequence,
+ groupKills: sent,
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ reaperWatchedTheLiveServerAfterTheAppDied: true,
+ returned: { unclosed: [], survivors: [], closedAfterServerRelease: [] },
+ sequence: ['app exited', 'app closed', 'server exited', 'call returned'],
+ groupKills: [{ target: -APP_PID, signal: 'SIGKILL', whileHeld: true }],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ ROW_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ 'a close that arrives only after the server released is still admitted within the reap window',
+ async () => {
+ expect(typeof closeAppsThenAwaitServerRelease).toBe('function');
+ const { standIn, pid, logPath } = await startStandInServer();
+ const app = appDouble('held-by-its-server');
+ const sequence: string[] = [];
+ const probesWhenTheAppExited = observeApp(app, sequence);
+ let probesWhenTheServerExited: number | undefined;
+ standIn.once('exit', () => {
+ probesWhenTheServerExited = boundary.probes.length;
+ sequence.push('server exited');
+ });
+ const { sent, kill } = groupKillRecorder(app);
+ expect(process.kill).toBe(boundary.send);
+
+ const { settled, hasReturned } = track(
+ () =>
+ closeAppsThenAwaitServerRelease([app as unknown as ChildProcess], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: STAND_IN_RELEASE_LIVENESS_BOUND_MS,
+ kill,
+ platform: 'linux',
+ }),
+ sequence,
+ );
+ let reaperWatchedTheLiveServerAfterTheAppDied = false;
+ let reaperLookedAgainAfterTheServerExited = false;
+ try {
+ reaperWatchedTheLiveServerAfterTheAppDied = await watchFor(
+ () => probedSince(probesWhenTheAppExited(), pid),
+ hasReturned,
+ );
+ standIn.stdin?.end();
+ reaperLookedAgainAfterTheServerExited = await watchFor(
+ () => probedSince(probesWhenTheServerExited, pid),
+ hasReturned,
+ );
+ } finally {
+ standIn.stdin?.end();
+ releaseStdio(app);
+ }
+ const outcome = await settled;
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ reaperWatchedTheLiveServerAfterTheAppDied,
+ reaperLookedAgainAfterTheServerExited,
+ returned: whatTheCallReturned(outcome),
+ sequence,
+ groupKills: sent,
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ reaperWatchedTheLiveServerAfterTheAppDied: true,
+ reaperLookedAgainAfterTheServerExited: true,
+ returned: { unclosed: [], survivors: [], closedAfterServerRelease: [APP_PID] },
+ sequence: ['app exited', 'server exited', 'app closed', 'call returned'],
+ groupKills: [{ target: -APP_PID, signal: 'SIGKILL', whileHeld: true }],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ ROW_LIVENESS_BOUND_MS,
+ );
+
+ test(
+ 'a server whose lock reads empty mid-rewrite while the reaper watches it is still waited for, so its app closes once that server releases and is not reported',
+ async () => {
+ expect(typeof closeAppsThenAwaitServerRelease).toBe('function');
+ const { standIn, pid, lockPath, logPath } = await startStandInServer();
+ const app = appDouble('held-by-its-server');
+ const sequence: string[] = [];
+ const probesWhenTheAppExited = observeApp(app, sequence);
+ standIn.once('exit', () => {
+ sequence.push('server exited');
+ releaseStdio(app);
+ });
+ const { sent, kill } = groupKillRecorder(app);
+ expect(process.kill).toBe(boundary.send);
+
+ const { settled, hasReturned } = track(
+ () =>
+ closeAppsThenAwaitServerRelease([app as unknown as ChildProcess], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: STAND_IN_RELEASE_LIVENESS_BOUND_MS,
+ kill,
+ platform: 'linux',
+ }),
+ sequence,
+ );
+ let reaperWatchedTheLiveServerAfterTheAppDied = false;
+ let reaperProbedTheServerAgainAfterTheTear = false;
+ try {
+ reaperWatchedTheLiveServerAfterTheAppDied = await watchFor(
+ () => probedSince(probesWhenTheAppExited(), pid),
+ hasReturned,
+ );
+ writeFileSync(lockPath, '');
+ const probesWhenTheLockWasTorn = boundary.probes.length;
+ reaperProbedTheServerAgainAfterTheTear = await watchFor(
+ () => probedSince(probesWhenTheLockWasTorn, pid),
+ hasReturned,
+ );
+ } finally {
+ standIn.stdin?.end();
+ }
+ const outcome = await settled;
+ if (standIn.exitCode === null && standIn.signalCode === null) await once(standIn, 'exit');
+
+ expect({
+ reaperWatchedTheLiveServerAfterTheAppDied,
+ reaperProbedTheServerAgainAfterTheTear,
+ returned: whatTheCallReturned(outcome),
+ sequence,
+ groupKills: sent,
+ refused: boundary.refused,
+ signalsThatReachedTheStandIn: signalsThatReached(standIn, logPath),
+ }).toEqual({
+ reaperWatchedTheLiveServerAfterTheAppDied: true,
+ reaperProbedTheServerAgainAfterTheTear: true,
+ returned: { unclosed: [], survivors: [], closedAfterServerRelease: [APP_PID] },
+ sequence: ['app exited', 'server exited', 'app closed', 'call returned'],
+ groupKills: [{ target: -APP_PID, signal: 'SIGKILL', whileHeld: true }],
+ refused: [],
+ signalsThatReachedTheStandIn: [],
+ });
+ },
+ ROW_LIVENESS_BOUND_MS,
+ );
+
+ test('the window the teardown gives servers to release outlasts the lifetime a packaged launch gives each server', () => {
+ expect({
+ windowIsExported: typeof SMOKE_SERVER_RELEASE_WINDOW_MS === 'number',
+ lifetimeIsExported: typeof PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS === 'number',
+ windowOutlastsTheLifetime:
+ SMOKE_SERVER_RELEASE_WINDOW_MS > PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS,
+ }).toEqual({
+ windowIsExported: true,
+ lifetimeIsExported: true,
+ windowOutlastsTheLifetime: true,
+ });
+ });
+});
+
+function mentionsPid(text: string, pid: number): boolean {
+ return new RegExp(`(^|\\D)${pid}(\\D|$)`).test(text);
+}
+
+describe('cleanupIncompleteReport — the app-cleanup-incomplete attachment body', () => {
+ const survivingServers = [
+ {
+ lockPath: join(tmpdir(), 'ok-smoke-report', 'consent', '.ok', 'local', 'server.lock'),
+ pid: 4_194_319,
+ },
+ {
+ lockPath: join(tmpdir(), 'ok-smoke-report', 'create-new', 'a', '.ok', 'local', 'server.lock'),
+ pid: 41_943,
+ },
+ ] satisfies ServerLockRecord[];
+
+ function unclosedApps(): Error[] {
+ const exited = appDouble('held-by-its-server');
+ exited.exitCode = 0;
+ return [
+ new AppCleanupIncompleteError(
+ exited as unknown as ChildProcess,
+ [{ lever: 'leader-exited', elapsedMs: 0 }],
+ GRACEFUL_MS,
+ ),
+ new Error('app pid 4194333 did not close'),
+ ];
+ }
+
+ test('there is nothing to report when every app closed and no server outlived the window', () => {
+ expect(typeof cleanupIncompleteReport).toBe('function');
+ expect({
+ reportIsExported: typeof cleanupIncompleteReport === 'function',
+ body: cleanupIncompleteReport([], []),
+ }).toStrictEqual({
+ reportIsExported: true,
+ body: undefined,
+ });
+ });
+
+ test.each<[string, 'unclosed' | 'survivors' | 'both']>([
+ ['an app did not close', 'unclosed'],
+ ['a server outlived the window', 'survivors'],
+ ['both happened', 'both'],
+ ])(
+ "the body carries every unclosed app's failure and names every surviving server by pid and exact lock path when %s",
+ (_case, which) => {
+ const unclosed = which === 'survivors' ? [] : unclosedApps();
+ const survivors = which === 'unclosed' ? [] : survivingServers;
+ expect(typeof cleanupIncompleteReport).toBe('function');
+ const body = cleanupIncompleteReport(unclosed, survivors);
+
+ expect({
+ reportIsExported: typeof cleanupIncompleteReport === 'function',
+ bodyIsText: typeof body === 'string',
+ unclosedFailuresCarried: unclosed.map((error) => body?.includes(error.message) === true),
+ survivorsNamed: survivors.map(
+ (server) =>
+ body !== undefined && mentionsPid(body, server.pid) && body.includes(server.lockPath),
+ ),
+ }).toEqual({
+ reportIsExported: true,
+ bodyIsText: true,
+ unclosedFailuresCarried: unclosed.map(() => true),
+ survivorsNamed: survivors.map(() => true),
+ });
+ },
+ );
+
+ test('a server lock that never yields a readable pid within the release window is named in the warning and the body by its exact path alone, and nothing is probed or signalled', async () => {
+ const local = join(root, '.ok', 'local');
+ mkdirSync(local, { recursive: true });
+ const lockPath = join(local, 'server.lock');
+ writeFileSync(lockPath, '');
+ const warnings: string[] = [];
+ vi.spyOn(console, 'warn').mockImplementation((...args: unknown[]) => {
+ warnings.push(args.map(String).join(' '));
+ });
+ expect(process.kill).toBe(boundary.send);
+
+ const outcome = await track(
+ () =>
+ closeAppsThenAwaitServerRelease([], [root], {
+ gracefulMs: GRACEFUL_MS,
+ postKillReapMs: REAP_MS,
+ serverReleaseWindowMs: SURVIVOR_WINDOW_MS,
+ }),
+ [],
+ ).settled;
+ const value = outcome.value as CloseAndAwaitOutcome | undefined;
+ const body =
+ value === undefined ? undefined : cleanupIncompleteReport(value.unclosed, value.survivors);
+
+ expect({
+ returned: whatTheCallReturned(outcome),
+ lockNamedInAWarning: warnings.some((line) => line.includes(lockPath)),
+ bodyNamesTheLock: body?.includes(lockPath) === true,
+ textThatPrintsAnAbsentPid: [...warnings, ...(body === undefined ? [] : [body])].filter(
+ (text) => text.includes('undefined'),
+ ),
+ probes: boundary.probes,
+ refused: boundary.refused,
+ }).toEqual({
+ returned: {
+ unclosed: [],
+ survivors: [{ lockPath, pid: undefined }],
+ closedAfterServerRelease: [],
+ },
+ lockNamedInAWarning: true,
+ bodyNamesTheLock: true,
+ textThatPrintsAnAbsentPid: [],
+ probes: [],
+ refused: [],
+ });
+ });
+});
diff --git a/packages/desktop/tests/smoke/_helpers/electron-cleanup.test.ts b/packages/desktop/tests/smoke/_helpers/electron-cleanup.test.ts
index 4182979c6..56808ed67 100644
--- a/packages/desktop/tests/smoke/_helpers/electron-cleanup.test.ts
+++ b/packages/desktop/tests/smoke/_helpers/electron-cleanup.test.ts
@@ -1,8 +1,13 @@
import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
import { once } from 'node:events';
-import { afterEach, describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import {
+ installSignalBoundary,
+ type SignalBoundary,
+} from '../../../../../test-support/held-signal-boundary.test-helper';
import {
AppCleanupIncompleteError,
+ type CloseAppBoundedOpts,
closeAppBounded,
type TaskkillOutcome,
} from './electron-cleanup';
@@ -119,17 +124,17 @@ describe('closeAppBounded — real subprocess contract', () => {
});
});
-const HOLDER_SCRIPT = 'setInterval(() => {}, 1000);';
const HANG_FOREVER = "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);";
+const GRACEFUL_WAIT_THE_ROOT_EXITS_INSIDE_MS = 3_000;
function exitAfter(ms: number): string {
return `setTimeout(() => process.exit(0), ${ms});`;
}
-function rootScript(afterHolderSpawn: string): string {
+function rootScript(afterHolderSpawn: string, holderGroup: 'root' | 'own'): string {
return [
"const { spawn } = require('node:child_process');",
- `const holder = spawn(process.execPath, ['-e', ${JSON.stringify(HOLDER_SCRIPT)}], { stdio: 'inherit' });`,
+ `const holder = spawn('sh', ['-c', 'exec cat <&3'], { stdio: ['inherit', 'inherit', 'inherit', 3], detached: ${holderGroup === 'own'} });`,
afterHolderSpawn,
"process.stdout.write('HOLDER_PID=' + holder.pid + '\\n');",
].join('\n');
@@ -153,38 +158,31 @@ interface StreamHeldTree {
closeObserved: () => boolean;
}
-interface TrackedTree {
- rootPid: number;
- holderPid: number | undefined;
-}
-
-const liveTrees: TrackedTree[] = [];
+const liveRoots: ChildProcess[] = [];
+let boundary: SignalBoundary | undefined;
afterEach(() => {
- for (const tracked of liveTrees) {
- try {
- process.kill(-tracked.rootPid, 'SIGKILL');
- } catch {}
- if (tracked.holderPid === undefined) continue;
- try {
- process.kill(tracked.holderPid, 'SIGKILL');
- } catch {}
+ for (const root of liveRoots) {
+ root.kill('SIGKILL');
+ root.stdio[3]?.destroy();
}
- liveTrees.length = 0;
+ liveRoots.length = 0;
});
-async function spawnStreamHeldTree(afterHolderSpawn: string): Promise<StreamHeldTree> {
- const root = spawn(process.execPath, ['-e', rootScript(afterHolderSpawn)], {
- stdio: 'pipe',
+async function spawnStreamHeldTree(
+ afterHolderSpawn: string,
+ holderGroup: 'root' | 'own' = 'root',
+): Promise<StreamHeldTree> {
+ const root = spawn(process.execPath, ['-e', rootScript(afterHolderSpawn, holderGroup)], {
+ stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
detached: true,
});
+ liveRoots.push(root);
+ boundary?.hold(root);
if (root.pid === undefined) await once(root, 'spawn');
const rootPid = root.pid;
if (rootPid === undefined) throw new Error('spawn did not assign a root pid');
- const tracked: TrackedTree = { rootPid, holderPid: undefined };
- liveTrees.push(tracked);
-
let closeObserved = false;
root.once('close', () => {
closeObserved = true;
@@ -212,38 +210,93 @@ async function spawnStreamHeldTree(afterHolderSpawn: string): Promise<StreamHeld
check();
});
- tracked.holderPid = holderPid;
return { root, rootPid, holderPid, closeObserved: () => closeObserved };
}
+async function rootExited(tree: StreamHeldTree): Promise<void> {
+ if (tree.root.exitCode === null && tree.root.signalCode === null) {
+ await once(tree.root, 'exit');
+ }
+}
+
+function settleClose(
+ tree: StreamHeldTree,
+ opts: CloseAppBoundedOpts,
+): Promise<'returned' | 'reported-failure' | 'threw'> {
+ return closeAppBounded(tree.root, opts).then(
+ () => 'returned' as const,
+ (error: unknown) =>
+ error instanceof AppCleanupIncompleteError ? ('reported-failure' as const) : 'threw',
+ );
+}
+
describe.skipIf(process.platform === 'win32')(
'closeAppBounded — close, not exit, is the postcondition',
() => {
- test('(1) root exits on its own while a descendant still holds its stdio → returns only once the launched process closed', async () => {
+ beforeEach(() => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ });
+
+ afterEach(() => {
+ boundary?.restore();
+ boundary = undefined;
+ });
+
+ function heldBoundary(): SignalBoundary {
+ if (boundary === undefined || process.kill !== boundary.send) {
+ throw new Error('the signal boundary is not installed; refusing to run code that signals');
+ }
+ return boundary;
+ }
+
+ test('(1) root exits on its own while a same-group descendant still holds its stdio → nothing is signalled once the root has exited, and closure is never claimed while the holder lives', async () => {
const tree = await spawnStreamHeldTree(exitAfter(150));
+ const signals = heldBoundary();
+ const calledAt = Date.now();
+ let rootExitedAt =
+ tree.root.exitCode === null && tree.root.signalCode === null ? undefined : calledAt;
+ tree.root.once('exit', () => {
+ rootExitedAt ??= Date.now();
+ });
- await closeAppBounded(tree.root, { gracefulMs: 1_000, platform: 'linux' });
+ const outcome = await settleClose(tree, {
+ gracefulMs: GRACEFUL_WAIT_THE_ROOT_EXITS_INSIDE_MS,
+ postKillReapMs: REAP_MS,
+ platform: 'linux',
+ });
expect({
- closeObserved: tree.closeObserved(),
- holderAlive: isAlive(tree.holderPid),
- }).toEqual({ closeObserved: true, holderAlive: false });
+ rootExitedInsideTheGracefulWait:
+ rootExitedAt !== undefined &&
+ rootExitedAt - calledAt < GRACEFUL_WAIT_THE_ROOT_EXITS_INSIDE_MS,
+ refused: signals.refused,
+ outcome: outcome === 'threw' ? 'threw' : 'settled',
+ claimedCleanupComplete: outcome === 'returned' && isAlive(tree.holderPid),
+ }).toEqual({
+ rootExitedInsideTheGracefulWait: true,
+ refused: [],
+ outcome: 'settled',
+ claimedCleanupComplete: false,
+ });
});
test('(2) hung root with a stdio-holding descendant → returns only once the group kill reached both and the launched process closed', async () => {
const tree = await spawnStreamHeldTree(HANG_FOREVER);
+ const signals = heldBoundary();
await closeAppBounded(tree.root, { gracefulMs: 500, platform: 'linux' });
expect({
+ refused: signals.refused,
closeObserved: tree.closeObserved(),
rootAlive: isAlive(tree.rootPid),
holderAlive: isAlive(tree.holderPid),
- }).toEqual({ closeObserved: true, rootAlive: false, holderAlive: false });
+ }).toEqual({ refused: [], closeObserved: true, rootAlive: false, holderAlive: false });
});
test('(3) win32 tree-kill reports ETIMEDOUT once and kills nothing, then succeeds → converges to real closure', async () => {
const tree = await spawnStreamHeldTree(HANG_FOREVER);
+ heldBoundary();
const attempts: TaskkillOutcome[] = [];
const taskkill = async (pid: number): Promise<TaskkillOutcome> => {
@@ -252,9 +305,8 @@ describe.skipIf(process.platform === 'win32')(
attempts.push(timedOut);
return timedOut;
}
- try {
- process.kill(-pid, 'SIGKILL');
- } catch {}
+ tree.root.kill('SIGKILL');
+ tree.root.stdio[3]?.destroy();
const reaped = reapedTaskkill(pid);
attempts.push(reaped);
return reaped;
@@ -272,6 +324,7 @@ describe.skipIf(process.platform === 'win32')(
test('(4) win32 tree-kill always reports ETIMEDOUT and kills nothing → never returns normally while the tree is still alive', async () => {
const tree = await spawnStreamHeldTree(HANG_FOREVER);
+ heldBoundary();
const attempts: number[] = [];
const taskkill = async (pid: number): Promise<TaskkillOutcome> => {
@@ -279,16 +332,12 @@ describe.skipIf(process.platform === 'win32')(
return timedOutTaskkill();
};
- const outcome = await closeAppBounded(tree.root, {
+ const outcome = await settleClose(tree, {
gracefulMs: 500,
postKillReapMs: REAP_MS,
taskkill,
platform: 'win32',
- }).then(
- () => 'returned' as const,
- (error: unknown) =>
- error instanceof AppCleanupIncompleteError ? ('reported-failure' as const) : 'threw',
- );
+ });
const rootAlive = isAlive(tree.rootPid);
const holderAlive = isAlive(tree.holderPid);
@@ -304,18 +353,22 @@ describe.skipIf(process.platform === 'win32')(
});
});
- test('(5) root already exited before the call while a descendant still holds its stdio → escalation still establishes closure', async () => {
+ test('(5) root already exited before the call while a same-group descendant still holds its stdio → nothing is signalled after the exit, and closure is never claimed while the holder lives', async () => {
const tree = await spawnStreamHeldTree(exitAfter(50));
- if (tree.root.exitCode === null && tree.root.signalCode === null) {
- await once(tree.root, 'exit');
- }
+ await rootExited(tree);
+ const signals = heldBoundary();
- await closeAppBounded(tree.root, { gracefulMs: 1_000, platform: 'linux' });
+ const outcome = await settleClose(tree, {
+ gracefulMs: 1_000,
+ postKillReapMs: REAP_MS,
+ platform: 'linux',
+ });
expect({
- closeObserved: tree.closeObserved(),
- holderAlive: isAlive(tree.holderPid),
- }).toEqual({ closeObserved: true, holderAlive: false });
+ refused: signals.refused,
+ outcome: outcome === 'threw' ? 'threw' : 'settled',
+ claimedCleanupComplete: outcome === 'returned' && isAlive(tree.holderPid),
+ }).toEqual({ refused: [], outcome: 'settled', claimedCleanupComplete: false });
});
test('(7) a piped process that already closed before the call → the structural fallback returns without a kill', async () => {
@@ -346,6 +399,7 @@ describe.skipIf(process.platform === 'win32')(
test('(6) a signal was sent but the root ignored it → `killed === true` alone is not closure', async () => {
const tree = await spawnStreamHeldTree(HANG_FOREVER);
+ const signals = heldBoundary();
tree.root.kill('SIGTERM');
expect(tree.root.killed).toBe(true);
expect(isAlive(tree.rootPid)).toBe(true);
@@ -353,10 +407,29 @@ describe.skipIf(process.platform === 'win32')(
await closeAppBounded(tree.root, { gracefulMs: 500, platform: 'linux' });
expect({
+ refused: signals.refused,
closeObserved: tree.closeObserved(),
rootAlive: isAlive(tree.rootPid),
holderAlive: isAlive(tree.holderPid),
- }).toEqual({ closeObserved: true, rootAlive: false, holderAlive: false });
+ }).toEqual({ refused: [], closeObserved: true, rootAlive: false, holderAlive: false });
+ });
+
+ test('(8) root exits while its stdio holder sits in a group of its own → nothing is signalled at the emptied root group, and closure is never claimed while the holder lives', async () => {
+ const tree = await spawnStreamHeldTree(exitAfter(50), 'own');
+ await rootExited(tree);
+ const signals = heldBoundary();
+
+ const outcome = await settleClose(tree, {
+ gracefulMs: 300,
+ postKillReapMs: REAP_MS,
+ platform: 'linux',
+ });
+
+ expect({
+ refused: signals.refused,
+ outcome: outcome === 'threw' ? 'threw' : 'settled',
+ claimedCleanupComplete: outcome === 'returned' && isAlive(tree.holderPid),
+ }).toEqual({ refused: [], outcome: 'settled', claimedCleanupComplete: false });
});
},
);
diff --git a/packages/desktop/tests/smoke/_helpers/electron-cleanup.ts b/packages/desktop/tests/smoke/_helpers/electron-cleanup.ts
index 6fdff20c2..50f70f313 100644
--- a/packages/desktop/tests/smoke/_helpers/electron-cleanup.ts
+++ b/packages/desktop/tests/smoke/_helpers/electron-cleanup.ts
@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
import { type Dirent, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import type { ElectronApplication } from '@playwright/test';
+import { PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS } from './launch-desktop';
export interface TaskkillOutcome {
status: number | null;
@@ -90,8 +91,44 @@ export function captureAppProcess(app: ElectronApplication): ChildProcess {
}
const LOCK_SEARCH_DEPTH = 3;
+export const DETACHED_SERVER_RELEASE_BOUND_MS = 15_000;
+export const SMOKE_SERVER_RELEASE_WINDOW_MS =
+ PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS + DETACHED_SERVER_RELEASE_BOUND_MS;
+const DETACHED_SERVER_POLL_INTERVAL_MS = 100;
-function collectServerLockPids(dir: string, depth: number, out: number[]): void {
+export interface ServerLockRecord {
+ lockPath: string;
+ pid: number | undefined;
+}
+
+type LockRead =
+ | { kind: 'absent' }
+ | { kind: 'unreadable' }
+ | { kind: 'foreign' }
+ | { kind: 'names'; pid: number };
+
+function readLock(lockPath: string): LockRead {
+ let text: string;
+ try {
+ text = readFileSync(lockPath, 'utf8');
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ return code === 'ENOENT' || code === 'ENOTDIR' ? { kind: 'absent' } : { kind: 'unreadable' };
+ }
+ let lock: unknown;
+ try {
+ lock = JSON.parse(text);
+ } catch {
+ return { kind: 'unreadable' };
+ }
+ const pid =
+ typeof lock === 'object' && lock !== null ? (lock as { pid?: unknown }).pid : undefined;
+ return typeof pid === 'number' && Number.isInteger(pid) && pid > 1
+ ? { kind: 'names', pid }
+ : { kind: 'foreign' };
+}
+
+function collectServerLocks(dir: string, depth: number, out: Map<string, ServerLockRecord>): void {
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
@@ -101,27 +138,61 @@ function collectServerLockPids(dir: string, depth: number, out: number[]): void
for (const entry of entries) {
if (!entry.isDirectory()) continue;
if (entry.name === '.ok') {
- try {
- const raw = readFileSync(join(dir, '.ok', 'local', 'server.lock'), 'utf8');
- const pid = (JSON.parse(raw) as { pid?: unknown }).pid;
- if (typeof pid === 'number' && Number.isInteger(pid) && pid > 1) out.push(pid);
- } catch {}
+ const lockPath = join(dir, '.ok', 'local', 'server.lock');
+ const lock = readLock(lockPath);
+ if (lock.kind === 'names') out.set(lockPath, { lockPath, pid: lock.pid });
+ if (lock.kind === 'unreadable') out.set(lockPath, { lockPath, pid: undefined });
continue;
}
- if (depth > 0) collectServerLockPids(join(dir, entry.name), depth - 1, out);
+ if (depth > 0) collectServerLocks(join(dir, entry.name), depth - 1, out);
}
}
-export function reapDetachedServers(dirs: readonly string[]): void {
- const pids: number[] = [];
- for (const dir of dirs) collectServerLockPids(dir, LOCK_SEARCH_DEPTH, pids);
- for (const pid of new Set(pids)) {
- try {
- process.kill(pid, 'SIGKILL');
- } catch {}
+function probeFindsProcess(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (error) {
+ return (error as NodeJS.ErrnoException).code === 'EPERM';
}
}
+function stillPending(record: ServerLockRecord): ServerLockRecord[] {
+ const lock = readLock(record.lockPath);
+ if (lock.kind === 'absent') return [];
+ if (lock.kind === 'names' && record.pid !== undefined && lock.pid !== record.pid) return [];
+ const pid = record.pid === undefined && lock.kind === 'names' ? lock.pid : record.pid;
+ if (pid === undefined) return [record];
+ return probeFindsProcess(pid) ? [{ lockPath: record.lockPath, pid }] : [];
+}
+
+export async function reapDetachedServers(
+ dirs: readonly string[],
+ opts: { boundMs?: number } = {},
+): Promise<ServerLockRecord[]> {
+ const boundMs = opts.boundMs ?? DETACHED_SERVER_RELEASE_BOUND_MS;
+ const locks = new Map<string, ServerLockRecord>();
+ for (const dir of dirs) collectServerLocks(dir, LOCK_SEARCH_DEPTH, locks);
+ const deadline = Date.now() + boundMs;
+ let pending = [...locks.values()].flatMap(stillPending);
+ while (pending.length > 0 && Date.now() < deadline) {
+ await new Promise<void>((resolve) => setTimeout(resolve, DETACHED_SERVER_POLL_INTERVAL_MS));
+ pending = pending.flatMap(stillPending);
+ }
+ for (const { lockPath, pid } of pending) {
+ if (pid === undefined) {
+ console.warn(
+ `[smoke-test] ${lockPath} still exists with no readable pid after ${boundMs}ms; nothing was signalled`,
+ );
+ continue;
+ }
+ console.warn(
+ `[smoke-test] server pid ${pid} still holds ${lockPath} after ${boundMs}ms; not signalling a process this teardown did not spawn`,
+ );
+ }
+ return pending;
+}
+
function openStdioCount(proc: ChildProcess): number {
const slots = Array.isArray(proc.stdio) ? proc.stdio : [];
let open = 0;
@@ -176,12 +247,14 @@ export type KillAttempt = { elapsedMs: number } & (
| { lever: 'taskkill'; outcome: TaskkillOutcome }
| { lever: 'group-kill'; thrown: unknown }
| { lever: 'no-pid' }
+ | { lever: 'leader-exited' }
);
async function escalate(proc: ChildProcess, opts: CloseAppBoundedOpts): Promise<KillAttempt> {
const startedAt = Date.now();
const pid = usablePid(proc);
if (pid === undefined) return { lever: 'no-pid', elapsedMs: Date.now() - startedAt };
+ if (hasExited(proc)) return { lever: 'leader-exited', elapsedMs: Date.now() - startedAt };
if ((opts.platform ?? process.platform) === 'win32') {
const outcome = await (opts.taskkill ?? taskkillTree)(pid);
return { lever: 'taskkill', outcome, elapsedMs: Date.now() - startedAt };
@@ -203,6 +276,9 @@ function quote(text: string): string {
function describeAttempt(attempt: KillAttempt, slot: number): string {
const label = `attempt ${slot + 1} after ${attempt.elapsedMs}ms`;
if (attempt.lever === 'no-pid') return `${label}: no usable pid, no kill lever available`;
+ if (attempt.lever === 'leader-exited') {
+ return `${label}: nothing signalled because the launched process had already exited`;
+ }
if (attempt.lever === 'group-kill') {
const thrown = attempt.thrown;
if (thrown === undefined) return `${label}: kill(-pid, SIGKILL) sent`;
@@ -279,3 +355,55 @@ export async function closeAppBounded(
incomplete.set(proc, failure);
throw failure;
}
+
+export async function closeAppsThenAwaitServerRelease(
+ procs: readonly ChildProcess[],
+ cleanupDirs: readonly string[],
+ opts: CloseAppBoundedOpts & { gracefulMs: number; serverReleaseWindowMs?: number },
+): Promise<{
+ unclosed: Error[];
+ survivors: ServerLockRecord[];
+ closedAfterServerRelease: number[];
+}> {
+ const { serverReleaseWindowMs, ...closeOpts } = opts;
+ const failedFirstClose: { proc: ChildProcess; failure: Error }[] = [];
+ for (const proc of procs) {
+ try {
+ await closeAppBounded(proc, closeOpts);
+ } catch (error) {
+ failedFirstClose.push({
+ proc,
+ failure: error instanceof Error ? error : new Error(String(error)),
+ });
+ }
+ }
+ const survivors = await reapDetachedServers(cleanupDirs, {
+ boundMs: serverReleaseWindowMs ?? SMOKE_SERVER_RELEASE_WINDOW_MS,
+ });
+ const unclosed: Error[] = [];
+ const closedAfterServerRelease: number[] = [];
+ for (const { proc, failure } of failedFirstClose) {
+ await waitForClose(proc, opts.postKillReapMs ?? POST_KILL_REAP_MS);
+ if (hasClosed(proc)) {
+ if (proc.pid !== undefined) closedAfterServerRelease.push(proc.pid);
+ } else {
+ unclosed.push(failure);
+ }
+ }
+ return { unclosed, survivors, closedAfterServerRelease };
+}
+
+export function cleanupIncompleteReport(
+ unclosed: readonly Error[],
+ survivors: readonly ServerLockRecord[],
+): string | undefined {
+ if (unclosed.length === 0 && survivors.length === 0) return undefined;
+ return [
+ ...unclosed.map((error) => error.message),
+ ...survivors.map(({ lockPath, pid }) =>
+ pid === undefined
+ ? `${lockPath} still existed with no readable pid when the release window ended; nothing was signalled`
+ : `server pid ${pid} still held ${lockPath} when the release window ended; it was not signalled`,
+ ),
+ ].join('\n\n');
+}
diff --git a/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts b/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts
index 05c943cb2..e4ee2df0b 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-desktop.test.ts
@@ -1,14 +1,24 @@
import { readdirSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
+import {
+ applyConfigOverlay,
+ type Config,
+ idleShutdownToMs,
+ resolveEnvConfigLayer,
+ resolveServerRuntimeConfig,
+} from '@inkeep/open-knowledge-core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { SPAWN_STARTUP_DEADLINE_MS } from '../../../src/shared/boot-narration.ts';
import {
DEFAULT_LAUNCH_TIMEOUT_MS,
DEFAULT_LOCAL_PACKAGED_APP,
desktopLaunchOptions,
executableForAppBundle,
PACKAGED_APP_ENV,
+ PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS,
resolveDesktopTarget,
+ type SmokeLaunchEnv,
UNPACKAGED_MAIN_ENTRY,
} from './launch-desktop';
@@ -126,6 +136,71 @@ describe('desktopLaunchOptions', () => {
});
});
+function idleThresholdTheServerDerivesFrom(
+ env: SmokeLaunchEnv | undefined,
+): number | null | string {
+ let layer: Record<string, unknown>;
+ try {
+ layer = resolveEnvConfigLayer({ OK_IDLE_SHUTDOWN: env?.OK_IDLE_SHUTDOWN }).layer;
+ } catch (error) {
+ return `rejected by the server's env layer: ${error instanceof Error ? error.message : String(error)}`;
+ }
+ return idleShutdownToMs(
+ resolveServerRuntimeConfig(applyConfigOverlay({}, layer) as Config).idleShutdown,
+ );
+}
+
+describe("desktopLaunchOptions — a packaged launch bounds its detached server's lifetime", () => {
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it.each<[string, string | undefined, string | undefined]>([
+ ['neither the parent env nor the caller sets one', undefined, undefined],
+ ["the parent env sets 'off'", 'off', undefined],
+ ["the parent env sets '30m'", '30m', undefined],
+ ["the caller's env sets 'off'", undefined, 'off'],
+ ["the caller's env sets '30m'", undefined, '30m'],
+ ])(
+ "the server's own config parsing turns a packaged launch's env into exactly the exported lifetime bound when %s",
+ (_case, parent, supplied) => {
+ vi.stubEnv('OK_IDLE_SHUTDOWN', parent);
+ const opts = desktopLaunchOptions({
+ target: packaged,
+ env: supplied === undefined ? {} : { OK_IDLE_SHUTDOWN: supplied },
+ });
+ expect({
+ lifetimeBoundIsExported: typeof PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS === 'number',
+ serverIdleThresholdMs: idleThresholdTheServerDerivesFrom(opts.env),
+ }).toEqual({
+ lifetimeBoundIsExported: true,
+ serverIdleThresholdMs: PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS,
+ });
+ },
+ );
+
+ it('an unpackaged launch sets no idle shutdown of its own, while a packaged launch from the same env sets one', () => {
+ vi.stubEnv('OK_IDLE_SHUTDOWN', undefined);
+ const supplied = { HOME: '/tmp/home' };
+
+ expect({
+ packagedLaunchSetsOne:
+ desktopLaunchOptions({ target: packaged, env: supplied }).env?.OK_IDLE_SHUTDOWN !==
+ undefined,
+ unpackagedLaunchSetsOne:
+ desktopLaunchOptions({ target: unpackaged, env: supplied }).env?.OK_IDLE_SHUTDOWN !==
+ undefined,
+ }).toEqual({ packagedLaunchSetsOne: true, unpackagedLaunchSetsOne: false });
+ });
+
+ it("the packaged server's lifetime bound outlasts the app's own deadline for that server's lock", () => {
+ expect({
+ lifetimeBoundIsExported: typeof PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS === 'number',
+ outlastsTheLockDeadline: PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS > SPAWN_STARTUP_DEADLINE_MS,
+ }).toEqual({ lifetimeBoundIsExported: true, outlastsTheLockDeadline: true });
+ });
+});
+
describe('no smoke file references __dirname without defining it', () => {
const SMOKE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
diff --git a/packages/desktop/tests/smoke/_helpers/launch-desktop.ts b/packages/desktop/tests/smoke/_helpers/launch-desktop.ts
index 4f0894088..722aa18e8 100644
--- a/packages/desktop/tests/smoke/_helpers/launch-desktop.ts
+++ b/packages/desktop/tests/smoke/_helpers/launch-desktop.ts
@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
import { basename, dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import type { _electron as electron } from '@playwright/test';
+import { SPAWN_STARTUP_DEADLINE_MS } from '../../../src/shared/boot-narration.ts';
import { readinessGiveUpBoundMs } from './launch-readiness';
type ElectronLaunchOptions = NonNullable<Parameters<typeof electron.launch>[0]>;
@@ -86,6 +87,8 @@ export interface DesktopLaunchOptions {
export const DEFAULT_LAUNCH_TIMEOUT_MS = 30_000;
+export const PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS = 2 * SPAWN_STARTUP_DEADLINE_MS;
+
export const SETUP_BEFORE_FIRST_READINESS_WAIT_MS = 0;
export const ONE_LAUNCH_AND_ITS_READINESS_VERDICT_MS =
@@ -103,5 +106,16 @@ export function desktopLaunchOptions(input: DesktopLaunchOptionsInput = {}): Des
? { args: [...extraArgs], timeout, executablePath: target.targetPath }
: { args: [target.targetPath, ...extraArgs], timeout };
- return { ...base, env: { ...process.env, ...input.env, OK_LANG: 'en', OK_LOG_LEVEL: 'info' } };
+ return {
+ ...base,
+ env: {
+ ...process.env,
+ ...input.env,
+ OK_LANG: 'en',
+ OK_LOG_LEVEL: 'info',
+ ...(target.mode === 'packaged'
+ ? { OK_IDLE_SHUTDOWN: `${PACKAGED_SMOKE_SERVER_IDLE_SHUTDOWN_MS / 1000}s` }
+ : {}),
+ },
+ };
}
diff --git a/packages/desktop/tests/smoke/_helpers/smoke-test.ts b/packages/desktop/tests/smoke/_helpers/smoke-test.ts
index aa4986593..47eccb96d 100644
--- a/packages/desktop/tests/smoke/_helpers/smoke-test.ts
+++ b/packages/desktop/tests/smoke/_helpers/smoke-test.ts
@@ -2,7 +2,11 @@ import type { ChildProcess } from 'node:child_process';
import { rmSync } from 'node:fs';
import { expect as baseExpect, test as baseTest, type ElectronApplication } from '@playwright/test';
import { emitBootGapLines } from './boot-gap-emit';
-import { captureAppProcess, closeAppBounded, reapDetachedServers } from './electron-cleanup';
+import {
+ captureAppProcess,
+ cleanupIncompleteReport,
+ closeAppsThenAwaitServerRelease,
+} from './electron-cleanup';
import {
attachCapturedStderr,
captureElectronStderr,
@@ -37,18 +41,21 @@ export const test = baseTest.extend<SmokeFixtures>({
}
});
await emitBootGapLines(apps, testInfo);
- const unclosed: Error[] = [];
- for (const proc of procs) {
- try {
- await closeAppBounded(proc, { gracefulMs: 5_000 });
- } catch (error) {
- unclosed.push(error instanceof Error ? error : new Error(String(error)));
- }
+ const { unclosed, survivors, closedAfterServerRelease } = await closeAppsThenAwaitServerRelease(
+ procs,
+ cleanupDirs,
+ { gracefulMs: 5_000 },
+ );
+ for (const pid of closedAfterServerRelease) {
+ console.log(
+ `[smoke-test] app pid ${pid} closed only after the detached servers under its dirs released`,
+ );
}
- if (unclosed.length > 0) {
+ const report = cleanupIncompleteReport(unclosed, survivors);
+ if (report !== undefined) {
try {
await testInfo.attach('app-cleanup-incomplete', {
- body: unclosed.map((error) => error.message).join('\n\n'),
+ body: report,
contentType: 'text/plain',
});
} catch (error) {
@@ -56,7 +63,6 @@ export const test = baseTest.extend<SmokeFixtures>({
console.warn(`[smoke-test] cleanup-diagnostic attach failed: ${reason}`);
}
}
- reapDetachedServers(cleanupDirs);
for (const dir of cleanupDirs) {
try {
rmSync(dir, { recursive: true, force: true });
diff --git a/packages/desktop/tests/smoke/cold-single-file-launch.e2e.ts b/packages/desktop/tests/smoke/cold-single-file-launch.e2e.ts
index c6bb211e7..229062387 100644
--- a/packages/desktop/tests/smoke/cold-single-file-launch.e2e.ts
+++ b/packages/desktop/tests/smoke/cold-single-file-launch.e2e.ts
@@ -43,10 +43,9 @@ function quitAppCleanly(): void {
} catch {}
waitForExit();
if (appIsRunning()) {
- try {
- execFileSync('pkill', ['-x', APP_NAME], { stdio: 'pipe' });
- } catch {}
- waitForExit();
+ throw new Error(
+ `${APP_NAME} did not quit after the Apple-Event quit request, and this test does not stop apps by name`,
+ );
}
}
diff --git a/packages/desktop/tests/smoke/consent-dialog.e2e.ts b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
index 18cddb8bd..aa10183e9 100644
--- a/packages/desktop/tests/smoke/consent-dialog.e2e.ts
+++ b/packages/desktop/tests/smoke/consent-dialog.e2e.ts
@@ -118,7 +118,7 @@ test.describe('Consent-dialog smoke', () => {
test.afterEach(async () => {
const targets = cleanupTargets.splice(0);
- reapDetachedServers(targets);
+ await reapDetachedServers(targets);
for (const target of targets) {
try {
rmSync(target, { recursive: true, force: true });
@@ -133,7 +133,7 @@ test.describe('Consent-dialog smoke', () => {
trackForCleanup(tmpHome, projectDir);
const app = await launchApp(tmpHome, { pickedPath: projectDir });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavOpen(navigator);
@@ -160,7 +160,7 @@ test.describe('Consent-dialog smoke', () => {
trackForCleanup(tmpHome, projectDir);
const app = await launchApp(tmpHome, { pickedPath: projectDir });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavOpen(navigator);
@@ -187,7 +187,7 @@ test.describe('Consent-dialog smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedPath: subFolder });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavOpen(navigator);
diff --git a/packages/desktop/tests/smoke/create-new-project.e2e.ts b/packages/desktop/tests/smoke/create-new-project.e2e.ts
index 13792ef72..c540c2127 100644
--- a/packages/desktop/tests/smoke/create-new-project.e2e.ts
+++ b/packages/desktop/tests/smoke/create-new-project.e2e.ts
@@ -120,7 +120,7 @@ test.describe('Create-new-project smoke', () => {
test.afterEach(async () => {
const targets = cleanupTargets.splice(0);
- reapDetachedServers(targets);
+ await reapDetachedServers(targets);
for (const target of targets) {
try {
rmSync(target, { recursive: true, force: true });
@@ -139,7 +139,7 @@ test.describe('Create-new-project smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedParent: parent });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavCreateNew(navigator);
@@ -202,7 +202,7 @@ test.describe('Create-new-project smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedParent: subFolder });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavCreateNew(navigator);
@@ -239,7 +239,7 @@ test.describe('Create-new-project smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedParent });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavCreateNew(navigator);
@@ -300,7 +300,7 @@ test.describe('Create-new-project smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedParent: `${sub1}\x1f${sub2}` });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavCreateNew(navigator);
@@ -388,7 +388,7 @@ test.describe('Create-new-project smoke', () => {
trackForCleanup(tmpHome);
const app = await launchApp(tmpHome, { pickedParent });
- captureStderrFor(app, { home: tmpHome });
+ captureStderrFor(app, { home: tmpHome, cleanupDirs: cleanupTargets.splice(0) });
const navigator = await findWindowByMode(app, 'navigator');
await clickNavCreateNew(navigator);
diff --git a/packages/desktop/tests/unit/electron-cleanup-bounded.test.ts b/packages/desktop/tests/unit/electron-cleanup-bounded.test.ts
index 17c206358..3939c8062 100644
--- a/packages/desktop/tests/unit/electron-cleanup-bounded.test.ts
+++ b/packages/desktop/tests/unit/electron-cleanup-bounded.test.ts
@@ -1,7 +1,11 @@
import { type ChildProcess, spawn } from 'node:child_process';
import { EventEmitter } from 'node:events';
import type { ElectronApplication } from '@playwright/test';
-import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+ installSignalBoundary,
+ type SignalBoundary,
+} from '../../../../test-support/held-signal-boundary.test-helper';
import {
AppCleanupIncompleteError,
captureAppProcess,
@@ -417,6 +421,245 @@ describe('closeAppBounded — bounded-time process-group reap', () => {
});
});
+describe('closeAppBounded — nothing is signalled once the launched process has exited', () => {
+ let backstop: SignalBoundary;
+
+ beforeEach(() => {
+ backstop = installSignalBoundary({ deliverToHeldChildren: false });
+ });
+
+ afterEach(() => {
+ backstop.restore();
+ });
+
+ function withStdioHeldOpen(proc: MockProc): MockProc {
+ proc.stdio = [{ destroyed: false }, { destroyed: false }, { destroyed: false }];
+ return proc;
+ }
+
+ function recordingKill() {
+ const calls: MockProc['killCalls'] = [];
+ const kill = (pid: number, signal: NodeJS.Signals | string) => {
+ calls.push({ pid, signal });
+ };
+ return { calls, kill };
+ }
+
+ test('exited at first sight while a descendant still holds its stdio → no group kill of the exited pid, and closure is reported unestablished', async () => {
+ const proc = withStdioHeldOpen(makeProc(31_313));
+ proc.exitCode = 0;
+ const { calls, kill } = recordingKill();
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 50,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).catch((error: unknown) => error);
+
+ expect({
+ killCalls: calls,
+ reported: rejection instanceof AppCleanupIncompleteError,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({ killCalls: [], reported: true, reachedProcessKill: [] });
+ });
+
+ test('exited at first sight on win32 while a descendant still holds its stdio → no tree-kill of the exited pid, and closure is reported unestablished', async () => {
+ const proc = withStdioHeldOpen(makeProc(31_314));
+ proc.exitCode = 0;
+ const { calls, kill } = recordingKill();
+ const taskkillPids: number[] = [];
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 50,
+ postKillReapMs: REAP_MS,
+ kill,
+ taskkill: async (pid) => {
+ taskkillPids.push(pid);
+ return reapedTaskkill(pid);
+ },
+ platform: 'win32',
+ }).catch((error: unknown) => error);
+
+ expect({
+ taskkillPids,
+ killCalls: calls,
+ reported: rejection instanceof AppCleanupIncompleteError,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({ taskkillPids: [], killCalls: [], reported: true, reachedProcessKill: [] });
+ });
+
+ test('exits during the graceful wait while a descendant still holds its stdio → no group kill after the exit', async () => {
+ const proc = withStdioHeldOpen(makeProc(31_315));
+ const exitTimer = setTimeout(() => proc.fireExitWithoutClose(0), 10);
+ (exitTimer as unknown as { unref?: () => void }).unref?.();
+ const { calls, kill } = recordingKill();
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 100,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).catch((error: unknown) => error);
+
+ expect({
+ exitedBeforeEscalation: proc.exitCode === 0,
+ killCalls: calls,
+ reported: rejection instanceof AppCleanupIncompleteError,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ exitedBeforeEscalation: true,
+ killCalls: [],
+ reported: true,
+ reachedProcessKill: [],
+ });
+ });
+
+ test('a group kill that stops the launched process but not its stdio holder is not repeated after the exit', async () => {
+ const proc = withStdioHeldOpen(makeProc(31_317));
+ const calls: MockProc['killCalls'] = [];
+ const kill = (pid: number, signal: NodeJS.Signals | string) => {
+ calls.push({ pid, signal });
+ if (proc.exitCode === null && proc.signalCode === null) {
+ proc.signalCode = 'SIGKILL';
+ proc.emit('exit', null, 'SIGKILL');
+ }
+ };
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 50,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).catch((error: unknown) => error);
+
+ expect({
+ killCalls: calls,
+ reported: rejection instanceof AppCleanupIncompleteError,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ killCalls: [{ pid: -31_317, signal: 'SIGKILL' }],
+ reported: true,
+ reachedProcessKill: [],
+ });
+ });
+
+ function leversOf(outcome: unknown): unknown {
+ return outcome instanceof AppCleanupIncompleteError
+ ? outcome.attempts.map((attempt) => attempt.lever)
+ : outcome;
+ }
+
+ test.each(['linux', 'win32'] as const)(
+ "records a 'leader-exited' attempt in every escalation round on %s when the launched process exited while a descendant holds its stdio",
+ async (platform) => {
+ const proc = withStdioHeldOpen(makeProc(31_319));
+ proc.exitCode = 0;
+ const { calls, kill } = recordingKill();
+ const taskkillPids: number[] = [];
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 50,
+ postKillReapMs: REAP_MS,
+ kill,
+ taskkill: async (pid) => {
+ taskkillPids.push(pid);
+ return reapedTaskkill(pid);
+ },
+ platform,
+ }).catch((error: unknown) => error);
+
+ expect({
+ levers: leversOf(rejection),
+ killCalls: calls,
+ taskkillPids,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ levers: ['leader-exited', 'leader-exited'],
+ killCalls: [],
+ taskkillPids: [],
+ reachedProcessKill: [],
+ });
+ },
+ );
+
+ test("records 'leader-exited' for the round after a group kill stopped the launched process, instead of a second kill", async () => {
+ const proc = withStdioHeldOpen(makeProc(31_321));
+ const calls: MockProc['killCalls'] = [];
+ const kill = (pid: number, signal: NodeJS.Signals | string) => {
+ calls.push({ pid, signal });
+ if (proc.exitCode === null && proc.signalCode === null) {
+ proc.signalCode = 'SIGKILL';
+ proc.emit('exit', null, 'SIGKILL');
+ }
+ };
+
+ const rejection = await closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs: 50,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).catch((error: unknown) => error);
+
+ expect({
+ levers: leversOf(rejection),
+ killCalls: calls,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ levers: ['group-kill', 'leader-exited'],
+ killCalls: [{ pid: -31_321, signal: 'SIGKILL' }],
+ reachedProcessKill: [],
+ });
+ });
+
+ test("a 'leader-exited' round keeps its reap window, so a stdio holder that lets go inside it ends the call as closed", async () => {
+ vi.useFakeTimers();
+ try {
+ const gracefulMs = 50;
+ const proc = withStdioHeldOpen(makeProc(31_320));
+ proc.exitCode = 0;
+ const { calls, kill } = recordingKill();
+ let outcome = 'pending';
+ const settled = closeAppBounded(proc as unknown as ChildProcess, {
+ gracefulMs,
+ postKillReapMs: REAP_MS,
+ kill,
+ platform: 'linux',
+ }).then(
+ () => {
+ outcome = 'closed';
+ },
+ () => {
+ outcome = 'reported-incomplete';
+ },
+ );
+
+ await vi.advanceTimersByTimeAsync(gracefulMs);
+ const afterFirstRound = outcome;
+ for (const slot of proc.stdio) {
+ if (slot !== null && slot !== undefined) slot.destroyed = true;
+ }
+ proc.fireClose();
+ await vi.runAllTimersAsync();
+ await settled;
+
+ expect({
+ afterFirstRound,
+ outcome,
+ killCalls: calls,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ afterFirstRound: 'pending',
+ outcome: 'closed',
+ killCalls: [],
+ reachedProcessKill: [],
+ });
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
+
interface FakeTaskkillChild extends EventEmitter {
stdout: EventEmitter;
stderr: EventEmitter;
diff --git a/packages/desktop/tests/utility/pty-host-reap.test.ts b/packages/desktop/tests/utility/pty-host-reap.test.ts
index 94e9f308f..6515bbf71 100644
--- a/packages/desktop/tests/utility/pty-host-reap.test.ts
+++ b/packages/desktop/tests/utility/pty-host-reap.test.ts
@@ -46,18 +46,12 @@ async function assertNoOrphan(killSignal: 'SIGTERM' | 'SIGKILL'): Promise<void>
kill: (signal: NodeJS.Signals) => child.kill(signal),
exited: once(child, 'exit'),
};
- let shellPid: number | null = null;
try {
- shellPid = await readShellPid(proc.stdout, 20_000);
+ const shellPid = await readShellPid(proc.stdout, 20_000);
expect(isProcessAlive(shellPid)).toBe(true);
proc.kill(killSignal);
expect(await waitForReaped(shellPid, 10_000)).toBe(true);
} finally {
- if (shellPid !== null && isProcessAlive(shellPid)) {
- try {
- process.kill(shellPid, 'SIGKILL');
- } catch {}
- }
proc.kill('SIGKILL');
await proc.exited;
}
diff --git a/packages/server/src/acp/launch-package-acquisition.test.ts b/packages/server/src/acp/launch-package-acquisition.test.ts
index c3e8c8343..8783ce85b 100644
--- a/packages/server/src/acp/launch-package-acquisition.test.ts
+++ b/packages/server/src/acp/launch-package-acquisition.test.ts
@@ -270,13 +270,14 @@ describe('hermetic package acquisition and native dispatch', () => {
installNodeFixture(bin);
const pidPath = join(home, 'probe.pid');
const observed = join(home, 'probe.json');
+ const HUNG_NPM_SELF_EXIT_MS = 240_000;
writeExecutable(join(bin, 'npx'), 'process.exit(0);');
const response =
mode === 'malformed'
? "process.stdout.write('{not-json');"
: mode === 'overflow'
? "process.stdout.write('x'.repeat(32 * 1024 * 1024));"
- : 'setInterval(() => {}, 1000);';
+ : `setTimeout(() => process.exit(0), ${HUNG_NPM_SELF_EXIT_MS});`;
writeExecutable(
join(bin, 'npm'),
`require('node:fs').writeFileSync(${JSON.stringify(pidPath)}, String(process.pid));
@@ -284,27 +285,20 @@ describe('hermetic package acquisition and native dispatch', () => {
${response}`,
);
let pid: number | undefined;
- try {
- const result = await resolveRegistryLaunch(
- registryPackage('[email protected]', 'npx', { PATH: bin }),
- null,
- log,
- ).catch((error: unknown) => error);
- if (existsSync(pidPath)) pid = Number(readFileSync(pidPath, 'utf8'));
- expect(result).toBeInstanceOf(AgentLaunchError);
- expect(result).toMatchObject({ code: 'install-failed' });
- const probe = JSON.parse(readFileSync(observed, 'utf8'));
- expect(probe.cwd).toBe(join(home, '.ok', 'acp-npx-cwd'));
- expect(probe.args).toContain('--ignore-scripts');
- expect(() => process.kill(pid ?? 0, 0)).toThrow();
- expect(String(result).length).toBeLessThan(20_000);
- } finally {
- if (pid !== undefined) {
- try {
- process.kill(pid, 'SIGKILL');
- } catch {}
- }
- }
+ const result = await resolveRegistryLaunch(
+ registryPackage('[email protected]', 'npx', { PATH: bin }),
+ null,
+ log,
+ ).catch((error: unknown) => error);
+ if (existsSync(pidPath)) pid = Number(readFileSync(pidPath, 'utf8'));
+ expect(result).toBeInstanceOf(AgentLaunchError);
+ expect(result).toMatchObject({ code: 'install-failed' });
+ const probe = JSON.parse(readFileSync(observed, 'utf8'));
+ expect(probe.cwd).toBe(join(home, '.ok', 'acp-npx-cwd'));
+ expect(probe.args).toContain('--ignore-scripts');
+ if (pid === undefined) throw new Error('the npm fixture recorded no pid');
+ expect(() => process.kill(pid, 0)).toThrow();
+ expect(String(result).length).toBeLessThan(20_000);
});
},
120_000,
diff --git a/packages/server/src/acp/launch.test.ts b/packages/server/src/acp/launch.test.ts
index 7d0252a59..bff04c7a5 100644
--- a/packages/server/src/acp/launch.test.ts
+++ b/packages/server/src/acp/launch.test.ts
@@ -1,4 +1,4 @@
-import { execFileSync } from 'node:child_process';
+import { type ChildProcess, execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import {
existsSync,
@@ -15,7 +15,6 @@ import { delimiter, join } from 'node:path';
import { OK_HOSTED_AGENT_ENV } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { getLogger, type PinoLogger } from '../logger.ts';
-import { isValidLockPid } from '../process-alive.ts';
import { withLocalAcquisitionRegistry } from './acquisition-contract.test-helper.ts';
import { createDiagnosticStderrCapture } from './diagnostics.ts';
import {
@@ -348,7 +347,8 @@ async function waitFor(pred: () => boolean, ms: number, what: string): Promise<v
}
let dirs: string[] = [];
-let strayPids: number[] = [];
+let strayChildren: ChildProcess[] = [];
+const GRANDCHILD_SELF_EXIT_MS = 60_000;
const log = getLogger('acp-launch-test');
function tmp(): string {
const d = mkdtempSync(join(tmpdir(), 'acp-launch-test-'));
@@ -356,13 +356,8 @@ function tmp(): string {
return d;
}
afterEach(() => {
- for (const pid of strayPids) {
- if (!isValidLockPid(pid)) continue;
- try {
- process.kill(pid, 'SIGKILL');
- } catch {}
- }
- strayPids = [];
+ for (const child of strayChildren) child.kill('SIGKILL');
+ strayChildren = [];
for (const d of dirs) rmSync(d, { recursive: true, force: true });
dirs = [];
});
@@ -839,7 +834,7 @@ describe('hosted-agent marker', () => {
].join('\n'),
);
const child = spawnAcpAgent(launchFor(script), dir);
- if (child.pid !== undefined) strayPids.push(child.pid);
+ if (child.pid !== undefined) strayChildren.push(child);
await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its env');
expect(readFileSync(`${script}.out`, 'utf8')).toBe('1');
});
@@ -873,7 +868,7 @@ describe('spawnAcpAgent — cwd isolation for npx launches', () => {
spawnNpxWithProjectCwd(launch, dir);
}).toThrow('spawnAcpAgent does not accept a project cwd for npx launches.');
const child = spawnAcpAgent(launch);
- if (child.pid !== undefined) strayPids.push(child.pid);
+ if (child.pid !== undefined) strayChildren.push(child);
await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its cwd');
const observed = readFileSync(`${script}.out`, 'utf8');
expect(observed).not.toBe(dir);
@@ -911,7 +906,7 @@ describe('spawnAcpAgent — cwd isolation for npx launches', () => {
pathFromOverlay: false,
};
const child = spawnAcpAgent(launch, dir);
- if (child.pid !== undefined) strayPids.push(child.pid);
+ if (child.pid !== undefined) strayChildren.push(child);
await waitFor(() => existsSync(`${script}.out`), 10_000, 'spawned agent to report its cwd');
const observed = readFileSync(`${script}.out`, 'utf8');
expect(observed.endsWith(dir) || dir.endsWith(observed)).toBe(true);
@@ -1046,7 +1041,7 @@ describe.skipIf(process.platform === 'win32')('probeInterpreterHealth', () => {
const kidPidFile = join(dir, 'kid.pid');
writeFileSync(
join(dir, 'npx'),
- `#!/bin/sh\n(while : ; do /bin/sleep 0.05; done) &\necho $! > ${kidPidFile}\nwait\n`,
+ `#!/bin/sh\n(n=0; while [ "$n" -lt ${GRANDCHILD_SELF_EXIT_MS / 50} ]; do /bin/sleep 0.05; n=$((n + 1)); done) &\necho $! > ${kidPidFile}\nwait\n`,
{ mode: 0o755 },
);
const launch: ResolvedLaunch = {
@@ -1074,7 +1069,6 @@ describe.skipIf(process.platform === 'win32')('probeInterpreterHealth', () => {
'the fixture to publish its grandchild pid',
);
kidPid = Number(publishedKidPid());
- strayPids.push(kidPid);
expect(
settledEarly,
@@ -1310,7 +1304,7 @@ describe('terminateAgentTree', () => {
const script = join(dir, 'compliant.mjs');
writeFileSync(script, 'setInterval(() => {}, 1000);\n');
const child = spawnAcpAgent(launchFor(script), dir);
- if (child.pid !== undefined) strayPids.push(child.pid);
+ if (child.pid !== undefined) strayChildren.push(child);
await waitFor(() => child.pid !== undefined, 2_000, 'spawn');
const dead = await terminateAgentTree(child, { graceMs: 3_000 });
@@ -1331,7 +1325,7 @@ describe('terminateAgentTree', () => {
"process.on('SIGTERM', () => {});",
'const kid = spawn(process.execPath, [',
" '-e',",
- ' "process.on(\'SIGTERM\', () => {}); setInterval(() => {}, 1000);",',
+ ` "process.on('SIGTERM', () => {}); setTimeout(() => process.exit(0), ${GRANDCHILD_SELF_EXIT_MS});",`,
"], { stdio: 'ignore' });",
'writeFileSync(process.env.KID_PID_FILE, String(kid.pid));',
'setInterval(() => {}, 1000);',
@@ -1339,10 +1333,9 @@ describe('terminateAgentTree', () => {
].join('\n'),
);
const child = spawnAcpAgent(launchFor(script, { KID_PID_FILE: kidPidFile }), dir);
- if (child.pid !== undefined) strayPids.push(child.pid);
+ if (child.pid !== undefined) strayChildren.push(child);
await waitFor(() => existsSync(kidPidFile), 5_000, 'grandchild pid file');
const kidPid = Number(readFileSync(kidPidFile, 'utf8'));
- strayPids.push(kidPid);
expect(Number.isInteger(kidPid) && kidPid > 0).toBe(true);
expect(isAlive(kidPid)).toBe(true);
diff --git a/packages/server/src/acp/thread-manager.integration.test.ts b/packages/server/src/acp/thread-manager.integration.test.ts
index 1afb06f14..8140c412c 100644
--- a/packages/server/src/acp/thread-manager.integration.test.ts
+++ b/packages/server/src/acp/thread-manager.integration.test.ts
@@ -5551,6 +5551,7 @@ describe('diagnostic stream lifetime', () => {
const localDir = tmp();
const id = 'resume-after-close';
const pidFile = join(localDir, 'resumed-pid');
+ const RESUMED_AGENT_SELF_EXIT_MS = 30_000;
writeResumableAgentEntry(localDir, id, { FAKE_CAPS: 'resume' });
const release = Promise.withResolvers<string | null>();
const entered = Promise.withResolvers<void>();
@@ -5573,7 +5574,7 @@ describe('diagnostic stream lifetime', () => {
`
import { writeFileSync } from 'node:fs';
writeFileSync(${JSON.stringify(pidFile)}, String(process.pid));
- setInterval(() => {}, 1000);
+ setTimeout(() => process.exit(0), ${RESUMED_AGENT_SELF_EXIT_MS});
process.stdin.once('data', (chunk) => {
const msg = JSON.parse(chunk.toString());
process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id,
@@ -5587,51 +5588,31 @@ describe('diagnostic stream lifetime', () => {
await manager.closeThread(info.threadId);
expect(manager.getInfo(info.threadId)?.archived).toBe(true);
release.resolve(null);
- try {
- expect(await resumed).toMatchObject({ code: 'spawn-failed' });
- const pid = Number(readFileSync(pidFile, 'utf8'));
- expect(
- isValidLockPid(pid),
- `resumed-pid held ${JSON.stringify(readFileSync(pidFile, 'utf8'))}`,
- ).toBe(true);
- await expect
- .poll(
- () => {
- try {
- process.kill(pid, 0);
- return true;
- } catch {
- return false;
- }
- },
- { timeout: 3000 },
- )
- .toBe(false);
- const replay: ThreadEvent[] = [];
- await manager.subscribe(info.threadId, 0, (frame) => {
- if (frame.op === 'event') replay.push(frame.event);
- if (frame.op === 'events') replay.push(...frame.events);
- });
- expect(replay.at(-1)).toMatchObject({ kind: 'status', detail: 'thread closed' });
- } finally {
- if (existsSync(pidFile)) {
- const raw = readFileSync(pidFile, 'utf8');
- const pid = Number(raw);
- if (isValidLockPid(pid)) {
+ expect(await resumed).toMatchObject({ code: 'spawn-failed' });
+ const pid = Number(readFileSync(pidFile, 'utf8'));
+ expect(
+ isValidLockPid(pid),
+ `resumed-pid held ${JSON.stringify(readFileSync(pidFile, 'utf8'))}`,
+ ).toBe(true);
+ await expect
+ .poll(
+ () => {
try {
- process.kill(pid, 'SIGKILL');
- } catch {}
- } else {
- console.warn(
- `[resume-after-close cleanup] left a spawned child unreaped: ${pidFile} held ${JSON.stringify(raw)}, which isValidLockPid rejects`,
- );
- }
- } else {
- console.warn(
- `[resume-after-close cleanup] no pidfile at ${pidFile}: either the resume failed before spawning, or a child was spawned and this test threw before the child's first write — in that case it is still running`,
- );
- }
- }
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+ },
+ { timeout: 3000 },
+ )
+ .toBe(false);
+ const replay: ThreadEvent[] = [];
+ await manager.subscribe(info.threadId, 0, (frame) => {
+ if (frame.op === 'event') replay.push(frame.event);
+ if (frame.op === 'events') replay.push(...frame.events);
+ });
+ expect(replay.at(-1)).toMatchObject({ kind: 'status', detail: 'thread closed' });
}, 15_000);
test.each(['prompt', 'resume'] as const)(
diff --git a/packages/server/src/git-worktree-status.test.ts b/packages/server/src/git-worktree-status.test.ts
index 56179094d..76f60d344 100644
--- a/packages/server/src/git-worktree-status.test.ts
+++ b/packages/server/src/git-worktree-status.test.ts
@@ -695,9 +695,6 @@ describe('readWorktreeStatus — the panel listing is trustworthy', () => {
expect(readSpawnedPids(pidFile).filter(isProcessAlive)).toEqual([]);
});
} finally {
- for (const pid of readSpawnedPids(pidFile)) {
- if (isProcessAlive(pid)) process.kill(pid, 'SIGKILL');
- }
process.env.PATH = realPath;
errorSpy.mockRestore();
warnSpy.mockRestore();
diff --git a/packages/server/src/lint-plugins/no-sentinel-signal-target.test.ts b/packages/server/src/lint-plugins/no-sentinel-signal-target.test.ts
index ad29b6168..416d87600 100644
--- a/packages/server/src/lint-plugins/no-sentinel-signal-target.test.ts
+++ b/packages/server/src/lint-plugins/no-sentinel-signal-target.test.ts
@@ -36,7 +36,7 @@ describe('no-sentinel-signal-target oxlint rule', () => {
expect(fires.length).toBe(20);
const literal = fires.filter((d) => d.message.includes('Signal only a pid you spawned'));
const fallback = fires.filter((d) => d.message.includes('Filter the nullable pid out'));
- const parsed = fires.filter((d) => d.message.includes('Validate it with `isValidLockPid()`'));
+ const parsed = fires.filter((d) => d.message.includes('Signal the `ChildProcess` you spawned'));
expect(literal.length).toBe(10);
expect(fallback.length).toBe(4);
expect(parsed.length).toBe(6);
@@ -59,6 +59,18 @@ describe('no-sentinel-signal-target oxlint rule', () => {
expect(readme).toContain('only if you spawned it detached');
});
+ test('the parsed remedy names the handle you spawned and, for a pid you hold no handle for, its owner or a report, in the diagnostic and the README alike', () => {
+ const parsed = lintFixture().filter((d) =>
+ d.message.includes('Signal the `ChildProcess` you spawned'),
+ );
+ expect(parsed.length).toBe(6);
+ for (const fire of parsed) {
+ expect(fire.message).toContain('stop that process through its owner, or report it');
+ }
+ const readme = readFileSync(join(REPO_ROOT, README_REL), 'utf8');
+ expect(readme).toContain('Stop that process through its owner, or report it');
+ });
+
test('every fire lands on a positive case and none on the negatives', () => {
const source = readFileSync(join(REPO_ROOT, FIXTURE_REL), 'utf8').split('\n');
const firedLines = lintFixture()
diff --git a/scripts/check-i18n-drift.sh b/scripts/check-i18n-drift.sh
index 7fd6e9552..e035073df 100755
--- a/scripts/check-i18n-drift.sh
+++ b/scripts/check-i18n-drift.sh
@@ -11,13 +11,13 @@ LOCALES_DIR="packages/app/src/locales"
SNAPSHOT_ROOT="$(mktemp -d)"
SNAPSHOT_READY=0
CATALOGS_SETTLED=0
-EXTRACT_PID=''
+EXTRACTING=0
STAGED_RESTORE="$REPO_ROOT/$LOCALES_DIR.restore.$$"
restore_catalogs() {
set +e
- if [ -n "$EXTRACT_PID" ]; then
- kill -- "-$EXTRACT_PID" 2>/dev/null
- wait "$EXTRACT_PID" 2>/dev/null
+ if [ "$EXTRACTING" -eq 1 ]; then
+ kill -TERM %1 2>/dev/null
+ wait %1 2>/dev/null
fi
if [ "$SNAPSHOT_READY" -eq 1 ] && [ "$CATALOGS_SETTLED" -eq 0 ]; then
rm -rf "${STAGED_RESTORE:?}"
@@ -41,12 +41,12 @@ cd "$REPO_ROOT"
UNTRACKED_BEFORE="$(git ls-files --others --exclude-standard -- "$LOCALES_DIR")"
cd "$REPO_ROOT/packages/app"
-set -m
-pnpm run --silent i18n >/dev/null &
-EXTRACT_PID=$!
-set +m
-wait "$EXTRACT_PID"
-EXTRACT_PID=''
+node "$SCRIPT_DIR/run-in-own-process-group.mjs" pnpm run --silent i18n >/dev/null &
+EXTRACTING=1
+extract_status=0
+wait %1 || extract_status=$?
+EXTRACTING=0
+[ "$extract_status" -eq 0 ] || exit "$extract_status"
cd "$REPO_ROOT"
UNTRACKED_AFTER="$(git ls-files --others --exclude-standard -- "$LOCALES_DIR")"
diff --git a/scripts/run-in-own-process-group.mjs b/scripts/run-in-own-process-group.mjs
new file mode 100644
index 000000000..b9fa36aaa
--- /dev/null
+++ b/scripts/run-in-own-process-group.mjs
@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { constants } from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+const RELAYED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+export function relayToHeldGroup(child, signal, send = process.kill.bind(process)) {
+ if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) return;
+ try {
+ send(-child.pid, signal);
+ } catch (error) {
+ if (error?.code === 'ESRCH') return;
+ if (error?.code !== 'EPERM') throw error;
+ process.stderr.write(
+ `relaying ${signal} to process group ${child.pid} reported EPERM; treating the group as already gone\n`,
+ );
+ }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+ const [command, ...args] = process.argv.slice(2);
+ const onWindows = process.platform === 'win32';
+ const child = onWindows
+ ? spawn([command, ...args].join(' '), { shell: true, stdio: 'inherit' })
+ : spawn(command, args, { detached: true, stdio: 'inherit' });
+ const relay = (signal) => relayToHeldGroup(child, signal);
+ if (!onWindows) {
+ for (const signal of RELAYED_SIGNALS) process.on(signal, relay);
+ }
+ child.on('exit', (code, signal) => {
+ for (const relayed of RELAYED_SIGNALS) process.off(relayed, relay);
+ process.exitCode = signal === null ? code : 128 + constants.signals[signal];
+ });
+ child.on('error', (error) => {
+ process.stderr.write(`${error.message}\n`);
+ process.exitCode = 1;
+ });
+}
diff --git a/scripts/run-in-own-process-group.test.mjs b/scripts/run-in-own-process-group.test.mjs
new file mode 100644
index 000000000..d9f1142ee
--- /dev/null
+++ b/scripts/run-in-own-process-group.test.mjs
@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { installSignalBoundary } from '../test-support/held-signal-boundary.test-helper.ts';
+
+const [runner = {}] = Object.values(
+ import.meta.glob('./run-in-own-process-group.mjs', { eager: true }),
+);
+const { relayToHeldGroup } = runner;
+
+const CHILD_PID = 424_242;
+
+let backstop;
+
+beforeEach(() => {
+ backstop = installSignalBoundary({ deliverToHeldChildren: false });
+});
+
+afterEach(() => {
+ backstop.restore();
+});
+
+function recordingSend() {
+ const sent = [];
+ return {
+ sent,
+ send: (target, signal) => {
+ sent.push([target, signal]);
+ return true;
+ },
+ };
+}
+
+describe('relayToHeldGroup relays a signal only while the child it spawned is unreaped', () => {
+ test.each([
+ ['exits with a code', { exitCode: 0, signalCode: null }],
+ ['is killed by a signal', { exitCode: null, signalCode: 'SIGKILL' }],
+ ])(
+ 'relays to the group of a running child, and sends nothing once the child %s',
+ (_label, exit) => {
+ expect(typeof relayToHeldGroup).toBe('function');
+ const { sent, send } = recordingSend();
+ const child = { pid: CHILD_PID, exitCode: null, signalCode: null };
+
+ relayToHeldGroup(child, 'SIGTERM', send);
+ Object.assign(child, exit);
+ relayToHeldGroup(child, 'SIGINT', send);
+
+ expect({ sent, reachedProcessKill: backstop.refused }).toEqual({
+ sent: [[-CHILD_PID, 'SIGTERM']],
+ reachedProcessKill: [],
+ });
+ },
+ );
+
+ test('sends nothing for a child that never received a pid', () => {
+ expect(typeof relayToHeldGroup).toBe('function');
+ const { sent, send } = recordingSend();
+
+ relayToHeldGroup({ pid: undefined, exitCode: null, signalCode: null }, 'SIGHUP', send);
+ relayToHeldGroup({ pid: CHILD_PID, exitCode: null, signalCode: null }, 'SIGHUP', send);
+
+ expect({ sent, reachedProcessKill: backstop.refused }).toEqual({
+ sent: [[-CHILD_PID, 'SIGHUP']],
+ reachedProcessKill: [],
+ });
+ });
+});
+
+function relayRefusedWith(code) {
+ const sent = [];
+ const send = (target, signal) => {
+ sent.push([target, signal]);
+ throw Object.assign(new Error(`kill ${code}`), { code });
+ };
+ const written = [];
+ const write = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+ written.push(String(chunk));
+ return true;
+ });
+ try {
+ relayToHeldGroup({ pid: CHILD_PID, exitCode: null, signalCode: null }, 'SIGTERM', send);
+ return { escaped: null, sent, stderr: written.join('') };
+ } catch (error) {
+ return { escaped: error.code, sent, stderr: written.join('') };
+ } finally {
+ write.mockRestore();
+ }
+}
+
+describe('relayToHeldGroup keeps a send refused because the group is already gone inside the relay', () => {
+ test.each([
+ ['ESRCH', false],
+ ['EPERM', true],
+ ])(
+ 'a send refused with %s does not escape the relay (reported on stderr: %s)',
+ (code, reported) => {
+ expect(typeof relayToHeldGroup).toBe('function');
+
+ const outcome = relayRefusedWith(code);
+
+ expect({
+ escaped: outcome.escaped,
+ sent: outcome.sent,
+ stderr: outcome.stderr,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ escaped: null,
+ sent: [[-CHILD_PID, 'SIGTERM']],
+ stderr: reported ? expect.stringContaining(code) : '',
+ reachedProcessKill: [],
+ });
+ },
+ );
+
+ test('a send refused for any other reason still escapes the relay', () => {
+ expect(typeof relayToHeldGroup).toBe('function');
+
+ const outcome = relayRefusedWith('EINVAL');
+
+ expect({
+ escaped: outcome.escaped,
+ sent: outcome.sent,
+ stderr: outcome.stderr,
+ reachedProcessKill: backstop.refused,
+ }).toEqual({
+ escaped: 'EINVAL',
+ sent: [[-CHILD_PID, 'SIGTERM']],
+ stderr: '',
+ reachedProcessKill: [],
+ });
+ });
+});
diff --git a/test-support/held-signal-boundary.test-helper.ts b/test-support/held-signal-boundary.test-helper.ts
new file mode 100644
index 000000000..b93bf301b
--- /dev/null
+++ b/test-support/held-signal-boundary.test-helper.ts
@@ -0,0 +1,90 @@
+import type { ChildProcess } from 'node:child_process';
+
+type SignalArgument = NodeJS.Signals | string | number | undefined;
+
+interface SignalRecord {
+ target: number;
+ signal: SignalArgument;
+}
+
+export interface SignalBoundary {
+ hold<T extends ChildProcess>(child: T): T;
+ send(target: number, signal?: SignalArgument): true;
+ readonly refused: readonly SignalRecord[];
+ readonly delivered: readonly SignalRecord[];
+ readonly probes: readonly SignalRecord[];
+ readonly selfSignals: readonly SignalRecord[];
+ restore(): void;
+}
+
+let active: SignalBoundary | undefined;
+
+function isProbe(signal: SignalArgument): boolean {
+ return signal === 0 || signal === '0';
+}
+
+function heldAndUnreaped(held: ReadonlySet<ChildProcess>, pid: number): boolean {
+ for (const child of held) {
+ if (child.pid === pid) return child.exitCode === null && child.signalCode === null;
+ }
+ return false;
+}
+
+export function installSignalBoundary(options: { deliverToHeldChildren: boolean }): SignalBoundary {
+ if (active !== undefined) {
+ throw new Error('a signal boundary is already installed; restore it before installing another');
+ }
+ const realKill = process.kill;
+ const held = new Set<ChildProcess>();
+ const refused: SignalRecord[] = [];
+ const delivered: SignalRecord[] = [];
+ const probes: SignalRecord[] = [];
+ const selfSignals: SignalRecord[] = [];
+
+ const send = (target: number, signal?: SignalArgument): true => {
+ const record = { target, signal };
+ if (!Number.isInteger(target) || Math.abs(target) <= 1) {
+ refused.push(record);
+ return true;
+ }
+ if (isProbe(signal)) {
+ probes.push(record);
+ return realKill.call(process, target, 0);
+ }
+ if (target === process.pid) {
+ selfSignals.push(record);
+ return true;
+ }
+ if (!options.deliverToHeldChildren || !heldAndUnreaped(held, Math.abs(target))) {
+ refused.push(record);
+ return true;
+ }
+ delivered.push(record);
+ return realKill.call(process, target, signal);
+ };
+
+ const boundary: SignalBoundary = {
+ hold(child) {
+ held.add(child);
+ return child;
+ },
+ send,
+ refused,
+ delivered,
+ probes,
+ selfSignals,
+ restore() {
+ if (active !== boundary) return;
+ process.kill = realKill;
+ active = undefined;
+ },
+ };
+
+ process.kill = send as typeof process.kill;
+ if (process.kill !== send) {
+ process.kill = realKill;
+ throw new Error('process.kill could not be replaced; refusing to run code that may signal');
+ }
+ active = boundary;
+ return boundary;
+}
diff --git a/test-support/held-signal-boundary.test.ts b/test-support/held-signal-boundary.test.ts
new file mode 100644
index 000000000..381e6f581
--- /dev/null
+++ b/test-support/held-signal-boundary.test.ts
@@ -0,0 +1,146 @@
+import type { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { installSignalBoundary, type SignalBoundary } from './held-signal-boundary.test-helper';
+
+const PID_BEYOND_ANY_KERNEL_LIMIT = 4_194_331;
+const SECOND_PID_BEYOND_ANY_KERNEL_LIMIT = 4_194_347;
+const THIRD_PID_BEYOND_ANY_KERNEL_LIMIT = 4_194_353;
+
+const originalKill = process.kill;
+let underlying: Array<[number, unknown]>;
+let underlyingSender: (target: number, signal?: unknown) => true;
+let boundary: SignalBoundary | undefined;
+
+beforeEach(() => {
+ underlying = [];
+ underlyingSender = (target, signal) => {
+ underlying.push([target, signal]);
+ return true;
+ };
+ process.kill = underlyingSender as typeof process.kill;
+ if (process.kill !== underlyingSender) {
+ process.kill = originalKill;
+ throw new Error('process.kill could not be stubbed; refusing to exercise the boundary');
+ }
+});
+
+afterEach(() => {
+ boundary?.restore();
+ boundary = undefined;
+ process.kill = originalKill;
+});
+
+function fakeChild(
+ pid: number,
+ state: { exitCode: number | null; signalCode: NodeJS.Signals | null },
+): ChildProcess {
+ return Object.assign(new EventEmitter(), { pid, ...state }) as unknown as ChildProcess;
+}
+
+describe('installSignalBoundary', () => {
+ test('replaces process.kill until restored, and refuses a second install', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ expect(process.kill).toBe(boundary.send);
+ expect(() => installSignalBoundary({ deliverToHeldChildren: true })).toThrow();
+ boundary.restore();
+ expect(process.kill).toBe(underlyingSender);
+ });
+
+ test('delivers a signal to a held child that has not been reaped, and to its group', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ boundary.hold(fakeChild(PID_BEYOND_ANY_KERNEL_LIMIT, { exitCode: null, signalCode: null }));
+
+ boundary.send(PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGTERM');
+ boundary.send(-PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL');
+
+ expect({ underlying, refused: boundary.refused }).toEqual({
+ underlying: [
+ [PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGTERM'],
+ [-PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL'],
+ ],
+ refused: [],
+ });
+ });
+
+ test('records without delivering a signal to a held child that exited or was killed', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ boundary.hold(fakeChild(PID_BEYOND_ANY_KERNEL_LIMIT, { exitCode: 0, signalCode: null }));
+ boundary.hold(
+ fakeChild(SECOND_PID_BEYOND_ANY_KERNEL_LIMIT, { exitCode: null, signalCode: 'SIGTERM' }),
+ );
+
+ boundary.send(-PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL');
+ boundary.send(SECOND_PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL');
+
+ expect({ underlying, refused: boundary.refused }).toEqual({
+ underlying: [],
+ refused: [
+ { target: -PID_BEYOND_ANY_KERNEL_LIMIT, signal: 'SIGKILL' },
+ { target: SECOND_PID_BEYOND_ANY_KERNEL_LIMIT, signal: 'SIGKILL' },
+ ],
+ });
+ });
+
+ test('records without delivering a signal to a pid it was never given', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ boundary.hold(fakeChild(PID_BEYOND_ANY_KERNEL_LIMIT, { exitCode: null, signalCode: null }));
+
+ boundary.send(THIRD_PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL');
+
+ expect({ underlying, refused: boundary.refused }).toEqual({
+ underlying: [],
+ refused: [{ target: THIRD_PID_BEYOND_ANY_KERNEL_LIMIT, signal: 'SIGKILL' }],
+ });
+ });
+
+ test('delivers nothing to a held, unreaped child when told to deliver to no child', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: false });
+ boundary.hold(fakeChild(PID_BEYOND_ANY_KERNEL_LIMIT, { exitCode: null, signalCode: null }));
+
+ boundary.send(PID_BEYOND_ANY_KERNEL_LIMIT, 'SIGKILL');
+
+ expect({ underlying, refused: boundary.refused.length }).toEqual({
+ underlying: [],
+ refused: 1,
+ });
+ });
+
+ test.each([0, 1, -1, 1.5, Number.NaN])(
+ 'records without delivering a signal to %p, which names no single process',
+ (target) => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+ boundary.hold(fakeChild(1, { exitCode: null, signalCode: null }));
+
+ boundary.send(target, 'SIGKILL');
+
+ expect({ underlying, refused: boundary.refused.length }).toEqual({
+ underlying: [],
+ refused: 1,
+ });
+ },
+ );
+
+ test('passes a liveness probe through without recording it as a signal', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: false });
+
+ boundary.send(PID_BEYOND_ANY_KERNEL_LIMIT, 0);
+
+ expect({ underlying, probes: boundary.probes.length, refused: boundary.refused }).toEqual({
+ underlying: [[PID_BEYOND_ANY_KERNEL_LIMIT, 0]],
+ probes: 1,
+ refused: [],
+ });
+ });
+
+ test('records without delivering a signal addressed to this process', () => {
+ boundary = installSignalBoundary({ deliverToHeldChildren: true });
+
+ boundary.send(process.pid, 'SIGTERM');
+
+ expect({ underlying, selfSignals: boundary.selfSignals.length }).toEqual({
+ underlying: [],
+ selfSignals: 1,
+ });
+ });
+});