ravensight-playtest 0.2.7 → 0.2.8

package/README.md

@@ -206,6 +206,7 @@ splitting the job in two is what gets everything played.
 | `--upload-video` | Upload `session.webm` as well as the reports. |
 | `--upload-transcript` | Upload `transcript.jsonl` as well as the reports. |
 | `--dry-upload` | List every file and byte that would be sent, and send nothing. |
+| `--key-modifier <meta\|control>` | The modifier the browser driver uses for editing shortcuts such as select all. Defaults to this machine's own (Command on macOS, Control elsewhere); set it when the browser's platform is not this machine's. `RAVENSIGHT_KEY_MODIFIER` does the same. |
 | `--headed`, `--headless` | Show or hide the browser. |
 | `--verbose` | Print each turn. |
 
@@ -257,6 +258,38 @@ How the report step reads what happened:
 - The model is told never to write calendar dates. `report.md` carries the
   CLI's own `Generated at` timestamp under its title, and the aggregate report's
   header uses its `generated_at`.
+- A template slot the model copied instead of filling (`**Date:** <run date>`,
+  `<driver>`, `<N actions>`) is filled from the CLI's own facts, or "not
+  recorded" when it has none, in `report.md`, the prose of `report.json` and
+  the aggregate. Other angle brackets are left as written: keys such as
+  `<Enter>`, elements such as `<form>`, types such as `Array<string>`, links,
+  code and quoted game text.
+- The server keeps a finding only when one of its evidence references points
+  at a file the run uploaded. After delivery the CLI marks the findings it
+  dropped (by the server's `dropped_finding_ids`, or by applying the same rule
+  to the files it uploaded when its count matches): `dropped: true` in
+  `report.json`, out of the summary in `report.md` and into a section headed
+  "Dropped by the server (no usable evidence)", and out of the aggregate and
+  the synthetic telemetry, so the local report counts what the dashboard
+  counts. When it cannot tell which, `report.md` says how many and that the
+  dashboard is the record. The rewritten files are journalled as local edits,
+  and `upload <job>` never re-sends a completed run's report files.
+
+### What personas do well
+
+A persona plays like a first time player at human speed: menus, onboarding,
+the first few minutes, unclear text, screens that do not respond, and whether
+it would come back. On the web, when a persona replaces a field's value (the
+`type` tool with `replace`), the driver clears it with `fill`, the same way on
+macOS, Windows and Linux; ordinary typing is keystrokes. An editing shortcut
+such as select all uses the platform's own modifier (Command on a Mac, Control
+elsewhere, or `--key-modifier`).
+
+Each persona starts at the game's URL as a fresh player with no account, so a
+sign-up form with validation can use up a whole unit before the game itself is
+reached. Point `--build-url` at a guest or demo path, or say where to start in
+the brief's `how_to_start` note (for example "choose Play as guest"), when the
+sign-up is not what you want tested.
 
 ### fix
 
@@ -429,6 +462,7 @@ CI can treat 2 as a success with a warning.
 | `RAVENSIGHT_API_URL` | The API base URL. Defaults to `https://api.ravensight.io`. |
 | `RAVENSIGHT_DASHBOARD_URL` | Where the dashboard is, if it is not derivable from the API URL. |
 | `RAVENSIGHT_GAME_ID` | The game, when there is no linked repo. |
+| `RAVENSIGHT_KEY_MODIFIER` | `meta` or `control`: the browser driver's modifier for editing shortcuts, as `--key-modifier`. The flag wins when both are set. |
 | `RAVENSIGHT_INGEST_KEY` | The game's ingest key, so a web run can emit its synthetic session into your event stream. `ingest_key` in `.ravensight/config.json` does the same. Without either the run still reports; it just sends no telemetry. |
 | `RAVENSIGHT_GODOT` | Path to the Godot binary. Tried first, then `$GODOT`, then `$GODOT_PATH`, then the PATH, then the platform's usual install locations. `--godot-path` beats all of them. |
 | `RAVENSIGHT_FFMPEG` | Path to ffmpeg. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "AI personas play your game and file reports to Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",

package/src/cli.js

@@ -63,6 +63,7 @@ Run options (parsed by the runner, see src/run/args.js):
   --upload-video            upload session.webm as well as the reports
   --upload-transcript       upload transcript.jsonl as well as the reports
   --dry-upload              list every file and byte that would be sent, send nothing
+  --key-modifier <name>     meta or control: the modifier for editing shortcuts in the browser, default the platform's own
   --headed                  show the browser
   --headless                hide it
   --verbose                 print each turn

package/src/commands/run.js

@@ -13,6 +13,7 @@ import { jobDir, runDir as runDirFor, JOB_FILES, RUN_FILES } from '../run/paths.
 import { readBridgeConfig } from "../run/drivers/stdio.js";
 import { WEBDRIVER_NAMES, readDriverConfig } from '../run/drivers/webdriver.js';
 import { runPersona } from '../run/personaLoop.js';
+import { reconcileDroppedFindings } from '../run/dropped.js';
 import * as stateFile from '../run/state.js';
 import { emitRunEvents } from '../run/synthetic.js';
 
@@ -90,6 +91,8 @@ async function run(flags, injected, deps, log) {
   const { context, gameId, repoRoot, apiUrl, cliVersion, api } = setup;
 
   if (options.controller && !['standard', 'jev'].includes(options.controller)) { log('Choose --controller standard or --controller jev.'); return EXIT.ENVIRONMENT; }
+  const keyModifier = resolveKeyModifier(options.keyModifier);
+  if (keyModifier.error) { log(keyModifier.error); return EXIT.ENVIRONMENT; }
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
   const target = resolveTarget(options, context.config, driverName);
   if (!target) {
@@ -497,7 +500,7 @@ export async function playPersonaRun({
   // Headless is right for a browser and wrong for Godot: a headless Godot
   // routes no GUI input, so it is a smoke-test mode rather than a way to play.
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
-  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId }));
+  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId, keyModifier: options.keyModifier }));
   // The ledger is created here rather than inside the loop so the heartbeat
   // can feed it the server's own figure for what this run has spent. Prices
   // are server side only, so that answer is the only real one.
@@ -563,7 +566,7 @@ export async function playPersonaRun({
     const failed = error.outcome || { state: 'failed', quitReason: 'error', actionsTaken: 0, report: null, reportLint: [], reachedState: 'playing' };
     await stateFile.patchRun(repoRoot, journal, runId, { state: failed.state, error: String(error && error.message), quit_reason: failed.quitReason });
     const delivery = {};
-    const answer = await deliver({ deps, api, gameId, jobId, runId, directory, outcome: failed, options, log, delivery });
+    const answer = await deliver({ deps, api, gameId, jobId, runId, directory, outcome: failed, options, log, repoRoot, delivery });
     if (isReportStepBudget(failed)) {
       // The money ran out while the report was being written. The partial
       // report went up and the run is completed as budget_exceeded from
@@ -713,6 +716,7 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
     if (journal) await stateFile.patchRun(repoRoot, journal, runId, { uploaded: true, completed: true });
     if (answer && answer.dropped_findings > 0) {
       log(`run ${runId}: the server dropped ${answer.dropped_findings} finding(s) with no usable evidence.`);
+      await markDropped({ directory, jobId, runId, repoRoot, outcome, droppedCount: answer.dropped_findings, droppedIds: answer.dropped_finding_ids, options, log });
     }
     if (answer && Array.isArray(answer.report_lint) && answer.report_lint.length > 0) {
       log(`run ${runId}: report lint: ${answer.report_lint.join('; ')}`);
@@ -729,6 +733,28 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
   }
 }
 
+/**
+ * Bring the local report into line with what the server kept, so report.md,
+ * report.json, the aggregate and the telemetry count what the dashboard
+ * counts. A failure here never fails the delivery: the run is already
+ * complete on the server.
+ */
+async function markDropped({ directory, jobId, runId, repoRoot, outcome, droppedCount, droppedIds, options, log }) {
+  try {
+    const result = await reconcileDroppedFindings({ directory, droppedCount, droppedIds, options, journal: { jobId, runId, repoRoot } });
+    if (!result) return;
+    if (outcome) {
+      outcome.report = result.report;
+      outcome.reportMarkdown = result.markdown;
+    }
+    log(result.identified
+      ? `run ${runId}: marked ${result.dropped.join(', ')} as dropped in report.md and report.json, under "Dropped by the server".`
+      : `run ${runId}: could not tell which finding(s) the server dropped, so report.md says so and the dashboard is the record.`);
+  } catch (error) {
+    log(`run ${runId}: could not mark the dropped finding(s) in the local report (${String(error && error.message)}).`);
+  }
+}
+
 /**
  * Whether a run ran out of money in the report step: it is budget_exceeded
  * and the server had already accepted `reporting` (or `uploading`) for it.
@@ -1040,9 +1066,12 @@ export async function resolveSetup(deps, options, log) {
  *
  * @returns {Object}
  */
-export function driverOptions({ headless, driverName, target, directory, entry, jobId }) {
+export function driverOptions({ headless, driverName, target, directory, entry, jobId, keyModifier }) {
+  // Only the browser driver sends key chords with a modifier.
+  const modifier = driverName === 'playwright_web' ? resolveKeyModifier(keyModifier).modifier : null;
   return {
     headless,
+    ...(modifier ? { modifier } : {}),
     playtest: {
       token: entry.playtest_token || null,
       runId: entry.run_id,
@@ -1054,6 +1083,25 @@ export function driverOptions({ headless, driverName, target, directory, entry,
   };
 }
 
+/**
+ * The modifier the web driver uses for editing shortcuts, from
+ * `--key-modifier meta|control`, else `RAVENSIGHT_KEY_MODIFIER`, else the
+ * platform's own (Command on macOS, Control elsewhere, decided in the driver).
+ * For a remote or containerised browser whose platform is not this machine's.
+ *
+ * @param {string} [value] the flag's value
+ * @param {Object} [env]
+ * @returns {{modifier: 'Meta'|'Control'|null, error?: string}}
+ */
+export function resolveKeyModifier(value, env = process.env) {
+  const raw = value !== undefined && value !== null && value !== '' ? value : env.RAVENSIGHT_KEY_MODIFIER;
+  if (raw === undefined || raw === null || raw === '') return { modifier: null };
+  const key = String(raw).trim().toLowerCase();
+  if (['meta', 'cmd', 'command'].includes(key)) return { modifier: 'Meta' };
+  if (['control', 'ctrl'].includes(key)) return { modifier: 'Control' };
+  return { modifier: null, error: `Choose --key-modifier meta or --key-modifier control (or set RAVENSIGHT_KEY_MODIFIER), not "${raw}".` };
+}
+
 /**
  * The persona reports on disk, for the aggregate. A partial report (written
  * from the notes when the money ran out) is loaded as a `budget_exceeded`

package/src/commands/upload.js

@@ -8,6 +8,9 @@ import { pending } from '../upload/queue.js';
 import { uploadRunDir } from '../upload/index.js';
 import { JOB_UPLOAD_PATHS } from '../upload/allowlist.js';
 import { ui } from '../ui/index.js';
+
+/** Report files never re-sent for a run the journal marks completed. */
+const COMPLETED_RUN_REPORTS = Object.freeze(['report.md', 'report.json']);
 import { CliError, ExitCode } from '../errors.js';
 
 /**
@@ -73,11 +76,18 @@ async function drainJob(context, jobId, flags) {
   const results = [];
 
   for (const runId of runIds) {
+    // A completed run's report went to the server with `complete`, which
+    // validated it; the copy on disk may since have been marked locally
+    // (dropped findings), and sending it again would replace the validated
+    // artifact, or be refused once the job is closed.
+    const completed = Boolean(state && state.runs && state.runs[runId] && state.runs[runId].completed);
     const result = await uploadRunDir(paths.runDir(jobId, runId, { repoRoot }), {
       api: context.api,
       gameId,
       jobId,
       runId,
+      exclude: completed ? COMPLETED_RUN_REPORTS : null,
+      excludeReason: 'the run is complete; its report was delivered with complete',
       includeVideo,
       includeTranscript,
       dryRun: Boolean(flags.dryRun),

package/src/run/aggregate.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { fillPlaceholders } from './placeholders.js';
 import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseJsonArray, parseJsonObject } from './json.js';
@@ -331,7 +332,10 @@ export async function buildAggregate({
     persona: run.persona,
     state: run.state,
     report: run.report,
-    findings: run.report.findings || []
+    // A finding the server dropped for want of evidence is marked on disk
+    // after delivery (./dropped.js) and kept out of the aggregate, so the
+    // job report counts what the dashboard counts.
+    findings: (run.report.findings || []).filter(finding => !(finding && finding.dropped === true))
   }));
   const personasRun = new Set(inputs.map(run => run.persona).filter(Boolean)).size;
 
@@ -624,7 +628,9 @@ export function renderAggregateMarkdown(json) {
     ? `Observations dropped for lack of evidence:\n${json.observations.map(o => `- ${o.persona}: ${o.text}`).join('\n')}`
     : 'No dropped observations.');
   lines.push('');
-  return lines.join('\n');
+  // The synthesis writes the TL;DR, and a model can copy a template slot into
+  // it as easily as into a persona report.
+  return fillPlaceholders(lines.join('\n'), { generatedAt: json.generated_at, game: json.game_id });
 }
 
 /**

package/src/run/args.js

@@ -22,7 +22,8 @@ const VALUED = new Map([
   ['--cli', 'cli'],
   ['--max-actions', 'maxActions'],
   ['--concurrency', 'concurrency'],
-  ['--quality', 'quality']
+  ['--quality', 'quality'],
+  ['--key-modifier', 'keyModifier']
 ]);
 
 /** Options that are just present or absent. */

package/src/run/drivers/godot.js

@@ -360,6 +360,11 @@ export class GodotDriver {
     if (!action || typeof action.kind !== 'string') {
       return { ok: false, error: 'action needs a kind', changed: false };
     }
+    // Typing more characters is not replacing a value, and claiming it was
+    // would join the old text to the new one without saying so.
+    if (action.kind === 'type' && (action.replace || action.target)) {
+      return { ok: false, error: 'replace (empty a field, then type) and a typing target are only available on playwright_web; this driver can only type more text into what has focus', changed: false };
+    }
     try {
       await this._perform(action);
     } catch (error) {

package/src/run/drivers/stdio.js

@@ -79,6 +79,7 @@ export function createStdioDriver({ spawn: spawnImpl = spawn, timeoutMs = 30000
     observe,
     async act(action) {
       if (!['type', 'key', 'click', 'wait'].includes(action.kind)) return { ok: false, changed: false, error: 'Unsupported bridge action.' };
+      if (action.kind === 'type' && (action.replace || action.target)) return { ok: false, changed: false, error: 'replace (empty a field, then type) and a typing target are only available on playwright_web; this driver can only type more text into what has focus' };
       const before = lastHash;
       const safe = action.kind === 'type' ? { kind: 'type', text: String(action.text || '').slice(0, 2000), submit: Boolean(action.submit) }
         : action.kind === 'key' ? { kind: 'key', key: String(action.key || '').slice(0, 64) }

package/src/run/drivers/web.js

@@ -35,6 +35,12 @@ export const MAX_WAIT_MS = 10000;
 /** How long a single Playwright call may take before it is an error, not a hang. */
 export const ACTION_TIMEOUT_MS = 15000;
 
+/**
+ * How long a replace waits for a focused field. Short, because nothing
+ * focused is an ordinary answer (a canvas game), not a page still loading.
+ */
+export const FOCUSED_FILL_TIMEOUT_MS = 2000;
+
 /**
  * The web observation ceiling. An aria snapshot is re-sent on every turn the
  * observation stays in context, and the run's model budget is fixed, so a busy
@@ -116,6 +122,74 @@ export function unquoteKey(body) {
   return body;
 }
 
+/**
+ * The modifier a platform's editing shortcuts use: Command on macOS,
+ * Control everywhere else. Chromium follows the host's conventions even
+ * headless, so on a Mac `Control+A` in a text field moves the caret to the
+ * start of the line instead of selecting the text, and a persona that
+ * "selects all and retypes" ends up with two values joined together.
+ *
+ * @param {string} [platform] a `process.platform` value
+ * @returns {'Meta'|'Control'}
+ */
+export function platformModifier(platform = process.platform) {
+  return platform === 'darwin' ? 'Meta' : 'Control';
+}
+
+/** Editing shortcuts (select all, copy, cut, paste, undo, redo) that follow the platform modifier. */
+const EDITING_KEYS = new Set(['a', 'c', 'v', 'x', 'z', 'y']);
+
+/** Spellings a model writes for a modifier, mapped to Playwright's names. */
+const MODIFIER_ALIASES = Object.freeze({
+  ctrl: 'Control',
+  control: 'Control',
+  cmd: 'Meta',
+  command: 'Meta',
+  meta: 'Meta',
+  super: 'Meta',
+  win: 'Meta',
+  mod: 'ControlOrMeta',
+  controlormeta: 'ControlOrMeta',
+  alt: 'Alt',
+  option: 'Alt',
+  opt: 'Alt',
+  shift: 'Shift'
+});
+
+/**
+ * Rewrite a key chord the persona asked for into one that does the same
+ * thing on this machine.
+ *
+ * Modifier spellings are normalised (`Ctrl`, `Cmd`, `Option`), and an
+ * editing shortcut held with Control or Command (`Control+A`, `Cmd+V`,
+ * `Ctrl+Shift+Z`) uses the platform modifier, because the persona means
+ * "select all", not "the Control key". Any other chord is left as written:
+ * a game that binds Control+S to something of its own wants Control on
+ * every platform.
+ *
+ * @param {string} key
+ * @param {'Meta'|'Control'} modifier the platform modifier
+ * @returns {string}
+ */
+export function normalizeChord(key, modifier) {
+  const value = String(key == null ? '' : key);
+  // A lone "+" is the plus key, and "Shift++" is Shift and plus.
+  const parts = value.length > 1 ? value.split(/\+(?=.)/) : [value];
+  if (parts.length < 2) return value;
+  const mapped = parts.map((part, index) => {
+    if (index === parts.length - 1) return part;
+    return MODIFIER_ALIASES[part.trim().toLowerCase()] || part;
+  });
+  const last = mapped[mapped.length - 1];
+  const editing = EDITING_KEYS.has(String(last).toLowerCase());
+  return mapped.map((part, index) => {
+    if (index === mapped.length - 1) return part;
+    if (part === 'ControlOrMeta') return modifier;
+    if (editing && (part === 'Control' || part === 'Meta')) return modifier;
+    return part;
+  }).join('+');
+}
+
 const KNOWN_SELECTOR_ENGINES = /^(role|text|css|xpath|id|data-testid|internal:)=/;
 
 /**
@@ -231,9 +305,14 @@ function injectPlaytestIdentity(identity) {
  * @param {{token?: string, runId?: string, jobId?: string, persona?: string}} [opts.playtest]
  *   the run's playtest identity, handed to the page so the game's own SDK
  *   session is marked synthetic
+ * @param {string} [opts.platform] the host platform, `process.platform` by
+ *   default; decides the editing modifier
+ * @param {'Meta'|'Control'} [opts.modifier] the editing modifier, overriding
+ *   the one the platform implies
  * @returns {Object} a driver
  */
-export function createWebDriver({ importer, headless = true, playtest = null } = {}) {
+export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null } = {}) {
+  const editModifier = modifier === 'Meta' || modifier === 'Control' ? modifier : platformModifier(platform);
   let browser = null;
   let context = null;
   let page = null;
@@ -297,8 +376,42 @@ export function createWebDriver({ importer, headless = true, playtest = null } =
     return truncateObservation(snap.aria ? compactAriaSnapshot(snap.text) : snap.text, WEB_OBSERVATION_MAX_CHARS);
   }
 
+  /**
+   * Type, or with `replace` put this text in place of what the field holds.
+   *
+   * Replacing goes through Playwright's `fill`, which clears the field
+   * natively on every platform, rather than a select-all chord: the chord is
+   * Command+A on a Mac and Control+A elsewhere, and getting it wrong joins the
+   * old value to the new one. A target names the field; without one the
+   * focused element is filled. Only an element `fill` refuses (a canvas, a
+   * custom widget) falls back to the platform select-all, then typing.
+   *
+   * @param {any} current the page
+   * @param {{text: string, target?: string, replace?: boolean}} action
+   */
+  async function typeText(current, action) {
+    const text = String(action.text == null ? '' : action.text);
+    const field = action.target ? resolveLocator(current, action.target) : null;
+    if (action.replace) {
+      try {
+        await (field || current.locator('*:focus')).fill(text, { timeout: field ? ACTION_TIMEOUT_MS : FOCUSED_FILL_TIMEOUT_MS });
+        return;
+      } catch {
+        // Not something fill can write to. Focus it if it was named, then
+        // clear it the way a player on this machine would.
+        if (field) await field.click({ timeout: ACTION_TIMEOUT_MS });
+        await current.keyboard.press(`${editModifier}+a`);
+        await current.keyboard.press('Backspace');
+      }
+    } else if (field) {
+      await field.click({ timeout: ACTION_TIMEOUT_MS });
+    }
+    if (text) await current.keyboard.type(text, { delay: 20 });
+  }
+
   return {
     name: 'playwright_web',
+    editModifier,
     keepObservations: WEB_KEEP_OBSERVATIONS,
 
     /**
@@ -407,10 +520,10 @@ export function createWebDriver({ importer, headless = true, playtest = null } =
       try {
         switch (action.kind) {
           case 'key':
-            await current.keyboard.press(String(action.key), { timeout: ACTION_TIMEOUT_MS });
+            await current.keyboard.press(normalizeChord(action.key, editModifier), { timeout: ACTION_TIMEOUT_MS });
             break;
           case 'type':
-            await current.keyboard.type(String(action.text), { delay: 20 });
+            await typeText(current, action);
             if (action.submit) await current.keyboard.press('Enter');
             break;
           case 'click': {

package/src/run/drivers/webdriver.js

@@ -51,6 +51,7 @@ export function createWebDriverAdapter({name='desktop_driver',fetch:fetchImpl=gl
     }else if(action.kind==='swipe'){
      const from=point(action.from),to=point(action.to);await actions('pointer',[{type:'pointerMove',duration:0,origin:'viewport',...from},{type:'pointerDown',button:0},{type:'pointerMove',duration:Math.min(2000,Math.max(100,Number(action.durationMs)||500)),origin:'viewport',...to},{type:'pointerUp',button:0}],touch);
     }else if(action.kind==='key'||action.kind==='type'){
+     if(action.kind==='type'&&(action.replace||action.target))throw new DriverError('replace (empty a field, then type) and a typing target are only available on playwright_web; this driver can only type more text into what has focus');
      const chars=action.kind==='type'?Array.from(String(action.text||'').slice(0,2000)):[KEYS[action.key]||action.key];
      if(chars.some(key=>typeof key!=='string'||Array.from(key).length!==1))throw new DriverError('Unsupported device key.');
      if(action.submit)chars.push(KEYS.Enter);

package/src/run/dropped.js

@@ -0,0 +1,294 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256File } from '../fsutil.js';
+import { planRunDir } from '../upload/index.js';
+import { record, STATUS } from '../upload/queue.js';
+import { TRANSCRIPT_PATH, VIDEO_PATHS } from '../upload/allowlist.js';
+import { RUN_FILES } from './paths.js';
+import { fillPlaceholders } from './placeholders.js';
+import { writeReportFiles } from './report.js';
+
+/**
+ * Findings the server dropped, marked in the local report so it agrees with
+ * the dashboard.
+ *
+ * At `complete` the server keeps a finding only when at least one of its
+ * evidence refs resolves to a file the run actually uploaded, and answers
+ * with how many it dropped, not which. Without this step the CLI said "the
+ * server dropped 1 finding" while report.md and report.json still listed it,
+ * major severity and all, and the dashboard showed one fewer.
+ *
+ * The CLI uploaded the files itself, so it can apply the server's rule to
+ * the same list and name them. When its count matches the server's, each
+ * one is marked `dropped: true` in report.json and moved in report.md to a
+ * section of its own: kept for the developer to read, out of the top issues,
+ * the aggregate and the synthetic telemetry. When the counts disagree it
+ * does not guess which; it says how many the server dropped and points at
+ * the dashboard.
+ */
+
+/** The section dropped findings are moved to. */
+export const DROPPED_HEADING = '## Dropped by the server (no usable evidence)';
+
+/**
+ * The uploaded path, or candidate paths, an evidence entry needs. The same
+ * mapping as the server's `manifestPathForEvidence`.
+ *
+ * @param {{type?: string, ref?: string}} evidence
+ * @returns {string|Array<string>|null}
+ */
+export function evidencePath(evidence) {
+  if (!evidence || typeof evidence.type !== 'string') return null;
+  const ref = typeof evidence.ref === 'string' ? evidence.ref : '';
+  switch (evidence.type) {
+    case 'screenshot':
+      return ref || null;
+    case 'video_ts':
+      return [...VIDEO_PATHS];
+    case 'transcript_step':
+      return TRANSCRIPT_PATH;
+    case 'file_line':
+      return ref ? ref.split(':')[0] : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * The findings none of whose evidence resolves to an uploaded file.
+ *
+ * @param {Object} report
+ * @param {Iterable<string>} uploaded the run relative paths that were uploaded
+ * @returns {Array<Object>}
+ */
+export function unbackedFindings(report, uploaded) {
+  const paths = new Set(uploaded);
+  const findings = Array.isArray(report && report.findings) ? report.findings : [];
+  return findings.filter(finding => {
+    if (!finding || finding.dropped === true) return false;
+    const evidence = Array.isArray(finding.evidence) ? finding.evidence : [];
+    return !evidence.some(entry => {
+      const wanted = evidencePath(entry);
+      if (wanted === null) return false;
+      return (Array.isArray(wanted) ? wanted : [wanted]).some(candidate => paths.has(candidate));
+    });
+  });
+}
+
+/**
+ * report.json with the named findings marked.
+ *
+ * @param {Object} report
+ * @param {Set<string>} ids
+ * @returns {Object}
+ */
+export function markDroppedFindings(report, ids) {
+  return {
+    ...report,
+    findings: (report.findings || []).map(finding => (finding && ids.has(finding.id) ? { ...finding, dropped: true } : finding))
+  };
+}
+
+const SECTION = /^## /;
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
+
+/**
+ * report.md with the dropped findings out of the summary and in a section of
+ * their own.
+ *
+ * A list item that names a dropped finding id and no kept one is removed
+ * wherever it is, which is how "Top issues" names them (`F003 ...`). A
+ * section left with nothing under it says so. Then the dropped findings are
+ * listed under {@link DROPPED_HEADING}, replacing one written before, so a
+ * second reconcile does not stack them.
+ *
+ * @param {string} markdown
+ * @param {Array<Object>} dropped the dropped findings, from report.json
+ * @param {Array<Object>} kept the findings the server kept
+ * @param {{unidentified?: number}} [opts] a count the CLI could not attribute
+ * @returns {string}
+ */
+export function rewriteMarkdown(markdown, dropped, kept, { unidentified = 0 } = {}) {
+  const lines = withoutDroppedSection(String(markdown || '').replace(/\s+$/, '')).split('\n');
+  const droppedIds = dropped.map(finding => String(finding.id)).filter(Boolean);
+  const keptIds = kept.map(finding => String(finding.id)).filter(Boolean);
+  const names = (line, id) => new RegExp(`(^|[^A-Za-z0-9])${escapeRegExp(id)}(?![0-9])`).test(line);
+
+  const out = [];
+  let section = null;
+  let sectionRemoved = 0;
+  let sectionKept = 0;
+  const closeSection = () => {
+    if (section !== null && sectionRemoved > 0 && sectionKept === 0) {
+      // Trailing blank lines stay after the note, as they were after the list.
+      let blanks = 0;
+      while (out.length > 0 && out[out.length - 1].trim() === '') {
+        out.pop();
+        blanks += 1;
+      }
+      out.push('- Nothing here that the server kept. See the dropped findings below.');
+      for (let i = 0; i < blanks; i += 1) out.push('');
+    }
+  };
+  for (const line of lines) {
+    if (SECTION.test(line)) {
+      closeSection();
+      section = line;
+      sectionRemoved = 0;
+      sectionKept = 0;
+      out.push(line);
+      continue;
+    }
+    if (LIST_ITEM.test(line) && droppedIds.some(id => names(line, id)) && !keptIds.some(id => names(line, id))) {
+      sectionRemoved += 1;
+      continue;
+    }
+    if (LIST_ITEM.test(line)) sectionKept += 1;
+    out.push(line);
+  }
+  closeSection();
+
+  const tail = ['', DROPPED_HEADING];
+  if (dropped.length > 0) {
+    tail.push(
+      'The server keeps a finding only when at least one of its evidence references points at a file this run uploaded. These did not, so the dashboard does not show them and they are not counted. They are kept here so you can judge them yourself.',
+      ''
+    );
+    for (const finding of dropped) {
+      const evidence = (Array.isArray(finding.evidence) ? finding.evidence : [])
+        .map(entry => `${entry && entry.type} ${entry && entry.ref}`)
+        .join(', ') || 'none';
+      // The title is the model's prose, copied here; fill any slot it carries first.
+      tail.push(`- ${finding.id} (${finding.severity}, ${finding.category}): ${fillPlaceholders(String(finding.title || ''))}. Evidence cited: ${evidence}.`);
+    }
+  }
+  if (unidentified > 0) {
+    tail.push(
+      `The server dropped ${unidentified} finding(s) with no usable evidence, and this report could not tell which, so every finding above is still listed and counted here. The dashboard shows the findings the server kept.`
+    );
+  }
+  return `${out.join('\n')}\n${tail.join('\n')}\n`;
+}
+
+/**
+ * Remove a dropped section written by an earlier reconcile.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+function withoutDroppedSection(markdown) {
+  const lines = markdown.split('\n');
+  const start = lines.findIndex(line => line.trim() === DROPPED_HEADING);
+  if (start === -1) return markdown;
+  let end = lines.findIndex((line, index) => index > start && SECTION.test(line));
+  if (end === -1) end = lines.length;
+  return [...lines.slice(0, start), ...lines.slice(end)].join('\n').replace(/\s+$/, '');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Mark the findings the server dropped in a run directory's report files.
+ *
+ * The server's own list (`dropped_finding_ids`) is used when it sends one.
+ * Without it the CLI applies the server's evidence rule to its upload plan,
+ * and marks only when that count matches the server's. Findings marked by an
+ * earlier reconcile count towards the server's number, so running it twice
+ * changes nothing.
+ *
+ * Rewriting the two files changes their sha256, which would make `upload
+ * <job>` send them again over the validated artifacts. So each new hash is
+ * recorded in the job's upload journal as a local edit, which the journal
+ * treats as already delivered.
+ *
+ * @param {Object} args
+ * @param {string} args.directory the run directory
+ * @param {number} args.droppedCount `dropped_findings` from the complete answer
+ * @param {Array<string>} [args.droppedIds] `dropped_finding_ids` from the complete answer, when the server sends it
+ * @param {{uploadVideo?: boolean, uploadTranscript?: boolean}} [args.options] what was uploaded
+ * @param {{jobId: string, runId: string, repoRoot?: string}} [args.journal] where to record the local edit
+ * @param {(dir: string, opts: Object) => Promise<{files: Array<{path: string}>}>} [args.plan] test seam
+ * @returns {Promise<{report: Object, markdown: string, identified: boolean, dropped: Array<string>, source: string}|null>}
+ *   null when there was nothing to mark or no report on disk
+ */
+export async function reconcileDroppedFindings({ directory, droppedCount, droppedIds = null, options = {}, journal = null, plan = planRunDir }) {
+  const serverIds = Array.isArray(droppedIds) ? droppedIds.map(String).filter(Boolean) : null;
+  const count = serverIds && serverIds.length > 0 ? serverIds.length : Number(droppedCount) || 0;
+  if (count <= 0) return null;
+  let report;
+  let markdown;
+  try {
+    report = JSON.parse(await readFile(path.join(directory, RUN_FILES.reportJson), 'utf8'));
+    markdown = await readFile(path.join(directory, RUN_FILES.reportMd), 'utf8');
+  } catch {
+    return null;
+  }
+  if (!report || !Array.isArray(report.findings)) return null;
+
+  const already = report.findings.filter(finding => finding && finding.dropped === true).map(finding => finding.id);
+  let ids;
+  let identified;
+  let source;
+  if (serverIds && serverIds.length > 0) {
+    const present = new Set(report.findings.filter(Boolean).map(finding => finding.id));
+    ids = new Set(serverIds.filter(id => present.has(id)));
+    identified = ids.size === serverIds.length;
+    source = 'server';
+  } else {
+    const planned = await plan(directory, { video: Boolean(options.uploadVideo), transcript: Boolean(options.uploadTranscript) });
+    const unbacked = unbackedFindings(report, planned.files.map(file => file.path)).map(finding => finding.id);
+    identified = already.length + unbacked.length === count;
+    ids = new Set(identified ? [...already, ...unbacked] : already);
+    source = 'plan';
+  }
+  const marked = markDroppedFindings(report, ids);
+  const dropped = marked.findings.filter(finding => finding && finding.dropped === true);
+  const kept = marked.findings.filter(finding => !(finding && finding.dropped === true));
+  const rewritten = rewriteMarkdown(markdown, dropped, kept, { unidentified: identified ? 0 : count - dropped.length });
+  await writeReportFiles({ runDirectory: directory, markdown: rewritten, report: marked });
+  await recordLocalEdits(directory, journal);
+  return { report: marked, markdown: rewritten, identified, dropped: [...ids], source };
+}
+
+/**
+ * Record the rewritten report files' hashes as local edits, so the upload
+ * journal treats them as delivered rather than owed.
+ *
+ * @param {string} directory
+ * @param {{jobId: string, runId: string, repoRoot?: string}|null} journal
+ */
+async function recordLocalEdits(directory, journal) {
+  const where = journal && journal.jobId && journal.repoRoot ? journal : journalFromDirectory(directory) || (journal && journal.jobId ? journal : null);
+  if (!where) return;
+  for (const name of [RUN_FILES.reportMd, RUN_FILES.reportJson]) {
+    const file = path.join(directory, name);
+    const info = await stat(file);
+    await record(where.jobId, {
+      kind: 'run',
+      run_id: where.runId,
+      path: name,
+      sha256: await sha256File(file),
+      size: info.size,
+      status: STATUS.LOCAL_EDIT,
+      detail: 'dropped findings marked after complete; the delivered copy stays the record'
+    }, where.repoRoot ? { repoRoot: where.repoRoot } : {});
+  }
+}
+
+/**
+ * The job, run and repository a run directory belongs to, from its own path
+ * (`<repo>/.ravensight/jobs/<jobId>/runs/<runId>`), or null for any other.
+ *
+ * @param {string} directory
+ * @returns {{jobId: string, runId: string, repoRoot: string}|null}
+ */
+export function journalFromDirectory(directory) {
+  const parts = path.resolve(directory).split(path.sep);
+  const n = parts.length;
+  if (n < 6 || parts[n - 2] !== 'runs' || parts[n - 4] !== 'jobs' || parts[n - 5] !== '.ravensight') return null;
+  return { jobId: parts[n - 3], runId: parts[n - 1], repoRoot: parts.slice(0, n - 5).join(path.sep) || path.sep };
+}
+
+export default { reconcileDroppedFindings, unbackedFindings, markDroppedFindings, rewriteMarkdown, evidencePath, DROPPED_HEADING };

package/src/run/personaLoop.js

@@ -11,6 +11,7 @@ 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';
 
 /**
  * One persona's playthrough: PLAYING then REPORTING (spec 03).
@@ -651,7 +652,8 @@ async function reportPhase({
         '',
         '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"}.',
         '',
-        'Never write calendar dates or times in the prose of report.md or report.json. The runner stamps when the report was generated.',
+        'Never write calendar dates or times in the prose of report.md or report.json. The runner stamps when the report was generated, so leave the template\'s Date out rather than writing a placeholder for it.',
+        'Replace every <...> slot in the template with real content. Never copy a <...> placeholder into the report.',
         '',
         'Screenshots available as evidence (use these exact paths in evidence refs):',
         screenshots.length > 0 ? screenshots.map(shot => `- ${shot.relativePath}${shot.reason ? ` (${shot.reason})` : ''}`).join('\n') : '(none)',
@@ -764,7 +766,11 @@ async function reportPhase({
   if (!markdown) {
     markdown = renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason: 'The report step wrote report.json but no report.md.' });
   }
-  markdown = stampGeneratedAt(markdown, new Date().toISOString());
+  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 });
 
   await writeReportFiles({ runDirectory, markdown, report });
   return { report, markdown, lint };
@@ -1083,14 +1089,14 @@ async function writePartialReport({ outcome, runDirectory, persona, driverName,
     play,
     reason: 'The run reached its model budget before the report step. What the persona saw is below, and report.json carries the notes as unreviewed findings.'
   });
-  const stamped = stampGeneratedAt(markdown, new Date().toISOString());
+  const stamped = stampGeneratedAt(markdown, new Date().toISOString(), reportFacts({ persona, driverName, target, play }));
   await writeReportFiles({ runDirectory, markdown: stamped, report });
   outcome.report = report;
   outcome.reportMarkdown = stamped;
 }
 
 async function writePartialMarkdown({ runDirectory, persona, driverName, target, notes, screenshots, play, reason }) {
-  const markdown = stampGeneratedAt(renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason }), new Date().toISOString());
+  const markdown = stampGeneratedAt(renderFallbackMarkdown({ persona, driverName, target, notes, screenshots, play, reason }), new Date().toISOString(), reportFacts({ persona, driverName, target, play }));
   assertNoSecrets('report.md', markdown);
   await writeFile(path.join(runDirectory, RUN_FILES.reportMd), markdown, 'utf8');
 }
@@ -1216,13 +1222,32 @@ export function capNetworkOnlyFindings(report, { notes = [], screenshots = [] }
  * @param {string} generatedAt an ISO timestamp
  * @returns {string}
  */
-export function stampGeneratedAt(markdown, generatedAt) {
+export function stampGeneratedAt(markdown, generatedAt, facts = {}) {
   const line = `**Generated at:** ${generatedAt}`;
   const lines = String(markdown || '').split('\n').filter(entry => !/^\*\*Generated at:\*\* /.test(entry));
   const heading = lines.findIndex(entry => /^# /.test(entry));
-  if (heading === -1) return [line, '', ...lines].join('\n');
-  lines.splice(heading + 1, 0, line);
-  return lines.join('\n');
+  if (heading === -1) lines.unshift(line, '');
+  else lines.splice(heading + 1, 0, line);
+  // The template's own slots (`**Date:** <date>`) are filled from what the
+  // runner knows, because the prompt forbids the model a calendar date and a
+  // model that obeys both writes the placeholder itself.
+  return fillPlaceholders(lines.join('\n'), { generatedAt, ...facts });
+}
+
+/**
+ * What the runner knows about a run, for the template slots a report left
+ * unfilled.
+ *
+ * @returns {{driver: string, target: string, persona: string, actionsTaken: number, quitReason: string}}
+ */
+function reportFacts({ persona, driverName, target, play }) {
+  return {
+    driver: driverName,
+    target,
+    persona: persona ? persona.name || persona.slug : undefined,
+    actionsTaken: play ? play.actionsTaken : undefined,
+    quitReason: play ? play.quitReason : undefined
+  };
 }
 
 /**

package/src/run/placeholders.js

@@ -0,0 +1,186 @@
+/**
+ * Template placeholders a model copied into a report instead of filling.
+ *
+ * The persona skill's report template reads `**Date:** <date> ...`, and the
+ * report prompt says never to write a calendar date, so a model that obeys
+ * both writes the placeholder itself (`<run date>`) and the developer reads
+ * it as the report's date.
+ *
+ * Deliberately narrow, because angle brackets in a report are usually real:
+ * a key (`<Enter>`, `<Ctrl+A>`), an element (`<form>`, `<title>`), a type
+ * (`Array<string>`), a link, or the game's own text. So only two things are
+ * treated as a slot:
+ *
+ * 1. A slot the runner knows (date, driver, target, persona, actions, quit
+ *    reason, game, version), filled from its own facts, or "not recorded"
+ *    when it has no value for it.
+ * 2. Lowercase words in brackets on a `**Field:**` line, the shape of the
+ *    template's header, which become "not recorded".
+ *
+ * Never touched: a `<` straight after a word character, a key name, anything
+ * quoted, HTML, autolinks, code spans and fenced blocks.
+ */
+
+/** What a slot with no value becomes. */
+export const NOT_RECORDED = 'not recorded';
+
+const HTML_TAGS = new Set([
+  'a', 'abbr', 'article', 'aside', 'b', 'blockquote', 'body', 'br', 'button', 'canvas', 'caption', 'code', 'dd', 'del',
+  'details', 'dialog', 'div', 'dl', 'dt', 'em', 'figcaption', 'figure', 'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5',
+  'h6', 'head', 'header', 'hr', 'html', 'i', 'iframe', 'img', 'input', 'ins', 'kbd', 'label', 'li', 'link', 'main', 'mark',
+  'meta', 'nav', 'ol', 'option', 'p', 'picture', 'pre', 'q', 's', 'samp', 'script', 'section', 'select', 'small',
+  'source', 'span', 'strong', 'style', 'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'template', 'textarea',
+  'tfoot', 'th', 'thead', 'title', 'tr', 'u', 'ul', 'video'
+]);
+
+const KEY_NAMES = new Set([
+  'enter', 'return', 'tab', 'space', 'spacebar', 'esc', 'escape', 'backspace', 'delete', 'del', 'insert', 'home', 'end',
+  'pageup', 'pagedown', 'up', 'down', 'left', 'right', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright', 'shift',
+  'ctrl', 'control', 'alt', 'option', 'cmd', 'command', 'meta', 'super', 'win', 'fn', 'capslock'
+]);
+
+/** `<...>` with no nested bracket and no line break, short enough to be a template slot. */
+const ANGLE = /<([^<>\n]{1,80})>/g;
+
+/** A line in the template's header shape: `**Date:** ...`. */
+const FIELD_LINE = /\*\*[^*\n]+:\*\*/;
+
+const QUOTES = { '"': '"', "'": "'", '“': '”', '‘': '’', '`': '`' };
+
+function normalise(inner) {
+  return String(inner).trim().toLowerCase().replace(/[_-]+/g, ' ').replace(/\s+/g, ' ');
+}
+
+/**
+ * Whether the bracket is a slot the runner knows, and its value if it has one.
+ *
+ * @param {string} inner
+ * @param {Object} facts
+ * @returns {{known: boolean, value: string|null}}
+ */
+function knownSlot(inner, facts) {
+  const key = normalise(inner);
+  const date = facts.generatedAt ? String(facts.generatedAt).slice(0, 10) : null;
+  const actions = facts.actionsTaken === null || facts.actionsTaken === undefined || !Number.isFinite(Number(facts.actionsTaken))
+    ? null
+    : Number(facts.actionsTaken);
+  const slot = value => ({ known: true, value: value === null || value === undefined || value === '' ? null : String(value) });
+  if (/^(run |report |session )?(date|timestamp|date and time)$/.test(key) || key === 'generated at') return slot(date);
+  if (/^driver( name)?$/.test(key)) return slot(facts.driver);
+  if (/^(target|target url|build url|game url)$/.test(key)) return slot(facts.target);
+  if (/^persona( name| slug)?$/.test(key)) return slot(facts.persona);
+  if (/^(n|number of) actions$/.test(key)) return slot(actions === null ? null : `${actions} actions`);
+  if (key === 'actions taken') return slot(actions);
+  if (/^(quit|stop) reason$/.test(key)) return slot(facts.quitReason);
+  if (key === 'game' || key === 'game name') return slot(facts.game);
+  if (key === 'version' || key === 'game version') return slot(facts.version);
+  return { known: false, value: null };
+}
+
+/**
+ * The replacement for one bracket match, or null to leave it as written.
+ *
+ * @param {string} text the prose segment the match is in
+ * @param {string} whole the match, brackets included
+ * @param {string} inner
+ * @param {number} offset
+ * @param {string} line the whole line, for the field check
+ * @param {Object} facts
+ * @returns {string|null}
+ */
+function replacementFor(text, whole, inner, offset, line, facts) {
+  const before = text[offset - 1];
+  const after = text[offset + whole.length];
+  // `Array<string>`, `Map<K, V>`: a type, not a slot.
+  if (before !== undefined && /\w/.test(before)) return null;
+  // The game's own words, quoted as evidence.
+  if (before !== undefined && QUOTES[before] !== undefined && QUOTES[before] === after) return null;
+  const value = String(inner).trim();
+  if (!/^[A-Za-z]/.test(value)) return null;
+  // A key or a chord: <Enter>, <Ctrl+A>, <Shift + Tab>.
+  if (value.includes('+') || KEY_NAMES.has(value.toLowerCase())) return null;
+  const known = knownSlot(value, facts);
+  if (known.known) return known.value || NOT_RECORDED;
+  if (FIELD_LINE.test(line) && /^[a-z]+(?: [a-z]+)*$/.test(value) && !HTML_TAGS.has(value)) return NOT_RECORDED;
+  return null;
+}
+
+/**
+ * Walk the prose of a markdown document (not fenced blocks, not code spans),
+ * handing each segment and its whole line to `fn`.
+ *
+ * @param {string} markdown
+ * @param {(text: string, line: string) => string} fn
+ * @returns {string}
+ */
+function mapProse(markdown, fn) {
+  let fenced = false;
+  return String(markdown == null ? '' : markdown).split('\n').map(line => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return line;
+    }
+    if (fenced) return line;
+    return line.split(/(`[^`]*`)/).map(part => (part.length > 1 && part.startsWith('`') && part.endsWith('`') ? part : fn(part, line))).join('');
+  }).join('\n');
+}
+
+/**
+ * Fill the slots the runner knows, and the header fields it does not, from
+ * its own facts. Everything else in angle brackets is left as written.
+ *
+ * @param {string} markdown
+ * @param {{generatedAt?: string, driver?: string, target?: string, persona?: string,
+ *   actionsTaken?: number, quitReason?: string, game?: string, version?: string}} [facts]
+ * @returns {string}
+ */
+export function fillPlaceholders(markdown, facts = {}) {
+  return mapProse(markdown, (text, line) => text.replace(ANGLE, (whole, inner, offset) => {
+    const replacement = replacementFor(text, whole, inner, offset, line, facts);
+    return replacement === null ? whole : replacement;
+  }));
+}
+
+/**
+ * Every slot `fillPlaceholders` would still replace, for tests and a last check.
+ *
+ * @param {string} markdown
+ * @returns {Array<string>}
+ */
+export function findPlaceholders(markdown) {
+  const found = [];
+  mapProse(markdown, (text, line) => {
+    for (const match of text.matchAll(ANGLE)) {
+      if (replacementFor(text, match[0], match[1], match.index, line, {}) !== null) found.push(match[0]);
+    }
+    return text;
+  });
+  return found;
+}
+
+/**
+ * The same filling over the prose fields of report.json, which the dashboard
+ * shows: titles, descriptions, repro steps and quotes.
+ *
+ * @param {Object} report
+ * @param {Object} [facts]
+ * @returns {Object}
+ */
+export function fillReportPlaceholders(report, facts = {}) {
+  if (!report || !Array.isArray(report.findings)) return report;
+  const fill = value => (typeof value === 'string' ? fillPlaceholders(value, facts) : value);
+  return {
+    ...report,
+    findings: report.findings.map(finding => {
+      if (!finding || typeof finding !== 'object') return finding;
+      const out = { ...finding };
+      for (const field of ['title', 'description', 'persona_quote']) {
+        if (field in out) out[field] = fill(out[field]);
+      }
+      if (Array.isArray(out.repro_steps)) out.repro_steps = out.repro_steps.map(fill);
+      return out;
+    })
+  };
+}
+
+export default { fillPlaceholders, findPlaceholders, fillReportPlaceholders, NOT_RECORDED };

package/src/run/resume.js

@@ -3,6 +3,7 @@ import { getDeps } from './deps.js';
 import EXIT from './exit.js';
 import { runDir as runDirFor } from './paths.js';
 import { buildPartialReport, readTranscript, shouldFinalize } from './regenerate.js';
+import { reconcileDroppedFindings } from './dropped.js';
 import { createReportValidator, writeReportFiles } from './report.js';
 import * as stateFile from './state.js';
 import { playJob, resolvePersonas } from '../commands/run.js';
@@ -221,7 +222,7 @@ async function finalizeFromTranscript({ deps, api, gameId, jobId, repoRoot, row,
     // `interrupted` can go to `reporting`, which is where this run actually is:
     // it has a report now. Then `uploading`, then the delivery.
     await api.runs.transition(gameId, jobId, row.run_id, 'reporting', { reason: 'rebuilt from transcript' });
-    await deps.finalizeRun(directory, {
+    const answer = await deps.finalizeRun(directory, {
       api,
       gameId,
       jobId,
@@ -237,6 +238,20 @@ async function finalizeFromTranscript({ deps, api, gameId, jobId, repoRoot, row,
         report_md: markdown
       }
     });
+    if (answer && answer.dropped_findings > 0) {
+      log(`run ${row.run_id}: the server dropped ${answer.dropped_findings} finding(s) with no usable evidence.`);
+      try {
+        await reconcileDroppedFindings({
+          directory,
+          droppedCount: answer.dropped_findings,
+          droppedIds: answer.dropped_finding_ids,
+          options,
+          journal: { jobId, runId: row.run_id, repoRoot }
+        });
+      } catch (markError) {
+        log(`run ${row.run_id}: could not mark the dropped finding(s) in the local report (${String(markError && markError.message)}).`);
+      }
+    }
   } catch (error) {
     log(`run ${row.run_id}: could not be finalised (${String(error && error.message)}); it will be replayed.`);
     return false;

package/src/run/synthetic.js

@@ -193,6 +193,8 @@ export async function emitRunEvents({ apiUrl, ingestKey, playtestToken, pageSdk
 
     session.track('playtest_run_started', { driver });
     for (const finding of Array.isArray(report && report.findings) ? report.findings : []) {
+      // The server kept no record of a dropped finding, so neither does the game's telemetry.
+      if (finding && finding.dropped === true) continue;
       session.track('playtest_finding', {
         finding_id: finding.id,
         severity: finding.severity,

package/src/run/tools.js

@@ -86,7 +86,7 @@ export const PLAY_TOOLS = Object.freeze([
   },
   {
     name: 'type',
-    description: 'Type text. Spends an action. Set submit to press Enter afterwards.',
+    description: 'Type text. Spends an action. Set submit to press Enter afterwards. To correct or clear a text field, set replace: the field is emptied first and holds only this text afterwards (an empty text clears it). Do that rather than a select-all key chord, which differs between platforms.',
     input_schema: {
       type: 'object',
       additionalProperties: false,
@@ -94,6 +94,8 @@ export const PLAY_TOOLS = Object.freeze([
       properties: {
         text: { type: 'string' },
         submit: { type: 'boolean' },
+        replace: { type: 'boolean', description: 'Empty the field first, so it holds only this text. playwright_web only; other drivers refuse it.' },
+        target: { type: 'string', description: 'playwright_web only, other drivers refuse it: the field to type into, named like a click target, such as textbox "Email". Without it, the focused field.' },
         thought_in_character: thought,
         note
       }
@@ -101,7 +103,7 @@ export const PLAY_TOOLS = Object.freeze([
   },
   {
     name: 'key',
-    description: 'Press one key. Spends an action. Names are the usual ones: Enter, Space, ArrowUp, Escape, a, 1.',
+    description: 'Press one key. Spends an action. Names are the usual ones: Enter, Space, ArrowUp, Escape, a, 1. Hold a modifier with +, such as Shift+Tab; editing shortcuts such as Control+A are sent with this platform\'s own modifier. To clear a text field, use type with replace instead.',
     input_schema: {
       type: 'object',
       additionalProperties: false,
@@ -187,8 +189,12 @@ export function actionFor(toolUse) {
       return Number.isFinite(Number(input.x)) && Number.isFinite(Number(input.y))
         ? { kind: 'click', target: { x: Number(input.x), y: Number(input.y) } }
         : { kind: 'click', target: String(input.target || '') };
-    case 'type':
-      return { kind: 'type', text: String(input.text || ''), submit: Boolean(input.submit) };
+    case 'type': {
+      const action = { kind: 'type', text: String(input.text || ''), submit: Boolean(input.submit) };
+      if (input.replace === true) action.replace = true;
+      if (typeof input.target === 'string' && input.target.trim()) action.target = input.target;
+      return action;
+    }
     case 'key':
       return { kind: 'key', key: String(input.key || '') };
     case 'navigate':

package/src/upload/index.js

@@ -274,7 +274,7 @@ export async function uploadRunDir(runDir, options) {
   const {
     api, gameId, jobId, runId = null,
     includeVideo = false, includeTranscript = false,
-    dryRun = false, force = false, only = null, allowedPaths = null,
+    dryRun = false, force = false, only = null, allowedPaths = null, exclude = null, excludeReason = 'excluded',
     onFile, repoRoot, fetch: fetchImpl, sleep
   } = options;
 
@@ -295,6 +295,14 @@ export async function uploadRunDir(runDir, options) {
     files = files.filter(file => wanted.has(file.path));
   }
 
+  if (Array.isArray(exclude) && exclude.length > 0) {
+    const unwanted = new Set(exclude);
+    for (const file of files) {
+      if (unwanted.has(file.path)) skipped.push({ path: file.path, reason: excludeReason });
+    }
+    files = files.filter(file => !unwanted.has(file.path));
+  }
+
   if (!force) {
     const done = await uploadedKeys(jobId, journalOptions);
     const remaining = [];

package/src/upload/queue.js

@@ -14,7 +14,10 @@ import { paths } from '../paths.js';
  * was.
  *
  * Each line is `{ at, kind, run_id, path, sha256, size, status, detail }`.
- * `status` is one of `queued`, `uploaded`, `failed`, `skipped`.
+ * `status` is one of `queued`, `uploaded`, `failed`, `skipped`, `local_edit`.
+ * A `local_edit` is a file the CLI changed on disk after it was delivered
+ * (dropped findings marked in a run's report): the delivered copy is the
+ * record, so the new hash counts as done and is never sent again.
  *
  * Idempotency is by sha256: a path recorded `uploaded` with the same hash is
  * not sent again, which is what makes `resume` and the manual `upload <job>`
@@ -25,9 +28,13 @@ export const STATUS = Object.freeze({
   QUEUED: 'queued',
   UPLOADED: 'uploaded',
   FAILED: 'failed',
-  SKIPPED: 'skipped'
+  SKIPPED: 'skipped',
+  LOCAL_EDIT: 'local_edit'
 });
 
+/** Statuses that mean "nothing left to send at this hash". */
+const DONE = new Set([STATUS.UPLOADED, STATUS.LOCAL_EDIT]);
+
 /**
  * Append one entry.
  * @param {string} jobId
@@ -70,7 +77,8 @@ export async function readQueue(jobId, options = {}) {
 }
 
 /**
- * The set of `<runId>|<path>|<sha256>` triples already recorded as uploaded.
+ * The set of `<runId>|<path>|<sha256>` triples already recorded as uploaded,
+ * or as a local edit of a file that was.
  * The sha256 is part of the key on purpose: a corrected file at the same path
  * has a different hash and must be sent again.
  * @param {string} jobId
@@ -80,7 +88,7 @@ export async function readQueue(jobId, options = {}) {
 export async function uploadedKeys(jobId, options = {}) {
   const done = new Set();
   for (const entry of await readQueue(jobId, options)) {
-    if (entry.status === STATUS.UPLOADED) {
+    if (DONE.has(entry.status)) {
       done.add(keyFor(entry.run_id || null, entry.path, entry.sha256));
     }
   }
@@ -105,7 +113,7 @@ export async function pending(jobId, options = {}) {
   for (const entry of entries) {
     if (!entry.path) continue;
     const key = keyFor(entry.run_id || null, entry.path, entry.sha256);
-    if (entry.status === STATUS.UPLOADED) done.add(key);
+    if (DONE.has(entry.status)) done.add(key);
     latest.set(key, entry);
   }
   return [...latest.entries()]