ruvnet-brain 4.3.39 → 4.3.40

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.39 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.39-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.40 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.40-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -562,7 +562,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 199 public stores · 161,322 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 199 public stores · 161,365 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -102,8 +102,9 @@ const PACKAGE_VERSION = (() => {
 const REPO = 'stuinfla/ruvnet-brain';
 const RELEASE_API = `https://api.github.com/repos/${REPO}/releases/latest`;
 const ASSET_NAME = 'ruvnet-brain.zip';
-// Known-good BUNDLE tag, used when we can't reach GitHub (offline / rate-limited / no releases),
-// and by --pin. Default behavior is "get the latest Release"; this is only the safety net.
+// Known-good BUNDLE tag, used ONLY by --pin. It is no longer a silent fallback for a failed
+// latest-release lookup: that bundle predates ReleaseCoverage and cannot pass validation, so a lookup
+// failure now stops with its real cause (resolveRelease / releaseLookupFailure).
 //
 // This MUST NOT be derived from this package's own version. The installer and the brain bundle are
 // two independent version streams (README: "Three independent things version separately here — by
@@ -299,7 +300,9 @@ function fetchJson(url, redirects = 0) {
         }
         if (statusCode !== 200) {
           res.resume();
-          return reject(new Error(`GitHub API returned HTTP ${statusCode}`));
+          const reset = headers['x-ratelimit-remaining'] === '0' && Number(headers['x-ratelimit-reset']);
+          return reject(new Error(`GitHub API returned HTTP ${statusCode}${reset
+            ? ` (anonymous rate limit used up; it resets at ${new Date(reset * 1000).toISOString()})` : ''}`));
         }
         let body = '';
         res.setEncoding('utf8');
@@ -321,8 +324,8 @@ function fetchJson(url, redirects = 0) {
 // ── step: resolve which Release to download (latest by default; safe fallback) ───────────────────
 // Default behavior: ask GitHub for the LATEST Release and use its ruvnet-brain.zip asset.
 // --version <tag> forces a tag; --pin skips the network check and uses the bundled known-good tag.
-// Any failure (offline / rate-limited / no releases) FALLS BACK to the pinned known-good Release,
-// narrated clearly so the user knows exactly what happened.
+// Any failure (offline / rate-limited / no releases) THROWS with the HTTP status or network error and
+// a retry hint; callers that must download stop on it, the staleness check reports "could not check".
 /**
  * Which asset of a Release actually holds the brain bundle.
  *
@@ -387,12 +390,31 @@ async function resolveRelease() {
     ok(`latest Release is ${c.bold(tag)}`);
     return { tag, url, source: 'latest' };
   } catch (e) {
-    warn(`couldn't check for the latest version (${e.message})`);
-    info(`using the known-good ${c.bold(RELEASE_VERSION)} instead — the install is still safe and complete`);
-    return { tag: RELEASE_VERSION, url: fallbackUrl(RELEASE_VERSION), source: 'fallback' };
+    // FAIL LOUD. This used to return the hardcoded RELEASE_VERSION and promise "the install is still
+    // safe and complete" — but that bundle predates ReleaseCoverage, so two steps later it failed
+    // validation with "COVERAGE.json is missing", and the reason (a rate limit, a network blip) was
+    // gone from the screen. Measured 2026-09-30 on the owner's recovery rail. Only --pin and
+    // --version choose a tag the lookup did not return.
+    const failure = releaseLookupFailure(e);
+    throw Object.assign(new Error(failure.message), { hint: failure.hint });
   }
 }
 
+/** Why the latest-release lookup failed, and what to do about it. Pure, for testing. */
+export function releaseLookupFailure(error) {
+  const detail = (error && error.message) || String(error);
+  const limited = /HTTP (?:403|429)\b/.test(detail);
+  return {
+    message: `couldn't look up the latest RuvNet Brain release (${detail}).`,
+    hint: [
+      limited
+        ? 'GitHub allows a limited number of anonymous release checks per hour from one network address. Wait until the reset time above, then re-run the same command.'
+        : 'Check your connection, then re-run the same command in a minute.',
+      `Nothing was downloaded or installed. To install one specific release instead: add  --version <tag>  (tags: https://github.com/${REPO}/releases).`,
+    ].join('\n'),
+  };
+}
+
 // ── step: resolve the cache dir ──────────────────────────────────────────────────────────────────
 function resolveCacheDir() {
   const custom = process.env.RUVNET_BRAIN_KB;
@@ -3650,7 +3672,7 @@ async function runUpdate() {
     let fr;
     if (hasPrivateOverlay) {
       warn("\nthe installed updater failed; using authenticated staged recovery to preserve private stores…\n");
-      const release = await resolveRelease();
+      const release = await resolveRelease().catch((error) => die(error.message, error.hint));
       const bundle = await obtainBundle(release);
       if (!bundle.zipPath) throw new Error('private-overlay recovery requires a downloadable signed bundle');
       const sigPath = `${bundle.zipPath}.sig`;
@@ -5333,8 +5355,9 @@ function showHelp() {
   console.log(`
 RuvNet Brain installer
 
-By default this installs the LATEST published Release (it asks GitHub which one that is),
-and falls back to a known-good version if GitHub can't be reached.
+By default this installs the LATEST published Release (it asks GitHub which one that is).
+If GitHub can't be reached or rate-limits the check, it STOPS with the reason and downloads
+nothing; re-run later, or pick a release yourself with  --version <tag>.
 
 Usage:
   npx ruvnet-brain                         Install the brain + Claude Code plugin (recommended, npm)
@@ -5476,9 +5499,9 @@ the installer reports that boot-level declarations changed.
     installedTag = installedBrainVersion(cacheDir); // 'unknown' when SOURCE.json has no releaseTag
     try {
       resolvedRelease = await resolveRelease();
-      // ONLY a genuine `latest` lookup counts as "what current means". resolveRelease() does NOT
-      // throw when the GitHub API fails — it returns the hardcoded known-good pin with
-      // source:'fallback'. Treating that as latest inverts this whole fix: a rate-limited lookup
+      // ONLY a genuine `latest` lookup counts as "what current means". A failed lookup now THROWS
+      // (caught below: "could not check"); it used to return the hardcoded known-good pin with
+      // source:'fallback'. Treating that as latest inverted this whole fix: a rate-limited lookup
       // would report installed v3.4.21-dev "→ latest v2.9.0" and DOWNGRADE a perfectly current
       // machine. (Caught by exercising the failure path against a 404 repo — the first version of
       // this fix did exactly that.) A pinned/forced resolution is likewise the operator's explicit
@@ -5541,7 +5564,8 @@ the installer reports that boot-level declarations changed.
     const localZipPresent =
       FLAG_LOCAL || fs.existsSync(path.join(REPO_ROOT, 'dist', 'ruvnet-brain.zip'));
     // Reuse the staleness check's resolution when it already ran — one network round-trip, not two.
-    const release = localZipPresent ? null : (resolvedRelease || await resolveRelease());
+    const release = localZipPresent ? null
+      : (resolvedRelease || await resolveRelease().catch((error) => die(error.message, error.hint)));
     const { zipPath, sourceDir, tmpDir, downloaded, sigError } = await obtainBundle(release);
     // Verify the Ed25519 signature BEFORE extracting a downloaded bundle into the user's config
     // (SEC-0010 #6 — trust root = the pubkey EMBEDDED in this file, so an attacker who swaps the

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 });
@@ -658,23 +662,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 +731,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 +763,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.`);
 }
@@ -1692,6 +1737,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 +1770,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 +1814,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 +1855,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 +1901,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 +1915,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/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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.39",
+  "version": "4.3.40",
   "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.3.40",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

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'));