@elench/testkit 0.1.41 → 0.1.42

package/README.md

@@ -83,6 +83,7 @@ export default defineTestkitSetup({
       }),
       runtime: {
         instances: 1,
+        maxConcurrentTasks: 4,
       },
       requirements: {
         files: [
@@ -134,6 +135,7 @@ for:
 - per-file wall clock timeout budget
 - multi-service graphs
 - local runtime instance counts
+- per-runtime concurrent task caps
 - local DB binding configuration
 - explicit per-file or per-suite locks
 - migrate / seed commands

package/bin/testkit.mjs

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
 import { run } from "../lib/cli/index.mjs";
-run();
+
+run().catch((error) => {
+  setImmediate(() => {
+    throw error;
+  });
+});

package/lib/cli/index.mjs

@@ -11,7 +11,7 @@ import {
 } from "./args.mjs";
 import * as runner from "../runner/index.mjs";
 
-export function run() {
+export async function run(argv = process.argv) {
   const cli = cac("testkit");
 
   cli
@@ -91,5 +91,7 @@ export function run() {
     });
 
   cli.help();
-  cli.parse();
+  const parsed = cli.parse(argv, { run: false });
+  await cli.runMatchedCommand();
+  return parsed;
 }

package/lib/config/index.mjs

@@ -12,6 +12,7 @@ import {
   DEFAULT_FILE_TIMEOUT_SECONDS,
   normalizeDatabaseBinding,
   normalizeExecutionConfig,
+  normalizeRuntimeMaxConcurrentTasks,
   normalizeRuntimeInstances,
 } from "../runner/execution-config.mjs";
 
@@ -265,6 +266,7 @@ function normalizeRuntimeConfig(value, serviceName) {
   if (!value) {
     return {
       instances: 1,
+      maxConcurrentTasks: Number.POSITIVE_INFINITY,
     };
   }
 
@@ -273,6 +275,10 @@ function normalizeRuntimeConfig(value, serviceName) {
       value.instances ?? 1,
       `Service "${serviceName}" runtime.instances`
     ),
+    maxConcurrentTasks: normalizeRuntimeMaxConcurrentTasks(
+      value.maxConcurrentTasks,
+      `Service "${serviceName}" runtime.maxConcurrentTasks`
+    ),
   };
 }
 
@@ -578,6 +584,11 @@ function validateServiceConfig({
   if (runtime.instances < 1) {
     throw new Error(`Service "${name}" runtime.instances must be a positive integer`);
   }
+  if (runtime.maxConcurrentTasks <= 0) {
+    throw new Error(
+      `Service "${name}" runtime.maxConcurrentTasks must be a positive integer when provided`
+    );
+  }
 
   for (const depName of dependsOn || []) {
     if (depName === name) {

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

@@ -12,6 +12,7 @@ import { determineDefaultRuntimeFailure } from "./default-runtime-errors.mjs";
 import { RUNTIME_ARTIFACT_MARKER } from "../runtime-src/k6/artifacts.js";
 import { readDatabaseUrl } from "./state-io.mjs";
 import { buildTaskExecutionEnv } from "./template.mjs";
+import { killChildProcess } from "./processes.mjs";
 
 export async function runHttpK6Task(targetConfig, task, lifecycle, lease) {
   const baseUrl = targetConfig.testkit.local?.baseUrl;
@@ -24,7 +25,9 @@ export async function runHttpK6Task(targetConfig, task, lifecycle, lease) {
     serviceName: targetConfig.name,
     sourceFile: path.join(targetConfig.productDir, task.file),
   });
-  console.log(`·· ${targetConfig.runtimeLabel}:${task.suiteName} → ${task.file}`);
+  if (lifecycle.isStopRequested()) {
+    throw new Error(`testkit run interrupted before starting ${task.file}`);
+  }
   return runDefaultRuntimeTask(
     targetConfig,
     task,
@@ -45,7 +48,9 @@ export async function runDalTask(targetConfig, task, lifecycle, lease) {
     serviceName: targetConfig.name,
     sourceFile: path.join(targetConfig.productDir, task.file),
   });
-  console.log(`·· ${targetConfig.runtimeLabel}:${task.suiteName} → ${task.file}`);
+  if (lifecycle.isStopRequested()) {
+    throw new Error(`testkit run interrupted before starting ${task.file}`);
+  }
   return runDefaultRuntimeTask(
     targetConfig,
     task,
@@ -74,11 +79,25 @@ export async function runDefaultRuntimeTask(targetConfig, task, lease, args, lif
         process.env
       ),
       reject: false,
-      cancelSignal: lifecycle.signal,
       forceKillAfterDelay: 5_000,
     }
   );
-  const { result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds);
+  lifecycle.registerProcess(subprocess, () => {
+    killChildProcess(subprocess, "SIGINT");
+  });
+  if (lifecycle.isStopRequested()) {
+    const interruptSubprocess = () => killChildProcess(subprocess, "SIGINT");
+    if (subprocess.pid) interruptSubprocess();
+    else subprocess.once?.("spawn", interruptSubprocess);
+  }
+  console.log(`·· ${targetConfig.runtimeLabel}:${task.suiteName} → ${task.file}`);
+  let result;
+  let timedOut;
+  try {
+    ({ result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds));
+  } finally {
+    lifecycle.unregisterProcess(subprocess.pid);
+  }
 
   const stdout = parseDefaultRuntimeOutput(result.stdout || "");
   const stderr = parseDefaultRuntimeOutput(result.stderr || "");
@@ -118,7 +137,7 @@ export async function settleSubprocess(subprocess, fileTimeoutSeconds) {
       new Promise((resolve) => {
         timeoutHandle = setTimeout(async () => {
           timedOut = true;
-          subprocess.kill("SIGTERM");
+          killChildProcess(subprocess, "SIGTERM");
           const result = await subprocess.catch((error) => error);
           resolve({ result, timedOut: true });
         }, timeoutMs);

package/lib/runner/execution-config.mjs

@@ -20,6 +20,23 @@ export function normalizeRuntimeInstances(value, label = "runtime.instances") {
   return normalizePositiveInteger(value, label);
 }
 
+export function parseRuntimeMaxConcurrentTasksOption(
+  value,
+  label = "runtime.maxConcurrentTasks"
+) {
+  return parsePositiveInteger(value, label);
+}
+
+export function normalizeRuntimeMaxConcurrentTasks(
+  value,
+  label = "runtime.maxConcurrentTasks"
+) {
+  if (value === undefined || value === null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return normalizePositiveInteger(value, label);
+}
+
 export function normalizeDatabaseBinding(value, label = "database.binding") {
   const normalized = String(value || "").trim();
   if (!DATABASE_BINDINGS.has(normalized)) {

package/lib/runner/execution-config.test.mjs

@@ -5,8 +5,10 @@ import {
   DEFAULT_FILE_TIMEOUT_SECONDS,
   normalizeDatabaseBinding,
   normalizeExecutionConfig,
+  normalizeRuntimeMaxConcurrentTasks,
   normalizeRuntimeInstances,
   parseFileTimeoutOption,
+  parseRuntimeMaxConcurrentTasksOption,
   parseRuntimeInstancesOption,
   parseWorkersOption,
   resolveExecutionConfig,
@@ -16,9 +18,13 @@ describe("execution-config", () => {
   it("parses worker and runtime-instance options", () => {
     expect(parseWorkersOption("8")).toBe(8);
     expect(parseRuntimeInstancesOption("2")).toBe(2);
+    expect(parseRuntimeMaxConcurrentTasksOption("4")).toBe(4);
     expect(parseFileTimeoutOption("45")).toBe(45);
     expect(() => parseWorkersOption("0")).toThrow('Invalid --workers value "0"');
     expect(() => parseRuntimeInstancesOption("0")).toThrow('Invalid runtime.instances value "0"');
+    expect(() => parseRuntimeMaxConcurrentTasksOption("0")).toThrow(
+      'Invalid runtime.maxConcurrentTasks value "0"'
+    );
     expect(() => parseFileTimeoutOption("0")).toThrow(
       'Invalid --file-timeout-seconds value "0"'
     );
@@ -49,6 +55,8 @@ describe("execution-config", () => {
 
   it("normalizes runtime instances and database bindings", () => {
     expect(normalizeRuntimeInstances(2)).toBe(2);
+    expect(normalizeRuntimeMaxConcurrentTasks(undefined)).toBe(Number.POSITIVE_INFINITY);
+    expect(normalizeRuntimeMaxConcurrentTasks(3)).toBe(3);
     for (const binding of DATABASE_BINDINGS) {
       expect(normalizeDatabaseBinding(binding)).toBe(binding);
     }

package/lib/runner/lifecycle.mjs

@@ -1,11 +1,13 @@
 import fs from "fs";
 import path from "path";
 import crypto from "crypto";
+import { execFileSync } from "child_process";
 import { destroyRuntimeDatabase, cleanupOrphanedLocalInfrastructure } from "../database/index.mjs";
 
 const RUN_SCHEMA_VERSION = 1;
 const RUNS_DIRNAME = path.join(".testkit", "_runs");
 const TERMINATION_TIMEOUT_MS = 5_000;
+const SHUTDOWN_HOLD_TIMEOUT_MS = 10_000;
 
 export function createRunLifecycle(productDir) {
   const runId = buildRunId();
@@ -25,6 +27,9 @@ export function createRunLifecycle(productDir) {
     runtimeStateDirs: [],
   };
   const signalListeners = [];
+  const managedProcesses = new Set();
+  let shutdownHold = null;
+  let shutdownHoldTimeout = null;
 
   function persist() {
     fs.mkdirSync(getRunsDir(productDir), { recursive: true });
@@ -36,6 +41,24 @@ export function createRunLifecycle(productDir) {
     persist();
   }
 
+  function ensureShutdownHold() {
+    if (shutdownHold) return;
+    shutdownHold = setInterval(() => {}, 1_000);
+    shutdownHoldTimeout = setTimeout(() => {
+      releaseShutdownHold();
+    }, SHUTDOWN_HOLD_TIMEOUT_MS);
+  }
+
+  function releaseShutdownHold() {
+    if (!shutdownHold) return;
+    clearInterval(shutdownHold);
+    shutdownHold = null;
+    if (shutdownHoldTimeout) {
+      clearTimeout(shutdownHoldTimeout);
+      shutdownHoldTimeout = null;
+    }
+  }
+
   const api = {
     runId,
     manifestPath,
@@ -55,9 +78,18 @@ export function createRunLifecycle(productDir) {
       });
     },
     requestStop(reason = "interrupted") {
+      ensureShutdownHold();
       if (!abortController.signal.aborted) {
         abortController.abort(new Error(`testkit run interrupted (${reason})`));
       }
+      for (const entry of managedProcesses) {
+        try {
+          entry.terminate?.();
+        } catch {
+          // Best-effort interruption only.
+        }
+      }
+      terminateDescendantProcesses(process.pid, "SIGINT");
       mutate((draft) => {
         draft.status = "interrupting";
         draft.interruptReason = reason;
@@ -72,7 +104,22 @@ export function createRunLifecycle(productDir) {
         }
       });
     },
-    registerService(config, child, cwd) {
+    registerProcess(child, terminate) {
+      if (!child) return;
+      managedProcesses.add({
+        child,
+        terminate,
+      });
+    },
+    unregisterProcess(childPid) {
+      for (const entry of managedProcesses) {
+        if (entry.child?.pid === childPid) {
+          managedProcesses.delete(entry);
+        }
+      }
+    },
+    registerService(config, child, cwd, terminate) {
+      api.registerProcess(child, terminate);
       const ports = collectConfigPorts(config);
       mutate((draft) => {
         draft.services = draft.services.filter((service) => service.pid !== child.pid);
@@ -89,6 +136,7 @@ export function createRunLifecycle(productDir) {
       });
     },
     unregisterService(childPid) {
+      api.unregisterProcess(childPid);
       mutate((draft) => {
         draft.services = draft.services.filter((service) => service.pid !== childPid);
       });
@@ -116,6 +164,9 @@ export function createRunLifecycle(productDir) {
     removeManifest() {
       removeManifestFile(productDir, runId);
     },
+    dispose() {
+      releaseShutdownHold();
+    },
   };
 
   return api;
@@ -264,6 +315,53 @@ function killProcessGroup(pid, signal) {
   }
 }
 
+function terminateDescendantProcesses(rootPid, signal) {
+  const descendants = listDescendantPids(rootPid);
+  for (const pid of descendants) {
+    try {
+      process.kill(pid, signal);
+    } catch (error) {
+      if (error?.code !== "ESRCH") {
+        // Best-effort interruption only.
+      }
+    }
+  }
+}
+
+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/orchestrator.mjs

@@ -106,6 +106,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
   const executedPlans = servicePlans.filter((plan) => !plan.skipped);
   let workerCount = 0;
   let runtimeInstanceCount = 0;
+  let runtimeStats = [];
   let exitCode = 0;
   const lifecycle = createRunLifecycle(productDir);
   lifecycle.markRunning();
@@ -155,6 +156,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
             }
           }
         }
+        runtimeStats = runtimeManager.getStats();
       } finally {
         await runtimeManager.cleanupAll();
       }
@@ -174,6 +176,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
       execution,
       workerCount,
       runtimeInstanceCount,
+      runtimeStats,
       typeValues,
       suiteSelectors,
       fileNames: requestedFiles,
@@ -205,6 +208,9 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
     if (results.some((result) => result.failed)) exitCode = 1;
     if (lifecycle.isStopRequested()) exitCode = Math.max(exitCode, 130);
   } finally {
+    if (lifecycle.isStopRequested()) {
+      exitCode = Math.max(exitCode, 130);
+    }
     lifecycle.removeSignalHandlers();
     lifecycle.markFinished(
       exitCode === 0 ? "finished" : lifecycle.isStopRequested() ? "interrupted" : "failed"
@@ -212,6 +218,7 @@ export async function runAll(configs, typeValues, suiteSelectors, opts, allConfi
     await cleanupRunById(productDir, lifecycle.runId);
     await cleanupRuns(productDir, { includeActive: false });
     lifecycle.removeManifest();
+    lifecycle.dispose();
     process.exitCode = exitCode;
   }
 }

package/lib/runner/planning.mjs

@@ -113,6 +113,10 @@ export function buildRuntimeGraphs(servicePlans) {
     if (existing) {
       existing.targetNames.push(plan.config.name);
       existing.instanceCount = Math.max(existing.instanceCount, plan.config.testkit.runtime.instances);
+      existing.maxConcurrentTasks = Math.min(
+        existing.maxConcurrentTasks,
+        resolveGraphMaxConcurrentTasks(plan.runtimeConfigs)
+      );
       continue;
     }
 
@@ -123,6 +127,7 @@ export function buildRuntimeGraphs(servicePlans) {
       targetNames: [plan.config.name],
       dirName: buildGraphDirName(plan.runtimeNames),
       instanceCount: plan.config.testkit.runtime.instances,
+      maxConcurrentTasks: resolveGraphMaxConcurrentTasks(plan.runtimeConfigs),
     };
     graphs.push(graph);
     graphByRuntimeKey.set(plan.runtimeKey, graph);
@@ -166,6 +171,7 @@ export function buildTaskQueue(servicePlans, graphs, timings) {
           orderIndex: suite.orderIndex,
           file,
           locks: resolveTaskLocks(plan.config, suite, file),
+          resourceCost: 1,
           timingKey,
           estimatedDurationMs: estimateTaskDuration(timings, timingKey, suite),
         });
@@ -183,16 +189,25 @@ export function buildTaskQueue(servicePlans, graphs, timings) {
   );
 }
 
-export function claimNextTask(queue, preferredGraphKey) {
+export function claimNextTask(queue, preferredGraphKey, isRunnable = () => true) {
   if (queue.length === 0) return null;
 
-  let index = -1;
-  if (preferredGraphKey) {
-    index = queue.findIndex((task) => task.graphKey === preferredGraphKey);
+  const preferredIndexes = [];
+  const fallbackIndexes = [];
+  for (let index = 0; index < queue.length; index += 1) {
+    if (preferredGraphKey && queue[index].graphKey === preferredGraphKey) {
+      preferredIndexes.push(index);
+    } else {
+      fallbackIndexes.push(index);
+    }
+  }
+
+  for (const index of [...preferredIndexes, ...fallbackIndexes]) {
+    if (!isRunnable(queue[index])) continue;
+    return queue.splice(index, 1)[0];
   }
-  if (index === -1) index = 0;
 
-  return queue.splice(index, 1)[0];
+  return null;
 }
 
 export function buildGraphDirName(runtimeNames) {
@@ -267,3 +282,10 @@ function normalizePathSeparators(filePath) {
 function slugSegment(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "svc";
 }
+
+function resolveGraphMaxConcurrentTasks(runtimeConfigs) {
+  return runtimeConfigs.reduce(
+    (currentMin, config) => Math.min(currentMin, config.testkit.runtime.maxConcurrentTasks),
+    Number.POSITIVE_INFINITY
+  );
+}

package/lib/runner/planning.test.mjs

@@ -22,6 +22,7 @@ function makeConfig(name, extras = {}) {
       },
       runtime: providedTestkit.runtime || {
         instances: 1,
+        maxConcurrentTasks: Number.POSITIVE_INFINITY,
       },
       requirements: providedTestkit.requirements || {
         suites: [],
@@ -156,6 +157,7 @@ describe("runner-planning", () => {
       testkit: {
         runtime: {
           instances: 3,
+          maxConcurrentTasks: 2,
         },
         requirements: {
           suites: [
@@ -226,6 +228,7 @@ describe("runner-planning", () => {
       testkit: {
         runtime: {
           instances: 2,
+          maxConcurrentTasks: 4,
         },
       },
     });
@@ -234,6 +237,7 @@ describe("runner-planning", () => {
       testkit: {
         runtime: {
           instances: 1,
+          maxConcurrentTasks: 2,
         },
       },
     });
@@ -282,11 +286,13 @@ describe("runner-planning", () => {
       expect.objectContaining({
         key: "api",
         instanceCount: 2,
+        maxConcurrentTasks: 4,
         targetNames: ["api"],
       }),
       expect.objectContaining({
         key: "api|frontend",
         instanceCount: 1,
+        maxConcurrentTasks: 2,
         targetNames: ["frontend"],
       }),
     ]);
@@ -304,4 +310,36 @@ describe("runner-planning", () => {
       graphKey: "api",
     });
   });
+
+  it("skips blocked preferred-graph work and claims the next runnable task", () => {
+    const queue = [
+      {
+        id: 1,
+        graphKey: "api",
+        file: "blocked.js",
+      },
+      {
+        id: 2,
+        graphKey: "api|frontend",
+        file: "runnable.js",
+      },
+    ];
+
+    const claimed = claimNextTask(
+      queue,
+      "api",
+      (task) => task.file === "runnable.js"
+    );
+
+    expect(claimed).toMatchObject({
+      id: 2,
+      file: "runnable.js",
+    });
+    expect(queue).toEqual([
+      expect.objectContaining({
+        id: 1,
+        file: "blocked.js",
+      }),
+    ]);
+  });
 });

package/lib/runner/playwright-config.mjs

@@ -28,6 +28,9 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
       `  testDir: ${JSON.stringify(cwd)},\n` +
       `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
       `  outputDir: ${JSON.stringify(outputDir)},\n` +
+      `  workers: 1,\n` +
+      `  fullyParallel: false,\n` +
+      `  webServer: undefined,\n` +
       `};\n`;
   } else {
     source =
@@ -35,6 +38,8 @@ export function ensurePlaywrightTestConfig(targetConfig, cwd, requestedFiles, le
       `  testDir: ${JSON.stringify(cwd)},\n` +
       `  testMatch: ${JSON.stringify(normalizedFiles)},\n` +
       `  outputDir: ${JSON.stringify(outputDir)},\n` +
+      `  workers: 1,\n` +
+      `  fullyParallel: false,\n` +
       `};\n`;
   }
 

package/lib/runner/playwright-config.test.mjs

@@ -31,7 +31,7 @@ describe("runner-playwright-config", () => {
     fs.mkdirSync(cwd, { recursive: true });
     fs.writeFileSync(
       path.join(cwd, "playwright.config.mjs"),
-      "export default { outputDir: 'shared-test-results' };\n"
+      "export default { outputDir: 'shared-test-results', workers: 8, fullyParallel: true, webServer: { command: 'npm run dev', url: 'http://127.0.0.1:3000' } };\n"
     );
 
     const configPath = ensurePlaywrightTestConfig(
@@ -44,10 +44,15 @@ describe("runner-playwright-config", () => {
 
     const expectedOutputDir = resolvePlaywrightOutputDir(leaseDir);
     expect(generated.default.outputDir).toBe(expectedOutputDir);
+    expect(generated.default.workers).toBe(1);
+    expect(generated.default.fullyParallel).toBe(false);
+    expect(generated.default.webServer).toBeUndefined();
     expect(fs.existsSync(expectedOutputDir)).toBe(true);
     expect(fs.readFileSync(configPath, "utf8")).toContain(
       `outputDir: ${JSON.stringify(expectedOutputDir)}`
     );
+    expect(fs.readFileSync(configPath, "utf8")).toContain("workers: 1");
+    expect(fs.readFileSync(configPath, "utf8")).toContain("fullyParallel: false");
   });
 
   it("requires a lease-scoped directory", () => {

package/lib/runner/playwright-runner.mjs

@@ -8,6 +8,7 @@ import { ensurePlaywrightTestConfig } from "./playwright-config.mjs";
 import { printBufferedOutput } from "./processes.mjs";
 import { normalizePathSeparators } from "./state.mjs";
 import { buildPlaywrightEnv } from "./template.mjs";
+import { killChildProcess } from "./processes.mjs";
 
 export async function runPlaywrightTask(targetConfig, task, lifecycle, lease) {
   const local = targetConfig.testkit.local;
@@ -17,11 +18,12 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease) {
     );
   }
 
-  console.log(`\n── ${targetConfig.runtimeLabel} playwright:${targetConfig.name} (${task.file}) ──`);
-
   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(
@@ -31,11 +33,25 @@ export async function runPlaywrightTask(targetConfig, task, lifecycle, lease) {
       cwd,
       env: buildPlaywrightEnv(targetConfig, local.baseUrl, lease, process.env),
       reject: false,
-      cancelSignal: lifecycle.signal,
       forceKillAfterDelay: 5_000,
     }
   );
-  const { result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds);
+  lifecycle.registerProcess(subprocess, () => {
+    killChildProcess(subprocess, "SIGINT");
+  });
+  if (lifecycle.isStopRequested()) {
+    const interruptSubprocess = () => killChildProcess(subprocess, "SIGINT");
+    if (subprocess.pid) interruptSubprocess();
+    else subprocess.once?.("spawn", interruptSubprocess);
+  }
+  console.log(`\n── ${targetConfig.runtimeLabel} playwright:${targetConfig.name} (${task.file}) ──`);
+  let result;
+  let timedOut;
+  try {
+    ({ result, timedOut } = await settleSubprocess(subprocess, fileTimeoutSeconds));
+  } finally {
+    lifecycle.unregisterProcess(subprocess.pid);
+  }
 
   if (result.stderr) {
     printBufferedOutput(result.stderr, `[${targetConfig.runtimeLabel}:${targetConfig.name}:playwright]`);

package/lib/runner/reporting.mjs

@@ -97,6 +97,7 @@ export function buildRunArtifact({
   execution,
   workerCount,
   runtimeInstanceCount,
+  runtimeStats,
   typeValues,
   suiteSelectors,
   fileNames,
@@ -138,6 +139,7 @@ export function buildRunArtifact({
       fileTimeoutSeconds: execution.fileTimeoutSeconds,
       workerCount,
       runtimeInstanceCount,
+      runtimeStats: runtimeStats || [],
       dbBackend,
       types: typeValues,
       suiteSelectors: suiteSelectors.map((selector) => selector.raw),

package/lib/runner/runtime-manager.mjs

@@ -21,53 +21,56 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
   };
 
   return {
+    canAcquire(task) {
+      const pool = getPool(pools, graphByKey, task, productDir, lifecycle);
+      if (!locksAvailable(locks, task.locks || [])) {
+        return false;
+      }
+      return claimableRuntimeSlot(pool, task) !== null;
+    },
     async acquire(task) {
       const pool = getPool(pools, graphByKey, task, productDir, lifecycle);
+      if (lifecycle.isStopRequested()) {
+        throw lifecycle.signal.reason || new Error("testkit run interrupted");
+      }
 
-      while (true) {
-        if (lifecycle.isStopRequested()) {
-          throw lifecycle.signal.reason || new Error("testkit run interrupted");
-        }
-
-        const leaseId = `lease-${task.id}-${nextLeaseCounter}`;
-        nextLeaseCounter += 1;
+      const leaseId = `lease-${task.id}-${nextLeaseCounter}`;
+      nextLeaseCounter += 1;
 
-        if (!tryAcquireLocks(locks, task.locks || [], leaseId)) {
-          await runtimeHooks.sleep(10);
-          continue;
-        }
+      if (!tryAcquireLocks(locks, task.locks || [], leaseId)) {
+        throw new Error(`Task ${task.id} was claimed before its locks were available`);
+      }
 
-        const slot = claimRuntimeSlot(pool);
-        if (!slot) {
-          releaseLocks(locks, task.locks || [], leaseId);
-          await runtimeHooks.sleep(10);
-          continue;
-        }
+      const slot = claimRuntimeSlot(pool, task);
+      if (!slot) {
+        releaseLocks(locks, task.locks || [], leaseId);
+        throw new Error(`Task ${task.id} was claimed before runtime capacity was available`);
+      }
 
-        try {
-          const context = await getReadyContext(slot, productDir, task, lifecycle, runtimeHooks);
-          const leaseDir = path.join(context.runtimeDir, "leases", leaseId);
-          fs.mkdirSync(leaseDir, { recursive: true });
-          return {
-            leaseId,
-            leaseDir,
-            lockNames: task.locks || [],
-            slot,
-            context,
-          };
-        } catch (error) {
-          releaseRuntimeSlot(slot);
-          releaseLocks(locks, task.locks || [], leaseId);
-          cleanupLeaseDir({ leaseDir: path.join(slot.context?.runtimeDir || productDir, "leases", leaseId) });
-          await drainRuntimeSlot(slot, lifecycle, runtimeHooks);
-          throw error;
-        }
+      try {
+        const context = await getReadyContext(slot, productDir, task, lifecycle, runtimeHooks);
+        const leaseDir = path.join(context.runtimeDir, "leases", leaseId);
+        fs.mkdirSync(leaseDir, { recursive: true });
+        return {
+          leaseId,
+          leaseDir,
+          lockNames: task.locks || [],
+          resourceCost: task.resourceCost || 1,
+          slot,
+          context,
+        };
+      } catch (error) {
+        releaseRuntimeSlot(slot, task);
+        releaseLocks(locks, task.locks || [], leaseId);
+        cleanupLeaseDir({ leaseDir: path.join(slot.context?.runtimeDir || productDir, "leases", leaseId) });
+        await drainRuntimeSlot(slot, lifecycle, runtimeHooks);
+        throw error;
       }
     },
     async release(lease, options = {}) {
       if (!lease?.slot) return;
       releaseLocks(locks, lease.lockNames || [], lease.leaseId);
-      releaseRuntimeSlot(lease.slot);
+      releaseRuntimeSlot(lease.slot, { resourceCost: lease.resourceCost || 1 });
       cleanupLeaseDir(lease);
       if (options.invalidate) {
         lease.slot.draining = true;
@@ -84,6 +87,23 @@ export function createRuntimeManager({ productDir, graphs, lifecycle, hooks = {}
         }
       }
     },
+    getStats() {
+      return [...pools.values()]
+        .map((pool) => ({
+          graphKey: pool.slots[0]?.graph.key || null,
+          targetNames: [...(pool.slots[0]?.graph.targetNames || [])],
+          maxConcurrentTasks: Number.isFinite(pool.slots[0]?.graph.maxConcurrentTasks)
+            ? pool.slots[0]?.graph.maxConcurrentTasks
+            : null,
+          runtimeCount: pool.slots.length,
+          runtimes: pool.slots.map((slot) => ({
+            runtimeId: slot.runtimeId,
+            peakLeaseCount: slot.peakLeaseCount,
+            peakResourceUnits: slot.peakResourceUnits,
+          })),
+        }))
+        .sort((left, right) => String(left.graphKey).localeCompare(String(right.graphKey)));
+    },
   };
 }
 
@@ -105,6 +125,9 @@ function getPool(pools, graphByKey, task, productDir, lifecycle) {
       context: null,
       contextPromise: null,
       activeLeaseCount: 0,
+      activeResourceUnits: 0,
+      peakLeaseCount: 0,
+      peakResourceUnits: 0,
       draining: false,
     })),
   };
@@ -112,21 +135,30 @@ function getPool(pools, graphByKey, task, productDir, lifecycle) {
   return pool;
 }
 
-function claimRuntimeSlot(pool) {
+function claimRuntimeSlot(pool, task) {
+  const resourceCost = task.resourceCost || 1;
   const available = pool.slots.filter((slot) => !slot.draining);
   if (available.length === 0) return null;
 
-  const slot = [...available].sort(
-    (left, right) =>
-      left.activeLeaseCount - right.activeLeaseCount ||
-      left.runtimeId.localeCompare(right.runtimeId)
-  )[0];
+  const slot = [...available]
+    .filter((candidate) => slotHasCapacity(candidate, resourceCost))
+    .sort(
+      (left, right) =>
+        left.activeResourceUnits - right.activeResourceUnits ||
+        left.activeLeaseCount - right.activeLeaseCount ||
+        left.runtimeId.localeCompare(right.runtimeId)
+    )[0];
+  if (!slot) return null;
   slot.activeLeaseCount += 1;
+  slot.activeResourceUnits += resourceCost;
+  slot.peakLeaseCount = Math.max(slot.peakLeaseCount, slot.activeLeaseCount);
+  slot.peakResourceUnits = Math.max(slot.peakResourceUnits, slot.activeResourceUnits);
   return slot;
 }
 
-function releaseRuntimeSlot(slot) {
+function releaseRuntimeSlot(slot, task = {}) {
   slot.activeLeaseCount = Math.max(0, slot.activeLeaseCount - 1);
+  slot.activeResourceUnits = Math.max(0, slot.activeResourceUnits - (task.resourceCost || 1));
 }
 
 async function getReadyContext(slot, productDir, task, lifecycle, runtimeHooks) {
@@ -163,6 +195,21 @@ function tryAcquireLocks(lockMap, lockNames, leaseId) {
   return true;
 }
 
+function locksAvailable(lockMap, lockNames) {
+  return [...new Set(lockNames)].every((lockName) => !lockMap.has(lockName));
+}
+
+function claimableRuntimeSlot(pool, task) {
+  const resourceCost = task.resourceCost || 1;
+  return (
+    pool.slots.find((slot) => !slot.draining && slotHasCapacity(slot, resourceCost)) || null
+  );
+}
+
+function slotHasCapacity(slot, resourceCost) {
+  return slot.activeResourceUnits + resourceCost <= slot.graph.maxConcurrentTasks;
+}
+
 function releaseLocks(lockMap, lockNames, leaseId) {
   for (const lockName of [...new Set(lockNames)].sort()) {
     if (lockMap.get(lockName) === leaseId) {

package/lib/runner/runtime-manager.test.mjs

@@ -76,6 +76,7 @@ describe("runtime-manager", () => {
           dirName: "api",
           targetNames: ["api"],
           instanceCount: 2,
+          maxConcurrentTasks: 1,
         },
       ],
       hooks: makeHooks(events),
@@ -93,7 +94,7 @@ describe("runtime-manager", () => {
     await manager.cleanupAll();
   });
 
-  it("blocks conflicting locks until the first lease releases", async () => {
+  it("marks conflicting locks unavailable until the first lease releases", async () => {
     const productDir = makeTempDir("testkit-runtime-manager-");
     const manager = createRuntimeManager({
       productDir,
@@ -104,24 +105,17 @@ describe("runtime-manager", () => {
           dirName: "api",
           targetNames: ["api"],
           instanceCount: 1,
+          maxConcurrentTasks: 1,
         },
       ],
       hooks: makeHooks({ created: [], ready: [], cleaned: [] }),
     });
 
     const firstLease = await manager.acquire(makeTask(1, { locks: ["shared-lock"] }));
-    let secondSettled = false;
-    const secondPromise = manager.acquire(makeTask(2, { locks: ["shared-lock"] })).then((lease) => {
-      secondSettled = true;
-      return lease;
-    });
-
-    await new Promise((resolve) => setTimeout(resolve, 20));
-    expect(secondSettled).toBe(false);
+    expect(manager.canAcquire(makeTask(2, { locks: ["shared-lock"] }))).toBe(false);
 
     await manager.release(firstLease);
-    const secondLease = await secondPromise;
-    expect(secondSettled).toBe(true);
+    const secondLease = await manager.acquire(makeTask(2, { locks: ["shared-lock"] }));
 
     await manager.release(secondLease);
     await manager.cleanupAll();
@@ -139,6 +133,7 @@ describe("runtime-manager", () => {
           dirName: "api",
           targetNames: ["api"],
           instanceCount: 1,
+          maxConcurrentTasks: 2,
         },
       ],
       hooks: makeHooks(events),
@@ -165,6 +160,7 @@ describe("runtime-manager", () => {
           dirName: "api",
           targetNames: ["api"],
           instanceCount: 1,
+          maxConcurrentTasks: 1,
         },
       ],
       hooks: makeHooks({ created: [], ready: [], cleaned: [] }),
@@ -178,4 +174,33 @@ describe("runtime-manager", () => {
 
     await manager.cleanupAll();
   });
+
+  it("exposes runtime capacity through canAcquire", async () => {
+    const productDir = makeTempDir("testkit-runtime-manager-");
+    const manager = createRuntimeManager({
+      productDir,
+      lifecycle: makeLifecycle(),
+      graphs: [
+        {
+          key: "api",
+          dirName: "api",
+          targetNames: ["api"],
+          instanceCount: 1,
+          maxConcurrentTasks: 2,
+        },
+      ],
+      hooks: makeHooks({ created: [], ready: [], cleaned: [] }),
+    });
+
+    expect(manager.canAcquire(makeTask(1))).toBe(true);
+    const leaseOne = await manager.acquire(makeTask(1));
+    expect(manager.canAcquire(makeTask(2))).toBe(true);
+    const leaseTwo = await manager.acquire(makeTask(2));
+    expect(manager.canAcquire(makeTask(3))).toBe(false);
+
+    await manager.release(leaseOne);
+    expect(manager.canAcquire(makeTask(3))).toBe(true);
+    await manager.release(leaseTwo);
+    await manager.cleanupAll();
+  });
 });

package/lib/runner/services.mjs

@@ -1,7 +1,7 @@
 import { resolveServiceCwd } from "../config/index.mjs";
 import { buildExecutionEnv, numericPortFromUrl } from "./template.mjs";
 import { DEFAULT_READY_TIMEOUT_MS, assertLocalServicePortsAvailable, isPortInUse, waitForReady } from "./readiness.mjs";
-import { pipeOutput, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
+import { killChildProcess, pipeOutput, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
 import { readDatabaseUrl } from "./state-io.mjs";
 
 export async function startLocalServices(runtimeConfigs, lifecycle) {
@@ -43,7 +43,9 @@ export async function startLocalService(config, lifecycle) {
     pipeOutput(child.stdout, `[${config.runtimeLabel}:${config.name}]`),
     pipeOutput(child.stderr, `[${config.runtimeLabel}:${config.name}]`),
   ];
-  lifecycle.registerService(config, child, cwd);
+  lifecycle.registerService(config, child, cwd, () => {
+    killChildProcess(child, "SIGTERM");
+  });
 
   const readyTimeoutMs = config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
 

package/lib/runner/worker-loop.mjs

@@ -32,8 +32,14 @@ export async function runWorker(
   try {
     while (true) {
       if (lifecycle.isStopRequested()) break;
-      const task = claimNextTask(queue, worker.currentGraphKey);
-      if (!task) break;
+      const task = claimNextTask(queue, worker.currentGraphKey, (candidate) =>
+        runtimeManager.canAcquire(candidate)
+      );
+      if (!task) {
+        if (queue.length === 0) break;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        continue;
+      }
 
       let lease = null;
       try {

package/lib/setup/index.d.ts

@@ -36,6 +36,7 @@ export interface SkipConfig {
 
 export interface RuntimeConfig {
   instances?: number;
+  maxConcurrentTasks?: number;
 }
 
 export interface SuiteRequirementRule {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",