ruvnet-brain 4.4.1 → 4.5.0

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

@@ -26,14 +26,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { restoreProgressionForSession } from './project-progression-session-start.mjs';
+import { restoreWithBrief } from './continuity-brief.mjs';
 import {
   read, json, exists, mkdir, write, runNode,
 } from './session-start-fsutil.mjs';
 import { maintainerIssueEntitlement, surfaceIssuePointer } from './session-start-issue-alert.mjs';
 import { surfaceSignals } from './session-start-signals.mjs';
 import { brainState, health, knowledgeCurrency, mcpReadiness, KNOWLEDGE_LINE_PREFIX } from './session-start-health.mjs';
-import { stableSpine, heartbeat, knowledgeAutoUpdate } from './session-start-update-plane.mjs';
+import { stableSpine, heartbeat, knowledgeAutoUpdate, footprintCheck } from './session-start-update-plane.mjs';
+import { FOOTPRINT_LINE_PREFIX } from './brain-confirmation.mjs';
 import { describeLifecycleHooks, readHookContracts } from './session-start-hook-description.mjs';
 import { createStageTracer } from './session-start-trace.mjs';
 
@@ -59,13 +60,33 @@ const meter = ({ env, cwd, stateDir, output }) => {
   } catch { /* metering never blocks */ }
 };
 
+/**
+ * ground-ruvnet.sh sends each long block once per session and a one-line form after that (4.5). A
+ * SessionStart — startup, resume, clear, or compact — is exactly when the earlier full text may have
+ * left the model's context, so touching injected/.reset makes every block go out in full once more.
+ * No session id reaches this hook, so the reset is global: another window re-receives its blocks once,
+ * which errs toward delivering. Per-session marker dirs older than 3 days are pruned. Never throws.
+ */
+export function resetInjectionDedupe(stateDir, now = Date.now()) {
+  const base = path.join(stateDir, 'injected');
+  try {
+    fs.mkdirSync(base, { recursive: true });
+    fs.writeFileSync(path.join(base, '.reset'), `${new Date(now).toISOString()}\n`);
+    for (const name of fs.readdirSync(base)) {
+      if (name.startsWith('.')) continue;
+      const dir = path.join(base, name);
+      try { if (now - fs.statSync(dir).mtimeMs > 3 * 86_400_000) fs.rmSync(dir, { recursive: true, force: true }); } catch { /* raced */ }
+    }
+  } catch { /* an unwritable cache only costs dedupe, never the session */ }
+}
+
 export async function runSessionStart({
   env = process.env,
   cwd = process.cwd(),
   stdout = process.stdout,
   stderr = process.stderr,
   platform = process.platform,
-  restoreContinuity = restoreProgressionForSession,
+  restoreContinuity = restoreWithBrief,
   runHeartbeat = true,
 } = {}) {
   const lines = [];
@@ -80,6 +101,7 @@ export async function runSessionStart({
       || s.startsWith('[RuvNet Brain — INSTALL ALARM')
       || s.startsWith('[RuvNet Brain — NIGHTLY FAILED')
       || s.startsWith(KNOWLEDGE_LINE_PREFIX)
+      || s.startsWith(FOOTPRINT_LINE_PREFIX)
       || s.startsWith('[RuvNet Brain — OPEN ISSUES')
       || /\bopen issue\(s\)/i.test(s)
       || /^\[RuvNet Brain — external signal/i.test(s)
@@ -100,6 +122,7 @@ export async function runSessionStart({
       || s.startsWith('[ASCII→SVG]')
       || s.startsWith('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]')
       || s.startsWith('[RuvNet Brain — PROJECT CONTINUITY RESTORED]')
+      || s.startsWith('[RuvNet Brain — COME UP TO SPEED')
       || s.startsWith('[RuvNet Brain — MAINTAINER ONLY:');
   };
   // An alarm's HEADER line always matches isSafeStatus on its own dedicated prefix (above); its
@@ -132,9 +155,10 @@ export async function runSessionStart({
   };
   const home = env.HOME || env.USERPROFILE || os.homedir();
   const stateDir = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
+  resetInjectionDedupe(stateDir, Date.now());
   const hookDir = path.dirname(fileURLToPath(import.meta.url));
   const now = Date.now();
-  const consoleInvoke = env.RUVNET_HOOK_HOST === 'codex' ? '$ruvnet-brain:rvbc' : '/rvbc';
+  const consoleInvoke = env.RUVNET_HOOK_HOST === 'codex' ? '$ruvnet-brain:rnbc' : '/rnbc';
   const brain = brainState(env, home);
   const pluginRoot = env.CLAUDE_PLUGIN_ROOT || path.resolve(hookDir, '..');
   const manifest = json(path.join(pluginRoot, '.claude-plugin', 'plugin.json'), {});
@@ -218,6 +242,12 @@ export async function runSessionStart({
       const line = knowledgeCurrency({ env, home, now });
       if (line) emit(line);
     });
+    // ONE line only when the footprint is wrong (a second KB copy, cruft, a worker on another copy);
+    // a bounded detached sweep follows at most every 6h (ADR-0098). Silent on a clean machine.
+    tracer.stage('footprint', () => {
+      if (brain.off || state.problem) return;
+      footprintCheck({ env, home, now, hookDir, emit });
+    });
 
     tracer.stage('misc', () => {
       const consoleOffered = path.join(stateDir, '.console-offered');

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

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { json, exists, mtimeMs, read } from './session-start-fsutil.mjs';
+import { unmountedNotice } from './brain-location.mjs';
 import {
   describeFailedRefreshRun, readNightlyRegistration, refreshHistory, updateOwnedByAgenticKit,
 } from './nightly-scheduler.mjs';
@@ -33,9 +34,14 @@ export const brainState = (env, home) => {
 };
 
 export const health = (home, off) => {
+  // Moved to another disk that is not plugged in: say exactly that — not "MISSING, reinstall", which
+  // would re-create a fresh brain in ~/.cache over the link. A problem also stands the self-heal down.
+  const unmounted = unmountedNotice({ home });
+  if (unmounted) return { problem: unmounted, absentByChoice: false };
   const kb = path.join(home, '.cache', 'ruvnet-brain', 'kb');
   let rvf = false;
-  try { rvf = fs.readdirSync(kb).some((name) => name.endsWith('.rvf') && exists(path.join(kb, name))); }
+  // `._x.rvf` is macOS AppleDouble from an exFAT/FAT volume, not a store.
+  try { rvf = fs.readdirSync(kb).some((name) => name.endsWith('.rvf') && !name.startsWith('._') && exists(path.join(kb, name))); }
   catch { /* absent */ }
   const absentByChoice = off && (!exists(kb) || !rvf);
   if (absentByChoice) return { problem: '', absentByChoice };

package/plugin/scripts/session-start-update-plane.mjs

@@ -9,6 +9,8 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { read, write, exists, json, firstVersion, dispatchDetached, mtimeMs } from './session-start-fsutil.mjs';
 import { KNOWLEDGE_LINE_PREFIX, AUTO_UPDATE_LOCK_STALE_MS, autoUpdateOptOut, knowledgeFacts } from './session-start-health.mjs';
+import { inventoryFootprint } from './brain-footprint.mjs';
+import { confirm, footprintAlarm } from './brain-confirmation.mjs';
 
 /**
  * KNOWLEDGE SELF-HEAL (owner invariant 2026-09-30: no brain may ever be more than 48h old). The
@@ -77,6 +79,39 @@ export const knowledgeAutoUpdate = ({ env, home, now, hookDir, emit = () => {},
   return { launched: true, why: 'stale' };
 };
 
+/**
+ * FOOTPRINT (ADR-0098): a cheap, read-only classification (names and sizes of single files only, no
+ * hashing, no tree walks) on every session. Silent when the machine is clean. When it is not: ONE line,
+ * and — at most once per 6h, never in test mode, never while a refresh holds the lock — a detached
+ * `brain-footprint.mjs --sweep --apply` that removes only what the proof allows (private-unique copies are
+ * kept). Self-heal installs and updates enforce the same sweep inside bin/install.mjs.
+ */
+export const FOOTPRINT_SWEEP_HOURS = 6;
+export const footprintCheck = ({ env, home, now, hookDir, emit = () => {}, dispatch = dispatchDetached }) => {
+  const footprint = inventoryFootprint({ env, home, now, measure: false });
+  const line = footprintAlarm(confirm({ footprint, env, home, now }));
+  if (!line) return { clean: true, dispatched: false };
+  const stamp = path.join(footprint.roots.brainHome, '.footprint-sweep');
+  const removable = footprint.cruft.some((i) => ['remove', 'remove-if-proven', 'rotate', 'truncate'].includes(i.action));
+  // Nothing a sweep could remove (e.g. a copy kept for the private data it holds — review S7): say it ONCE,
+  // until the line changes, instead of at every session; and dispatch no sweep that could only keep it again.
+  if (!removable && !footprint.roots.dangling) { // an unplugged brain disk is told every session, and nothing is written beside it
+    const notice = path.join(footprint.roots.brainHome, '.footprint-kept-notice');
+    if (read(notice) === line) return { clean: false, dispatched: false, repeated: true };
+    write(notice, line);
+  }
+  const due = !(now - mtimeMs(stamp) < FOOTPRINT_SWEEP_HOURS * 3_600_000);
+  const testMode = env.RUVNET_BRAIN_TEST === '1' && String(env.RUVNET_FOOTPRINT_SWEEP || '').toLowerCase() !== 'on';
+  let dispatched = false;
+  if (removable && due && !testMode && !footprint.lockHeld) {
+    write(stamp, `${new Date(now).toISOString()}\n`);
+    dispatched = dispatch(hookDir, 600, path.join(footprint.roots.brainHome, '.last-footprint-sweep.log'),
+      process.execPath, [path.join(hookDir, 'brain-footprint.mjs'), '--sweep', '--apply', '--json'], env);
+  }
+  emit(dispatched ? line.replace(/\. Fix: /, ' — cleaning it up in the background now. Fix: ') : line);
+  return { clean: false, dispatched };
+};
+
 export const compareVersions = (a, b) => {
   const left = String(a).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
   const right = String(b).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));

package/plugin/scripts/turn-outcome-capture.mjs

@@ -43,6 +43,7 @@ import crypto from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
+import { userLevelAgentdbHooks } from './continuity-events.mjs';
 
 export const TURN_NAMESPACE = 'turns';
 export const MIN_OUTCOME_CHARS = 200;
@@ -201,7 +202,17 @@ export function captureTurnOutcome({
   const project = projectName(projectDir);
   const receipts = path.join(brainHome, 'turn-capture', 'receipts.jsonl');
 
-  if (event === 'Stop') {
+  // ONE WRITER PER TURN (ADR-100 §3). Measured 2026-10-01 on this repo's real store: 624 `turns` rows
+  // in five days for 323 distinct outcomes — this writer (host-tagged) and the owner's user-level
+  // ~/.claude/hooks/agentdb-turn-capture.mjs both recorded every Claude turn. The user-level hook is
+  // the owner's and is never edited by the product, so where it is registered the product DEFERS
+  // (RUVNET_TURN_CAPTURE=force keeps both). Codex turns are not seen by that Claude-only hook.
+  const deferTo = event === 'Stop' && host === 'claude' && String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() !== 'force'
+    && userLevelAgentdbHooks({ home }).turnCapture;
+  if (deferTo) {
+    report.skipped = 'deferred: the user-level ~/.claude/hooks/agentdb-turn-capture.mjs records this turn (one writer per turn)';
+    report.deferredToUserLevel = true;
+  } else if (event === 'Stop') {
     const sessionKey = String(payload.session_id || payload.transcript_path || '');
     const message = typeof payload.last_assistant_message === 'string' ? payload.last_assistant_message.trim() : '';
     let turn = { finalText: '', files: [], actions: [] };

package/plugin/scripts/unprompted-runtime.mjs

@@ -112,8 +112,8 @@ const SCRIPTS_DIR = path.dirname(SELF);                     // the payload's scr
 // The CC event name the shim forwarded. No event → nothing to run; stay silent.
 const EVENT = process.argv[2] || '';
 
-// Bound the whole runtime well under this hook's DECLARED timeout (hooks.json / codex-hooks.json:
-// 'unprompted-speech' is 3s, not the 5s this comment used to assume) — producers run sequentially and
+// Bound the whole runtime well under this hook's DECLARED timeout (hooks.json: 'unprompted-speech' is
+// 9s; codex-hooks.json: 10s host, 9000ms outer — it was 3s when this budget was first set) — producers run sequentially and
 // each has its own internal watchdog, but a backstop timeout here means a wedged producer can never
 // hang the turn. Found live 2026-09-27: the old 4000ms default left NO real margin under a 3000ms
 // declared timeout once Node startup + per-producer spawnSync overhead is counted, and slower

package/plugin/skills/brain-console/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: brain-console
-description: Open the RuvNet Brain Console for "/rvbc", "/rvcb", "/brain-console", or "/ruvnet-brain:configure". Use when the user asks to open, configure, inspect, or view the Brain Console. It opens the live local page in the background; the page is read-only until the user clicks a clearly explained, reversible action.
-updated: 2026-07-28
+description: Open the RuvNet Brain Console (RNBC) for "/rnbc", "/rnb", "/rvbc", "/rvcb", "/brain-console", or "/ruvnet-brain:configure". Use when the user asks to open, configure, inspect, or view the Brain Console. It opens the live local page in the background; the page is read-only until the user clicks a clearly explained, reversible action.
+updated: 2026-10-01
 ---
 
 # Brain Console
 
-Treat `/rvbc`, `/rvcb`, `/brain-console`, and `/ruvnet-brain:configure` as equally valid names.
+Treat `/rnbc` (the name), `/rnb`, `/rvbc`, `/rvcb`, `/brain-console`, and `/ruvnet-brain:configure` as equally valid names.
 Never correct the user's spelling.
 
 1. Say one short sentence: "Opening it now; it scans live while you watch."

package/plugin/skills/rnbc/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: rnbc
+description: Open the RNBC — RuvNet Brain Console — in Claude Code and Codex when the user says "rnbc", "rnb", "Configure RuvNet Brain", asks for the Brain Console, or wants to configure or inspect RuvNet Brain. Claude Code supports /rnbc (and /rnb, /rvbc); Codex invokes the native $ruvnet-brain:rnbc skill.
+updated: 2026-10-01
+---
+
+# RNBC — RuvNet Brain Console
+
+RuvNet Brain abbreviates as RNB, so its console is the RNBC. Claude Code opens it with `/rnbc`
+(also `/rnb`, `/rvbc`, `/rvcb`, `/brain-console`, `/ruvnet-brain:configure`); Codex invokes this
+skill as `$ruvnet-brain:rnbc` because custom plugin slash commands are not part of the Codex CLI
+slash-command surface. Never correct the user's spelling.
+
+1. Say one short sentence: "Opening it now; it scans live while you watch."
+2. Resolve the installed runtime at
+   `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository `scripts/onboarding-console.mjs` is allowed only for an explicit developer
+   checkout. Never fall back to a guessed `~/Code` path.
+3. Run `node <resolved-script> --serve --open` in the background.
+4. Give the URL immediately. Do not promise a duration; the page reports its own scan progress.
+
+An already-running server is success. The Console is read-only until the user chooses an action;
+every change must be explained and reversible. If the script cannot be located or the server fails,
+report the exact failure plainly instead of claiming the Console opened.

package/plugin/skills/rvbc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rvbc
-description: Open the RuvNet Brain Console in Claude Code and Codex when the user says "Configure RuvNet Brain", mentions "rvbc", asks for the Brain Console, or wants to configure or inspect RuvNet Brain. Claude Code supports /rvbc; Codex invokes the native $ruvnet-brain:rvbc skill.
-updated: 2026-07-30
+description: Open the RuvNet Brain Console in Claude Code and Codex when the user says "Configure RuvNet Brain", mentions "rvbc" or "rnbc", asks for the Brain Console, or wants to configure or inspect RuvNet Brain. Claude Code supports /rnbc and /rvbc; Codex invokes the native $ruvnet-brain:rvbc skill (or $ruvnet-brain:rnbc).
+updated: 2026-10-01
 ---
 
 # RuvNet Brain Console

package/scripts/approved-runtime.mjs

@@ -14,7 +14,7 @@
 // "Pinning survives only through enforced equality to the approved shipped runtime and its
 // executable hashes. Copying current-main package.json or preserving a version string alone is
 // insufficient." So this compares every executable/runtime file's sha256 AND byte length against a
-// inventory produced from the owner-approved shipped code artifact — and, in the other
+// inventory produced from the install-verified shipped code artifact — and, in the other
 // direction, refuses any executable-shaped file in the archive that the inventory does not cover, so
 // a NEW unpinned executable cannot ride along.
 //
@@ -405,7 +405,7 @@ async function main() {
   catch (error) { console.error(`[approved-runtime] ${error.message}`); return 1; }
   const result = verifyApprovedRuntime({ manifest, pin });
   if (result.verdict !== 'PASS') {
-    console.error('[approved-runtime] FAIL: archive runtime is not the owner-approved shipped code artifact');
+    console.error('[approved-runtime] FAIL: archive runtime is not the install-verified shipped code artifact');
     for (const failure of result.failures) console.error(`  - ${failure}`);
     return 1;
   }

package/scripts/ci/warm-brain-models.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// scripts/ci/warm-brain-models.mjs — download every embedder the Brain at $RUVNET_BRAIN_KB requires into
+// $KB_MODEL_CACHE, resolving @xenova/transformers from that Brain's own node_modules (the reader that
+// will run). Used by ci.yml's warm-brain job (seed corpus) and release-qe's capability battery (the
+// exact assembled candidate), so both warm the cache the same way.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { requiredEmbedderModels } from '../../plugin/test/model-cache.mjs';
+
+async function main() {
+  const modelCache = process.env.KB_MODEL_CACHE;
+  const kb = process.env.RUVNET_BRAIN_KB;
+  if (!modelCache || !kb) throw new Error('RUVNET_BRAIN_KB and KB_MODEL_CACHE are required');
+  fs.mkdirSync(modelCache, { recursive: true });
+  const requireFromKb = createRequire(path.join(kb, 'package.json'));
+  const T = await import(pathToFileURL(requireFromKb.resolve('@xenova/transformers')).href);
+  T.env.localModelPath = modelCache;
+  T.env.cacheDir = modelCache;
+  T.env.allowRemoteModels = true;
+  for (const model of requiredEmbedderModels(kb)) {
+    await T.pipeline('feature-extraction', model, { quantized: true });
+    console.log(`[warm-brain-models] ${model}`);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/codex-hook-trust.mjs

@@ -0,0 +1,94 @@
+// codex-hook-trust.mjs — which Brain hooks will Codex refuse to run after this update until the user
+// re-reviews them? Answered OFFLINE, from the two hooks files, with Codex's own trust identity.
+//
+// THE MECHANISM (source, not inference — openai/codex at tag rust-v0.159.3, the installed codex-cli):
+//   codex-rs/hooks/src/engine/discovery.rs
+//     · key  = hook_key("<plugin_id>:<relative hooks file>", event, group_index, handler_index)
+//              e.g. "ruvnet-brain@ruvnet-brain:hooks/codex-hooks.json:user_prompt_submit:0:1"
+//     · hash = hook_hash(): sha256 over the canonical JSON of the NORMALISED identity
+//              { event_name, matcher (tool/session events only), hooks: [normalised handler] } —
+//              command, timeout (normalised), async, statusMessage; "so equivalent hooks from config
+//              TOML and hooks.json converge on the same trust identity".
+//     · hook_trust_status(): trusted_hash == current hash -> Trusted; a different stored hash ->
+//              Modified; none -> Untrusted. Only Managed|Trusted handlers are pushed to run (unless
+//              bypass_hook_trust). So a release that edits a command's text, its timeout or its
+//              matcher, or that shifts a hook to another group/handler index, silently stops that
+//              hook on every machine until the user trusts it again.
+//   codex-rs/config/src/fingerprint.rs version_for_toml(): "sha256:" + hex(sha256(serde_json::to_vec(
+//              canonical_json(value)))) — keys sorted recursively, compact.
+//   codex-rs/tui/src/startup_hooks_review.rs: the interactive prompt "Hooks need review" offers
+//              "Review hooks" / "Trust all and continue" / "Continue without trusting (hooks won't run)".
+// MEASURED 2026-10-01 in an isolated CODEX_HOME (codex-cli 0.159.3, no credentials): fresh install ->
+// all 11 Brain hooks `untrusted`; trusted_hash written -> `trusted`; one command's text changed ->
+// that one hook `modified`, the other ten still `trusted`. currentHash from `hooks/list` equals
+// codexHookHash() below for every hook (tests/unit/codex-hook-trust.test.mjs pins the real values).
+import crypto from 'node:crypto';
+
+const EVENT_LABEL = Object.freeze({
+  PreToolUse: 'pre_tool_use', PermissionRequest: 'permission_request', PostToolUse: 'post_tool_use',
+  PreCompact: 'pre_compact', PostCompact: 'post_compact', SessionStart: 'session_start', SessionEnd: 'session_end',
+  UserPromptSubmit: 'user_prompt_submit', SubagentStart: 'subagent_start', SubagentStop: 'subagent_stop',
+  Stop: 'stop', Interrupt: 'interrupt',
+});
+const NO_MATCHER = new Set(['UserPromptSubmit', 'Stop', 'Interrupt']);
+const CONTEXT_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart', 'UserPromptSubmit', 'SubagentStart']);
+const DEFAULT_CONTEXT_LIMIT = 2500;
+
+function canonical(v) {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v && typeof v === 'object') return Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])]));
+  return v;
+}
+
+/** discovery.rs normalize_command_hook(): SessionEnd/Interrupt default 1s, clamped 1..3; others default 600, min 1. */
+function normalisedTimeout(event, t) {
+  const n = Number.isInteger(t) && t >= 0 ? t : null;
+  if (event === 'SessionEnd' || event === 'Interrupt') return Math.min(3, Math.max(1, n ?? 1));
+  return Math.max(1, n ?? 600);
+}
+
+/** The exact `currentHash` Codex computes for one command handler, or null for a handler Codex would skip. */
+export function codexHookHash(event, group, handler) {
+  if (!EVENT_LABEL[event] || handler?.type !== 'command' || typeof handler.command !== 'string' || !handler.command.trim()) return null;
+  const h = { type: 'command', command: handler.command, timeout: normalisedTimeout(event, handler.timeout), async: handler.async === true };
+  if (typeof handler.statusMessage === 'string') h.statusMessage = handler.statusMessage;
+  const limit = handler.additionalContextLimit;
+  if (CONTEXT_EVENTS.has(event) && Number.isInteger(limit) && limit !== DEFAULT_CONTEXT_LIMIT) h.additionalContextLimit = limit;
+  const identity = { event_name: EVENT_LABEL[event], hooks: [h] };
+  if (!NO_MATCHER.has(event) && typeof group?.matcher === 'string') identity.matcher = group.matcher;
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(canonical(identity))).digest('hex')}`;
+}
+
+/** key -> hash for every handler in a Codex hooks file ({ hooks: { Event: [groups] } }). */
+export function codexHookIdentities(hooksFile, keySource = 'ruvnet-brain@ruvnet-brain:hooks/codex-hooks.json') {
+  const out = new Map();
+  for (const [event, groups] of Object.entries(hooksFile?.hooks || {})) {
+    if (!EVENT_LABEL[event] || !Array.isArray(groups)) continue;
+    groups.forEach((group, gi) => (group?.hooks || []).forEach((handler, hi) => {
+      const hash = codexHookHash(event, group, handler);
+      if (hash) out.set(`${keySource}:${EVENT_LABEL[event]}:${gi}:${hi}`, hash);
+    }));
+  }
+  return out;
+}
+
+/**
+ * The Brain hooks an update leaves needing review: every key of the NEW file whose hash differs from the
+ * OLD file's hash at the same key ('modified') or that did not exist before ('untrusted'). A hook the user
+ * had already trusted at the old hash stops running until reviewed; that is the whole point of the list.
+ */
+export function codexTrustChanges(prevHooksFile, nextHooksFile, keySource) {
+  const prev = codexHookIdentities(prevHooksFile, keySource);
+  const next = codexHookIdentities(nextHooksFile, keySource);
+  const changes = [];
+  for (const [key, hash] of next) {
+    if (!prev.has(key)) changes.push({ key, status: 'untrusted' });
+    else if (prev.get(key) !== hash) changes.push({ key, status: 'modified' });
+  }
+  return changes;
+}
+
+/** The exact instruction for a user whose Brain hooks Codex is holding back. */
+export const CODEX_TRUST_ACTION = 'Start Codex (interactive, in any project). At the "Hooks need review" prompt choose'
+  + ' "Trust all and continue" — or type /hooks and trust each RuvNet Brain hook. Until then Codex skips them'
+  + ' (codex exec never asks). Then re-run npx ruvnet-brain --doctor.';

package/scripts/console-runtime-identity.mjs

@@ -51,6 +51,11 @@ export const CONSOLE_RUNTIME_SURFACE = Object.freeze([
   // ERR_MODULE_NOT_FOUND on import, before a single line runs.
   'kb/corpus-release-identity.mjs',
   'bin/install.mjs',
+  // The Console's Settings → Nightly switch runs the copied installer's --enable-nightly, which installs
+  // THIS file (beside it, REPO_ROOT/bin) as the scheduler's immutable runner. Without it every installed
+  // customer got "nightly runner source is missing" (RNBC review 2026-10-01). It imports only node:
+  // built-ins, so nothing further travels with it.
+  'bin/nightly-refresh.mjs',
   'package.json',
 ]);
 

package/scripts/corpus-canary.mjs

@@ -35,7 +35,7 @@
 // `codex` host is wired — this is the knowledge channel, not the host matrix.
 //
 //   node scripts/corpus-canary.mjs --repo owner/name --tag corpus-sha256-<64hex> --approved-version X.Y.Z
-//        --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>]
+//        --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--footprint-updates]
 //   exit 0 = PASS, 1 = FAIL (verdict written either way), 2 = usage.
 
 import crypto from 'node:crypto';
@@ -45,6 +45,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { addPrivateStore, resolveRuntime, resultFromRefreshReceipt, runInstallerDoor } from './customer-seams.mjs';
 import { CANARY_VERDICT_KIND, CORPUS_TAG_PATTERN, REQUIRED_CANARY_CHECKS } from './corpus-promotion.mjs';
+import { inventoryFootprint } from '../plugin/scripts/brain-footprint.mjs';
 
 export const PUBLIC_API = 'https://api.github.com';
 export const FRESHNESS_LIMIT_MS = 48 * 3_600_000;
@@ -331,8 +332,30 @@ async function fetchReleaseList({ apiBase, repo }) {
   return response.json();
 }
 
+/** The footprint of a customer HOME after one update (plugin/scripts/brain-footprint.mjs, never restated). */
+export function footprintSnapshot({ home, kbDir }) {
+  const fp = inventoryFootprint({ env: { HOME: home, RUVNET_BRAIN_KB: kbDir, RUVNET_BRAIN_HOME: path.dirname(kbDir) }, home });
+  const receipts = fp.breakdown.receipts || 0;
+  return { kbCopies: fp.kbCopies, netBytes: fp.totalBytes - receipts, receipts, budgetBytes: fp.budgetBytes,
+    withinBudget: fp.withinBudget, copies: fp.cruft.filter((i) => /kb-copy|quarantine|install-/.test(i.kind)).map((i) => i.path) };
+}
+
+/** Three updates, one KB: exactly one copy after each, nothing that must not exist, no net growth. */
+export function judgeFootprintStability(inventories, { growthAllowanceBytes = 1024 * 1024 } = {}) {
+  const problems = [];
+  inventories.forEach((inv, index) => {
+    if (inv.exitCode !== undefined && inv.exitCode !== 0) problems.push(`update ${index + 1} exited ${inv.exitCode}`);
+    if (inv.kbCopies !== 1) problems.push(`update ${index + 1}: ${inv.kbCopies} KB copies (${inv.copies.join(', ')})`);
+    if (!inv.withinBudget) problems.push(`update ${index + 1}: over the footprint budget`);
+  });
+  const growth = inventories.at(-1).netBytes - inventories[0].netBytes;
+  if (growth > growthAllowanceBytes) problems.push(`grew ${growth} bytes across ${inventories.length} updates (receipts excluded)`);
+  return problems.length ? { ok: false, detail: problems.join('; ') }
+    : { ok: true, detail: `${inventories.length} updates: 1 KB copy each time, within budget, net growth ${growth} bytes` };
+}
+
 async function runCase({ name, spec, repo, tag, approvedVersion, release, work, home, apiBase, install, now,
-  retryDelayMs, maxAttempts, log, writerRoot, approvedInstaller }) {
+  retryDelayMs, maxAttempts, log, writerRoot, approvedInstaller, footprintUpdates = false }) {
   fs.mkdirSync(home, { recursive: true });
   let runtime = approvedVersion;
   if (spec.runtime !== 'approved') runtime = resolveRuntime(spec.runtime, { candidateTag: `v${approvedVersion}`, releases: await fetchReleaseList({ apiBase, repo }) });
@@ -362,6 +385,22 @@ async function runCase({ name, spec, repo, tag, approvedVersion, release, work,
     : (fs.existsSync(resultFile) ? readJson(resultFile) : null);
   const judged = await judgeCanary({ tag, approvedVersion, release, updater, before, beforeModules, beforeCoverage,
     kbDir: fs.realpathSync(kbDir), home: fs.realpathSync(home), now: now() });
+  // ADR-0098 footprint check, OPT-IN (--footprint-updates): two more updates of the same customer through
+  // the same door, each followed by the footprint inventory. Off by default because its CI runtime on the
+  // real ~1.4 GB brain (two more full-tree validations) has not been measured yet; the offline fixture
+  // run is in tests/unit/corpus-canary.test.mjs.
+  if (footprintUpdates && name === 'clean' && updater.exitCode === 0) {
+    const inventories = [footprintSnapshot({ home: fs.realpathSync(home), kbDir })];
+    for (let extra = 0; extra < 2; extra += 1) {
+      fs.rmSync(resultFile, { force: true });
+      const again = spec.door === 'installer'
+        ? await runInstallerDoor({ installer: await approvedInstaller(), env: childEnv, cwd: home })
+        : await runUpdater({ kbDir, env: childEnv, resultFile });
+      log(`--- [${name}] footprint update ${extra + 2} exit ${again.exitCode}\n${again.output}`);
+      inventories.push({ ...footprintSnapshot({ home: fs.realpathSync(home), kbDir }), exitCode: again.exitCode });
+    }
+    judged.checks.push({ name: 'footprint-three-updates', ...judgeFootprintStability(inventories) });
+  }
   if (overlay) {
     const after = Object.fromEntries(Object.keys(overlay.digests).map((f) => [f,
       fs.existsSync(path.join(kbDir, f)) ? sha256File(path.join(kbDir, f)) : null]));
@@ -403,7 +442,7 @@ export async function runCanary({
   repo, tag, approvedVersion, work, apiBase = PUBLIC_API, install = installCustomer, home = path.join(work, 'home'),
   env = process.env, now = () => Date.now(), retryDelayMs = 30_000, maxAttempts = 3, log = () => {},
   cases = ['clean'], writerRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
-  approvedInstaller = null,
+  approvedInstaller = null, footprintUpdates = false,
 }) {
   if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('--repo must be owner/name');
   if (!CORPUS_TAG_PATTERN.test(String(tag || ''))) throw new Error('--tag must be corpus-sha256-<64 hex>');
@@ -426,7 +465,7 @@ export async function runCanary({
     return installerPath;
   });
   const common = { repo, tag, approvedVersion, release, apiBase, install, now, retryDelayMs, maxAttempts, log, writerRoot,
-    approvedInstaller: resolveInstaller };
+    approvedInstaller: resolveInstaller, footprintUpdates };
   let cleanKb = null;
   const clean = await runCase({ ...common, name: 'clean', spec: CANARY_CASES.clean, work, home,
     install: async (args) => { const installed = await install(args); cleanKb = physical(installed.kbDir); return installed; } });
@@ -476,7 +515,7 @@ async function main(argv = process.argv.slice(2)) {
   const work = opt('--work') && path.resolve(opt('--work'));
   const verdictOut = opt('--verdict-out') && path.resolve(opt('--verdict-out'));
   if (!work || !verdictOut) {
-    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--cases clean,private-overlay,older-runtime]\n');
+    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--cases clean,private-overlay,older-runtime] [--footprint-updates]\n');
     return 2;
   }
   fs.mkdirSync(work, { recursive: true });
@@ -488,7 +527,8 @@ async function main(argv = process.argv.slice(2)) {
   let record;
   try {
     record = await runCanary({ repo: opt('--repo'), tag: opt('--tag'), approvedVersion: opt('--approved-version'), work,
-      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log, cases });
+      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log, cases,
+      footprintUpdates: argv.includes('--footprint-updates') });
   } catch (error) {
     // Could not even reach a judgement = the consumer did not accept. Still a written verdict.
     record = { schemaVersion: 1, kind: CANARY_VERDICT_KIND, verdict: 'FAIL', repo: opt('--repo') || null, tag: opt('--tag') || null,

package/scripts/corpus-dispatch-decision.mjs

@@ -48,8 +48,8 @@ export function killSwitchOff(nightlyVar) {
 }
 
 /**
- * @param nightlyVar   repository variable CORPUS_NIGHTLY (armed unless it reads `off`, any case; the owner's
- *                     approval of the code release is the consent)
+ * @param nightlyVar   repository variable CORPUS_NIGHTLY (armed unless it reads `off`, any case; the newest
+ *                     install-verified code release is the consent — no person approves it)
  * @param resolution   { status: 'resolved', release: {tag, version, sourceSha} }
  *                   | { status: 'not-yet-verified' } | { status: 'invalid', reason }
  */

package/scripts/corpus-promotion.mjs

@@ -33,7 +33,7 @@ export function evaluateCorpusPromotion({ tag, generation, currentLatest } = {})
   if (!CORPUS_TAG_PATTERN.test(String(currentLatest.tagName || ''))) {
     // A code release holds latest. Corpus promotion does not regress the runtime, because
     // scripts/approved-runtime.mjs has already proved this archive's executables ARE the
-    // owner-approved shipped runtime, byte for byte.
+    // install-verified shipped runtime, byte for byte.
     return {
       allowed: true,
       reason: `current latest ${currentLatest.tagName} is a code release; runtime equality is enforced by the approved runtime pin`,

package/scripts/hook-qualify-hosts.mjs

@@ -58,7 +58,15 @@ export function scanCodex({ stdout, stderr }) {
   for (const l of lines(stderr)) if (/hook/i.test(l)) f.push(`stderr: ${l.slice(0, 200)}`);
   return { findings: [...new Set(f)], unrelatedStderr: lines(stderr).filter((l) => !/hook/i.test(l)).slice(0, 3) };
 }
-/** Pure: scan a real `grok -p --debug-file` run. */
+/**
+ * Pure: scan a real `grok -p --debug-file` run.
+ *
+ * MEASURED 2026-10-01 (grok 1.0.13, docs/research/grok-hooks-2026-10-01.md): `grok -p` discovers the Brain
+ * from Claude Code's plugin cache ("plugin discovered name=ruvnet-brain … has_hooks=true") and attaches its
+ * MCP server, but the session's "loaded hooks hook_count=8" was exactly the 4 hooks in ~/.claude/settings.json
+ * plus the 4 in ~/.grok/hooks/ — no plugin's hooks at all — and no Brain hook ever completed. A discovered
+ * plugin whose hooks never dispatch is therefore a FINDING here, never a silent pass.
+ */
 export function scanGrok({ stdout, stderr, debug = '' }) {
   const f = []; let loaded = null; const pluginHooks = /plugin discovered name=ruvnet-brain .*has_hooks=true/.test(debug);
   for (const l of lines(debug)) {
@@ -68,7 +76,11 @@ export function scanGrok({ stdout, stderr, debug = '' }) {
   }
   if (stderr.trim()) f.push(`process stderr: ${JSON.stringify(stderr.trim().slice(0, 300))}`);
   if (/hook/i.test(stdout) && /(error|failed)/i.test(stdout.match(/.{0,80}hook.{0,120}/i)?.[0] || '')) f.push('hook error text in the output stream');
-  return { findings: [...new Set(f)], hooksLoaded: loaded, pluginHasHooks: pluginHooks, pluginHooksRan: /hook_name=plugin|hook_name=ruvnet/.test(debug) };
+  const brainHooksRan = /hook completed hook_name=\S*ruvnet/.test(debug);
+  if (pluginHooks && !brainHooksRan) {
+    f.push(`Brain plugin hooks discovered but never ran (session loaded ${loaded ?? '?'} hooks): grok -p loads only global hooks — see docs/research/grok-hooks-2026-10-01.md`);
+  }
+  return { findings: [...new Set(f)], hooksLoaded: loaded, pluginHasHooks: pluginHooks, pluginHooksRan: brainHooksRan };
 }
 
 async function runClaude(root, dbgDir) {
@@ -98,7 +110,7 @@ async function runGrok(root, dbgDir) {
   const debug = fs.existsSync(debugFile) ? fs.readFileSync(debugFile, 'utf8') : '';
   const s = scanGrok({ stdout: r.stdout || '', stderr: r.stderr || '', debug });
   fs.rmSync(dir, { recursive: true, force: true });
-  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'throwaway cwd is untrusted by Grok, so project/plugin hook loading there is part of what is measured' };
+  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'real HOME: the Brain is discovered from Claude Code\'s plugin cache; whether its hooks actually RUN in grok -p is what is measured (they did not on grok 1.0.13)' };
 }
 
 export async function layer2(hosts, { maxLoad = 40, waitMs = 15 * 60_000, log = () => {}, root = REPO } = {}) {