@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/heal/loop.ts

@@ -0,0 +1,357 @@
+import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { CodeEvent, Usage } from "../types.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { addUsage, costOf, meterSince, meterSnapshot, type Cost } from "../usage.ts"
+import { openSession, type OpencodeSession } from "../code/runtime.ts"
+import { runTestCommand, type TestRun } from "../code/testrun.ts"
+import { changedFiles, ownPaths, protectPatterns, restoreRemoved, snapshot } from "../code/worktree.ts"
+import type { AppConfig } from "../config.ts"
+import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
+import { TOOLS, environmentNotes, type ToolContext, type ToolEvent } from "../mcp/tools.ts"
+import { runDirectory } from "../run.ts"
+import {
+  healAgentPrompt,
+  HEAL_SCHEMA,
+  findCommandPrompt,
+  firstHealPrompt,
+  missingTestsPrompt,
+  healNextPrompt,
+  remainingPrompt,
+  stillFailingPrompt,
+  type HealReport,
+  type HealVerdict,
+} from "./prompt.ts"
+import { healMarkdown } from "./report.ts"
+import { loadSkills } from "../skills/registry.ts"
+import { domainNotes } from "../domain.ts"
+
+export const HEAL_AGENT = "forgeqe-heal"
+const HEAL_TOOLS = new Set(["browser_run", "run_details", "run_test", "page_memory"])
+const FATAL_ERRORS = ["ProviderAuthError", "APIError", "ContextOverflowError", "ContentFilterError"]
+
+export type HealStatus = "passed" | "failed" | "stopped" | "clean"
+
+export type HealTest = {
+  name: string
+  file?: string
+  status: HealVerdict
+  command?: string
+  reason?: string
+  runDir?: string
+  /** ForgeQE ran the test's command itself and it passed. */
+  verified?: boolean
+}
+
+export type CommandResult = { exitCode: number | null; output: string; ms: number }
+
+export type HealResult = {
+  status: HealStatus
+  repo: string
+  command: string
+  attempts: number
+  maxAttempts: number
+  tests: HealTest[]
+  changed: string[]
+  notes: string
+  /** The test command before and after healing, as ForgeQE ran it. */
+  before?: CommandResult
+  after?: CommandResult
+  /** Browser runs the agent made to see what the pages do now. */
+  runs: string[]
+  usage: Usage
+  /** What `usage` cost at the profile's price; unset without one. */
+  cost?: Cost
+  /** The whole job, browser runs included: tokens and cost from the usage meter. */
+  total?: { usage: Usage; cost?: Cost }
+  /** Skills the agent loaded. */
+  skills?: string[]
+  model: string
+  dir: string
+  startedAt: string
+  ms: number
+}
+
+export type HealOptions = {
+  config: AppConfig
+  repo: string
+  /** The repo's test command; default code.test_command, else the agent finds it. */
+  command?: string
+  outDir?: string
+  headed?: boolean
+  maxSteps?: number
+  url?: string
+  signal?: AbortSignal
+  /** Scribe's progress: tool calls, thoughts, test runs, tokens. */
+  onEvent?: (e: CodeEvent) => void
+  /** Browser runs the agent starts through ForgeQE's tools. */
+  onTool?: (e: ToolEvent) => void
+  /** Replaces openSession; tests use it to script the agent. */
+  open?: (o: Parameters<typeof openSession<HealReport>>[0]) => Promise<OpencodeSession<HealReport>>
+  /** Replaces executeRun for browser_run; tests use it. */
+  execute?: ToolContext["execute"]
+}
+
+function realpathOr(dir: string): string {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return path.resolve(dir)
+  }
+}
+
+const commandResult = (run: TestRun): CommandResult => ({ exitCode: run.exitCode, output: run.output, ms: run.ms })
+
+/**
+ * Run the repo's tests; when they fail, Scribe, with ForgeQE's browser tools, heals the tests the app has
+ * outgrown and reports real app bugs. ForgeQE re-runs every test the agent calls healed, then the whole command,
+ * and only its own runs count.
+ */
+export async function runHeal(opts: HealOptions): Promise<HealResult> {
+  const given = path.resolve(opts.repo)
+  if (!existsSync(given) || !statSync(given).isDirectory()) throw new Error(`Repo not found: ${given}`)
+  const repo = realpathSync(given)
+  const { config } = opts
+  const emit = opts.onEvent || (() => {})
+  const t0 = Date.now()
+  const meterStart = meterSnapshot()
+  let spent: Usage = { input: 0, output: 0 }
+  const dir = runDirectory(path.join(config.export.outDir, "heal"), opts.outDir)
+  mkdirSync(dir, { recursive: true })
+  // Browser runs land inside this heal's folder, and run_details' default (the latest run) finds them there.
+  const runsConfig: AppConfig = { ...config, export: { ...config.export, outDir: dir } }
+  const maxAttempts = Math.max(1, config.code.maxAttempts)
+  const timeoutSeconds = config.code.testTimeoutSeconds
+
+  const result: HealResult = {
+    status: "failed",
+    repo,
+    command: opts.command || config.code.testCommand || "",
+    attempts: 0,
+    maxAttempts,
+    tests: [],
+    changed: [],
+    notes: "",
+    runs: [],
+    usage: { input: 0, output: 0 },
+    model: "",
+    dir,
+    startedAt: new Date(t0).toISOString(),
+    ms: 0,
+  }
+
+  const onTool = (e: ToolEvent) => {
+    if (e.type === "run-done" && e.runDir && !result.runs.includes(e.runDir)) result.runs.push(e.runDir)
+    opts.onTool?.(e)
+  }
+  const context = (): ToolContext => ({
+    config: runsConfig,
+    cwd: repo,
+    headed: opts.headed,
+    maxSteps: opts.maxSteps,
+    url: opts.url,
+    signal: opts.signal,
+    emit: onTool,
+    execute: opts.execute,
+  })
+
+  const agent: { tools?: ReturnType<typeof localToolServer>; session?: OpencodeSession<HealReport> } = {}
+  // Healing edits tests, never ForgeQE's config, runs, or page memory: denied to the agent, and put back if changed anyway.
+  const own = ownPaths(repo, [config.export.outDir, config.memory.dir])
+  const outside = [config.export.outDir, config.memory.dir].map((d) => realpathOr(d)).filter((d) => path.relative(repo, d).startsWith(".."))
+  const before = snapshot(repo, own)
+  const openAgent = async () => {
+    const tools = localToolServer({ tools: TOOLS.filter((t) => HEAL_TOOLS.has(t.name)), context, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
+    agent.tools = tools
+    const readDirs = [...new Set([given, config.export.outDir, config.memory.dir].flatMap((d) => [path.resolve(d), realpathOr(d)]))]
+    const s = await (opts.open || openSession<HealReport>)({
+      repo,
+      profile: config.llm,
+      domain: domainNotes(config),
+      model: config.code.model,
+      bin: config.code.opencode,
+      readDirs,
+      hide: privateEnvNames(config),
+      protect: protectPatterns(repo, own, outside),
+      signal: opts.signal,
+      onEvent: emit,
+      agent: { name: HEAL_AGENT, description: "Heals tests the app has outgrown and reports real app bugs", prompt: `${healAgentPrompt()}\n\nThis session:\n${environmentNotes(context())}`, skills: "scribe" },
+      skills: loadSkills(config.skills, repo).skills,
+      schema: HEAL_SCHEMA as unknown as Record<string, unknown>,
+      mcp: { [MCP_NAME]: tools.entry },
+      hideTool: (tool) => tool.startsWith(`${MCP_NAME}_`),
+      title: "ForgeQE heal",
+    })
+    agent.session = s
+    result.model = s.model
+    return s
+  }
+
+  const run = async (command: string) => runTestCommand({ command, cwd: repo, timeoutSeconds, signal: opts.signal, hide: privateEnvNames(config) })
+  const stopped = () => Boolean(opts.signal?.aborted)
+  const secs = (ms: number) => `${Math.round(ms / 1000)}s`
+  const failWhy = (r: TestRun) => (r.exitCode === null ? `timed out after ${timeoutSeconds}s` : `exit ${r.exitCode}`)
+
+  try {
+    if (!result.command) {
+      const session = await openAgent()
+      emit({ type: "code", kind: "info", text: `Scribe (${session.model}) is finding the test command in ${repo}` })
+      const reply = await session.prompt(findCommandPrompt())
+      if (stopped()) {
+        result.status = "stopped"
+        return result
+      }
+      result.command = reply.report?.suite_command?.trim() || ""
+      if (!result.command) {
+        result.notes = reply.error || "The agent did not find a test command. Pass one: forgeqe heal \"<command>\", or set code.test_command."
+        return result
+      }
+    }
+
+    emit({ type: "code", kind: "info", text: `ForgeQE runs the tests: ${result.command}` })
+    const baseline = await run(result.command)
+    result.before = commandResult(baseline)
+    if (stopped()) {
+      result.status = "stopped"
+      return result
+    }
+    if (baseline.ok) {
+      result.status = "clean"
+      result.after = result.before
+      emit({ type: "code", kind: "test", ok: true, attempt: 0, text: `All tests pass (${secs(baseline.ms)}); nothing to heal` })
+      return result
+    }
+    emit({ type: "code", kind: "test", ok: false, attempt: 0, text: `Tests failed, ${failWhy(baseline)} (${secs(baseline.ms)})` })
+
+    let session = agent.session || (await openAgent())
+    emit({ type: "code", kind: "info", text: `Scribe (${session.model}) is healing the failing tests in ${repo}` })
+    // Each attempt after a failed re-run starts a new session from the state of the job (healNextPrompt), so the
+    // model is not sent every earlier attempt's tool calls again.
+    const attemptLog: string[] = []
+    const freshSession = async (attempt: number, outcome: string, task: string): Promise<string> => {
+      attemptLog.push(`${attempt}: ${outcome}`)
+      spent = addUsage(spent, session.usage)
+      await session.close()
+      agent.tools?.server.abortAll()
+      agent.tools?.stop()
+      session = await openAgent()
+      emit({ type: "code", kind: "info", text: `Scribe starts attempt ${attempt + 1} in a fresh session, from a summary of the job so far` })
+      return healNextPrompt({ command: result.command, tests: result.tests, changed: changedFiles(repo, result.changed), attempts: attemptLog, task })
+    }
+    const byName = new Map<string, HealTest>()
+    let full: TestRun | undefined
+    let verifiedSinceFull = false
+    let prompt = firstHealPrompt(result.command, baseline)
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      result.attempts = attempt
+      const reply = await session.prompt(prompt)
+      if (stopped()) {
+        result.status = "stopped"
+        break
+      }
+      if (reply.error && FATAL_ERRORS.some((name) => reply.error!.startsWith(name))) {
+        result.notes = reply.error
+        emit({ type: "code", kind: "info", text: `Scribe stopped: ${reply.error}` })
+        break
+      }
+      const report = reply.report
+      if (report?.changed) result.changed = [...new Set([...result.changed, ...report.changed])]
+      if (report?.notes) result.notes = report.notes
+      if (!report?.tests?.length) {
+        emit({ type: "code", kind: "test", ok: false, attempt, text: "no failing tests reported yet" })
+        prompt = missingTestsPrompt()
+        continue
+      }
+      for (const t of report.tests) {
+        const prev = byName.get(t.name)
+        const next: HealTest = {
+          ...prev,
+          name: t.name,
+          status: t.status,
+          ...(t.file ? { file: t.file } : {}),
+          ...(t.command ? { command: t.command } : {}),
+          ...(t.reason ? { reason: t.reason } : {}),
+          ...(t.run_dir ? { runDir: path.resolve(repo, t.run_dir) } : {}),
+        }
+        const unchanged = prev?.verified && prev.status === "healed" && t.status === "healed" && (!t.command || t.command === prev.command)
+        next.verified = unchanged ? true : undefined
+        byName.set(t.name, next)
+      }
+      result.tests = [...byName.values()]
+
+      const pending = result.tests.filter((t) => t.status === "healed" && !t.verified)
+      if (!pending.length) break
+
+      const failures: { name: string; command?: string; run?: TestRun }[] = []
+      for (const t of pending) {
+        if (!t.command) {
+          failures.push({ name: t.name })
+          emit({ type: "code", kind: "test", ok: false, attempt, text: `${t.name}: no command to run it on its own` })
+          continue
+        }
+        emit({ type: "code", kind: "info", text: `ForgeQE runs: ${t.command}` })
+        const r = await run(t.command)
+        if (stopped()) break
+        if (r.ok) {
+          t.verified = true
+          verifiedSinceFull = true
+          emit({ type: "code", kind: "test", ok: true, attempt, text: `${t.name} passed in ${secs(r.ms)}` })
+        } else {
+          failures.push({ name: t.name, command: t.command, run: r })
+          emit({ type: "code", kind: "test", ok: false, attempt, text: `${t.name} failed, ${failWhy(r)}` })
+        }
+      }
+      if (stopped()) {
+        result.status = "stopped"
+        break
+      }
+      if (failures.length) {
+        if (attempt < maxAttempts) prompt = await freshSession(attempt, `${failures.map((f) => f.name).join(", ")} still failing`, stillFailingPrompt(failures))
+        continue
+      }
+
+      emit({ type: "code", kind: "info", text: `ForgeQE runs the tests: ${result.command}` })
+      full = await run(result.command)
+      verifiedSinceFull = false
+      if (stopped()) {
+        result.status = "stopped"
+        break
+      }
+      emit({ type: "code", kind: "test", ok: full.ok, attempt, text: full.ok ? `All tests pass (${secs(full.ms)})` : `Tests still fail, ${failWhy(full)}` })
+      if (full.ok) break
+      if (attempt < maxAttempts) prompt = await freshSession(attempt, `the tests still fail, ${failWhy(full)}`, remainingPrompt(result.command, full))
+    }
+
+    if (result.status !== "stopped") {
+      if (verifiedSinceFull) {
+        emit({ type: "code", kind: "info", text: `ForgeQE runs the tests: ${result.command}` })
+        full = await run(result.command)
+        emit({ type: "code", kind: "test", ok: full.ok, attempt: result.attempts, text: full.ok ? `All tests pass (${secs(full.ms)})` : `Tests still fail, ${failWhy(full)}` })
+      }
+      if (stopped()) result.status = "stopped"
+      else {
+        result.after = full ? commandResult(full) : result.before
+        result.status = result.after?.exitCode === 0 ? "passed" : "failed"
+      }
+    }
+    return result
+  } finally {
+    if (agent.session) {
+      result.usage = addUsage(spent, agent.session.usage)
+      result.cost = costOf(result.usage, config.code.model ? undefined : config.llm.price)
+      if (agent.session.skillsUsed?.length) result.skills = [...agent.session.skillsUsed]
+      await agent.session.close()
+    }
+    agent.tools?.server.abortAll()
+    agent.tools?.stop()
+    const restored = restoreRemoved(before, "own")
+    if (restored.length) emit({ type: "code", kind: "info", text: `Put back ${restored.join(", ")}: the agent changed ForgeQE's files` })
+    result.ms = Date.now() - t0
+    const jobTotal = meterSince(meterStart)
+    result.total = { usage: jobTotal.total, cost: jobTotal.cost }
+    writeFileSync(path.join(dir, "heal.json"), `${JSON.stringify(result, null, 2)}\n`)
+    writeFileSync(path.join(dir, "heal.md"), healMarkdown(result))
+  }
+}

package/src/heal/prompt.ts

@@ -0,0 +1,143 @@
+import type { ChangedFile } from "../code/prompt.ts"
+import { prompt } from "../prompts.ts"
+
+/** How to fix tests broken by changes in the app. The heal agent and ForgeQE's own agent both follow it. */
+export const HEAL_BRIEF = `- Work on failing tests only; leave passing tests alone.
+- For each failing test, read it and the page objects, fixtures, and helpers it uses, and work out why it fails:
+  - the app changed under the test (an element was renamed or moved, a locator no longer matches, a step was added or removed, text or timing changed): heal the test;
+  - the test's own code, config, or environment is broken (an import, a dependency, the base URL, test data): fix that;
+  - the app no longer does what the test checks: that is a bug in the app, not in the test.
+- When a failure involves the page, find out what the page does now before changing anything: run the flow the test covers with browser_run, as a plain-language goal that names the start page, each step, and each check the test makes. Do not put locators in the goal.
+  - If the browser run passes, the flow still works and the test is out of date. Call run_details for that run and update the test with the steps and the highest-confidence locators it recorded. When the locator lives in a page object, fixture, or helper, fix it there once.
+  - If the browser run fails at the step where the test fails, the app is broken there. Do not change the test to make it pass; report it as an app bug with what the browser run found.
+- Keep each test's intent. Never delete or skip a test, loosen or remove an assertion, or raise a timeout just to get a pass.
+- Run each healed test with run_test until it passes, then the whole test command again.`
+
+/** System prompt of Scribe behind `forgeqe heal`. */
+export const healAgentPrompt = () => prompt("heal")
+
+export const HEAL_SCHEMA = {
+  type: "object",
+  properties: {
+    tests: {
+      type: "array",
+      description: "Every test that failed, including ones you could not heal",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The test as the runner names it, e.g. tests/login.spec.ts › signs in" },
+          file: { type: "string", description: "Test file, relative to the repository root" },
+          status: {
+            type: "string",
+            enum: ["healed", "app_bug", "not_healed"],
+            description: "healed: fixed and passing when you run it. app_bug: the app is broken at the step the test checks. not_healed: you could not fix it",
+          },
+          command: { type: "string", description: "Command, from the repository root, that runs only this test non-interactively; required for healed tests" },
+          reason: { type: "string", description: "Why it failed and what you changed, or what is broken in the app" },
+          run_dir: { type: "string", description: "Folder of the browser run you used, if any" },
+        },
+        required: ["name", "status"],
+      },
+    },
+    changed: { type: "array", items: { type: "string" }, description: "Files created or modified" },
+    notes: { type: "string", description: "Anything the user should know, in one or two sentences" },
+    suite_command: { type: "string", description: "Only when asked for it: the command that runs the repository's tests" },
+  },
+  required: ["tests"],
+} as const
+
+export type HealVerdict = "healed" | "app_bug" | "not_healed"
+
+export type HealReport = {
+  tests?: { name: string; file?: string; status: HealVerdict; command?: string; reason?: string; run_dir?: string }[]
+  changed?: string[]
+  notes?: string
+  suite_command?: string
+}
+
+export type CommandRun = { exitCode: number | null; output: string }
+
+function outcome(run: CommandRun): string {
+  return run.exitCode === null ? "timed out" : `exited with code ${run.exitCode}`
+}
+
+function fenced(output: string): string[] {
+  return ["```", output.trimEnd() || "(no output)", "```"]
+}
+
+export function findCommandPrompt(): string {
+  return "Before fixing anything, find the command that runs this repository's browser or UI tests from the repository root, non-interactively (for example npx playwright test). Do not run it and do not change files yet. Answer with suite_command and an empty tests list."
+}
+
+export function firstHealPrompt(command: string, run: CommandRun): string {
+  return [
+    `ForgeQE ran this repository's tests with \`${command}\` and it ${outcome(run)}. The end of the output:`,
+    "",
+    ...fenced(run.output),
+    "",
+    "Heal the failing tests as your instructions describe, then give the structured result for every test that failed.",
+  ].join("\n")
+}
+
+export function stillFailingPrompt(failures: { name: string; command?: string; run?: CommandRun }[]): string {
+  const parts = failures.flatMap((f) =>
+    !f.command
+      ? [`- ${f.name}: you gave no command that runs only this test.`]
+      : [`- ${f.name}: \`${f.command}\` ${outcome(f.run!)}.`, "", ...fenced(f.run!.output), ""],
+  )
+  return [
+    "ForgeQE ran the tests you reported as healed, and these do not pass:",
+    "",
+    ...parts,
+    "Fix them and run them until they pass, or report them as app_bug or not_healed. Then give the structured result again for every test that failed.",
+  ].join("\n")
+}
+
+export function remainingPrompt(command: string, run: CommandRun): string {
+  return [
+    `Your healed tests pass on their own, but \`${command}\` still ${outcome(run)}. The end of the output:`,
+    "",
+    ...fenced(run.output),
+    "",
+    "Account for every test that still fails: heal it, or report it as app_bug or not_healed with the reason. Then give the structured result again for every test that failed.",
+  ].join("\n")
+}
+
+export function missingTestsPrompt(): string {
+  return "Your result did not list the failing tests. Give the structured result with every test that failed, each as healed, app_bug, or not_healed, with a command that runs only that test."
+}
+
+/**
+ * The first prompt of a fresh session for the next healing attempt: the state of the job instead of the earlier
+ * attempts' conversation, so the model is not sent every earlier tool call again.
+ */
+export function healNextPrompt(opts: {
+  command: string
+  tests: { name: string; status: string; file?: string; command?: string; reason?: string; verified?: boolean }[]
+  changed: ChangedFile[]
+  attempts: string[]
+  task: string
+}): string {
+  const files = opts.changed.map((f) =>
+    f.content === undefined ? `- ${f.path} (read it if you need it)` : [`### ${f.path}`, "", "```", f.content.trimEnd(), "```"].join("\n"),
+  )
+  return [
+    "You are continuing a healing job in a new session. The earlier attempts' conversation is not here; this message carries what matters from it. Read another file only when the fix needs it.",
+    "",
+    `The test command: ${opts.command}`,
+    "",
+    "Your verdicts so far:",
+    ...opts.tests.map((t) => `- ${t.name}: ${t.status}${t.verified ? " (ForgeQE confirmed it passes)" : ""}${t.file ? `, ${t.file}` : ""}${t.command ? `, run with: ${t.command}` : ""}${t.reason ? `. ${t.reason.replace(/\s+/g, " ").slice(0, 300)}` : ""}`),
+    "",
+    "Attempts, in order:",
+    ...opts.attempts.map((a) => `- ${a}`),
+    "",
+    "Files this job changed, as they are now:",
+    "",
+    ...(files.length ? files : ["(none yet)"]),
+    "",
+    "## Now",
+    "",
+    opts.task,
+  ].join("\n")
+}

package/src/heal/report.ts

@@ -0,0 +1,95 @@
+import path from "node:path"
+
+import { cardText, type Card, type CardStatus } from "../card.ts"
+import { formatDuration, formatTokens } from "../tui/theme.ts"
+import { usageLine } from "../usage.ts"
+import type { HealResult, HealStatus, HealTest } from "./loop.ts"
+
+const TITLE: Record<HealStatus, string> = {
+  clean: "Nothing to heal",
+  passed: "Tests healed",
+  failed: "Tests still failing",
+  stopped: "Healing stopped",
+}
+
+const STATUS: Record<HealStatus, CardStatus> = { clean: "ok", passed: "ok", failed: "fail", stopped: "stopped" }
+
+const VERDICT: Record<HealTest["status"], string> = { healed: "healed", app_bug: "app bug", not_healed: "not healed" }
+
+function testMark(t: HealTest): string {
+  if (t.status === "healed") return t.verified ? "✓" : "?"
+  return t.status === "app_bug" ? "!" : "✗"
+}
+
+const OUTPUT_CHARS = 4000
+
+function tail(s: string): string {
+  return s.length <= OUTPUT_CHARS ? s : `…${s.slice(-OUTPUT_CHARS)}`
+}
+
+function exit(r: { exitCode: number | null; ms: number }): string {
+  return `${r.exitCode === null ? "timed out" : `exit ${r.exitCode}`} after ${formatDuration(r.ms)}`
+}
+
+/** heal.md: the command before and after, each failing test's verdict, the browser runs, and the files changed. */
+export function healMarkdown(r: HealResult): string {
+  const cell = (s: string) => s.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim()
+  const lines = [
+    `# ForgeQE heal: ${TITLE[r.status].toLowerCase()}`,
+    "",
+    `- Repo: ${r.repo}`,
+    `- Command: ${r.command ? `\`${r.command}\`` : "(none found)"}`,
+    `- Started: ${r.startedAt}, took ${formatDuration(r.ms)}`,
+    ...(r.model ? [`- Agent: ${r.model}, ${r.attempts}/${r.maxAttempts} attempts, ${formatTokens(r.usage.input + r.usage.output)} tokens`] : []),
+    ...(r.total && (r.total.usage.input || r.total.usage.output) ? [`- Usage: ${usageLine(r.total.usage, r.total.cost)}`] : []),
+    ...(r.notes ? ["", r.notes] : []),
+  ]
+  if (r.tests.length) {
+    lines.push("", "## Failing tests", "", "| | Test | Verdict | Why | Browser run |", "|---|---|---|---|---|")
+    for (const t of r.tests) {
+      const verdict = t.status === "healed" && !t.verified ? "healed (not confirmed by ForgeQE)" : VERDICT[t.status]
+      lines.push(`| ${testMark(t)} | ${cell(t.name)} | ${verdict} | ${cell(t.reason || "")} | ${t.runDir ? cell(path.relative(r.dir, t.runDir) || t.runDir) : ""} |`)
+    }
+  }
+  if (r.changed.length) lines.push("", "## Files changed", "", ...r.changed.map((f) => `- ${f}`))
+  if (r.runs.length) lines.push("", "## Browser runs", "", ...r.runs.map((d) => `- ${d} (report.html)`))
+  for (const [title, run] of [
+    ["Before", r.before],
+    ["After", r.status === "clean" ? undefined : r.after],
+  ] as const) {
+    if (run) lines.push("", `## ${title}: ${exit(run)}`, "", "```", tail(run.output).trimEnd() || "(no output)", "```")
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** The end-of-heal summary, as a card for the shell. */
+export function healCard(r: HealResult, cwd = process.cwd()): Card {
+  const stats = [
+    r.model ? `${r.attempts}/${r.maxAttempts} ${r.maxAttempts === 1 ? "attempt" : "attempts"}` : "",
+    formatDuration(r.ms),
+    r.model ? `${formatTokens(r.usage.input + r.usage.output)} tokens` : "",
+    r.model,
+  ].filter(Boolean)
+  const lines: string[] = []
+  if (r.status === "clean") lines.push(`${r.command} passes; nothing needed healing.`)
+  for (const t of r.tests) {
+    const verdict = t.status === "healed" && !t.verified ? "healed, not confirmed" : VERDICT[t.status]
+    lines.push(`${testMark(t)} ${t.name}  ${verdict}`)
+    if (t.reason) lines.push(`    ${t.reason.split("\n")[0].slice(0, 200)}`)
+  }
+  const bugs = r.tests.filter((t) => t.status === "app_bug").length
+  if (r.status === "failed" && bugs) lines.push("", `${bugs} failure${bugs === 1 ? " is" : "s are"} in the app, not the tests; the tests were left as they are.`)
+  if (r.notes && (r.status === "failed" || r.status === "stopped") && !r.tests.length) lines.push(r.notes)
+  const show = (f: string) => path.relative(cwd, f) || f
+  lines.push("")
+  if (r.command) lines.push(`Command   ${r.command}${r.after && r.status !== "clean" ? `  (${r.after.exitCode === 0 ? "passes" : exit(r.after)})` : ""}`)
+  if (r.changed.length) lines.push(`Changed   ${r.changed.join(", ")}`)
+  if (r.total && (r.total.usage.input || r.total.usage.output)) lines.push(`Usage     ${usageLine(r.total.usage, r.total.cost)}`)
+  lines.push(`Report    ${show(path.join(r.dir, "heal.md"))}`)
+  return { status: STATUS[r.status], title: TITLE[r.status], stats: stats.join(" · "), body: lines }
+}
+
+/** The end-of-heal summary for the terminal. */
+export function formatHeal(r: HealResult, cwd = process.cwd()): string {
+  return cardText(healCard(r, cwd))
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import "./legacyEnv.ts"
+import { main } from "./cli/index.ts"
+
+if (import.meta.main) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err: unknown) => {
+      console.error(err instanceof Error ? err.message : String(err))
+      process.exit(1)
+    })
+}