ruvnet-brain 4.3.21 → 4.3.25

package/README.md

@@ -1,4 +1,4 @@
-Updated: 2026-09-07 11:22:00 EDT | Version 4.3.10
+Updated: 2026-09-11 08:00:00 EDT | Version 4.3.21
 Created: 2026-06-29 22:36:38 EDT
 
 <div align="center">
@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.21 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.21-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.25 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.25-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.**
 
@@ -47,7 +47,7 @@ safe inverse must not be advertised as a one-click undo. See the
 [![explainer](https://img.shields.io/badge/▶%20see%20it%20live-isovision.ai%2Fruvnet--brain-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
 [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
 [![grounded](https://img.shields.io/badge/answers-cited%20rUv%20source-333?style=flat-square)](#testing--proof)
-[![coverage](https://img.shields.io/badge/coverage-41%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
+[![coverage](https://img.shields.io/badge/coverage-42%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **One Brain generation everywhere.** npm, the GitHub tag/release, bundle manifests, source metadata, and checksum-bound RVF generations must share the same product version. Headline claims are regenerated and checked by the claims ledger (`scripts/claims-verify.mjs`); other numbers below are hand-stamped and dated:
 > - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
@@ -525,7 +525,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L4 "orchestrate"** | **downgraded — measures speech, not obedience** | L4 asserts the hook's own injected prose contains required words (`must: ['take the wheel','SPARC','swarm',…]`). That proves **the brain spoke**. It cannot fail when the advice is read and ignored — which is the failure this product exists to prevent. Counterfactual replay against a brain-off control (ADR-058 §D4) is what will earn this row back |
 | **Plugin QA** | **60 / 60** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published bundle fresh → unzip → query → grounded, cited answers |
-| **Unit tests** | **3,035 passing, 161 todo** · 41% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 41% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
+| **Unit tests** | **3,035 passing, 161 todo** · 42% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 42% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
 | **Grounding proof** | `npx ruvnet-brain --doctor` | asks a real question, then checks the cited path really exists in the on-disk store; a citation that doesn't resolve is reported as **NOT grounded** |
 | **Held-out eval** | **grounded 100/100** · routed 63/80 | `npm run eval` — 120 frozen, hash-pinned questions across 5 strata, never used for tuning, graded on ground truth, never by a model |
 
@@ -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** — 184 public stores · 146,970 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** — 182 public stores · 143,719 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

@@ -32,8 +32,9 @@ import { applyManagedCatalogUpdate } from '../scripts/model-router-catalog.mjs';
 import { cmpVersion } from '../scripts/stack-sync.mjs';
 import { validateCoverageDirectory } from '../plugin/scripts/coverage-integrity.mjs';
 import {
-  CONTINUITY_EVENTS,
   continuityContractIds,
+  continuityHookId,
+  continuityRegistrations,
   isAllowedContinuityRegistration,
 } from '../plugin/scripts/continuity-hook-policy.mjs';
 import {
@@ -68,6 +69,9 @@ import {
   CONSOLE_RUNTIME_SURFACE, CONSOLE_RUNTIME_IDENTITY_FILE, consoleRuntimeDigest,
 } from '../scripts/console-runtime-identity.mjs';
 import { shellDiff as pluginShellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
+import {
+  writeInstalledRuntimeIdentity, recordCorpusTransportIdentity, isCorpusReleaseTag, rejectedReleasePath,
+} from '../kb/corpus-release-identity.mjs';
 
 // SEC-0010 #6 — the Ed25519 PUBLIC key is EMBEDDED here (not a separate file) so the installer's
 // trust root travels with the installer code itself: an attacker who swaps the downloaded bundle
@@ -318,6 +322,32 @@ function fetchJson(url, redirects = 0) {
 // --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.
+/**
+ * Which asset of a Release actually holds the brain bundle.
+ *
+ * THE UNAMBIGUOUS SINGLE ZIP — the lesson kb/forge-update.mjs's resolveBundleUrl() already learned
+ * (issue #35) and this installer had not. Matching ONLY the conventional `ruvnet-brain.zip` means a
+ * release whose bundle asset is named anything else falls through to `fallbackUrl(tag)`, a URL
+ * assembled from that same conventional name — so the "fallback" is a guaranteed 404, not a
+ * download. The path that reaches it is a FRESH install: the one case with no brain already on disk
+ * to keep working. ADR-086 step 16 makes this reachable in practice, because `releases/latest` can
+ * now be a corpus release.
+ *
+ * A release carrying exactly one .zip is not ambiguous about which zip is the bundle. Two or more
+ * and guessing would be worse than the honest warning, so it falls through as before.
+ *
+ * Pure and exported so the choice is testable without a network round-trip.
+ * @returns {{url: string, origin: 'exact-name'|'single-zip'|'conventional-url', assetName: string|null}}
+ */
+export function resolveReleaseAsset({ tag, assets, assetName = ASSET_NAME }) {
+  const list = Array.isArray(assets) ? assets : [];
+  const exact = list.find((a) => a && a.name === assetName && a.browser_download_url);
+  if (exact) return { url: exact.browser_download_url, origin: 'exact-name', assetName: exact.name };
+  const zips = list.filter((a) => a && typeof a.name === 'string' && a.name.endsWith('.zip') && a.browser_download_url);
+  if (zips.length === 1) return { url: zips[0].browser_download_url, origin: 'single-zip', assetName: zips[0].name };
+  return { url: fallbackUrl(tag), origin: 'conventional-url', assetName: null };
+}
+
 async function resolveRelease() {
   step(
     'Finding the latest brain to install',
@@ -347,9 +377,10 @@ async function resolveRelease() {
     const rel = await fetchJson(RELEASE_API);
     const tag = rel && rel.tag_name;
     if (!tag) throw new Error('latest Release has no tag_name');
-    const asset = Array.isArray(rel.assets) ? rel.assets.find((a) => a.name === ASSET_NAME) : null;
-    const url = asset && asset.browser_download_url ? asset.browser_download_url : fallbackUrl(tag);
-    if (!asset) {
+    const { url, origin, assetName } = resolveReleaseAsset({ tag, assets: rel.assets });
+    if (origin === 'single-zip') {
+      warn(`latest Release ${tag} has no ${ASSET_NAME} — using its only .zip asset, ${c.bold(assetName)}`);
+    } else if (origin === 'conventional-url') {
       warn(`latest Release ${tag} has no ${ASSET_NAME} asset listed — using the conventional download URL`);
     }
     ok(`latest Release is ${c.bold(tag)}`);
@@ -485,7 +516,51 @@ export function copyLocalBundleInto(sourceDir, cacheDir) {
   return copied;
 }
 
-export async function unzipInto(zipPath, cacheDir, sourceDir = null) {
+// ── the trusted coverage validator lives beside the updater, and only the INSTALLER puts it there ──
+// kb/forge-update.mjs (`loadTrustedCoverageValidator`) judges every downloaded bundle with
+// `KB_DIR/coverage-integrity.mjs` and dies — "installed coverage validator is missing; re-run the
+// current installer before self-update" — when it is absent. The bundle cannot be the source: the
+// validator vets the bundle, so it must come from the signed npm package. Measured 2026-09-12: no
+// production path had ever placed it (build-bundle's import walk cannot see the updater's dynamic
+// load; this installer imported the module for its own checks and never copied it), so every
+// 4.3.21 `--update` — the nightly included — died in the updater and fell back to a fresh install,
+// which a private-overlay brain refuses. Idempotent, byte-compared, atomic; a symlink is replaced by
+// a real file because a link is not a trusted regular file.
+const TRUSTED_VALIDATOR_SOURCE = path.join(REPO_ROOT, 'plugin', 'scripts', 'coverage-integrity.mjs');
+export function placeTrustedCoverageValidator(kbDir, { source = TRUSTED_VALIDATOR_SOURCE,
+  brainVersion = PACKAGE_VERSION } = {}) {
+  let bytes;
+  try { bytes = fs.readFileSync(source); }
+  catch (error) { throw new Error(`trusted coverage validator is missing from this package (${source}): ${error.message}`); }
+  const target = path.join(kbDir, 'coverage-integrity.mjs');
+  let existing = null;
+  try { existing = fs.lstatSync(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const unchanged = existing && existing.isFile() && !existing.isSymbolicLink() && fs.readFileSync(target).equals(bytes);
+  if (!unchanged) {
+    const staged = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(staged, bytes, { mode: 0o644 });
+    if (existing && existing.isSymbolicLink()) fs.unlinkSync(target); // never write through a link
+    fs.renameSync(staged, target);
+  }
+  // STAMP THE APPROVED RUNTIME IN THE SAME BREATH AS PLACING ITS EXECUTABLES (ADR-086 step 16).
+  //
+  // This is the one moment where "which runtime is this brain running" is a measured fact rather
+  // than an assertion: the bytes were just written from THIS package, so the version and the hashes
+  // are recorded together and cannot drift. kb/forge-update.mjs re-hashes them before it will accept
+  // a corpus release — Dual: "Pinning survives only through enforced equality to the approved
+  // shipped runtime and its executable hashes. Copying current-main package.json or preserving a
+  // version string alone is insufficient." Re-stamped on every placement (install AND `--update`
+  // preflight), so an upgraded runtime immediately supersedes the previous pin.
+  const runtime = writeInstalledRuntimeIdentity(kbDir, { brainVersion });
+  return { action: unchanged ? 'unchanged' : (existing ? 'replaced' : 'placed'), path: target, runtimeIdentity: runtime };
+}
+/** `--update` preflight: place the validator only where an updater exists to consume it. */
+export function ensureUpdaterPrerequisites(kbDir) {
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) return { updater: false, validator: null };
+  return { updater: true, validator: placeTrustedCoverageValidator(kbDir) };
+}
+
+export async function unzipInto(zipPath, cacheDir, sourceDir = null, { releaseTag = null } = {}) {
   step(
     'Unpacking the brain into place',
     'so the plugin finds forge-mcp-all.mjs and the vector stores right where it looks',
@@ -566,6 +641,25 @@ export async function unzipInto(zipPath, cacheDir, sourceDir = null) {
       `The archive layout may have changed. Re-run, or report this at https://github.com/stuinfla/ruvnet-brain/issues`,
     );
   }
+  // A freshly installed brain must be able to self-update on its first night: the bundle never
+  // carries the trusted validator its own updater demands, so the installer lays it into the stage.
+  placeTrustedCoverageValidator(stageDir);
+  // THE TRANSPORT IDENTITY LANDS WITH THE BYTES. When `releases/latest` is a corpus release, the
+  // tag that authenticated these bytes (`corpus-sha256-<64 hex>`) is recorded in the STAGE, so the
+  // single rename below promotes the tree and its provenance together or promotes neither. Writing
+  // it after activation would leave a window where a crash yields an installed corpus this brain
+  // cannot name — and an unnamed corpus is a corpus the updater re-downloads every night.
+  // `brainVersion` / `releaseTag` are untouched: they are the runtime the bundle was built by, and
+  // a content address is not a version of that runtime (ADR-086 step 16, "keep runtime version
+  // distinct"). A non-corpus tag CLEARS any stale corpus tag — see recordCorpusTransportIdentity.
+  if (releaseTag) {
+    try { recordCorpusTransportIdentity(stageDir, { releaseTag }); }
+    catch (error) {
+      fs.rmSync(stageDir, { recursive: true, force: true });
+      die(`could not record the release identity into the staged brain (${error.message})`,
+        'The live brain was not touched. Re-run the installer.');
+    }
+  }
   const stagedCoverage = validateCoverageDirectory(stageDir, { expectedVersion: PACKAGE_VERSION });
   if (!stagedCoverage.valid) {
     fs.rmSync(stageDir, { recursive: true, force: true });
@@ -647,7 +741,8 @@ export async function unzipInto(zipPath, cacheDir, sourceDir = null) {
     `Candidate retained for inspection at ${stageDir}.`);
   }
   if (hadPrior) warn(`PRESERVED_UNCLASSIFIED: prior generation retained at ${preservedDir}. ` +
-    'Not eligible for automatic cleanup; repeated installs can grow disk usage. Inspect manually before removal.');
+    'The updater (kb/forge-update.mjs) releases it only once every byte is proven to survive in the live brain; ' +
+    'until then it stays, and repeated installs can grow disk usage.');
   ok(`brain unpacked to ${cacheDir}`);
   return { status: 'ACTIVATED', priorGeneration: hadPrior
     ? { status: 'PRESERVED_UNCLASSIFIED', path: preservedDir, automaticCleanupEligible: false }
@@ -1901,14 +1996,25 @@ export function classifyCodexLifecycle(plugin, listed = null) {
   if (!plugin.enabled) return { state: 'disabled', plugin, hooks: [] };
   if (!listed.ok) return { state: 'probe-failed', plugin, hooks: [], error: listed.error };
   const groups = Array.isArray(listed.value?.data) ? listed.value.data : [];
-  const hooks = groups.flatMap((group) => Array.isArray(group?.hooks) ? group.hooks : [])
+  const hooks = groups.flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : [])
+    .map((hook) => ({ ...hook, event: hook?.event ?? group?.event ?? null })))
     .filter((hook) => hook?.pluginId === CODEX_PLUGIN_ID);
   const errors = groups.flatMap((group) => Array.isArray(group?.errors) ? group.errors : []);
   if (errors.length) {
     return { state: 'missing-runtime-hooks', plugin, hooks, errors };
   }
-  if (hooks.length === 0) return { state: 'inactive-by-design', plugin, hooks, errors };
-  return { state: 'unexpected-runtime-hooks', plugin, hooks, errors };
+  // A REGISTERED CONTINUITY HOOK IS NOT A RETIRED ONE.
+  //
+  // This used to treat EVERY Brain-owned runtime registration as stale, because at the time the
+  // policy permitted none on Codex. The doctor therefore reported the SessionStart restore and the
+  // Stop continuation gate — the two handlers the policy itself requires — as "retired Brain
+  // lifecycle hooks", told the user to upgrade, and returned a failing exit code for a correctly
+  // wired machine. The authority on what belongs is the policy, so ask it instead of assuming zero.
+  const conforming = hooks.filter((hook) => continuityHookId(hook?.command, hook?.event));
+  const unexpected = hooks.filter((hook) => !continuityHookId(hook?.command, hook?.event));
+  if (unexpected.length) return { state: 'unexpected-runtime-hooks', plugin, hooks: unexpected, errors };
+  if (conforming.length === 0) return { state: 'inactive-by-design', plugin, hooks, errors };
+  return { state: 'continuity-registered', plugin, hooks: conforming, errors };
 }
 
 export async function codexLifecycleStatus(options = {}) {
@@ -1930,6 +2036,16 @@ export function codexLifecycleGuidance(status) {
         detail: 'Any Brain-owned runtime registration is stale and must not be trusted or executed.',
         action: `Upgrade ${CODEX_PLUGIN_ID}, then start a fresh Codex session and re-run --doctor.`,
       };
+    case 'continuity-registered':
+      return {
+        healthy: true,
+        intentional: true,
+        summary: `Codex carries ${hookCount} declared Brain continuity hook${hookCount === 1 ? '' : 's'}.`,
+        detail: 'Each one is named in plugin/hooks/hook-contracts.json. Codex capture is SessionEnd only:'
+          + ' a 2026-09-11 probe observed SessionStart, UserPromptSubmit and SessionEnd firing, and did not'
+          + ' observe Stop or PreCompact, so no capture handler was registered on those.',
+        action: null,
+      };
     case 'inactive-by-design':
       return {
         healthy: true,
@@ -2054,22 +2170,31 @@ export function automaticHookRetirementStatus(root = REPO_ROOT, { scope = 'sourc
             // Project-local host settings must remain empty. The package registries may carry only
             // the two continuity handlers; every former gate is still retired.
             const packageRegistry = relative === 'plugin/hooks/hooks.json' || relative === 'plugin/hooks/codex-hooks.json';
-            if (!packageRegistry || !isAllowedContinuityRegistration(row)) registrations.push(row);
+            const host = relative === 'plugin/hooks/codex-hooks.json' ? 'codex' : 'claude';
+            if (!packageRegistry || !isAllowedContinuityRegistration({ ...row, host })) registrations.push(row);
           }
         }
       }
       if (relative === 'plugin/hooks/hooks.json' || relative === 'plugin/hooks/codex-hooks.json') {
-        for (const [event, spec] of Object.entries(CONTINUITY_EVENTS)) {
-          const count = (doc.hooks[event] ?? []).flatMap((group) => group?.hooks ?? [])
-            .filter((hook, index, hooks) => isAllowedContinuityRegistration({
-              event,
-              matcher: (doc.hooks[event] ?? []).find((group) => (group.hooks ?? []).includes(hook))?.matcher,
-              command: hook?.command,
-            })).length;
-          if (count !== 1) errors.push(`${relative}: continuity ${spec.id} must have exactly one registration (found ${count})`);
+        // PAIRS, NOT IDS. `session-snapshot` is legitimately registered at Stop, PreCompact and
+        // SessionEnd, so "exactly one registration per id" is the wrong invariant; "exactly one per
+        // (event, id), on the hosts that are proven to deliver that event" is the right one.
+        const host = relative === 'plugin/hooks/codex-hooks.json' ? 'codex' : 'claude';
+        const expected = continuityRegistrations(host);
+        for (const spec of expected) {
+          const groups = doc.hooks[spec.event] ?? [];
+          const count = groups.flatMap((group) => (group?.hooks ?? []).map((hook) => ({ group, hook })))
+            .filter(({ group, hook }) => String(group?.matcher ?? '') === spec.matcher
+              && isAllowedContinuityRegistration({ event: spec.event, matcher: group?.matcher, command: hook?.command, host })
+              && continuityHookId(hook?.command, spec.event)?.id === spec.id).length;
+          if (count !== 1) {
+            errors.push(`${relative}: continuity ${spec.event}:${spec.id} must have exactly one registration (found ${count})`);
+          }
         }
         for (const event of Object.keys(doc.hooks)) {
-          if (!CONTINUITY_EVENTS[event]) errors.push(`${relative}: legacy automatic event ${event} remains registered`);
+          if (!expected.some((spec) => spec.event === event)) {
+            errors.push(`${relative}: legacy automatic event ${event} remains registered`);
+          }
         }
       }
     } catch (error) {
@@ -2080,12 +2205,19 @@ export function automaticHookRetirementStatus(root = REPO_ROOT, { scope = 'sourc
     const contractsFile = 'plugin/hooks/hook-contracts.json';
     const contracts = JSON.parse(fs.readFileSync(path.join(root, contractsFile), 'utf8'));
     checkedFiles.push(contractsFile);
-    const ids = Array.isArray(contracts.contracts) ? contracts.contracts.map((c) => c?.id) : [];
-    if (ids.length !== continuityContractIds().length || continuityContractIds().some((id) => !ids.includes(id))) {
-      errors.push(`${contractsFile}: contracts must list only the continuity handlers (${continuityContractIds().join(', ')})`);
+    const pairs = Array.isArray(contracts.contracts) ? contracts.contracts.map((c) => `${c?.event}:${c?.id}`) : [];
+    const expectedPairs = continuityContractIds();
+    if (pairs.length !== expectedPairs.length || expectedPairs.some((pair) => !pairs.includes(pair))) {
+      errors.push(`${contractsFile}: contracts must list exactly the continuity handlers (${expectedPairs.join(', ')})`);
     }
-    if (!Array.isArray(contracts.matcherAllowlist) || contracts.matcherAllowlist.length !== continuityContractIds().length) {
-      errors.push(`${contractsFile}: matcherAllowlist must list the two continuity matchers`);
+    // One allowlist entry per DISTINCT (event, matcher): the matcher is a property of the event, so
+    // three snapshot registrations on three events need three entries, not three copies of one.
+    const expectedMatchers = [...new Set(continuityRegistrations().map((spec) => `${spec.event}:${spec.matcher}`))];
+    const declaredMatchers = Array.isArray(contracts.matcherAllowlist)
+      ? contracts.matcherAllowlist.map((row) => `${row?.event}:${row?.matcher}`) : [];
+    if (declaredMatchers.length !== expectedMatchers.length
+      || expectedMatchers.some((entry) => !declaredMatchers.includes(entry))) {
+      errors.push(`${contractsFile}: matcherAllowlist must list exactly the continuity matchers (${expectedMatchers.join(', ')})`);
     }
   } catch (error) {
     errors.push(`plugin/hooks/hook-contracts.json: ${error.message}`);
@@ -2141,17 +2273,21 @@ export function claudeInstalledHookRetirementStatus({ home = os.homedir(), plugi
           }
         }
       }
-      for (const [event, spec] of Object.entries(CONTINUITY_EVENTS)) {
-        const count = (doc.hooks[event] ?? []).flatMap((group) => group?.hooks ?? [])
-          .filter((hook) => isAllowedContinuityRegistration({
-            event,
-            matcher: (doc.hooks[event] ?? []).find((group) => (group.hooks ?? []).includes(hook))?.matcher,
-            command: hook?.command,
-          })).length;
-        if (count !== 1) errors.push(`installed Claude continuity ${spec.id} must have exactly one registration (found ${count})`);
+      const expected = continuityRegistrations('claude');
+      for (const spec of expected) {
+        const count = (doc.hooks[spec.event] ?? [])
+          .flatMap((group) => (group?.hooks ?? []).map((hook) => ({ group, hook })))
+          .filter(({ group, hook }) => String(group?.matcher ?? '') === spec.matcher
+            && isAllowedContinuityRegistration({ event: spec.event, matcher: group?.matcher, command: hook?.command, host: 'claude' })
+            && continuityHookId(hook?.command, spec.event)?.id === spec.id).length;
+        if (count !== 1) {
+          errors.push(`installed Claude continuity ${spec.event}:${spec.id} must have exactly one registration (found ${count})`);
+        }
       }
       for (const event of Object.keys(doc.hooks)) {
-        if (!CONTINUITY_EVENTS[event]) errors.push(`installed Claude legacy automatic event ${event} remains registered`);
+        if (!expected.some((spec) => spec.event === event)) {
+          errors.push(`installed Claude legacy automatic event ${event} remains registered`);
+        }
       }
     }
   } catch (error) {
@@ -2295,7 +2431,19 @@ async function smokeQuery(cacheDir) {
   const secs = ((Date.now() - started) / 1000).toFixed(1);
   const out = `${r.stdout || ''}`;
   if (r.status !== 0 || !out.trim()) {
-    warn('no answer came back (first-run model download or offline) — the brain is installed; it\'ll warm on your first real question');
+    // NAME THE ACTUAL CAUSE, DO NOT GUESS A REASSURING ONE.
+    //
+    // This said "first-run model download or offline" unconditionally. It is one plausible cause
+    // among several, asserted as though it had been checked — and it is the reassuring one, so a
+    // crash, a timeout, and a missing module all read as "nothing is wrong, it will warm up".
+    // Observed on this machine: a smoke query that produced no answer in 240s was reported as a
+    // first-run download. spawnSync already tells us which it was; say that instead.
+    const cause = r.error ? `could not launch the reader: ${r.error.message}`
+      : r.signal === 'SIGTERM' ? `timed out after ${secs}s (240s limit) with no answer`
+        : r.signal ? `the reader was killed by ${r.signal} after ${secs}s`
+          : r.status !== 0 ? `the reader exited ${r.status} after ${secs}s`
+            : `the reader exited 0 after ${secs}s but printed nothing`;
+    warn(`no answer came back — ${cause}`);
     // SHOW THE ACTUAL ERROR (issue #37 bug 2, Agentist-Elder, 2026-07-21).
     //
     // This captured stderr and then threw it away, so every hard failure — a crash, a missing
@@ -2315,7 +2463,9 @@ async function smokeQuery(cacheDir) {
       for (const line of lines.slice(0, 12)) info(c.dim(`    ${line.slice(0, 200)}`));
       if (lines.length > 12) info(c.dim(`    … ${lines.length - 12} more line(s)`));
     }
-    return { ran: true, grounded: false, reason: 'no-answer', stderr: err.slice(0, 4000) };
+    // The reason travels with the verdict so the doctor's "Grounding NOT proven (<reason>)" line
+    // names the real cause too, instead of the generic token.
+    return { ran: true, grounded: false, reason: `no-answer: ${cause}`, secs, stderr: err.slice(0, 4000) };
   }
 
   const verifier = await loadCitationVerifier(cacheDir);
@@ -2613,11 +2763,16 @@ async function doctor() {
   const v = verifyInstall(cacheDir);
   const smoke = await smokeQuery(cacheDir);
   const allGreen = v.repos > 0 && v.reader && v.mcp;
-  console.log(
-    `\n  ${allGreen ? c.green('✓ Healthy.') : c.yellow('! Needs attention.')} ${
-      allGreen ? 'The brain is installed and reachable.' : 'Re-run the installer to fix the warnings above.'
-    }`,
-  );
+  // ONE VERDICT, AND IT COMES AFTER ITS EVIDENCE.
+  //
+  // This line used to print "✓ Healthy." here, from `allGreen` — which reads only repos/reader/mcp —
+  // and then a SECOND verdict, "✗ FAILING", printed ~120 lines later from the much wider `failed`.
+  // A --doctor run genuinely emitted both, and exited 0. Two verdicts is not a cosmetic problem: a
+  // reader stops at the first one, so the tool told people they were healthy while its own exit-code
+  // logic had already decided otherwise. The single verdict is now emitted at the end, where every
+  // input to `failed` exists; this position keeps only the installed-and-reachable READING.
+  console.log(`\n  ${allGreen ? c.green('Install: present and reachable.')
+    : c.yellow('Install: incomplete — see the warnings above.')}`);
   // Installed-and-reachable and actually-grounded are different claims. Keep them separate, so a
   // healthy install can never be mistaken for proven grounding.
   if (smoke.grounded === true) {
@@ -2736,8 +2891,11 @@ async function doctor() {
     || codexReadinessFailed
     || !hostConvergence.healthy
     || Boolean(rufloOperational && !rufloOperational.healthy);
-  if (failed && !hookResult && !groundingUnprovenPersisted) {
-    console.log(`  ${c.red('✗ FAILING')} — the warnings above are real. Re-run  ${c.bold('npx ruvnet-brain')}  to repair.`);
+  // THE ONE VERDICT. Always printed, always consistent with the exit code, never alongside another.
+  if (failed) {
+    console.log(`\n  ${c.red('✗ FAILING')} — the warnings above are real. Re-run  ${c.bold('npx ruvnet-brain')}  to repair.`);
+  } else {
+    console.log(`\n  ${c.green('✓ Healthy.')} The brain is installed, reachable, and its checks pass.`);
   }
   return failed ? 1 : 0;
 }
@@ -2805,6 +2963,20 @@ function cmpTag(a, b) {
   return A.pre > B.pre ? 1 : -1;
 }
 
+/**
+ * The CORPUS transport tag this brain last received, or null.
+ *
+ * Deliberately separate from installedBrainVersion(): that one answers "which runtime built the KB
+ * on disk" (a semver), this one answers "which published corpus archive is on disk" (a content
+ * address). Conflating them is the defect ADR-086 step 16 exists to fix.
+ */
+function installedCorpusTag(cacheDir) {
+  try {
+    const tag = JSON.parse(fs.readFileSync(path.join(cacheDir, 'SOURCE.json'), 'utf8')).corpusReleaseTag;
+    return isCorpusReleaseTag(tag) ? tag : null;
+  } catch { return null; }
+}
+
 function installedBrainVersion(cacheDir) {
   // Same read the telemetry ping uses: the bundle stamps its Release tag into SOURCE.json.
   // "unknown" is honest for a locally-built or pre-stamping bundle — never guess a tag.
@@ -2909,7 +3081,11 @@ function feedbackHealthLines(cacheDir) {
   return [
     `${s.repos} repo stores on disk · reader ${s.reader ? 'ok' : 'MISSING'} · search_ruvnet ${s.mcp ? 'ok' : 'MISSING'} · plugin ${s.plugin ? 'ok' : 'NOT INSTALLED (no /rvbc)'}`,
     `toolkit: Ruflo ${env.ruflo ? 'present' : 'not found'} · RuVector ${env.ruvector ? 'present' : 'not found'} · claude CLI ${env.claude ? 'present' : 'not found'}`,
-    allGreen ? 'verdict: Healthy — installed and reachable' : 'verdict: Needs attention — re-run npx ruvnet-brain',
+    // NOT called a "verdict": this reads only repos/reader/mcp, while --doctor's verdict also weighs
+    // grounding, Codex wiring, nightly health, host convergence and the hook policy. Two lines both
+    // labelled "verdict" that answer different questions can disagree in public, which is the exact
+    // Healthy-and-FAILING confusion the doctor's single verdict was collapsed to remove.
+    allGreen ? 'install reading: present and reachable' : 'install reading: incomplete — re-run npx ruvnet-brain',
   ];
 }
 
@@ -3321,6 +3497,17 @@ function runUpdate() {
     settleRefresh(1, { phase: 'source-enumeration' });
     return;
   }
+  // The updater exists; make sure the trusted validator it will load exists too (package copy,
+  // byte-compared). A failure here is reported, not fatal — the updater states the same absence
+  // in its own words and the run then takes the documented fallback.
+  try {
+    const prerequisites = ensureUpdaterPrerequisites(kbDir);
+    if (prerequisites.validator?.action !== 'unchanged') {
+      info(c.dim(`trusted coverage validator ${prerequisites.validator.action} beside the updater`));
+    }
+  } catch (error) {
+    warn(`could not place the trusted coverage validator (${error.message}); the updater will report what it finds`);
+  }
   info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
   // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
   // streams the updater's narration live and unedited.
@@ -3667,6 +3854,12 @@ export function machineFootprint() {
     const artifact = nightlyArtifact({ platform: process.platform, env: process.env });
     if (artifact.kind === 'launchd') add('Nightly updater (LaunchAgent)', artifact.path, 'npx ruvnet-brain --disable-nightly');
     add('Nightly scheduler registration', path.join(process.env.RUVNET_BRAIN_HOME || path.dirname(resolvedKbDir()), 'scheduler', 'registration.json'), 'npx ruvnet-brain --disable-nightly');
+    // Only ever present after the updater refused an incompatible corpus release (ADR-086 step 16).
+    // It lives BESIDE the KB rather than inside it so an exact-tree update cannot erase the memory of
+    // the refusal — which is what keeps a refusal from being rediscovered, and re-downloaded, nightly.
+    // Declared here because a file we write is a file we own and must be able to take back.
+    add('Rejected-release memo (only after an incompatible corpus release)',
+      rejectedReleasePath(resolvedKbDir()), 'npx ruvnet-brain --uninstall');
   }
   if (process.platform === 'darwin') {
     add('Spend watchdog (LaunchAgent)', spendGuardPlistPath(), 'npx ruvnet-brain --disable-spend-guard');
@@ -3847,6 +4040,7 @@ function uninstallAll() {
   // owns (settings.json entries, the MCP registration) and the Claude Code plugin itself are not
   // ours to delete, so they are handed over as commands.
   const AUTO = new Set(['Brain bundle (knowledge base)', 'Nightly updater (LaunchAgent)', 'Nightly scheduler registration',
+    'Rejected-release memo (only after an incompatible corpus release)',
     'Spend watchdog (LaunchAgent)', 'Spend watchdog script', 'CLAUDE.md block (6 lines, between markers)',
     'Model-router files', 'Status-bar version script', 'Status-bar preference', 'Usage-counts preference',
     // Two gaps closed here: the statusLine KEY is now removable in place (we know exactly what we
@@ -4471,7 +4665,11 @@ export function classifyRufloOperationalHealth({ status = '', memory = '', metri
 
 function probeRufloOperationalHealth() {
   const run = (args) => {
-    const result = spawnSync('ruflo', args, { cwd: process.cwd(), encoding: 'utf8', timeout: 10_000 });
+    // Every `ruflo` invocation auto-starts a project background daemon unless this is set
+    // (verified live: ~/.npm-global/lib/node_modules/ruflo/node_modules/@claude-flow/cli/dist/src/
+    // services/daemon-autostart.js:85) — a read-only health probe must not leave one running.
+    const result = spawnSync('ruflo', args, { cwd: process.cwd(), encoding: 'utf8', timeout: 10_000,
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' } });
     return `${result.stdout || ''}\n${result.stderr || ''}`;
   };
   return classifyRufloOperationalHealth({
@@ -5169,21 +5367,33 @@ the installer reports that boot-level declarations changed.
         ? (resolvedRelease.tag_name || resolvedRelease.tag || null)
         : null;
     } catch { latestTag = null; }
-    const norm = (v) => (v == null || v === 'unknown' ? null : String(v).replace(/^v/, ''));
-    const a = norm(installedTag), b = norm(latestTag);
-    // BEHIND => download. SAME => skip. AHEAD => skip, and say so honestly.
-    //
-    // This was a bare `a !== b`, which treats "newer than the latest release" as staleness. Anyone
-    // running a pre-release or dev build — or who simply updated in the window before a release was
-    // cut — was told "Brain is out of date" and pushed through a 2 GB download that would DOWNGRADE
-    // them. Found 2026-07-22 the moment this repo's own version moved to 3.5.0-dev ahead of the
-    // 3.4.22-dev release: the installer immediately declared its own newest brain stale.
-    //
-    // stack-sync.mjs has modelled AHEAD as legal from the start ("AHEAD is legal and produces NO
-    // recommendation — that modelling choice is what makes the alpha-vs-latest downgrade war
-    // structurally impossible"). The installer never learned the same lesson. It has now.
-    ahead = Boolean(a && b && cmpTag(a, b) > 0);
-    staleSkip = Boolean(b && (a === null || (a !== b && !ahead)));
+    // A CORPUS RELEASE IS NOT ORDERABLE AGAINST A SEMVER (ADR-086 step 16). `corpus-sha256-<64 hex>`
+    // is a content address; cmpTag() parses its leading segment with parseInt, gets NaN, floors it
+    // to 0, and concludes any installed version is NEWER — so a corpus release would be reported as
+    // "installed is NEWER than the latest release" and silently skipped, forever. Compare the
+    // installed corpus tag against the offered corpus tag instead: equal = current, different =
+    // behind, never "ahead", because content addresses have no order.
+    if (isCorpusReleaseTag(latestTag)) {
+      const installedCorpus = installedCorpusTag(cacheDir);
+      ahead = false;
+      staleSkip = installedCorpus !== latestTag;
+    } else {
+      const norm = (v) => (v == null || v === 'unknown' ? null : String(v).replace(/^v/, ''));
+      const a = norm(installedTag), b = norm(latestTag);
+      // BEHIND => download. SAME => skip. AHEAD => skip, and say so honestly.
+      //
+      // This was a bare `a !== b`, which treats "newer than the latest release" as staleness. Anyone
+      // running a pre-release or dev build — or who simply updated in the window before a release was
+      // cut — was told "Brain is out of date" and pushed through a 2 GB download that would DOWNGRADE
+      // them. Found 2026-07-22 the moment this repo's own version moved to 3.5.0-dev ahead of the
+      // 3.4.22-dev release: the installer immediately declared its own newest brain stale.
+      //
+      // stack-sync.mjs has modelled AHEAD as legal from the start ("AHEAD is legal and produces NO
+      // recommendation — that modelling choice is what makes the alpha-vs-latest downgrade war
+      // structurally impossible"). The installer never learned the same lesson. It has now.
+      ahead = Boolean(a && b && cmpTag(a, b) > 0);
+      staleSkip = Boolean(b && (a === null || (a !== b && !ahead)));
+    }
   }
 
   if (alreadyInstalled && !FLAG_FORCE && !staleSkip) {
@@ -5242,7 +5452,12 @@ the installer reports that boot-level declarations changed.
         ok(reason);
       }
     }
-    await unzipInto(zipPath, cacheDir, sourceDir);
+    // The tag is only carried when it came from a genuine `latest` resolution — a pinned/offline
+    // fallback is not evidence of which release these bytes are, and recording a guess would be
+    // worse than recording nothing.
+    await unzipInto(zipPath, cacheDir, sourceDir, {
+      releaseTag: release && release.source === 'latest' ? (release.tag_name || release.tag || null) : null,
+    });
     const brainProfile = readBrainProfile();
     if (brainProfile !== 'complete') {
       const scoped = applyBrainProfile(cacheDir, brainProfile);