ruvnet-brain 4.4.0 → 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-instances.mjs

@@ -37,12 +37,60 @@ export function probeRuntimeSync(port, timeoutMs = 1500) {
 
 export const sameIdentity = (left, right) => IDENTITY_KEYS.every((key) => left?.[key] === right?.[key]);
 
+const MONTHS = 'JanFebMarAprMayJunJulAugSepOctNovDec';
+/** When process `pid` started (epoch ms, UTC, 1 s resolution), or null when it cannot be read. */
+let clockTicks = null;
 /**
- * Console receipts in `receiptDir`, with dead ones pruned. A receipt is dead only when BOTH hold:
- * its pid is not alive, and its port does not answer /api/runtime with the receipt's identity.
- * A receipt with no integer pid cannot be proven dead and is kept (counted as before).
+ * Linux: boot-relative start (/proc/<pid>/stat field 22, clock ticks since boot) anchored at the kernel's
+ * boot time (/proc/stat btime) — not `ps lstart`, which a forward wall-clock jump would push later.
  */
-export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = probeRuntimeSync } = {}) {
+export function linuxProcessStartMs(pid, { readFile = fs.readFileSync, spawn = spawnSync } = {}) {
+  try {
+    const stat = String(readFile(`/proc/${pid}/stat`, 'utf8'));
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' '); // field 3 onward (comm may hold spaces)
+    const startTicks = Number(fields[22 - 3]);
+    const btime = Number(String(readFile('/proc/stat', 'utf8')).match(/^btime\s+(\d+)/m)?.[1]);
+    if (clockTicks === null) clockTicks = Number(String(spawn('getconf', ['CLK_TCK'], { encoding: 'utf8' })?.stdout || '').trim()) || 100;
+    if (!Number.isFinite(startTicks) || !Number.isFinite(btime)) return null;
+    return btime * 1000 + Math.round((startTicks * 1000) / clockTicks);
+  } catch { return null; }
+}
+
+export function processStartMs(pid, { spawn = spawnSync, platform = process.platform, readFile } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (platform === 'linux') {
+    const linux = linuxProcessStartMs(pid, { spawn, ...(readFile ? { readFile } : {}) });
+    if (linux !== null) return linux;
+  }
+  const run = process.platform === 'win32'
+    ? spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      `$p=Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().ToString('ddd MMM d HH:mm:ss yyyy',[Globalization.CultureInfo]::InvariantCulture)`],
+    { encoding: 'utf8', windowsHide: true })
+    : spawn('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' } });
+  if (run?.status !== 0) return null;
+  const m = String(run.stdout || '').trim().match(/^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/);
+  if (!m || MONTHS.indexOf(m[1]) % 3 !== 0) return null;
+  return Date.UTC(+m[6], MONTHS.indexOf(m[1]) / 3, +m[2], +m[3], +m[4], +m[5]);
+}
+
+/**
+ * A live pid that is NOT the receipt's Console: the process now holding that pid started after the
+ * Console wrote its receipt (a Console's process always starts before it records startedAt). Two seconds
+ * of slack cover the 1 s resolution of the start time. Unreadable start time = not provably reused.
+ */
+export function pidReused(receipt, { startMs = processStartMs } = {}) {
+  const recorded = Date.parse(receipt?.startedAt || '');
+  const started = startMs(receipt?.pid);
+  return Number.isFinite(recorded) && Number.isFinite(started) && started > recorded + 2_000;
+}
+
+/**
+ * Console receipts in `receiptDir`, with dead ones pruned. A receipt is dead when its port does not
+ * answer /api/runtime with the receipt's identity AND either its pid is not alive or that pid now
+ * belongs to a process that started after the receipt was written (pid reuse). A busy live Console
+ * (pid alive, same process) is never pruned. A receipt with no integer pid cannot be proven dead.
+ */
+export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = probeRuntimeSync, startMs = processStartMs } = {}) {
   const live = [];
   const pruned = [];
   let names = [];
@@ -53,12 +101,17 @@ export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = prob
     let receipt;
     try { receipt = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
     if (receipt?.product !== PRODUCT || receipt.schema !== 1) continue;
-    if (Number.isInteger(receipt.pid) && receipt.pid > 0 && !alive(receipt.pid)) {
-      const answer = probe(receipt.port);
-      if (!answer || !sameIdentity(answer, receipt)) {
-        try { fs.unlinkSync(file); } catch { /* raced or read-only: still not a running Console */ }
-        pruned.push({ file, pid: receipt.pid, port: receipt.port ?? null, startedAt: receipt.startedAt ?? null });
-        continue;
+    if (Number.isInteger(receipt.pid) && receipt.pid > 0) {
+      const dead = !alive(receipt.pid);
+      const reused = !dead && pidReused(receipt, { startMs });
+      if (dead || reused) {
+        const answer = probe(receipt.port);
+        if (!answer || !sameIdentity(answer, receipt)) {
+          try { fs.unlinkSync(file); } catch { /* raced or read-only: still not a running Console */ }
+          pruned.push({ file, pid: receipt.pid, port: receipt.port ?? null, startedAt: receipt.startedAt ?? null,
+            reason: dead ? 'pid not alive' : 'pid reused by a process started after the receipt' });
+          continue;
+        }
       }
     }
     live.push({ file, receipt });
@@ -73,8 +126,13 @@ export function readConsoleReceipts(receiptDir, { alive = pidAlive, probe = prob
 // process plumbing. A denylist, so nothing the Console legitimately reads is silently lost.
 const CONSOLE_ENV_DENY = new Set(['RUVNET_NIGHTLY', 'RUVNET_BRAIN_TEST', 'RUVNET_BRAIN_TEST_LATEST_TAG', 'RUVNET_BRAIN_SCHEDULER_TEST',
   'RUVNET_BRAIN_IMPORT_ONLY', 'RUVNET_BRAIN_NO_UPDATE_FALLBACK', 'RUVNET_STRICT_INSTALL', 'RUVNET_REFRESH_RUN_TOKEN',
-  'RUVNET_REFRESH_RECEIPT', 'RUVNET_UPGRADE_NOTICE_FILE', 'NODE_OPTIONS', 'NODE_TEST_CONTEXT', 'INIT_CWD', 'CONSOLE_PORT']);
-const CONSOLE_ENV_DENY_PREFIX = /^(?:RUVNET_NIGHTLY_|npm_|VITEST)/;
+  'RUVNET_REFRESH_RECEIPT', 'RUVNET_UPGRADE_NOTICE_FILE', 'NODE_OPTIONS', 'NODE_TEST_CONTEXT', 'INIT_CWD', 'CONSOLE_PORT',
+  // The launching host session's own identity (the spine version it booted, the hook host, its Node).
+  'RUVNET_BRAIN_ACTIVE_VERSION', 'RUVNET_HOOK_HOST', 'RUVNET_NODE_BIN']);
+// CLAUDE* describes the Claude Code SESSION that ran the installer (CLAUDECODE, CLAUDE_PROJECT_DIR,
+// CLAUDE_PLUGIN_ROOT, CLAUDE_SESSION_ID, CLAUDE_CODE_*): stale for a long-lived Console. CLAUDE_CONFIG_DIR
+// is the user's configuration location, not session state, and is kept (host-update.mjs forwards it too).
+const CONSOLE_ENV_DENY_PREFIX = /^(?:RUVNET_NIGHTLY_|npm_|VITEST|CLAUDE(?!_CONFIG_DIR$))/;
 export function consoleEnv(env = process.env, port) {
   const clean = Object.fromEntries(Object.entries(env).filter(([key, value]) => value != null
     && !CONSOLE_ENV_DENY.has(key) && !CONSOLE_ENV_DENY_PREFIX.test(key)));

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',
 ]);