ruvnet-brain 4.7.23 → 4.7.25

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.25-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
@@ -2101,6 +2108,12 @@ export function codexBrokenMarketplaces(text) {
 }
 const sleepSync = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
 
+// `codex plugin list` refreshes Codex's remote plugin catalog when its cache is stale: a 56 MB download measured at
+// 38-40 s on the owner's Mac (codex-cli 0.166.0, 2026-10-30). The old 30 s limit killed it every time, and a killed
+// fetch writes no cache, so every later attempt (the 03:30 nightly, each retry, each --update) repeated the cold fetch
+// and failed the same way until someone used Codex by hand. Bounded, with ~4x headroom over the measured fetch.
+export const CODEX_PLUGIN_COMMAND_TIMEOUT_MS = 180_000;
+
 export function runCodexJson(args, {
   codexBin = process.env.CODEX_BIN || 'codex',
   codexHome = codexHomeDir(),
@@ -2110,9 +2123,10 @@ export function runCodexJson(args, {
   // Refreshing another tool's marketplace is a network write; only an install/update that is about to change the
   // Brain's Codex plugin opts in. --doctor and listings report the broken snapshot and change nothing (review 2026-10-24).
   repair = false,
+  timeoutMs = CODEX_PLUGIN_COMMAND_TIMEOUT_MS,
 } = {}) {
   const options = { stdio: 'pipe', shell: false, cwd, env: { ...process.env, CODEX_HOME: codexHome }, encoding: 'utf8',
-    timeout: 30_000, maxBuffer: 20 * 1024 * 1024 };
+    timeout: timeoutMs, maxBuffer: 20 * 1024 * 1024 };
   const snapshotFailure = (res) => !res.missingBinary && res.status !== 0 && CODEX_SNAPSHOT_FAILURE.test(String(res.stderr || res.stdout || ''));
   let r = run(codexBin, args, options);
   // One wait covers a refresh Codex is finishing; then refresh only the OTHER Git marketplaces it named (the Brain's
@@ -4072,6 +4086,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'),
@@ -4105,51 +4163,66 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     return { ok: false, results, ...detail, error: detail.error || hostFailureReason(results) };
   };
 
+  // ONE HOST CANNOT HOLD THE OTHERS BACK (2026-10-30). A Codex failure used to return before the Stable Spine and the
+  // convergence receipt, so a single `codex plugin list` timeout left Claude Code on the new plugin, the runtime and
+  // Codex on the old one, and no receipt saying so (owner's Mac, 4.7.21 -> 4.7.24, three nights). Each host is now
+  // attempted on its own, the runtime is activated regardless, and a failed host is RECORDED as `failed` with its
+  // reason: the run still ends not-ok, so the night still fails and pages, but nothing is left half-updated.
+  const failedHosts = new Set();
+  const hostError = (error) => error?.message || String(error);
   try {
     if (wireClaude === wirePlugin) results.hookRetirement = retireManagedHookRegistrations();
     results.claude = wireClaude === wirePlugin
       ? wirePlugin({ expectedVersion: PACKAGE_VERSION, requireManaged: true })
       : wireClaude({ expectedVersion: PACKAGE_VERSION, requireManaged: true });
-    if (results.claude.host && !results.claude.wired) return fail();
+    if (results.claude.host && !results.claude.wired) failedHosts.add('claude');
+  } catch (error) {
+    results.claude = { host: true, wired: false, action: 'failed', error: hostError(error) };
+    failedHosts.add('claude');
+  }
+  try {
     results.codexHost = detectCodexHost();
     if (results.codexHost.host) {
       if (!['added', 'rewritten', 'unchanged', 'user-owned'].includes(results.codexHost.action)) {
-        return fail({ error: `Codex host convergence failed: ${results.codexHost.action || 'unknown action'}` });
-      }
-      results.codex = installCodexPlugin({ expectedVersion: PACKAGE_VERSION });
-      // ~/.codex exists but no `codex` binary is on PATH (an uninstalled CLI, or a desktop-only setup whose shell
-      // cannot see it): there is no Codex host to converge here, which is absence, not a failed update (4.7.21,
-      // audit C-opus #6). Any other unavailability (the binary ran and failed) still fails.
-      if (results.codex.action === 'codex-unavailable' && results.codex.missingBinary === true) {
-        results.codexAbsent = true;
-      } else if (!['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
-        return fail();
+        results.codexHostError = `Codex host convergence failed: ${results.codexHost.action || 'unknown action'}`;
+        failedHosts.add('codex');
+      } else {
+        results.codex = installCodexPlugin({ expectedVersion: PACKAGE_VERSION });
+        // ~/.codex exists but no `codex` binary is on PATH (an uninstalled CLI, or a desktop-only setup whose shell
+        // cannot see it): there is no Codex host to converge here, which is absence, not a failed update (4.7.21,
+        // audit C-opus #6). Any other unavailability (the binary ran and failed) still fails.
+        if (results.codex.action === 'codex-unavailable' && results.codex.missingBinary === true) {
+          results.codexAbsent = true;
+        } else if (!['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
+          failedHosts.add('codex');
+        }
       }
     }
   } catch (error) {
-    results.codex = { action: 'failed', error: error?.message || String(error) };
-    return fail();
+    results.codex = { action: 'failed', error: hostError(error) };
+    failedHosts.add('codex');
   }
 
   const apply = path.join(sourceRoot, 'plugin', 'scripts', 'update-apply.mjs');
   if (!fs.existsSync(apply)) return fail({ error: 'Stable Spine updater missing from package' });
   const applied = runStableSpine(apply);
   const okApplied = !applied.error && applied.status === 0;
-  const codexReceipt = {
-    state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host && !results.codexAbsent ? 'ready' : 'absent'),
-    version: results.codex?.version || null,
-  };
-  if (results.codex?.restartRequired === true) {
+  const codexReceipt = failedHosts.has('codex')
+    ? { state: 'failed', version: results.codex?.version || null, error: hostFailureReason({ codex: results.codex, codexHostError: results.codexHostError }) }
+    : {
+      state: results.codex?.action === 'disabled' ? 'disabled' : (results.codexHost?.host && !results.codexAbsent ? 'ready' : 'absent'),
+      version: results.codex?.version || null,
+    };
+  if (!failedHosts.has('codex') && results.codex?.restartRequired === true) {
     codexReceipt.restartRequired = true;
     codexReceipt.sessionSafety = results.codex.sessionSafety || null;
     codexReceipt.sessionSafetyReason = results.codex.sessionSafetyReason || null;
     codexReceipt.restartScope = results.codex.restartScope || 'unproven';
   }
-  const claudeReceipt = {
-    state: results.claude.host ? 'ready' : 'absent',
-    version: results.claude.version || null,
-  };
-  if (results.claude?.restartRequired === true) {
+  const claudeReceipt = failedHosts.has('claude')
+    ? { state: 'failed', version: results.claude.version || null, error: hostFailureReason({ claude: results.claude }) }
+    : { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null };
+  if (!failedHosts.has('claude') && results.claude?.restartRequired === true) {
     claudeReceipt.restartRequired = true;
     claudeReceipt.sessionSafety = results.claude.sessionSafety || null;
     claudeReceipt.sessionSafetyReason = results.claude.sessionSafetyReason || null;
@@ -4236,6 +4309,11 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   };
   const convergence = classifyHostConvergence(convergedReceipt);
   hostLock.release();
+  if (failedHosts.size) {
+    // The runtime and every other host converged; the failed host is the night's failure, with its own reason.
+    return { ok: false, convergence, results, applyStatus: applied.status, failedHosts: [...failedHosts],
+      error: `${hostFailureReason(results)}; runtime ${PACKAGE_VERSION} and the other hosts converged` };
+  }
   return { ok: convergence.healthy === true, convergence, results, applyStatus: applied.status,
     ...(convergence.healthy !== true && hostRestartIsOnlyGap(convergedReceipt) ? { restartOnly: true } : {}),
     error: convergence.healthy === true ? null : `host convergence is ${convergence.state}: ${convergence.action}` };
@@ -4374,13 +4452,16 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
 /** Why host synchronization stopped, from the per-host results it had gathered; null when nothing says. */
 export function hostFailureReason(results = {}) {
   const firstLines = (text) => String(text || '').trim().split('\n').slice(0, 3).join(' ');
+  // Every failed host is named: since hosts no longer stop at the first failure, two can fail in one run.
+  const reasons = [];
   if (results.claude?.host && !results.claude.wired) {
-    return `Claude Code plugin ${results.claude.action || 'wiring failed'}${results.claude.version ? ` (installed ${results.claude.version}, required ${results.claude.expectedVersion || PACKAGE_VERSION})` : ''}`;
+    reasons.push(`Claude Code plugin ${results.claude.action || 'wiring failed'}${results.claude.version ? ` (installed ${results.claude.version}, required ${results.claude.expectedVersion || PACKAGE_VERSION})` : ''}${results.claude.error ? `: ${firstLines(results.claude.error)}` : ''}`);
   }
-  if (results.codex && !['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
-    return `Codex plugin ${results.codex.action || 'failed'}${results.codex.error ? `: ${firstLines(results.codex.error)}` : ''}`;
+  if (results.codexHostError) reasons.push(results.codexHostError);
+  else if (results.codex && !['unchanged', 'installed', 'updated', 'disabled'].includes(results.codex.action)) {
+    reasons.push(`Codex plugin ${results.codex.action || 'failed'}${results.codex.error ? `: ${firstLines(results.codex.error)}` : ''}`);
   }
-  return null;
+  return reasons.length ? reasons.join('; ') : null;
 }
 
 export function hostSynchronizationFailureMessage(convergence, active, expectedVersion = PACKAGE_VERSION) {
@@ -6829,6 +6910,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 +7029,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}$/;
@@ -349,8 +349,17 @@ function compactTerminalPhases(row) {
 }
 
 export const MAX_VANISHED_RETRIES = 64;
+// A prune stops this far UNDER the byte budget, not at it. The update that prunes still writes its own terminal refresh
+// receipt afterwards; measured on the owner's Mac on 2026-10-30, a prune left 16,769,613 bytes (8 KiB under the
+// 16 MiB budget), the settled receipt pushed it to 16,785,892, and --doctor reported the evidence as cruft after a
+// clean update. The room is made by compacting terminal phase files first, then by removing the oldest removable entry.
+export const PRUNE_HEADROOM_BYTES = 1024 * 1024;
 export function pruneLifecycleEvidence(options = {}) {
   const policy = options.policy || LIFECYCLE_EVIDENCE_RETENTION_POLICY;
+  // 1 MiB on the real 16 MiB budget; never more than a sixteenth of a (test-sized) budget.
+  const headroom = Number.isFinite(options.headroomBytes) ? Math.max(0, options.headroomBytes)
+    : Math.min(PRUNE_HEADROOM_BYTES, Math.floor(policy.maxEvidenceBytes / 16));
+  const roomy = (state) => isWithin(state, policy) && state.bytes <= policy.maxEvidenceBytes - headroom;
   const removeEntry = options.removeEntry || ((entry) => fs.rmSync(entry, { recursive: true, force: true }));
   // A prior invocation's quarantine name is not proof of ownership of its current
   // bytes. Preserve it as unsafe, measured evidence; only this invocation may remove
@@ -393,7 +402,7 @@ export function pruneLifecycleEvidence(options = {}) {
   }
   const compacted = [];
   const compactState = snapshot(options);
-  if (!compactState.unsafe.length && compactState.bytes > policy.maxEvidenceBytes) {
+  if (!compactState.unsafe.length && compactState.bytes > policy.maxEvidenceBytes - headroom) {
     for (const row of compactState.transactions.filter((entry) => TERMINAL_TRANSACTION.has(entry.latest.state))) {
       compacted.push(...compactTerminalPhases(row));
     }
@@ -404,7 +413,7 @@ export function pruneLifecycleEvidence(options = {}) {
   let vanishedRetries = 0; let stopped = null;
   for (;;) {
     const state = snapshot(options);
-    if (isWithin(state, policy)) break;
+    if (roomy(state)) break;
     if (state.unsafe.length) break;
     const refreshCandidates = state.refresh.filter((row) => TERMINAL_REFRESH.has(row.receipt.status)
       && !state.protectedRefresh.has(row.path)).sort((a, b) => a.timestamp - b.timestamp);

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.25",
   "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.25",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/scripts/brain-footprint.mjs

@@ -68,9 +68,16 @@ const RECOVERY_LEFTOVER = /(?:\.(?:bak|retired|dead)-\d{6,}|^bootstrap-backup-\d
 // One list with ruflo-bin.mjs, which clears the same names before each call (incl. a self-update's npm install, 1.3 GB on 2026-10-22).
 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.
+// The maintainer-only issue-autofix job (ADR-107, scripts/issue-autofix-state.mjs) keeps its clone, runner and fix
+// worktrees here too: ~1.1 GB on the owner's Mac on 2026-10-30, counted as "Brain state", which put a correctly
+// pruned Brain 0.7 GB over its budget every night. They are that job's working data, not the product's footprint.
 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']);
+  'worktree-recovery': 'hand-made recovery archives, not created by the Brain',
+  'autofix-repo': 'the maintainer issue-autofix job\'s clone (ADR-107); that job owns and prunes it',
+  'autofix-runner': 'the maintainer issue-autofix job\'s pinned runner worktree (ADR-107); that job owns it',
+  'issue-fix-worktrees': 'the maintainer issue-autofix job\'s fix worktrees (ADR-107); that job owns and prunes them',
+  'issue-autofix': 'the maintainer issue-autofix job\'s run receipts (ADR-107); that job owns them' };
+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 +197,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/developer-update.mjs

@@ -232,6 +232,9 @@ export function pluginUpdateDecision(plugin, target) {
   return { state: target.version === plugin.version ? 'CURRENT' : 'UPDATE_AVAILABLE', proof: target.proof,
     sourceCommitMatched: target.catalogCommit ? plugin.gitCommitSha?.toLowerCase() === target.catalogCommit : null };
 }
+// Codex refreshes a remote plugin catalog (56 MB, 38-40 s cold, 2026-10-30) inside its plugin commands; a killed refresh
+// caches nothing, so a 30 s limit failed every later night the same way. Same bound as bin/install.mjs.
+export const CODEX_COMMAND_TIMEOUT_MS = 180_000;
 export async function synchronizePlugins(run, dryRun, notes, { home, prefix, scope, locate, unattended = false, artifactProvider = pinnedClaudeTarget }) {
   const installed = path.join(home, '.claude/plugins/installed_plugins.json');
   const inventoryOptions = { unattended };
@@ -290,10 +293,10 @@ export async function synchronizePlugins(run, dryRun, notes, { home, prefix, sco
   for (const p of after.filter(p => writable.some(b => scopeKey(b) === scopeKey(p)))) if (!exists(p.installPath)) throw Error(`plugin artifact missing: ${p.id}`);
   const codex = locate('codex');
   if (codex) {
-    const result = JSON.parse(run(codex, ['plugin', 'marketplace', 'list', '--json'], { timeout: 30_000 }));
+    const result = JSON.parse(run(codex, ['plugin', 'marketplace', 'list', '--json'], { timeout: CODEX_COMMAND_TIMEOUT_MS }));
     const git = (result.marketplaces || []).filter(m => m.marketplaceSource?.sourceType === 'git' && (scope === 'all' || PLUGIN_MARKETPLACES.has(m.name)));
     if (!dryRun) for (const m of git) run(codex, ['plugin', 'marketplace', 'upgrade', m.name, '--json']);
-    const help = run(codex, ['plugin', '--help'], { timeout: 30_000 });
+    const help = run(codex, ['plugin', '--help'], { timeout: CODEX_COMMAND_TIMEOUT_MS });
     // Tripwire, reported not thrown: a new Codex command must not end the night before the knowledge is checked (AuditC #17).
     if (/^\s+update\s/m.test(help)) notes.push('Codex plugin update now exists and is unsupported until its scope-aware policy is reviewed; installed generations preserved');
     else notes.push('Codex has no plugin update command; configured Git catalogues refreshed, installed generations preserved');
@@ -307,6 +310,13 @@ export const INSTALL_UPDATE_TIMEOUT_MS = 135 * 60_000;
 export const TRANSIENT_RETRY_DELAYS_MS = Object.freeze([15_000, 30_000]);
 const sleepSync = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 const exitOf = result => typeof result === 'string' ? 0 : (result?.exitCode ?? result?.status ?? result?.code ?? null);
+/** The lines of a child's output that say why it failed (the ✗/failed/incomplete ones, else its last lines), ANSI-free, <= 600 chars. */
+export function outputReason(result) {
+  if (!result || typeof result === 'string') return '';
+  const lines = `${result.stderr || ''}\n${result.stdout || ''}`.replace(/\x1b\[[0-9;]*m/g, '').split('\n').map(l => l.trim()).filter(Boolean);
+  const telling = lines.filter(l => /✗|\berror\b|failed|incomplete|refused|timed out|ETIMEDOUT/i.test(l));
+  return [...new Set((telling.length ? telling : lines).slice(-3))].join(' | ').slice(-600);
+}
 export const TRANSIENT_NETWORK = /ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|ENETUNREACH|socket hang up|network|timed out|\bE5\d\d\b|\b50[234]\b/i;
 /** Three tries of `attempt` (15 s, then 30 s apart) while `transient(error)` says the failure was the network's. */
 export function withTransientRetry(attempt, { transient = () => true, sleep = sleepSync, delays = TRANSIENT_RETRY_DELAYS_MS } = {}) {
@@ -314,15 +324,17 @@ export function withTransientRetry(attempt, { transient = () => true, sleep = sl
     try { return attempt(i); } catch (error) { if (i >= delays.length || !transient(error)) throw error; sleep(delays[i]); }
   }
 }
-export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = sleepSync }) {
+export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = sleepSync, convergeRuntime = true }) {
   const kb = path.join(brainHome, 'kb'), updater = path.join(kb, 'forge-update.mjs');
   if (!exists(updater)) throw Error('existing Brain KB updater absent; fresh install refused');
   const file = path.join(brainHome, `nightly-suite-corpus-${runId}.json`);
   // Exit codes are forge-update's: 0 current, 10 newer, 2 network (retried), 5 incompatible with this runtime.
+  let lastOutput = '';
   const exec = (args, options) => {
     if (!run.receipt) { run(node, args, options); return 0; }
     const result = run.receipt(node, args, options);
-    if (result?.error) throw Error(`${path.basename(args[0])} ${args[1]}: ${result.error}`);
+    lastOutput = outputReason(result);
+    if (result?.error) throw Error(`${path.basename(args[0])} ${args[1]}: ${result.error}${lastOutput ? ` — ${lastOutput}` : ''}`);
     return exitOf(result);
   };
   function check() {
@@ -333,7 +345,7 @@ export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = s
       return status;
     }, { transient: error => error.transient === true, sleep });
     if (code === 5) return { currencyVerdict: 'INCOMPATIBLE', exitCode: 5 };
-    if (code !== 0 && code !== 10) throw Error(`corpus check exited ${code}`);
+    if (code !== 0 && code !== 10) throw Error(`corpus check exited ${code}${lastOutput ? `: ${lastOutput}` : ''}`);
     let receipt;
     try { receipt = read(file); } finally { fs.rmSync(file, { force: true }); }
     if (receipt.kind !== 'ruvnet-brain-check-result' || Date.parse(receipt.recordedAt) < started - 1000) throw Error('fresh corpus check receipt absent');
@@ -344,7 +356,8 @@ export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = s
     if (!exists(installer)) throw Error('existing Brain installer absent');
     // 12 is cleanup-pending: the knowledge was applied and the next run finishes the cleanup (shared exit contract).
     const code = exec([installer, '--update', '--no-nightly-prompt', '--no-stack'], { timeout: INSTALL_UPDATE_TIMEOUT_MS, allowed: [0, 12] });
-    if (code !== 0 && code !== 12) throw Error(`Brain installer --update exited ${code}`);
+    // The installer's own words ride along: "exited 1" alone hid a Codex timeout for three nights (2026-10-28..30).
+    if (code !== 0 && code !== 12) throw Error(`Brain installer --update exited ${code}${lastOutput ? `: ${lastOutput}` : ''}`);
     return code;
   };
   const before = check();
@@ -360,7 +373,21 @@ export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = s
     if (!['CURRENT', 'REFUSED'].includes(after.currencyVerdict)) throw Error(`corpus update failed to converge after re-stamping ${stamped} -> ${installed}`);
     return { before, after, state: 'updated', installerExit, restamped: { from: stamped, to: installed } };
   }
-  if (before.currencyVerdict === 'CURRENT' || before.currencyVerdict === 'REFUSED') return { before, after: before, state: before.currencyVerdict === 'CURRENT' ? 'current' : 'ahead-preserved' };
+  if (before.currencyVerdict === 'CURRENT' || before.currencyVerdict === 'REFUSED') {
+    // A CURRENT corpus is not a converged machine: the package stage can install a newer ruvnet-brain on a night with no
+    // new corpus, and only the installer's --update moves the runtime and hosts to it (a no-op on the corpus). Before
+    // this, such a night reported "current" and left runtime + hosts on the old version until a corpus was published.
+    const runtime = runtimeConvergence({ root, brainHome });
+    const state = before.currencyVerdict === 'CURRENT' ? 'current' : 'ahead-preserved';
+    if (runtime.converged) return { before, after: before, state, runtime };
+    // The SessionStart self-heal (--knowledge-only) runs unattended without the nightly's identity, so an installer
+    // run there would count as interactive (and could reload a shared Codex app-server): it reports, the nightly acts.
+    if (!convergeRuntime) return { before, after: before, state, runtime, deferred: 'runtime convergence is left to the scheduled nightly' };
+    if (dryRun) return { before, state: 'update-available', reason: runtime.reason, runtime };
+    const installerExit = apply(), after = check(), converged = runtimeConvergence({ root, brainHome });
+    if (!converged.converged) throw Error(`runtime did not converge: ${converged.reason}`);
+    return { before, after, state: 'runtime-converged', installerExit, runtime: converged };
+  }
   // UNKNOWN is what a tree installed from a code release reports (no corpus generation stamp): forge-update
   // documents it as apply-allowed, exactly like UPDATE_AVAILABLE, and the check after the apply must reach
   // CURRENT or REFUSED. Throwing here failed every scheduled night until someone ran --update by hand.
@@ -369,7 +396,34 @@ export function knowledge(run, dryRun, runId, { brainHome, root, node, sleep = s
   const installerExit = apply();
   const after = check();
   if (!['CURRENT', 'REFUSED'].includes(after.currencyVerdict)) throw Error('corpus update failed to converge');
-  return { before, after, state: 'updated', installerExit };
+  // Positive confirmation: the corpus converged AND the runtime and hosts sit on the installed package.
+  const runtime = runtimeConvergence({ root, brainHome });
+  if (!runtime.converged) throw Error(`corpus updated but the runtime did not converge: ${runtime.reason}`);
+  return { before, after, state: 'updated', installerExit, runtime };
+}
+/**
+ * Does this machine RUN the installed ruvnet-brain package? The Stable Spine (active.json) and the host-convergence
+ * receipt must name that version (or a newer one: ahead is not behind) and no host may be recorded failed. Evidence
+ * that does not exist is not judged (an install without a spine has nothing to compare).
+ */
+export function runtimeConvergence({ root = ROOT, brainHome = CACHE } = {}) {
+  const value = (file) => { try { return read(file); } catch { return null; } };
+  // A linked source checkout's version is not a release the runtime can be converged to (it may be ahead of npm): its
+  // versions are not compared, but a host recorded failed is still a host that did not converge.
+  let linked = false;
+  try { linked = fs.lstatSync(path.join(root, 'ruvnet-brain')).isSymbolicLink(); } catch { /* absent: judged below */ }
+  const installed = linked ? null : value(path.join(root, 'ruvnet-brain/package.json'))?.version || null;
+  const active = value(path.join(brainHome, 'active.json'));
+  const receipt = value(path.join(brainHome, 'host-convergence.json'));
+  const evidence = { installed, active: active?.version || null, desired: receipt?.desiredVersion || null };
+  const behind = (version) => { try { return !version || compare(version, installed) < 0; } catch { return true; } };
+  if (!installed && !linked) return { converged: true, ...evidence, reason: 'no installed ruvnet-brain package' };
+  if (!linked && active && behind(active.version)) return { converged: false, ...evidence, reason: `runtime ${active.version || 'unknown'} is behind the installed package ${installed}` };
+  if (!linked && receipt && behind(receipt.desiredVersion)) return { converged: false, ...evidence, reason: `hosts were last converged to ${receipt.desiredVersion || 'unknown'}, not the installed package ${installed}` };
+  const failed = Object.entries(receipt?.hosts || {}).filter(([, host]) => !['ready', 'disabled', 'absent'].includes(host?.state));
+  if (failed.length) return { converged: false, ...evidence, reason: `host ${failed.map(([name, host]) => `${name} ${host?.state || 'unknown'}${host?.error ? ` (${host.error})` : ''}`).join(', ')}` };
+  if (linked) return { converged: true, ...evidence, reason: 'ruvnet-brain is a linked source checkout' };
+  return { converged: true, ...evidence, reason: active || receipt ? `runtime and hosts on ${installed}` : 'no runtime evidence to compare' };
 }
 /** Corpus check results this coordinator left behind (a run killed between check and delete) older than 48 h. */
 export function pruneCorpusResults(brainHome, now = Date.now()) {
@@ -419,7 +473,31 @@ export function locateExecutable(name, { env = process.env, platform = process.p
   }
   return null;
 }
-export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(), brainHome, config: override, runner = invoke, env = process.env, knowledgeOnly = false, sleep = sleepSync } = {}) {
+// A failed scheduled knowledge stage is tried once more the same night, this long after the first attempt (a network or
+// release-publication blip clears; a deterministic failure fails twice and pages with both reasons).
+export const SCHEDULED_RETRY_DELAY_MS = 20 * 60_000;
+/**
+ * Page the owner about a scheduled night through the shipped scripts/notify.sh (ntfy). Topic: NTFY_TOPIC, else the
+ * owner's `<brain home>/ntfy-topic` opt-in file; neither = paging off (recorded, not an error). Never throws, never
+ * records the topic. `kind`: 'failed' (urgent) or 'recovered' (after a failed night).
+ */
+export function pageNight(receipt, kind, { root = ROOT, brainHome = CACHE, env = process.env, runner = invoke, platform = process.platform } = {}) {
+  try {
+    if (platform === 'win32') return { kind, state: 'unsupported', reason: 'scripts/notify.sh needs a POSIX shell' };
+    const notify = path.join(root, 'ruvnet-brain/scripts/notify.sh');
+    if (!exists(notify)) return { kind, state: 'unavailable', reason: 'the installed package has no scripts/notify.sh' };
+    let topic = env.NTFY_TOPIC;
+    if (topic === undefined) { try { topic = fs.readFileSync(path.join(brainHome, 'ntfy-topic'), 'utf8').trim(); } catch { topic = ''; } }
+    if (!topic) return { kind, state: 'off', reason: 'no ntfy topic (NTFY_TOPIC or the brain home ntfy-topic file)' };
+    const title = kind === 'failed' ? 'RuvNet Brain nightly update FAILED' : 'RuvNet Brain nightly update recovered';
+    const body = `${kind === 'failed' ? receipt.error || receipt.state : `completed after a failed night (${receipt.state})`}\n\nrun ${receipt.runId}, started ${receipt.startedAt}\nreceipt: ${path.join(brainHome, 'scheduler', 'last-suite-attempt.json')}`;
+    const r = runner('/bin/sh', [notify, title, body.slice(0, 1500), kind === 'failed' ? 'urgent' : 'default', kind === 'failed' ? 'rotating_light' : 'white_check_mark'],
+      { capture: true, timeout: 30_000, env: { ...env, NTFY_TOPIC: topic } });
+    const exitCode = r?.exitCode ?? null;
+    return { kind, state: exitCode === 0 ? 'delivered' : exitCode === 2 ? 'off' : 'not-delivered', exitCode, at: new Date().toISOString() };
+  } catch (error) { return { kind, state: 'not-delivered', reason: error.message }; }
+}
+export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(), brainHome, config: override, runner = invoke, env = process.env, knowledgeOnly = false, sleep = sleepSync, retryDelayMs = SCHEDULED_RETRY_DELAY_MS } = {}) {
   if (!['check', 'apply'].includes(mode)) throw Error('mode must be check or apply');
   const paths = developerUpdatePaths({ home, brainHome });
   const config = validateDeveloperUpdateConfig(override || readDeveloperUpdateConfig(paths));
@@ -467,6 +545,8 @@ export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(),
     }
   };
   let latestMayBeReplaced = receipt.scheduled;
+  let previousScheduled = null;
+  try { previousScheduled = receipt.scheduled ? readAttempt(paths.scheduledReceipt) : null; } catch { previousScheduled = null; }
   try {
     if (!receipt.scheduled) {
       const latest = readAttempt(paths.receipt), retained = readAttempt(paths.scheduledReceipt);
@@ -521,8 +601,20 @@ export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(),
       }
     }
     if (exists(path.join(paths.brainHome, 'kb/forge-update.mjs'))) {
-      receipt.knowledge = await stage('knowledge', () => knowledge(run, mode === 'check', receipt.runId, { brainHome: paths.brainHome, root, node: process.execPath, sleep }),
-        error => { receipt.knowledge = { state: 'failed', error: error.message }; }) ?? receipt.knowledge;
+      const knowledgeStage = () => stage('knowledge', () => knowledge(run, mode === 'check', receipt.runId, { brainHome: paths.brainHome, root, node: process.execPath, sleep, convergeRuntime: !knowledgeOnly }),
+        error => { receipt.knowledge = { state: 'failed', error: error.message }; });
+      receipt.knowledge = await knowledgeStage() ?? receipt.knowledge;
+      // SELF-RETRY THE SAME NIGHT (2026-10-30): a scheduled night whose knowledge stage failed tries once more after
+      // retryDelayMs. Only the second attempt's outcome counts; the first one's reason stays on the receipt.
+      if (receipt.scheduled && mode === 'apply' && receipt.knowledge?.state === 'failed') {
+        const firstAttemptError = receipt.knowledge.error;
+        receipt.notes.push(`knowledge attempt 1 failed (${firstAttemptError}); retrying once in ${Math.round(retryDelayMs / 60_000)} min`);
+        persistReceipt();
+        sleep(retryDelayMs);
+        const firstFailure = failures.findIndex(f => f.stage === 'knowledge');
+        if (firstFailure >= 0) failures.splice(firstFailure, 1);
+        receipt.knowledge = { ...(await knowledgeStage() ?? receipt.knowledge), attempts: 2, firstAttemptError };
+      }
       pruneCorpusResults(paths.brainHome);
     } else receipt.notes.push('Brain corpus absent; fresh knowledge install excluded');
     persistReceipt();
@@ -556,6 +648,12 @@ export async function runDeveloperUpdate({ mode = 'check', home = os.homedir(),
     throw error;
   } finally {
     receipt.finishedAt = new Date().toISOString();
+    // Every scheduled night ends with a word to the owner when it failed, and once more when it recovers.
+    if (receipt.scheduled && mode === 'apply') {
+      const previousFailed = previousScheduled && previousScheduled.ok !== true && previousScheduled.state !== 'running';
+      if (receipt.ok !== true) receipt.page = pageNight(receipt, 'failed', { root: receipt.npmIdentity?.root, brainHome: paths.brainHome, env, runner });
+      else if (previousFailed) receipt.page = pageNight(receipt, 'recovered', { root: receipt.npmIdentity?.root, brainHome: paths.brainHome, env, runner });
+    }
     try { if (latestMayBeReplaced) persistReceipt(); } finally { lock.release(); }
   }
 }

package/plugin/scripts/footprint-io.mjs

@@ -131,7 +131,29 @@ export function treeBytes(target) {
 
 /** Atomic rename-rotation: <name> -> <name>.1 (replacing the previous .1). Appenders reopen by path. */
 export function rotate(file) { fs.renameSync(file, `${file}.1`); }
+/**
+ * Keep a text log's newest tail IN PLACE (same inode). A rename-over gave the log a new inode, so a writer that still
+ * held it open (launchd's StandardOutPath for the nightly, whose own installer runs this sweep) wrote the rest of the
+ * night into a deleted file (review, 2026-10-30). Appenders (O_APPEND) continue at the new end.
+ */
+// In-place trimming is only safe for an O_APPEND writer; the SessionStart jobs open their `.last-*.log` with 'w' (a
+// trim under them would leave a hole of zero bytes), so only the launchd nightly log, appended to all night, is
+// trimmed in place; every other text log keeps the rename-over trim (review r2, 2026-10-30).
+const TRIM_IN_PLACE = new Set(['.last-nightly-update.log']);
 export function truncateToTail(file, keep) {
+  if (!TRIM_IN_PLACE.has(path.basename(file))) return truncateByRename(file, keep);
+  const fd = fs.openSync(file, 'r+');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const buf = Buffer.alloc(Math.min(keep, size));
+    fs.readSync(fd, buf, 0, buf.length, size - buf.length);
+    const nl = buf.indexOf(10);
+    const tail = nl >= 0 ? buf.subarray(nl + 1) : buf;
+    fs.ftruncateSync(fd, 0);
+    fs.writeSync(fd, tail, 0, tail.length, 0);
+  } finally { fs.closeSync(fd); }
+}
+function truncateByRename(file, keep) {
   const size = fs.statSync(file).size;
   const fd = fs.openSync(file, 'r');
   const buf = Buffer.alloc(Math.min(keep, size));

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/plugin/scripts/nightly-scheduler.mjs

@@ -609,6 +609,17 @@ function cronRows(run) {
   return { ok: true, rows: String(listed.stdout || '').split('\n').filter(Boolean) };
 }
 
+/**
+ * Where the scheduled run's own output goes. On macOS it was kb/update.log, INSIDE the tree each knowledge update
+ * replaces: launchd wrote the night into the old tree, the swap moved it aside and the updater reclaimed it, so every
+ * failed night's log was gone by morning (owner's Mac, 2026-10-28..30: no update.log existed). The brain home keeps it;
+ * the `.last-*.log` name puts it under the footprint's text-log cap (truncated to its tail past 512 KiB). Linux keeps
+ * its exact registered cron line (changing it would read every existing install as degraded); Windows logs nothing.
+ */
+export function nightlyLogPath({ platform = process.platform, kbDir }) {
+  return platform === 'darwin' ? path.join(path.dirname(kbDir), '.last-nightly-update.log') : path.join(kbDir, 'update.log');
+}
+
 export function installScheduler(record, { platform = process.platform, env = process.env, kbDir,
   run = spawnSync, testMode = false, proofTick = false, proofAt, pathValue = process.env.PATH || '' } = {}) {
   validateIdentity(record.identity);
@@ -616,7 +627,7 @@ export function installScheduler(record, { platform = process.platform, env = pr
   const artifact = nightlyArtifact({ platform, env, brainHome: path.dirname(kbDir), identity: record.identity });
   if (!artifact.supported) return { ok: false, artifact, why: `unsupported platform: ${platform}` };
   if (testMode && platform !== 'darwin') run = fixtureSchedulerRun(env, platform, record.identity);
-  const logPath = path.join(kbDir, 'update.log');
+  const logPath = nightlyLogPath({ platform, kbDir });
   if (platform === 'darwin') {
     fs.mkdirSync(path.dirname(artifact.path), { recursive: true });
     fs.writeFileSync(artifact.path, launchdPlist(record, { kbDir, logPath, pathValue, env }));

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

@@ -40,7 +40,7 @@ import crypto from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { nativeTurnLines } from './native-turn-transcript.mjs';
-import { resolveRuflo, rufloInvocation, rufloCwdFor, rufloScratchRoot } from './ruflo-bin.mjs';
+import { resolveRuflo, rufloInvocation, rufloRunDir, rufloScratchRoot } from './ruflo-bin.mjs';
 import { redactText } from './continuity-events.mjs';
 import { resolveProjectStore, globalEnrollmentAllowed, storeEncryptedAtRest, ENCRYPTED_STORE_REASON } from './project-store-resolver.mjs';
 import { recordHookFailure } from './hook-failures.mjs';
@@ -388,7 +388,7 @@ export function runSteps({ steps = [], receipts, event = '' } = {}, { run: suppl
   };
   const results = [];
   for (const queued of steps) {
-    let status = 1; let error = null; let skipped = null; let verified = false; let db = ''; let key; let privacyPatterns = [];
+    let status = 1; let error = null; let skipped = null; let verified = false; let db = ''; let key; let privacyPatterns = []; let scratchRun = null;
     const kind = queued.kind;
     try {
       if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') throw new Error('RUVNET_TURN_CAPTURE=off');
@@ -439,9 +439,12 @@ export function runSteps({ steps = [], receipts, event = '' } = {}, { run: suppl
       if (remaining <= 0) throw new Error('turn write deadline exhausted');
       // Measured 2026-10-10 with global Ruflo 3.56.3: cwd=<project>/.swarm litters ruvector.db/.claude-flow there, and
       // CLAUDE_FLOW_MEMORY_PATH=<.swarm> makes Ruflo create a second agentdb-memory.db beside the canonical store.
-      // The explicit --path already binds the store, so run from private scratch with neither.
+      // The explicit --path already binds the store, so run from private scratch with neither. One fresh run-* directory
+      // per call, removed after it (ruflo-bin rufloRunDir): the shared project scratch dir used here before kept ruflo's
+      // ruvector.db/.swarm/.claude-flow copies between turns, which --doctor counted as cruft after every turn (2026-10-30).
+      scratchRun = rufloRunDir(db, { root: rufloScratchRoot({ ...env, RUVNET_BRAIN_HOME: brainHome }) });
       const options = { encoding: 'utf8', timeout: Math.min(STEP_TIMEOUT_MS, remaining), windowsHide: true,
-        cwd: rufloCwdFor(db, { root: rufloScratchRoot({ ...env, RUVNET_BRAIN_HOME: brainHome }) }),
+        cwd: scratchRun,
         maxBuffer: 1024 * 1024, env: { ...env, ...RUFLO_ENV } };
       delete options.env.CLAUDE_FLOW_MEMORY_PATH;
       const r = run(invocation.executable, invocation.args, options);
@@ -456,6 +459,7 @@ export function runSteps({ steps = [], receipts, event = '' } = {}, { run: suppl
       else if (!verified && (r.error || status !== 0)) error = captureFailureReason(r, status);
       else if (kind === 'store' && !verified) { status = 1; error = 'exact turn key/content readback failed'; }
     } catch (e) { status = 1; error = redactText(e.message).slice(0, 300); }
+    if (scratchRun) { try { fs.rmSync(scratchRun, { recursive: true, force: true }); } catch { /* a stale run-* is swept by the next rufloRunDir */ } }
     if (error) error = maskExcludedPaths(error, privacyPatterns, projectDir);
     const row = { at: new Date().toISOString(), kind, db: redactText(db), storeIdentity: digest(db), key, status, error,
       ...(kind === 'store' ? { verified } : {}), ...(skipped ? { skipped } : {}) };

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/nightly-watchdog.mjs

@@ -245,8 +245,13 @@ export function checkAll(now, { registry = REGISTRY, loaded = loadedLabels(), hb
 }
 
 export function productSchedulerVerdict(status) {
+  // The night's receipt: its runId tells one failed night from the next, and a failed night the coordinator already
+  // paged itself (developer-update.mjs pageNight, delivered) is handled like a wrapper-paged one.
+  const receipt = status?.runHealth?.receipt || null;
+  const night = { ...(receipt?.runId ? { runId: receipt.runId } : {}),
+    ...(receipt?.page?.kind === 'failed' && receipt.page.state === 'delivered' ? { coordinatorPaged: true } : {}) };
   const base = { label: NIGHTLY_LABEL, what: 'Refreshes the installed Brain corpus and converges every detected host',
-    schedule: 'daily 03:30', maxAgeHours: 30, required: true };
+    schedule: 'daily 03:30', maxAgeHours: 30, required: true, ...night };
   // A 'degraded' adapter whose only defect is a NON-ZERO LAST EXIT is a job that is loaded, verified
   // and FIRED — the exact opposite of MISSING ("not loaded — it can never fire", top of this file).
   // Its truth is the receipt. Measured 2026-09-12 against two FAILED receipts: this projected as
@@ -282,9 +287,13 @@ export function brainUpdateOwnedByAgenticKit(home = os.homedir()) {
 const loadState = () => { try { return JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return {}; } };
 const saveState = (s) => { fs.mkdirSync(path.dirname(STATE), { recursive: true }); fs.writeFileSync(STATE, JSON.stringify(s, null, 2)); };
 
-/** Page only on a CHANGE of state. Repeating the same alarm nightly is how alarms get ignored. */
+/** Page only on a CHANGE of state. Repeating the same alarm nightly is how alarms get ignored. One exception: a NEW
+ *  failed night of the product nightly (a different receipt runId than the one last handled) pages once, because "it
+ *  failed again tonight" is news; before this, three failed nights in a row paged only the first (2026-10-27..30). */
 export function transitions(results, prev) {
-  return results.filter((r) => !r.self && (prev[r.label] ?? OK) !== r.state);
+  const handledRun = (label) => prev._runs?.[label];
+  return results.filter((r) => !r.self && ((prev[r.label] ?? OK) !== r.state
+    || (r.state === FAILING && !!r.runId && !!handledRun(r.label) && handledRun(r.label) !== r.runId)));
 }
 
 /** An HTTP header value must be a ByteString. An emoji in `Title` made fetch() throw before sending a byte, so
@@ -371,7 +380,7 @@ async function main() {
     const pagedBy = { ...(prev._pagedBy || {}) };
     const sends = []; const owners = []; const viaBoth = new Set();
     for (const c of transitions(results, prev)) {
-      if (c.wrapperPaged) { pagedBy[c.label] = 'wrapper'; continue; }
+      if (c.wrapperPaged || (c.coordinatorPaged && c.state === FAILING)) { pagedBy[c.label] = 'wrapper'; continue; }
       if (c.state === OK) {
         if (pagedBy[c.label] === 'both') { delete pagedBy[c.label]; continue; } // the wrapper's "Recovered" covers it
         if (prev[c.label] === FAILING && pagedBy[c.label] !== 'watchdog') { delete pagedBy[c.label]; continue; }
@@ -389,7 +398,10 @@ async function main() {
     }
     const next = Object.fromEntries(results.map((r) => [r.label,
       r.self || undelivered.has(r.label) ? (prev[r.label] ?? OK) : r.state]));
-    saveState({ ...next, _pagedBy: pagedBy });
+    // The night each label's verdict was last handled for; an undelivered page keeps the old one so it re-fires.
+    const runs = { ...(prev._runs || {}) };
+    for (const r of results) if (r.runId && !undelivered.has(r.label)) runs[r.label] = r.runId;
+    saveState({ ...next, _pagedBy: pagedBy, _runs: runs });
   }
 
   if (json) console.log(JSON.stringify({ results, checkedAt: new Date().toISOString() }, null, 2));

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,24 @@ 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": "nightly-converges-4-7-25",
+      "reason": "The scheduled nightly converges or says why (ADR-104 4.7.25): a CURRENT corpus still runs the installer when the runtime or a host is behind the installed package, an installer exit 0 that leaves it behind is a failure, a failed knowledge stage is retried once the same night, a night that ends not-ok pages through scripts/notify.sh and the next good one pages recovered, the failure carries the installer's own lines, and Codex plugin commands get the catalog-refresh limit. Paging needs a POSIX shell, so Windows is not verified",
+      "files": [],
+      "platformFiles": {
+        "linux": ["tests/unit/nightly-self-retry-and-page.test.mjs"],
+        "macos": ["tests/unit/nightly-self-retry-and-page.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",