ruvnet-brain 4.7.22 → 4.7.24

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

package/scripts/issue-autofix-comment.mjs

@@ -0,0 +1,224 @@
+// Issue autofix REPORTER COMMENTS (ADR-107 §6). What a person who filed an issue reads from the automation.
+//
+// Four promises, each enforced in code rather than hoped for:
+//   1. MARKER FIRST. Every body begins with BOT_MARKER. issue-watch's judgeIssue ignores an owner comment only when it
+//      starts with the marker; a body without it would count as the maintainer's own reply and silence the SLA page.
+//   2. HONEST. `fixed` is the only kind that says "Fixed in"; `shipping` says it is still being verified; `findings`
+//      claims no fix. A hidden marker at the END makes every outcome idempotent even if the state file is wiped.
+//   3. PERSONAL. The thanks sentence must name something concrete from THEIR issue and must not echo a note we already
+//      sent that person; otherwise it is dropped (the caller pages the owner to write one) rather than posted generic.
+//   4. SAFE. The note fields are model-written. They are scrubbed of closing keywords, other @mentions, robot markers and
+//      HTML comments before they can reach a public thread.
+import { BOT_MARKER, OWNER_LOGIN } from './issue-watch.mjs';
+import { AutofixAbort, findClosingKeywords, CLOSING_KEYWORD_SOURCE } from './issue-autofix-policy.mjs';
+
+export { BOT_MARKER, OWNER_LOGIN };
+
+const OUTCOMES = new Set(['fixed', 'shipping', 'findings', 'not-fixed', 'reply']);
+const MARKER_RE = /<!--\s*ruvnet-autofix v1\s+([^>]*?)\s*-->/g;
+// Our own comment (and the autofix:needs-owner label that follows it) bumps issue.updatedAt a moment after the marker's
+// `at`. Only an update later than this grace counts as the reporter coming back.
+export const FINDINGS_GRACE_MS = 10 * 60_000;
+export const SIMILARITY_LIMIT = 0.5;
+
+const fail = (detail) => new AutofixAbort('S13', 'comment-failed', detail);
+
+// ---------------------------------------------------------------------------------------------
+// Hidden marker
+// ---------------------------------------------------------------------------------------------
+export function hiddenMarker({ issueNumber, outcome, version, sha, at } = {}) {
+  if (!Number.isInteger(issueNumber) || issueNumber < 1) throw fail('hiddenMarker: bad issue number');
+  if (!OUTCOMES.has(outcome)) throw fail(`hiddenMarker: bad outcome ${outcome}`);
+  const parts = [`issue=${issueNumber}`, `outcome=${outcome}`];
+  if (version != null) { if (!/^\d+\.\d+\.\d+$/.test(version)) throw fail('hiddenMarker: bad version'); parts.push(`version=${version}`); }
+  if (sha != null) { if (!/^[0-9a-f]{7,40}$/.test(sha)) throw fail('hiddenMarker: bad sha'); parts.push(`sha=${sha}`); }
+  if (at != null) { if (!/^[\w:.+-]+$/.test(at)) throw fail('hiddenMarker: bad timestamp'); parts.push(`at=${at}`); }
+  return `<!-- ruvnet-autofix v1 ${parts.join(' ')} -->`;
+}
+
+const isBotComment = (c) => String(c?.author?.login || '').toLowerCase() === OWNER_LOGIN
+  && String(c?.body || '').trimStart().startsWith(BOT_MARKER);
+
+function markerEntries(comments) {
+  const out = [];
+  for (const c of Array.isArray(comments) ? comments : []) {
+    if (!isBotComment(c)) continue; // a stranger quoting a marker proves nothing
+    for (const m of String(c.body).matchAll(MARKER_RE)) {
+      const kv = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
+      const issue = Number(kv.issue);
+      if (!Number.isInteger(issue) || !kv.outcome) continue;
+      out.push({ marker: { issue, outcome: kv.outcome, version: kv.version ?? null, sha: kv.sha ?? null, at: kv.at ?? null }, createdAt: c.createdAt });
+    }
+  }
+  return out;
+}
+
+export const parseHiddenMarkers = (comments) => markerEntries(comments).map((e) => e.marker);
+
+export function alreadyPosted(comments, { outcome, version, issueUpdatedAt } = {}) {
+  const entries = markerEntries(comments);
+  if (outcome === 'reply') return entries.some(({ marker: m }) => m.outcome === 'reply'); // once per issue, ever
+  if (outcome === 'findings' || outcome === 'not-fixed') {
+    const times = entries.filter((e) => e.marker.outcome === outcome)
+      .map((e) => Math.max(Date.parse(e.marker.at) || 0, Date.parse(e.createdAt) || 0));
+    if (times.length === 0) return false;
+    const updated = Date.parse(issueUpdatedAt);
+    if (!Number.isFinite(updated)) return true; // cannot show the reporter came back: do not repeat ourselves
+    return !(updated > Math.max(...times) + FINDINGS_GRACE_MS);
+  }
+  return entries.some(({ marker: m }) => m.version === (version ?? null)
+    && (m.outcome === outcome || (outcome === 'shipping' && m.outcome === 'fixed'))); // "shipping" after "fixed" would be a regression
+}
+
+// ---------------------------------------------------------------------------------------------
+// Thanks: specific and never repeated
+// ---------------------------------------------------------------------------------------------
+const trigrams = (s) => {
+  const t = String(s ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+  const set = new Set();
+  for (let i = 0; i + 3 <= t.length; i++) set.add(t.slice(i, i + 3));
+  return set;
+};
+
+export function trigramSimilarity(a, b) {
+  const x = trigrams(a); const y = trigrams(b);
+  if (x.size === 0 && y.size === 0) return 0;
+  let both = 0;
+  for (const g of x) if (y.has(g)) both++;
+  return both / (x.size + y.size - both);
+}
+
+const STOP = new Set(['the', 'a', 'an', 'this', 'that', 'issue', 'bug', 'report', 'problem', 'thanks', 'thank', 'you', 'for', 'your', 'it', 'is', 'of', 'to', 'and', 'in', 'on', 'with', 'error', 'fix', 'was', 'were', 'when', 'what']);
+const codeLike = (t) => /[./\\_:()[\]{}=<>\d]/.test(t) || /[a-z][A-Z]/.test(t) || /^--?[a-z]/i.test(t)
+  || (/^[A-Z][A-Z0-9_]{3,}$/.test(t) && !STOP.has(t.toLowerCase())); // error codes such as ENOENT
+
+/** Concrete things a sentence points at: code-shaped tokens (path, function, flag, version) or a quoted phrase that is not
+ *  just filler. Each must appear VERBATIM in the reporter's own text. */
+function specificMentions(thanks, issueText) {
+  const found = [];
+  for (const raw of String(thanks).split(/\s+/)) {
+    const tok = raw.replace(/^[("'`*_]+/, '').replace(/[)"'`*_.,;:!?]+$/, '');
+    if (tok.replace(/[^A-Za-z0-9]/g, '').length >= 4 && codeLike(tok) && issueText.includes(tok)) found.push(tok);
+  }
+  for (const m of String(thanks).matchAll(/[`"“]([^`"”]{4,120})[`"”]/g)) {
+    const span = m[1].trim();
+    const words = span.toLowerCase().split(/\W+/).filter(Boolean);
+    if (span.length >= 4 && words.some((w) => !STOP.has(w)) && issueText.includes(span)) found.push(span);
+  }
+  return found;
+}
+
+export function checkThanks({ thanks, issueText, priorNotes = [] } = {}) {
+  const text = String(thanks ?? '').trim();
+  if (!text) return { ok: false, reasons: ['empty'] };
+  const reasons = [];
+  if (specificMentions(text, String(issueText ?? '')).length === 0) reasons.push('not-specific');
+  if ((priorNotes || []).some((p) => trigramSimilarity(text, p) >= SIMILARITY_LIMIT)) reasons.push('too-similar');
+  return { ok: reasons.length === 0, reasons };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------------------------
+const NAMES = { windows: 'Windows', linux: 'Linux', macos: 'macOS', codex: 'Codex', grok: 'Grok' };
+const ran = new Set(['macos', 'linux']); // the platforms our evidence actually ran on
+
+/** Scrub model-written text for a public thread (see header, promise 4). */
+function scrub(text, kind, max) {
+  let t = String(text ?? '')
+    .replace(/<!--[\s\S]*?-->/g, ' ').replace(/<!--|-->/g, ' ')
+    .split(BOT_MARKER).join('')
+    .replace(/[\u0000-\u001f\u007f]+/g, ' ')
+    .replace(/(^|[^\w.])@(?=[A-Za-z0-9_-])/g, '$1')
+    .replace(new RegExp(CLOSING_KEYWORD_SOURCE, 'gi'), (m) => `see ${m.replace(/^\w+\s*:?\s*/, '')}`)
+    .replace(/\s+/g, ' ').trim();
+  if (kind !== 'fixed') t = t.replace(/\bfixed in\b/gi, 'changed in');
+  return t.length > max ? `${t.slice(0, max - 1).trimEnd()}…` : t;
+}
+
+const joinNames = (xs) => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`);
+
+/**
+ * thanks: the person's note (only on the first of their issues tonight) or null; thanksOn: the issue that carries it.
+ * entry: the note's perIssue entry for THIS issue; facts: {verified, notVerified} measured by machines, never by a model.
+ */
+export function renderComment({ kind, issueNumber, login, thanks = null, thanksOn = null, entry = {}, facts = null, version, sha, commitUrl, testPath, platformCaveat = [], at } = {}) {
+  if (!OUTCOMES.has(kind)) throw fail(`renderComment: unknown kind ${kind}`);
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(String(login || ''))) throw fail('renderComment: unsafe reporter login');
+  const t = thanks ? scrub(thanks, kind, 700) : '';
+  const hi = t ? `Hi @${login} — ${t}` : Number.isInteger(thanksOn) && thanksOn !== issueNumber ? `Hi @${login} — my note to you is on issue ${thanksOn}.` : `Hi @${login}.`;
+  const wrong = scrub(entry.whatWasWrong, kind, 600);
+  if (!wrong) throw fail('renderComment: entry.whatWasWrong is required');
+  const list = (xs) => (xs || []).map((x) => scrub(x, kind, 200)).filter(Boolean).join('; ');
+  const factsLine = facts && (facts.verified?.length || facts.notVerified?.length)
+    ? [`**Checked:** ${list(facts.verified) || 'nothing yet'}.`, facts.notVerified?.length ? ` **Not checked:** ${list(facts.notVerified)}.` : ''].join('') : null;
+  const needs = scrub(entry.whatItNeeds, kind, 600) || 'a maintainer’s decision.';
+  const foot = (o) => hiddenMarker({ issueNumber, outcome: o, at: at ?? new Date().toISOString() });
+
+  if (kind === 'findings') {
+    return [`${BOT_MARKER} findings — RuvNet Brain`, '', hi, '',
+      `I dug into this rather than guess at a patch. Here's what I found: ${wrong}`,
+      `What it needs: ${needs} I've flagged it for the maintainer, so the next reply here will be from a person or a real fix.`, '', foot('findings')].join('\n');
+  }
+  if (kind === 'not-fixed') {
+    return [`${BOT_MARKER} status — RuvNet Brain`, '', hi, '',
+      `I worked on a fix for this, but it did not pass verification, so nothing was shipped. What I found: ${wrong}`,
+      ...(factsLine ? [factsLine] : []),
+      `What it needs: ${needs} A maintainer will take it from here.`, '', foot('not-fixed')].join('\n');
+  }
+  if (kind === 'reply') {
+    return [`${BOT_MARKER} note — RuvNet Brain`, '', hi, '',
+      `${wrong}`, `This needs the maintainer's call, so nothing has been changed: ${needs} I've flagged it, so the next reply here will be from a person.`, '', foot('reply')].join('\n');
+  }
+
+  const changed = scrub(entry.whatChanged, kind, 400);
+  if (!changed) throw fail('renderComment: entry.whatChanged is required');
+  if (!/^\d+\.\d+\.\d+$/.test(String(version))) throw fail('renderComment: version is required');
+  if (!/^[0-9a-f]{7,40}$/.test(String(sha))) throw fail('renderComment: sha is required');
+  const short = sha.slice(0, 7);
+  const ref = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/commit\/[0-9a-f]{7,40}$/.test(String(commitUrl)) ? `[${short}](${commitUrl})` : `\`${short}\``;
+  const test = String(testPath || '').replace(/[`\s]/g, '');
+  const where = kind === 'fixed'
+    ? `Fixed in **v${version}**, published to npm and GitHub and install-verified on Linux, macOS and Windows. \`npx ruvnet-brain@latest --update\` picks it up (plugin installs update on their own).`
+    : `Built and merged; shipping in **v${version}**, which is still finishing verification. I'll confirm here once it is verified on all three platforms.`;
+  const missing = [...new Set((platformCaveat || []).map((p) => String(p).toLowerCase()))].filter((p) => !ran.has(p) && NAMES[p]);
+  const lines = [`${BOT_MARKER} fix report — RuvNet Brain`, '', hi, '',
+    `**What was wrong:** ${wrong}`,
+    `**What changed:** ${ref} — ${changed}${test ? ` It comes with a new test (\`${test}\`) that fails on the old code and passes now.` : ''}`,
+    `**Where it is:** ${where}`];
+  if (factsLine) lines.push(factsLine);
+  if (missing.length) lines.push(`Our tests ran on macOS and Linux; if you can confirm on ${joinNames(missing.map((p) => NAMES[p]))}, that closes the loop.`);
+  lines.push('If it still looks wrong after updating, reply here or open a new issue — a maintainer sees both.', '',
+    hiddenMarker({ issueNumber, outcome: kind, version, sha }));
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------------------------
+// Posting (the only function here that writes to GitHub)
+// ---------------------------------------------------------------------------------------------
+export function postOutcome(ctx, { issueNumber, body, close = false, addLabels = [] } = {}) {
+  if (!Number.isInteger(issueNumber) || issueNumber < 1) throw fail('postOutcome: bad issue number');
+  if (typeof body !== 'string' || !body.startsWith(BOT_MARKER)) throw fail('body must begin with the bot marker');
+  if (body.startsWith(`${BOT_MARKER} acknowledgment`)) throw fail('body must not impersonate the acknowledgment');
+  if (findClosingKeywords(body).length) throw fail('body contains a closing keyword');
+  const own = markerEntries([{ author: { login: OWNER_LOGIN }, body }]).map((e) => e.marker);
+  if (own.length === 0) throw fail('body lacks the hidden dedupe marker');
+  if (own.some((m) => m.issue !== issueNumber)) throw fail('hidden marker names a different issue');
+  if (close && own[own.length - 1].outcome !== 'fixed') throw fail('only a fixed comment may close an issue');
+  if (!(addLabels || []).every((l) => /^autofix:[a-z-]+$/.test(l))) throw fail('label outside the autofix: namespace');
+  if (!/^[\w.-]+\/[\w.-]+$/.test(String(ctx?.repo))) throw fail('bad repo');
+
+  const gh = ctx.ghBin || process.env.GH_BIN || 'gh';
+  const base = (...a) => [...a, String(issueNumber), '--repo', ctx.repo];
+  const result = { commented: false, closed: false, labeled: false, error: null };
+  const step = (args) => {
+    try { const r = ctx.exec(gh, args); return r.status === 0 ? null : String(r.stderr || r.stdout || `exit ${r.status}`).trim().slice(0, 300); }
+    catch (e) { if (e?.name === 'AutofixAbort') throw e; return String(e?.message || e).slice(0, 300); }
+  };
+  let err = step([...base('issue', 'comment'), '--body', body]);
+  if (err) return { ...result, error: `comment: ${err}` };
+  result.commented = true;
+  if (addLabels.length) { err = step([...base('issue', 'edit'), '--add-label', addLabels.join(',')]); if (err) result.error = `label: ${err}`; else result.labeled = true; }
+  if (close) { err = step([...base('issue', 'close'), '--reason', 'completed']); if (err) result.error = [result.error, `close: ${err}`].filter(Boolean).join('; '); else result.closed = true; }
+  return result;
+}

package/scripts/issue-autofix-diff.mjs

@@ -0,0 +1,108 @@
+// scripts/issue-autofix-diff.mjs — what the build stage changed, and whether its new test is a real test.
+// The orchestrator never takes the builder's word for either: it reads the diff from git itself (S4) and measures
+// the new test against origin/main WITHOUT the fix and against the worktree WITH it (spec §4 "Test validity").
+import fs from 'node:fs';
+import path from 'node:path';
+import { AutofixAbort, judgeDiff, judgeTestValidity } from './issue-autofix-policy.mjs';
+import { parseUnifiedDiff } from './issue-autofix-release-util.mjs';
+
+const GIT_DIFF = ['diff', '--no-color', '--no-ext-diff', '--no-renames'];
+const SAFE_TEST_PATH = /^[\w./-]+$/;
+
+/** The working-tree diff against the commit the worktree was cut from (untracked files included via intent-to-add). */
+export function collectDiff(exec, wt, gitBin = 'git') {
+  const g = (...a) => exec(gitBin, ['-C', wt, ...a]);
+  const head = g('rev-parse', 'HEAD');
+  if (head.status !== 0) throw new AutofixAbort('S4', 'diff-policy', 'cannot read the worktree HEAD');
+  const add = g('add', '-A', '-N');
+  if (add.status !== 0) throw new AutofixAbort('S4', 'diff-policy', `git add -N failed: ${add.stderr.slice(-300)}`);
+  const u0 = g(...GIT_DIFF, '-U0', 'HEAD');
+  const full = g(...GIT_DIFF, 'HEAD');
+  if (u0.status !== 0 || full.status !== 0) throw new AutofixAbort('S4', 'diff-policy', 'git diff failed');
+  const files = parseUnifiedDiff(u0.stdout);
+  return { base: head.stdout.trim(), files, text: full.stdout,
+    changedLines: files.reduce((n, f) => n + f.added.length + f.removed.length, 0) };
+}
+
+/** judgeDiff, mapped to the abort code the receipt and page use. */
+export function assertDiffAllowed(diff, governed0103) {
+  if (diff.files.length === 0) throw new AutofixAbort('S4', 'diff-policy', 'the build stage changed nothing');
+  const verdict = judgeDiff({ files: diff.files, governed0103 });
+  if (!verdict.ok) {
+    const v = verdict.violations[0];
+    const code = { 'test-weakened': 'test-weakened', 'protected-path': 'protected-path', 'not-editable': 'not-editable' }[v.rule] || 'diff-policy';
+    throw new AutofixAbort('S4', code, verdict.violations.map((x) => `${x.rule} ${x.path}: ${x.detail}`).join('; ').slice(0, 800));
+  }
+  return verdict;
+}
+
+function parseVitestJson(stdout) {
+  const i = stdout.indexOf('{'); const j = stdout.lastIndexOf('}');
+  if (i < 0 || j <= i) return null;
+  try { return JSON.parse(stdout.slice(i, j + 1)); } catch { return null; }
+}
+
+/**
+ * `vitest run <files>` in `cwd`, ALWAYS through the sandbox runner (issue-autofix-sandbox.mjs): the files were written
+ * by a model from a stranger's issue. vitest is started from the worktree's own node_modules entry, never through npx,
+ * so nothing is resolved from the network. Returns the exit code, the failing tests ("<file> > <title>") and the output.
+ */
+export function runVitest(runSandboxed, cwd, files) {
+  if (typeof runSandboxed !== 'function') throw new AutofixAbort('S4', 'sandbox-unavailable', 'no sandbox runner');
+  if (!files.length || !files.every((f) => SAFE_TEST_PATH.test(f) && !f.startsWith('-') && !f.split('/').includes('..'))) {
+    throw new AutofixAbort('S4', 'test-validity', `unsafe test path in ${JSON.stringify(files)}`);
+  }
+  const r = runSandboxed(process.execPath, ['node_modules/vitest/vitest.mjs', 'run', '--reporter=json', ...files], { cwd, timeoutMs: 20 * 60_000 });
+  const out = `${r.stdout}${r.stderr}`;
+  const json = parseVitestJson(r.stdout);
+  const failedTests = [];
+  for (const tr of json?.testResults || []) {
+    const file = files.find((f) => String(tr.name).endsWith(`/${f}`) || tr.name === f) || tr.name;
+    const failed = (tr.assertionResults || []).filter((a) => a.status === 'failed');
+    for (const a of failed) failedTests.push(`${file} > ${a.fullName || a.title}`);
+    // A new test that imports what the fix adds cannot even load against the old code: the FILE failed. That is the
+    // new test failing on unfixed code, attributed to that file (judgeTestValidity still requires it to be a new test).
+    if (tr.status === 'failed' && failed.length === 0) failedTests.push(`${file} > (the test file failed to load)`);
+  }
+  return { exitCode: r.timedOut ? 124 : r.status, failedTests, output: out.slice(-6000) };
+}
+
+/**
+ * The worktree gets its OWN node_modules directory whose entries link to the shared install (measured 2026-10-30:
+ * vitest compiles vitest.config.mjs into node_modules/.vite-temp, and with node_modules itself a link into the shared
+ * install the sandbox refused that write, so no real test could start). Packages still resolve to the shared, read-only
+ * install; vitest's scratch files land inside the worktree, where the sandbox allows writes.
+ */
+const linkModules = (from, to) => {
+  const dest = path.join(to, 'node_modules');
+  if (!from || !fs.existsSync(from) || fs.existsSync(dest)) return;
+  const src = fs.realpathSync(from);
+  fs.mkdirSync(dest);
+  for (const e of fs.readdirSync(src)) {
+    if (e === '.vite' || e === '.vite-temp' || e === '.cache') continue; // tool scratch stays per worktree
+    fs.symlinkSync(path.join(src, e), path.join(dest, e));
+  }
+};
+export { linkModules };
+
+/**
+ * The new tests must FAIL on unfixed code and PASS on the fix. `scratch` is a detached worktree at the base commit
+ * onto which only the test files are copied.
+ */
+export function measureTestValidity(exec, { wt, scratch, diff, newTests, nodeModules, gitBin = 'git', runSandboxed }) {
+  const present = newTests.map((t) => t.replace(/^(\.\/)+/, '')).filter((t) => diff.files.some((f) => f.path === t));
+  if (present.length === 0) return { verdict: judgeTestValidity({ newTests: [] }), before: null, after: null, newTests: [] };
+  const head = exec(gitBin, ['-C', wt, 'rev-parse', 'HEAD']);
+  const mk = exec(gitBin, ['-C', wt, 'worktree', 'add', '--detach', scratch, head.stdout.trim()]);
+  if (mk.status !== 0) throw new AutofixAbort('S4', 'test-validity', `cannot create the scratch worktree: ${mk.stderr.slice(-300)}`);
+  // The scratch checkout is left in place (it holds only copied test files): nothing is force-removed, and a
+  // directory the job did not finish with is evidence, not litter.
+  for (const f of diff.files.filter((x) => x.status !== 'D' && /(^|\/)tests?\/|\.(test|spec)\.[cm]?[jt]sx?$/i.test(x.path))) {
+    fs.mkdirSync(path.dirname(path.join(scratch, f.path)), { recursive: true });
+    fs.copyFileSync(path.join(wt, f.path), path.join(scratch, f.path));
+  }
+  linkModules(nodeModules, scratch);
+  const before = runVitest(runSandboxed, scratch, present);
+  const after = runVitest(runSandboxed, wt, present);
+  return { verdict: judgeTestValidity({ before, after, newTests: present }), before, after, newTests: present };
+}

package/scripts/issue-autofix-exec.mjs

@@ -0,0 +1,128 @@
+// scripts/issue-autofix-exec.mjs — the ONE place the autofix job (ADR-107) touches child_process, plus the
+// primary-checkout guard. Every git/gh/npm/node call in the orchestrator, the release path and the reporter goes
+// through the exec this module builds, so two rails live here and nowhere else to be forgotten:
+//   * assertCommandAllowed (no force, no merge, no delete) runs on EVERY argv before it is spawned;
+//   * a command whose cwd (or `git -C` dir) is inside the developer's primary checkout is refused.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { AutofixAbort, assertCommandAllowed } from './issue-autofix-policy.mjs';
+
+/** realpath of the nearest existing ancestor + the not-yet-existing tail (macOS /var -> /private/var safe). */
+function realish(p) {
+  let cur = path.resolve(String(p));
+  const rest = [];
+  while (!fs.existsSync(cur)) {
+    const up = path.dirname(cur);
+    if (up === cur) break;
+    rest.unshift(path.basename(cur));
+    cur = up;
+  }
+  let base = cur;
+  try { base = fs.realpathSync(cur); } catch { /* keep the unresolved path */ }
+  return path.join(base, ...rest);
+}
+
+/** Throws AutofixAbort('S2','primary-checkout') when `p` is the primary checkout or anywhere inside it. */
+export function resolveWorkPath(p, { primary }) {
+  const real = realish(p);
+  const prim = realish(primary);
+  if (real === prim || real.startsWith(prim + path.sep)) {
+    throw new AutofixAbort('S2', 'primary-checkout', `${real} is inside the primary checkout ${prim}`);
+  }
+  return real;
+}
+
+// git global options that take a value, so the sub-command is the first token after them.
+function gitSub(args) {
+  const a = args.map(String);
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] === '-C' || a[i] === '-c') { i += 1; continue; }
+    if (a[i].startsWith('-')) continue;
+    return { sub: a[i], rest: a.slice(i + 1) };
+  }
+  return { sub: '', rest: [] };
+}
+
+/** True for a command that WRITES (to a remote, the clone, or a worktree): a --dry-run records and skips these. */
+export function isWriteCommand(cmd, args, { ghBin } = {}) {
+  const a = (args || []).map(String);
+  const bin = path.basename(String(cmd));
+  if (bin === 'git') {
+    const { sub, rest } = gitSub(a);
+    if (['push', 'commit', 'cherry-pick', 'clone', 'add'].includes(sub)) return true;
+    return sub === 'worktree' && ['add', 'remove'].includes(rest[0]);
+  }
+  if (String(cmd) === ghBin || bin === 'gh') {
+    const [g, s] = a;
+    if (g === 'issue') return ['comment', 'close', 'edit'].includes(s);
+    if (g === 'pr') return ['create', 'close'].includes(s);
+    if (g === 'workflow') return s === 'run';
+    if (g === 'variable') return s === 'set';
+    if (g === 'api') return a.some((t) => /dispatches/.test(t));
+    return false;
+  }
+  if (bin === 'npm') return a[0] === 'ci' || (a[0] === 'run' && a[1] === 'version:set');
+  return false;
+}
+
+/** True for a command that reaches GitHub with a write (push, comment, label, close, PR, workflow, dispatch, variable). */
+export function isRemoteWrite(cmd, args, { ghBin } = {}) {
+  const a = (args || []).map(String);
+  const bin = path.basename(String(cmd));
+  if (bin === 'git') return gitSub(a).sub === 'push';
+  return (String(cmd) === ghBin || bin === 'gh') && isWriteCommand(cmd, a, { ghBin });
+}
+
+/**
+ * exec(cmd, args, {cwd, env, timeoutMs, input}) -> {status, stdout, stderr, signal, timedOut}. Never throws on a
+ * non-zero exit; throws AutofixAbort for a forbidden argv or a primary-checkout cwd. dryRun skips every write;
+ * rehearse skips only writes that reach GitHub (local worktrees and commits in the job's own clone still happen).
+ */
+export function makeExec({ dryRun = false, rehearse = false, log = () => {}, primary = null, ghBin = 'gh', env = process.env } = {}) {
+  let stage = 'S0';
+  const exec = (cmd, args = [], opts = {}) => {
+    const argv = args.map(String);
+    assertCommandAllowed(cmd, argv, stage);
+    if (primary) {
+      if (opts.cwd) resolveWorkPath(opts.cwd, { primary });
+      const c = argv.indexOf('-C');
+      if (path.basename(String(cmd)) === 'git' && c !== -1 && argv[c + 1]) resolveWorkPath(argv[c + 1], { primary });
+    }
+    const line = [cmd, ...argv.map((t) => (t.length > 160 ? `${t.slice(0, 160)}…` : t))].join(' ');
+    if ((dryRun && isWriteCommand(cmd, argv, { ghBin })) || (rehearse && isRemoteWrite(cmd, argv, { ghBin }))) {
+      log(`[dry-run, not executed] ${line}`);
+      return { status: 0, stdout: '', stderr: '', signal: null, timedOut: false, skipped: true };
+    }
+    log(line);
+    const r = spawnSync(cmd, argv, { cwd: opts.cwd, env: opts.env || env, encoding: 'utf8', timeout: opts.timeoutMs,
+      input: opts.input, maxBuffer: 256 * 1024 * 1024, killSignal: 'SIGTERM' });
+    const timedOut = r.error?.code === 'ETIMEDOUT';
+    return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error && !timedOut ? String(r.error.message) : ''),
+      signal: r.signal || null, timedOut };
+  };
+  exec.setStage = (s) => { stage = s; };
+  return exec;
+}
+
+/**
+ * notify.sh exit code: 0 delivered, 1 failed, 2 paging off. The job runs from its own runner worktree, which has no
+ * .env, so the topic comes from $NTFY_TOPIC or ~/.cache/ruvnet-brain/ntfy-topic — the file job-heartbeat.sh reads.
+ * NTFY_TOPIC set but empty stays an explicit opt-out.
+ */
+export function defaultNotify(root, env = process.env) {
+  return (title, body, priority = 'default') => {
+    let topic = env.NTFY_TOPIC;
+    if (topic === undefined) {
+      try { topic = fs.readFileSync(path.join(env.HOME || '', '.cache', 'ruvnet-brain', 'ntfy-topic'), 'utf8').trim(); } catch { topic = undefined; }
+    }
+    const r = spawnSync('sh', [path.join(root, 'scripts', 'notify.sh'), title, body, priority, 'autofix'],
+      { encoding: 'utf8', timeout: 30_000, env: topic === undefined ? env : { ...env, NTFY_TOPIC: topic } });
+    return Number.isInteger(r.status) ? r.status : 1;
+  };
+}
+
+/** Stops the Mac sleeping for as long as this process lives (best effort). */
+export function keepAwake(pid = process.pid) {
+  try { spawn('caffeinate', ['-i', '-w', String(pid)], { stdio: 'ignore', detached: true }).unref(); } catch { /* best effort */ }
+}