ruvnet-brain 4.5.6 → 4.5.8

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.6 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.6-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.8 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.8-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

@@ -79,6 +79,7 @@ import {
 } from '../scripts/console-runtime-identity.mjs';
 import { shellDiff as pluginShellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
 import { codexTrustChanges, CODEX_TRUST_ACTION } from '../scripts/codex-hook-trust.mjs';
+import { probeFreshCodexDeclarations } from '../scripts/codex-fresh-host-proof.mjs';
 import { repairSecurityGuidance } from '../scripts/security-guidance-codex-compat.mjs';
 import { installNativeLaunchers, installRoutingRuntime } from '../scripts/model-routing-launchers.mjs';
 import { installTerminalLaunchers } from '../scripts/model-terminal-launchers.mjs';
@@ -3045,6 +3046,21 @@ async function doctorRun({ json }) {
       const recorded = withLiveConsoleState(JSON.parse(fs.readFileSync(convergencePath, 'utf8')),
         { receiptDir: path.join(path.dirname(convergencePath), 'console-instances') });
       hostConvergence = classifyHostConvergence(recorded);
+      const codex = recorded.hosts?.codex;
+      if (codex?.state === 'ready' && codex.restartRequired === true && codex.restartScope === 'unproven') {
+        let binary = process.env.CODEX_BIN || 'codex';
+        if (!process.env.CODEX_BIN) {
+          try {
+            const configured = JSON.parse(fs.readFileSync(path.join(path.dirname(convergencePath), 'model-routing', 'terminal-launcher-config.json'), 'utf8'));
+            if (typeof configured.realCodex === 'string' && path.isAbsolute(configured.realCodex)) binary = configured.realCodex;
+          } catch { /* native PATH resolution remains bounded and fail closed */ }
+        }
+        const fresh = await probeFreshCodexDeclarations({ binary, codexHome: codexHomeDir(), cwd: process.cwd(),
+          releasedPluginRoot: path.join(REPO_ROOT, 'plugin'), expectedVersion: PACKAGE_VERSION });
+        hostConvergence = reconcileFreshCodexDeclarations(recorded, fresh);
+        if (fresh.ok) info('Codex fresh-declarations-ready: current trusted hook declarations only; hook bodies and MCP execution were not tested. Existing open windows remain unproven.');
+        else warn(`Codex fresh declarations remain unproven: ${fresh.reason}`);
+      }
       if (hostConvergence.healthy) {
         ok(`host convergence receipt: ${hostConvergence.state}`);
         if (hostConvergence.notice) info(hostConvergence.notice);
@@ -3922,6 +3938,36 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
   return { healthy: true, state: 'channels-converged' };
 }
 
+/** Activation and host readiness are independent; never claim a rollback from a host refusal. */
+export function hostSynchronizationFailureMessage(convergence, active, expectedVersion = PACKAGE_VERSION) {
+  const verified = active?.version === expectedVersion && Number.isSafeInteger(active.generation) && active.generation > 0
+    && active.codeRoot === `versions/${expectedVersion}`;
+  const state = verified ? `runtime ${expectedVersion} generation ${active.generation} is active`
+    : 'the active runtime generation could not be verified';
+  return `host synchronization is incomplete — ${state}${convergence?.error ? ` (${convergence.error})` : ''}`;
+}
+
+/** Doctor projection only. Fresh hook metadata cannot clear an executable or MCP boot gap. */
+export function reconcileFreshCodexDeclarations(recorded, proof, expectedVersion = PACKAGE_VERSION) {
+  const original = classifyHostConvergence(recorded, expectedVersion);
+  const codex = recorded?.hosts?.codex;
+  if (!proof?.ok || proof.state !== 'fresh-declarations-ready' || proof.expectedVersion !== expectedVersion
+    || recorded?.desiredVersion !== expectedVersion || codex?.version !== expectedVersion
+    || codex.state !== 'ready' || codex.restartRequired !== true || codex.restartScope !== 'unproven') return original;
+  // Older receipts carry the paths only in this machine-generated reason. An unknown reason,
+  // body file, skill/command surface, or MCP declaration retains the historical restart refusal.
+  const prefix = 'boot-level declarations changed: ';
+  const reason = codex.sessionSafetyReason;
+  const changed = typeof reason === 'string' && reason.startsWith(prefix) ? reason.slice(prefix.length).split(', ') : [];
+  if (!changed.length || changed.some((file) => !['hooks/codex-hooks.json', 'hooks/hooks.json'].includes(file))) {
+    return { ...original, freshDeclarations: proof, notice: 'Fresh Codex hook declarations are ready; executable/MCP boot readiness and existing open windows remain unproven.' };
+  }
+  const projected = classifyHostConvergence({ ...recorded, hosts: { ...recorded.hosts,
+    codex: { ...codex, restartScope: 'open-sessions' } } }, expectedVersion);
+  return { ...projected, ...(projected.healthy ? { state: 'fresh-declarations-ready' } : {}), freshDeclarations: proof,
+    notice: 'Fresh Codex hook declarations are ready; hook bodies and MCP execution were not tested. Existing open windows remain unproven.' };
+}
+
 const HOST_LABELS = { claude: 'Claude Code', codex: 'Codex' };
 /** The one accurate line for converged hosts whose already-open windows booted the old declarations. */
 export function openSessionsNotice(hosts, version) {
@@ -4233,7 +4279,9 @@ async function runUpdate() {
     info(c.dim('\nsynchronizing every detected host to this exact published version…\n'));
     const convergence = syncHostsAfterUpdate(kbDir);
     if (!convergence.ok) {
-      warn(`host synchronization is incomplete — runtime stays on the prior verified generation${convergence.error ? ` (${convergence.error})` : ''}`);
+      let active;
+      try { active = JSON.parse(fs.readFileSync(path.join(footprintRoots().brainHome, 'active.json'), 'utf8')); } catch { /* report unknown activation */ }
+      warn(hostSynchronizationFailureMessage(convergence, active));
       updateStatus = 1;
     } else if (convergence.convergence?.notice) info(convergence.convergence.notice);
     try { reportLegacyRufloDebris(); } catch (error) { warn(`legacy ruflo debris cleanup failed: ${error.message}`); }
@@ -4953,6 +5001,7 @@ export function syncManagedRouterTools({ routerDir = path.join(os.homedir(), '.c
   }
   // Preserve package-relative imports without replacing user policy.mjs overrides.
   for (const runtimeRelative of [path.join('plugin', 'scripts', 'runtime-preferences.mjs'),
+    path.join('plugin', 'scripts', 'project-identity.mjs'),
     path.join('config', 'model-router', 'policy.default.mjs')]) {
   const runtimeTarget = path.join(routerDir, runtimeRelative);
   const runtimeBytes = fs.readFileSync(path.join(packageRoot, runtimeRelative));

package/kb/forge-update.mjs

@@ -1405,6 +1405,35 @@ export function bundleIdentity(src) {
   return parts.some(Boolean) ? parts.join('|') : null;
 }
 
+const downloadedArchiveVerifiers = new WeakSet();
+
+function archiveVerifierFromDigests(actualDigests, bytes) {
+  const verifier = Object.freeze({
+    bytes,
+    digest(algorithm = 'sha256') {
+      if (!Object.hasOwn(actualDigests, algorithm)) throw new Error(`archive algorithm ${algorithm} was not captured`);
+      return actualDigests[algorithm];
+    },
+  });
+  downloadedArchiveVerifiers.add(verifier);
+  return verifier;
+}
+
+// Capture the closed transaction algorithm inventory synchronously. Never retain mutable bytes:
+// the capability attests only to this creation-time snapshot, not a later caller-owned Buffer.
+export function createDownloadedArchiveVerifier(downloadedBuffer, expectedDigests = []) {
+  if (!Buffer.isBuffer(downloadedBuffer) || !Array.isArray(expectedDigests)) throw new TypeError('archive bytes and digest inventory required');
+  const algorithms = new Set(['sha256']);
+  for (const expected of expectedDigests) {
+    if (expected == null) continue;
+    if (typeof expected !== 'string' || !expected) throw new TypeError('invalid archive digest');
+    algorithms.add(expected.includes(':') ? expected.split(':')[0] : 'sha256');
+  }
+  const actualDigests = Object.freeze(Object.fromEntries([...algorithms].map(algorithm =>
+    [algorithm, createHash(algorithm).update(downloadedBuffer).digest('hex')])));
+  return archiveVerifierFromDigests(actualDigests, downloadedBuffer.length);
+}
+
 /**
  * Confirm the download+extraction actually changed what is on disk (issue #35 item 2, Dr. Mark
  * Allen / @mamd69).
@@ -1448,8 +1477,11 @@ export function bundleIdentity(src) {
  * @returns {{ok: boolean, reason: string|null, landed: object|null, kind: 'noop'|'damaged'|null,
  *            storeUnchanged: boolean, bundleChanged: boolean|null}}
  */
-export function verifyLanded({ kbDir, kbName, before, beforeBundle = null, expectedDigest = null, downloadedBuffer = null }) {
+export function verifyLanded({ kbDir, kbName, before, beforeBundle = null, expectedDigest = null, downloadedBuffer = null, archiveVerifier = null }) {
   const damaged = (reason, landed = null) => ({ ok: false, kind: 'damaged', reason, landed, storeUnchanged: false, bundleChanged: null });
+  if (archiveVerifier !== null && (!downloadedArchiveVerifiers.has(archiveVerifier) || downloadedBuffer !== null)) {
+    return damaged('archive verification capability is invalid or mixed with mutable archive bytes');
+  }
   const p = path.join(kbDir, 'SOURCE.json');
   if (!fs.existsSync(p)) {
     return damaged(`no SOURCE.json found at ${p} after extraction — cannot confirm what actually landed`);
@@ -1487,9 +1519,11 @@ export function verifyLanded({ kbDir, kbName, before, beforeBundle = null, expec
 
   // Bytes that do not match what the release declared are a HARD failure whatever the identities
   // say, and the copy now in place is suspect — so this is checked before anything else.
-  if (expectedDigest && downloadedBuffer) {
+  if (expectedDigest && (downloadedBuffer || archiveVerifier)) {
     const algo = expectedDigest.includes(':') ? expectedDigest.split(':')[0] : 'sha256';
-    const actual = `${algo}:${createHash(algo).update(downloadedBuffer).digest('hex')}`;
+    let actual;
+    try { actual = `${algo}:${archiveVerifier ? archiveVerifier.digest(algo) : createHash(algo).update(downloadedBuffer).digest('hex')}`; }
+    catch (error) { return damaged(`downloaded bundle digest verification failed: ${error.message}`, landed); }
     if (actual !== expectedDigest) {
       return damaged(`downloaded bundle digest ${actual} does not match the release-declared digest ${expectedDigest}`, landed);
     }
@@ -1705,7 +1739,7 @@ async function main() {
   const originLabel = resolved.origin === 'latest-release-asset' ? `live release asset "${resolved.assetName}"`
     : resolved.origin === 'live-manifest' ? 'live manifest' : 'PINNED FALLBACK (see warning above)';
   console.log(`\n[${behindStores.length} store(s)] downloading ${resolved.url}\n  (source: ${originLabel}) ...`);
-  const buf = await fetchBuffer(resolved.url);
+  let buf = await fetchBuffer(resolved.url);
   const sigBuf = await fetchBuffer(`${resolved.url}.sig`, { failureCode: 3, kind: 'signature' });
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-update-release-'));
   const zipPath = path.join(tmp, 'bundle.zip');
@@ -1718,6 +1752,14 @@ async function main() {
   const signature = verifyDownloadedBundle(zipPath, sigPath);
   if (!signature.ok) { fs.rmSync(tmp, { recursive: true, force: true }); die(`✗ SIGNATURE VERIFICATION FAILED: ${signature.reason}`, 4); }
   console.log(`  ✓ signature verified — ${signature.reason}`);
+  let archiveVerifier;
+  try { archiveVerifier = createDownloadedArchiveVerifier(buf, resolvedTargets.map(({ resolved: target }) => target.digest)); }
+  catch (error) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    die(`archive digest snapshot failed: ${error.message} — local files untouched.`, 4);
+  }
+  const bundleSha256 = archiveVerifier.digest();
+  buf = null; // Snapshot owns only immutable digest strings; release the downloaded bytes before validation.
   // DISK-SPACE PREFLIGHT, before a single byte is unpacked: the bundle unpacks in temp, then a whole
   // candidate generation is built beside the live one: the bundle, plus what prepareCandidate carries into
   // it from live — node_modules, and every private/local-ingest store file (restorePrivateFilesIntoCandidate
@@ -1801,7 +1843,7 @@ async function main() {
       for (const { local, resolved: storeResolution } of landingTargets) {
         execFileSync(process.execPath, [guard, '--dir', dir, '--name', local.kbName], { cwd: dir, stdio: 'pipe' });
         const verified = verifyLanded({ kbDir: dir, kbName: local.kbName, before: local, beforeBundle: source,
-          expectedDigest: storeResolution.digest, downloadedBuffer: buf });
+          expectedDigest: storeResolution.digest, archiveVerifier });
         if (!verified.ok && verified.kind !== 'noop') return { valid: false, failures: [verified.reason] };
         if (phase === 'live') finalVerificationByStore.set(local.kbName, verified);
       }
@@ -1872,7 +1914,6 @@ async function main() {
   fs.rmSync(tmp, { recursive: true, force: true });
   console.log(`  storage transaction: ${transaction.terminalVerdict}`);
   if (transaction.terminalVerdict === 'cleanup-pending') {
-    const bundleSha256 = createHash('sha256').update(buf).digest('hex');
     const cleanupOutcome = writeUpdateOutcome({ terminalVerdict: 'cleanup-pending', storageDelta: transaction.storageDelta,
       transactionReceipts: transaction.paths.receipts, bundleSha256,
       phaseEvidence: phaseEvidenceFor({ root: KB_DIR, terminalVerdict: 'cleanup-pending', bundleSha256,
@@ -1886,7 +1927,7 @@ async function main() {
   for (const { local, resolved: storeResolution } of landingTargets) {
     const verified = finalVerificationByStore.get(local.kbName)
       || verifyLanded({ kbDir: KB_DIR, kbName: local.kbName, before: local, beforeBundle: source,
-        expectedDigest: storeResolution.digest, downloadedBuffer: buf });
+        expectedDigest: storeResolution.digest, archiveVerifier });
     if (verified.storeUnchanged || verified.kind === 'noop') unchangedStores.push(local.kbName);
     landedByStore.set(local.kbName, { landed: verified.landed, origin: storeResolution.origin, assetName: storeResolution.assetName });
   }
@@ -1947,10 +1988,10 @@ async function main() {
     currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
     storageDelta: transaction.storageDelta,
     transactionReceipts: transaction.paths.receipts,
-    bundleSha256: createHash('sha256').update(buf).digest('hex'),
+    bundleSha256,
     coverageSha256: sha256File(path.join(KB_DIR, 'COVERAGE.json')),
     phaseEvidence: phaseEvidenceFor({ root: KB_DIR, terminalVerdict: transaction.terminalVerdict,
-      bundleSha256: createHash('sha256').update(buf).digest('hex'),
+      bundleSha256,
       transactionReceipts: transaction.paths.receipts, overlay: privateOverlay,
       storageDelta: transaction.storageDelta }) });
   if (finalOutcome?.terminalVerdict === 'recovery-required') die(finalOutcome.reason);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.6",
-  "description": "One-command installer for RuvNet Brain — 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.",
+  "version": "4.5.8",
+  "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": {
     "ruvnet-brain": "bin/install.mjs"
@@ -74,7 +74,9 @@
     "hooks:check": "node scripts/hook-retirement-check.mjs",
     "release:qualify": "node scripts/release-qualification.mjs",
     "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs",
-    "single-source:check": "node scripts/single-source-check.mjs"
+    "single-source:check": "node scripts/single-source-check.mjs",
+    "benchmark:continuity": "node scripts/qa/progression-validation-benchmark.mjs",
+    "host:codex:execution-proof": "node scripts/codex-host-execution-proof.mjs"
   },
   "files": [
     ".claude-plugin/marketplace.json",

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.6",
+  "version": "4.5.8",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/commands/configure.md

@@ -1,6 +1,7 @@
 ---
 description: Open the RuvNet Brain Console (/rnbc) — a local web page that mirrors YOUR machine's RuvNet setup, explains it in plain English, and lets you safely configure and fix it. Read-only until you click; every machine change is explained first and is reversible.
-updated: 2026-10-01
+updated: 2026-10-04
+version: 1.0.1
 ---
 
 Launch the **RuvNet Brain Console** (RNBC) for the user. `/rnbc` is its name; `/rnb`, `/rvbc`,
@@ -64,6 +65,17 @@ header chip says how fresh the reading is and re-measures if they click it.
 Report it plainly — the real error, not a guess — and offer to fix it. Never leave them staring at
 a dead tab wondering whether it is still loading.
 
+## Promise capture preference
+
+If the user asks to stop automatic promise capture, explain the supported setting:
+`RUVNET_PROMISE_CAPTURE=off` in the hook process environment. It can be supplied for the machine or
+one project through the host's environment configuration. The exact value `off` stops capturing new
+"I'll …" promises; unset it or set `on` to resume capture. This preference is separate from the Brain
+on/off switch and is not currently a Console toggle. Existing promises remain visible and forceable,
+and close only on verified evidence. Capability and completion integrity checks keep running. Do not
+disable the Stop hook or edit the work ledger to apply this preference. Reopen the host if its current
+session has not picked up the changed environment.
+
 ---
 
 ## Things NOT to do before the page is open

package/plugin/hooks/codex-hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps the pre-existing, project-scoped continuation gate; session-snapshot was added at Stop on 2026-09-29 to record each turn's outcome (turn-outcome-capture.mjs) \u2014 Codex SessionEnd carries no last_assistant_message, so Stop is the only boundary that can. Its delivery rests on codex-cli 0.158.0's declared stop.command.input schema and the other Codex Stop handlers; it has NOT been live-observed and fails open. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 \u00a7Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on \u2014 that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered \u2014 today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair \u2014 a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses. Capacity-aware parallel-work guidance is also registered at UserPromptSubmit: it advises the coordinator to launch only real independent workers within sampled resource headroom and the live runtime/tool cap; it never spawns workers or claims execution. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope.",
+  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps the pre-existing, project-scoped continuation gate; session-snapshot was added at Stop on 2026-09-29 to record each turn's outcome (turn-outcome-capture.mjs) \u2014 Codex SessionEnd carries no last_assistant_message, so Stop is the only boundary that can. Its delivery rests on codex-cli 0.158.0's declared stop.command.input schema and the other Codex Stop handlers; it has NOT been live-observed and fails open. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 \u00a7Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on \u2014 that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered \u2014 today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair \u2014 a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses. Capacity-aware parallel-work guidance is also registered at UserPromptSubmit: it advises the coordinator to launch only real independent workers within sampled resource headroom and the live runtime/tool cap; it never spawns workers or claims execution. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope. Issue377: consent-eligible learning captures only fixed workflow metadata; lifecycle recovery schedules one finite worker. Original records remain retained with hash-bound acknowledgments. Native delivery must be separately evidenced; registration is not proof.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,16 @@
             "timeout": 8
           }
         ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 learn-flush",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "Stop": [
@@ -77,6 +87,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 learn-capture",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -121,6 +141,16 @@
             "timeout": 3
           }
         ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 learn-flush",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "SubagentStop": [

package/plugin/hooks/hook-contracts.json

@@ -1,6 +1,6 @@
 {
   "_note": "The legacy automatic gate collection remains retired. What is permitted is the continuity plane below and nothing else: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint; Stop may nudge one explicitly authorized project-scoped objective AND capture a project snapshot; PreCompact and SessionEnd capture a project snapshot. Version 3 of this file permitted exactly two handlers, which was not a safety property but a contradiction: it demanded a restore while forbidding any event that could WRITE the journal the restore reads, so the canonical store held zero progression rows. Adding to this list is still a deliberate act that must pass `npm run hooks:check`; what changed is that the shape can now express the plane that actually works. Amended 2026-09-11 (Stuart): the continuity-only charter had retired the ONLY enforcement of ADR-0012 \u2014 never write rUv-product code the brain has not seen \u2014 and the failure it exists to prevent recurred the day it was measured absent. The plane now also carries three grounding registrations: ground-ruvnet (UserPromptSubmit, grounding injection \u2014 a second owner of that event, scoped by ADR-040 \u00a7Amendment 2026-09-11 to directives rather than speech), decision-gate\u2019s write route (PreToolUse, the one refuser, ADR-067), and grounding-stamp (PostToolUse on a successful search_ruvnet, the receipt that opens the write gate). Amended 2026-09-12: the 2026-09-11 claim that Codex PreToolUse/PostToolUse delivery had never been observed was measured with a prompt that never invoked a tool (`codex exec \"reply OK\"`), so it was an untested path, not a failing one. Re-measured with prompts that actually call a tool (a real apply_patch write, a real MCP search_ruvnet call against this repo's own server): both events FIRED on codex-cli 0.154.0 with real payloads. decision-gate's write route and grounding-stamp are now dual-host (see _codexCapture and contracts below); the bash route (exec_command) remains Claude-only \u2014 today's measurement did not exercise it. Also amended 2026-09-12: added grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair \u2014 ground-ruvnet's Gate 1 directive is advisory, so nothing previously checked whether the model complied before the turn ended. grounding-turn-mark records that Gate 1 fired for a turn; grounding-turn-gate forces continuation at Stop if grounding-stamp's own evidence shows no search_ruvnet call happened since. Both dual-host from the start (the Stop-block contract is already proven on Codex via continuation-gate). Added capacity-aware-parallel-work at UserPromptSubmit on both measured hosts: it is context-only, resource-bounded, and requires the coordinator to check actual tool/runtime slots; it does not spawn or claim workers. Amended 2026-09-30 (ADR-0030 decision point #1, no new registration): grounding-turn-mark also arms a turn when the prompt asks a capability/feasibility/architecture question about any tool or platform, and grounding-turn-gate then requires every capability claim in the final answer to be bound to a relevant STRONG source read this turn after the last weak one (a WebFetch body is a small model's summary: weak); on Claude it reads the transcript instead of stamp mtimes, which removed the measured 'no search recorded' false alarms. ADR-0030 #2/#3 run in shadow only. Amendment 2026-10-03: normalized prompt/tool/failure/child observations are automatic; startup replays before restoring. Queued and unavailable evidence remain distinct from exact committed readback. Native Grok prompt recall is unsupported.",
-  "_version": 9,
+  "_version": 10,
   "_eventOwners": [
     {
       "event": "SessionStart",
@@ -169,6 +169,36 @@
         "codex"
       ],
       "responsibility": "Capture bounded redacted observable intent or outcome through the canonical progression bridge; retain pending/failed status and do not infer success from pre-tool intent."
+    },
+    {
+      "event": "PostToolUse",
+      "owner": "learn-capture",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
+    },
+    {
+      "event": "SessionEnd",
+      "owner": "learn-flush",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
+    },
+    {
+      "event": "SessionStart",
+      "owner": "learn-flush",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
     }
   ],
   "_notInThisPlane": [
@@ -297,7 +327,7 @@
         "codex"
       ],
       "mode": "advisory",
-      "offBehavior": "run",
+      "offBehavior": "silence",
       "matcher": "*",
       "timeout": 6
     },
@@ -407,6 +437,42 @@
       "offBehavior": "run",
       "matcher": "*",
       "timeout": 10
+    },
+    {
+      "id": "learn-capture",
+      "event": "PostToolUse",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "timeout": 3
+    },
+    {
+      "id": "learn-flush",
+      "event": "SessionEnd",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 3
+    },
+    {
+      "id": "learn-flush",
+      "event": "SessionStart",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "startup|resume|clear|compact|fork",
+      "timeout": 3
     }
   ],
   "matcherAllowlist": [
@@ -549,6 +615,20 @@
       "matcher": "*",
       "reason": "Explicit supported Codex lifecycle registration, corresponding to the host-filtered continuity policy; its enforcing handler and live registration are checked independently.",
       "retiredBy": "not retired - canonical continuity host parity"
+    },
+    {
+      "layer": "plugin",
+      "event": "PostToolUse",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "reason": "Consent-eligible normalized fixed workflow vocabulary, privacy-minimized before write.",
+      "retiredBy": "reviewed issue377 learning repair"
+    },
+    {
+      "layer": "codex",
+      "event": "PostToolUse",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "reason": "Consent-eligible normalized fixed workflow vocabulary, privacy-minimized before write.",
+      "retiredBy": "reviewed issue377 learning repair"
     }
   ]
 }

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech \u2014 ADR-040 \u00a7Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if the final answer asserts a rUv capability and no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors \u2014 the Stop stdout envelopes are advisory at the shim boundary but keep the agent working. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope.",
+  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech \u2014 ADR-040 \u00a7Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if the final answer asserts a rUv capability and no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors \u2014 the Stop stdout envelopes are advisory at the shim boundary but keep the agent working. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope. Issue377: consent-eligible learning captures only fixed workflow metadata; lifecycle recovery schedules one finite worker. Original records remain retained with hash-bound acknowledgments. Native delivery must be separately evidenced; registration is not proof.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,16 @@
             "timeout": 8
           }
         ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-flush || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -87,6 +97,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-capture || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "Stop": [
@@ -133,6 +153,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-flush || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "SubagentStop": [

package/plugin/mcp/managed-cli-generation.mjs

@@ -0,0 +1,91 @@
+// DISTINCT-FROM hook-shim.mjs: managed execution fails closed; advisory hook fallback cannot
+// authorize a command. The protocol shell owns declarations, each request owns one generation.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const LOCAL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const contained = (root, file) => file.startsWith(`${root}${path.sep}`);
+
+export function managedGenerationIdentity(root, { version, generation = 'source' } = {}) {
+  root = fs.realpathSync(root);
+  const manifestPath = path.join(root, '.claude-plugin', 'plugin.json');
+  const handlerPath = path.join(root, 'mcp', 'managed-cli-interface.mjs');
+  for (const file of [manifestPath, handlerPath]) {
+    if (!fs.lstatSync(file).isFile() || !contained(root, fs.realpathSync(file))) {
+      throw new Error('managed generation resource is not a contained regular file');
+    }
+  }
+  const manifestBytes = fs.readFileSync(manifestPath);
+  const manifest = JSON.parse(manifestBytes);
+  if (manifest.name !== 'ruvnet-brain' || typeof manifest.version !== 'string'
+    || !/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.+-]+)?$/.test(manifest.version)
+    || (version !== undefined && manifest.version !== version)) {
+    throw new Error('managed generation manifest name/version mismatch');
+  }
+  const sourceDigest = digest(Buffer.concat([manifestBytes, fs.readFileSync(handlerPath)]));
+  return Object.freeze({ root, handlerPath, version: manifest.version, generation, sourceDigest,
+    binding: digest(JSON.stringify([root, manifest.version, generation, sourceDigest])) });
+}
+
+function selectGeneration(env, fallbackRoot) {
+  const home = env.HOME || os.homedir();
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
+  let activeBytes;
+  try { activeBytes = fs.readFileSync(path.join(brainHome, 'active.json'), 'utf8'); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    // A copied persistent shell must never manufacture an active generation from its resources.
+    if (path.resolve(fallbackRoot) === path.join(home, '.claude', 'ruvnet-brain')) {
+      throw new Error('managed active generation unavailable');
+    }
+    return { ...managedGenerationIdentity(fallbackRoot), brainHome, leased: false };
+  }
+  const active = JSON.parse(activeBytes);
+  if (typeof active.codeRoot !== 'string' || typeof active.version !== 'string'
+    || !Number.isSafeInteger(active.generation) || active.generation < 0) {
+    throw new Error('managed active generation descriptor invalid');
+  }
+  const versions = fs.realpathSync(path.join(brainHome, 'versions'));
+  const root = fs.realpathSync(path.resolve(brainHome, active.codeRoot));
+  if (!contained(versions, root) || path.basename(root) !== active.version) {
+    throw new Error('managed active generation escapes its version tree');
+  }
+  return { ...managedGenerationIdentity(root, active), brainHome, leased: true };
+}
+
+export function createManagedCliDispatcher({ fallbackRoot = LOCAL_ROOT,
+  importModule = (url) => import(url) } = {}) {
+  const pins = new Map();
+  return async function dispatchManagedCli(toolName, args, env = process.env,
+    fetchImpl = globalThis.fetch, lifecycle = {}) {
+    let lease;
+    try {
+      const selected = selectGeneration(env, fallbackRoot);
+      // ESM caches by URL. A changed file at the same immutable path must never be blessed as
+      // new code while execution still uses the old cached module (nor can query strings fix dependencies).
+      const pinned = pins.get(selected.root);
+      if (pinned && pinned !== selected.sourceDigest) throw new Error('managed immutable generation changed; restart required');
+      pins.set(selected.root, selected.sourceDigest);
+      if (selected.leased) {
+        const dir = path.join(selected.brainHome, 'leases');
+        fs.mkdirSync(dir, { recursive: true });
+        lease = path.join(dir, `mcp-managed-${process.pid}-${randomUUID()}.json`);
+        fs.writeFileSync(lease, JSON.stringify({ pid: process.pid, version: selected.version, at: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+      }
+      const handler = await importModule(pathToFileURL(selected.handlerPath).href);
+      if (typeof handler.callManagedCli !== 'function') throw new Error('managed generation handler unavailable');
+      return await handler.callManagedCli(toolName, args, env, fetchImpl,
+        { ...lifecycle, generationBinding: selected.binding });
+    } catch (error) {
+      return { content: [{ type: 'text', text: `managed generation unavailable: ${error.message}` }], isError: true };
+    } finally {
+      if (lease) { try { fs.unlinkSync(lease); } catch { /* lease expiry preserves interrupted calls */ } }
+    }
+  };
+}
+
+export const dispatchManagedCli = createManagedCliDispatcher();