ruvnet-brain 4.5.6 → 4.5.8

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

@@ -0,0 +1,60 @@
+// Operator containment only (#390 B). No store, checkpoint, event, turn or search is disabled here.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+const suspendedResults = new WeakSet();
+export function progressionSuspensionFile(env = process.env) {
+  return path.join(env.RUVNET_BRAIN_STATE_DIR || path.join(env.HOME || os.homedir(), '.config', 'ruvnet-brain'), 'brain-progression-suspension');
+}
+export function operatorProgressionSuspension(env = process.env) {
+  if (env.RUVNET_BRAIN_PROGRESSION_SUSPENDED === '1') return { source: 'environment' };
+  if (env.RUVNET_BRAIN_PROGRESSION_SUSPENDED && env.RUVNET_BRAIN_PROGRESSION_SUSPENDED !== '0') {
+    throw new Error('invalid automatic progression suspension environment setting');
+  }
+  let value;
+  try { value = JSON.parse(fs.readFileSync(progressionSuspensionFile(env), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw new Error('automatic progression suspension policy unreadable or invalid'); }
+  if (value?.schemaVersion !== 1 || typeof value.suspended !== 'boolean') {
+    throw new Error('automatic progression suspension policy unreadable or invalid');
+  }
+  return value.suspended ? { source: 'operator-state' } : null;
+}
+export function automaticProgressionSuspensionResult(env = process.env, fields = {}) {
+  const control = operatorProgressionSuspension(env);
+  if (!control) return null;
+  const result = Object.freeze({ ...fields, progressionSuspended: true, progressionCaptured: false,
+    receipt: null, skipped: 'operator suspended automatic project progression', suspensionSource: control.source });
+  suspendedResults.add(result);
+  return result;
+}
+// A look-alike public flag is never authority to bypass an unexpected capture failure.
+export const isAutomaticProgressionSuspension = (result) => Boolean(result && suspendedResults.has(result));
+
+/** Explicit operator configuration: replacing this control file never touches evidence or queues. */
+export function setOperatorProgressionSuspension(suspended, { env = process.env } = {}) {
+  if (typeof suspended !== 'boolean') throw new TypeError('suspended must be a boolean');
+  const file = progressionSuspensionFile(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, suspended }), { flag: 'wx', mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally { try { fs.unlinkSync(temporary); } catch { /* renamed or not created */ } }
+  return operatorProgressionSuspension(env);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const argv = process.argv.slice(2);
+    if (argv.length !== 1 || !['--suspend', '--resume', '--status'].includes(argv[0])) {
+      throw new Error('usage: project-progression-suspension.mjs --suspend | --resume | --status');
+    }
+    if (argv[0] !== '--status') setOperatorProgressionSuspension(argv[0] === '--suspend');
+    const control = operatorProgressionSuspension();
+    console.log(JSON.stringify({ automaticProgression: control ? 'operator-suspended' : 'enabled', source: control?.source || null,
+      evidencePreserved: true, explicitCheckpointsAvailable: true }));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/plugin/scripts/project-transition-hook.mjs

@@ -5,9 +5,11 @@ import crypto from 'node:crypto';
 import os from 'node:os';
 import { developmentHooksSuspended } from './development-maintenance.mjs';
 import { resolveTurnDb } from './turn-outcome-capture.mjs';
+import { automaticProgressionSuspensionResult } from './project-progression-suspension.mjs';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { redactText } from './continuity-events.mjs';
+import { conditionNotice } from './continuity-journal.mjs';
 import { normalizeHostEvent } from './hook-input.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { withProgressionReader } from './project-progression-reader.mjs';
@@ -148,7 +150,9 @@ export function observeTransitionSource(resolution, projectDir = resolution.chec
 
 /** Called only by the fenced queue drainer; current heads merge, original observations stay fixed. */
 export function captureNormalizedTransition(job, { readHistory = readTransitionHistory, capture = runSessionSnapshotHook,
-  budgetMs = 6500, makeStoreFactory, now = Date.now } = {}) {
+  budgetMs = 6500, makeStoreFactory, now = Date.now, env = process.env } = {}) {
+  const suspended = automaticProgressionSuspensionResult(env);
+  if (suspended) return suspended;
   const deadlineAt = now() + budgetMs;
   const resolution = resolveProjectStore({ projectDir: job.originProjectDir, gitTimeoutMs: Math.max(1, Math.min(500, budgetMs)) });
   const normalized = job.payload.normalizedTransition;
@@ -173,7 +177,7 @@ export function captureNormalizedTransition(job, { readHistory = readTransitionH
   const progression = buildRestoredTransitionProgression({ resolution, observation: normalized.observation,
     snapshots, sessionIdentity: job.payload.session_id, host: job.host,
     sourceIdentity: normalized.sourceIdentity }, restored);
-  const result = capture(job.originProjectDir, job.event, { host: job.host, budgetMs: Math.max(0, deadlineAt - now()),
+  const result = capture(job.originProjectDir, job.event, { host: job.host, env, budgetMs: Math.max(0, deadlineAt - now()),
     ...(makeStoreFactory ? { makeStoreFactory } : {}), writeMetadata: false,
     rawInput: JSON.stringify({ session_id: job.payload.session_id, hook_event_name: job.event, projectProgression: progression }),
     captureTurn: () => ({ recorded: false, skipped: 'transition boundary' }),
@@ -184,6 +188,8 @@ export function captureNormalizedTransition(job, { readHistory = readTransitionH
 export function runProjectTransitionHook(projectDir, event, { payload = {}, host = process.env.RUVNET_HOOK_HOST || 'claude',
   readHistory = readTransitionHistory, capture = runSessionSnapshotHook, env = process.env } = {}) {
   if (developmentHooksSuspended(projectDir)) return { state: 'skipped', reason: 'development hooks suspended' };
+  const suspended = automaticProgressionSuspensionResult(env, { state: 'suspended', reason: 'automatic project progression is operator-suspended' });
+  if (suspended) return suspended;
   const observation = normalizeTransition(payload, event, { host });
   if (observation.skipped) return { state: 'skipped', reason: observation.skipped };
   const brainHome = env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
@@ -194,22 +200,33 @@ export function runProjectTransitionHook(projectDir, event, { payload = {}, host
   const transportEvent = event === 'PostToolUseFailure' ? 'PostToolUse' : event;
   // Fsync the selected observation BEFORE any history enumeration/merge. A deadline, corruption,
   // or long-lived project must leave it pending rather than erase it or fabricate root ancestry.
-  const queued = queueCapture({ projectDir: resolution.projectRoot, originProjectDir: projectDir, event: transportEvent, host,
+  const queued = queueCapture({ projectDir: resolution.projectRoot, originProjectDir: projectDir, env, event: transportEvent, host,
     payload: { session_id: payload.session_id, hook_event_name: transportEvent,
       normalizedTransition: { observation, sourceIdentity: observeTransitionSource(resolution, projectDir) } } });
   if (!queued) return { state: 'degraded', reason: 'normalized observation queue unwritable', eventId: observation.id };
   let result = null;
-  runOutboxReplay({ projectDir: resolution.projectRoot, budgetMs: Math.min(6500, effectiveBudgetMs(env)),
-    captureNormalized: (job, options) => captureNormalizedTransition(job, { ...options, readHistory, capture }),
+  runOutboxReplay({ projectDir: resolution.projectRoot, env, budgetMs: Math.min(6500, effectiveBudgetMs(env)),
+    captureNormalized: (job, options) => captureNormalizedTransition(job, { ...options, env, readHistory, capture }),
     onCaptured: (captured) => { if (captured?.eventId === observation.id) result = captured; } });
-  if (!result?.receipt) replayOutboxDetached({ projectDir: resolution.projectRoot });
+  if (!result?.receipt) replayOutboxDetached({ projectDir: resolution.projectRoot, env });
   return { state: result?.progressionCaptured && result.receipt ? 'committed' : 'pending', eventId: observation.id, result };
 }
 
+/** One pending-readback condition across prompt/tool boundaries and both CLI entrypoints. */
+export function transitionPendingNotice(projectDir, payload, message) {
+  const { projectRoot } = resolveProjectStore({ projectDir, gitTimeoutMs: 500 });
+  return conditionNotice({ swarm: path.join(projectRoot, '.swarm'),
+    session: normalizeHostEvent(payload)?.session_id, condition: 'project-transition-pending-readback', message });
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     const payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
-    const result = runProjectTransitionHook(payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd(), process.argv[2], { payload });
-    if (result.state === 'pending') process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: process.argv[2], additionalContext: 'Project memory transition is pending; exact AgentDB readback was not verified at this boundary.' } }));
+    const projectDir = payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const result = runProjectTransitionHook(projectDir, process.argv[2], { payload });
+    if (result.state === 'pending') {
+      const message = transitionPendingNotice(projectDir, payload, 'Project memory transition is pending; exact AgentDB readback was not verified at this boundary.');
+      if (message) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: process.argv[2], additionalContext: message } }));
+    }
   } catch { process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition capture degraded; exact readback was not verified.' })); }
 }

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-snapshot-hook.mjs

@@ -17,6 +17,7 @@ import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { resolveTurnDb, captureTurnOutcome } from './turn-outcome-capture.mjs';
 import { captureContinuityEvents, stopNotice } from './continuity-journal.mjs';
+import { automaticProgressionSuspensionResult } from './project-progression-suspension.mjs';
 
 /**
  * The capture boundary's whole budget. hooks.json declares 10s; this keeps the internal work well
@@ -158,6 +159,8 @@ export function runSessionSnapshotHook(projectDir, event, {
     continuity = { recorded: 0, skipped: `continuity capture failed: ${error.message}` };
   }
   const idle = { metadataWritten, progressionCaptured: false, receipt: null, turn, continuity };
+  const operatorSuspended = automaticProgressionSuspensionResult(env, idle);
+  if (operatorSuspended) return operatorSuspended;
 
   if (hasProjectProgression(payload)) {
     if (payload.hook_event_name !== event) {
@@ -206,7 +209,7 @@ export function runSessionSnapshotHook(projectDir, event, {
     try { frozen = produce({ resolution, projectDir, payload, host, trigger: event }); } catch { frozen = null; }
     const queued = frozen?.projectProgression ? queueCapture({ projectDir: root, originProjectDir: projectDir, env, event, host,
       payload: { session_id: payload.session_id, hook_event_name: event, projectProgression: frozen.projectProgression } }) : null;
-    const handed = queued ? spawnReplay({ projectDir: root, token }) : false;
+    const handed = queued ? spawnReplay({ projectDir: root, token, env }) : false;
     if (!handed && token && token !== ordered) releaseReplayLock(root, token);
     return { ...idle, replayed: 0, progressionCaptured: false, deferredToReplayer: Boolean(queued),
       replaySkipped: `${why}; this capture ${queued ? 'queued behind it' : 'NOT queued (queue unwritable)'}`
@@ -262,7 +265,7 @@ export function runSessionSnapshotHook(projectDir, event, {
       // NOT LOST — DEFERRED. capture() fsyncs the snapshot to the durable outbox BEFORE it writes to
       // the store, so a budget overrun leaves the evidence on disk. On a short budget nothing later in
       // this process can settle it, so the lock goes straight to a detached worker.
-      handedLock = !ordered && budgetMs < REPLAY_MIN_BUDGET_MS && pendingCount() > 0 && spawnReplay({ projectDir: root, token });
+      handedLock = !ordered && budgetMs < REPLAY_MIN_BUDGET_MS && pendingCount() > 0 && spawnReplay({ projectDir: root, token, env });
       return { ...idle, replayed, skipped: `capture deferred: ${error.message}`,
         ...(handedLock ? { replaySkipped: 'deferred capture handed to a detached worker' } : {}) };
     }
@@ -281,9 +284,9 @@ export function runSessionSnapshotHook(projectDir, event, {
     // simultaneous SessionEnds lost the second one's final state (4.4.1). So: queued work → hand THIS
     // lock to a worker; and re-check after releasing, for a boundary that queued in between.
     if (!ordered && !handedLock) {
-      if (!(queuedWork(root) && spawnReplay({ projectDir: root, token }))) {
+      if (!(queuedWork(root) && spawnReplay({ projectDir: root, token, env }))) {
         releaseReplayLock(root, token);
-        if (queuedWork(root)) spawnReplay({ projectDir: root });
+        if (queuedWork(root)) spawnReplay({ projectDir: root, env });
       }
     }
   }
@@ -297,10 +300,14 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-
   // Finish evaluating this module before importing its transition consumer.
   void (async () => {
   try {
-    const { runProjectTransitionHook } = await import('./project-transition-hook.mjs');
+    const { runProjectTransitionHook, transitionPendingNotice } = await import('./project-transition-hook.mjs');
     const payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}');
-    const result = runProjectTransitionHook(payload.cwd || projectDirectory(), process.argv[2], { payload });
-    if (result.state === 'pending') process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition remains pending; exact readback was not verified.' }));
+    const projectDir = payload.cwd || projectDirectory();
+    const result = runProjectTransitionHook(projectDir, process.argv[2], { payload });
+    if (result.state === 'pending') {
+      const message = transitionPendingNotice(projectDir, payload, 'Project memory transition remains pending; exact readback was not verified.');
+      if (message) process.stdout.write(JSON.stringify({ systemMessage: message }));
+    }
   } catch { process.stdout.write(JSON.stringify({ systemMessage: 'Project memory transition capture degraded; exact readback was not verified.' })); }
   })();
 } else if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {

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/plugin/scripts/turn-outcome-capture.mjs

@@ -110,10 +110,12 @@ export function claudeTurn(lines) {
 }
 
 function readTail(file, bytes = TRANSCRIPT_TAIL_BYTES) {
-  const size = fs.statSync(file).size;
-  const offset = Math.max(0, size - bytes);
   const handle = fs.openSync(file, 'r');
   try {
+    const stat = fs.fstatSync(handle);
+    if (!stat.isFile()) throw new Error('Transcript must be a regular file');
+    const size = stat.size;
+    const offset = Math.max(0, size - bytes);
     const buf = Buffer.alloc(size - offset);
     fs.readSync(handle, buf, 0, buf.length, offset);
     const lines = buf.toString('utf8').split(/\r?\n/);
@@ -128,7 +130,9 @@ export function readSettledTranscript(file, { stableMs = 400, maxMs = 2000, slee
   const deadline = Date.now() + Math.max(0, maxMs);
   let size = -1;
   for (;;) {
-    const now = fs.statSync(file).size;
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error('Transcript must be a regular file');
+    const now = stat.size;
     if (now === size || Date.now() >= deadline) break;
     size = now;
     pause(Math.min(stableMs, Math.max(0, deadline - Date.now())));

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) };
+  }
+}