ruvnet-brain 4.7.23 → 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.23-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.23",
+  "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": {

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.23",
+  "version": "4.7.24",
   "author": {
     "name": "Stuart Kerr"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.7.23",
+  "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/issue-autofix-night.mjs

@@ -139,7 +139,7 @@ export async function shipAndSettle(rt, journal) {
     publish('fixed', ['install-verified on Linux, macOS and Windows']);
     patchNs(rt.paths.state, { _daily: { day: etDay(rt.now()), shipped: true, version: journal.version, issues: journal.issues } });
     rt.page(`AUTOFIX SHIPPED v${journal.version}`, `Issues ${journal.issues.join(', ')}; install-verified on main ${journal.sha}.`, 'low');
-    return { items, status: 'shipped', exitCode: 0 };
+    return { items, status: res.phase, exitCode: 0 }; // derived from the release result, never a literal (ADR-0024)
   }
   if (res.phase === 'published-unverified') {
     publish('shipping', []);

package/scripts/onboarding-console.mjs

@@ -2092,7 +2092,12 @@ function gatherActivity(cwd) {
 // recent decisions from its append-only log. Nothing here can disagree with what actually routes.
 function gatherRouterEngine() {
   const profile = engineProfile();
-  const candidates = applyProfile(engineCatalog(), profile);
+  // A missing or invalid per-user engine catalog is a degraded panel (catalogSource says 'unavailable'),
+  // never a thrown read model that takes the whole Console API down with it (issue #86 boundary; red on
+  // CI from 4.7.22, where no per-user catalog exists). No built-in model list is substituted.
+  let engineCandidates = [];
+  try { engineCandidates = engineCatalog(); } catch { /* reported through catalogSource: 'unavailable' */ }
+  const candidates = applyProfile(engineCandidates, profile);
   const prices = effectivePrices(candidates, profile);
   const { rows, unusable } = loadLabelledRows();
   const installed = fs.existsSync(path.join(__dirname, '..', 'node_modules', '@metaharness', 'router', 'package.json'));

package/scripts/release-qualification-contract.mjs

@@ -355,6 +355,15 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "macos": ["tests/unit/continuation-gate-codex-transcript.test.mjs", "tests/unit/codex-boot-surface-proof.test.mjs", "tests/unit/console-activity-fleet-dedupe.test.mjs", "tests/unit/console-activity-identity.test.mjs", "tests/unit/console-activity-lessons.test.mjs", "tests/unit/lesson-gate.test.mjs", "tests/unit/ruflo-memory-session.test.mjs"]
       }
     },
+    {
+      "id": "open-issue-fixes-4-7-24",
+      "reason": "A storage transaction stuck at RECOVERY_REQUIRED has a supported way out: a read-only preview, then an explicit keep-live disposition bound to the live tree's exact sha256 that moves every other tree intact and records a terminal DISPOSED receipt (#335); a detached learning capture is acknowledged only after its exact readback, so a refused store is retried instead of being coalesced away for ten minutes (#377). Windows is not verified",
+      "files": [],
+      "platformFiles": {
+        "linux": ["tests/unit/update-recovery-disposition.test.mjs", "tests/unit/learn-capture-ack-after-readback.test.mjs"],
+        "macos": ["tests/unit/update-recovery-disposition.test.mjs", "tests/unit/learn-capture-ack-after-readback.test.mjs"]
+      }
+    },
     {
       "id": "issue-autofix-bounded-writer",
       "reason": "The unattended issue fixer (ADR-107) stays inside its authority: kill switch, single-writer lock, deny-by-default editable paths, the static malware and secret scan, the manifest/lockfile/pack/audit night gate, the red-team judge, restricted tool-less LLM stages, the macOS sandbox for model-written code (macOS only), never-weakened tests, independent verifier, resumable never-doubled release steps, no force or merge, owner-marker-prefixed comments, personal notes that are never boilerplate or repeated, and a registry and LaunchAgent that match. It runs on the owner's macOS launchd, so it is qualified on macOS and Linux only, the same scope as the ntfy inbox reader",