@capagents/forgeqe 1.1.4 → 1.1.6

package/src/cases/predict.ts

@@ -0,0 +1,372 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { importsOf } from "../code/impact.ts"
+import { DEFECT_HISTORY, readDefectHistory, type DefectHistoryFile, type PastDefect } from "./defectHistory.ts"
+import type { DefectCluster } from "./defects.ts"
+import type { CaseStatus } from "./types.ts"
+
+/**
+ * Defect intelligence, part four: where the next defects are likely, and how the defects went over time.
+ *
+ * An area is a page or an API route, by its path without ids (/checkout, /api/cart/:id). What ForgeQE knows about each
+ * comes from the suites saved in one folder: the pages their cases ended on, the defects in defect-history.json, and
+ * how often the cases failed. A prediction scores the areas a change touches (a file named after the area, a diff that
+ * mentions its route) by that history, with every reason given. It is a heuristic, not a model: each prediction is
+ * saved and scored against the next suite, so the trend report says how often it was right.
+ */
+
+export const PREDICTIONS = "defect-predictions.json"
+const KEEP = 30
+const WINDOW = 10
+const GENERIC = new Set(["api", "v1", "v2", "v3", "rest", "graphql", "www", "app", "index", "home", "static", "assets", "src", "public"])
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte|py|cs|java|kt|go|rb|php|rs|scala|swift)$/i
+const NOT_PRODUCT = /(^|\/)(tests?|__tests__|spec|e2e|docs?|\.github|\.forgeqe)\/|\.(test|spec)\.[a-z]+$/i
+
+export type Level = "high" | "medium" | "low"
+
+export type RiskArea = {
+  area: string
+  level: Level
+  score: number
+  reasons: string[]
+  /** Changed files that touch the area. */
+  changed: string[]
+  /** Cases that ended on the area in earlier suites: the ones to run first. */
+  cases: string[]
+  defects: { id: string; title: string; seen: number; open: boolean; returns: number }[]
+}
+
+export type Prediction = {
+  id: string
+  at: string
+  repo: string
+  base: string
+  head: string
+  changed: string[]
+  areas: RiskArea[]
+  /** Changed product code that touches no area ForgeQE has seen: nothing tests it yet. */
+  untested: string[]
+  /** The cases to run first, the riskiest areas' first. */
+  runFirst: string[]
+  /** Filled in by the first suite after it: whether its defects fell in the areas predicted. */
+  scored?: { suite: string; at: string; defects: number; inPredicted: number; high: number; highWithDefect: number }
+}
+
+type PredictionsFile = { version: 1; predictions: Prediction[] }
+
+/** An area's path, from a URL or a route ("localhost:4517/api/cart/:id" → /api/cart/:id). */
+export function areaPath(urlOrRoute: string): string {
+  // "localhost:4517/api" parses as a URL whose scheme is "localhost:": only a "://" makes one.
+  let p: string
+  try {
+    p = urlOrRoute.includes("://") ? new URL(urlOrRoute).pathname : urlOrRoute.slice(Math.max(0, urlOrRoute.indexOf("/"))) || "/"
+  } catch {
+    p = "/"
+  }
+  if (!p.startsWith("/")) p = "/"
+  const segs = p.split(/[?#]/)[0].split("/").map((s) => (s && /\d/.test(s) && /^(\d+|[0-9a-f-]{8,}|(?=.*\d)[A-Za-z0-9_-]{16,})$/i.test(s) ? ":id" : s))
+  return segs.join("/").replace(/\/+$/, "") || "/"
+}
+
+/** The area a defect is in: its route for a failed request, else the page it was seen on. */
+export function areaOf(d: Pick<DefectCluster, "kind" | "title" | "page"> | (Pick<PastDefect, "kind" | "title"> & { page?: string })): string | undefined {
+  if (d.kind === "request") return areaPath(d.title.replace(/ (returns \d{3}|fails)$/, ""))
+  return d.page ? areaPath(d.page) : undefined
+}
+
+/** The words of an area a file or a change would carry: /api/cart/:id → cart. */
+export function areaWords(area: string): string[] {
+  return area.split("/").filter((w) => w.length >= 3 && !w.startsWith(":") && !GENERIC.has(w.toLowerCase()))
+}
+
+type SavedSuite = { name: string; at: string; results: { case: { id: string }; status: CaseStatus; finalUrl?: string }[] }
+
+function savedSuites(folder: string): SavedSuite[] {
+  let names: string[] = []
+  try {
+    names = readdirSync(folder).filter((n) => existsSync(path.join(folder, n, "suite.json")))
+  } catch {}
+  const out: SavedSuite[] = []
+  for (const name of names) {
+    try {
+      const s = JSON.parse(readFileSync(path.join(folder, name, "suite.json"), "utf8"))
+      if (s?.startedAt && Array.isArray(s.results)) out.push({ name, at: s.startedAt, results: s.results })
+    } catch {}
+  }
+  return out.sort((a, b) => a.at.localeCompare(b.at))
+}
+
+export type AreaFacts = { area: string; cases: Set<string>; runs: number; failed: number; failedLast: boolean; defects: RiskArea["defects"] }
+
+/** What the suites in `folder` and its defect history know about each area. */
+export function areaFacts(folder: string, history: DefectHistoryFile = readDefectHistory(path.join(folder, DEFECT_HISTORY))): Map<string, AreaFacts> {
+  const facts = new Map<string, AreaFacts>()
+  const get = (area: string) => {
+    let f = facts.get(area)
+    if (!f) facts.set(area, (f = { area, cases: new Set(), runs: 0, failed: 0, failedLast: false, defects: [] }))
+    return f
+  }
+  const suites = savedSuites(folder).slice(-WINDOW)
+  suites.forEach((s, i) => {
+    for (const r of s.results) {
+      if (!r.finalUrl || r.status === "stopped") continue
+      const f = get(areaPath(r.finalUrl))
+      f.cases.add(r.case.id)
+      f.runs++
+      if (r.status !== "passed") {
+        f.failed++
+        if (i === suites.length - 1) f.failedLast = true
+      }
+    }
+  })
+  for (const [id, d] of Object.entries(history.defects)) {
+    const area = areaOf(d)
+    if (!area) continue
+    const f = get(area)
+    for (const c of d.cases) f.cases.add(c)
+    f.defects.push({ id, title: d.title, seen: d.seen, open: !d.goneSince, returns: d.returns?.length || 0 })
+  }
+  return facts
+}
+
+const git = (repo: string, args: string[]) => spawnSync("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 50 * 1024 * 1024 })
+
+export type Change = {
+  files: string[]
+  diff: Map<string, string>
+  /** For each changed file, the repository's files that import it: a change to a helper reaches what uses it. */
+  usedBy?: Map<string, string[]>
+}
+
+const MAX_SCAN = 4000
+const MAX_READ = 300_000
+
+/** The files a change touches, its diff, and who imports each changed file, between the merge base of `base` and `head`. */
+export function changeOf(repo: string, base: string, head = "HEAD"): Change {
+  const range = `${base}...${head}`
+  const names = git(repo, ["diff", "--name-only", range])
+  if (names.status !== 0) throw new Error(`git diff ${range} failed in ${repo}: ${names.stderr.trim().split("\n")[0]}`)
+  const files = names.stdout.split("\n").map((l) => l.trim()).filter(Boolean)
+  const diff = new Map<string, string>()
+  const patch = git(repo, ["diff", "-U0", range])
+  let current = ""
+  for (const line of patch.stdout.split("\n")) {
+    const m = /^\+\+\+ b\/(.+)$/.exec(line)
+    if (m) current = m[1]
+    else if (current && (line.startsWith("+") || line.startsWith("-")) && !line.startsWith("---")) diff.set(current, `${diff.get(current) || ""}${line.slice(1)}\n`)
+  }
+  const usedBy = new Map<string, string[]>()
+  const changed = new Set(files)
+  const all = git(repo, ["ls-files"]).stdout.split("\n").map((l) => l.trim()).filter((f) => f && CODE.test(f) && !NOT_PRODUCT.test(f))
+  const known = new Set(all)
+  for (const rel of all.slice(0, MAX_SCAN)) {
+    let text = ""
+    try {
+      const file = path.join(repo, rel)
+      if (statSync(file).size <= MAX_READ) text = readFileSync(file, "utf8")
+    } catch {}
+    for (const dep of importsOf(rel, text, known)) if (changed.has(dep) && dep !== rel) usedBy.set(dep, [...(usedBy.get(dep) || []), rel])
+  }
+  return { files, diff, usedBy }
+}
+
+const LEVEL = (score: number): Level => (score >= 6 ? "high" : score >= 3 ? "medium" : "low")
+
+/** Score each area the change touches, with the reasons, riskiest first. */
+export function predict(facts: Map<string, AreaFacts>, change: Change): Pick<Prediction, "areas" | "untested" | "runFirst"> {
+  const product = change.files.filter((f) => CODE.test(f) && !NOT_PRODUCT.test(f))
+  const touched = new Set<string>()
+  const areas: RiskArea[] = []
+  for (const f of facts.values()) {
+    const words = areaWords(f.area)
+    const route = f.area.split("/:")[0]
+    const namedAfter = (file: string) => words.some((w) => file.toLowerCase().includes(w.toLowerCase()))
+    const named = product.filter(namedAfter)
+    // The route on its own: "/cart" in "/api/cart" is another route.
+    const own = new RegExp(`(^|[^\\w/-])${route.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`)
+    const mentioned = route.length > 1 ? product.filter((file) => own.test(change.diff.get(file) || "")) : []
+    const used = product.filter((file) => !named.includes(file) && (change.usedBy?.get(file) || []).some(namedAfter))
+    const changed = [...new Set([...mentioned, ...named, ...used])]
+    if (!changed.length) continue
+    for (const c of changed) touched.add(c)
+    const reasons: string[] = []
+    let score = 0
+    if (mentioned.length) {
+      score += 3
+      reasons.push(`the change mentions ${route} (${mentioned.slice(0, 3).join(", ")})`)
+    }
+    if (named.length) {
+      score += 2
+      reasons.push(`it changes ${named.slice(0, 3).join(", ")}${named.length > 3 ? ` and ${named.length - 3} more` : ""}`)
+    } else if (used.length) {
+      score += 1
+      const by = (change.usedBy?.get(used[0]) || []).filter(namedAfter)
+      reasons.push(`it changes ${used[0]}, which ${by.slice(0, 2).join(" and ")} import${by.length === 1 ? "s" : ""}${used.length > 1 ? ` (and ${used.length - 1} more such file${used.length === 2 ? "" : "s"})` : ""}`)
+    }
+    const defects = [...f.defects].sort((a, b) => b.seen - a.seen)
+    if (defects.length) {
+      score += 2 * Math.min(defects.length, 3)
+      reasons.push(`${defects.length} defect${defects.length === 1 ? "" : "s"} here before, the latest: ${defects[0].title}`)
+    }
+    const returned = defects.reduce((n, d) => n + d.returns, 0)
+    if (returned) {
+      score += 2
+      reasons.push(`defects came back here ${returned} time${returned === 1 ? "" : "s"} after they were fixed`)
+    }
+    if (defects.some((d) => d.open)) {
+      score += 1
+      reasons.push("a defect here is still open")
+    }
+    if (f.runs) {
+      const rate = f.failed / f.runs
+      if (rate >= 0.2) {
+        score += rate >= 0.5 ? 2 : 1
+        reasons.push(`its cases failed in ${f.failed} of ${f.runs} recent runs`)
+      }
+    }
+    if (!f.cases.size) reasons.push("no case ends on it: nothing tests it directly")
+    areas.push({ area: f.area, level: LEVEL(score), score, reasons, changed, cases: [...f.cases], defects })
+  }
+  areas.sort((a, b) => b.score - a.score || a.area.localeCompare(b.area))
+  const runFirst = [...new Set(areas.filter((a) => a.level !== "low").flatMap((a) => a.cases))]
+  return { areas, untested: product.filter((f) => !touched.has(f)), runFirst }
+}
+
+const predictionsFile = (folder: string) => path.join(folder, PREDICTIONS)
+
+export function readPredictions(folder: string): PredictionsFile {
+  try {
+    const d = JSON.parse(readFileSync(predictionsFile(folder), "utf8")) as PredictionsFile
+    return { version: 1, predictions: Array.isArray(d?.predictions) ? d.predictions : [] }
+  } catch {
+    return { version: 1, predictions: [] }
+  }
+}
+
+export function savePrediction(folder: string, p: Prediction): void {
+  const file = readPredictions(folder)
+  file.predictions = [...file.predictions, p].slice(-KEEP)
+  writeFileSync(predictionsFile(folder), `${JSON.stringify(file, null, 2)}\n`)
+}
+
+/**
+ * Score the newest prediction made before this suite, once: how many of the suite's defects fell in the areas it
+ * named (medium or high), and how many of its high areas had one. Returns it, scored, or undefined.
+ */
+export function scorePrediction(folder: string, suite: string, startedAt: string, clusters: DefectCluster[]): Prediction | undefined {
+  const file = readPredictions(folder)
+  const p = [...file.predictions].reverse().find((x) => x.at <= startedAt)
+  if (!p || p.scored) return undefined
+  const named = new Set(p.areas.filter((a) => a.level !== "low").map((a) => a.area))
+  const high = p.areas.filter((a) => a.level === "high").map((a) => a.area)
+  const hit = clusters.map((c) => areaOf(c)).filter((a): a is string => Boolean(a))
+  p.scored = { suite, at: startedAt, defects: hit.length, inPredicted: hit.filter((a) => named.has(a)).length, high: high.length, highWithDefect: high.filter((a) => hit.includes(a)).length }
+  writeFileSync(predictionsFile(folder), `${JSON.stringify(file, null, 2)}\n`)
+  return p
+}
+
+export type DefectTrends = {
+  suites: number
+  defects: number
+  open: number
+  gone: number
+  /** Defects that came back after going away, and how many times in all. */
+  regressions: number
+  returns: number
+  /** Days from first seen to gone, for the defects that went away. */
+  daysToFix?: { median: number; mean: number; count: number }
+  recurring: { id: string; title: string; seen: number; firstSeen: string; lastSeen: string; open: boolean; returns: number; bug?: { label: string; url?: string } }[]
+  areas: { area: string; defects: number; open: number; failed: number; runs: number; cases: number }[]
+  /** Defects found in each suite, oldest first. */
+  perSuite: { suite: string; at: string; defects: number; failed: number }[]
+  predictions?: { scored: number; defects: number; inPredicted: number; high: number; highWithDefect: number }
+}
+
+const DAY = 86_400_000
+
+/** How the defects of the suites in `folder` went over time. */
+export function defectTrends(folder: string): DefectTrends {
+  const h = readDefectHistory(path.join(folder, DEFECT_HISTORY))
+  const all = Object.entries(h.defects)
+  const suites = savedSuites(folder)
+  const days = all.filter(([, d]) => d.goneSince).map(([, d]) => (Date.parse(d.goneSince!) - Date.parse(d.firstSeen)) / DAY).filter((n) => n >= 0).sort((a, b) => a - b)
+  const round = (n: number) => Math.round(n * 10) / 10
+  const facts = areaFacts(folder, h)
+  const scored = readPredictions(folder).predictions.filter((p) => p.scored)
+  const sum = (k: keyof NonNullable<Prediction["scored"]>) => scored.reduce((n, p) => n + Number(p.scored![k] || 0), 0)
+  const perSuite = suites.map((s) => {
+    const json = (() => {
+      try {
+        return JSON.parse(readFileSync(path.join(folder, s.name, "suite.json"), "utf8")) as { defects?: unknown[] }
+      } catch {
+        return {}
+      }
+    })()
+    return { suite: s.name, at: s.at, defects: Array.isArray(json.defects) ? json.defects.length : 0, failed: s.results.filter((r) => r.status === "failed" || r.status === "error").length }
+  })
+  return {
+    suites: suites.length,
+    defects: all.length,
+    open: all.filter(([, d]) => !d.goneSince).length,
+    gone: all.filter(([, d]) => d.goneSince).length,
+    regressions: all.filter(([, d]) => d.returns?.length).length,
+    returns: all.reduce((n, [, d]) => n + (d.returns?.length || 0), 0),
+    ...(days.length ? { daysToFix: { median: round(days[Math.floor((days.length - 1) / 2)]), mean: round(days.reduce((a, b) => a + b, 0) / days.length), count: days.length } } : {}),
+    recurring: all
+      .map(([id, d]) => ({ id, title: d.title, seen: d.seen, firstSeen: d.firstSeen, lastSeen: d.lastSeen, open: !d.goneSince, returns: d.returns?.length || 0, ...(d.bug ? { bug: d.bug } : {}) }))
+      .sort((a, b) => b.seen - a.seen || b.lastSeen.localeCompare(a.lastSeen))
+      .slice(0, 10),
+    areas: [...facts.values()]
+      .filter((f) => f.defects.length || f.failed)
+      .map((f) => ({ area: f.area, defects: f.defects.length, open: f.defects.filter((d) => d.open).length, failed: f.failed, runs: f.runs, cases: f.cases.size }))
+      .sort((a, b) => b.defects - a.defects || b.failed - a.failed)
+      .slice(0, 10),
+    perSuite: perSuite.slice(-20),
+    ...(scored.length ? { predictions: { scored: scored.length, defects: sum("defects"), inPredicted: sum("inPredicted"), high: sum("high"), highWithDefect: sum("highWithDefect") } } : {}),
+  }
+}
+
+const pct = (a: number, b: number) => (b ? `${Math.round((a / b) * 100)}%` : "—")
+
+/** The trends as Markdown, for defect-trends.md and the terminal. */
+export function trendsMarkdown(t: DefectTrends, generated = new Date().toISOString().slice(0, 16).replace("T", " ")): string {
+  const cell = (s: string) => s.replace(/\|/g, "\\|")
+  const lines = [
+    `# Defect trends`,
+    "",
+    `${t.suites} suite run${t.suites === 1 ? "" : "s"} · ${t.defects} defect${t.defects === 1 ? "" : "s"} found by browser evidence: ${t.open} still there, ${t.gone} gone, ${t.regressions} came back (${t.returns} time${t.returns === 1 ? "" : "s"}) · generated ${generated} UTC`,
+    "",
+    t.daysToFix ? `Time to go away: median ${t.daysToFix.median} days, mean ${t.daysToFix.mean} days, over ${t.daysToFix.count} defect${t.daysToFix.count === 1 ? "" : "s"}.` : "Time to go away: no defect has gone away yet.",
+  ]
+  if (t.predictions) {
+    const p = t.predictions
+    lines.push("", `Predictions: ${p.scored} scored. ${p.inPredicted} of ${p.defects} defects (${pct(p.inPredicted, p.defects)}) fell in an area rated medium or high; ${p.highWithDefect} of ${p.high} high-risk areas (${pct(p.highWithDefect, p.high)}) had a defect.`)
+  }
+  if (t.recurring.length) {
+    lines.push("", "## Most seen", "", "| Defect | Runs | First seen | Last seen | Now | Came back | Bug |", "|---|---|---|---|---|---|---|")
+    for (const d of t.recurring) lines.push(`| ${cell(d.title)} | ${d.seen} | ${d.firstSeen.slice(0, 10)} | ${d.lastSeen.slice(0, 10)} | ${d.open ? "there" : "gone"} | ${d.returns || ""} | ${d.bug ? (d.bug.url ? `[${cell(d.bug.label)}](${d.bug.url})` : cell(d.bug.label)) : ""} |`)
+  }
+  if (t.areas.length) {
+    lines.push("", "## By area", "", "| Area | Defects | Still there | Case failures | Cases |", "|---|---|---|---|---|")
+    for (const a of t.areas) lines.push(`| ${cell(a.area)} | ${a.defects} | ${a.open} | ${a.runs ? `${a.failed} of ${a.runs}` : "—"} | ${a.cases} |`)
+  }
+  if (t.perSuite.length) {
+    lines.push("", "## Per suite", "", "| Suite | Started | Defects | Failed cases |", "|---|---|---|---|")
+    for (const s of t.perSuite) lines.push(`| ${s.suite} | ${s.at.slice(0, 16).replace("T", " ")} | ${s.defects} | ${s.failed} |`)
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** The prediction as Markdown lines, for the terminal and the agent. */
+export function predictionLines(p: Pick<Prediction, "areas" | "untested" | "runFirst" | "changed">): string[] {
+  const lines = [`${p.changed.length} changed file${p.changed.length === 1 ? "" : "s"}; ${p.areas.length} area${p.areas.length === 1 ? "" : "s"} touched.`]
+  for (const a of p.areas) {
+    lines.push("", `${a.level.toUpperCase()} ${a.area} (score ${a.score})`, ...a.reasons.map((r) => `  - ${r}`))
+    if (a.cases.length) lines.push(`  cases: ${a.cases.slice(0, 8).join(", ")}${a.cases.length > 8 ? ` and ${a.cases.length - 8} more` : ""}`)
+  }
+  if (p.runFirst.length) lines.push("", `Run first: ${p.runFirst.join(", ")}`)
+  if (p.untested.length) lines.push("", `Changed with no area ForgeQE has seen (nothing tests them yet): ${p.untested.slice(0, 10).join(", ")}${p.untested.length > 10 ? ` and ${p.untested.length - 10} more` : ""}`)
+  return lines
+}

package/src/cases/rca.ts

@@ -0,0 +1,258 @@
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { openSession, type AgentSpec, type OpencodeSession } from "../code/runtime.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { domainNotes } from "../domain.ts"
+import { prompt } from "../prompts.ts"
+import type { CodeEvent, Usage } from "../types.ts"
+import { costOf, type Cost } from "../usage.ts"
+import { lastPassed } from "./defectHistory.ts"
+import { routeOf, type DefectCluster } from "./defects.ts"
+import { reproText } from "./repro.ts"
+import type { CaseResult } from "./types.ts"
+
+/**
+ * Defect intelligence, part three (b): why a defect may happen. Always a hypothesis, never a verdict.
+ *
+ * - From the evidence alone, at no cost: the layer it most likely sits in (the server, the front end, access, the
+ *   environment) and the component (the route, the script).
+ * - From the product's repository (defects.product_repo): suspect commits, made since the defect's cases last
+ *   passed, whose changes mention its route or error (git log -G).
+ * - From a model, for new defects and regressions only (defects.analyze): a read-only agent reads the evidence, the
+ *   suspect commits, and the product's code, and writes a hypothesis with its confidence and how to confirm it.
+ */
+
+export type Suspect = { sha: string; subject: string; author: string; at: string; files: string[]; why: string }
+
+export type RootCause = {
+  layer: string
+  component?: string
+  /** What the layer was read from. */
+  basis: string
+  suspects?: Suspect[]
+  /** The commits searched, e.g. "since 2026-10-12, when SHOP-1 last passed". */
+  range?: string
+  hypothesis?: string
+  confidence?: "low" | "medium" | "high"
+  evidence?: string[]
+  confirm?: string[]
+  files?: string[]
+  /** Why there is no hypothesis or no suspect commits, when there is a reason to give. */
+  note?: string
+  model?: string
+  tokens?: number
+  usage?: Usage
+  cost?: Cost
+}
+
+const STATUS = /returns (\d{3})/
+
+/** The layer and component a defect points to, from its evidence. */
+export function layerOf(c: DefectCluster): Pick<RootCause, "layer" | "component" | "basis"> {
+  if (c.kind === "request") {
+    const status = Number(STATUS.exec(c.title)?.[1] || 0)
+    const component = c.title.replace(/ (returns \d{3}|fails)$/, "")
+    if (status >= 500) return { layer: "Server (API)", component, basis: `the server answered ${status}` }
+    if (status === 401 || status === 403) return { layer: "Access: sign-in or permissions", component, basis: `the server refused with ${status}` }
+    if (status === 404) return { layer: "API route or deployment", component, basis: "the route was not found" }
+    if (status >= 400) return { layer: "API request: the page sent what the server refused", component, basis: `the server answered ${status}` }
+    return { layer: "Network", component, basis: "the request did not complete" }
+  }
+  if (c.kind === "exception") {
+    const at = / at (\S+?)(?::\d+)?$/.exec(c.evidence[0] || "")?.[1]
+    return { layer: "Front end (JavaScript)", ...(at ? { component: routeOf(at) } : {}), basis: "an uncaught error in the page" }
+  }
+  if (c.kind === "console") return { layer: "Front end", ...(c.page ? { component: routeOf(c.page) } : {}), basis: "an error in the browser console" }
+  const page = c.page ? { component: routeOf(c.page) } : {}
+  if (c.failure === "environment") return { layer: "Environment", ...page, basis: "the run met an environment problem" }
+  if (c.failure === "test_case_issue") return { layer: "Test case", ...page, basis: "the test case does not fit the application" }
+  if (c.failure === "automation") return { layer: "Test automation", ...page, basis: "the browser agent could not finish" }
+  return { layer: "Application behaviour (a page or business rule)", ...page, basis: "the page showed a wrong result with no browser error" }
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+const GENERIC = new Set(["api", "v1", "v2", "v3", "rest", "graphql", "www", "app", "index", "home"])
+
+/** What a change that caused it would mention: the route and its words, or the error message. */
+export function searchTerms(c: DefectCluster): string[] {
+  if (c.kind === "request" && c.term) return [c.term, ...c.term.split("/").filter((w) => w.length >= 3 && !GENERIC.has(w.toLowerCase()))]
+  if (c.kind === "exception" && c.term) return [c.term, ...c.term.split(/\W+/).filter((w) => w.length >= 5).slice(0, 3)]
+  if (c.page) {
+    const p = routeOf(c.page)
+    return p.slice(p.indexOf("/")).split("/").filter((w) => w.length >= 3 && !GENERIC.has(w.toLowerCase()))
+  }
+  return []
+}
+
+const git = (repo: string, args: string[]) => spawnSync("git", ["-C", repo, ...args], { encoding: "utf8", maxBuffer: 20 * 1024 * 1024 })
+
+type Commit = { sha: string; subject: string; author: string; at: string; files: string[] }
+
+function commits(repo: string, args: string[]): Commit[] {
+  const out = git(repo, ["log", "--no-merges", "-n", "300", "--format=%x1e%H%x1f%an%x1f%aI%x1f%s", "--name-only", ...args])
+  if (out.status !== 0) return []
+  return out.stdout
+    .split("\x1e")
+    .filter((b) => b.trim())
+    .map((b) => {
+      const [head, ...files] = b.trim().split("\n")
+      const [sha, author, at, subject] = head.split("\x1f")
+      return { sha, author, at, subject, files: files.map((f) => f.trim()).filter(Boolean) }
+    })
+}
+
+/**
+ * Commits since `since` whose changes mention the defect's terms (strongest first), or whose files are named after
+ * them. Five at most; none when the folder is not a git repository.
+ */
+export function suspectCommits(repo: string, c: DefectCluster, since: string): Suspect[] {
+  const terms = searchTerms(c)
+  if (!terms.length || !existsSync(path.join(repo, ".git"))) return []
+  const changed = commits(repo, [`--since=${since}`, "-i", `-G${terms.map(escape).join("|")}`])
+  const all = commits(repo, [`--since=${since}`])
+  const scored = new Map<string, { c: Commit; score: number; why: string[] }>()
+  for (const x of changed) scored.set(x.sha, { c: x, score: 2, why: [`its changes mention ${terms.slice(0, 2).map((t) => `\`${t}\``).join(" or ")}`] })
+  for (const x of all) {
+    const named = x.files.filter((f) => terms.slice(1).some((t) => f.toLowerCase().includes(t.toLowerCase())))
+    if (!named.length) continue
+    const s = scored.get(x.sha) || { c: x, score: 0, why: [] }
+    s.score += 1
+    s.why.push(`it changes ${named.slice(0, 2).map((f) => `\`${f}\``).join(", ")}`)
+    scored.set(x.sha, s)
+  }
+  return [...scored.values()]
+    .sort((a, b) => b.score - a.score || b.c.at.localeCompare(a.c.at))
+    .slice(0, 5)
+    .map(({ c: x, why }) => ({ sha: x.sha, subject: x.subject, author: x.author, at: x.at, files: x.files.slice(0, 8), why: why.join("; ") }))
+}
+
+/** The layer, and the suspect commits when the product's repository is known: no model, no cost. */
+export function basicCause(c: DefectCluster, opts: { suiteDir: string; productRepo?: string; now?: string }): RootCause {
+  const rc: RootCause = { ...layerOf(c) }
+  if (!opts.productRepo) return rc
+  const passed = lastPassed(opts.suiteDir, c.cases.map((x) => x.id))
+  if (!passed) {
+    rc.note = "No earlier run where its cases passed: no commit range to search."
+    return rc
+  }
+  rc.range = `since ${passed.slice(0, 16).replace("T", " ")}, the last run where its cases passed`
+  rc.suspects = suspectCommits(opts.productRepo, c, passed)
+  return rc
+}
+
+export const rcaAgentPrompt = () => prompt("defect-rca")
+
+export const RCA_AGENT: AgentSpec = {
+  name: "forgeqe-defect-rca",
+  description: "Writes a root-cause hypothesis for a defect from its evidence and the product's code",
+  get prompt() {
+    return rcaAgentPrompt()
+  },
+  permission: {
+    edit: "deny",
+    webfetch: "deny",
+    task: "deny",
+    "live_*": "deny",
+    bash: { "*": "deny", "git log*": "allow", "git show*": "allow", "git diff*": "allow", "git blame*": "allow", "git ls-files*": "allow", "git grep*": "allow", "ls*": "allow" },
+  },
+  steps: 25,
+}
+
+const lines = { type: "array", items: { type: "string" } } as const
+
+export const RCA_SCHEMA = {
+  type: "object",
+  properties: {
+    hypothesis: { type: "string", description: "The most likely cause, in two sentences or fewer" },
+    confidence: { type: "string", enum: ["low", "medium", "high"] },
+    layer: { type: "string", description: "Where the cause most likely sits, e.g. Server (API), Front end, Data, Configuration" },
+    component: { type: "string", description: "The file, module, route, or service, as named in the code or the evidence" },
+    evidence: { ...lines, description: "The facts the hypothesis rests on, each from the evidence or a file you read, with where" },
+    confirm: { ...lines, description: "Checks a developer can make to confirm or reject it" },
+    files: { ...lines, description: "Repository paths of the code to look at first" },
+  },
+  required: ["hypothesis", "confidence", "layer", "evidence", "confirm", "files"],
+} as const
+
+type RcaReport = { hypothesis?: string; confidence?: string; layer?: string; component?: string; evidence?: string[]; confirm?: string[]; files?: string[] }
+
+/** What the agent is told: the defect, how it happened, its history, and the suspect commits. */
+export function rcaPrompt(c: DefectCluster, first: CaseResult, rc: RootCause, productRepo?: string): string {
+  return [
+    `Defect: ${c.title}`,
+    `Kind of failure: ${c.failureLabel}. It breaks ${c.cases.length} case${c.cases.length === 1 ? "" : "s"}: ${c.cases.map((x) => `${x.id} ${x.title}`).join("; ")}.`,
+    "",
+    "Evidence from the runs:",
+    ...c.evidence.map((e) => `- ${e}`),
+    ...(c.pages.length ? [`Pages: ${c.pages.join(", ")}`] : []),
+    "",
+    `What the browser agent reported for ${first.case.id}: ${first.summary.split("\n")[0]}`,
+    ...(c.repro ? ["", reproText(c.repro)] : []),
+    "",
+    `From the evidence alone: layer ${rc.layer}${rc.component ? `, component ${rc.component}` : ""} (${rc.basis}).`,
+    ...(c.history ? [`History: ${c.history.status}${c.history.seen ? `, seen in ${c.history.seen} earlier runs` : ""}${c.history.previousBug ? `, earlier bug ${c.history.previousBug.label}` : ""}.`] : []),
+    ...(rc.suspects?.length ? ["", `Suspect commits (${rc.range}):`, ...rc.suspects.map((s) => `- ${s.sha.slice(0, 10)} ${s.subject} (${s.author}, ${s.at.slice(0, 10)}): ${s.why}. Files: ${s.files.join(", ")}`)] : rc.range ? ["", `No commit ${rc.range} mentions it.`] : []),
+    "",
+    productRepo ? `The product's code is in ${productRepo}. Read it.` : "You have no access to the product's code. Reason from the evidence only, and say so in the confidence.",
+  ].join("\n")
+}
+
+/**
+ * The model's hypothesis for one defect, added to `rc`. A failure leaves `rc` with what it had and a note: the
+ * analysis is a hint, never a reason for a suite to fail.
+ */
+export async function analyzeCause(
+  config: AppConfig,
+  c: DefectCluster,
+  first: CaseResult,
+  rc: RootCause,
+  opts: { cwd: string; productRepo?: string; signal?: AbortSignal; onEvent?: (e: CodeEvent) => void; open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<RcaReport>> },
+): Promise<RootCause> {
+  const repo = opts.productRepo || opts.cwd
+  const open = (opts.open || openSession) as (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<RcaReport>>
+  let session: OpencodeSession<RcaReport> | undefined
+  try {
+    session = await open({
+      repo,
+      profile: config.llm,
+      domain: domainNotes(config),
+      model: config.code.model,
+      bin: config.code.opencode,
+      readDirs: [repo],
+      hide: privateEnvNames(config),
+      signal: opts.signal,
+      onEvent: opts.onEvent,
+      agent: RCA_AGENT,
+      schema: RCA_SCHEMA as unknown as Record<string, unknown>,
+      title: `ForgeQE root cause: ${c.title}`.slice(0, 120),
+      role: "root-cause analyst",
+    })
+    let reply = await session.prompt(rcaPrompt(c, first, rc, opts.productRepo))
+    if (!reply.report && !reply.error && !opts.signal?.aborted) reply = await session.prompt("Give the structured result: hypothesis, confidence, layer, component, evidence, confirm, and files.")
+    const usage: Usage = { ...session.usage }
+    const spent = { model: session.model, tokens: usage.input + usage.output, usage, ...(costOf(usage, config.llm.price) ? { cost: costOf(usage, config.llm.price) } : {}) }
+    const r = reply.report
+    if (!r?.hypothesis) return { ...rc, ...spent, note: `No hypothesis${reply.error ? `: ${reply.error}` : "."}` }
+    const confidence = r.confidence === "high" || r.confidence === "medium" ? r.confidence : "low"
+    // A guess does not replace what the evidence says: the model's layer and component only with code behind them.
+    const sure = confidence !== "low"
+    return {
+      ...rc,
+      ...(sure && r.layer ? { layer: r.layer } : {}),
+      ...(sure && r.component ? { component: r.component } : {}),
+      hypothesis: r.hypothesis.trim(),
+      confidence,
+      evidence: (r.evidence || []).map(String).filter(Boolean).slice(0, 8),
+      confirm: (r.confirm || []).map(String).filter(Boolean).slice(0, 5),
+      files: (r.files || []).map(String).filter(Boolean).slice(0, 8),
+      ...spent,
+    }
+  } catch (err) {
+    return { ...rc, note: `No hypothesis: ${(err as Error).message.split("\n")[0].slice(0, 200)}` }
+  } finally {
+    await session?.close()
+  }
+}