ruvnet-brain 4.3.1 → 4.3.3

package/plugin/scripts/session-start-core.mjs

@@ -98,12 +98,12 @@ const surfaceIssues = (stateDir, emit, now, env, home, platform) => {
   const more = selected.length > 4 ? ` · +${selected.length - 4} more` : '';
   if (breaches.length) {
     emit('[RuvNet Brain — OPEN ISSUES need attention (surface this to the maintainer, once, near the top)]');
-    emit(`${breaches.length} open issue(s) past SLA on ${status.repo}: ${top}${more}`);
+    emit(`${breaches.length} open issue(s) past SLA on ${status.repo}: ${top}${more}; open issues are visible to the maintainer`);
     emit('These are real user-filed bugs sitting past the response SLA. Mention them plainly so they do not stack unseen; offer to fix them (gh issue list --state open for detail).');
     return;
   }
   emit("[RuvNet Brain — open issues on the maintainer's repo (mention once, calmly, near the top)]");
-  emit(`${open.length} open issue(s) on ${status.repo}, none past SLA: ${top}${more}`);
+  emit(`${open.length} open issue(s) on ${status.repo}, none past SLA: ${top}${more}; open issues are visible to the maintainer`);
   emit('Within SLA, but the maintainer should know they exist. One line is enough; offer to look.');
 };
 
@@ -133,7 +133,7 @@ const surfaceSignals = ({ env, cwd, stateDir, hookDir, emit, now }) => {
     if (debt?.state === 'resolved' && debt.conclusion !== 'success') {
       if (surfaced.debts[key] === 'red') continue;
       emit(`[RuvNet Brain — EXTERNAL SIGNAL: CI is RED for ${debt.repo}@${shortSha} — surface this to the user now, near the top, with ZERO prompting]`);
-      emit(`Workflow ${debt.workflowName || 'ci'} concluded ${debt.conclusion} on ${debt.repo}@${shortSha}. Say it plainly and offer to look (gh run list --repo ${debt.repo} --commit ${debt.ref}).`);
+      emit(`Workflow ${debt.workflowName || 'ci'} concluded ${debt.conclusion} on ${debt.repo}@${shortSha}; inspect with gh run list --repo ${debt.repo} --commit ${debt.ref}.`);
       surfaced.debts[key] = 'red';
       surfaced.redRepo[debt.repo] = key;
       changed = true;
@@ -352,14 +352,40 @@ export async function runSessionStart({
   stderr = process.stderr,
   platform = process.platform,
   restoreContinuity = restoreProgressionForSession,
+  runHeartbeat = true,
 } = {}) {
   const lines = [];
-  // SessionStart is context plumbing, not an instruction channel. The old implementation
-  // injected response scripts, setup questions and maintainer workflow into every host session;
-  // Claude correctly treated that unsolicited prose as noise. Keep the diagnostic work and
-  // durable state updates, but make user-facing output opt-in for troubleshooting only.
+  // SessionStart is context plumbing, not an instruction channel. Keep factual, actionable
+  // health/CI/issue signals and the single status line; suppress response scripts, setup
+  // questions, promotional copy, and injected "tell the user" prose. This preserves #198's
+  // maintainer alarms without recreating the unsolicited Claude Code hook noise.
+  const isSafeStatus = (line) => {
+    const s = String(line);
+    return s.startsWith('🚨')
+      || s.startsWith('[RuvNet Brain — HEALTH ALARM')
+      || s.startsWith('[RuvNet Brain — NIGHTLY FAILED')
+      || s.startsWith('[RuvNet Brain — OPEN ISSUES')
+      || /\bopen issue\(s\)/i.test(s)
+      || /^\[RuvNet Brain — external signal/i.test(s)
+      || (s.startsWith('Workflow ') && !/\b(Say it plainly|offer to look|ask only|run:|invoke)\b/i.test(s))
+      || s.startsWith('[RuvNet Brain — grounding not yet PROVEN')
+      || s.startsWith('The last check (')
+      || s.startsWith('[RuvNet Brain — update available')
+      || s.startsWith('[RuvNet Brain — brain OFF by your setting')
+      || s.startsWith('[RuvNet Brain — new in v')
+      || s.startsWith('[RuvNet Brain — first session initialized]')
+      || s.startsWith('[RuvNet Brain — one-time note')
+      || s.startsWith('At a natural CLOSING')
+      || s.includes('github.com/stuinfla/ruvnet-brain or leave feedback')
+      || s.startsWith('[RuvNet Brain v')
+      || s.startsWith('USER-LEVEL:')
+      || s.startsWith('[ASCII→SVG]')
+      || s.startsWith('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]')
+      || s.startsWith('[RuvNet Brain — PROJECT CONTINUITY RESTORED]')
+      || s.startsWith('[RuvNet Brain — MAINTAINER ONLY:');
+  };
   const emit = (line = '') => {
-    if (env.RUVNET_VERBOSE_HOOKS === '1') lines.push(String(line));
+    if (env.RUVNET_VERBOSE_HOOKS === '1' || isSafeStatus(line)) lines.push(String(line));
   };
   const home = env.HOME || env.USERPROFILE || os.homedir();
   const stateDir = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
@@ -370,6 +396,11 @@ export async function runSessionStart({
   const pluginRoot = env.CLAUDE_PLUGIN_ROOT || path.resolve(hookDir, '..');
   const manifest = json(path.join(pluginRoot, '.claude-plugin', 'plugin.json'), {});
   const running = typeof manifest?.version === 'string' ? manifest.version : '';
+  // The Stable Spine supplies the immutable generation actually executing this invocation. This
+  // avoids showing a boot-frozen plugin version after a restart-free update.
+  const activeVersion = typeof env.RUVNET_BRAIN_ACTIVE_VERSION === 'string'
+    ? env.RUVNET_BRAIN_ACTIVE_VERSION : '';
+  const effectiveVersion = activeVersion || running;
   const updated = typeof manifest?.updated === 'string' ? manifest.updated : '';
   const trace = (stage) => {
     if (env.RUVNET_SESSION_TRACE === '1') {
@@ -414,6 +445,8 @@ export async function runSessionStart({
     }
 
     const consoleOffered = path.join(stateDir, '.console-offered');
+    const firstSession = !brain.off && !exists(consoleOffered);
+    if (firstSession) emit('[RuvNet Brain — first session initialized]');
     if (!brain.off && !exists(consoleOffered)) {
       write(consoleOffered, '');
       emit('[RuvNet Brain — FIRST LOAD: offer the Console once]');
@@ -447,7 +480,7 @@ export async function runSessionStart({
       emit('No answer: ask next session, never twice.');
     }
     const spine = stableSpine({ env, hookDir, stateDir, home, pluginVersion: running, emit, now });
-    heartbeat({ env, hookDir, stateDir, home, running, ...spine, emit, now });
+    if (runHeartbeat) heartbeat({ env, hookDir, stateDir, home, running, ...spine, emit, now });
 
     const star = path.join(stateDir, '.star-ask-shown');
     if (!brain.off && exists(path.join(stateDir, '.grounded-once')) && !exists(star) && write(star, '')) {
@@ -456,7 +489,7 @@ export async function runSessionStart({
       emit('  "Finding this useful? Star github.com/stuinfla/ruvnet-brain or leave feedback — it keeps the nightly updates coming."');
     }
 
-    const bannerVersion = running || 'unknown';
+    const bannerVersion = effectiveVersion || 'unknown';
     if (pluginRoot.startsWith(path.join(home, '.claude', 'plugins') + path.sep)) {
       if (running) write(path.join(stateDir, '.running-version'), `${running}\n`);
     } else if (running) {
@@ -521,8 +554,11 @@ export async function runSessionStart({
     if (env.RUVNET_SESSION_TRACE === '1') stderr.write(`SESSION_TRACE native-fail-open ${error?.message || error}\n`);
   }
 
-  if (env.RUVNET_VERBOSE_HOOKS !== '1') {
+  if (env.RUVNET_VERBOSE_HOOKS !== '1' && !brain.off) {
     lines.push(`[RuvNet Brain v${running || 'unknown'} — active this session]`);
+    // Keep the legacy plain status token for host integrations that key off it; it carries no
+    // instruction and does not introduce a second version or bundle identity.
+    lines.push('[RuvNet Brain active]');
   }
   const output = lines.length ? `${lines.join('\n')}\n` : '';
   meter({ env, cwd, stateDir, output });

package/scripts/brain-stamp-resolve.mjs

@@ -0,0 +1,22 @@
+// brain-stamp-resolve.mjs — pure helper split out of brain-stamp.mjs specifically so it can be unit
+// tested. brain-stamp.mjs is 100% top-level script: importing it for real shells out to git and
+// writes data/manifest.json + rewrites primer/ruvnet-primer.md as a side effect of the import alone
+// (documented in tests/unit/brain-stamp-manifest.test.mjs's header, and confirmed the hard way while
+// writing this candidate's test — an early version imported resolveBuiltFromSha straight from
+// brain-stamp.mjs and it silently restamped this checkout's own manifest/primer on `vitest run`).
+// This module has zero side effects on import; brain-stamp.mjs imports resolveBuiltFromSha from here.
+
+// `builtFromSha` promises the commit the SHIPPED RVF bytes were built from — not whatever HEAD the
+// local clone happens to sit at when the stamper runs. RVF-GENERATIONS.json's `sourceCommit` is
+// recorded once, at actual build time (rvf-generation.mjs's writeRvfGeneration); the clone's live
+// HEAD drifts from it the moment the clone is pulled or rebuilt after that. ADR-069's audit named
+// this exact gap ("clone freshness is not artifact freshness") and cites synthlang/autogenous as
+// cases where the two values already disagree in this repo's own committed kb/RVF-GENERATIONS.json.
+// Prefer the recorded generation; fall back to the live clone HEAD only for stores with no generation
+// record yet. Case-insensitive lookup matches brain-stamp.mjs's own findClone() convention (store
+// names are lowercased, clone dirs are not).
+export function resolveBuiltFromSha(name, { generations = {}, localSha = null } = {}) {
+  const key = Object.keys(generations).find((k) => k.toLowerCase() === String(name).toLowerCase());
+  const recorded = key ? generations[key].sourceCommit : null;
+  return recorded || localSha || 'unknown';
+}

package/scripts/brain-stamp.mjs

@@ -8,7 +8,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { canonicalRvfStores, hasCanonicalRvfStore } from './rvf-generation.mjs';
+import { canonicalRvfStores, hasCanonicalRvfStore, readRvfGenerations } from './rvf-generation.mjs';
+import { resolveBuiltFromSha } from './brain-stamp-resolve.mjs';
 import { getVersionTag, stripTag } from './version.mjs';
 // The org total is DERIVED, never a literal: it was hardcoded 248 in this file and in its
 // sibling while the account actually had 200 — one stale fact, restated twice (2026-08-12).
@@ -27,6 +28,7 @@ const shaOf = (dir) => { try { return execFileSync('git', ['rev-parse', 'HEAD'],
 // no shell: slug is placed in a URL arg, never interpreted by a shell
 const remoteSha = (slug) => { try { return execFileSync('git', ['ls-remote', `https://github.com/ruvnet/${slug}`, 'HEAD']).toString().split(/\s/)[0] || null; } catch { return null; } };
 
+const generations = readRvfGenerations(KB_DIR).stores || {};
 const tiers = JSON.parse(fs.readFileSync(path.join(ROOT, 'data/registry.tiers.json'), 'utf8'));
 const repos = [];
 for (const t of ['T0', 'T1', 'T2', 'T3']) {
@@ -38,7 +40,7 @@ for (const t of ['T0', 'T1', 'T2', 'T3']) {
     const localSha = fs.existsSync(path.join(cloneDir, '.git')) ? shaOf(cloneDir) : null;
     repos.push({
       name: r.name, tier: t, stars: r.stars,
-      builtFromSha: builtName(r.name) ? (localSha || 'unknown') : null,
+      builtFromSha: builtName(r.name) ? resolveBuiltFromSha(r.name, { generations, localSha }) : null,
       latestRemoteSha: null,           // filled by --check-remote (network) in self-update
       status: builtName(r.name) ? 'built' : 'pending',
     });
@@ -67,7 +69,7 @@ for (const store of canonicalRvfStores(KB_DIR)) {
   const cloneDir = findClone(store);
   repos.push({
     name: store, tier: 'fresh', stars: undefined,
-    builtFromSha: cloneDir ? (shaOf(cloneDir) || 'unknown') : 'unknown',
+    builtFromSha: resolveBuiltFromSha(store, { generations, localSha: cloneDir ? shaOf(cloneDir) : null }),
     latestRemoteSha: null,
     status: 'built',
   });

package/scripts/build-bundle.mjs

@@ -38,6 +38,7 @@ const OUT = path.resolve(ROOT, arg('--out', 'dist/ruvnet-brain'));
 const COVERAGE = arg('--coverage', null);
 const PROJECTION = arg('--projection', null);
 const BRAIN_VERSION = arg('--version', getVersionTag()); // inherits the single source of truth
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
 
 // ---- registry: tier + the full 169-repo pending list -------------------------------------------
 const registry = JSON.parse(fs.readFileSync(path.join(DATA, 'registry.tiers.json'), 'utf8'));
@@ -182,6 +183,22 @@ if (COVERAGE) {
   }
   let inventory;
   try {
+    if (PROJECTION) {
+      const projectionDir = path.resolve(PROJECTION);
+      const receiptFile = path.join(projectionDir, 'ruv-gists.sources.json');
+      if (fs.existsSync(receiptFile)) fs.copyFileSync(receiptFile, path.join(ASSETS, 'ruv-gists.sources.json'));
+      const classesFile = path.join(projectionDir, 'public-store-classes.json');
+      if (fs.existsSync(classesFile)) fs.copyFileSync(classesFile, path.join(ASSETS, 'public-store-classes.json'));
+      const conceptsReceipt = path.join(projectionDir, 'concepts.sources.json');
+      if (fs.existsSync(conceptsReceipt)) fs.copyFileSync(conceptsReceipt, path.join(ASSETS, 'concepts.sources.json'));
+      // The projection is derived from the public seed and therefore does not
+      // contain the repository's release-policy fence.  The inventory validator
+      // still needs that fence when validating the projected input.
+      const privateStores = path.join(KB, 'PRIVATE-STORES.json');
+      if (fs.existsSync(privateStores) && !fs.existsSync(path.join(ASSETS, 'PRIVATE-STORES.json'))) {
+        fs.copyFileSync(privateStores, path.join(ASSETS, 'PRIVATE-STORES.json'));
+      }
+    }
     inventory = validatePublicInventory({ assetsDir: ASSETS, coverage, ledger: readRvfGenerations(ASSETS) });
   } catch (error) {
     console.error(`[build-bundle] FATAL: public inventory is not exhaustive (${error.message})`);
@@ -291,9 +308,29 @@ if (hasConcepts) for (const suf of ['concepts.big.rvf', 'concepts.big.rvf.idmap.
 // so ruv-gists — a PUBLIC store, not private-fenced — was silently omitted from EVERY bundle ever
 // shipped. Include it, WITH .big.passages.jsonl (the big variant opens it by name, same as concepts).
 const hasGists = fs.existsSync(path.join(ASSETS, 'ruv-gists.big.rvf'));
-if (hasGists) for (const suf of ['ruv-gists.big.rvf', 'ruv-gists.big.rvf.idmap.json', 'ruv-gists.big.rvf.embed.json', 'ruv-gists.big.passages.jsonl', 'ruv-gists.big.meta.json', 'ruv-gists.passages.jsonl', 'ruv-gists.meta.json', 'ruv-gists.sources.json']) cp(suf, OUT, { asset: true });
-// The inventory projection consumes this registry from the assembled bundle, not the checkout.
-cp('public-store-classes.json', OUT, { asset: true });
+if (hasGists) {
+  // RVF and passage bytes come from the sealed seed; the source receipt is governed source
+  // evidence from this checkout. The seed predates shipping that receipt, so sourcing every file
+  // from ASSETS makes the release projection fail closed even though the exact gist bytes exist.
+  for (const suf of ['ruv-gists.big.rvf', 'ruv-gists.big.rvf.idmap.json', 'ruv-gists.big.rvf.embed.json', 'ruv-gists.big.passages.jsonl', 'ruv-gists.big.meta.json', 'ruv-gists.passages.jsonl', 'ruv-gists.meta.json']) cp(suf, OUT, { asset: true });
+  cp('ruv-gists.sources.json', OUT, { required: !PROJECTION });
+}
+// The inventory projection consumes this registry from the assembled bundle. Older corpus seeds
+// do not carry it, so derive the only valid legacy class (concepts) from the exact bytes already
+// assembled instead of failing before projection can create its release-bound evidence set.
+if (!cp('public-store-classes.json', OUT, { asset: true })) {
+  const derived = [];
+  const conceptsPassages = path.join(OUT, 'concepts.passages.jsonl');
+  if (fs.existsSync(conceptsPassages)) {
+    const bytes = fs.readFileSync(conceptsPassages);
+    const receipt = { schemaVersion: 1, kind: 'ruvnet-brain-derived-store-receipt', store: 'concepts',
+      inputs: [{ path: 'concepts.passages.jsonl', sha256: sha256(bytes) }], passagesSha256: sha256(bytes) };
+    fs.writeFileSync(path.join(OUT, 'concepts.sources.json'), `${JSON.stringify(receipt, null, 2)}\n`);
+    derived.push({ store: 'concepts', receipt: 'concepts.sources.json' });
+  }
+  fs.writeFileSync(path.join(OUT, 'public-store-classes.json'), `${JSON.stringify({ schemaVersion: 1, derived }, null, 2)}\n`);
+  copied++;
+}
 
 // capability-cards.md — the FAST LANE's zero-ML answer source (kb/card-lane.mjs, the first
 // responder search_ruvnet consults before the heavy cross-repo search). Ships as its own small
@@ -470,7 +507,7 @@ cp(path.join(ROOT, 'keys', 'ruvnet-brain-signing.pub.pem'), path.join(OUT, 'keys
 // ReleaseProjection is generated from the exact candidate asset tree immediately before this
 // assembly. Copy all three linked ledgers together; a partial projection is never publishable.
 if (PROJECTION) {
-  for (const file of ['COVERAGE.json', 'CORPUS-COVERAGE.json', 'PUBLIC-RVF-GENERATIONS.json']) {
+  for (const file of ['COVERAGE.json', 'CORPUS-COVERAGE.json', 'PUBLIC-RVF-GENERATIONS.json', 'ruv-gists.sources.json', 'public-store-classes.json', 'concepts.sources.json']) {
     cp(path.join(path.resolve(PROJECTION), file), OUT, { required: true });
   }
 }

package/scripts/ci/step-watchdog.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Run one CI operation with an explicit wall-clock budget and visible progress.
+// GitHub Actions has job timeouts, but no per-step timeout. This wrapper makes a
+// stalled operation fail locally at its named boundary and leaves a receipt.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const argv = process.argv.slice(2);
+const value = (flag, fallback = null) => {
+  const index = argv.indexOf(flag);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+};
+const separator = argv.indexOf('--');
+const command = separator >= 0 ? argv.slice(separator + 1) : [];
+const name = value('--name', command[0] || 'ci-step');
+const timeoutMs = Number(value('--timeout-ms', '600000'));
+const heartbeatMs = Number(value('--heartbeat-ms', '30000'));
+const receiptDir = value('--receipt-dir', process.env.RUNNER_TEMP ? path.join(process.env.RUNNER_TEMP, 'step-receipts') : path.join(os.tmpdir(), 'ruvnet-brain-step-receipts'));
+
+if (!command.length || !Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isFinite(heartbeatMs) || heartbeatMs <= 0) {
+  console.error('usage: node step-watchdog.mjs --name <name> --timeout-ms <ms> [--heartbeat-ms <ms>] [--receipt-dir <dir>] -- <command> [args...]');
+  process.exit(2);
+}
+
+fs.mkdirSync(receiptDir, { recursive: true });
+const startedAt = new Date().toISOString();
+const started = Date.now();
+const receiptPath = path.join(receiptDir, `${name}.json`);
+const child = spawn(command[0], command.slice(1), {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+  shell: false,
+  detached: process.platform !== 'win32',
+});
+let timedOut = false;
+let heartbeat;
+const writeReceipt = (status, exitCode = null, signal = null) => {
+  const receipt = {
+    schema: 'ruvnet-brain.ci.step-receipt',
+    name,
+    command,
+    startedAt,
+    endedAt: new Date().toISOString(),
+    elapsedMs: Date.now() - started,
+    timeoutMs,
+    status,
+    exitCode,
+    signal,
+  };
+  fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  return receipt;
+};
+
+console.log(`[watchdog] START ${name} budget=${timeoutMs}ms command=${command.join(' ')}`);
+heartbeat = setInterval(() => {
+  console.log(`[watchdog] HEARTBEAT ${name} elapsed=${Date.now() - started}ms budget=${timeoutMs}ms`);
+}, heartbeatMs);
+const timeout = setTimeout(() => {
+  timedOut = true;
+  console.error(`[watchdog] TIMEOUT ${name} after ${timeoutMs}ms; terminating process`);
+  if (process.platform === 'win32') child.kill('SIGTERM');
+  else try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+  setTimeout(() => {
+    if (!child.killed) {
+      if (process.platform === 'win32') child.kill('SIGKILL');
+      else try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); }
+    }
+  }, 2000).unref();
+}, timeoutMs);
+
+child.on('error', (error) => {
+  clearTimeout(timeout); clearInterval(heartbeat);
+  writeReceipt('ERROR', null, error.code || error.name);
+  console.error(`[watchdog] ERROR ${name}: ${error.message}`);
+  process.exit(1);
+});
+child.on('close', (code, signal) => {
+  clearTimeout(timeout); clearInterval(heartbeat);
+  const status = timedOut ? 'TIMEOUT' : code === 0 ? 'PASS' : 'FAIL';
+  const receipt = writeReceipt(status, code, signal);
+  console.log(`[watchdog] ${status} ${name} elapsed=${receipt.elapsedMs}ms receipt=${receiptPath}`);
+  process.exit(status === 'PASS' ? 0 : 1);
+});

package/scripts/convergence-manifest.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Deterministic convergence authority for source identity, version surfaces, ADR inventory,
+// and executable ownership. No timestamps or live-network answers are included.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const OUT = path.join(ROOT, 'data', 'convergence-manifest.json');
+const VERSION_FILES = [
+  'package.json', 'plugin/.claude-plugin/plugin.json', 'plugin/.codex-plugin/plugin.json',
+  'data/manifest.json', 'kb/RVF-GENERATIONS.json', 'explainer/index.html', 'primer/ruvnet-primer.md',
+];
+const INVENTORY_DIRS = ['src', 'bin', 'console', 'data', 'docs/adr', 'kb', 'plugin', 'scripts', 'tests', '.github'];
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel));
+const tracked = () => execFileSync('git', ['-C', ROOT, 'ls-files', '-z', '--', ...INVENTORY_DIRS], { encoding: 'buffer' })
+  .toString().split('\0').filter(Boolean).sort();
+const fileRows = (files) => files.filter((rel) => rel !== 'data/convergence-manifest.json' && fs.existsSync(path.join(ROOT, rel)))
+  .map((rel) => ({ path: rel, sha256: sha256(read(rel)), bytes: fs.statSync(path.join(ROOT, rel)).size }));
+const stable = (value) => {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+};
+
+function build() {
+  const versions = Object.fromEntries(VERSION_FILES.map((rel) => {
+    const text = read(rel).toString('utf8');
+    const match = rel.endsWith('.html') ? text.match(/softwareVersion["']\s*:\s*["']([^"']+)/)
+      : rel.endsWith('.md') ? text.match(/Brain version:\s*v([^\s·]+)/i)
+        : text.match(/"(?:version|brainVersion)"\s*:\s*"([^\"]+)"/);
+    return [rel, match?.[1] || null];
+  }));
+  const version = JSON.parse(read('package.json')).version;
+  const files = fileRows(tracked());
+  const sourceIdentity = sha256(Buffer.from(files.map((row) => `${row.path}\0${row.sha256}\0${row.bytes}\n`).join('')));
+  return { schemaVersion: 1, kind: 'ruvnet-brain-convergence-manifest', version, sourceIdentity,
+    versionSurfaces: versions,
+    adrInventory: fs.readdirSync(path.join(ROOT, 'docs/adr')).filter((name) => name.endsWith('.md')).sort(),
+    trackedFileCount: files.length, trackedFilesSha256: sha256(Buffer.from(JSON.stringify(files))),
+    ownershipChecks: ['version:check', 'doc:currency', 'wired:check'] };
+}
+
+function check() {
+  if (!fs.existsSync(OUT)) throw new Error('manifest missing; run npm run convergence:write');
+  const expected = build();
+  const actual = JSON.parse(fs.readFileSync(OUT, 'utf8'));
+  if (stable(actual) !== stable(expected)) throw new Error('manifest is stale; run npm run convergence:write');
+  if (Object.values(actual.versionSurfaces).some((value) => value !== actual.version)) {
+    throw new Error('version surfaces do not converge on package.json');
+  }
+  console.log(JSON.stringify({ ok: true, version: actual.version, sourceIdentity: actual.sourceIdentity,
+    trackedFileCount: actual.trackedFileCount, adrCount: actual.adrInventory.length }));
+}
+
+if (process.argv.includes('--write')) {
+  fs.writeFileSync(OUT, `${JSON.stringify(build(), null, 2)}\n`);
+  console.log(`[convergence] wrote ${path.relative(ROOT, OUT)}`);
+} else {
+  try { check(); } catch (error) { console.error(`[convergence] ${error.message}`); process.exitCode = 1; }
+}

package/scripts/distill-project.mjs

@@ -96,12 +96,25 @@ function writeReceipt(rec) {
   } catch { return false; }
 }
 
-/** The newest snapshot this project has, or null. Used to tell the user what `--restore` would take. */
-function newestSnapshot() {
+// Some filesystems truncate mtime to whole seconds (FAT32, some overlay/network mounts), so a file
+// written a moment after `sinceMs` was captured can still report an mtime slightly before it. This
+// grace window is tolerance for that truncation, not a loophole — it stays far smaller than the gap
+// between one run and the next.
+const MTIME_GRACE_MS = 1500;
+
+/**
+ * The newest snapshot this project has, or null. With `sinceMs`, only a file whose mtime is no
+ * older than that moment (minus the grace window) counts — so a stale snapshot left over from a
+ * PRIOR run can never be mistaken for proof that THIS run's backup actually landed. `--restore`
+ * calls this with no floor: it legitimately wants the newest snapshot ever, not the newest since a
+ * particular run.
+ */
+function newestSnapshot(sinceMs = 0) {
   try {
     const files = fs.readdirSync(BACKUP_DIR)
       .filter((f) => /\.(db|sqlite|bak)$/i.test(f) || /memory.*\d/.test(f))
       .map((f) => ({ f, p: path.join(BACKUP_DIR, f), t: fs.statSync(path.join(BACKUP_DIR, f)).mtimeMs }))
+      .filter((x) => x.t >= sinceMs - MTIME_GRACE_MS)
       .sort((a, b) => b.t - a.t);
     return files.length ? files[0].p : null;
   } catch { return null; }
@@ -158,13 +171,18 @@ if (DRY) {
 
 // ── 1. SNAPSHOT FIRST. This is the undo; without it the operation is not offerable. ────────────────
 say('snapshot: taking a WAL-safe copy via `ruflo memory backup` before touching anything…');
+const backupStartedAt = Date.now();
 const bk = ruflo(['memory', 'backup', '--db', DB, '--dir', BACKUP_DIR]);
 if (!bk.ok) {
   die(`REFUSING TO DISTILL — the snapshot failed (${bk.err.trim().split('\n')[0] || 'unknown error'}).\n`
     + 'This is deliberate: distillation without a verified undo is exactly the unsafe offer this wrapper exists to prevent.');
 }
-const snapshot = newestSnapshot();
-if (!snapshot) die('REFUSING TO DISTILL — `memory backup` reported success but no snapshot file is present, so the undo cannot be located.');
+// sinceMs=backupStartedAt: a stale snapshot from a PRIOR run sitting in BACKUP_DIR must never be
+// mistaken for proof that THIS backup call actually wrote something (issue: `ruflo memory backup`
+// exiting 0 without landing a new file — process killed post-commit, a --dir misconfiguration, a
+// ruflo regression — would otherwise be indistinguishable from a genuine fresh backup).
+const snapshot = newestSnapshot(backupStartedAt);
+if (!snapshot) die('REFUSING TO DISTILL — `memory backup` reported success but no snapshot from this run is present, so the undo cannot be located.');
 say(`snapshot: ${snapshot.replace(HOME, '~')}`);
 
 // ── 2. RECEIPT, FAIL-CLOSED, BEFORE THE MUTATION. ─────────────────────────────────────────────────

package/scripts/eval-brain.mjs

@@ -70,10 +70,20 @@ export function wilson(k, n, z = 1.96) {
 /**
  * Grade one answered question by its stratum's rule. Pure — takes the verifier verdict, the top
  * citation (with its ce score), and whether the raw output carried the gist provenance banner.
+ *
+ * `receipt` (verifyGrounding's `receipt.repo`, from kb/verify-citation.mjs) names the citation that
+ * ACTUALLY resolved on disk — not necessarily citations[0]. citationResolves walks citations in rank
+ * order and accepts the first that resolves, so when the top-ranked citation is unverified/fabricated
+ * but a lower-ranked one grounds the answer, `citations[0].repo` is the WRONG repo to credit or debit
+ * "routed" against: it can under-count a correctly-routed answer (top fabricated, real hit lower) or
+ * over-count a wrong one (top coincidentally names the expected repo but never resolved). `routed`
+ * answers "does the query reach the store that actually holds the answer" (brain-score.mjs's own
+ * wording for this metric) — that store is the one named in `receipt`, when one was verified.
  */
-export function gradeQuestion(q, { grounded, citations, bannerPresent }) {
+export function gradeQuestion(q, { grounded, citations, bannerPresent, receipt }) {
   const top = citations?.[0] ?? null;
-  const routed = !!(grounded && q.expectRepo?.length && top && q.expectRepo.includes(top.repo));
+  const routedRepo = receipt?.repo ?? top?.repo ?? null;
+  const routed = !!(grounded && q.expectRepo?.length && routedRepo && q.expectRepo.includes(routedRepo));
   const abstained = !top || (typeof top.ce === 'number' && top.ce < ABSTAIN_CE);
   switch (q.stratum) {
     case 'adversarial':
@@ -180,7 +190,7 @@ async function main() {
         continue;
       }
       const v = await verifyGrounding(out, KB);
-      const graded = gradeQuestion(q, { grounded: v.grounded, citations: v.citations, bannerPresent: /GIST STATUS/.test(out) });
+      const graded = gradeQuestion(q, { grounded: v.grounded, citations: v.citations, receipt: v.receipt, bannerPresent: /GIST STATUS/.test(out) });
       const top = v.citations?.[0] ?? null;
       rows[i] = {
         id: q.id, stratum: q.stratum, query: q.query,

package/scripts/execution-policy.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// One deterministic boundary between Brain knowledge and consequential execution.
+// This module is deliberately pure: it never loads credentials, calls a provider, or mutates state.
+
+const NATIVE_HOSTS = new Set(['claude', 'codex']);
+const API_EXECUTORS = new Set(['agent_execute', 'sdk', 'openrouter', 'api']);
+const ARCHITECTURE_TERMS = /\b(adr|ddd|architecture|release|deploy|qa|security|schema|migration)\b/i;
+
+export function classifyExecutionPolicy(input = {}) {
+  const action = String(input.action || 'read');
+  const description = String(input.description || '');
+  const changedFiles = [...new Set((input.changedFiles || []).map(String).filter(Boolean))];
+  const nativeHosts = [...new Set((input.nativeHosts || []).map(String).filter((h) => NATIVE_HOSTS.has(h)))];
+  const requestedExecutor = String(input.requestedExecutor || '');
+  const explicitSwarm = input.explicitSwarm === true;
+  const multiFile = changedFiles.length >= 3;
+  const architectureTask = ARCHITECTURE_TERMS.test(description) || ['release', 'external'].includes(action);
+  const swarmRequired = explicitSwarm || multiFile || architectureTask;
+  const swarmReason = explicitSwarm
+    ? 'explicit-swarm-request'
+    : multiFile
+      ? 'three-or-more-independent-file-surfaces'
+      : architectureTask
+        ? 'architecture-or-consequential-action'
+        : 'single-sequential-surface';
+
+  if (action !== 'delegate') {
+    return {
+      schema: 'ruvnet-brain.execution-policy.v1',
+      verdict: 'ALLOW', action, swarmRequired, swarmReason,
+      executor: 'current-agent', reason: 'delegation-not-requested',
+    };
+  }
+
+  const nativeHost = NATIVE_HOSTS.has(input.activeHost) && nativeHosts.includes(input.activeHost)
+    ? input.activeHost : nativeHosts[0] || null;
+  if (API_EXECUTORS.has(requestedExecutor)) {
+    return {
+      schema: 'ruvnet-brain.execution-policy.v1',
+      verdict: nativeHost ? 'REFUSE' : 'DEGRADED', action, swarmRequired, swarmReason,
+      executor: nativeHost ? `native:${nativeHost}` : 'unknown',
+      reason: nativeHost
+        ? 'api-backed-executor-is-not-the-native-subscription-route'
+        : 'no-authenticated-native-host-is-available',
+    };
+  }
+  if (!nativeHost) {
+    return {
+      schema: 'ruvnet-brain.execution-policy.v1',
+      verdict: 'DEGRADED', action, swarmRequired, swarmReason, executor: 'unknown',
+      reason: 'no-authenticated-native-host-is-available',
+    };
+  }
+  return {
+    schema: 'ruvnet-brain.execution-policy.v1',
+    verdict: 'ALLOW', action, swarmRequired, swarmReason,
+    executor: `native:${nativeHost}`, reason: 'native-subscription-route-selected',
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const raw = process.argv[2] || '{}';
+  let input;
+  try { input = JSON.parse(raw); } catch { process.stderr.write('execution-policy: input must be JSON\n'); process.exit(2); }
+  process.stdout.write(`${JSON.stringify(classifyExecutionPolicy(input))}\n`);
+}

package/scripts/git-hooks/pre-push

@@ -114,6 +114,22 @@ if [ "$commands_status" -ne 0 ]; then
   exit 1
 fi
 
+# The convergence manifest is the exact source/version/ADR identity consumed by hosted QA.
+# Check it here so a push cannot publish a commit whose generated identity was produced before
+# the final source edit (the failure mode that repeatedly escaped local pre-push validation).
+if [ -f "$ROOT/scripts/convergence-manifest.mjs" ]; then
+  node "$ROOT/scripts/convergence-manifest.mjs"
+  convergence_status=$?
+else
+  convergence_status=0
+fi
+if [ "$convergence_status" -ne 0 ]; then
+  echo ""
+  echo "  ⛔ pre-push gate refused this push — convergence identity is stale."
+  echo "     Run: npm run convergence:write"
+  exit 1
+fi
+
 # ── DOCUMENT CURRENCY (ADR-056 §5) ─────────────────────────────────────────────────────────────────
 # The tool was written and tested on 2026-07-22 and then invoked by NOTHING for five days — absent
 # from this hook, gate.sh, gates.mjs and every workflow, while `wired-check` reported it "wired"

package/scripts/health-repair.mjs

@@ -25,11 +25,15 @@ import os from 'node:os';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { findStores, diagnose } from './memory-doctor.mjs';
 import { learnerCwd, loadRuntimePreferences } from '../plugin/scripts/runtime-preferences.mjs';
+import { projectDirectory } from '../plugin/scripts/project-identity.mjs';
 
 const HOME = os.homedir();
 // The SAME project root learn-flush.mjs computes, by the same rule — the two halves of the flush
 // have to agree about which project they mean or they address different queues (issue #104).
-const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
+// RESIDUAL of #134: RUVNET_BRAIN_PROJECT_DIR is never set by real hook dispatch on either host, so
+// consult `projectDirectory()` (project-identity.mjs) — the CLAUDE_PROJECT_DIR-with-containment
+// rule #85/#107 already established, reused rather than trusting the variable unconditionally.
+const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || projectDirectory();
 const argv = process.argv.slice(2);
 const has = (f) => argv.includes(f);
 

package/scripts/public-verification-aggregate.mjs

@@ -159,7 +159,9 @@ export function buildPublicVerificationAggregate(leaves, reviews) {
     deltaCases: delta.length,
     deltaHits: delta.filter(({ retrievalHit }) => retrievalHit === true).length,
     recallAt10: retrievalCases.filter(({ retrievalHit }) => retrievalHit === true).length / retrievalCases.length,
-    deltaCitationRate: delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length,
+    // A release with no corpus delta has no delta citations to score; the sealed
+    // retrieval plan carries noDelta=true and still requires the legacy cohort.
+    deltaCitationRate: delta.length === 0 ? 1 : delta.filter(({ retrievalHit, citationResolved }) => retrievalHit === true && citationResolved === true).length / delta.length,
     skipped: leaves.reduce((sum, leaf) => sum + leaf.skipped + leaf.retrieval.metrics.skipped, 0),
     unknown: leaves.reduce((sum, leaf) => sum + leaf.unknown + leaf.retrieval.metrics.unknown, 0),
   };