ruvnet-brain 4.4.0 → 4.5.0

package/scripts/corpus-canary.mjs

@@ -35,7 +35,7 @@
 // `codex` host is wired — this is the knowledge channel, not the host matrix.
 //
 //   node scripts/corpus-canary.mjs --repo owner/name --tag corpus-sha256-<64hex> --approved-version X.Y.Z
-//        --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>]
+//        --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--footprint-updates]
 //   exit 0 = PASS, 1 = FAIL (verdict written either way), 2 = usage.
 
 import crypto from 'node:crypto';
@@ -45,6 +45,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { addPrivateStore, resolveRuntime, resultFromRefreshReceipt, runInstallerDoor } from './customer-seams.mjs';
 import { CANARY_VERDICT_KIND, CORPUS_TAG_PATTERN, REQUIRED_CANARY_CHECKS } from './corpus-promotion.mjs';
+import { inventoryFootprint } from '../plugin/scripts/brain-footprint.mjs';
 
 export const PUBLIC_API = 'https://api.github.com';
 export const FRESHNESS_LIMIT_MS = 48 * 3_600_000;
@@ -331,8 +332,30 @@ async function fetchReleaseList({ apiBase, repo }) {
   return response.json();
 }
 
+/** The footprint of a customer HOME after one update (plugin/scripts/brain-footprint.mjs, never restated). */
+export function footprintSnapshot({ home, kbDir }) {
+  const fp = inventoryFootprint({ env: { HOME: home, RUVNET_BRAIN_KB: kbDir, RUVNET_BRAIN_HOME: path.dirname(kbDir) }, home });
+  const receipts = fp.breakdown.receipts || 0;
+  return { kbCopies: fp.kbCopies, netBytes: fp.totalBytes - receipts, receipts, budgetBytes: fp.budgetBytes,
+    withinBudget: fp.withinBudget, copies: fp.cruft.filter((i) => /kb-copy|quarantine|install-/.test(i.kind)).map((i) => i.path) };
+}
+
+/** Three updates, one KB: exactly one copy after each, nothing that must not exist, no net growth. */
+export function judgeFootprintStability(inventories, { growthAllowanceBytes = 1024 * 1024 } = {}) {
+  const problems = [];
+  inventories.forEach((inv, index) => {
+    if (inv.exitCode !== undefined && inv.exitCode !== 0) problems.push(`update ${index + 1} exited ${inv.exitCode}`);
+    if (inv.kbCopies !== 1) problems.push(`update ${index + 1}: ${inv.kbCopies} KB copies (${inv.copies.join(', ')})`);
+    if (!inv.withinBudget) problems.push(`update ${index + 1}: over the footprint budget`);
+  });
+  const growth = inventories.at(-1).netBytes - inventories[0].netBytes;
+  if (growth > growthAllowanceBytes) problems.push(`grew ${growth} bytes across ${inventories.length} updates (receipts excluded)`);
+  return problems.length ? { ok: false, detail: problems.join('; ') }
+    : { ok: true, detail: `${inventories.length} updates: 1 KB copy each time, within budget, net growth ${growth} bytes` };
+}
+
 async function runCase({ name, spec, repo, tag, approvedVersion, release, work, home, apiBase, install, now,
-  retryDelayMs, maxAttempts, log, writerRoot, approvedInstaller }) {
+  retryDelayMs, maxAttempts, log, writerRoot, approvedInstaller, footprintUpdates = false }) {
   fs.mkdirSync(home, { recursive: true });
   let runtime = approvedVersion;
   if (spec.runtime !== 'approved') runtime = resolveRuntime(spec.runtime, { candidateTag: `v${approvedVersion}`, releases: await fetchReleaseList({ apiBase, repo }) });
@@ -362,6 +385,22 @@ async function runCase({ name, spec, repo, tag, approvedVersion, release, work,
     : (fs.existsSync(resultFile) ? readJson(resultFile) : null);
   const judged = await judgeCanary({ tag, approvedVersion, release, updater, before, beforeModules, beforeCoverage,
     kbDir: fs.realpathSync(kbDir), home: fs.realpathSync(home), now: now() });
+  // ADR-0098 footprint check, OPT-IN (--footprint-updates): two more updates of the same customer through
+  // the same door, each followed by the footprint inventory. Off by default because its CI runtime on the
+  // real ~1.4 GB brain (two more full-tree validations) has not been measured yet; the offline fixture
+  // run is in tests/unit/corpus-canary.test.mjs.
+  if (footprintUpdates && name === 'clean' && updater.exitCode === 0) {
+    const inventories = [footprintSnapshot({ home: fs.realpathSync(home), kbDir })];
+    for (let extra = 0; extra < 2; extra += 1) {
+      fs.rmSync(resultFile, { force: true });
+      const again = spec.door === 'installer'
+        ? await runInstallerDoor({ installer: await approvedInstaller(), env: childEnv, cwd: home })
+        : await runUpdater({ kbDir, env: childEnv, resultFile });
+      log(`--- [${name}] footprint update ${extra + 2} exit ${again.exitCode}\n${again.output}`);
+      inventories.push({ ...footprintSnapshot({ home: fs.realpathSync(home), kbDir }), exitCode: again.exitCode });
+    }
+    judged.checks.push({ name: 'footprint-three-updates', ...judgeFootprintStability(inventories) });
+  }
   if (overlay) {
     const after = Object.fromEntries(Object.keys(overlay.digests).map((f) => [f,
       fs.existsSync(path.join(kbDir, f)) ? sha256File(path.join(kbDir, f)) : null]));
@@ -403,7 +442,7 @@ export async function runCanary({
   repo, tag, approvedVersion, work, apiBase = PUBLIC_API, install = installCustomer, home = path.join(work, 'home'),
   env = process.env, now = () => Date.now(), retryDelayMs = 30_000, maxAttempts = 3, log = () => {},
   cases = ['clean'], writerRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
-  approvedInstaller = null,
+  approvedInstaller = null, footprintUpdates = false,
 }) {
   if (!/^[^/\s]+\/[^/\s]+$/.test(String(repo || ''))) throw new Error('--repo must be owner/name');
   if (!CORPUS_TAG_PATTERN.test(String(tag || ''))) throw new Error('--tag must be corpus-sha256-<64 hex>');
@@ -426,7 +465,7 @@ export async function runCanary({
     return installerPath;
   });
   const common = { repo, tag, approvedVersion, release, apiBase, install, now, retryDelayMs, maxAttempts, log, writerRoot,
-    approvedInstaller: resolveInstaller };
+    approvedInstaller: resolveInstaller, footprintUpdates };
   let cleanKb = null;
   const clean = await runCase({ ...common, name: 'clean', spec: CANARY_CASES.clean, work, home,
     install: async (args) => { const installed = await install(args); cleanKb = physical(installed.kbDir); return installed; } });
@@ -476,7 +515,7 @@ async function main(argv = process.argv.slice(2)) {
   const work = opt('--work') && path.resolve(opt('--work'));
   const verdictOut = opt('--verdict-out') && path.resolve(opt('--verdict-out'));
   if (!work || !verdictOut) {
-    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--cases clean,private-overlay,older-runtime]\n');
+    process.stderr.write('usage: corpus-canary.mjs --repo o/n --tag corpus-sha256-<hex> --approved-version X.Y.Z --work <dir> --verdict-out <file> [--api-base URL] [--installed-kb <dir> --home <dir>] [--cases clean,private-overlay,older-runtime] [--footprint-updates]\n');
     return 2;
   }
   fs.mkdirSync(work, { recursive: true });
@@ -488,7 +527,8 @@ async function main(argv = process.argv.slice(2)) {
   let record;
   try {
     record = await runCanary({ repo: opt('--repo'), tag: opt('--tag'), approvedVersion: opt('--approved-version'), work,
-      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log, cases });
+      apiBase: opt('--api-base') || PUBLIC_API, install, home: path.resolve(opt('--home') || path.join(work, 'home')), log, cases,
+      footprintUpdates: argv.includes('--footprint-updates') });
   } catch (error) {
     // Could not even reach a judgement = the consumer did not accept. Still a written verdict.
     record = { schemaVersion: 1, kind: CANARY_VERDICT_KIND, verdict: 'FAIL', repo: opt('--repo') || null, tag: opt('--tag') || null,

package/scripts/corpus-dispatch-decision.mjs

@@ -48,8 +48,8 @@ export function killSwitchOff(nightlyVar) {
 }
 
 /**
- * @param nightlyVar   repository variable CORPUS_NIGHTLY (armed unless it reads `off`, any case; the owner's
- *                     approval of the code release is the consent)
+ * @param nightlyVar   repository variable CORPUS_NIGHTLY (armed unless it reads `off`, any case; the newest
+ *                     install-verified code release is the consent — no person approves it)
  * @param resolution   { status: 'resolved', release: {tag, version, sourceSha} }
  *                   | { status: 'not-yet-verified' } | { status: 'invalid', reason }
  */

package/scripts/corpus-promotion.mjs

@@ -33,7 +33,7 @@ export function evaluateCorpusPromotion({ tag, generation, currentLatest } = {})
   if (!CORPUS_TAG_PATTERN.test(String(currentLatest.tagName || ''))) {
     // A code release holds latest. Corpus promotion does not regress the runtime, because
     // scripts/approved-runtime.mjs has already proved this archive's executables ARE the
-    // owner-approved shipped runtime, byte for byte.
+    // install-verified shipped runtime, byte for byte.
     return {
       allowed: true,
       reason: `current latest ${currentLatest.tagName} is a code release; runtime equality is enforced by the approved runtime pin`,

package/scripts/full-suite-gate.mjs

@@ -50,10 +50,17 @@ export function redFiles(report, quarantine, root = ROOT) {
  * assertion and stays RED. Matched on the failure text only, never the test title. */
 const VITEST_TIMEOUT = /\b(?:Test|Hook) timed out in \d+ ?ms\b/;
 const NUMERIC_BOUND = /\bexpected -?\d+(?:\.\d+)? to be (?:less|greater) than (?:or equal to )?-?\d+(?:\.\d+)?/;
-const DURATION_CUE = /\d ?ms\b|\bp9[59]\b|\btook\b|\belapsed\b|\bduration\b|\blatency\b|\bbudget\b|\bceiling\b|\btimeout\b/i;
+// A DURATION, stated: a number with a time unit, or a percentile. This alone binds a bound to time.
+const UNIT_CUE = /\d ?(?:ms|s|sec|seconds?)\b|\bp9[59]\b/i;
+// A duration WORD is weaker: "retries before timeout: expected 5 to be less than 3" is a count. A word
+// cue binds only a MEASURED value — a fractional left-hand number, which is what performance.now()-based
+// timings produce ("…the ceiling: expected 337.294918 to be less than 300"); integer counts stay RED.
+const WORD_CUE = /\b(?:took|elapsed|duration|latency|budget|ceiling|timeout)\b/i;
+const MEASURED = /\bexpected -?\d+\.\d+ to be (?:less|greater) than/;
 export const isTimingFailure = (message) => {
   const text = String(message || '').slice(0, 2000);
-  return VITEST_TIMEOUT.test(text) || (NUMERIC_BOUND.test(text) && DURATION_CUE.test(text));
+  return VITEST_TIMEOUT.test(text)
+    || (NUMERIC_BOUND.test(text) && (UNIT_CUE.test(text) || (WORD_CUE.test(text) && MEASURED.test(text))));
 };
 /** More flaky tests than this in one run fails the gate: load-sensitivity that wide is itself a defect. */
 export const MAX_FLAKY = 3;

package/scripts/hook-qualify-hosts.mjs

@@ -58,7 +58,15 @@ export function scanCodex({ stdout, stderr }) {
   for (const l of lines(stderr)) if (/hook/i.test(l)) f.push(`stderr: ${l.slice(0, 200)}`);
   return { findings: [...new Set(f)], unrelatedStderr: lines(stderr).filter((l) => !/hook/i.test(l)).slice(0, 3) };
 }
-/** Pure: scan a real `grok -p --debug-file` run. */
+/**
+ * Pure: scan a real `grok -p --debug-file` run.
+ *
+ * MEASURED 2026-10-01 (grok 1.0.13, docs/research/grok-hooks-2026-10-01.md): `grok -p` discovers the Brain
+ * from Claude Code's plugin cache ("plugin discovered name=ruvnet-brain … has_hooks=true") and attaches its
+ * MCP server, but the session's "loaded hooks hook_count=8" was exactly the 4 hooks in ~/.claude/settings.json
+ * plus the 4 in ~/.grok/hooks/ — no plugin's hooks at all — and no Brain hook ever completed. A discovered
+ * plugin whose hooks never dispatch is therefore a FINDING here, never a silent pass.
+ */
 export function scanGrok({ stdout, stderr, debug = '' }) {
   const f = []; let loaded = null; const pluginHooks = /plugin discovered name=ruvnet-brain .*has_hooks=true/.test(debug);
   for (const l of lines(debug)) {
@@ -68,7 +76,11 @@ export function scanGrok({ stdout, stderr, debug = '' }) {
   }
   if (stderr.trim()) f.push(`process stderr: ${JSON.stringify(stderr.trim().slice(0, 300))}`);
   if (/hook/i.test(stdout) && /(error|failed)/i.test(stdout.match(/.{0,80}hook.{0,120}/i)?.[0] || '')) f.push('hook error text in the output stream');
-  return { findings: [...new Set(f)], hooksLoaded: loaded, pluginHasHooks: pluginHooks, pluginHooksRan: /hook_name=plugin|hook_name=ruvnet/.test(debug) };
+  const brainHooksRan = /hook completed hook_name=\S*ruvnet/.test(debug);
+  if (pluginHooks && !brainHooksRan) {
+    f.push(`Brain plugin hooks discovered but never ran (session loaded ${loaded ?? '?'} hooks): grok -p loads only global hooks — see docs/research/grok-hooks-2026-10-01.md`);
+  }
+  return { findings: [...new Set(f)], hooksLoaded: loaded, pluginHasHooks: pluginHooks, pluginHooksRan: brainHooksRan };
 }
 
 async function runClaude(root, dbgDir) {
@@ -98,7 +110,7 @@ async function runGrok(root, dbgDir) {
   const debug = fs.existsSync(debugFile) ? fs.readFileSync(debugFile, 'utf8') : '';
   const s = scanGrok({ stdout: r.stdout || '', stderr: r.stderr || '', debug });
   fs.rmSync(dir, { recursive: true, force: true });
-  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'throwaway cwd is untrusted by Grok, so project/plugin hook loading there is part of what is measured' };
+  return { status: r.status === 0 && !s.findings.length ? 'PASS' : 'FAIL', exit: r.status, ...s, note: 'real HOME: the Brain is discovered from Claude Code\'s plugin cache; whether its hooks actually RUN in grok -p is what is measured (they did not on grok 1.0.13)' };
 }
 
 export async function layer2(hosts, { maxLoad = 40, waitMs = 15 * 60_000, log = () => {}, root = REPO } = {}) {

package/scripts/host-install-matrix.mjs

@@ -37,6 +37,24 @@ export const SELF_STORE_PROOF_K = 1;
 export const RELEASE_SEARCH_QUERY = 'repo:ruvnet-brain How does RuvNet Brain prove a public release artifact?';
 export const HOST_WARMUP_TIMEOUT_MS = 300_000;
 export const RELEASE_SEARCH_DEADLINE_MS = 30_000;
+
+// RETRIEVAL-CANARY FIRST-PASS BOUND, PER OS (4.5, approved by the release coordinator 2026-10-01).
+// This bounds a CI runner's COLD canary search — the first time one warm MCP worker meets each of the
+// 19 canary repos. It is NOT a product latency target (CONTRIBUTING.md, "Hosts and verification").
+// RULE: the bound is the worst measured first-pass query x 1.5, rounded up to whole seconds, and never
+// below RELEASE_SEARCH_DEADLINE_MS. The measurement is the input, so the bound cannot drift silently:
+// changing it means changing the evidence below. Worst first-pass query, one warm worker, public 4.4.1:
+//   macOS  33,351 ms  legacy:metaharness, macos-latest (ci-probe run 36886413597); 7 samples over runs
+//                     36885062160 / 36886413597 / 36887732228 on macos-latest, -15, -14: maxima
+//                     22.4, 21.7, 22.6, 33.4, 21.5, 22.9, 30.9 s; second-pass maxima 13.5-17.5 s
+//   Linux  11,741 ms  ubuntu-latest (run 36885062160)  -> 17.6 s, so the 30 s floor holds
+//   Windows 10,679 ms windows-latest (run 36885062160) -> 16.0 s, so the 30 s floor holds
+export const CANARY_WORST_FIRST_PASS_MS = Object.freeze({ darwin: 33_351, linux: 11_741, win32: 10_679 });
+export function canarySearchDeadlineMs(platform = process.platform) {
+  const worst = CANARY_WORST_FIRST_PASS_MS[platform];
+  if (!Number.isFinite(worst)) return RELEASE_SEARCH_DEADLINE_MS;
+  return Math.max(RELEASE_SEARCH_DEADLINE_MS, Math.ceil((worst * 1.5) / 1000) * 1000);
+}
 // The shared model-cache prewarm's own candidate pool size, named so the test asserting on it
 // derives from this constant instead of restating the digit as a second, driftable literal.
 export const PREWARM_POOL_SIZE = 8;
@@ -282,7 +300,10 @@ export async function runHostMatrixAsync({
     try {
       const serverPath = resolveMcpServer(context);
       // One installed worker per host: model/store state survives smoke and every sealed case.
-      session = runMcpSearch === runInstalledMcpSearch ? createInstalledMcpSession({ serverPath, env: context.env }) : null;
+      session = runMcpSearch === runInstalledMcpSearch ? createRestartingMcpSession({
+        open: () => createInstalledMcpSession({ serverPath, env: context.env }),
+        warm: (fresh) => fresh.search({ query: SELF_STORE_PROOF_QUERY, k: SELF_STORE_PROOF_K, timeoutMs: HOST_WARMUP_TIMEOUT_MS }),
+      }) : null;
       const searchMcp = session ? (args) => session.search(args) : runMcpSearch;
       // The installed shell warms its in-process models and stores asynchronously from MCP
       // initialize. Candidate qualification must give that same worker the same cited readiness
@@ -313,7 +334,7 @@ export async function runHostMatrixAsync({
         warmupGrounding, error: `MCP search grounding unproven for ${context.mode}` };
       let receipt;
       if (retrieval) {
-        receipt = await runRetrievalCanaries({ ...retrieval, searchTimeoutMs: RELEASE_SEARCH_DEADLINE_MS,
+        receipt = await runRetrievalCanaries({ ...retrieval, searchTimeoutMs: canarySearchDeadlineMs(),
           search: async ({ query, k, timeoutMs }) => {
             const result = await searchMcp({ mode: context.mode, serverPath, env: context.env, query, k, timeoutMs });
             if (result.error || result.status !== 0) throw new Error(`canary MCP search failed: ${processDiagnostic(result)}`);
@@ -478,6 +499,46 @@ export function createInstalledMcpSession({ serverPath, env, timeout = 300_000,
   };
 }
 
+// ONE SLOW QUERY MUST FAIL ONLY ITSELF. A search that times out or fails closes its session — the
+// worker may be wedged mid-rerank — and a closed session answers every later call with that same
+// stored error, instantly. So one slow canary case became every remaining case "timed out" (4.4.1
+// preflight attempt 1: cases 9-18 ETIMEDOUT; recovery 36881395598: cases 14-18). This keeps one warm
+// worker for the whole lane, as a customer has, and only after a failure opens a fresh one, warmed
+// on the warm-up bound (never on the next case's deadline) before that case is timed.
+export function createRestartingMcpSession({ open, warm = null }) {
+  let session = open();
+  let closed = false;
+  let restarts = 0;
+  let queue = Promise.resolve();
+  const failed = (result) => Boolean(result?.error) || result?.status !== 0;
+  const run = async (args) => {
+    if (closed) return { status: null, signal: null, error: new Error('MCP session closed'), stdout: '', stderr: '' };
+    if (!session) {
+      session = open();
+      restarts += 1;
+      if (warm) {
+        const warmed = await warm(session);
+        if (failed(warmed)) { const dead = session; session = null; await dead.close(); return warmed; }
+      }
+    }
+    const result = await session.search(args);
+    if (failed(result)) { const dead = session; session = null; await dead.close(); }
+    return result;
+  };
+  return {
+    search(args) {
+      const result = queue.then(() => run(args));
+      queue = result.then(() => undefined, () => undefined);
+      return result;
+    },
+    async close() {
+      closed = true;
+      if (session) { const live = session; session = null; await live.close(); }
+    },
+    get restarts() { return restarts; },
+  };
+}
+
 async function runInstalledMcpSearch(options) {
   const session = createInstalledMcpSession(options);
   try { return await session.search(options); } finally { await session.close(); }

package/scripts/human-approval-phrases.mjs

@@ -0,0 +1,46 @@
+// human-approval-phrases.mjs — the matcher behind single-source B6 (tracked instructions) and B12 (the
+// local CLAUDE.md / AGENTS.md): no instruction may put a person clicking in GitHub back into the release
+// path (CONTRIBUTING.md, "What replaces a human approval").
+//
+// Two gaps the 4.3.39 review measured, both closed here:
+//  • Markdown emphasis broke the match: "Stuart's approval** of the …" did not match "Stuart's approval of".
+//    Lines are matched after stripping `*` and backticks.
+//  • B6 exempted any line containing "never" ANYWHERE, so "The owner approves the Production deployment;
+//    never skip it." passed. A negation now counts only inside the same clause as the matched phrase.
+
+/** Phrases that re-introduce a person as a release gate (B6, tracked instruction files). */
+export const HUMAN_APPROVAL_STEP = /(owner|stuart'?s?|maintainer) (approves?|approval|click|must approve)\b[^.;]*(deployment|release|publish|gate)|approves? the Production|hand (it|the work) over[^.;]*click|required[- ]reviewers?\b|standing authori[sz]ation permits|owner[- ]approved/i;
+
+/** B12: the same, plus the local-file drifts that file has carried (npx ruflo, retired npm scripts). */
+export const LOCAL_INSTRUCTION_DRIFT = /npx (-y )?(@claude-flow|claude-flow|ruflo)\b|standing authori[sz]ation permits|owner (approves?|click)|Stuart's approval (of|in GitHub)|approves? the Production|hand (it|the work) over[^.]*click|npm run (build|dev|test:integration|test:coverage|test:security)\b|not direct Agent tool|owner[- ]approved/i;
+
+const NEGATION = /\b(no|not|never|nobody|none|without|cannot|isn't|is not|removed|retired)\b/i;
+
+/** Markdown emphasis and code ticks are formatting, not words. */
+export const plainText = (line) => String(line).replace(/[*`]/g, '');
+
+/** The clause around [start, end): bounded by . ; : ! ? or the line ends. */
+function clauseAround(text, start, end) {
+  const before = text.slice(0, start);
+  const after = text.slice(end);
+  const from = Math.max(...['.', ';', ':', '!', '?'].map((c) => before.lastIndexOf(c))) + 1;
+  const stops = ['.', ';', ':', '!', '?'].map((c) => after.indexOf(c)).filter((i) => i >= 0);
+  const to = end + (stops.length ? Math.min(...stops) : after.length);
+  return text.slice(from, to);
+}
+
+/**
+ * Hits of `pattern` in `line` that are not negated in their own clause.
+ * @returns {string[]} the matched phrases that count
+ */
+export function approvalHits(line, pattern = HUMAN_APPROVAL_STEP, { allowNegation = true } = {}) {
+  const text = plainText(line);
+  const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+  const hits = [];
+  for (const match of text.matchAll(global)) {
+    const clause = clauseAround(text, match.index, match.index + match[0].length);
+    if (allowNegation && NEGATION.test(clause)) continue;
+    hits.push(match[0]);
+  }
+  return hits;
+}

package/scripts/installed-brain-health.mjs

@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto';
 import { readInstalledRuntime, isCorpusReleaseTag } from '../kb/corpus-release-identity.mjs';
 import { cmpVersion } from './stack-sync.mjs';
 import { isRuntimeFile } from './approved-runtime.mjs';
+import { modelCacheReady, requiredEmbedderModels, RERANKER_MODEL } from '../kb/model-requirements.mjs';
 
 const SEARCH_FILES = ['forge-mcp-all.mjs', 'forge-ask-all.mjs', 'forge-rerank.mjs', 'card-lane.mjs'];
 // Keep the doctor probe answerable and bounded. A health probe must exercise a real indexed
@@ -14,6 +15,58 @@ export function doctorSmokeArgs(cacheDir) {
   return ['forge-ask-all.mjs', '--dir', cacheDir, '--q', DOCTOR_SMOKE_QUERY,
     '--repos', 'ruvnet-brain', '--k', '3', '--pool', '8', '--bounded'];
 }
+
+// The models the doctor's question loads whose local copy is not complete. A partial download is
+// cold, not ready: the reader would fetch it again inside the timed question.
+export function coldModels(kbDir, modelCache) {
+  return [...requiredEmbedderModels(kbDir), RERANKER_MODEL]
+    .filter((model, i, all) => all.indexOf(model) === i && !modelCacheReady(modelCache, model));
+}
+
+// One-time model download + load + first forward pass, kept OUT of the timed question so the
+// question's limit measures answering, not fetching. Exits 3 on a bundle that predates the hooks.
+export const MODEL_WARMUP_SCRIPT = [
+  "const ask = await import('./forge-ask.mjs');",
+  "const rr = await import('./forge-rerank.mjs');",
+  "if (typeof ask.warmQueryEmbedder !== 'function' || typeof rr.warmReranker !== 'function') process.exit(3);",
+  'await ask.warmQueryEmbedder();',
+  'await rr.warmReranker();',
+  'process.exit(0);',
+].join('\n');
+export const MODEL_WARMUP_TIMEOUT_MS = 300_000;
+
+// WHY the doctor's question produced no answer, from what spawnSync returned. "slow" is the reader's
+// own deadline: kb/query-deadline.mjs describeDeadline() prints this line, naming the phase still
+// running, only on that path (that module is not in the npm package, so its text is the contract
+// here). The reader works and was mid-answer — a different fault, with different advice, from a crash.
+export function classifySmokeFailure({ error, signal, status, stderr = '', secs, limitSecs }) {
+  // spawnSync delivers its own timeout as signal SIGTERM AND error ETIMEDOUT: a timeout, not a launch failure.
+  if (error?.code === 'ETIMEDOUT') return { kind: 'timeout', cause: `timed out after ${secs}s (240s limit) with no answer` };
+  if (error) return { kind: 'launch', cause: `could not launch the reader: ${error.message}` };
+  if (signal === 'SIGTERM') return { kind: 'timeout', cause: `timed out after ${secs}s (240s limit) with no answer` };
+  if (signal) return { kind: 'killed', cause: `the reader was killed by ${signal} after ${secs}s` };
+  const phase = (String(stderr).match(/QUERY DEADLINE EXCEEDED — phase "([^"]+)"/) || [])[1];
+  if (status !== 0 && phase) {
+    return { kind: 'slow', phase,
+      cause: `still answering (phase "${phase}") when the ${limitSecs}s limit ran out, after ${secs}s — slow on this machine, not broken` };
+  }
+  if (status !== 0) return { kind: 'crash', cause: `the reader exited ${status} after ${secs}s` };
+  return { kind: 'empty', cause: `the reader exited 0 after ${secs}s but printed nothing` };
+}
+
+/**
+ * Why the model warm-up did not finish (re-review B1). spawnSync's own timeout is signal SIGTERM WITH error
+ * ETIMEDOUT — a slow machine, advisory. A signal with NO error is the child dying on its own: SIGABRT,
+ * SIGSEGV, an OOM SIGKILL — a broken model runtime or cache, a failure with its own cause. The old test,
+ * `signal && !error`, had both backwards.
+ */
+export function classifyWarmupFailure({ error, signal, status, secs, limitSecs }) {
+  if (error?.code === 'ETIMEDOUT') return { kind: 'timeout', advisory: true, cause: `ran out of time after ${secs}s (${limitSecs}s limit) — slow on this machine, not broken` };
+  if (error) return { kind: 'launch', advisory: false, cause: `could not start: ${error.message}` };
+  if (signal) return { kind: 'crash', advisory: false, cause: `crashed (${signal}) after ${secs}s — the model runtime or its cache is broken` };
+  return { kind: 'exit', advisory: false, cause: `exited ${status} after ${secs}s` };
+}
+
 const version = value => typeof value === 'string' && /^v?\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(value)
   ? value.replace(/^v/, '') : null;