@capagents/forgeqe 1.2.0 → 1.3.0

package/src/engine/bridge.ts

@@ -1,10 +1,12 @@
 import { spawn } from "node:child_process"
 import { createInterface } from "node:readline"
+import path from "node:path"
 
 import type { LlmProfile } from "../llm.ts"
-import type { AgentEvent, CaseReport, MemoryInfo, ReplayMode, RunResult } from "../types.ts"
+import type { AgentEvent, CaseReport, MemoryInfo, ReplayMode, RunResult, Usage } from "../types.ts"
 import { browserProviderEnvNames, loginEnvNames } from "../childEnv.ts"
-import { recordUsage } from "../usage.ts"
+import { recordCall, withUsageScope } from "../tokenomics/ledger.ts"
+import { addUsage } from "../usage.ts"
 import type { BrowserProvider, BrowserRemoteConfig, LoginConfig } from "../config.ts"
 import { debugLogging, logEvent } from "../sessionLog.ts"
 import { engineEnv } from "./setup.ts"
@@ -20,14 +22,20 @@ export type EngineRequest = {
   allowedHosts: string[]
   browser?: { provider: BrowserProvider; remote?: BrowserRemoteConfig }
   extendSystemMessage?: string
-  /** Page memory folder and replay mode; omit to run without memory. */
-  memory?: { dir: string; replay: ReplayMode }
+  /**
+   * Page memory folder and replay mode; omit to run without memory. checks_first (registry.mode on,
+   * docs/COST_ARCHITECTURE.md): read-only steps are left out of a replay, and recorded checks can pass it.
+   */
+  memory?: { dir: string; replay: ReplayMode; checks_first?: boolean }
   /** BROWSER_USE_* tuning for the engine process. */
   env?: Record<string, string>
   /** Saved logins: the engine reads values from the environment by name, or from `values` (logins remembered for this session). */
   logins?: (LoginConfig & { values?: { username?: string; password?: string; totp?: string } })[]
   /** Steps in the test case this goal came from; the agent reports a verdict for each. */
   caseSteps?: number
+  /** The test case and a key per step: a run of an edited case replays the recorded steps before the first change. */
+  caseId?: string
+  caseStepKeys?: string[]
   screenshots?: "all" | "failures" | "off"
   accessibility?: boolean
   /** Record the application's API calls (network.json). */
@@ -73,6 +81,9 @@ type EngineMemory = {
   new_elements?: number
   flow?: "saved" | "updated" | null
   resume?: { steps?: number; failed_at?: number; reason?: string; lines?: string[]; file?: string }
+  checked?: number
+  checks_held?: number
+  skipped_reads?: number
 }
 
 type EngineResult = {
@@ -108,6 +119,8 @@ type EngineEvent =
     }
   | { type: "result"; step?: number; items?: { ok?: boolean; done?: boolean; text?: string }[] }
   | { type: "usage"; input?: number; output?: number; cached?: number }
+  /** One model call of the browser agent: its time and tokens (prompt tokens include cached ones). */
+  | { type: "call"; ms?: number; ok?: boolean; input?: number; output?: number; cached?: number; cache_write?: number }
   | { type: "done"; result?: EngineResult }
 
 function toMemoryInfo(m: EngineMemory | undefined): MemoryInfo | undefined {
@@ -123,6 +136,8 @@ function toMemoryInfo(m: EngineMemory | undefined): MemoryInfo | undefined {
     elements: Number(m.elements || 0),
     newElements: Number(m.new_elements || 0),
     flow: m.flow || null,
+    ...(m.checked ? { checked: Number(m.checked), checksHeld: Number(m.checks_held || 0) } : {}),
+    ...(m.skipped_reads ? { skippedReads: Number(m.skipped_reads) } : {}),
     ...(m.resume?.steps
       ? {
           resume: {
@@ -222,6 +237,11 @@ export async function runEngine(opts: {
   graceMs?: { stop: number; kill: number }
 }): Promise<{ result: RunResult; files: string[] }> {
   const { request: req, onEvent } = opts
+  // Each model call goes to the usage ledger under this run (its folder's name) and case; what the per-call events
+  // missed (an engine that sends only a total) is recorded as one unattributed call when the run ends.
+  const scope = { runId: path.basename(req.outDir), ...(req.caseId ? { caseId: req.caseId } : {}) }
+  const model = req.llm.deployment || req.llm.model
+  const callTotal: Usage = { input: 0, output: 0 }
   const [bin, ...args] = opts.command || [opts.python, "-m", "forgeqe_engine", "run"]
   const child = spawn(bin!, args, {
     env: engineEnv(debugLogging() ? { ...req.env, BROWSER_USE_LOGGING_LEVEL: "debug" } : req.env, [
@@ -256,6 +276,7 @@ export async function runEngine(opts: {
     memory: req.memory || null,
     logins: loginPayload(req.logins),
     case_steps: req.caseSteps || 0,
+    ...(req.caseId && req.caseStepKeys?.length ? { case_id: req.caseId, case_step_keys: req.caseStepKeys } : {}),
     screenshots: req.screenshots || "all",
     accessibility: req.accessibility !== false,
     network: req.network !== false,
@@ -335,6 +356,19 @@ export async function runEngine(opts: {
       case "usage":
         onEvent?.({ type: "usage", usage: { input: Number(ev.input || 0), output: Number(ev.output || 0), ...(ev.cached ? { cached: Number(ev.cached) } : {}) } })
         return
+      case "call": {
+        const usage: Usage = {
+          input: Number(ev.input || 0),
+          output: Number(ev.output || 0),
+          ...(ev.cached ? { cached: Number(ev.cached) } : {}),
+          ...(ev.cache_write ? { cacheWrite: Number(ev.cache_write) } : {}),
+        }
+        Object.assign(callTotal, addUsage(callTotal, usage))
+        withUsageScope(scope, () =>
+          recordCall({ agent: "browser agent", usage, price: req.llm.price, provider: req.llm.provider, model, purpose: "browser", ms: Number(ev.ms || 0), outcome: ev.ok === false ? "error" : "ok" }),
+        )
+        return
+      }
       case "done":
         done = ev.result || {}
         setTimeout(() => child.kill(), 10_000).unref()
@@ -382,7 +416,15 @@ export async function runEngine(opts: {
   }
   const finished: EngineResult = done
   const result = toRunResult(req.goal, req.startUrl || "", finished)
-  recordUsage("browser agent", result.usage, req.llm.price)
+  const rest: Usage = {
+    input: Math.max(0, result.usage.input - callTotal.input),
+    output: Math.max(0, result.usage.output - callTotal.output),
+    ...((result.usage.cached || 0) > (callTotal.cached || 0) ? { cached: (result.usage.cached || 0) - (callTotal.cached || 0) } : {}),
+  }
+  if (rest.cached) rest.cached = Math.min(rest.cached, rest.input)
+  withUsageScope(scope, () =>
+    recordCall({ agent: "browser agent", usage: rest, price: req.llm.price, provider: req.llm.provider, model, purpose: callTotal.input || callTotal.output ? "unattributed" : "browser", outcome: finished.cancelled ? "cancelled" : "ok" }),
+  )
   onEvent?.({ type: "usage", usage: result.usage })
   onEvent?.({ type: "done", result })
   return { result, files: finished.files || [] }

package/src/mcp/casetools.ts

@@ -6,7 +6,8 @@ import type { TestCase } from "../cases/types.ts"
 import type { AppConfig } from "../config.ts"
 import { readPages } from "../memory.ts"
 import { DEFAULT_THRESHOLDS, releaseReadiness, saveReadiness, type Readiness } from "../cases/readiness.ts"
-import { updateAdoCase } from "../cases/save.ts"
+import { jiraCase, storyCases, updateAdoCase, updateJiraCase, type NewCase } from "../cases/save.ts"
+import { planJourneys, type JourneyCase } from "../cases/journey.ts"
 import { writeAdoWikiPage } from "../cases/wiki.ts"
 import type { McpTool, ToolContext } from "./tools.ts"
 import { notifiedLine, notify, readinessNotice } from "../notify/events.ts"
@@ -106,11 +107,11 @@ export const CASE_TOOLS: McpTool[] = [
   {
     name: "update_test_case",
     description:
-      "Rewrite an Azure DevOps Test Case's steps (and optionally its title) after the user agrees: ForgeQE shows the current and the new steps and asks (Update / Don't update); the reason goes into the work item's history, and the old steps stay there. Use it for a case run_test_cases classified as test case needs updating (write the steps from what the run found the application does: run_details has every step and element), or a case check_test_cases found unclear. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to these exact steps.",
+      "Rewrite a test case's steps (and optionally its title) in place after the user agrees: an Azure DevOps Test Case (the reason goes into its history, the old steps stay there) or a Jira test issue (the steps in its description are replaced, the text above them kept, and the reason added as a comment). ForgeQE shows the current and the new steps and asks (Update / Don't update). Use it for a case run_test_cases classified as test case needs updating (write the steps from what the run found the application does: run_details has every step and element), a case check_test_cases found unclear, a change the user asks for after reviewing a case, and a case save_test_cases returned as differs or similar. The case's automated test, when it has one, is brought up to date on its next run. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to these exact steps.",
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "The test case: ADO-2236, 2236, or its link" },
+        id: { type: "string", description: "The test case: ADO-2236, 2236, or its link in Azure DevOps; SHOP-31 in Jira" },
         title: { type: "string", description: "A new title, only when the old one no longer fits" },
         steps: {
           type: "array",
@@ -123,17 +124,23 @@ export const CASE_TOOLS: McpTool[] = [
       required: ["id", "steps", "reason"],
     },
     async run(args, ctx) {
-      const id = Number(/(\d+)\s*$/.exec(String(args.id).replace(/[/?#].*$/, ""))?.[1] || /edit\/(\d+)/.exec(String(args.id))?.[1])
-      if (!id) throw new Error(`"${args.id}" is not an Azure DevOps test case id.`)
-      if (!ctx.config.sources.ado) throw new Error("Azure DevOps is not set up: updating test cases works for Azure DevOps Test Cases.")
+      const raw = String(args.id).trim()
+      const jiraKey = /^(?!ADO-)[A-Z][A-Z0-9_]*-\d+$/i.test(raw) ? raw.toUpperCase() : /\/browse\/([A-Z][A-Z0-9_]*-\d+)/i.exec(raw)?.[1]?.toUpperCase()
+      const id = jiraKey ? 0 : Number(/(\d+)\s*$/.exec(raw.replace(/[/?#].*$/, ""))?.[1] || /edit\/(\d+)/.exec(raw)?.[1])
+      if (!jiraKey && !id) throw new Error(`"${args.id}" is not an Azure DevOps test case id or a Jira issue key.`)
+      if (jiraKey && !ctx.config.sources.jira) throw new Error("Jira is not set up: add sources.jira to forgeqe.yaml.")
+      if (!jiraKey && !ctx.config.sources.ado) throw new Error("Azure DevOps is not set up: add sources.azure_devops to forgeqe.yaml.")
       const steps = (args.steps as { action: string; expected?: string }[]).filter((s) => s?.action?.trim()).map((s) => ({ action: s.action.trim(), ...(s.expected?.trim() ? { expected: s.expected.trim() } : {}) }))
       if (!steps.length) throw new Error("steps is empty.")
-      const [current] = await casesFrom([{ source: "azure_devops", ids: [String(id)] } as CaseSelector], ctx.config.sources, ctx.cwd)
+      const current: { steps: NewCase["steps"]; url?: string } | undefined = jiraKey
+        ? await jiraCase(ctx.config.sources, jiraKey)
+        : (await casesFrom([{ source: "azure_devops", ids: [String(id)] } as CaseSelector], ctx.config.sources, ctx.cwd))[0]
+      const label = jiraKey || String(id)
       const show = (list: { action: string; expected?: string }[]) => list.map((s, i) => `  ${i + 1}. ${s.action}${s.expected ? `  → ${s.expected}` : ""}`)
       const lines = ["Now:", ...show(current?.steps || []), "", "New:", ...show(steps), "", `Why: ${args.reason}`]
       if (ctx.ask) {
         const choice = await ctx.ask({
-          title: `Update test case ${id}${args.title ? ` and rename it "${args.title}"` : ""}?`,
+          title: `Update test case ${label}${args.title ? ` and rename it "${args.title}"` : ""}?`,
           detail: current?.url,
           lines,
           options: [
@@ -145,9 +152,98 @@ export const CASE_TOOLS: McpTool[] = [
       } else if (args.confirmed !== true) {
         return { updated: false, needs_confirmation: true, current: current?.steps, proposed: steps, next_step: "Show the user the current and new steps; call update_test_case again with confirmed: true only after they agree." }
       }
-      const url = await updateAdoCase(ctx.config.sources, id, { title: args.title ? String(args.title) : undefined, steps, reason: String(args.reason) })
-      ctx.emit?.({ type: "card", card: { status: "ok", title: `Test case ${id} updated`, stats: `${steps.length} steps`, body: [...show(steps), "", `Why: ${args.reason}`, url] } })
-      return { updated: true, url, steps: steps.length, next_step: "Offer to run it again with run_test_cases." }
+      const change = { title: args.title ? String(args.title) : undefined, steps, reason: String(args.reason) }
+      const url = jiraKey ? await updateJiraCase(ctx.config.sources, jiraKey, change) : await updateAdoCase(ctx.config.sources, id, change)
+      ctx.emit?.({ type: "card", card: { status: "ok", title: `Test case ${label} updated`, stats: `${steps.length} steps`, body: [...show(steps), "", `Why: ${args.reason}`, url] } })
+      return { updated: true, url, steps: steps.length, next_step: "Offer to run it again with run_test_cases; its automated test, when it has one, is updated to the new steps in that run." }
+    },
+  },
+  {
+    name: "story_test_cases",
+    description:
+      "The test cases already linked to an Azure DevOps or Jira story, with their steps and expected results. Call it before writing test cases for a story, so you write only the cases its acceptance criteria still need, and propose updates (update_test_case) to linked cases that no longer fit, instead of writing them again. Reads only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"], description: "Where the story is" },
+        story: { type: "string", description: "The story's work item id (Azure DevOps) or issue key (Jira)" },
+      },
+      required: ["system", "story"],
+    },
+    async run(args, ctx) {
+      const story = String(args.story || "").trim()
+      if (!story) throw new Error("story is required.")
+      const found = await storyCases(ctx.config.sources, args.system === "jira" ? "jira" : "azure_devops", story)
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: "info",
+          title: `Test cases linked to ${found.story.id}${found.story.title ? ` ${found.story.title}` : ""}`,
+          stats: `${found.cases.length} linked`,
+          body: found.cases.length ? found.cases.map((c) => `${c.id}  ${c.title}  (${c.steps.length} steps)`) : ["None yet."],
+        },
+      })
+      return {
+        story: found.story,
+        cases: found.cases.map((c) => ({ id: c.id, title: c.title, url: c.url, steps: c.steps.map((st, i) => `${i + 1}. ${st.action}${st.expected ? ` → ${st.expected}` : ""}`) })),
+        next_step: found.cases.length
+          ? "Compare these with the story's acceptance criteria. Write only the cases for criteria and rules no linked case covers, and save only those. For a linked case that no longer fits the story, propose its new steps with update_test_case. Tell the user which criteria the linked cases already cover."
+          : "No case is linked yet: write the cases from the story.",
+      }
+    },
+  },
+  {
+    name: "e2e_journey",
+    description:
+      "Plan end-to-end journeys from test cases that already exist, instead of writing them again: from the cases linked to a story (system and story) or any find_test_cases sources. Groups the cases that start the same way (same start page and first steps, such as signing in), keeps those shared steps once, and lays out each case's remaining steps as a section of one journey, with which case and steps each section comes from. Flags cases that look like negative paths, which may end the session. Writes nothing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"], description: "With story: the story's system" },
+        story: { type: "string", description: "A story whose linked cases to use" },
+        sources: { type: "array", description: "Or the same sources as find_test_cases", items: { type: "object" } },
+      },
+    },
+    async run(args, ctx) {
+      let cases: JourneyCase[]
+      let story: { id: string; title: string; url: string } | undefined
+      if (args.story) {
+        const found = await storyCases(ctx.config.sources, args.system === "jira" ? "jira" : "azure_devops", String(args.story).trim())
+        story = found.story
+        cases = found.cases.map((c) => ({ id: c.id, title: c.title, url: c.url, steps: c.steps }))
+      } else if (Array.isArray(args.sources) && args.sources.length) {
+        cases = (await casesFrom(args.sources as CaseSelector[], ctx.config.sources, ctx.cwd)).map((c) => ({ id: c.id, title: c.title, url: c.url, startUrl: c.startUrl, steps: c.steps }))
+      } else throw new Error("Give a story (with system), or sources.")
+      const plan = planJourneys(cases)
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: plan.journeys.length ? "ok" : "info",
+          title: `End-to-end journeys${story ? ` for ${story.id}` : ""}`,
+          stats: `${plan.journeys.length} journeys from ${cases.length} cases · ${plan.stepsSaved} repeated steps saved`,
+          body: [
+            ...plan.journeys.flatMap((j, n) => [
+              `Journey ${n + 1}: ${j.shared.length} shared steps, then ${j.sections.length} cases`,
+              ...j.sections.map((sec) => `    ${sec.negative ? "▲" : "·"} ${sec.caseId}  ${sec.title}  (steps ${sec.from}-${sec.to})`),
+            ]),
+            ...(plan.alone.length ? ["", `On their own: ${plan.alone.map((c) => c.id).join(", ")}`] : []),
+          ],
+        },
+      })
+      return {
+        ...(story ? { story } : {}),
+        journeys: plan.journeys.map((j) => ({
+          start_url: j.startUrl,
+          shared_steps: j.shared.length,
+          steps: j.steps.map((st, i) => `${i + 1}. ${st.action}${st.expected ? ` → ${st.expected}` : ""}`),
+          sections: j.sections.map((sec) => ({ case: sec.caseId, title: sec.title, steps: `${sec.from}-${sec.to}`, ...(sec.negative ? { negative: true } : {}) })),
+          repeated_steps_saved: j.saved,
+        })),
+        on_their_own: plan.alone.map((c) => ({ case: c.id, title: c.title })),
+        next_step: plan.journeys.length
+          ? "Order the sections so each leaves the application in the state the next one needs. A negative section (an error, a refusal, signing out, deleting shared data) goes last or stays its own case. Show the user each journey with the cases it covers. When they agree, save each as one case with save_test_cases, titled \"E2E: …\", with a description naming the cases it covers; keep the original cases. Run a journey instead of its separate cases only when the user asks for an end-to-end run."
+          : "The cases share no first steps, so a journey saves nothing: offer to run them as they are.",
+      }
     },
   },
   {

package/src/mcp/commands.ts

@@ -1,6 +1,7 @@
-import { coverageLines, EXTEND_FROM, measureCoverage, type Candidate } from "../code/coverage.ts"
+import { coverageLines, EXTEND_FROM, measureCoverage, settle, type Candidate } from "../code/coverage.ts"
 import { buildGraph } from "../code/graph/graph.ts"
-import { EXISTING_TEST_FILE } from "../code/notes.ts"
+import { EXISTING_TEST_FILE, EXTEND_TEST_FILE } from "../code/notes.ts"
+import { recordDecision, type DecisionRecord } from "../code/decisions.ts"
 import type { ExistingTest, TestTarget } from "../code/prompt.ts"
 import { existsSync, readFileSync } from "node:fs"
 import path from "node:path"
@@ -33,19 +34,54 @@ const clip = (s: string | undefined, n: number) => {
 /** Marks a browser_run that was a task (a lookup in a tool), not a flow to automate; write_test refuses such runs. */
 
 /**
- * Reuse, extend, or new, from what the repository's tests already cover of the run (code graph and page memory).
- * The clear cases go ahead and say why; where the evidence fits more than one way, the user picks, seeing each
- * option's effect. A mode the user gave (through ForgeQE's agent) is followed without asking.
+ * Reuse, extend, add a test beside one, or new, from what the repository's tests already cover of the run (code graph
+ * and page memory). The clear cases go ahead and say why; where the evidence fits more than one way, the user picks,
+ * seeing each option's effect, and with no one to ask a fixed policy decides (settle). A mode the user gave is followed
+ * as it is; one ForgeQE's agent chose before the browser run is followed too, but a test is not made overlong.
  */
 export async function chooseTarget(runDir: string, repo: string, args: Record<string, any>, ctx: ToolContext): Promise<{ target?: TestTarget } | { cancelled: true }> {
-  const asked = typeof args.mode === "string" && args.mode !== "auto" ? (args.mode as "new" | "extend" | "reuse" | "update") : null
-  if (asked === "new") return {}
+  const asked = typeof args.mode === "string" && args.mode !== "auto" ? (args.mode as "new" | "extend" | "reuse" | "update" | "sibling") : null
+  // ForgeQE's agent chose it before the browser run (args.why); otherwise the user named it.
+  const byAgent = Boolean(args.why)
+  const goal = ((): string => {
+    try {
+      return (JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8")) as { goal?: string }).goal || ""
+    } catch {
+      return ""
+    }
+  })()
+  const note = (by: NonNullable<DecisionRecord["by"]>, mode: NonNullable<DecisionRecord["mode"]>, c: Candidate | undefined, why: string) =>
+    recordDecision(repo, { goal, stage: "chosen", where: "write_test", by, mode, ...(c ? { test: c.test, file: c.file } : {}), why, run_dir: runDir })
+  if (asked === "new") {
+    note(byAgent ? "agent" : "user", "new", undefined, "asked for a new test")
+    return {}
+  }
   const graph = await buildGraph(repo).catch(() => null)
   if (!graph) return {}
   const cov = measureCoverage(runDir, graph, ctx.config.memory.dir)
-  const named = args.test_file ? cov.candidates.find((c) => c.file === String(args.test_file).replace(/^\.\//, "")) : undefined
+  const file = args.test_file ? String(args.test_file).replace(/^\.\//, "") : ""
+  // A test named but not measured (its page objects do not locate this run's elements) is still the one to work from.
+  const measurable = cov.items.flatMap((it, i) => (it.members.length ? [i] : []))
+  // In a file of many tests, the one named (Class.Method, or its method name) when there is one.
+  const testName = args.test_name ? String(args.test_name) : ""
+  const sameTest = (c: Candidate) => !testName || c.test === testName || c.test.endsWith(`.${testName}`)
+  const lineCount = (test: string) => graph.files.find((f) => f.file === file)?.classes.flatMap((k) => k.members.map((m) => ({ k, m }))).find(({ k, m }) => `${k.name}.${m.name}` === test || m.name === test)
+  const unmeasured = (): Candidate => {
+    const test = testName || path.basename(file).replace(/\.[^.]+$/, "")
+    const at = lineCount(test)
+    return { test: at ? `${at.k.name}.${at.m.name}` : test, file, line: at?.m.line || 1, lines: at ? at.m.endLine - at.m.line + 1 : undefined, covered: [], missing: measurable, share: 0 }
+  }
+  const named = file ? cov.candidates.find((c) => c.file === file && sameTest(c)) || unmeasured() : undefined
   let decision = cov.decision
-  if (asked) decision = { mode: asked, ask: false, target: named || cov.candidates[0], why: "the user asked for it" }
+  if (asked) decision = { mode: asked, ask: false, target: named || cov.candidates[0], why: args.why ? String(args.why) : "the user asked for it" }
+  // Not the user's own choice, and no one to ask, or the agent's: ForgeQE's policy settles it.
+  // Who decided: the user, ForgeQE's agent, the coverage measure, or ForgeQE's policy when it changed or settled it.
+  let by: NonNullable<DecisionRecord["by"]> = asked ? (byAgent ? "agent" : "user") : "coverage"
+  if ((!asked || byAgent) && (byAgent || !decision.ask || !ctx.ask)) {
+    const settled = settle(decision)
+    if (settled.mode !== decision.mode || decision.ask) by = "policy"
+    decision = settled
+  }
   const lines = coverageLines(cov)
   const toTarget = (mode: TestTarget["mode"], c: Candidate): TestTarget => ({
     mode,
@@ -54,7 +90,7 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
     line: c.line,
     covered: c.covered.map((i) => cov.items[i]!.label),
     missing: c.missing.map((i) => cov.items[i]!.label),
-    why: `it covers ${c.covered.length} of ${c.covered.length + c.missing.length} steps and checks this run located`,
+    why: c.covered.length ? `it covers ${c.covered.length} of ${c.covered.length + c.missing.length} steps and checks this run located` : decision.why,
   })
   const say = (title: string, why: string) =>
     ctx.emit?.({ type: "card", card: { status: "info", title, stats: why, body: lines.length ? ["What the repository's tests already cover of this run:", ...lines] : [] } })
@@ -62,7 +98,7 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
     const options = cov.candidates.filter((c) => c.share >= EXTEND_FROM).slice(0, 2).flatMap((c, n) => {
       const name = `${path.basename(c.file)}`
       return c.missing.length
-        ? [{ id: `extend:${n}`, label: `Extend ${name} (adds ${c.missing.length})` }]
+        ? [{ id: `extend:${n}`, label: `Extend ${name} (adds ${c.missing.length})` }, ...(n === 0 ? [{ id: `sibling:${n}`, label: `Add a test beside ${c.test.split(".").pop()} in ${name}` }] : [])]
         : [{ id: `reuse:${n}`, label: `Reuse ${name} as it is` }]
     })
     const answer = await ctx.ask({
@@ -72,18 +108,26 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
       options: [...options, { id: "new", label: "Write a new test" }, { id: "cancel", label: "Cancel" }],
     })
     if (!answer || answer === "cancel") return { cancelled: true }
-    if (answer === "new") return {}
-    const [mode, n] = answer.split(":") as ["reuse" | "extend", string]
+    if (answer === "new") {
+      note("user", "new", undefined, `${decision.why}; the user chose a new test`)
+      say("Writing a new test", "the user chose it")
+      return {}
+    }
+    const [mode, n] = answer.split(":") as ["reuse" | "extend" | "sibling", string]
     const c = cov.candidates.filter((x) => x.share >= EXTEND_FROM)[Number(n)]!
-    say(mode === "reuse" ? `Reusing ${c.test}` : `Extending ${c.test}`, "the user chose it")
+    note("user", mode, c, `${decision.why}; the user chose it`)
+    say(mode === "reuse" ? `Reusing ${c.test}` : mode === "sibling" ? `Adding a test beside ${c.test}` : `Extending ${c.test}`, "the user chose it")
     return { target: toTarget(mode, c) }
   }
   if (decision.mode === "new" || !decision.target) {
+    note(by, "new", undefined, decision.why)
     if (cov.candidates.length) say("Writing a new test", decision.why)
     return {}
   }
-  const mode: TestTarget["mode"] = decision.mode === "reuse" ? "reuse" : decision.mode === "update" ? "update" : "extend"
-  say(mode === "reuse" ? `Reusing ${decision.target.test}` : mode === "update" ? `Updating ${decision.target.test}` : `Extending ${decision.target.test}`, decision.why)
+  const mode: TestTarget["mode"] = decision.mode === "reuse" || decision.mode === "update" || decision.mode === "sibling" ? decision.mode : "extend"
+  const verb = { reuse: "Reusing", update: "Updating", sibling: "Adding a test beside", extend: "Extending" }[mode]
+  note(by, mode, decision.target, decision.why)
+  say(`${verb} ${decision.target.test}`, decision.why)
   return { target: toTarget(mode, decision.target) }
 }
 
@@ -158,11 +202,12 @@ export const COMMAND_TOOLS: McpTool[] = [
         repo: { type: "string", description: "Repository to write the test in, relative to the working directory (default: the working directory)" },
         mode: {
           type: "string",
-          enum: ["auto", "new", "extend", "reuse", "update"],
+          enum: ["auto", "new", "extend", "reuse", "update", "sibling"],
           description:
-            "auto (default): ForgeQE measures which existing tests already cover the run, then reuses one that covers it all, extends one that covers most, or writes a new test, and asks the user when that is not clear. new, extend, reuse, update: only when the user said which (\"extend the login test\", \"write a separate test\", \"update it\" after a reused test failed).",
+            "auto (default): ForgeQE measures which existing tests already cover the run, then reuses one that covers it all, extends one that covers most (or adds a test beside it, in its class, when it is already long), or writes a new test that reuses the repository's code, and asks the user when that is not clear. new, extend, reuse, update, sibling: only when the user said which (\"extend the login test\", \"add a separate test next to it\", \"write a separate test\", \"update it\" after a reused test failed).",
         },
-        test_file: { type: "string", description: "With mode extend, reuse, or update: the existing test file (from the user, or from an earlier write_test result)" },
+        test_file: { type: "string", description: "With mode extend, reuse, update, or sibling: the existing test file (from the user, or from an earlier write_test result)" },
+        test_name: { type: "string", description: "With test_file: the test in it (Class.Method or the method name), when the file has more than one" },
       },
     },
     async run(args, ctx) {
@@ -177,8 +222,16 @@ export const COMMAND_TOOLS: McpTool[] = [
       const goal = (readJson(path.join(runDir, "run.json")) as { goal?: string } | null)?.goal || ""
       // browser_run found an earlier test for this flow and it failed: Scribe updates it rather than adding another.
       const existingTest = readJson(path.join(runDir, EXISTING_TEST_FILE)) as ExistingTest | null
+      // ForgeQE's agent chose, before the browser ran, to extend an earlier test: that test, unless the user says otherwise.
+      const extend = readJson(path.join(runDir, EXTEND_TEST_FILE)) as { testFile?: string; test?: string; mode?: "extend" | "sibling" } | null
+      // The agent repeating that choice to write_test (its mode and file) is still the agent's choice, not the user's.
+      const sameChoice = extend?.testFile && args.mode === (extend.mode || "extend") && (!args.test_file || String(args.test_file).replace(/^\.\//, "") === extend.testFile)
+      const how =
+        extend?.testFile && (!args.mode || args.mode === "auto" || sameChoice)
+          ? { ...args, mode: extend.mode || "extend", test_file: extend.testFile, ...(extend.test ? { test_name: extend.test } : {}), why: "chosen before the browser run, from the existing tests closest to this flow" }
+          : args
       // Otherwise: what the repository's tests already cover of this run decides reuse, extend, or new.
-      const chosen = existingTest?.testFile ? { target: undefined } : await chooseTarget(runDir, repo, args, ctx)
+      const chosen = existingTest?.testFile ? { target: undefined } : await chooseTarget(runDir, repo, how, ctx)
       if ("cancelled" in chosen) return { status: "cancelled", notes: "The user cancelled before Scribe started; nothing was changed." }
       const target = chosen.target
       ctx.emit?.({ type: "code-start", runDir, repo, goal })
@@ -200,6 +253,7 @@ export const COMMAND_TOOLS: McpTool[] = [
         throw err
       }
       ctx.emit?.({ type: "code-done", result: r, ms: Date.now() - t0 })
+      recordDecision(repo, { goal, stage: "outcome", where: "write_test", status: r.status, ...(r.existing ? { existing: r.existing } : {}), ...(r.testFile ? { file: r.testFile } : {}), ...(target ? { mode: target.mode, test: target.test } : existingTest ? { mode: "update" } : { mode: "new" }), ...(r.breaches ? { breaches: r.breaches } : {}), run_dir: runDir })
       ctx.emit?.({ type: "card", card: codeCard(buildCodeSummary(r, Date.now() - t0)) })
       return {
         status: r.status,