@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/code/slices.ts

@@ -0,0 +1,159 @@
+import { readFileSync } from "node:fs"
+
+/**
+ * Small pieces of Playwright aria snapshots (the page as roles and accessible names, one YAML line per element) around
+ * the element a step or a failure is about: its section, its neighbours, and the line itself. Scribe gets these in its
+ * prompt instead of whole snapshots or a live browser, which re-send thousands of lines with every later call.
+ */
+
+/** What a Playwright locator points at, in terms an aria snapshot shows: a role and accessible name, or text. */
+export type AriaTarget = { role?: string; name?: string; text?: string }
+
+const STRING = `['"\`]((?:[^'"\`\\\\]|\\\\.)*)['"\`]`
+
+/** The role and name, or the text, of a Playwright locator; null for CSS, XPath, and test ids, which a snapshot does not show. */
+export function ariaTarget(locator: string): AriaTarget | null {
+  const role = new RegExp(`getByRole\\(\\s*${STRING}(?:\\s*,\\s*\\{([^}]*)\\})?`).exec(locator)
+  if (role) {
+    const opts = role[2] || ""
+    const name = new RegExp(`name:\\s*${STRING}`).exec(opts)?.[1] ?? /name:\s*\/(.*?)\/[a-z]*/.exec(opts)?.[1]
+    return { role: role[1], ...(name ? { name: unescape(name) } : {}) }
+  }
+  const text = new RegExp(`getBy(?:Label|Placeholder|Text|Title|AltText)\\(\\s*${STRING}`).exec(locator)
+  if (text) return { text: unescape(text[1]) }
+  const has = new RegExp(`hasText:\\s*${STRING}`).exec(locator)
+  if (has) return { text: unescape(has[1]) }
+  return null
+}
+
+const unescape = (s: string) => s.replace(/\\(.)/g, "$1")
+const norm = (s: string) => s.replace(/\s+/g, " ").trim().toLowerCase()
+const indentOf = (line: string) => line.length - line.trimStart().length
+
+/** The quoted name on an aria line (`- button "Search"`), or its text (`- text: Search`). */
+function lineName(line: string): string {
+  const t = line.trim()
+  return /^- [\w-]+ "((?:[^"\\]|\\.)*)"/.exec(t)?.[1] ?? /^- [\w-]+: (.+)$/.exec(t)?.[1] ?? ""
+}
+
+/** The line the target is on: exact name first, then a name that contains it. -1 when the page does not show it. */
+export function findLine(lines: string[], target: AriaTarget): number {
+  const want = norm(target.name ?? target.text ?? "")
+  const roleOk = (l: string) => !target.role || l.trim().startsWith(`- ${target.role}`)
+  const candidates = lines.map((l, i) => ({ l, i })).filter(({ l }) => l.trim().startsWith("-") && roleOk(l))
+  if (!want) return candidates[0]?.i ?? -1
+  const exact = candidates.find(({ l }) => norm(lineName(l)) === want)
+  if (exact) return exact.i
+  const within = candidates.find(({ l }) => norm(lineName(l)).includes(want))
+  if (within) return within.i
+  // Text locators also match a label's text inside a longer line.
+  if (!target.role) return lines.findIndex((l) => norm(l).includes(want))
+  return -1
+}
+
+/** The line that shares the most words with the target's name: where to look when the element itself is gone. */
+function closestLine(lines: string[], target: AriaTarget): number {
+  const words = norm(target.name ?? target.text ?? "").split(" ").filter((w) => w.length >= 4)
+  if (!words.length) return -1
+  let best = -1
+  let score = 0
+  lines.forEach((l, i) => {
+    const n = norm(l)
+    const s = words.filter((w) => n.includes(w)).length
+    if (s > score) {
+      score = s
+      best = i
+    }
+  })
+  return best
+}
+
+/**
+ * The element's section of the snapshot: from its grandparent (or parent) down, at most `max` lines, kept around the
+ * element, with the element's line marked. Long lines are shortened.
+ */
+export function sliceAround(lines: string[], at: number, mark: string, max = 18): string[] {
+  let top = at
+  for (let level = 0; level < 2; level++) {
+    const want = indentOf(lines[top])
+    let j = top - 1
+    while (j >= 0 && indentOf(lines[j]) >= want) j--
+    if (j < 0) break
+    top = j
+  }
+  let end = top + 1
+  while (end < lines.length && indentOf(lines[end]) > indentOf(lines[top])) end++
+  let from = top
+  let to = end
+  if (to - from > max) {
+    from = Math.max(top, at - Math.floor(max / 2))
+    to = Math.min(end, from + max)
+    from = Math.max(top, to - max)
+  }
+  const clip = (l: string) => (l.length > 160 ? `${l.slice(0, 159)}…` : l)
+  const out = lines.slice(from, to).map((l, k) => (from + k === at ? `${clip(l)}  # ← ${mark}` : clip(l)))
+  const base = Math.min(...out.map(indentOf))
+  const shifted = out.map((l) => l.slice(base))
+  if (from > top) shifted.unshift(`${" ".repeat(Math.max(0, indentOf(lines[top]) - base))}${clip(lines[top].trim())}`, "…")
+  if (to < end) shifted.push("…")
+  return shifted
+}
+
+/** The slice for a locator on one snapshot, or null when the snapshot does not show what it points at. */
+export function sliceFor(snapshot: string, locator: string, mark: string, max?: number): string[] | null {
+  const target = ariaTarget(locator)
+  if (!target) return null
+  const lines = snapshot.split("\n")
+  const at = findLine(lines, target)
+  return at < 0 ? null : sliceAround(lines, at, mark, max)
+}
+
+/** The locator a Playwright failure names: "waiting for getByRole(…)" or "Locator: getByText(…)". */
+export function failingLocator(output: string): string | null {
+  const m = /(?:waiting for|Locator:)\s+((?:page\.)?(?:getBy\w+|locator)\(.+?\))(?:\s+to\b|\s*$)/m.exec(output)
+  return m ? m[1] : null
+}
+
+function read(file?: string): string {
+  if (!file) return ""
+  try {
+    return readFileSync(file, "utf8")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * For a failed test run: the element the failure names, on the test's page at the failure and on the page ForgeQE's
+ * replay of the run saw. Usually enough to fix a locator, a wait, or an overlay without opening a browser.
+ */
+export function failureContext(output: string, testSnapshot: string | undefined, runSnapshots: string[]): string[] {
+  const locator = failingLocator(output)
+  if (!locator) return []
+  const target = ariaTarget(locator)
+  if (!target) return [`The failing locator: ${locator}. It is not a role, label, or text locator, so the page snapshots cannot show it; use one of the step's role or text locators from the handoff.`]
+  const yaml = (lines: string[]) => ["```yaml", ...lines, "```"]
+  const out = [`The failing locator: ${locator}`]
+  const test = read(testSnapshot).split("\n")
+  if (test.length > 1) {
+    const at = findLine(test, target)
+    if (at >= 0) out.push(`Your test's page at the failure shows it:`, ...yaml(sliceAround(test, at, "the failing locator")))
+    else {
+      const near = closestLine(test, target)
+      out.push(
+        near >= 0
+          ? "Your test's page at the failure does not show it. The closest part of that page:"
+          : "Your test's page at the failure does not show it, or anything with its words: the test is on another page, or something covers it.",
+        ...(near >= 0 ? yaml(sliceAround(test, near, "closest match")) : []),
+      )
+    }
+  }
+  for (const file of runSnapshots) {
+    const run = read(file).split("\n")
+    const at = findLine(run, target)
+    if (at < 0) continue
+    out.push("The same element on ForgeQE's replay of the run:", ...yaml(sliceAround(run, at, "the element")))
+    break
+  }
+  return out
+}

package/src/code/testrun.ts

@@ -0,0 +1,187 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { withoutNames } from "../childEnv.ts"
+import { redactSecrets, sessionLoginEnv } from "../sessionLogins.ts"
+
+const HEAD_CHARS = 8_000
+const TAIL_CHARS = 4_000
+
+/**
+ * `browsers`: automation-controlled browsers that ran under the command, e.g. "Google Chrome (headless)".
+ * `output` is short enough for a prompt with the failure message kept; `log` and `pageSnapshot` hold what it left out.
+ */
+export type TestRun = { ok: boolean; exitCode: number | null; output: string; ms: number; browsers: string[]; log?: string; pageSnapshot?: string }
+
+type Proc = { pid: number; ppid: number; args: string }
+
+/** Switches Playwright, Puppeteer, Selenium, Cypress, and WebDriver BiDi put on the browsers they launch. */
+const AUTOMATION_SWITCHES = ["--remote-debugging-pipe", "--remote-debugging-port", "-juggler-pipe", "--inspector-pipe", "-marionette", "--marionette"]
+
+/**
+ * Playwright puts the whole page's accessibility tree into a failed assertion's message ("Aria snapshot:" and a YAML
+ * list, often thousands of lines), between the error and the stack trace. Each one is taken out and returned apart.
+ */
+export function withoutPageDumps(text: string): { text: string; dumps: string[] } {
+  const lines = text.split("\n")
+  const out: string[] = []
+  const dumps: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*Aria snapshot:\s*$/.test(lines[i])) {
+      out.push(lines[i])
+      continue
+    }
+    let j = i + 1
+    while (j < lines.length && /^\s*- /.test(lines[j])) j++
+    if (j === i + 1) {
+      out.push(lines[i])
+      continue
+    }
+    dumps.push(lines.slice(i + 1, j).join("\n"))
+    out.push(`${lines[i].replace(/:\s*$/, "")}: ${j - i - 1} lines of the page, left out here {{snapshot}}`)
+    i = j - 1
+  }
+  return { text: out.join("\n"), dumps }
+}
+
+/** The start (where test runners put the first failure) and the end (the summary) of a long output. */
+export function headAndTail(text: string, note = ""): string {
+  if (text.length <= HEAD_CHARS + TAIL_CHARS) return text
+  const head = text.slice(0, HEAD_CHARS)
+  const tail = text.slice(-TAIL_CHARS)
+  const cut = text.slice(HEAD_CHARS, -TAIL_CHARS).split("\n").length
+  return `${head}\n… ${cut} lines left out${note ? ` (${note})` : ""} …\n${tail}`
+}
+
+/** A test run's output for a prompt: page dumps out, then its start and end; the full text goes to `save`.log. */
+export function promptOutput(full: string, save?: string): { output: string; log?: string; pageSnapshot?: string } {
+  const { text, dumps } = withoutPageDumps(full)
+  let log: string | undefined
+  let pageSnapshot: string | undefined
+  if (save) {
+    try {
+      mkdirSync(path.dirname(save), { recursive: true })
+      log = `${save}.log`
+      writeFileSync(log, full)
+      if (dumps.length) {
+        pageSnapshot = `${save}-page.aria.yml`
+        writeFileSync(pageSnapshot, dumps[0])
+      }
+    } catch {
+      log = pageSnapshot = undefined
+    }
+  }
+  const where = pageSnapshot ? `(saved in ${pageSnapshot})` : ""
+  const output = headAndTail(text.replaceAll(" {{snapshot}}", where ? ` ${where}` : ""), log ? `full output in ${log}` : "")
+  return { output, ...(log ? { log } : {}), ...(pageSnapshot ? { pageSnapshot } : {}) }
+}
+
+async function processTable(): Promise<Proc[]> {
+  const windows = process.platform === "win32"
+  const argv = windows
+    ? [
+        "powershell.exe",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.CommandLine)" }',
+      ]
+    : ["ps", "-A", "-o", "pid=,ppid=,args="]
+  try {
+    const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "pipe", stderr: "ignore" })
+    const text = await new Response(proc.stdout).text()
+    await proc.exited
+    return text.split(/\r?\n/).flatMap((line) => {
+      const m = /^\s*(\d+)\s+(\d+)\s?(.*)$/.exec(line)
+      return m ? [{ pid: Number(m[1]), ppid: Number(m[2]), args: m[3] || "" }] : []
+    })
+  } catch {
+    return []
+  }
+}
+
+/** "Google Chrome (headless)" for an automation-launched browser's main process, else null. */
+export function automatedBrowser(args: string): string | null {
+  if (/\s--type=/.test(args) || !AUTOMATION_SWITCHES.some((s) => args.includes(` ${s}`))) return null
+  const exe = args.split(/\s-{1,2}[a-z]/i)[0].trim().replace(/^"|"$/g, "")
+  const name = path.basename(exe.replace(/\\/g, "/")).replace(/\.exe$/i, "") || "browser"
+  return /\s--headless(=|\s|$)|\s-headless(\s|$)/.test(args) ? `${name} (headless)` : name
+}
+
+/** Browsers launched for automation at or below `root` in the process tree right now; a shell may exec into its command. */
+async function browsersUnder(root: number): Promise<string[]> {
+  const table = await processTable()
+  const children = new Map<number, Proc[]>()
+  for (const p of table) children.set(p.ppid, [...(children.get(p.ppid) || []), p])
+  const found: string[] = []
+  const queue = table.filter((p) => p.pid === root)
+  const seen = new Set<number>()
+  while (queue.length) {
+    const p = queue.shift()!
+    if (seen.has(p.pid)) continue
+    seen.add(p.pid)
+    const browser = automatedBrowser(p.args)
+    if (browser) found.push(browser)
+    queue.push(...(children.get(p.pid) || []))
+  }
+  return found
+}
+
+/**
+ * Run the agent's test command from the repo root, non-interactively. The output keeps the failure message and the
+ * summary (see promptOutput); with `save`, the full output is kept in `save`.log.
+ * While it runs, the process tree is sampled for browsers the test launched: a passing exit code alone
+ * does not show the test drove a browser.
+ */
+export async function runTestCommand(opts: {
+  command: string
+  cwd: string
+  timeoutSeconds: number
+  signal?: AbortSignal
+  /** Path without extension for the full output and the first page dump, e.g. <run>/tests/attempt-1. */
+  save?: string
+  /** Variables the test must not see: ForgeQE's own secrets (privateEnvNames). */
+  hide?: string[]
+}): Promise<TestRun> {
+  const started = Date.now()
+  const windows = process.platform === "win32"
+  const argv = windows ? ["cmd.exe", "/d", "/s", "/c", `"${opts.command}"`] : ["sh", "-c", opts.command]
+  const proc = Bun.spawn(argv, {
+    cwd: opts.cwd,
+    windowsVerbatimArguments: windows,
+    env: { ...withoutNames(process.env, opts.hide || []), ...sessionLoginEnv(), CI: process.env.CI || "1", PLAYWRIGHT_HTML_OPEN: "never", FORCE_COLOR: "0", NO_COLOR: "1" },
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  let timedOut = false
+  const kill = () => {
+    try {
+      proc.kill("SIGTERM")
+    } catch {}
+  }
+  const timer = setTimeout(() => {
+    timedOut = true
+    kill()
+  }, opts.timeoutSeconds * 1000)
+  opts.signal?.addEventListener("abort", kill, { once: true })
+
+  const browsers = new Set<string>()
+  let running = true
+  const sampling = (async () => {
+    const every = windows ? 1500 : 250
+    while (running) {
+      for (const b of await browsersUnder(proc.pid)) browsers.add(b)
+      if (running) await Bun.sleep(every)
+    }
+  })()
+
+  const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited])
+  running = false
+  await sampling
+  clearTimeout(timer)
+  opts.signal?.removeEventListener("abort", kill)
+  const full = redactSecrets([out, err].filter((s) => s.trim()).join("\n").replace(/\x1b\[[0-9;]*m/g, ""))
+  const ok = !timedOut && code === 0
+  return { ok, exitCode: timedOut ? null : code, ...promptOutput(full, ok ? undefined : opts.save), ms: Date.now() - started, browsers: [...browsers] }
+}

package/src/code/traceability.ts

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { projectDir } from "../tools.ts"
+
+import { adoSettings } from "../cases/ado.ts"
+import { http } from "../cases/http.ts"
+import type { TestCase, WriteBack } from "../cases/types.ts"
+import type { SourcesConfig } from "../config.ts"
+
+/**
+ * Which automated test belongs to which manual test case. Every coding job for a test case records its test in
+ * .forgeqe/test-cases.json in the repository (committed with the tests, so the team shares it), and a test case
+ * from Azure DevOps also gets its Associated Automation fields set, so the test plan shows it as automated.
+ */
+
+export const MAP_FILE = path.join(".forgeqe", "test-cases.json")
+const mapFile = (repo: string) => path.join(projectDir(repo), path.basename(MAP_FILE))
+
+export type MappingStatus = "automated" | "known_defect" | "needs_attention"
+
+export type Mapping = {
+  caseId: string
+  title: string
+  source: string
+  url?: string
+  status: MappingStatus
+  testFile?: string
+  testName?: string
+  command?: string
+  /** The bug a known-defect test waits on. */
+  bug?: { label: string; url?: string }
+  /** The needs-attention folder, for an unfinished test. */
+  attention?: string
+  updatedAt: string
+}
+
+type MapFile = { version: 1; cases: Record<string, Mapping> }
+
+export function readMappings(repo: string): MapFile {
+  try {
+    const data = JSON.parse(readFileSync(mapFile(repo), "utf8")) as MapFile
+    return { version: 1, cases: data?.cases && typeof data.cases === "object" ? data.cases : {} }
+  } catch {
+    return { version: 1, cases: {} }
+  }
+}
+
+/** Record (or replace) a test case's test in the repository's mapping file. */
+export function recordMapping(repo: string, m: Omit<Mapping, "updatedAt">): void {
+  const data = readMappings(repo)
+  data.cases[m.caseId] = { ...m, updatedAt: new Date().toISOString() }
+  const sorted: MapFile = { version: 1, cases: Object.fromEntries(Object.entries(data.cases).sort(([a], [b]) => a.localeCompare(b))) }
+  mkdirSync(projectDir(repo), { recursive: true })
+  writeFileSync(mapFile(repo), `${JSON.stringify(sorted, null, 2)}\n`)
+}
+
+/** The test framework a command runs, for Azure DevOps' AutomatedTestType. */
+export function frameworkOf(command: string | undefined, testFile: string | undefined): string {
+  const c = `${command || ""} ${testFile || ""}`.toLowerCase()
+  if (c.includes("playwright")) return "Playwright"
+  if (c.includes("cypress")) return "Cypress"
+  if (c.includes("pytest") || c.endsWith(".py")) return "pytest"
+  if (c.includes("dotnet test") || /\.cs\b/.test(c)) return "NUnit/xUnit (dotnet test)"
+  if (c.includes("vitest")) return "Vitest"
+  if (c.includes("jest")) return "Jest"
+  if (c.includes("mvn") || c.includes("gradle")) return "JUnit"
+  return "Automated test"
+}
+
+/** A stable GUID for a test, from its name and file: AutomatedTestId must be one, and the same test keeps the same id. */
+export function testGuid(name: string, file: string): string {
+  const h = createHash("sha1").update(`${file}::${name}`).digest("hex")
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-${((parseInt(h.slice(16, 18), 16) & 0x3f) | 0x80).toString(16)}${h.slice(18, 20)}-${h.slice(20, 32)}`
+}
+
+/**
+ * Set a Test Case work item's Associated Automation: the test's name, its file, its framework, and a stable id, with
+ * Automation status Automated. One write-back line, with an error when Azure DevOps refused it.
+ */
+export async function associateAdoAutomation(cfg: SourcesConfig, tc: TestCase, test: { name: string; file: string; command?: string }): Promise<WriteBack> {
+  const id = Number(tc.ref?.workItem)
+  if (!id) return { source: "ado", caseId: tc.id, text: `${tc.id}: automation not associated`, error: "the test case has no work item id" }
+  try {
+    const { org, project, base } = adoSettings(cfg)
+    const where = project ? base : typeof tc.ref?.project === "string" ? `${org}/${encodeURIComponent(tc.ref.project)}` : org
+    const ops = [
+      ["Microsoft.VSTS.TCM.AutomatedTestName", test.name],
+      ["Microsoft.VSTS.TCM.AutomatedTestStorage", test.file],
+      ["Microsoft.VSTS.TCM.AutomatedTestType", frameworkOf(test.command, test.file)],
+      ["Microsoft.VSTS.TCM.AutomatedTestId", testGuid(test.name, test.file)],
+      ["Microsoft.VSTS.TCM.AutomationStatus", "Automated"],
+    ].map(([field, value]) => ({ op: "add", path: `/fields/${field}`, value }))
+    await http(`${where}/_apis/wit/workitems/${id}?api-version=7.1`, { auth: adoSettings(cfg).auth, method: "PATCH", body: ops, contentType: "application/json-patch+json" })
+    return { source: "ado", caseId: tc.id, text: `${tc.id}: associated with the automated test ${test.name}`, ...(tc.url ? { url: tc.url } : {}) }
+  } catch (err) {
+    return { source: "ado", caseId: tc.id, text: `${tc.id}: automation not associated`, error: (err as Error).message }
+  }
+}

package/src/code/worktree.ts

@@ -0,0 +1,153 @@
+import { spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { ChangedFile } from "./prompt.ts"
+
+const KEEP_BYTES = 5_000_000
+
+type Entry = { status: string; hash: string; content?: Buffer }
+
+/** The repository's uncommitted state before a job: what the user had changed, and ForgeQE's own files. */
+export type WorkTree = { git: boolean; repo: string; own: string[]; entries: Map<string, Entry> }
+
+/** ForgeQE's files in the repository, relative to it: config, run folders, and page memory. Never part of a job's change. */
+export function ownPaths(repo: string, dirs: string[]): string[] {
+  const inside = dirs.map((d) => path.relative(repo, path.resolve(d))).filter((r) => r && !r.startsWith("..") && !path.isAbsolute(r))
+  return [...new Set([".forgeqe", "forgeqe.yaml", ".webpilot", "webpilot.yaml", "llms.json", ...inside].map((p) => p.split(path.sep).join("/")))]
+}
+
+/**
+ * What the coding agent may not touch, as the agent runtime matches it: edit patterns relative to the git worktree root (or
+ * the filesystem root outside git), shell patterns as the agent would write the paths.
+ */
+export function protectPatterns(repo: string, own: string[], outside: string[]): { edit: string[]; bash: string[] } {
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: repo, encoding: "utf8" })
+  const base = top.status === 0 && top.stdout.trim() ? path.resolve(top.stdout.trim()) : path.parse(repo).root
+  const abs = [...own.map((p) => path.join(repo, p)), ...outside]
+  const posix = (p: string) => p.split(path.sep).join("/")
+  return { edit: abs.map((p) => posix(path.relative(base, p))), bash: [...own, ...outside.map(posix)] }
+}
+
+export function isOwn(own: string[], rel: string): boolean {
+  return own.some((o) => rel === o || rel.startsWith(`${o}/`))
+}
+
+function gitStatus(repo: string): Map<string, string> | null {
+  const r = spawnSync("git", ["status", "--porcelain=v1", "-z", "-uall", "--no-renames"], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+  if (r.status !== 0) return null
+  const out = new Map<string, string>()
+  for (const rec of r.stdout.split("\0")) if (rec.length > 3) out.set(rec.slice(3), rec.slice(0, 2))
+  return out
+}
+
+function read(repo: string, rel: string): Buffer | null {
+  try {
+    const file = path.join(repo, rel)
+    return statSync(file).isFile() ? readFileSync(file) : null
+  } catch {
+    return null
+  }
+}
+
+const hashOf = (b: Buffer | null) => (b ? createHash("sha1").update(b).digest("hex") : "-")
+
+export function snapshot(repo: string, own: string[]): WorkTree {
+  const entries = new Map<string, Entry>()
+  const status = gitStatus(repo)
+  const add = (rel: string, st: string) => {
+    const content = read(repo, rel)
+    entries.set(rel, { status: st, hash: hashOf(content), content: content && content.length <= KEEP_BYTES ? content : undefined })
+  }
+  for (const [rel, st] of status || []) if (!isOwn(own, rel)) add(rel, st)
+  for (const rel of own) if (!entries.has(rel) && read(repo, rel)) add(rel, "own")
+  return { git: status !== null, repo, own, entries }
+}
+
+/** Uncommitted paths the user already had before the job, ForgeQE's own files left out. */
+export function preexisting(tree: WorkTree): string[] {
+  return [...tree.entries].filter(([rel, e]) => e.status !== "own" && !isOwn(tree.own, rel)).map(([rel]) => rel)
+}
+
+/** Paths the job created, changed, reverted, or deleted since the snapshot; null outside git. */
+export function jobChanges(tree: WorkTree): string[] | null {
+  const now = tree.git ? gitStatus(tree.repo) : null
+  if (!now) return null
+  const paths = new Set([...now.keys(), ...preexisting(tree)])
+  return [...paths].filter((rel) => {
+    if (isOwn(tree.own, rel)) return false
+    const was = tree.entries.get(rel)
+    return !was || !now.has(rel) || was.hash !== hashOf(read(tree.repo, rel))
+  }).sort()
+}
+
+/**
+ * Put back what the job must not take away: ForgeQE's files (removed or changed: the shell rules that protect them are
+ * only guard rails), the user's untracked files, and the user's uncommitted edits reverted to the committed version.
+ * Edits the job made on top of the user's are kept.
+ */
+export function restoreRemoved(tree: WorkTree, only: "all" | "own" = "all"): string[] {
+  const now = tree.git && only === "all" ? gitStatus(tree.repo) : null
+  const back: string[] = []
+  for (const [rel, e] of tree.entries) {
+    if (!e.content) continue
+    if (only === "own" && e.status !== "own") continue
+    const current = read(tree.repo, rel)
+    const gone = current === null
+    const ownChanged = e.status === "own" && !gone && hashOf(current) !== e.hash
+    const reverted = now !== null && e.status !== "own" && e.status !== "??" && e.status.includes("M") && !now.has(rel)
+    if (!gone && !reverted && !ownChanged) continue
+    const file = path.join(tree.repo, rel)
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(file, e.content)
+    back.push(rel)
+  }
+  return back
+}
+
+const INLINE_FILE_BYTES = 12_000
+const INLINE_TOTAL_BYTES = 60_000
+
+/** The job's changed files for a fresh session's brief: contents inline while they are small, paths only past that. */
+export function changedFiles(repo: string, paths: string[]): ChangedFile[] {
+  let total = 0
+  return paths.map((rel) => {
+    try {
+      const text = readFileSync(path.join(repo, rel), "utf8")
+      if (text.length > INLINE_FILE_BYTES || total + text.length > INLINE_TOTAL_BYTES) return { path: rel }
+      total += text.length
+      return { path: rel, content: text }
+    } catch {
+      return { path: rel }
+    }
+  })
+}
+
+/** The current contents of the given files (null for a file that does not exist), to put back later. */
+export function snapshotFiles(repo: string, paths: string[]): Map<string, Buffer | null> {
+  return new Map(paths.map((rel) => [rel, read(repo, rel)]))
+}
+
+/**
+ * Put the files back as `files` had them. A file changed since that is not in it goes back to how it was before the
+ * job (the user's version, or the committed one), or is removed when the job created it after the snapshot.
+ */
+export function restoreSnapshot(repo: string, tree: WorkTree, files: Map<string, Buffer | null>): void {
+  for (const [rel, content] of files) {
+    const file = path.join(repo, rel)
+    if (content === null) rmSync(file, { force: true })
+    else {
+      mkdirSync(path.dirname(file), { recursive: true })
+      writeFileSync(file, content)
+    }
+  }
+  for (const rel of jobChanges(tree) || []) {
+    if (files.has(rel)) continue
+    const file = path.join(repo, rel)
+    const was = tree.entries.get(rel)
+    if (was?.content) writeFileSync(file, was.content)
+    else if (spawnSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: repo }).status === 0) spawnSync("git", ["checkout", "--", rel], { cwd: repo })
+    else rmSync(file, { force: true })
+  }
+}