ruvnet-brain 4.7.21 → 4.7.23

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 */ }
+}

package/scripts/issue-autofix-fix.mjs

@@ -0,0 +1,104 @@
+// scripts/issue-autofix-fix.mjs — one issue, start to verified fix commit (ADR-107 S2..S5). Each issue gets its own
+// worktree, its own plan, build, red-team and verifier, and its own sandboxed evidence; one issue's failure never
+// touches another's. Returns { status: 'ready', fixSha, ... } or throws AutofixAbort; the orchestrator decides what the
+// reporter is told. Order matters: nothing a model wrote is EXECUTED until the static scan has passed, and then only
+// inside the sandbox (issue-autofix-sandbox.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import { AutofixAbort, judgePlan, judgeVerdict, EVIDENCE_COMMAND } from './issue-autofix-policy.mjs';
+import { collectDiff, assertDiffAllowed, measureTestValidity, runVitest, linkModules } from './issue-autofix-diff.mjs';
+import { staticScan, redTeam } from './issue-autofix-gate.mjs';
+import { mustGit } from './issue-autofix-release-util.mjs';
+import { commitFix } from './issue-autofix-release.mjs';
+
+const PLATFORMS = { windows: 'Windows', linux: 'Linux', macos: 'macOS', codex: 'Codex', grok: 'Grok' };
+
+/** Any file under node_modules newer than `stamp` means a model wrote through the link: never trust that tree again. */
+function assertModulesUntouched(rt, nodeModules, stamp) {
+  if (!nodeModules) return;
+  const r = rt.exec('find', [fs.realpathSync(nodeModules), '-newer', stamp, '-not', '-path', '*/.vite/*', '-print', '-quit']);
+  if (r.status !== 0 || r.stdout.trim()) throw new AutofixAbort('S4', 'modules-tampered', `node_modules changed during the build: ${r.stdout.trim().slice(0, 200)}`);
+}
+
+const evidenceFiles = (cmd) => {
+  if (typeof cmd !== 'string' || !EVIDENCE_COMMAND.test(cmd)) return null;
+  const files = cmd.split(/\s+/).slice(3);
+  return files.length && files.every((t) => !t.startsWith('-') && !t.split('/').includes('..')) ? files : null;
+};
+
+export async function fixOne(rt, issue, { governed }) {
+  const n = issue.number;
+  const out = { number: n, status: 'dropped', plan: null, verify: null, testValidity: null, diff: null, wt: null, fixSha: null };
+  rt.current.wt = null;
+
+  // S2 — own worktree at origin/main; node_modules is a link to the clone's install made at origin/main.
+  rt.begin('S2');
+  const stamp = rt.now();
+  const wt = path.join(rt.paths.worktrees, `issue-${n}-${stamp}`);
+  rt.resolveWorkPath(wt);
+  fs.mkdirSync(rt.paths.worktrees, { recursive: true });
+  await mustGit(rt.ctx, 'S2', 'agent-failed', rt.paths.clone, ['worktree', 'add', '-b', `autofix/issue-${n}-${stamp}`, wt, rt.base || 'origin/main']);
+  out.wt = wt; rt.current.wt = wt;
+  linkModules(rt.nodeModules, wt);
+  rt.end(true);
+
+  // S3 — plan (read-only tools), judged against the allowlist and the protected set.
+  const plan = (await rt.agent('plan', 'S3', wt, { issue: rt.agentIssue(issue), repo: rt.repo })).result;
+  out.plan = plan; rt.current.plan = plan;
+  const jp = judgePlan(plan, { governed0103: governed });
+  if (!jp.proceed) throw new AutofixAbort('S3', jp.code, String(plan?.summary || ''), { publicFindings: jp.publicFindings });
+
+  // S4 — build (file tools only), then: diff policy → static scan → modules check → sandboxed test validity.
+  let repair = null; let diff; let tv;
+  for (let round = 0; round < 2; round += 1) {
+    const stampFile = path.join(rt.runDir, `build-${n}-${round}.stamp`);
+    fs.writeFileSync(stampFile, '');
+    await rt.agent('build', 'S4', wt, { issue: rt.agentIssue(issue), plan, repair });
+    const head = rt.exec('git', ['-C', wt, 'rev-parse', 'HEAD']).stdout.trim();
+    diff = collectDiff(rt.exec, wt);
+    if (head !== diff.base) throw new AutofixAbort('S4', 'diff-policy', 'HEAD moved during the build');
+    out.diff = { files: diff.files.length, changedLines: diff.changedLines, violations: [] };
+    try { assertDiffAllowed(diff, governed); } catch (e) { out.diff.violations = [e.detail]; throw e; }
+    const scan = staticScan(diff);
+    if (!scan.ok) {
+      out.diff.violations = scan.findings.map((f) => `${f.rule} ${f.path}:${f.line ?? '-'}`);
+      throw new AutofixAbort('S4', 'security-finding', scan.findings.slice(0, 8).map((f) => `${f.rule} ${f.path}:${f.line ?? '-'} ${f.excerpt}`).join('; ').slice(0, 900));
+    }
+    assertModulesUntouched(rt, rt.nodeModules, stampFile);
+    tv = measureTestValidity(rt.exec, { wt, scratch: `${wt}-scratch-${round}`, diff, newTests: plan.testPlan.newTests,
+      nodeModules: rt.nodeModules, runSandboxed: rt.runSandboxed });
+    out.testValidity = { ok: tv.verdict.ok, reason: tv.verdict.reason, round };
+    if (tv.verdict.ok) break;
+    if (round === 1 || tv.verdict.reason === 'no-new-tests') throw new AutofixAbort('S4', 'test-validity', tv.verdict.reason);
+    repair = `test-validity: ${tv.verdict.reason}\n--- unfixed code ---\n${tv.before?.output || ''}\n--- fixed code ---\n${tv.after?.output || ''}`;
+  }
+
+  // S4b — an independent Opus red-team that sees only this diff.
+  await redTeam(rt, { stage: 'S4', diffText: diff.text, files: diff.files, staticFindings: [], scope: `one fix for issue ${n}` });
+
+  // S5 — independent verifier (read-only), then the orchestrator re-runs its evidence in the sandbox.
+  const verify = (await rt.agent('verify', 'S5', wt, { issue: rt.agentIssue(issue), diffText: diff.text,
+    testValidity: { beforeOutput: tv.before.output, afterOutput: tv.after.output, newTests: tv.newTests } })).result;
+  const reruns = [];
+  for (const ev of verify.evidence || []) {
+    if (ev.command === undefined) continue;
+    const files = evidenceFiles(ev.command);
+    if (!files) { reruns.push({ command: ev.command, exitCode: -1 }); continue; }
+    const r = runVitest(rt.runSandboxed, wt, files);
+    reruns.push({ command: ev.command, exitCode: r.exitCode });
+  }
+  out.verify = { verdict: verify.verdict, evidence: (verify.evidence || []).length, reruns, summary: verify.summary };
+  const jv = judgeVerdict(verify, reruns);
+  if (!jv.ship) {
+    throw new AutofixAbort('S5', jv.code, `${verify.verdict}: ${verify.summary}`,
+      { publicFindings: verify.verdict === 'NEEDS_OWNER' && plan.rootCause?.line > 0 });
+  }
+
+  // Commit in the issue worktree (message names only the issue number: no stranger text enters git history).
+  const { fixSha } = await commitFix(rt.ctx, { wt, issueNumber: n });
+  const missing = [...new Set(plan.platformSpecific || [])].filter((p) => !['macos', 'linux'].includes(p)).map((p) => PLATFORMS[p]).filter(Boolean);
+  return { ...out, status: 'ready', fixSha, testPath: tv.newTests[0], platformCaveat: plan.platformSpecific || [],
+    facts: { verified: ['a new test that fails on the old code and passes with the fix (run in an isolated sandbox on macOS)',
+      'an independent review of the change, whose cited checks were re-run'],
+    notVerified: [`your exact setup${missing.length ? ` on ${missing.join(' and ')}` : ''}`] }, summary: verify.summary };
+}