@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/cli/index.ts

@@ -0,0 +1,1142 @@
+import { spawn } from "node:child_process"
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs"
+import path from "node:path"
+
+import { projectDir } from "../tools.ts"
+
+import { NO_MODEL_SET_UP } from "../llm.ts"
+import { brainUnavailable, openBrain, sessionSetup, type Brain } from "../brain/index.ts"
+import { goalFor, loadCases } from "../cases/index.ts"
+import { codeSkipReason, latestRunDir, runCodeAgent } from "../code/index.ts"
+import { detailFrom } from "../detail.ts"
+import { ensureOpencode, INSTALL_HINT } from "../code/runtime.ts"
+import { loadConfig, parseDuration, replayMode, selectProfile, userConfigDir, type AppConfig } from "../config.ts"
+import { runHeal } from "../heal/loop.ts"
+import { formatHeal } from "../heal/report.ts"
+import { backgroundMonitors, stopBackgroundMonitors } from "../monitor/background.ts"
+import { formatRound, runMonitor, sendTestAlert } from "../monitor/run.ts"
+import { ignoreReports, initWorkspace } from "../init.ts"
+import { clearLogins, describeLogins, interactiveLogin } from "../logins.ts"
+import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow } from "../memory.ts"
+import { formatEvent } from "../print.ts"
+import { bundleLogs, logEvent, recentLogs, startSessionLog } from "../sessionLog.ts"
+import { executeRun, runDirectory } from "../run.ts"
+import { findSkill, loadSkills, SKILL_AGENTS, type SkillAgent } from "../skills/registry.ts"
+import { ignoredNote, newSkill, setSkillDisabled } from "../skills/scaffold.ts"
+import { skillDetail, skillsOverview } from "../skills/view.ts"
+import { buildCodeSummary, buildSummary, formatCodeSummary, formatSummary } from "../summary.ts"
+import { engineDoctor, ensureEngine } from "../engine/setup.ts"
+import { externalMcp } from "../mcp/external.ts"
+import { createMcpServer, serveStdio } from "../mcp/server.ts"
+import { TOOLS, environmentNotes, type ToolContext } from "../mcp/tools.ts"
+import { formatSuite } from "../suite/report.ts"
+import { runSuite, suiteExitCode } from "../suite/run.ts"
+import { packageVersion } from "../tui/theme.ts"
+import { update } from "../update.ts"
+import { meterSnapshot, requestLine } from "../usage.ts"
+import { boolFlag, configOpts, maxStepsFlag, memoryFlags, parseArgs, repoFlag, skillFlags, strFlag, type Flags } from "./args.ts"
+import { HELP_TEXT } from "./help.ts"
+import { suiteEventLine, terminalAsk, terminalInput, terminalWait, toolPrinter, writeJobSummary } from "./terminal.ts"
+import { applySavedCredentials } from "../auth/store.ts"
+import { ensurePrices } from "../prices.ts"
+import { authStatus, signIn, signOut } from "../auth/signin.ts"
+import { resultsCard, runSelection, selectionCard } from "../code/find.ts"
+import { listSets as listApiSets } from "../api/store.ts"
+import { builtinPrompt, lineDiff, listPrompts, prompt, promptDirs, promptFile, promptWarnings } from "../prompts.ts"
+import { resultsMarkdown, selectPrTests } from "../code/prtests.ts"
+import { postPrComment, resolvePr } from "../code/prreview.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { cardText } from "../card.ts"
+import { featuresText } from "../capabilities/render.ts"
+import { DOMAIN_CASES, gate, loadDomainCases, reportMarkdown, runDomainEval, saveReport, VARIANTS, type Variant } from "../evals/domain.ts"
+import { evalNotice, notifiedLine, notify, notifySuite } from "../notify/events.ts"
+import { sendNotice, type Notice } from "../notify/notice.ts"
+
+const AGENT_COMMANDS = new Set(["start", "run", "code", "suite", "heal", "monitor", "explore"])
+const LOGGED_COMMANDS = new Set([...AGENT_COMMANDS, "mcp", "login", "setup"])
+
+/** How much of the agents' work to print: brief unless --verbose. */
+const detailOf = (flags: Flags) => detailFrom(boolFlag(flags, "verbose"))
+
+function debugRequested(flags: Flags): boolean {
+  return boolFlag(flags, "debug") || /^(1|true|yes|on)$/i.test(process.env.FORGEQE_DEBUG || "")
+}
+
+/** Every command that runs something writes a session log; a broken config is reported by the command itself. */
+function openSessionLog(command: string, flags: Flags, argv: string[]): void {
+  try {
+    const file = startSessionLog(loadConfig(configOpts(flags)), { command, debug: debugRequested(flags), argv })
+    if (file && debugRequested(flags) && command !== "start") console.error(`Session log: ${file}`)
+  } catch {
+    // no config yet
+  }
+}
+
+/** llms.json prices that differ from the list price, for the profiles this command uses. */
+function priceWarnings(flags: Flags): string[] {
+  try {
+    const cfg = loadConfig(configOpts(flags))
+    const used = [cfg.llm, cfg.code.reviewProfile ? cfg.profiles[cfg.code.reviewProfile] : undefined]
+    return [...new Set(used.map((p) => p?.priceWarning).filter((w): w is string => Boolean(w)))]
+  } catch {
+    return []
+  }
+}
+
+function configuredOpencode(flags: Flags): string | undefined {
+  try {
+    return loadConfig(configOpts(flags)).code.opencode
+  } catch {
+    return undefined
+  }
+}
+
+/** Keeps the default reports folder beside forgeqe.yaml out of git, for projects set up before init did it. */
+function ignoreDefaultReports(flags: Flags): void {
+  try {
+    const cfg = loadConfig(configOpts(flags))
+    if (!cfg.configPath) return
+    const dir = path.dirname(cfg.configPath)
+    if (dir === userConfigDir() || path.relative(path.join(projectDir(dir), "reports"), cfg.export.outDir).startsWith("..")) return
+    const note = ignoreReports(dir)
+    if (note) console.error(note)
+  } catch {
+    // a broken config is reported by the command itself
+  }
+}
+
+/**
+ * Run a command that uses models, then print what it used and cost in total, by role (ForgeQE's agent, the browser
+ * agent, Scribe, the reviewer). Each job's own summary has its Usage line too.
+ */
+async function withUsageLine(run: () => Promise<number>): Promise<number> {
+  const before = meterSnapshot()
+  try {
+    return await run()
+  } finally {
+    const line = requestLine(before, "This command used")
+    if (line) console.log(`\n${line}`)
+  }
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const { positionals, flags } = parseArgs(argv)
+  const command = positionals[0] || "help"
+  if (command === "version" || (command === "help" && (flags.get("version") === true || flags.get("v") === true))) {
+    console.log(packageVersion())
+    return 0
+  }
+  if (boolFlag(flags, "help") || command === "help" || command === "--help") {
+    console.log(HELP_TEXT)
+    return 0
+  }
+
+  // Sign-ins saved with forgeqe auth login, under the names the config reads; the terminal's own variables win.
+  await applySavedCredentials().catch(() => [])
+  // Models' list prices for costs: waited for only the first time, refreshed daily in the background after that.
+  await ensurePrices()
+  if (LOGGED_COMMANDS.has(command)) openSessionLog(command, flags, argv)
+  if (AGENT_COMMANDS.has(command) && command !== "start") for (const w of [...priceWarnings(flags), ...promptWarnings()]) console.error(`Note: ${w}`)
+  try {
+    if (AGENT_COMMANDS.has(command)) {
+      await ensureOpencode(configuredOpencode(flags), (text) => console.error(text))
+      ignoreDefaultReports(flags)
+    }
+    switch (command) {
+      case "init":
+        return cmdInit(flags)
+      case "setup":
+        return await cmdSetup(flags)
+      case "models":
+        return cmdModels(flags)
+      case "docs":
+        return cmdDocs(flags)
+      case "features":
+        // What ForgeQE can do, and whether each capability works with this config and machine.
+        console.log(featuresText(loadConfig(configOpts(flags))))
+        return 0
+      case "start":
+        return await cmdStart(flags)
+      case "run":
+        return await withUsageLine(() => cmdRun(positionals.slice(1), flags))
+      case "mcp":
+        return await cmdMcp(positionals.slice(1), flags)
+      case "memory":
+        return cmdMemory(positionals.slice(1), flags)
+      case "code":
+        return await withUsageLine(() => cmdCode(positionals.slice(1), flags))
+      case "cases":
+        return await cmdCases(positionals.slice(1), flags)
+      case "suite":
+        return await withUsageLine(() => cmdSuite(positionals.slice(1), flags))
+      case "heal":
+        return await withUsageLine(() => cmdHeal(positionals.slice(1), flags))
+      case "monitor":
+        return await cmdMonitor(positionals.slice(1), flags)
+      case "auth":
+        return await cmdAuth(positionals.slice(1), flags)
+      case "login":
+        return await interactiveLogin(loadConfig(configOpts(flags)), positionals[1], strFlag(flags, "url"))
+      case "pr-tests":
+        return await withUsageLine(() => cmdPrTests(positionals.slice(1), flags))
+      case "api":
+        return await withUsageLine(() => cmdApi(positionals.slice(1), flags))
+      case "explore":
+        return await withUsageLine(() => cmdExplore(positionals.slice(1), flags))
+      case "prompts":
+        return cmdPrompts(positionals.slice(1), flags)
+      case "eval":
+        return await withUsageLine(() => cmdEval(positionals.slice(1), flags))
+      case "notify":
+        return await cmdNotify(positionals.slice(1), flags)
+      case "visual": {
+        // forgeqe visual [run]: the run's pages against their baselines; forgeqe visual approve [run] [--page a,b].
+        const cfg = loadConfig(configOpts(flags))
+        const approve = positionals[1] === "approve"
+        const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+        const ask = approve && process.stdin.isTTY && !boolFlag(flags, "yes") ? terminalAsk(new AbortController().signal) : undefined
+        const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)), ...(ask ? { ask } : {}) }
+        const pages = (strFlag(flags, "page") || "").split(",").map((s) => s.trim()).filter(Boolean)
+        const run = approve ? positionals[2] : positionals[1]
+        const out = (await TOOLS.find((t) => t.name === (approve ? "visual_approve" : "visual_compare"))!.run({ run_dir: run, ...(pages.length ? { pages } : {}) }, ctx)) as { pages?: { over_budget?: boolean }[] }
+        return out.pages?.some((p) => p.over_budget) ? 1 : 0
+      }
+      case "quality": {
+        // forgeqe quality [run-dir]: a run's WCAG and Core Web Vitals; forgeqe quality trends [page]: over time.
+        const cfg = loadConfig(configOpts(flags))
+        const trends = positionals[1] === "trends"
+        const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+        const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+        const out = (await TOOLS.find((t) => t.name === (trends ? "quality_trends" : "quality_report"))!.run(trends ? { page: positionals[2] } : { run_dir: positionals[1] }, ctx)) as { budget_exceeded?: unknown[]; pages?: { slower: unknown[]; newly_failing_rules: unknown[] }[] }
+        return out.budget_exceeded?.length || out.pages?.some((p) => p.slower.length || p.newly_failing_rules.length) ? 1 : 0
+      }
+      case "logs":
+        return cmdLogs(positionals.slice(1), flags)
+      case "skills":
+        return cmdSkills(positionals.slice(1), flags)
+      case "update":
+        return await update({
+          version: strFlag(flags, "version") || positionals[1],
+          check: boolFlag(flags, "check"),
+          waitMinutes: strFlag(flags, "wait") ? Number(strFlag(flags, "wait")) : undefined,
+        })
+      case "logins": {
+        const cfg = loadConfig(configOpts(flags))
+        if (positionals[1] === "clear") console.log(clearLogins(cfg, positionals[2], boolFlag(flags, "all")))
+        else console.log(describeLogins(cfg))
+        return 0
+      }
+      default:
+        console.error(`Unknown command "${command}".\n`)
+        console.log(HELP_TEXT)
+        return 1
+    }
+  } catch (err) {
+    logEvent("error", { message: (err as Error).message || String(err), stack: (err as Error).stack })
+    console.error((err as Error).message || String(err))
+    return 1
+  }
+}
+
+function cmdLogs(args: string[], flags: Flags): number {
+  const cfg = loadConfig(configOpts(flags))
+  if (args[0] === "bundle") {
+    const out = bundleLogs(cfg, { log: args[1] ? path.resolve(args[1]) : undefined, shots: boolFlag(flags, "shots") })
+    console.log(`log      ${out.log}`)
+    console.log(`runs     ${out.runs}`)
+    console.log(`archive  ${out.archive}`)
+    console.log("\nSecrets are replaced in every file. Share the archive to get help with this session.")
+    return 0
+  }
+  const logs = recentLogs(cfg)
+  if (!logs.length) {
+    console.log("No session logs yet. Each forgeqe session writes one to .forgeqe/logs.")
+    return 0
+  }
+  for (const l of logs) console.log(`${l.modified.toLocaleString()}  ${String(Math.ceil(l.size / 1024)).padStart(6)} KB  ${l.file}`)
+  console.log("\nforgeqe logs bundle        archive the newest one with its runs, to share")
+  return 0
+}
+
+function cmdInit(flags: Flags): number {
+  const global = boolFlag(flags, "global")
+  const dir = global ? userConfigDir() : path.resolve(strFlag(flags, "dir") || ".")
+  const { created, notes } = initWorkspace(dir, {
+    force: boolFlag(flags, "force"),
+    profile: strFlag(flags, "profile"),
+  })
+  for (const file of created) console.log(`created  ${file}`)
+  for (const note of notes) console.log(note)
+  if (!created.length) return 0
+  console.log("")
+  console.log("Next:")
+  console.log(`  1. Edit ${path.join(dir, "llms.json")}: a key in an environment variable (api_key_env), or auth: entra to sign in to Azure OpenAI with no key`)
+  console.log("  2. Sign in to your tools and save keys: forgeqe auth login (or put them in a .env file)")
+  console.log(`  3. Describe your product in ${path.join(dir, ".forgeqe", "knowledge")} (product, roles, rules, test data, and the controls you must meet in compliance.md)`)
+  console.log(`  4. In ${path.join(dir, "forgeqe.yaml")}: your industry and regulations (domain:) and Teams or email channels (notify:); then forgeqe notify test`)
+  console.log(`  5. Optional: adjust the agents' prompts in ${path.join(dir, ".forgeqe", "prompts")} and skills in ${path.join(dir, ".forgeqe", "skills")}`)
+  console.log("  6. forgeqe models and forgeqe features, then forgeqe start")
+  return 0
+}
+
+async function cmdSetup(flags: Flags): Promise<number> {
+  const runtime = await ensureOpencode(configuredOpencode(flags), (text) => console.log(text))
+  const python = await ensureEngine((text) => console.log(text), { force: boolFlag(flags, "force") })
+  const doc = engineDoctor(python)
+  if (!doc.browser_use) {
+    console.error(`Engine check failed for ${python}: ${doc.error}`)
+    console.error("Run forgeqe setup --force to rebuild ForgeQE's engine environment.")
+    return 1
+  }
+  console.log(`python      ${python} (${doc.python})`)
+  console.log(`engine      ready (${doc.browser_use})`)
+  console.log(`browser     ${doc.executable_path || doc.channel}`)
+  console.log(`runtime     ${runtime || `not available (${INSTALL_HINT})`}`)
+  return 0
+}
+
+function cmdModels(flags: Flags): number {
+  const cfg = loadConfig(configOpts(flags))
+  if (!Object.keys(cfg.profiles).length) {
+    console.log(NO_MODEL_SET_UP)
+    if (cfg.configPath) console.log(`\nconfig  ${cfg.configPath}`)
+    return 0
+  }
+  const width = Math.max(8, ...Object.keys(cfg.profiles).map((n) => n.length))
+  console.log(`${"PROFILE".padEnd(width)}  PROVIDER  MODEL`)
+  for (const [name, profile] of Object.entries(cfg.profiles)) {
+    const mark = name === cfg.activeProfile ? "*" : " "
+    const p = profile.price
+    const price = p ? `  ${p.input}/${p.cachedInput ?? "?"}/${p.output} ${p.currency} per M in/cached/out${p.note ? ` (${p.note})` : ""}` : "  no price known"
+    console.log(`${mark} ${name.padEnd(width)}  ${profile.provider.padEnd(8)}  ${profile.model}${price}`)
+    if (profile.priceWarning) console.log(`  ! ${profile.priceWarning}`)
+  }
+  if (cfg.configPath) console.log(`\nconfig  ${cfg.configPath}`)
+  return 0
+}
+
+const ARCHITECTURE_PAGE = "forgeqe-architecture.html"
+
+function openFile(file: string): void {
+  const [cmd, args] =
+    process.platform === "darwin" ? ["open", [file]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", file]] : ["xdg-open", [file]]
+  spawn(cmd as string, args as string[], { stdio: "ignore", detached: true }).unref()
+}
+
+function configOrNone(flags: Flags): AppConfig | undefined {
+  try {
+    return loadConfig(configOpts(flags))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * forgeqe pr-tests [pr] [--base BRANCH] [--agent] [--run] [--post]: the tests a pull request (or the commits since a
+ * base branch) can break. Without --agent no model is used. --run runs them (the flag is the consent) and the exit code
+ * is the result, for a CI gate: 0 when they pass or none are affected, 1 when one fails, 2 when there is no command.
+ */
+async function cmdPrTests(args: string[], flags: Flags): Promise<number> {
+  const cfg = loadConfig(configOpts(flags))
+  const repo = strFlag(flags, "repo") || process.cwd()
+  const out = await selectPrTests({
+    config: cfg,
+    repo,
+    pr: args[0],
+    base: strFlag(flags, "base"),
+    agent: boolFlag(flags, "agent"),
+    onEvent: (e) => e.kind === "info" && console.error(e.text),
+  })
+  for (const n of out.notes) console.error(n)
+  for (const t of out.impact.tests) console.log(`• ${t.file}\n    ${t.reasons.join("; ")}`)
+  if (out.impact.untested.length) console.log(`\nNo test reaches: ${out.impact.untested.join(", ")}`)
+  if (!out.selection) return out.impact.tests.length ? 2 : 0
+  console.log(`\n${cardText(selectionCard(out.selection, process.cwd()))}`)
+  if (!boolFlag(flags, "run")) return 0
+  const run = await runSelection({ selection: out.selection, timeoutSeconds: cfg.code.testTimeoutSeconds, hide: privateEnvNames(cfg), flaky: cfg.flaky })
+  console.log(`\n${cardText(resultsCard(run, process.cwd()))}`)
+  if (boolFlag(flags, "post") && args[0]) {
+    const { root, ref } = await resolvePr(repo, args[0])
+    console.log(`Results posted: ${await postPrComment(ref, cfg, root, resultsMarkdown(run, `pull request ${ref.number}`))}`)
+  }
+  return run.status === "passed" ? 0 : 1
+}
+
+/**
+ * forgeqe api contracts --spec <link|file> | --run [RUN] · api run [SET] · api tests [SET] · api list: API and
+ * contract tests. `api run` exits 1 when a contract fails, for a CI gate; --allow-writes is the consent for calls that
+ * change data.
+ */
+async function cmdApi(args: string[], flags: Flags): Promise<number> {
+  const cfg = loadConfig(configOpts(flags))
+  const action = args[0] || "list"
+  const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+  const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+  const tool = (name: string) => TOOLS.find((t) => t.name === name)!
+  const csv = (name: string) => (strFlag(flags, name) || "").split(",").map((s) => s.trim()).filter(Boolean)
+  switch (action) {
+    case "list": {
+      const sets = listApiSets(cfg)
+      if (!sets.length) console.log("No API contracts yet. Make some: forgeqe api contracts --spec <link or file>, or --run after a browser run.")
+      for (const s of sets) console.log(`${s.id}  ${s.contracts} contracts${s.scenarios ? `, ${s.scenarios} scenarios` : ""}  ${s.name}`)
+      return 0
+    }
+    case "contracts": {
+      const spec = strFlag(flags, "spec")
+      const run = flags.get("run")
+      await tool("api_contracts").run(
+        { ...(spec ? { from: "spec", spec } : { from: "run", ...(typeof run === "string" ? { run_dir: run } : args[1] ? { run_dir: args[1] } : {}) }), include: csv("include"), name: strFlag(flags, "name"), base_url: strFlag(flags, "base-url"), third_party: boolFlag(flags, "third-party") },
+        ctx,
+      )
+      return 0
+    }
+    case "run": {
+      const out = (await tool("run_api_contracts").run(
+        { set_id: args[1], base_url: strFlag(flags, "base-url"), only: csv("only"), allow_writes: boolFlag(flags, "allow-writes"), include_needs_data: boolFlag(flags, "include-needs-data") },
+        ctx,
+      )) as { counts: { failed: number; error: number; passed: number } }
+      return out.counts.failed || out.counts.error ? 1 : 0
+    }
+    case "tests": {
+      await ensureOpencode(cfg.code.opencode, (text) => console.error(text))
+      const scenarios = flags.get("scenarios") === true ? ["all"] : csv("scenarios")
+      const out = (await tool("write_api_tests").run({ set_id: args[1], repo: strFlag(flags, "repo"), only: csv("only"), include_writes: boolFlag(flags, "include-writes"), base_url: strFlag(flags, "base-url"), scenarios }, ctx)) as { status: string }
+      return out.status === "passed" ? 0 : 1
+    }
+    case "scenarios": {
+      const run = flags.get("run")
+      const from = strFlag(flags, "text") ? "text" : strFlag(flags, "cases") ? "cases" : run !== undefined ? "run" : "spec"
+      if (from === "text" || from === "cases") await ensureOpencode(cfg.code.opencode, (text) => console.error(text))
+      await tool("api_scenarios").run(
+        {
+          from,
+          ...(typeof run === "string" ? { run_dir: run } : {}),
+          spec: strFlag(flags, "spec"),
+          set_id: args[1],
+          cases: csv("cases"),
+          text: strFlag(flags, "text"),
+          negative: !boolFlag(flags, "no-negative"),
+          name: strFlag(flags, "name"),
+          base_url: strFlag(flags, "base-url"),
+        },
+        ctx,
+      )
+      return 0
+    }
+    case "run-scenarios": {
+      // --allow-writes is the consent for scenarios that change data; without it only read-only scenarios run.
+      const out = (await tool("run_api_scenarios").run({ set_id: args[1], only: csv("only"), base_url: strFlag(flags, "base-url"), allow_writes: boolFlag(flags, "allow-writes") }, ctx)) as { counts: { failed: number; error: number } }
+      return out.counts.failed || out.counts.error ? 1 : 0
+    }
+    default:
+      throw new Error("Usage: forgeqe api [list | contracts --spec <link|file> | contracts --run [RUN] | run [SET] | tests [SET] [--scenarios] | scenarios --run [RUN] | --spec <link|file> | --cases <refs> | --text <scenario> | run-scenarios [SET]]")
+  }
+}
+
+/**
+ * forgeqe explore <story> [--url URL] [--charters N] [--roles a,b] [--focus TEXT] [--yes] [--file-bugs]: exploratory
+ * testing of a story. In a terminal it asks before running the charters and before filing bugs; --yes runs without
+ * asking (bugs only with --file-bugs). Exits 1 when a defect is confirmed.
+ */
+async function cmdExplore(args: string[], flags: Flags): Promise<number> {
+  const story = args.join(" ").trim()
+  if (!story) throw new Error('Usage: forgeqe explore <ado:123 | SHOP-12 | link | "story text"> [--url URL] [--charters N] [--roles a,b] [--focus TEXT] [--yes] [--file-bugs]')
+  const cfg = loadConfig(configOpts(flags))
+  const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const ask = process.stdin.isTTY && !boolFlag(flags, "yes") ? terminalAsk(controller.signal) : undefined
+    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", signal: controller.signal, headed: boolFlag(flags, "headed"), maxSteps: maxStepsFlag(flags), emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)), ...(ask ? { ask } : {}) }
+    const roles = (strFlag(flags, "roles") || "").split(",").map((s) => s.trim()).filter(Boolean)
+    const out = (await TOOLS.find((t) => t.name === "explore_story")!.run(
+      { story, url: strFlag(flags, "url"), charters: Number(strFlag(flags, "charters")) || undefined, ...(roles.length ? { roles } : {}), focus: strFlag(flags, "focus"), file_bugs: boolFlag(flags, "file-bugs") },
+      ctx,
+    )) as { confirmed_defects?: unknown[]; cancelled?: boolean }
+    return out.confirmed_defects?.length ? 1 : 0
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}
+
+/** forgeqe notify test [channel]: a test card to every notification channel (or one), to check each arrives. */
+async function cmdNotify(args: string[], flags: Flags): Promise<number> {
+  if (args[0] !== "test") throw new Error("Usage: forgeqe notify test [channel]")
+  const cfg = loadConfig(configOpts(flags))
+  const channels = (cfg.notify?.channels || []).filter((c) => !args[1] || c.name === args[1])
+  if (!channels.length) throw new Error(cfg.notify ? `No channel ${args[1]}. Channels: ${cfg.notify.channels.map((c) => c.name).join(", ")}.` : "No notification channels: add notify.channels to forgeqe.yaml (see HOW_TO_USE.md, section 17).")
+  const notice: Notice = {
+    source: "ForgeQE",
+    title: "Test notification",
+    status: "good",
+    subtitle: `Sent with forgeqe notify test · ${new Date().toLocaleString()}`,
+    items: channels.map((c) => ({ line: `Channel ${c.name}`, details: [`Gets: ${c.on.join(", ") || "nothing automatic"}`] })),
+  }
+  const sent = await Promise.all(channels.map(async (c) => ({ channel: c.name, sent: await sendNotice(c, notice) })))
+  console.log(notifiedLine(sent))
+  return sent.every((s) => s.sent.every((x) => x.ok)) ? 0 : 1
+}
+
+/**
+ * forgeqe eval domain [--cases DIR|FILE] [--only a,b] [--variant declared|undeclared] [--repeat N]
+ * [--judge-profile NAME] [--min 0.8]: whether ForgeQE's agent applies domain and regulatory knowledge when it designs
+ * tests, with the domain declared and without; exits 1 when --min is given and the declared variant falls short.
+ */
+async function cmdEval(args: string[], flags: Flags): Promise<number> {
+  if (args[0] !== "domain") throw new Error("Usage: forgeqe eval domain [--cases DIR] [--only id,id] [--variant declared|undeclared] [--repeat N] [--judge-profile NAME] [--min 0.8]")
+  const cfg = loadConfig(configOpts(flags))
+  const why = brainUnavailable(cfg)
+  if (why) throw new Error(why)
+  const judgeName = strFlag(flags, "judge-profile")
+  const judgeConfig = judgeName ? loadConfig({ ...configOpts(flags), profile: judgeName }) : undefined
+  const only = (strFlag(flags, "only") || "").split(",").map((s) => s.trim()).filter(Boolean)
+  const all = loadDomainCases(path.resolve(strFlag(flags, "cases") || DOMAIN_CASES))
+  const cases = only.length ? all.filter((c) => only.includes(c.id)) : all
+  if (!cases.length) throw new Error(`No case matches --only ${only.join(",")}. Cases: ${all.map((c) => c.id).join(", ")}.`)
+  const variant = strFlag(flags, "variant")
+  if (variant && !(VARIANTS as string[]).includes(variant)) throw new Error(`--variant is declared or undeclared, not ${variant}.`)
+  const min = strFlag(flags, "min") ? Number(strFlag(flags, "min")) : undefined
+  if (min !== undefined && !(min >= 0 && min <= 1)) throw new Error("--min is a share between 0 and 1, e.g. 0.8.")
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const report = await runDomainEval({
+      config: cfg,
+      judgeConfig,
+      cases,
+      variants: variant ? [variant as Variant] : undefined,
+      repeat: Number(strFlag(flags, "repeat")) || 1,
+      signal: controller.signal,
+      onProgress: (text) => console.log(text),
+    })
+    const dir = saveReport(report, cfg.export.outDir)
+    console.log("")
+    console.log(reportMarkdown(report).split("\n## ")[0]!.trim())
+    console.log("")
+    console.log(`Report: ${path.join(dir, "report.md")}`)
+    if (min === undefined) return 0
+    const failed = gate(report, min)
+    console.log(failed ? `Gate failed: ${failed}.` : `Gate passed (at least ${Math.round(min * 100)}% of domain and regulation expectations, no invented ids).`)
+    if (failed) {
+      const notified = notifiedLine(await notify(cfg, "eval_failed", evalNotice(report, failed, cfg, path.join(dir, "report.md"))))
+      if (notified) console.log(notified)
+    }
+    return failed ? 1 : 0
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}
+
+/**
+ * forgeqe prompts [list] | show <name> | diff <name> | reset <name>: the agents' prompts, where each comes from
+ * (ForgeQE's, or an edited copy in .forgeqe/prompts), and how an edited one differs from ForgeQE's.
+ */
+function cmdPrompts(args: string[], flags: Flags): number {
+  loadConfig(configOpts(flags))
+  const action = args[0] || "list"
+  const name = args[1]
+  if (action === "list") {
+    const all = listPrompts()
+    const width = Math.max(...all.map((p) => p.name.length))
+    for (const p of all) console.log(`${p.name.padEnd(width)}  ${p.source === "built-in" ? "ForgeQE's" : `${p.source}: ${path.relative(process.cwd(), p.file) || p.file}`}${p.outdated ? "  (based on an older version: forgeqe prompts diff " + p.name + ")" : ""}\n${" ".repeat(width + 2)}${p.description}`)
+    console.log(`\nLooked for in: ${promptDirs().map((d) => `${d.dir} (${d.source})`).join(", ")}, then ForgeQE's own.`)
+    return 0
+  }
+  if (!name) throw new Error(`Usage: forgeqe prompts ${action} <name>  (forgeqe prompts lists the names)`)
+  const where = promptFile(name)
+  if (!existsSync(where.file)) throw new Error(`No prompt named "${name}". forgeqe prompts lists them.`)
+  if (action === "show") {
+    console.log(`# ${name} (${where.source === "built-in" ? "ForgeQE's" : where.file})\n`)
+    console.log(boolFlag(flags, "raw") ? readFileSync(where.file, "utf8") : prompt(name))
+    return 0
+  }
+  if (action === "diff") {
+    if (where.source === "built-in") {
+      console.log(`${name} is ForgeQE's own: nothing to compare.`)
+      return 0
+    }
+    const mine = readFileSync(where.file, "utf8").replace(/^---\n[\s\S]*?\n---\n/, "").trim()
+    const diff = lineDiff(builtinPrompt(name), mine)
+    console.log(`--- ForgeQE's ${name}\n+++ ${where.file}${where.outdated ? "\n(ForgeQE's changed after your copy was made)" : ""}\n`)
+    console.log(diff.length ? diff.join("\n") : "No differences in the prompt text.")
+    return 0
+  }
+  if (action === "reset") {
+    if (where.source === "built-in") {
+      console.log(`${name} is already ForgeQE's own.`)
+      return 0
+    }
+    renameSync(where.file, `${where.file}.bak`)
+    console.log(`${name}: your version moved to ${where.file}.bak; ForgeQE's is used from now on.`)
+    return 0
+  }
+  throw new Error("Usage: forgeqe prompts [list | show <name> [--raw] | diff <name> | reset <name>]")
+}
+
+/** forgeqe auth [login [system|ENV_NAME]] | status | logout <system|ENV_NAME> */
+async function cmdAuth(args: string[], flags: Flags): Promise<number> {
+  const action = args[0] || "status"
+  if (action === "status") {
+    console.log(authStatus(configOrNone(flags)).join("\n"))
+    return 0
+  }
+  if (action === "logout") {
+    if (!args[1]) throw new Error("Usage: forgeqe auth logout <system>")
+    console.log(await signOut(args[1]))
+    return 0
+  }
+  if (action !== "login") throw new Error("Usage: forgeqe auth [login [system]|status|logout <system>]")
+  if (!process.stdin.isTTY) throw new Error("forgeqe auth login needs a terminal. In a pipeline, set the tokens as environment variables instead.")
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const res = await signIn(
+      {
+        say: (text, kind) => (kind === "err" ? console.error(text) : console.log(kind === "ok" ? `✓ ${text}` : text)),
+        input: terminalInput(controller.signal),
+        choose: terminalAsk(controller.signal)!,
+        openUrl: (url) => {
+          console.log(`Opening ${url}`)
+          if (!boolFlag(flags, "no-browser")) openFile(url)
+        },
+        attached: true,
+        signal: controller.signal,
+      },
+      args[1],
+      configOrNone(flags),
+    )
+    return res.ok ? 0 : 1
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}
+
+function cmdDocs(flags: Flags): number {
+  const root = path.resolve(import.meta.dir, "..", "..")
+  const guide = path.join("docs", "user-guide.html")
+  const docs = ["README.md", "HOW_TO_USE.md", guide, ARCHITECTURE_PAGE, path.join("docs", "ARCHITECTURE.md")]
+  const copyTo = strFlag(flags, "copy")
+  if (copyTo) {
+    const dir = path.resolve(copyTo)
+    mkdirSync(dir, { recursive: true })
+    for (const doc of docs) {
+      mkdirSync(path.dirname(path.join(dir, doc)), { recursive: true })
+      copyFileSync(path.join(root, doc), path.join(dir, doc))
+      console.log(`copied  ${path.join(dir, doc)}`)
+    }
+    return 0
+  }
+  for (const doc of docs) console.log(path.join(root, doc))
+  if (boolFlag(flags, "guide")) openFile(path.join(root, guide))
+  else if (boolFlag(flags, "open")) openFile(path.join(root, ARCHITECTURE_PAGE))
+  return 0
+}
+
+async function cmdStart(flags: Flags): Promise<number> {
+  if (!process.stdout.isTTY) {
+    console.error('forgeqe start needs a terminal. Elsewhere use: forgeqe run "<request>" --plain, or forgeqe suite <source...>')
+    return 1
+  }
+  const { startTui } = await import("../tui/main.tsx")
+  await startTui({
+    configPath: strFlag(flags, "config"),
+    profile: strFlag(flags, "profile"),
+    url: strFlag(flags, "url"),
+    goal: strFlag(flags, "goal"),
+    headed: boolFlag(flags, "headed"),
+    verbose: boolFlag(flags, "verbose"),
+    ...memoryFlags(flags),
+    repo: boolFlag(flags, "no-code") ? null : strFlag(flags, "repo") ? path.resolve(strFlag(flags, "repo")!) : undefined,
+  })
+  await stopMonitorsOnExit((line) => console.log(line))
+  return 0
+}
+
+/** Background monitors started by the agent live as long as this process; wind their rounds down before exiting. */
+async function stopMonitorsOnExit(log: (line: string) => void) {
+  const running = backgroundMonitors()
+  if (!running.length) return
+  log(`Stopping ${running.length === 1 ? "the monitor" : `${running.length} monitors`}…`)
+  await stopBackgroundMonitors()
+}
+
+const SKILLS_USAGE = "Usage: forgeqe skills [list|check] · show <name> · new <name> --description TEXT [--user] [--agent browser|scribe|forgeqe] · enable|disable <name>"
+
+function cmdSkills(args: string[], flags: Flags): number {
+  const cfg = loadConfig(configOpts(flags))
+  const repo = strFlag(flags, "repo") ? path.resolve(strFlag(flags, "repo")!) : process.cwd()
+  const [sub = "list", name] = args
+  const reg = loadSkills(cfg.skills, repo)
+  switch (sub) {
+    case "list":
+      console.log(skillsOverview(reg, cfg.skills, repo))
+      return 0
+    case "check":
+      if (!cfg.skills.enabled) {
+        console.log(skillsOverview(reg, cfg.skills, repo))
+        return 0
+      }
+      for (const p of reg.problems) console.log(`✗ ${p}`)
+      console.log(reg.problems.length ? `\n${reg.problems.length} problem${reg.problems.length === 1 ? "" : "s"}; ${reg.skills.length} skills usable.` : `✓ ${reg.skills.length} skills, no problems.`)
+      return reg.problems.length ? 1 : 0
+    case "show": {
+      if (!name) throw new Error(SKILLS_USAGE)
+      const skill = findSkill(reg, name)
+      if (!skill) throw new Error(`No skill named "${name}". ${reg.skills.length ? `Skills: ${reg.skills.map((s) => s.name).join(", ")}.` : "There are no skills yet."}`)
+      console.log(skillDetail(skill, reg.disabled.includes(skill)))
+      return 0
+    }
+    case "new": {
+      if (!name) throw new Error(SKILLS_USAGE)
+      const description = strFlag(flags, "description")
+      if (!description) throw new Error(`Say when the skill applies: forgeqe skills new ${name} --description "Use when …". The agents choose skills by their description.`)
+      const agents = (strFlag(flags, "agent") || "").split(",").map((a) => a.trim()).filter(Boolean)
+      const bad = agents.filter((a) => !SKILL_AGENTS.includes(a as SkillAgent))
+      if (bad.length) throw new Error(`--agent takes browser, scribe, or forgeqe (comma-separated); got ${bad.join(", ")}.`)
+      const root = boolFlag(flags, "user") ? cfg.skills.userDir : cfg.skills.projectDir
+      const file = newSkill(root, { name, description, agents: agents as SkillAgent[] })
+      console.log(`✓ ${file}\nWrite the instructions in it, then check it with: forgeqe skills show ${name}`)
+      const ignored = boolFlag(flags, "user") ? null : ignoredNote(file)
+      if (ignored) console.log(ignored)
+      if (!cfg.skills.enabled) console.log("Skills are turned off in forgeqe.yaml; turn them on to use it.")
+      return 0
+    }
+    case "enable":
+    case "disable": {
+      if (!name) throw new Error(SKILLS_USAGE)
+      if (!cfg.configPath) throw new Error("There is no forgeqe.yaml to record this in. Create one with: forgeqe init")
+      if (sub === "disable" && cfg.skills.enabled && !findSkill(reg, name)) throw new Error(`No skill named "${name}".`)
+      const changed = setSkillDisabled(cfg.configPath, name, sub === "disable")
+      console.log(changed ? `✓ ${name} ${sub}d (skills.disable in ${cfg.configPath})` : `${name} is already ${sub}d.`)
+      return 0
+    }
+    default:
+      throw new Error(SKILLS_USAGE)
+  }
+}
+
+function cmdMemory(args: string[], flags: Flags): number {
+  const cfg = loadConfig(configOpts(flags))
+  const dirFlag = strFlag(flags, "dir")
+  const dir = dirFlag ? path.resolve(dirFlag) : cfg.memory.dir
+  const [sub = "list", target] = args
+  const show = (what: string) =>
+    memoryShow(dir, what, { locators: boolFlag(flags, "locators"), limit: boolFlag(flags, "all") ? 0 : 40 })
+  switch (sub) {
+    case "list":
+      console.log(memoryOverview(dir))
+      return 0
+    case "show":
+      if (!target) throw new Error("Usage: forgeqe memory show <host|url> [--locators] [--all]")
+      console.log(show(target))
+      return 0
+    case "flows":
+      console.log(memoryFlows(dir, { steps: boolFlag(flags, "steps") }))
+      return 0
+    case "clear": {
+      const files = memoryFilesFor(dir, target)
+      if (!files.length) {
+        console.log("Nothing to clear.")
+        return 0
+      }
+      if (!boolFlag(flags, "yes")) {
+        console.log(`Would delete ${files.length} memory files${target ? ` for ${target}` : ""} in ${dir}.`)
+        console.log("Run again with --yes to delete them.")
+        return 1
+      }
+      clearMemory(files)
+      console.log(`Deleted ${files.length} memory files.`)
+      return 0
+    }
+    default:
+      console.log(show(sub))
+      return 0
+  }
+}
+
+async function cmdRun(args: string[], flags: Flags): Promise<number> {
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  cfg = withCodeFlags(cfg, flags)
+  const text = [strFlag(flags, "goal"), ...args].filter(Boolean).join(" ").trim()
+  if (!text) throw new Error('What should ForgeQE do? forgeqe run "Search hotels in Mumbai on booking.com"')
+  const maxSteps = maxStepsFlag(flags)
+  if (cfg.llm.provider === "none") throw new Error(NO_MODEL_SET_UP)
+  if (boolFlag(flags, "direct")) return runGoal(cfg, flags, text, maxSteps)
+  const why = brainUnavailable(cfg)
+  if (why) {
+    console.log(`ForgeQE's agent is off (${why}), so the request runs as one browser goal.${why.includes("agent runtime") ? ` ${INSTALL_HINT}` : ""}\n`)
+    return runGoal(cfg, flags, text, maxSteps)
+  }
+  return runAgent(cfg, flags, text, maxSteps)
+}
+
+async function runAgent(cfg: AppConfig, flags: Flags, text: string, maxSteps: number | undefined): Promise<number> {
+  const color = Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain")
+  const { cwd, notes, writeTests } = sessionSetup(cfg, repoFlag(flags))
+  const controller = new AbortController()
+  const emit = toolPrinter(color, (line) => console.log(line), detailOf(flags))
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  let brain: Brain | undefined
+  try {
+    brain = await openBrain({
+      config: cfg,
+      cwd,
+      notes,
+      signal: controller.signal,
+      context: () => ({
+        headed: boolFlag(flags, "headed"),
+        maxSteps,
+        url: strFlag(flags, "url"),
+        ...memoryFlags(flags),
+        signal: controller.signal,
+        emit,
+        session: "once",
+        writeTests,
+        waitForUser: terminalWait(controller.signal),
+        ask: terminalAsk(controller.signal),
+      }),
+      onEvent: (e) => {
+        const line = formatEvent(e, color, detailOf(flags))
+        if (line) console.log(line)
+      },
+    })
+    const b = brain
+    controller.signal.addEventListener("abort", () => void b.abort(), { once: true })
+    const answer = await brain.ask(text)
+    if (answer.outcome === "stopped") {
+      console.log("\nStopped.")
+      return 2
+    }
+    if (answer.reply) console.log(`\n${answer.reply}`)
+    else if (answer.error) console.error(`\n${answer.error}`)
+    if (answer.outcome === "needs_input") console.log('\nRun again with the details, e.g. forgeqe run "…", or use forgeqe start to talk it through.')
+    return answer.outcome === "done" ? 0 : answer.outcome === "needs_input" ? 3 : 1
+  } finally {
+    process.off("SIGINT", onSigint)
+    await brain?.close()
+  }
+}
+
+function cmdMcpList(cfg: AppConfig): number {
+  const { servers, skipped } = externalMcp(cfg)
+  if (!servers.length && !skipped.length) {
+    console.log("No MCP servers for other systems. Set sources.azure_devops or sources.jira, or add servers under mcp:, in forgeqe.yaml.")
+  }
+  for (const s of servers) {
+    const c = s.config as { type: string; command?: string[]; url?: string; environment?: Record<string, string>; headers?: Record<string, string> }
+    console.log(`✓ ${s.name.padEnd(13)} ${s.label}`)
+    console.log(`    ${c.type === "local" ? c.command!.join(" ") : c.url}`)
+    for (const [k, v] of Object.entries(c.environment || c.headers || {})) {
+      console.log(`    ${k}: ${v}${/\{env:FORGEQE_/.test(v) ? "  (ForgeQE builds this from your token when the agent starts)" : ""}`)
+    }
+  }
+  for (const s of skipped) console.log(`✗ ${s.label}: ${s.why}`)
+  console.log(`\nForgeQE's own tools (browser runs, test cases from every source, read_confluence, query_api) are always there.`)
+  console.log("Servers connect when ForgeQE's agent starts; the shell and forgeqe run report which ones did.")
+  return 0
+}
+
+async function cmdMcp(args: string[], flags: Flags): Promise<number> {
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  if (args[0] === "list") return cmdMcpList(cfg)
+  if (args[0]) throw new Error(`Unknown: forgeqe mcp ${args[0]}. Use forgeqe mcp (serve) or forgeqe mcp list.`)
+  const repo = repoFlag(flags)
+  const cwd = repo || process.cwd()
+  const log = toolPrinter(false, (line) => process.stderr.write(`${line}\n`), detailOf(flags))
+  const context = (): ToolContext => ({ config: cfg, cwd, headed: boolFlag(flags, "headed"), maxSteps: maxStepsFlag(flags), url: strFlag(flags, "url"), ...memoryFlags(flags), emit: log, session: "server" })
+  const server = createMcpServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), version: packageVersion() })
+  process.stderr.write(`ForgeQE MCP server on stdio (${TOOLS.length} tools, working in ${cwd})\n`)
+  await serveStdio(server)
+  await stopMonitorsOnExit((line) => process.stderr.write(`${line}\n`))
+  return 0
+}
+
+async function runGoal(cfg: AppConfig, flags: Flags, goal: string, maxSteps: number | undefined): Promise<number> {
+  const out = runDirectory(cfg.export.outDir, strFlag(flags, "out"))
+  const t0 = Date.now()
+  let steps = 0
+  const { result, files } = await executeRun({
+    config: cfg,
+    goal,
+    url: strFlag(flags, "url"),
+    headed: boolFlag(flags, "headed"),
+    maxSteps,
+    outDir: out,
+    skills: skillFlags(flags),
+    repo: process.cwd(),
+    ...memoryFlags(flags),
+    onEvent: (event) => {
+      if (event.type === "step") steps = Math.max(steps, event.step)
+      if (event.type === "done") return
+      const line = formatEvent(event, Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain"), detailOf(flags))
+      if (line) console.log(line)
+    },
+  })
+  const summary = buildSummary({
+    status: result.status,
+    text: result.summary,
+    finalUrl: result.finalUrl,
+    ms: Date.now() - t0,
+    tokens: result.usage.input + result.usage.output,
+    steps,
+    files,
+    memory: result.memory,
+    usage: result.usage,
+    cost: result.cost,
+    outcome: result.outcome,
+    failedChecks: result.failedChecks,
+    quality: result.quality,
+    budgetExceeded: result.budgetExceeded,
+  })
+  console.log("")
+  console.log(formatSummary(summary))
+  const runCode = result.status === "complete" ? 0 : result.status === "stopped" ? 2 : 1
+  // A budget fails the run, but the steps passed: the test is still written.
+  const budget = result.budgetExceeded?.length ? 1 : 0
+
+  const repo = codeRepo(cfg, flags)
+  if (!repo || runCode !== 0) return runCode || budget
+  const skip = codeSkipReason(cfg, result)
+  if (skip) {
+    console.log(`\nCoding agent skipped: ${skip}.`)
+    return runCode || budget
+  }
+  console.log("")
+  return (await runCodeStep(cfg, flags, repo, out)) || budget
+}
+
+function codeRepo(cfg: AppConfig, flags: Flags): string | undefined {
+  if (boolFlag(flags, "no-code")) return undefined
+  const flag = strFlag(flags, "repo")
+  return flag ? path.resolve(flag) : cfg.code.repo
+}
+
+function withCodeFlags(cfg: AppConfig, flags: Flags): AppConfig {
+  const attempts = strFlag(flags, "attempts")
+  if (attempts && !(Number(attempts) >= 1)) throw new Error("--attempts must be a positive number")
+  const model = strFlag(flags, "code-model")
+  return { ...cfg, code: { ...cfg.code, ...(attempts ? { maxAttempts: Number(attempts) } : {}), ...(model ? { model } : {}) } }
+}
+
+async function runCodeStep(cfg: AppConfig, flags: Flags, repo: string, runDir: string): Promise<number> {
+  const t0 = Date.now()
+  const color = Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain")
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const result = await runCodeAgent({
+      config: withCodeFlags(cfg, flags),
+      repo,
+      runDir,
+      signal: controller.signal,
+      onEvent: (event) => {
+        const line = formatEvent(event, color, detailOf(flags))
+        if (line) console.log(line)
+      },
+    })
+    console.log("")
+    console.log(formatCodeSummary(buildCodeSummary(result, Date.now() - t0)))
+    return result.status === "passed" ? 0 : result.status === "stopped" ? 2 : 1
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}
+
+async function cmdCode(args: string[], flags: Flags): Promise<number> {
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  const repo = strFlag(flags, "repo") ? path.resolve(strFlag(flags, "repo")!) : cfg.code.repo
+  if (!repo) throw new Error("Which repo? Pass --repo DIR or set code.repo in forgeqe.yaml.")
+  const runDir = args[0] ? path.resolve(args[0]) : latestRunDir(cfg.export.outDir)
+  if (!runDir) throw new Error(`No runs in ${cfg.export.outDir}. Run a goal first, or pass a run directory.`)
+  if (cfg.llm.provider === "mock" && !cfg.code.model && !strFlag(flags, "code-model")) {
+    throw new Error("The mock profile has no model for the coding agent. Pass --profile, --code-model, or set code.model.")
+  }
+  if (cfg.llm.provider === "none" && !cfg.code.model && !strFlag(flags, "code-model")) throw new Error(NO_MODEL_SET_UP)
+  console.log(`Run  ${path.relative(process.cwd(), runDir) || runDir}`)
+  return runCodeStep(cfg, flags, repo, runDir)
+}
+
+const CASES_USAGE = `Pass test cases: a file (.txt .md .csv .yaml .json .feature), ado:123,456, ado:plan=12[/suite=34],
+jira:SHOP-1,SHOP-2, jira:jql=<query>, xray:SHOP-1, xray:jql=<query>, xray:plan=SHOP-100, testrail:C12,C13,
+testrail:run=45, testrail:plan=7, testrail:suite=3, zephyr:SHOP-T1, zephyr:cycle=SHOP-R5, zephyr:folder=12,
+qtest:1234, qtest:cycle=88, qtest:suite=9, or quoted plain text.`
+
+async function cmdCases(refs: string[], flags: Flags): Promise<number> {
+  if (!refs.length) throw new Error(CASES_USAGE)
+  const cfg = loadConfig(configOpts(flags))
+  const cases = await loadCases(refs, cfg.sources)
+  const full = boolFlag(flags, "goal")
+  for (const tc of cases) {
+    console.log(`${tc.id}  ${tc.title}${tc.url ? `  ${tc.url}` : ""}`)
+    if (full) console.log(`${goalFor(tc).replace(/^/gm, "    ")}\n`)
+    else if (tc.steps.length) console.log(`    ${tc.steps.length} step${tc.steps.length === 1 ? "" : "s"}${tc.startUrl ? ` · starts at ${tc.startUrl}` : ""}`)
+  }
+  console.log(`\n${cases.length} test case${cases.length === 1 ? "" : "s"}. forgeqe suite ${refs.map((r) => (/\s/.test(r) ? JSON.stringify(r) : r)).join(" ")} runs them.`)
+  return 0
+}
+
+async function cmdHeal(args: string[], flags: Flags): Promise<number> {
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  cfg = withCodeFlags(cfg, flags)
+  const why = brainUnavailable(cfg)
+  if (why) throw new Error(`forgeqe heal needs the agent runtime and a live model, but ${why}. ${why.includes("agent runtime") ? INSTALL_HINT : "Pick a profile with --profile, or set code.model."}`)
+  const repo = strFlag(flags, "repo") ? path.resolve(strFlag(flags, "repo")!) : cfg.code.repo || process.cwd()
+  const command = args.join(" ").trim() || strFlag(flags, "command") || undefined
+  const color = Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain")
+  console.log(`Repo  ${repo}`)
+
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const result = await runHeal({
+      config: cfg,
+      repo,
+      command,
+      outDir: strFlag(flags, "out"),
+      headed: boolFlag(flags, "headed"),
+      maxSteps: maxStepsFlag(flags),
+      url: strFlag(flags, "url"),
+      signal: controller.signal,
+      onEvent: (e) => {
+        const line = formatEvent(e, color, detailOf(flags))
+        if (line) console.log(line)
+      },
+      onTool: toolPrinter(color, (line) => console.log(line), detailOf(flags)),
+    })
+    console.log("")
+    console.log(formatHeal(result))
+    return result.status === "passed" || result.status === "clean" ? 0 : result.status === "stopped" ? 2 : 1
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}
+
+function withMonitorFlags(cfg: AppConfig, flags: Flags): AppConfig {
+  const m = { ...cfg.monitor }
+  const every = strFlag(flags, "every")
+  if (every) {
+    m.everyMs = parseDuration(every, "--every")
+    if (m.everyMs < 10_000) throw new Error("--every must be at least 10s.")
+  }
+  const replay = strFlag(flags, "replay")
+  if (replay) m.replay = replayMode(replay)
+  const parallel = strFlag(flags, "parallel")
+  if (parallel) {
+    if (!(Number(parallel) >= 1)) throw new Error("--parallel must be a positive number")
+    m.parallel = Number(parallel)
+  }
+  const out = strFlag(flags, "out")
+  if (out) m.outDir = path.resolve(out)
+  return { ...cfg, monitor: m }
+}
+
+async function cmdMonitor(refs: string[], flags: Flags): Promise<number> {
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  cfg = withMonitorFlags(cfg, flags)
+  const m = cfg.monitor
+  const channels = [m.alerts.teams ? "Teams" : "", m.alerts.email ? `email to ${m.alerts.email.to.join(", ")}` : ""].filter(Boolean)
+
+  if (boolFlag(flags, "test-alerts")) {
+    if (!channels.length) throw new Error("No alert channels are set up. Add monitor.alerts.teams or monitor.alerts.email to forgeqe.yaml.")
+    const sent = await sendTestAlert(cfg)
+    for (const s of sent) console.log(s.ok ? `✓ Test alert sent to ${s.channel === "teams" ? "Teams" : `email (${m.alerts.email!.to.join(", ")})`}` : `✗ ${s.channel === "teams" ? "Teams" : "Email"}: ${s.error}`)
+    return sent.every((s) => s.ok) ? 0 : 1
+  }
+
+  const checks = refs.length ? refs : m.checks
+  if (!checks.length) throw new Error(`What should ForgeQE monitor? Set monitor.checks in forgeqe.yaml, or pass sources.\n${CASES_USAGE}`)
+  const once = boolFlag(flags, "once")
+  const verbose = boolFlag(flags, "verbose")
+  const color = Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain")
+  const every = m.everyMs % 3_600_000 === 0 ? `${m.everyMs / 3_600_000}h` : m.everyMs % 60_000 === 0 ? `${m.everyMs / 60_000}m` : `${Math.round(m.everyMs / 1000)}s`
+  console.log(
+    `${once ? "Checking" : "Monitoring"} ${checks.map((r) => (/\s/.test(r) ? JSON.stringify(r) : r)).join(" ")}${once ? "" : ` every ${every}`} · replay ${m.replay} · alerts: ${channels.length ? channels.join(", ") : "none (set monitor.alerts)"}${once ? "" : " · Ctrl+C stops"}`,
+  )
+
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.on("SIGINT", onSigint)
+  process.on("SIGTERM", onSigint)
+  try {
+    return await runMonitor({
+      config: cfg,
+      checks,
+      once,
+      headed: boolFlag(flags, "headed"),
+      url: strFlag(flags, "url"),
+      skills: skillFlags(flags),
+      signal: controller.signal,
+      onEvent: (e) => {
+        const line = verbose ? suiteEventLine(e, m.parallel, color, detailOf(flags)) : null
+        if (line) console.log(line)
+      },
+      onRound: (r, nextAt) => console.log(`${verbose ? "\n" : ""}${formatRound(r, nextAt)}`),
+    })
+  } finally {
+    process.off("SIGINT", onSigint)
+    process.off("SIGTERM", onSigint)
+  }
+}
+
+async function cmdSuite(refs: string[], flags: Flags): Promise<number> {
+  if (!refs.length) throw new Error(CASES_USAGE)
+  let cfg = loadConfig(configOpts(flags))
+  const profile = strFlag(flags, "profile")
+  if (profile) cfg = selectProfile(cfg, profile)
+  cfg = withCodeFlags(cfg, flags)
+  const parallelRaw = strFlag(flags, "parallel")
+  if (parallelRaw && !(Number(parallelRaw) >= 1)) throw new Error("--parallel must be a positive number")
+  const parallel = parallelRaw ? Number(parallelRaw) : cfg.suite.parallel
+  const cases = await loadCases(refs, cfg.sources)
+  const repo = codeRepo(cfg, flags)
+  const color = Boolean(process.stdout.isTTY) && !boolFlag(flags, "plain")
+  console.log(`${cases.length} test case${cases.length === 1 ? "" : "s"}${parallel > 1 ? `, ${parallel} at a time` : ""}${repo ? `; passed cases get a test in ${repo}` : ""}`)
+
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  try {
+    const suite = await runSuite({
+      config: cfg,
+      cases,
+      repo,
+      parallel,
+      outDir: strFlag(flags, "out"),
+      writeBack: boolFlag(flags, "no-write-back") ? false : undefined,
+      headed: boolFlag(flags, "headed"),
+      url: strFlag(flags, "url"),
+      skills: skillFlags(flags),
+      skillsRepo: repo || process.cwd(),
+      ...memoryFlags(flags),
+      signal: controller.signal,
+      onEvent: (e) => {
+        const line = suiteEventLine(e, parallel, color, detailOf(flags))
+        if (line) console.log(line)
+      },
+    })
+    console.log("")
+    console.log(formatSuite(suite))
+    writeJobSummary(suite)
+    const notified = notifiedLine(await notifySuite(cfg, suite))
+    if (notified) console.log(notified)
+    return suiteExitCode(suite)
+  } finally {
+    process.off("SIGINT", onSigint)
+  }
+}