ruvnet-brain 4.3.20 → 4.3.25

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 {
@@ -67,6 +68,10 @@ const versionSatisfies = (installed, expected) => {
 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
@@ -317,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',
@@ -346,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)}`);
@@ -484,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',
@@ -565,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 });
@@ -646,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 }
@@ -1182,6 +1278,55 @@ export function claudePluginStatus({ home = os.homedir() } = {}) {
   }
 }
 
+// A plugin version can change without changing anything a running host freezes at boot. Compare
+// the actual installed payload with this candidate before updating it so body-only releases do not
+// manufacture a restart requirement. Unknown paths fail closed: if we cannot prove the boundary,
+// the caller must retain the restart notice rather than silently promise hot loading.
+function inspectPluginShellBoundary(installedRoot, candidateRoot = path.join(REPO_ROOT, 'plugin')) {
+  if (!installedRoot || !candidateRoot) {
+    return { known: false, changed: true, paths: [], restartRequired: true, reason: 'plugin boot surface could not be located' };
+  }
+  try {
+    const paths = pluginShellDiff(installedRoot, candidateRoot);
+    return {
+      known: true,
+      changed: paths.length > 0,
+      paths,
+      restartRequired: paths.length > 0,
+      reason: paths.length ? `boot-level declarations changed: ${paths.join(', ')}` : 'body-only plugin update',
+    };
+  } catch (error) {
+    return { known: false, changed: true, paths: [], restartRequired: true,
+      reason: `plugin boot surface comparison failed: ${error.message}` };
+  }
+}
+
+function codexInstalledPluginRoot({ codexHome = codexHomeDir(), status } = {}) {
+  const row = status?.row || {};
+  for (const value of [status?.installPath, status?.path, row.installPath, row.path]) {
+    if (typeof value === 'string' && value) {
+      try {
+        const real = fs.realpathSync(value);
+        if (fs.statSync(real).isDirectory()) return real;
+      } catch { /* try the cache scan below */ }
+    }
+  }
+  const cacheRoot = path.join(codexHome, 'plugins', 'cache', 'ruvnet-brain', 'ruvnet-brain');
+  let candidates = [];
+  try {
+    candidates = fs.readdirSync(cacheRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(cacheRoot, entry.name))
+      .filter((dir) => {
+        try {
+          const manifest = JSON.parse(fs.readFileSync(path.join(dir, '.codex-plugin', 'plugin.json'), 'utf8'));
+          return manifest?.name === 'ruvnet-brain' && (!status?.version || manifest.version === status.version);
+        } catch { return false; }
+      });
+  } catch { /* absent cache is handled as unknown below */ }
+  return candidates.sort().at(-1) || null;
+}
+
 function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false } = {}) {
   step(
     'Wiring the Claude Code plugin',
@@ -1204,6 +1349,9 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
 
   const before = claudePluginStatus();
   if (requireManaged && !before.managed) return { host: false, wired: false, action: 'unmanaged' };
+  const shellBoundary = before.installed
+    ? inspectPluginShellBoundary(before.installPath)
+    : { known: true, changed: false, paths: [], restartRequired: false, reason: 'new host installation' };
   const addedMarket = before.managed
     ? tryRun('claude', ['plugin', 'marketplace', 'update', 'ruvnet-brain'])
     : tryRun('claude', ['plugin', 'marketplace', 'add', marketplaceSource]);
@@ -1224,8 +1372,18 @@ function wirePlugin({ expectedVersion = PACKAGE_VERSION, requireManaged = false
   const installedHookRetirement = claudeInstalledHookRetirementStatus({ plugin: installed });
   if (installed.installed && versionSatisfies(installed.version, expectedVersion) && installedHookRetirement.ok) {
     ok(`plugin installed at user scope (global, alongside Ruflo / RuVector) — exact version ${installed.version}`);
-    info(`  commands available after a restart: ${c.bold('/rvbc')}, ${c.bold('/ruvnet-brain:configure')}`);
-    return { host: true, wired: true, version: installed.version, manualMarketplace, manualInstall };
+    if (shellBoundary.restartRequired) {
+      warn(`boot-level plugin declarations changed; restart Claude Code once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+    } else if (before.installed && before.version !== installed.version) {
+      info('  body-only update: the Stable Spine is live on the next hook/MCP call; no restart is required.');
+    }
+    info(`  commands available${shellBoundary.restartRequired ? ' after a restart' : ' immediately'}: ${c.bold('/rvbc')}, ${c.bold('/ruvnet-brain:configure')}`);
+    return {
+      host: true, wired: true, version: installed.version, manualMarketplace, manualInstall,
+      shellChanged: shellBoundary.changed, shellChangedPaths: shellBoundary.paths,
+      restartRequired: shellBoundary.restartRequired,
+      ...(shellBoundary.restartRequired ? { sessionSafety: 'restart-required', sessionSafetyReason: shellBoundary.reason } : {}),
+    };
   }
 
   // The honest failure. The brain still WORKS — this is the difference between a broken install and
@@ -1654,6 +1812,7 @@ export function codexPluginStatus(options = {}) {
     installed: Boolean(row?.installed),
     enabled: Boolean(row?.enabled),
     version: row?.version || null,
+    installPath: row?.installPath || row?.path || null,
     row: row || null,
   };
 }
@@ -1691,9 +1850,22 @@ export function wireCodexPlugin({
     if (announce) warn(`Codex Brain plugin is installed but disabled by user or policy — left disabled (${CODEX_PLUGIN_ID}).`);
     return { host: true, action: 'disabled', ...before };
   }
+  // An existing Codex session can keep the plugin generation it loaded at boot. Compare the
+  // installed bytes with the source candidate before mutating the marketplace so body-only updates
+  // remain live while a changed/unknown boot surface gets one explicit restart request.
+  const shellBoundary = before.installed
+    ? inspectPluginShellBoundary(
+      codexInstalledPluginRoot({ codexHome, status: before }),
+      path.join(REPO_ROOT, 'plugin'),
+    )
+    : { known: true, changed: false, paths: [], restartRequired: false, reason: 'new host installation' };
   if (before.installed && before.enabled && versionSatisfies(before.version, expectedVersion)) {
     if (announce) ok(`Codex Brain plugin already installed and enabled (${before.version || 'version unknown'}) — no changes.`);
-    return { host: true, action: 'unchanged', ...before };
+    return {
+      host: true, action: 'unchanged', ...before,
+      shellChanged: shellBoundary.changed, shellChangedPaths: shellBoundary.paths,
+      restartRequired: false,
+    };
   }
 
   if (runJson === runCodexJson && !localMarketplace) {
@@ -1735,17 +1907,23 @@ export function wireCodexPlugin({
   }
   if (announce) {
     ok(`Codex Brain plugin installed and enabled (${after.version || 'version unknown'}).`);
-    warn('Existing Codex app-server sessions may retain the previous plugin path; restart Codex before using the updated plugin.');
+    if (shellBoundary.restartRequired) {
+      warn(`boot-level plugin declarations changed; restart Codex once to load them (${shellBoundary.paths.join(', ') || shellBoundary.reason}).`);
+    } else if (before.installed && before.version !== after.version) {
+      info('  body-only update: the Stable Spine is live on the next hook/MCP call; no restart is required.');
+    }
   }
   return {
     host: true,
     action: before.installed ? 'updated' : 'installed',
     ...after,
-    // Codex currently exposes no generation/session lease API. This explicit guard prevents the
-    // installer from implying that a native cache update is safe for an already-running session.
-    sessionSafety: 'restart-required',
-    restartRequired: true,
-    sessionSafetyReason: 'Codex host cache generations are owned by Codex and have no lease API',
+    shellChanged: shellBoundary.changed,
+    shellChangedPaths: shellBoundary.paths,
+    restartRequired: shellBoundary.restartRequired,
+    ...(shellBoundary.restartRequired ? {
+      sessionSafety: 'restart-required',
+      sessionSafetyReason: shellBoundary.reason,
+    } : {}),
   };
 }
 
@@ -1818,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 = {}) {
@@ -1847,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,
@@ -1971,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) {
@@ -1997,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}`);
@@ -2058,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) {
@@ -2212,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
@@ -2232,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);
@@ -2530,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) {
@@ -2653,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;
 }
@@ -2722,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.
@@ -2802,7 +3057,7 @@ function reportVersionDrift(cacheDir) {
   if (!state.drift) return state;
   warn(`the brain (${c.bold(state.kb)}) and the Claude Code plugin (${c.bold(state.wrapper)}) have drifted apart —`);
   info(`that's normal (they update on separate schedules) and neither one is broken. To bring the`);
-  info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(then restart Claude Code)')}`);
+  info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(body updates go live without a restart; boot-surface changes are called out)')}`);
   return state;
 }
 
@@ -2826,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',
   ];
 }
 
@@ -3061,6 +3320,15 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
     codexReceipt.sessionSafety = results.codex.sessionSafety || null;
     codexReceipt.sessionSafetyReason = results.codex.sessionSafetyReason || null;
   }
+  const claudeReceipt = {
+    state: results.claude.host ? 'ready' : 'absent',
+    version: results.claude.version || null,
+  };
+  if (results.claude?.restartRequired === true) {
+    claudeReceipt.restartRequired = true;
+    claudeReceipt.sessionSafety = results.claude.sessionSafety || null;
+    claudeReceipt.sessionSafetyReason = results.claude.sessionSafetyReason || null;
+  }
   if (okApplied) {
     // ISSUE #153 — a running host may freeze an old plugin root. Reclaim only generations whose
     // modern leases prove no live consumer; legacy roots without that proof stay on disk.
@@ -3093,7 +3361,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
         desiredVersion: PACKAGE_VERSION,
         verifiedAt: new Date().toISOString(),
         hosts: {
-          claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
+          claude: claudeReceipt,
           codex: codexReceipt,
         },
         consoleRuntime: results.consoleRuntime,
@@ -3108,7 +3376,7 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   const convergence = classifyHostConvergence({
     desiredVersion: PACKAGE_VERSION,
     hosts: {
-      claude: { state: results.claude.host ? 'ready' : 'absent', version: results.claude.version || null },
+      claude: claudeReceipt,
       codex: codexReceipt,
     },
     consoleRuntime: results.consoleRuntime,
@@ -3229,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.
@@ -3575,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');
@@ -3755,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
@@ -4379,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({
@@ -4871,10 +5161,8 @@ function success({ cacheDir, isCustom, plugin, codexHost, codexPlugin, env, nigh
   console.log(`\n  ${c.bold('Keep it fresh:')} re-run ${c.bold('npx ruvnet-brain')} any time — the brain itself always pulls the latest`);
   console.log(`  Release regardless (that part isn't cached). For the bleeding-edge installer too, use ${c.bold('npx github:stuinfla/ruvnet-brain')}.`);
 
-  // Hosts cache plugin registries for the lifetime of a session. A restart is therefore required to
-  // unload callbacks from an older hook-bearing generation even though this version registers none.
-  console.log(`\n  ${c.yellow(c.bold('One required cleanup step:'))} restart any ${hostLabel} window that was open before this update.`);
-  console.log(`  ${c.dim('That unloads the old in-memory hook registry; new sessions load the intentional empty registry.')}`);
+  console.log(`\n  ${c.bold('Updates take effect:')} body-only releases go live on the next hook/MCP call without a restart.`);
+  console.log(`  ${c.dim('If boot-level declarations change, the installer names the affected host and requests one restart.')}`);
 
   // ── what to do now ──
   console.log(`\n  ${c.bold('What to do now:')}`);
@@ -4982,8 +5270,8 @@ Env:
                         download or an air-gapped machine is not a broken install). Only ever set
                         this for a locked-down environment where you want to know immediately.
 
-It is safe to re-run at any time. After updating from a hook-bearing version, restart open hosts so
-their old in-memory hook registries unload.
+It is safe to re-run at any time. Body updates go live on the next hook/MCP call. Restart only when
+the installer reports that boot-level declarations changed.
 `);
 }
 
@@ -5079,21 +5367,33 @@ their old in-memory hook registries unload.
         ? (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) {
@@ -5152,7 +5452,12 @@ their old in-memory hook registries unload.
         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);