@capagents/forgeqe 1.2.0 → 1.3.0

package/src/code/coverage.ts

@@ -19,9 +19,10 @@ import type { Check, Locator, Step } from "./handoff.ts"
 export type CoverageItem = { label: string; kind: "step" | "check"; members: string[] }
 
 /** An existing test and which of the run's items (by index) it reaches. */
-export type Candidate = { test: string; file: string; line: number; covered: number[]; missing: number[]; share: number }
+export type Candidate = { test: string; file: string; line: number; covered: number[]; missing: number[]; share: number; lines?: number }
 
-export type Mode = "new" | "extend" | "reuse" | "update"
+/** sibling: a new test method beside an existing one, in its class, reusing its setup and steps. */
+export type Mode = "new" | "extend" | "reuse" | "update" | "sibling"
 
 /** `ask`: the evidence fits more than one way, so the person chooses (the options, each with what it changes). */
 export type Decision = { mode: Mode; ask: boolean; target?: Candidate; why: string }
@@ -32,6 +33,10 @@ export type Coverage = { items: CoverageItem[]; candidates: Candidate[]; decisio
 export const EXTEND_FROM = 0.4
 /** Another test this close to the best one makes the choice the person's. */
 const RIVAL = 0.75
+/** A test this long is not made longer: the new steps go in a test beside it, which reuses its setup and steps. */
+export const MAX_EXTEND_LINES = 80
+/** With no one to ask, a test covering at least this share is extended; one covering less gets a test beside it. */
+export const EXTEND_ALONE_FROM = 0.6
 
 type RunJson = { final_url?: string; memory?: { dir?: string } }
 
@@ -84,7 +89,7 @@ export function measureCoverage(runDir: string, graph: CodeGraph, memoryDir?: st
   // test in its own way, so it is unknown, not missing.
   const measurable = items.flatMap((it, i) => (it.members.length ? [i] : []))
   const candidates = [...byTest.values()]
-    .map(({ at, covered }) => ({ test: qualified(at), file: at.file, line: at.member.line, covered: [...covered].sort((a, b) => a - b), missing: measurable.filter((i) => !covered.has(i)), share: measurable.length ? covered.size / measurable.length : 0 }))
+    .map(({ at, covered }) => ({ test: qualified(at), file: at.file, line: at.member.line, lines: at.member.endLine - at.member.line + 1, covered: [...covered].sort((a, b) => a - b), missing: measurable.filter((i) => !covered.has(i)), share: measurable.length ? covered.size / measurable.length : 0 }))
     .sort((a, b) => b.covered.length - a.covered.length || a.missing.length - b.missing.length)
   return { items, candidates, decision: decide(items, candidates) }
 }
@@ -104,6 +109,20 @@ export function decide(items: CoverageItem[], candidates: Candidate[]): Decision
   return { mode: "extend", ask: false, target: best, why: `${best.test} covers ${best.covered.length} of ${n}; only ${best.missing.length} ${best.missing.length === 1 ? "is" : "are"} missing` }
 }
 
+/**
+ * The decision when it is ForgeQE's to make, not the person's: nobody can be asked (a pipeline, a plain run) or the
+ * choice came from ForgeQE's agent. Tests stay short: a long test gets a test beside it instead of more steps. Unclear
+ * between close tests, the best is extended when it covers most of the flow, else a test is added beside it.
+ */
+export function settle(d: Decision): Decision {
+  const t = d.target
+  if (!t || d.mode === "new" || d.mode === "update") return { ...d, ask: false }
+  if (d.mode === "reuse") return { ...d, ask: false, why: d.ask ? `${d.why}; with no one to ask, the one covering the most is reused` : d.why }
+  if (t.lines && t.lines > MAX_EXTEND_LINES) return { ...d, mode: "sibling", ask: false, why: `${d.why}; ${t.test} is already ${t.lines} lines, so the new steps go in a test beside it` }
+  if (d.ask && t.share < EXTEND_ALONE_FROM) return { ...d, mode: "sibling", ask: false, why: `${d.why}; with no one to ask and ${t.test} covering ${Math.round(t.share * 100)}%, a test beside it rather than a longer one` }
+  return { ...d, ask: false, why: d.ask ? `${d.why}; with no one to ask, the one covering the most (${Math.round(t.share * 100)}%) is extended` : d.why }
+}
+
 /** The evidence as card lines: each close test, what it covers, and what it lacks. */
 export function coverageLines(c: Coverage, max = 3): string[] {
   const n = c.items.filter((i) => i.members.length).length

package/src/code/decisions.ts

@@ -0,0 +1,73 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { logEvent } from "../sessionLog.ts"
+import { projectDir } from "../tools.ts"
+
+/**
+ * Every decision about existing tests, kept so it can be read back: which tests were shown before a browser run, who
+ * chose what (ForgeQE's agent, the user, ForgeQE's policy, the coverage measure, or a test an earlier job wrote for the
+ * same flow), why, and how it ended. One JSON line each in .forgeqe/decisions.jsonl in the repository (commit it, or
+ * keep it between CI runs, like test-history.json), and in the session log. What a later job learns from comes from here.
+ */
+
+export const DECISIONS_FILE = "decisions.jsonl"
+/** Past this size the oldest half is dropped. */
+const MAX_BYTES = 2_000_000
+
+export type Shown = { test?: string; file: string; score?: number; covers?: string[]; lacks?: string[] }
+
+export type DecisionRecord = {
+  at: string
+  goal: string
+  /** shown: tests offered before the browser; chosen: what was picked; outcome: how it ended. */
+  stage: "shown" | "chosen" | "outcome"
+  /** Where it was decided: before the browser run, or in write_test after it. */
+  where: "browser_run" | "write_test"
+  by?: "agent" | "user" | "policy" | "coverage" | "history"
+  mode?: "reuse" | "extend" | "sibling" | "update" | "new" | "fresh"
+  test?: string
+  file?: string
+  why?: string
+  shown?: Shown[]
+  status?: string
+  existing?: string
+  run_dir?: string
+  /** Times Scribe changed the existing test it was asked to keep, and was sent back. */
+  breaches?: number
+}
+
+export const decisionsFile = (repo: string) => path.join(projectDir(repo), DECISIONS_FILE)
+
+export function recordDecision(repo: string, rec: Omit<DecisionRecord, "at">): void {
+  const full: DecisionRecord = { at: new Date().toISOString(), ...rec }
+  logEvent("decision", full)
+  const file = decisionsFile(repo)
+  try {
+    mkdirSync(path.dirname(file), { recursive: true })
+    appendFileSync(file, `${JSON.stringify(full)}\n`)
+    if (statSync(file).size > MAX_BYTES) {
+      const lines = readFileSync(file, "utf8").trim().split("\n")
+      writeFileSync(file, `${lines.slice(Math.floor(lines.length / 2)).join("\n")}\n`)
+    }
+  } catch {
+    // The record is for later jobs; a repository ForgeQE cannot write to still gets its test.
+  }
+}
+
+export function readDecisions(repo: string): DecisionRecord[] {
+  try {
+    return readFileSync(decisionsFile(repo), "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l) as DecisionRecord]
+        } catch {
+          return []
+        }
+      })
+  } catch {
+    return []
+  }
+}

package/src/code/find.ts

@@ -382,6 +382,8 @@ export async function runSelection(opts: {
   hide?: string[]
   /** Retries and quarantine; default: one retry, quarantine suggested. */
   flaky?: FlakyConfig
+  /** Extra variables for the tests, such as a remote browser's endpoint. */
+  env?: Record<string, string>
 }): Promise<TestsRun> {
   const sel = opts.selection
   const flakyCfg = opts.flaky || { retries: 1, quarantine: "suggest", flakyAfter: 2 }
@@ -389,7 +391,7 @@ export async function runSelection(opts: {
   mkdirSync(sel.dir, { recursive: true })
   for (const p of sel.results) if (p.startsWith(sel.dir) && existsSync(p) && statSync(p).isFile()) rmSync(p)
   const started = Date.now()
-  const exec = (command: string) => (opts.runTest || runTestCommand)({ command, cwd: sel.repo, timeoutSeconds: opts.timeoutSeconds, signal: opts.signal, hide: opts.hide })
+  const exec = (command: string) => (opts.runTest || runTestCommand)({ command, cwd: sel.repo, timeoutSeconds: opts.timeoutSeconds, signal: opts.signal, hide: opts.hide, ...(opts.env ? { env: opts.env } : {}) })
   const read = (since: number) => {
     const out: TestOutcome[] = []
     for (const f of resultFiles(sel.results, since)) {

package/src/code/graph/graph.ts

@@ -86,8 +86,15 @@ export async function buildGraph(repo: string, opts: { cacheDir?: string } = {})
 /** A member (or top-level function or test) with where it is. */
 export type Located = { file: string; cls?: ClassFacts; member: Member }
 
+const membersOf = new WeakMap<CodeGraph, Located[]>()
+
+/** Every member of the graph; worked out once per graph, which does not change once built. */
 export function allMembers(g: CodeGraph): Located[] {
-  return g.files.flatMap((f) => [...f.classes.flatMap((cls) => cls.members.map((member) => ({ file: f.file, cls, member }))), ...f.functions.map((member) => ({ file: f.file, member }))])
+  const known = membersOf.get(g)
+  if (known) return known
+  const all = g.files.flatMap((f) => [...f.classes.flatMap((cls) => cls.members.map((member) => ({ file: f.file, cls, member }))), ...f.functions.map((member) => ({ file: f.file, member }))])
+  membersOf.set(g, all)
+  return all
 }
 
 export const qualified = (l: Located) => (l.cls ? `${l.cls.name}.${l.member.name}` : l.member.name)
@@ -314,8 +321,21 @@ export function describeMatches(g: CodeGraph, matches: ElementMatch[], max = 3):
 // References
 
 /** The class a receiver names: from the file's declarations, then any file's, then by name (articlePage → WikipediaArticlePage). */
+const receivers = new WeakMap<CodeGraph, Map<string, string | null>>()
+
 function receiverClass(g: CodeGraph, file: FileFacts, receiver: string, classes: Set<string>): string | null {
   if (!receiver) return null
+  // The graph does not change once built: each file's receiver resolves the same way every time it is asked.
+  let cache = receivers.get(g)
+  if (!cache) receivers.set(g, (cache = new Map()))
+  const key = `${file.file}\u0000${receiver}\u0000${classes.size}`
+  if (cache.has(key)) return cache.get(key)!
+  const found = resolveReceiver(g, file, receiver, classes)
+  cache.set(key, found)
+  return found
+}
+
+function resolveReceiver(g: CodeGraph, file: FileFacts, receiver: string, classes: Set<string>): string | null {
   const last = receiver.split(".").pop() || receiver
   if (classes.has(last)) return last
   const bound = file.bindings[receiver] || file.bindings[last]
@@ -331,13 +351,24 @@ function receiverClass(g: CodeGraph, file: FileFacts, receiver: string, classes:
 }
 
 /** The class and its base classes, nearest first. */
+const lineages = new WeakMap<CodeGraph, { byName: Map<string, ClassFacts>; memo: Map<string, string[]> }>()
+
 function lineage(g: CodeGraph, name: string): string[] {
+  let c = lineages.get(g)
+  if (!c) {
+    const byName = new Map<string, ClassFacts>()
+    for (const f of g.files) for (const cls of f.classes) if (!byName.has(cls.name)) byName.set(cls.name, cls)
+    lineages.set(g, (c = { byName, memo: new Map() }))
+  }
+  const known = c.memo.get(name)
+  if (known) return known
   const out: string[] = []
   let cur: string | undefined = name
   while (cur && !out.includes(cur)) {
     out.push(cur)
-    cur = g.files.flatMap((f) => f.classes).find((c) => c.name === cur)?.bases[0]
+    cur = c.byName.get(cur)?.bases[0]
   }
+  c.memo.set(name, out)
   return out
 }
 

package/src/code/handoff.ts

@@ -43,6 +43,16 @@ export type Step = {
   scripted?: boolean
   /** click: the control sat in an overlay (cookie banner, sign-in prompt, dialog) that this click dismissed. */
   overlay?: { kind?: string; name?: string; id?: string }
+  /** api: an HTTP call made in the browser's session, and what the server answered when the run made it. */
+  method?: string
+  body?: string
+  content_type?: string
+  /** api: where the CSRF token came from: the "cookie", or the page's "form". */
+  csrf?: string
+  status?: number
+  final_url?: string
+  redirected?: boolean
+  snippet?: string
 }
 
 /** An element the engine found on the live page, with its locators (verified ones first). */
@@ -174,6 +184,10 @@ function stepLines(step: Step, n: number): string[] {
       break
     case "press":
       return [`${n}. press ${step.keys}`]
+    case "api":
+      return [
+        `${n}. API ${step.method || "GET"} ${step.url}${step.body ? ` with ${step.content_type?.includes("json") ? "JSON" : "form"} body ${quote(step.body.slice(0, 300))}` : ""}${step.csrf ? `, CSRF token from the ${step.csrf === "form" ? "page's form" : "csrftoken cookie"}` : ""}: the server answered ${step.status ?? "?"}${step.redirected && step.final_url ? `, ending at ${step.final_url}` : ""}${step.snippet ? `; response starts: ${quote(step.snippet.slice(0, 160))}` : ""}`,
+      ]
     case "evaluate":
       return step.scripted
         ? [
@@ -558,6 +572,12 @@ export function buildHandoff(runDir: string, memoryDir?: string, opts: { replay?
       "",
     )
   }
+  if (steps.some((s) => s.op === "api")) {
+    md.push(
+      "Steps marked API are HTTP calls the run made in the browser's own session (its cookies went with each call, so a login and a cart carry over between the API and the UI steps). Make each one in the test the same way: through the framework's API request context that shares the browser's cookies (Playwright: page.request in TypeScript, Page.APIRequest in .NET, page.request in Python and Java), with the same method, URL, and body, reading the CSRF token where the step says (the page's form, or the csrftoken cookie) and sending it as the site expects. Assert the status the run got. Do not replace an API step with clicks, or a UI step with an API call.",
+      "",
+    )
+  }
   const slices = stepSlices(steps, opts.replay)
   if (slices.size) {
     md.push(

package/src/code/loop.ts

@@ -10,6 +10,7 @@ import type { TestCase } from "../cases/types.ts"
 import { buildProfile, profileSection } from "./profile.ts"
 import { LIVE_BROWSER_SERVER, liveBrowser } from "./livebrowser.ts"
 import { additionFacts, buildGraph, classesUsedBy, outlines, type CodeGraph } from "./graph/graph.ts"
+import { breachPrompt, checkOriginal, readOriginal } from "./protect.ts"
 import { CODE_GRAPH_SERVER, codeGraphTools } from "./graph/tools.ts"
 import { localToolServer } from "../mcp/server.ts"
 import type { ToolContext } from "../mcp/tools.ts"
@@ -19,6 +20,7 @@ import { openSession, READ_AGENT, TEST_AGENT, type OpencodeSession, type PromptO
 import { failureContext } from "./slices.ts"
 import { moveToAttention } from "./attention.ts"
 import { recordMapping } from "./traceability.ts"
+import { stepsHash } from "../cases/types.ts"
 import {
   blockedChallengePrompt,
   carryOnPrompt,
@@ -167,6 +169,8 @@ export async function runCodeAgent(opts: {
   // locates it, Scribe gets code_* tools instead of reading whole files, and the reviewer gets what the job duplicated.
   const built = config.code.graph === false ? null : await buildGraph(repo).catch(() => null)
   const graph: CodeGraph | null = built?.files.length ? built : null
+  // The existing test the job works from, as it is now: what Scribe may do to it is checked before each test run.
+  const original = opts.target ? await readOriginal(repo, opts.target) : null
   let handoff = buildHandoff(opts.runDir, config.memory.dir, { knownDefect: opts.knownDefect, graph })
   if (!handoff.success && !opts.knownDefect) throw new Error("The coding agent only takes runs that passed. This run failed.")
   const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? "" : "s"}`
@@ -496,6 +500,17 @@ export async function runCodeAgent(opts: {
       result.reused = report.reused || []
       result.changed = report.changed || []
 
+      if (original && opts.target) {
+        const breach = await checkOriginal(repo, original, opts.target.mode)
+        if (breach) {
+          result.breaches = (result.breaches || 0) + 1
+          emit({ type: "code", kind: "test", ok: false, attempt, text: `${breach.why}: not run; Scribe puts it back (attempt ${attempt}/${allowed})` })
+          attemptLog.push(attemptLine(attempt, "changed the existing test it was asked to keep", breach.lines.slice(0, 3).join(" | "), report.notes))
+          nextTask = breachPrompt(original, breach, opts.target.mode)
+          next = { why: breach.why, fixing: [opts.target.mode === "extend" ? "Put back the existing test's lines exactly; add only the new steps" : "Leave the existing test as it was"] }
+          continue
+        }
+      }
       emit({ type: "code", kind: "info", text: `ForgeQE runs the test: ${report.command}` })
       const run = await runTest({
         command: report.command,
@@ -571,7 +586,7 @@ export async function runCodeAgent(opts: {
           result.status = "passed"
           // What it did with the existing test it was given, for the result card and the agent.
           if (opts.existingTest) result.existing = "updated"
-          else if (opts.target) result.existing = opts.target.mode === "reuse" ? "reused" : opts.target.mode === "update" ? "updated" : "extended"
+          else if (opts.target) result.existing = opts.target.mode === "reuse" ? "reused" : opts.target.mode === "update" ? "updated" : opts.target.mode === "sibling" ? "added_beside" : "extended"
           if (standards.length) {
             result.review = { ...verdict.review, approved: true, standardsLeft: true }
             result.notes = `The test passes and tests the goal. Coding standards still to fix: ${standards.map((i) => `${i.file ? `${i.file}: ` : ""}${i.problem}`).join(" ")}`
@@ -605,6 +620,16 @@ export async function runCodeAgent(opts: {
         break
       }
       const why = run.exitCode === null ? `timed out after ${config.code.testTimeoutSeconds}s` : `exit ${run.exitCode}`
+      // ForgeQE's own replay of the run could not get through the flow either: no script reproduces it as recorded,
+      // so more attempts only spend tokens. Stop with what the replay met, for the user to act on.
+      const unreproducible = replay && !replay.error && replay.passes.length > 0 && replay.passes.every((p) => !p.reached)
+      if (unreproducible) {
+        const stuck = replay!.passes[0]!.steps.find((st) => !st.ok && !st.skipped)
+        const reason = failureReason(run.output)[0] || why
+        result.notes = `Stopped after attempt ${attempt}: the test failed (${reason}), and ForgeQE's replay of the run could not reach its final page either${stuck ? ` (step ${stuck.n}, ${stuck.action}: ${String(stuck.error || "").split("\n")[0]!.slice(0, 200)})` : ""}. The flow as recorded cannot be repeated by a script: usually a step the run did in a way a test cannot (a script in the page, state left from an earlier run, a pop-up only the agent dismissed). Run the case again after fixing that step, or check the handoff's replay section.`
+        emit({ type: "code", kind: "test", ok: false, attempt, text: `stopped: the flow cannot be reproduced; ForgeQE's replay stopped at ${stuck ? `step ${stuck.n}` : "a step"} as well (attempt ${attempt}/${maxAttempts})` })
+        break
+      }
       const mismatch = browserMismatch(runBrowser, run.browsers, report.command)
       if (mismatch) emit({ type: "code", kind: "info", text: `The test's browser differs from the run's: ${run.browsers.join(", ")}` })
       const key = failureKey(run.output)
@@ -642,6 +667,7 @@ export async function runCodeAgent(opts: {
         ...(result.testName ? { testName: result.testName } : {}),
         ...(result.command ? { command: result.command } : {}),
         ...(opts.knownDefect?.bug ? { bug: opts.knownDefect.bug } : {}),
+        ...(tc.steps?.length ? { stepsHash: stepsHash(tc.steps) } : {}),
       })
     }
     // An unfinished job (not one that can be resumed) leaves no failing test among the tests: it goes to needs-attention.

package/src/code/notes.ts

@@ -98,7 +98,8 @@ function goalWords(goal: string): Set<string> {
 
 /** The website a goal names, if any: the same steps on another site are another flow. */
 function goalHost(goal: string): string {
-  return /https?:\/\/(?:www\.)?([^/\s,)]+)/i.exec(goal)?.[1]?.toLowerCase() || ""
+  // A URL ending a sentence ("Open https://shop.test.") keeps its host without the full stop.
+  return (/https?:\/\/(?:www\.)?([^/\s,)]+)/i.exec(goal)?.[1]?.toLowerCase() || "").replace(/[.:;!?]+$/, "")
 }
 
 /**
@@ -147,5 +148,51 @@ export function findWrittenTest(memoryDir: string, repo: string, goal: string, e
   return best?.test || null
 }
 
+/**
+ * Goals at least this alike may be the same journey, or one a request extends. ForgeQE's agent rewrites the user's
+ * request each time, so the same request scores as low as 0.34 against an earlier wording, while unrelated flows
+ * measured on real goals stay under 0.21. Too loose to decide on its own: ForgeQE's agent compares the goals.
+ */
+export const RELATED_GOAL = 0.25
+/** And they share at least this many content words: two short goals on one site share a word or two by chance. */
+const RELATED_WORDS = 3
+
+function sharedWords(a: string, b: string): number {
+  const y = goalWords(b)
+  let n = 0
+  for (const w of goalWords(a)) if (y.has(w)) n++
+  return n
+}
+
+/**
+ * Earlier tests in this repository whose goals are close to `goal` without being the same flow: candidates to reuse or
+ * extend before the browser explores anything. One per test file, the closest first.
+ */
+export function findRelatedTests(memoryDir: string, repo: string, goal: string, exists: (file: string) => boolean, max = 3): (WrittenTest & { similarity: number })[] {
+  const best = new Map<string, WrittenTest & { similarity: number }>()
+  for (const t of load(memoryDir).repos[repo]?.tests || []) {
+    const similarity = goalSimilarity(t.goal, goal)
+    if (similarity < RELATED_GOAL || sharedWords(t.goal, goal) < RELATED_WORDS || !exists(t.test_file)) continue
+    const had = best.get(t.test_file)
+    if (!had || similarity > had.similarity || (similarity === had.similarity && t.at > had.at)) best.set(t.test_file, { ...t, similarity })
+  }
+  return [...best.values()].sort((a, b) => b.similarity - a.similarity || b.at.localeCompare(a.at)).slice(0, max)
+}
+
+/** Every test earlier jobs wrote in this repository, of any age: their commands show how it runs one test. */
+export function writtenTests(memoryDir: string, repo: string): WrittenTest[] {
+  return load(memoryDir).repos[repo]?.tests || []
+}
+
+/** The earlier test written in this repository to this file (the newest), for a test ForgeQE's agent names. */
+export function writtenTestFor(memoryDir: string, repo: string, testFile: string): WrittenTest | null {
+  const file = testFile.replace(/^\.\//, "")
+  const tests = (load(memoryDir).repos[repo]?.tests || []).filter((t) => t.test_file === file)
+  return tests.sort((a, b) => b.at.localeCompare(a.at))[0] || null
+}
+
 /** Where browser_run leaves the earlier test for a goal that failed, so write_test updates it instead of adding one. */
 export const EXISTING_TEST_FILE = "existing-test.json"
+
+/** Where browser_run leaves the earlier test ForgeQE's agent chose to extend, so write_test extends it. */
+export const EXTEND_TEST_FILE = "extend-test.json"

package/src/code/prompt.ts

@@ -78,7 +78,7 @@ export type ExistingTest = { testFile: string; command: string; output: string;
  * An existing test the job works from, chosen from measured coverage (or by the person): `reuse` it as it is, or
  * `extend` it with only the steps and checks it lacks.
  */
-export type TestTarget = { mode: "reuse" | "extend" | "update"; testFile: string; test: string; line: number; covered: string[]; missing: string[]; why: string }
+export type TestTarget = { mode: "reuse" | "extend" | "update" | "sibling"; testFile: string; test: string; line: number; covered: string[]; missing: string[]; why: string }
 
 function targetSection(t: TestTarget): string[] {
   const list = (items: string[]) => items.map((i) => `- ${i}`)
@@ -91,6 +91,18 @@ function targetSection(t: TestTarget): string[] {
       "",
     ]
   }
+  if (t.mode === "sibling") {
+    return [
+      "## Add a test beside the existing one, do not change it",
+      "",
+      `${t.test} (${t.testFile}:${t.line}) covers the start of this journey (${t.why}). Add one new test method next to it, in the same class, for the flow below: reuse its setup, its helpers, and the page-object methods it calls for the steps the two share, and add only what the flow adds. Leave ${t.test} as it is. Do not create a new test file.`,
+      ...(t.covered.length ? ["", "The steps it already has, to reuse through the same methods:", ...t.covered.map((i) => `- ${i}`)] : []),
+      ...(t.missing.length ? ["", "What the new test adds:", ...t.missing.map((i) => `- ${i}`)] : []),
+      "",
+      "Add page-object members for elements the repository does not locate yet. Do not change what an existing member or method does: other tests use it (code_references shows which).",
+      "",
+    ]
+  }
   if (t.mode === "reuse") {
     return [
       "## The existing test that already covers this flow",
@@ -100,16 +112,24 @@ function targetSection(t: TestTarget): string[] {
       "",
     ]
   }
+  const measured = t.covered.length
+    ? [
+        `ForgeQE's code graph found that ${t.test} (${t.testFile}:${t.line}) already covers most of this flow (${t.why}). Extend that test: add only what it lacks, in the order of the flow, through the same page objects and helpers. Keep every step and assertion it has. Do not create a new test file.`,
+        "",
+        "It already covers:",
+        ...list(t.covered),
+        "",
+        "Add only these:",
+        ...list(t.missing),
+      ]
+    : [
+        `${t.testFile} was chosen to extend (${t.why}): it covers the start of this journey. ForgeQE's code graph could not tell which of the run's steps it already does, so read it, keep every step and assertion it has, and add only the steps and checks of the run it lacks, in the order of the flow, through the same page objects and helpers. Do not create a new test file.`,
+        ...(t.missing.length ? ["", "The run's steps and checks:", ...list(t.missing)] : []),
+      ]
   return [
     "## Extend the existing test, do not write a new one",
     "",
-    `ForgeQE's code graph found that ${t.test} (${t.testFile}:${t.line}) already covers most of this flow (${t.why}). Extend that test: add only what it lacks, in the order of the flow, through the same page objects and helpers. Keep every step and assertion it has. Do not create a new test file.`,
-    "",
-    "It already covers:",
-    ...list(t.covered),
-    "",
-    "Add only these:",
-    ...list(t.missing),
+    ...measured,
     "",
     "When the missing steps start from a different place than the test does, add one test method next to it in the same class, reusing its setup and helpers, instead of a new file.",
     "Add page-object members for elements the repository does not locate yet. Do not change what an existing member or method does: other tests use it (code_references shows which). When one must change, keep its behaviour for those tests and say so in notes.",
@@ -142,13 +162,15 @@ export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; l
     : ""
   return [
     opts.existing
-      ? `Update the existing test for the flow below so it passes again. When it is updated, give the structured result; ForgeQE then runs it.`
+      ? `Update the existing test so it does the flow below and passes. When it is updated, give the structured result; ForgeQE then runs it.`
       : opts.target?.mode === "reuse"
         ? `An existing test already covers the flow below. Report how to run it; change nothing. ForgeQE then runs it.`
         : opts.target?.mode === "extend"
           ? `Extend the existing test named below with what the flow below adds. When it is extended, give the structured result; ForgeQE then runs it.`
           : opts.target?.mode === "update"
             ? `Update the existing test named below to match the flow below. When it is updated, give the structured result; ForgeQE then runs it.`
+          : opts.target?.mode === "sibling"
+            ? `Add a test for the flow below next to the existing test named below, in its class, reusing its setup and steps. When it is written, give the structured result; ForgeQE then runs it.`
           : `Write a test in this repository for the flow below, reusing the repository's existing test code. When it is written, give the structured result; ForgeQE then runs it.`,
     "",
     ...(opts.existing ? existingSection(opts.existing) : opts.target ? targetSection(opts.target) : []),

package/src/code/protect.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+
+import { parseFile, type FileFacts, type Member } from "./graph/parse.ts"
+import type { TestTarget } from "./prompt.ts"
+
+/**
+ * What a job may do to the existing test it was given, checked in code rather than left to the prompt: extending keeps
+ * every line the test had, in order, and only adds; a test added beside it, or a test reused, leaves it as it was; and
+ * the test keeps its name. A live run showed why: asked to extend, Scribe changed the test's data values to the run's,
+ * and the reviewer approved it.
+ */
+
+/** The existing test as the job found it: its method name and its lines. */
+export type Original = { file: string; test: string; method: string; lines: string[] }
+
+/** A line that is only punctuation says nothing about what the test does: braces, a lone semicolon, a closing paren. */
+const SAYS_NOTHING = /^[{}()[\];,]*$/
+
+const meaningful = (lines: string[]) => lines.map((l) => l.trim()).filter((l) => l && !SAYS_NOTHING.test(l))
+
+function members(facts: FileFacts | null): { cls?: string; m: Member }[] {
+  if (!facts) return []
+  return [...facts.classes.flatMap((c) => c.members.map((m) => ({ cls: c.name, m }))), ...facts.functions.map((m) => ({ m }))]
+}
+
+/** The test's member in a parsed file: by Class.Method, or by its method name or title alone. */
+function find(facts: FileFacts | null, test: string): Member | null {
+  const method = test.split(".").pop() || test
+  const all = members(facts).filter(({ m }) => m.kind === "test" || m.kind === "method")
+  return all.find(({ cls, m }) => `${cls}.${m.name}` === test)?.m || all.find(({ m }) => m.name === method)?.m || null
+}
+
+async function read(repo: string, file: string): Promise<{ text: string; facts: FileFacts | null } | null> {
+  try {
+    const text = readFileSync(path.join(repo, file), "utf8")
+    return { text, facts: await parseFile(file, text) }
+  } catch {
+    return null
+  }
+}
+
+/** The target test's lines before the job starts; null when the file or the test cannot be read. */
+export async function readOriginal(repo: string, target: Pick<TestTarget, "testFile" | "test">): Promise<Original | null> {
+  const got = await read(repo, target.testFile)
+  const m = got && find(got.facts, target.test)
+  if (!got || !m) return null
+  return { file: target.testFile, test: target.test, method: m.name, lines: got.text.split("\n").slice(m.line - 1, m.endLine) }
+}
+
+/** Lines of `before` missing from `after` when `after` must keep them in order (it may add lines between them). */
+export function droppedLines(before: string[], after: string[]): string[] {
+  const keep = meaningful(before)
+  const now = meaningful(after)
+  const dropped: string[] = []
+  let j = 0
+  for (const line of keep) {
+    const at = now.indexOf(line, j)
+    if (at === -1) dropped.push(line)
+    else j = at + 1
+  }
+  return dropped
+}
+
+export type Breach = { why: string; lines: string[] }
+
+/**
+ * How the job broke what its mode allows on the original test, or null when it did not. extend: no line dropped or
+ * changed; sibling and reuse: the test exactly as it was; every mode: the test still there under its name.
+ */
+export async function checkOriginal(repo: string, original: Original, mode: TestTarget["mode"]): Promise<Breach | null> {
+  if (mode === "update") return null
+  const got = await read(repo, original.file)
+  const m = got && find(got.facts, original.method)
+  if (!got || !m) return { why: `the existing test ${original.test} is no longer in ${original.file} under that name`, lines: [] }
+  const now = got.text.split("\n").slice(m.line - 1, m.endLine)
+  if (mode === "extend") {
+    const dropped = droppedLines(original.lines, now)
+    return dropped.length ? { why: `lines of the existing test ${original.test} were changed or removed; extending keeps every line it had and only adds`, lines: dropped } : null
+  }
+  const changed = meaningful(original.lines).join("\n") !== meaningful(now).join("\n")
+  if (!changed) return null
+  const dropped = droppedLines(original.lines, now)
+  return {
+    why: mode === "sibling" ? `the existing test ${original.test} was changed; a test added beside it leaves it as it was` : `the existing test ${original.test} was changed; reusing it changes nothing`,
+    lines: dropped.length ? dropped : meaningful(now).filter((l) => !meaningful(original.lines).includes(l)),
+  }
+}
+
+/** The task for Scribe's next attempt: put the original test back as the mode requires. */
+export function breachPrompt(original: Original, b: Breach, mode: TestTarget["mode"]): string {
+  return [
+    `ForgeQE checked the existing test and stopped before running it: ${b.why}.`,
+    ...(b.lines.length ? ["", mode === "extend" ? "These lines of it are missing or changed; put them back exactly as they were:" : "The test as it was had these lines:", "", "```", ...b.lines.slice(0, 20), "```"] : []),
+    "",
+    mode === "extend"
+      ? `Keep every step, value, and assertion of ${original.test} as it was, and add only the new steps and checks around them. When a value in the run differs from the test's, keep the test's value: the run's data was an example.`
+      : mode === "sibling"
+        ? `Leave ${original.test} as it was, and put the new flow in a new test method beside it in the same class.`
+        : `Leave ${original.test} as it was.`,
+    "Then give the structured result again.",
+  ].join("\n")
+}

package/src/code/replay.ts

@@ -135,11 +135,31 @@ function describe(step: Step): string {
       return "go back"
     case "evaluate":
       return "run the agent's JavaScript"
+    case "api":
+      return `API ${step.method || "GET"} ${step.url}`
     default:
       return `${step.op || "unknown"}${step.action_keys?.length ? ` (${step.action_keys.join(", ")})` : ""}`
   }
 }
 
+/**
+ * An API step as the engine's api_request makes it (py/forgeqe_engine/api_step.py): fetch in the page with its cookies,
+ * the CSRF token from the cookie or the page's form, sent in headers and, for a form post, in the form.
+ */
+export const API_CALL_JS = `async (a) => {
+  const cookie = (n) => { const c = document.cookie.split('; ').find((x) => x.startsWith(n + '=')); return c ? decodeURIComponent(c.slice(n.length + 1)) : '' };
+  let token = '';
+  if (a.csrf === 'cookie') token = cookie('csrftoken') || cookie('XSRF-TOKEN') || cookie('csrf_token') || cookie('_csrf');
+  if (a.csrf === 'form') { const f = document.querySelector('input[name="csrfmiddlewaretoken"], input[name="_csrf"], input[name="csrf_token"], input[name="authenticity_token"], input[name="__RequestVerificationToken"]'); const m = document.querySelector('meta[name="csrf-token"], meta[name="_csrf"]'); token = (f && f.value) || (m && m.content) || ''; }
+  const headers = {};
+  if (a.contentType) headers['Content-Type'] = a.contentType;
+  let body = a.body || undefined;
+  if (token) { headers['X-CSRFToken'] = token; headers['X-XSRF-TOKEN'] = token; headers['X-CSRF-Token'] = token; if (/x-www-form-urlencoded/i.test(a.contentType || '') && !/(^|&)(csrfmiddlewaretoken|_csrf|authenticity_token)=/.test(body || '')) body = (body ? body + '&' : '') + 'csrfmiddlewaretoken=' + encodeURIComponent(token); }
+  const method = (a.method || 'GET').toUpperCase();
+  try { const r = await fetch(a.url, { method, headers, body: method === 'GET' || method === 'HEAD' ? undefined : body, credentials: 'include', redirect: 'follow' }); return { status: r.status, final_url: r.url }; }
+  catch (e) { return { error: String(e && e.message || e) }; }
+}`
+
 /** The body of one step in the script, or null when it has no Playwright equivalent. */
 function stepCode(step: Step): string | null {
   const loc = step.locators?.map(locatorExpr).find(Boolean) || null
@@ -171,6 +191,19 @@ function stepCode(step: Step): string | null {
       return "(page) => page.goBack()"
     case "evaluate":
       return step.code ? `(page) => page.evaluate(${q(step.code)})` : null
+    case "api": {
+      if (!step.url) return null
+      // The call is made in the page, as the run made it: the session's cookies and its CSRF token go with it. The step
+      // fails when the server answers differently than it did in the run (403 where the run got 200).
+      const args = JSON.stringify({ method: step.method || "GET", url: step.url, body: step.body || "", contentType: step.content_type || "", csrf: step.csrf || "" })
+      return [
+        "async (page) => {",
+        `    const r = await page.evaluate(${API_CALL_JS}, ${args})`,
+        "    if (r.error) throw new Error(`API ${r.error}`)",
+        ...(step.status ? [`    if (r.status !== ${Number(step.status)}) throw new Error(\`API answered \${r.status}, the run got ${Number(step.status)}\`)`] : []),
+        "  }",
+      ].join("\n")
+    }
     default:
       return null
   }

package/src/code/review.ts

@@ -133,6 +133,8 @@ export function reviewPrompt(input: ReviewInput, repo?: string): string {
           "",
           input.target.mode === "extend"
             ? `The job was asked to extend the existing test ${input.target.test} (${input.target.testFile}) with only what it lacked: ${input.target.missing.join("; ")}. Adding those steps and checks to that test is the requested change, not a rewrite. A step or assertion of it removed or weakened, those steps duplicated in a new test file, or a shared page-object member changed in a way its other users would notice, is a correctness issue.`
+            : input.target.mode === "sibling"
+              ? `The job was asked to add a test beside the existing test ${input.target.test} (${input.target.testFile}), in the same class, reusing its setup and the page-object methods for the steps they share. A change to ${input.target.test} itself, a new test file, or the shared steps written again instead of reused, is a correctness issue.`
             : input.target.mode === "update"
               ? `The user asked to update the existing test ${input.target.test} (${input.target.testFile}) to match this run. Changing its steps, locators, or expected values to match the run is the requested change. Removing an assertion the run still supports, or writing a new test file instead, is a correctness issue.`
               : `The job was asked to reuse the existing test ${input.target.test} (${input.target.testFile}) as it is, since it already covers the flow. Any change to it, or a new test, is a correctness issue.`,