ravensight-playtest 0.5.2 → 0.7.0

package/src/run/checks.js

@@ -0,0 +1,705 @@
+import { execFileSync, spawn as spawnProcess } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { copyProjectTree, detectGodotBinary, isGodotProject, measureProject } from './drivers/godot-project.js';
+import { stopAll, track } from './liveWork.js';
+import { isSecretPath } from './repoTools.js';
+
+/**
+ * Fix v2's named checks: the only way a model step ever causes a process to
+ * run on the developer's machine, and the reason it is a fixed list rather
+ * than a shell.
+ *
+ * - `godot_import`: `godot --headless --path <copy> --import`, then every
+ *   script error in its output. Godot exits 0 with parse errors in the log, so
+ *   the exit code alone proves nothing; the log is what is read.
+ * - `godot_script_check`: `--check-only --script` over each changed `.gd`
+ *   file, after the same import, so a script naming a global class resolves.
+ * - `project_tests`: GUT or gdUnit4, found by their addon folder, with a
+ *   timeout. A project with neither answers `unavailable`, not `passed`.
+ *
+ * Every check runs on a fresh temporary copy of the project, never on the
+ * developer's directory, with a time limit and an output cap, and the copy is
+ * removed afterwards. Arguments are fixed here; nothing the model sends
+ * reaches a command line except the choice of check name, which is matched
+ * against `CHECK_NAMES`.
+ */
+
+export const CHECK_NAMES = Object.freeze(['godot_import', 'godot_script_check', 'project_tests']);
+
+/** Time limits, per check. A check that runs over is a failure, never a pass. */
+export const CHECK_TIMEOUTS_MS = Object.freeze({
+  godot_import: 180000,
+  godot_script_check: 120000,
+  project_tests: 300000
+});
+
+/** Bytes of output kept per check, whatever the process printed. */
+export const MAX_CHECK_OUTPUT_BYTES = 64 * 1024;
+
+/** Characters of a check's result a model turn is shown. */
+export const MAX_CHECK_RESULT_CHARS = 4000;
+
+/** At most this many errors are listed per check. */
+export const MAX_CHECK_ERRORS = 40;
+
+/** Never copied into the check's temp project. */
+export const CHECK_COPY_EXCLUDES = Object.freeze(['.git', '.ravensight', 'node_modules', '.DS_Store']);
+
+/** The tool definition offered to `fix.apply` when the job runs Fix v2. */
+export const RUN_CHECK_TOOL = Object.freeze({
+  name: 'run_check',
+  description: 'Run one named check on a temporary copy of the project as it is now, with your edits. godot_import imports the project headless and lists script errors; godot_script_check parses each changed .gd file; project_tests runs the project\'s GUT or gdUnit4 tests. No other command can be run.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['check'],
+    properties: { check: { type: 'string', enum: [...CHECK_NAMES] } }
+  }
+});
+
+/* eslint-disable-next-line no-control-regex */
+const ANSI = /\u001b\[[0-9;]*m/g;
+
+/** The lines of Godot output that mean a script did not load. */
+const ERROR_LINE = /^(SCRIPT ERROR:|ERROR: Failed to load script|ERROR: .*Parse error|Parse Error:|Compile Error:)/;
+
+/**
+ * The script errors in a Godot log, each with its `at:` line when there is one.
+ *
+ * @param {string} output
+ * @returns {Array<string>}
+ */
+export function parseGodotErrors(output) {
+  const lines = String(output || '').replace(ANSI, '').split(/\r?\n/);
+  const errors = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!ERROR_LINE.test(line)) continue;
+    const next = (lines[i + 1] || '').trim();
+    const where = /^at: /.test(next) ? ` (${next.replace(/^at: /, '')})` : '';
+    const entry = `${line}${where}`;
+    if (!errors.includes(entry)) errors.push(entry);
+    if (errors.length >= MAX_CHECK_ERRORS) break;
+  }
+  return errors;
+}
+
+/**
+ * The autoload names a project registers, from its `project.godot` text.
+ *
+ * @param {string} text
+ * @returns {Array<string>}
+ */
+export function autoloadNames(text) {
+  const names = [];
+  let inSection = false;
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith('[')) inSection = line === '[autoload]';
+    else if (inSection) {
+      const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+      if (match) names.push(match[1]);
+    }
+  }
+  return names;
+}
+
+/**
+ * `--check-only` stops before Godot registers the autoloads, so any script that
+ * names one fails there with "Identifier not found" although the game runs it
+ * fine. Those errors, and the "failed to load" that follows from them, are not
+ * about the script. Nor is the "failed to compile depended scripts" a script
+ * gets for using a class that names one: a real mistake in that class would be
+ * its own entry here. Anything else in the list still stands: the analyzer's own
+ * errors come first, so a real mistake is reported beside or before these.
+ *
+ * @param {Array<string>} errors from parseGodotErrors
+ * @param {Array<string>} names from autoloadNames
+ * @returns {Array<string>} what is left; empty means the script is fine
+ */
+export function withoutAutoloadAlarms(errors, names) {
+  const isAutoload = entry => names.some(name => new RegExp(`Identifier not found: ${name}\\b`).test(entry));
+  if (!errors.some(isAutoload)) return errors;
+  const left = errors.filter(entry => !isAutoload(entry));
+  return left.every(entry => /Failed to load script .*"Compilation failed"|Failed to compile depended scripts/.test(entry)) ? [] : left;
+}
+
+/**
+ * Which test runner the project ships, by its addon folder.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<'gut'|'gdunit4'|null>}
+ */
+export async function detectTestRunner(projectDir) {
+  const has = async relative => Boolean(await fs.stat(path.join(projectDir, relative)).catch(() => null));
+  if (await has('addons/gut/gut_cmdln.gd')) return 'gut';
+  if (await has('addons/gdUnit4/bin/GdUnitCmdTool.gd')) return 'gdunit4';
+  return null;
+}
+
+/**
+ * The arguments for a test runner. Fixed: the project picks the runner by
+ * shipping it, nothing picks the arguments.
+ *
+ * @param {'gut'|'gdunit4'} runner
+ * @param {string} copy
+ * @returns {Array<string>}
+ */
+export function testArgs(runner, copy) {
+  if (runner === 'gut') return ['--headless', '--path', copy, '-s', 'res://addons/gut/gut_cmdln.gd', '-gexit'];
+  return ['--headless', '--path', copy, '-s', 'res://addons/gdUnit4/bin/GdUnitCmdTool.gd', '--ignoreHeadlessMode', '-a', 'res://test'];
+}
+
+/**
+ * The environment a check's Godot sees: PATH and the locale from the
+ * developer's environment, and nothing else from it. HOME, the temp dirs and
+ * Godot's user-data dirs (HOME on macOS, XDG on Linux, APPDATA on Windows)
+ * all point into the check's own temp root. No token, provider key, agent
+ * socket or cloud credential can reach the edited project's code this way.
+ *
+ * @param {{root: string|null, env?: Object, platform?: string}} args
+ * @returns {Object}
+ */
+export function checkEnv({ root = null, env = process.env, platform = process.platform } = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (value === undefined) continue;
+    if (/^path$/i.test(key) || key === 'LANG' || /^LC_[A-Z_]+$/.test(key)) out[key] = value;
+    if (platform === 'win32' && /^systemroot$/i.test(key)) out.SystemRoot = value;
+  }
+  if (!root) return out;
+  const home = path.join(root, 'home');
+  const tmp = path.join(root, 'tmp');
+  Object.assign(out, {
+    HOME: home,
+    TMPDIR: tmp,
+    TMP: tmp,
+    TEMP: tmp,
+    XDG_DATA_HOME: path.join(home, '.local', 'share'),
+    XDG_CONFIG_HOME: path.join(home, '.config'),
+    XDG_CACHE_HOME: path.join(home, '.cache')
+  });
+  if (platform === 'win32') {
+    out.APPDATA = path.join(root, 'appdata');
+    out.LOCALAPPDATA = path.join(root, 'localappdata');
+  }
+  return out;
+}
+
+/** The directories `checkEnv` points into, created before the first spawn. */
+async function makeEnvDirs(environment) {
+  for (const key of ['HOME', 'TMPDIR', 'XDG_DATA_HOME', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'APPDATA', 'LOCALAPPDATA']) {
+    if (environment[key]) await fs.mkdir(environment[key], { recursive: true });
+  }
+}
+
+/** Where macOS keeps `sandbox-exec`. */
+export const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+
+/**
+ * `sandbox-exec` when this is macOS and it exists, else null. Elsewhere no OS
+ * sandbox is applied: the minimal environment and the temp copy are the
+ * whole of the isolation, and the README says so.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function detectSandbox({ platform = process.platform, file = SANDBOX_EXEC } = {}) {
+  if (platform !== 'darwin') return null;
+  try {
+    await fs.access(file, fs.constants.X_OK);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where a developer's credentials live, relative to the real home. A check runs with
+ * its own HOME, but code can name a path outright, and whatever a failing check prints
+ * goes to the model. Named rather than the whole home, because a project may link to
+ * shared assets that live there.
+ */
+export const CREDENTIAL_STORES = Object.freeze([
+  '.ssh', '.aws', '.gnupg', '.kube', '.docker', '.azure', '.config/gh', '.config/gcloud', '.config/ravensight',
+  '.config/ravensight-playtest', '.ravensight', '.ravensight-playtest', '.netrc', '.git-credentials', '.npmrc', '.pypirc', '.pgpass', 'Library/Keychains'
+]);
+
+function sbString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * The macOS sandbox profile for one check: no network at all, and no write
+ * anywhere but the check's temp root (named both ways, because /var is a
+ * link to /private/var) and the null and tty devices.
+ *
+ * Reads are open, because Godot needs the system, except for `CREDENTIAL_STORES`.
+ *
+ * @param {Array<string>} roots
+ * @param {{home?: string|null}} [options] the developer's real home
+ * @returns {string}
+ */
+export function sandboxProfile(roots, { home = null } = {}) {
+  const allowed = [...new Set(roots)].map(root => `(subpath ${sbString(root)})`).join(' ');
+  return [
+    '(version 1)',
+    '(allow default)',
+    '(deny network*)',
+    ...(home ? [`(deny file-read* ${CREDENTIAL_STORES.map(store => `(subpath ${sbString(path.join(home, store))})`).join(' ')})`] : []),
+    '(deny file-write*)',
+    `(allow file-write* ${allowed} (literal "/dev/null") (literal "/dev/tty") (literal "/dev/dtracehelper") (regex #"^/dev/fd/"))`
+  ].join('\n');
+}
+
+/**
+ * Paths an edit may not touch for a check to run without --allow-tool-scripts. Case
+ * blind, because the filesystems on macOS and Windows are. A `.gdextension` names a
+ * native library for the editor to load.
+ */
+const TOOL_PATHS = [/^project\.godot$/i, /^export_presets\.cfg$/i, /^override\.cfg$/i, /^addons\//i, /^\.godot\//i, /\.gdextension$/i];
+
+/** A GDScript file that runs in the editor, which is to say during an import. */
+const TOOL_ANNOTATION = /^[ \t]*(?:@\w+(?:\([^)\n]*\))?[ \t]+)*@tool\b/m;
+
+function posix(file) {
+  return String(file).split(path.sep).join('/').replace(/^\.\//, '');
+}
+
+/**
+ * Why the edits make an import unsafe to run, or null. Editor-side code runs
+ * during `--import`: project settings and autoloads, export presets, addons
+ * (editor plugins), the import cache, and any `@tool` script.
+ *
+ * @param {string} projectDir
+ * @param {Array<string>} files project relative paths the fix changed
+ * @returns {Promise<string|null>}
+ */
+export async function toolScriptRefusal(projectDir, files) {
+  const hits = [];
+  for (const raw of files) {
+    const file = posix(raw);
+    if (TOOL_PATHS.some(pattern => pattern.test(file))) {
+      hits.push(file);
+      continue;
+    }
+    if (file.endsWith('.gd')) {
+      const text = await fs.readFile(path.join(projectDir, file), 'utf8').catch(() => '');
+      if (TOOL_ANNOTATION.test(text)) hits.push(`${file} (@tool)`);
+    }
+  }
+  if (hits.length === 0) return null;
+  return `the fix edited code that runs inside the Godot editor during an import (${hits.slice(0, 5).join(', ')}); pass --allow-tool-scripts to run checks on it`;
+}
+
+/** The test directories a runner is configured with, as project relative prefixes. */
+async function configuredTestDirs(projectDir) {
+  const dirs = [];
+  const gut = await fs.readFile(path.join(projectDir, '.gutconfig.json'), 'utf8').catch(() => null);
+  if (gut) {
+    try {
+      const parsed = JSON.parse(gut);
+      for (const dir of Array.isArray(parsed.dirs) ? parsed.dirs : []) {
+        const relative = posix(String(dir).replace(/^res:\/\//, '')).replace(/\/+$/, '');
+        if (relative) dirs.push(`${relative}/`);
+      }
+    } catch {
+      // An unreadable config names no directories; the name patterns still apply.
+    }
+  }
+  return dirs;
+}
+
+const TEST_FILE = [/(^|\/)tests?\//, /(^|\/)test_[^/]*\.gd$/, /Test\.gd$/, /_test\.gd$/];
+
+/**
+ * Why the edits touched test code, or null. Test scripts are executed by
+ * project_tests and parsed by the import, so a fix that writes them needs the
+ * developer's --allow-tests.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function testFileRefusal(projectDir, files) {
+  const configured = await configuredTestDirs(projectDir);
+  const hits = files.map(posix).filter(file => TEST_FILE.some(pattern => pattern.test(file)) || configured.some(dir => file.startsWith(dir)));
+  if (hits.length === 0) return null;
+  return `the fix created or changed test files (${hits.slice(0, 5).join(', ')}); pass --allow-tests to run checks on them`;
+}
+
+/** Ends every check running now. Ctrl-C uses it: a check can run for minutes. */
+export function stopRunningChecks() {
+  stopAll();
+}
+
+/**
+ * Every process under this one, from `ps`. A process group is not enough on its own:
+ * Godot's `OS.create_process` starts a new session, which leaves the group.
+ *
+ * @param {number} pid
+ * @returns {Array<number>}
+ */
+export function descendantsOf(pid) {
+  try {
+    const children = new Map();
+    for (const line of execFileSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', timeout: 2000 }).split('\n')) {
+      const [child, parent] = line.trim().split(/\s+/).map(Number);
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(child);
+    }
+    const found = [];
+    const walk = (id) => {
+      for (const child of children.get(id) || []) {
+        found.push(child);
+        walk(child);
+      }
+    };
+    walk(pid);
+    return found;
+  } catch {
+    return [];
+  }
+}
+
+/** How long a process that has exited may keep its pipes open before it is done. */
+const DRAIN_MS = 1000;
+
+/**
+ * Run one process with a timeout and an output cap. Never a shell. With no
+ * `env` the child gets the minimal allowlist, never `process.env`, so no
+ * caller inherits the developer's secrets by leaving the option out.
+ *
+ * In its own process group, because killing one process does not kill what it
+ * started: `OS.create_process` in a game or an addon outlives a timeout otherwise, and
+ * holds this function's pipes open as well. The group goes when the process does.
+ *
+ * @returns {Promise<{exitCode: number|null, output: string, timedOut: boolean, error: string|null}>}
+ */
+export function runBounded(command, args, { cwd, env = checkEnv({ root: null }), timeoutMs, maxBytes = MAX_CHECK_OUTPUT_BYTES, spawnFn = spawnProcess }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnFn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], shell: false, detached: process.platform !== 'win32' });
+    } catch (error) {
+      resolve({ exitCode: null, output: '', timedOut: false, error: error.message });
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    const take = (chunk) => {
+      if (size >= maxBytes) {
+        truncated = true;
+        return;
+      }
+      const buffer = Buffer.from(chunk);
+      const room = maxBytes - size;
+      chunks.push(buffer.subarray(0, room));
+      size += Math.min(room, buffer.length);
+      if (buffer.length > room) truncated = true;
+    };
+    child.stdout?.on('data', take);
+    child.stderr?.on('data', take);
+    let settled = false;
+    let timedOut = false;
+    let stopped = false;
+    const killGroup = () => {
+      try {
+        if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        // Already gone.
+      }
+    };
+    // While it still runs, its descendants can still be named.
+    const killTree = () => {
+      if (process.platform !== 'win32' && child.pid) {
+        for (const pid of descendantsOf(child.pid)) {
+          try {
+            process.kill(pid, 'SIGKILL');
+          } catch {
+            // Already gone.
+          }
+        }
+      }
+      killGroup();
+    };
+    const untrack = track({
+      stop: () => {
+        stopped = true;
+        killTree();
+        done(null, 'stopped');
+      }
+    });
+    const done = (exitCode, error = null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(drain);
+      untrack();
+      const output = Buffer.concat(chunks).toString('utf8') + (truncated ? '\n(output cut at the cap)' : '');
+      resolve({ exitCode, output, timedOut, error });
+    };
+    let drain = null;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree();
+      done(null, `timed out after ${Math.round(timeoutMs / 1000)} s`);
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', error => done(null, error.message));
+    child.on('exit', (code) => {
+      // Whatever it left behind goes now, which is what lets the pipes close.
+      killGroup();
+      if (!stopped) drain = setTimeout(() => done(code), DRAIN_MS);
+    });
+    child.on('close', code => done(code));
+  });
+}
+
+/**
+ * A plain copy of the project for one check: no addon injected, no
+ * `.git`, no journals.
+ *
+ * @param {string} projectDir
+ * @returns {Promise<{root: string, copy: string}>}
+ */
+export async function copyForCheck(projectDir, { excludes = CHECK_COPY_EXCLUDES } = {}) {
+  await measureProject(projectDir, { excludes: [...excludes] });
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ravensight-check-'));
+  await fs.chmod(root, 0o700);
+  const copy = path.join(root, 'project');
+  // No link survives: an import writes `.import` files beside the art it finds, and
+  // through a link that is the developer's own folder. And no credential file: game
+  // code runs on this copy, and what a failing check prints goes to the model.
+  try {
+    await copyProjectTree(projectDir, copy, { excludes, skip: source => isSecretPath(path.relative(projectDir, source)) });
+  } catch (error) {
+    // A half written copy has no owner yet, so it goes here. A full disk ends up here.
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+  return { root, copy };
+}
+
+/**
+ * The checks for one fix, bound to one project and one Godot binary.
+ *
+ * `run(name)` always resolves, with a result whose `status` is `passed`,
+ * `failed` or `unavailable`. Unavailable is not failed: a project with no
+ * tests, or a machine with no Godot, is told so rather than blocked.
+ *
+ * @param {Object} args
+ * @param {string|null} args.projectDir the Godot project, or null when there is none
+ * @param {string|null} [args.godotPath] an explicit binary
+ * @param {() => Promise<Array<string>>} [args.changedFiles] project relative paths changed so far
+ * @returns {{available: boolean, run: (name: string) => Promise<Object>, results: Array<Object>}}
+ */
+export function createCheckRunner({
+  projectDir,
+  godotPath = null,
+  changedFiles = async () => [],
+  env = process.env,
+  timeouts = CHECK_TIMEOUTS_MS,
+  spawnFn = spawnProcess,
+  detect = detectGodotBinary,
+  copy = copyForCheck,
+  now = () => Date.now(),
+  allowToolScripts = false,
+  allowTests = false,
+  sandbox = undefined,
+  platform = process.platform
+}) {
+  const results = [];
+  let sandboxPath = sandbox;
+  let binary;
+
+  async function godot() {
+    if (binary !== undefined) return binary;
+    try {
+      const found = await detect({ explicitPath: godotPath || undefined, projectDir, env });
+      binary = found.path;
+    } catch {
+      binary = null;
+    }
+    return binary;
+  }
+
+  async function unavailable(name, why, started) {
+    return { name, status: 'unavailable', ok: null, durationMs: now() - started, errors: [], detail: why, output: '' };
+  }
+
+  /**
+   * One Godot process for a check: the minimal environment rooted in the
+   * check's temp root, and on macOS inside sandbox-exec when it exists.
+   */
+  async function launch(binaryPath, args, made, timeoutMs) {
+    if (sandboxPath === undefined) sandboxPath = await detectSandbox({ platform });
+    const environment = checkEnv({ root: made.root, env, platform });
+    await makeEnvDirs(environment);
+    if (!sandboxPath) return runBounded(binaryPath, args, { cwd: made.copy, env: environment, timeoutMs, spawnFn });
+    const real = await fs.realpath(made.root).catch(() => made.root);
+    return runBounded(sandboxPath, ['-p', sandboxProfile([made.root, real], { home: os.homedir() }), binaryPath, ...args], { cwd: made.copy, env: environment, timeoutMs, spawnFn });
+  }
+
+  async function importInto(made, binaryPath, deadline) {
+    return launch(binaryPath, ['--headless', '--path', made.copy, '--import'], made, deadline);
+  }
+
+  async function runOne(name) {
+    const started = now();
+    if (!CHECK_NAMES.includes(name)) {
+      return { name: String(name), status: 'refused', ok: null, durationMs: 0, errors: [], detail: `there is no check called ${name}; the checks are ${CHECK_NAMES.join(', ')}`, output: '' };
+    }
+    if (!projectDir || !(await isGodotProject(projectDir))) return unavailable(name, 'there is no Godot project to check', started);
+    if (name === 'project_tests' && !allowTests) {
+      return unavailable(name, 'project tests run only when the developer allows them with --allow-tests', started);
+    }
+    // Every check imports the project, and an import runs editor-side code.
+    // An edit to that code, or to tests, is not run without the developer's say.
+    const changed = await changedFiles();
+    const refusal = (allowToolScripts ? null : await toolScriptRefusal(projectDir, changed))
+      || (allowTests ? null : await testFileRefusal(projectDir, changed));
+    if (refusal) {
+      return { name, status: 'check_refused', ok: false, durationMs: now() - started, errors: [], detail: refusal, output: '' };
+    }
+    const binaryPath = await godot();
+    if (!binaryPath) return unavailable(name, 'no Godot 4.2+ binary was found; pass --godot-path or set RAVENSIGHT_GODOT', started);
+
+    let runner = null;
+    let scripts = [];
+    if (name === 'project_tests') {
+      runner = await detectTestRunner(projectDir);
+      if (!runner) return unavailable(name, 'the project ships neither GUT (addons/gut) nor gdUnit4 (addons/gdUnit4)', started);
+    }
+    if (name === 'godot_script_check') {
+      scripts = changed.filter(file => file.endsWith('.gd') && !file.startsWith('..'));
+      if (scripts.length === 0) return unavailable(name, 'no .gd file has changed', started);
+    }
+
+    let made;
+    try {
+      made = await copy(projectDir);
+    } catch (error) {
+      return { name, status: 'failed', ok: false, durationMs: now() - started, errors: [], detail: `the project could not be copied: ${error.message}`, output: '' };
+    }
+    const release = track({ root: made.root });
+    try {
+      const budget = timeouts[name];
+      const imported = await importInto(made, binaryPath, budget);
+      let output = imported.output;
+      let exitCode = imported.exitCode;
+      let failure = imported.error;
+      if (name === 'godot_script_check' && !failure) {
+        const autoloads = autoloadNames(await fs.readFile(path.join(made.copy, 'project.godot'), 'utf8').catch(() => ''));
+        for (const script of scripts) {
+          const remaining = Math.max(1000, budget - (now() - started));
+          const checked = await launch(binaryPath, ['--headless', '--path', made.copy, '--check-only', '--script', `res://${script.split(path.sep).join('/')}`], made, remaining);
+          output = checked.output;
+          if (checked.error) failure = checked.error;
+          const reported = parseGodotErrors(checked.output);
+          const errors = withoutAutoloadAlarms(reported, autoloads);
+          // Only the autoload alarm explains a non-zero exit with nothing left.
+          if (reported.length > 0 && errors.length === 0) continue;
+          if (errors.length > 0 || checked.exitCode !== 0) {
+            exitCode = checked.exitCode;
+            output = `${script}:\n${checked.output}`;
+            const result = finish(name, started, { exitCode: checked.exitCode, output, failure, errors });
+            return result;
+          }
+        }
+        return finish(name, started, { exitCode: 0, output: `${scripts.length} script(s) parsed: ${scripts.join(', ')}`, failure, errors: [] });
+      }
+      if (name === 'project_tests' && !failure) {
+        const remaining = Math.max(1000, budget - (now() - started));
+        const tested = await launch(binaryPath, testArgs(runner, made.copy), made, remaining);
+        return finish(name, started, { exitCode: tested.exitCode, output: tested.output, failure: tested.error, errors: parseGodotErrors(tested.output), runner });
+      }
+      return finish(name, started, { exitCode, output, failure, errors: parseGodotErrors(output) });
+    } finally {
+      await fs.rm(made.root, { recursive: true, force: true }).catch(() => {});
+      release();
+    }
+  }
+
+  function finish(name, started, { exitCode, output, failure, errors, runner = null }) {
+    const ok = !failure && exitCode === 0 && errors.length === 0;
+    const detail = failure
+      ? failure
+      : errors.length > 0
+        ? `${errors.length} script error(s)`
+        : exitCode === 0 ? 'no errors' : `exit ${exitCode}`;
+    return {
+      name,
+      status: ok ? 'passed' : 'failed',
+      ok,
+      durationMs: now() - started,
+      errors,
+      detail,
+      output: String(output || '').replace(ANSI, ''),
+      ...(runner ? { runner } : {})
+    };
+  }
+
+  return {
+    get available() {
+      return Boolean(projectDir);
+    },
+    results,
+    async run(name) {
+      const result = await runOne(name);
+      results.push(result);
+      return result;
+    }
+  };
+}
+
+/**
+ * A check result as a model turn reads it: the verdict, the errors, and the
+ * tail of the output, capped.
+ *
+ * @param {Object} result
+ * @returns {string}
+ */
+export function checkResultText(result) {
+  const head = `${result.name}: ${result.status} (${result.detail}, ${Math.round((result.durationMs || 0) / 100) / 10} s)`;
+  const errors = result.errors && result.errors.length > 0 ? `\nerrors:\n${result.errors.map(line => `- ${line}`).join('\n')}` : '';
+  const room = Math.max(0, MAX_CHECK_RESULT_CHARS - head.length - errors.length - 20);
+  const output = result.status === 'failed' && !errors && result.output ? `\noutput (tail):\n${result.output.slice(-room)}` : '';
+  return `${head}${errors}${output}`.slice(0, MAX_CHECK_RESULT_CHARS);
+}
+
+/**
+ * The repo tools plus `run_check`, as one tool surface for `fix.apply`.
+ *
+ * A model may run at most `maxRuns` checks per apply turn set: each can take
+ * minutes of the developer's machine.
+ *
+ * @param {Object} repo a `createRepoTools` surface
+ * @param {Object} checks a `createCheckRunner` surface
+ * @param {{maxRuns?: number}} [options]
+ * @returns {Object}
+ */
+export function withRunCheck(repo, checks, { maxRuns = 6 } = {}) {
+  let runs = 0;
+  return {
+    tools: [...repo.tools, RUN_CHECK_TOOL],
+    get written() {
+      return repo.written;
+    },
+    async execute(toolUse) {
+      if (toolUse.name !== 'run_check') return repo.execute(toolUse);
+      const answer = text => ({ result: { type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text }], ...(text.startsWith('refused') ? { is_error: true } : {}) } });
+      const name = toolUse.input && toolUse.input.check;
+      if (!CHECK_NAMES.includes(name)) return answer(`refused: the checks are ${CHECK_NAMES.join(', ')}`);
+      if (runs >= maxRuns) return answer(`refused: ${maxRuns} checks have run this turn set, which is the limit`);
+      runs += 1;
+      const result = await checks.run(name);
+      const out = answer(checkResultText(result));
+      if (result.status === 'failed') out.result.is_error = true;
+      return out;
+    }
+  };
+}
+
+export default { createCheckRunner, parseGodotErrors, detectTestRunner, withRunCheck, checkResultText, RUN_CHECK_TOOL, CHECK_NAMES };