ruvnet-brain 4.0.8 → 4.0.12

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.0.8 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.8-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.0.12 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.0.12-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.**
 

package/bin/install.mjs

@@ -24,7 +24,10 @@ import {
   requiredEmbedderModels,
   missingEmbedderModels,
 } from '../kb/model-requirements.mjs';
-import { mergeManagedCatalog } from '../scripts/model-router-catalog.mjs';
+import { applyManagedCatalogUpdate } from '../scripts/model-router-catalog.mjs';
+import {
+  CONSOLE_RUNTIME_SURFACE, CONSOLE_RUNTIME_IDENTITY_FILE, consoleRuntimeDigest,
+} from '../scripts/console-runtime-identity.mjs';
 
 // SEC-0010 #6 — the Ed25519 PUBLIC key is EMBEDDED here (not a separate file) so the installer's
 // trust root travels with the installer code itself: an attacker who swaps the downloaded bundle
@@ -613,22 +616,17 @@ export function beginConsoleRuntimeTransaction(cacheDir, sourceRoot = REPO_ROOT)
   fs.rmSync(prior, { recursive: true, force: true });
   fs.mkdirSync(staged, { recursive: true, mode: 0o700 });
 
-  const required = [
-    ['console', 'console'],
-    ['scripts', 'scripts'],
-    ['plugin/scripts', 'plugin/scripts'],
-    ['data/model-catalog.json', 'data/model-catalog.json'],
-    ['kb/brain-profile.mjs', 'kb/brain-profile.mjs'],
-    ['bin/install.mjs', 'bin/install.mjs'],
-    ['package.json', 'package.json'],
-  ];
-  for (const [from, to] of required) {
-    const source = path.join(sourceRoot, from);
+  // The copy list IS the generation's digest input (scripts/console-runtime-identity.mjs). Adding a
+  // file the runtime needs adds it to the runtime's identity in the same edit, so an asset can never
+  // again travel separately from the executable that reads it (#76) and a candidate can never again
+  // be indistinguishable from the one it replaces (#79).
+  for (const relative of CONSOLE_RUNTIME_SURFACE) {
+    const source = path.join(sourceRoot, relative);
     if (!fs.existsSync(source)) {
       fs.rmSync(staged, { recursive: true, force: true });
-      throw new Error(`console runtime is incomplete: missing ${from}`);
+      throw new Error(`console runtime is incomplete: missing ${relative}`);
     }
-    const target = path.join(staged, to);
+    const target = path.join(staged, relative);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.cpSync(source, target, { recursive: true, force: true, preserveTimestamps: true });
   }
@@ -661,15 +659,28 @@ export function beginConsoleRuntimeTransaction(cacheDir, sourceRoot = REPO_ROOT)
       throw new Error(`console runtime failed syntax verification: ${path.relative(staged, syntaxTarget)}`);
     }
   }
+  // #76: prove the installed What's New boundary from the staged bytes, not from a file listing. The
+  // executable exits nonzero when its version manifest or curated notes are absent, so a runtime that
+  // would have to tell the user "the notes are unavailable" never activates in the first place.
+  const stagedWhatsNew = path.join(staged, 'plugin', 'scripts', 'whats-new.mjs');
+  const whatsNew = spawnSync(process.execPath, [stagedWhatsNew], { encoding: 'utf8' });
+  if (whatsNew.error || whatsNew.status !== 0) {
+    const detail = (whatsNew.stderr || whatsNew.error?.message || `exit ${whatsNew.status}`).trim();
+    fs.rmSync(staged, { recursive: true, force: true });
+    throw new Error(`console runtime cannot report its own release notes: ${detail}`);
+  }
   const identity = {
     product: 'ruvnet-brain-console-runtime',
     schema: 1,
     apiContract: 1,
     runtimeVersion: packageManifest.version,
     entrypoint: 'scripts/onboarding-console.mjs',
-    sourceSha256: crypto.createHash('sha256').update(fs.readFileSync(stagedEntry)).digest('hex'),
+    // The WHOLE runtime, not just its entrypoint (#79). The launcher compares this against a live
+    // server's self-reported identity, so it has to change whenever anything the server executes or
+    // serves changes — otherwise a stale process passes as current.
+    sourceSha256: consoleRuntimeDigest(staged),
   };
-  fs.writeFileSync(path.join(staged, 'runtime-identity.json'), `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+  fs.writeFileSync(path.join(staged, CONSOLE_RUNTIME_IDENTITY_FILE), `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
 
   let state = 'staged';
   const entry = path.join(runtime, identity.entrypoint);
@@ -2230,6 +2241,37 @@ const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').
 const cronExample = (kbDir) =>
   `47 3 * * *  cd ${kbDir} && ${process.execPath} forge-update.mjs --apply >> ${kbDir}/update.log 2>&1`;
 
+/**
+ * kb/forge-update.mjs exit 11 = "the download completed but the bundle on disk did NOT change"
+ * (its `EXIT_NOT_LANDED`). Duplicated as a literal on purpose: the updater lives in the KB BUNDLE,
+ * which versions and ships independently of this installer, so there is no import to share. The
+ * two are pinned together by tests/unit/update-not-landed-exit.test.mjs, which reads the constant
+ * out of kb/forge-update.mjs and fails if they ever drift.
+ */
+export const UPDATE_NOT_LANDED = 11;
+
+/**
+ * What `--update` does with the KB updater's exit code (issue #106).
+ *
+ * `--update` used to convert an honest failure into a reported success. The updater detected the
+ * problem itself and said so — "UPDATE MISMATCH: SOURCE.json on disk is IDENTICAL to before the
+ * update … REFUSING to report success" — and then the fresh-install FALLBACK below ran, succeeded
+ * at re-installing the very same bytes, and its exit 0 became the exit code of the whole command.
+ * A user's scheduled job read that as success while the corpus had not moved.
+ *
+ * The fallback exists for ONE thing: an old bundle whose canonical manifest URL 404s, where a fresh
+ * install genuinely rescues the user. "Nothing landed" is not that case — it is a TRUE verdict
+ * about an intact KB, and re-downloading the same bundle cannot change it. So that verdict is
+ * terminal and keeps its own exit code; every other failure keeps today's fallback behaviour.
+ */
+export function classifyUpdaterExit(status, { fallbackAllowed = true } = {}) {
+  if (status === 0) return { verdict: 'updated', fallback: false, exitCode: 0 };
+  if (status === UPDATE_NOT_LANDED) {
+    return { verdict: 'not-landed', fallback: false, exitCode: UPDATE_NOT_LANDED };
+  }
+  return { verdict: 'failed', fallback: fallbackAllowed, exitCode: status || 1 };
+}
+
 function missingUpdaterHelp(kbDir) {
   console.error(`\n${c.red('✗ can\'t update:')} ${c.bold('forge-update.mjs')} is missing from ${kbDir}.`);
   console.error(`  Either no brain is installed there, or the bundle predates the self-updater.`);
@@ -2366,12 +2408,29 @@ function runUpdate() {
   // real user, Jan Lafko, hit). NEVER leave the user stranded at a 404: re-run THIS installer as a
   // fresh install, which pulls the latest Release DIRECTLY (releases/latest) and never touches the
   // manifest — so --update always succeeds and self-heals the stale SOURCE.json in one shot.
-  if (updateStatus !== 0 && !process.env.RUVNET_BRAIN_NO_UPDATE_FALLBACK) {
+  //
+  // Scoped again 2026-08-04 (issue #106): "nothing landed" is excluded, because for THAT verdict the
+  // fallback re-installed identical bytes and its exit 0 became the command's exit code, turning the
+  // updater's own correct refusal into a reported success.
+  const outcome = classifyUpdaterExit(updateStatus, {
+    fallbackAllowed: !process.env.RUVNET_BRAIN_NO_UPDATE_FALLBACK,
+  });
+  if (outcome.verdict === 'not-landed') {
+    console.error(`\n    ${c.red('✗ the knowledge bundle did not change.')} The updater downloaded a bundle and refused to`);
+    console.error(`      call it an update because the copy on disk is identical to the one it replaced.`);
+    console.error(`      Nothing is broken and nothing was lost — but this run is ${c.bold('not')} a success, so it exits`);
+    console.error(`      ${c.bold(String(UPDATE_NOT_LANDED))} rather than 0 and a scheduled job will see the failure (issue #106).`);
+    console.error(`      If you believe a newer build exists, check:  ${c.bold('node forge-update.mjs --check')}  in ${kbDir}`);
+    process.exit(outcome.exitCode);
+  }
+  if (outcome.fallback) {
     warn("\nthe bundle's own updater couldn't complete — falling back to a fresh install of the latest Release (this always works)…\n");
     const self = fileURLToPath(import.meta.url);
     const fr = spawnSync(process.execPath, [self, '--force'], { stdio: 'inherit',
       env: { ...process.env, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' } });
     updateStatus = fr.error ? 1 : (fr.status === null ? 1 : fr.status);
+  } else {
+    updateStatus = outcome.exitCode;
   }
   }
   if (updateStatus === 0) {
@@ -2382,6 +2441,25 @@ function runUpdate() {
       updateStatus = 1;
     }
   }
+  // Issue #87: a normal lifecycle update must also carry MANAGED MODEL additions to an existing
+  // user. This call used to live only in offerRouterProfile() — the fresh-install path — so someone
+  // who already had ~/.claude/model-router/catalog.json (i.e. every existing user, the only ones who
+  // can be behind) never received a newly shipped managed candidate no matter how often they
+  // updated. Additive and non-interactive; their overrides win, metered rows are never auto-enabled,
+  // and a failure here is reported but never fails an otherwise-good update.
+  if (updateStatus === 0) {
+    try {
+      const managed = applyManagedCatalogUpdate({
+        routerDir: path.join(os.homedir(), '.claude', 'model-router'),
+        packageRoot: REPO_ROOT,
+      });
+      if (managed.action === 'merged' && managed.added.length) {
+        ok(`model router: added ${managed.added.length} managed model(s) — ${managed.added.join(', ')} (your catalog edits were preserved)`);
+      }
+    } catch (e) {
+      warn(`managed model additions were not merged (${e.message}); your catalog was left unchanged`);
+    }
+  }
   // `--update --auto` = update now AND enroll in Evergreen, so this is the LAST time it's ever run by
   // hand. Only enroll if the update itself succeeded — never promise "you're set forever" on a failed
   // update. enableNightly() prints its own real verification (plist path + launchctl result).
@@ -2975,31 +3053,20 @@ export async function offerRouterProfile() {
   );
 
   fs.mkdirSync(path.join(routerDir, 'bin'), { recursive: true });
-  for (const [src, dst] of [['catalog.template.json', 'catalog.json'], ['policy.default.mjs', 'policy.default.mjs']]) {
-    const s = path.join(pkgRoot, 'config', 'model-router', src);
-    const d = path.join(routerDir, dst);
-    if (!fs.existsSync(s)) continue;
-    if (!fs.existsSync(d)) {
-      fs.copyFileSync(s, d);
-      ok(`installed ${dst} (edit freely — goldie keeps prices fresh where scheduled)`);
-      continue;
-    }
-    if (src === 'catalog.template.json') {
-      try {
-        const existing = JSON.parse(fs.readFileSync(d, 'utf8'));
-        const managed = JSON.parse(fs.readFileSync(s, 'utf8'));
-        const merged = mergeManagedCatalog(existing, managed);
-        if (merged !== existing) {
-          fs.copyFileSync(d, `${d}.pre-managed-merge`);
-          const tmp = `${d}.tmp-${process.pid}`;
-          fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, { mode: 0o600 });
-          fs.renameSync(tmp, d);
-          ok(`merged ${merged.candidates.length - existing.candidates.length} managed subscription model(s); your catalog overrides were preserved`);
-        }
-      } catch (error) {
-        warn(`managed model additions were not merged (${error.message}); your existing catalog was left unchanged`);
-      }
-    }
+  const policySrc = path.join(pkgRoot, 'config', 'model-router', 'policy.default.mjs');
+  const policyDst = path.join(routerDir, 'policy.default.mjs');
+  if (fs.existsSync(policySrc) && !fs.existsSync(policyDst)) {
+    fs.copyFileSync(policySrc, policyDst);
+    ok('installed policy.default.mjs (edit freely — goldie keeps prices fresh where scheduled)');
+  }
+  // ONE implementation of the managed-catalog step, shared with runUpdate() (issue #87). It used to
+  // live here only, which is exactly why existing users never received managed additions.
+  try {
+    const managed = applyManagedCatalogUpdate({ routerDir, packageRoot: pkgRoot });
+    if (managed.action === 'created') ok('installed catalog.json (edit freely — goldie keeps prices fresh where scheduled)');
+    if (managed.action === 'merged') ok(`merged ${managed.added.length} managed subscription model(s); your catalog overrides were preserved`);
+  } catch (error) {
+    warn(`managed model additions were not merged (${error.message}); your existing catalog was left unchanged`);
   }
   let copied = 0;
   // dispatch-receipt + metaharness-receipts added 2026-07-13: without the LOGGER, subagent routing is

package/console/app.js

@@ -2313,6 +2313,25 @@ function renderDistribution(u) {
     el('p', { class: 'fineprint' }, u.note));
 }
 
+// One provider's key chip. THREE states, never two: found, not found, and NOT CHECKED. The third
+// exists because an instrument that could not run has found nothing — it has not found "no key"
+// (issue #86). Pure and total, so the not-checked branch cannot be reached by accident.
+function providerKeyChip(id, keys, keysVerified, names) {
+  const name = names[id] || id;
+  if (!keysVerified) {
+    return el('span', {
+      class: 'plan-key unknown',
+      title: `Not checked: Brain could not load its provider catalog, so it cannot tell whether an API key for ${name} is set on this machine`,
+    }, el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, '?'), ` ${name}`);
+  }
+  const found = !!keys[id];
+  return el('span', {
+    class: `plan-key ${found ? 'yes' : 'no'}`,
+    title: found ? `An API key for ${name} is set on this machine`
+                 : `No API key for ${name} found on this machine`,
+  }, el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, found ? '✓' : '✗'), ` ${name}`);
+}
+
 // Plan block (issue #24, applying sparkling's #21 redesign) — three genuinely different questions
 // used to render as one flat row of identical "chips": which subscription this runs on ("house" — a
 // word nobody outside the source knows), whether cheap-task routing is on, and which OTHER API keys
@@ -2339,19 +2358,21 @@ function renderProviders(sv) {
 
   // BOX 1 — YOUR PLAN. The one choice here that changes cost: which subscription MetaHarness treats
   // as $0. Footer checklist: which OTHER providers have a real API key on this machine — honest now.
+  //
+  // Issue #86: `keys` is only a MEASUREMENT while the verified provider catalog actually loaded. When
+  // that asset was missing from the packaged runtime, the server fell back to native detections and
+  // said so in providerCatalog — and this checklist ignored it, printing a confident "✗ … No API key
+  // for Gemini found on this machine" straight off `keys`. That turned an internal packaging failure
+  // into a stated fact about the user's credentials. Not-checked is now its own third state.
+  const catalogHealth = re.providerCatalog || null;
+  const keysVerified = !catalogHealth
+    || (catalogHealth.keysVerified !== false && catalogHealth.status !== 'degraded');
   const others = ['anthropic', 'openai', 'google', 'xai'].filter((id) => id !== house.provider);
   const checklist = el('div', { class: 'plan-keys' },
-    el('span', { class: 'plan-keys-lab' }, 'Other keys found:'),
-    ...others.map((id) => {
-      const ok = !!keys[id];
-      return el('span', {
-        class: `plan-key ${ok ? 'yes' : 'no'}`,
-        title: ok ? `An API key for ${KEY_NAME[id]} is set on this machine`
-                  : `No API key for ${KEY_NAME[id]} found on this machine`,
-      },
-        el('span', { class: 'plan-key-mark', 'aria-hidden': 'true' }, ok ? '✓' : '✗'),
-        ` ${KEY_NAME[id]}`);
-    }));
+    el('span', { class: 'plan-keys-lab' }, keysVerified ? 'Other keys found:' : 'Other keys:'),
+    ...others.map((id) => providerKeyChip(id, keys, keysVerified, KEY_NAME)),
+    ...(keysVerified ? [] : [el('span', { class: 'plan-keys-note' },
+      `Not checked — Brain could not load its provider catalog${catalogHealth && catalogHealth.detail ? ` (${catalogHealth.detail})` : ''}.`)]));
   const planBox = el('div', { class: 'plan-box' },
     el('span', { class: 'plan-label' }, 'Your plan', infoBtn('Your plan and OpenRouter', PROVIDERS_INFO)),
     head('is-house', houseName, action('Change', 'provider')),

package/console/style.css

@@ -1236,6 +1236,11 @@ details.sub .sub-body > *:first-child { margin-top: 4px; }
 .plan-key-mark { font-weight: 700; }
 .plan-key.yes .plan-key-mark { color: var(--green-text); }
 .plan-key.no, .plan-key.no .plan-key-mark { color: var(--faint); }
+/* Not checked (issue #86): visually distinct from "no key found" so a degraded catalog never reads
+   as a finding about the user's machine. */
+.plan-key.unknown { color: var(--muted); }
+.plan-key.unknown .plan-key-mark { color: var(--amber); }
+.plan-keys-note { flex-basis: 100%; color: var(--muted); font-size: 11.5px; line-height: 1.5; }
 
 /* WP2b — first-run empty state: confident, designed, not an apology */
 .mh-empty {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.8",
+  "version": "4.0.12",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 69 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.0.8",
+  "version": "4.0.12",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.0.8",
+  "version": "4.0.12",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/scripts/continuation-gate.mjs

@@ -160,7 +160,47 @@ const nowMs = Date.now();
 // force. This closes the empty-stdin hole that LOOP-SAFETY 1's `__source` check does not cover.
 if (!hookInput.session_id) process.exit(EXIT_ALLOW);
 
-const open = led.items.filter((i) => !i.done);
+/**
+ * ARTIFACT-DERIVED OPEN WORK — the half that cannot be forgotten.
+ *
+ * WHY THIS EXISTS, measured rather than supposed. On 2026-08-04 the owner asked why the model had
+ * gone back to stopping early, and the ledger answered: 25 items, ZERO open, last written 2026-07-25.
+ * The gate had been structurally silent for ten days. Not broken — starved.
+ *
+ * The cause is the design, not the drift. Until now the ONLY source of "is work outstanding" was
+ * `--commit-to`, i.e. the model noticing its own commitment and recording it. So the guard against
+ * the model stopping early depended on the model remembering to arm it, and the failure mode is
+ * silent in exactly the sessions where it matters most. That is this project's oldest rule broken
+ * inside the mechanism meant to enforce it: status must be DERIVED FROM A VERIFIABLE ARTIFACT,
+ * never asserted.
+ *
+ * So the gate now also reads work that exists whether or not anyone remembered to write it down.
+ * `open-issues.json` is produced by the issue-watch pipeline against the real repo; an issue past
+ * its response SLA is outstanding work by definition, and no amount of forgetting can erase it.
+ *
+ * Deliberately narrow: ONLY SLA breaches, never the full backlog — a permanently non-empty backlog
+ * would make this fire forever, which is nagging, not enforcement. And only a FRESH observation
+ * (<6h, the same window session-start-core uses), because a stale file is not evidence of anything.
+ */
+function artifactOpenWork() {
+  try {
+    const file = process.env.RUVNET_OPEN_ISSUES_FILE
+      || path.join(HOME, '.cache', 'ruvnet-brain', 'open-issues.json');
+    const status = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const observedAt = Date.parse(status?.at || '');
+    if (!Number.isFinite(observedAt) || nowMs - observedAt > 6 * 3600_000) return [];
+    return (Array.isArray(status.issues) ? status.issues : [])
+      .filter((issue) => issue?.breach)
+      .map((issue) => ({
+        text: `issue #${issue.number} on ${status.repo} is ${issue.ageHours}h past its response SLA — ${String(issue.title || '').slice(0, 80)}`,
+        done: false,
+        at: new Date(observedAt).toISOString(),
+        derived: true,
+      }));
+  } catch { return []; }
+}
+
+const open = [...led.items.filter((i) => !i.done), ...artifactOpenWork()];
 if (!open.length) process.exit(EXIT_ALLOW);   // nothing outstanding: silence is correct
 
 /**

package/plugin/scripts/learn-flush.mjs

@@ -14,6 +14,13 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { readStdinBounded } from './hook-input.mjs';
 import { loadRuntimePreferences } from './runtime-preferences.mjs';
+import { resolveRuflo, RUFLO_MISSING } from './ruflo-bin.mjs';
+
+// ONE BOUNDED LINE ON STDERR. stderr because a SessionEnd hook's stdout is not surfaced, and bounded
+// because a hook that prints a stack trace on every `/clear` gets muted — and a muted diagnostic is
+// no diagnostic at all (the same lesson as the session-start line that reported its own defect every
+// session for eight days and went unread).
+const warn = (msg) => { try { process.stderr.write(`learn-flush: ${msg}\n`); } catch { /* stderr gone */ } };
 
 const HOME = os.homedir();
 const PROJECT = process.env.RUVNET_BRAIN_PROJECT_DIR || process.cwd();
@@ -48,7 +55,11 @@ const QUEUE_ROOT = LEARNING_SCOPE === 'user'
   ? path.join(HOME, '.cache', 'ruvnet-brain', 'learn')
   : path.join(PROJECT, '.swarm', 'ruvnet-brain-learn');
 const QUEUE = process.env.LEARN_QUEUE || path.join(QUEUE_ROOT, `session-${SID}.jsonl`);
-const RUFLO = path.join(HOME, '.npm-global/bin/ruflo');
+// Issue #105: this was a hardcoded `path.join(HOME, '.npm-global/bin/ruflo')` — the owner's npm
+// prefix. On any other prefix (Homebrew, nvm, Volta, plain `npm -g`) the path simply did not exist,
+// every feed below threw ENOENT, and every throw landed in a `catch {}` that said nothing. One
+// resolver, shared with distill-project.mjs and health-repair.mjs's original — see ruflo-bin.mjs.
+const RUFLO = resolveRuflo();
 const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
 const MAX_ACTIONS = 8; // bound the work so SessionEnd stays fast
 
@@ -98,7 +109,16 @@ for (const line of lines) {
 const actions = allDistinct.slice(0, MAX_ACTIONS);
 const deferred = allDistinct.slice(MAX_ACTIONS);
 
+// ruflo is genuinely not on this machine. SAY SO — once — and keep the queue. Exiting 0 keeps the
+// best-effort contract (an absent optional learner must never break SessionEnd); saying nothing at
+// all is what turned #105 into eight invisible ENOENTs and a queue that never drained.
+if (!RUFLO && actions.length) {
+  warn(`0/${actions.length} fed — ${RUFLO_MISSING}. The queue is KEPT for retry.`);
+  process.exit(0);
+}
+
 let fed = 0;
+const failures = [];              // WHY each feed failed — the thing `catch {}` used to destroy
 let stoppedAt = actions.length;   // how far the feed actually got before the deadline
 for (let i = 0; i < actions.length; i++) {
   const remaining = DEADLINE - Date.now();
@@ -120,7 +140,22 @@ for (let i = 0; i < actions.length; i++) {
       timeout: Math.min(6000, remaining),
     });
     fed++;
-  } catch { /* best-effort — one slow/failed record must not stall session end */ }
+  } catch (e) {
+    // BEST-EFFORT, NOT SILENT. The old `catch { /* best-effort */ }` swallowed the reason, so a
+    // machine where every call failed looked exactly like one where every call worked: exit 0,
+    // no output, and the only trace a queue that never shrank. "Reports success while doing
+    // nothing" is the defect class this project treats as the worst thing it can ship. Keep going
+    // (one bad record must not stall session end), but keep the reason.
+    failures.push(String(e?.message || e).split('\n')[0].slice(0, 120));
+  }
+}
+// SURFACE IT. Distinct reasons only, at most two: eight copies of the same ENOENT is noise, and the
+// second distinct reason is usually where the real information is.
+if (failures.length) {
+  const distinct = [...new Set(failures)];
+  warn(`${failures.length}/${actions.length} feed call(s) FAILED via ${RUFLO}`
+    + ` — ${distinct.slice(0, 2).join(' | ')}${distinct.length > 2 ? ` (+${distinct.length - 2} more kind(s))` : ''}`
+    + (fed === 0 ? '. Nothing was learned; the queue is KEPT for retry.' : `. ${fed} succeeded.`));
 }
 // Whatever the deadline cut off is WORK, not waste: it goes back on the front of the queue so the
 // next flush continues from there. Dropping it would turn a time limit into the same silent data

package/plugin/scripts/project-identity.mjs

@@ -0,0 +1,89 @@
+// project-identity.mjs — ONE answer to "which directory is this, and have I seen it already?"
+//
+// WHY THIS EXISTS. Two user-filed bugs, #85 and #107, are the same defect: the product derives a
+// project's location independently at each site and the sites then disagree.
+//
+//   #85  The PreCompact producer wrote its receipt under `CLAUDE_PROJECT_DIR`; the Console probe
+//        that reports whether a receipt exists looked under `process.cwd()`. Launch the Console
+//        from a subdirectory of the project and it warns "no supported PreCompact snapshot found"
+//        about a snapshot it had itself just written. Nothing was broken except the agreement.
+//
+//   #107 `candidateRoots()` returned BOTH `~/Code` and `~/code`, which on APFS are one directory
+//        with one inode. Every project under them was scanned, counted and summed twice, so the
+//        machine-wide memory total read exactly 2x — silently, confidently, in the one figure the
+//        Console exists to make trustworthy. `path.resolve()` was the guard, and it normalises
+//        `.`/`..` only: it case-folds nothing and resolves no symlinks, which the guard's own
+//        comment ("e.g. a symlink") shows it was believed to do.
+//
+// WHY DEVICE+INODE RATHER THAN LOWER-CASING. Lower-casing is a guess about the filesystem, and it
+// is wrong on the machines that would suffer most: Linux, and case-sensitive APFS volumes, where
+// `Code` and `code` really are two projects and folding them would DELETE one from the report.
+// `st_dev` + `st_ino` is not a guess — it is the filesystem's own answer, correct in both
+// directions on every volume, and it settles symlinks and bind mounts in the same stroke. The
+// case-insensitivity probe the reporter suggested (write a temp file, stat the other spelling)
+// would also work, but it writes to the user's disk to learn something `stat` already knows.
+//
+// `fs.realpathSync.native` is the OS canonicaliser: it resolves symlinks AND returns the case as
+// stored on disk. Plain `fs.realpathSync` is a JavaScript reimplementation that does symlinks only
+// — measured on this repo's own machine, `realpathSync('~/code')` stays `~/code` while
+// `realpathSync.native('~/code')` returns `~/Code`. That one missing word is the whole of #107.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const defaultRealpath = (value) => fs.realpathSync.native(value);
+const defaultStat = (value) => fs.statSync(value, { bigint: true });
+
+/** The operating system's own spelling of an existing path, or null when it cannot be resolved. */
+export function canonicalPath(value, { realpath = defaultRealpath } = {}) {
+  if (typeof value !== 'string' || !value) return null;
+  try { return realpath(value); } catch { return null; }
+}
+
+/**
+ * A key that is equal for two names of one directory and different for two directories.
+ * Falls back to the canonical path when the volume reports no usable inode (some Windows and
+ * network mounts report 0) — never worse than the raw string compare it replaces.
+ */
+export function pathIdentity(value, { realpath = defaultRealpath, stat = defaultStat } = {}) {
+  const canonical = canonicalPath(value, { realpath });
+  if (!canonical) return null;
+  try {
+    const info = stat(canonical);
+    if (info?.ino) return `${info.dev}:${info.ino}`;
+  } catch { /* unreadable — the canonical spelling is still a better key than the raw one */ }
+  return canonical;
+}
+
+/** True when both names denote the same existing directory or file. */
+export function sameLocation(a, b, options = {}) {
+  const left = pathIdentity(a, options);
+  return left !== null && left === pathIdentity(b, options);
+}
+
+/** True when `child` is `root` or lies beneath it, compared canonically rather than by raw string. */
+export function contains(root, child, options = {}) {
+  const canonicalRoot = canonicalPath(root, options);
+  const canonicalChild = canonicalPath(child, options);
+  if (!canonicalRoot || !canonicalChild) return false;
+  if (sameLocation(canonicalRoot, canonicalChild, options)) return true;
+  const relative = path.relative(canonicalRoot, canonicalChild);
+  return Boolean(relative) && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
+}
+
+/**
+ * THE project directory. The PreCompact snapshot producer and the Console probe that detects the
+ * snapshot both call this, so they cannot disagree about where the project is (#85).
+ *
+ * `CLAUDE_PROJECT_DIR` wins only when the current directory actually lies inside it. Containment,
+ * not mere presence, is what makes the two sides agree by construction: a hook and a Console
+ * launched anywhere within one project resolve to that project's root, while a caller that hands
+ * over an unrelated directory (a test fixture, an explicit `--project`) is never overruled by an
+ * environment variable it knows nothing about.
+ */
+export function projectDirectory({ env = process.env, cwd = process.cwd(), ...options } = {}) {
+  const here = canonicalPath(cwd, options) || path.resolve(cwd);
+  const declared = typeof env.CLAUDE_PROJECT_DIR === 'string' && env.CLAUDE_PROJECT_DIR.trim()
+    ? canonicalPath(env.CLAUDE_PROJECT_DIR, options)
+    : null;
+  return declared && contains(declared, here, options) ? declared : here;
+}

package/plugin/scripts/ruflo-bin.mjs

@@ -0,0 +1,81 @@
+/**
+ * ruflo-bin.mjs — the ONE place this repo decides WHERE the global `ruflo` binary is.
+ *
+ * WHY THIS FILE EXISTS. Issues #99 and #105 are one defect filed twice: `scripts/distill-project.mjs`
+ * and `plugin/scripts/learn-flush.mjs` each hardcoded `~/.npm-global/bin/ruflo` — the owner's npm
+ * prefix, nobody else's. On a Homebrew, nvm, Volta, or plain `npm -g` install that path does not
+ * exist, so #99 died with "ruflo is not at ~/.npm-global/bin/ruflo" and #105 failed every feed
+ * silently — both on machines where ruflo was installed and sitting on PATH the whole time.
+ *
+ * `health-repair.mjs` had already fixed exactly this, and its header says why: "Telling someone their
+ * tool is missing when it is on their PATH is the product lying, and it is unfalsifiable from their
+ * side: they cannot see why we looked in one place." That fix lived as a private function inside one
+ * file, so its two siblings kept the bug — the identical shape ADR-021 was written about ("One class,
+ * fixed in one file, regenerated in the sibling"). So the resolver moves here instead of being pasted
+ * a third time.
+ *
+ * MECHANISM — the hardened form, not the first draft. Two resolvers already existed in this repo:
+ *   • health-repair.mjs      (2026-07-21)  preferred path, then `sh -lc 'command -v ruflo'`
+ *   • capability-registry.mjs (2026-07-22)  preferred path, then a plain PATH walk, NO shell
+ * The second IS the first one, hardened, and it says so in place: `-l` sources the user's entire
+ * profile — every export, shim, and one-off line anyone has ever pasted into .profile — as the price
+ * of answering "where is ruflo?". Resolving a name against directories is all `command -v` was ever
+ * wanted for here, and it needs no shell at all. This module takes that version. Adopting the older
+ * mechanism would mean re-introducing, in a shared module, a bug the repo had already fixed one file
+ * over.
+ *
+ * ORDER, and each step earns its place:
+ *   1. RUFLO_BIN, if set, is AUTHORITATIVE — returned as given, whether or not it exists. An explicit
+ *      override that quietly falls back to some other ruflo is not an override, and the caller's
+ *      "not at <path>" message has to name the path the user actually asked for.
+ *   2. ~/.npm-global/bin/ruflo — Rule 21's ONE global binary, checked first so a machine that has it
+ *      never depends on PATH ordering.
+ *   3. A PATH walk — the entire point of #99/#105: an installed ruflo living anywhere else.
+ *   4. null — "I could not find it", said plainly. Never guess a path and then blame the user for it.
+ *
+ * Rule 21 is untouched by this: still ONE ruflo, still the global one, never `npx ruflo@latest`. This
+ * resolves WHERE that one global binary is rather than assuming everyone's prefix matches the owner's.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Locate the global ruflo. LOCATES, NEVER EXECUTES — no shell, no daemon, no side effects.
+ *
+ * @param {{ env?: Record<string, string|undefined>, home?: string }} [opts]
+ * @returns {string|null} path to ruflo, or null when it is genuinely not on this machine.
+ */
+export function resolveRuflo({ env = process.env, home = os.homedir() } = {}) {
+  if (env.RUFLO_BIN) return env.RUFLO_BIN;
+
+  // On Windows a global npm ruflo is `ruflo.cmd`; the extensionless sibling is a POSIX shell wrapper
+  // that Node cannot exec (and refuses to spawn without a shell since CVE-2024-27980).
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+
+  // The preferred path needs that SAME rule. It first checked a bare `ruflo` only, so on Windows it
+  // either missed the real `ruflo.cmd` entirely or returned the POSIX wrapper the comment above
+  // says is unrunnable — and the caller then reported "ruflo is not at ~/.npm-global/bin/ruflo" to
+  // someone who had ruflo installed. That is the exact complaint #99 and #105 were filed about,
+  // reintroduced one platform over.
+  const preferredDir = path.join(home, '.npm-global', 'bin');
+  for (const ext of exts) {
+    const cand = path.join(preferredDir, `ruflo${ext}`);
+    try { if (fs.existsSync(cand) && fs.statSync(cand).isFile()) return cand; } catch { /* unreadable */ }
+  }
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const cand = path.join(dir, `ruflo${ext}`);
+      try { if (fs.existsSync(cand) && fs.statSync(cand).isFile()) return cand; } catch { /* unreadable PATH entry */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * What to say when resolveRuflo() returns null. ONE wording, so every caller reports the same thing
+ * and names both places it looked — the diagnostic #99 and #105 never gave anyone.
+ */
+export const RUFLO_MISSING = 'ruflo was not found in ~/.npm-global/bin or anywhere on your PATH'
+  + ' — install it with `npm i -g ruflo@latest`, or set RUFLO_BIN to its full path';

package/plugin/scripts/session-snapshot-hook.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createSessionSnapshot } from './session-snapshot-contract.mjs';
+import { projectDirectory } from './project-identity.mjs';
 
 function regularOrAbsent(file) {
   try {
@@ -30,5 +31,7 @@ export function writeSessionSnapshot(projectDir, event) {
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
-  writeSessionSnapshot(process.env.CLAUDE_PROJECT_DIR || process.cwd(), process.argv[2] || 'SessionEnd');
+  // projectDirectory() is the SAME derivation the Console's detector uses. Deriving it here
+  // independently is what let this hook write a receipt the Console then reported as missing (#85).
+  writeSessionSnapshot(projectDirectory(), process.argv[2] || 'SessionEnd');
 }