ravensight-playtest 0.3.0 → 0.3.2

package/src/run/personaLoop.js

@@ -1,17 +1,19 @@
 import { rewriteMarkdown } from './dropped.js';
 import { selectAction, JEV_CONTROLLER_PROMPT } from './actionSelector.js';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { prepareMessages, MAX_IMAGES_IN_CONTEXT, KEEP_OBSERVATIONS, shrinkImages } from './context.js';
 import { withRollingCacheBreakpoint } from './fixLoop.js';
 import { callStepWithRetry, ProxyError, STEPS } from './model.js';
 import { RUN_FILES } from './paths.js';
-import { checkEvidence, createReportValidator, lintMarkdownSections, normaliseEvidence, repairInstruction, REQUIRED_MARKDOWN_SECTIONS, stampReport, writeReportFiles } from './report.js';
+import { appendNormalisedMarkdown, checkEvidence, createReportValidator, lintMarkdownSections, normaliseEnums, normaliseEvidence, repairInstruction, REQUIRED_MARKDOWN_SECTIONS, stampReport, writeReportFiles } from './report.js';
 import { assertNoSecrets } from './secretScan.js';
 import { ACTION_TOOLS, PLAY_TOOLS, SWIPE_TOOL, REPORT_TOOLS, executeTool } from './tools.js';
 import { createTranscript } from './transcript.js';
 import { createUsageLedger, writeUsageFile } from './usage.js';
 import { fillPlaceholders, fillReportPlaceholders } from './placeholders.js';
+import { BUILT_IN_NOISE, expectedNoiseForPrompt, isExpectedNoise } from './noise.js';
+import { MIN_PASSWORD_CHARS } from '../briefLocal.js';
 
 /**
  * One persona's playthrough: PLAYING then REPORTING (spec 03).
@@ -130,6 +132,9 @@ export async function runPersona(args) {
     runDirectory,
     skill,
     brief = null,
+    // The brief fields that stay on this machine (../briefLocal.js):
+    // expected_noise and test_account.
+    localBrief = {},
     intentNotes = [],
     schemas,
     maxActions,
@@ -267,6 +272,7 @@ export async function runPersona(args) {
       validator,
       skill: args.reportSkill || skill,
       brief,
+      localBrief,
       intentNotes,
       transcript,
       ledger,
@@ -330,6 +336,7 @@ async function playLoop({
   target,
   skill,
   brief,
+  localBrief = {},
   intentNotes,
   maxActions,
   transcript,
@@ -344,7 +351,10 @@ async function playLoop({
   onBudgetWarning = null,
   log = () => {}
 }) {
-  const system = buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions });
+  const system = buildSystem({ skill, persona, brief, localBrief, intentNotes, driverName, target, maxActions, runId });
+  const identity = runIdentity({ persona, runId });
+  const secrets = secretsOf(localBrief);
+  const noisePatterns = (localBrief && Array.isArray(localBrief.expected_noise)) ? localBrief.expected_noise : [];
   if (controller === 'jev') system.push({ type: 'text', text: JEV_CONTROLLER_PROMPT });
   const availableTools = driver.supportedActions
     ? [...PLAY_TOOLS, ...(driver.supportedActions.includes('swipe') ? [SWIPE_TOOL] : [])].filter(tool => !ACTION_TOOLS.includes(tool.name) || driver.supportedActions.includes(tool.name))
@@ -362,6 +372,9 @@ async function playLoop({
     }
   })) : availableTools;
   const recentActions = [];
+  // The observation and action lines of the transcript, kept for the report
+  // step's "Actions you took" list.
+  const actionRecords = [];
   let latestObservation = '';
   let visualObservation = false;
   const messages = [];
@@ -387,7 +400,9 @@ async function playLoop({
     return entry;
   };
   const noted = note => {
-    const entry = { ...note, at_action: actions, observation: observations.length, order: nextOrder() };
+    // A note never carries the test account password, in the transcript, a
+    // partial report or the report prompt.
+    const entry = { ...scrubSecrets(note, secrets), at_action: actions, observation: observations.length, order: nextOrder() };
     notes.push(entry);
     awaitingAfter.push(entry);
     return entry;
@@ -398,6 +413,7 @@ async function playLoop({
   latestObservation = first.text;
   visualObservation = Boolean(first.screenshotBase64);
   transcript.write({ kind: 'observation', step: first.step, text: first.text, url: first.url });
+  actionRecords.push({ kind: 'observation', text: first.text });
   const landing = await safeScreenshot(driver, 'landing', screenshots, transcript, observations.length);
   messages.push({
     role: 'user',
@@ -508,13 +524,14 @@ async function playLoop({
         driver,
         toolUse,
         staleRefs: screenChangedThisTurn,
+        identity,
         onNote: note => {
           // The note is nested rather than spread: its own `kind`
           // (bug, confusing, good, suggestion, reaction) would otherwise
           // overwrite the transcript line's `kind`, and every note would
           // read as a different sort of line.
           noted(note);
-          transcript.write({ kind: 'note', tool: toolUse.name, note });
+          transcript.write({ kind: 'note', tool: toolUse.name, note: scrubSecrets(note, secrets) });
         },
         onScreenshot: shot => {
           screenshots.push({ ...shot, observation: observations.length, order: nextOrder() });
@@ -524,16 +541,18 @@ async function playLoop({
       results.push(executed.result);
       if (executed.spentAction) actions += 1;
       if (executed.changed && ACTION_TOOLS.includes(toolUse.name)) screenChangedThisTurn = true;
-      transcript.write({
+      const actionLine = {
         kind: 'action',
         tool: toolUse.name,
-        input: redactToolInput(toolUse),
-        thought: (toolUse.input && toolUse.input.thought_in_character) || null,
+        input: redactToolInput(toolUse, secrets),
+        thought: scrubSecrets((toolUse.input && toolUse.input.thought_in_character) || null, secrets),
         ok: !executed.error,
         error: executed.error,
         changed: executed.changed,
         actions
-      });
+      };
+      transcript.write(actionLine);
+      actionRecords.push(actionLine);
       if (executed.driverError) {
         // The driver failed, not the game: a target that matched twice,
         // locator code, a ref not on screen, a timeout on an unchanged page.
@@ -551,6 +570,7 @@ async function playLoop({
         recentActions.push(`${toolUse.name}: ${executed.changed ? 'screen changed' : 'no observed change'}`);
         if (recentActions.length > 10) recentActions.shift();
         transcript.write({ kind: 'observation', step: executed.observation.step, text: executed.observation.text, url: executed.observation.url });
+        actionRecords.push({ kind: 'observation', text: executed.observation.text });
         // Only an input to the game can tell us anything about being stuck. A
         // `snapshot` or a `screenshot` never changes the screen by design, so
         // counting those would have a persona that looks twice before acting
@@ -580,9 +600,20 @@ async function playLoop({
       const shot = await safeScreenshot(driver, 'console-error', screenshots, transcript, observations.length);
       for (const entry of consoleErrors) {
         const kind = RESOURCE_4XX.test(String(entry.text)) ? 'network' : 'bug';
-        const note = { kind, text: `${entry.type}: ${entry.text}`, automatic: true, ...(shot ? { screenshot: shot.relativePath } : {}) };
+        const note = {
+          kind,
+          text: `${entry.type}: ${entry.text}`,
+          automatic: true,
+          ...(entry.url ? { url: String(entry.url).slice(0, 200) } : {}),
+          ...(entry.url && Number.isInteger(entry.status) ? { status: entry.status } : {}),
+          ...(shot ? { screenshot: shot.relativePath } : {})
+        };
+        // Noise the developer said to expect (or the built in rule: a 401 on
+        // an auth check while signed out) is marked, so the report step is
+        // told and the runner can drop a finding that rests only on it.
+        if (isExpectedNoise({ ...note, status: Number.isInteger(entry.status) ? entry.status : note.status }, noisePatterns)) note.expected_noise = true;
         noted(note);
-        transcript.write({ kind: 'note', note });
+        transcript.write({ kind: 'note', note: scrubSecrets(note, secrets) });
       }
       asides.push(`The game logged ${consoleErrors.length} error(s): ${consoleErrors.map(entry => entry.text).join(' | ').slice(0, 800)}${shot ? ` A screenshot is saved at ${shot.relativePath}.` : ''}`);
     }
@@ -631,7 +662,8 @@ async function playLoop({
     budgetExceeded,
     canceled,
     imageBudget,
-    finalScreenshot: final ? final.relativePath : null
+    finalScreenshot: final ? final.relativePath : null,
+    actionLog: actionLogFrom(actionRecords)
   };
 }
 
@@ -647,9 +679,11 @@ async function reportPhase({
   driverName,
   target,
   runDirectory,
+  schemas = [],
   validator,
   skill,
   brief,
+  localBrief = {},
   intentNotes,
   transcript,
   ledger,
@@ -661,7 +695,11 @@ async function reportPhase({
   endedAt,
   log
 }) {
-  const system = buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions: play.actionsTaken });
+  // The report step never sees the test account: it has nothing to sign in
+  // to, and the password crosses the model proxy during play only.
+  const secrets = secretsOf(localBrief);
+  const reportLocal = localBrief && Array.isArray(localBrief.expected_noise) ? { expected_noise: localBrief.expected_noise } : {};
+  const system = buildSystem({ skill, persona, brief, localBrief: reportLocal, intentNotes, driverName, target, maxActions: play.actionsTaken, runId });
   const messages = [{
     role: 'user',
     content: [{
@@ -676,13 +714,22 @@ async function reportPhase({
         '',
         'Notes marked automatic were recorded by the runner from the console, with no severity: decide one from what the persona saw. Network notes are context, not bugs: a failed request is a finding only when the persona saw a broken screen because of it. A finding whose only evidence is automatic network notes is capped at minor by the runner.',
         'Driver errors are never evidence of a game bug. An observation marked [driver error: ...] or a note "written on a driver error" means the runner could not carry out the action (a target that matched two elements, locator code, a ref not on screen, a timeout on a page that did not change); the game did nothing wrong there. Never report a blocked loop, a frozen screen or a broken button from them. The runner drops any blocker or major whose only cited observations are driver errors.',
+        `Notes marked expected noise match the brief's expected_noise or the built in rule (${BUILT_IN_NOISE}); they are never a finding of any severity, and the runner drops a finding whose transcript evidence is only expected noise.`,
         'Notes of kind waiting ("waiting for X to finish") are context, never a finding of any severity, and the runner drops a finding cited only by them. Before reporting a loading problem, check the later observations and screenshots: if they show the content loaded, it is not a finding.',
         '',
         'Observations the persona was shown, by index:',
         observationLines(observations),
         '',
+        'Actions you took (every action that went through, numbered by action; "screen changed" means the screen after it differed from the screen before):',
+        actionLogLines(play.actionLog),
+        '',
+        'A claim in report.md or report.json that something was never done, never worked, did nothing or could not be done must agree with this list. If the list shows you clicked a control and the screen changed, do not write that you never clicked it or that it did nothing; describe what the screen showed after it instead. The runner downgrades a finding that says otherwise.',
+        '',
+        'Network notes (failed requests the runner recorded, with the URL and the status; list them under a "Network notes" heading in report.md when there are any):',
+        networkNoteLines(notes),
+        '',
         'Each note carries "after": the URL and title of the observation that followed it. A blocker or major finding must cite the observation index where the failure is visible, as evidence {"type": "transcript_step", "ref": "observation N"}, and must not be contradicted by its note\'s "after" state or by a later persona note: if the next screen or a later note shows the game working, it is not a blocker or a major. Cite a note as {"type": "transcript_step", "ref": "note N"}.',
-        'A blocker or major finding must also cite the screenshot taken at or after that observation (the list below says which observation each one followed), and that screenshot must not contradict it: if it shows the thing the finding says is missing or broken, such as the field or the button, it is not a blocker or a major. A text observation can be cut short on a long page; the screenshot is what the player saw.',
+        'A blocker or major finding must also cite the screenshot taken at or after that observation (the list below says which observation each one followed), and that screenshot must not contradict it: if it shows the thing the finding says is missing or broken, such as the field or the button, it is not a blocker or a major. A text observation can be cut short on a long page; the screenshot is what the player saw. After you write the report, the runner shows each blocker or major (at most three) its cited screenshot and downgrades one step any finding the image contradicts.',
         '',
         'Every evidence entry is an object with exactly two keys, "type" and "ref", and nothing else. A screenshot is {"type": "screenshot", "ref": "screenshots/04-example.png"}, never "path" or "file".',
         '',
@@ -697,6 +744,9 @@ async function reportPhase({
       ].join('\n')
     }]
   }];
+  // The prompt is built from notes, observations and the action log; none
+  // of them may carry the test account password into the report step.
+  messages[0].content[0].text = scrubSecrets(messages[0].content[0].text, secrets);
 
   let report = null;
   let markdown = null;
@@ -707,6 +757,9 @@ async function reportPhase({
   let repaired = false;
   let continued = false;
   let droppedByRunner = [];
+  let downgradedByRunner = [];
+  let normalisedByRunner = [];
+  const reportSchema = ((schemas || []).find(schema => schema && schema.name === 'playtest-report') || {}).content || null;
 
   // One repair at most when the schema or the evidence refs refuse what was
   // written: each turn is a metered question, and the dogfood gate asks for
@@ -807,13 +860,30 @@ async function reportPhase({
     if (normalised && normalised.changed > 0) {
       transcript.write({ kind: 'report_evidence_normalised', attempt, entries: normalised.changed });
     }
-    const capped = normalised ? capNetworkOnlyFindings(stampReport(normalised.report, facts), { notes, screenshots }) : null;
+    // Known out of range values (a category written as the severity, an
+    // unknown category) are brought back into the schema before anything
+    // judges the report, so a run is never lost to them for want of a repair
+    // turn. The server's schema stays strict.
+    const enumFixed = normalised ? normaliseEnums(normalised.report, reportSchema) : { report: null, changes: [] };
+    normalisedByRunner = enumFixed.changes;
+    if (enumFixed.changes.length > 0) {
+      transcript.write({ kind: 'report_values_normalised', attempt, changes: enumFixed.changes.map(change => ({ id: change.id, field: change.field, from: change.from, to: change.to })) });
+    }
+    const capped = normalised ? capNetworkOnlyFindings(stampReport(enumFixed.report, facts), { notes, screenshots }) : null;
     const runnerDrop = capped ? dropRunnerRejectedFindings(capped, { notes, observations }) : { report: null, dropped: [] };
-    const candidate = runnerDrop.report;
     for (const entry of runnerDrop.dropped) {
       transcript.write({ kind: 'finding_dropped', id: entry.finding.id, severity: entry.finding.severity, title: entry.finding.title, reason: entry.reason });
     }
     droppedByRunner = runnerDrop.dropped;
+    const contradicted = runnerDrop.report ? downgradeContradictedFindings(runnerDrop.report, play.actionLog) : { report: null, downgraded: [] };
+    const candidate = contradicted.report;
+    for (const entry of contradicted.downgraded) {
+      transcript.write({ kind: 'finding_downgraded', id: entry.id, from: entry.from, to: entry.to, control: entry.control, action: entry.action });
+    }
+    downgradedByRunner = contradicted.downgraded;
+    if (contradicted.downgraded.length > 0) {
+      log(`downgraded ${contradicted.downgraded.length} finding(s) the action log contradicts: ${contradicted.downgraded.map(entry => `${entry.id} (${entry.from} to ${entry.to}, ${entry.control} clicked at step ${entry.action})`).join(', ')}`);
+    }
     if (candidate) lastCandidate = candidate;
     const validation = candidate ? validator.validate(candidate) : { ok: false, details: [{ instancePath: '/', message: parseError || 'report.json was not written' }] };
     const evidenceProblems = candidate ? await checkEvidence(candidate, runDirectory) : [];
@@ -872,6 +942,22 @@ async function reportPhase({
     });
   }
 
+  // One bounded look at the evidence: each blocker or major (at most
+  // MAX_CLAIM_CHECKS) is shown the screenshot it cites with its claim. It runs
+  // after the report is settled, so a refusal can cost the check and never
+  // the report.
+  report = scrubSecrets(report, secrets);
+  if (!shrunk) {
+    const checked = await checkClaimsAgainstScreenshots({ client, jobId, runId, report, screenshots, runDirectory, ledger, transcript, log });
+    if (checked.downgraded.length > 0) {
+      report = checked.report;
+      downgradedByRunner = [...downgradedByRunner, ...checked.downgraded];
+      log(`downgraded ${checked.downgraded.length} finding(s) their own screenshot contradicts: ${checked.downgraded.map(entry => `${entry.id} (${entry.from} to ${entry.to}, ${entry.screenshot})`).join(', ')}`);
+    }
+  } else {
+    transcript.write({ kind: 'claim_check_skipped', reason: 'the report turn needed a smaller output ceiling to fit the budget' });
+  }
+
   if (!markdown) {
     markdown = renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason: 'The report step wrote report.json but no report.md.' });
   }
@@ -879,16 +965,154 @@ async function reportPhase({
     markdown = rewriteMarkdown(markdown, droppedByRunner.map(entry => entry.finding), report.findings || [], RUNNER_DROPPED_SECTION);
     log(`dropped ${droppedByRunner.length} finding(s) the runner's evidence rules refuse: ${droppedByRunner.map(entry => `${entry.finding.id} (${entry.reason})`).join(', ')}`);
   }
+  // The uploaded pair agree: report.md says the severity report.json does.
+  if (downgradedByRunner.length > 0) markdown = rewriteDowngradedMarkdown(markdown, downgradedByRunner);
+  if (normalisedByRunner.length > 0) {
+    markdown = appendNormalisedMarkdown(markdown, normalisedByRunner);
+    log(`normalised ${normalisedByRunner.length} value(s) the report schema does not allow: ${normalisedByRunner.map(change => `${change.id ? `${change.id} ` : ''}${change.field} ${JSON.stringify(change.from)} to ${JSON.stringify(change.to)}`).join(', ')}`);
+  }
   const generatedAt = new Date().toISOString();
   const facts = reportFacts({ persona, driverName, target, play });
   markdown = stampGeneratedAt(markdown, generatedAt, facts);
   // The same slots in the prose the dashboard shows from report.json.
   report = fillReportPlaceholders(report, { generatedAt, ...facts });
+  // Whatever the model wrote, the password does not leave in a report.
+  markdown = scrubSecrets(markdown, secrets);
+  report = scrubSecrets(report, secrets);
 
   await writeReportFiles({ runDirectory, markdown, report });
   return { report, markdown, lint };
 }
 
+/** The most blocker or major findings whose screenshot is checked against the claim. */
+export const MAX_CLAIM_CHECKS = 3;
+
+/** Output ceiling for one claim check: the answer is one word. */
+export const CLAIM_CHECK_MAX_TOKENS = 32;
+
+/** The instruction for a claim check. */
+export const CLAIM_CHECK_SYSTEM = 'You check playtest findings against their evidence. You are shown one screenshot and one claim about it. Answer with exactly one word: yes if the image contradicts the claim, no if it does not, unclear if the image cannot settle it.';
+
+/**
+ * The screenshot a finding's claim is checked against: of those it cites, the
+ * one taken nearest after the latest observation it cites (the later of two on
+ * the same observation), else the last screenshot it cites. Null when it cites none that exists in the list.
+ *
+ * @param {Object} finding
+ * @param {Array<Object>} screenshots
+ * @returns {Object|null}
+ */
+export function citedAfterScreenshot(finding, screenshots) {
+  const evidence = Array.isArray(finding && finding.evidence) ? finding.evidence : [];
+  const byPath = new Map((screenshots || []).filter(shot => shot && shot.relativePath).map(shot => [shot.relativePath, shot]));
+  const cited = evidence.filter(item => item && item.type === 'screenshot' && byPath.has(String(item.ref))).map(item => byPath.get(String(item.ref)));
+  if (cited.length === 0) return null;
+  const observations = evidence
+    .map(item => (item && item.type === 'transcript_step' ? String(item.ref || '').match(/^\s*observation\s*#?\s*(\d+)\s*$/i) : null))
+    .filter(Boolean)
+    .map(match => Number(match[1]));
+  if (observations.length > 0) {
+    const latest = Math.max(...observations);
+    // The nearest screen after the claim: the lowest observation at or after
+    // it, and of two taken on the same observation the later one.
+    const order = new Map((screenshots || []).map((shot, index) => [shot, index]));
+    const after = cited
+      .filter(shot => Number.isInteger(shot.observation) && shot.observation >= latest)
+      .sort((a, b) => a.observation - b.observation || order.get(b) - order.get(a))[0];
+    if (after) return after;
+  }
+  return cited[cited.length - 1];
+}
+
+/**
+ * Read a claim check answer: yes, no or unclear, from its first word.
+ *
+ * @param {string} text
+ * @returns {'yes'|'no'|'unclear'}
+ */
+export function claimCheckAnswer(text) {
+  const match = String(text || '').match(/^[^A-Za-z]*(yes|no|unclear)\b/i);
+  return match ? match[1].toLowerCase() : 'unclear';
+}
+
+/**
+ * The bounded verification turn of the report step. For each blocker or
+ * major, at most {@link MAX_CLAIM_CHECKS}, the cited `after` screenshot is
+ * sent with the finding's claim and the question "does this image contradict
+ * the claim: yes, no, unclear". A yes downgrades the finding one step, with a
+ * note naming the screenshot. Texas and Snowball both filed a finding its own
+ * screenshot contradicted.
+ *
+ * It goes to `persona_playtest.act`, the run's one step that accepts an image
+ * (the report step accepts none), with no tools and a one word ceiling, and
+ * it is spent from the same run budget the warning at 80 percent keeps for the
+ * report step. A budget refusal, or any other refusal, ends the checks and
+ * keeps the report as it is.
+ *
+ * @returns {Promise<{report: Object, downgraded: Array<Object>}>}
+ */
+export async function checkClaimsAgainstScreenshots({ client, jobId, runId, report, screenshots, runDirectory, ledger, transcript, log = () => {} }) {
+  if (!report || !Array.isArray(report.findings)) return { report, downgraded: [] };
+  const targets = report.findings.filter(finding => finding && ABOVE_MINOR.includes(finding.severity)).slice(0, MAX_CLAIM_CHECKS);
+  const downgraded = [];
+  const verdicts = new Map();
+  for (const finding of targets) {
+    const shot = citedAfterScreenshot(finding, screenshots);
+    if (!shot) {
+      transcript.write({ kind: 'claim_check', id: finding.id, screenshot: null, answer: 'skipped', reason: 'no cited screenshot' });
+      continue;
+    }
+    let data;
+    try {
+      data = (await readFile(path.join(runDirectory, shot.relativePath))).toString('base64');
+    } catch {
+      transcript.write({ kind: 'claim_check', id: finding.id, screenshot: shot.relativePath, answer: 'skipped', reason: 'the screenshot could not be read' });
+      continue;
+    }
+    let answer;
+    const askedAt = Date.now();
+    try {
+      answer = await callStepWithRetry({
+        client,
+        jobId,
+        runId,
+        step: STEPS.personaAct,
+        system: CLAIM_CHECK_SYSTEM,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'image', source: { type: 'base64', media_type: 'image/png', data } },
+            { type: 'text', text: `Claim (${finding.severity}): ${finding.title || ''}\n${String(finding.description || '').slice(0, 1200)}\n\nDoes this image contradict the claim: yes, no, unclear?` }
+          ]
+        }],
+        maxTokens: CLAIM_CHECK_MAX_TOKENS,
+        escalate: false,
+        maxAttempts: 1
+      });
+    } catch (error) {
+      const reason = error instanceof ProxyError && error.isBudget ? 'the run budget is spent' : String(error && error.message ? error.message : error);
+      transcript.write({ kind: 'claim_check', id: finding.id, screenshot: shot.relativePath, answer: 'skipped', reason });
+      log(`the screenshot check stopped (${reason}); the report is kept as written.`);
+      break;
+    }
+    if (ledger) ledger.record({ model: answer.model, usage: answer.usage, ms: Date.now() - askedAt });
+    const verdict = claimCheckAnswer(answer.text);
+    transcript.write({ kind: 'claim_check', id: finding.id, screenshot: shot.relativePath, answer: verdict });
+    if (verdict === 'yes' && DOWNGRADE[finding.severity]) verdicts.set(finding, shot.relativePath);
+  }
+  if (verdicts.size === 0) return { report, downgraded };
+  const findings = report.findings.map(finding => {
+    if (!verdicts.has(finding)) return finding;
+    const screenshot = verdicts.get(finding);
+    const to = DOWNGRADE[finding.severity];
+    const note = `its own screenshot ${screenshot} contradicts the claim`;
+    downgraded.push({ id: finding.id, from: finding.severity, to, screenshot, note });
+    const description = String(finding.description || '');
+    return { ...finding, severity: to, description: description ? `${description}\n\nDowngraded by the runner: ${note}.` : `Downgraded by the runner: ${note}.` };
+  });
+  return { report: { ...report, findings }, downgraded };
+}
+
 /** The smallest output ceiling worth retrying a report turn with. */
 export const REPORT_MIN_TOKENS = 1536;
 
@@ -988,7 +1212,9 @@ async function callWithImageRetry({ imageBudget, keepObservations, messages, onI
  * product where the same few thousand tokens are re-sent tens of times. The
  * proxy allowlists `system` and passes the blocks through unchanged.
  */
-export function buildSystem({ skill, persona, brief, intentNotes, driverName, target, maxActions }) {
+export function buildSystem({ skill, persona, brief, localBrief = {}, intentNotes, driverName, target, maxActions, runId = null }) {
+  const identity = runIdentity({ persona, runId });
+  const account = testAccountOf(localBrief);
   return [
     { type: 'text', text: skill },
     { type: 'text', text: `<persona_file>\n${persona.body}\n</persona_file>` },
@@ -999,13 +1225,87 @@ export function buildSystem({ skill, persona, brief, intentNotes, driverName, ta
         `target: ${target}`,
         `max_actions: ${maxActions}`,
         `<expectations_brief>\n${briefForPrompt(brief)}\n</expectations_brief>`,
-        `<design_intent_notes>\n${intentNotesForPrompt(brief, intentNotes)}\n</design_intent_notes>`
+        `<design_intent_notes>\n${intentNotesForPrompt(brief, intentNotes)}\n</design_intent_notes>`,
+        `<expected_noise>\nConsole errors and failed requests matching these are expected and never a finding:\n${expectedNoiseForPrompt(localBrief && localBrief.expected_noise)}\n</expected_noise>`,
+        ...(account ? [`<test_account>\n${testAccountForPrompt(account)}\n</test_account>`] : []),
+        ...(identity ? [`<run_identity>\n${runIdentityForPrompt(identity, { testAccount: Boolean(account) })}\n</run_identity>`] : [])
       ].join('\n'),
       cache_control: { type: 'ephemeral' }
     }
   ];
 }
 
+/**
+ * The run id cut to something short enough for an email or a display name:
+ * the last eight letters and digits after the `pt_run_` prefix.
+ *
+ * @param {string} runId
+ * @returns {string}
+ */
+export function shortRunId(runId) {
+  const compact = String(runId == null ? '' : runId).replace(/^pt_run_/, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+  return compact.slice(-8);
+}
+
+/**
+ * A fresh identity for every run, so a sign-up form never sees an email an
+ * earlier run already registered. The Texas round lost actions to a 409 on
+ * sign-up from a reused address. `example.test` is a reserved name that never
+ * delivers mail.
+ *
+ * @param {{persona: {slug?: string, name?: string}, runId: string}} args
+ * @returns {{email: string, displayName: string, short: string}|null}
+ */
+export function runIdentity({ persona, runId }) {
+  const short = shortRunId(runId);
+  if (!short) return null;
+  const slug = String((persona && persona.slug) || 'player').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'player';
+  const name = String((persona && (persona.name || persona.slug)) || 'Player').replace(/\s+/g, ' ').trim().slice(0, 40) || 'Player';
+  return { email: `persona-${slug}-${short}@example.test`, displayName: `${name} ${short}`, short };
+}
+
+/**
+ * @param {{email: string, displayName: string}} identity
+ * @returns {string}
+ */
+export function runIdentityForPrompt(identity, { testAccount = false } = {}) {
+  return [
+    `email: ${identity.email}`,
+    `display_name: ${identity.displayName}`,
+    testAccount
+      ? 'Sign in with the test account above. Use this email and this display name only if you have to make a new account, and whenever a form asks for a display name, a coach or a player name. Never reuse an email from an earlier run.'
+      : 'Use this email and this display name whenever a form asks for an email, a name, a username or a coach or player name, unless the brief says otherwise. They are new for this run, so an account made with them does not exist yet. Never reuse an email from an earlier run.'
+  ].join('\n');
+}
+
+/**
+ * The local brief's test account, or null when it has none that can be used.
+ *
+ * @param {Object} localBrief
+ * @returns {{email: string, password: string, how_to_sign_in: string|null}|null}
+ */
+export function testAccountOf(localBrief) {
+  const account = localBrief && localBrief.test_account;
+  if (!account || typeof account !== 'object' || typeof account.email !== 'string' || !account.email || typeof account.password !== 'string' || account.password.length < MIN_PASSWORD_CHARS) return null;
+  return { email: account.email, password: account.password, how_to_sign_in: typeof account.how_to_sign_in === 'string' && account.how_to_sign_in.trim() ? account.how_to_sign_in.trim() : null };
+}
+
+/**
+ * The test account block of the persona prompt: an account the developer made
+ * so a run can start past sign up.
+ *
+ * @param {{email: string, password: string, how_to_sign_in: string|null}} account
+ * @returns {string}
+ */
+export function testAccountForPrompt(account) {
+  return [
+    `email: ${account.email}`,
+    `password: ${account.password}`,
+    ...(account.how_to_sign_in ? [`how_to_sign_in: ${account.how_to_sign_in}`] : []),
+    'This is a throwaway account the developer made for this playtest. Sign in with it rather than signing up, so your actions go to the game itself. Never write the password in a note or a report.'
+  ].join('\n');
+}
+
 /**
  * The brief as the persona skill expects it: the `fields` object the
  * expectations-brief schema describes, with the version alongside so a report
@@ -1073,11 +1373,54 @@ export function assistantContent(answer) {
   return content;
 }
 
-/** Keep the transcript readable without storing a whole screenshot in it. */
-function redactToolInput(toolUse) {
+/** What a typed secret is written as in the transcript and the action log. */
+export const REDACTED_SECRET = '[test password]';
+
+/**
+ * Every string in a value with each secret replaced by {@link REDACTED_SECRET},
+ * through arrays and plain objects. A new value; the input is not changed.
+ *
+ * @param {any} value
+ * @param {Array<string>} secrets
+ * @returns {any}
+ */
+export function scrubSecrets(value, secrets = []) {
+  if (!Array.isArray(secrets) || secrets.length === 0) return value;
+  if (typeof value === 'string') {
+    let text = value;
+    // Whole tokens only: the password with no letter, digit or underscore
+    // directly before or after it, so it is replaced where it was written
+    // (alone, quoted, after a colon) and never inside a longer word.
+    for (const secret of secrets) {
+      if (!secret) continue;
+      const escaped = secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      text = text.replace(new RegExp(`(?<![\\p{L}\\p{N}_])${escaped}(?![\\p{L}\\p{N}_])`, 'gu'), REDACTED_SECRET);
+    }
+    return text;
+  }
+  if (Array.isArray(value)) return value.map(entry => scrubSecrets(entry, secrets));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, scrubSecrets(entry, secrets)]));
+  return value;
+}
+
+/**
+ * The strings the transcript must not repeat: the local brief's test account
+ * password. It is in the prompt (that is how a persona can type it), but the
+ * transcript can be uploaded and the action log is shown in the report step.
+ *
+ * @param {Object} localBrief
+ * @returns {Array<string>}
+ */
+export function secretsOf(localBrief) {
+  const password = localBrief && localBrief.test_account && localBrief.test_account.password;
+  return typeof password === 'string' && password.length >= MIN_PASSWORD_CHARS ? [password] : [];
+}
+
+/** Keep the transcript readable without storing a whole screenshot in it, or a test account password. */
+export function redactToolInput(toolUse, secrets = []) {
   if (!toolUse.input) return null;
   const { thought_in_character: ignored, ...rest } = toolUse.input;
-  return rest;
+  return scrubSecrets(rest, secrets);
 }
 
 async function safeScreenshot(driver, name, screenshots, transcript, observation = null) {
@@ -1143,6 +1486,7 @@ async function finish(outcome, ledger, runDirectory, transcript, heartbeat) {
 export function renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason }) {
   const good = notes.filter(note => note.kind === 'good');
   const bad = notes.filter(note => note.kind === 'bug' || note.kind === 'confusing');
+  const network = notes.filter(note => note.automatic && note.url);
   const list = entries => (entries.length > 0
     ? entries.map(note => `- **${note.kind}${note.severity ? `/${note.severity}` : ''}**: ${note.text}`).join('\n')
     : '- Nothing was logged.');
@@ -1170,6 +1514,7 @@ export function renderFallbackMarkdown({ persona, driverName, target, notes, scr
     '## Suggested next step',
     'Run this persona again once the reason above is resolved.',
     '',
+    ...(network.length > 0 ? ['## Network notes', network.map(note => `- ${note.status ? `${note.status} ` : ''}${note.url}`).join('\n'), ''] : []),
     '## Evidence',
     screenshots.length > 0 ? screenshots.map(shot => `- ${shot.relativePath}`).join('\n') : '- (none)',
     ''
@@ -1218,6 +1563,8 @@ export function notesToFindings(notes, screenshots) {
     if (!category || !note.text) continue;
     // A blocker or major written on a driver error is the runner's failure.
     if (note.driver_error && ABOVE_MINOR.includes(note.severity)) continue;
+    // Console noise the developer said to expect is never a finding.
+    if (note.expected_noise) continue;
     const text = String(note.text);
     const shot = nearestScreenshot(note, screenshots);
     findings.push({
@@ -1296,6 +1643,7 @@ export function noteLine(note, i) {
   const tags = [
     note.automatic ? 'automatic' : null,
     note.driver_error ? 'written on a driver error' : null,
+    note.expected_noise ? 'expected noise' : null,
     Number.isInteger(note.observation) && note.observation > 0 ? `seen at observation ${note.observation}` : null,
     note.screenshot ? `screenshot ${note.screenshot}` : null
   ].filter(Boolean);
@@ -1368,8 +1716,8 @@ export function observationTitle(observation) {
  */
 /** How report.md lists what the runner dropped. */
 export const RUNNER_DROPPED_SECTION = Object.freeze({
-  heading: '## Dropped by the runner (driver errors or waiting notes only)',
-  explanation: 'The runner removes a blocker or major whose only cited observations are driver errors (the runner could not carry out an action; the game did nothing wrong), and any finding cited only by waiting notes. They are not sent to the server. They are kept here so you can judge them yourself.',
+  heading: '## Dropped by the runner (driver errors, waiting notes or expected noise only)',
+  explanation: 'The runner removes a blocker or major whose only cited observations are driver errors (the runner could not carry out an action; the game did nothing wrong), and any finding cited only by waiting notes or by console noise the brief says to expect. They are not sent to the server. They are kept here so you can judge them yourself.',
   emptyNote: '- Nothing here that the runner kept. See the dropped findings below.'
 });
 
@@ -1392,11 +1740,26 @@ export const RUNNER_DROPPED_SECTION = Object.freeze({
 export function dropRunnerRejectedFindings(report, { notes = [], observations = [] } = {}) {
   if (!report || !Array.isArray(report.findings)) return { report, dropped: [] };
   const byIndex = new Map(observations.map(entry => [entry.index, entry]));
+  // The runner's console-error screenshot of a moment whose every console
+  // note was expected noise says nothing more than those notes do.
+  const noiseShots = new Set();
+  const shotNotes = new Map();
+  for (const note of notes) {
+    if (!note || !note.automatic || !note.screenshot) continue;
+    if (!shotNotes.has(note.screenshot)) shotNotes.set(note.screenshot, []);
+    shotNotes.get(note.screenshot).push(note);
+  }
+  for (const [shot, attached] of shotNotes) if (attached.every(note => note.expected_noise)) noiseShots.add(shot);
   const verdict = finding => {
     const cited = [];
     for (const item of Array.isArray(finding.evidence) ? finding.evidence : []) {
-      if (!item || item.type !== 'transcript_step') continue;
+      if (!item) continue;
       const ref = String(item.ref || '');
+      if (item.type === 'screenshot') {
+        if (noiseShots.has(ref)) cited.push('noise');
+        continue;
+      }
+      if (item.type !== 'transcript_step') continue;
       const observation = ref.match(/^\s*observation\s*#?\s*(\d+)\s*$/i);
       const note = ref.match(/^\s*note\s*#?\s*(\d+)\s*$/i);
       if (observation) {
@@ -1404,7 +1767,7 @@ export function dropRunnerRejectedFindings(report, { notes = [], observations =
         cited.push(entry && entry.driver_error ? 'driver' : 'other');
       } else if (note) {
         const entry = notes[Number(note[1]) - 1];
-        cited.push(entry && entry.kind === 'waiting' ? 'waiting' : entry && entry.driver_error ? 'driver' : 'other');
+        cited.push(entry && entry.kind === 'waiting' ? 'waiting' : entry && entry.expected_noise ? 'noise' : entry && entry.driver_error ? 'driver' : 'other');
       } else {
         cited.push('other');
       }
@@ -1412,7 +1775,9 @@ export function dropRunnerRejectedFindings(report, { notes = [], observations =
     if (cited.length === 0) return null;
     if (ABOVE_MINOR.includes(finding.severity) && cited.every(kind => kind === 'driver')) return 'driver errors only';
     if (cited.every(kind => kind === 'waiting')) return 'waiting notes only';
-    if (ABOVE_MINOR.includes(finding.severity) && cited.every(kind => kind === 'driver' || kind === 'waiting')) return 'driver errors and waiting notes only';
+    if (cited.every(kind => kind === 'noise')) return 'expected console noise only';
+    if (cited.every(kind => kind === 'waiting' || kind === 'noise')) return 'expected console noise and waiting notes only';
+    if (ABOVE_MINOR.includes(finding.severity) && cited.every(kind => kind === 'driver' || kind === 'waiting' || kind === 'noise')) return 'driver errors, waiting notes and expected noise only';
     return null;
   };
   const dropped = [];
@@ -1425,6 +1790,273 @@ export function dropRunnerRejectedFindings(report, { notes = [], observations =
   return { report: dropped.length > 0 ? { ...report, findings } : report, dropped };
 }
 
+/** The most actions the report prompt lists; the newest are kept. */
+export const MAX_ACTIONS_IN_REPORT = 60;
+
+/** The longest typed text an action line repeats. */
+const MAX_TYPED_CHARS = 40;
+
+/**
+ * The names of the refs a compacted snapshot shows: `- button "Start" [e12]`
+ * gives e12 -> button "Start".
+ *
+ * @param {string} text
+ * @returns {Map<string, {role: string, name: string}>}
+ */
+export function refNamesFrom(text) {
+  const names = new Map();
+  for (const line of String(text == null ? '' : text).split('\n')) {
+    const match = line.match(/^\s*- ([a-z]+) "([^"]*)"(?: \[[^\]]*\])*? \[(e\d+)\]/);
+    if (match && match[2]) names.set(match[3], { role: match[1], name: match[2] });
+  }
+  return names;
+}
+
+/**
+ * Every action that went through, from the transcript's observation and
+ * action lines, with the name of what it targeted when the screen before it
+ * showed one.
+ *
+ * @param {Array<Object>} records transcript lines of kind observation and action, in order
+ * @returns {Array<{action: number, kind: string, target: string, name: string|null, ref: string|null, changed: boolean}>}
+ */
+export function actionLogFrom(records) {
+  const log = [];
+  let names = new Map();
+  // Observations are numbered as the report prompt numbers them: one per
+  // observation line, in order.
+  let observation = 0;
+  let previousText = '';
+  let pending = null;
+  for (const record of Array.isArray(records) ? records : []) {
+    if (!record) continue;
+    if (record.kind === 'observation') {
+      observation += 1;
+      const text = String(record.text == null ? '' : record.text);
+      if (pending) {
+        pending.observationAfter = observation;
+        pending.introducedError = introducesError(previousText, text);
+        pending = null;
+      }
+      previousText = text;
+      const next = refNamesFrom(text);
+      // An unchanged marker or a canvas shows no refs; the last names stand.
+      if (next.size > 0) names = next;
+      continue;
+    }
+    if (record.kind !== 'action') continue;
+    pending = null;
+    if (!record.ok || !ACTION_TOOLS.includes(record.tool)) continue;
+    const input = record.input || {};
+    const ref = typeof input.ref === 'string' && input.ref.trim() ? input.ref.trim() : null;
+    const known = ref ? names.get(ref) : null;
+    let name = known ? known.name : null;
+    let target;
+    if (record.tool === 'key') target = `key ${String(input.key || '')}`;
+    else if (record.tool === 'navigate') target = String(input.url || '');
+    else if (record.tool === 'swipe') target = `from (${input.x},${input.y}) to (${input.toX},${input.toY})`;
+    else {
+      const named = typeof input.target === 'string' && input.target.trim() ? input.target.trim() : null;
+      if (!name && named) {
+        const roleAndName = named.match(/^[a-z]+\s+"([^"]*)"$/);
+        name = roleAndName ? roleAndName[1] : named;
+      }
+      const where = known ? `${known.role} "${known.name}" [${ref}]` : ref ? `[${ref}]` : named || (Number.isFinite(Number(input.x)) && Number.isFinite(Number(input.y)) ? `(${input.x},${input.y})` : 'the focused element');
+      if (record.tool === 'type') {
+        const text = String(input.text == null ? '' : input.text);
+        target = `${JSON.stringify(text.length > MAX_TYPED_CHARS ? `${text.slice(0, MAX_TYPED_CHARS - 3)}...` : text)} into ${where}${input.replace ? ' (replacing)' : ''}${input.submit ? ' then Enter' : ''}`;
+      } else {
+        target = where;
+      }
+    }
+    const entry = { action: Number(record.actions) || log.length + 1, kind: record.tool, target, name, ref, changed: Boolean(record.changed), observationBefore: observation, observationAfter: null, introducedError: false };
+    log.push(entry);
+    pending = entry;
+  }
+  return log;
+}
+
+/** A line that reads as an error: an alert or a dialog, or error wording. */
+const ERROR_LINE = /^\s*- (?:alert|alertdialog|dialog)\b|\b(?:error|errors|failed|invalid)\b/i;
+
+/**
+ * Whether the screen after an action shows an alert, a dialog or error
+ * wording that the screen before it did not: a change, but not the one the
+ * persona wanted.
+ *
+ * @param {string} before
+ * @param {string} after
+ * @returns {boolean}
+ */
+export function introducesError(before, after) {
+  const seen = new Set(String(before || '').split('\n').map(line => line.trim()));
+  return String(after || '').split('\n').some(line => !seen.has(line.trim()) && ERROR_LINE.test(line));
+}
+
+/**
+ * The action log as the report prompt's numbered list, bounded to the newest
+ * {@link MAX_ACTIONS_IN_REPORT}.
+ *
+ * @param {Array<Object>} log
+ * @returns {string}
+ */
+export function actionLogLines(log) {
+  if (!Array.isArray(log) || log.length === 0) return '(none)';
+  const shown = log.slice(-MAX_ACTIONS_IN_REPORT);
+  const lines = shown.map(entry => `${entry.action}. ${entry.kind} ${entry.target}: ${entry.changed ? 'screen changed' : 'no change'}`);
+  if (shown.length < log.length) lines.unshift(`(the first ${log.length - shown.length} are left out)`);
+  return lines.join('\n');
+}
+
+/**
+ * The failed requests the runner recorded, one line each, for the report
+ * prompt's network notes.
+ *
+ * @param {Array<Object>} notes
+ * @returns {string}
+ */
+export function networkNoteLines(notes) {
+  const lines = [];
+  (notes || []).forEach((note, index) => {
+    if (!note || !note.automatic || !note.url) return;
+    lines.push(`- note ${index + 1}: ${note.status ? `${note.status} ` : ''}${note.url}`);
+  });
+  return lines.length > 0 ? lines.join('\n') : '(none)';
+}
+
+/**
+ * The "nothing happens" family: wording that says a control was used and
+ * produced nothing. Deliberately narrow; "cannot" or "fails" can be true of a
+ * control the persona clicked.
+ */
+const NOTHING_HAPPENED = /\b(?:did nothing|does nothing|never kicked off|never started|no response|nothing happened)\b/i;
+
+/** One step down the severity scale. Cosmetic and praise are never touched. */
+const DOWNGRADE = Object.freeze({ blocker: 'major', major: 'minor', minor: 'cosmetic' });
+
+/**
+ * Whether a text names a control as a whole word, ignoring case: "Play"
+ * matches "press Play" and never "Players".
+ *
+ * @param {string} text
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function namesControl(text, name) {
+  const value = String(name || '').trim();
+  if (value.length < 3) return false;
+  const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, 'iu').test(String(text || ''));
+}
+
+/**
+ * Downgrade, never drop, a finding the action log contradicts. All of these
+ * have to hold, or the severity is left alone:
+ *
+ * - its title or description is in the "nothing happens" family ("did
+ *   nothing", "does nothing", "never kicked off", "never started", "no
+ *   response", "nothing happened") and names a control, whole word, of at
+ *   least three characters;
+ * - the most recent click on that control changed the screen, and the screen
+ *   after it gained no alert, dialog or error wording;
+ * - that click happened at or after the latest observation the finding cites
+ *   (a finding citing no observation is left alone).
+ *
+ * The Texas round's report said the season was never kicked off, with the
+ * click on KICK OFF THE SEASON and a changed screen in its own transcript.
+ *
+ * @param {Object} report
+ * @param {Array<Object>} log from {@link actionLogFrom}
+ * @returns {{report: Object, downgraded: Array<{id: string, from: string, to: string, control: string, action: number, note: string}>}}
+ */
+export function downgradeContradictedFindings(report, log) {
+  if (!report || !Array.isArray(report.findings) || !Array.isArray(log) || log.length === 0) return { report, downgraded: [] };
+  const clicks = log.filter(entry => entry.kind === 'click' && entry.name && entry.name.trim().length >= 3);
+  if (clicks.length === 0) return { report, downgraded: [] };
+  const downgraded = [];
+  const findings = report.findings.map(finding => {
+    if (!finding || !DOWNGRADE[finding.severity]) return finding;
+    const text = `${finding.title || ''}\n${finding.description || ''}`;
+    if (!NOTHING_HAPPENED.test(text)) return finding;
+    const cited = (Array.isArray(finding.evidence) ? finding.evidence : [])
+      .map(item => (item && item.type === 'transcript_step' ? String(item.ref || '').match(/^\s*observation\s*#?\s*(\d+)\s*$/i) : null))
+      .filter(Boolean)
+      .map(match => Number(match[1]));
+    if (cited.length === 0) return finding;
+    const citedLatest = Math.max(...cited);
+    // The controls the finding names, each judged by its most recent click.
+    const named = [...new Set(clicks.map(entry => entry.name.trim().toLowerCase()))]
+      .filter(name => namesControl(text, name));
+    let hit = null;
+    for (const name of named) {
+      const latest = clicks.filter(entry => entry.name.trim().toLowerCase() === name).at(-1);
+      if (!latest.changed || latest.introducedError) continue;
+      if (!Number.isInteger(latest.observationBefore) || latest.observationBefore < citedLatest) continue;
+      hit = latest;
+      break;
+    }
+    if (!hit) return finding;
+    const to = DOWNGRADE[finding.severity];
+    const note = `the action log shows ${hit.name.trim()} clicked at step ${hit.action} with the screen changing`;
+    const description = String(finding.description || '');
+    downgraded.push({ id: finding.id, from: finding.severity, to, control: hit.name.trim(), action: hit.action, note });
+    return { ...finding, severity: to, description: description ? `${description}\n\nDowngraded by the runner: ${note}.` : `Downgraded by the runner: ${note}.` };
+  });
+  return { report: downgraded.length > 0 ? { ...report, findings } : report, downgraded };
+}
+
+/** How report.md lists the findings the runner downgraded. */
+export const DOWNGRADED_HEADING = '## Downgraded by the runner (the action log or its own screenshot contradicts the claim)';
+
+/**
+ * report.md agreeing with report.json about downgraded findings: on every
+ * line that names a downgraded finding's id, its old severity word becomes
+ * the new one, and a section lists each downgrade with the runner's note,
+ * replacing one written before.
+ *
+ * @param {string} markdown
+ * @param {Array<{id: string, from: string, to: string, note: string}>} downgraded
+ * @returns {string}
+ */
+export function rewriteDowngradedMarkdown(markdown, downgraded) {
+  if (!Array.isArray(downgraded) || downgraded.length === 0) return markdown;
+  const text = String(markdown || '');
+  const at = text.indexOf(`\n${DOWNGRADED_HEADING}`);
+  let body = (at === -1 ? (text.startsWith(DOWNGRADED_HEADING) ? '' : text) : text.slice(0, at)).replace(/\s+$/, '');
+  const recase = (word, to) => (word === word.toUpperCase() ? to.toUpperCase() : word[0] === word[0].toUpperCase() ? to[0].toUpperCase() + to.slice(1) : to);
+  const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const namesId = (line, id) => new RegExp(`(^|[^A-Za-z0-9])${escape(id)}(?![0-9])`).test(line);
+  // The finding a "Severity:" line belongs to: the one named by the nearest
+  // heading or list item above it. A heading naming none ends it.
+  let current = null;
+  body = body.split('\n').map(line => {
+    let out = line;
+    const named = downgraded.find(entry => entry.id && namesId(line, String(entry.id)));
+    if (named) current = named;
+    else if (/^#{1,6} /.test(line) || /^\s*(?:[-*+]|\d+[.)])\s+\S*\b[A-Z]\d{2,}\b/.test(line)) current = null;
+    for (const entry of downgraded) {
+      const id = String(entry.id || '');
+      if (!id) continue;
+      // Only the severity slot the writer labels: right after the id in
+      // parentheses or brackets ("F001 (major)", "**F001 [Major, bug]**"), or
+      // after "Severity:" within that finding. A title that happens to
+      // contain the word stays as written.
+      if (namesId(out, id)) {
+        out = out.replace(new RegExp(`(${escape(id)}\\**\\s*[([]\\s*)(${entry.from})\\b`, 'i'), (match, lead, word) => `${lead}${recase(word, entry.to)}`);
+      }
+      if (current === entry) {
+        out = out.replace(new RegExp(`(severity\\**\\s*:\\s*\\**\\s*)(${entry.from})\\b`, 'gi'), (match, lead, word) => `${lead}${recase(word, entry.to)}`);
+      }
+    }
+    return out;
+  }).join('\n');
+  const section = [
+    DOWNGRADED_HEADING,
+    ...downgraded.map(entry => `- ${entry.id}: ${entry.from} to ${entry.to}, because ${entry.note}.`)
+  ].join('\n');
+  return `${body}\n\n${section}\n`;
+}
+
 export function capNetworkOnlyFindings(report, { notes = [], screenshots = [] } = {}) {
   if (!report || !Array.isArray(report.findings)) return report;
   const byShot = new Map();