ruvnet-brain 4.5.7 → 4.5.8

package/plugin/scripts/learning-worker-supervisor.mjs

@@ -0,0 +1,79 @@
+// One finite owner retires its separate worker tree before surrendering the queue fence.
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ownsQueueLock, releaseQueueLock, writeExclusive, writeAtomic, readSafe } from './learning-queue.mjs';
+import { learningContext } from './runtime-preferences.mjs';
+
+const aliveGroup = pid => {
+  try { process.kill(-pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+};
+const killTree = pid => {
+  if (process.platform === 'win32') {
+    const r = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { timeout: 1000, windowsHide: true, stdio: 'ignore' });
+    return !r.error && r.status === 0;
+  }
+  try { process.kill(-pid, 'SIGKILL'); return true; } catch (error) { return error.code === 'ESRCH'; }
+};
+
+export async function superviseLearning(context, token, deadline, { report = false, spawnEngine = spawn,
+  killOwned = killTree, groupAlive = aliveGroup, platform = process.platform, env = process.env,
+  persistFence = writeAtomic, writeDiagnostic = writeExclusive } = {}) {
+  // A supervisor crash or later read-only filesystem must never permit expired-lease takeover.
+  // Persist and verify the retirement requirement before any worker can exist.
+  const lockFile = path.join(context.queueDir, '.worker-lock');
+  try {
+    if (!ownsQueueLock(context, token)) throw new Error('queue ownership lost');
+    const lock = JSON.parse(readSafe(lockFile));
+    persistFence(lockFile, JSON.stringify({ ...lock, retirementRequired: true }));
+    const verified = JSON.parse(readSafe(lockFile));
+    if (verified.token !== token || verified.retirementRequired !== true) throw new Error('retirement requirement unverified');
+  } catch {
+    return { retirementConfirmed: true, fencePersisted: false, launched: false };
+  }
+  const child = spawnEngine(process.execPath, [fileURLToPath(new URL('./learn-flush.mjs', import.meta.url)), '--worker', ...(report ? ['--report'] : [])], {
+    cwd: context.projectDir, detached: true, stdio: ['ignore', report ? 'inherit' : 'ignore', report ? 'inherit' : 'ignore', 'ipc'], windowsHide: true,
+    env: { ...env, RUVNET_LEARN_WORKER_TOKEN: token, RUVNET_LEARN_WORKER_EXPIRES: String(deadline), RUFLO_DAEMON_AUTOSTART: '0' },
+  });
+  return await new Promise(resolve => {
+    let retiring = false; let exited = false;
+    const timer = setTimeout(() => void retire(true), Math.max(1, deadline - Date.now()));
+    const retire = async failed => {
+      if (retiring) return; retiring = true; clearTimeout(timer);
+      let killed = false;
+      try { killed = !child.pid || killOwned(child.pid); } catch { /* bounded refusal below */ }
+      const until = Date.now() + 600; let confirmed = !child.pid;
+      while (!confirmed && Date.now() < until) {
+        try { confirmed = platform === 'win32' ? killed && exited : !groupAlive(child.pid); } catch { confirmed = false; }
+        if (!confirmed) await new Promise(r => setTimeout(r, 25));
+      }
+      // Mandatory fencing is independent of optional diagnostics (including ENOSPC).
+      let fencePersisted = confirmed;
+      if (!confirmed) {
+        try {
+          if (ownsQueueLock(context, token)) {
+            const lock = JSON.parse(readSafe(lockFile));
+            persistFence(lockFile, JSON.stringify({ ...lock, retirementUnconfirmed: true }));
+            fencePersisted = JSON.parse(readSafe(lockFile)).retirementUnconfirmed === true;
+          }
+        } catch { /* Report failed durability without claiming the queue is fenced. */ }
+      }
+      try {
+        const current = learningContext({ env, cwd: context.projectDir });
+        if (current.enabled && current.queueDir === context.queueDir) {
+          if (failed || !confirmed) writeDiagnostic(path.join(context.queueDir, `.run-${Date.now()}-${process.pid}.json`), JSON.stringify({
+            schemaVersion: 1, failed: 1, fed: 0, acknowledged: 0, workerPid: child.pid, retirementConfirmed: confirmed, fencePersisted,
+            reason: confirmed ? 'owned worker exceeded deadline or crashed; retired; originals retained' : fencePersisted
+              ? 'owned tree retirement unconfirmed; queue fenced; originals retained'
+              : 'owned tree retirement unconfirmed; fence persistence failed; manual recovery required; originals retained',
+          }));
+        }
+      } catch { /* Diagnostic failure never consumes original evidence. */ }
+      if (confirmed) releaseQueueLock(context, token);
+      if (child.connected) child.disconnect(); child.unref?.(); resolve({ retirementConfirmed: confirmed, fencePersisted });
+    };
+    child.once('message', message => { if (message?.type === 'learning-worker-complete') void retire(false); });
+    child.once('error', () => void retire(true));
+    child.once('exit', () => { exited = true; if (!retiring) void retire(true); });
+  });
+}

package/plugin/scripts/project-progression-contract.mjs

@@ -14,7 +14,32 @@ function canonicalize(value) {
 }
 
 export function digestCanonical(value) {
-  return crypto.createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+  return crypto.createHash('sha256').update(JSON.stringify(isCanonicalJson(value) ? value : canonicalize(value))).digest('hex');
+}
+
+// Stored snapshots are already canonical. Verify that fact without constructing a second
+// complete object graph; arbitrary callers still receive the original sorting/validation path.
+function isCanonicalJson(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype || ['toJSON', 'map', 'constructor'].some(key => Object.hasOwn(value, key))) return false;
+    for (let index = 0; index < value.length; index++) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, index);
+      if (!descriptor || !Object.hasOwn(descriptor, 'value') || !isCanonicalJson(descriptor.value)) return false;
+    }
+    return true;
+  }
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) return false;
+  if (Object.hasOwn(value, 'toJSON')) return false;
+  let previous;
+  for (const key of Object.keys(value)) {
+    if (previous !== undefined && previous > key) return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!Object.hasOwn(descriptor, 'value') || !isCanonicalJson(descriptor.value)) return false;
+    previous = key;
+  }
+  return true;
 }
 
 function requireRecord(value, label) {
@@ -115,6 +140,35 @@ const INLINE_SECRETS = Object.freeze([
   },
 ]);
 
+// Validation needs a verdict, not a rebuilt redacted payload. Keep exactly the writer's
+// key and replacement semantics, including already-redacted markers and nested values.
+function containsUnredactedSecret(value) {
+  const kinds = new Map();
+  const visit = (current) => {
+    if (typeof current === 'string') {
+      if (!/PRIVATE KEY|Bearer|(?:sk|api-key|ghp|github_pat)[-_]|password|passwd|token|secret|credential/i.test(current)) return false;
+      for (const rule of INLINE_SECRETS) {
+        rule.pattern.lastIndex = 0;
+        if (current.replace(rule.pattern, rule.replace) !== current) return true;
+      }
+      return false;
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) if (visit(item)) return true;
+    } else if (current && typeof current === 'object' && Object.getPrototypeOf(current) === Object.prototype) {
+      for (const key of Object.keys(current)) {
+        if (!kinds.has(key)) kinds.set(key, secretKind(key));
+        const kind = kinds.get(key);
+        if (kind && current[key] !== null && current[key] !== undefined) {
+          if (current[key] !== `[REDACTED:${kind}]`) return true;
+        } else if (visit(current[key])) return true;
+      }
+    }
+    return false;
+  };
+  return visit(value);
+}
+
 export function redactProgression(value) {
   const redactions = [];
   const mark = (path, kind) => {
@@ -239,15 +293,15 @@ export function validateProgressionSnapshot(snapshot, { expectedProjectIdentity
     } catch { errors.push('event key is unverifiable'); }
   }
   try {
-    const body = canonicalize(snapshot);
-    delete body.payloadDigest;
+    if (Object.getPrototypeOf(snapshot) !== Object.prototype) throw new TypeError('snapshot must be a plain JSON object');
+    const { payloadDigest: _digest, ...body } = snapshot;
     if (snapshot.payloadDigest !== digestCanonical(body)) errors.push('payload digest mismatch');
   } catch { errors.push('payload is not canonical JSON'); }
   if (Array.isArray(snapshot.redactions)
     && snapshot.redactions.some((row) => !row || typeof row.path !== 'string' || typeof row.kind !== 'string'
       || Object.keys(row).sort().join(',') !== 'kind,path')) errors.push('invalid redaction marker');
   try {
-    if (redactProgression(snapshot).redactions.length > 0) errors.push('unredacted secret material');
+    if (containsUnredactedSecret(snapshot)) errors.push('unredacted secret material');
   } catch { /* canonical validation already reports the malformed payload */ }
 
   return { ok: errors.length === 0, errors: [...new Set(errors)] };

package/plugin/scripts/runtime-preferences.mjs

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { projectDirectory } from './project-identity.mjs';
 
 const DEFAULT_HOME = os.homedir();
 const PROJECT_FILE = '.swarm/ruvnet-brain-settings.json';
@@ -306,7 +307,7 @@ if (process.argv.includes('--learning-scope')) {
  */
 export function learningScope(options = {}) {
   const env = options.env ?? process.env;
-  const cwd = options.cwd ?? process.env.RUVNET_BRAIN_PROJECT_DIR ?? process.cwd();
+  const cwd = projectDirectory({ env, cwd: options.cwd ?? env.RUVNET_BRAIN_PROJECT_DIR ?? process.cwd() });
   const configured = env.RUVNET_LEARNING_SCOPE
     || loadRuntimePreferences({ ...options, cwd }).values.learningScope;
   return ['off', 'project', 'user'].includes(configured) ? configured : 'project';
@@ -321,7 +322,47 @@ export function learningScope(options = {}) {
  * quiet" about the one training every few seconds.
  */
 export function learnerCwd(options = {}) {
-  const home = options.home ?? os.homedir();
-  const project = options.cwd ?? process.env.RUVNET_BRAIN_PROJECT_DIR ?? process.cwd();
-  return learningScope(options) === 'user' ? home : project;
+  return learningContext(options).learnerCwd;
+}
+
+/** One scope snapshot for Console observation, remedies and the learning queue. Never creates paths. */
+export function learningContext(options = {}) {
+  const env = options.env ?? process.env;
+  const requestedHome = options.home ?? env.HOME ?? os.homedir();
+  let home; try { home = fs.realpathSync.native(requestedHome); } catch { home = path.resolve(requestedHome); }
+  const projectDir = projectDirectory({ env, cwd: options.cwd ?? env.RUVNET_BRAIN_PROJECT_DIR ?? process.cwd() });
+  const scope = learningScope({ ...options, env, cwd: projectDir });
+  const learner = scope === 'user' ? home : projectDir;
+  let persistedOff = false;
+  let consentUnknown = !!env.RUVNET_LEARNING_SCOPE && !['off', 'project', 'user'].includes(env.RUVNET_LEARNING_SCOPE);
+  for (const file of Object.values(preferencePaths({ ...options, env, cwd: projectDir })).slice(0, 2)
+    .concat(preferencePaths({ ...options, env, cwd: projectDir }).project)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) consentUnknown = true;
+      for (const name of ['values', 'settings']) if (raw && Object.hasOwn(raw, name)) {
+        const inner = raw[name];
+        if (!inner || typeof inner !== 'object' || Array.isArray(inner)) consentUnknown = true;
+      }
+      const value = (raw.values || raw.settings || raw).learningScope;
+      persistedOff ||= value === 'off';
+      if (value !== undefined && !['off', 'project', 'user'].includes(value)) consentUnknown = true;
+    } catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) consentUnknown = true; }
+  }
+
+  const state = env.RUVNET_BRAIN_STATE_DIR || path.join(home, '.config', 'ruvnet-brain');
+  let brainOff = env.RUVNET_BRAIN_OFF === '1';
+  try { fs.statSync(path.join(state, 'brain-off')); brainOff = true; }
+  catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) brainOff = true; }
+  let adopted = scope === 'user' || env.RUVNET_LEARNING_SCOPE === 'project';
+  try {
+    const swarm = path.join(projectDir, '.swarm');
+    adopted ||= fs.lstatSync(swarm).isDirectory() && fs.realpathSync.native(swarm) === swarm;
+  } catch { /* No implicit adoption or directory creation. */ }
+  return {
+    scope, projectDir, home, learnerCwd: learner, adopted, enabled: scope !== 'off' && !brainOff && !consentUnknown && !persistedOff && adopted,
+    disabledReason: consentUnknown ? 'unknown-consent' : brainOff ? 'brain-off' : scope === 'off' || persistedOff ? 'learning-off' : !adopted ? 'unadopted' : null,
+    queueDir: scope === 'user' ? path.join(home, '.cache', 'ruvnet-brain', 'learn')
+      : path.join(projectDir, '.swarm', 'ruvnet-brain-learn'),
+  };
 }

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

@@ -38,6 +38,7 @@ import { stableSpine, heartbeat, knowledgeAutoUpdate, footprintCheck } from './s
 import { FOOTPRINT_LINE_PREFIX } from './brain-confirmation.mjs';
 import { describeLifecycleHooks, readHookContracts } from './session-start-hook-description.mjs';
 import { createStageTracer } from './session-start-trace.mjs';
+import { sessionStartProofRecorder } from './session-start-proof.mjs';
 
 // Re-exported for callers/tests that import the entitlement check directly from this file's own
 // long-standing public surface (tests/unit/session-start-core-parity.test.mjs).
@@ -170,6 +171,7 @@ export async function runSessionStart({
   const activeVersion = typeof env.RUVNET_BRAIN_ACTIVE_VERSION === 'string'
     ? env.RUVNET_BRAIN_ACTIVE_VERSION : '';
   const effectiveVersion = activeVersion || running;
+  const recordProof = sessionStartProofRecorder({ env, sourcePath: fileURLToPath(import.meta.url), cwd, version: effectiveVersion });
   const updated = typeof manifest?.updated === 'string' ? manifest.updated : '';
   const trace = (stage) => {
     if (env.RUVNET_SESSION_TRACE === '1') {
@@ -178,13 +180,16 @@ export async function runSessionStart({
   };
 
   const restoreStart = Date.now();
+  let restoreFailed = false;
   try {
     const continuity = await restoreContinuity({ env, cwd });
     if (continuity?.context) emit(continuity.context);
   } catch {
+    restoreFailed = true;
     emit('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]');
     emit('The SessionStart restore boundary failed unexpectedly. Do not claim project state was restored; verify the canonical store before relying on remembered state.');
   }
+  const restoreProof = { name: 'restore', ms: Date.now() - restoreStart, failed: restoreFailed };
   // Turn health remains visible even when the separate progression restore fails.
   const turnStatus = turnRecordingStatus({ projectDir: cwd, env, home });
   if (turnStatus.state === 'warn') emit(`[RuvNet Brain — TURN RECORDING] ${turnStatus.line}`);
@@ -202,6 +207,7 @@ export async function runSessionStart({
     write: (chunk) => stderr.write(chunk),
   });
   let bannerEmitted = false;
+  let bodyFailed = false;
 
   try {
     trace('body-start');
@@ -387,6 +393,7 @@ export async function runSessionStart({
       }
     });
   } catch (error) {
+    bodyFailed = true;
     if (env.RUVNET_SESSION_TRACE === '1') stderr.write(`SESSION_TRACE native-fail-open ${error?.message || error}\n`);
   }
 
@@ -401,6 +408,7 @@ export async function runSessionStart({
   meter({ env, cwd, stateDir, output });
   stdout.write(output);
   trace('body-finished');
+  recordProof({ stages: tracer.table(), restore: restoreProof, bodyFailed, bannerFallback: !bannerEmitted });
   return { ok: true, outputBytes: Buffer.byteLength(output, 'utf8'), platform };
 }
 

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

@@ -0,0 +1,49 @@
+// Optional execution evidence, never a health verdict. Only overwrite a caller-owned nonce file.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const digest = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+export function sessionStartProofRecorder({ env, sourcePath, cwd, version }) {
+  const file = env.RUVNET_BRAIN_HOST_PROOF_PATH;
+  const nonce = env.RUVNET_BRAIN_HOST_PROOF_NONCE;
+  if (!file && !nonce) return () => false;
+  let fd;
+  try {
+    if (process.platform === 'win32' || !path.isAbsolute(file || '') || !/^[a-f0-9]{64}$/.test(nonce || '')) return () => false;
+    const parent = path.dirname(file); const dir = fs.lstatSync(parent);
+    if (!dir.isDirectory() || dir.isSymbolicLink() || fs.realpathSync(parent) !== parent
+      || dir.uid !== process.getuid() || (dir.mode & 0o777) !== 0o700) return () => false;
+    fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.uid !== process.getuid() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || stat.size > 1024) throw new Error('Unsafe proof file');
+    const seed = JSON.parse(fs.readFileSync(fd, 'utf8'));
+    if (seed.schema !== 1 || seed.state !== 'pending' || seed.nonce !== nonce || Object.keys(seed).length !== 3) throw new Error('Proof seed mismatch');
+    const sourceSha256 = digest(fs.readFileSync(sourcePath)); const startedAt = Date.now();
+    fs.closeSync(fd); fd = undefined;
+    return ({ stages, restore, bodyFailed, bannerFallback }) => {
+      let receiptFd;
+      try {
+        const current = fs.lstatSync(file);
+        const parentNow = fs.lstatSync(parent);
+        if (current.ino !== stat.ino || current.dev !== stat.dev || current.isSymbolicLink()
+          || current.uid !== stat.uid || (current.mode & 0o777) !== 0o600 || current.nlink !== 1
+          || parentNow.uid !== dir.uid || parentNow.ino !== dir.ino || parentNow.dev !== dir.dev || (parentNow.mode & 0o777) !== 0o700
+          || fs.realpathSync(parent) !== parent || digest(fs.readFileSync(sourcePath)) !== sourceSha256) return false;
+        receiptFd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+        const opened = fs.fstatSync(receiptFd);
+        if (opened.ino !== stat.ino || opened.dev !== stat.dev) return false;
+        if (opened.size > 1024 || JSON.stringify(JSON.parse(fs.readFileSync(receiptFd, 'utf8'))) !== JSON.stringify(seed)) return false;
+        const receipt = { schema: 1, state: 'body-executed', nonce, pid: process.pid,
+          sourcePath, sourceSha256, cwd, version, startedAt, finishedAt: Date.now(),
+          restore, stages, bodyFailed, bannerFallback, scope: 'stage-return-milestones',
+          health: 'unknown', detachedMaintenance: 'possible' };
+        const bytes = `${JSON.stringify(receipt)}\n`;
+        fs.writeSync(receiptFd, bytes, 0, 'utf8');
+        fs.ftruncateSync(receiptFd, Buffer.byteLength(bytes));
+        fs.fsyncSync(receiptFd); return true;
+      } catch { return false; }
+      finally { if (receiptFd !== undefined) fs.closeSync(receiptFd); }
+    };
+  } catch { if (fd !== undefined) fs.closeSync(fd); return () => false; }
+}

package/scripts/codex-fresh-host-proof.mjs

@@ -0,0 +1,179 @@
+// Evidence from a fresh native metadata process; Codex may refresh its own marketplace cache.
+// No configuration write or hook-body execution is requested by this probe. It does not
+// prove MCP readiness or declarations frozen in existing windows.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { codexHookIdentities, codexHookHash } from './codex-hook-trust.mjs';
+import { obtainVerifiedPublishedHookIdentity } from './codex-hook-trust-reconcile.mjs';
+
+const OWNER = 'ruvnet-brain@ruvnet-brain';
+const FILES = ['.codex-plugin/plugin.json', 'hooks/codex-hooks.json'];
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const failed = (reason) => ({ ok: false, state: 'fresh-declarations-unproven', scope: 'fresh-codex-hook-declarations', reason,
+  hookBodiesExecuted: false, mcpReadiness: 'unknown', existingWindows: 'unproven', inferenceRequests: 0, nativeCacheRefresh: 'possible' });
+
+function readSurface(root) {
+  const bytes = FILES.map((file) => {
+    const target = path.join(root, file); const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error('Plugin source is unavailable or unsafe');
+    return fs.readFileSync(target);
+  });
+  return { manifest: JSON.parse(bytes[0]), hooks: JSON.parse(bytes[1]), hashes: Object.fromEntries(FILES.map((file, i) => [file, sha256(bytes[i])])) };
+}
+
+export function classifyFreshCodexDeclarations({ plugin, listed, target, expectedVersion, codexHome, cwd }) {
+  if (!plugin?.installed || plugin.enabled !== true || plugin.version !== expectedVersion) return failed('Current Codex plugin is missing, disabled, or stale');
+  if (target?.manifest?.name !== 'ruvnet-brain' || target.manifest.version !== expectedVersion) return failed('Released target version is unavailable');
+  let root;
+  try {
+    root = fs.realpathSync(path.join(codexHome, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain', expectedVersion));
+    if (plugin.installPath && fs.realpathSync(plugin.installPath) !== root) return failed('Native plugin source differs from the managed version');
+    const cache = fs.realpathSync(path.join(codexHome, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain'));
+    if (!root.startsWith(`${cache}${path.sep}`)) return failed('Native plugin source is outside the managed cache');
+    if (JSON.stringify(readSurface(root).hashes) !== JSON.stringify(target.hashes)) return failed('Installed declarations differ from the independent released target');
+  } catch { return failed('Native plugin source cannot be verified'); }
+  const groups = listed?.data;
+  if (!Array.isArray(groups) || groups.length !== 1 || groups[0]?.cwd !== cwd
+    || !Array.isArray(groups[0]?.hooks) || !Array.isArray(groups[0]?.errors) || !Array.isArray(groups[0]?.warnings)) return failed('Native registry shape or project scope is unproven');
+  if (groups[0].errors.length || groups[0].warnings.length) return failed('Native registry reports errors or warnings');
+  const rows = groups[0].hooks.filter((row) => row?.pluginId === OWNER);
+  const identities = codexHookIdentities(target.hooks);
+  if (!identities.size || rows.length !== identities.size || new Set(rows.map((row) => row.key)).size !== identities.size) return failed('Brain hook declarations are missing, duplicated, or unexpected');
+  for (const row of rows) {
+    if (row.source !== 'plugin' || row.sourcePath !== path.join(root, FILES[1]) || row.enabled !== true
+      || !['trusted', 'managed'].includes(row.trustStatus)) return failed('Brain hook source, enabled state, or trust is unproven');
+    // Verify the metadata itself, as well as the native currentHash. Foreign owner hooks are untouched.
+    const event = Object.keys(target.hooks.hooks).find((name) => `${name[0].toLowerCase()}${name.slice(1)}` === row.eventName);
+    const metadataHash = codexHookHash(event, { matcher: row.matcher }, {
+      type: row.handlerType, command: row.command, timeout: row.timeoutSec, async: row.async,
+      statusMessage: row.statusMessage, additionalContextLimit: row.additionalContextLimit,
+    });
+    if (!identities.has(row.key) || identities.get(row.key) !== row.currentHash || metadataHash !== row.currentHash) return failed('Brain hook metadata differs from released declarations');
+  }
+  return { ok: true, state: 'fresh-declarations-ready', scope: 'fresh-codex-hook-declarations', expectedVersion,
+    pluginRoot: root, sourceHashes: target.hashes, hookCount: rows.length, hookBodiesExecuted: false,
+    mcpReadiness: 'unknown', existingWindows: 'unproven', inferenceRequests: 0 };
+}
+
+function nativeBinary(binary, env) {
+  const names = path.isAbsolute(binary) ? [binary] : String(env.PATH || '').split(path.delimiter).map((dir) => path.join(dir, binary));
+  for (const name of names) {
+    try {
+      const real = fs.realpathSync(name); const stat = fs.statSync(real);
+      if (!stat.isFile() || stat.size > 256 * 1024 * 1024) continue;
+      fs.accessSync(real, fs.constants.X_OK);
+      const bytes = fs.readFileSync(real); const magic = bytes.subarray(0, 4).toString('hex');
+      if (!['cffaedfe', 'feedfacf', 'cefaedfe', 'feedface', 'cafebabe', 'bebafeca', '7f454c46'].includes(magic) && bytes.subarray(0, 2).toString() !== 'MZ') continue;
+      return { path: real, sha256: sha256(bytes) };
+    } catch { /* try the next executable */ }
+  }
+  throw new Error('Actual native Codex binary is unavailable');
+}
+
+/** One deadline and cumulative stdout/stderr budget across every owned native process. No API turns. */
+export async function probeFreshCodexDeclarations({ binary = 'codex', codexHome, cwd, releasedPluginRoot,
+  expectedVersion, timeoutMs = 12_000, publishedIdentity, verifyPublished = obtainVerifiedPublishedHookIdentity, maxBytes = 2 * 1024 * 1024, env = process.env, spawnChild = spawn } = {}) {
+  const children = new Map(); let totalBytes = 0; let deadline; let identity; let target;
+  const nativeEnv = { ...env };
+  for (const key of ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'ANTHROPIC_API_KEY', 'CODEX_API_KEY']) delete nativeEnv[key];
+  const remaining = () => { const ms = deadline - Date.now(); if (ms <= 0) throw new Error('Fresh declaration proof deadline exceeded'); return ms; };
+  const consume = (chunk) => { totalBytes += chunk.length; if (totalBytes > maxBytes) throw new Error('Fresh declaration proof output exceeds bound'); };
+  const own = (args) => {
+    remaining();
+    const child = spawnChild(identity.path, args, { cwd, env: { ...nativeEnv, CODEX_HOME: codexHome }, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    const exited = new Promise((resolve) => { child.once('exit', resolve); child.once('error', () => { if (!child.pid) resolve(); }); });
+    children.set(child, exited); child.stdin.on('error', () => {}); return child;
+  };
+  const command = (args) => new Promise((resolve, reject) => {
+    const child = own(args); let stdout = ''; let done = false;
+    const finish = (error, value) => { if (done) return; done = true; clearTimeout(timer); error ? reject(error) : resolve(value); };
+    const timer = setTimeout(() => finish(new Error('Fresh declaration proof deadline exceeded')), remaining());
+    child.on('error', () => finish(new Error('Native metadata command failed')));
+    child.stdout.on('data', (chunk) => { try { consume(chunk); stdout += chunk; } catch (error) { finish(error); } });
+    child.stderr.on('data', (chunk) => { try { consume(chunk); } catch (error) { finish(error); } });
+    child.once('exit', (code) => finish(code === 0 ? null : new Error('Native metadata command refused'), stdout)); child.stdin.end();
+  });
+  try {
+    if (![codexHome, cwd, releasedPluginRoot].every((value) => typeof value === 'string' && path.isAbsolute(value))
+      || !Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 12_000
+      || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 8 * 1024 * 1024) throw new Error('Fresh declaration proof boundaries are invalid');
+    deadline = Date.now() + timeoutMs;
+    codexHome = fs.realpathSync(codexHome); cwd = fs.realpathSync(cwd); releasedPluginRoot = fs.realpathSync(releasedPluginRoot);
+    target = readSurface(releasedPluginRoot); identity = nativeBinary(binary, env); remaining();
+    const published = publishedIdentity || await verifyPublished({ version: expectedVersion, timeoutMs: remaining() });
+    const anchor = published.releaseIdentity;
+    if (published.state !== 'verified' || anchor?.version !== expectedVersion
+      || anchor.hooksSha256 !== target.hashes['hooks/codex-hooks.json']) throw new Error('Released hook declarations are not independently verified');
+    const managedRoot = path.join(codexHome, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain', expectedVersion);
+    const nativeVersion = (await command(['--version'])).trim();
+    if (!/^codex-cli \S+$/.test(nativeVersion)) throw new Error('Native Codex version is unavailable');
+    const inventory = async () => {
+      const listed = JSON.parse(await command(['plugin', 'list', '--json']));
+      if (!Array.isArray(listed?.installed)) throw new Error('Native plugin inventory is unavailable');
+      const rows = listed.installed.filter((row) => row?.pluginId === OWNER);
+      if (rows.length !== 1) throw new Error('Brain plugin inventory is missing or duplicated');
+      return rows[0];
+    };
+    const before = await inventory();
+    const beforeSurface = readSurface(fs.realpathSync(managedRoot));
+    if (JSON.stringify(beforeSurface.hashes) !== JSON.stringify(target.hashes)) throw new Error('Installed declarations differ from the independent released target');
+    const listed = await new Promise((resolve, reject) => {
+      const child = own(['app-server', '--listen', 'stdio://']); let buffer = ''; let done = false; let phase = 1; let observed;
+      const finish = (error, value) => { if (done) return; done = true; clearTimeout(timer); error ? reject(error) : resolve(value); };
+      const timer = setTimeout(() => finish(new Error('Fresh declaration proof deadline exceeded')), remaining());
+      const send = (message) => child.stdin.write(`${JSON.stringify(message)}\n`);
+      child.on('error', () => finish(new Error('Fresh native metadata process failed')));
+      child.once('exit', () => finish(new Error('Fresh native metadata process exited before proof')));
+      child.stderr.on('data', (chunk) => { try { consume(chunk); } catch (error) { finish(error); } });
+      child.stdout.on('data', (chunk) => {
+        try {
+          consume(chunk); buffer += chunk;
+          while (!done && buffer.includes('\n')) {
+            const end = buffer.indexOf('\n'); const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+            const row = JSON.parse(line); if (row.id !== phase) continue;
+            if (row.error) throw new Error('Native metadata proof was refused');
+            if (phase === 1) { phase = 2; send({ method: 'initialized' }); send({ id: 2, method: 'hooks/list', params: { cwds: [cwd] } }); }
+            else if (phase === 2) { observed = row.result; phase = 3; send({ id: 3, method: 'hooks/list', params: { cwds: [cwd] } }); }
+            else if (JSON.stringify(observed) !== JSON.stringify(row.result)) throw new Error('Native registry changed during proof');
+            else finish(null, row.result);
+          }
+        } catch (error) { finish(error); }
+      });
+      send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'rnb_fresh_declarations_doctor', version: '1' }, capabilities: { experimentalApi: true } } });
+    });
+    const after = await inventory();
+    if (JSON.stringify(before) !== JSON.stringify(after) || JSON.stringify(readSurface(managedRoot).hashes) !== JSON.stringify(beforeSurface.hashes)
+      || JSON.stringify(readSurface(releasedPluginRoot).hashes) !== JSON.stringify(target.hashes)
+      || nativeBinary(identity.path, env).sha256 !== identity.sha256 || (await command(['--version'])).trim() !== nativeVersion) throw new Error('Plugin, native binary, or released source changed during proof');
+    remaining();
+    return { ...classifyFreshCodexDeclarations({ plugin: after, listed, target, expectedVersion, codexHome, cwd }),
+      publishedRelease: anchor, nativeBinary: identity.path, nativeBinarySha256: identity.sha256, nativeVersion, codexHome, cwd, totalOutputBytes: totalBytes };
+  } catch (error) { return failed(error instanceof SyntaxError ? 'Native metadata or released source is malformed' : error.message); }
+  finally {
+    // Never contact or terminate a shared daemon. Retire only children created by this proof.
+    const retired = await Promise.all([...children].map(async ([child, exited]) => {
+      const stopped = () => child.exitCode !== null || child.signalCode !== null;
+      if (stopped()) return true;
+      const wait = async () => {
+        let timer;
+        try { await Promise.race([exited, new Promise((resolve) => {
+          timer = setTimeout(resolve, Math.max(0, Math.min(250, deadline - Date.now())));
+        })]); } finally { clearTimeout(timer); }
+      };
+      child.stdin.destroy();
+      try { child.kill('SIGTERM'); } catch { /* bounded second attempt below */ }
+      await wait();
+      if (!stopped()) { try { child.kill('SIGKILL'); } catch { /* report unverified retirement */ } await wait(); }
+      if (!stopped()) {
+        // A referenced ChildProcess or pipe can keep the doctor CLI alive after this promise returns.
+        child.stdout.destroy(); child.stderr.destroy(); child.unref?.();
+        return false;
+      }
+      return true;
+    }));
+    if (retired.includes(false)) return { ...failed('Owned native proof child retirement is unverified'),
+      unverifiedOwnedChildPids: [...children.keys()].filter((_child, index) => retired[index] === false).map((child) => child.pid).filter(Number.isSafeInteger) };
+  }
+}