@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/code/find.ts

@@ -0,0 +1,540 @@
+import { XMLParser } from "fast-xml-parser"
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { CodeEvent, Usage } from "../types.ts"
+import type { Card } from "../card.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import type { AppConfig, FlakyConfig } from "../config.ts"
+import { runDirectory } from "../run.ts"
+import { openSession, type AgentSpec, type OpencodeSession } from "./runtime.ts"
+import { runTestCommand, type TestRun } from "./testrun.ts"
+import { CAUSE_TEXT, flakyReport, quarantined, recordResults, RELEASE_AFTER, setQuarantine, type Flakiness } from "./history.ts"
+import { loadSkills } from "../skills/registry.ts"
+import { prompt } from "../prompts.ts"
+import { domainNotes } from "../domain.ts"
+
+const LIST_ROUNDS = 3
+const LIST_TIMEOUT_SECONDS = 180
+const OUTPUT_CHARS = 6_000
+
+export const findAgentPrompt = () => prompt("find-tests")
+
+export const FIND_AGENT: AgentSpec = {
+  name: "forgeqe-find",
+  description: "Finds the repository's automated tests that match a request, without changing or running anything",
+  get prompt() {
+    return findAgentPrompt()
+  },
+  permission: {
+    edit: "deny",
+    bash: {
+      "*": "deny",
+      "git log*": "allow",
+      "git show*": "allow",
+      "git diff*": "allow",
+      "git blame*": "allow",
+      "git ls-files*": "allow",
+      "git rev-parse*": "allow",
+      "git status*": "allow",
+      "ls*": "allow",
+    },
+    webfetch: "deny",
+    task: "deny",
+  },
+  skills: "scribe",
+}
+
+const TEST_ITEM = {
+  type: "object",
+  properties: {
+    name: { type: "string", description: "The test's full name as the framework reports it, e.g. 'login › signs in with a valid user' or 'tests/test_login.py::test_valid_user'" },
+    file: { type: "string", description: "Path relative to the repository root" },
+    reason: { type: "string", description: "Why it matches (or, under related, why it was left out), from what the test does" },
+    added: { type: "string", description: "For a time range: the date and commit that added it" },
+  },
+  required: ["name", "reason"],
+}
+
+export const FIND_SCHEMA = {
+  type: "object",
+  properties: {
+    framework: { type: "string", description: "The test framework(s), e.g. 'Playwright (TypeScript)'" },
+    tests: { type: "array", items: TEST_ITEM, description: "The tests that match" },
+    related: { type: "array", items: TEST_ITEM, description: "Near misses left out, with the reason" },
+    list_command: { type: "string", description: "Lists exactly the selected tests without running them; empty when the framework cannot list" },
+    run_command: { type: "string", description: "Runs exactly the selected tests and writes JUnit XML or TRX results" },
+    results_file: { type: "string", description: "Where run_command writes the results (file or folder), when not the path ForgeQE gave" },
+    list_matches: { type: "boolean", description: "After ForgeQE listed the tests: true when the listing is exactly the selection" },
+    notes: { type: "string", description: "What was searched, and anything the user should know" },
+  },
+  required: ["framework", "tests", "run_command", "notes"],
+} as const
+
+export type FoundTest = { name: string; file?: string; reason: string; added?: string }
+
+type FindReport = {
+  framework?: string
+  tests?: FoundTest[]
+  related?: FoundTest[]
+  list_command?: string
+  run_command?: string
+  results_file?: string
+  list_matches?: boolean
+  notes?: string
+}
+
+export type TestRange = { since?: string; until?: string; label?: string }
+
+export type TestSelection = {
+  id: string
+  dir: string
+  repo: string
+  request: string
+  range?: TestRange
+  framework: string
+  tests: FoundTest[]
+  related: FoundTest[]
+  listCommand: string
+  /** ForgeQE ran listCommand and Scribe confirmed it lists exactly the selected tests. */
+  listed: boolean
+  runCommand: string
+  /** Where ForgeQE looks for JUnit XML or TRX after running. */
+  results: string[]
+  notes: string
+  model: string
+  usage: Usage
+  createdAt: string
+}
+
+const clean = (tests: unknown): FoundTest[] =>
+  (Array.isArray(tests) ? tests : [])
+    .filter((t) => t && typeof t.name === "string" && t.name.trim())
+    .map((t) => ({ name: String(t.name).trim(), file: t.file ? String(t.file) : undefined, reason: String(t.reason || ""), added: t.added ? String(t.added) : undefined }))
+
+const tailOf = (s: string) => (s.length > OUTPUT_CHARS ? `…${s.slice(-OUTPUT_CHARS)}` : s)
+
+function rangeText(r?: TestRange): string {
+  if (!r || (!r.since && !r.until)) return ""
+  const span = r.since && r.until ? `between ${r.since} and ${r.until}` : r.since ? `since ${r.since}` : `until ${r.until}`
+  return `Only tests added ${span}${r.label ? ` (${r.label})` : ""}, both days included.`
+}
+
+export function findPrompt(opts: { request: string; range?: TestRange; junit: string; trx: string }): string {
+  const today = new Date().toISOString().slice(0, 10)
+  const shell = process.platform === "win32" ? "cmd.exe" : "sh"
+  return [
+    `Find the tests for this request: ${opts.request}`,
+    rangeText(opts.range),
+    `Today is ${today}. Commands run in ${shell}.`,
+    `Write JUnit XML results to ${opts.junit}, or TRX (dotnet test) to ${opts.trx}.`,
+  ]
+    .filter(Boolean)
+    .join("\n")
+}
+
+function listPrompt(report: FindReport, run: TestRun): string {
+  const n = report.tests?.length || 0
+  return [
+    `ForgeQE ran the list command from the repository root: ${report.list_command}`,
+    `${run.exitCode === null ? "It timed out or was stopped" : `Exit code ${run.exitCode}`} after ${Math.round(run.ms / 1000)}s. End of the output:`,
+    "```",
+    tailOf(run.output) || "(no output)",
+    "```",
+    `Compare the listing with your ${n} selected test${n === 1 ? "" : "s"}. If it lists exactly them, give the same result with list_matches true.`,
+    "If it lists tests you did not select, misses some, or failed, fix the commands (or the selection, when the listing shows you misjudged a test) and give the result with list_matches false; ForgeQE lists again.",
+  ].join("\n")
+}
+
+const sameTests = (a: FoundTest[], b: FoundTest[]) => a.length === b.length && a.every((t, i) => t.name === b[i].name)
+
+/**
+ * A read-only Scribe session picks the tests that match the request by reading them (and git history for a time range)
+ * and gives a list and a run command. ForgeQE runs the list command and Scribe checks the listing is exactly its selection.
+ * The selection is saved as selection.json in a new folder under <export.outDir>/tests.
+ */
+export async function findTests(opts: {
+  config: AppConfig
+  repo: string
+  request: string
+  range?: TestRange
+  signal?: AbortSignal
+  onEvent?: (e: CodeEvent) => void
+  open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession>
+  runTest?: typeof runTestCommand
+}): Promise<TestSelection> {
+  const repo = path.resolve(opts.repo)
+  if (!existsSync(repo) || !statSync(repo).isDirectory()) throw new Error(`Repo not found: ${repo}`)
+  const emit = opts.onEvent || (() => {})
+  const runTest = opts.runTest || runTestCommand
+  const dir = runDirectory(path.join(opts.config.export.outDir, "tests"))
+  const junit = path.join(dir, "results.xml")
+  const trx = path.join(dir, "results.trx")
+
+  const open = (opts.open || openSession) as (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<FindReport>>
+  const session = await open({
+    repo,
+    profile: opts.config.llm,
+    domain: domainNotes(opts.config),
+    model: opts.config.code.model,
+    bin: opts.config.code.opencode,
+    readDirs: [repo],
+    hide: privateEnvNames(opts.config),
+    signal: opts.signal,
+    onEvent: emit,
+    agent: FIND_AGENT,
+    skills: loadSkills(opts.config.skills, repo).skills,
+    schema: FIND_SCHEMA as unknown as Record<string, unknown>,
+    title: "ForgeQE find tests",
+  })
+  try {
+    emit({ type: "code", kind: "info", text: `Scribe (${session.model}) is looking for tests in ${repo}: ${opts.request}` })
+    let reply = await session.prompt(findPrompt({ request: opts.request, range: opts.range, junit, trx }))
+    if (!reply.report && !reply.error && !opts.signal?.aborted) reply = await session.prompt("Give the structured result: framework, tests, related, list_command, run_command, and notes.")
+    if (!reply.report) throw new Error(`Scribe gave no list of tests${reply.error ? `: ${reply.error}` : "."}`)
+    let report = reply.report
+    let listed = false
+    for (let round = 1; round <= LIST_ROUNDS && clean(report.tests).length && report.list_command?.trim() && !opts.signal?.aborted; round++) {
+      emit({ type: "code", kind: "info", text: `ForgeQE lists the selected tests: ${report.list_command}` })
+      const run = await runTest({ command: report.list_command!, cwd: repo, timeoutSeconds: LIST_TIMEOUT_SECONDS, signal: opts.signal, hide: privateEnvNames(opts.config) })
+      if (opts.signal?.aborted) break
+      const next = (await session.prompt(listPrompt(report, run))).report
+      if (!next) break
+      const unchanged = next.list_command === report.list_command && next.run_command === report.run_command && sameTests(clean(next.tests), clean(report.tests))
+      report = { ...report, ...next }
+      if (next.list_matches && unchanged) {
+        listed = true
+        break
+      }
+    }
+    if (opts.signal?.aborted) throw new Error("Stopped.")
+    const results = [report.results_file ? path.resolve(repo, report.results_file) : "", junit, trx].filter((p, i, all) => p && all.indexOf(p) === i)
+    const selection: TestSelection = {
+      id: path.basename(dir),
+      dir,
+      repo,
+      request: opts.request,
+      range: opts.range,
+      framework: String(report.framework || ""),
+      tests: clean(report.tests),
+      related: clean(report.related),
+      listCommand: String(report.list_command || ""),
+      listed,
+      runCommand: String(report.run_command || ""),
+      results,
+      notes: String(report.notes || ""),
+      model: session.model,
+      usage: { ...session.usage },
+      createdAt: new Date().toISOString(),
+    }
+    writeFileSync(path.join(dir, "selection.json"), JSON.stringify(selection, null, 2))
+    return selection
+  } finally {
+    await session.close()
+  }
+}
+
+export function loadSelection(config: AppConfig, id: string): TestSelection {
+  const file = path.join(config.export.outDir, "tests", path.basename(id), "selection.json")
+  if (!existsSync(file)) throw new Error(`No test selection "${id}": call find_tests first.`)
+  return JSON.parse(readFileSync(file, "utf8")) as TestSelection
+}
+
+export type TestOutcome = {
+  name: string
+  status: "passed" | "failed" | "skipped"
+  seconds?: number
+  message?: string
+  file?: string
+  /** Failed, then passed when run again in the same run: flaky, not failed. */
+  flaky?: boolean
+  /** In quarantine: its failure does not fail the run. */
+  quarantined?: boolean
+}
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "",
+  parseTagValue: false,
+  isArray: (name) => ["testsuite", "testcase", "UnitTestResult", "UnitTest", "failure", "error"].includes(name),
+})
+
+function text(v: unknown): string {
+  if (v == null) return ""
+  if (typeof v === "string") return v
+  if (Array.isArray(v)) return text(v[0])
+  if (typeof v === "object") {
+    const o = v as Record<string, unknown>
+    return String(o.message || o["#text"] || "")
+  }
+  return String(v)
+}
+
+function oneLine(s: string): string {
+  const t = s.replace(/\s+/g, " ").trim()
+  return t.length > 300 ? `${t.slice(0, 300)}…` : t
+}
+
+function junitCases(node: unknown, out: Record<string, any>[] = []): Record<string, any>[] {
+  if (!node || typeof node !== "object") return out
+  if (Array.isArray(node)) {
+    for (const n of node) junitCases(n, out)
+    return out
+  }
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (key === "testcase") out.push(...(value as Record<string, any>[]))
+    else if (typeof value === "object") junitCases(value, out)
+  }
+  return out
+}
+
+/** hh:mm:ss.fffffff (TRX) in seconds. */
+function trxSeconds(d: unknown): number | undefined {
+  const m = typeof d === "string" ? /^(\d+):(\d+):(\d+(?:\.\d+)?)$/.exec(d) : null
+  return m ? Math.round((Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3])) * 100) / 100 : undefined
+}
+
+/** Per-test outcomes from a JUnit XML or TRX document. */
+export function parseResults(xml: string): TestOutcome[] {
+  const doc = parser.parse(xml) as Record<string, any>
+  if (doc.TestRun) {
+    const results: Record<string, any>[] = doc.TestRun.Results?.UnitTestResult || []
+    const files = new Map<string, string>()
+    for (const t of doc.TestRun.TestDefinitions?.UnitTest || []) if (t.id && t.storage) files.set(t.id, String(t.storage))
+    return results.map((r) => {
+      const outcome = String(r.outcome || "")
+      const status = outcome === "Passed" ? "passed" : outcome === "Failed" || outcome === "Error" || outcome === "Timeout" || outcome === "Aborted" ? "failed" : "skipped"
+      const message = oneLine(text(r.Output?.ErrorInfo?.Message))
+      return { name: String(r.testName || ""), status, seconds: trxSeconds(r.duration), ...(message ? { message } : {}), ...(files.get(r.testId) ? { file: files.get(r.testId) } : {}) }
+    })
+  }
+  return junitCases(doc).map((c) => {
+    const failure = c.failure?.[0] ?? c.error?.[0]
+    const status = failure !== undefined ? "failed" : c.skipped !== undefined ? "skipped" : "passed"
+    const name = c.classname && !String(c.name || "").includes(String(c.classname)) ? `${c.classname} › ${c.name}` : String(c.name || "")
+    const message = failure !== undefined ? oneLine(text(failure)) : ""
+    const seconds = c.time !== undefined && !Number.isNaN(Number(c.time)) ? Number(c.time) : undefined
+    return { name, status, ...(seconds !== undefined ? { seconds } : {}), ...(message ? { message } : {}), ...(c.file ? { file: String(c.file) } : {}) }
+  })
+}
+
+/** Result files written at or after `since`: the given files, or the XML/TRX files in a given folder (one level down too). */
+function resultFiles(paths: string[], since: number): string[] {
+  const fresh = (f: string) => statSync(f).mtimeMs >= since - 1000
+  const out: string[] = []
+  for (const p of paths) {
+    if (!existsSync(p)) continue
+    if (statSync(p).isFile()) {
+      if (fresh(p)) out.push(p)
+      continue
+    }
+    for (const e of readdirSync(p, { withFileTypes: true })) {
+      const f = path.join(p, e.name)
+      if (e.isFile() && /\.(xml|trx)$/i.test(e.name) && fresh(f)) out.push(f)
+      else if (e.isDirectory()) for (const g of readdirSync(f)) if (/\.(xml|trx)$/i.test(g) && fresh(path.join(f, g))) out.push(path.join(f, g))
+    }
+  }
+  return [...new Set(out)]
+}
+
+export type TestsRun = {
+  status: "passed" | "failed" | "timed out" | "stopped"
+  command: string
+  exitCode: number | null
+  seconds: number
+  tests: TestOutcome[]
+  counts: { passed: number; failed: number; skipped: number }
+  resultFiles: string[]
+  browsers: string[]
+  output: string
+  outputFile: string
+  dir: string
+  /** Tests that failed, then passed when run again. */
+  flaky?: string[]
+  /** Quarantined tests that failed: not counted against the run. */
+  quarantinedFailures?: string[]
+  /** Tests whose history now makes them flaky, and not in quarantine (flaky.quarantine: suggest). */
+  suggestQuarantine?: Flakiness[]
+  /** Put in quarantine by this run (flaky.quarantine: auto). */
+  quarantinedNow?: string[]
+  /** In quarantine, and clean for several runs in a row. */
+  releasable?: string[]
+}
+
+/**
+ * The command that runs only the tests that just failed, in the framework's own way: Playwright --last-failed,
+ * pytest --lf, Jest --onlyFailures. Otherwise the whole command again when the selection is small; null past that.
+ */
+export function retryCommand(command: string, total: number): string | null {
+  if (/\bplaywright\s+test\b/.test(command)) return `${command} --last-failed`
+  if (/\bpytest\b/.test(command)) return `${command} --lf`
+  if (/\bjest\b/.test(command) && !/\bvitest\b/.test(command)) return `${command} --onlyFailures`
+  return total <= 20 ? command : null
+}
+
+/** Run a saved selection's command and read the per-test results it wrote; results.json lands in the selection's folder. */
+export async function runSelection(opts: {
+  selection: TestSelection
+  timeoutSeconds: number
+  signal?: AbortSignal
+  runTest?: typeof runTestCommand
+  /** Variables the tests must not see: ForgeQE's own secrets (privateEnvNames). */
+  hide?: string[]
+  /** Retries and quarantine; default: one retry, quarantine suggested. */
+  flaky?: FlakyConfig
+}): Promise<TestsRun> {
+  const sel = opts.selection
+  const flakyCfg = opts.flaky || { retries: 1, quarantine: "suggest", flakyAfter: 2 }
+  if (!sel.runCommand.trim()) throw new Error("The selection has no run command.")
+  mkdirSync(sel.dir, { recursive: true })
+  for (const p of sel.results) if (p.startsWith(sel.dir) && existsSync(p) && statSync(p).isFile()) rmSync(p)
+  const started = Date.now()
+  const exec = (command: string) => (opts.runTest || runTestCommand)({ command, cwd: sel.repo, timeoutSeconds: opts.timeoutSeconds, signal: opts.signal, hide: opts.hide })
+  const read = (since: number) => {
+    const out: TestOutcome[] = []
+    for (const f of resultFiles(sel.results, since)) {
+      try {
+        out.push(...parseResults(readFileSync(f, "utf8")))
+      } catch {}
+    }
+    return out
+  }
+  let run = await exec(sel.runCommand)
+  let files = resultFiles(sel.results, started)
+  let tests = read(started)
+  let output = run.output
+
+  // A failed test runs again: passing then means flaky, not failed.
+  const failedFirst = tests.filter((t) => t.status === "failed")
+  for (let attempt = 1; attempt <= flakyCfg.retries && failedFirst.length && run.exitCode !== null && !opts.signal?.aborted; attempt++) {
+    const still = tests.filter((t) => t.status === "failed")
+    if (!still.length) break
+    const cmd = retryCommand(sel.runCommand, tests.length)
+    if (!cmd) break
+    const again = Date.now()
+    const second = await exec(cmd)
+    output += `\n\n--- run again: ${still.length} failed test${still.length === 1 ? "" : "s"} (${cmd}) ---\n${second.output}`
+    const rerun = new Map(read(again).map((t) => [t.name, t]))
+    tests = tests.map((t) => (t.status === "failed" && rerun.get(t.name)?.status === "passed" ? { ...t, status: "passed", flaky: true } : t))
+    if (rerun.size) files = [...new Set([...files, ...resultFiles(sel.results, again)])]
+    if (second.exitCode === null) break
+    run = { ...second, ok: tests.every((t) => t.status !== "failed") }
+  }
+
+  // History, and quarantine: a quarantined test's failure does not count.
+  const q = quarantined(sel.repo)
+  tests = tests.map((t) => (q.has(t.name) ? { ...t, quarantined: true } : t))
+  recordResults(sel.repo, tests.map((t) => ({ name: t.name, status: t.status, retried: t.flaky, message: t.message, seconds: t.seconds })))
+  const report = new Map(flakyReport(sel.repo, flakyCfg.flakyAfter).map((f) => [f.name, f]))
+  const nowFlaky = tests.map((t) => report.get(t.name)).filter((f): f is Flakiness => Boolean(f?.flaky && !f.quarantined))
+  let quarantinedNow: string[] = []
+  if (flakyCfg.quarantine === "auto" && nowFlaky.length) {
+    quarantinedNow = setQuarantine(sel.repo, nowFlaky.map((f) => f.name), "flaky: ForgeQE quarantined it from its history", "auto")
+    tests = tests.map((t) => (quarantinedNow.includes(t.name) ? { ...t, quarantined: true } : t))
+  }
+  const blocking = tests.filter((t) => t.status === "failed" && !t.quarantined)
+  const counts = { passed: 0, failed: 0, skipped: 0 }
+  for (const t of tests) counts[t.status]++
+  const allQuarantined = tests.length > 0 && !blocking.length
+  const status = opts.signal?.aborted ? "stopped" : run.exitCode === null ? "timed out" : (run.ok || allQuarantined) && !blocking.length ? "passed" : "failed"
+  const outputFile = path.join(sel.dir, "output.log")
+  writeFileSync(outputFile, output)
+  const flakyNow = tests.filter((t) => t.flaky).map((t) => t.name)
+  const qFailed = tests.filter((t) => t.status === "failed" && t.quarantined).map((t) => t.name)
+  const releasable = tests.map((t) => report.get(t.name)).filter((f): f is Flakiness => Boolean(f?.releasable)).map((f) => f.name)
+  const result: TestsRun = {
+    status,
+    command: sel.runCommand,
+    exitCode: run.exitCode,
+    seconds: Math.round((Date.now() - started) / 100) / 10,
+    tests,
+    counts,
+    resultFiles: files,
+    browsers: run.browsers,
+    output,
+    outputFile,
+    dir: sel.dir,
+    ...(flakyNow.length ? { flaky: flakyNow } : {}),
+    ...(qFailed.length ? { quarantinedFailures: qFailed } : {}),
+    ...(flakyCfg.quarantine === "suggest" && nowFlaky.length ? { suggestQuarantine: nowFlaky } : {}),
+    ...(quarantinedNow.length ? { quarantinedNow } : {}),
+    ...(releasable.length ? { releasable } : {}),
+  }
+  writeFileSync(path.join(sel.dir, "results.json"), JSON.stringify({ ...result, output: undefined }, null, 2))
+  return result
+}
+
+const rel = (cwd: string, p: string) => {
+  const r = path.relative(cwd, p)
+  return r && !r.startsWith("..") && !path.isAbsolute(r) ? r : p
+}
+
+const LIST_MAX = 40
+
+export function selectionCard(sel: TestSelection, cwd: string): Card {
+  const n = sel.tests.length
+  const body: string[] = []
+  for (const t of sel.tests.slice(0, LIST_MAX)) {
+    body.push(`• ${t.name}`)
+    const where = [t.file, t.added ? `added ${t.added}` : ""].filter(Boolean).join(", ")
+    body.push(`    ${[where, t.reason].filter(Boolean).join(" · ")}`)
+  }
+  if (n > LIST_MAX) body.push(`and ${n - LIST_MAX} more (selection.json has all of them)`)
+  if (sel.related.length) {
+    body.push("", "Left out:")
+    for (const t of sel.related.slice(0, 10)) body.push(`• ${t.name}${t.reason ? ` · ${t.reason}` : ""}`)
+    if (sel.related.length > 10) body.push(`and ${sel.related.length - 10} more`)
+  }
+  if (n) {
+    body.push("")
+    if (sel.listCommand) body.push(`List      ${sel.listCommand} (${sel.listed ? "ForgeQE ran it: lists exactly these" : "not confirmed"})`)
+    body.push(`Run       ${sel.runCommand}`)
+  }
+  if (sel.notes) body.push("", sel.notes)
+  body.push(`Saved     ${rel(cwd, path.join(sel.dir, "selection.json"))}`)
+  return {
+    status: "info",
+    title: n ? `${n} test${n === 1 ? "" : "s"} found for "${sel.request}"` : `No tests found for "${sel.request}"`,
+    stats: [sel.framework, sel.range?.label || [sel.range?.since, sel.range?.until].filter(Boolean).join(" to ")].filter(Boolean).join(" · "),
+    body,
+  }
+}
+
+export function resultsCard(r: TestsRun, cwd: string): Card {
+  const { passed, failed, skipped } = r.counts
+  const total = r.tests.length
+  const body: string[] = []
+  const sorted = [...r.tests.filter((t) => t.status === "failed"), ...r.tests.filter((t) => t.status !== "failed")]
+  for (const t of sorted.slice(0, LIST_MAX)) {
+    const mark = t.flaky ? "↻" : t.status === "passed" ? "✓" : t.status === "failed" ? "✗" : "–"
+    const note = t.flaky ? "  flaky: failed, then passed when run again" : t.quarantined && t.status === "failed" ? "  quarantined: not counted" : t.quarantined ? "  quarantined" : ""
+    body.push(`${mark} ${t.name}${t.seconds !== undefined ? `  ${t.seconds}s` : ""}${note}`)
+    if (t.message && (t.status === "failed" || t.flaky)) body.push(`    ${t.message}`)
+  }
+  for (const f of r.suggestQuarantine || []) body.push(`⚠ ${f.name} is flaky (${f.trail}): likely ${CAUSE_TEXT[f.cause]}. Quarantine it, or fix it with heal_tests.`)
+  if (r.quarantinedNow?.length) body.push(`Quarantined now (flaky): ${r.quarantinedNow.join(", ")}`)
+  if (r.releasable?.length) body.push(`Passing again ${RELEASE_AFTER} runs in a row, ready to leave quarantine: ${r.releasable.join(", ")}`)
+  if (total > LIST_MAX) body.push(`and ${total - LIST_MAX} more`)
+  if (!total) body.push("No per-test results were written; the exit code decides.", ...r.output.split("\n").slice(-8).map((l) => `  ${l}`))
+  body.push("", `Command   ${r.command}`)
+  if (r.resultFiles.length) body.push(`Results   ${r.resultFiles.map((f) => rel(cwd, f)).join(", ")}`)
+  body.push(`Output    ${rel(cwd, r.outputFile)}`)
+  const title =
+    r.status === "stopped"
+      ? "Test run stopped"
+      : r.status === "timed out"
+        ? "Test run timed out"
+        : total
+          ? failed - (r.quarantinedFailures?.length || 0) > 0
+            ? `${failed - (r.quarantinedFailures?.length || 0)} of ${total} tests failed`
+            : `${passed} test${passed === 1 ? "" : "s"} passed${r.flaky?.length ? `, ${r.flaky.length} after a retry` : ""}${r.quarantinedFailures?.length ? `; ${r.quarantinedFailures.length} quarantined failed` : ""}`
+          : r.status === "passed"
+            ? "Tests passed"
+            : `Tests failed (exit code ${r.exitCode})`
+  return {
+    status: r.status === "passed" ? "ok" : r.status === "stopped" ? "stopped" : "fail",
+    title,
+    stats: [`${r.seconds}s`, skipped ? `${skipped} skipped` : "", r.browsers.length ? r.browsers.join(", ") : ""].filter(Boolean).join(" · "),
+    body,
+  }
+}