ruvnet-brain 4.5.9 → 4.5.11

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.9 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.9-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.11 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.11-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 

package/bin/install.mjs

@@ -11,7 +11,7 @@
 // Design rules: dependency-free (Node built-ins + shelling to unzip/npm/claude only), idempotent
 // (safe to re-run), and never a silent half-state (every failure explains the next step).
 
-import https from 'node:https';
+import { downloadFileWithRetry, httpsJsonWithRetry } from '../kb/download-retry.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -25,6 +25,7 @@ import { acquireRefreshLock, finishRefreshReceipt, openRefreshReceipt, physicalP
   recordRefreshPhase, settleRefreshRun, UPDATE_REFRESH_PHASES } from '../kb/refresh-run.mjs';
 import { assessLifecycleEvidence, pruneLifecycleEvidence } from '../kb/lifecycle-evidence-retention.mjs';
 import { checkDiskSpace, recoverIncompleteStorageTransactions } from '../kb/update-storage-transaction.mjs';
+import { saveUpdateSource, stableNode } from '../plugin/scripts/automatic-update.mjs';
 import { footprintRoots, inventoryFootprint, sweepFootprint } from '../plugin/scripts/brain-footprint.mjs';
 import { kbCopyProof } from '../plugin/scripts/kb-copy-proof.mjs';
 import { assessMoveLeftovers, isVolumeMetadata } from '../plugin/scripts/footprint-io.mjs';
@@ -122,8 +123,13 @@ const REPO = 'stuinfla/ruvnet-brain';
 const RELEASE_API = `https://api.github.com/repos/${REPO}/releases/latest`;
 const ASSET_NAME = 'ruvnet-brain.zip';
 const fallbackUrl = (tag) => `https://github.com/${REPO}/releases/download/${tag}/${ASSET_NAME}`;
-const APPROX_SIZE = '~736MB';
 
+export function optionArg(args, flag) {
+  const at = args.indexOf(flag);
+  if (at < 0) return undefined;
+  if (!args[at + 1] || args[at + 1].startsWith('-') || args.filter(value => value === flag).length !== 1) throw new Error(`${flag} requires one value`);
+  return args[at + 1];
+}
 const argv = process.argv.slice(2);
 const FLAG_LOCAL = argv.includes('--local');
 const FLAG_FORCE = argv.includes('--force');
@@ -182,6 +188,9 @@ export function namedReleaseFromArgs(args) {
   };
   const pin = valueAfter('--pin');
   const version = valueAfter('--version');
+  if (version === null) {
+    return { error: '--version needs the release to install, e.g.  --version vX.Y.Z', hint: 'Use --help for installer options; read the package manifest to inspect the installed version.' };
+  }
   if (pin === null) {
     return { error: '--pin needs the release to install, e.g.  --pin vX.Y.Z', hint: `It no longer falls back to a built-in release (that bundle could not pass validation). Pick one from https://github.com/${REPO}/releases, or omit --pin to install the latest.` };
   }
@@ -270,94 +279,25 @@ function tryHostCli(cmd, args, opts = {}) {
 }
 
 // ── download with redirect-following + progress ──────────────────────────────────────────────────
-function download(url, dest, redirects = 0) {
-  return new Promise((resolve, reject) => {
-    if (redirects > 10) return reject(new Error('too many redirects'));
-    const req = https.get(
-      url,
-      { headers: { 'User-Agent': 'ruvnet-brain-installer', Accept: 'application/octet-stream' } },
-      (res) => {
-        const { statusCode = 0, headers } = res;
-        if ([301, 302, 303, 307, 308].includes(statusCode) && headers.location) {
-          res.resume(); // drain so the socket frees up
-          const next = new URL(headers.location, url).toString();
-          return resolve(download(next, dest, redirects + 1));
-        }
-        if (statusCode !== 200) {
-          res.resume();
-          return reject(new Error(`server returned HTTP ${statusCode}`));
-        }
-        const total = Number(headers['content-length'] || 0);
-        let received = 0;
-        let lastShown = -1;
-        const out = fs.createWriteStream(dest);
-        res.on('data', (chunk) => {
-          received += chunk.length;
-          const mb = (received / 1e6).toFixed(0);
-          if (total) {
-            const pct = Math.floor((received / total) * 100);
-            if (pct !== lastShown && pct % 5 === 0) {
-              process.stdout.write(`\r    …${pct}% (${mb}MB / ${(total / 1e6).toFixed(0)}MB)`);
-              lastShown = pct;
-            }
-          } else if (mb % 20 === 0 && Number(mb) !== lastShown) {
-            process.stdout.write(`\r    …${mb}MB`);
-            lastShown = Number(mb);
-          }
-        });
-        res.pipe(out);
-        out.on('finish', () => out.close(() => {
-          process.stdout.write('\n');
-          resolve();
-        }));
-        out.on('error', (e) => reject(e));
-      },
-    );
-    req.on('error', (e) => reject(e));
-  });
+function download(url, dest) {
+  let lastShown = -1;
+  return downloadFileWithRetry(url, dest, {
+    headers: { 'User-Agent': 'ruvnet-brain-installer', Accept: 'application/octet-stream' },
+    onRetry: ({ attempt, error }) => warn(`download interrupted (${error.message}); retry ${attempt + 1}/3 from a fresh stage`),
+    onProgress: ({ received, total }) => {
+      const mb = Math.floor(received / 1e6);
+      const pct = total ? Math.floor(received / total * 100) : mb;
+      if (pct !== lastShown && pct % (total ? 5 : 20) === 0) {
+        process.stdout.write(`\r    …${total ? `${pct}% (${mb}MB / ${Math.floor(total / 1e6)}MB)` : `${mb}MB`}`);
+        lastShown = pct;
+      }
+    },
+  }).then(() => process.stdout.write('\n'));
 }
 
-// ── fetch a small JSON payload (redirect-following, dependency-free) ──────────────────────────────
-function fetchJson(url, redirects = 0) {
-  return new Promise((resolve, reject) => {
-    if (redirects > 10) return reject(new Error('too many redirects'));
-    const req = https.get(
-      url,
-      {
-        headers: {
-          // GitHub's API requires a User-Agent; the Accept header pins the v3 JSON schema.
-          'User-Agent': 'ruvnet-brain-installer',
-          Accept: 'application/vnd.github+json',
-        },
-        timeout: 15000,
-      },
-      (res) => {
-        const { statusCode = 0, headers } = res;
-        if ([301, 302, 303, 307, 308].includes(statusCode) && headers.location) {
-          res.resume();
-          const next = new URL(headers.location, url).toString();
-          return resolve(fetchJson(next, redirects + 1));
-        }
-        if (statusCode !== 200) {
-          res.resume();
-          const reset = headers['x-ratelimit-remaining'] === '0' && Number(headers['x-ratelimit-reset']);
-          return reject(new Error(`GitHub API returned HTTP ${statusCode}${reset
-            ? ` (anonymous rate limit used up; it resets at ${new Date(reset * 1000).toISOString()})` : ''}`));
-        }
-        let body = '';
-        res.setEncoding('utf8');
-        res.on('data', (chunk) => (body += chunk));
-        res.on('end', () => {
-          try {
-            resolve(JSON.parse(body));
-          } catch (e) {
-            reject(new Error(`GitHub API response was not valid JSON: ${e.message}`));
-          }
-        });
-      },
-    );
-    req.on('timeout', () => req.destroy(new Error('GitHub API request timed out')));
-    req.on('error', (e) => reject(e));
+function fetchJson(url) {
+  return httpsJsonWithRetry(url, {
+    headers: { 'User-Agent': 'ruvnet-brain-installer', Accept: 'application/vnd.github+json' },
   });
 }
 
@@ -505,7 +445,7 @@ async function obtainBundle(release) {
   if (!release || !release.url) die('no release was resolved to download.', 'Re-run to look up the latest release, or name one with  --version <tag>.');
   const downloadUrl = release.url;
   step(
-    `Downloading the brain (${APPROX_SIZE})`,
+    'Downloading the brain',
     'the brain embeds source from dozens of RuvNet repos — too big for git, so it ships as a Release',
   );
   info(`version: ${c.bold(release.tag)}`);
@@ -520,7 +460,7 @@ async function obtainBundle(release) {
   process.on('exit', () => { try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ } });
   const tmp = path.join(tmpDir, ASSET_NAME);
   try {
-    console.log(`    downloading the brain (${APPROX_SIZE})…`);
+    console.log('    downloading the brain…');
     await download(downloadUrl, tmp);
   } catch (e) {
     try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
@@ -607,7 +547,7 @@ function placeFileAtomic(target, bytes) {
 // one. The signed npm package carries the updater and the sibling modules it imports; the `--update`
 // preflight places them (same trust as the validator) so a stale updater upgrades itself before it runs.
 const UPDATER_FILES = ['forge-update.mjs', 'zip-extract.mjs', 'brain-profile.mjs', 'refresh-run.mjs',
-  'update-storage-transaction.mjs', 'lifecycle-evidence-retention.mjs', 'corpus-release-identity.mjs'];
+  'update-storage-transaction.mjs', 'lifecycle-evidence-retention.mjs', 'corpus-release-identity.mjs', 'download-retry.mjs'];
 export function placeUpdater(kbDir, { sourceDir = path.join(REPO_ROOT, 'kb') } = {}) {
   const placed = {};
   for (const name of UPDATER_FILES) {
@@ -4374,7 +4314,8 @@ function enableNightly() {
   try {
     const brainHome = process.env.RUVNET_BRAIN_HOME || path.dirname(kbDir);
     const registration = installNightlyRunner({ brainHome, env: { ...process.env, RUVNET_BRAIN_HOME: brainHome, RUVNET_BRAIN_KB: kbDir },
-      source: path.join(REPO_ROOT, 'bin', 'nightly-refresh.mjs') });
+      source: path.join(REPO_ROOT, 'bin', 'nightly-refresh.mjs'),
+      nodePath: stableNode({ explicit: optionArg(argv, '--nightly-node') }) });
     const installed = installScheduler(registration, {
       platform: process.platform, env: process.env, kbDir, testMode: TEST_MODE,
       pathValue: [...new Set([path.dirname(process.execPath), ...(process.env.PATH || '').split(path.delimiter)])].filter(Boolean).join(path.delimiter),
@@ -4990,7 +4931,7 @@ export function syncManagedRouterTools({ routerDir = path.join(os.homedir(), '.c
   const destination = path.join(routerDir, 'bin');
   fs.mkdirSync(destination, { recursive: true });
   let copied = 0;
-  for (const name of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'subscription-hosts.mjs', 'review-model-defaults.mjs', 'dual-host-deliberation.mjs', 'dual-host-suggest.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'metaharness-router.mjs', 'model-router-dispatch.mjs', 'model-currency.mjs', 'model-currency-evidence.mjs', 'user-model-prompt-hook.mjs', 'model-router-agent-hook.mjs', 'model-weekly-assessment.mjs', 'model-weekly-analyst.mjs', 'model-weekly-cycle.mjs', 'model-weekly-qualification.mjs', 'model-native-qualification.mjs', 'model-routing-launchers.mjs', 'model-terminal-gateway.mjs', 'model-terminal-launchers.mjs', 'claude-terminal-mod.mjs', 'model-native-catalog.mjs', 'model-analyst-sandbox.mjs', 'model-routing-policy-promotion.mjs', 'model-routing-gateway.mjs', 'native-subscription-usage.mjs', 'codex-routed.sh', 'goldie-weekly.sh']) {
+  for (const name of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'subscription-hosts.mjs', 'review-model-defaults.mjs', 'dual-host-deliberation.mjs', 'dual-host-suggest.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'metaharness-router.mjs', 'model-router-dispatch.mjs', 'model-currency.mjs', 'model-currency-evidence.mjs', 'user-model-prompt-hook.mjs', 'model-router-agent-hook.mjs', 'model-weekly-assessment.mjs', 'model-weekly-analyst.mjs', 'model-weekly-cycle.mjs', 'model-weekly-qualification.mjs', 'model-native-qualification.mjs', 'model-routing-launchers.mjs', 'model-terminal-gateway.mjs', 'model-terminal-launchers.mjs', 'claude-terminal-mod.mjs', 'claude-controlled-terminal.mjs', 'model-native-catalog.mjs', 'model-analyst-sandbox.mjs', 'model-routing-policy-promotion.mjs', 'model-routing-gateway.mjs', 'native-subscription-usage.mjs', 'codex-routed.sh', 'goldie-weekly.sh']) {
     const source = path.join(packageRoot, 'scripts', name);
     if (!fs.existsSync(source)) throw new Error(`Packaged router tool missing: ${name}`);
     const target = path.join(destination, name);
@@ -6183,6 +6124,9 @@ Usage:
   npx ruvnet-brain --enhance-claude-md    Add the 6-line RuvNet-Brain block to ~/.claude/CLAUDE.md
                               (appended at the bottom between markers; your file is backed up first)
                               (a default install RECOMMENDS nightly and asks, defaulting to yes)
+  node bin/install.mjs --update-source installed  Keep compatible signed corpus updates; never unattended npx
+  node bin/install.mjs --update-source latest     Restore the default latest-package update coordinator
+  node bin/install.mjs --enable-nightly --nightly-node /absolute/stable/node  Use a supported stable Node alias
   node bin/install.mjs --no-nightly-prompt Don't offer nightly auto-updates at the end of the install
   node bin/install.mjs --no-telemetry      Decline anonymous usage counts without being asked
                               (counts of installs/searches ONLY — never queries, code, or paths;
@@ -6230,6 +6174,17 @@ the installer reports that boot-level declarations changed.
     && canonical(process.argv[1]) === canonical(fileURLToPath(import.meta.url));
   if (!invokedDirectly) return;
   if (FLAG_HELP) return showHelp();
+  if (NAMED_RELEASE?.error) {
+    console.error(NAMED_RELEASE.error);
+    console.error(NAMED_RELEASE.hint);
+    process.exitCode = 1;
+    return;
+  }
+  if (argv.includes('--update-source')) {
+    try { saveUpdateSource(optionArg(argv, '--update-source')); }
+    catch (error) { console.error(error.message); process.exitCode = 1; return; }
+    if (!FLAG_UPDATE && !FLAG_ENABLE_NIGHTLY) { info('automatic update source saved; other owner settings preserved'); return; }
+  }
   // The Brain moved to another disk (a symlink at ~/.cache/ruvnet-brain) and that disk is not here:
   // say so in one line and stop. Never re-create a fresh brain in ~/.cache over the dangling link, and
   // never update one that is not there. --doctor reports it as its verdict.

package/bin/nightly-refresh.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const runnerPath = path.resolve(fileURLToPath(import.meta.url));
 const registrationPath = String((process.argv[2] === '--registration' ? process.argv[3] : null) || process.env.RUVNET_NIGHTLY_REGISTRATION
@@ -21,7 +21,7 @@ try {
       && !/^com\.ruvnet\.brain-update\.proof-[A-Za-z0-9._-]+$/.test(registration.identity || ''))
     || path.resolve(registration.runnerPath || '') !== runnerPath
     || registration.runnerSha256 !== runnerSha256
-    || path.resolve(registration.nodePath || '') !== path.resolve(process.execPath)
+    || fs.realpathSync(registration.nodePath || '') !== fs.realpathSync(process.execPath)
     || !Array.isArray(registration.argv) || registration.argv.length !== 0
     || !registration.packageTarget || typeof registration.packageTarget.spec !== 'string') {
     throw new Error('registration does not bind this exact runner and Node executable');
@@ -58,44 +58,30 @@ if (registration.environment !== undefined && (!registration.environment || Arra
 }
 Object.assign(process.env, registration.environment || {});
 
-const npxName = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-const adjacent = path.join(path.dirname(process.execPath), npxName);
-const npx = fs.existsSync(adjacent) ? adjacent : npxName;
-const argv = ['--yes', registration.packageTarget.spec, '--update', '--no-nightly-prompt'];
-let executable = npx;
-let launchArgs = argv;
-if (process.platform === 'win32') {
-  // This content-addressed runner is copied alone: keep its dependency closure standalone.
-  // Like rufloInvocation, execute the managed package's declared JS entry, never a .cmd shell.
-  try {
-    const shim = fs.existsSync(adjacent) ? adjacent : String(process.env.PATH || '')
-      .split(path.delimiter).filter(Boolean).map(dir => path.join(dir, npxName))
-      .find(candidate => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
-    if (!shim) throw new Error('managed npm npx shim is missing');
-    const packageRoot = fs.realpathSync(path.join(path.dirname(fs.realpathSync(shim)), 'node_modules', 'npm'));
-    const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
-    const declared = manifest.bin?.npx;
-    if (manifest.name !== 'npm' || typeof declared !== 'string' || !declared
-      || path.isAbsolute(declared) || path.win32.isAbsolute(declared) || declared.split(/[\\/]/).includes('..')) {
-      throw new Error('managed npm package has no safe declared npx entry');
-    }
-    const entry = fs.realpathSync(path.resolve(packageRoot, declared));
-    const relative = path.relative(packageRoot, entry);
-    if (!relative || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || !fs.statSync(entry).isFile()) {
-      throw new Error('managed npm npx entry escapes its package');
-    }
-    executable = process.execPath;
-    launchArgs = [entry, ...argv];
-  } catch (error) {
-    console.error(`RuvNet Brain nightly refresh could not resolve managed npm: ${error.message}`);
-    process.exit(1);
+let invocation;
+try {
+  const modules = registration.updateModules;
+  if (!modules || Object.keys(modules).sort().join(',') !== 'automatic-update.mjs,ruvnet-gate1-pattern.mjs,user-settings.mjs') throw new Error('registered update module closure is missing');
+  for (const [name, item] of Object.entries(modules)) {
+    if (!path.isAbsolute(item.path) || path.basename(item.path) !== name
+      || path.dirname(item.path) !== path.dirname(modules['automatic-update.mjs'].path)
+      || !fs.lstatSync(item.path).isFile()
+      || crypto.createHash('sha256').update(fs.readFileSync(item.path)).digest('hex') !== item.sha256) throw new Error('update module digest mismatch');
   }
+  const policy = await import(pathToFileURL(modules['automatic-update.mjs'].path).href);
+  process.env.PATH = policy.automaticPath({ nodePath: registration.nodePath });
+  invocation = policy.automaticInvocation(['--update', '--no-nightly-prompt'], {
+    nodePath: registration.nodePath, packageTarget: registration.packageTarget.spec,
+  });
+} catch (error) {
+  console.error(`RuvNet Brain automatic update refused: ${error.message}`);
+  process.exit(1);
 }
 const allowed = ['PATH', 'HOME', 'USERPROFILE', 'RUVNET_BRAIN_HOME', 'RUVNET_BRAIN_KB',
   'npm_config_cache', 'NO_COLOR', 'SystemRoot', 'SYSTEMROOT', 'ComSpec', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP'];
 const childEnv = Object.fromEntries(allowed.filter((key) => process.env[key] !== undefined)
   .map((key) => [key, process.env[key]]));
-const result = spawnSync(executable, launchArgs, {
+const result = spawnSync(invocation.executable, invocation.args, {
   stdio: 'inherit',
   shell: false,
   env: { ...childEnv, RUVNET_NIGHTLY: '1',

package/kb/download-retry.mjs

@@ -0,0 +1,97 @@
+// Retry transport failures only. Parsing, signature and corpus validation remain caller-owned.
+import fs from 'node:fs';
+import https from 'node:https';
+import { pipeline } from 'node:stream/promises';
+import { randomUUID } from 'node:crypto';
+
+const TRANSIENT = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN', 'EPIPE',
+  'ERR_STREAM_PREMATURE_CLOSE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT']);
+function retryable(error) {
+  for (let current = error; current; current = current.cause) {
+    if (TRANSIENT.has(current.code)) return true;
+  }
+  return [408, 429, 500, 502, 503, 504].includes(error.status);
+}
+function httpError(status) {
+  return Object.assign(new Error(`server returned HTTP ${status}`), { status });
+}
+
+export async function retryDownload(operation, { deadlineMs = 20 * 60_000,
+  attemptMs = 5 * 60_000, delays = [250, 1000], onRetry = () => {} } = {}) {
+  const deadline = Date.now() + deadlineMs;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error('download deadline exceeded');
+    const controller = new AbortController();
+    const timeout = Object.assign(new Error('download request timed out'), { code: 'ETIMEDOUT' });
+    const timer = setTimeout(() => controller.abort(timeout), Math.min(attemptMs, remaining));
+    try { return await operation({ signal: controller.signal, attempt }); }
+    catch (caught) {
+      const error = controller.signal.aborted ? controller.signal.reason : caught;
+      const delay = delays[attempt - 1] ?? 0;
+      if (attempt === 3 || !retryable(error) || Date.now() + delay >= deadline) throw error;
+      onRetry({ attempt, error });
+      await new Promise(resolve => setTimeout(resolve, delay));
+    } finally { clearTimeout(timer); }
+  }
+}
+
+export async function fetchBytesWithRetry(url, { fetchImpl = globalThis.fetch, ...options } = {}) {
+  return retryDownload(async ({ signal }) => {
+    const response = await fetchImpl(url, { redirect: 'follow', signal });
+    if (!response.ok) {
+      try { await response.body?.cancel(); } catch { /* preserve the permanent HTTP refusal */ }
+      throw httpError(response.status);
+    }
+    return Buffer.from(await response.arrayBuffer());
+  }, options);
+}
+
+export async function fetchJsonWithRetry(url, options = {}) {
+  // Parse AFTER transport succeeds: malformed JSON must never be re-requested or accepted.
+  const bytes = await fetchBytesWithRetry(url, { deadlineMs: 45_000, attemptMs: 15_000, ...options });
+  return JSON.parse(bytes.toString('utf8'));
+}
+
+function get(url, { signal, headers }, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 10) { reject(new Error('too many redirects')); return; }
+    const request = https.get(url, { signal, headers }, response => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+        response.destroy();
+        resolve(get(new URL(response.headers.location, url).toString(), { signal, headers }, redirects + 1));
+      } else if (response.statusCode !== 200) {
+        response.destroy(); reject(httpError(response.statusCode));
+      } else resolve(response);
+    });
+    request.on('error', reject);
+  });
+}
+
+export async function downloadFileWithRetry(url, destination, { headers = {}, onProgress = () => {}, ...options } = {}) {
+  return retryDownload(async ({ signal }) => {
+    const staged = `${destination}.part-${process.pid}-${randomUUID()}`;
+    try {
+      const response = await get(url, { signal, headers });
+      let received = 0;
+      const total = Number(response.headers['content-length'] || 0);
+      response.on('data', bytes => { received += bytes.length; onProgress({ received, total }); });
+      await pipeline(response, fs.createWriteStream(staged, { flags: 'wx', mode: 0o600 }), { signal });
+      if (!response.complete || (total && received !== total)) {
+        throw Object.assign(new Error('download body ended prematurely'), { code: 'ECONNRESET' });
+      }
+      fs.renameSync(staged, destination);
+    } finally { fs.rmSync(staged, { force: true }); }
+  }, options);
+}
+
+export async function httpsJsonWithRetry(url, { headers = {}, ...options } = {}) {
+  const bytes = await retryDownload(async ({ signal }) => {
+    const response = await get(url, { signal, headers });
+    const chunks = [];
+    for await (const chunk of response) chunks.push(chunk);
+    if (!response.complete) throw Object.assign(new Error('response body ended prematurely'), { code: 'ECONNRESET' });
+    return Buffer.concat(chunks);
+  }, { deadlineMs: 45_000, attemptMs: 15_000, ...options });
+  return JSON.parse(bytes.toString('utf8'));
+}

package/kb/forge-update.mjs

@@ -25,6 +25,7 @@ import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
+import { fetchJsonWithRetry, fetchBytesWithRetry } from './download-retry.mjs';
 import { extractZip, zipDeclaredBytes } from './zip-extract.mjs';
 import { applyBrainProfile, discoverStoreFamilies, readBrainProfile } from './brain-profile.mjs';
 import { acquireRefreshLock, releaseRefreshLock } from './refresh-run.mjs';
@@ -773,18 +774,19 @@ if (!manifestUrl && !STAGED_RELEASE_FILE) {
 }
 
 async function fetchJson(url) {
-  let res;
-  try { res = await fetch(url, { redirect: 'follow' }); }
-  catch (e) { die(`network failure fetching ${url}\n  ${e.message} — nothing changed locally.`, 2); }
-  if (!res.ok) die(`canonical manifest returned HTTP ${res.status} for ${url} — nothing changed.`, 2);
-  try { return await res.json(); } catch (e) { die(`canonical manifest was not valid JSON: ${e.message}`, 2); }
+  try { return await fetchJsonWithRetry(url); }
+  catch (error) {
+    if (error instanceof SyntaxError) die(`canonical manifest was not valid JSON: ${error.message}`, 2);
+    if (error.status) die(`canonical manifest returned HTTP ${error.status} for ${url} — nothing changed.`, 2);
+    die(`network failure fetching ${url}: ${error.message} — nothing changed locally.`, 2);
+  }
 }
 async function fetchBuffer(url, { failureCode = 2, kind = 'bundle' } = {}) {
-  let res;
-  try { res = await fetch(url, { redirect: 'follow' }); }
-  catch (e) { die(`network failure downloading ${kind} ${url}\n  ${e.message} — nothing changed locally.`, failureCode); }
-  if (!res.ok) die(`${kind} download returned HTTP ${res.status} for ${url} — nothing changed.`, failureCode);
-  return Buffer.from(await res.arrayBuffer());
+  try { return await fetchBytesWithRetry(url); }
+  catch (error) {
+    if (error.status) die(`${kind} download returned HTTP ${error.status} for ${url} — nothing changed.`, failureCode);
+    die(`network failure downloading ${kind} ${url}: ${error.message} — nothing changed locally.`, failureCode);
+  }
 }
 
 // The canonical manifest can be ONE of three shapes — handle all three:

package/kb/verify-citation.mjs

@@ -33,9 +33,9 @@ import readline from 'node:readline';
  * stop ("not airtight"). The reader prints, before each body, `chars: <exact body length>`; the parser
  * consumes the body BY THAT COUNT and requires the 67-'=' terminator right after it, so nothing inside a
  * body is ever scanned for headers. A declared length that does not land on the terminator fails closed:
- * that hit keeps no body and nothing after it is trusted; so does a body without `chars:` once an earlier
- * hit carried one. Output with no `chars:` line at all (a reader older than this field) keeps the previous
- * bounded-span parsing; a header with no body keeps none. `path`/`title`/scores come only from the header lines between
+ * that hit keeps no body and nothing after it is trusted. Legacy bodies without `chars:` also stop
+ * parsing: their header metadata is retained, but their body and everything after it are untrusted.
+ * Metadata-only headers remain supported. `path`/`title`/scores come only from the header lines between
  * a hit's header and its body, never from a body, and hits are numbered #1, #2, … strictly in order.
  */
 const SEPARATOR = '='.repeat(67);
@@ -44,10 +44,10 @@ export function parseCitations(stdout) {
   const text = String(stdout ?? '');
   const headerRe = /^#(\d+)[ \t]+repo=(\S+)([^\r\n]*)/gm;
   const nextHeaderRe = /^#\d+\s+repo=\S+/gm;
-  const markerRe = /^----- full document -----\r?\n/gm;
+  // Recognize marker-shaped lines too: malformed framing must not expose body headers as metadata.
+  const markerRe = /^[ \t]*-{3,}[ \t]*full[ \t]+document[ \t]*-{3,}[^\r\n]*(?:\r?\n|$)/gm;
   let m;
   let expectedRank = 1;
-  let structured = false;
   while ((m = headerRe.exec(text)) !== null) {
     const rank = Number(m[1]);
     if (rank !== expectedRank) continue; // out-of-sequence header: a look-alike, not a real hit
@@ -61,28 +61,25 @@ export function parseCitations(stdout) {
     const head = text.slice(headStart, markerAt >= 0 ? markerAt : nextAt);
     const pathM = /^path\s*:\s*(.+)$/m.exec(head);
     const titleM = /^title\s*:\s*(.+)$/m.exec(head);
-    const charsM = /^chars:\s*(\d+)\b/m.exec(head);
+    const charsM = /^chars:[ \t]*(\d+)(?:[ \t]*\|[ \t]*chunks:[ \t]*\d+(?:[ \t]+\(truncated\))?)?[ \t]*\r?$/m.exec(head);
+    const bodyLength = charsM ? Number(charsM[1]) : null;
+    const canonicalMarker = marker && /^----- full document -----\r?\n$/.test(marker[0]);
     // A pathless match does not fill (or burn) its rank: real reader output never omits path, and a
     // look-alike fragment consuming the slot would reject the real citation that fills it later.
     if (!pathM) continue;
     let returnedText = null;
     let stop = false;
-    if (charsM && markerAt >= 0) {
+    if (Number.isSafeInteger(bodyLength) && bodyLength >= 0 && markerAt >= 0 && canonicalMarker) {
       const bodyStart = markerAt + marker[0].length;
       const bodyEnd = bodyStart + Number(charsM[1]);
       const terminator = text.startsWith(`\n${SEPARATOR}`, bodyEnd) ? 1 + SEPARATOR.length
         : text.startsWith(`\r\n${SEPARATOR}`, bodyEnd) ? 2 + SEPARATOR.length : 0;
       if (terminator) {
         returnedText = text.slice(bodyStart, bodyEnd);
-        structured = true;
         headerRe.lastIndex = bodyEnd + terminator; // resume AFTER the body: its contents are never parsed
       } else stop = true; // the declared body does not end where it says: its boundary, and all after it, is unknown
-    } else if (markerAt >= 0 && structured) {
-      stop = true; // a body with no declared length after length-bound hits: its boundary is unknown
     } else if (markerAt >= 0) {
-      // A reader older than `chars:`: the body is the bounded span up to the next header.
-      const body = /^----- full document -----\r?\n([\s\S]*?)\r?\n={67}(?:\r?\n|$)/m.exec(text.slice(headStart, nextAt));
-      returnedText = body ? body[1] : null;
+      stop = true; // missing/invalid length or noncanonical marker: later body boundaries are untrusted
     }
     expectedRank = rank + 1;
     const repo = m[2];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.9",
+  "version": "4.5.11",
   "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
     "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
     "route:cheap": "node scripts/route-cheap.mjs",
     "routing:eval": "node scripts/model-routing-eval.mjs",
+    "routing:hooks:plan": "node scripts/user-model-hook-install.mjs --plan",
     "hooks:security-guidance:compat": "node scripts/security-guidance-codex-compat.mjs",
     "route:receipt": "node scripts/dispatch-receipt.mjs",
     "trismart": "node scripts/trismart.mjs",
@@ -102,6 +103,7 @@
     "kb/verify-citation.mjs",
     "kb/retrieval-result.mjs",
     "kb/forge-update.mjs",
+    "kb/download-retry.mjs",
     "kb/corpus-release-identity.mjs",
     "kb/capability-only.mjs",
     "kb/capability-summaries/",

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

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

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

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