ruvnet-brain 4.7.22 → 4.7.23

package/README.md

@@ -9,7 +9,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 ### Discover the stack. Read the source. Build with confidence.
 
-[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.22-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
+[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.23-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
 
 **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.22",
+  "version": "4.7.23",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -77,6 +77,7 @@
     "deferral:replay": "node scripts/deferral-replay.mjs",
     "hooks:check": "node scripts/hook-retirement-check.mjs",
     "release:qualify": "node scripts/release-qualification.mjs",
+    "release:prepush": "node scripts/release-prepush.mjs",
     "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs",
     "single-source:check": "node scripts/single-source-check.mjs",
     "host:codex:execution-proof": "node scripts/codex-host-execution-proof.mjs"

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.7.22",
+  "version": "4.7.23",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.22",
+  "version": "4.7.23",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/scripts/generation-census.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// DISTINCT-FROM: kb/zip-extract.mjs — that extracts a whole local archive from a file descriptor; this reads only the idmap sidecars of a REMOTE release asset over HTTP Range and never fetches the ~750 MB body.
+//
+// scripts/generation-census.mjs — the public census (public stores, chunks) of a published corpus
+// generation, read straight from its release asset without downloading it.
+//
+// Release QE requires the committed claim surfaces (README, explainer/*) to quote the exact census of
+// the NEWEST corpus generation, and the corpus republishes nightly. Assembling a candidate to learn
+// two numbers costs ~750 MB and a minute; the numbers live in ~200 small `*.big.rvf.idmap.json`
+// members of the zip. So: Range-read the end-of-central-directory, the central directory, and each
+// idmap member; inflate, CRC-check, count `idToLabel` keys; exclude the private fence exactly as
+// scripts/claims-verify.mjs computePublicChunkTotal does. Anything unexpected (zip64, another
+// compression method, a CRC mismatch, a short read) fails loudly — a wrong census is worse than none.
+//
+//   node scripts/generation-census.mjs --repo owner/name --tag corpus-sha256-<digest>
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const ARCHIVE_ASSET = 'ruvnet-brain.zip';
+export const IDMAP_SUFFIX = '.big.rvf.idmap.json';
+const TAIL_BYTES = 66_000; // EOCD (22) + the largest possible comment (65,535) + the zip64 locator (20)
+const SIG = { eocd: 0x06054b50, zip64Locator: 0x07064b50, central: 0x02014b50, local: 0x04034b50 };
+const U16 = 0xffff;
+const U32 = 0xffffffff;
+const CONCURRENCY = 8;
+
+const zip64 = (what) => new Error(`zip64 ${what}: this reader refuses zip64 archives rather than guess at their layout`);
+
+/** End-of-central-directory from the archive's last bytes. */
+export function parseEocd(tail) {
+  for (let i = tail.length - 22; i >= 0; i -= 1) {
+    if (tail.readUInt32LE(i) !== SIG.eocd) continue;
+    if (i >= 20 && tail.readUInt32LE(i - 20) === SIG.zip64Locator) throw zip64('end-of-central-directory locator');
+    const disk = tail.readUInt16LE(i + 4), cdDisk = tail.readUInt16LE(i + 6);
+    const onDisk = tail.readUInt16LE(i + 8), total = tail.readUInt16LE(i + 10);
+    const cdSize = tail.readUInt32LE(i + 12), cdOffset = tail.readUInt32LE(i + 16);
+    if (total === U16 || onDisk === U16 || cdSize === U32 || cdOffset === U32) throw zip64('marker in the end-of-central-directory');
+    if (disk !== 0 || cdDisk !== 0 || onDisk !== total) throw new Error('multi-disk zip archives are not supported');
+    return { total, cdSize, cdOffset };
+  }
+  throw new Error('no end-of-central-directory record in the archive tail');
+}
+
+/** Every central-directory entry: name, method, flags, crc, sizes, local-header offset. */
+export function parseCentralDirectory(cd, expected) {
+  const entries = [];
+  let p = 0;
+  while (p < cd.length) {
+    if (p + 46 > cd.length || cd.readUInt32LE(p) !== SIG.central) throw new Error(`malformed central directory at byte ${p}`);
+    const nameLength = cd.readUInt16LE(p + 28), extraLength = cd.readUInt16LE(p + 30), commentLength = cd.readUInt16LE(p + 32);
+    const entry = {
+      name: cd.subarray(p + 46, p + 46 + nameLength).toString('utf8'),
+      flags: cd.readUInt16LE(p + 8), method: cd.readUInt16LE(p + 10), crc: cd.readUInt32LE(p + 16),
+      compressedSize: cd.readUInt32LE(p + 20), size: cd.readUInt32LE(p + 24), offset: cd.readUInt32LE(p + 42),
+      extraLength,
+    };
+    if (entry.compressedSize === U32 || entry.size === U32 || entry.offset === U32) throw zip64(`marker on entry ${entry.name}`);
+    const extra = cd.subarray(p + 46 + nameLength, p + 46 + nameLength + extraLength);
+    for (let q = 0; q + 4 <= extra.length; q += 4 + extra.readUInt16LE(q + 2)) {
+      if (extra.readUInt16LE(q) === 0x0001) throw zip64(`extra field on entry ${entry.name}`);
+    }
+    entries.push(entry);
+    p += 46 + nameLength + extraLength + commentLength;
+  }
+  if (Number.isInteger(expected) && entries.length !== expected) {
+    throw new Error(`central directory lists ${entries.length} entries; the end record says ${expected}`);
+  }
+  return entries;
+}
+
+/** The public idmap members: no resource forks, no private store, no store counted twice. */
+export function selectIdmapEntries(entries, privateStores = []) {
+  const fence = new Set(privateStores);
+  const seen = new Map();
+  for (const entry of entries) {
+    if (!entry.name.endsWith(IDMAP_SUFFIX) || entry.name.split('/').includes('__MACOSX')) continue;
+    const base = path.posix.basename(entry.name);
+    if (base.startsWith('._')) continue;
+    const store = base.slice(0, -IDMAP_SUFFIX.length);
+    if (fence.has(store)) continue;
+    if (seen.has(store)) throw new Error(`store ${store} has two idmap members (${seen.get(store).name}, ${entry.name})`);
+    seen.set(store, { ...entry, store });
+  }
+  return [...seen.values()];
+}
+
+/** One member's bytes from a buffer that starts at its local header; null when the buffer is too short. */
+export function decodeEntry(entry, local) {
+  if (local.length < 30 || local.readUInt32LE(0) !== SIG.local) throw new Error(`no local header for ${entry.name}`);
+  const start = 30 + local.readUInt16LE(26) + local.readUInt16LE(28);
+  if (local.length < start + entry.compressedSize) return { need: start + entry.compressedSize };
+  const raw = local.subarray(start, start + entry.compressedSize);
+  let data;
+  if (entry.method === 0) data = raw;
+  else if (entry.method === 8) data = zlib.inflateRawSync(raw);
+  else throw new Error(`${entry.name} uses compression method ${entry.method}; only stored (0) and deflate (8) are read`);
+  if (typeof zlib.crc32 !== 'function') throw new Error('zlib.crc32 is unavailable (Node >= 20.15 / 22.2 required) — cannot verify members');
+  if (data.length !== entry.size) throw new Error(`${entry.name} inflated to ${data.length} bytes; the directory says ${entry.size}`);
+  const crc = zlib.crc32(data) >>> 0;
+  if (crc !== entry.crc >>> 0) throw new Error(`${entry.name} failed its CRC-32 check (expected ${entry.crc.toString(16)}, got ${crc.toString(16)})`);
+  return { data };
+}
+
+export function countIdmap(buffer, name) {
+  const { idToLabel } = JSON.parse(buffer.toString('utf8'));
+  if (!idToLabel || typeof idToLabel !== 'object' || Array.isArray(idToLabel)) throw new Error(`${name} has no idToLabel object`);
+  return Object.keys(idToLabel).length;
+}
+
+export function readPrivateStores(file = path.join(ROOT, 'kb', 'PRIVATE-STORES.json')) {
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!Array.isArray(parsed?.privateStores)) throw new Error(`${file} lacks a privateStores array`);
+  return [...parsed.privateStores].sort();
+}
+
+/** The release asset row (id, size, url) from the GitHub API. */
+async function resolveAsset({ repo, tag, fetch, token }) {
+  const headers = { Accept: 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+  const response = await fetch(`https://api.github.com/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`, { headers });
+  if (!response.ok) throw new Error(`release ${tag}: GitHub API answered HTTP ${response.status}`);
+  const assets = ((await response.json())?.assets || []).filter((asset) => asset?.name === ARCHIVE_ASSET);
+  if (assets.length !== 1) throw new Error(`release ${tag} has ${assets.length} ${ARCHIVE_ASSET} assets; expected exactly one`);
+  return { id: assets[0].id, size: assets[0].size, url: assets[0].browser_download_url };
+}
+
+/** Range reads against the asset; the redirect is resolved once and re-resolved if the signed URL lapses. */
+function rangeReader({ url, size, fetch }) {
+  let target = url;
+  let fetched = 0;
+  const read = async (start, end, retried = false) => {
+    const response = await fetch(target, { headers: { Range: `bytes=${start}-${end}` }, redirect: 'follow' });
+    if (response.status !== 206) {
+      if (!retried && target !== url) { target = url; return read(start, end, true); }
+      throw new Error(`range ${start}-${end} of ${url}: expected HTTP 206, got ${response.status}`);
+    }
+    const total = Number(/\/(\d+)$/.exec(response.headers.get('content-range') || '')?.[1]);
+    if (total !== size) throw new Error(`asset is ${total} bytes; the release says ${size}`);
+    if (response.url) target = response.url;
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length !== end - start + 1) throw new Error(`short range read ${start}-${end}: ${buffer.length} bytes`);
+    fetched += buffer.length;
+    return buffer;
+  };
+  return { read, fetched: () => fetched };
+}
+
+async function pool(items, limit, work) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) { const i = next++; out[i] = await work(items[i]); }
+  }));
+  return out;
+}
+
+export async function rangeCensus({ repo, tag, bytes = null, privateStoresFile, fetch = globalThis.fetch,
+  cacheDir = os.tmpdir(), token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null, asset = null,
+  concurrency = CONCURRENCY } = {}) {
+  if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('repo must be owner/name');
+  if (!/^[A-Za-z0-9._-]+$/.test(String(tag || ''))) throw new Error(`invalid release tag: ${tag}`);
+  const privateStores = readPrivateStores(privateStoresFile);
+  const resolved = asset || await resolveAsset({ repo, tag, fetch, token });
+  if (!Number.isSafeInteger(resolved.size) || resolved.size < 22) throw new Error(`release ${tag} asset has no usable size`);
+  if (bytes !== null && bytes !== resolved.size) throw new Error(`release ${tag} asset is ${resolved.size} bytes; expected ${bytes}`);
+
+  const key = crypto.createHash('sha256').update(JSON.stringify({ repo, tag, assetId: resolved.id, size: resolved.size, privateStores }))
+    .digest('hex').slice(0, 32);
+  const cacheFile = path.join(cacheDir, 'ruvnet-brain-generation-census', `${key}.json`);
+  try {
+    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    if (cached?.tag === tag && Number.isSafeInteger(cached.chunks)) return { ...cached, cached: true };
+  } catch { /* no usable cache entry: measure */ }
+
+  const started = Date.now();
+  const { read, fetched } = rangeReader({ url: resolved.url || `https://github.com/${repo}/releases/download/${tag}/${ARCHIVE_ASSET}`,
+    size: resolved.size, fetch });
+  const tailStart = Math.max(0, resolved.size - TAIL_BYTES);
+  const eocd = parseEocd(await read(tailStart, resolved.size - 1));
+  if (eocd.cdOffset + eocd.cdSize > resolved.size) throw new Error('central directory lies outside the archive');
+  const entries = parseCentralDirectory(await read(eocd.cdOffset, eocd.cdOffset + eocd.cdSize - 1), eocd.total);
+  const selected = selectIdmapEntries(entries, privateStores);
+  if (!selected.length) throw new Error(`release ${tag} contains no public *${IDMAP_SUFFIX} members`);
+  const counts = await pool(selected, concurrency, async (entry) => {
+    const guess = 30 + Buffer.byteLength(entry.name) + entry.extraLength + entry.compressedSize + 256;
+    let local = await read(entry.offset, Math.min(resolved.size, entry.offset + guess) - 1);
+    let decoded = decodeEntry(entry, local);
+    if (decoded.need) {
+      local = await read(entry.offset, entry.offset + decoded.need - 1);
+      decoded = decodeEntry(entry, local);
+      if (decoded.need) throw new Error(`${entry.name}: local header disagrees with the central directory`);
+    }
+    return countIdmap(decoded.data, entry.name);
+  });
+  const result = { tag, publicStores: selected.length, chunks: counts.reduce((a, b) => a + b, 0), builtStores: selected.length,
+    assetId: resolved.id ?? null, archiveBytes: resolved.size, fetchedBytes: fetched(), entries: entries.length,
+    seconds: Math.round((Date.now() - started) / 100) / 10 };
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const temp = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(result, null, 2)}\n`);
+    fs.renameSync(temp, cacheFile);
+  } catch { /* a cache is an optimisation; the measured result stands */ }
+  return { ...result, cached: false };
+}
+
+const arg = (argv, name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+
+if (isDirectInvocation(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  rangeCensus({ repo: arg(argv, '--repo') || process.env.GITHUB_REPOSITORY, tag: arg(argv, '--tag') })
+    .then((result) => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`))
+    .catch((error) => { console.error(`[generation-census] ${error.message}`); process.exitCode = 1; });
+}

package/scripts/issue-autofix-agents.mjs

@@ -0,0 +1,172 @@
+// scripts/issue-autofix-agents.mjs — how the daily autofix job (ADR-107) spawns `claude -p`.
+//
+// Four LLM stages (plan / build / verify / note) with no git, gh or network access: the orchestrator does every
+// push and API call itself. This module only decides WHAT is spawned (exact argv, tool allowlist, model alias,
+// stripped environment, wall clock) and PROVES what answered (the model named in the result, not the one we asked
+// for). It never asks the CLI to bypass permissions: least-privilege --allowedTools instead.
+//
+// Verified live against claude 2.1.312 (2026-10-29): --max-turns (undocumented in --help but accepted),
+// --json-schema with --output-format json returns the object in `structured_output` and the models that served the
+// call as the keys of `modelUsage`.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { AutofixAbort } from './issue-autofix-policy.mjs';
+
+// NO stage can run a command: Bash is absent from every tool list, and --restricted removes every code-running tool
+// that --tools does not name. Code a model wrote runs only in the orchestrator, under the macOS sandbox
+// (issue-autofix-sandbox.mjs), after the static security scan. The note and red-team stages get no tools at all and
+// run in an empty temporary directory: they see only what the prompt hands them.
+export const STAGE_CONFIG = Object.freeze({
+  plan:    { model: 'opus',   maxTurns: 40, timeoutMs: 20 * 60_000, tools: ['Read', 'Glob', 'Grep'], schema: 'config/issue-autofix/plan.schema.json', family: /opus/ },
+  build:   { model: 'sonnet', maxTurns: 80, timeoutMs: 45 * 60_000, tools: ['Read', 'Edit', 'Write', 'Glob', 'Grep'], schema: null, family: /sonnet|opus/ },
+  verify:  { model: 'opus',   maxTurns: 60, timeoutMs: 30 * 60_000, tools: ['Read', 'Glob', 'Grep'], schema: 'config/issue-autofix/verify.schema.json', family: /opus/ },
+  redteam: { model: 'opus',   maxTurns: 4,  timeoutMs: 15 * 60_000, tools: [], schema: 'config/issue-autofix/redteam.schema.json', family: /opus/ },
+  note:    { model: 'opus',   maxTurns: 4,  timeoutMs: 5 * 60_000,  tools: [], schema: 'config/issue-autofix/note.schema.json', family: /opus/ },
+});
+export const GRACE_MS = 20_000;
+const MAX_STDOUT = 32 * 1024 * 1024;
+const NO_MCP = 'config/issue-autofix/no-mcp.json';
+
+// BILLING SAFETY (issue-fix.mjs): an ambient API key either fails the run (stale key) or bills it. The git/gh
+// credentials go too, so an LLM stage that somehow got a shell still cannot push or comment.
+export const STRIPPED_ENV = [/^ANTHROPIC_/, /^CLAUDE_API_KEY$/, /^CLAUDE_CODE_USE_/, /^GH_TOKEN$/, /^GITHUB_TOKEN$/, /^GH_ENTERPRISE_TOKEN$/, /^SSH_AUTH_SOCK$/];
+
+// SUBSCRIPTION LOGIN UNDER LAUNCHD (measured 2026-10-30). Under launchd the login keychain is readable, and the
+// "Claude Code-credentials" item there was an EXPIRED OAuth session that could not refresh: `claude auth status`
+// said loggedIn false. Claude Code's file login (~/.claude/.credentials.json), which the owner's own sessions keep
+// fresh, is the one that works; claude uses it when the keychain cannot be reached. So on macOS every stage runs
+// with keychain lookups denied: measured under a test LaunchAgent, loggedIn true (max) and served by opus. It also
+// means no stage can read any other keychain item. No API key is ever used (BILLING SAFETY above).
+export const KEYCHAIN_DENY_PROFILE = '(version 1)(allow default)(deny mach-lookup (global-name "com.apple.SecurityServer") '
+  + '(global-name "com.apple.securityd.xpc") (global-name "com.apple.security.agent") (global-name "com.apple.secd"))';
+const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+/** [command, args] that start claude without keychain access on macOS (the real spawn only; an injected spawn is not wrapped). */
+export function claudeCommand(claudeBin, args, { platform = process.platform, exists = fs.existsSync } = {}) {
+  return platform === 'darwin' && exists(SANDBOX_EXEC) ? [SANDBOX_EXEC, ['-p', KEYCHAIN_DENY_PROFILE, claudeBin, ...args]] : [claudeBin, args];
+}
+
+export function sanitizedEnv(baseEnv, { ghConfigDir }) {
+  const env = {};
+  for (const [k, v] of Object.entries(baseEnv || {})) {
+    if (STRIPPED_ENV.some((re) => re.test(k)) || /^GIT_CONFIG_/.test(k)) continue;
+    env[k] = v;
+  }
+  return { ...env, GH_CONFIG_DIR: ghConfigDir, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '/usr/bin/false',
+    GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'credential.helper', GIT_CONFIG_VALUE_0: '' };
+}
+
+const stageOf = (stage) => { const c = STAGE_CONFIG[stage]; if (!c) throw new Error(`unknown stage: ${stage}`); return c; };
+
+export function buildClaudeArgs(stage, prompt, { root }) {
+  const c = stageOf(stage);
+  const schema = c.schema ? ['--json-schema', JSON.stringify(JSON.parse(fs.readFileSync(path.join(root, c.schema), 'utf8')))] : [];
+  // --restricted: no code-running tool, user/project/local settings ignored (so a hook or permission the build stage
+  //   writes into the worktree never loads), file tools confined to the cwd, writes to settings/git files refused.
+  // --safe-mode: no CLAUDE.md, skills, plugins, hooks or MCP from anywhere. Both measured live on claude 2.1.314
+  //   (2026-10-30): planted .claude/settings.json hook and CLAUDE.md inert; reads/writes outside the cwd refused.
+  // --permission-prompts none: anything that would ask is denied. Subscription OAuth still works (no API key used).
+  const tools = c.tools.length ? c.tools.join(',') : '';
+  const allow = c.tools.length ? ['--allowedTools', ...c.tools] : [];
+  return ['-p', prompt, '--model', c.model, '--max-turns', String(c.maxTurns), '--output-format', 'json', ...schema,
+    '--restricted', '--safe-mode', '--tools', tools, ...allow, '--disallowedTools', 'Bash', 'WebFetch', 'WebSearch', 'Task',
+    '--permission-prompts', 'none', '--strict-mcp-config', '--mcp-config', path.join(root, NO_MCP),
+    '--no-session-persistence', '--max-budget-usd', '5'];
+}
+
+export { buildPrompt } from './issue-autofix-prompts.mjs';
+import { buildPrompt } from './issue-autofix-prompts.mjs';
+
+// ── minimal JSON-schema check (type/enum/const/required/additionalProperties/items/min/max). The claude CLI
+//    validates too; this keeps a hallucinated shape from ever reaching the policy code. ──
+function check(schema, v, at, errs) {
+  if ('const' in schema && v !== schema.const) errs.push(`${at}: must be ${JSON.stringify(schema.const)}`);
+  if (schema.enum && !schema.enum.includes(v)) errs.push(`${at}: not one of ${schema.enum.join('|')}`);
+  const t = schema.type;
+  const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : Number.isInteger(v) ? 'integer' : typeof v;
+  if (t && !(t === actual || (t === 'number' && actual === 'integer'))) { errs.push(`${at}: expected ${t}, got ${actual}`); return; }
+  if (t === 'string') {
+    if (schema.maxLength != null && v.length > schema.maxLength) errs.push(`${at}: longer than ${schema.maxLength}`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(v)) errs.push(`${at}: does not match ${schema.pattern}`);
+  }
+  if (t === 'integer' && schema.minimum != null && v < schema.minimum) errs.push(`${at}: below ${schema.minimum}`);
+  if (t === 'array') {
+    if (schema.minItems != null && v.length < schema.minItems) errs.push(`${at}: fewer than ${schema.minItems} items`);
+    if (schema.maxItems != null && v.length > schema.maxItems) errs.push(`${at}: more than ${schema.maxItems} items`);
+    if (schema.items) v.forEach((x, i) => check(schema.items, x, `${at}[${i}]`, errs));
+  }
+  if (t === 'object') {
+    for (const k of schema.required || []) if (!(k in v)) errs.push(`${at}.${k}: missing`);
+    for (const [k, x] of Object.entries(v)) {
+      if (schema.properties?.[k]) check(schema.properties[k], x, `${at}.${k}`, errs);
+      else if (schema.additionalProperties === false) errs.push(`${at}.${k}: not allowed`);
+    }
+  }
+}
+
+// The model that served the call: the key of `modelUsage` that cost the most (helper calls to a smaller model do
+// not count), else the `model` field.
+function resolveModel(out) {
+  const usage = out?.modelUsage && typeof out.modelUsage === 'object' ? Object.entries(out.modelUsage) : [];
+  if (usage.length) return usage.sort((a, b) => (Number(b[1]?.costUSD) || 0) - (Number(a[1]?.costUSD) || 0))[0][0];
+  return typeof out?.model === 'string' && out.model ? out.model : null;
+}
+
+export function assertModelFamily(stage, resolvedModel) {
+  const c = stageOf(stage);
+  if (!resolvedModel || !c.family.test(resolvedModel)) {
+    throw new AutofixAbort(stage, 'model-downgrade', `asked for ${c.model}; ${resolvedModel ? `served by ${resolvedModel}` : 'the result names no model'}`);
+  }
+}
+
+export async function runAgent({ stage, cwd, input, claudeBin, logPath, root, ghConfigDir, timeoutMs, graceMs, spawnImpl = spawn }) {
+  const c = stageOf(stage);
+  const limit = timeoutMs ?? STAGE_CONFIG[stage].timeoutMs;
+  const grace = graceMs ?? GRACE_MS;
+  const t0 = Date.now();
+  const ownDir = ghConfigDir ? null : fs.mkdtempSync(path.join(os.tmpdir(), 'autofix-gh-'));
+  const finish = (r) => ({ ok: false, stage, exitCode: null, signal: null, timedOut: false, resolvedModel: null, result: null, error: null, logPath, ...r, durationMs: Date.now() - t0 });
+  try {
+    // Behind sandbox-exec a missing binary would only show as an exit code: say what is wrong plainly.
+    if (path.isAbsolute(claudeBin) && !fs.existsSync(claudeBin)) return finish({ error: `spawn failed: ENOENT ${claudeBin}` });
+    const args = buildClaudeArgs(stage, buildPrompt(stage, input), { root });
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const logFd = fs.openSync(logPath, 'a');
+    fs.writeSync(logFd, `===== autofix ${stage} — started ${new Date().toISOString()} (model ${c.model}, max-turns ${c.maxTurns}, timeout ${limit}ms) =====\n`);
+    const env = sanitizedEnv(process.env, { ghConfigDir: ghConfigDir || ownDir });
+    const res = await new Promise((resolve) => {
+      let stdout = ''; let timedOut = false; let killTimer; let graceTimer; let child;
+      const [cmd, argv] = spawnImpl === spawn ? claudeCommand(claudeBin, args) : [claudeBin, args];
+      try { child = spawnImpl(cmd, argv, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }); } catch (e) { resolve({ spawnError: e }); return; }
+      child.on('error', (e) => { clearTimeout(killTimer); clearTimeout(graceTimer); resolve({ spawnError: e }); });
+      child.stdout.on('data', (d) => { if (stdout.length < MAX_STDOUT) stdout += d; fs.writeSync(logFd, d); });
+      child.stderr.on('data', (d) => fs.writeSync(logFd, d));
+      killTimer = setTimeout(() => {
+        timedOut = true;
+        fs.writeSync(logFd, `\n===== WALL-CLOCK TIMEOUT (${limit}ms) — SIGTERM =====\n`);
+        child.kill('SIGTERM');
+        graceTimer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* already dead */ } }, grace);
+      }, limit);
+      child.on('close', (code, signal) => { clearTimeout(killTimer); clearTimeout(graceTimer); resolve({ code, signal, timedOut, stdout }); });
+    });
+    try { fs.writeSync(logFd, `\n===== autofix ${stage} — ended ${new Date().toISOString()} =====\n`); fs.closeSync(logFd); } catch { /* log only */ }
+    if (res.spawnError) return finish({ error: `spawn failed: ${res.spawnError.message}` });
+    const base = { exitCode: res.code, signal: res.signal, timedOut: res.timedOut };
+    if (res.timedOut) return finish({ ...base, error: `${stage} timed out after ${limit}ms` });
+    let out;
+    try { out = JSON.parse(res.stdout); } catch { out = null; }
+    const resolvedModel = resolveModel(out);
+    if (res.code !== 0) return finish({ ...base, resolvedModel, error: `claude exited with exit ${res.code}${res.signal ? ` (${res.signal})` : ''}` });
+    if (!out || typeof out !== 'object') return finish({ ...base, error: 'claude output was not JSON' });
+    if (out.is_error || (out.subtype && out.subtype !== 'success')) return finish({ ...base, resolvedModel, error: `claude reported ${out.subtype || 'error'}` });
+    assertModelFamily(stage, resolvedModel); // fail closed: never accept work from a model we did not ask for
+    if (!c.schema) return finish({ ...base, ok: true, resolvedModel });
+    let result = out.structured_output;
+    if (result === undefined && typeof out.result === 'string') { try { result = JSON.parse(out.result); } catch { /* handled below */ } }
+    if (!result || typeof result !== 'object') return finish({ ...base, resolvedModel, error: 'no structured output in the result' });
+    const errs = []; check(JSON.parse(fs.readFileSync(path.join(root, c.schema), 'utf8')), result, '$', errs);
+    if (errs.length) return finish({ ...base, resolvedModel, error: `structured output failed the schema: ${errs.slice(0, 5).join('; ')}` });
+    return finish({ ...base, ok: true, resolvedModel, result });
+  } finally { if (ownDir) fs.rmSync(ownDir, { recursive: true, force: true }); }
+}