ruvnet-brain 4.5.3 → 4.5.5

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

@@ -31,9 +31,8 @@
  *
  * LATENCY: Stop runs synchronously in the host's turn, and one `ruflo memory store` costs ~0.7s
  * (measured). So the writes run in ONE detached worker (this file, `--run-steps`), store then
- * distill in order; the hook itself only reads, fingerprints and spawns. A breadcrumb line is
- * containing only key, hash and length is appended BEFORE the spawn; exact readback receipts make a lost
- * write is visible rather than silent. Advisory always: nothing here throws to the caller.
+ * distill in order; the hook itself only reads, fingerprints and spawns. A project-local journal containing redacted content and canonical binding is fsynced BEFORE
+ * spawning; fresh sessions replay stable keys without upsert and require exact readback receipts. Advisory always: nothing here throws to the caller.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -44,6 +43,7 @@ import { fileURLToPath } from 'node:url';
 import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
 import { redactText, userLevelAgentdbHooks } from './continuity-events.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
+import { digest, journalTurn, readJournal, pendingTurnFiles, acknowledgeJournal, appendReceipt, storeData } from './turn-transport-journal.mjs';
 
 export const TURN_NAMESPACE = 'turns';
 export const MIN_OUTCOME_CHARS = 200;
@@ -154,8 +154,9 @@ const consentMap = (value) => value !== null && typeof value === 'object'
   && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
   && Object.values(value).every((setting) => setting === 'on' || setting === 'off');
 
-export function resolveTurnDb({ projectDir, brainHome, requestedStorePath, gitTimeoutMs = 1000 } = {}) {
+export function resolveTurnDb({ projectDir, brainHome, requestedStorePath, gitTimeoutMs = 1000, unknownOriginalPath = false } = {}) {
   const resolved = resolveProjectStore({ projectDir, requestedStorePath, gitTimeoutMs });
+  const capturePath = fs.realpathSync.native(projectDir);
   let policy = {};
   const file = brainHome && turnCapturePolicyFile(brainHome);
   if (file && fs.existsSync(file)) {
@@ -166,15 +167,19 @@ export function resolveTurnDb({ projectDir, brainHome, requestedStorePath, gitTi
     } catch { return { skipped: 'turn capture policy unreadable or invalid', projectRoot: resolved.projectRoot }; }
   }
   // A path rule wins over a project rule, allowing a linked checkout/subdirectory to opt out.
-  const setting = policy.paths?.[fs.realpathSync.native(projectDir)] ?? policy.projects?.[resolved.projectRoot];
+  const setting = policy.paths?.[capturePath] ?? policy.projects?.[resolved.projectRoot];
   if (setting !== undefined && !['on', 'off'].includes(setting)) return { skipped: 'invalid turn capture consent', projectRoot: resolved.projectRoot };
   const db = resolved.canonicalAgentDbPath;
+  if (unknownOriginalPath && Object.entries(policy.paths || {}).some(([origin, choice]) => choice === 'off'
+    && (origin === resolved.checkoutRoot || origin.startsWith(`${resolved.checkoutRoot}${path.sep}`)))) {
+    return { db, scope: 'project', capturePath, projectRoot: resolved.projectRoot, skipped: 'capture origin cannot be verified under path opt-out' };
+  }
   assertTurnStoreFiles(db);
-  if (setting === 'off') return { db, scope: 'project', projectRoot: resolved.projectRoot, skipped: 'persisted turn capture opt-out' };
+  if (setting === 'off') return { db, scope: 'project', capturePath, projectRoot: resolved.projectRoot, skipped: 'persisted turn capture opt-out' };
   let exists = false;
   try { exists = fs.statSync(db).isFile(); } catch { /* absent */ }
-  if (!exists && setting !== 'on') return { db, scope: 'project', projectRoot: resolved.projectRoot, skipped: 'no project memory db; persisted opt-in required' };
-  return { db, scope: 'project', projectRoot: resolved.projectRoot, optedIn: setting === 'on' };
+  if (!exists && setting !== 'on') return { db, scope: 'project', capturePath, projectRoot: resolved.projectRoot, skipped: 'no project memory db; persisted opt-in required' };
+  return { db, scope: 'project', capturePath, projectRoot: resolved.projectRoot, optedIn: setting === 'on' };
 }
 
 // Revalidation narrows the queue-to-launch window; it does not make SQLite's later open atomic.
@@ -197,9 +202,9 @@ function assertTurnStoreFiles(db) {
 const projectName = (projectDir) => redactText(path.basename(path.resolve(projectDir))).replace(/[^A-Za-z0-9._-]/g, '_') || 'project';
 
 /** Detached worker launch: the hook returns immediately; the worker runs the steps in order. */
-export function launchDetached(steps, { receipts }) {
-  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--run-steps', JSON.stringify({ steps, receipts })], {
-    cwd: os.tmpdir(), detached: true, stdio: 'ignore', windowsHide: true, env: { ...process.env, ...RUFLO_ENV },
+export function launchDetached(steps, { receipts, brainHome, projectDir, env = process.env }) {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--run-steps', JSON.stringify({ steps: steps.map((step) => step.kind === 'store' && step.journalFile ? { kind: 'journal', journalFile: step.journalFile, db: step.args[step.args.indexOf('--path') + 1] } : step), receipts })], {
+    cwd: os.tmpdir(), detached: true, stdio: 'ignore', windowsHide: true, env: { ...env, ...RUFLO_ENV, ...(brainHome ? { RUVNET_BRAIN_HOME: brainHome } : {}), ...(projectDir ? { RUVNET_TURN_PROJECT_DIR: projectDir } : {}) },
   });
   child.unref();
   return { launched: true, pid: child.pid };
@@ -257,7 +262,8 @@ export function captureTurnOutcome({
   Object.assign(report, { db, scope });
   if (target.skipped) return { ...report, skipped: target.skipped, distill: { queued: false, skipped: target.skipped } };
   const steps = [];
-  const binding = { projectRoot, projectDir: fs.realpathSync.native(projectDir), brainHome };
+  const rootStat = fs.statSync(projectRoot);
+  const binding = { projectRoot, projectDir: fs.realpathSync.native(projectDir), brainHome, rootIdentity: `${rootStat.dev}:${rootStat.ino}` };
   let dedupe;
   const project = projectName(projectRoot);
   const receipts = path.join(brainHome, 'turn-capture', 'receipts.jsonl');
@@ -292,11 +298,17 @@ export function captureTurnOutcome({
       if (sameTurnSeen(stateFile, identity, fingerprint, receipts)) report.skipped = 'same turn outcome already queued or verified';
       else {
         const at = now();
-        const key = `turn-${project}-${at.getTime()}-${crypto.randomBytes(6).toString('hex')}`;
+        const key = `turn-${project}-${digest(`${identity}:${fingerprint}`).slice(0, 40)}`;
         dedupe = { stateFile, identity, fingerprint, key };
-        const value = buildTurnRecord({ turn, project, host, session: payload.session_id, at });
+        let value = buildTurnRecord({ turn, project, host, session: payload.session_id, at });
+        // Retry uses the original durable content (including its timestamp), never a new value.
+        const pendingFile = path.join(path.dirname(db), 'turn-outbox', `${digest(key)}.json`);
+        if (fs.existsSync(pendingFile)) {
+          try { const pending = readJournal(pendingFile, db); value = pending.value; }
+          catch (error) { return { ...report, skipped: `durable turn queue invalid: ${redactText(error.message)}` }; }
+        }
         steps.push({ ...binding, kind: 'store', ruflo, args: ['memory', 'store', '-k', key, '--value', value, '-n', TURN_NAMESPACE,
-          '--path', db, '--tags', `project=${project},host=${host}`, '--provenance', 'agent_output'] });
+          '--path', db, '--no-upsert', '--tags', `project=${project},host=${host}`, '--provenance', 'agent_output'] });
         // This synchronous boundary proves only queuing; the worker's exact receipt proves recording.
         Object.assign(report, { queued: true, key, value });
       }
@@ -316,10 +328,12 @@ export function captureTurnOutcome({
     // Only explicit persisted consent permits creating a project store directory.
     if (target.optedIn) fs.mkdirSync(path.dirname(db), { recursive: true, mode: 0o700 });
     if (report.queued) {
+      const step = steps.find((item) => item.kind === 'store');
+      step.journalFile = journalTurn(step, db, report.key, { onDurability: (evidence) => { report.durability = evidence; } });
       fs.appendFileSync(path.join(path.dirname(db), 'agentdb-turns.jsonl'),
         `${JSON.stringify({ ts: Date.now(), key: report.key, hash: crypto.createHash('sha256').update(report.value).digest('hex'), len: report.value.length })}\n`, { mode: 0o600 });
     }
-    report.launch = launch(steps, { receipts });
+    report.launch = launch(steps, { receipts, brainHome, projectDir: binding.projectDir, env });
     if (dedupe) markTurnQueued(dedupe.stateFile, dedupe.identity, dedupe.fingerprint, dedupe.key);
   } catch (error) {
     return { ...report, queued: false, recorded: false, distill: { queued: false, skipped: `launch failed: ${redactText(error.message)}` }, skipped: `launch failed: ${redactText(error.message)}` };
@@ -335,48 +349,106 @@ function readBack({ ruflo, db, key, run, options }) {
 }
 
 /** The detached worker: bounded steps, safe error evidence, exact content readback. */
-export function runSteps({ steps = [], receipts } = {}, { run = spawnSync, read = readBack, env = process.env } = {}) {
+export function runSteps({ steps = [], receipts } = {}, { run: suppliedRun = spawnSync, read = readBack,
+  env = process.env, deadlineMs, home = os.homedir(),
+  projectDir = env.RUVNET_TURN_PROJECT_DIR || process.cwd(),
+  brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain') } = {}) {
+  const run = (binary, args, options) => {
+    if (deadlineMs === undefined) return suppliedRun(binary, args, options);
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0) return { status: 1, error: new Error('turn replay deadline exhausted') };
+    return suppliedRun(binary, args, { ...options, timeout: Math.min(options.timeout, remaining) });
+  };
   const results = [];
-  for (const step of steps) {
-    let status = null; let error = null; let verified = false;
-    const args = [...step.args];
-    const db = args[args.indexOf(step.kind === 'store' ? '--path' : '--db') + 1];
-    const key = step.kind === 'store' ? args[args.indexOf('-k') + 1] : undefined;
-    const valueIndex = args.indexOf('--value') + 1;
-    if (step.kind === 'store') args[valueIndex] = redactText(args[valueIndex]);
+  for (const queued of steps) {
+    let status = 1; let error = null; let verified = false; let db = ''; let key;
+    const kind = queued.kind === 'journal' ? 'store' : queued.kind;
     try {
-      if (!step.projectRoot || !step.projectDir || !step.brainHome) throw new Error('queued step has no canonical project binding');
-      const target = resolveTurnDb({ projectDir: step.projectDir, brainHome: step.brainHome, requestedStorePath: db, gitTimeoutMs: 1000 });
-      if (target.skipped) throw new Error(target.skipped);
-      if (target.projectRoot !== step.projectRoot || target.db !== db) throw new Error('queued canonical project/store identity changed');
       if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') throw new Error('RUVNET_TURN_CAPTURE=off');
-      const invocation = rufloInvocation(step.ruflo, args);
-      // Contain Ruflo's auxiliary writes in the canonical store's own directory.
-      const home = path.dirname(db);
-      const options = { encoding: 'utf8', timeout: STEP_TIMEOUT_MS, cwd: home, windowsHide: true,
-        maxBuffer: 1024 * 1024, env: { ...env, ...RUFLO_ENV, CLAUDE_FLOW_MEMORY_PATH: home } };
-      const r = run(invocation.executable, invocation.args, options);
+      if (kind === 'store' && queued.kind !== 'journal') { const data = storeData(queued); key = data.key; db = data.db; }
+      if (queued.kind !== 'journal' && (!queued.projectRoot || !queued.projectDir || !queued.brainHome)) throw new Error('queued step has no canonical project binding');
+      const target = resolveTurnDb({ projectDir, brainHome, gitTimeoutMs: 1000 });
+      if (target.skipped) throw new Error(target.skipped);
+      db = target.db;
+      let args; let value; let binding;
+      if (kind === 'store') {
+        const data = queued.kind === 'journal' ? readJournal(queued.journalFile, db) : storeData(queued);
+        if (queued.kind === 'journal' && queued.db !== db) throw new Error('foreign turn queue store rejected');
+        if (queued.kind !== 'journal' && data.db !== db) throw new Error('foreign turn store rejected');
+        if (data.legacyBrainHome && data.legacyBrainHome !== brainHome) throw new Error('queued consent settings differ from trusted caller');
+        if (queued.kind !== 'journal' && queued.brainHome !== brainHome) throw new Error('queued consent settings differ from trusted caller');
+        binding = queued.kind === 'journal' ? data.binding : queued;
+        key = data.key; value = redactText(data.value);
+        args = ['memory', 'store', '-k', key, '--value', value, '-n', TURN_NAMESPACE, '--path', db, '--no-upsert', '--provenance', 'agent_output'];
+      } else if (kind === 'distill') {
+        if (queued.brainHome !== brainHome) throw new Error('queued consent settings differ from trusted caller');
+        const recipe = queued.args;
+        if (!Array.isArray(recipe) || recipe.slice(0, 3).join(' ') !== 'memory distill run') throw new Error('invalid turn distill operation');
+        const seen = new Set();
+        for (let i = 3; i < recipe.length; i += 2) {
+          const flag = recipe[i]; const value = recipe[i + 1];
+          if (seen.has(flag) || !['--db', '--namespace', '--max-entries'].includes(flag) || typeof value !== 'string') throw new Error('invalid turn distill flags');
+          seen.add(flag);
+          if (flag === '--db' && value !== db || flag === '--namespace' && value !== TURN_NAMESPACE || flag === '--max-entries' && value !== '500') throw new Error('invalid turn distill scope');
+        }
+        if (!seen.has('--db')) throw new Error('missing turn distill database');
+        binding = queued;
+        args = ['memory', 'distill', 'run', '--db', db, '--namespace', TURN_NAMESPACE, '--max-entries', '500'];
+      } else throw new Error('invalid turn worker operation');
+      if (!binding.projectRoot || !binding.projectDir) throw new Error('queued step has no canonical project binding');
+      const rootStat = fs.statSync(target.projectRoot);
+      if (binding.rootIdentity && binding.rootIdentity !== `${rootStat.dev}:${rootStat.ino}`) throw new Error('queued canonical project identity changed');
+      if (binding.projectRoot !== target.projectRoot) throw new Error('queued canonical project/store identity changed');
+      const origin = resolveTurnDb({ projectDir: binding.projectDir, brainHome, requestedStorePath: db, gitTimeoutMs: 1000 });
+      if (origin.skipped) throw new Error(origin.skipped);
+      if (origin.projectRoot !== target.projectRoot || origin.db !== db) throw new Error('queued canonical capture origin changed');
+      const ruflo = resolveRuflo({ env, home });
+      if (!ruflo) throw new Error('ruflo not found for durable replay');
+      const invocation = rufloInvocation(ruflo, args);
+      const remaining = deadlineMs === undefined ? STEP_TIMEOUT_MS : deadlineMs - Date.now();
+      if (remaining <= 0) throw new Error('turn replay deadline exhausted');
+      const options = { encoding: 'utf8', timeout: Math.min(STEP_TIMEOUT_MS, remaining), cwd: path.dirname(db), windowsHide: true,
+        maxBuffer: 1024 * 1024, env: { ...env, ...RUFLO_ENV, CLAUDE_FLOW_MEMORY_PATH: path.dirname(db) } };
+      const existing = kind === 'store' && queued.journalFile ? read({ ruflo, db, key, run, options }) : null;
+      if (existing !== null && existing !== value) throw new Error('existing turn key content differs; no upsert permitted');
+      verified = kind === 'store' && existing === value;
+      const r = verified ? { status: 0 } : run(invocation.executable, invocation.args, options);
       status = Number.isInteger(r.status) ? r.status : 1;
-      if (r.error || status !== 0) error = redactText(r.error?.message || String(r.stderr || '').trim().split(/\r?\n/)[0] || `ruflo exited ${status}`).slice(0, 300);
-      else if (step.kind === 'store') {
-        verified = read({ ruflo: step.ruflo, db, key, run, options }) === args[valueIndex];
-        if (!verified) { status = 1; error = 'exact turn key/content readback failed'; }
-      }
+      if (kind === 'store' && !verified) verified = read({ ruflo, db, key, run, options }) === value;
+      if (verified) status = 0;
+      if (!verified && (r.error || status !== 0)) error = redactText(r.error?.message || String(r.stderr || '').trim().split(/\r?\n/)[0] || `ruflo exited ${status}`).slice(0, 300);
+      else if (kind === 'store' && !verified) { status = 1; error = 'exact turn key/content readback failed'; }
     } catch (e) { status = 1; error = redactText(e.message).slice(0, 300); }
-    const row = { at: new Date().toISOString(), kind: step.kind, db: redactText(db),
-      storeIdentity: crypto.createHash('sha256').update(db).digest('hex'), key, status, error,
-      ...(step.kind === 'store' ? { verified } : {}) };
+    const row = { at: new Date().toISOString(), kind, db: redactText(db), storeIdentity: digest(db), key, status, error,
+      ...(kind === 'store' ? { verified } : {}) };
     results.push(row);
     if (receipts) {
-      try {
-        fs.mkdirSync(path.dirname(receipts), { recursive: true, mode: 0o700 });
-        fs.appendFileSync(receipts, `${JSON.stringify(row)}\n`, { mode: 0o600 });
-      } catch { /* receipts are best effort */ }
+      try { appendReceipt(receipts, row); if (verified && queued.journalFile) acknowledgeJournal(queued.journalFile, db); }
+      catch { /* failed receipt persistence retains the journal for exact-key retry */ }
     }
   }
   return results;
 }
 
+/** Replay only bounded canonical project entries; consent suspends rather than deletes them. */
+export function replayTurnQueue({ projectDir = process.cwd(), env = process.env, home = os.homedir(),
+  brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain'), limit = 10,
+  launch = launchDetached, synchronous = false, runner, deadlineMs } = {}) {
+  if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') return { queued: false, skipped: 'RUVNET_TURN_CAPTURE=off' };
+  try {
+    const target = resolveTurnDb({ projectDir, brainHome });
+    if (target.skipped) return { queued: false, skipped: target.skipped };
+    const steps = pendingTurnFiles(target.db, limit).map((journalFile) => ({ kind: 'journal', journalFile, db: target.db }));
+    if (!steps.length) return { queued: false, count: 0 };
+    if (synchronous) {
+      const results = runSteps({ steps, receipts: path.join(brainHome, 'turn-capture', 'receipts.jsonl') }, { env, home, projectDir, brainHome, ...(runner ? { run: runner } : {}), deadlineMs });
+      const pending = pendingTurnFiles(target.db, 25).length;
+      return { queued: false, count: steps.length, pending, failed: results.filter((row) => row.status !== 0).length, verified: results.filter((row) => row.verified === true).length, results };
+    }
+    return { queued: true, count: steps.length, pending: steps.length, launch: launch(steps, { receipts: path.join(brainHome, 'turn-capture', 'receipts.jsonl'), projectDir, brainHome, env }) };
+  } catch (error) { return { queued: false, skipped: redactText(error.message) }; }
+}
+
 /** Bounded recent evidence, isolated by canonical db. A continuity success cannot mask turn failures. */
 export function turnRecordingStatus({ projectDir = process.cwd(), env = process.env, home = os.homedir(), now = Date.now() } = {}) {
   const brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
@@ -389,8 +461,14 @@ export function turnRecordingStatus({ projectDir = process.cwd(), env = process.
       try { return [JSON.parse(line)]; } catch { return []; }
     }).filter((r) => r.kind === 'store' && (r.storeIdentity === crypto.createHash('sha256').update(target.db).digest('hex') || r.db === target.db) && now - Date.parse(r.at) < 7 * 86_400_000).slice(-20);
   } catch { /* first run */ }
-  const failed = rows.filter((r) => r.status !== 0 || r.verified !== true);
+  rows = [...new Map(rows.map((row) => [row.key || row.at, row])).values()];
+  let pending = 0;
+  try { pending = pendingTurnFiles(target.db, 25).length; } catch { return { state: 'warn', line: 'turn recording durable queue unsafe or unreadable' }; }
+  const historical = rows.filter((r) => r.status === 0 && r.verified === undefined);
+  const failed = rows.filter((r) => r.status !== 0 || r.verified === false);
   if (failed.length) return { state: 'warn', line: `turn recording failing ${failed.length}/${rows.length} — ${redactText(failed.at(-1).error || 'write has no exact readback evidence').slice(0, 300)}` };
+  if (historical.length) return { state: 'unknown', line: `turn recording unverified historical (${historical.length} receipts without exact readback evidence)` };
+  if (pending) return { state: 'unknown', line: `turn recording pending durable replay (${pending} entries); not yet proven` };
   return rows.length ? { state: 'ok', line: `turn recording ✓ (${rows.length}/${rows.length} exact readbacks)` }
     : { state: 'unknown', line: 'turn recording not yet proven — no exact readback receipt' };
 }

package/plugin/scripts/turn-transport-journal.mjs

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const digest = (value) => crypto.createHash('sha256').update(value).digest('hex');
+export const turnQueueDirectory = (db) => path.join(path.dirname(db), 'turn-outbox');
+function regular(file, directory = false) {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || (!directory && (!stat.isFile() || stat.nlink !== 1))
+    || (directory && (!stat.isDirectory() || fs.realpathSync.native(file) !== file))) throw new Error('unsafe turn journal path');
+}
+// Node's Windows directory handles do not consistently support fsync. Never weaken
+// file fsync or hide unexpected I/O errors; a missing namespace flush is reported.
+export function syncTurnDirectory(dir, { platform = process.platform, io = fs } = {}) {
+  let fd;
+  try {
+    fd = io.openSync(dir, 'r'); io.fsyncSync(fd);
+    return { platform, directoryFsync: 'completed' };
+  } catch (error) {
+    if (platform !== 'win32' || !['EISDIR', 'EPERM', 'EACCES', 'EINVAL', 'ENOTSUP', 'EBADF'].includes(error.code)) throw error;
+    return { platform, directoryFsync: 'unavailable', reason: error.code,
+      limitation: 'file fsync remains required; directory-entry persistence across power loss is unproven' };
+  } finally { if (fd !== undefined) io.closeSync(fd); }
+}
+// Legacy recipes are data extraction inputs only, never executable commands.
+export function storeData(step) {
+  if (step?.kind !== 'store' || !Array.isArray(step.args) || step.args[0] !== 'memory' || step.args[1] !== 'store') throw new Error('invalid turn store operation');
+  const fields = {}; const aliases = { '-k': 'key', '--key': 'key', '--value': 'value', '-n': 'namespace', '--namespace': 'namespace', '--path': 'db', '--tags': 'tags', '--provenance': 'provenance' };
+  let strict = false;
+  for (let i = 2; i < step.args.length; i++) {
+    const flag = step.args[i];
+    if (flag === '--no-upsert') { if (strict) throw new Error('duplicate turn store flag'); strict = true; continue; }
+    const field = aliases[flag];
+    if (!field || Object.hasOwn(fields, field) || typeof step.args[i + 1] !== 'string') throw new Error('unknown or duplicate turn store flag');
+    fields[field] = step.args[++i];
+  }
+  if (!fields.key || typeof fields.value !== 'string' || fields.namespace !== 'turns' || !path.isAbsolute(fields.db || '')) throw new Error('invalid turn store namespace or data');
+  return { key: fields.key, value: fields.value, db: fields.db };
+}
+const bindingOf = (step) => ({ projectRoot: step.projectRoot, projectDir: step.projectDir, rootIdentity: step.rootIdentity });
+function validateBinding(binding) {
+  if (!binding || Object.keys(binding).some((key) => !['projectRoot', 'projectDir', 'rootIdentity'].includes(key))
+    || !path.isAbsolute(binding.projectRoot || '') || !path.isAbsolute(binding.projectDir || '')
+    || typeof binding.rootIdentity !== 'string' || !/^\d+:\d+$/.test(binding.rootIdentity)) throw new Error('invalid turn canonical binding');
+}
+export function journalTurn(step, db, key, { platform = process.platform, io = fs, onDurability } = {}) {
+  const dir = turnQueueDirectory(db);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); regular(dir, true);
+  const file = path.join(dir, `${digest(key)}.json`);
+  const data = storeData(step);
+  if (data.db !== db || data.key !== key) throw new Error('turn journal identity mismatch');
+  const binding = bindingOf(step); validateBinding(binding);
+  const record = { schemaVersion: 2, key, value: data.value, contentDigest: digest(data.value), consentScope: 'canonical-project-and-path', binding };
+  let created = false;
+  try {
+    const fd = io.openSync(file, 'wx', 0o600);
+    created = true;
+    try { io.writeFileSync(fd, JSON.stringify(record)); io.fsyncSync(fd); } finally { io.closeSync(fd); }
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const previous = readJournal(file, db);
+    if (previous.key !== key || previous.contentDigest !== record.contentDigest) throw new Error('turn journal identity collision');
+    // Reflush an existing complete entry: its creator may have died before fsync.
+    const fd = io.openSync(file, 'r+');
+    try { io.fsyncSync(fd); } finally { io.closeSync(fd); }
+  }
+  const evidence = { fileFsync: 'completed', entry: created ? 'created-exclusively' : 'existing-exact-match-reflushed', ...syncTurnDirectory(dir, { platform, io }) };
+  if (onDurability) onDurability(evidence);
+  return file;
+}
+export function readJournal(file, db) {
+  const dir = turnQueueDirectory(db); regular(dir, true);
+  if (path.dirname(file) !== dir) throw new Error('foreign turn journal rejected');
+  regular(file);
+  const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+  let normalized = record;
+  if (record.schemaVersion === 1) {
+    const data = storeData(record.step);
+    if (!record.step.args.includes('--no-upsert')) throw new Error('legacy turn journal requires strict insert');
+    if (data.db !== db || data.key !== record.key) throw new Error('legacy turn journal identity mismatch');
+    // Legacy job-selected consent settings are never consumed; caller policy governs replay.
+    normalized = { schemaVersion: 2, key: data.key, value: data.value, contentDigest: record.contentDigest,
+      consentScope: record.consentScope, binding: bindingOf(record.step), legacyBrainHome: record.step.brainHome };
+  } else if (Object.keys(record).some((key) => !['schemaVersion', 'key', 'value', 'contentDigest', 'consentScope', 'binding'].includes(key))) throw new Error('unknown turn journal field');
+  validateBinding(normalized.binding);
+  if (normalized.schemaVersion !== 2 || normalized.consentScope !== 'canonical-project-and-path'
+    || typeof normalized.key !== 'string' || !normalized.key.startsWith('turn-') || normalized.key.length > 250
+    || typeof normalized.value !== 'string' || normalized.value.length > 4000
+    || digest(normalized.value) !== normalized.contentDigest
+    || path.basename(file) !== `${digest(normalized.key)}.json`) throw new Error('invalid turn journal');
+  return normalized;
+}
+export function pendingTurnFiles(db, limit = 10) {
+  const dir = turnQueueDirectory(db);
+  try { regular(dir, true); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return fs.readdirSync(dir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name)).sort().slice(0, Math.min(25, Math.max(0, limit))).map((name) => path.join(dir, name));
+}
+export function acknowledgeJournal(file, db, options = {}) {
+  readJournal(file, db); fs.unlinkSync(file); return syncTurnDirectory(path.dirname(file), options);
+}
+export function appendReceipt(file, row) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  if (fs.existsSync(file)) regular(file);
+  const fd = fs.openSync(file, 'a', 0o600);
+  try { fs.writeFileSync(fd, `${JSON.stringify(row)}\n`); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}

package/scripts/codex-hook-trust-reconcile.mjs

@@ -0,0 +1,247 @@
+// Metadata-only repair. releaseIdentity is an independently verified release input owned by the
+// installer, NOT a hash/boolean synthesized from the installed file. No artifact discovery/inference.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+import { codexHookIdentities } from './codex-hook-trust.mjs';
+
+/** Authenticate exact published package bytes before reading one archive member. No extraction/install. */
+export async function obtainVerifiedPublishedHookIdentity({ version, fetch: fetcher = globalThis.fetch,
+  timeoutMs = 10000, maxTarballBytes = 32 * 1024 * 1024, tarBinary = '/usr/bin/tar' } = {}) {
+  if (!/^\d+\.\d+\.\d+$/.test(version || '') || typeof fetcher !== 'function') return blocked('Exact released version and HTTPS fetch required');
+  const deadline = Date.now() + timeoutMs;
+  const get = async (url, limit) => {
+    const remaining = deadline - Date.now(); if (remaining <= 0) throw new Error('Published artifact fetch deadline exceeded');
+    const response = await fetcher(url, { redirect: 'error', signal: AbortSignal.timeout(remaining) });
+    if (!response.ok || !response.body) throw new Error('Published artifact HTTPS fetch failed');
+    if (Number(response.headers.get('content-length')) > limit) throw new Error('Published artifact exceeds size bound');
+    const reader = response.body.getReader(); const chunks = []; let length = 0;
+    try {
+      while (true) {
+        if (Date.now() >= deadline) throw new Error('Published artifact fetch deadline exceeded');
+        const { done, value } = await reader.read(); if (done) break;
+        length += value.byteLength; if (length > limit) throw new Error('Published artifact exceeds size bound');
+        chunks.push(Buffer.from(value));
+      }
+    } finally { await reader.cancel().catch(() => {}); }
+    return Buffer.concat(chunks);
+  };
+  try {
+    const metadataUrl = `https://registry.npmjs.org/ruvnet-brain/${version}`;
+    const metadata = JSON.parse((await get(metadataUrl, 2 * 1024 * 1024)).toString('utf8'));
+    const tarballUrl = `https://registry.npmjs.org/ruvnet-brain/-/ruvnet-brain-${version}.tgz`;
+    if (metadata.name !== 'ruvnet-brain' || metadata.version !== version || metadata.dist?.tarball !== tarballUrl
+      || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(metadata.dist?.integrity || '')) throw new Error('Published version/path/integrity mismatch');
+    const archive = await get(tarballUrl, maxTarballBytes);
+    const integrity = `sha512-${crypto.createHash('sha512').update(archive).digest('base64')}`;
+    if (integrity !== metadata.dist.integrity) throw new Error('Published archive integrity mismatch');
+    const remaining = deadline - Date.now(); if (remaining <= 0) throw new Error('Published artifact deadline exceeded');
+    // stdout-only exact member: no archive paths are ever written to disk or traversed.
+    const result = spawnSync(tarBinary, ['-xzOf', '-', 'package/plugin/hooks/codex-hooks.json'],
+      { input: archive, timeout: Math.min(remaining, 3000), maxBuffer: 256 * 1024 });
+    if (result.error || result.status !== 0 || !result.stdout?.length) throw new Error('Platform tar cannot read exact published hooks entry');
+    if (!codexHookIdentities(JSON.parse(result.stdout)).size) throw new Error('Published native hooks are invalid');
+    return { state: 'verified', releaseIdentity: { version, integrity, hooksSha256: digest(result.stdout) },
+      metadataUrl, tarballUrl, archiveBytes: archive.length };
+  } catch (error) { return blocked(error.message); }
+}
+
+const activeMetadataChildren = new Map();
+async function shutdownMetadataChild(child) {
+  const entry = activeMetadataChildren.get(child); if (!entry) return;
+  if (entry.closing) return entry.closing;
+  entry.closing = (async () => {
+    const wait = async () => {
+      let timer;
+      try { await Promise.race([entry.exited, new Promise((resolve) => { timer = setTimeout(resolve, 350); })]); }
+      finally { clearTimeout(timer); }
+    };
+    if (child.pid && child.exitCode === null && child.signalCode === null) {
+      child.kill('SIGTERM'); await wait();
+      if (child.exitCode === null && child.signalCode === null) { child.kill('SIGKILL'); await wait(); }
+    }
+    if (child.pid && child.exitCode === null && child.signalCode === null) throw new Error('Native metadata child exit unverified');
+    activeMetadataChildren.delete(child);
+  })();
+  return entry.closing;
+}
+
+const OWNER = 'ruvnet-brain@ruvnet-brain';
+const digest = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const blocked = (reason) => ({ state: 'blocked', changed: false, reason });
+function privateBackup(configPath, bytes, backupDir) {
+  fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+  if (fs.lstatSync(backupDir).isSymbolicLink()) throw new Error('Backup directory symlink refused');
+  const file = path.join(backupDir, `rnb-hook-trust-${new Date().toISOString().replaceAll(':', '-')}-${crypto.randomUUID()}.toml`);
+  const fd = fs.openSync(file, 'wx', 0o600);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  const dir = fs.openSync(backupDir, 'r'); try { fs.fsyncSync(dir); } finally { fs.closeSync(dir); }
+  return file;
+}
+
+export function resolveNativeBinary(binary, { env = process.env, platform = process.platform } = {}) {
+  if (typeof binary !== 'string' || !binary) throw new Error('Native executable required');
+  const candidates = path.isAbsolute(binary) ? [binary] : /^[A-Za-z0-9._-]+$/.test(binary)
+    ? String(env.PATH || '').split(platform === 'win32' ? ';' : path.delimiter).filter(Boolean).flatMap((dir) => {
+      const suffixes = platform === 'win32' && !path.extname(binary) ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';') : [''];
+      return suffixes.map((suffix) => path.resolve(dir, binary + suffix));
+    }) : [];
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+      if (!fs.statSync(candidate).isFile()) continue;
+      const resolved = fs.realpathSync(candidate);
+      if (resolved === fs.realpathSync(fileURLToPath(import.meta.url))) throw new Error('Recursive native gateway refused');
+      return resolved;
+    } catch (error) { if (error.message === 'Recursive native gateway refused') throw error; }
+  }
+  throw new Error('Native executable unavailable on configured PATH');
+}
+
+/** Only initialize/config/read/config/batchWrite/hooks/list are ever sent by this client. */
+async function nativeClient(binary, cwd, deadlineAt, configPath) {
+  binary = resolveNativeBinary(binary);
+  const env = { ...process.env, CODEX_HOME: path.dirname(configPath) };
+  for (const key of ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'ANTHROPIC_API_KEY', 'CODEX_API_KEY']) delete env[key];
+  const child = spawn(binary, ['app-server', '--listen', 'stdio://'], { cwd, env, stdio: ['pipe', 'pipe', 'ignore'] });
+  const exited = new Promise((resolve) => { child.once('exit', resolve); child.once('error', () => { if (!child.pid) resolve(); }); });
+  activeMetadataChildren.set(child, { exited });
+  let nextId = 1; let buffer = ''; const pending = new Map();
+  const rejectAll = (message) => { for (const item of pending.values()) { clearTimeout(item.timer); item.reject(new Error(message)); } pending.clear(); };
+  child.on('error', () => rejectAll('Native metadata process failed'));
+  child.stdin.on('error', () => rejectAll('Native metadata input failed'));
+  child.on('exit', () => rejectAll('Native metadata process exited'));
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk;
+    if (Buffer.byteLength(buffer) > 8 * 1024 * 1024) { rejectAll('Native metadata output exceeds bound'); child.kill(); return; }
+    while (buffer.includes('\n')) {
+      const end = buffer.indexOf('\n'); const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+      let row; try { row = JSON.parse(line); } catch { continue; }
+      const item = pending.get(row.id); if (!item) continue;
+      pending.delete(row.id); clearTimeout(item.timer);
+      // Do not include native error details: they may contain private config values.
+      if (row.error) item.reject(new Error(`Native ${item.method} rejected`)); else item.resolve(row.result);
+    }
+  });
+  const rpc = (method, params) => new Promise((resolve, reject) => {
+    const remaining = deadlineAt - Date.now(); if (remaining <= 0) { reject(new Error('Native metadata deadline exceeded')); return; }
+    const id = nextId++; const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Native ${method} timed out`)); }, remaining);
+    pending.set(id, { resolve, reject, timer, method });
+    child.stdin.write(`${JSON.stringify({ id, method, params })}\n`, (error) => { if (error) rejectAll('Native metadata input failed'); });
+  });
+  const close = async () => { rejectAll('Native metadata client closed'); child.stdin.destroy(); await shutdownMetadataChild(child); };
+  try {
+    await rpc('initialize', { clientInfo: { name: 'rnb_verified_hook_trust', version: '1' }, capabilities: { experimentalApi: true } });
+    child.stdin.write(`${JSON.stringify({ method: 'initialized' })}\n`);
+    return { rpc, close };
+  } catch (error) { await close(); throw error; }
+}
+const rowsFor = (response) => {
+  if (!Array.isArray(response?.data)) throw new Error('Native hook registry unavailable');
+  return response.data.flatMap((r) => r.hooks || []).filter((r) => r.pluginId === OWNER);
+};
+function assertRegistry(rows, identities) {
+  if (rows.length !== identities.size || new Set(rows.map((r) => r.key)).size !== identities.size
+    || rows.some((row) => identities.get(row.key) !== row.currentHash)) throw new Error('Native registry differs from verified released artifact');
+}
+
+function otherSettings(config, keys) {
+  const clone = structuredClone(config);
+  for (const key of keys) {
+    const state = clone?.hooks?.state?.[key];
+    if (state && typeof state === 'object') {
+      delete state.trusted_hash;
+      if (!Object.keys(state).length) delete clone.hooks.state[key];
+    }
+  }
+  if (clone?.hooks?.state && !Object.keys(clone.hooks.state).length) delete clone.hooks.state;
+  if (clone?.hooks && !Object.keys(clone.hooks).length) delete clone.hooks;
+  const canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === 'object'
+    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])])) : v;
+  return JSON.stringify(canonical(clone));
+}
+
+/** Caller must authenticate releaseIdentity against its verified tarball/protected-release receipt.
+ * The helper checks installed bytes/version and native identities; it cannot authenticate caller data.
+ * rpc injection owns its own client lifetime. Default client never starts a thread, turn or account call.
+ */
+export async function reconcileVerifiedCodexHookTrust({ releaseIdentity, installedVersion, hooksPath,
+  configPath, nativeBinary, cwd = process.cwd(), backupDir = path.join(path.dirname(configPath || ''), 'backups'),
+  rpc: suppliedRpc, timeoutMs = 10000 } = {}) {
+  let client; let wrote = false; let writeAttempted = false; let backupPath;
+  try {
+    if (!releaseIdentity || !/^\d+\.\d+\.\d+$/.test(releaseIdentity.version || '')
+      || installedVersion !== releaseIdentity.version || !/^[a-f0-9]{64}$/.test(releaseIdentity.hooksSha256 || '')
+      || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(releaseIdentity.integrity || '')) return blocked('Verified released artifact identity required');
+    if (![hooksPath, configPath, backupDir].every((p) => typeof p === 'string' && path.isAbsolute(p))) return blocked('Absolute owned paths required');
+    if (fs.lstatSync(hooksPath).isSymbolicLink() || fs.lstatSync(configPath).isSymbolicLink()) return blocked('Source/config symlink refused');
+    const bytes = fs.readFileSync(hooksPath);
+    if (digest(bytes) !== releaseIdentity.hooksSha256) return blocked('Installed hooks differ from verified release');
+    const identities = codexHookIdentities(JSON.parse(bytes));
+    if (!identities.size) return blocked('Verified artifact has no native hooks');
+    if (!suppliedRpc) client = await nativeClient(nativeBinary, cwd, Date.now() + Math.min(timeoutMs, 20000), configPath);
+    const rpc = suppliedRpc || client.rpc;
+    const before = rowsFor(await rpc('hooks/list', { cwds: [cwd] })); assertRegistry(before, identities);
+    const disabled = before.filter((r) => r.enabled === false).map((r) => r.key).sort();
+    if (before.some((r) => !['trusted', 'modified', 'untrusted', 'managed'].includes(r.trustStatus))) return blocked('Unknown native trust state');
+    const pending = before.filter((r) => r.enabled === true && ['modified', 'untrusted'].includes(r.trustStatus));
+    if (!pending.length) return { state: 'unchanged', changed: false, disabledPreserved: disabled };
+    const read = await rpc('config/read', { includeLayers: true });
+    const users = (read.layers || []).filter((r) => r.name?.type === 'user' && r.name.file === configPath);
+    if (users.length !== 1 || typeof users[0].version !== 'string' || !users[0].version) return blocked('Current user config version unavailable');
+    // Config stays memory-only except the private backup. No logging of effective config values.
+    const prior = fs.readFileSync(configPath);
+    backupPath = privateBackup(configPath, prior, backupDir);
+    const edits = pending.map((r) => ({ keyPath: `hooks.state.${JSON.stringify(r.key)}.trusted_hash`,
+      value: identities.get(r.key), mergeStrategy: 'replace' }));
+    writeAttempted = true;
+    await rpc('config/batchWrite', { filePath: configPath, expectedVersion: users[0].version, reloadUserConfig: true, edits });
+    wrote = true;
+    const afterRead = await rpc('config/read', { includeLayers: true });
+    const afterUsers = (afterRead.layers || []).filter((r) => r.name?.type === 'user' && r.name.file === configPath);
+    if (afterUsers.length !== 1 || otherSettings(users[0].config, pending.map((r) => r.key))
+      !== otherSettings(afterUsers[0].config, pending.map((r) => r.key))) throw new Error('Unrelated config changed; no whole-file rollback attempted');
+    const after = rowsFor(await rpc('hooks/list', { cwds: [cwd] })); assertRegistry(after, identities);
+    if (JSON.stringify(after.filter((r) => r.enabled === false).map((r) => r.key).sort()) !== JSON.stringify(disabled)
+      || after.some((r) => r.enabled === true && !['trusted', 'managed'].includes(r.trustStatus))) throw new Error('Native trust repair verification incomplete');
+    return { state: 'registry-verified', changed: true, editedTrustHashes: edits.length,
+      enabledBrainTrusted: after.filter((r) => r.enabled === true).length, disabledPreserved: disabled,
+      artifactHooksSha256: releaseIdentity.hooksSha256, backupPath, otherSemanticSettingsUnchanged: true,
+      priorConfigSha256: digest(prior), afterConfigSha256: digest(fs.readFileSync(configPath)), inferenceRequests: 0,
+      executionAcceptance: 'not-run' };
+  } catch (error) {
+    // Never restore an entire backup over concurrent writers. A successful write followed by failed
+    // verification is degraded, not "unchanged"; the installer must expose this outcome.
+    return { state: wrote || writeAttempted ? 'degraded' : 'blocked', changed: wrote ? true : writeAttempted ? 'unknown' : false, reason: error.message, ...(backupPath ? { backupPath } : {}) };
+  } finally { await client?.close(); }
+}
+
+// Explicit CLI only; importing the helper never starts a process or reads stdin.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  && process.argv[2] === '--reconcile-installed') {
+  const started = Date.now(); let emitted = false; let reconcileStarted = false;
+  const emit = (receipt) => { if (!emitted) { emitted = true; process.stdout.write(JSON.stringify(receipt) + '\n'); } };
+  const guard = setTimeout(async () => {
+    await Promise.allSettled([...activeMetadataChildren.keys()].map(shutdownMetadataChild));
+    emit({ state: 'degraded', changed: 'unknown', reason: 'CLI deadline exceeded; verify native trust state', inferenceRequests: 0 });
+    process.exit(1);
+  }, 29000);
+  (async () => {
+    let input = ''; for await (const chunk of process.stdin) {
+      input += chunk; if (Buffer.byteLength(input) > 16384) throw new Error('CLI input exceeds bound');
+    }
+    const args = JSON.parse(input);
+    if (!args || typeof args !== 'object' || Array.isArray(args)
+      || Object.keys(args).some((k) => !['installedVersion', 'hooksPath', 'configPath', 'nativeBinary', 'cwd'].includes(k))) throw new Error('Invalid CLI options');
+    const proof = await obtainVerifiedPublishedHookIdentity({ version: args.installedVersion, timeoutMs: 10000 });
+    if (proof.state !== 'verified') { emit(proof); return; }
+    reconcileStarted = true;
+    const result = await reconcileVerifiedCodexHookTrust({ ...args, releaseIdentity: proof.releaseIdentity,
+      timeoutMs: Math.max(1, Math.min(20000, 28000 - (Date.now() - started))) });
+    emit(result);
+  })().catch(() => emit(reconcileStarted
+    ? { state: 'degraded', changed: 'unknown', reason: 'Native reconciliation or shutdown failed; verify trust state', inferenceRequests: 0 }
+    : blocked('CLI request or published artifact proof failed'))).finally(() => clearTimeout(guard));
+}