ruvnet-brain 4.5.6 → 4.5.8

package/plugin/scripts/learning-queue.mjs

@@ -0,0 +1,135 @@
+// Workflow queue transport only. Retained source bytes plus acknowledgments permit crash replay.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const MAX_QUEUE_BYTES = 1024 * 1024;
+export const WORKER_BUDGET_MS = 18_000;
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const nofollow = fs.constants.O_NOFOLLOW || 0;
+export const queueName = /^session-[A-Za-z0-9_-]+\.jsonl$/;
+
+/** Reject symlinks/junctions at every ancestor beneath the canonical selected scope. */
+export function safeQueue(context, create = false) {
+  const root = fs.realpathSync.native(context.scope === 'user' ? context.home : context.projectDir);
+  const relative = path.relative(root, context.queueDir);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('queue outside scope');
+  let current = root;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || fs.realpathSync.native(current) !== current) throw new Error('unsafe queue ancestor');
+  }
+  return current;
+}
+
+export function readSafe(file, maxBytes = MAX_QUEUE_BYTES) {
+  if (!fs.lstatSync(file).isFile()) throw new Error('unsafe queue file');
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | nofollow);
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > maxBytes) throw new Error('queue file exceeds bounded read');
+    return fs.readFileSync(fd);
+  } finally { fs.closeSync(fd); }
+}
+
+export function queueFiles(context, options = {}) {
+  try {
+    const dir = safeQueue(context);
+    if (Number.isInteger(options.limit)) {
+      const before = []; const after = []; let passed = !options.cursor;
+      const iterator = fs.opendirSync(dir);
+      try {
+        let entry;
+        while (Date.now() < options.deadline && (entry = iterator.readSync())) {
+          if (!queueName.test(entry.name)) continue;
+          const file = path.join(dir, entry.name);
+          if (!passed && entry.name === options.cursor) { passed = true; if (before.length < options.limit) before.push(file); continue; }
+          if (passed) { after.push(file); if (after.length >= options.limit) break; }
+          else if (before.length < options.limit) before.push(file);
+        }
+      } finally { iterator.closeSync(); }
+      return [...after, ...before].slice(0, options.limit);
+    }
+    return fs.readdirSync(dir).filter(name => queueName.test(name)).map(name => path.join(dir, name))
+      .sort((a, b) => fs.lstatSync(a).mtimeMs - fs.lstatSync(b).mtimeMs || a.localeCompare(b));
+  } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+
+/** Hash-bound offsets cannot acknowledge replaced source bytes or an appended sibling line. */
+export function pendingRecords(file) {
+  const bytes = readSafe(file); let ack = {};
+  try { ack = JSON.parse(readSafe(`${file}.ack.json`).toString()); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const records = []; let start = 0;
+  for (let end = 0; end < bytes.length; end++) {
+    if (bytes[end] !== 10) continue;
+    const line = bytes.subarray(start, end + 1); const key = `${start}:${hash(line)}`;
+    if (line.toString().trim() && ack[key] !== true) records.push({ key, raw: line.toString() });
+    start = end + 1;
+  }
+  // A torn final line is pending evidence; it can become complete on a legacy writer's next append.
+  if (start < bytes.length && bytes.subarray(start).toString().trim()) records.push({ key: null, raw: bytes.subarray(start).toString() });
+  return { records, ack };
+}
+
+export function writeExclusive(file, bytes) {
+  const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | nofollow, 0o600);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+
+export function writeAtomic(target, bytes) {
+  try { if (!fs.lstatSync(target).isFile()) throw new Error('unsafe acknowledgment'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const temporary = `${target}.${randomUUID()}`;
+  writeExclusive(temporary, bytes);
+  fs.renameSync(temporary, target);
+}
+export function acknowledge(file, ack) { writeAtomic(`${file}.ack.json`, JSON.stringify(ack)); }
+
+/** Lease lasts longer than the finite worker. PID is diagnostic, never writer authority. */
+export function takeQueueLock(context, now = Date.now()) {
+  const dir = safeQueue(context); const file = path.join(dir, '.worker-lock');
+  const token = randomUUID(); const body = JSON.stringify({ token, expires: now + 60_000 });
+  try { writeExclusive(file, body); return token; } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const seen = readSafe(file).toString();
+  let expires;
+  try { const owner = JSON.parse(seen); if (owner.retirementUnconfirmed || owner.retirementRequired) return null; expires = owner.expires; } catch { expires = fs.lstatSync(file).mtimeMs + 60_000; }
+  if (!Number.isFinite(expires)) expires = fs.lstatSync(file).mtimeMs + 60_000;
+  if (!(expires < now)) return null;
+  const aside = `${file}.${token}`;
+  fs.renameSync(file, aside);
+  if (readSafe(aside).toString() !== seen) {
+    try { fs.linkSync(aside, file); } catch { /* another fenced owner already exists */ }
+    fs.rmSync(aside); return null;
+  }
+  fs.rmSync(aside);
+  try { writeExclusive(file, body); return token; } catch (error) { if (error.code === 'EEXIST') return null; throw error; }
+}
+
+export function ownsQueueLock(context, token) {
+  try {
+    safeQueue(context);
+    const lock = JSON.parse(readSafe(path.join(context.queueDir, '.worker-lock')).toString());
+    return !lock.retirementUnconfirmed && lock.token === token && Date.now() < lock.expires;
+  } catch { return false; }
+}
+export function releaseQueueLock(context, token) {
+  if (ownsQueueLock(context, token)) fs.rmSync(path.join(context.queueDir, '.worker-lock'));
+}
+
+// Fixed vocabulary: arbitrary executable names, arguments, basenames and paths never persist.
+const verbs = new Set('git npm node python python3 cargo rustc go gh cd ls rg cat export mkdir rm cp mv bash sh curl wget npx ruflo'.split(' '));
+const subs = new Set('status diff log show add commit push pull fetch checkout switch branch test run install ci build check fmt clippy auth workflow release memory hooks'.split(' '));
+export function safeAction(tool, value) {
+  if (typeof value !== 'string') return null;
+  if (tool === 'Bash') {
+    const [verb, sub] = value.trim().split(/\s+/, 3);
+    if (!verbs.has(verb)) return 'command';
+    return subs.has(sub) ? `${verb} ${sub}` : verb;
+  }
+  if (!['Write', 'Edit', 'MultiEdit'].includes(tool)) return null;
+  // Legacy action is minimized again before invocation; no private basename reaches Ruflo argv.
+  return 'edit file';
+}

package/plugin/scripts/learning-store.mjs

@@ -0,0 +1,105 @@
+// Canonical workflow observations; existing Ruflo is the sole writer, never the legacy JSON hook store.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { withProgressionReader } from './project-progression-reader.mjs';
+import { rufloRunDir } from './project-progression-store.mjs';
+import { rufloInvocation } from './ruflo-bin.mjs';
+import { loadRuntimePreferences } from './runtime-preferences.mjs';
+import { loadNodeSqlite } from './node-sqlite.mjs';
+import { safeQueue, writeAtomic } from './learning-queue.mjs';
+
+export const LEARNING_NAMESPACE = 'learning-observations';
+export function learningTarget(context, { env = process.env, explicitLegacyApply = false } = {}) {
+  if (!context.enabled) throw new Error('learning consent disabled');
+  if (context.scope === 'project') return resolveProjectStore({ projectDir: context.projectDir, gitTimeoutMs: 1000 }).canonicalAgentDbPath;
+  const root = path.join(context.home, '.claude', 'global-memory');
+  const chosen = loadRuntimePreferences({ env, cwd: context.projectDir }).values.learningScope === 'user';
+  if (!chosen && !explicitLegacyApply) throw new Error('user learning requires persisted user consent or explicit legacy Apply');
+  safeQueue({ scope: 'user', home: context.home, queueDir: root });
+  const db = path.join(root, '.swarm', 'memory.db');
+  if (!fs.lstatSync(db).isFile()) throw new Error('user store not adopted');
+  const resolved = resolveProjectStore({ projectDir: root, requestedStorePath: db, gitTimeoutMs: 1000 });
+  if (resolved.projectRoot !== root) throw new Error('foreign global learner root');
+  return resolved.canonicalAgentDbPath;
+}
+
+export function runLearningRuflo(binary, args, db, { env = process.env, deadline = Date.now() + 18_000 } = {}) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error('learning deadline exhausted');
+  const cwd = rufloRunDir(db, { root: env.RUVNET_RUFLO_CWD_ROOT || path.join(env.HOME, '.cache', 'ruvnet-brain', 'learning-ruflo') });
+  try {
+    const invocation = rufloInvocation(binary, args);
+    return spawnSync(invocation.executable, invocation.args, { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' },
+      encoding: 'utf8', shell: false, timeout: Math.min(6000, remaining), killSignal: 'SIGKILL', maxBuffer: 65536, windowsHide: true });
+  } finally { fs.rmSync(cwd, { force: true, recursive: true }); }
+}
+
+export function recordLearningObservation(binary, context, file, record, row, options = {}) {
+  const db = learningTarget(context, options);
+  const key = 'workflow-' + createHash('sha256').update(path.basename(file) + ':' + record.key).digest('hex');
+  const value = JSON.stringify({ schemaVersion: 1, tool: row.tool, action: row.action, scope: context.scope,
+    authoritative: false, provenance: 'system-observation', outcome: 'host-reported-success' });
+  const run = args => { if (options.allowed && !options.allowed()) throw new Error('learning consent changed'); return runLearningRuflo(binary, args, db, options); };
+  const existing = withProgressionReader(db, reader => reader.readContent(LEARNING_NAMESPACE, key));
+  if (!(existing.ok && existing.value === value)) {
+    const stored = run(['memory', 'store', '--key', key, '--value', value, '--namespace', LEARNING_NAMESPACE,
+      '--no-upsert', '--provenance', 'system_observation', '--path', db]);
+    if (stored.error || stored.status !== 0) throw new Error('canonical observation write failed');
+  }
+  const retrieved = run(['memory', 'retrieve', '--key', key, '--namespace', LEARNING_NAMESPACE, '--value-only', '--path', db]);
+  if (retrieved.error || retrieved.status !== 0 || retrieved.stdout.trim() !== value) throw new Error('canonical exact CLI readback failed');
+  const independent = withProgressionReader(db, reader => reader.readContent(LEARNING_NAMESPACE, key));
+  if (!independent.ok || independent.value !== value) throw new Error('canonical independent row readback failed');
+  return { db, key, digest: createHash('sha256').update(value).digest('hex'), exactCli: true, independentRow: true };
+}
+
+export function learningStoreStatus(db) {
+  const rows = withProgressionReader(db, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).length);
+  if (!rows.ok) return { known: false, observations: 0, patterns: null, lastDistillAt: null };
+  const sqlite = loadNodeSqlite(); let connection;
+  try {
+    connection = new sqlite.DatabaseSync(db, { readOnly: true });
+    const present = name => !!connection.prepare('SELECT 1 FROM sqlite_master WHERE type=? AND name=?').get('table', name);
+    const patterns = present('reasoning_patterns') ? connection.prepare('SELECT count(*) AS n FROM reasoning_patterns WHERE json_valid(metadata) AND json_extract(metadata,?)=?').get('$.namespace', LEARNING_NAMESPACE).n : 0;
+    const at = present('distill_state') ? connection.prepare('SELECT last_run_at AS at FROM distill_state WHERE namespace=?').get(LEARNING_NAMESPACE)?.at : null;
+    return { known: true, observations: rows.value, patterns, lastDistillAt: at ?? null };
+  } catch { return { known: false, observations: rows.value, patterns: null, lastDistillAt: null }; }
+  finally { connection?.close(); }
+}
+
+/** Existing $0 structural distiller, with a verified native WAL-safe snapshot before mutation. */
+export function distillLearning(binary, context, options = {}) {
+  const db = learningTarget(context, options); const before = learningStoreStatus(db);
+  if (!before.known) throw new Error('distillation baseline unavailable');
+  if (options.automatic && before.lastDistillAt !== null && Date.now() - before.lastDistillAt < 3600_000) {
+    return { db, completed: false, deferred: 'automatic cadence: at most hourly', patternDelta: 0, ratifiedLessons: 0 };
+  }
+  const backupDir = path.join(path.dirname(db), 'learning-backups');
+  const run = args => { if (options.allowed && !options.allowed()) throw new Error('learning consent changed'); return runLearningRuflo(binary, args, db, options); };
+  if (options.allowed && !options.allowed()) throw new Error('learning consent changed');
+  safeQueue({ scope: 'project', projectDir: path.dirname(path.dirname(db)), queueDir: backupDir }, true);
+  const prior = new Set(fs.readdirSync(backupDir));
+  const backup = run(['memory', 'backup', '--db', db, '--dir', backupDir, '--keep', '3', '--verbose']);
+  if (backup.error || backup.status !== 0) throw new Error('distillation backup failed');
+  if (!backup.stdout.includes('memory DB backed up → ') || backup.stdout.includes('byte-copy')) throw new Error('native online backup mode unverified');
+  const images = fs.readdirSync(backupDir).filter(name => name.endsWith('.db') && !prior.has(name));
+  if (images.length !== 1) throw new Error('fresh distillation snapshot absent');
+  const image = path.join(backupDir, images[0]);
+  fs.chmodSync(image, 0o600);
+  // The source-bound verbose marker above distinguishes native online backup from
+  // Ruflo's byte-copy fallback. Row verification is additional observation evidence,
+  // not a claim that this subset alone proves whole-database rollback.
+  const source = withProgressionReader(db, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).map(key => [key, reader.readContent(LEARNING_NAMESPACE, key)]));
+  const copy = withProgressionReader(image, reader => reader.listKeys(LEARNING_NAMESPACE, { maxEntries: 100_000 }).map(key => [key, reader.readContent(LEARNING_NAMESPACE, key)]));
+  if (!source.ok || !copy.ok || JSON.stringify(source.value) !== JSON.stringify(copy.value)) throw new Error('distillation snapshot row verification failed');
+  writeAtomic(path.join(backupDir, 'latest-receipt.json'), JSON.stringify({ db, before, snapshot: image, providerMode: 'native-online-backup', observationsVerified: true, retainedSnapshots: 3, restore: 'automatic exact restore unavailable' }));
+  const distilled = run(['memory', 'distill', 'run', '--db', db, '--namespace', LEARNING_NAMESPACE,
+    '--max-entries', '8', '--judge', 'structural', '--budget-usd', '0']);
+  const after = learningStoreStatus(db);
+  return { db, before, after, completed: !distilled.error && distilled.status === 0,
+    patternDelta: before.known && after.known ? after.patterns - before.patterns : null,
+    snapshot: image, ratifiedLessons: 0 };
+}

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

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

package/plugin/scripts/nightly-scheduler.mjs

@@ -101,8 +101,12 @@ export function describeFailedRefreshRun(receipt, { reasonLimit = 200 } = {}) {
   const ledger = receipt.phases.map((entry) => entry?.phase);
   if (ledger.length > declared.length || ledger.some((phase, index) => phase !== declared[index])) return null;
   if (ledger.length === 0) return `failed before its first phase (${receipt.terminalVerdict || 'unknown'})`;
-  const failing = [...receipt.phases].reverse().find((entry) => entry?.status !== 'PASS') || receipt.phases[receipt.phases.length - 1];
-  const reason = String(failing.evidence?.updateResult?.reason ?? failing.evidence?.reason ?? '').split('\n')[0].trim();
+  const failing = receipt.phases.find((entry) => entry?.required !== false && entry?.status === 'FAIL')
+    || receipt.phases.find((entry) => entry?.status === 'FAIL')
+    || [...receipt.phases].reverse().find((entry) => entry?.status !== 'PASS')
+    || receipt.phases[receipt.phases.length - 1];
+  const reason = String(failing.evidence?.updateResult?.reason ?? failing.evidence?.error
+    ?? failing.evidence?.reason ?? '').split('\n')[0].trim();
   return reason ? `failed at ${failing.phase}: ${reason.slice(0, reasonLimit)}` : `failed at ${failing.phase}`;
 }
 

package/plugin/scripts/project-capture-queue.mjs

@@ -13,6 +13,7 @@ import { redactProgression } from './project-progression-contract.mjs';
 import { ProgressionOutbox } from './project-progression-outbox.mjs';
 import { captureNormalizedTransition } from './project-transition-hook.mjs';
 import { boundedStoreFactory, runSessionSnapshotHook } from './session-snapshot-hook.mjs';
+import { operatorProgressionSuspension } from './project-progression-suspension.mjs';
 
 /**
  * How long the detached worker may spend per step. The lock is refreshed between steps and goes stale
@@ -49,6 +50,7 @@ const mtimeOf = (projectDir, name) => { try { return fs.statSync(path.join(proje
  */
 export function queueCapture({ projectDir, originProjectDir = projectDir, event, host, payload, env = process.env }) {
   try {
+    if (operatorProgressionSuspension(env)) return null;
     const consent = resolveTurnDb({ projectDir: originProjectDir, requestedStorePath: path.join(projectDir, '.swarm', 'memory.db'),
       brainHome: env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain') });
     if (consent.skipped) return null;
@@ -232,13 +234,16 @@ export function releaseReplayLock(projectDir, token) {
 }
 
 /** Hand the lock (or take it, if free) to a detached worker. Returns whether one was started. Never throws. */
-export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn } = {}) {
+export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn, env = process.env } = {}) {
+  try {
+    if (operatorProgressionSuspension(env)) { if (token) releaseReplayLock(projectDir, token); return false; }
+  } catch { if (token) releaseReplayLock(projectDir, token); return false; }
   const held = token || takeReplayLock(projectDir);
   if (!held) return false;
   try {
     const child = spawnFn(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'session-snapshot-hook.mjs'), '--replay-outbox'], {
       cwd: projectDir, detached: true, stdio: 'ignore', windowsHide: true,
-      env: { ...process.env, RUVNET_REPLAY_LOCK_TOKEN: held },
+      env: { ...env, RUVNET_REPLAY_LOCK_TOKEN: held },
     });
     child.unref?.();
     return true;
@@ -259,10 +264,11 @@ export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn
  */
 export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_LOCK_TOKEN || null, budgetMs = DETACHED_REPLAY_BUDGET_MS,
   makeStoreFactory = boundedStoreFactory, now = Date.now, runCapture = runSessionSnapshotHook, onClaim = null,
-  captureNormalized = captureNormalizedTransition, onCaptured = null } = {}) {
+  captureNormalized = captureNormalizedTransition, onCaptured = null, env = process.env } = {}) {
   const deadlineAt = now() + budgetMs;
   if (developmentHooksSuspended(projectDir)) return 0;
-  const brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
+  if (operatorProgressionSuspension(env)) { if (token) releaseReplayLock(projectDir, token); return 0; }
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
   try {
     const consent = resolveTurnDb({ projectDir, brainHome });
     if (consent.skipped && !consent.skipped.startsWith('no project memory db')) return 0;
@@ -274,8 +280,9 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
       if (!adoptReplayLock(projectDir, held)) return replayed;
       reclaimOrphans(projectDir);
       const resolution = resolveProjectStore({ projectDir });
-      const store = makeStoreFactory(deadlineAt)({ projectDir, requestedStorePath: resolution.canonicalAgentDbPath });
+      const store = makeStoreFactory(deadlineAt)({ projectDir, env, requestedStorePath: resolution.canonicalAgentDbPath });
       for (const snapshot of store.outbox.pendingSnapshots()) {
+        if (operatorProgressionSuspension(env)) return replayed;
         if (now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
         store.captureFrozen(snapshot, { canCommit: () => refreshReplayLock(projectDir, held) });
@@ -283,6 +290,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
         replayed += 1;
       }
       for (const file of queuedCaptures(projectDir)) {
+        if (operatorProgressionSuspension(env)) return replayed;
         if (now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
         const claimed = claimQueued(file);
@@ -292,6 +300,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
           returnClaim(claimed);
           return replayed;
         }
+        if (operatorProgressionSuspension(env)) { returnClaim(claimed); return replayed; }
         let job = null;
         try { job = JSON.parse(fs.readFileSync(claimed, 'utf8')); } catch { /* torn: dropped below */ }
         let committed = false;
@@ -302,7 +311,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
             const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome });
             if (developmentHooksSuspended(job.originProjectDir || projectDir)
               || (consent.skipped && !consent.skipped.startsWith('no project memory db'))) { returnClaim(claimed); return replayed; }
-            const options = { rawInput: JSON.stringify(job.payload), host: job.host,
+            const options = { rawInput: JSON.stringify(job.payload), host: job.host, env,
               budgetMs: Math.max(0, deadlineAt - now()), makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
               captureTurn: () => ({ recorded: false, skipped: 'detached replay' }),
               captureEvents: () => ({ recorded: 0, skipped: 'detached replay' }) };
@@ -327,6 +336,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
 
 /** Synchronous bounded startup drain. Pending debt must downgrade restore, never disappear. */
 export function drainCaptureQueue({ projectDir, budgetMs = 1000, ...options } = {}) {
+  if (operatorProgressionSuspension(options.env || process.env)) return { state: 'suspended', replayed: 0, pending: null };
   const startedAt = Date.now();
   const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)) });
   const root = resolution.projectRoot;
@@ -336,4 +346,3 @@ export function drainCaptureQueue({ projectDir, budgetMs = 1000, ...options } =
   const pending = queuedWork(root) + outboxPending;
   return { state: pending ? 'pending' : 'settled', replayed, pending };
 }
-

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

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

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

@@ -157,13 +157,21 @@ export class ProgressionOutbox {
     const committed = new Map();
     const quarantined = new Map();
     const recoveries = [];
+    let ordinal = 0;
     for (const record of readJsonl(this.path)) {
+      ordinal += 1;
       requireIdentity(record?.eventKey, 'outbox eventKey');
       requireIdentity(record?.payloadDigest, 'outbox payloadDigest');
       if (record.type === 'snapshot') {
         const prior = snapshots.get(record.eventKey);
         if (prior && prior.payloadDigest !== record.payloadDigest) quarantined.set(record.eventKey, 'outbox event key collision');
-        else snapshots.set(record.eventKey, record);
+        // Retain identity/recovery metadata, never every historical snapshot's full payload.
+        // A second incremental scan materializes only the unresolved payloads selected here.
+        else snapshots.set(record.eventKey, { eventKey: record.eventKey, payloadDigest: record.payloadDigest,
+          ordinal, recoveryDiagnostics: record.snapshot?.recoveryDiagnostics && {
+            originalEventKey: record.snapshot.recoveryDiagnostics.originalEventKey,
+            frozenPayloadDigest: record.snapshot.recoveryDiagnostics.frozenPayloadDigest,
+          }, snapshotDigest: record.snapshot?.payloadDigest });
       } else if (record.type === 'commit') {
         const prior = committed.get(record.eventKey);
         if (prior && prior !== record.payloadDigest) quarantined.set(record.eventKey, 'outbox commit collision');
@@ -186,19 +194,27 @@ export class ProgressionOutbox {
       }
     }
     const recovered = new Set(recoveries.filter((record) => {
-      const target = snapshots.get(record.recoveryEventKey)?.snapshot;
+      const target = snapshots.get(record.recoveryEventKey);
       return !quarantined.has(record.recoveryEventKey)
         && committed.get(record.recoveryEventKey) === record.recoveryPayloadDigest
-        && target?.payloadDigest === record.recoveryPayloadDigest
+        && target?.snapshotDigest === record.recoveryPayloadDigest
         && target.recoveryDiagnostics?.originalEventKey === record.eventKey
         && target.recoveryDiagnostics?.frozenPayloadDigest === record.payloadDigest;
     }).map((record) => `${record.eventKey}:${record.payloadDigest}`));
     this.quarantine = [...quarantined].map(([eventKey, reason]) => ({ eventKey, reason }));
-    return [...snapshots.values()]
+    const pending = new Map([...snapshots.values()]
       .filter((record) => !quarantined.has(record.eventKey) && !committed.has(record.eventKey)
         && !recovered.has(`${record.eventKey}:${record.payloadDigest}`))
-      .sort((left, right) => left.eventKey.localeCompare(right.eventKey))
-      .map((record) => record.snapshot);
+      .map((record) => [record.ordinal, record.eventKey]));
+    const payloads = [];
+    ordinal = 0;
+    if (pending.size) {
+      for (const record of readJsonl(this.path)) {
+        ordinal += 1;
+        if (pending.has(ordinal)) payloads.push({ eventKey: pending.get(ordinal), snapshot: record.snapshot });
+      }
+    }
+    return payloads.sort((left, right) => left.eventKey.localeCompare(right.eventKey)).map((record) => record.snapshot);
   }
 
   /** Keys pendingSnapshots() refused to replay because their records disagree, with the reason. */

package/plugin/scripts/project-progression-session-start.mjs

@@ -8,6 +8,7 @@ import { withProgressionReader } from './project-progression-reader.mjs';
 import { drainCaptureQueue, queuedWork } from './session-snapshot-hook.mjs';
 import { replayTurnQueue } from './turn-outcome-capture.mjs';
 import { STAGE_BUDGETS_MS } from './session-start-budget.mjs';
+import { operatorProgressionSuspension } from './project-progression-suspension.mjs';
 
 const PROGRESSION_NAMESPACE = 'project-progression';
 
@@ -191,6 +192,15 @@ export function restoreProgressionForSession({
   },
 } = {}) {
   const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
+  try {
+    if (operatorProgressionSuspension(env)) {
+      // Turn recording is independent: suspension must not strand ordinary AgentDB capture.
+      const turns = replayTurnQueue({ projectDir, env, home: env.HOME || os.homedir(), synchronous: true,
+        deadlineMs: Date.now() + deadlineMs });
+      return { status: 'unavailable', reason: 'operator-suspended', severity: 'info', pendingTurns: turns.pending,
+        context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nAutomatic progression capture, replay and restore are operator-suspended. Evidence and queues are preserved. Ordinary AgentDB memory and explicit checkpoints remain available; no project progression was restored.' };
+    }
+  } catch { return unknown('restore-failed'); }
   let resolution;
   try {
     resolution = resolveProjectStore({ projectDir });