ruvnet-brain 4.7.22 → 4.7.24

package/README.md

@@ -9,7 +9,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 ### Discover the stack. Read the source. Build with confidence.
 
-[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.22-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
+[![RuvNet Brain version 4.6.2 — README updated 2026-10-10 EDT](https://img.shields.io/badge/version_4.7.24-updated_2026--10--10_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](plugin/.claude-plugin/plugin.json)
 
 **A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
 

package/bin/install.mjs

@@ -25,7 +25,7 @@ import { applyBrainProfile, readBrainProfile } from '../kb/brain-profile.mjs';
 import { acquireRefreshLock, finishRefreshReceipt, openRefreshReceipt, physicalPath, recordRefreshAdvisory,
   recordRefreshPhase, settleRefreshRun, UPDATE_REFRESH_PHASES } from '../kb/refresh-run.mjs';
 import { assessLifecycleEvidence, pruneLifecycleEvidence } from '../kb/lifecycle-evidence-retention.mjs';
-import { checkDiskSpace, recoverIncompleteStorageTransactions } from '../kb/update-storage-transaction.mjs';
+import { checkDiskSpace, disposeRecoveryRequired, previewRecoveryRequired, recoverIncompleteStorageTransactions } from '../kb/update-storage-transaction.mjs';
 import { saveUpdateSource, stableNode } from '../plugin/scripts/automatic-update.mjs';
 import { acquireDeveloperLock } from '../plugin/scripts/developer-update-lock.mjs';
 import { footprintRoots, inventoryFootprint, sweepFootprint } from '../plugin/scripts/brain-footprint.mjs';
@@ -172,6 +172,13 @@ const MOVE_BRAIN_TO = (() => { const i = argv.indexOf('--move-brain'); const v =
 const FLAG_CLEAN = argv.includes('--clean'); // enforce the footprint guarantee now (ADR-0098), then confirm
 const FLAG_JSON = argv.includes('--json'); // with --doctor / --clean: machine-readable confirmation only
 const FLAG_ARCHIVE = argv.includes('--archive'); // with --clean only (#335): archive files unique to old KB copies, then release them
+// --recover-update (#335): show every update transaction stuck at RECOVERY_REQUIRED, changing nothing.
+// --recover-update --keep-live <sha256> [--transaction <id>]: keep that exact live tree, move the
+// transaction's other trees intact into .kb.recovered/<id>/, and record a terminal DISPOSED receipt.
+const FLAG_RECOVER_UPDATE = argv.includes('--recover-update');
+const argValue = (flag) => { const i = argv.indexOf(flag); const v = i === -1 ? null : argv[i + 1]; return v && !v.startsWith('-') ? v : null; };
+const RECOVER_KEEP_LIVE = argValue('--keep-live');
+const RECOVER_TRANSACTION = argValue('--transaction');
 // ── onboarding-experience flags (all optional; every offer is safe to decline) ──
 const FLAG_YES = argv.includes('--yes') || argv.includes('-y'); // accept every optional offer non-interactively
 const FLAG_PLAN = argv.includes('--plan') || argv.includes('--dry-run'); // show the interactive checklist, then exit — install NOTHING
@@ -4072,6 +4079,50 @@ export function acquireHostConvergenceLock(lockPath, {
   return { acquired: false, error: 'host synchronization lock changed concurrently' };
 }
 
+/**
+ * `--recover-update` (#335). Preview is read-only; disposition needs the exact live sha256 the preview
+ * printed, so nothing is decided for the operator. Returns the exit code.
+ */
+export function runRecoverUpdate({ kbDir = physicalPath(resolvedKbDir()), keepLive = RECOVER_KEEP_LIVE,
+  transaction = RECOVER_TRANSACTION, json = FLAG_JSON, log = console.log } = {}) {
+  const stuck = previewRecoveryRequired(kbDir);
+  const short = (identity) => identity?.sha256 ? `${identity.sha256}  (${identity.fileCount} files, ${identity.bytes} bytes)` : 'absent';
+  if (!keepLive) {
+    if (json) log(JSON.stringify({ kbDir, stuck }, null, 2));
+    else if (!stuck.length) log('No update is stuck at RECOVERY_REQUIRED. Nothing to recover.');
+    else {
+      for (const t of stuck) {
+        log(`Update ${t.transactionId} needs recovery: ${t.reason || 'no reason recorded'}`);
+        log(`  sealed prior:     ${short(t.sealed.prior)}`);
+        log(`  sealed candidate: ${short(t.sealed.candidate)}`);
+        for (const [name, tree] of Object.entries(t.trees)) {
+          const match = tree.matchesPrior ? ' = sealed prior' : tree.matchesCandidate ? ' = sealed candidate' : tree.exists ? ' matches no sealed identity' : '';
+          log(`  ${name.padEnd(9)} ${tree.exists ? short(tree.identity) : 'absent'}${match}`);
+        }
+        log(`  To keep the live tree above and close this update (other trees are moved, never deleted):`);
+        log(`    npx ruvnet-brain --recover-update --transaction ${t.transactionId} --keep-live ${t.trees.live.identity?.sha256 || '<live sha256>'}`);
+      }
+      log('Nothing was changed.');
+    }
+    return stuck.length ? 1 : 0;
+  }
+  const targets = transaction ? stuck.filter((t) => t.transactionId === transaction) : stuck;
+  if (!targets.length) { log(transaction ? `No stuck update named ${transaction}.` : 'No update is stuck at RECOVERY_REQUIRED.'); return 1; }
+  if (targets.length > 1) { log('More than one update is stuck; name one with --transaction <id>. Nothing was changed.'); return 1; }
+  try {
+    const result = disposeRecoveryRequired(kbDir, targets[0].transactionId, { keepLiveSha256: keepLive });
+    if (json) log(JSON.stringify(result, null, 2));
+    else {
+      log(`Closed update ${result.transactionId}: kept the live tree ${result.live.sha256}`
+        + ` (${result.liveMatchesPrior ? 'it equals the sealed prior' : result.liveMatchesCandidate ? 'it equals the sealed candidate' : 'it matches no sealed identity'}).`);
+      for (const p of result.preserved) log(`  moved ${p.tree} intact to ${p.to}`);
+      if (!result.preserved.length) log('  the update owned no other tree.');
+      log('Run  npx ruvnet-brain --update  next; nothing was deleted.');
+    }
+    return 0;
+  } catch (error) { log(`Not recovered: ${error.message}. Nothing was deleted.`); return 1; }
+}
+
 export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   sourceRoot = REPO_ROOT,
   brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain'),
@@ -6829,6 +6880,12 @@ Usage:
                               footprint within budget, no cruft. --doctor --json prints only that, as JSON.
   npx ruvnet-brain --clean    Remove everything that must not exist (old KB copies — never one holding
                               private files the live brain lacks — old installers, over-cap logs), then confirm.
+  npx ruvnet-brain --recover-update
+                              Read-only: list any update stuck at RECOVERY_REQUIRED, with the measured
+                              identity of the live tree and every tree that update owns.
+  npx ruvnet-brain --recover-update --keep-live <sha256> [--transaction <id>]
+                              Keep that exact live tree, move the update's other trees intact into
+                              .kb.recovered/<id>/ (nothing is deleted) and close the update for good.
   npx ruvnet-brain --clean --archive
                               Same, and for a kept copy: copy only the files it alone holds into
                               kb.archive/<stamp>/ (verified byte-for-byte), then release that copy.
@@ -6942,6 +6999,7 @@ the installer reports that boot-level declarations changed.
   // and `echo $?` → 0 coexisted for so long.
   // `--doctor --json`: the positive-confirmation object ONLY (no narration), exit 0 iff every line that
   // can be proven here is green — for scripts, CI, and agents (ADR-0098).
+  if (FLAG_RECOVER_UPDATE) { process.exitCode = runRecoverUpdate(); return; }
   if (FLAG_DOCTOR) { process.exitCode = await doctor({ json: FLAG_JSON }); return; }
   // `--clean`: enforce the footprint guarantee now, then confirm. Exit 0 only when exactly one KB copy
   // remains and nothing that must not exist is left (a private-unique copy kept for safety is a 1).

package/kb/lifecycle-evidence-retention.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { physicalPath } from './refresh-run.mjs';
 
 const TERMINAL_REFRESH = new Set(['SUCCEEDED', 'FAILED', 'ABANDONED']);
-const TERMINAL_TRANSACTION = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK']);
+const TERMINAL_TRANSACTION = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK', 'DISPOSED']);
 const SAFE_ID = /^[A-Za-z0-9._-]+$/;
 const PHASE_FILE = /^\d{3}-[A-Z_]+\.json$/;
 const QUARANTINE = /^\.prune-[A-Za-z0-9._-]+-[a-f0-9]{16}$/;

package/kb/update-storage-transaction.mjs

@@ -15,8 +15,13 @@ const STATES = Object.freeze([
   'COMMITTED',
   'ROLLED_BACK',
   'RECOVERY_REQUIRED',
+  'DISPOSED',
 ]);
 
+// Terminal states: recovery never acts on a transaction whose newest receipt is one of these.
+// DISPOSED is the operator's explicit, evidence-preserving end to a RECOVERY_REQUIRED transaction (#335).
+export const TERMINAL_TRANSACTION_STATES = Object.freeze(['NOOP', 'COMMITTED', 'ROLLED_BACK', 'DISPOSED']);
+
 // ── DISK-SPACE PREFLIGHT ──────────────────────────────────────────────────────────────────────────
 // An apply needs room for the unpacked bundle (temp), the candidate generation beside the live one
 // (the bundle plus the live node_modules carried into it) and its receipts; measured ~3.3 GB growth and
@@ -337,6 +342,7 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
     const phaseFiles = fs.readdirSync(receipts).filter((name) => /^\d{3}-[A-Z_]+\.json$/.test(name)).sort();
     if (!phaseFiles.length) throw new Error(`storage transaction receipt is empty: ${receipts}`);
     const latest = JSON.parse(fs.readFileSync(path.join(receipts, phaseFiles.at(-1)), 'utf8'));
+    if (latest.state === 'DISPOSED') continue;
     if (['NOOP', 'COMMITTED', 'ROLLED_BACK'].includes(latest.state)) {
       // A quarantined unsealed candidate is kept for ONE full update cycle, then released on the next
       // run — but only if its bytes are exactly what was sealed when it was quarantined.
@@ -354,7 +360,10 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
       }
       continue;
     }
-    if (latest.state === 'RECOVERY_REQUIRED') throw new Error(`storage transaction requires manual recovery: ${transactionId}`);
+    if (latest.state === 'RECOVERY_REQUIRED') {
+      throw new Error(`storage transaction requires manual recovery: ${transactionId} `
+        + `(preview with  npx ruvnet-brain --recover-update ; nothing is changed by the preview)`);
+    }
     const paths = latest.paths;
     const expectedPaths = transactionPaths(live, transactionId);
     if (!paths || ['live', 'candidate', 'rollback', 'failed'].some((name) =>
@@ -567,3 +576,154 @@ export function runStorageTransaction({
   record('COMMITTED', { terminalVerdict: 'applied', prior, candidate, storageDelta: delta });
   return { terminalVerdict: 'applied', prior, candidate, paths, storageDelta: delta };
 }
+
+// ── OPERATOR RECOVERY FOR A RECOVERY_REQUIRED TRANSACTION (#335) ──────────────────────────────────
+// Automatic recovery stops at RECOVERY_REQUIRED on purpose: the trees no longer match what the receipts
+// sealed, so no receipt can say which bytes are disposable. These two functions give the operator a
+// supported way out without weakening that check:
+//   1. previewRecoveryRequired() measures every tree the transaction owns and compares each with the
+//      identities its receipts sealed. It changes nothing.
+//   2. disposeRecoveryRequired() keeps the CURRENT live tree in service only when the operator names its
+//      exact sha256 from the preview, moves every other tree the transaction owns intact into
+//      `.<kb>.recovered/<transaction>/` (nothing is deleted), proves each moved tree is byte-identical
+//      after the move, and records a terminal DISPOSED receipt with what was measured. It never infers
+//      that live equals the prior sealed tree: it records whether it does.
+
+const SAFE_TRANSACTION_ID = /^[A-Za-z0-9._-]+$/;
+const OWNED_TREES = Object.freeze(['candidate', 'rollback', 'failed']);
+
+function receiptsRootFor(live) {
+  return path.join(path.dirname(live), `.${path.basename(live)}.update-transactions`);
+}
+
+/** Where a disposition keeps the trees it moved. Sibling of the live tree, so a move is a rename. */
+export function recoveredRootFor(liveDir) {
+  const live = path.resolve(liveDir);
+  return path.join(path.dirname(live), `.${path.basename(live)}.recovered`);
+}
+
+function latestReceipt(receipts) {
+  const phaseFiles = fs.readdirSync(receipts).filter((name) => /^\d{3}-[A-Z_]+\.json$/.test(name)).sort();
+  if (!phaseFiles.length) return null;
+  return JSON.parse(fs.readFileSync(path.join(receipts, phaseFiles.at(-1)), 'utf8'));
+}
+
+function sealedReceipts(receipts) {
+  // Every identity any receipt of this transaction sealed, newest last.
+  const out = { prior: null, candidate: null };
+  for (const name of fs.readdirSync(receipts).filter((n) => /^\d{3}-[A-Z_]+\.json$/.test(n)).sort()) {
+    try {
+      const r = JSON.parse(fs.readFileSync(path.join(receipts, name), 'utf8'));
+      if (r.prior?.sha256) out.prior = r.prior;
+      if (r.candidate?.sha256) out.candidate = r.candidate;
+    } catch { /* an unreadable receipt seals nothing */ }
+  }
+  return out;
+}
+
+const sameIdentity = (a, b) => Boolean(a?.sha256 && b?.sha256 && a.sha256 === b.sha256
+  && a.bytes === b.bytes && a.fileCount === b.fileCount);
+
+function measureTree(dir, sealed) {
+  let st = null;
+  try { st = fs.lstatSync(dir); } catch { /* absent */ }
+  if (!st) return { path: dir, exists: false, identity: null, matchesPrior: false, matchesCandidate: false };
+  if (st.isSymbolicLink() || !st.isDirectory()) {
+    return { path: dir, exists: true, directory: false, identity: null, matchesPrior: false, matchesCandidate: false };
+  }
+  const identity = identitySummary(treeIdentity(dir));
+  return { path: dir, exists: true, directory: true, identity,
+    matchesPrior: sameIdentity(identity, sealed.prior), matchesCandidate: sameIdentity(identity, sealed.candidate) };
+}
+
+/**
+ * Mutation-free report of every transaction whose newest receipt is RECOVERY_REQUIRED.
+ * @returns {Array<{transactionId:string, reason:string|null, recordedAt:string|null,
+ *   sealed:{prior:object|null,candidate:object|null}, trees:Record<string,object>}>}
+ */
+export function previewRecoveryRequired(liveDir) {
+  const live = path.resolve(liveDir);
+  const root = receiptsRootFor(live);
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const transactionId of fs.readdirSync(root).sort()) {
+    if (!SAFE_TRANSACTION_ID.test(transactionId) || transactionId.startsWith('.')) continue;
+    const receipts = path.join(root, transactionId);
+    if (!fs.lstatSync(receipts).isDirectory()) continue;
+    const latest = latestReceipt(receipts);
+    if (latest?.state !== 'RECOVERY_REQUIRED') continue;
+    const sealed = sealedReceipts(receipts);
+    const expected = transactionPaths(live, transactionId);
+    const trees = { live: measureTree(live, sealed) };
+    for (const name of OWNED_TREES) trees[name] = measureTree(expected[name], sealed);
+    out.push({ transactionId, reason: latest.reason || null, recordedAt: latest.recordedAt || null,
+      sealed: { prior: sealed.prior ? identitySummary(sealed.prior) : null,
+        candidate: sealed.candidate ? identitySummary(sealed.candidate) : null }, trees });
+  }
+  return out;
+}
+
+/**
+ * The operator's explicit disposition: keep the current live tree, preserve every other tree intact.
+ * @param {string} liveDir
+ * @param {string} transactionId
+ * @param {{ keepLiveSha256: string, rename?: Function }} options keepLiveSha256 must be the live tree's
+ *   sha256 exactly as the preview reported it; any change since the preview refuses.
+ */
+export function disposeRecoveryRequired(liveDir, transactionId, { keepLiveSha256, rename = fs.renameSync } = {}) {
+  const live = path.resolve(liveDir);
+  if (!SAFE_TRANSACTION_ID.test(String(transactionId || '')) || String(transactionId).startsWith('.')) {
+    throw new Error(`not a transaction id: ${transactionId}`);
+  }
+  if (!/^[a-f0-9]{64}$/.test(String(keepLiveSha256 || ''))) {
+    throw new Error('name the live tree to keep by the exact sha256 the preview printed (--keep-live <sha256>)');
+  }
+  const receipts = path.join(receiptsRootFor(live), transactionId);
+  if (!fs.existsSync(receipts) || !fs.lstatSync(receipts).isDirectory()) throw new Error(`no such transaction: ${transactionId}`);
+  const latest = latestReceipt(receipts);
+  if (latest?.state !== 'RECOVERY_REQUIRED') {
+    throw new Error(`transaction ${transactionId} is ${latest?.state || 'empty'}, not RECOVERY_REQUIRED; nothing to dispose`);
+  }
+  const expected = transactionPaths(live, transactionId);
+  if (latest.paths && ['live', ...OWNED_TREES].some((name) => latest.paths[name] && path.resolve(latest.paths[name]) !== expected[name])) {
+    throw new Error(`transaction ${transactionId} names paths that belong to another live tree; refusing`);
+  }
+  assertDirectory(live, 'live tree');
+  const sealed = sealedReceipts(receipts);
+  const liveIdentity = identitySummary(treeIdentity(live));
+  if (liveIdentity.sha256 !== keepLiveSha256) {
+    throw new Error(`the live tree changed since the preview (now ${liveIdentity.sha256}); run the preview again`);
+  }
+  const archiveDir = path.join(recoveredRootFor(live), transactionId);
+  const moves = [];
+  for (const name of OWNED_TREES) {
+    const source = expected[name];
+    if (!fs.existsSync(source)) continue;
+    assertDirectory(source, `transaction ${name} tree`);
+    const target = path.join(archiveDir, name);
+    if (fs.existsSync(target)) throw new Error(`recovered tree already exists: ${target}`);
+    moves.push({ name, source, target, before: identitySummary(treeIdentity(source)) });
+  }
+  fs.mkdirSync(archiveDir, { recursive: true });
+  const preserved = [];
+  for (const move of moves) {
+    rename(move.source, move.target);
+    const after = identitySummary(treeIdentity(move.target));
+    if (!sameIdentity(after, move.before)) {
+      throw new Error(`${move.name} tree changed while it was moved to ${move.target}; it is kept there, nothing was deleted`);
+    }
+    preserved.push({ tree: move.name, from: move.source, to: move.target, identity: after,
+      matchesPrior: sameIdentity(after, sealed.prior), matchesCandidate: sameIdentity(after, sealed.candidate) });
+  }
+  const receipt = appendRecoveryReceipt(receipts, 'DISPOSED', {
+    terminalVerdict: 'operator-kept-live',
+    live: liveIdentity,
+    liveMatchesPrior: sameIdentity(liveIdentity, sealed.prior),
+    liveMatchesCandidate: sameIdentity(liveIdentity, sealed.candidate),
+    preserved,
+    recoveredFrom: { reason: latest.reason || null, recordedAt: latest.recordedAt || null },
+    reason: 'operator kept the current live tree; every other tree this transaction owned was moved intact, not deleted',
+  });
+  return { transactionId, terminalVerdict: 'operator-kept-live', live: liveIdentity,
+    liveMatchesPrior: receipt.liveMatchesPrior, liveMatchesCandidate: receipt.liveMatchesCandidate, preserved, archiveDir };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.22",
+  "version": "4.7.24",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -77,6 +77,7 @@
     "deferral:replay": "node scripts/deferral-replay.mjs",
     "hooks:check": "node scripts/hook-retirement-check.mjs",
     "release:qualify": "node scripts/release-qualification.mjs",
+    "release:prepush": "node scripts/release-prepush.mjs",
     "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs",
     "single-source:check": "node scripts/single-source-check.mjs",
     "host:codex:execution-proof": "node scripts/codex-host-execution-proof.mjs"

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.7.22",
+  "version": "4.7.24",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.22",
+  "version": "4.7.24",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/scripts/brain-footprint.mjs

@@ -70,7 +70,7 @@ const RUFLO_DEBRIS = new Set(RUFLO_CWD_ARTIFACTS);
 // Directories in the brain home that hold data another tool owns: measured, shown, never budgeted or removed.
 const FOREIGN = { 'ruvector-mcp': 'RuVector MCP server working store (its own live memory)',
   'worktree-recovery': 'hand-made recovery archives, not created by the Brain' };
-const TERMINAL = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK']);
+const TERMINAL = new Set(['NOOP', 'COMMITTED', 'ROLLED_BACK', 'DISPOSED']); // DISPOSED: operator recovery (#335)
 
 const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
 const lstat = (file) => { try { return fs.lstatSync(file); } catch { return null; } };
@@ -190,6 +190,10 @@ export function inventoryFootprint({ env = process.env, home = os.homedir(), now
     }
   };
   const classifySibling = (name, full, st) => {
+    if (name === `.${base}.recovered` && st.isDirectory() && !st.isSymbolicLink()) { // #335: written only by --recover-update --keep-live
+      return void add({ id: 'kb-recovered', path: full, class: 'may-exist', kind: 'kb-recovered', action: 'keep', bytes: bytes(full),
+        reason: 'trees an operator-disposed update transaction owned, moved intact (--recover-update); never removed automatically' });
+    }
     if (name === `${base}.archive` && st.isDirectory() && !st.isSymbolicLink()) { // #335: written only by --clean --archive
       return void add({ id: 'kb-archive', path: full, class: 'may-exist', kind: 'kb-archive', action: 'keep', bytes: bytes(full),
         reason: 'files unique to released KB copies, archived on request (--clean --archive); never removed automatically' });

package/plugin/scripts/learn-capture.mjs

@@ -24,6 +24,21 @@ const learnDir = (brainHome, sub) => { const dir = path.join(brainHome, 'learn-c
 export function recentlyCaptured(brainHome, key, now = Date.now()) {
   try { return now - fs.statSync(path.join(learnDir(brainHome, 'recent'), key)).mtimeMs < COALESCE_MS; } catch { return false; }
 }
+// #377 residual (sparkling, 2026-10-30): the parent used to call markCaptured() BEFORE the detached child stored
+// anything, so a child whose store or exact readback failed left the key acknowledged as captured for the whole
+// COALESCE_MS window. Now the parent only marks the key IN FLIGHT (`<key>.pending`, which is never an
+// acknowledgement and expires with the child's slot), and the child acknowledges with markCaptured() only after
+// recordLearningObservation() has completed its exact readback. A failed child clears the in-flight mark.
+const inFlightMarker = (brainHome, key) => path.join(learnDir(brainHome, 'recent'), `${key}.pending`);
+export function captureInFlight(brainHome, key, now = Date.now()) {
+  try { return now - fs.statSync(inFlightMarker(brainHome, key)).mtimeMs < SLOT_STALE_MS; } catch { return false; }
+}
+export function markInFlight(brainHome, key) {
+  try { fs.writeFileSync(inFlightMarker(brainHome, key), '', { mode: 0o600 }); } catch { /* best effort: coalescing only */ }
+}
+export function clearInFlight(brainHome, key) {
+  try { fs.unlinkSync(inFlightMarker(brainHome, key)); } catch { /* already gone */ }
+}
 export function markCaptured(brainHome, key, now = Date.now()) {
   const dir = learnDir(brainHome, 'recent');
   try { fs.writeFileSync(path.join(dir, key), '', { mode: 0o600 }); } catch { return; }
@@ -105,12 +120,13 @@ export function captureLearning(input, { env = process.env, binary = resolveRufl
     const observation = { tool, action, session: String(input.session_id || '') };
     const key = observationKey(observation);
     if (recentlyCaptured(brainHome, key)) return true; // identical observation already captured this window: no process
+    if (detach && captureInFlight(brainHome, key)) return true; // the same observation is being stored right now
     // Review M3: on the hook path the store + exact readback run in a detached, bounded child, so the
     // tool call returns at once; that child writes the ledger row if the write is refused or unverified.
     if (detach) {
       const slot = acquireObserveSlot(brainHome);
       if (!slot) return shedObservation(brainHome);
-      markCaptured(brainHome, key);
+      markInFlight(brainHome, key); // NOT an acknowledgement: only the child's exact readback acknowledges (#377)
       return detachLearning('--observe', { env: { ...env, RUFLO_BIN: binary }, brainHome, observation, slot });
     }
     recordLearningObservation(binary, context, observation, { env, deadline: Date.now() + 6000 });
@@ -136,6 +152,8 @@ export function detachLearning(mode, { env = process.env, brainHome, observation
 }
 
 function runDetached(mode) {
+  const brainHome = defaultBrainHome(process.env);
+  let observation = null;
   const fail = (error) => recordHookFailure({ hook: mode === '--distill' ? 'learn-distill' : 'learn-capture', event: mode === '--distill' ? 'SessionEnd' : 'PostToolUse', error: String(error?.message || error).slice(0, 160) });
   try {
     const context = learningContext(); // consent is re-read: a withdrawn consent writes nothing
@@ -145,8 +163,13 @@ function runDetached(mode) {
     if (mode === '--distill') { distillObservations(binary, context, { env: process.env }); return; }
     const o = JSON.parse(process.env.RUVNET_LEARN_OBSERVATION || '{}');
     if (!['Bash', 'Write', 'Edit', 'MultiEdit'].includes(o.tool) || typeof o.action !== 'string') throw new Error('invalid detached observation');
-    recordLearningObservation(binary, context, { tool: o.tool, action: o.action, session: String(o.session || '') }, { env: process.env, deadline: Date.now() + 14_000, allowed: () => learningContext().enabled });
-  } catch (error) { fail(error); } finally { if (process.env.RUVNET_LEARN_SLOT) releaseObserveSlot(process.env.RUVNET_LEARN_SLOT); }
+    observation = { tool: o.tool, action: o.action, session: String(o.session || '') };
+    recordLearningObservation(binary, context, observation, { env: process.env, deadline: Date.now() + 14_000, allowed: () => learningContext().enabled });
+    markCaptured(brainHome, observationKey(observation)); // acknowledged only after the exact readback succeeded (#377)
+  } catch (error) { fail(error); } finally {
+    if (observation) clearInFlight(brainHome, observationKey(observation));
+    if (process.env.RUVNET_LEARN_SLOT) releaseObserveSlot(process.env.RUVNET_LEARN_SLOT);
+  }
 }
 
 const isMain = isDirectInvocation(import.meta.url);

package/scripts/generation-census.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// DISTINCT-FROM: kb/zip-extract.mjs — that extracts a whole local archive from a file descriptor; this reads only the idmap sidecars of a REMOTE release asset over HTTP Range and never fetches the ~750 MB body.
+//
+// scripts/generation-census.mjs — the public census (public stores, chunks) of a published corpus
+// generation, read straight from its release asset without downloading it.
+//
+// Release QE requires the committed claim surfaces (README, explainer/*) to quote the exact census of
+// the NEWEST corpus generation, and the corpus republishes nightly. Assembling a candidate to learn
+// two numbers costs ~750 MB and a minute; the numbers live in ~200 small `*.big.rvf.idmap.json`
+// members of the zip. So: Range-read the end-of-central-directory, the central directory, and each
+// idmap member; inflate, CRC-check, count `idToLabel` keys; exclude the private fence exactly as
+// scripts/claims-verify.mjs computePublicChunkTotal does. Anything unexpected (zip64, another
+// compression method, a CRC mismatch, a short read) fails loudly — a wrong census is worse than none.
+//
+//   node scripts/generation-census.mjs --repo owner/name --tag corpus-sha256-<digest>
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const ARCHIVE_ASSET = 'ruvnet-brain.zip';
+export const IDMAP_SUFFIX = '.big.rvf.idmap.json';
+const TAIL_BYTES = 66_000; // EOCD (22) + the largest possible comment (65,535) + the zip64 locator (20)
+const SIG = { eocd: 0x06054b50, zip64Locator: 0x07064b50, central: 0x02014b50, local: 0x04034b50 };
+const U16 = 0xffff;
+const U32 = 0xffffffff;
+const CONCURRENCY = 8;
+
+const zip64 = (what) => new Error(`zip64 ${what}: this reader refuses zip64 archives rather than guess at their layout`);
+
+/** End-of-central-directory from the archive's last bytes. */
+export function parseEocd(tail) {
+  for (let i = tail.length - 22; i >= 0; i -= 1) {
+    if (tail.readUInt32LE(i) !== SIG.eocd) continue;
+    if (i >= 20 && tail.readUInt32LE(i - 20) === SIG.zip64Locator) throw zip64('end-of-central-directory locator');
+    const disk = tail.readUInt16LE(i + 4), cdDisk = tail.readUInt16LE(i + 6);
+    const onDisk = tail.readUInt16LE(i + 8), total = tail.readUInt16LE(i + 10);
+    const cdSize = tail.readUInt32LE(i + 12), cdOffset = tail.readUInt32LE(i + 16);
+    if (total === U16 || onDisk === U16 || cdSize === U32 || cdOffset === U32) throw zip64('marker in the end-of-central-directory');
+    if (disk !== 0 || cdDisk !== 0 || onDisk !== total) throw new Error('multi-disk zip archives are not supported');
+    return { total, cdSize, cdOffset };
+  }
+  throw new Error('no end-of-central-directory record in the archive tail');
+}
+
+/** Every central-directory entry: name, method, flags, crc, sizes, local-header offset. */
+export function parseCentralDirectory(cd, expected) {
+  const entries = [];
+  let p = 0;
+  while (p < cd.length) {
+    if (p + 46 > cd.length || cd.readUInt32LE(p) !== SIG.central) throw new Error(`malformed central directory at byte ${p}`);
+    const nameLength = cd.readUInt16LE(p + 28), extraLength = cd.readUInt16LE(p + 30), commentLength = cd.readUInt16LE(p + 32);
+    const entry = {
+      name: cd.subarray(p + 46, p + 46 + nameLength).toString('utf8'),
+      flags: cd.readUInt16LE(p + 8), method: cd.readUInt16LE(p + 10), crc: cd.readUInt32LE(p + 16),
+      compressedSize: cd.readUInt32LE(p + 20), size: cd.readUInt32LE(p + 24), offset: cd.readUInt32LE(p + 42),
+      extraLength,
+    };
+    if (entry.compressedSize === U32 || entry.size === U32 || entry.offset === U32) throw zip64(`marker on entry ${entry.name}`);
+    const extra = cd.subarray(p + 46 + nameLength, p + 46 + nameLength + extraLength);
+    for (let q = 0; q + 4 <= extra.length; q += 4 + extra.readUInt16LE(q + 2)) {
+      if (extra.readUInt16LE(q) === 0x0001) throw zip64(`extra field on entry ${entry.name}`);
+    }
+    entries.push(entry);
+    p += 46 + nameLength + extraLength + commentLength;
+  }
+  if (Number.isInteger(expected) && entries.length !== expected) {
+    throw new Error(`central directory lists ${entries.length} entries; the end record says ${expected}`);
+  }
+  return entries;
+}
+
+/** The public idmap members: no resource forks, no private store, no store counted twice. */
+export function selectIdmapEntries(entries, privateStores = []) {
+  const fence = new Set(privateStores);
+  const seen = new Map();
+  for (const entry of entries) {
+    if (!entry.name.endsWith(IDMAP_SUFFIX) || entry.name.split('/').includes('__MACOSX')) continue;
+    const base = path.posix.basename(entry.name);
+    if (base.startsWith('._')) continue;
+    const store = base.slice(0, -IDMAP_SUFFIX.length);
+    if (fence.has(store)) continue;
+    if (seen.has(store)) throw new Error(`store ${store} has two idmap members (${seen.get(store).name}, ${entry.name})`);
+    seen.set(store, { ...entry, store });
+  }
+  return [...seen.values()];
+}
+
+/** One member's bytes from a buffer that starts at its local header; null when the buffer is too short. */
+export function decodeEntry(entry, local) {
+  if (local.length < 30 || local.readUInt32LE(0) !== SIG.local) throw new Error(`no local header for ${entry.name}`);
+  const start = 30 + local.readUInt16LE(26) + local.readUInt16LE(28);
+  if (local.length < start + entry.compressedSize) return { need: start + entry.compressedSize };
+  const raw = local.subarray(start, start + entry.compressedSize);
+  let data;
+  if (entry.method === 0) data = raw;
+  else if (entry.method === 8) data = zlib.inflateRawSync(raw);
+  else throw new Error(`${entry.name} uses compression method ${entry.method}; only stored (0) and deflate (8) are read`);
+  if (typeof zlib.crc32 !== 'function') throw new Error('zlib.crc32 is unavailable (Node >= 20.15 / 22.2 required) — cannot verify members');
+  if (data.length !== entry.size) throw new Error(`${entry.name} inflated to ${data.length} bytes; the directory says ${entry.size}`);
+  const crc = zlib.crc32(data) >>> 0;
+  if (crc !== entry.crc >>> 0) throw new Error(`${entry.name} failed its CRC-32 check (expected ${entry.crc.toString(16)}, got ${crc.toString(16)})`);
+  return { data };
+}
+
+export function countIdmap(buffer, name) {
+  const { idToLabel } = JSON.parse(buffer.toString('utf8'));
+  if (!idToLabel || typeof idToLabel !== 'object' || Array.isArray(idToLabel)) throw new Error(`${name} has no idToLabel object`);
+  return Object.keys(idToLabel).length;
+}
+
+export function readPrivateStores(file = path.join(ROOT, 'kb', 'PRIVATE-STORES.json')) {
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!Array.isArray(parsed?.privateStores)) throw new Error(`${file} lacks a privateStores array`);
+  return [...parsed.privateStores].sort();
+}
+
+/** The release asset row (id, size, url) from the GitHub API. */
+async function resolveAsset({ repo, tag, fetch, token }) {
+  const headers = { Accept: 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+  const response = await fetch(`https://api.github.com/repos/${repo}/releases/tags/${encodeURIComponent(tag)}`, { headers });
+  if (!response.ok) throw new Error(`release ${tag}: GitHub API answered HTTP ${response.status}`);
+  const assets = ((await response.json())?.assets || []).filter((asset) => asset?.name === ARCHIVE_ASSET);
+  if (assets.length !== 1) throw new Error(`release ${tag} has ${assets.length} ${ARCHIVE_ASSET} assets; expected exactly one`);
+  return { id: assets[0].id, size: assets[0].size, url: assets[0].browser_download_url };
+}
+
+/** Range reads against the asset; the redirect is resolved once and re-resolved if the signed URL lapses. */
+function rangeReader({ url, size, fetch }) {
+  let target = url;
+  let fetched = 0;
+  const read = async (start, end, retried = false) => {
+    const response = await fetch(target, { headers: { Range: `bytes=${start}-${end}` }, redirect: 'follow' });
+    if (response.status !== 206) {
+      if (!retried && target !== url) { target = url; return read(start, end, true); }
+      throw new Error(`range ${start}-${end} of ${url}: expected HTTP 206, got ${response.status}`);
+    }
+    const total = Number(/\/(\d+)$/.exec(response.headers.get('content-range') || '')?.[1]);
+    if (total !== size) throw new Error(`asset is ${total} bytes; the release says ${size}`);
+    if (response.url) target = response.url;
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length !== end - start + 1) throw new Error(`short range read ${start}-${end}: ${buffer.length} bytes`);
+    fetched += buffer.length;
+    return buffer;
+  };
+  return { read, fetched: () => fetched };
+}
+
+async function pool(items, limit, work) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) { const i = next++; out[i] = await work(items[i]); }
+  }));
+  return out;
+}
+
+export async function rangeCensus({ repo, tag, bytes = null, privateStoresFile, fetch = globalThis.fetch,
+  cacheDir = os.tmpdir(), token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null, asset = null,
+  concurrency = CONCURRENCY } = {}) {
+  if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('repo must be owner/name');
+  if (!/^[A-Za-z0-9._-]+$/.test(String(tag || ''))) throw new Error(`invalid release tag: ${tag}`);
+  const privateStores = readPrivateStores(privateStoresFile);
+  const resolved = asset || await resolveAsset({ repo, tag, fetch, token });
+  if (!Number.isSafeInteger(resolved.size) || resolved.size < 22) throw new Error(`release ${tag} asset has no usable size`);
+  if (bytes !== null && bytes !== resolved.size) throw new Error(`release ${tag} asset is ${resolved.size} bytes; expected ${bytes}`);
+
+  const key = crypto.createHash('sha256').update(JSON.stringify({ repo, tag, assetId: resolved.id, size: resolved.size, privateStores }))
+    .digest('hex').slice(0, 32);
+  const cacheFile = path.join(cacheDir, 'ruvnet-brain-generation-census', `${key}.json`);
+  try {
+    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    if (cached?.tag === tag && Number.isSafeInteger(cached.chunks)) return { ...cached, cached: true };
+  } catch { /* no usable cache entry: measure */ }
+
+  const started = Date.now();
+  const { read, fetched } = rangeReader({ url: resolved.url || `https://github.com/${repo}/releases/download/${tag}/${ARCHIVE_ASSET}`,
+    size: resolved.size, fetch });
+  const tailStart = Math.max(0, resolved.size - TAIL_BYTES);
+  const eocd = parseEocd(await read(tailStart, resolved.size - 1));
+  if (eocd.cdOffset + eocd.cdSize > resolved.size) throw new Error('central directory lies outside the archive');
+  const entries = parseCentralDirectory(await read(eocd.cdOffset, eocd.cdOffset + eocd.cdSize - 1), eocd.total);
+  const selected = selectIdmapEntries(entries, privateStores);
+  if (!selected.length) throw new Error(`release ${tag} contains no public *${IDMAP_SUFFIX} members`);
+  const counts = await pool(selected, concurrency, async (entry) => {
+    const guess = 30 + Buffer.byteLength(entry.name) + entry.extraLength + entry.compressedSize + 256;
+    let local = await read(entry.offset, Math.min(resolved.size, entry.offset + guess) - 1);
+    let decoded = decodeEntry(entry, local);
+    if (decoded.need) {
+      local = await read(entry.offset, entry.offset + decoded.need - 1);
+      decoded = decodeEntry(entry, local);
+      if (decoded.need) throw new Error(`${entry.name}: local header disagrees with the central directory`);
+    }
+    return countIdmap(decoded.data, entry.name);
+  });
+  const result = { tag, publicStores: selected.length, chunks: counts.reduce((a, b) => a + b, 0), builtStores: selected.length,
+    assetId: resolved.id ?? null, archiveBytes: resolved.size, fetchedBytes: fetched(), entries: entries.length,
+    seconds: Math.round((Date.now() - started) / 100) / 10 };
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const temp = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(result, null, 2)}\n`);
+    fs.renameSync(temp, cacheFile);
+  } catch { /* a cache is an optimisation; the measured result stands */ }
+  return { ...result, cached: false };
+}
+
+const arg = (argv, name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+
+if (isDirectInvocation(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  rangeCensus({ repo: arg(argv, '--repo') || process.env.GITHUB_REPOSITORY, tag: arg(argv, '--tag') })
+    .then((result) => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`))
+    .catch((error) => { console.error(`[generation-census] ${error.message}`); process.exitCode = 1; });
+}