ruvnet-brain 4.5.2 → 4.5.4

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

@@ -10,9 +10,8 @@
  *                           is the RECORDING tier; distill mines it into episodes/reasoning_patterns/
  *                           causal_edges, the KNOWLEDGE tier, which stays empty unless it is run)
  *
- * WHERE: the project's `.swarm/memory.db` when it exists, else the machine-wide
- * `~/.claude/global-memory/.swarm/memory.db` (outside every repository). `.swarm` is NEVER created
- * inside a project — see session-snapshot-hook.mjs's writeSessionSnapshot for why that is trespass.
+ * WHERE: only the canonical project's `.swarm/memory.db` (including linked worktrees).
+ * An absent store requires persisted opt-in; there is no automatic machine-wide fallback.
  *
  * WHAT (measured facts carried over from the owner's local Claude hook, 2026-09-29):
  *   • The Brain's continuation gate continues most turns, so the turn's REAL final Stop carries
@@ -32,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
- * appended next to the db BEFORE the spawn, and the worker appends a receipt per step, so 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';
@@ -43,7 +41,9 @@ import crypto from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
-import { userLevelAgentdbHooks } from './continuity-events.mjs';
+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;
@@ -87,7 +87,7 @@ export function claudeTurn(lines) {
     if ((o?.message?.role || o?.role) !== 'assistant') continue;
     const c = o.message?.content;
     const t = textOf(c).trim();
-    if (t) texts.push(t);
+    if (t) texts.push(redactText(t));
     if (!Array.isArray(c)) continue;
     for (const u of c) {
       if (!u || u.type !== 'tool_use') continue;
@@ -138,48 +138,108 @@ export function readSettledTranscript(file, { stableMs = 400, maxMs = 2000, slee
 
 export function buildTurnRecord({ turn, project, host, session, at = new Date() }) {
   const parts = [`[turn ${at.toISOString()} project=${project} host=${host}]`,
-    `OUTCOME: ${turn.finalText.replace(/\s+/g, ' ').slice(0, 2500)}`];
-  if (turn.files.length) parts.push(`FILES CHANGED: ${turn.files.slice(0, 25).join(', ')}`);
-  if (turn.actions.length) parts.push(`ACTIONS: ${turn.actions.slice(-15).join(' • ')}`);
+    `OUTCOME: ${redactText(turn.finalText).replace(/\s+/g, ' ').slice(0, 2500)}`];
+  if (turn.files.length) parts.push(`FILES CHANGED: ${turn.files.slice(0, 25).map(redactText).join(', ')}`);
+  if (turn.actions.length) parts.push(`ACTIONS: ${turn.actions.slice(-15).map(redactText).join(' • ')}`);
   parts.push(`SESSION: ${session || '?'}`);
-  return parts.join('  ||  ').slice(0, 4000);
+  return redactText(parts.join('  ||  ')).slice(0, 4000);
 }
 
-/** Project db if the project already has one; otherwise the machine-wide db outside every repo. */
-export function resolveTurnDb({ projectDir, home = os.homedir(), env = process.env } = {}) {
-  const projectDb = path.join(projectDir, '.swarm', 'memory.db');
-  try { if (fs.statSync(projectDb).isFile()) return { db: projectDb, scope: 'project' }; } catch { /* absent */ }
-  const globalDb = env.RUVNET_TURN_GLOBAL_DB || path.join(home, '.claude', 'global-memory', '.swarm', 'memory.db');
-  return { db: globalDb, scope: 'global' };
+/** Persisted per-canonical-project/per-path consent, reread at every boundary (no restart). */
+export function turnCapturePolicyFile(brainHome) {
+  return path.join(brainHome, 'turn-capture', 'policy.json');
 }
 
-const projectName = (projectDir) => path.basename(path.resolve(projectDir)).replace(/[^A-Za-z0-9._-]/g, '_') || 'project';
+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, 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)) {
+    try {
+      policy = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (policy?.schemaVersion !== 1 || !consentMap(policy.projects)
+        || (Object.hasOwn(policy, 'paths') && !consentMap(policy.paths))) throw new Error('invalid policy');
+    } 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?.[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', 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', 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.
+function assertTurnStoreFiles(db) {
+  const directory = path.dirname(db);
+  let stat;
+  try { stat = fs.lstatSync(directory); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink() || fs.realpathSync.native(directory) !== directory)) {
+    throw new Error('store directory is not a canonical regular directory');
+  }
+  for (const file of [db, `${db}-wal`, `${db}-shm`, `${db}-journal`]) {
+    let entry;
+    try { entry = fs.lstatSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (entry && (!entry.isFile() || entry.isSymbolicLink() || entry.nlink > 1)) {
+      throw new Error('store or SQLite side file is a symlink, hard link or non-regular file');
+    }
+  }
+}
+
+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 };
 }
 
-function sameTurnSeen(stateFile, sessionKey, fingerprint) {
-  let last = {};
-  try { last = JSON.parse(fs.readFileSync(stateFile, 'utf8')) || {}; } catch { /* first run */ }
-  if (last[sessionKey] === fingerprint) return true;
+function readTurnState(stateFile) {
+  try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')) || {}; } catch { return {}; }
+}
+
+function sameTurnSeen(stateFile, sessionKey, fingerprint, receipts) {
+  const previous = readTurnState(stateFile)[sessionKey];
+  if (previous?.fingerprint !== fingerprint) return false;
+  try {
+    const rows = readTail(receipts, 128 * 1024).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } });
+    const receipt = rows.findLast((r) => r.kind === 'store' && r.key === previous.key);
+    if (receipt) return receipt.status === 0 && receipt.verified === true;
+  } catch { /* queued worker has no receipt yet */ }
+  // An in-flight worker gets a bounded grace period; a killed/lost worker cannot consume the turn forever.
+  return Date.now() - previous.at < 2 * STEP_TIMEOUT_MS + 10_000;
+}
+
+function markTurnQueued(stateFile, sessionKey, fingerprint, key) {
+  const last = readTurnState(stateFile);
   const keys = Object.keys(last);
   for (const k of keys.slice(0, Math.max(0, keys.length - 200))) delete last[k];
   try {
     fs.mkdirSync(path.dirname(stateFile), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(stateFile, JSON.stringify({ ...last, [sessionKey]: fingerprint }), { mode: 0o600 });
+    fs.writeFileSync(stateFile, JSON.stringify({ ...last, [sessionKey]: { fingerprint, key, at: Date.now() } }), { mode: 0o600 });
   } catch { /* dedupe is best effort; a duplicate record beats a lost one */ }
-  return false;
 }
 
 /**
  * Capture this turn's outcome (Stop) and/or queue distillation (SessionEnd, PreCompact).
- * Returns a plain report; `skipped` / `distill.skipped` carry the reason whenever nothing is written.
+ * Returns a plain report; `queued` means a worker request, never proof the store committed.
+ * `skipped` / `distill.skipped` carry the reason whenever nothing is requested.
  */
 export function captureTurnOutcome({
   projectDir, event, payload = {}, host = 'claude',
@@ -191,15 +251,21 @@ export function captureTurnOutcome({
   settleMs = 2000,
   now = () => new Date(),
 } = {}) {
-  const report = { event, host, recorded: false, distill: { queued: false } };
+  const report = { event, host, queued: false, recorded: false, distill: { queued: false } };
   if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') {
     return { ...report, skipped: 'RUVNET_TURN_CAPTURE=off', distill: { queued: false, skipped: 'RUVNET_TURN_CAPTURE=off' } };
   }
   if (!ruflo) return { ...report, skipped: 'ruflo not found', distill: { queued: false, skipped: 'ruflo not found' } };
-  const { db, scope } = resolveTurnDb({ projectDir, home, env });
+  let target;
+  try { target = resolveTurnDb({ projectDir, brainHome }); } catch (error) { return { ...report, skipped: `store resolution failed: ${redactText(error.message)}` }; }
+  const { db, scope, projectRoot } = target;
   Object.assign(report, { db, scope });
+  if (target.skipped) return { ...report, skipped: target.skipped, distill: { queued: false, skipped: target.skipped } };
   const steps = [];
-  const project = projectName(projectDir);
+  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');
 
   // ONE WRITER PER TURN (ADR-100 §3). Measured 2026-10-01 on this repo's real store: 624 `turns` rows
@@ -228,14 +294,23 @@ export function captureTurnOutcome({
     } else {
       const fingerprint = crypto.createHash('sha256').update(JSON.stringify([turn.finalText, turn.files])).digest('hex');
       const stateFile = path.join(brainHome, 'turn-capture', 'last-turn.json');
-      if (sameTurnSeen(stateFile, `${host}:${sessionKey}`, fingerprint)) report.skipped = 'same turn outcome already recorded';
+      const identity = crypto.createHash('sha256').update(`${host}:${db}:${sessionKey}`).digest('hex');
+      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()}`;
-        const value = buildTurnRecord({ turn, project, host, session: payload.session_id, at });
-        steps.push({ kind: 'store', ruflo, args: ['memory', 'store', '-k', key, '--value', value, '-n', TURN_NAMESPACE,
-          '--path', db, '--tags', `project=${project},host=${host}`, '--provenance', 'agent_output'] });
-        Object.assign(report, { recorded: true, key, value });
+        const key = `turn-${project}-${digest(`${identity}:${fingerprint}`).slice(0, 40)}`;
+        dedupe = { stateFile, identity, fingerprint, key };
+        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, '--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 });
       }
     }
   } else report.skipped = `turn outcomes are recorded at Stop, not ${event}`;
@@ -243,60 +318,161 @@ export function captureTurnOutcome({
   if (event === 'SessionEnd' || event === 'PreCompact') {
     if (!fs.existsSync(db)) report.distill = { queued: false, skipped: 'no memory db to distill yet' };
     else {
-      steps.push({ kind: 'distill', ruflo, args: ['memory', 'distill', 'run', '--db', db, '--namespace', TURN_NAMESPACE, '--max-entries', '500'] });
+      steps.push({ ...binding, kind: 'distill', ruflo, args: ['memory', 'distill', 'run', '--db', db, '--namespace', TURN_NAMESPACE, '--max-entries', '500'] });
       report.distill = { queued: true, db };
     }
   }
   if (!steps.length) return report;
 
   try {
-    // The machine-wide db lives outside every repository; its directory is created on first use so a
-    // fresh machine records from its first turn. A project's `.swarm` is never created (scope check).
-    if (scope === 'global') fs.mkdirSync(path.dirname(db), { recursive: true, mode: 0o700 });
-    if (report.recorded) {
+    // 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, project, host, value: report.value })}\n`, { mode: 0o600 });
+        `${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, recorded: false, distill: { queued: false, skipped: `launch failed: ${error.message}` }, skipped: `launch failed: ${error.message}` };
+    return { ...report, queued: false, recorded: false, distill: { queued: false, skipped: `launch failed: ${redactText(error.message)}` }, skipped: `launch failed: ${redactText(error.message)}` };
   }
   return report;
 }
 
-/** The detached worker: run each step in order, bounded, and append one receipt per step. */
-export function runSteps({ steps = [], receipts } = {}, { run = spawnSync } = {}) {
+/** Exact (namespace, key, content) readback. Exit zero alone never proves capture. */
+function readBack({ ruflo, db, key, run, options }) {
+  const invocation = rufloInvocation(ruflo, ['memory', 'retrieve', '--key', key, '--namespace', TURN_NAMESPACE, '--value-only', '--path', db]);
+  const result = run(invocation.executable, invocation.args, options);
+  return result.status === 0 ? String(result.stdout || '').trim() : null;
+}
+
+/** The detached worker: bounded steps, safe error evidence, exact content readback. */
+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;
-    const db = step.args[step.args.indexOf(step.kind === 'store' ? '--path' : '--db') + 1];
+  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 {
-      const { executable, args } = rufloInvocation(step.ruflo, step.args);
-      // CONTAINMENT (measured 2026-09-29, ruflo 3.48.0): even with an explicit --path, `memory store`
-      // writes `.swarm/hnsw.index` and `ruvector.db` relative to its CWD. Run from an inherited cwd,
-      // that planted `.swarm/` + `ruvector.db` in a repository that never adopted the brain — the
-      // exact trespass session-snapshot-hook.mjs forbids. So every step runs INSIDE the db's own
-      // directory, with ruflo's memory root pinned there too.
-      const home = path.dirname(db);
-      const r = run(executable, args, { stdio: 'ignore', timeout: STEP_TIMEOUT_MS, cwd: home, windowsHide: true,
-        env: { ...process.env, ...RUFLO_ENV, CLAUDE_FLOW_MEMORY_PATH: home } });
-      status = r.status;
-      if (r.error) error = r.error.message;
-    } catch (e) { error = e.message; }
-    const row = { at: new Date().toISOString(), kind: step.kind, db,
-      key: step.kind === 'store' ? step.args[step.args.indexOf('-k') + 1] : undefined, status, error };
+      if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') throw new Error('RUVNET_TURN_CAPTURE=off');
+      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 (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, 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');
+  let target;
+  try { target = resolveTurnDb({ projectDir, brainHome }); } catch { return { state: 'unknown', line: 'turn recording unavailable: canonical store resolution failed' }; }
+  if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off' || target.skipped) return { state: 'unknown', line: `turn recording n/a — ${target.skipped || 'RUVNET_TURN_CAPTURE=off'}` };
+  let rows = [];
+  try {
+    rows = readTail(path.join(brainHome, 'turn-capture', 'receipts.jsonl'), 128 * 1024).flatMap((line) => {
+      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 */ }
+  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' };
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--run-steps') {
   try { runSteps(JSON.parse(process.argv[3] || '{}')); } catch { /* a detached worker has no one to report to */ }
   process.exit(0);

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/learning-replay-cli.mjs

@@ -41,6 +41,7 @@ const usage = () => `Usage:
   node scripts/learning-replay.mjs [--trap ${TRAP.MEMORY_SEARCH}|${TRAP.POST_TASK}] [--n N] [--host codex|claude-code] [--model MODEL]
   node scripts/learning-replay.mjs --check
   node scripts/learning-replay.mjs --check-portfolio
+  node scripts/learning-replay.mjs --measure-portfolio --host codex --model MODEL
   node scripts/learning-replay.mjs --check-mutants
   node scripts/learning-replay.mjs --dry-run
   node scripts/learning-replay.mjs --mutant <${Object.keys(MUTANTS).join('|')}>
@@ -86,6 +87,19 @@ function printed(label, result) {
   return EXIT[result.status] ?? EXIT.UNKNOWN;
 }
 
+// A portfolio includes both positive traps AND all four causal mutants. Run every scenario even
+// after a failure, then let the unchanged evidence checker decide the result; child exit 1 is the
+// expected outcome of a causal mutant, and is never by itself a successful portfolio measurement.
+export async function measurePortfolio({ host, model, execute = main, check = checkPortfolio }) {
+  for (const trap of [TRAP.MEMORY_SEARCH, TRAP.POST_TASK]) {
+    await execute(['--trap', trap, '--n', '3', '--host', host, '--model', model]);
+    for (const mutant of ['delete-lesson', 'brain-off-treated']) {
+      await execute(['--trap', trap, '--mutant', mutant, '--n', '1', '--host', host, '--model', model]);
+    }
+  }
+  return printed(`${INVARIANT}-PORTFOLIO`, check());
+}
+
 export async function main(argv = process.argv.slice(2)) {
   const { has, arg } = parse(argv);
   if (has('--help') || has('-h')) {
@@ -113,6 +127,7 @@ export async function main(argv = process.argv.slice(2)) {
   }
   if (has('--check-portfolio')) return printed(`${INVARIANT}-PORTFOLIO`, checkPortfolio());
   if (has('--check-mutants')) return printed(`${INVARIANT}-MUTANTS`, checkMutantArtifacts());
+  if (has('--measure-portfolio')) return measurePortfolio({ host, model });
 
   const source = checkSourceIdentity();
   if (!source.clean) {

package/scripts/learning-replay.mjs

@@ -8,7 +8,7 @@ export * from './learning-replay-contract.mjs';
 export * from './learning-replay-execution.mjs';
 export * from './learning-replay-fixture.mjs';
 export * from './learning-replay-proof.mjs';
-export { main } from './learning-replay-cli.mjs';
+export { main, measurePortfolio } from './learning-replay-cli.mjs';
 
 const invokedDirectly = process.argv[1]
   && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);

package/scripts/nightly-wrapper.sh

@@ -177,14 +177,14 @@ sh scripts/memdb-health.sh "$RUVNET_PROJECT_MEMORY_DB" >> "$LOG" 2>&1 \
   && echo "===== memdb-health canary: OK =====" >> "$LOG" \
   || echo "===== memdb-health canary: UNHEALTHY (see line above) =====" >> "$LOG"
 
-# ── LEARNING-REPLAY: the D4 counterfactual trap (ADR-058 §D4). THE ONE STANDING TOKEN SPEND, priced
-# in the open: N=3 replay, two model arms per run, ~$0.09 and ~55s measured 2026-07-27 on haiku.
+# ── LEARNING-REPLAY: the D4 counterfactual portfolio (ADR-058 §D4). This manual author run spends
+# real model tokens: two N=3 positive traps and four N=1 causal mutants, with two arms per run.
 #
 # It runs HERE, and not on a GitHub runner, because the trap needs credentials a bare runner does not
 # have — a real model session AND the real global `ruflo` binary (it records into a fixture project's
 # .swarm/memory.db and refreshes it with `ruflo memory distill`). .github/workflows/learning-replay.yml
-# is the currency gate on the artifact this writes; if this step stops running, that workflow goes red
-# on staleness rather than everything staying quietly green.
+# is the currency gate on the evidence this writes; if evidence stops being refreshed, it goes red
+# on staleness. This wrapper is an author diagnostic, not an installed scheduler or publisher.
 #
 # Best-effort, same shape as the canaries below: it never blocks the rebuild. Its exit code is not
 # thrown away though — it is written to the log by name, because 0/1/3/4 are four different facts
@@ -222,7 +222,7 @@ echo "===== RELEASE-CONVERGENCE watchdog — $(date -u +%FT%TZ) =====" >> "$LOG"
   || echo "[release-watchdog] exited non-zero — see above; nightly continues" >> "$LOG"
 
 echo "===== LEARNING-REPLAY counterfactual trap — $(date -u +%FT%TZ) =====" >> "$LOG"
-"$NODE_BIN" scripts/learning-replay.mjs --n 3 --model haiku >> "$LOG" 2>&1
+"$NODE_BIN" scripts/learning-replay.mjs --measure-portfolio --host codex --model gpt-6.1-sol >> "$LOG" 2>&1
 LR_RC=$?
 case "$LR_RC" in
   0) echo "===== LEARNING-REPLAY: PASS =====" >> "$LOG" ;;