ravensight-playtest 0.5.2 → 0.6.0

package/src/run/repoTools.js

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
-import { lstat, mkdir, readFile, readdir, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { scanForSecrets } from './secretScan.js';
+import vm from 'node:vm';
+import { isMediaPath } from '../assets/inventory.js';
+import { allIgnoredFiles, hooksDirectory, ignoredPaths } from './git.js';
+import { MAX_SCAN_BYTES, scanForSecrets } from './secretScan.js';
 
 /**
  * The read-only source tools for `game_profile`: `read_file`, `glob` and
@@ -49,6 +52,20 @@ export const SKIP_DIRS = Object.freeze([
  */
 export const NEVER_TOUCHED = Object.freeze(['.git', '.ravensight']);
 
+/**
+ * What a fix reports with: this CLI writes them beside its journals once the fix
+ * is done, and they are never part of the change. A model once wrote them into
+ * the repository root as well, where they were counted as the fix's own edits
+ * ("+77 -1" for a three line change). Only at the root, and only when the project
+ * does not already have one: a project's own report.md is the project's.
+ */
+export const RUN_OUTPUT_NAMES = Object.freeze(['changeset.json', 'report.md']);
+
+/** @param {string} relativePath */
+export function isRunOutputName(relativePath) {
+  return RUN_OUTPUT_NAMES.includes(String(relativePath).toLowerCase());
+}
+
 /** `SKIP_DIRS`, lowercased once, because the comparison is case insensitive. */
 const SKIP_DIRS_LOWER = Object.freeze(SKIP_DIRS.map(name => name.toLowerCase()));
 
@@ -57,10 +74,77 @@ export const SECRET_FILE_PATTERNS = Object.freeze([
   /(^|\/)\.env($|\.)/i,
   /(^|\/)\.npmrc$/i,
   /(^|\/)id_(rsa|dsa|ecdsa|ed25519)$/i,
-  /(^|\/)credentials$/i,
-  /\.(pem|key|p12|pfx|keystore|jks)$/i
+  /(^|\/)credentials(\.[a-z]+)?$/i,
+  /\.(pem|key|p8|ppk|p12|pfx|keystore|jks)$/i,
+  /(^|\/)[._]netrc$/i,
+  /(^|\/)\.(git-credentials|pgpass|pypirc|htpasswd|dockercfg)$/i,
+  /(^|\/)secrets?\.(json|ya?ml|toml|cfg|ini|xml|properties)$/i,
+  /(^|\/)(google-services\.json|googleservice-info\.plist)$/i,
+  /(^|\/)service[-_]?account[^/]*\.json$/i,
+  /(^|\/)\.(aws|ssh|gnupg|kube|docker)\//i,
+  // Godot keeps signing passwords here: in export_presets.cfg up to 4.2, and in
+  // export_credentials.cfg after it.
+  /(^|\/)export_(presets|credentials)\.cfg$/i,
+  // A game's Ravensight key file, written by `create` and ignored by git.
+  /(^|\/)ravensight_key(\.[a-z]+)?\.cfg$/i
 ]);
 
+/**
+ * Files that are not the game. What is in them runs on a developer's or a CI
+ * machine, or changes what git shows, so a write here is either code execution
+ * (`git commit` runs a hook, and `--open-pr` commits) or a change that hides other
+ * changes (a `.gitignore` that ignores the file just written). None of it is what
+ * a playtest finding asks for, so it is never written, whatever the model read.
+ */
+export const NEVER_WRITTEN_PATTERNS = Object.freeze([
+  /(^|\/)\.(husky|githooks)(\/|$)/i,
+  /(^|\/)\.git(ignore|attributes|modules|config)$/i,
+  /(^|\/)\.mailmap$/i,
+  /(^|\/)\.envrc$/i,
+  /^\.github\/(workflows|actions)\//i,
+  /^\.gitlab-ci\.ya?ml$/i,
+  /^\.circleci\//i,
+  /^\.pre-commit-config\.ya?ml$/i,
+  /(^|\/)\.?lefthook(-local)?\.ya?ml$/i,
+  /(^|\/)\.vscode\//i
+]);
+
+/**
+ * A file name that means something else somewhere else: control characters and
+ * invisible or direction-changing ones (a terminal, a code review), a trailing dot
+ * or space and a colon or short name (`.git.`, `.git::$INDEX_ALLOCATION` and `git~1`
+ * are `.git` on Windows), and a backslash (a separator on Windows, a filename here).
+ */
+/* eslint-disable-next-line no-control-regex */
+const UNSAFE_NAME_CHARS = /[\u0000-\u001f\u007f-\u009f\u00ad\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff:\\]/;
+
+/**
+ * @param {string} relative
+ * @returns {boolean}
+ */
+function isUnsafeName(relative) {
+  if (UNSAFE_NAME_CHARS.test(relative)) return true;
+  return relative.split('/').some(segment => /[. ]$/.test(segment) || /~\d+$/.test(segment));
+}
+
+/**
+ * The directory under the root that is its own repository, if the path goes
+ * through one. The outer diff shows a submodule as one line with no counts and a
+ * nested repository's new files not at all, so a write there is one nobody reviews.
+ *
+ * @param {string} root
+ * @param {string} relative
+ * @returns {Promise<string|null>}
+ */
+async function nestedRepositoryIn(root, relative) {
+  const parts = relative.split('/').slice(0, -1);
+  for (let i = 1; i <= parts.length; i += 1) {
+    const directory = parts.slice(0, i).join('/');
+    if (await lstat(path.join(root, directory, '.git')).then(() => true, () => false)) return directory;
+  }
+  return null;
+}
+
 /** How much of one file a single read returns. */
 export const MAX_READ_BYTES = 120000;
 
@@ -381,14 +465,18 @@ export async function listFiles(root, { limit = 20000 } = {}) {
  * @param {string} args.root the repository root
  * @returns {{tools: Array, execute: (toolUse: Object) => Promise<{result: Object}>}}
  */
-export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
+export function createRepoTools({ root, tools = PROFILE_TOOLS, maxWrites = MAX_WRITES_PER_RUN }) {
   let cachedFiles = null;
   const canWrite = tools.some(tool => tool.name === 'write_file');
   /** The distinct paths this run has written, which is what the cap counts. */
   const written = new Set();
 
   async function files() {
-    if (!cachedFiles) cachedFiles = await listFiles(root);
+    if (!cachedFiles) {
+      const all = await listFiles(root);
+      const ignored = await allIgnoredFiles(root);
+      cachedFiles = all.filter(file => !ignored.has(file));
+    }
     return cachedFiles;
   }
 
@@ -411,25 +499,23 @@ export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
           // A refusal comes back as an `is_error` result naming the rule,
           // never as a thrown error: the model has to be able to read why and
           // try a legal write instead, and a thrown error would end the run.
-          const planned = await planWrite(root, input, written);
+          const planned = await planWrite(root, input, written, maxWrites);
           if (planned.refusal) return { result: ok(toolUse.id, planned.refusal, true) };
           await doWrite(planned.absolute, input.content);
           written.add(planned.relative);
-          const left = MAX_WRITES_PER_RUN - written.size;
+          const left = maxWrites - written.size;
           return { result: ok(toolUse.id, `Wrote ${planned.relative} (${planned.bytes} bytes). ${left} more file(s) may be written in this run.`) };
         }
         if (toolUse.name === 'edit_file' && canWrite) {
-          const planned = await planEdit(root, input, written);
+          const planned = await planEdit(root, input, written, maxWrites);
           if (planned.refusal) return { result: ok(toolUse.id, planned.refusal, true) };
           await doWrite(planned.absolute, planned.content);
           written.add(planned.relative);
-          const left = MAX_WRITES_PER_RUN - written.size;
+          const left = maxWrites - written.size;
           return { result: ok(toolUse.id, `Edited ${planned.relative}: ${planned.replaced} occurrence(s) replaced, now ${planned.bytes} bytes. ${left} more file(s) may be written in this run.`) };
         }
         if (toolUse.name === 'glob') {
-          const matcher = globToRegExp(input.pattern);
-          const matched = (await files()).filter(file => matcher.test(file)).slice(0, MAX_GLOB_RESULTS);
-          return { result: ok(toolUse.id, matched.length > 0 ? matched.join('\n') : '(no matches)') };
+          return { result: ok(toolUse.id, doGlob(await files(), input.pattern)) };
         }
         if (toolUse.name === 'grep') return { result: ok(toolUse.id, await doGrep(root, await files(), input)) };
         return { result: ok(toolUse.id, `There is no tool called ${toolUse.name}.`, true) };
@@ -440,6 +526,12 @@ export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
   };
 }
 
+/**
+ * Art, audio and anything else that is not text never reach the model: the bytes say
+ * nothing it can use, and they would spend the run's budget and leave this machine.
+ */
+const NOT_TEXT = relative => `Refused: ${relative} is an art, audio or other binary file, and its content is never read or sent.`;
+
 async function doRead(root, input) {
   const asked = String(input.path || '');
   if (isSecretPath(asked)) {
@@ -449,13 +541,28 @@ async function doRead(root, input) {
   // symlinked directory would otherwise let a read leave the repository, and
   // `/etc/passwd` read through `shared/` is still a read of `/etc/passwd`.
   const { absolute, relative } = await resolveInsideReal(root, asked);
+  // Again on the resolved path: `.env/` and `.env/.` are spellings of `.env` that
+  // the filesystem accepts and the patterns above do not.
+  if (isSecretPath(relative)) {
+    return `Refused: ${relative} is a credential file and is never read. Note in warnings that credentials are checked into the repository, without quoting anything.`;
+  }
   const skipped = skippedDirIn(relative);
   if (skipped) {
     return `Refused: ${relative} is under ${skipped}, which is not part of the game's source.`;
   }
+  // What a developer told git to leave alone is local to this machine, and it is
+  // where a key with no recognisable shape lives.
+  if (relative && (await ignoredPaths(root, [relative])).has(relative)) {
+    return `Refused: ${relative} is gitignored, so it is local to this machine and is never read.`;
+  }
   const info = await stat(absolute);
   if (!info.isFile()) throw new Error(`${relative} is not a file`);
+  if (isMediaPath(relative)) return NOT_TEXT(relative);
+  // Refused before it is loaded: a raw asset dump would otherwise be read into
+  // memory whole, only to be refused by the scan below.
+  if (info.size > MAX_SCAN_BYTES) return `Refused: ${relative} is too large (${info.size} bytes) to read here.`;
   const text = await readFile(absolute, 'utf8');
+  if (text.includes(NUL)) return NOT_TEXT(relative);
   const secrets = scanForSecrets(text);
   if (secrets.length > 0) {
     // The content is withheld rather than redacted: a partial redaction of
@@ -485,7 +592,7 @@ async function doRead(root, input) {
  * @param {Set<string>} written the distinct paths written so far
  * @returns {Promise<{relative: string, absolute: string, bytes: number}|{refusal: string}>}
  */
-export async function planWrite(root, input, written = new Set()) {
+export async function planWrite(root, input, written = new Set(), maxWrites = MAX_WRITES_PER_RUN) {
   const asked = String((input && input.path) || '').trim();
   if (!asked) return { refusal: 'Refused: write_file needs a path relative to the repository root.' };
 
@@ -507,6 +614,31 @@ export async function planWrite(root, input, written = new Set()) {
   if (skipped) {
     return { refusal: `Refused: ${relative} is under ${skipped}, which is generated, vendored or this tool's own bookkeeping, and is never written.` };
   }
+  if (isUnsafeName(relative)) {
+    return { refusal: 'Refused: that file name holds characters that are unsafe in a terminal, in git or on another filesystem. Use a plain name.' };
+  }
+  if (NEVER_WRITTEN_PATTERNS.some(pattern => pattern.test(relative))) {
+    return { refusal: `Refused: ${relative} controls git or runs on a developer's or CI machine, and is never written. Change only the game.` };
+  }
+  const hooks = await hooksDirectory(root);
+  if (hooks && (absolute === hooks || absolute.startsWith(hooks + path.sep))) {
+    return { refusal: `Refused: ${relative} is in this repository's git hooks directory, and is never written.` };
+  }
+  const nested = await nestedRepositoryIn(root, relative);
+  if (nested) {
+    return { refusal: `Refused: ${nested} is its own git repository, so a change inside it would not show in this branch's diff. Change only this repository's files.` };
+  }
+  if (isMediaPath(relative)) {
+    return { refusal: `Refused: ${relative} is an art, audio or other binary file, and only text files are written.` };
+  }
+  // Git would never show this write: the changeset would call it no change, the
+  // unit would be refunded, and the developer's file would stay edited.
+  if ((await ignoredPaths(root, [relative])).has(relative)) {
+    return { refusal: `Refused: ${relative} is gitignored, so a change to it could never be reviewed. Change a tracked file, or a new file git will see.` };
+  }
+  if (isRunOutputName(relative) && !(await lstat(absolute).catch(() => null))) {
+    return { refusal: `Refused: ${relative} is a report this CLI writes itself once you stop, and it is never part of the change. Change only the project's own files.` };
+  }
 
   const content = input && input.content;
   if (typeof content !== 'string') {
@@ -519,8 +651,13 @@ export async function planWrite(root, input, written = new Set()) {
   if (bytes > MAX_WRITE_BYTES) {
     return { refusal: `Refused: ${relative} would be ${bytes} bytes and one write may be at most ${MAX_WRITE_BYTES}. Change less of it, or change a smaller file.` };
   }
-  if (!written.has(relative) && written.size >= MAX_WRITES_PER_RUN) {
-    return { refusal: `Refused: this run has already written ${written.size} files and may write at most ${MAX_WRITES_PER_RUN}. Finish with the files you have already changed.` };
+  const existing = await lstat(absolute).catch(() => null);
+  if (existing && !existing.isFile()) return { refusal: `Refused: ${relative} is not a regular file.` };
+  if (existing && !isPlainText(await readFile(absolute).catch(() => Buffer.alloc(0)))) {
+    return { refusal: `Refused: ${relative} is not UTF-8 text, and replacing it would destroy it.` };
+  }
+  if (!written.has(relative) && written.size >= maxWrites) {
+    return { refusal: `Refused: this run has already written ${written.size} files and may write at most ${maxWrites}. Finish with the files you have already changed.` };
   }
   return { relative, absolute, bytes };
 }
@@ -545,7 +682,7 @@ export async function planWrite(root, input, written = new Set()) {
  * @param {Set<string>} written
  * @returns {Promise<{refusal: string}|{relative: string, absolute: string, content: string, bytes: number, replaced: number}>}
  */
-export async function planEdit(root, input, written = new Set()) {
+export async function planEdit(root, input, written = new Set(), maxWrites = MAX_WRITES_PER_RUN) {
   const oldText = input && input.old_text;
   const newText = input && input.new_text;
   if (typeof oldText !== 'string' || oldText.length === 0) {
@@ -554,16 +691,19 @@ export async function planEdit(root, input, written = new Set()) {
   if (typeof newText !== 'string') return { refusal: 'Refused: new_text has to be a string (it may be empty to delete the passage).' };
   // The path rules are the write rules; the placeholder content only has to be
   // a string so the shared checks run.
-  const planned = await planWrite(root, { path: input && input.path, content: '' }, written);
+  const planned = await planWrite(root, { path: input && input.path, content: '' }, written, maxWrites);
   if (planned.refusal) return { refusal: planned.refusal.replace('write_file', 'edit_file') };
 
   let current;
   try {
-    current = await readFile(planned.absolute, 'utf8');
+    const raw = await readFile(planned.absolute);
+    // Decoding other bytes as UTF-8 and writing them back would corrupt every
+    // character outside the passage being replaced.
+    if (!isPlainText(raw)) return { refusal: `Refused: ${planned.relative} is not UTF-8 text, so it cannot be edited here without damaging it.` };
+    current = raw.toString('utf8');
   } catch {
     return { refusal: `Refused: ${planned.relative} does not exist yet. Use write_file to create a new file.` };
   }
-  if (current.includes(NUL)) return { refusal: `Refused: ${planned.relative} is not a text file.` };
 
   const occurrences = current.split(oldText).length - 1;
   if (occurrences === 0) {
@@ -584,8 +724,11 @@ export async function planEdit(root, input, written = new Set()) {
 async function doWrite(absolute, content) {
   await mkdir(path.dirname(absolute), { recursive: true });
   const tmp = `${absolute}.${process.pid}.${randomUUID()}.tmp`;
-  await writeFile(tmp, content, 'utf8');
+  // A rename takes the new file's permissions, and git records the executable bit.
+  const before = await stat(absolute).catch(() => null);
   try {
+    await writeFile(tmp, content, 'utf8');
+    if (before) await chmod(tmp, before.mode & 0o777);
     await rename(tmp, absolute);
   } catch (error) {
     // A failed rename would otherwise leave the half-named temp file in the
@@ -595,29 +738,72 @@ async function doWrite(absolute, content) {
   }
 }
 
+/**
+ * A model's pattern is untrusted, and a catastrophic one spins inside one
+ * synchronous call: no timer fires, no signal handler runs, Ctrl-C does nothing and
+ * the job's heartbeat stops. So every pattern runs under a time limit, in a script
+ * V8 can interrupt, and a limit reached is an answer the model can act on.
+ */
+export const MAX_PATTERN_MS = 3000;
+
+const SCAN = new vm.Script('for (; next < items.length && found.length < limit; next += 1) { if (pattern.test(items[next])) found.push(next); }');
+
+/**
+ * @param {number} [budgetMs]
+ * @returns {(pattern: RegExp, items: Array<string>, limit: number) => Array<number>|null} matching
+ * indexes; `stopped` says the budget ran out, and what was found so far stands
+ */
+function boundedMatcher(budgetMs = MAX_PATTERN_MS) {
+  const context = vm.createContext({ pattern: null, items: [], limit: 0, found: [], next: 0 });
+  const scan = (pattern, items, limit) => {
+    Object.assign(context, { pattern, items, limit, found: [], next: 0 });
+    const started = Date.now();
+    if (budgetMs > 0) {
+      try {
+        SCAN.runInContext(context, { timeout: Math.max(1, Math.ceil(budgetMs)) });
+      } catch (error) {
+        if (!error || error.code !== 'ERR_SCRIPT_EXECUTION_TIMEOUT') throw error;
+        budgetMs = 0;
+      }
+      if (budgetMs > 0) budgetMs -= Date.now() - started;
+    }
+    scan.stopped = budgetMs <= 0;
+    return context.found;
+  };
+  scan.stopped = false;
+  return scan;
+}
+
+const TOO_SLOW = 'that pattern takes too long to run here, so use a simpler one';
+
 async function doGrep(root, all, input) {
   const regex = new RegExp(String(input.pattern), 'i');
   const matcher = input.glob ? globToRegExp(input.glob) : null;
   const hits = [];
-  for (const relative of all) {
-    if (hits.length >= MAX_GREP_RESULTS) break;
-    if (matcher && !matcher.test(relative)) continue;
+  const scan = boundedMatcher();
+  const candidates = matcher ? scan(matcher, all, Number.MAX_SAFE_INTEGER).map(index => all[index]) : all;
+  for (const relative of candidates) {
+    if (hits.length >= MAX_GREP_RESULTS || scan.stopped) break;
+    if (isMediaPath(relative)) continue;
     let text;
     try {
       const info = await stat(path.join(root, relative));
-      if (info.size > MAX_READ_BYTES) continue;
+      // A named pipe has no size and a read of one never returns.
+      if (!info.isFile() || info.size > MAX_READ_BYTES) continue;
       text = await readFile(path.join(root, relative), 'utf8');
     } catch {
       continue;
     }
+    if (text.includes(NUL)) continue;
     // A file with secrets in it is not searched either: a grep result is a
     // quoted line, and a quoted line from such a file is the leak.
     if (scanForSecrets(text).length > 0) continue;
     const lines = text.split('\n');
-    for (let i = 0; i < lines.length && hits.length < MAX_GREP_RESULTS; i += 1) {
-      if (regex.test(lines[i])) hits.push(`${relative}:${i + 1}: ${lines[i].trim().slice(0, 300)}`);
+    for (const i of scan(regex, lines, MAX_GREP_RESULTS - hits.length)) {
+      hits.push(`${relative}:${i + 1}: ${lines[i].trim().slice(0, 300)}`);
     }
   }
+  if (scan.stopped) return `${hits.length > 0 ? `${hits.join('\n')}\n` : ''}(stopped: ${TOO_SLOW})`;
   if (hits.length === 0) return '(no matches)';
   const capped = hits.length >= MAX_GREP_RESULTS;
   return capped
@@ -625,6 +811,20 @@ async function doGrep(root, all, input) {
     : hits.join('\n');
 }
 
+/** The paths a glob matches, under the same limit a grep runs under. */
+function doGlob(all, pattern) {
+  const scan = boundedMatcher();
+  const matched = scan(globToRegExp(pattern), all, MAX_GLOB_RESULTS).map(index => all[index]);
+  if (scan.stopped) return `${matched.length > 0 ? `${matched.join('\n')}\n` : ''}(stopped: ${TOO_SLOW})`;
+  return matched.length > 0 ? matched.join('\n') : '(no matches)';
+}
+
+/** No NUL byte, and decoding then encoding gives back exactly these bytes. */
+function isPlainText(buffer) {
+  if (buffer.includes(0)) return false;
+  return Buffer.from(buffer.toString('utf8'), 'utf8').equals(buffer);
+}
+
 function ok(id, text, isError = false) {
   return { type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], ...(isError ? { is_error: true } : {}) };
 }

package/src/run/report.js

@@ -120,7 +120,13 @@ export function stampReport(report, facts) {
   // A run the proxy cut off for money did not quit for the reason the model
   // thinks it did. `cost_cap` is in the schema's quit_reason enum precisely
   // for this.
-  if (facts.quitReason) stamped.quit_reason = facts.quitReason;
+  //
+  // The one thing the runner cannot know is whether a persona that chose to stop
+  // had finished what it came for, so the model's own `goal_reached` stands over a
+  // plain `persona_quit`. No money reads the difference; a validation's completion
+  // measure does, and without this no real run could ever have reached a goal.
+  const reachedGoal = facts.quitReason === 'persona_quit' && stamped.quit_reason === 'goal_reached';
+  if (facts.quitReason && !reachedGoal) stamped.quit_reason = facts.quitReason;
   // Why it stopped, in the runner's words rather than the model's guess: the
   // action budget ran out, the screen stopped changing, the proxy cut it off.
   if (facts.quitDetail) stamped.quit_detail = facts.quitDetail;

package/src/run/resume.js

@@ -1,4 +1,5 @@
 import { optionsFrom } from './args.js';
+import { finishJob } from './settle.js';
 import { getDeps } from './deps.js';
 import EXIT from './exit.js';
 import { runsMatchPlan } from './controllers.js';
@@ -9,6 +10,9 @@ import { createReportValidator, writeReportFiles } from './report.js';
 import * as stateFile from './state.js';
 import { playJob, resolvePersonas } from '../commands/run.js';
 
+/** Server states that only a live process can be in, and this one is resuming it. */
+const ABANDONED_MID_RUN = Object.freeze(['launching', 'playing']);
+
 /**
  * `resumeJob`, the hand-off cli-core's `resume` command makes once it has
  * decided there is something to carry on with.
@@ -58,6 +62,12 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
     log(`There is no journal for ${jobId} in this repository, so there is nothing to resume from. "ravensight-playtest upload ${jobId}" can still drain any pending uploads.`);
     return EXIT.ENVIRONMENT;
   }
+  // Its runs play two extracted commits this path knows nothing about, so playing
+  // them here would put both sides on one build.
+  if (journal.validate) {
+    log(`${jobId} is a validation. Carry on with "ravensight-playtest validate --resume ${jobId}".`);
+    return EXIT.ENVIRONMENT;
+  }
   const controllers = job.controllers?.length ? job.controllers : null;
   if (journal.job_id !== jobId || journal.game_id !== gameId ||
       JSON.stringify(journal.options?.controllers || null) !== JSON.stringify(controllers) ||
@@ -87,6 +97,12 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
       journal.runs[row.run_id] = stateFile.newRunEntry({ runId: row.run_id, module: row.module, persona: row.persona });
     }
     const entry = journal.runs[row.run_id];
+    // A process killed outright never said it was stopping, and the server refuses
+    // `launching` to `launching`, so a replay of this run would die on its first move.
+    if (ABANDONED_MID_RUN.includes(row.state)) {
+      await api.runs.transition(gameId, jobId, row.run_id, 'interrupted', { reason: 'the process that was playing it is gone' });
+      row.state = 'interrupted';
+    }
     entry.state = row.state;
     if (stateFile.RUN_DONE_STATES.includes(row.state)) entry.completed = true;
     if (Number.isFinite(Number(row.actions_taken))) entry.actions_taken = Number(row.actions_taken);
@@ -127,10 +143,12 @@ export async function resumeJob({ api, gameId, jobId, job, runs, state, repoRoot
   if (outstanding.length === 0) {
     log(`${finalized.length} interrupted run(s) were finalised from their own transcripts. Nothing left to replay.`);
     if (!isTerminalJob(job)) {
-      const settled = await api.jobs.finish(gameId, jobId, { reason: 'resumed and finalised' });
+      const settled = await finishJob({ api, gameId, jobId, body: { reason: 'resumed and finalised' }, log });
+      if (!settled) return EXIT.OK;
       journal.finished = true;
       await stateFile.save(repoRoot, journal);
       log(`job ${jobId} ${settled.job ? settled.job.state : 'finished'}: refunded ${formatCents(settled.refunded_cents)}.`);
+      if (settled.job && ['failed', 'stalled'].includes(settled.job.state)) return EXIT.FAILED;
     }
     return EXIT.OK;
   }

package/src/run/secretScan.js

@@ -169,3 +169,38 @@ export function assertNoSecrets(what, text) {
   const secrets = scanForSecrets(text);
   if (secrets.length > 0) throw new SecretsFoundError(what, secrets);
 }
+
+/**
+ * A changeset whose pull request text does not quote a secret. The text is the
+ * model's, written after reading source, and it is the one part of a changeset
+ * that can go without: a refusal here would throw away a finished change over its
+ * description. So the match goes, the developer is told without being shown it, and
+ * `assertNoSecrets` still refuses anything else in the file.
+ *
+ * @param {Object} changeset
+ * @param {(message: string) => void} [log]
+ * @returns {Object}
+ */
+export function withoutQuotedSecrets(changeset, log = () => {}) {
+  const found = scanForSecrets(`${changeset.pr_title || ''}\n${changeset.pr_body || ''}`);
+  if (found.length === 0) return changeset;
+  log(`The model's pull request text quoted something shaped like a secret (${found.map(item => item.type).join(', ')}). It was removed from the text and the change was kept. If it is a real key, rotate it.`);
+  return { ...changeset, pr_title: redactSecrets(changeset.pr_title), pr_body: redactSecrets(changeset.pr_body) };
+}
+
+/**
+ * The text with every secret shaped match replaced by `[redacted <type>]`,
+ * for local diagnostics that must still be readable. Files that are uploaded
+ * use assertNoSecrets and are refused instead.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function redactSecrets(text) {
+  let out = String(text == null ? '' : text);
+  for (const { type, regex, accept } of PATTERNS) {
+    const pattern = new RegExp(regex.source, regex.flags.includes('g') ? regex.flags : `${regex.flags}g`);
+    out = out.replace(pattern, match => (!accept || accept(match) ? `[redacted ${type}]` : match));
+  }
+  return out;
+}

package/src/run/settle.js

@@ -0,0 +1,41 @@
+/**
+ * What a job's finish call says when the server could not settle it. 409
+ * `settle_contended` is already retried by the HTTP layer on its `Retry-After`, so
+ * reaching this means the retries ran out: nothing moved, the job is still open,
+ * and it is not this CLI's to settle any other way.
+ */
+
+/** @param {string} jobId */
+export function stillOpenLine(jobId) {
+  return `job ${jobId} is still open: the server could not settle it after several tries, and no money moved. The hourly sweep will settle it, so there is nothing to do.`;
+}
+
+/**
+ * @param {string} jobId
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function settleFailureLine(jobId, error) {
+  if (error && error.code === 'settle_contended') return stillOpenLine(jobId);
+  return `the job could not be settled now; the hourly sweep will settle it: ${String(error && error.message)}`;
+}
+
+/**
+ * `api.jobs.finish`, except a contended settle is an answer rather than a crash at
+ * the end of a run that already did its work.
+ *
+ * @returns {Promise<Object|null>} the finish answer, or null when the job is still open
+ */
+export async function finishJob({ api, gameId, jobId, body, log }) {
+  try {
+    const finished = await api.jobs.finish(gameId, jobId, body);
+    if (finished && finished.refund_limited_note) log(finished.refund_limited_note);
+    return finished;
+  } catch (error) {
+    if (!error || error.code !== 'settle_contended') throw error;
+    log(stillOpenLine(jobId));
+    return null;
+  }
+}
+
+export default { stillOpenLine, settleFailureLine, finishJob };

package/src/run/tools.js

@@ -35,6 +35,12 @@ export const NOTE_KINDS = Object.freeze(['bug', 'confusing', 'good', 'suggestion
 /** Severities, from the report schema's finding severity enum. */
 export const SEVERITIES = Object.freeze(['blocker', 'major', 'minor', 'cosmetic', 'praise']);
 
+/** The longest a persona may hold a key in one action (godot_driver's own cap). */
+export const MAX_HOLD_MS = 5000;
+
+/** Extra keys one key action may hold together with `key`, for a diagonal. */
+export const MAX_WITH_KEYS = 2;
+
 /** Tools that spend an action. */
 export const ACTION_TOOLS = Object.freeze(['click', 'type', 'key', 'navigate', 'swipe']);
 
@@ -111,13 +117,15 @@ 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. 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.',
+    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. A press without hold_ms is a tap of about one frame, which moves a character a pixel or two: to walk or run, set hold_ms (up to ${MAX_HOLD_MS}) and the key is held that long while the game runs. with_keys holds more keys at the same time, such as with_keys ["s"] with key "d" to move diagonally. On godot_driver the game is paused between your actions and runs only while one executes, so thinking costs no game time.`,
     input_schema: {
       type: 'object',
       additionalProperties: false,
       required: ['key'],
       properties: {
         key: { type: 'string' },
+        hold_ms: { type: 'integer', minimum: 0, maximum: MAX_HOLD_MS, description: 'How long to hold the key down, in milliseconds of game time. Leave out for a tap.' },
+        with_keys: { type: 'array', maxItems: MAX_WITH_KEYS, items: { type: 'string' }, description: 'Keys held down together with key for the same time, such as ["s"] for a diagonal.' },
         thought_in_character: thought,
         note
       }
@@ -205,8 +213,14 @@ export function actionFor(toolUse) {
       if (typeof input.ref === 'string' && input.ref.trim()) action.ref = input.ref.trim();
       return action;
     }
-    case 'key':
-      return { kind: 'key', key: String(input.key || '') };
+    case 'key': {
+      const action = { kind: 'key', key: String(input.key || '') };
+      const hold = Math.min(Math.round(Number(input.hold_ms) || 0), MAX_HOLD_MS);
+      if (hold > 0) action.holdMs = hold;
+      const extra = Array.isArray(input.with_keys) ? input.with_keys.filter(key => typeof key === 'string' && key.trim()).slice(0, MAX_WITH_KEYS) : [];
+      if (extra.length > 0) action.keys = extra;
+      return action;
+    }
     case 'navigate':
       return { kind: 'navigate', url: String(input.url || '') };
     case 'wait':
@@ -251,6 +265,16 @@ export async function executeTool({ driver, toolUse, onNote, onScreenshot, stale
   if (toolUse.name === 'screenshot') {
     try {
       const shot = await driver.screenshot(String(input.name || 'shot'));
+      // Saved nothing (headless Godot): no file to list, cite or claim.
+      if (!shot || !shot.relativePath) {
+        return {
+          result: toolResult(toolUse.id, `No screenshot was saved here (${(shot && shot.skipped) || 'the driver returned no file'}), so there is nothing to cite. Describe what you saw in a note.`),
+          observation: null,
+          spentAction: false,
+          changed: false,
+          error: null
+        };
+      }
       if (onScreenshot) onScreenshot({ ...shot, reason: String(input.reason || '') });
       return {
         result: toolResult(toolUse.id, `Saved ${shot.relativePath}.`),
@@ -301,7 +325,12 @@ export async function executeTool({ driver, toolUse, onNote, onScreenshot, stale
   // before anything reaches the game.
   // A ref in a later tool call of a turn whose earlier call already changed
   // the screen was read off a screen that is gone.
-  const outcome = action.ref && !driver.supportsRefs
+  // A hold sent to a driver that can only tap would be a one frame tap the
+  // persona believes was a walk, which is the 0.5.0 Godot failure in reverse.
+  const wantsHold = action.kind === 'key' && (action.holdMs > 0 || (action.keys && action.keys.length > 0));
+  const outcome = wantsHold && !driver.supportsHold
+    ? { ok: false, changed: false, error: `${driver.name || 'this driver'} cannot hold keys; send key without hold_ms or with_keys`, driverError: true }
+    : action.ref && !driver.supportsRefs
     ? { ok: false, changed: false, error: `ref targets are only available on playwright_web; ${driver.name || 'this driver'} takes a named target or coordinates`, driverError: true }
     : action.ref && staleRefs
       ? { ok: false, changed: false, error: STALE_REF_MESSAGE, driverError: true }