ruvnet-brain 3.9.85-dev → 3.9.129-dev

package/bin/install.mjs

@@ -3,7 +3,7 @@
 //
 //   npx ruvnet-brain                           # published on npm — shortest, recommended
 //   npx github:stuinfla/ruvnet-brain           # always the latest commit, even ahead of the npm release
-//   node bin/install.mjs --local               # from a repo clone that already has dist/ruvnet-brain.zip
+//   node bin/install.mjs --local               # from a repo clone with assembled dist/ruvnet-brain/
 //
 // Goal: a newcomer runs ONE command and ends up with (a) the brain on disk and (b) the Claude Code
 // plugin wired at user scope — narrating "what I'm doing and why" at every step (the product's ethos).
@@ -15,10 +15,15 @@ import https from 'node:https';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import readline from 'node:readline';
 import crypto from 'node:crypto';
+import { applyBrainProfile, readBrainProfile } from '../kb/brain-profile.mjs';
+import {
+  requiredEmbedderModels,
+  missingEmbedderModels,
+} from '../kb/model-requirements.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
@@ -40,6 +45,10 @@ function verifyBundle(bundlePath, sigPath) {
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
+const PACKAGE_VERSION = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version; }
+  catch { return null; }
+})();
 
 const REPO = 'stuinfla/ruvnet-brain';
 const RELEASE_API = `https://api.github.com/repos/${REPO}/releases/latest`;
@@ -62,7 +71,14 @@ const FLAG_LOCAL = argv.includes('--local');
 const FLAG_FORCE = argv.includes('--force');
 const FLAG_HELP = argv.includes('--help') || argv.includes('-h');
 const FLAG_DOCTOR = argv.includes('--doctor');
+// `--doctor --hooks`: the post-install hook battery (ADR-053 §2 / ADR-055 build item 2). Fires every
+// registration in the INSTALLED hooks.json through the real shim under four stdin regimes with an
+// external process-group watchdog. Separate flag because it spawns real hooks — the plain --doctor
+// stays a pure read.
+const FLAG_HOOKS = argv.includes('--hooks');
 const FLAG_NO_VERIFY = argv.includes('--no-verify');
+// Escape hatch for the installer's closing self-check ONLY (it never disables --doctor's verdict).
+const FLAG_NO_SELFCHECK = argv.includes('--no-selfcheck');
 const FLAG_PIN = argv.includes('--pin'); // skip the latest-check, use the bundled default
 const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walkthrough of the brain in action
 const FLAG_FEEDBACK = argv.includes('--feedback'); // prefill a GitHub Discussion (version + health, nothing private) and open it
@@ -272,6 +288,14 @@ async function resolveRelease() {
     return { tag: FORCED_VERSION, url: fallbackUrl(FORCED_VERSION), source: 'forced' };
   }
 
+  // Deterministic integration seam: stale/current behavior must not depend on GitHub API quota.
+  // It is inert unless the installer's existing mutation-safe test mode is explicitly enabled.
+  if (process.env.RUVNET_BRAIN_TEST === '1' && process.env.RUVNET_BRAIN_TEST_LATEST_TAG) {
+    const tag = process.env.RUVNET_BRAIN_TEST_LATEST_TAG;
+    info(`test mode: latest Release is ${c.bold(tag)}`);
+    return { tag, url: fallbackUrl(tag), source: 'latest' };
+  }
+
   try {
     info(`checking ${RELEASE_API} …`);
     const rel = await fetchJson(RELEASE_API);
@@ -308,16 +332,24 @@ function resolveCacheDir() {
 // ── step: obtain the bundle (local or download) ──────────────────────────────────────────────────
 async function obtainBundle(release) {
   const localZip = path.join(REPO_ROOT, 'dist', 'ruvnet-brain.zip');
+  const localDir = path.join(REPO_ROOT, 'dist', 'ruvnet-brain');
   const haveLocal = fs.existsSync(localZip);
+  const haveLocalDir = fs.existsSync(path.join(localDir, 'forge-mcp-all.mjs'));
 
-  if (FLAG_LOCAL && !haveLocal) {
+  if (FLAG_LOCAL && !haveLocalDir) {
     die(
-      `--local was passed but ${localZip} does not exist.`,
+      `--local was passed but ${localDir} is not an assembled brain bundle.`,
       `Build it first with:  ${c.bold('node scripts/build-bundle.mjs')}  (then re-run with --local),\nor drop --local to download the published brain instead.`,
     );
   }
 
-  if (haveLocal || FLAG_LOCAL) {
+  if (FLAG_LOCAL) {
+    step('Using the local brain bundle', 'you are running from the repo, so no download is needed');
+    info(`source: ${localDir}`);
+    return { sourceDir: localDir, downloaded: false };
+  }
+
+  if (haveLocal) {
     step('Using the local brain bundle', 'you are running from the repo, so no download is needed');
     info(`source: ${localZip}`);
     return { zipPath: localZip, downloaded: false };
@@ -326,7 +358,7 @@ async function obtainBundle(release) {
   const downloadUrl = (release && release.url) || fallbackUrl(RELEASE_VERSION);
   step(
     `Downloading the brain (${APPROX_SIZE})`,
-    'the brain is the embedded source of 20+ RuvNet repos — too big for git, so it ships as a Release',
+    'the brain embeds source from dozens of RuvNet repos — too big for git, so it ships as a Release',
   );
   info(`version: ${c.bold((release && release.tag) || RELEASE_VERSION)}`);
   info(`from: ${downloadUrl}`);
@@ -365,50 +397,99 @@ async function obtainBundle(release) {
 }
 
 // ── step: unzip into the cache dir (flattening the top-level ruvnet-brain/ folder) ───────────────
-function unzipInto(zipPath, cacheDir) {
+//
+// EXTRACTION IS NO LONGER GATED ON AN EXTERNAL BINARY (stranger-matrix, windows cells).
+// The old code shelled to `unzip`, with PowerShell's Expand-Archive only as a fallback when `unzip`
+// was ABSENT. That has two measured failure modes on a stranger's Windows machine:
+//   · windows-powershell: no `unzip` exists at all — the fallback carried the whole install.
+//   · windows-gitbash:    `unzip` IS on PATH (MSYS2 build), so the fallback never engaged, and the
+//                         call died — `unzip -q -o D:\a\_temp\...\ruvnet-brain.zip -d D:\a\...`
+//                         exited 1. Windows spawns go through `shell: true` here (mandatory, for
+//                         .cmd shims), so native backslash paths reach a POSIX-ish tool that treats
+//                         `\` as an escape. A path handed to a shell must be correct for THAT shell.
+// The fix is to stop involving a shell: kb/zip-extract.mjs reads the archive in-process with
+// node:zlib. Measured on macOS against a real `zip -r -y` archive, its output is byte-for-byte
+// identical to `unzip -q -o` (same tree, sizes, 0755/0644 modes, symlinks preserved).
+//
+// ORDER IS DELIBERATE, and the non-Windows default is UNCHANGED:
+//   non-win32 -> `unzip` first (byte-identical to every previous release), node:zlib as fallback
+//                so a slim container without unzip now installs instead of dying.
+//   win32     -> node:zlib first (no PATH lookup, no shell, no quoting), PowerShell second.
+// Every attempt is recorded and, if all of them fail, ALL are printed with the exact command and
+// exit code. The old message's best property — it named the precise failing command — is kept.
+export function copyLocalBundleInto(sourceDir, cacheDir) {
+  let copied = 0;
+  for (const entry of fs.readdirSync(sourceDir)) {
+    fs.cpSync(path.join(sourceDir, entry), path.join(cacheDir, entry), {
+      recursive: true,
+      force: true,
+      preserveTimestamps: true,
+    });
+    copied++;
+  }
+  return copied;
+}
+
+async function unzipInto(zipPath, cacheDir, sourceDir = null) {
   step(
     'Unpacking the brain into place',
     'so the plugin finds forge-mcp-all.mjs and the vector stores right where it looks',
   );
 
-  const hasUnzip = have('unzip');
-  // Windows fallback: PowerShell's Expand-Archive is available on all modern Windows systems.
-  const psExe = !hasUnzip ? (['pwsh', 'powershell'].find(have) || null) : null;
+  const localCopy = async () => `local directory copy — ${copyLocalBundleInto(sourceDir, cacheDir)} top-level entries`;
+  const nodeExtract = async () => {
+    const { extractZip } = await import(new URL('../kb/zip-extract.mjs', import.meta.url).href);
+    const r = await extractZip(zipPath, cacheDir);
+    return `node:zlib — ${r.files} files, ${(r.bytes / 1e6).toFixed(1)}MB${r.crcChecked ? ', CRC verified' : ''}`;
+  };
+  const unzipExtract = async () => {
+    if (!have('unzip')) throw new Error('`unzip` is not on PATH');
+    run('unzip', ['-q', '-o', zipPath, '-d', cacheDir]);
+    return 'unzip';
+  };
+  const psExtract = async () => {
+    // PowerShell's Expand-Archive handles .zip natively with -Force for overwrite.
+    // shell:false here (pwsh/powershell are real .exe files, not .cmd shims) — routing this
+    // through cmd.exe would re-tokenize the already-quoted -Command string and break it.
+    // -ExecutionPolicy Bypass: Expand-Archive ships as a script module (.psm1); on a locked-down
+    // machine (Restricted/AllSigned policy — common in sandboxes) importing it fails with
+    // "running scripts is disabled on this system" even though the exe itself runs fine. Bypass
+    // only affects this one child process, not any persistent machine setting.
+    const psExe = ['pwsh', 'powershell'].find(have);
+    if (!psExe) throw new Error('neither `pwsh` nor `powershell` is on PATH');
+    run(psExe, [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command',
+      `Expand-Archive -LiteralPath "${zipPath}" -DestinationPath "${cacheDir}" -Force`,
+    ], { shell: false });
+    return `${psExe} Expand-Archive`;
+  };
+
+  const strategies = sourceDir
+    ? [['local assembled directory', localCopy]]
+    : (IS_WIN
+        ? [['node:zlib (built-in)', nodeExtract], ['PowerShell Expand-Archive', psExtract]]
+        : [['unzip', unzipExtract], ['node:zlib (built-in)', nodeExtract]]);
 
-  if (!hasUnzip && !psExe) {
+  // The zip extracts to a top-level `ruvnet-brain/` folder. Extract into the cache dir, then lift
+  // its CONTENTS up one level so that cacheDir/forge-mcp-all.mjs exists (idempotent: overwrites).
+  const failures = [];
+  let extractedBy = null;
+  for (const [label, attempt] of strategies) {
+    try { extractedBy = await attempt(); break; }
+    catch (e) { failures.push(`  • ${label}: ${(e && e.message) || e}`); }
+  }
+  if (!extractedBy) {
     die(
-      `no zip extraction tool is available on this machine.`,
+      `extraction failed — every available method was tried and each one is reported below.\n${failures.join('\n')}`,
       [
-        `Install one and re-run:`,
-        `  • macOS:  \`unzip\` is already built in — check your PATH`,
-        `  • Debian/Ubuntu:  ${c.bold('sudo apt-get install -y unzip')}`,
-        `  • Fedora/RHEL:  ${c.bold('sudo dnf install -y unzip')}`,
-        `  • Windows:  open a PowerShell window and re-run (Expand-Archive is built in)`,
+        `The archive may be incomplete or corrupt — re-run to download a fresh copy.`,
+        `If it keeps failing, one of these gives the same job to a tool you control:`,
+        `  • macOS/Linux:  ${c.bold(`unzip -o "${zipPath}" -d "${cacheDir}"`)}`,
+        `  • Windows:  ${c.bold(`Expand-Archive -LiteralPath "${zipPath}" -DestinationPath "${cacheDir}" -Force`)}`,
       ].join('\n'),
     );
   }
-
-  // The zip extracts to a top-level `ruvnet-brain/` folder. Extract into the cache dir, then lift
-  // its CONTENTS up one level so that cacheDir/forge-mcp-all.mjs exists (idempotent: -o overwrites).
-  try {
-    if (hasUnzip) {
-      run('unzip', ['-q', '-o', zipPath, '-d', cacheDir]);
-    } else {
-      // Windows: PowerShell's Expand-Archive handles .zip natively with -Force for overwrite.
-      // shell:false here (pwsh/powershell are real .exe files, not .cmd shims) — routing this
-      // through cmd.exe would re-tokenize the already-quoted -Command string and break it.
-      // -ExecutionPolicy Bypass: Expand-Archive ships as a script module (.psm1); on a locked-down
-      // machine (Restricted/AllSigned policy — common in sandboxes) importing it fails with
-      // "running scripts is disabled on this system" even though the exe itself runs fine. Bypass
-      // only affects this one child process, not any persistent machine setting.
-      run(psExe, [
-        '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command',
-        `Expand-Archive -LiteralPath "${zipPath}" -DestinationPath "${cacheDir}" -Force`,
-      ], { shell: false });
-    }
-  } catch (e) {
-    die(`extraction failed (${e.message}).`, `The archive may be incomplete — re-run to download a fresh copy.`);
-  }
+  if (failures.length) warn(`extracted via ${extractedBy} after ${failures.length} method(s) failed:\n${failures.join('\n')}`);
 
   const nested = path.join(cacheDir, 'ruvnet-brain');
   if (fs.existsSync(path.join(nested, 'forge-mcp-all.mjs'))) {
@@ -421,6 +502,16 @@ function unzipInto(zipPath, cacheDir) {
     fs.rmdirSync(nested);
   }
 
+  // An update is a replacement, not an overlay. Before this prune existed, installing a public
+  // bundle over a KB that once contained private stores left every omitted `.rvf` and passages file
+  // behind. discoverRepos() then served those stale stores as if they were part of the new bundle.
+  // Only repo-artifact families are touched; reader deps, local logs, preferences, and unrelated
+  // files remain byte-for-byte.
+  const pruned = pruneUnlistedStores(cacheDir);
+  if (pruned.length) {
+    warn(`pruned ${pruned.length} stale repo artifact file(s) omitted by this bundle: ${[...new Set(pruned.map((p) => p.repo))].join(', ')}`);
+  }
+
   if (!fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs'))) {
     die(
       `the brain unpacked but forge-mcp-all.mjs is missing from ${cacheDir}.`,
@@ -430,6 +521,40 @@ function unzipInto(zipPath, cacheDir) {
   ok(`brain unpacked to ${cacheDir}`);
 }
 
+export function pruneUnlistedStores(cacheDir) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(cacheDir, 'manifest.json'), 'utf8'));
+    const allowed = new Set((manifest.builtRepos || []).map((r) => String(r?.name || '')).filter(Boolean));
+    if (manifest.conceptsStore?.store) allowed.add(String(manifest.conceptsStore.store).replace(/\.big\.rvf$|\.rvf$/, ''));
+    // ruv-gists is a separately assembled provenance store, not a registry builtRepo.
+    if (fs.existsSync(path.join(cacheDir, 'ruv-gists.rvf')) || fs.existsSync(path.join(cacheDir, 'ruv-gists.big.rvf'))) {
+      allowed.add('ruv-gists');
+    }
+    if (!allowed.size) return [];
+
+    const presentRepos = new Set();
+    for (const entry of fs.readdirSync(cacheDir)) {
+      const m = /^(.*?)(?:\.big)?\.rvf$/.exec(entry);
+      if (m?.[1] && /^[A-Za-z0-9._-]+$/.test(m[1])) presentRepos.add(m[1]);
+      const primer = /^(.*)-primer\.md$/.exec(entry);
+      if (primer?.[1] && /^[A-Za-z0-9._-]+$/.test(primer[1])) presentRepos.add(primer[1]);
+    }
+    const stale = [...presentRepos].filter((repo) => !allowed.has(repo));
+    const removed = [];
+    for (const repo of stale) {
+      for (const entry of fs.readdirSync(cacheDir)) {
+        if (entry !== repo && entry !== `${repo}-primer.md` && !entry.startsWith(`${repo}.`)) continue;
+        fs.rmSync(path.join(cacheDir, entry), { recursive: true, force: true });
+        removed.push({ repo, entry });
+      }
+    }
+    return removed;
+  } catch {
+    // A missing/corrupt manifest is already a verification failure. Never guess what to delete.
+    return [];
+  }
+}
+
 // ── step: install the reader deps ────────────────────────────────────────────────────────────────
 function installReader(cacheDir) {
   step(
@@ -557,14 +682,16 @@ function wirePlugin() {
 //      it and touch nothing. Their hand-written config outranks our convenience.
 //
 // The registered path must also OUTLIVE the install. The npx checkout is ephemeral (the same reason
-// the spend watchdog and the router tools get copied under ~/.claude), and plugin/mcp/server.mjs is
-// self-contained — node builtins only — so it is copied to a persistent home and THAT absolute path
-// is what gets registered. Registering the npx dir would rot the moment the temp dir vanished.
+// the spend watchdog and the router tools get copied under ~/.claude). The MCP shell and its one
+// local structured-interface module use node builtins only; both are copied to a persistent home and
+// THAT absolute server path is registered. Registering the npx dir would rot when the temp dir vanished.
 const CODEX_BLOCK_START = '# --- ruvnet-brain (managed block, installer-rewritten) ---';
 const CODEX_BLOCK_END = '# --- end ruvnet-brain ---';
 const codexHomeDir = () => path.join(os.homedir(), '.codex');
 const codexConfigPath = () => path.join(codexHomeDir(), 'config.toml');
 const codexServerDir = () => path.join(os.homedir(), '.claude', 'ruvnet-brain', 'mcp');
+const codexHookWrapperPath = (codexDir = codexHomeDir()) =>
+  path.join(path.dirname(codexDir), '.cache', 'ruvnet-brain', 'codex-hook.mjs');
 
 // The exact bytes we own. Kept in one place so the writer and the doctor probe can never disagree.
 function codexManagedBlock(serverPath) {
@@ -645,6 +772,8 @@ export function wireCodexHost({
   configPath = path.join(codexDir, 'config.toml'),
   serverDir = codexServerDir(),
   source = path.join(__dirname, '..', 'plugin', 'mcp', 'server.mjs'),
+  hookWrapperSource = path.join(__dirname, '..', 'plugin', 'scripts', 'codex-hook-wrapper.mjs'),
+  hookWrapperPath = codexHookWrapperPath(codexDir),
   announce = true,
 } = {}) {
   let host = false;
@@ -659,12 +788,25 @@ export function wireCodexHost({
     if (announce) warn('MCP server missing from this bundle — Codex left untouched (non-fatal)');
     return { host: true, action: 'no-source' };
   }
+  const managedCliSource = path.join(path.dirname(source), 'managed-cli-interface.mjs');
+  if (!fs.existsSync(managedCliSource)) {
+    if (announce) warn('MCP structured-interface module missing from this bundle — Codex left untouched (non-fatal)');
+    return { host: true, action: 'no-source' };
+  }
   const serverPath = path.join(serverDir, 'server.mjs');
+  const managedCliPath = path.join(serverDir, 'managed-cli-interface.mjs');
   fs.mkdirSync(serverDir, { recursive: true });
   // Write-beside-then-rename, both here and for the config below (issue #43): an interrupted plain
   // copy leaves a TORN server.mjs at the exact path a prior install's config already points at, so
   // Codex spawns half a file. rename() over the target is atomic; a failure leaves the old bytes.
+  // Copy the dependency first. If the later server swap fails, the previously registered server
+  // remains byte-intact and continues to import a backward-compatible module at the same path.
+  atomicReplace(managedCliPath, (tmp) => fs.copyFileSync(managedCliSource, tmp));
   atomicReplace(serverPath, (tmp) => fs.copyFileSync(source, tmp));
+  if (fs.existsSync(hookWrapperSource)) {
+    fs.mkdirSync(path.dirname(hookWrapperPath), { recursive: true });
+    atomicReplace(hookWrapperPath, (tmp) => fs.copyFileSync(hookWrapperSource, tmp));
+  }
 
   let before = '';
   try { before = fs.readFileSync(configPath, 'utf8'); } catch { /* first run — no config yet */ }
@@ -674,7 +816,7 @@ export function wireCodexHost({
       ok('Codex already declares ruvnet-brain in your own config — left exactly as you wrote it');
       info(`  to hand it to us instead, delete that ${c.bold('[mcp_servers.ruvnet-brain]')} block and re-run this installer`);
     }
-    return { host: true, action, serverPath };
+    return { host: true, action, serverPath, managedCliPath, hookWrapperPath };
   }
   if (text !== before) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -685,7 +827,253 @@ export function wireCodexHost({
     info(`  server: ${serverPath} ${c.dim('(persistent copy — the npx dir vanishes)')}`);
     info(`  ${c.dim('only our marked block is written; every other section is byte-preserved')}`);
   }
-  return { host: true, action, serverPath, changed: text !== before };
+  return { host: true, action, serverPath, managedCliPath, hookWrapperPath, changed: text !== before };
+}
+
+const CODEX_PLUGIN_ID = 'ruvnet-brain@ruvnet-brain';
+const CODEX_MARKETPLACE = 'ruvnet-brain';
+const CODEX_MARKETPLACE_SOURCE = 'stuinfla/ruvnet-brain';
+
+// Codex 0.145 returns `{ marketplaces: [...] }`; early preview builds returned the array itself.
+// Keep both shapes so an installer update never turns a harmless host-version difference into a
+// repeated "marketplace already exists" failure.
+export function codexMarketplaceRows(value) {
+  if (Array.isArray(value?.marketplaces)) return value.marketplaces;
+  return Array.isArray(value) ? value : [];
+}
+
+function runCodexJson(args, {
+  codexBin = process.env.CODEX_BIN || 'codex',
+  codexHome = codexHomeDir(),
+  cwd = process.cwd(),
+} = {}) {
+  const r = spawnSync(codexBin, args, {
+    cwd,
+    env: { ...process.env, CODEX_HOME: codexHome },
+    encoding: 'utf8',
+    timeout: 30_000,
+    maxBuffer: 20 * 1024 * 1024,
+  });
+  if (r.error || r.status !== 0) {
+    const detail = String(r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim();
+    return { ok: false, error: detail };
+  }
+  try { return { ok: true, value: JSON.parse(r.stdout || 'null') }; }
+  catch { return { ok: false, error: `Codex returned non-JSON output for ${args.join(' ')}` }; }
+}
+
+export function codexPluginStatus(options = {}) {
+  const { runJson = runCodexJson, ...commandOptions } = options;
+  const listed = runJson(['plugin', 'list', '--json'], commandOptions);
+  if (!listed.ok) return { available: false, installed: false, enabled: false, error: listed.error };
+  const rows = Array.isArray(listed.value?.installed) ? listed.value.installed : [];
+  const row = rows.find((candidate) => candidate?.pluginId === CODEX_PLUGIN_ID);
+  return {
+    available: true,
+    installed: Boolean(row?.installed),
+    enabled: Boolean(row?.enabled),
+    version: row?.version || null,
+    row: row || null,
+  };
+}
+
+export function wireCodexPlugin({
+  codexDir = codexHomeDir(),
+  codexHome = codexDir,
+  codexBin = process.env.CODEX_BIN || 'codex',
+  marketplaceSource = CODEX_MARKETPLACE_SOURCE,
+  expectedVersion = PACKAGE_VERSION,
+  cwd = process.cwd(),
+  announce = true,
+  runJson = runCodexJson,
+} = {}) {
+  if (!fs.existsSync(codexDir)) return { host: false, action: 'no-host' };
+  const options = { codexBin, codexHome, cwd };
+  const before = codexPluginStatus({ ...options, runJson });
+  if (!before.available) {
+    if (announce) warn(`Codex plugin lifecycle not installed — ${before.error}`);
+    return { host: true, action: 'codex-unavailable', ...before };
+  }
+  if (before.installed && !before.enabled) {
+    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 };
+  }
+  if (before.installed && before.enabled && (!expectedVersion || 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 };
+  }
+
+  const markets = runJson(['plugin', 'marketplace', 'list', '--json'], options);
+  if (!markets.ok) {
+    if (announce) warn(`Codex marketplace check failed — ${markets.error}`);
+    return { host: true, action: 'marketplace-check-failed', error: markets.error };
+  }
+  const marketRows = codexMarketplaceRows(markets.value);
+  const known = marketRows.some((market) => market?.name === CODEX_MARKETPLACE);
+  const marketAction = known
+    ? runJson(['plugin', 'marketplace', 'upgrade', CODEX_MARKETPLACE, '--json'], options)
+    : runJson(['plugin', 'marketplace', 'add', marketplaceSource, '--json'], options);
+  if (!marketAction.ok) {
+    if (announce) warn(`Codex marketplace ${known ? 'upgrade' : 'add'} failed — ${marketAction.error}`);
+    return { host: true, action: 'marketplace-failed', error: marketAction.error };
+  }
+  const added = runJson(['plugin', 'add', CODEX_PLUGIN_ID, '--json'], options);
+  if (!added.ok) {
+    if (announce) warn(`Codex plugin install failed — ${added.error}. The prior MCP registration remains intact.`);
+    return { host: true, action: 'plugin-failed', error: added.error };
+  }
+  const after = codexPluginStatus({ ...options, runJson });
+  if (!after.installed || !after.enabled) {
+    if (announce) warn('Codex accepted the install command but the Brain plugin is not installed and enabled.');
+    return { host: true, action: 'verification-failed', ...after };
+  }
+  if (announce) {
+    ok(`Codex Brain plugin installed and enabled (${after.version || 'version unknown'}).`);
+  }
+  return { host: true, action: before.installed ? 'updated' : 'installed', ...after };
+}
+
+function codexHooksList({
+  codexBin = process.env.CODEX_BIN || 'codex',
+  codexHome = codexHomeDir(),
+  cwd = process.cwd(),
+  timeoutMs = 8_000,
+} = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let buffer = '';
+    let stderr = '';
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child.kill(); } catch { /* already exited */ }
+      resolve(value);
+    };
+    const child = spawn(codexBin, ['app-server'], {
+      cwd,
+      env: { ...process.env, CODEX_HOME: codexHome },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const timer = setTimeout(() => finish({ ok: false, error: `Codex hooks probe timed out after ${timeoutMs}ms` }), timeoutMs);
+    child.on('error', (error) => finish({ ok: false, error: error.message }));
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.stdout.on('data', (chunk) => {
+      buffer += String(chunk);
+      let newline;
+      while ((newline = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { continue; }
+        if (message.id === 1) {
+          child.stdin.write(`${JSON.stringify({ method: 'initialized' })}\n`);
+          child.stdin.write(`${JSON.stringify({ method: 'hooks/list', id: 2, params: { cwds: [cwd] } })}\n`);
+        } else if (message.id === 2) {
+          finish(message.error
+            ? { ok: false, error: message.error.message || JSON.stringify(message.error) }
+            : { ok: true, value: message.result });
+        }
+      }
+    });
+    child.on('exit', (code) => {
+      if (!settled) finish({ ok: false, error: stderr.trim() || `Codex app-server exited ${code} before hooks/list` });
+    });
+    child.stdin.write(`${JSON.stringify({
+      method: 'initialize',
+      id: 1,
+      params: { clientInfo: { name: 'ruvnet_brain_doctor', title: 'RuvNet Brain Doctor', version: PACKAGE_VERSION || '0' } },
+    })}\n`);
+  });
+}
+
+export function classifyCodexLifecycle(plugin, listed = null) {
+  if (!plugin.available) return { state: 'probe-failed', plugin, hooks: [], error: plugin.error };
+  if (!plugin.installed) return { state: 'not-installed', plugin, hooks: [] };
+  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 : [])
+    .filter((hook) => hook?.pluginId === CODEX_PLUGIN_ID);
+  const errors = groups.flatMap((group) => Array.isArray(group?.errors) ? group.errors : []);
+  if (errors.length || hooks.length === 0) {
+    return { state: 'missing-runtime-hooks', plugin, hooks, errors };
+  }
+  if (hooks.some((hook) => hook.enabled === false)) return { state: 'disabled', plugin, hooks, errors };
+  if (hooks.every((hook) => hook.trustStatus === 'trusted')) return { state: 'active', plugin, hooks, errors };
+  return { state: 'pending-trust', plugin, hooks, errors };
+}
+
+export async function codexLifecycleStatus(options = {}) {
+  const plugin = codexPluginStatus(options);
+  if (!plugin.available || !plugin.installed || !plugin.enabled) {
+    return classifyCodexLifecycle(plugin);
+  }
+  return classifyCodexLifecycle(plugin, await codexHooksList(options));
+}
+
+export function codexLifecycleGuidance(status) {
+  const hookCount = Array.isArray(status?.hooks) ? status.hooks.length : 0;
+  switch (status?.state) {
+    case 'active':
+      return {
+        healthy: true,
+        intentional: false,
+        summary: `Codex lifecycle active (${hookCount} Brain hook${hookCount === 1 ? '' : 's'} enabled and trusted).`,
+        detail: 'Proactive grounding, routing, learning capture, and session continuity are on.',
+        action: null,
+      };
+    case 'pending-trust':
+      return {
+        healthy: false,
+        intentional: false,
+        summary: `Codex installed the Brain, but ${hookCount || 'its'} lifecycle hook${hookCount === 1 ? '' : 's'} await review.`,
+        detail: 'Search works now; proactive interventions start after Codex records hook trust.',
+        action: `Start a fresh Codex session, run /hooks, and trust only ${CODEX_PLUGIN_ID}.`,
+      };
+    case 'disabled':
+      return {
+        healthy: false,
+        intentional: true,
+        summary: 'Codex Brain lifecycle is disabled.',
+        detail: 'The installer preserved your explicit disabled state instead of silently overriding it.',
+        action: null,
+      };
+    case 'not-installed':
+      return {
+        healthy: false,
+        intentional: false,
+        summary: 'Codex can reach the Brain MCP, but the proactive lifecycle plugin is not installed.',
+        detail: 'Questions can still be grounded; automatic routing, learning, and session guidance are inactive.',
+        action: 'Run npx ruvnet-brain to install and verify the Codex lifecycle plugin.',
+      };
+    case 'missing-runtime-hooks':
+      return {
+        healthy: false,
+        intentional: false,
+        summary: 'Codex has the Brain plugin, but its runtime hooks are missing or invalid.',
+        detail: Array.isArray(status?.errors) && status.errors.length
+          ? status.errors.map(String).join('; ')
+          : 'The installed plugin snapshot did not produce runnable lifecycle definitions.',
+        action: `Run codex plugin marketplace upgrade ${CODEX_MARKETPLACE}, then npx ruvnet-brain.`,
+      };
+    default:
+      return {
+        healthy: false,
+        intentional: false,
+        summary: 'Codex lifecycle status could not be verified.',
+        detail: status?.error || 'Codex did not return a lifecycle status.',
+        action: 'Run npx ruvnet-brain --doctor after confirming codex is on PATH.',
+      };
+  }
+}
+
+function printCodexLifecycle(status) {
+  const guidance = codexLifecycleGuidance(status);
+  console.log(`  ${guidance.healthy ? c.green('✓') : guidance.intentional ? c.dim('○') : c.yellow('!')} ${guidance.summary}`);
+  if (guidance.detail) console.log(`    ${guidance.detail}`);
+  if (guidance.action) console.log(`    ${c.bold(`Fix: ${guidance.action}`)}`);
+  return guidance;
 }
 
 // ── step: verify the install is REAL (counts — never take "installed" on faith) ──────────────────
@@ -768,6 +1156,12 @@ async function loadCitationVerifier(cacheDir) {
 // real, indexed passage on this disk. The old check here tested `/rvf|ruvector|hnsw/` against the
 // answer text, which a hallucinated "just use RVF!" passes with zero sources. Keyword presence is
 // not evidence. We now print the cited path as a receipt, so you can go look at it yourself.
+export function resolveRuntimeModelCache(env = process.env, home = os.homedir()) {
+  if (env.KB_MODEL_CACHE) return env.KB_MODEL_CACHE;
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
+  return path.join(brainHome, 'models');
+}
+
 async function smokeQuery(cacheDir) {
   const ask = path.join(cacheDir, 'forge-ask-all.mjs');
   if (!fs.existsSync(ask)) return { ran: false };
@@ -790,7 +1184,10 @@ async function smokeQuery(cacheDir) {
       cwd: cacheDir,
       encoding: 'utf8',
       timeout: 240000,
-      env: process.env,
+      // The stable MCP shell sets this exact default before spawning its worker. Passing the same
+      // path here makes the install smoke warm the model cache the product will actually reopen,
+      // instead of a second kb-local cache that can go green while the real door stays cold.
+      env: { ...process.env, KB_MODEL_CACHE: resolveRuntimeModelCache() },
     });
   } catch {
     warn("skipped the live test (couldn't launch the reader) — it'll warm on your first real question");
@@ -934,7 +1331,13 @@ async function runDemo() {
         console.log(`  ${line}`);
       }
     }
-  } catch { /* informational only — never break an install */ }
+  } catch (e) {
+    // REPORT, never swallow. A bare `catch {}` here is how this block stayed dead: install-scope.mjs
+    // was missing from package.json `files[]`, so on every real npm install the import threw
+    // MODULE_NOT_FOUND and the empty catch made that indistinguishable from "nothing to say". Both
+    // halves are fixed — it ships now, and if it ever stops shipping, this line says so out loud.
+    warn(`scope explainer could not run (${e && e.message}) — the setup summary was skipped`);
+  }
 
   try {
     const { shouldNotify, noticeFor } = await import(new URL('../scripts/upgrade-notice.mjs', import.meta.url).href);
@@ -988,6 +1391,16 @@ function meterSummaryLine() {
 }
 
 // ── `--doctor`: a standalone health check the user can run any time ───────────────────────────────
+//
+// EXIT CODES ARE THE POINT (the 40/100 finding). Before this, doctor() printed "! Needs attention."
+// on an install with zero stores and no reader, then returned `undefined` — so:
+//
+//     $ npx ruvnet-brain --doctor >/dev/null 2>&1; echo $?
+//     0
+//
+// Honest prose that no machine can read is not a check. It could not gate a CI job, a nightly probe,
+// or a `&&` in someone's shell. It now RETURNS a verdict and main() exits with it, so "needs
+// attention" and "success" can never again be the same thing to a script.
 async function doctor() {
   printBanner('doctor');
   console.log(c.dim('Checking every part of the install and reporting green/red.\n'));
@@ -996,7 +1409,7 @@ async function doctor() {
   const present = fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs'));
   if (!present) {
     warn('brain not found here — run the installer first:  npx ruvnet-brain');
-    return;
+    return 1; // "not installed" is a FAILING doctor, not a neutral one
   }
   have('node') ? ok('node present') : warn('node missing');
   have('npm') ? ok('npm present') : warn('npm missing');
@@ -1004,9 +1417,17 @@ async function doctor() {
   // Two independent version streams (KB bundle vs plugin wrapper) — see checkVersionDrift()'s
   // header comment for the full story. Silent unless they've genuinely diverged.
   reportVersionDrift(cacheDir);
-  have('unzip') || have('pwsh') || have('powershell')
-    ? ok('zip extraction available (unzip or PowerShell Expand-Archive)')
-    : warn('no zip tool found — unzip or PowerShell needed for re-install');
+  // Extraction no longer needs an external binary at all — kb/zip-extract.mjs does it with node:zlib
+  // (see unzipInto()). So this reports the file's PRESENCE, not a PATH lookup: if it is missing from
+  // the install, extraction on Windows silently loses its primary method, which is exactly the class
+  // of "shipped, never actually there" gap tests/unit/installer-sibling-imports-packaged.test.mjs
+  // exists to catch. Naming the external tools too, because they are still the fallback/primary
+  // depending on platform.
+  fs.existsSync(fileURLToPath(new URL('../kb/zip-extract.mjs', import.meta.url)))
+    ? ok(`zip extraction available (built-in node:zlib${have('unzip') ? ' + unzip' : ''}${have('pwsh') || have('powershell') ? ' + PowerShell Expand-Archive' : ''})`)
+    : (have('unzip') || have('pwsh') || have('powershell')
+      ? warn('built-in extractor kb/zip-extract.mjs is MISSING from this install — falling back to an external tool')
+      : warn('no zip extraction available: kb/zip-extract.mjs missing AND no unzip/PowerShell on PATH'));
   have('git')
     ? ok('git present (not required by this installer, but handy)')
     : info('git not found — that\'s fine, this installer never needs it');
@@ -1022,17 +1443,30 @@ async function doctor() {
   // pull used to hang FOREVER. Diagnose the condition here, explicitly and in 3 seconds flat: if the
   // model host is unreachable AND no local model cache exists, the first query needs the network and
   // will fail loud (bounded by RUVNET_BRAIN_FETCH_TIMEOUT_MS) — tell the user BEFORE they hit it.
-  const modelCacheDir = process.env.KB_MODEL_CACHE || path.join(cacheDir, 'models-cache');
-  const haveLocalModel = fs.existsSync(path.join(modelCacheDir, 'Xenova', 'all-MiniLM-L6-v2'))
-    || fs.existsSync(path.join(modelCacheDir, 'Xenova/all-MiniLM-L6-v2'));
+  // ONE CACHE, NOT TWO (2026-07-27). This defaulted to `<cacheDir>/models-cache` — and cacheDir is
+  // `~/.cache/ruvnet-brain/KB` (note the /kb) — while the RUNTIME
+  // reads `<BRAIN_HOME>/models` (plugin/mcp/server.mjs:99, mirrored by plugin/test/model-cache.mjs:36).
+  // So the installer verified — and warmed — a directory the product never opens.
+  //
+  // MEASURED ON THIS MACHINE, which is how it was found: `<cacheDir>/models-cache` DID NOT EXIST at
+  // all, while `<BRAIN_HOME>/models` held 23MB containing ONLY the ms-marco reranker — the bge-base
+  // EMBEDDER, the model every query needs first, was absent (0 files). That is the 53s cold start:
+  // every cold query re-fetches the embedder because install warmed the wrong path, and it is why
+  // search_ruvnet timed out twice in one session. A smoke test that passes against a cache the
+  // runtime never reads proves nothing about the runtime — the D8 deduction, in one line of path.
+  const modelCacheDir = resolveRuntimeModelCache();
+  const requiredModels = requiredEmbedderModels(cacheDir);
+  const missingModels = missingEmbedderModels(modelCacheDir, requiredModels);
+  const haveLocalModel = missingModels.length === 0;
   try {
     await fetch('https://huggingface.co', { method: 'HEAD', signal: AbortSignal.timeout(3000) });
     ok('model host reachable (huggingface.co) — cold-cache model download would work');
   } catch {
     if (haveLocalModel) {
-      ok(`model host UNREACHABLE, but the embedder is already cached locally (${modelCacheDir}) — queries work offline`);
+      ok(`model host UNREACHABLE, but every required embedder is cached locally (${modelCacheDir}) — queries work offline`);
     } else {
       warn('network-restricted environment detected: huggingface.co unreachable (3s probe) AND no local model cache.');
+      warn(`  Missing query model(s): ${missingModels.join(', ')}`);
       warn(`  The first query needs the embedder model once. Fix: on a networked machine run one query, then copy`);
       warn(`  its model cache to this machine and set KB_MODEL_CACHE to that path. (Queries fail loud, not hang.)`);
     }
@@ -1062,10 +1496,13 @@ async function doctor() {
   // from disk (our entry present AND the server.mjs it names really there), never asserted from the
   // fact that an install once ran.
   const cx = codexStatus();
+  let codexLifecycle = null;
   if (!cx.host) {
     console.log(`  ${c.dim('Codex: no host detected (no ~/.codex) — nothing to wire.')}`);
   } else if (cx.wired) {
     console.log(`  ${c.green('✓ Codex: wired.')} search_ruvnet is registered in ~/.codex/config.toml and its server exists.`);
+    codexLifecycle = await codexLifecycleStatus();
+    printCodexLifecycle(codexLifecycle);
   } else {
     console.log(`  ${c.yellow('! Codex: host detected but NOT wired')}${
       cx.serverPath && !cx.serverExists ? ` — registered server is missing (${cx.serverPath})` : ' — no [mcp_servers.ruvnet-brain] entry'
@@ -1094,6 +1531,79 @@ async function doctor() {
   console.log(
     c.dim('\n  Heads-up: a window that was ALREADY open when you installed needs a restart to pick it up;\n  newly-opened windows are fine.\n'),
   );
+
+  // ── THE MECHANICAL VERDICT ────────────────────────────────────────────────────────────────────
+  // `--hooks` additionally fires every registration in the INSTALLED hooks.json through the real
+  // shim under the four stdin regimes. Opt-in because it spawns real hooks; plain --doctor stays a
+  // pure read that anyone can run without side effects.
+  let hookResult = null;
+  if (FLAG_HOOKS) {
+    console.log(`  ${c.dim('── hook battery (installed hooks.json, four stdin regimes, external watchdog) ──')}`);
+    hookResult = await runSelfCheck({ installState: { repos: v.repos, reader: v.reader, mcp: v.mcp } });
+  }
+
+  // ── THE PERSISTED GROUNDING VERDICT (ADR-058 §D8) — read-only, never re-derived here ────────────
+  // bin/install.mjs's own install run is the ONLY writer (right after its real smoke query), so a
+  // failed smoke stays non-fatal there. `--doctor` is different: it is the command someone runs
+  // SPECIFICALLY TO ASK whether the install is healthy, so this is the one place an unresolved
+  // "unproven" verdict DOES gate the exit code — without doctor() re-running a second live query
+  // (the live smoke result printed above already updates the SAME file the next real install or
+  // search_ruvnet touches; this just reads back whatever the most recent real attempt recorded).
+  let groundingUnprovenPersisted = false;
+  try {
+    const mod = await import(new URL('../scripts/selfcheck.mjs', import.meta.url).href);
+    groundingUnprovenPersisted = mod.groundingUnproven(mod.readInstallState());
+    if (groundingUnprovenPersisted) {
+      console.log(`  ${c.yellow('! Grounding UNPROVEN')} (recorded at ${c.bold(mod.installStatePath())}).`);
+      console.log(`    This is what makes ${c.bold('--doctor')} fail here even though nothing above crashed — re-run`);
+      console.log(`    ${c.bold('npx ruvnet-brain')} once you're online, or ask a real question, to clear it.`);
+    }
+  } catch { /* selfcheck.mjs unavailable — degrade to the live smoke signal already printed above */ }
+
+  // Without --hooks the verdict is the install-state check the old code already computed and threw
+  // away, PLUS the persisted grounding verdict above. `allGreen` was RIGHT here all along; nothing
+  // ever read it.
+  const codexLifecycleFailed = Boolean(
+    codexLifecycle
+    && !codexLifecycleGuidance(codexLifecycle).healthy
+    && !codexLifecycleGuidance(codexLifecycle).intentional,
+  );
+  const failed = (hookResult ? hookResult.exitCode !== 0 : !allGreen)
+    || groundingUnprovenPersisted
+    || codexLifecycleFailed;
+  if (failed && !hookResult && !groundingUnprovenPersisted) {
+    console.log(`  ${c.red('✗ FAILING')} — the warnings above are real. Re-run  ${c.bold('npx ruvnet-brain')}  to repair.`);
+  }
+  return failed ? 1 : 0;
+}
+
+// ── the post-install self-check, wired for both --doctor --hooks and the installer's last step ────
+//
+// Loaded dynamically and failing SOFT on a load error: bin/install.mjs is the one file that runs
+// before anything is installed, so it must survive a partial/odd delivery rather than crash. A load
+// failure is REPORTED, never silently swallowed — a self-check that quietly does not run is exactly
+// the 40/100 finding again.
+//
+// THE COMMENT THAT USED TO BE HERE SAID "scripts/selfcheck.mjs is shipped in package.json `files`".
+// It was not. Checked with `npm pack --dry-run` on 2026-07-27, one day after this block merged under
+// the headline "the installer can finally FAIL": the tarball carried 21 entries and selfcheck.mjs was
+// not among them, so on every real npm install this import threw and the installer could NOT fail.
+// The same comment correctly identified install-scope.mjs as having that exact defect and deferred
+// fixing it — while asserting from intent, not from `npm pack`, that its own dependency was fine.
+// All three of install.mjs's dynamic imports are in `files[]` now, and
+// tests/integration/pack-completeness.test.mjs derives the list from this file instead of trusting a
+// sentence about it.
+async function runSelfCheck({ installState = null, quiet = false } = {}) {
+  let mod;
+  try {
+    mod = await import(new URL('../scripts/selfcheck.mjs', import.meta.url).href);
+  } catch (e) {
+    warn(`self-check could not run (${e && e.message}) — this install has NOT been verified end to end`);
+    return { exitCode: 0, violations: [], lines: [], unavailable: true };
+  }
+  const result = await mod.selfCheck({ installState, security: true });
+  if (!quiet || result.violations.length) console.log(mod.formatVerdict(result, { color: c }));
+  return result;
 }
 
 // ── `--feedback`: the easiest possible way to tell us how it went ────────────────────────────────
@@ -1923,7 +2433,7 @@ export async function offerRouterProfile() {
   // invisible; without the VIEWER, the user has no scoreboard to hold it to. Shipping one without the
   // other is how a router ends up "working" with three test pings in its log and nobody the wiser.
   // (dispatch-receipt.mjs relative-imports route-cheap.mjs — they land in the same bin/ dir, so it resolves.)
-  for (const t of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'codex-routed.sh']) {
+  for (const t of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'subscription-hosts.mjs', 'dual-host-deliberation.mjs', 'dual-host-suggest.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'codex-routed.sh']) {
     const s = path.join(pkgRoot, 'scripts', t);
     if (fs.existsSync(s)) { fs.copyFileSync(s, path.join(routerDir, 'bin', t)); copied++; }
   }
@@ -2572,7 +3082,10 @@ export async function offerClaudeMd() {
 // sitting under the <50ms budget and blowing past it on every single prompt. `.cjs` forces
 // CommonJS unambiguously regardless of any stray package.json a user's HOME might contain.
 const STATUSLINE_HELPER_NAME = 'ruvnet-brain-statusline.cjs';
-const statuslineHelperPath = () => path.join(telemetryStateDir(), STATUSLINE_HELPER_NAME);
+// Exported (ADR-058 D5): the coexistence suite reconstructs the exact "ours" command string under
+// an overridden HOME, so the settings.json byte-preservation claim is measured against the real
+// path computation rather than a hand-copied guess.
+export const statuslineHelperPath = () => path.join(telemetryStateDir(), STATUSLINE_HELPER_NAME);
 const statuslinePrefPath = () => path.join(telemetryStateDir(), '.statusline-pref');
 const settingsJsonPath = () => path.join(os.homedir(), '.claude', 'settings.json');
 
@@ -2637,7 +3150,10 @@ function backupSettingsJson(settingsPath) {
   return backup;
 }
 
-function writeSettingsStatusLine(detected, command) {
+// Exported (ADR-058 D5): same testability contract as wireCodexHost — the coexistence suite calls
+// this directly against a scratch settings.json rather than reaching for the CLI, so the invariant
+// under test is the real write path, never a reimplementation of it.
+export function writeSettingsStatusLine(detected, command) {
   const backup = detected.exists ? backupSettingsJson(detected.path) : null;
   const next = { ...(detected.json || {}), statusLine: { type: 'command', command } };
   fs.mkdirSync(path.dirname(detected.path), { recursive: true });
@@ -2651,7 +3167,9 @@ function writeSettingsStatusLine(detected, command) {
 // machineFootprint() comment this replaces) so a status line the user has since folded their own
 // script into, or edited by hand, is left completely alone. Same "refuse rather than guess"
 // discipline removeClaudeMdBlock() already applies to CLAUDE.md, and the same backup-first courtesy.
-function removeSettingsStatusLine() {
+// Exported (ADR-058 D5): the uninstall-side mirror, made independently callable for the same
+// reason as writeSettingsStatusLine above.
+export function removeSettingsStatusLine() {
   const settingsPath = settingsJsonPath();
   const detected = detectStatusLine(settingsPath);
   if (!detected.exists || detected.parseError || !detected.hasStatusLine) return 'absent';
@@ -2765,13 +3283,24 @@ export async function offerStatusline() {
 }
 
 // ── final success block ──────────────────────────────────────────────────────────────────────────
+function installedRepoCount(cacheDir) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(cacheDir, 'manifest.json'), 'utf8'));
+    return Array.isArray(manifest.builtRepos) && manifest.builtRepos.length
+      ? String(manifest.builtRepos.length)
+      : 'dozens of';
+  } catch {
+    return 'dozens of';
+  }
+}
+
 function success({ cacheDir, isCustom, plugin, env, nightly }) {
   const line = '─'.repeat(64);
   console.log(`\n${c.green(line)}`);
   console.log(`${c.green(c.bold('  RuvNet Brain is installed.'))}`);
   console.log(`${c.green(line)}`);
   console.log(`\n  What you now have:`);
-  console.log(`    • the brain (embedded source of 20+ RuvNet repos) at:`);
+  console.log(`    • the brain (embedded source of ${installedRepoCount(cacheDir)} RuvNet repos) at:`);
   console.log(`        ${c.bold(cacheDir)}`);
   console.log(
     `    • the Claude Code plugin ${plugin.wired ? c.green('wired at user scope') : c.yellow('(finish the 2 commands above)')} — search_ruvnet + grounding hook`,
@@ -2853,7 +3382,16 @@ and falls back to a known-good version if GitHub can't be reached.
 Usage:
   npx ruvnet-brain                         Install the brain + Claude Code plugin (recommended, npm)
   npx github:stuinfla/ruvnet-brain         Same, but from the bleeding-edge GitHub commit
-  npx ruvnet-brain --doctor   Health-check an existing install (green/red per part)
+  npx ruvnet-brain --doctor   Health-check an existing install (green/red per part).
+                              EXITS NON-ZERO when the install is genuinely broken, so it can gate a
+                              script:  npx ruvnet-brain --doctor && ./deploy.sh
+  npx ruvnet-brain --doctor --hooks
+                              …and additionally fire every hook this plugin registered on THIS
+                              machine through the real shim under four stdin regimes (valid event
+                              JSON, empty EOF, 1MB garbage, and stdin held open past budget), with an
+                              external process-group watchdog. Asserts each hook's declared exit
+                              codes, a 4KB stdout cap, its declared timeout with margin, and zero
+                              surviving descendants. Your own hooks are listed, never executed.
   npx ruvnet-brain --demo     Guided walkthrough — 2 real questions, real cited answers
   npx ruvnet-brain --feedback Tell us how it went — prefills a GitHub Discussion with your brain
                               version, platform, and a 3-line health summary (you see exactly
@@ -2879,7 +3417,7 @@ Usage:
                               ~/.cache/ruvnet-brain/.telemetry-consent)
   node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.5.0-dev)
   node bin/install.mjs --pin               Skip the latest-check; use the bundled known-good version
-  node bin/install.mjs --local             Install from a repo clone's dist/ruvnet-brain.zip
+  node bin/install.mjs --local             Install from a repo clone's assembled dist/ruvnet-brain/
   node bin/install.mjs --force             Re-fetch and reinstall even if already present
   node bin/install.mjs --no-verify         Skip the post-install verify + warm-up smoke test
   node bin/install.mjs --with-stack        Also add missing Ruflo / RuVector (no prompt)
@@ -2893,7 +3431,10 @@ Usage:
   node bin/install.mjs --yes, -y           Accept every optional offer (good for scripted installs)
 
 Env:
-  RUVNET_BRAIN_KB   Override where the brain is stored (default ~/.cache/ruvnet-brain/kb)
+  RUVNET_BRAIN_KB       Override where the brain is stored (default ~/.cache/ruvnet-brain/kb)
+  RUVNET_STRICT_INSTALL Make an unproven grounding smoke FATAL (default: never — a first-run model
+                        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 installing, restart Claude Code so the grounding hook loads.
 `);
@@ -2903,7 +3444,10 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
 (async () => {
   if (IMPORT_ONLY) return; // imported for its exports (tests) — never run the installer as a side effect
   if (FLAG_HELP) return showHelp();
-  if (FLAG_DOCTOR) return await doctor();
+  // `process.exitCode`, not `return` — doctor()'s verdict is the whole point of running it in a
+  // script. A bare `return await doctor()` discarded the number, which is how "! Needs attention"
+  // and `echo $?` → 0 coexisted for so long.
+  if (FLAG_DOCTOR) { process.exitCode = await doctor(); return; }
   if (FLAG_DEMO) return runDemo();
   if (FLAG_FEEDBACK) return runFeedback();
   if (FLAG_UPDATE) return runUpdate();
@@ -3015,12 +3559,12 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
       info(`${c.dim('(the old installer skipped this whenever any brain was present, which is why stale installs never moved)')}`);
     }
     // Resolve which Release to fetch BEFORE downloading. Skipped entirely on the --local path
-    // (obtainBundle short-circuits to the repo's dist/ zip and never touches the network).
+    // (obtainBundle short-circuits to the repo's assembled dist/ directory and never touches the network).
     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 { zipPath, tmpDir, downloaded, sigError } = await obtainBundle(release);
+    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
     // bundle cannot also swap the key it is checked against).
@@ -3050,7 +3594,12 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
         ok(reason);
       }
     }
-    unzipInto(zipPath, cacheDir);
+    await unzipInto(zipPath, cacheDir, sourceDir);
+    const brainProfile = readBrainProfile();
+    if (brainProfile !== 'complete') {
+      const scoped = applyBrainProfile(cacheDir, brainProfile);
+      ok(`${brainProfile} profile preserved (${scoped.stores.join(', ')} kept; ${scoped.removed.length} unselected artifact(s) removed)`);
+    }
     if (downloaded && tmpDir) {
       try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* leave temp behind, not fatal */ }
     }
@@ -3060,10 +3609,29 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   const plugin = wirePlugin();
   // Codex hosts got nothing before this (issue #42): shipped, never registered. Non-fatal like every
   // other wiring step — a second host we cannot reach must never break the one we can.
-  try { wireCodexHost(); } catch (e) { warn(`(Codex wiring skipped: ${e && e.message})`); }
+  try {
+    const codexHost = wireCodexHost();
+    if (codexHost.host) {
+      const codexPlugin = wireCodexPlugin();
+      if (codexPlugin.available) printCodexLifecycle(await codexLifecycleStatus());
+    }
+  } catch (e) {
+    warn(`(Codex wiring skipped: ${e && e.message})`);
+  }
+  // THE CONSUMPTION FIX (the 40/100 finding, half two). These two lines used to be exactly this:
+  //
+  //     verifyInstall(cacheDir);
+  //     await smokeQuery(cacheDir);
+  //
+  // Both functions RETURN a verdict. Both were called as statements. So an install with zero vector
+  // stores, missing reader deps, or no MCP server printed three yellow warnings and then exited 0 —
+  // and every downstream consumer (a CI job, a Dockerfile, a `&&` chain, a nightly probe) was told
+  // the install succeeded. The detection was never the problem; dropping the result was.
+  let verified = null;
+  let smoke = null;
   if (!FLAG_NO_VERIFY) {
-    verifyInstall(cacheDir);
-    await smokeQuery(cacheDir);
+    verified = verifyInstall(cacheDir);
+    smoke = await smokeQuery(cacheDir);
   }
 
   // ── onboarding: detect the toolkit + make offers (all optional, all non-fatal) ──
@@ -3112,7 +3680,10 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
       console.log(`\n${c.dim('  ── how this is set up on your machine ──')}`);
       for (const line of String(explainChoice({ current: current.scope })).split('\n').slice(0, 12)) console.log(`  ${line}`);
     }
-  } catch { /* informational only */ }
+  } catch (e) {
+    // Same reasoning as the sibling block above — a silent import failure is what hid this for good.
+    warn(`scope explainer could not run (${e && e.message}) — the setup summary was skipped`);
+  }
 
   try {
     const { shouldNotify, noticeFor, recordNotified } = await import(new URL('../scripts/upgrade-notice.mjs', import.meta.url).href);
@@ -3128,6 +3699,63 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
       }
     }
   } catch { /* informational only */ }
+
+  // ── FINAL STEP: THE POST-INSTALL SELF-CHECK — the thing that runs on a stranger's machine and
+  //    CAN FAIL (ADR-053 §2, ADR-055 build item 2). Deliberately last, so it observes the machine in
+  //    the exact state the user is left in, after every wiring step and every optional offer.
+  //
+  //    ON A HEALTHY MACHINE: one calm confirming line. No nagging, no restating what already
+  //    printed above.
+  //    ON A BROKEN ONE: the violations, plainly, and a NON-ZERO exit code.
+  //
+  //    "Never block a healthy install" is honoured literally: a healthy install still exits 0 and
+  //    nothing above this point is undone. What changes is that a genuinely broken install can no
+  //    longer masquerade as a successful one to a script. The user's OWN hooks and third-party
+  //    plugins are enumerated and reported but NEVER charged against them — only registrations this
+  //    package ships can make this fail.
+  if (!FLAG_NO_SELFCHECK) {
+    const selfcheck = await runSelfCheck({
+      installState: verified ? { repos: verified.repos, reader: verified.reader, mcp: verified.mcp } : null,
+      quiet: true,
+    });
+    if (selfcheck.exitCode !== 0) {
+      console.log(`\n  ${c.dim(`Re-run  ${c.bold('npx ruvnet-brain --doctor --hooks')}  after fixing, to re-check.`)}`);
+      process.exitCode = selfcheck.exitCode;
+    }
+  }
+  // The grounding smoke result is consumed here rather than discarded: it is a SEPARATE claim from
+  // "installed and reachable" (an unproven grounding is not a broken install), so it informs the
+  // user without failing the install.
+  if (smoke && smoke.grounded === false) {
+    warn('grounding was not proven on this run — the install is present but no verifiable citation came back.');
+  }
+
+  // ── THE DEGRADED STATE, PERSISTED, NOT DODGED (ADR-058 §D8 "the grounding-smoke decision") ──────
+  // A failed smoke stays NON-FATAL here — a first-run model download or an air-gapped machine is
+  // not a broken install, and blocking on it here would fail every offline user on first contact.
+  // What changes is that the verdict stops EVAPORATING: it is written to disk so `--doctor` and
+  // session-start.sh can see it without re-running a live query, and the FIRST REAL search_ruvnet
+  // later either clears it (a real cited answer came back) or reconfirms it. `RUVNET_STRICT_INSTALL`
+  // is the one place this non-fatal default flips to fatal — used ONLY by the hostile-machine CI
+  // cell to prove the strict path is real, never set by a real install.
+  try {
+    const mod = await import(new URL('../scripts/selfcheck.mjs', import.meta.url).href);
+    const grounding = smoke && smoke.grounded === true ? 'proven' : 'unproven';
+    mod.writeInstallState({
+      grounding,
+      reason: !smoke ? 'verify-skipped' : (smoke.grounded === true ? null : (smoke.reason || (smoke.ran ? 'not-grounded' : 'no-answer'))),
+    });
+    if (grounding !== 'proven' && process.env.RUVNET_STRICT_INSTALL === '1') {
+      die(
+        'RUVNET_STRICT_INSTALL=1 and grounding was not proven on this run — refusing to report success.',
+        'This strict mode exists only to prove the DEGRADED state is real (ADR-058 §D8); a default\ninstall never fails here — unset RUVNET_STRICT_INSTALL to get the normal, non-fatal behavior.',
+      );
+    }
+  } catch (e) {
+    // Persisting the verdict must never break a finished install — but a silently-skipped write is
+    // exactly the kind of thing that must be visible, not swallowed, so it is named here.
+    warn(`(could not persist the grounding verdict: ${e && e.message})`);
+  }
 })().catch((e) => {
   die(e && e.message ? e.message : String(e));
 });