ruvnet-brain 4.0.36 → 4.2.2-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.36 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.36-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.2.2-dev — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.2.2--dev-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -56,7 +56,30 @@
 
 ---
 
-## What's new in 4.0 — it anticipates, and it learns whether it was right
+## What's new in 4.2 — it loads what rUv ships, without being asked
+
+**The corpus stopped drifting behind the org.** Until 4.2 nothing ever ingested a new repo: the
+nightly refreshed lessons, health and proofs and contained *zero* ingestion, so a repo entered the
+brain only when a human typed the command. `brain-stamp.mjs` had been measuring that gap every
+night, but nothing consumed it until the ingestion loop shipped.
+
+- **187 stores, up from 69.** Everything rUv ships that has content, pulled in and kept level by
+  `scripts/ingest-new-repos.mjs` running nightly, newest-first. Empty repos (`size=0KB`) are skipped
+  rather than retried forever — a permanent nightly failure that is actually correct behaviour
+  trains you to ignore the failure line, which is how a real one would hide inside it.
+- **174 capability cards, up from 39.** Ingesting a repo is not the same as making it reachable: a
+  store with no card is *dark* — valid bytes no by-description query can find. Cards are written
+  from each repo's **own** description and README, never from its name, and where there is no
+  grounded source text the store is **left dark and reported** rather than given an invented
+  sentence. 13 remain dark for exactly that reason.
+- **The download barely grew** for 2.4x the corpus — most of rUv's repos are small, so the bulk
+  of the bundle was always the large ones. (No size is hand-typed here: a number typed onto a
+  public page rots the moment the next bundle is built, and this repo gates against exactly that.)
+- **The nightly stopped discarding its own writes.** It hardcoded a node whose ABI did not match
+  agentdb's binding, so `lesson-bridge --apply` and `learning-replay` wrote into a silent
+  non-persistent fallback. It now resolves an ABI-matched interpreter and fails loudly instead.
+
+## What's new in 4.2 — it anticipates, and it learns whether it was right
 
 **Building toward L4/L5 (3.9.x, dev).** The mechanisms for the top two rungs of the proactivity
 ladder are built and wired — but they are **not yet verified to 4.0's bar**, which requires all five
@@ -445,7 +468,7 @@ The brain answers **both** kinds of questions. **Name the repo or ask something
 
 ## What it covers
 
-71 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked into its own canonical RVF segment. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
+77 of rUv's repos in the [ruvnet](https://github.com/ruvnet) org — the reusable **building blocks** you'd actually compose into a system — each deep-walked into its own canonical RVF segment. The core blocks below also carry symbol indexes and capability cards (the 8 newest repos are findable by name; their capability cards are coming).
 
 ![The RuvNet stack the brain covers](primer/assets/diagrams/ruvnet-stack.svg)
 
@@ -504,7 +527,7 @@ Most of the numbers above were tuned against. [`evals/held-out.json`](evals/held
 
 **Why not let an LLM grade it?** Because on this very repo an LLM panel scored a **zero-citation answer 98/100**. Model-as-judge is blind to the one failure that matters here.
 
-Current baseline (n=120, [`evals/baseline.json`](evals/baseline.json)): **grounded 100/100 · routed 63/80 · abstain 18/20 · banner 20/20**, promotion gated on Wilson lower bounds. The routing misses are recorded, not tuned away — the recurring shapes: `"generate tests and find coverage gaps"` cites agentic-qe's real test generator, which lives *vendored inside the ruflo repo*, so the answer is right and the repo label is a corpus-attribution artifact; `"spend less money on model calls"` cites a genuine `agentic-qe/docs/guides/cheaper-model-eval-lanes.md`, the same cost/orchestration overlap noted above.
+Baseline **measured 2026-07-10** (n=120, [`evals/baseline.json`](evals/baseline.json)): **grounded 100/100 · routed 63/80 · abstain 18/20 · banner 20/20**, promotion gated on Wilson lower bounds. The routing misses are recorded, not tuned away — the recurring shapes: `"generate tests and find coverage gaps"` cites agentic-qe's real test generator, which lives *vendored inside the ruflo repo*, so the answer is right and the repo label is a corpus-attribution artifact; `"spend less money on model calls"` cites a genuine `agentic-qe/docs/guides/cheaper-model-eval-lanes.md`, the same cost/orchestration overlap noted above.
 
 **Query it directly (CLI):**
 
@@ -522,7 +545,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 64 public stores · 138,140 public source chunks (71 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 70 public stores · 140,520 public source chunks (77 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { readAll as readAllReadiness, aggregate as aggregateReadiness } from '../plugin/scripts/mcp-readiness.mjs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import readline from 'node:readline';
 import crypto from 'node:crypto';
@@ -545,6 +546,250 @@ async function unzipInto(zipPath, cacheDir, sourceDir = null) {
   ok(`brain unpacked to ${cacheDir}`);
 }
 
+/**
+ * ISSUE #128 / #153 — STALE PLUGIN GENERATIONS MAY STILL BACK LIVE SESSIONS.
+ *
+ * `pruneUnlistedStores` below states the rule this repo already believes: "an update is a
+ * replacement, not an overlay." That rule was applied to KB stores and never to the plugin cache.
+ *
+ * Measured on the maintainer's machine 2026-08-10: the registry names ONE generation and the cache
+ * held TWENTY-EIGHT, 22 MB, each a complete generation with its own `skills/` and `hooks/`. Claude
+ * Code resolves skills by walking that directory rather than by honouring `installPath`, so old
+ * generations keep answering. One session announced three different versions, none of them the one
+ * executing, and the stale block's mandatory phrasing — "must say ONE version, never a second
+ * number" — made the assistant state the wrong version authoritatively in its first sentence.
+ *
+ * Worse than cosmetic: the three blocks CONTRADICT each other inside one session (one says do not
+ * restart, one says an update is landing, one mandates a third version), so whichever the model
+ * obeys, the user is misinformed by a source that sounds definitive.
+ *
+ * Registry reachability identifies candidates; it is not deletion proof. Claude freezes
+ * CLAUDE_PLUGIN_ROOT at session start, so an unregistered generation can remain live until that
+ * session exits. Modern roots expose `.in_use` PID-incarnation leases. Live or ambiguous leases
+ * retain the complete root; dead leases are collected. Legacy roots without the protocol receive
+ * a 14-day compatibility grace.
+ *
+ * WHAT MAKES DELETION SAFE HERE, since this removes directories from someone's machine:
+ *   • The registry is the ONLY authority. Unreadable, missing, or naming no ruvnet-brain install →
+ *     nothing is removed and a reason is returned. Never guess what to delete — the same discipline
+ *     as pruneUnlistedStores' catch, for a far larger blast radius.
+ *   • Only siblings of a registered installPath are considered, so the scan cannot wander.
+ *   • A candidate must LOOK like a generation (its own .claude-plugin/plugin.json). Anything else is
+ *     someone else's data and is left alone.
+ *   • Symlinks are never followed or removed: scripts/dev-plugin-link.sh links a dev checkout in
+ *     here, and deleting through that link would delete the working tree.
+ *   • EVERY registered installPath is protected, not just the first — the plugin may legitimately be
+ *     installed at both user and project scope, and treating one as stale would delete a live install.
+ *   • Registered generations are excluded by RESOLVED PATH, never by version string.
+ *   • The registry is re-read immediately before deletion; any byte change retains the candidate.
+ *   • Malformed, unreadable, symlinked, live, or unverifiable lease state fails closed.
+ *   • Report-only unless `apply` is set, and every removal is returned by name, so a silent sweep is
+ *     impossible.
+ */
+export function prunePluginGenerations({
+  registryPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json'),
+  apply = false,
+  now = () => Date.now(),
+  graceMs = 14 * 24 * 60 * 60 * 1000,
+  processIdentity = pluginProcessIdentity,
+} = {}) {
+  const nothing = (why) => ({ active: [], stale: [], marked: [], removed: [], bytes: 0, staleBytes: 0, cleanupBlocked: [], why });
+  let registryRaw;
+  let registry;
+  try {
+    registryRaw = fs.readFileSync(registryPath, 'utf8');
+    registry = JSON.parse(registryRaw);
+  } catch (e) {
+    return nothing(`plugin registry unreadable (${e.code || e.message}) — refusing to remove anything`);
+  }
+  const active = Object.entries(registry?.plugins || {})
+    .filter(([name]) => /^ruvnet-brain@/.test(name))
+    .flatMap(([, v]) => (Array.isArray(v) ? v : []))
+    .map((e) => e?.installPath)
+    .filter((p) => typeof p === 'string' && p);
+  if (!active.length) return nothing('no ruvnet-brain install is registered — refusing to remove anything');
+
+  const keep = new Set(active.map((p) => path.resolve(p)));
+  const stale = [];
+  for (const parent of new Set(active.map((p) => path.dirname(path.resolve(p))))) {
+    let names = [];
+    try { names = fs.readdirSync(parent); } catch { continue; }
+    for (const name of names) {
+      const full = path.resolve(parent, name);
+      if (keep.has(full)) continue;
+      let st;
+      try { st = fs.lstatSync(full); } catch { continue; }
+      if (st.isSymbolicLink() || !st.isDirectory()) continue;
+      if (!fs.existsSync(path.join(full, '.claude-plugin', 'plugin.json'))) continue;
+      stale.push({ path: full, version: name, bytes: dirBytes(full) });
+    }
+  }
+  const staleBytes = stale.reduce((n, s) => n + s.bytes, 0);
+  if (!apply) return { active, stale, marked: [], removed: [], bytes: 0, staleBytes, cleanupBlocked: [], why: null };
+
+  const marked = [];
+  const removed = [];
+  const cleanupBlocked = [];
+  let freed = 0;
+  for (const candidate of stale) {
+    const marker = path.join(candidate.path, '.orphaned_at');
+    if (!fs.existsSync(marker)) {
+      const temporary = `${marker}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
+      try {
+        fs.writeFileSync(temporary, String(now()), { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temporary, marker);
+        marked.push(candidate.version);
+      } catch {
+        try { fs.rmSync(temporary, { force: true }); } catch { /* retain on ambiguity */ }
+      }
+    }
+
+    let orphanedAt;
+    try {
+      const markerStat = fs.lstatSync(marker);
+      if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+        cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at is not a trusted file' });
+        continue;
+      }
+      orphanedAt = Number(fs.readFileSync(marker, 'utf8').trim());
+      if (!Number.isFinite(orphanedAt) || orphanedAt <= 0) {
+        cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at is malformed' });
+        continue;
+      }
+    } catch {
+      cleanupBlocked.push({ version: candidate.version, reason: '.orphaned_at could not be inspected' });
+      continue;
+    }
+
+    const leaseDir = path.join(candidate.path, '.in_use');
+    let leaseCapable = false;
+    let leaseNames = [];
+    try {
+      if (fs.existsSync(leaseDir)) {
+        const leaseDirStat = fs.lstatSync(leaseDir);
+        if (leaseDirStat.isSymbolicLink() || !leaseDirStat.isDirectory()) {
+          cleanupBlocked.push({ version: candidate.version, reason: '.in_use is not a trusted directory' });
+          continue;
+        }
+        leaseCapable = true;
+        leaseNames = fs.readdirSync(leaseDir);
+      }
+    } catch {
+      cleanupBlocked.push({ version: candidate.version, reason: '.in_use could not be inspected' });
+      continue;
+    }
+
+    if (!leaseCapable && now() - orphanedAt < graceMs) continue;
+    let safeToReap = true;
+    for (const leaseName of leaseNames) {
+      const leasePath = path.join(leaseDir, leaseName);
+      let lease;
+      try {
+        const leaseStat = fs.lstatSync(leasePath);
+        if (!leaseStat.isFile() || leaseStat.isSymbolicLink()) throw new Error('not a trusted file');
+        lease = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+        if (!Number.isSafeInteger(lease?.pid) || lease.pid <= 0 || typeof lease?.procStart !== 'string' || !lease.procStart.trim()) {
+          throw new Error('malformed');
+        }
+      } catch {
+        cleanupBlocked.push({ version: candidate.version, reason: `lease ${leaseName} is malformed or unreadable` });
+        safeToReap = false;
+        break;
+      }
+      const state = processIdentity(lease);
+      if (state !== 'dead') {
+        cleanupBlocked.push({ version: candidate.version, reason: `lease ${leaseName} is ${state === 'live' ? 'live' : 'ambiguous'}` });
+        safeToReap = false;
+        break;
+      }
+      try { fs.rmSync(leasePath); } catch {
+        cleanupBlocked.push({ version: candidate.version, reason: `dead lease ${leaseName} could not be removed` });
+        safeToReap = false;
+        break;
+      }
+    }
+    if (!safeToReap) continue;
+
+    // The host registry can advance while the collector scans. Any byte change invalidates the
+    // original authority snapshot; retain every candidate rather than deleting on stale evidence.
+    let currentRaw;
+    try { currentRaw = fs.readFileSync(registryPath, 'utf8'); } catch { continue; }
+    if (currentRaw !== registryRaw) continue;
+    try {
+      fs.rmSync(candidate.path, { recursive: true });
+      removed.push(candidate.version);
+      freed += candidate.bytes;
+    } catch { /* retained for a later pass */ }
+  }
+  return {
+    active, stale, marked, removed, bytes: freed, staleBytes, cleanupBlocked,
+    why: stale.length
+      ? 'lease-proven orphan reconciliation; legacy generations receive a 14-day grace and live or ambiguous generations are retained'
+      : null,
+  };
+}
+
+/** Verify the exact PID incarnation recorded by a plugin generation lease. */
+function pluginProcessIdentity({ pid, procStart }) {
+  try { process.kill(pid, 0); } catch (error) {
+    return error?.code === 'ESRCH' ? 'dead' : 'unknown';
+  }
+  const result = process.platform === 'win32'
+    ? spawnSync('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `$p=Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().ToString('ddd MMM dd HH:mm:ss yyyy',[Globalization.CultureInfo]::InvariantCulture)`,
+    ], { encoding: 'utf8' })
+    : spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+      encoding: 'utf8', env: { ...process.env, TZ: 'UTC', LC_ALL: 'C', LANG: 'C' },
+    });
+  if (result.status !== 0 || !String(result.stdout || '').trim()) return 'unknown';
+  return String(result.stdout).trim() === procStart.trim() ? 'live' : 'dead';
+}
+
+/** Size of a directory tree, best-effort — used only to report what was or would be freed. */
+function dirBytes(dir) {
+  let total = 0;
+  const walk = (d) => {
+    let items = [];
+    try { items = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const it of items) {
+      const p = path.join(d, it.name);
+      if (it.isSymbolicLink()) continue;
+      if (it.isDirectory()) { walk(p); continue; }
+      try { total += fs.statSync(p).size; } catch { /* vanished mid-walk */ }
+    }
+  };
+  walk(dir);
+  return total;
+}
+
+
+/**
+ * Every relative module `server.mjs` needs, transitively — read from the source, never restated.
+ *
+ * Bounded and cycle-safe. Returns `{ spec, from }` with the spec EXACTLY as written, because the
+ * copy target is resolved against the destination using that same spec: preserving the specifier is
+ * what makes `./sibling.mjs` and `../scripts/sibling.mjs` both land where the server will look.
+ */
+export function serverDependencies(source, seen = new Set()) {
+  const out = [];
+  const walk = (file, specPrefix) => {
+    if (seen.has(file)) return;
+    seen.add(file);
+    let src = '';
+    try { src = fs.readFileSync(file, 'utf8'); } catch { return; }
+    for (const m of src.matchAll(/^\s*(?:import|export)[^'"\n]*from\s*['"](\.[^'"]+)['"]/gm)) {
+      const spec = specPrefix ? path.join(specPrefix, m[1]) : m[1];
+      const from = path.resolve(path.dirname(file), m[1]);
+      if (out.some((d) => d.from === from)) continue;
+      out.push({ spec: spec.startsWith('.') ? spec : `./${spec}`, from });
+      walk(from, path.dirname(spec));
+    }
+  };
+  walk(source, '');
+  return out;
+}
+
 export function pruneUnlistedStores(cacheDir) {
   try {
     const manifest = JSON.parse(fs.readFileSync(path.join(cacheDir, 'manifest.json'), 'utf8'));
@@ -1002,7 +1247,23 @@ export function codexStatus({
   const section = m ? text.slice(m.index).split(/\n[ \t]*\[/, 1)[0] : '';
   const timeoutMatch = /(?:^|\n)[ \t]*startup_timeout_sec\s*=\s*(\d+)/.exec(section);
   const startupTimeoutSec = timeoutMatch ? Number(timeoutMatch[1]) : null;
+  // ISSUE #133: read the DERIVED machine state, not one contested file. Every MCP shell used to
+  // overwrite `mcp-readiness.json`, so this read the state of whichever process wrote last and
+  // presented it as the state of the machine. Per-process records are aggregated (degraded wins over
+  // ready — a machine with one broken shell HAS a broken shell) with dead pids pruned on read. The
+  // legacy file is still the fallback, so a machine mid-update, whose server predates the split,
+  // reports something true rather than nothing.
   const readinessReceipt = (() => {
+    try {
+      const live = readAllReadiness(brainHome);
+      if (live.length) {
+        const agg = aggregateReadiness(live);
+        // Carry the winning record forward so every downstream field (pid, workerPid, phase) still
+        // describes ONE real process rather than a blend of several.
+        const chosen = live.find((r) => r.state === agg.state) || live[0];
+        return { ...chosen, ...agg, shells: live.length };
+      }
+    } catch { /* fall through to the legacy single file */ }
     try { return JSON.parse(fs.readFileSync(path.join(brainHome, 'mcp-readiness.json'), 'utf8')); }
     catch { return null; }
   })();
@@ -1106,27 +1367,46 @@ 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' };
-  }
-  if (!fs.existsSync(runtimePreferencesSource)) {
-    if (announce) warn('MCP runtime-preferences module missing from this bundle — Codex left untouched (non-fatal)');
+  // THE DEPENDENCY LIST IS DERIVED FROM server.mjs ITSELF, never hand-maintained.
+  //
+  // It used to name `managed-cli-interface.mjs` and `runtime-preferences.mjs` as literals — a second
+  // copy of the server's own import graph, and therefore a fact in two places with no producer. It
+  // failed exactly the way that always fails: ADR-067 added ONE import to server.mjs, this list did
+  // not know, and the Codex host shipped a server whose sibling was absent. The npm-tarball suite
+  // caught it as "no reply to initialize in 15s" — a dead server, on the packaging boundary, from a
+  // change that looked local.
+  //
+  // Relative specifiers are preserved verbatim on copy, so `./x.mjs` and `../scripts/y.mjs` both
+  // land where the server will look for them, and the walk is transitive because a dependency's own
+  // dependency is no less required.
+  const deps = serverDependencies(source);
+  const missing = deps.filter((d) => !fs.existsSync(d.from));
+  if (missing.length) {
+    if (announce) warn(`MCP server dependency missing from this bundle (${missing.map((d) => d.spec).join(', ')}) — 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');
-  const runtimePreferencesPath = path.join(path.dirname(serverDir), 'scripts', 'runtime-preferences.mjs');
+  // Named for the return contract that callers and tests already depend on — RESOLVED from the
+  // derived list rather than re-stated, so they cannot drift from what is actually copied.
+  const depTarget = (suffix) => {
+    const hit = deps.find((d) => d.spec.endsWith(suffix));
+    return hit ? path.resolve(serverDir, hit.spec) : null;
+  };
+  const managedCliPath = depTarget('managed-cli-interface.mjs');
+  const runtimePreferencesPath = depTarget('runtime-preferences.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.
-  fs.mkdirSync(path.dirname(runtimePreferencesPath), { recursive: true });
-  atomicReplace(runtimePreferencesPath, (tmp) => fs.copyFileSync(runtimePreferencesSource, tmp));
-  atomicReplace(managedCliPath, (tmp) => fs.copyFileSync(managedCliSource, tmp));
+  // Dependencies FIRST, server last: if the server swap fails, the previously registered server
+  // remains byte-intact and continues to import backward-compatible modules at the same paths.
+  for (const dep of deps) {
+    const target = path.resolve(serverDir, dep.spec);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    atomicReplace(target, (tmp) => fs.copyFileSync(dep.from, tmp));
+  }
   atomicReplace(serverPath, (tmp) => fs.copyFileSync(source, tmp));
   if (fs.existsSync(hookWrapperSource)) {
     fs.mkdirSync(path.dirname(hookWrapperPath), { recursive: true });
@@ -2254,10 +2534,73 @@ const TEST_MODE = process.env.RUVNET_BRAIN_TEST === '1';
 const IMPORT_ONLY = process.env.RUVNET_BRAIN_IMPORT_ONLY === '1';
 const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
-// The same nightly command, cron-flavored — the pattern forge-update.mjs documents in its header.
-// 03:47 on purpose: an off-hour minute, so it never piles onto the :00 cron rush.
+/**
+ * THE ONE SCHEDULED-UPDATE COMMAND (issue #129). Every scheduler — cron, systemd, LaunchAgent —
+ * runs THIS, and it is byte-for-byte the entrypoint plugin/scripts/host-update.mjs already uses on
+ * SessionStart.
+ *
+ * It used to be `forge-update.mjs --apply`, which advances the KB BYTES ONLY. That path never
+ * reaches host convergence, so a scheduled run could move the corpus forward while the Stable Spine,
+ * the Claude and Codex plugin payloads, the Console runtime and `host-convergence.json` all stayed
+ * behind — silently, on a schedule, with the update log reporting success. A machine updating itself
+ * into a split state overnight is worse than one that never updates, because nothing looks wrong.
+ *
+ * Two entrypoints for one job is the defect; naming it once here is the fix. 03:47 on purpose: an
+ * off-hour minute, so it never piles onto the :00 cron rush.
+ */
+const NIGHTLY_ARGV = ['--yes', 'ruvnet-brain@latest', '--update', '--host-sync-only', '--no-nightly-prompt'];
+const nightlyCommand = () => `npx ${NIGHTLY_ARGV.join(' ')}`;
+
+/**
+ * Absolute path to npx, resolved at install time — a scheduler has no shell profile, so a bare name
+ * would resolve only on installs whose npx happens to sit in launchd's minimal PATH. Falls back to
+ * the bare name rather than refusing: a wrong-but-present command is fixable by the user, whereas a
+ * refusal to install any schedule leaves them with nothing.
+ */
+function npxPath() {
+  const local = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npx.cmd' : 'npx');
+  if (fs.existsSync(local)) return local;
+  try {
+    const r = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['npx'], { encoding: 'utf8' });
+    const found = String(r.stdout || '').split('\n')[0].trim();
+    if (found && fs.existsSync(found)) return found;
+  } catch { /* not on PATH here either — fall through */ }
+  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+/**
+ * Add the nightly line to the user's crontab, idempotently (issue #129).
+ *
+ * Read-modify-write through `crontab -l` / `crontab -` because that is the only portable interface;
+ * writing /var/spool/cron directly needs root and bypasses the daemon's reload. Every failure mode
+ * returns a REASON rather than a boolean: "no crontab binary" and "the write was rejected" need
+ * different things from the user, and collapsing them into "failed" is how a person ends up
+ * re-running a command that can never work.
+ */
+export function installCronEntry(line, { run = spawnSync } = {}) {
+  const marker = 'ruvnet-brain@latest';
+  const list = run('crontab', ['-l'], { encoding: 'utf8' });
+  if (list.error) return { ok: false, why: 'no crontab command was found on this system' };
+  // Exit 1 with no output is the documented "this user has no crontab yet" case, not an error.
+  const current = String(list.stdout || '');
+  if (current.split('\n').some((l) => l.includes(marker) && !l.trim().startsWith('#'))) {
+    return { ok: true, already: true };
+  }
+  const next = `${current.replace(/\n*$/, '')}\n${line}\n`.replace(/^\n+/, '');
+  const write = run('crontab', ['-'], { input: next, encoding: 'utf8' });
+  if (write.error) return { ok: false, why: `crontab could not be written (${write.error.message})` };
+  if (write.status !== 0) {
+    return { ok: false, why: `crontab rejected the entry (exit ${write.status})${String(write.stderr || '').trim() ? `: ${String(write.stderr).trim()}` : ''}` };
+  }
+  return { ok: true, already: false };
+}
+
+/** launchd's own minimal PATH, plus the directory node/npx actually live in on this machine. */
+const launchdPath = () => [...new Set([
+  path.dirname(process.execPath), path.dirname(npxPath()),
+  '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin',
+])].filter(Boolean).join(':');
 const cronExample = (kbDir) =>
-  `47 3 * * *  cd ${kbDir} && ${process.execPath} forge-update.mjs --apply >> ${kbDir}/update.log 2>&1`;
+  `47 3 * * *  ${nightlyCommand()} >> ${kbDir}/update.log 2>&1`;
 
 /**
  * kb/forge-update.mjs exit 11 = "the download completed but the bundle on disk did NOT change"
@@ -2344,6 +2687,21 @@ export function syncHostsAfterUpdate(cacheDir = resolvedKbDir(), {
   const applied = runStableSpine(apply);
   const okApplied = !applied.error && applied.status === 0;
   if (okApplied) {
+    // ISSUE #153 — running Claude sessions freeze their plugin root. Collect only generations whose
+    // leases prove that exact PID incarnation dead, or legacy roots past the compatibility grace.
+    try {
+      const gens = prunePluginGenerations({ apply: true });
+      if (gens.removed.length) {
+        ok(`pruned ${gens.removed.length} stale plugin generation(s), freed ${(gens.bytes / 1048576).toFixed(1)} MB: ${gens.removed.join(', ')}`);
+      }
+      if (gens.cleanupBlocked?.length) {
+        warn(`plugin cleanup retained ${gens.cleanupBlocked.length} generation(s): ${gens.cleanupBlocked.map((item) => `${item.version} (${item.reason})`).join(', ')}`);
+      } else if (!gens.removed.length && gens.why) {
+        warn(`stale plugin generations were not pruned: ${gens.why}`);
+      }
+    } catch (e) {
+      warn(`stale plugin generations were not pruned (${e.message}); nothing was removed`);
+    }
     const receiptPath = path.join(brainHome, 'host-convergence.json');
     try {
       runtimeTransaction.activate();
@@ -2496,12 +2854,24 @@ function enableNightly() {
   const kbDir = resolvedKbDir();
 
   if (process.platform !== 'darwin') {
-    info('The LaunchAgent scheduler is macOS-only (for now).');
-    info("On this platform, schedule the bundle's self-updater with cron — the pattern");
-    info('forge-update.mjs itself documents:');
-    console.log(`\n    ${c.bold(cronExample(kbDir))}\n`);
+    // ISSUE #129 — A COMMAND NAMED `--enable-nightly` MAY NOT EXIT 0 WITHOUT ENABLING ANYTHING.
+    //
+    // This printed a cron recipe and returned success. Every automated check of "is Evergreen on?"
+    // — a provisioning script, a CI step, a user reading the exit code — was told yes on a machine
+    // where no schedule existed. So it now INSTALLS the entry, and when it cannot, it says so and
+    // exits non-zero rather than dressing a manual instruction up as a completed action.
+    const line = cronExample(kbDir);
+    const installed = installCronEntry(line);
+    if (installed.ok) {
+      ok(`installed a nightly crontab entry (03:47 local):\n\n    ${c.bold(line)}\n`);
+      info(`(${c.bold('crontab -l')} to see it, ${c.bold('crontab -e')} to remove it.)`);
+      return;
+    }
+    console.error(`\n${c.red('✗ nightly updates were NOT enabled:')} ${installed.why}`);
+    info('\nAdd this line by hand and nightly updates will work exactly as they do on macOS:');
+    console.log(`\n    ${c.bold(line)}\n`);
     info(`(${c.bold('crontab -e')}, paste the line, save. Remove the line to disable.)`);
-    return; // exit 0 — the user got the working recipe
+    process.exit(1);   // the caller asked for a schedule and does not have one
   }
 
   info(`brain dir: ${c.bold(kbDir)}`);
@@ -2526,12 +2896,24 @@ function enableNightly() {
 <dict>
   <key>Label</key>
   <string>${NIGHTLY_LABEL}</string>
+  <!-- Issue #129: the SAME host-convergent entrypoint the session updater runs, not the KB-only
+       forge-update.mjs it used to schedule. See NIGHTLY_ARGV. Still no `/bin/sh -c` (ADR-038) —
+       this execs npx directly. -->
   <key>ProgramArguments</key>
   <array>
-    <string>${xmlEscape(process.execPath)}</string>
-    <string>forge-update.mjs</string>
-    <string>--apply</string>
+    <string>${xmlEscape(npxPath())}</string>
+${NIGHTLY_ARGV.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n')}
   </array>
+  <!-- launchd starts agents with a MINIMAL PATH (/usr/bin:/bin:/usr/sbin:/sbin) - it does not read
+       the user's shell profile. npx resolved by bare name would therefore fail to launch on every
+       Homebrew/nvm/Volta install, which is most of them, and the only symptom would be a nightly
+       that silently never ran. The absolute path above is resolved at install time; PATH is also set
+       so npx can find node and the package's own bin shims once it starts. -->
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(launchdPath())}</string>
+  </dict>
   <key>WorkingDirectory</key>
   <string>${xmlEscape(kbDir)}</string>
   <key>StandardOutPath</key>