ruvnet-brain 4.3.39 → 4.4.0

package/kb/forge-update.mjs

@@ -420,9 +420,13 @@ export async function applyVerifiedStagedRelease({
     if (runtime.brainVersion !== expectedRuntimeVersion) throw new Error('installed runtime identity differs from the approved recovery runtime');
     fs.copyFileSync(assertNoFollowPath(liveDir, runtimeIdentity),
       assertNoFollowPath(candidateDir, path.join(candidateDir, 'RUNTIME-IDENTITY.json')));
-    const privateFence = path.join(liveDir, 'PRIVATE-STORES.json');
-    if (fs.existsSync(privateFence)) fs.copyFileSync(privateFence,
-      assertNoFollowPath(candidateDir, path.join(candidateDir, 'PRIVATE-STORES.json')));
+    // The candidate keeps the BUNDLE's fence; restorePrivateOverlayState adds the restored private
+    // names to it. Copying the LIVE fence over it imported every stale entry: measured 2026-09-30, the
+    // owner's live fence listed 108 stores, 100 of them public in 4.3.39, so the rail could only fail
+    // with "private/public store collision".
+    // Same carry main() does: without it the exact-tree swap deleted the live node_modules, and the
+    // recovered brain could no longer load its embedder (measured 2026-09-30 on the owner's copy).
+    carryLiveNodeModules({ candidateDir, liveDir });
     // S1: ONE APPLY PATH — the same helper main()'s normal apply uses, not a second, duplicated
     // copy-loop. It also adds the collision refusal main() previously lacked.
     restorePrivateFilesIntoCandidate({ candidateDir, sourceDir: liveDir, overlay });
@@ -646,7 +650,9 @@ export function restorePrivateOverlayState({ kbDir, overlay }) {
   const cardsFile = path.join(kbDir, 'capability-cards.md');
   const source = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
   const generations = JSON.parse(fs.readFileSync(generationsFile, 'utf8'));
-  const aliases = JSON.parse(fs.readFileSync(aliasesFile, 'utf8'));
+  // A public bundle may ship no repo-aliases.json at all (build-bundle: "aliases will not resolve"); the
+  // private aliases then start from an empty map instead of failing the whole update on ENOENT.
+  const aliases = fs.existsSync(aliasesFile) ? JSON.parse(fs.readFileSync(aliasesFile, 'utf8')) : {};
   const mergedSource = mergePrivateEntries(source.stores, overlay.sourceStores, 'SOURCE.json');
   const mergedGenerations = mergePrivateEntries(generations.stores, overlay.generationStores, 'RVF-GENERATIONS.json');
   const mergedAliases = mergePrivateEntries(aliases, overlay.aliases, 'repo-aliases.json');
@@ -658,23 +664,48 @@ export function restorePrivateOverlayState({ kbDir, overlay }) {
     }
   }
 
+  // The published capability-cards.md is a sealed input of the derived `concepts` store: its digest
+  // is in the release's concepts receipt, and the trusted validator re-hashes it on every candidate and
+  // live tree. So the public bytes are kept EXACTLY as extracted and private cards are APPENDED as
+  // whole sections after them — never re-serialized in between. Rejoining every section used to put
+  // private cards inside the hashed bytes, and every overlay install refused its own update with
+  // "derived concepts input receipt differs from capability-cards.md" (measured 2026-09-30).
   const publicCardsText = fs.existsSync(cardsFile) ? fs.readFileSync(cardsFile, 'utf8') : '';
   const publicCards = cardSections(publicCardsText);
+  const appendedCards = [];
+  // Case-folded, like the trusted validator (coverage-integrity derivedInputIdentity): an appended
+  // card whose heading folds onto a published one would fail the sealed-input check, so refuse it here
+  // with the collision named instead of writing a tree that cannot validate.
+  const publicFolded = new Set([...publicCards.keys()].map((name) => name.toLowerCase()));
   for (const [name, section] of Object.entries(overlay.cards || {})) {
-    if (publicCards.has(name) && publicCards.get(name) !== section) {
-      throw new Error(`capability-cards.md collision for private store ${name}`);
+    if (publicCards.has(name)) {
+      if (publicCards.get(name) !== section) throw new Error(`capability-cards.md collision for private store ${name}`);
+      continue; // already published verbatim
     }
-    publicCards.set(name, section);
+    if (publicFolded.has(name.toLowerCase())) throw new Error(`capability-cards.md collision for private store ${name}`);
+    appendedCards.push(section);
   }
-  const preambleEnd = publicCardsText.search(/^## /m);
-  const preamble = preambleEnd >= 0 ? publicCardsText.slice(0, preambleEnd).trimEnd() : publicCardsText.trimEnd();
-  const mergedCards = `${preamble}${preamble ? '\n\n' : ''}${[...publicCards.values()].join('\n\n')}\n`;
+  const separator = !publicCardsText ? '' : publicCardsText.endsWith('\n') ? '\n' : '\n\n';
+  const mergedCards = appendedCards.length
+    ? `${publicCardsText}${separator}${appendedCards.join('\n\n')}\n` : publicCardsText;
+
+  // The candidate's PRIVATE-STORES.json is the PUBLIC bundle's fence. A restored private store the
+  // bundle does not fence (a local ingest, or a store the bundle never knew) would leave the runtime
+  // ledger with "unclassified stores", so the restored names are added — never removed, and the file
+  // is untouched when the bundle already fences them all (a byte-identical re-apply stays a no-op).
+  const fenceFile = path.join(kbDir, 'PRIVATE-STORES.json');
+  const fence = fs.existsSync(fenceFile) ? JSON.parse(fs.readFileSync(fenceFile, 'utf8')) : { privateStores: [] };
+  const fenced = new Set((Array.isArray(fence.privateStores) ? fence.privateStores : []).map((name) => String(name).toLowerCase()));
+  const unfenced = Object.keys(overlay.sourceStores || {}).filter((name) => !fenced.has(name.toLowerCase()));
 
   atomicJson(sourceFile, { ...source, stores: mergedSource });
   atomicJson(generationsFile, { ...generations, stores: mergedGenerations });
   atomicJson(aliasesFile, mergedAliases);
-  fs.writeFileSync(`${cardsFile}.tmp-${process.pid}`, mergedCards);
-  fs.renameSync(`${cardsFile}.tmp-${process.pid}`, cardsFile);
+  if (unfenced.length) atomicJson(fenceFile, { ...fence, privateStores: [...(fence.privateStores || []), ...unfenced] });
+  if (mergedCards !== publicCardsText) {
+    fs.writeFileSync(`${cardsFile}.tmp-${process.pid}`, mergedCards);
+    fs.renameSync(`${cardsFile}.tmp-${process.pid}`, cardsFile);
+  }
   return { restored: Object.keys(overlay.sourceStores).length };
 }
 
@@ -702,6 +733,20 @@ export function restorePrivateOverlayState({ kbDir, overlay }) {
  * copying anything is the assertion `applyPublicBundlePreservingPrivate` had and the real path did
  * not; it is preserved here rather than dropped.
  */
+/**
+ * node_modules (the ONNX embedder and RVF readers) is installer-placed and never ships inside a
+ * bundle. The candidate is validated in a SIBLING directory with no parent node_modules, and the
+ * exact-tree swap would delete it from the live KB, so both apply paths carry the LIVE copy across.
+ * Reflink clone where the filesystem supports it (APFS/btrfs), plain copy otherwise.
+ */
+export function carryLiveNodeModules({ candidateDir, liveDir }) {
+  const liveModules = path.join(liveDir, 'node_modules');
+  if (!fs.existsSync(liveModules) || fs.existsSync(path.join(candidateDir, 'node_modules'))) return false;
+  fs.cpSync(assertNoFollowPath(liveDir, liveModules), path.join(candidateDir, 'node_modules'),
+    { recursive: true, verbatimSymlinks: true, mode: fs.constants.COPYFILE_FICLONE });
+  return true;
+}
+
 export function restorePrivateFilesIntoCandidate({ candidateDir, sourceDir, overlay }) {
   if (!overlay) return { restored: 0 };
   for (const relative of Object.keys(overlay.files || {})) {
@@ -720,7 +765,9 @@ export function restorePrivateFilesIntoCandidate({ candidateDir, sourceDir, over
 }
 
 const manifestUrl = source.canonicalManifestUrl || stores.find((s) => s.canonicalManifestUrl)?.canonicalManifestUrl;
-if (!manifestUrl) {
+// The recovery rail runs from the npm package's kb/forge-update.mjs, and the package ships no
+// kb/SOURCE.json (verified in ruvnet-brain-4.3.39.tgz), so this die() stopped the rail before it began.
+if (!manifestUrl && !STAGED_RELEASE_FILE) {
   die(`self-update not configured for this build — SOURCE.json has no canonicalManifestUrl ` +
       `(forge-build.mjs was run without --canonical-url). Provenance is still in SOURCE.json.`);
 }
@@ -1595,7 +1642,9 @@ async function main() {
   if (!APPLY) {
     writeCheckOutcome({ currencyVerdict: verdict.verdict, currencyReason: verdict.reason,
       candidateKind: candidateIdentity.kind, storeCount: targets.length });
-    if (anyBehind) { console.log(`\nA newer build exists. Run:  node forge-update.mjs --apply`); process.exit(10); }
+    // The npx door upgrades this updater before applying; an old installed updater run directly can fail
+    // the guard on a newer bundle (customer-state-matrix D8, 2026-09-30).
+    if (anyBehind) { console.log(`\nA newer build exists. Run:  npx ruvnet-brain@latest --update`); process.exit(10); }
     console.log(`\nAll stores current. Nothing to do.`); process.exit(0);
   }
 
@@ -1692,6 +1741,28 @@ async function main() {
     die(`staged ReleaseCoverage failed integrity: ${stagedCoverage.failures.join('; ')} — local files untouched.`);
   }
 
+  // A release may RETIRE a store this brain still lists. Measured 2026-09-30: 4.3.39 no longer ships
+  // agentic-flows/agentic-music (excluded-no-corpus) or cogs/support under those names, and guarding
+  // them could only fail ("[FAIL] MISSING file: agentic-flows.rvf"), so no brain listing them could
+  // ever update. The release coverage validated above is the authority on what ships; only the stores
+  // the staged bundle declares are guarded and read back, and the retired ones are named, not dropped
+  // silently. (A legacy flat SOURCE.json has no store name to compare and is always guarded.)
+  let stagedStoreNames;
+  try {
+    const staged = JSON.parse(fs.readFileSync(path.join(extractDir, 'SOURCE.json'), 'utf8')).stores || {};
+    stagedStoreNames = new Set(Array.isArray(staged) ? staged.map((s) => s?.kbName) : Object.keys(staged));
+  } catch (error) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    die(`staged SOURCE.json is unreadable: ${error.message} — local files untouched.`);
+  }
+  const landingTargets = resolvedTargets.filter(({ local }) => local.kbName == null || stagedStoreNames.has(local.kbName));
+  const retiredStores = resolvedTargets.filter((target) => !landingTargets.includes(target)).map(({ local }) => local.kbName);
+  if (!landingTargets.length) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    die(`release ${canonTag || canonLabel} ships none of the selected stores (${retiredStores.join(', ')}) — local files untouched.`);
+  }
+  if (retiredStores.length) console.log(`\n  retired by this release (no longer shipped): ${retiredStores.join(', ')}`);
+
   const privateNames = Object.keys(privateOverlay?.sourceStores || {});
   let profileResult = null;
   const finalVerificationByStore = new Map();
@@ -1703,7 +1774,7 @@ async function main() {
     const guard = path.join(dir, 'forge-guard.mjs');
     if (!fs.existsSync(guard)) return { valid: false, failures: ['forge-guard.mjs is missing'] };
     try {
-      for (const { local, resolved: storeResolution } of resolvedTargets) {
+      for (const { local, resolved: storeResolution } of landingTargets) {
         execFileSync(process.execPath, [guard, '--dir', dir, '--name', local.kbName], { cwd: dir, stdio: 'pipe' });
         const verified = verifyLanded({ kbDir: dir, kbName: local.kbName, before: local, beforeBundle: source,
           expectedDigest: storeResolution.digest, downloadedBuffer: buf });
@@ -1747,16 +1818,8 @@ async function main() {
           fs.copyFileSync(assertNoFollowPath(liveDir, liveRuntimeIdentity),
             assertNoFollowPath(candidateDir, path.join(candidateDir, 'RUNTIME-IDENTITY.json')));
         }
-        // node_modules (the ONNX embedder and RVF readers) is installer-placed and never ships inside a
-        // bundle, the same class as the two files above. The candidate is validated by forge-guard in a
-        // SIBLING directory with no parent node_modules, so without it the guard cannot load the
-        // embedder and every apply fails; and the exact-tree swap would delete it from the live KB.
-        // Reflink clone where the filesystem supports it (APFS/btrfs), plain copy otherwise.
-        const liveModules = path.join(liveDir, 'node_modules');
-        if (fs.existsSync(liveModules) && !fs.existsSync(path.join(candidateDir, 'node_modules'))) {
-          fs.cpSync(assertNoFollowPath(liveDir, liveModules), path.join(candidateDir, 'node_modules'),
-            { recursive: true, verbatimSymlinks: true, mode: fs.constants.COPYFILE_FICLONE });
-        }
+        // node_modules: the same installer-owned class as the two files above (see carryLiveNodeModules).
+        carryLiveNodeModules({ candidateDir, liveDir });
         restorePrivateFilesIntoCandidate({ candidateDir, sourceDir: liveDir, overlay: privateOverlay });
         // ATOMIC WITH INSTALLATION, not after it. The transport identity is written INTO the
         // candidate, so the storage transaction's single rename either promotes the bytes AND the
@@ -1796,7 +1859,7 @@ async function main() {
     process.exitCode = 12;
     return;
   }
-  for (const { local, resolved: storeResolution } of resolvedTargets) {
+  for (const { local, resolved: storeResolution } of landingTargets) {
     const verified = finalVerificationByStore.get(local.kbName)
       || verifyLanded({ kbDir: KB_DIR, kbName: local.kbName, before: local, beforeBundle: source,
         expectedDigest: storeResolution.digest, downloadedBuffer: buf });
@@ -1842,7 +1905,8 @@ async function main() {
     ? `\n=== DONE — exact no-op; installed bytes already equal the validated candidate ===`
     : `\n=== DONE — ${behindStores.length} store(s) updated ===`);
   console.log(`resolved target (live manifest, checked BEFORE downloading): ${canonLabel}`);
-  for (const { local } of behindStores) {
+  if (retiredStores.length) console.log(`retired by this release (no longer shipped): ${retiredStores.join(', ')}`);
+  for (const { local } of landingTargets) {
     const r = landedByStore.get(local.kbName);
     const l = r.landed;
     console.log(`[${local.kbName}] SOURCE.json on disk now reads: built ${l.builtUtc || '?'} from ${short(l.sourceCommit)}${l.sourceDescribe ? ` (${l.sourceDescribe})` : ''}`);
@@ -1855,7 +1919,7 @@ async function main() {
     console.log(`\n${unchangedStores.length} of ${behindStores.length} store(s) were already at the canonical build and did not change: ${unchangedStores.join(', ')}`);
     console.log(`  (stores are forged independently — an unchanged store means its upstream repo did not move, not a failed update.)`);
   }
-  const finalOutcome = writeUpdateOutcome({ terminalVerdict: transaction.terminalVerdict, storeCount: behindStores.length,
+  const finalOutcome = writeUpdateOutcome({ terminalVerdict: transaction.terminalVerdict, storeCount: behindStores.length, retiredStores,
     currencyVerdict: verdict.verdict, currencyReason: verdict.reason, candidateKind: candidateIdentity.kind,
     storageDelta: transaction.storageDelta,
     transactionReceipts: transaction.paths.receipts,

package/kb/lifecycle-evidence-retention.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 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']);
@@ -113,10 +114,11 @@ function newest(rows, predicate) {
 
 function trustedEvidenceRoot(root, unsafe) {
   try {
-    for (const entry of [path.dirname(root), root]) {
-      const stat = fs.lstatSync(entry);
-      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('evidence root is not a trusted directory (symbolic or special entry)');
-    }
+    // The PARENT is where the user put the brain (`~/.cache/ruvnet-brain` may be a link to another disk):
+    // it must be a directory once resolved. The evidence root itself must not be a link.
+    if (!fs.statSync(physicalPath(path.dirname(root))).isDirectory()) throw new Error('evidence root parent is not a directory');
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('evidence root is not a trusted directory (symbolic or special entry)');
     return true;
   } catch (error) {
     if (error.code !== 'ENOENT') unsafe.push({ path: root, reason: error.message });
@@ -130,7 +132,7 @@ function snapshot(options) {
   const refresh = trustedEvidenceRoot(roots.refresh, unsafe) ? scanRefresh(roots.refresh, unsafe) : [];
   const transactions = trustedEvidenceRoot(roots.transactions, unsafe) ? scanTransactions(roots.transactions, unsafe) : [];
   const preserveRefresh = new Set((options.preserveRefreshRunIds || []).map(String));
-  const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => path.resolve(entry)));
+  const preserveTransactions = new Set((options.preserveTransactionPaths || []).map((entry) => physicalPath(entry)));
   const protectedRefresh = new Map();
   const protectRefresh = (row, reason) => { if (row) protectedRefresh.set(row.path, reason); };
   for (const row of refresh) {
@@ -147,17 +149,18 @@ function snapshot(options) {
     if (!protectedRefresh.has(row.path)) continue;
     for (const reference of transactionReferences(row.receipt)) {
       const resolved = path.resolve(String(reference || ''));
-      const relative = path.relative(roots.transactions, resolved);
+      // The updater records real paths; the caller may spell the brain through a link. Same space, both sides.
+      const relative = path.relative(physicalPath(roots.transactions), physicalPath(resolved));
       if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || relative.includes(path.sep)) {
         unsafe.push({ path: row.path, reason: `forged external transaction reference: ${String(reference)}` });
-      } else retainedTransactionPaths.add(resolved);
+      } else retainedTransactionPaths.add(physicalPath(resolved));
     }
   }
   const protectedTransactions = new Map();
   for (const row of transactions) {
     if (!TERMINAL_TRANSACTION.has(row.latest.state)) protectedTransactions.set(row.path, `nonterminal ${row.latest.state}`);
-    if (preserveTransactions.has(row.path)) protectedTransactions.set(row.path, 'explicitly preserved transaction');
-    if (retainedTransactionPaths.has(row.path)) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
+    if (preserveTransactions.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'explicitly preserved transaction');
+    if (retainedTransactionPaths.has(physicalPath(row.path))) protectedTransactions.set(row.path, 'referenced by retained refresh receipt');
   }
   const bytes = [...refresh, ...transactions].reduce((sum, row) => sum + row.bytes, 0)
     + unsafe.filter(({ reason }) => /quarantine remains/.test(reason)).reduce((sum, { path: entry }) => {

package/kb/refresh-run.mjs

@@ -78,6 +78,19 @@ export function inspectRefreshOwner(owner, { hostname = os.hostname(), inspectPr
   return ownerState(owner, { hostname, inspectProcess, isAlive });
 }
 
+/**
+ * The ONE physical-path rule for brain directories. A user may reach the brain through a symlink
+ * (`~/.cache -> /Volumes/<disk>`) while the updater knows it by its real path (Node resolves
+ * import.meta.url), so identity checks compare this, never spellings. A directory that does not
+ * exist right now (kb/ mid-rename) resolves through its parent, so the answer does not flip.
+ */
+export function physicalPath(dir) {
+  const resolved = path.resolve(String(dir || ''));
+  try { return fs.realpathSync.native(resolved); } catch { /* absent: resolve through the parent */ }
+  try { return path.join(fs.realpathSync.native(path.dirname(resolved)), path.basename(resolved)); }
+  catch { return resolved; }
+}
+
 export const refreshLockPath = (kbDir) =>
   path.join(path.dirname(path.resolve(kbDir)), `.${path.basename(path.resolve(kbDir))}.refresh-run.lock`);
 
@@ -156,7 +169,10 @@ export function acquireRefreshLock({
   const inherited = String(env.RUVNET_REFRESH_RUN_TOKEN || '');
   if (inherited) {
     const owner = JSON.parse(fs.readFileSync(path.join(lockPath, 'owner.json'), 'utf8'));
-    if (owner.schemaVersion !== 3 || owner.token !== inherited || path.resolve(owner.kbDir) !== root
+    // Same DIRECTORY, not same spelling: the installer locks RUVNET_BRAIN_KB as given (possibly through
+    // a symlinked ~/.cache), the child updater knows its KB by import.meta.url, which Node resolves to
+    // the real path. Compare physical identity; a genuinely different directory still refuses.
+    if (owner.schemaVersion !== 3 || owner.token !== inherited || physicalPath(owner.kbDir) !== physicalPath(root)
       || path.resolve(owner.receiptPath || '') !== refreshReceiptPath(owner.brainHome, owner.runId)) {
       throw new Error(`refresh lock inheritance does not match ${lockPath}`);
     }

package/kb/update-storage-transaction.mjs

@@ -96,21 +96,27 @@ export function managedStorageInventory(liveDir, { measuredAt = new Date().toISO
   const basename = path.basename(live);
   const fullCorpusCopies = [];
   const evidence = [];
+  const evidenceNames = [`.${basename}.update-transactions`, 'refresh-runs'];
   for (const name of fs.readdirSync(parent).sort()) {
     const file = path.join(parent, name);
-    const stat = fs.lstatSync(file);
     const installerKind = name.startsWith(`${basename}.install-preserved-`) ? 'installer-preserved'
       : name.startsWith(`${basename}.install-prior-`) ? 'installer-prior'
         : name.startsWith(`.${basename}.install-stage-`) ? 'installer-stage' : null;
-    if (installerKind) {
-      fullCorpusCopies.push(observedInstallerSummary(file, installerKind));
-      continue;
-    }
     const kind = name === basename ? 'active'
       : name.startsWith(`${basename}.next-`) ? 'candidate'
         : name.startsWith(`${basename}.rollback-`) ? 'rollback'
           : name.startsWith(`${basename}.failed-`) ? 'failed'
             : name.startsWith(`${basename}.bak-`) ? 'backup' : null;
+    // Classify by NAME first and lstat only managed entries. The parent (e.g. ~/.cache/ruvnet-brain)
+    // also holds hook stamps and logs created and deleted constantly; one vanishing between readdir
+    // and lstat threw ENOENT and aborted the whole update. A managed entry that vanished is absent.
+    if (!installerKind && !kind && !evidenceNames.includes(name)) continue;
+    let stat;
+    try { stat = fs.lstatSync(file); } catch (error) { if (error?.code === 'ENOENT') continue; throw error; }
+    if (installerKind) {
+      fullCorpusCopies.push(observedInstallerSummary(file, installerKind));
+      continue;
+    }
     if (kind) {
       if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`managed ${kind} entry is not a trusted directory: ${file}`);
       fullCorpusCopies.push(trustedTreeSummary(file, kind));
@@ -252,7 +258,23 @@ 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 (['NOOP', 'COMMITTED', 'ROLLED_BACK'].includes(latest.state)) 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.
+      const quarantine = latest.quarantinedUnsealedCandidate;
+      if (latest.state === 'ROLLED_BACK' && quarantine && latest.quarantineReclaimed !== true
+        && path.resolve(quarantine) === transactionPaths(live, transactionId).failed) {
+        const unchanged = !fs.existsSync(quarantine) || (() => {
+          try { requireDigest(quarantine, latest.quarantineIdentity, 'quarantined candidate'); return true; } catch { return false; }
+        })();
+        if (unchanged) {
+          removeIfPresent(quarantine);
+          appendRecoveryReceipt(receipts, 'ROLLED_BACK', { quarantineReclaimed: true,
+            reason: 'released the quarantined unsealed candidate one update cycle later (bytes unchanged)' });
+        }
+      }
+      continue;
+    }
     if (latest.state === 'RECOVERY_REQUIRED') throw new Error(`storage transaction requires manual recovery: ${transactionId}`);
     const paths = latest.paths;
     const expectedPaths = transactionPaths(live, transactionId);
@@ -267,12 +289,22 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
     try {
       // Validate every retained tree before any rename or deletion. A receipt owns
       // paths, but cannot authorize discarding bytes added after the process died.
-      if (fs.existsSync(paths.candidate)) requireDigest(paths.candidate, latest.candidate, 'interrupted candidate');
+      // A kill DURING candidate building (the long phase: copy, private restore, guard) leaves a candidate
+      // that was never sealed, so no receipt can vouch for its bytes. Refusing made every later update
+      // fail forever; deleting would discard bytes nothing proved disposable. It is QUARANTINED instead:
+      // renamed intact to this transaction's `failed` path, named in the receipt, and live (proved equal
+      // to the prior identity) stays in service.
+      const unsealedCandidate = fs.existsSync(paths.candidate) && !latest.candidate?.sha256
+        && ['LOCKED', 'CANDIDATE_BUILDING'].includes(latest.state);
+      if (fs.existsSync(paths.candidate) && !unsealedCandidate) requireDigest(paths.candidate, latest.candidate, 'interrupted candidate');
       if (fs.existsSync(paths.rollback)) requireDigest(paths.rollback, prior, 'interrupted rollback');
       if (fs.existsSync(paths.failed)) throw new Error('interrupted failed tree has no safe recovery disposition');
       if (['LOCKED', 'CANDIDATE_BUILDING', 'CANDIDATE_VERIFIED'].includes(latest.state)) {
         requireDigest(live, prior, 'interrupted live');
-        removeIfPresent(paths.candidate);
+        if (unsealedCandidate) {
+          assertDirectory(paths.candidate, 'unsealed candidate');
+          fs.renameSync(paths.candidate, paths.failed);
+        } else removeIfPresent(paths.candidate);
       } else if (latest.state === 'OLD_RENAME_STARTED') {
         const hasLive = fs.existsSync(live);
         const hasRollback = fs.existsSync(paths.rollback);
@@ -318,10 +350,12 @@ export function recoverIncompleteStorageTransactions(liveDir, { removeTree = rem
         continue;
       } else throw new Error(`unsupported interrupted state ${latest.state}`);
       const delta = storageDelta(paths, { prior, candidate: latest.candidate || null });
+      const quarantined = unsealedCandidate
+        ? { quarantinedUnsealedCandidate: paths.failed, quarantineIdentity: identitySummary(treeIdentity(paths.failed)) } : {};
       appendRecoveryReceipt(receipts, 'ROLLED_BACK', { terminalVerdict: 'interrupted-run-restored', prior,
-        storageDelta: delta, reason: `recovered interrupted ${latest.state} transaction before new work` });
+        storageDelta: delta, reason: `recovered interrupted ${latest.state} transaction before new work`, ...quarantined });
       recovered.push({ transactionId, from: latest.state, terminalVerdict: 'interrupted-run-restored',
-        storageDelta: delta });
+        storageDelta: delta, ...quarantined });
     } catch (error) {
       appendRecoveryReceipt(receipts, 'RECOVERY_REQUIRED', { terminalVerdict: 'recovery-required', prior,
         reason: error.message });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.39",
+  "version": "4.4.0",
   "description": "One-command installer for RuvNet Brain \u2014 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.3.39",
+  "version": "4.4.0",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/hooks/codex-hooks.json

@@ -92,8 +92,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 session-snapshot SessionEnd",
-            "timeout": 10
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 session-snapshot SessionEnd",
+            "timeout": 3
           }
         ]
       }

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech — ADR-040 §Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — the Stop stdout envelopes are advisory at the shim boundary but keep the agent working.",
+  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech — ADR-040 §Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if the final answer asserts a rUv capability and no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — the Stop stdout envelopes are advisory at the shim boundary but keep the agent working.",
   "hooks": {
     "SessionStart": [
       {

package/plugin/scripts/capability-registry.mjs

@@ -451,11 +451,11 @@ export const CAPABILITIES = [
       if (d.unreadable) {
         const locked = /lock|busy|writer/i.test(String(d.unreadable));
         return row(STATE.UNKNOWN, locked
-          ? `the memory store is currently held by another process (${d.unreadable}) — that is a passing lock, not a fault; re-checking in a moment should clear it`
+          ? `could not read the memory store: another process is holding it (${d.unreadable}) — that is a passing lock, not a fault; re-checking in a moment should clear it`
           : `the memory store could not be read (${d.unreadable}) — this is not a transient lock, so re-checking will not clear it; the store or its journal files need attention before distillation state can be established`);
       }
-      if (d.schemaless) return row(STATE.UNKNOWN, 'the store exists but has no memory_entries table (pre-AgentDB schema, never initialised) — nothing to distill yet, and nothing is broken');
-      if (typeof d.total !== 'number') return row(STATE.UNKNOWN, 'the store opened but returned no countable rows — distillation state not established');
+      if (d.schemaless) return row(STATE.UNKNOWN, 'cannot measure distillation: the store exists but has no memory_entries table (pre-AgentDB schema, never initialised) — nothing to distill yet, and nothing is broken');
+      if (typeof d.total !== 'number') return row(STATE.UNKNOWN, 'the store opened but returned no countable rows — distillation state could not be established');
 
       if (d.total === 0) return row(STATE.ABSENT, 'the memory store is empty, so there is nothing to distill yet');
       if (d.learns) return row(STATE.ON, `${d.patterns} reusable patterns distilled from ${d.real} memories (${(d.cover * 100).toFixed(1)}% embedded)`);

package/plugin/scripts/codex-hook-wrapper.mjs

@@ -60,7 +60,7 @@ const blockingHooks = new Set([
 const DETACHED_HOOKS = new Set(['learn-flush']);
 
 /** THE BUDGET IS DERIVED FROM WHAT THE HOOK MEASURABLY COSTS, never from what looks tidy. */
-function timeoutFor(hookId) {
+function timeoutFor(hookId, event = '') {
   const override = Number(process.env.RUVNET_CODEX_HOOK_TIMEOUT_MS);
   if (Number.isFinite(override) && override > 0) return override;
   // decision-gate's own internal budget is 4000ms (RUVNET_DECISION_BUDGET_MS) and it is allowed to
@@ -75,6 +75,11 @@ function timeoutFor(hookId) {
   if (hookId === 'ground-ruvnet' || hookId === 'unprompted-speech' || hookId === 'continuation-gate') {
     return 8_500;
   }
+  // SessionEnd is hard-capped at 3s by the host (see DETACHED_HOOKS above) and the codex-hooks.json
+  // launcher kills this wrapper at 2500ms. A 4000ms budget here was a number nobody would ever reach:
+  // the body planned for 8s and was SIGKILLed mid-write. 2200ms leaves the launcher its margin, and the
+  // body receives it as RUVNET_CODEX_BUDGET_MS (below) so it can save the new snapshot first.
+  if (event === 'SessionEnd') return 2_200;
   return 4_000;
 }
 
@@ -193,7 +198,7 @@ if (DETACHED_HOOKS.has(hookId)) {
   process.exit(0);
 }
 
-const budgetMs = timeoutFor(hookId);
+const budgetMs = timeoutFor(hookId, process.argv[3] || '');
 const result = spawnSync(process.execPath, [adapter, ...process.argv.slice(2)], {
   input,
   encoding: 'utf8',

package/plugin/scripts/coverage-integrity.mjs

@@ -182,6 +182,54 @@ function evidenceIdentity(root, file, kind) {
   };
 }
 
+/**
+ * The ONE derived input a private overlay legitimately extends on an installed brain.
+ * kb/forge-update.mjs's restorePrivateOverlayState keeps the published capability-cards.md bytes
+ * verbatim and APPENDS the user's private `## <store>` cards after them, so card-lane and every other
+ * reader keep a single file. Hashing the whole file made every overlay install fail this check
+ * ("derived concepts input receipt differs from capability-cards.md", measured 2026-09-30 on the
+ * owner's 4.3.39 update) — the published digest can never cover bytes the user added locally.
+ */
+export const OVERLAY_EXTENSIBLE_DERIVED_INPUTS = Object.freeze(['capability-cards.md']);
+
+/**
+ * Identity of a derived input as the release sealed it. Exact file match first. For an
+ * overlay-extensible input, accept ONLY a file whose leading bytes, cut at a line boundary, hash to
+ * the sealed digest AND whose remainder is nothing but whole `## ` card sections — so every published
+ * card still parses to exactly its published body, and nothing local can be glued onto one. The
+ * evidence row records the sealed prefix (digest + byte count), which is what the release's partition
+ * digest was computed over. Returns null when the sealed bytes are not present.
+ */
+function derivedInputIdentity(root, file, input) {
+  const relative = path.relative(root, file).split(path.sep).join('/');
+  const bytes = fs.readFileSync(file);
+  const whole = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (whole === input.sha256) return { kind: 'derived-input', path: relative, sha256: whole, bytes: bytes.length };
+  if (!OVERLAY_EXTENSIBLE_DERIVED_INPUTS.includes(relative)) return null;
+  const hash = crypto.createHash('sha256');
+  let consumed = 0;
+  // An appended section may only ADD a card. One that repeats a sealed `## ` heading (another copy,
+  // a case variant, or an empty one) would be served by the card lane as curated evidence for that
+  // PUBLIC product, so it is refused, compared trimmed and case-insensitively.
+  const headings = (text) => [...text.matchAll(/^## ([^\n]*)$/gm)].map((m) => m[1].trim().toLowerCase());
+  const matchesAt = (end) => {
+    hash.update(bytes.subarray(consumed, end));
+    consumed = end;
+    if (hash.copy().digest('hex') !== input.sha256) return false;
+    const rest = bytes.subarray(end).toString('utf8');
+    if (!/^\n*## \S/.test(rest)) return false;
+    const sealed = new Set(headings(bytes.subarray(0, end).toString('utf8')));
+    return !headings(rest).some((heading) => sealed.has(heading));
+  };
+  for (let index = bytes.indexOf(0x0a); index >= 0; index = bytes.indexOf(0x0a, index + 1)) {
+    // Both sides of every newline: a published file that ends without one is still a clean prefix.
+    for (const end of [index, index + 1]) {
+      if (matchesAt(end)) return { kind: 'derived-input', path: relative, sha256: input.sha256, bytes: end };
+    }
+  }
+  return null;
+}
+
 const canonicalStores = (root) => {
   const stores = [];
   for (const name of fs.readdirSync(root).filter((entry) => !entry.startsWith('._'))) {
@@ -341,10 +389,9 @@ export function validatePublicInventory({ assetsDir, coverage, ledger, installed
     for (const input of receipt.inputs) {
       let inputFile = null;
       try { inputFile = containedRegular(root, input?.path, `derived ${store} input`); } catch { /* handled below */ }
-      if (!inputFile || !HEX64.test(String(input.sha256 || '')) || input.sha256 !== sha256File(inputFile)) {
-        throw new Error(`derived ${store} input receipt differs from ${input?.path || '(missing)'}`);
-      }
-      evidenceFiles.push(evidenceIdentity(root, inputFile, 'derived-input'));
+      const identity = inputFile && HEX64.test(String(input.sha256 || '')) ? derivedInputIdentity(root, inputFile, input) : null;
+      if (!identity) throw new Error(`derived ${store} input receipt differs from ${input?.path || '(missing)'}`);
+      evidenceFiles.push(identity);
     }
     evidenceFiles.push(evidenceIdentity(root, passages, 'derived-passages'));
     evidenceFiles.push(evidenceIdentity(root, receiptFile, 'derived-receipt'));

package/plugin/scripts/design-wall.sh

@@ -29,6 +29,7 @@ INPUT=""
 # exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
 # is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
 # the whole thing back at once and a per-iteration cap never fires.
+_l=""   # set -u: a read that times out before any byte leaves _l unset ("unbound variable" on stderr)
 while IFS= read -r -t 2 _l; do
   INPUT+="$_l"
   [ ${#INPUT} -ge 65536 ] && break

package/plugin/scripts/ground-before-write.sh

@@ -43,6 +43,7 @@ INPUT=""
 # exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
 # is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
 # the whole thing back at once and a per-iteration cap never fires.
+_l=""   # set -u: a read that times out before any byte leaves _l unset ("unbound variable" on stderr)
 while IFS= read -r -t 2 _l; do
   INPUT+="$_l"
   [ ${#INPUT} -ge 65536 ] && break

package/plugin/scripts/ground-ruvnet.sh

@@ -347,7 +347,7 @@ LASTV=$(cat "$VSTAMP" 2>/dev/null || echo 0)
 VJITTER=$(( ( $(hostname 2>/dev/null | cksum 2>/dev/null | cut -d' ' -f1 || echo 0) % 8641 ) - 4320 ))
 VINTERVAL=$(( 21600 + VJITTER ))
 if [ "$NOWV" -gt 0 ] && [ $((NOWV - LASTV)) -gt "$VINTERVAL" ]; then
-  echo "$NOWV" > "$VSTAMP" 2>/dev/null
+  echo "$NOWV" 2>/dev/null > "$VSTAMP"   # 2>/dev/null FIRST: a failed redirect prints the shell's own error otherwise
   # BACKGROUNDED (QE-0011 code#1): these are 3 sequential `curl --max-time 3` = up to ~9s. Running
   # them synchronously HERE — before the grounding gates below — risks the whole hook being killed by
   # Claude Code's ~5s hook timeout on the once/20h refresh tick, which would DROP the actual grounding
@@ -357,7 +357,7 @@ if [ "$NOWV" -gt 0 ] && [ $((NOWV - LASTV)) -gt "$VINTERVAL" ]; then
   ( for PKG in ruflo @claude-flow/cli @ruvector/rvf; do
       L=$(curl -fsS --max-time 3 "https://registry.npmjs.org/$PKG/latest" 2>/dev/null | sed -E 's/.*"version":"([^"]+)".*/\1/' | head -c 40)
       [ -n "$L" ] && echo "$PKG $L"
-    done > "$VCACHE".tmp 2>/dev/null && mv -f "$VCACHE".tmp "$VCACHE" 2>/dev/null ) &
+    done 2>/dev/null > "$VCACHE".tmp && mv -f "$VCACHE".tmp "$VCACHE" 2>/dev/null ) 2>/dev/null &
 fi
 if [ -s "$VCACHE" ]; then
   OUTDATED=""
@@ -625,7 +625,7 @@ if [ -n "$METER_TMP" ]; then
   mkdir -p "$METER_LEDGER_DIR" 2>/dev/null && \
     printf '{"ts":"%s","source":"hook","class":"%s","bytes":%d,"cwd":"%s"}\n' \
       "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$METER_CLASS" "$METER_BYTES" "$( { pwd -W 2>/dev/null || pwd 2>/dev/null; } | sed 's/"/\\"/g')" \
-      >> "$METER_LEDGER_DIR/token-ledger.jsonl" 2>/dev/null
+      2>/dev/null >> "$METER_LEDGER_DIR/token-ledger.jsonl"
 fi
 
 exit 0