ravensight-playtest 0.5.2 → 0.6.0

package/src/run/fixLoop.js

@@ -1,5 +1,6 @@
 import { parseJsonObject } from './json.js';
 import { callStepWithRetry, ProxyError, STEPS } from './model.js';
+import { acceptanceBlock } from './acceptance.js';
 import { createRepoTools, WRITE_TOOLS } from './repoTools.js';
 
 /**
@@ -51,6 +52,12 @@ export const PLAN_MAX_TURNS = 6;
  */
 export const NUDGE_EVERY = 8;
 
+/** What `fix.apply` is told first. */
+export const FIX_APPLY_INSTRUCTIONS = Object.freeze([
+  'Make the change now. Read before you edit. Change an existing file with `edit_file` (old_text copied verbatim, new_text in its place); use `write_file` only for a new file, because it replaces the whole file and a large file will not fit in one answer.',
+  'Change as little as possible, keep the style of the code around it, and stop as soon as the fix is in. When you are done, say in one line what you changed and call no more tools.'
+]);
+
 /** One breakpoint, frozen so no caller can hand a mutated one to the next turn. */
 const CACHE_BREAKPOINT = Object.freeze({ type: 'ephemeral' });
 
@@ -146,7 +153,7 @@ export function resolveFixMaxActions(options = {}, pack = {}) {
  * @param {Object} args
  * @returns {Array<Object>}
  */
-export function fixSystem({ skill, jobId, branch, baseCommit, engine = null }) {
+export function fixSystem({ skill, jobId, branch, baseCommit, engine = null, runCheck = false }) {
   return [
     { type: 'text', text: skill },
     {
@@ -156,7 +163,9 @@ export function fixSystem({ skill, jobId, branch, baseCommit, engine = null }) {
         'the paths you read and write are relative to the repository root; never absolute',
         `engine recorded on this game: ${engine || 'unknown'}`,
         `branch: ${branch} (created for this attempt, from ${baseCommit || 'unknown'})`,
-        'you cannot run commands, reach the network, or commit anything. The developer reviews the branch and opens the pull request themselves.'
+        runCheck
+          ? 'you cannot run commands, reach the network, or commit anything, except the named checks the run_check tool offers. The developer reviews the branch.'
+          : 'you cannot run commands, reach the network, or commit anything. The developer reviews the branch and opens the pull request themselves.'
       ].join('\n'),
       cache_control: { type: 'ephemeral' }
     }
@@ -244,7 +253,8 @@ export async function planFix({
   content,
   repo,
   ledger = null,
-  log = () => {}
+  log = () => {},
+  step = STEPS.fixPlan
 }) {
   const messages = [{ role: 'user', content }];
   let turns = 0;
@@ -260,7 +270,7 @@ export async function planFix({
       client,
       jobId,
       runId,
-      step: STEPS.fixPlan,
+      step,
       system,
       messages: withRollingCacheBreakpoint(messages),
       tools: repo ? repo.tools : undefined,
@@ -321,7 +331,9 @@ export function normalisePlan(parsed) {
       .map(entry => entry.trim()),
     out_of_scope: (Array.isArray(parsed.out_of_scope) ? parsed.out_of_scope : [])
       .map(entry => (typeof entry === 'string' ? entry : JSON.stringify(entry)))
-      .filter(Boolean)
+      .filter(Boolean),
+    // Only a feature plan answers this. A fix plan reads exactly as it did.
+    ...(Array.isArray(parsed.placeholders) ? { placeholders: parsed.placeholders.filter(entry => typeof entry === 'string' && entry.trim()).map(entry => entry.trim().slice(0, 200)) } : {})
   };
 }
 
@@ -346,21 +358,34 @@ export async function applyFix({
   maxActions,
   codeBrief = null,
   graphContext = null,
+  acceptance = null,
+  repair = null,
   repo = createRepoTools({ root: repoRoot, tools: WRITE_TOOLS }),
   ledger = null,
   log = () => {},
   onProgress = () => {},
-  shouldStop = () => false
+  shouldStop = () => false,
+  step = STEPS.fixApply,
+  // What this apply is told to do and what it is held to. The feature module
+  // has its own words and its own frozen spec; everything else about the loop,
+  // its guards and its budget stop, is shared.
+  instructions = FIX_APPLY_INSTRUCTIONS,
+  contract = null
 }) {
   const messages = [{
     role: 'user',
     content: [{
       type: 'text',
       text: [
-        'Make the change now. Read before you edit. Change an existing file with `edit_file` (old_text copied verbatim, new_text in its place); use `write_file` only for a new file, because it replaces the whole file and a large file will not fit in one answer.',
-        'Change as little as possible, keep the style of the code around it, and stop as soon as the fix is in. When you are done, say in one line what you changed and call no more tools.',
+        ...(repair ? repairLines(repair) : []),
+        ...instructions,
         '',
         `<plan>\n${JSON.stringify(plan || EMPTY_PLAN, null, 2)}\n</plan>`,
+        ...(acceptance ? [acceptanceBlock(acceptance)] : []),
+        ...(contract ? [contract] : []),
+        ...(repo.tools.some(tool => tool.name === 'run_check')
+          ? ['Before you finish, call run_check with godot_import to prove the project still imports. A change that fails it cannot be uploaded.']
+          : []),
         ...bundleLines(codeBrief, graphContext)
       ].join('\n')
     }]
@@ -384,7 +409,7 @@ export async function applyFix({
         client,
         jobId,
         runId,
-        step: STEPS.fixApply,
+        step,
         system,
         messages: withRollingCacheBreakpoint(messages),
         tools: repo.tools,
@@ -453,6 +478,47 @@ export async function applyFix({
   return { turns, written: repo.written, stop };
 }
 
+/**
+ * The opening of a repair turn set: the change already on disk did not pass,
+ * and this is why. The acceptance contract is restated by the caller,
+ * unchanged; nothing here redefines success.
+ *
+ * @param {{attempt: number, of: number, reason: string, detail: string}} repair
+ * @returns {Array<string>}
+ */
+export function repairLines(repair) {
+  return [
+    `Repair ${repair.attempt} of ${repair.of}. Your earlier change is on disk on this branch, and it did not pass: ${repair.reason}.`,
+    `<failure>\n${String(repair.detail || '').slice(0, 6000)}\n</failure>`,
+    'Read the files you changed, correct the change so it passes, and keep it as small as before. Do not undo the fix to make a check pass.',
+    ''
+  ];
+}
+
+/**
+ * The verify result as the summary model reads it. A bare `reproduced: 0.34`
+ * was once written up as "reproduced the finding in 34% of actions", so the
+ * number never travels without what it is, what it is not and how it reads.
+ *
+ * @param {Object|null} verify
+ * @param {{fixedBelow: number, reproducedAbove: number}} thresholds
+ * @returns {string}
+ */
+export function verifyForSummary(verify, { fixedBelow, reproducedAbove }) {
+  if (!verify) return 'The fix was not verified by replaying the finding, so say that and claim no result.';
+  if (verify.failed === 'game_boot_failed') return 'The verify run could not test the fix because the game did not boot. Say the fix is not verified and claim no result.';
+  if (verify.failed) return `The verify run did not finish${verify.detail ? ` (${verify.detail})` : ''}, so it says nothing about the fix. Say the fix is not verified and claim no result.`;
+  const score = verify.reproduced;
+  if (typeof score !== 'number' || !Number.isFinite(score)) return 'The verify run played, but no verdict was reached. Say the result is unknown and claim no result.';
+  const reads = score < fixedBelow ? 'fixed' : (score > reproducedAbove ? 'still reproduced' : 'unknown');
+  return [
+    `One verify run replayed the finding, and that run was judged and given a score of ${score}.`,
+    `The score is a judged probability, from 0 to 1, that the finding is still present: below ${fixedBelow} reads as fixed, above ${reproducedAbove} reads as still reproduced, and anything between reads as unknown.`,
+    `This score reads as ${reads}.`,
+    'It is one opinion about one replay. It is not a percentage or a share of actions, attempts, sessions or players, and nothing was measured a number of times. Do not write it as a rate.'
+  ].join(' ');
+}
+
 /**
  * The pull request text, written from the diff that exists rather than from
  * the plan that was made.
@@ -474,6 +540,7 @@ export async function summariseFix({
   plan,
   files,
   verify,
+  thresholds,
   branch,
   fallback,
   ledger = null,
@@ -487,7 +554,7 @@ export async function summariseFix({
       `<finding>\n${JSON.stringify(finding, null, 2)}\n</finding>`,
       `<plan>\n${JSON.stringify(plan || EMPTY_PLAN, null, 2)}\n</plan>`,
       `<diff_stat>\n${files.map(file => `${file.path}: +${file.additions} -${file.deletions}`).join('\n') || 'nothing'}\n</diff_stat>`,
-      `<verify>\n${verify ? JSON.stringify(verify) : 'the fix was not verified by replaying the finding'}\n</verify>`,
+      `<verify>\n${verifyForSummary(verify, thresholds)}\n</verify>`,
       `<branch>${branch}</branch>`,
       '',
       'Answer with this JSON object and nothing else:',
@@ -511,7 +578,10 @@ export async function summariseFix({
       log('There was no budget left to write the pull request text, so it was written locally instead.');
       return { ...fallback, source: 'local' };
     }
-    throw error;
+    // The change exists, the checks and the verify have run. Prose is the one thing
+    // left, and losing it must not lose the changeset or fail a run that worked.
+    log(`The pull request text could not be written by the model (${String(error && error.message)}), so it was written locally instead.`);
+    return { ...fallback, source: 'local' };
   }
   if (ledger) ledger.record({ model: answer.model, usage: answer.usage });
 
@@ -535,4 +605,4 @@ export function clamp(value, limit) {
   return text.length <= limit ? text : text.slice(0, limit);
 }
 
-export default { planFix, applyFix, summariseFix, resolveFixMaxActions, fixSystem, planContent, normalisePlan, withRollingCacheBreakpoint };
+export default { planFix, applyFix, summariseFix, verifyForSummary, resolveFixMaxActions, fixSystem, planContent, normalisePlan, withRollingCacheBreakpoint };

package/src/run/git.js

@@ -3,7 +3,7 @@ import { randomBytes } from 'node:crypto';
 import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { skippedDirIn } from './repoTools.js';
+import { isRunOutputName, skippedDirIn } from './repoTools.js';
 
 /**
  * The only module in this CLI that runs git, and the only one that ever will.
@@ -19,7 +19,9 @@ import { skippedDirIn } from './repoTools.js';
  * - **It never rewrites history.** No `reset`, no `rebase`, no `checkout --`
  *   of a path. The only mutation is creating and checking out one new branch,
  *   and that is refused if the branch already exists, so an earlier attempt's
- *   work is never landed on.
+ *   work is never landed on. Undoing it, when the server refused the job before
+ *   anything happened on it, goes back to where it started and deletes the branch
+ *   with `-d`, which git refuses if the branch holds anything.
  * - **It refuses a dirty tree** unless the developer says otherwise, because
  *   the changeset is computed as a diff against the recorded HEAD and a tree
  *   that was already dirty makes that diff a mixture of two people's work.
@@ -35,7 +37,7 @@ import { skippedDirIn } from './repoTools.js';
 const run = promisify(execFile);
 
 /** Branch names git itself refuses, checked before git is asked. */
-const BAD_BRANCH = /(^-|^\.|\.\.|[~^:?*[\\ ]|@\{|\.lock$|\/$|^\/|\/\/)/;
+const BAD_BRANCH = /(^-|^\+|^@$|^\.|\.\.|[~^:?*[\\ ]|@\{|\.lock$|\/$|^\/|\/\/)/;
 
 /**
  * Where a fix lands by default: one branch per attempt, named after the
@@ -136,14 +138,22 @@ export function createGit({ root, exec = run }) {
      * @returns {Promise<Array<string>>}
      */
     async dirtyPaths(limit = Number.POSITIVE_INFINITY) {
-      const answer = await git(['status', '--porcelain', '--untracked-files=normal']);
+      // `-z` because git quotes a name with non-ASCII characters otherwise, and a
+      // quoted name is a path that does not exist. `-- .` because a repository's
+      // other directories are not what this command changes.
+      const answer = await git(['status', '--porcelain', '-z', '--untracked-files=normal', '--', '.']);
       if (!answer.ok) return [];
-      return answer.stdout.split('\n')
-        .map(line => line.slice(3).trim())
-        // A rename is `old -> new`; the new path is the one that exists.
-        .map(entry => (entry.includes(' -> ') ? entry.split(' -> ').pop().trim() : entry))
-        .filter(entry => entry && !skippedDirIn(entry))
-        .slice(0, limit);
+      const fields = answer.stdout.split('\0');
+      const out = [];
+      for (let i = 0; i < fields.length; i += 1) {
+        const field = fields[i];
+        if (field.length < 4) continue;
+        // A rename is `R  new`, then the old name in a field of its own.
+        if (/[RC]/.test(field.slice(0, 2))) i += 1;
+        const entry = field.slice(3);
+        if (!skippedDirIn(entry)) out.push(entry);
+      }
+      return out.slice(0, limit);
     },
 
     /** Whether the tree has uncommitted work worth refusing over. */
@@ -192,12 +202,15 @@ export function createGit({ root, exec = run }) {
      */
     async diffStat() {
       const out = [];
-      const tracked = await git(['diff', '--numstat']);
+      // `-z` as above. `--relative` because numstat otherwise answers from the top
+      // of the repository, and the rest of this CLI, untracked files included,
+      // works from `root`, which may be one game inside a monorepo.
+      const tracked = await git(['diff', '--numstat', '-z', '--relative', '--no-renames', '--no-ext-diff']);
       if (tracked.ok) {
-        for (const line of tracked.stdout.split('\n')) {
+        for (const line of tracked.stdout.split('\0')) {
           if (!line.trim()) continue;
           const [additions, deletions, ...rest] = line.split('\t');
-          const file = rest.join('\t').trim();
+          const file = rest.join('\t');
           if (!file || skippedDirIn(file)) continue;
           out.push({
             path: file,
@@ -208,11 +221,12 @@ export function createGit({ root, exec = run }) {
           });
         }
       }
-      const untracked = await git(['ls-files', '--others', '--exclude-standard']);
+      const untracked = await git(['ls-files', '-z', '--others', '--exclude-standard']);
       if (untracked.ok) {
-        for (const line of untracked.stdout.split('\n')) {
-          const file = line.trim();
-          if (!file || skippedDirIn(file)) continue;
+        for (const file of untracked.stdout.split('\0')) {
+          // Untracked at the root under one of these names: an older CLI's
+          // leftovers, never the customer's source.
+          if (!file || skippedDirIn(file) || isRunOutputName(file)) continue;
           out.push({ path: file, additions: await countLines(path.join(root, file)), deletions: 0 });
         }
       }
@@ -226,6 +240,61 @@ export function createGit({ root, exec = run }) {
   };
 }
 
+/**
+ * Which of these paths git ignores. A tracked file is never among them, whatever
+ * the rules say, because git still shows its changes. Outside a repository, or
+ * with no git at all, nothing is ignored: there are no rules to apply.
+ *
+ * @param {string} root
+ * @param {Array<string>} paths repository relative
+ * @returns {Promise<Set<string>>}
+ */
+export function ignoredPaths(root, paths) {
+  return new Promise((resolve) => {
+    if (paths.length === 0) {
+      resolve(new Set());
+      return;
+    }
+    const child = execFile('git', ['-C', root, 'check-ignore', '--stdin', '-z'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }, (error, stdout) => {
+      // Exit 1 is "none of them", and 128 is "not a repository".
+      resolve(new Set(error ? [] : String(stdout).split('\0').filter(Boolean)));
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(`${paths.join('\0')}\0`);
+  });
+}
+
+/**
+ * Every ignored file under the root. Asked this way round for a whole tree, because
+ * `check-ignore` refuses the entire list over one path inside a submodule.
+ *
+ * @param {string} root
+ * @returns {Promise<Set<string>>}
+ */
+export async function allIgnoredFiles(root) {
+  try {
+    const { stdout } = await run('git', ['-C', root, 'ls-files', '-z', '--others', '--ignored', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    return new Set(stdout.split('\0').filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Where this repository's hooks live, `core.hooksPath` included, as an absolute path.
+ *
+ * @param {string} root
+ * @returns {Promise<string|null>}
+ */
+export async function hooksDirectory(root) {
+  try {
+    const { stdout } = await run('git', ['-C', root, 'rev-parse', '--git-path', 'hooks'], { encoding: 'utf8' });
+    return path.resolve(root, stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The checks `fix` runs before it edits anything, in the order that answers
  * the developer soonest.
@@ -247,7 +316,7 @@ export function createGit({ root, exec = run }) {
  * @param {boolean} [options.create] create and check out the branch now
  * @returns {Promise<{ok: true, head: string, branch: string, from: string|null, dirty: boolean, created: boolean}|{ok: false, reason: string}>}
  */
-export async function preflight({ git, branch, allowDirty = false, create = true }) {
+export async function preflight({ git, branch, allowDirty = false, create = true, reuseBranch = false }) {
   if (!(await git.available())) {
     return { ok: false, reason: 'This command needs git on the PATH, and there is none here.' };
   }
@@ -256,6 +325,10 @@ export async function preflight({ git, branch, allowDirty = false, create = true
   }
   const named = branchNameRefusal(branch);
   if (named) return { ok: false, reason: named };
+  // Git has the last word on what a branch can be called, and asking it now means
+  // the refusal comes before a price rather than after one.
+  const usable = await git.git(['check-ref-format', '--branch', branch]);
+  if (!usable.ok && !usable.missing) return { ok: false, reason: `"${printable(branch)}" is not a usable branch name.` };
 
   const dirty = await git.isDirty();
   if (!allowDirty && dirty) {
@@ -267,7 +340,8 @@ export async function preflight({ git, branch, allowDirty = false, create = true
   if (!head) {
     return { ok: false, reason: 'This repository has no commits yet, so there is nothing to branch from.' };
   }
-  if (await git.branchExists(branch)) {
+  // Only a rerun after an unknown register keeps its branch (`run/pendingRegister.js`).
+  if (!reuseBranch && await git.branchExists(branch)) {
     return { ok: false, reason: `The branch ${branch} already exists. Pass --branch <name> to use another one.` };
   }
 
@@ -303,6 +377,17 @@ export async function startBranch({ git, branch }) {
   return { ok: true, branch };
 }
 
+/**
+ * Undo `startBranch`, when the job it was for never existed.
+ *
+ * @param {{git: Object, branch: string, from: string|null, head: string}} options
+ * @returns {Promise<void>}
+ */
+export async function abandonBranch({ git, branch, from, head }) {
+  const back = await git.git(from ? ['switch', from] : ['switch', '--detach', head]);
+  if (back.ok) await git.git(['branch', '-d', branch]);
+}
+
 /**
  * Lines in a file the fix created. Read rather than counted with git, because
  * git does not have a number for a file it has never seen.
@@ -324,8 +409,13 @@ async function countLines(absolute) {
   }
 }
 
+function printable(text) {
+  /* eslint-disable-next-line no-control-regex */
+  return String(text).replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+}
+
 function firstLine(text) {
   return String(text || '').split('\n').map(line => line.trim()).find(Boolean) || 'git gave no reason';
 }
 
-export default { createGit, preflight, startBranch, fixBranchName, branchNameRefusal };
+export default { abandonBranch, allIgnoredFiles, createGit, hooksDirectory, ignoredPaths, preflight, startBranch, fixBranchName, branchNameRefusal };

package/src/run/json.js

@@ -19,21 +19,77 @@ function unfence(text) {
   return fenced ? fenced[1] : value;
 }
 
+/** The most `{` positions tried per candidate text, so a pathological answer stays cheap. */
+const MAX_OBJECT_STARTS = 200;
+
+/**
+ * Every balanced `{...}` span in a text, skipping braces inside strings.
+ *
+ * @param {string} body
+ * @returns {Array<string>}
+ */
+function objectSpans(body) {
+  const spans = [];
+  let starts = 0;
+  for (let start = body.indexOf('{'); start !== -1 && starts < MAX_OBJECT_STARTS; start = body.indexOf('{', start + 1)) {
+    starts += 1;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < body.length; i += 1) {
+      const char = body[i];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (char === '\\') escaped = true;
+        else if (char === '"') inString = false;
+        continue;
+      }
+      if (char === '"') inString = true;
+      else if (char === '{') depth += 1;
+      else if (char === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          spans.push(body.slice(start, i + 1));
+          break;
+        }
+      }
+    }
+  }
+  return spans;
+}
+
 /**
+ * The JSON object in a model answer: fenced or not, with prose before or
+ * after it, and with braces in that prose (a GDScript `{}` quoted in a
+ * sentence, a fence of another language first). Of every object that parses,
+ * the longest wins, since the report is the big one and a quoted example is
+ * small.
+ *
  * @param {string} text
  * @returns {Object|null} null when the answer holds no JSON object
  */
 export function parseJsonObject(text) {
-  const body = unfence(text);
-  const start = body.indexOf('{');
-  const end = body.lastIndexOf('}');
-  if (start === -1 || end <= start) return null;
-  try {
-    const parsed = JSON.parse(body.slice(start, end + 1));
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-  } catch {
-    return null;
+  const value = String(text || '');
+  const candidates = [];
+  for (const match of value.matchAll(/```[A-Za-z0-9_-]*[ \t]*\n?([\s\S]*?)```/g)) candidates.push(match[1]);
+  candidates.push(value);
+  let best = null;
+  let bestLength = -1;
+  for (const candidate of candidates) {
+    for (const span of objectSpans(candidate)) {
+      if (span.length <= bestLength) continue;
+      try {
+        const parsed = JSON.parse(span);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          best = parsed;
+          bestLength = span.length;
+        }
+      } catch {
+        // Not this span.
+      }
+    }
   }
+  return best;
 }
 
 /**

package/src/run/labsOutcome.js

@@ -0,0 +1,136 @@
+import { execFile } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { jobsDir } from './paths.js';
+import * as stateFile from './state.js';
+
+/**
+ * What became of a pull request this CLI opened with `--open-pr`, reported on the
+ * next run. Feedback for the job's `labs_outcome`, read by no money path.
+ *
+ * Best effort and never blocking: it starts in the background, every failure is
+ * swallowed, it has a hard time limit, and a report the server did not take is
+ * tried again on the run after. It runs `gh` only for a job whose local journal
+ * says this machine opened a pull request, so a job without one costs a directory
+ * read. A revert found this way is one made through a pull request: a direct push
+ * of a revert commit reads as merged.
+ */
+
+const run = promisify(execFile);
+
+/** A check of one pull request at most this long, and all of them together. */
+const GH_TIMEOUT_MS = 5000;
+const OVERALL_TIMEOUT_MS = 8000;
+/** How many pull requests one run looks at, newest first. */
+export const MAX_CHECKS_PER_RUN = 5;
+/** A merged pull request can still be reverted, so it is followed this long. */
+export const FOLLOW_DAYS = 90;
+const FINAL = new Set(['reverted', 'abandoned']);
+const PR_URL = /^https:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)$/;
+
+/**
+ * @param {{state: string}} pr what `gh pr view` shows
+ * @param {boolean} reverted
+ * @returns {'open'|'merged'|'reverted'|'abandoned'|null}
+ */
+export function outcomeOf(pr, reverted) {
+  if (pr.state === 'OPEN') return 'open';
+  if (pr.state === 'MERGED') return reverted ? 'reverted' : 'merged';
+  if (pr.state === 'CLOSED') return 'abandoned';
+  return null;
+}
+
+async function gh(exec, args, signal) {
+  const { stdout } = await exec('gh', args, { timeout: GH_TIMEOUT_MS, maxBuffer: 1024 * 1024, signal });
+  return JSON.parse(String(stdout));
+}
+
+/** A merged pull request whose title or body says it reverts this one. */
+async function wasReverted(exec, pr, [, owner, name, number], signal) {
+  const repo = `${owner}/${name}`;
+  const merged = await gh(exec, ['pr', 'list', '--repo', repo, '--state', 'merged', '--search', 'Revert in:title,body', '--json', 'title,body', '--limit', '30'], signal);
+  const byBody = new RegExp(`\\bReverts\\s+(${repo.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})?#${number}\\b`, 'i');
+  return merged.some(entry => entry.title === `Revert "${pr.title}"` || byBody.test(String(entry.body || '')));
+}
+
+/**
+ * Tell the server this job opened a pull request and remember the URL locally. The
+ * URL stays on this machine: the server stores the outcome only.
+ */
+export async function recordPrOpened({ api, gameId, repoRoot, journal, url, now = () => new Date() }) {
+  if (!url) return;
+  try {
+    journal.pull_request = { url, opened_at: now().toISOString(), reported: null };
+    await stateFile.save(repoRoot, journal);
+    await api.jobs.labsOutcomePr(gameId, journal.job_id, { pr: 'open' });
+    journal.pull_request.reported = 'open';
+    await stateFile.save(repoRoot, journal);
+  } catch {
+    // The next run says it again.
+  }
+}
+
+async function reportOne({ api, gameId, repoRoot, journal, exec, signal }) {
+  const record = journal.pull_request;
+  const parts = PR_URL.exec(record.url);
+  const pr = await gh(exec, ['pr', 'view', record.url, '--json', 'state,title,number'], signal);
+  const reverted = pr.state === 'MERGED' ? await wasReverted(exec, pr, parts, signal) : false;
+  const outcome = outcomeOf(pr, reverted);
+  if (!outcome) return;
+  if (!record.reported) {
+    await api.jobs.labsOutcomePr(gameId, journal.job_id, { pr: 'open' });
+    record.reported = 'open';
+    await stateFile.save(repoRoot, journal);
+  }
+  if (outcome === record.reported) return;
+  await api.jobs.labsOutcomePr(gameId, journal.job_id, { pr: outcome });
+  record.reported = outcome;
+  if (FINAL.has(outcome)) record.done = true;
+  await stateFile.save(repoRoot, journal);
+}
+
+async function followable(repoRoot, now) {
+  const cutoff = now().getTime() - FOLLOW_DAYS * 24 * 60 * 60 * 1000;
+  const found = [];
+  for (const jobId of await readdir(jobsDir(repoRoot))) {
+    const journal = await stateFile.load(repoRoot, jobId).catch(() => null);
+    const record = journal && journal.pull_request;
+    if (!record || record.done || !PR_URL.test(String(record.url))) continue;
+    const opened = Date.parse(record.opened_at);
+    if (!Number.isFinite(opened) || opened < cutoff) continue;
+    found.push({ journal, opened });
+  }
+  return found.sort((a, b) => b.opened - a.opened).slice(0, MAX_CHECKS_PER_RUN);
+}
+
+/**
+ * Look at every pull request this repository's jobs opened, and report what changed.
+ * Never rejects and never takes longer than its limit.
+ *
+ * @returns {Promise<void>}
+ */
+export async function reportPrOutcomes({ api, gameId, repoRoot, exec = run, now = () => new Date(), timeoutMs = OVERALL_TIMEOUT_MS }) {
+  const controller = new AbortController();
+  let timer;
+  const expired = new Promise(resolve => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve();
+    }, timeoutMs);
+  });
+  const work = (async () => {
+    const entries = await followable(repoRoot, now);
+    for (const { journal } of entries) {
+      if (controller.signal.aborted) return;
+      try {
+        await reportOne({ api, gameId, repoRoot, journal, exec, signal: controller.signal });
+      } catch {
+        // No gh, not signed in, no network, a server without the route: next run.
+      }
+    }
+  })().catch(() => {});
+  await Promise.race([work, expired]);
+  clearTimeout(timer);
+}
+
+export default { outcomeOf, recordPrOpened, reportPrOutcomes, MAX_CHECKS_PER_RUN, FOLLOW_DAYS };