ruvnet-brain 4.7.21 → 4.7.23

package/scripts/codex-boot-surface-proof.mjs

@@ -0,0 +1,208 @@
+// Proof that the Codex boot surface a release changed is the surface a FRESH Codex session will load (issue #391,
+// ADR-0070, ADR-0051). A receipt that names `scripts/hook-shim.mjs`, `mcp/server.mjs` or `skills/` as changed used to stay
+// restartScope:'unproven' forever, because only the two hook-declaration files could be cleared. Each path is proven by
+// the strongest evidence that can be gathered without a Codex relaunch, and any path with no prover stays unproven,
+// NAMED in the result:
+//   hooks/codex-hooks.json, hooks/hooks.json  the fresh-declarations proof (scripts/codex-fresh-host-proof.mjs)
+//   skills/                                    that proof plus a byte-identical skills/ tree
+//   scripts/hook-shim.mjs                      byte-identical AND a real run of the INSTALLED shim with an unknown hook
+//                                              id (it exits 0 doing nothing and lists its roles; every registered Codex
+//                                              role must be listed)
+//   mcp/server.mjs                             byte-identical AND a real stdio initialize + tools/list that must
+//                                              include search_ruvnet
+// The result ALWAYS reports windows that are already open as `unproven` and a host relaunch as `not-observed`. It is
+// read-only: both real processes run against an isolated temporary HOME and brain home (the MCP server leases its
+// generation while running), under a hard deadline, and the temp tree is removed. It never touches a receipt.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { shellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
+
+export const BOOT_REASON_PREFIX = 'boot-level declarations changed: ';
+export const PROVABLE_PATHS = Object.freeze(['hooks/codex-hooks.json', 'hooks/hooks.json', 'skills/',
+  'scripts/hook-shim.mjs', 'mcp/server.mjs']);
+const MAX_CAPTURE = 64 * 1024;
+
+/** The changed paths a machine-generated sessionSafetyReason names, or [] when it names none. */
+export function parseChangedPaths(reason) {
+  if (typeof reason !== 'string' || !reason.startsWith(BOOT_REASON_PREFIX)) return [];
+  return reason.slice(BOOT_REASON_PREFIX.length).split(', ').map((entry) => entry.trim()).filter(Boolean);
+}
+
+/** The hook roles a Codex hooks file registers: the id after the timeout in each `... <timeoutMs> <role> [event]` command. */
+export function registeredCodexRoles(hooksFile) {
+  const parsed = JSON.parse(fs.readFileSync(hooksFile, 'utf8'));
+  const roles = new Set();
+  for (const groups of Object.values(parsed.hooks || {})) {
+    for (const group of groups) {
+      for (const handler of group.hooks || []) {
+        const match = /"\s+\d+\s+([a-z][a-z0-9-]*)(?:\s+\S+)?\s*$/.exec(String(handler.command || ''));
+        if (match) roles.add(match[1]);
+      }
+    }
+  }
+  return [...roles];
+}
+
+// Windows cannot start node (or resolve DLLs, temp, shells) without these; copied only when present, never a secret.
+const WINDOWS_NEEDS = ['SystemRoot', 'windir', 'ComSpec', 'PATHEXT'];
+const IS_WIN = process.platform === 'win32';
+
+/** SIGKILL the probe's whole process group (it is spawned detached, so it leads one); the child alone on Windows. */
+function killTree(child) {
+  try {
+    if (!IS_WIN && Number.isInteger(child?.pid) && child.pid > 1) process.kill(-child.pid, 'SIGKILL');
+    else child?.kill('SIGKILL');
+  } catch { try { child?.kill('SIGKILL'); } catch { /* gone */ } }
+}
+
+export function isolatedEnv(tmp, extra = {}, source = process.env) {
+  const needs = {};
+  for (const name of WINDOWS_NEEDS) if (source[name]) needs[name] = source[name];
+  const env = { ...needs, PATH: source.PATH || source.Path || '', HOME: tmp, USERPROFILE: tmp, TMPDIR: tmp,
+    RUVNET_BRAIN_HOME: path.join(tmp, 'brain'), RUVNET_BRAIN_STATE_DIR: path.join(tmp, 'state'),
+    XDG_CACHE_HOME: path.join(tmp, 'xdg'), XDG_CONFIG_HOME: path.join(tmp, 'xdgc'), CODEX_HOME: path.join(tmp, 'codex'),
+    RUVNET_BRAIN_KB: path.join(tmp, 'kb'), RUVNET_NIGHTLY: '', ...extra };
+  if (IS_WIN) { env.TEMP = tmp; env.TMP = tmp; }   // USERPROFILE is already the isolated tmp; TEMP/TMP must not point at the real profile
+  return env;
+}
+
+function runBounded(args, { cwd, env, timeoutMs }) {
+  return new Promise((resolve) => {
+    let out = ''; let err = ''; let timedOut = false; let settled = false;
+    const child = spawn(process.execPath, args, { cwd, env, detached: !IS_WIN, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const finish = (result) => { if (settled) return; settled = true; clearTimeout(timer); resolve({ stdout: out, stderr: err, timedOut, ...result }); };
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    child.stdout.on('data', (b) => { if (out.length < MAX_CAPTURE) out += b; });
+    child.stderr.on('data', (b) => { if (err.length < MAX_CAPTURE) err += b; });
+    child.once('error', (error) => finish({ code: null, signal: null, spawnError: error.message }));
+    child.once('close', (code, signal) => { killTree(child); finish({ code, signal }); });
+  });
+}
+
+/** Run the INSTALLED shim with an id it does not know. Proven only by exit 0 plus a role list covering every registered role. */
+export async function runShimProbe({ installedRoot, roles, tmp, timeoutMs }) {
+  const shim = path.join(installedRoot, 'scripts', 'hook-shim.mjs');
+  const started = Date.now();
+  const run = await runBounded([shim, 'boot-surface-proof-unknown-hook'], { cwd: tmp, env: isolatedEnv(tmp), timeoutMs });
+  const elapsedMs = Date.now() - started;
+  if (run.timedOut) return { ok: false, elapsedMs, reason: `the installed hook shim did not exit within ${timeoutMs} ms and was killed` };
+  if (run.spawnError) return { ok: false, elapsedMs, reason: `the installed hook shim could not start: ${run.spawnError}` };
+  if (run.code !== 0) return { ok: false, elapsedMs, reason: `the installed hook shim exited ${run.code ?? run.signal} for an unknown hook id (expected 0)` };
+  const listed = /known:\s*([^\n]*)/.exec(run.stderr)?.[1]?.split(',').map((s) => s.trim()).filter(Boolean) || [];
+  const missing = roles.filter((role) => !listed.includes(role));
+  if (!listed.length) return { ok: false, elapsedMs, reason: 'the installed hook shim listed no hook roles' };
+  if (missing.length) return { ok: false, elapsedMs, listed, reason: `the installed hook shim does not list registered Codex role(s): ${missing.join(', ')}` };
+  return { ok: true, elapsedMs, rolesListed: listed.length, rolesRegistered: roles.length };
+}
+
+const STUB_WORKER = "require('node:fs').writeFileSync(process.env.RNB_PROOF_MARKER,String(process.pid));process.exit(0);\n";
+
+/** Real stdio MCP handshake against the INSTALLED server: initialize, tools/list. Never starts the real search worker. */
+export async function runMcpProbe({ installedRoot, tmp, timeoutMs }) {
+  const server = path.join(installedRoot, 'mcp', 'server.mjs');
+  const stub = path.join(tmp, 'stub-worker.cjs'); const marker = path.join(tmp, 'worker-started');
+  fs.writeFileSync(stub, STUB_WORKER);
+  const env = isolatedEnv(tmp, { RUVNET_BRAIN_CHILD_MCP: stub, RNB_PROOF_MARKER: marker });
+  const started = Date.now();
+  return await new Promise((resolve) => {
+    let buffer = ''; let settled = false; let timedOut = false;
+    const replies = new Map(); let stderr = '';
+    const child = spawn(process.execPath, [server], { cwd: tmp, env, detached: !IS_WIN, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    const kill = () => killTree(child);
+    const deadline = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+    const send = (message) => { try { child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`); } catch { /* exit handler reports */ } };
+    const done = (result) => { if (settled) return; settled = true; clearTimeout(deadline); resolve({ elapsedMs: Date.now() - started, ...result }); };
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk;
+      let at;
+      while ((at = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+        let message; try { message = JSON.parse(line); } catch { continue; }
+        if (message.id !== undefined) replies.set(message.id, message);
+        if (message.id === 1) { send({ method: 'notifications/initialized' }); send({ id: 2, method: 'tools/list', params: {} }); }
+        if (message.id === 2) {
+          // initialize launches the warm search worker in the background (plugin/mcp/server.mjs `void ensureChild()`); the
+          // stub worker records that it was launched, so the result reports the fact instead of assuming it.
+          setTimeout(() => { try { child.stdin.end(); } catch { /* gone */ } }, 400);
+        }
+      }
+    });
+    child.stderr.on('data', (b) => { if (stderr.length < MAX_CAPTURE) stderr += b; });
+    child.once('error', (error) => done({ ok: false, reason: `the installed MCP server could not start: ${error.message}` }));
+    child.once('close', (code, signal) => {
+      killTree(child);
+      const leaseLeft = fs.existsSync(path.join(tmp, 'brain', 'leases')) && fs.readdirSync(path.join(tmp, 'brain', 'leases')).length > 0;
+      const initialize = replies.get(1); const list = replies.get(2);
+      const workerStarted = fs.existsSync(marker);
+      const base = { exit: code ?? signal, leaseLeftBehind: leaseLeft, initializeStartsWarmWorker: workerStarted };
+      if (timedOut) return done({ ok: false, ...base, reason: `the installed MCP server did not finish an initialize + tools/list within ${timeoutMs} ms and was killed` });
+      if (!initialize?.result) return done({ ok: false, ...base, reason: 'the installed MCP server did not answer initialize' });
+      const names = Array.isArray(list?.result?.tools) ? list.result.tools.map((tool) => tool?.name) : null;
+      if (!names) return done({ ok: false, ...base, reason: 'the installed MCP server did not answer tools/list' });
+      if (!names.includes('search_ruvnet')) return done({ ok: false, ...base, tools: names, reason: 'the installed MCP server tools/list does not include search_ruvnet' });
+      if (leaseLeft) return done({ ok: false, ...base, tools: names, reason: 'the installed MCP server left its lease file behind after exit' });
+      return done({ ok: true, ...base, tools: names.length });
+    });
+    send({ id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'boot-surface-proof', version: '1' } } });
+  });
+}
+
+/**
+ * @param {object} o
+ * @param {string[]} o.changedPaths        paths the convergence receipt names as changed at boot level
+ * @param {string} o.releasedPluginRoot    the release being converged to (its plugin/ directory)
+ * @param {string} o.installedPluginRoot   the plugin tree Codex loads (its plugin cache for the active version)
+ * @param {object} [o.declarations]        a probeFreshCodexDeclarations() result; required for the declaration paths
+ */
+export async function proveCodexBootSurface({ changedPaths, releasedPluginRoot, installedPluginRoot, declarations = null, timeoutMs = 15_000 } = {}) {
+  const proven = []; const unproven = [];
+  const result = (extra = {}) => ({ ok: !extra.error && changedPaths?.length > 0 && unproven.length === 0,
+    state: !extra.error && changedPaths?.length > 0 && unproven.length === 0 ? 'boot-surface-ready' : 'boot-surface-unproven',
+    scope: 'fresh-codex-boot-surface', changed: changedPaths || [], proven, unproven,
+    reason: extra.error || (unproven.length ? unproven.map((u) => `${u.path}: ${u.reason}`).join('; ') : null),
+    existingWindows: 'unproven', hostRelaunch: 'not-observed', inferenceRequests: 0, ...extra.detail });
+  if (!Array.isArray(changedPaths) || !changedPaths.length) return result({ error: 'no changed boot-level paths are recorded, so there is nothing to prove' });
+  if (!releasedPluginRoot || !installedPluginRoot) return result({ error: 'the released or installed plugin root is unknown' });
+  let diff;
+  try { diff = new Set(shellDiff(installedPluginRoot, releasedPluginRoot)); }
+  catch (error) { return result({ error: `the installed and released plugin trees could not be compared: ${error.message}` }); }
+  const identical = (rel) => !diff.has(rel);
+  const declarationsReady = declarations?.ok === true && declarations.state === 'fresh-declarations-ready';
+  const wants = (rel) => changedPaths.includes(rel);
+  let tmp = null; let shim = null; let mcp = null;
+  try {
+    if (wants('scripts/hook-shim.mjs') || wants('mcp/server.mjs')) {
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rnb-boot-proof-'));
+      for (const dir of ['brain', 'state', 'xdg', 'xdgc', 'codex', 'kb']) fs.mkdirSync(path.join(tmp, dir), { recursive: true });
+    }
+    for (const rel of changedPaths) {
+      if (!PROVABLE_PATHS.includes(rel)) { unproven.push({ path: rel, reason: 'no prover exists for this path; it stays unproven' }); continue; }
+      if (rel === 'hooks/codex-hooks.json' || rel === 'hooks/hooks.json') {
+        if (declarationsReady) proven.push({ path: rel, evidence: 'fresh-declarations-ready' });
+        else unproven.push({ path: rel, reason: `fresh Codex hook declarations are not proven${declarations?.reason ? ` (${declarations.reason})` : ''}` });
+      } else if (rel === 'skills/') {
+        if (!identical(rel)) unproven.push({ path: rel, reason: 'the installed skills/ tree is not byte-identical to the release' });
+        else if (!declarationsReady) unproven.push({ path: rel, reason: `fresh Codex declarations are not proven${declarations?.reason ? ` (${declarations.reason})` : ''}` });
+        else proven.push({ path: rel, evidence: 'byte-identical skills/ tree plus fresh-declarations-ready' });
+      } else if (rel === 'scripts/hook-shim.mjs') {
+        if (!identical(rel)) { unproven.push({ path: rel, reason: 'the installed hook shim is not byte-identical to the release' }); continue; }
+        let roles;
+        try { roles = registeredCodexRoles(path.join(installedPluginRoot, 'hooks', 'codex-hooks.json')); }
+        catch (error) { unproven.push({ path: rel, reason: `the registered Codex roles could not be read: ${error.message}` }); continue; }
+        shim = await runShimProbe({ installedRoot: installedPluginRoot, roles, tmp, timeoutMs });
+        if (shim.ok) proven.push({ path: rel, evidence: `byte-identical; real run exited 0 and listed all ${shim.rolesRegistered} registered Codex roles` });
+        else unproven.push({ path: rel, reason: shim.reason });
+      } else if (rel === 'mcp/server.mjs') {
+        if (!identical(rel)) { unproven.push({ path: rel, reason: 'the installed MCP server is not byte-identical to the release' }); continue; }
+        mcp = await runMcpProbe({ installedRoot: installedPluginRoot, tmp, timeoutMs });
+        if (mcp.ok) proven.push({ path: rel, evidence: `byte-identical; real stdio initialize + tools/list returned ${mcp.tools} tools including search_ruvnet` });
+        else unproven.push({ path: rel, reason: mcp.reason });
+      }
+    }
+  } finally {
+    if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+  return result({ detail: { ...(shim ? { shim } : {}), ...(mcp ? { mcp } : {}) } });
+}

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 }); }
+}