@elench/testkit 0.1.53 → 0.1.55

package/lib/cli/viewer.mjs

@@ -1,7 +1,12 @@
 import fs from "fs";
 import path from "path";
 import { formatDuration } from "../runner/formatting.mjs";
-import { readLogTail } from "../runner/logs.mjs";
+import { findLogSliceByRequestId, readLogTail } from "../runner/logs.mjs";
+import {
+  findFailureLocation,
+  formatLocation,
+  renderCodeFrame,
+} from "./presentation/code-frames.mjs";
 
 export function loadLatestRunArtifact(productDir) {
   const artifactPath = path.join(productDir, ".testkit", "results", "latest.json");
@@ -11,6 +16,14 @@ export function loadLatestRunArtifact(productDir) {
   return JSON.parse(fs.readFileSync(artifactPath, "utf8"));
 }
 
+export function loadCurrentRunArtifact(productDir) {
+  const livePath = path.join(productDir, ".testkit", "results", "live.json");
+  if (fs.existsSync(livePath)) {
+    return JSON.parse(fs.readFileSync(livePath, "utf8"));
+  }
+  return loadLatestRunArtifact(productDir);
+}
+
 export function resolveFileSubject(runArtifact, selector = null, serviceFilter = null) {
   const files = collectFiles(runArtifact, serviceFilter);
   if (files.length === 0) {
@@ -63,6 +76,8 @@ export function collectArtifactEntries(productDir, runArtifact, selector = null,
 
 export function formatFileDetail(productDir, runArtifact, subject, options = {}) {
   const lines = [];
+  const failureDetails = subject.file.failureDetails || [];
+  const primaryDetail = rankFailureDetails(failureDetails)[0] || null;
   lines.push(`File: ${subject.file.path}`);
   lines.push(`Service: ${subject.service.name}`);
   lines.push(`Suite: ${subject.suite.type}:${subject.suite.name}`);
@@ -70,12 +85,53 @@ export function formatFileDetail(productDir, runArtifact, subject, options = {})
   lines.push(`Duration: ${formatDuration(subject.file.durationMs || 0)}`);
   if (subject.file.error) lines.push(`Error: ${subject.file.error}`);
 
-  if ((subject.file.failureDetails || []).length > 0) {
+  if (failureDetails.length > 0) {
     lines.push("");
     lines.push("Failure Details:");
-    for (const detail of subject.file.failureDetails.slice(0, options.failureLimit || 5)) {
+    for (const detail of rankFailureDetails(failureDetails).slice(0, options.failureLimit || 5)) {
       lines.push(`  ${detail.title}`);
       if (detail.message) lines.push(`    ${detail.message}`);
+      const requestLine = formatRequestLine(detail);
+      if (requestLine) lines.push(`    ${requestLine}`);
+      const responseLine = formatResponseLine(detail);
+      if (responseLine) lines.push(`    ${responseLine}`);
+      const location = findFailureLocation(detail, subject.file.error || "");
+      if (location) lines.push(`    at ${formatLocation(location, productDir)}`);
+    }
+  }
+
+  const codeFrame = renderCodeFrame(findFailureLocation(primaryDetail, subject.file.error || ""), {
+    cwd: productDir,
+  });
+  if (codeFrame.length > 0) {
+    lines.push("");
+    lines.push("Code Frame:");
+    for (const line of codeFrame) lines.push(`  ${line}`);
+  }
+
+  if (subject.file.triage) {
+    lines.push("");
+    lines.push("Triage:");
+    const triageLines = formatTriage(subject.file.triage);
+    for (const line of triageLines) lines.push(`  ${line}`);
+  }
+
+  const setupOperations = getSetupOperationsForService(runArtifact, subject.service.name);
+  if (setupOperations.length > 0) {
+    lines.push("");
+    lines.push("Setup:");
+    for (const operation of setupOperations.slice(0, 8)) {
+      const duration = operation.durationMs == null ? "" : ` ${formatDuration(operation.durationMs)}`;
+      const suffix = operation.summary ? ` ${operation.summary}` : "";
+      lines.push(`  ${operation.status} ${operation.stage}${duration}${suffix}`);
+      if (operation.logRef?.path) lines.push(`    ${operation.logRef.path}`);
+      if (operation.error) lines.push(`    ${operation.error}`);
+      if (operation.logRef?.path) {
+        const setupLogPath = path.join(productDir, operation.logRef.path);
+        for (const line of readLogTail(setupLogPath, 4).slice(-4)) {
+          lines.push(`    ${line}`);
+        }
+      }
     }
   }
 
@@ -100,7 +156,12 @@ export function formatFileDetail(productDir, runArtifact, subject, options = {})
     for (const logRef of logRefs) {
       lines.push(`  ${logRef.runtimeLabel}`);
       lines.push(`    ${logRef.path}`);
-      const tail = readLogTail(path.join(productDir, logRef.path), options.logTail || 12);
+      const logPath = path.join(productDir, logRef.path);
+      const requestId = primaryDetail?.request?.requestId || null;
+      const tail =
+        requestId && findLogSliceByRequestId(logPath, requestId, 2).length > 0
+          ? findLogSliceByRequestId(logPath, requestId, 2)
+          : readLogTail(logPath, options.logTail || 12);
       for (const line of tail.slice(-Math.max(0, options.logTail || 12))) {
         lines.push(`    ${line}`);
       }
@@ -114,11 +175,24 @@ export function getServiceLogRefs(runArtifact, serviceName) {
   return (runArtifact.logs?.services || []).filter((entry) => entry.serviceName === serviceName);
 }
 
+export function getSetupOperationsForService(runArtifact, serviceName) {
+  return (runArtifact.setup?.operations || [])
+    .filter((entry) => entry.serviceName === serviceName)
+    .sort(
+      (left, right) =>
+        String(left.startedAt || "").localeCompare(String(right.startedAt || "")) ||
+        String(left.stage || "").localeCompare(String(right.stage || ""))
+    );
+}
+
 export function formatArtifactPreview(payload, maxLines = 6) {
   if (!payload) return ["artifact payload missing"];
   if (payload.kind === "agentic-query") {
     return formatAgenticArtifact(payload, maxLines);
   }
+  if (payload.kind === "testkit.http-traces") {
+    return formatHttpTraceArtifact(payload, maxLines);
+  }
   if (payload.contentType === "text/plain" && typeof payload.data?.text === "string") {
     return payload.data.text
       .split(/\r?\n/)
@@ -145,6 +219,74 @@ function formatAgenticArtifact(payload, maxLines) {
   return lines.slice(0, maxLines);
 }
 
+function formatHttpTraceArtifact(payload, maxLines) {
+  const traces = Array.isArray(payload.data?.traces) ? payload.data.traces : [];
+  const lines = [];
+  for (const trace of traces.slice(0, maxLines)) {
+    lines.push(
+      `${trace.method} ${trace.path} -> ${trace.response?.status ?? "?"}${trace.requestId ? ` [${trace.requestId}]` : ""}`
+    );
+  }
+  return lines;
+}
+
+function rankFailureDetails(details) {
+  return [...(Array.isArray(details) ? details : [])].sort((left, right) => {
+    return failureDetailRank(left) - failureDetailRank(right) || String(left?.key || "").localeCompare(String(right?.key || ""));
+  });
+}
+
+function failureDetailRank(detail) {
+  if (detail?.kind === "http-assertion") return 1;
+  if (detail?.request && detail?.response) return 2;
+  if (detail?.location || detail?.stack) return 3;
+  if (detail?.message) return 4;
+  return 5;
+}
+
+function formatRequestLine(detail) {
+  const method = detail?.request?.method;
+  const path = detail?.request?.path;
+  if (!method || !path) return null;
+  const requestId = detail?.request?.requestId;
+  return requestId ? `request: ${method} ${path} [${requestId}]` : `request: ${method} ${path}`;
+}
+
+function formatResponseLine(detail) {
+  if (!detail?.response) return null;
+  const parts = [`response: ${detail.response.status ?? "?"}`];
+  if (detail.response.contentType) parts.push(detail.response.contentType);
+  if (detail.response.bodyPreview) parts.push(detail.response.bodyPreview);
+  return parts.join(" ");
+}
+
+function formatTriage(triage) {
+  const lines = [`status: ${triage.status}`];
+  if (triage.classifications?.length) {
+    lines.push(`classification: ${triage.classifications.join(", ")}`);
+  }
+  if (triage.availability?.mode) {
+    lines.push(
+      `validation: ${triage.availability.mode}${triage.availability.reason ? ` (${triage.availability.reason})` : ""}`
+    );
+  }
+  for (const entry of triage.entries || []) {
+    lines.push(`issue: ${entry.issue.repo}#${entry.issue.number}`);
+    if (entry.issue.url) lines.push(`url: ${entry.issue.url}`);
+    if (entry.github?.state) {
+      lines.push(`github state: ${entry.github.state}${entry.github.cached ? " (cache)" : ""}`);
+    }
+    if (entry.validationStatus) lines.push(`validation status: ${entry.validationStatus}`);
+    if (entry.findings?.length) {
+      for (const finding of entry.findings.slice(0, 3)) {
+        lines.push(`finding: ${finding.message}`);
+      }
+    }
+    break;
+  }
+  return lines;
+}
+
 function collectFiles(runArtifact, serviceFilter = null) {
   const files = [];
   for (const service of runArtifact.services || []) {

package/lib/database/index.mjs

@@ -36,25 +36,25 @@ const LOCAL_POLL_INTERVAL_MS = 1_000;
 const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
 const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
-export async function prepareDatabaseRuntime(config) {
+export async function prepareDatabaseRuntime(config, options = {}) {
   const db = config.testkit.database;
   if (!db) return;
 
   fs.mkdirSync(config.stateDir, { recursive: true });
   if (db.provider === "local") {
-    await prepareLocalDatabase(config);
+    await prepareLocalDatabase(config, options);
     return;
   }
 
   throw new Error(`Unsupported database provider "${db.provider}"`);
 }
 
-export async function captureDatabaseTemplateSnapshot(config, outputPath) {
+export async function captureDatabaseTemplateSnapshot(config, outputPath, options = {}) {
   if (!config.testkit.database || config.testkit.database.provider !== "local") {
     throw new Error(`Service "${config.name}" does not use a local testkit database`);
   }
 
-  await prepareDatabaseRuntime(config);
+  await prepareDatabaseRuntime(config, options);
   const cacheDir = getLocalServiceCacheDir(config.productDir, config.name);
   const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
   if (!templateDbName) {
@@ -66,7 +66,41 @@ export async function captureDatabaseTemplateSnapshot(config, outputPath) {
     throw new Error(`Missing local database container for service "${config.name}"`);
   }
 
-  return captureTemplateSnapshot(config, outputPath, buildDatabaseUrl(infra, templateDbName));
+  const snapshotOperation = options.setupRegistry?.start({
+    config,
+    stage: "template:snapshot",
+    kind: "database-snapshot",
+    summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+  });
+  try {
+    const output = await captureTemplateSnapshot(
+      config,
+      outputPath,
+      buildDatabaseUrl(infra, templateDbName),
+      {
+        reporter: options.reporter || null,
+        logRecord: snapshotOperation?._logRecord || null,
+      }
+    );
+    const finished = snapshotOperation
+      ? options.setupRegistry.finish(snapshotOperation, {
+          status: "passed",
+          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    return output;
+  } catch (error) {
+    const finished = snapshotOperation
+      ? options.setupRegistry.finish(snapshotOperation, {
+          status: "failed",
+          summary: `snapshot: ${path.relative(config.productDir, outputPath)}`,
+          error: error?.message || error,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
+    throw error;
+  }
 }
 
 export async function destroyRuntimeDatabase({ productDir, stateDir }) {
@@ -138,7 +172,7 @@ export function showServiceDatabaseStatus(productDir, serviceName) {
   return true;
 }
 
-async function prepareLocalDatabase(config) {
+async function prepareLocalDatabase(config, options = {}) {
   const db = config.testkit.database;
   const productDir = config.productDir;
   const serviceName = config.name;
@@ -154,7 +188,7 @@ async function prepareLocalDatabase(config) {
   );
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
-    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint);
+    await ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options);
   });
 
   await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
@@ -162,7 +196,7 @@ async function prepareLocalDatabase(config) {
   });
 }
 
-async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint) {
+async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options = {}) {
   const serviceName = config.name;
   const existingFingerprint = readStateValue(path.join(cacheDir, "template_fingerprint"));
   const existingDbName = readStateValue(path.join(cacheDir, "template_database_name"));
@@ -173,6 +207,12 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
     existingDbName &&
     (await databaseExists(infra, existingDbName))
   ) {
+    options.setupRegistry?.recordCached({
+      config,
+      stage: "template",
+      kind: "database-template",
+      summary: "template cache hit",
+    });
     writeLocalCacheState(cacheDir, infra, existingDbName, templateFingerprint);
     return;
   }
@@ -186,11 +226,45 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
 
   const templateUrl = buildDatabaseUrl(infra, desiredDbName);
   await createEmptyDatabase(infra, desiredDbName);
+  const templateOperation = options.setupRegistry?.start({
+    config,
+    stage: "template",
+    kind: "database-template",
+    summary: "template rebuild",
+    recordLog: false,
+  });
   try {
-    await runTemplateStage(config, "migrate", templateUrl);
-    await runTemplateStage(config, "seed", templateUrl);
-    await runTemplateStage(config, "verify", templateUrl);
+    await runTemplateStage(config, "migrate", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    await runTemplateStage(config, "seed", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    await runTemplateStage(config, "verify", templateUrl, {
+      reporter: options.reporter || null,
+      setupRegistry: options.setupRegistry || null,
+      parentOperation: templateOperation,
+    });
+    const finished = templateOperation
+      ? options.setupRegistry.finish(templateOperation, {
+          status: "passed",
+          summary: "template rebuild",
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
   } catch (error) {
+    const finished = templateOperation
+      ? options.setupRegistry.finish(templateOperation, {
+          status: "failed",
+          summary: "template rebuild",
+          error: error?.message || error,
+        })
+      : null;
+    if (finished) options.reporter?.setupOperationFinished?.(finished);
     await dropDatabaseIfExists(infra, desiredDbName);
     throw error;
   }

package/lib/database/template-steps.mjs

@@ -6,8 +6,9 @@ import {
   collectConfiguredInputs,
   runConfiguredSteps,
 } from "../runner/template-steps.mjs";
+import { captureOutput } from "../runner/processes.mjs";
 
-export async function runTemplateStage(config, stageName, databaseUrl) {
+export async function runTemplateStage(config, stageName, databaseUrl, options = {}) {
   const steps = config.testkit.database?.template?.[stageName] || [];
   if (steps.length === 0) return;
 
@@ -21,6 +22,9 @@ export async function runTemplateStage(config, stageName, databaseUrl) {
     steps,
     env,
     labelPrefix: `template:${stageName}`,
+    reporter: options.reporter || null,
+    setupRegistry: options.setupRegistry || null,
+    parentOperation: options.parentOperation || null,
   });
 }
 
@@ -32,12 +36,12 @@ export function collectTemplateInputs(productDir, template = {}) {
   });
 }
 
-export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
+export async function captureTemplateSnapshot(config, outputPath, databaseUrl, options = {}) {
   const templateDbUrl = databaseUrl;
   const absoluteOutputPath = path.resolve(config.productDir, outputPath);
   fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
 
-  await execa(
+  const child = execa(
     "pg_dump",
     [
       "--schema-only",
@@ -53,19 +57,54 @@ export async function captureTemplateSnapshot(config, outputPath, databaseUrl) {
         ...buildExecutionEnv(config, {}, process.env),
         DATABASE_URL: templateDbUrl,
       },
-      stdio: "inherit",
+      stdout: "pipe",
+      stderr: "pipe",
+      reject: false,
     }
   );
+  const liveWriter =
+    options.reporter?.outputMode === "debug"
+      ? (line) => options.reporter.writeDebugLine?.(line)
+      : null;
+  const logRecord = options.logRecord || null;
+  const drains = [
+    captureOutput(child.stdout, {
+      livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) logRecord.stream.write(`${new Date().toISOString()} [stdout] ${line}\n`);
+      },
+    }),
+    captureOutput(child.stderr, {
+      livePrefix: `[${config.runtimeLabel || config.name}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) logRecord.stream.write(`${new Date().toISOString()} [stderr] ${line}\n`);
+      },
+    }),
+  ];
+  const result = await child;
+  await Promise.all(drains);
+  if (result.exitCode !== 0) {
+    throw new Error(result.shortMessage || result.stderr || result.stdout || "pg_dump failed");
+  }
 
   sanitizeSnapshotFile(absoluteOutputPath);
   return absoluteOutputPath;
 }
 
-function sanitizeSnapshotFile(filePath) {
+export function sanitizeSnapshotFile(filePath) {
   const dump = fs.readFileSync(filePath, "utf8");
   const sanitized = dump
     .split("\n")
-    .filter((line) => line.trim() !== "SET transaction_timeout = 0;")
+    .filter((line) => {
+      const trimmed = line.trim();
+      return (
+        trimmed !== "SET transaction_timeout = 0;" &&
+        !trimmed.startsWith("\\restrict ") &&
+        !trimmed.startsWith("\\unrestrict ")
+      );
+    })
     .join("\n");
 
   if (sanitized !== dump) {

package/lib/database/template-steps.test.mjs

@@ -0,0 +1,43 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { sanitizeSnapshotFile } from "./template-steps.mjs";
+
+const tempDirs = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("template snapshot sanitization", () => {
+  it("removes volatile pg_dump control lines", () => {
+    const dir = makeTempDir("testkit-template-snapshot-");
+    const filePath = path.join(dir, "schema.sql");
+    fs.writeFileSync(
+      filePath,
+      [
+        "SET statement_timeout = 0;",
+        "SET transaction_timeout = 0;",
+        "\\restrict abc123",
+        "CREATE TABLE public.widgets (id integer);",
+        "\\unrestrict abc123",
+        "",
+      ].join("\n")
+    );
+
+    sanitizeSnapshotFile(filePath);
+
+    expect(fs.readFileSync(filePath, "utf8")).toBe(
+      ["SET statement_timeout = 0;", "CREATE TABLE public.widgets (id integer);", ""].join("\n")
+    );
+  });
+});

package/lib/known-failures/index.mjs

@@ -194,7 +194,7 @@ export function matchesKnownFailureMatch(match, fileSummary) {
   if (match.path !== fileSummary.path) return false;
   if (match.failureKey) {
     const failureKeys = Array.isArray(fileSummary.failureDetails)
-      ? fileSummary.failureDetails.map((detail) => detail?.key)
+      ? fileSummary.failureDetails.flatMap((detail) => [detail?.key, detail?.title].filter(Boolean))
       : [];
     if (!failureKeys.includes(match.failureKey)) return false;
   }

package/lib/known-failures/index.test.mjs

@@ -59,6 +59,52 @@ describe("known failures core", () => {
     expect(matches[0].id).toBe("bad-message");
   });
 
+  it("matches failureKey against a detail title when the key becomes richer", () => {
+    const document = normalizeKnownFailuresDocument({
+      schemaVersion: 1,
+      entries: [
+        {
+          id: "missing-route",
+          title: "Missing route bug",
+          classification: "product_bug",
+          state: "open",
+          issue: {
+            repo: "acme/repo",
+            number: 13,
+            url: "https://github.com/acme/repo/issues/13",
+          },
+          description: "Wrong status code",
+          whyFailing: "The route returns 404",
+          lastReviewedAt: "2026-04-28",
+          matches: [
+            {
+              service: "api",
+              type: "int",
+              path: "__testkit__/health/http-failure.int.testkit.ts",
+              failureKey: "GET /missing returns 200",
+            },
+          ],
+        },
+      ],
+    });
+
+    const matches = findMatchingKnownFailureEntries(document, {
+      service: "api",
+      type: "int",
+      path: "__testkit__/health/http-failure.int.testkit.ts",
+      error: "Default runtime thresholds failed: checks(rate==1.0)",
+      failureDetails: [
+        {
+          key: "GET /missing > GET /missing returns 200",
+          title: "GET /missing returns 200",
+        },
+      ],
+    });
+
+    expect(matches).toHaveLength(1);
+    expect(matches[0].id).toBe("missing-route");
+  });
+
   it("validates status coverage and filesystem matches", () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-known-failures-"));
     tempDirs.push(tempDir);

package/lib/runner/artifacts.mjs

@@ -9,11 +9,20 @@ import {
 const TIMINGS_FILENAME = "timings.json";
 const RESULT_ARTIFACTS_DIRNAME = "artifacts";
 const RESULT_LOGS_DIRNAME = "logs";
+const RESULT_SETUP_DIRNAME = "setup";
+const LIVE_ARTIFACT_FILENAME = "live.json";
 
 export function writeRunArtifact(productDir, artifact) {
   const resultsDir = path.join(productDir, ".testkit", "results");
   fs.mkdirSync(resultsDir, { recursive: true });
   fs.writeFileSync(path.join(resultsDir, "latest.json"), JSON.stringify(artifact, null, 2));
+  fs.rmSync(path.join(resultsDir, LIVE_ARTIFACT_FILENAME), { force: true });
+}
+
+export function writeLiveRunArtifact(productDir, artifact) {
+  const resultsDir = path.join(productDir, ".testkit", "results");
+  fs.mkdirSync(resultsDir, { recursive: true });
+  fs.writeFileSync(path.join(resultsDir, LIVE_ARTIFACT_FILENAME), JSON.stringify(artifact, null, 2));
 }
 
 export function writeStatusArtifact(productDir, artifact) {
@@ -32,6 +41,13 @@ export function resetResultArtifacts(productDir) {
     recursive: true,
     force: true,
   });
+  fs.rmSync(path.join(productDir, ".testkit", "results", RESULT_SETUP_DIRNAME), {
+    recursive: true,
+    force: true,
+  });
+  fs.rmSync(path.join(productDir, ".testkit", "results", LIVE_ARTIFACT_FILENAME), {
+    force: true,
+  });
 }
 
 export function persistTaskArtifacts(productDir, task, emittedArtifacts) {

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

@@ -1,3 +1,6 @@
+import path from "path";
+import { fileURLToPath } from "url";
+
 export function determineDefaultRuntimeFailure(result, summary, firstLine) {
   const fatalRuntimeError = extractDefaultRuntimeFatalError(result.stderr || "", firstLine);
   if (fatalRuntimeError) {
@@ -26,6 +29,22 @@ export function extractDefaultRuntimeFatalError(stderr, firstLine) {
   return matched?.[1]?.trim() || firstLine(stderr);
 }
 
+export function extractDefaultRuntimeFatalDetail(stderr, firstLine) {
+  if (!stderr || !/source=stacktrace/.test(stderr)) return null;
+  const message = extractDefaultRuntimeFatalError(stderr, firstLine);
+  if (!message) return null;
+
+  const location = extractFirstLocation(stderr);
+  return {
+    kind: "runtime-exception",
+    key: location ? `${location.path}:${location.line}:${location.column}` : message,
+    title: "Uncaught runtime exception",
+    message: `Uncaught testkit suite error: ${message}`,
+    location,
+    stack: sanitizeStack(stderr),
+  };
+}
+
 export function extractDefaultRuntimeThresholdFailures(summary) {
   const metrics = summary?.metrics;
   if (!metrics || typeof metrics !== "object") return [];
@@ -51,3 +70,50 @@ export function sanitizeDefaultRuntimeExitError(exitCode, output, firstLine) {
   }
   return `Default runtime failed with exit code ${exitCode}`;
 }
+
+function extractFirstLocation(stderr) {
+  const locations = [...String(stderr).matchAll(/(file:\/\/[^\s)]+|\/[^\s):]+):(\d+):(\d+)/g)].map((match) => ({
+    path: normalizeLocationPath(match[1]),
+    line: Number(match[2]),
+    column: Number(match[3]),
+  }));
+  if (locations.length === 0) return null;
+
+  return (
+    locations.find((location) => isPreferredLocation(location.path)) ||
+    locations.find((location) => !isRuntimeInternalLocation(location.path)) ||
+    locations[0]
+  );
+}
+
+function normalizeLocationPath(rawPath) {
+  if (!rawPath) return rawPath;
+  if (rawPath.startsWith("file://")) {
+    try {
+      return fileURLToPath(rawPath);
+    } catch {
+      return rawPath;
+    }
+  }
+  return rawPath;
+}
+
+function sanitizeStack(stderr) {
+  return String(stderr)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+}
+
+function isPreferredLocation(filePath) {
+  if (typeof filePath !== "string") return false;
+  const normalized = filePath.split(path.sep).join("/");
+  return normalized.includes("/.testkit/_bundles/") || normalized.includes("/__testkit__/");
+}
+
+function isRuntimeInternalLocation(filePath) {
+  if (typeof filePath !== "string") return false;
+  const normalized = filePath.split(path.sep).join("/");
+  return normalized.includes("/testkit/lib/runtime-src/k6/") || normalized.includes("/vendor/k6");
+}