ravensight-playtest 0.6.0 → 0.7.2

package/README.md

@@ -1,9 +1,47 @@
 # ravensight-playtest
 
-Hosted comparisons use a separate command from the local `run`:
+Hosted playtests run your uploaded build on our machines instead of yours. One
+persona plays it twice, once with Standard and once with Jev, and the dashboard
+gets a report for each and a comparison. They use a separate command from the
+local `run`:
 
 ```sh
-ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --transcript --output hosted-quote.json
+ravensight-playtest hosted run --wait
+ravensight-playtest hosted status ha_...
+ravensight-playtest hosted cancel ha_...
+```
+
+`hosted run` uses the game this directory is linked to (or `--game`), picks the
+newest build that passed its static archive check on a ready profile (or the one
+named by `--build`), asks the server for a quote and prints it: each unit and
+its price, the hosted compute for each mode, the total and what is due now from
+prepaid funds, the expiry, and the statements you accept with it (the refund
+rules for a failed build and for cancellation, no network access for the game,
+the separate validation hold). It asks before it charges. `--yes` answers for
+you, a run with no terminal and no `--yes` is a no, and `--json` needs `--yes`.
+A balance that does not meet the quote's funding requirement stops before the
+question, and nothing is charged.
+
+| Flag | Effect |
+|---|---|
+| `--build <id>` | Use this build instead of the newest ready one. |
+| `--persona <slug>` | The persona for both runs. Default `curious-kid`. |
+| `--video`, `--transcript` | Save video or transcripts of both sessions in their reports. Priced in the quote. |
+| `--wait` | Stay until the run finishes, printing each phase change, then each mode's outcome. |
+| `--game <id>` | Override the linked game. |
+
+The phases are the dashboard's: queued, provisioning, running, capturing,
+analyzing, then report ready, failed or canceled. `hosted status <id>` prints
+the current one (`--wait` to follow it) with each mode's state and findings and
+the dashboard link to the report. With `--wait`, a failed run exits 1 and a
+canceled one exits 10. `hosted cancel <id>` asks first, then requests
+cancellation: work already done follows the accepted policy and unstarted work
+is refunded during settlement.
+
+To review a quote before paying, save it and confirm it later:
+
+```sh
+ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --output hosted-quote.json
 ravensight-playtest hosted run hosted-quote.json
 ```
 
@@ -11,6 +49,7 @@ The quote names the full Standard then Jev price, prepaid amount, evidence
 options, expiry and refund rules. It charges nothing. `hosted run` confirms
 that saved quote before one admission request. Its durable journal blocks an
 automatic second POST after an uncertain outcome; preserve it for reconciliation.
+Both forms of `hosted run` keep that journal under `.ravensight/hosted-runs/`.
 A charged-blocked acknowledgement does not prove gameplay or a report. This
 command does not top up funds, change local run/report files or ask for model
 proxy permission on the CLI credential.
@@ -623,6 +662,14 @@ ravensight-playtest fix fnd_7g3k --no-verify
 The target is either `<jobId>/<label>`, where the label is the one the report
 gives the finding, or a bare finding id.
 
+It can also be a punch list or blue tape item, `li_...`, when the item came
+from a finding or a fresh-eyes finding.
+The fix then runs exactly as it does for that finding, at the same price. After
+the job registers, the job id is recorded on the item. The item stays open
+until you close it. An item that did not come from a finding is refused before
+anything is charged; `feature` is the tool for that item. See
+[Punch list and blue tape](#punch-list-and-blue-tape-labs-beta).
+
 | Flag | Effect |
 |---|---|
 | `--game <gameId>` | The game, when this repo is not linked. |
@@ -1209,6 +1256,68 @@ During a feature job the model reads a list of those measurements, never the fil
 
 The report says what was wired in, what the project uses, what is unused and which placeholders are left for you to supply. The names are in `assets-report.md` in the run directory, which stays on your machine.
 
+## Punch list and blue tape (Labs beta)
+
+Adding, closing, promoting and drafting need Ravensight Labs on for the game.
+The list commands still read when Labs is off; they show an empty list then.
+The dashboard shows the same two lists.
+
+The punch list holds what has to be finished before handover. You close the
+items one at a time. Blue tape holds small annoyances a new player meets in the
+first minutes. Capture them fast, then promote the ones that matter to the
+punch list.
+
+```sh
+ravensight-playtest punch list                  # open items; --status open|done|dropped|all
+ravensight-playtest punch add "Make the jump button respond on the first press."
+ravensight-playtest punch done li_9f2c
+ravensight-playtest punch drop li_9f2c
+ravensight-playtest punch draft                 # one AI unit; prints proposals, saves nothing
+ravensight-playtest punch draft --accept        # one AI unit; adds every proposal
+
+ravensight-playtest tape "The title music is too loud."
+ravensight-playtest tape list
+ravensight-playtest tape promote li_4a1b        # moves it to the punch list
+ravensight-playtest tape drop li_4a1b
+
+ravensight-playtest fix li_9f2c                 # an item that came from a finding
+```
+
+Reading, adding, closing and promoting are free. `punch draft` proposes items
+from the game's findings and specifications. It costs one AI unit, and nothing
+when there is nothing to propose. Without `--accept` it saves nothing. It asks
+before it spends, so pass `--yes` in a script. A list holds at most 500 open
+items.
+
+Each added item gets a free plain-language check, printed as hints under it:
+long sentences, two instructions in one sentence, passive voice, and words with
+a simpler choice. The hints follow the rules of Simplified Technical English.
+They never block an item.
+
+No command here closes an item for you, including `fix li_...`.
+
+| Flag | Effect |
+|---|---|
+| `--game <gameId>` | The game, when this repo is not linked. |
+| `--status <status>` | `list` only: `open` (the default), `done`, `dropped` or `all`. |
+| `--accept` | `punch draft` only: add every proposal to the punch list. |
+| `--json` | Print the server's answer as JSON. |
+
+### Fresh eyes
+
+A fresh-eyes playtest is a persona run with the `fresh-eyes` persona: a player
+in their first session who reports only small friction. When the job finishes,
+each of its findings becomes an open blue tape item.
+
+```sh
+ravensight-playtest personas                    # check that fresh-eyes is listed for your game
+ravensight-playtest run --personas fresh-eyes
+```
+
+It is priced as any persona run is. Personas come from the content pack the
+server sends, so `fresh-eyes` works once the server lists it. No CLI upgrade is
+needed for it.
+
 ## 3D proof of concept (Labs, Alpha)
 
 Labs beta is Godot 2D. There is one 3D template, for trying Build a feature and Validate changes on a 3D project. That is the whole of the Alpha: `create` does not make a 3D game from a brief and refuses to try, and how well a real model builds 3D has not been measured. It has no switch of its own, needing the same Labs opt-in and capability switches, and no price of its own: the jobs cost what they cost on a 2D project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.6.0",
+  "version": "0.7.2",
   "description": "Local AI playtests and seeded game simulations with reports in Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",

package/src/api/client.js

@@ -14,6 +14,15 @@ function gameBase(gameId) {
   return `/api/v1/games/${encodeURIComponent(gameId)}/playtest`;
 }
 
+/** `/api/v1/games/:gameId/labs/lists/:list`, for the punch list and blue tape. */
+function labsListBase(gameId, list) {
+  if (typeof gameId !== 'string' || gameId.length === 0) {
+    throw new TypeError('gameId is required');
+  }
+  if (list !== 'punch' && list !== 'tape') throw new TypeError('list must be punch or tape');
+  return `/api/v1/games/${encodeURIComponent(gameId)}/labs/lists/${list}`;
+}
+
 /**
  * The Ravensight playtest API, as one object with one namespace per surface.
  *
@@ -407,6 +416,25 @@ export function createClient(options = {}) {
      * free. Editing and approving are the dashboard's, on purpose: this token
      * cannot do either.
      */
+    /**
+     * The punch list and blue tape. `list` is `punch` or `tape`. Reads and
+     * plain writes are free; `draft` is one AI unit and saves nothing.
+     */
+    lists: {
+      list: (gameId, list, { status } = {}) =>
+        get(labsListBase(gameId, list), { query: status ? { status } : undefined }),
+      get: (gameId, list, itemId) =>
+        get(`${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`),
+      add: (gameId, list, body) =>
+        request('POST', labsListBase(gameId, list), { body }).then(answer => answer.body),
+      update: (gameId, list, itemId, body) =>
+        request('PATCH', `${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`, { body }).then(answer => answer.body),
+      promote: (gameId, itemId) =>
+        request('POST', `${labsListBase(gameId, 'tape')}/items/${encodeURIComponent(itemId)}/promote`, { body: {} }).then(answer => answer.body),
+      draft: gameId =>
+        request('POST', `${labsListBase(gameId, 'punch')}/draft`, { body: {} }).then(answer => answer.body)
+    },
+
     featureSpecs: {
       create: (gameId, brief, extra = {}) =>
         request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/feature-specs`, { body: { brief, ...extra } }).then(answer => answer.body),

package/src/auth/scopes.js

@@ -0,0 +1,36 @@
+/**
+ * The scopes a CLI token carries, checked before anything is charged.
+ *
+ * A token's scopes are fixed when it is approved. A persona run needs
+ * `playtest:model` to play and `playtest:upload` to hand in its report, and
+ * the server only checks each one when the run reaches it: in October a token
+ * without `playtest:upload` registered a paid job, played it, and was refused
+ * at the upload, so the job came back with no report. `whoami` answers with
+ * the token's scopes, so `run` asks first and refuses locally.
+ */
+
+/** What a persona run (`run`, and `fix`'s verify replay) needs. */
+export const RUN_SCOPES = Object.freeze(['playtest:write', 'playtest:model', 'playtest:upload']);
+
+/**
+ * The required scopes a token lacks, or null when its scopes are not known
+ * (an older server's `whoami` does not list them).
+ *
+ * @param {unknown} scopes the `scopes` field of a whoami answer
+ * @param {ReadonlyArray<string>} [required]
+ * @returns {Array<string>|null}
+ */
+export function missingScopes(scopes, required = RUN_SCOPES) {
+  if (!Array.isArray(scopes)) return null;
+  return required.filter(scope => !scopes.includes(scope));
+}
+
+/**
+ * The refusal for a token that lacks what a run needs.
+ *
+ * @param {Array<string>} missing
+ * @returns {string}
+ */
+export function missingScopeMessage(missing) {
+  return `This login cannot run a playtest: its token does not have ${missing.join(', ')}. Log in again with "ravensight-playtest login" and approve the full set of playtest permissions. Nothing was registered or charged.`;
+}

package/src/cli.js

@@ -153,7 +153,7 @@ function withoutFirst(values, value) {
 export function buildProgram() {
   const program = new Command();
   const slot = { code: ExitCode.OK };
-  const hosted = common(program.command('hosted').description('quote and admit a server-hosted Standard/Jev comparison'));
+  const hosted = common(program.command('hosted').description('run a server-hosted Standard and Jev playtest: quote, run, status and cancel'));
   hosted.command('quote')
     .description('save a full hosted quote without charging or admitting a run')
     .requiredOption('--build <id>', 'an existing validated hosted build')
@@ -163,18 +163,43 @@ export function buildProgram() {
     .option('--game <id>', 'game id, overriding this repo’s configuration')
     .addOption(new Option('--standard-provider <name>', 'explicit Standard provider; unavailable choices are refused').choices(['anthropic', 'openai']))
     .option('--video', 'include hosted gameplay video in this quote')
-    .option('--transcript', 'include the hosted transcript in this quote')
     .action(capture(slot, async (options, command) => {
       const { hostedQuote } = await import('./commands/hosted.js');
       return hostedQuote(flagsFrom(command.optsWithGlobals(), { build: options.build, profile: options.profile,
         persona: options.persona, output: options.output, game: options.game, standardProvider: options.standardProvider,
-        video: options.video, transcript: options.transcript }));
+        video: options.video }));
     }));
-  hosted.command('run <quote-file>')
-    .description('confirm the full saved quote and request one hosted admission; never retry an unknown outcome')
-    .action(capture(slot, async (filename, _options, command) => {
-      const { hostedRun } = await import('./commands/hosted.js');
-      return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+  common(hosted.command('run [quote-file]'))
+    .description('quote the newest ready build (or --build), confirm the price, and start one hosted Standard and Jev run; with a saved quote file, confirm that quote instead. Never retries an unknown outcome')
+    .option('--build <id>', 'a build that passed its static archive check (default: the newest one)')
+    .option('--persona <slug>', 'the persona that plays both runs (default: curious-kid)')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--video', 'save video of both game sessions in their reports')
+    .option('--wait', 'stay until the report is ready, printing each phase change')
+    .action(capture(slot, async (filename, options, command) => {
+      const { hostedRun, hostedRunDirect } = await import('./commands/hosted.js');
+      if (filename) {
+        const extra = ['build', 'persona', 'game', 'video', 'wait'].filter(name => options[name] !== undefined);
+        if (extra.length) throw new CliError(`A saved quote already fixes its build, persona and options. Drop --${extra.join(', --')}, or run "hosted run" without a quote file.`);
+        return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+      }
+      return hostedRunDirect(flagsFrom(command.optsWithGlobals(), { build: options.build, persona: options.persona, game: options.game,
+        video: options.video, wait: options.wait }));
+    }));
+  common(hosted.command('status <run-id>'))
+    .description('show the phase of one hosted run (queued, provisioning, running, capturing, analyzing, report ready, failed or canceled), each mode and the report link')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--wait', 'stay until the run finishes, printing each phase change')
+    .action(capture(slot, async (runId, options, command) => {
+      const { hostedStatus } = await import('./commands/hosted.js');
+      return hostedStatus(runId, flagsFrom(command.optsWithGlobals(), { game: options.game, wait: options.wait }));
+    }));
+  common(hosted.command('cancel <run-id>'))
+    .description('request cancellation of one hosted run; unstarted work is refunded during settlement')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .action(capture(slot, async (runId, options, command) => {
+      const { hostedCancel } = await import('./commands/hosted.js');
+      return hostedCancel(runId, flagsFrom(command.optsWithGlobals(), { game: options.game }));
     }));
   const build = common(program.command('build').description('check or upload a self-contained hosted game archive'));
   build.command('preflight <archive>')
@@ -537,6 +562,74 @@ export function buildProgram() {
       }));
     }));
 
+  // Labs lists. Each subcommand takes the shared flags itself, so `--json` and
+  // `--game` work after the subcommand name, where people type them.
+  const listFlags = command => common(command).option('--game <gameId>', 'the game, when this repo is not linked');
+  const statusOption = () => new Option('--status <status>', 'which items to show').choices(['open', 'done', 'dropped', 'all']).default('open');
+
+  const punch = common(program.command('punch')
+    .description('Labs beta: the punch list, what has to be finished before handover, closed one item at a time'));
+  listFlags(punch.command('list').description('show the punch list; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { punchList } = await import('./commands/punch.js');
+      return punchList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(punch.command('add').description('add one item; free, with plain-language hints'))
+    .argument('<text>', 'the item, in quotes')
+    .action(capture(slot, async (text, options) => {
+      const { punchAdd } = await import('./commands/punch.js');
+      return punchAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('done').description('close an item as done; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'done', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('drop').description('close an item as dropped; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'dropped', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('draft').description('propose items from this game\'s findings and specs; one AI unit, saves nothing without --accept'))
+    .option('--accept', 'add every proposal to the punch list')
+    .action(capture(slot, async options => {
+      const { punchDraft } = await import('./commands/punch.js');
+      return punchDraft(flagsFrom(options, { game: options.game, accept: Boolean(options.accept) }));
+    }));
+
+  const tape = listFlags(program.command('tape')
+    .description('Labs beta: blue tape, small first-impression annoyances; tape "<text>" captures one'))
+    .argument('[text]', 'the annoyance, in quotes')
+    .action(capture(slot, async (text, options, command) => {
+      if (!text) {
+        command.outputHelp();
+        return ExitCode.FAILURE;
+      }
+      const { tapeAdd } = await import('./commands/tape.js');
+      return tapeAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('list').description('show blue tape; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { tapeList } = await import('./commands/tape.js');
+      return tapeList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(tape.command('promote').description('move an item to the punch list; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapePromote } = await import('./commands/tape.js');
+      return tapePromote(itemId, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('drop').description('drop an item; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapeDrop } = await import('./commands/tape.js');
+      return tapeDrop(itemId, flagsFrom(options, { game: options.game }));
+    }));
+
   common(program.command('simulation-replay').description('verify a recorded simulation trace locally; creates no paid job'))
     .argument('<trace>', 'a selected trace.json written by simulate')
     .requiredOption('--driver-config <file>', 'local JSON-RPC executable configuration')

package/src/commands/check.js

@@ -3,6 +3,7 @@ import { ApiError } from '../api/errors.js';
 import { resolveApiUrl, paths } from '../paths.js';
 import { resolveToken, looksLikeIngestKey, looksLikeMcpToken } from '../auth/session.js';
 import { backendName } from '../auth/keychain.js';
+import { missingScopes } from '../auth/scopes.js';
 import { loadConfig } from '../config.js';
 import { packs } from '../packs/index.js';
 import { detectFfmpeg, freeBytes, recommendConcurrency } from '../detect.js';
@@ -421,7 +422,10 @@ export async function runChecks(flags = {}, deps = {}) {
       facts.login.valid = true;
       facts.login.games = games.map(game => ({ gameId: game.gameId, name: game.name || null }));
       const who = whoami.user.email || whoami.user.name || whoami.user.id;
-      rows.push(row(
+      const missing = missingScopes(whoami.scopes);
+      if (missing && missing.length > 0) {
+        rows.push(row('login', 'fail', `${who}, valid, but the token does not have ${missing.join(', ')}, so a playtest run would be refused`, 'ravensight-playtest login'));
+      } else rows.push(row(
         'login',
         games.length > 0 ? 'pass' : 'warn',
         games.length > 0

package/src/commands/fakeCore.js

@@ -363,7 +363,11 @@ export function fakeCore({
     runs: {
       async heartbeat(gameId, jobId, runId, options) {
         record('heartbeat', { runId, options });
-        return { run: { usage: { total_usd: 0.11 } }, cancel_requested: false };
+        // calls: 0, so the fake spend never prices a unit: $0.11 over a few
+        // ten-token scripted turns would make the report reserve
+        // (../run/budgetReserve.js) stop play after one turn in tests about
+        // other things. The reserve has its own tests.
+        return { run: { usage: { total_usd: 0.11, calls: 0 } }, cancel_requested: false };
       },
       async transition(gameId, jobId, runId, state, options) {
         record('transition', { runId, state, options });

package/src/commands/fix.js

@@ -13,6 +13,7 @@ import { createHeartbeat } from '../run/heartbeat.js';
 import { createModelClient } from '../run/model.js';
 import { jobDir, runDir as runDirFor, RUN_FILES, screenshotsDir } from '../run/paths.js';
 import { runPersona } from '../run/personaLoop.js';
+import { runModelBudgetUsd } from '../run/budgetReserve.js';
 import { replayTrace } from '../run/replay.js';
 import { loadTrace, replayReport, replaySentence } from './replay.js';
 import { createRepoTools, PROFILE_TOOLS, WRITE_TOOLS } from '../run/repoTools.js';
@@ -29,6 +30,8 @@ import * as stateFile from '../run/state.js';
 import { createUsageLedger, writeUsageFile } from '../run/usage.js';
 import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, godotRefusal, resolveSetup, resolveTarget, skillFor, usableLocalBrief, startBalanceLine, startBalanceShort } from './run.js';
 import { loadLocalBrief } from '../briefLocal.js';
+import { findListItem } from './lists.js';
+import { jobLink } from '../dashboard.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -212,9 +215,9 @@ async function fix(target, flags, injected, deps, log) {
     for (const line of unknownOptionNotes(unknown)) log(line);
     return EXIT.ENVIRONMENT;
   }
-  const parsed = parseTarget(target);
+  let parsed = parseTarget(target);
   if (!parsed) {
-    log('Name the finding to fix: either <jobId>/<label>, like pt_job_1/F002, or a finding id.');
+    log('Name the finding to fix: either <jobId>/<label>, like pt_job_1/F002, a finding id, or a punch list item, li_...');
     return EXIT.ENVIRONMENT;
   }
 
@@ -222,6 +225,20 @@ async function fix(target, flags, injected, deps, log) {
   if (setup.code !== undefined) return setup.code;
   const { context, api, gameId, apiUrl, repoRoot, cliVersion } = setup;
 
+  // A punch list item that came from a finding is fixed as that finding. The
+  // item only lends its finding's id, and later records the job; it is never closed here.
+  let listItem = null;
+  if (isListItemTarget(target)) {
+    const resolved = await resolveListItemTarget(api, gameId, String(target).trim());
+    if (resolved.refusal) {
+      log(resolved.refusal);
+      return EXIT.ENVIRONMENT;
+    }
+    listItem = resolved;
+    parsed = parseTarget(resolved.item.source.ref);
+    log(`${resolved.item.item_id} came from ${resolved.item.source.kind === 'fresh_eyes' ? 'fresh-eyes finding' : 'finding'} ${resolved.item.source.ref}, so this fixes that finding.`);
+  }
+
   const wantsVerify = options.verify !== false;
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
   const buildTarget = resolveTarget(options, context.config, driverName, repoRoot);
@@ -477,6 +494,7 @@ async function fix(target, flags, injected, deps, log) {
   // the runs, because the charge has already happened: a developer who cannot
   // name the job they paid for cannot ask anybody about it either.
   log(`job ${jobId}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${jobDir(repoRoot, jobId)}`);
+  if (listItem) await recordFixJob({ api, gameId, listItem, jobId, link: (registered.links && registered.links.dashboard) || jobLink(gameId, jobId, apiUrl), log });
 
   if (!fixRun) {
     log('The server registered the job without a fix run, so there is nothing to spend a model turn from.');
@@ -931,6 +949,56 @@ async function fix(target, flags, injected, deps, log) {
  * @param {{jobId: string|null, label: string|null, findingId: string|null}} target
  * @returns {Promise<Object|null>}
  */
+/** The list item sources whose ref is a finding a fix can replay. */
+export const FIXABLE_SOURCES = Object.freeze(['finding', 'fresh_eyes']);
+
+/** Whether a fix target names a Labs list item rather than a finding. */
+export function isListItemTarget(target) {
+  return String(target || '').trim().startsWith('li_');
+}
+
+/**
+ * Find a list item and check it came from a finding. Only a finding has the
+ * persona, the repro steps and the replay a fix needs; anything else is new
+ * work, which is what `feature` builds.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @param {string} itemId
+ * @returns {Promise<{item: Object, list: string}|{refusal: string}>}
+ */
+export async function resolveListItemTarget(api, gameId, itemId) {
+  if (!api.labs || !api.labs.lists) {
+    return { refusal: 'This server has no punch list. Fix the finding by its id instead.' };
+  }
+  const found = await findListItem(api, gameId, itemId);
+  if (!found) {
+    return { refusal: `No item ${itemId} is on this game's punch list or blue tape. Run "ravensight-playtest punch list --status all" to see the ids.` };
+  }
+  const source = found.item.source || {};
+  // A fresh-eyes item's ref is a finding's targetId too.
+  if (!FIXABLE_SOURCES.includes(source.kind) || !source.ref) {
+    return {
+      refusal: `${itemId} did not come from a finding, so fix has nothing to replay. Use "ravensight-playtest feature" for that item. Nothing was charged.`
+    };
+  }
+  return found;
+}
+
+/**
+ * Record the fix job on the list item. Best effort: the job is already paid
+ * for, and a list that cannot be written must not stop the fix.
+ */
+async function recordFixJob({ api, gameId, listItem, jobId, link, log }) {
+  const itemId = listItem.item.item_id;
+  try {
+    await api.labs.lists.update(gameId, listItem.list, itemId, { fix_job_id: jobId });
+    log(`Recorded job ${jobId} on ${itemId}: ${link}. The item stays open until you close it.`);
+  } catch (error) {
+    log(`warning: could not record job ${jobId} on ${itemId} (${error && error.message ? error.message : error}). The fix carries on.`);
+  }
+}
+
 export async function resolveFinding(api, gameId, target) {
   const answer = await api.jobs.findings(gameId, target.jobId ? { job: target.jobId } : {});
   const list = (answer && answer.findings) || [];
@@ -1135,6 +1203,7 @@ export async function runVerify({
     outcome = await runPersona({
       client,
       api,
+      modelBudgetUsd: runModelBudgetUsd(entry),
       gameId,
       jobId,
       runId: entry.run_id,