@elench/testkit 0.1.113 → 0.1.115

package/lib/cli/assistant/app.mjs

@@ -1,7 +1,8 @@
 import React, { createElement, useEffect, useMemo, useRef, useState } from "react";
-import { Box, Text, useApp, useBoxMetrics, useCursor, useInput, useStdout } from "ink";
+import { Box, Text, useApp, useCursor, useInput, useStdout } from "ink";
 import { bold, cyan, dim, green, red, yellow } from "../terminal/colors.mjs";
 import { RunTreeView } from "../components/blocks/run-tree.mjs";
+import { useElementLayout } from "../components/hooks/use-element-layout.mjs";
 import { colorCodeLine } from "./code-block.mjs";
 import { getComposerDisplayModel } from "./composer.mjs";
 import { MarkdownBlock } from "./markdown-block.mjs";
@@ -370,7 +371,8 @@ function colorCommandStatus(block, status) {
 
 function ComposerBar({ view, busy }) {
   const ref = useRef(null);
-  const metrics = useBoxMetrics(ref);
+  const { stdout } = useStdout();
+  const metrics = useElementLayout(ref, { stdout });
   const { setCursorPosition } = useCursor();
   const display = getComposerDisplayModel(
     {

package/lib/cli/assistant/session.mjs

@@ -81,7 +81,11 @@ export async function runAssistantConversationTurn({
       onEvent(event) {
         appendProviderTrace(tracePath, event);
         onProviderEvent?.(event);
-        if (event.type === "status" || event.type === "tool-start" || event.type === "tool-update" || event.type === "tool-end") {
+        if (
+          event.display !== false &&
+          !event.transient &&
+          (event.type === "status" || event.type === "tool-start" || event.type === "tool-update" || event.type === "tool-end")
+        ) {
           onStatus?.(formatProviderEvent(event));
         }
       },

package/lib/cli/assistant/state.mjs

@@ -757,14 +757,13 @@ function createProviderTurnState() {
     assistantMessageId: null,
     assistantMessageIdsByProviderItem: new Map(),
     providerToolMessageIdsByProviderItem: new Map(),
-    lastActivityText: null,
+  lastActivityText: null,
   };
 }
 
 function handleProviderEvent(turn, event, { appendMessage, updateMessage, setStatus } = {}) {
   if (!event) return;
   if (event.transient || event.display === false) {
-    if (event.type === "status" && event.text) setStatus?.(event.text);
     return;
   }
   if (event.type === "assistant-delta") {

package/lib/cli/components/blocks/run-tree.mjs

@@ -1,5 +1,5 @@
 import React, { createElement, useEffect, useMemo, useState } from "react";
-import { Box, Text, useAnimation, useApp, useInput } from "ink";
+import { Box, Text, useApp, useInput } from "ink";
 import figures from "figures";
 import { formatDuration } from "../../../runner/formatting.mjs";
 import {
@@ -14,6 +14,7 @@ import {
 import { renderSummaryBox } from "../primitives/summary-box.mjs";
 import { getTerminalWidth } from "../../terminal/layout.mjs";
 import { renderFailureDetail, renderPassedDetail } from "../../renderers/run/inline-detail.mjs";
+import { useSpinnerFrame } from "../hooks/use-spinner-frame.mjs";
 
 const SPINNER_FRAMES = ["|", "/", "-", "\\"];
 
@@ -27,7 +28,11 @@ export function RunTreeView({
   const { exit } = useApp();
   const controlledSnapshot = Boolean(snapshotOverride);
   const [snapshot, setSnapshot] = useState(() => snapshotOverride || runState.getSnapshot());
-  const { frame } = useAnimation({ interval: 80, isActive: !controlledSnapshot && !snapshot.finished });
+  const frame = useSpinnerFrame({
+    frameCount: SPINNER_FRAMES.length,
+    intervalMs: 80,
+    isActive: !controlledSnapshot && !snapshot.finished,
+  });
   const spinnerFrame = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
 
   useEffect(() => {

package/lib/cli/components/hooks/use-element-layout.mjs

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+const EMPTY_LAYOUT = Object.freeze({
+  width: 0,
+  height: 0,
+  left: 0,
+  top: 0,
+  hasMeasured: false,
+});
+
+export function readElementLayout(ref) {
+  const node = ref?.current || null;
+  const rawLayout = node?.yogaNode?.getComputedLayout?.() || null;
+  if (!node || !rawLayout) return EMPTY_LAYOUT;
+
+  return {
+    width: normalizeLayoutNumber(rawLayout.width),
+    height: normalizeLayoutNumber(rawLayout.height),
+    left: normalizeLayoutNumber(rawLayout.left),
+    top: normalizeLayoutNumber(rawLayout.top),
+    hasMeasured: true,
+  };
+}
+
+export function layoutsEqual(left, right) {
+  return (
+    left.width === right.width &&
+    left.height === right.height &&
+    left.left === right.left &&
+    left.top === right.top &&
+    left.hasMeasured === right.hasMeasured
+  );
+}
+
+export function useElementLayout(ref, { stdout } = {}) {
+  const [layout, setLayout] = useState(EMPTY_LAYOUT);
+
+  const updateLayout = useCallback(() => {
+    const nextLayout = readElementLayout(ref);
+    setLayout((currentLayout) => layoutsEqual(currentLayout, nextLayout) ? currentLayout : nextLayout);
+  }, [ref]);
+
+  useEffect(updateLayout);
+
+  useEffect(() => {
+    if (!stdout?.on) return undefined;
+
+    stdout.on("resize", updateLayout);
+    return () => {
+      if (stdout.off) {
+        stdout.off("resize", updateLayout);
+        return;
+      }
+      stdout.removeListener?.("resize", updateLayout);
+    };
+  }, [stdout, updateLayout]);
+
+  return useMemo(() => layout, [layout]);
+}
+
+function normalizeLayoutNumber(value) {
+  return Number.isFinite(value) ? value : 0;
+}

package/lib/cli/components/hooks/use-spinner-frame.mjs

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "react";
+
+export function nextSpinnerFrame(frame, frameCount) {
+  const normalizedFrameCount = Number.isInteger(frameCount) && frameCount > 0 ? frameCount : 1;
+  return (frame + 1) % normalizedFrameCount;
+}
+
+export function useSpinnerFrame({
+  frameCount,
+  intervalMs = 80,
+  isActive = true,
+} = {}) {
+  const [frame, setFrame] = useState(0);
+
+  useEffect(() => {
+    if (!isActive) return undefined;
+
+    const timer = setInterval(() => {
+      setFrame((currentFrame) => nextSpinnerFrame(currentFrame, frameCount));
+    }, intervalMs);
+
+    return () => clearInterval(timer);
+  }, [frameCount, intervalMs, isActive]);
+
+  return frame;
+}

package/lib/playwright/index.d.ts

@@ -11,6 +11,7 @@ export declare function defineConfig<T extends Record<string, unknown>>(
   config: T,
   options?: PlaywrightConfigOptions
 ): T & {
+  globalTimeout?: number;
   timeout: number;
   expect: Record<string, unknown> & { timeout: number };
   use: Record<string, unknown> & {

package/lib/playwright/index.mjs

@@ -27,6 +27,7 @@ export function defineConfig(config = {}, options = {}) {
 
   return {
     ...config,
+    ...(managed ? { globalTimeout: timeoutMs } : {}),
     timeout: timeoutMs,
     expect: {
       ...(config.expect || {}),

package/lib/runner/default-runtime-runner.mjs

@@ -1,6 +1,5 @@
 import fs from "fs";
 import path from "path";
-import { execa } from "execa";
 import { bundleK6File } from "../bundler/index.mjs";
 import { resolveK6Binary } from "../config/binaries.mjs";
 import {
@@ -17,7 +16,7 @@ import { RUNTIME_ARTIFACT_MARKER } from "../runtime-src/k6/artifacts.js";
 import { readDatabaseUrl } from "./state-io.mjs";
 import { buildTaskExecutionEnv } from "./template.mjs";
 import { registerManagedProcess, unregisterManagedProcess } from "./managed-processes.mjs";
-import { killChildProcess } from "./processes.mjs";
+import { settleManagedSubprocess, startManagedSubprocess } from "./subprocess.mjs";
 
 export async function runHttpK6Task(targetConfig, task, lifecycle, lease, reporter = null) {
   const baseUrl = targetConfig.testkit.local?.baseUrl;
@@ -88,7 +87,7 @@ export async function runDefaultRuntimeTask(
   fs.mkdirSync(path.dirname(summaryFile), { recursive: true });
   const startedAt = Date.now();
   const fileTimeoutSeconds = targetConfig.testkit.execution.fileTimeoutSeconds;
-  const subprocess = execa(
+  const subprocess = startManagedSubprocess(
     k6Binary,
     [...args.slice(0, 1), "--summary-export", summaryFile, ...args.slice(1)],
     {
@@ -102,8 +101,6 @@ export async function runDefaultRuntimeTask(
         },
         process.env
       ),
-      reject: false,
-      forceKillAfterDelay: 5_000,
     }
   );
   registerManagedProcess(lifecycle, subprocess, "SIGINT");
@@ -111,7 +108,9 @@ export async function runDefaultRuntimeTask(
   let result;
   let timedOut;
   try {
-    ({ result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds));
+    ({ result, timedOut } = await settleManagedSubprocess(subprocess, {
+      timeoutMs: fileTimeoutSeconds * 1000 + 1_000,
+    }));
   } finally {
     unregisterManagedProcess(lifecycle, subprocess);
   }
@@ -170,28 +169,6 @@ export async function runDefaultRuntimeTask(
   };
 }
 
-export async function settleSubprocess(subprocess, fileTimeoutSeconds) {
-  const timeoutMs = fileTimeoutSeconds * 1000 + 1_000;
-  let timeoutHandle = null;
-  let timedOut = false;
-
-  try {
-    return await Promise.race([
-      subprocess.then((result) => ({ result, timedOut })),
-      new Promise((resolve) => {
-        timeoutHandle = setTimeout(async () => {
-          timedOut = true;
-          killChildProcess(subprocess, "SIGTERM");
-          const result = await subprocess.catch((error) => error);
-          resolve({ result, timedOut: true });
-        }, timeoutMs);
-      }),
-    ]);
-  } finally {
-    if (timeoutHandle) clearTimeout(timeoutHandle);
-  }
-}
-
 export function buildDefaultRuntimeSummaryPath(lease, task) {
   return path.join(lease.leaseDir, "default-runtime", `task-${task.id}.summary.json`);
 }

package/lib/runner/lifecycle.mjs

@@ -1,8 +1,8 @@
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
-import { execFileSync } from "child_process";
 import { destroyRuntimeDatabase, cleanupOrphanedLocalInfrastructure } from "../database/index.mjs";
+import { killProcessTree, listDescendantPids } from "./processes.mjs";
 
 const RUN_SCHEMA_VERSION = 1;
 const RUNS_DIRNAME = path.join(".testkit", "_runs");
@@ -297,22 +297,7 @@ async function terminateOwnedProcess(service) {
 }
 
 function killProcessGroup(pid, signal) {
-  try {
-    process.kill(-pid, signal);
-    return;
-  } catch (error) {
-    if (error?.code !== "ESRCH") {
-      // Fall through and try the direct pid.
-    } else {
-      return;
-    }
-  }
-
-  try {
-    process.kill(pid, signal);
-  } catch (error) {
-    if (error?.code !== "ESRCH") throw error;
-  }
+  killProcessTree(pid, signal);
 }
 
 function terminateDescendantProcesses(rootPid, signal) {
@@ -328,40 +313,6 @@ function terminateDescendantProcesses(rootPid, signal) {
   }
 }
 
-function listDescendantPids(rootPid) {
-  try {
-    const output = execFileSync("ps", ["-eo", "pid=,ppid="], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    });
-    const childrenByParent = new Map();
-    for (const line of output.split(/\r?\n/)) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      const [pidRaw, parentRaw] = trimmed.split(/\s+/);
-      const pid = Number(pidRaw);
-      const parentPid = Number(parentRaw);
-      if (!Number.isInteger(pid) || !Number.isInteger(parentPid)) continue;
-      const siblings = childrenByParent.get(parentPid) || [];
-      siblings.push(pid);
-      childrenByParent.set(parentPid, siblings);
-    }
-
-    const descendants = [];
-    const stack = [...(childrenByParent.get(rootPid) || [])];
-    while (stack.length > 0) {
-      const pid = stack.pop();
-      descendants.push(pid);
-      for (const childPid of childrenByParent.get(pid) || []) {
-        stack.push(childPid);
-      }
-    }
-    return descendants;
-  } catch {
-    return [];
-  }
-}
-
 async function waitForPidExit(pid, timeoutMs) {
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {

package/lib/runner/managed-processes.mjs

@@ -1,8 +1,9 @@
 import { killChildProcess } from "./processes.mjs";
+import { terminateSubprocess } from "./subprocess.mjs";
 
 export function registerManagedProcess(lifecycle, subprocess, signal = "SIGINT") {
   lifecycle.registerProcess(subprocess, () => {
-    killChildProcess(subprocess, signal);
+    void terminateSubprocess(subprocess, { gracefulSignal: signal });
   });
   if (lifecycle.isStopRequested()) {
     interruptManagedProcess(subprocess, signal);

package/lib/runner/playwright-config.mjs

@@ -3,7 +3,7 @@ import path from "path";
 import { pathToFileURL } from "url";
 import { normalizePathSeparators } from "./state.mjs";
 
-export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, lease) {
+export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, lease, options = {}) {
   if (!lease?.leaseDir) {
     throw new Error(
       `Playwright task for service "${targetConfig.name}" requires a lease-scoped directory`
@@ -17,6 +17,7 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
   const configPath = path.join(stateDir, "playwright.testkit.config.mjs");
   const baseConfigPath = findPlaywrightConfig(cwd);
   const normalizedFiles = requestedFiles.map(normalizePathSeparators);
+  const globalTimeoutMs = normalizeOptionalPositiveInteger(options.globalTimeoutMs, "globalTimeoutMs");
 
   let source = "";
   if (baseConfigPath) {
@@ -28,6 +29,7 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
       `  testDir: ${JSON.stringify(cwd)},\n` +
       `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
       `  outputDir: ${JSON.stringify(outputDir)},\n` +
+      (globalTimeoutMs ? `  globalTimeout: ${globalTimeoutMs},\n` : "") +
       `  workers: 1,\n` +
       `  fullyParallel: false,\n` +
       `  webServer: undefined,\n` +
@@ -38,6 +40,7 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
       `  testDir: ${JSON.stringify(cwd)},\n` +
       `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
       `  outputDir: ${JSON.stringify(outputDir)},\n` +
+      (globalTimeoutMs ? `  globalTimeout: ${globalTimeoutMs},\n` : "") +
       `  workers: 1,\n` +
       `  fullyParallel: false,\n` +
       `};\n`;
@@ -47,6 +50,15 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
   return configPath;
 }
 
+function normalizeOptionalPositiveInteger(value, label) {
+  if (value == null) return null;
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return normalized;
+}
+
 export function resolvePlaywrightOutputDir(stateDir) {
   return path.join(stateDir, "playwright-output");
 }

package/lib/runner/playwright-runner.mjs

@@ -1,14 +1,14 @@
 import path from "path";
-import { execa } from "execa";
+import fs from "fs";
 import { parsePlaywrightJsonResults } from "../reporters/playwright.mjs";
 import { resolveServiceCwd } from "../config/paths.mjs";
-import { formatFileTimeoutBudgetError } from "../shared/file-timeout.mjs";
+import { buildFileTimeoutEnv, formatFileTimeoutBudgetError } from "../shared/file-timeout.mjs";
 import { persistTaskOutputArtifacts } from "./artifacts.mjs";
-import { settleSubprocess } from "./default-runtime-runner.mjs";
 import { ensurePlaywrightTestConfig } from "./playwright-config.mjs";
 import { registerManagedProcess, unregisterManagedProcess } from "./managed-processes.mjs";
 import { normalizePathSeparators } from "./state.mjs";
 import { buildPlaywrightEnv } from "./template.mjs";
+import { settleManagedSubprocess, startManagedSubprocess } from "./subprocess.mjs";
 
 export async function runPlaywrightTask(targetConfig, task, lifecycle, lease, reporter = null) {
   const local = targetConfig.testkit.local;
@@ -20,20 +20,36 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease, re
 
   const cwd = resolveServiceCwd(targetConfig.productDir, local.cwd);
   const requestedFile = path.relative(cwd, path.join(targetConfig.productDir, task.file));
-  const playwrightConfigPath = ensurePlaywrightTestConfig(targetConfig, cwd, [requestedFile], lease);
   if (lifecycle.isStopRequested()) {
     throw new Error(`testkit run interrupted before starting ${task.file}`);
   }
   const startedAt = Date.now();
   const fileTimeoutSeconds = targetConfig.testkit.execution.fileTimeoutSeconds;
-  const subprocess = execa(
+  const playwrightConfigPath = ensurePlaywrightTestConfig(
+    targetConfig,
+    cwd,
+    [requestedFile],
+    lease,
+    { globalTimeoutMs: fileTimeoutSeconds * 1000 }
+  );
+  const jsonReportPath = buildPlaywrightJsonReportPath(lease, task);
+  const subprocess = startManagedSubprocess(
     "npx",
     ["playwright", "test", "--config", playwrightConfigPath, "--reporter=json"],
     {
       cwd,
-      env: buildPlaywrightEnv(targetConfig, local.baseUrl, lease, process.env),
-      reject: false,
-      forceKillAfterDelay: 5_000,
+      env: {
+        ...buildPlaywrightEnv(
+          targetConfig,
+          local.baseUrl,
+          lease,
+          {
+            ...process.env,
+            ...buildFileTimeoutEnv(fileTimeoutSeconds, startedAt),
+          }
+        ),
+        PLAYWRIGHT_JSON_OUTPUT_FILE: jsonReportPath,
+      },
     }
   );
   registerManagedProcess(lifecycle, subprocess, "SIGINT");
@@ -41,17 +57,30 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease, re
   let result;
   let timedOut;
   try {
-    ({ result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds));
+    ({ result, timedOut } = await settleManagedSubprocess(subprocess, {
+      timeoutMs: fileTimeoutSeconds * 1000 + 1_000,
+    }));
   } finally {
     unregisterManagedProcess(lifecycle, subprocess);
   }
 
-  const parsed = parsePlaywrightJsonResults(result.stdout || "", cwd);
+  const jsonReport = readOptionalText(jsonReportPath);
+  const stdoutReport = jsonReport ? "" : extractJsonReportFromStdout(result.stdout || "");
+  const parsed = parsePlaywrightJsonResults(jsonReport || stdoutReport, cwd);
   const finishedAt = Date.now();
   const durationMs = finishedAt - startedAt;
   const relativeFile = normalizePathSeparators(requestedFile);
   const fileResult = parsed.fileResults.get(relativeFile);
   const outputArtifacts = persistTaskOutputArtifacts(targetConfig.productDir, task, [
+    result.stdout
+      ? {
+          name: "playwright-stdout",
+          kind: "runtime.output",
+          summary: result.stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean) || "captured stdout",
+          stream: "stdout",
+          text: result.stdout,
+        }
+      : null,
     result.stderr
       ? {
           name: "playwright-stderr",
@@ -62,16 +91,19 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease, re
         }
       : null,
   ]);
-  const genericError = timedOut
+  const parsedError = stripAnsi(parsed.errors[0] || "");
+  const globalTimeoutError = isPlaywrightGlobalTimeoutError(parsedError);
+  const genericError = timedOut || globalTimeoutError
     ? formatFileTimeoutBudgetError(fileTimeoutSeconds)
     : result.exitCode === 0
-      ? parsed.errors[0] || null
-      : parsed.errors[0] || result.stderr.trim() || `Playwright exited with code ${result.exitCode}`;
+      ? parsedError || null
+      : parsedError || firstNonEmptyLine(result.stderr) || firstNonEmptyLine(result.stdout) || `Playwright exited with code ${result.exitCode}`;
+  const failed = timedOut || globalTimeoutError || (fileResult ? fileResult.status === "failed" : genericError !== null);
 
   return {
     task,
-    failed: timedOut ? true : fileResult ? fileResult.status === "failed" : result.exitCode !== 0,
-    status: timedOut ? "failed" : fileResult?.status || (result.exitCode === 0 ? "passed" : "failed"),
+    failed,
+    status: timedOut ? "failed" : fileResult?.status || (failed ? "failed" : "passed"),
     error: timedOut ? genericError : fileResult?.error || genericError,
     durationMs: fileResult?.durationMs > 0 ? fileResult.durationMs : durationMs,
     startedAt,
@@ -80,3 +112,41 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease, re
     failureDetails: timedOut ? [] : fileResult?.failureDetails || [],
   };
 }
+
+export function buildPlaywrightJsonReportPath(lease, task) {
+  if (!lease?.leaseDir) {
+    throw new Error(`Playwright task ${task?.file || ""} requires a lease-scoped directory`);
+  }
+  const reportDir = path.join(lease.leaseDir, "playwright-reports");
+  fs.mkdirSync(reportDir, { recursive: true });
+  return path.join(reportDir, `task-${task.id}.json`);
+}
+
+function readOptionalText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function extractJsonReportFromStdout(stdout) {
+  const trimmed = String(stdout || "").trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return "";
+  return trimmed;
+}
+
+function firstNonEmptyLine(value) {
+  return stripAnsi(value)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean) || null;
+}
+
+function isPlaywrightGlobalTimeoutError(value) {
+  return /Timed out waiting \d+(?:\.\d+)?s for the test suite to run/i.test(value || "");
+}
+
+function stripAnsi(value) {
+  return String(value || "").replace(/\u001b\[[0-9;]*m/g, "");
+}

package/lib/runner/processes.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "child_process";
+import { execFileSync, spawn } from "child_process";
 
 export function normalizeServiceStartCommand(command) {
   if (typeof command !== "string") {
@@ -36,9 +36,16 @@ export function startDetachedCommand(command, cwd, env) {
 
 export function killChildProcess(child, signal) {
   if (!child?.pid) return;
+  killProcessTree(child.pid, signal);
+}
+
+export function killProcessTree(pid, signal) {
+  const normalizedPid = Number(pid);
+  if (!Number.isInteger(normalizedPid) || normalizedPid <= 0) return;
+  const descendants = listDescendantPids(normalizedPid);
 
   try {
-    process.kill(-child.pid, signal);
+    process.kill(-normalizedPid, signal);
     return;
   } catch (error) {
     if (error?.code !== "ESRCH") {
@@ -49,10 +56,18 @@ export function killChildProcess(child, signal) {
   }
 
   try {
-    child.kill(signal);
+    process.kill(normalizedPid, signal);
   } catch (error) {
     if (error?.code !== "ESRCH") throw error;
   }
+
+  for (const childPid of descendants) {
+    try {
+      process.kill(childPid, signal);
+    } catch (error) {
+      if (error?.code !== "ESRCH") throw error;
+    }
+  }
 }
 
 export function captureOutput(stream, options = {}) {
@@ -116,3 +131,44 @@ export async function stopChildProcess(child, outputDrains = []) {
 export function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+export function listDescendantPids(rootPid) {
+  const normalizedRootPid = Number(rootPid);
+  if (!Number.isInteger(normalizedRootPid) || normalizedRootPid <= 0) return [];
+
+  if (process.platform === "win32") {
+    return [];
+  }
+
+  try {
+    const output = execFileSync("ps", ["-eo", "pid=,ppid="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const childrenByParent = new Map();
+    for (const line of output.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [pidRaw, parentRaw] = trimmed.split(/\s+/);
+      const pid = Number(pidRaw);
+      const parentPid = Number(parentRaw);
+      if (!Number.isInteger(pid) || !Number.isInteger(parentPid)) continue;
+      const siblings = childrenByParent.get(parentPid) || [];
+      siblings.push(pid);
+      childrenByParent.set(parentPid, siblings);
+    }
+
+    const descendants = [];
+    const stack = [...(childrenByParent.get(normalizedRootPid) || [])];
+    while (stack.length > 0) {
+      const pid = stack.pop();
+      descendants.push(pid);
+      for (const childPid of childrenByParent.get(pid) || []) {
+        stack.push(childPid);
+      }
+    }
+    return descendants;
+  } catch {
+    return [];
+  }
+}