ruvnet-brain 4.3.40 → 4.4.1

package/scripts/host-cli.mjs

@@ -0,0 +1,115 @@
+// host-cli.mjs — run the `claude` / `codex` CLI from the installer, tolerating a binary that is
+// briefly absent because the host is updating itself.
+//
+// 2026-09-30, owner's Mac: Claude Code self-updated during `npx ruvnet-brain --update`;
+// ~/.npm-global/bin/claude was missing for a few seconds and the installer printed raw
+// "No such file or directory" shell errors. A missing binary is now retried with a short bounded
+// backoff (3 tries over ~20s by default) and, if it never comes back, reported as ONE clear line.
+// Raw stderr from a missing-binary attempt is swallowed; stderr from a real run is passed through.
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const IS_WIN = process.platform === 'win32';
+export const HOST_CLI_RETRY_DELAYS_MS = Object.freeze([5_000, 15_000]);
+const sleepSync = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+// CLIs this process has seen working. Only a CLI that was here (or whose PATH link still exists)
+// can be "transiently" missing; one that was never installed fails at once, with no 20s wait.
+const SEEN = new Set();
+// CLIs that stayed missing through one full wait: gone for this process. A permanently dangling link
+// must not cost ~20s on EVERY later call — one bounded wait per process, then fail at once.
+const GONE = new Set();
+
+/** The binary's real path, or null when it is not on PATH or its link points at nothing. */
+export function resolveHostCli(cmd, { spawn = spawnSync } = {}) {
+  const probe = IS_WIN
+    ? spawn('where', [cmd], { encoding: 'utf8' })
+    : spawn('sh', ['-c', 'command -v -- "$1"', 'sh', cmd], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) return null;
+  const found = String(probe.stdout || '').split(/\r?\n/).find(Boolean);
+  if (!found) return null;
+  if (!IS_WIN && !found.includes('/')) { SEEN.add(cmd); return found; } // builtin/function: nothing to stat
+  try { const real = fs.realpathSync(found); SEEN.add(cmd); return real; }
+  catch { return null; } // dangling link mid-update
+}
+
+/** A PATH entry named `cmd` exists (even as a link that currently points nowhere). */
+export function hostCliOnPath(cmd, { env = process.env } = {}) {
+  const names = IS_WIN ? [cmd, `${cmd}.cmd`, `${cmd}.exe`] : [cmd];
+  for (const dir of String(env.PATH || '').split(IS_WIN ? ';' : ':').filter(Boolean)) {
+    for (const name of names) { try { fs.lstatSync(`${dir}/${name}`); return true; } catch { /* next */ } }
+  }
+  return false;
+}
+
+/**
+ * Is the CLI usable? A link that exists but points nowhere is a host mid-self-update: wait for it
+ * (same bounded backoff). A CLI that is simply not installed returns at once, with no wait.
+ */
+export function waitForHostCli(cmd, { delays = HOST_CLI_RETRY_DELAYS_MS, sleep = sleepSync, resolve = resolveHostCli,
+  onPath = hostCliOnPath } = {}) {
+  if (resolve(cmd)) { GONE.delete(cmd); return { present: true, waited: false }; }
+  if (!onPath(cmd)) return { present: false, waited: false };
+  const waited = Math.round(delays.reduce((sum, ms) => sum + ms, 0) / 1000);
+  const message = `the \`${cmd}\` command is on PATH but points at nothing (checked for ${waited}s — it may be updating itself)`;
+  if (GONE.has(cmd)) return { present: false, waited: false, message };
+  for (const ms of delays) {
+    sleep(ms);
+    if (resolve(cmd)) return { present: true, waited: true };
+  }
+  GONE.add(cmd);
+  return { present: false, waited: true, message };
+}
+
+const MISSING_TEXT = /(?:No such file or directory|command not found|ENOENT|is not recognized as an internal or external command)/i;
+
+/** True when this attempt failed because the CLI itself could not be executed. */
+export function missingBinaryAttempt(result, cmd, { resolve = resolveHostCli } = {}) {
+  if (result?.error?.code === 'ENOENT') return true;
+  if (result?.error || result?.status === 0) return false;
+  // 127 is the shell's "could not execute" — but only when the binary really is gone; a CLI that
+  // resolves and itself exits 127 ran, and its failure is its own.
+  if (result?.status === 127) return !resolve(cmd);
+  // A run that started and failed for its own reasons is not "missing"; only a failure whose text
+  // says a file was missing AND whose binary no longer resolves is.
+  return MISSING_TEXT.test(String(result?.stderr || '')) && !resolve(cmd);
+}
+
+/**
+ * spawnSync-compatible. Extra fields on the returned object: `attempts`, and on exhaustion
+ * `missingBinary: true` plus `message` (the one line to print). With stdio 'inherit' (the default),
+ * stdin/stdout stay inherited; stderr is captured so a missing-binary attempt prints nothing.
+ */
+export function runHostCli(cmd, args, {
+  delays = HOST_CLI_RETRY_DELAYS_MS, sleep = sleepSync, spawn = spawnSync, resolve = resolveHostCli,
+  onPath = hostCliOnPath, stdio = 'inherit', echoStderr = (text) => process.stderr.write(text), ...opts
+} = {}) {
+  const inherit = stdio === 'inherit';
+  const spawnOpts = { shell: IS_WIN, ...opts, stdio: inherit ? ['inherit', 'inherit', 'pipe'] : stdio };
+  if (inherit && !spawnOpts.encoding) spawnOpts.encoding = 'utf8';
+  let result;
+  if (GONE.has(cmd)) delays = []; // already waited once this process: one attempt, no backoff
+  for (let attempt = 0; attempt <= delays.length; attempt += 1) {
+    if (attempt > 0) sleep(delays[attempt - 1]);
+    result = spawn(cmd, args, spawnOpts);
+    const missing = missingBinaryAttempt(result, cmd, { resolve });
+    if (!missing) { SEEN.add(cmd); GONE.delete(cmd); }
+    // Never installed (not seen this run, no PATH entry at all): the caller's own "not found"
+    // handling applies at once, exactly as before.
+    if (!missing || (attempt === 0 && !SEEN.has(cmd) && !onPath(cmd))) {
+      if (inherit && result?.stderr) echoStderr(String(result.stderr));
+      return Object.assign(result ?? {}, { attempts: attempt + 1 });
+    }
+  }
+  const waited = Math.round(delays.reduce((sum, ms) => sum + ms, 0) / 1000);
+  GONE.add(cmd);
+  return Object.assign(result ?? {}, {
+    attempts: delays.length + 1,
+    missingBinary: true,
+    message: delays.length
+      ? `the \`${cmd}\` command was not available (tried ${delays.length + 1} times over ${waited}s — it may be updating itself); skipped \`${cmd} ${args.join(' ')}\``
+      : `the \`${cmd}\` command is still not available (it already stayed missing through a wait earlier in this run); skipped \`${cmd} ${args.join(' ')}\``,
+  });
+}
+
+/** Test seam: forget which CLIs this process has seen. */
+export function resetSeenHostClis() { SEEN.clear(); GONE.clear(); }

package/scripts/qe/agentic-qe-4.3.mjs

@@ -58,7 +58,6 @@ const LANES = Object.freeze({
   release: [
     vitest([
       'tests/qe/release/packed-clean-install.test.mjs',
-      'tests/qe/release/release-publish-contract.test.mjs',
       'tests/qe/release/stable-spine-recovery.test.mjs',
       'tests/qe/security/release-abuse-cases.test.mjs',
     ], 240_000),

package/scripts/route-gold-rank.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * scripts/route-gold-rank.mjs — where does the source router put the store that holds the answer?
+ *
+ * search_ruvnet first plans a bounded set of stores (kb/forge-ask-all.mjs planSourceRoute) and only
+ * then retrieves and reranks inside them. A store the plan never opens cannot be cited, however good
+ * the reranker is. This harness measures ONLY that first step: for each question it runs the exact
+ * planner the search path runs (no model, no retrieval) and records the rank of the first planned
+ * store that matches the question's gold repository. It reports, with 95% Wilson intervals:
+ *
+ *   goldAt1 / goldAt3 / goldAt5   gold store among the first 1 / 3 / 5 planned stores
+ *   declined                      the planner opened nothing (bounded search refuses)
+ *   reposOpened                   mean planned stores per question (cost: each is a retrieval + rerank)
+ *
+ * Question sets (any number, each optional):
+ *   --needs <file>    novice need set (data/need-set/need-set-v1.json shape: questions[].need, .repo)
+ *   --heldout <file>  evals/held-out.json shape (questions[].query, .stratum, .expectRepo); the
+ *                     named/described/scenario strata are scored, adversarial is reported as declined
+ *   --recall-fixture <file>  data/retrieval-query-evidence.json with each store's identity stripped
+ *                     (unnameRecallQuery): one described need per store, 180+ stores
+ *
+ *   node scripts/route-gold-rank.mjs --kb <kbDir> [--impl <forge-ask-all.mjs>] [--needs f] [--heldout f]
+ *     [--recall-fixture f] [--out f]
+ *
+ * --impl lets the SAME KB be routed by two code versions (a baseline checkout and this one).
+ * Measurements only: it writes nothing but --out.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { wilson, repoMatchesExpected } from './eval-brain.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Rank (1-based) of the first planned store matching any expected repo, or null. Case-insensitive. */
+export function goldRank(plannedRepos, expected, aliases = {}) {
+  const lowerAliases = Object.fromEntries(Object.entries(aliases || {})
+    .map(([canonical, list]) => [canonical.toLowerCase(), (list || []).map((s) => String(s).toLowerCase())]));
+  const want = (expected || []).map((e) => String(e).toLowerCase());
+  const idx = (plannedRepos || []).findIndex((repo) => repoMatchesExpected(String(repo).toLowerCase(), want, lowerAliases));
+  return idx < 0 ? null : idx + 1;
+}
+
+const rate = (rows, pred) => {
+  const k = rows.filter(pred).length;
+  const w = wilson(k, rows.length);
+  return { k, n: rows.length, p: +w.p.toFixed(4), lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) };
+};
+
+/** Summarize scored rows ({ rank, repos, group }) into the reported metrics, overall and per group. */
+export function summarizeRoutes(rows) {
+  const one = (rs) => ({
+    goldAt1: rate(rs, (r) => r.rank != null && r.rank <= 1),
+    goldAt3: rate(rs, (r) => r.rank != null && r.rank <= 3),
+    goldAt5: rate(rs, (r) => r.rank != null && r.rank <= 5),
+    declined: rate(rs, (r) => !r.repos.length),
+    reposOpened: rs.length ? +(rs.reduce((s, r) => s + r.repos.length, 0) / rs.length).toFixed(3) : 0,
+  });
+  const groups = [...new Set(rows.map((r) => r.group))].sort();
+  return { all: one(rows), byGroup: Object.fromEntries(groups.map((g) => [g, one(rows.filter((r) => r.group === g))])) };
+}
+
+/** Route every question through `planSourceRoute` and score it. Pure apart from the planner itself. */
+export function measureRouteRanks({ kbDir, questions, planSourceRoute, discoverRepos, aliases = {} }) {
+  const discovered = discoverRepos(kbDir);
+  const rows = [];
+  const t0 = performance.now();
+  for (const q of questions) {
+    const planned = planSourceRoute({ dir: kbDir, query: q.query, discovered }) || { repos: [] };
+    const repos = Array.isArray(planned.repos) ? planned.repos : [];
+    rows.push({ id: q.id, group: q.group, expected: q.expected, repos, reason: planned.reason || null,
+      rank: q.expected?.length ? goldRank(repos, q.expected, aliases) : null });
+  }
+  return { rows, msPerQuestion: questions.length ? +((performance.now() - t0) / questions.length).toFixed(1) : 0 };
+}
+
+/**
+ * The recall fixture asks one question per store and NAMES the store ("In the agentdb repository,
+ * what is AgentDB ..."). With every spelling of the store key removed it becomes a described need
+ * for 180+ stores, so routing can be checked on far more than three repositories. Honest limit: a
+ * display name that is not the store key (e.g. "2 BoT Talk" for 2bottalk) can survive the strip.
+ */
+export function unnameRecallQuery(query, store) {
+  const words = String(store).toLowerCase().match(/[a-z0-9]+/g) || [];
+  const name = new RegExp(`(?<![a-z0-9])${words.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[\\s._-]*')}(?![a-z0-9])`, 'gi');
+  return String(query).replace(/^in the \S+ repository,\s*/i, '').replace(name, 'this project').replace(/\s+/g, ' ').trim();
+}
+
+export function loadQuestions({ needs, heldout, recallFixture }) {
+  const out = { needs: [], heldout: [], offTopic: [], recallUnnamed: [] };
+  if (recallFixture) {
+    for (const [store, q] of Object.entries(JSON.parse(fs.readFileSync(recallFixture, 'utf8')).queries)) {
+      out.recallUnnamed.push({ id: store, group: 'recall', query: unnameRecallQuery(q.query, store), expected: [store] });
+    }
+  }
+  if (needs) {
+    for (const q of JSON.parse(fs.readFileSync(needs, 'utf8')).questions) {
+      out.needs.push({ id: q.id, group: q.repo, query: q.need, expected: [q.repo] });
+    }
+  }
+  if (heldout) {
+    for (const q of JSON.parse(fs.readFileSync(heldout, 'utf8')).questions) {
+      if (q.stratum === 'adversarial') out.offTopic.push({ id: q.id, group: 'adversarial', query: q.query, expected: [] });
+      else if (['named', 'described', 'scenario'].includes(q.stratum)) {
+        out.heldout.push({ id: q.id, group: q.stratum, query: q.query, expected: q.expectRepo || [] });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * What a committed report says about its inputs. Never a local absolute path: the KB is named by its
+ * build stamp, and the implementation by its repo-relative path (or `<impl>` when it lives outside
+ * this checkout). The code's identity is the commit the report is filed with.
+ */
+export function reportIdentity({ impl, kbDir }) {
+  let kbBuild = null;
+  try {
+    const m = JSON.parse(fs.readFileSync(path.join(kbDir, 'manifest.json'), 'utf8'));
+    kbBuild = { brainVersion: m.brainVersion ?? null, generated: m.generated ?? null };
+  } catch { /* no manifest */ }
+  const rel = path.relative(ROOT, path.resolve(impl));
+  return { impl: rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : '<impl>', kbDir: '<kb>', kbBuild };
+}
+
+function arg(name) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+async function main() {
+  const kbDir = arg('--kb');
+  if (!kbDir || !fs.existsSync(kbDir)) throw new Error('--kb <dir> is required and must exist');
+  const impl = path.resolve(arg('--impl') || path.join(ROOT, 'kb/forge-ask-all.mjs'));
+  const mod = await import(pathToFileURL(impl).href);
+  if (typeof mod.planSourceRoute !== 'function') throw new Error(`${impl} does not export planSourceRoute`);
+  let aliases = {};
+  try { aliases = JSON.parse(fs.readFileSync(path.join(kbDir, 'repo-aliases.json'), 'utf8')); } catch { /* none */ }
+  const sets = loadQuestions({ needs: arg('--needs'), heldout: arg('--heldout'), recallFixture: arg('--recall-fixture') });
+  const report = { kind: 'ruvnet-brain-route-gold-rank', ...reportIdentity({ impl, kbDir }), measuredAt: new Date().toISOString(), sets: {} };
+  for (const [name, questions] of Object.entries(sets)) {
+    if (!questions.length) continue;
+    const { rows, msPerQuestion } = measureRouteRanks({ kbDir, questions, planSourceRoute: mod.planSourceRoute,
+      discoverRepos: mod.discoverRepos, aliases });
+    report.sets[name] = { ...summarizeRoutes(rows), msPerQuestion, rows };
+  }
+  const outFile = arg('--out');
+  if (outFile) fs.writeFileSync(outFile, `${JSON.stringify(report, null, 2)}\n`);
+  const brief = Object.fromEntries(Object.entries(report.sets).map(([k, v]) => [k, { ...v.all, msPerQuestion: v.msPerQuestion }]));
+  console.log(JSON.stringify(brief, null, 1));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/scripts/route-index-memory.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * scripts/route-index-memory.mjs — how much memory the router metadata index keeps alive in a
+ * long-lived process (the warm MCP worker), and how long the cold build takes.
+ *
+ * Builds the index for every store by routing one question, forces GC, and reports the retained
+ * delta of heapUsed and arrayBuffers. Needs --expose-gc.
+ *
+ *   node --expose-gc scripts/route-index-memory.mjs --kb <kbDir> [--impl <forge-ask-all.mjs>]
+ *
+ * Prints JSON with no local paths (the KB is named by its build stamp).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (name) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : undefined; };
+
+export function retained(before, after) {
+  const mb = (x) => +(x / 1048576).toFixed(1);
+  return { heapUsedMB: mb(after.heapUsed - before.heapUsed), arrayBuffersMB: mb(after.arrayBuffers - before.arrayBuffers),
+    totalMB: mb(after.heapUsed - before.heapUsed + after.arrayBuffers - before.arrayBuffers) };
+}
+
+async function main() {
+  if (typeof globalThis.gc !== 'function') throw new Error('run with node --expose-gc');
+  const kbDir = arg('--kb');
+  if (!kbDir || !fs.existsSync(kbDir)) throw new Error('--kb <dir> is required and must exist');
+  const impl = path.resolve(arg('--impl') || path.join(ROOT, 'kb/forge-ask-all.mjs'));
+  const { metadataSourceRoute, discoverRepos } = await import(pathToFileURL(impl).href);
+  const repos = discoverRepos(kbDir);
+  const query = 'keep embeddings searchable offline on a laptop without a database server';
+  metadataSourceRoute('warm up the tokenizer and module state only', path.join(kbDir, '__none__'), []);
+  globalThis.gc(); globalThis.gc();
+  const before = process.memoryUsage();
+  const t0 = performance.now();
+  metadataSourceRoute(query, kbDir, repos);
+  const coldMs = Math.round(performance.now() - t0);
+  globalThis.gc(); globalThis.gc();
+  const after = process.memoryUsage();
+  const t1 = performance.now();
+  metadataSourceRoute(query, kbDir, repos);
+  const warmMs = Math.round(performance.now() - t1);
+  let kbBuild = null;
+  try { const m = JSON.parse(fs.readFileSync(path.join(kbDir, 'manifest.json'), 'utf8')); kbBuild = { brainVersion: m.brainVersion, generated: m.generated }; } catch { /* none */ }
+  const rel = path.relative(ROOT, impl);
+  console.log(JSON.stringify({ impl: rel.startsWith('..') ? '<impl>' : rel, kbBuild, stores: repos.length, coldMs, warmMs, retained: retained(before, after) }));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/route-latency-warm.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * scripts/route-latency-warm.mjs — paired WARM latency of two or more search runtimes on the same
+ * questions, in ONE process (the warm MCP worker's regime).
+ *
+ * Each arm is a KB directory whose forge-ask-all.mjs is the code under test: a shadow copy of a
+ * corpus with that version's kb/*.mjs. Every question is asked of every arm back to back. The arm
+ * order rotates per question, and each question first waits for the 1-minute load average to drop
+ * below --max-load, so the arms of one question share conditions. searchAll is called exactly as
+ * kb/forge-mcp-all.mjs calls it (k 6, allowFullCorpus false). Rows are appended to <out>.rows.jsonl
+ * as they finish, so an interrupted run keeps what it measured.
+ *
+ *   node scripts/route-latency-warm.mjs --set <need-set.json> --out <file> [--stride 3] [--max-load 60]
+ *     --arm A_base=<kbDir> --arm B_final=<kbDir> [--arm ...]
+ *   node scripts/route-latency-warm.mjs --summarize <rows.jsonl> --arms A_base,B_final[,...]
+ *
+ * The summary reports, per arm, p50 / p90 and mean stores searched; for each pair, the p50 and p90
+ * deltas and the median per-question difference, each with a 95% paired bootstrap interval
+ * (2000 resamples, fixed seed). Nothing it writes contains a local path.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const percentile = (xs, p) => {
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor(p * s.length))];
+};
+
+/** Seeded LCG, so a summary of the same rows always prints the same intervals. */
+function rng(seed = 42) {
+  let s = seed;
+  return () => ((s = (s * 1103515245 + 12345) % 2147483648) / 2147483648);
+}
+
+export function summarizeRows(rows, labels, { resamples = 2000, seed = 42 } = {}) {
+  const ok = rows.filter((r) => labels.every((a) => r[a] && !r[a].err));
+  const out = { n: rows.length, nOk: ok.length, arms: {}, deltas: {} };
+  if (rows.length) out.loadAt = { min: Math.min(...rows.map((r) => r.loadAt)), max: Math.max(...rows.map((r) => r.loadAt)) };
+  for (const a of labels) {
+    const ms = ok.map((r) => r[a].ms);
+    out.arms[a] = { p50: Math.round(percentile(ms, 0.5)), p90: Math.round(percentile(ms, 0.9)),
+      meanRepos: ok.length ? +(ok.reduce((s, r) => s + (r[a].repos || 0), 0) / ok.length).toFixed(3) : 0,
+      errors: rows.filter((r) => r[a]?.err).length };
+  }
+  const rnd = rng(seed);
+  for (let x = 0; x < labels.length; x++) for (let y = x + 1; y < labels.length; y++) {
+    const A = labels[x];
+    const B = labels[y];
+    const stat = (idx) => ({
+      p50: percentile(idx.map((i) => ok[i][B].ms), 0.5) - percentile(idx.map((i) => ok[i][A].ms), 0.5),
+      p90: percentile(idx.map((i) => ok[i][B].ms), 0.9) - percentile(idx.map((i) => ok[i][A].ms), 0.9),
+      medianPaired: percentile(idx.map((i) => ok[i][B].ms - ok[i][A].ms), 0.5),
+    });
+    const all = stat(ok.map((_, i) => i));
+    const boots = Array.from({ length: resamples }, () => stat(ok.map(() => Math.floor(rnd() * ok.length))));
+    const ci = (k) => [Math.round(percentile(boots.map((s) => s[k]), 0.025)), Math.round(percentile(boots.map((s) => s[k]), 0.975))];
+    out.deltas[`${B} - ${A}`] = { p50: Math.round(all.p50), p50CI: ci('p50'), p90: Math.round(all.p90), p90CI: ci('p90'),
+      medianPairedDiff: Math.round(all.medianPaired), medianPairedCI: ci('medianPaired'),
+      bFaster: `${ok.filter((r) => r[B].ms < r[A].ms).length}/${ok.length}` };
+  }
+  return out;
+}
+
+const args = process.argv.slice(2);
+const arg = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const all = (name) => args.flatMap((v, i) => (v === name ? [args[i + 1]] : []));
+
+async function run() {
+  const set = arg('--set');
+  const out = arg('--out');
+  if (!set || !out) throw new Error('--set and --out are required');
+  const stride = Math.max(1, Number(arg('--stride')) || 1);
+  const maxLoad = Number(arg('--max-load')) || 60;
+  const arms = [];
+  for (const spec of all('--arm')) {
+    const [label, dir] = spec.split('=');
+    const { searchAll } = await import(pathToFileURL(path.join(path.resolve(dir), 'forge-ask-all.mjs')).href);
+    arms.push({ label, dir: path.resolve(dir), searchAll });
+  }
+  if (arms.length < 2) throw new Error('at least two --arm label=kbDir are required');
+  const questions = JSON.parse(fs.readFileSync(set, 'utf8')).questions.filter((_, i) => i % stride === 0);
+  const rowsFile = `${out}.rows.jsonl`;
+  fs.writeFileSync(rowsFile, '');
+  const ask = async (arm, query) => {
+    const t0 = performance.now();
+    let res = null;
+    let err = null;
+    try { res = await arm.searchAll({ dir: arm.dir, query, k: 6, allowFullCorpus: false }); } catch (e) { err = String(e?.message || e).slice(0, 200); }
+    return { ms: performance.now() - t0, repos: res?.repos?.length ?? null,
+      top: res?.results?.[0] ? `${res.results[0].repo}/${res.results[0].path}` : null, err };
+  };
+  for (const q of questions.slice(0, 3)) for (const arm of arms) await ask(arm, q.need); // warm, untimed
+  const rows = [];
+  for (let i = 0; i < questions.length; i++) {
+    while (os.loadavg()[0] >= maxLoad) await new Promise((r) => setTimeout(r, 15000));
+    const row = { id: questions[i].id, loadAt: +os.loadavg()[0].toFixed(1) };
+    for (let j = 0; j < arms.length; j++) {
+      const arm = arms[(i + j) % arms.length];
+      row[arm.label] = await ask(arm, questions[i].need);
+    }
+    rows.push(row);
+    fs.appendFileSync(rowsFile, `${JSON.stringify(row)}\n`);
+    process.stderr.write(`\r[route-latency-warm] ${i + 1}/${questions.length}`);
+  }
+  const summary = summarizeRows(rows, arms.map((a) => a.label));
+  fs.writeFileSync(out, `${JSON.stringify(summary, null, 1)}\n`);
+  console.log(JSON.stringify(summary, null, 1));
+}
+
+async function main() {
+  const rowsFile = arg('--summarize');
+  if (rowsFile) {
+    const rows = fs.readFileSync(rowsFile, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    console.log(JSON.stringify(summarizeRows(rows, String(arg('--arms') || '').split(',').filter(Boolean)), null, 1));
+    return;
+  }
+  await run();
+  process.exit(0);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/wired-check.mjs

@@ -75,8 +75,16 @@ const STANDALONE = [
     + 'producer exists, and Step 15 owns any prepareCorpusCandidate wiring. The three modules it drives (source-units, '
     + 'produce-questions, validate-labels) are each wired to a real caller; this driver is the human entry point.'],
   ['gate', 'retired automatic-hook helper and manual benchmark retained for explicit human use; no workflow or scheduler invokes this expensive command'],
-  ['dream-issue-gate', 'pure Dream Cycle disposition policy; invoked by the external issue adapter, never a GitHub writer'],
+  ['route-gold-rank', 'human-run measurement harness: routes question sets through kb/forge-ask-all.mjs planSourceRoute (no model) and reports where the gold store lands, with Wilson intervals; nothing to schedule'],
+  ['route-latency-warm', 'human-run measurement harness: paired warm latency of two or more search runtimes in one process, load-gated, with paired bootstrap intervals; minutes to hours of model time, never scheduled'],
+  ['route-index-memory', 'human-run measurement harness: retained memory and cold/warm time of the router metadata index (needs node --expose-gc); nothing to schedule'],
+  ['dream-issue-gate','pure Dream Cycle disposition policy; invoked by the external issue adapter, never a GitHub writer'],
   ['sync-census', 'explicit maintainer census writer; a destructive source-to-surface refresh is never scheduled'],
+  ['customer-state-matrix', 'human-run release-qualification harness (2026-09-30): applies ONE published release through the real '
+    + 'customer door to a COPY of a real install in one customer state at a time; it downloads releases and writes multi-GB '
+    + 'scratch trees, so it is never scheduled. Its install seam is corpus-canary.mjs\'s own (imported), and the states it '
+    + 'found are pinned as unit tests (tests/unit/customer-state-matrix.test.mjs and the per-defect tests).'],
+  ['hook-qualify', 'human-run hook qualification matrix (claude/codex/grok host contracts, repeat + concurrency, optional real-host Layer 2 that spends a real turn per host) run on an idle machine before a hook release; its core and host scanners are imported by it and by tests/unit/hook-qualify.test.mjs, and it is deliberately not scheduled or in CI because Layer 2 needs signed-in hosts'],
   ['grounding-turn-replay', 'human-run measurement harness for grounding-turn-gate.mjs (ADR-0030 #1 and shadow #2/#3): replays real transcripts read-only through the same pure functions the hooks call, sharing completion-claim-replay.mjs\'s turn walkers; nothing to schedule'],
   ['duplicate-gate-replay','human-run tuning harness for plugin/scripts/duplicate-gate.mjs: replays the gate over git history, read-only, when its thresholds are re-tuned; it imports the gate\'s own scoring functions, so there is no second copy to drift and nothing to schedule'],
   ['sync-commands', 'explicit maintainer alias synchronizer; run deliberately before release, never from a lifecycle hook'],
@@ -92,8 +100,9 @@ const STANDALONE = [
   ['lesson-ratify', 'the human control surface — a CLI is its entire purpose'],
   ['lesson-migrate-agentdb', 'one-time reconciliation between the two AgentDB lesson stores and the '
     + 'one plugin lesson store, run deliberately by a human/model, never scheduled. Completion is '
-    + 'proven and kept honest by tests/unit/lesson-migrate-agentdb.test.mjs (0 pending rows), a drift '
-    + 'canary rather than automated invocation — the same shape as lesson-seed/lesson-ratify above.'],
+    + 'checked by tests/diagnostics/lesson-migrate-agentdb.test.mjs (0 pending rows), a machine drift '
+    + 'canary over the developer\'s own AgentDB stores (outside the hermetic suite; run it by hand) rather '
+    + 'than automated invocation — the same shape as lesson-seed/lesson-ratify above.'],
   ['stamp-sweep', 'ADR-056 §2 — the ONE-TIME backfill half of the stamp rule. A human runs it once '
     + '(--apply) to reach the files nobody is editing; the ongoing half is the md-stamp PostToolUse '
     + 'hook, which IS wired. Deliberately not in a gate: it WRITES to documents, and a writer that '
@@ -352,6 +361,11 @@ const CALLER_ROOTS = [
 ];
 const CALLER_EXTS = new Set(['.mjs', '.js', '.sh', '.json', '.html', '.yml', '.yaml']);
 export const REQUIRED_OPERATIONAL_EXPORTS = [
+  // 4.4 update robustness (2026-09-30): bin/install.mjs syncHostsAfterUpdate replaces an owned stale
+  // Console and prunes dead Console receipts through these; host claude/codex calls go through runHostCli.
+  { rel: 'scripts/console-instances.mjs', symbol: 'replaceStaleConsoles' },
+  { rel: 'scripts/console-instances.mjs', symbol: 'readConsoleReceipts' },
+  { rel: 'scripts/host-cli.mjs', symbol: 'runHostCli' },
   { rel: 'scripts/corpus-reconcile.mjs', symbol: 'syncCorpusInputs' },
   { rel: 'scripts/corpus-aggregates.mjs', symbol: 'rebuildCorpusAggregates' },
   { rel: 'scripts/corpus-reconcile.mjs', symbol: 'acquireCorpusGeneration' },