ruvnet-brain 4.0.8 → 4.0.24

package/plugin/scripts/memory-doctor.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// memory-doctor.mjs — does this project's AgentDB actually LEARN, or does it just record?
+//
+// WHY THIS EXISTS (2026-07-14). For two days I told Stuart "AgentDB is fixed / verified / 33 of 33."
+// It was never fixed, and I never lied — I ran a check that COULD NOT FAIL:
+//     ruflo memory store  ->  ruflo memory search  ->  got a row back  ->  "healthy"
+// That exercises `memory_entries`, a key-value table with an HNSW index. It says NOTHING about
+// whether anything is embedded, distilled, or learned. It would pass on a database with the entire
+// intelligence substrate surgically removed — which is exactly the database most of his projects have.
+//
+// LIVENESS IS NOT HEALTH. This file is the referee that makes that distinction impossible to fudge.
+//
+// THE ROOT CAUSE IT FOUND (measured, not theorised):
+//   memory_entries.embedding is NULL for ~99% of rows in most projects.
+//     ruvnet-brain          1,023 entries · 99.8% embedded ->   456 patterns   (learns)
+//     ugo-ai-register-now   7,214 entries ·  100% embedded -> 3,610 patterns   (learns)
+//     AMBUILANCE_INVENTORY 11,133 entries ·  0.03% embedded ->     1 pattern    (dead)
+//     flighttest           19,108 entries ·   0.3% embedded ->    12 patterns   (dead)
+//   No embedding -> no semantic recall AND nothing for distill to consume (ADR-174 explicitly skips
+//   rows with no parseable vector) -> no patterns -> no episodes -> no intelligence. The whole chain
+//   snaps at the first link.
+//
+//   And the rows are unembedded because of WHO WRITES THEM: namespaces `hooks:pre-bash`,
+//   `hooks:post-bash`, `command-history`, `command-results`, `performance-metrics` — telemetry
+//   emitted by the `npx @claude-flow/cli hooks pre-command/post-command` calls wired into ~190 hooks
+//   across 16 projects. Five unembedded rows per Bash command. They bury the real memories under
+//   thousands of rows of "I ran a command", none of it recallable or distillable.
+//
+// GROUNDED IN rUv's SOURCE (not invented here):
+//   ruflo/v3/docs/adr/ADR-174-memory-distillation-self-optimization.md  (ACCEPTED) — the
+//     RETRIEVE->JUDGE->DISTILL->CONSOLIDATE pipeline, and the finding that the substrate was empty
+//     because the consolidate worker was a stub. rUv hit this exact wall and shipped `memory distill`.
+//   agentdb/src/controllers/ReflexionMemory.ts — storeEpisode()/retrieveRelevant()/getCritiqueSummary().
+//     Its retrieval INNER-JOINs episode_embeddings, which is empty everywhere, so reflexion recall
+//     currently returns nothing on every project. That is a SEPARATE layer from ADR-174 distillation;
+//     do not conflate them (I did, and had to retract it).
+//
+// This tool DIAGNOSES ONLY. It opens every database read-only and writes nothing, anywhere.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath, pathIdentity } from './project-identity.mjs';
+
+const HOME = os.homedir();
+const DEFAULT_SCAN_ROOTS = ['Code', 'code', 'src', 'source', 'projects', 'dev', 'work'];
+
+// Telemetry namespaces: high-volume, unembedded, zero-signal. Written by the npx hook calls.
+// Counted separately so "you have 11,000 memories" is never mistaken for "you have 11,000 lessons".
+const NOISE_NS = new Set([
+  'hooks:pre-bash', 'hooks:post-bash', 'hooks:pre-edit', 'hooks:post-edit',
+  'command-history', 'command-results', 'performance-metrics', 'notifications',
+]);
+
+// A doctor that cannot tell "the patient is dead" from "I could not find the patient" is worse than
+// no doctor. The FIRST version of this function swallowed every sqlite error and returned 0 — so a
+// database it could not even OPEN (spaces in the path broke the file: URI) was reported as
+// "0 memories, 0 patterns", indistinguishable from a genuinely empty store. That is the exact
+// can't-fail check this whole file exists to abolish, reproduced inside it. Caught by running it.
+//
+// Now: every query returns {ok, value} or {ok:false, err}. Unreadable is UNKNOWN, never zero, and
+// UNKNOWN is reported loudly rather than averaged into a reassuring number.
+// `mode=ro` ALONE CANNOT OPEN A RESTING WAL DATABASE, and that is not an edge case — it is the normal
+// state of every store nobody is currently using. A WAL database needs its -shm shared-memory segment
+// to be read, and a read-only connection is not allowed to create one, so SQLite returns CANTOPEN(14).
+//
+// MEASURED (fresh WAL db, same file, three ways):
+//     sidecars removed + mode=ro              -> Error: unable to open database file (14)
+//     sidecars present + mode=ro              -> 1
+//     sidecars removed + mode=ro&immutable=1  -> 1, and `ls` shows no -wal/-shm created
+//
+// This was live on the owner's own machine while it shipped: `.swarm/memory.db-{shm,wal}` had been
+// renamed `.CORRUPT-20260714-144824`, so every single read of the repo's 16MB store returned
+// unreadable, and the console reported memory distillation as permanently UNKNOWN on a healthy store.
+// Three retries two seconds apart cannot fix a structural refusal; they just make it slow.
+//
+// `immutable=1` is GATED, because it promises SQLite the file will not change underneath it — a
+// promise nobody can keep about a database with a live writer, and breaking it returns torn or
+// stale rows rather than an error. So it is used ONLY when both sidecars are absent, which is the
+// observable signature of "no process has this open in WAL mode", and the absence is re-checked
+// AFTER the read so a writer that arrived mid-flight invalidates the result instead of being
+// reported as fact. A locked store still yields an honest unreadable.
+const walSidecarsPresent = (db) => fs.existsSync(`${db}-wal`) || fs.existsSync(`${db}-shm`);
+
+const q = (db, sql) => {
+  // encodeURI, not raw interpolation: "Helix - Personal Health Intelligence Platform" has spaces,
+  // and sqlite3 rejects the URI outright (error 14) rather than falling back to a plain path.
+  const base = `file:${encodeURI(db)}?mode=ro`; // read-only: this process will never be a second writer
+  const run = (uri) => execFileSync('sqlite3', [uri, sql], { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+  // MODE IS CHOSEN BEFORE THE OPEN, FROM A FACT ON DISK — NOT AFTER CATCHING WHICHEVER ERROR A
+  // GIVEN SQLITE BUILD HAPPENS TO THROW. This used to try plain `mode=ro` first and only add
+  // `immutable=1` after catching "unable to open database file (14)". CONFIRMED LIVE 2026-07-26
+  // (Docker ubuntu:24.04, apt sqlite3 3.45.1 — the exact version this repo's "check" CI job
+  // installs): on a resting WAL db with no sidecars, plain `mode=ro` does NOT throw there the way
+  // macOS's bundled 3.51.0 does — it succeeds AND silently vivifies `-shm`/`-wal` as a side effect
+  // of establishing WAL-index shared memory for the reader. No exception meant the catch block's
+  // sidecar check — the only place this was ever guarded — never ran, so a "read-only" diagnosis
+  // left litter in the caller's directory on every ubuntu CI run.
+  //
+  // The fix does not depend on which behavior a given SQLite build has. It decides the mode from a
+  // fact available before either would be attempted: do the sidecars already exist?
+  //   - present -> a live/resting WAL with real frames; open plain `mode=ro` and let a genuine
+  //     pending WAL be read normally (immutable=1 here would be a promise we cannot make).
+  //   - absent  -> nothing to replay; open `mode=ro&immutable=1` STRAIGHT AWAY — the one mode both
+  //     measured SQLite builds leave clean. Plain mode=ro never gets the chance to vivify a -shm
+  //     file nobody asked for.
+  const restingWal = fs.existsSync(db) && !walSidecarsPresent(db);
+  const uri = restingWal ? `${base}&immutable=1` : base;
+
+  try {
+    const value = run(uri);
+    // Belt and suspenders for a third SQLite build we have not measured: a read that started with
+    // no sidecars must end with no sidecars. If one appeared anyway — a fresh concurrent writer, or
+    // another version-specific quirk — the bytes just read cannot be trusted, and this read's own
+    // litter is removed rather than left in the caller's directory.
+    if (restingWal && walSidecarsPresent(db)) {
+      for (const suffix of ['-wal', '-shm']) {
+        try { fs.unlinkSync(`${db}${suffix}`); } catch { /* best-effort cleanup only */ }
+      }
+      return { ok: false, err: 'a writer opened the store mid-read' };
+    }
+    return { ok: true, value, viaImmutable: restingWal || undefined };
+  } catch (e) {
+    const err = String(e.stderr || e.message || '');
+    // "no such table/column" is SCHEMA VARIANCE (an older store) — a real, reportable fact.
+    if (/no such (table|column)/.test(err)) return { ok: true, value: null, missing: true };
+    // Anything else means we could not read the database, and we must say so, not guess zero.
+    return { ok: false, err: err.split('\n')[0].slice(0, 60) };
+  }
+};
+// n() returns null for "unknown" and a number only when we genuinely counted. Callers must handle null.
+const n = (r) => (r.ok ? (r.value === null || r.value === '' ? null : parseInt(r.value, 10)) : null);
+
+export function candidateRoots({
+  home = HOME,
+  configPath = path.join(home, '.claude', 'ruvnet-brain', 'config.json'),
+} = {}) {
+  let configured = [];
+  let configuredCount = 0;
+  try {
+    const value = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (Array.isArray(value.scanRoots)) {
+      configuredCount = value.scanRoots.length;
+      configured = value.scanRoots.filter((item) => typeof item === 'string' && item.trim());
+    }
+  } catch { /* absent or malformed config does not erase the common roots */ }
+
+  // Keyed by pathIdentity, not by the spelling. DEFAULT_SCAN_ROOTS deliberately lists both `Code`
+  // and `code` so neither convention is missed, and on a case-insensitive volume those are ONE
+  // directory — which the old Set-of-strings admitted twice and then scanned, counted and summed
+  // twice (#107). On a case-sensitive volume they are two inodes and both are still kept.
+  const roots = new Map();
+  const addRoot = (value) => {
+    const absolute = path.isAbsolute(value) ? value : path.join(home, value);
+    const canonical = canonicalPath(absolute);
+    try {
+      if (canonical && fs.statSync(canonical).isDirectory()) {
+        const identity = pathIdentity(canonical) ?? canonical;
+        if (!roots.has(identity)) roots.set(identity, canonical);
+        return true;
+      }
+    } catch { /* missing/non-directory roots are not candidates on this machine */ }
+    return false;
+  };
+  for (const value of DEFAULT_SCAN_ROOTS) addRoot(value);
+  let validConfigured = 0;
+  for (const value of configured) {
+    if (addRoot(value)) validConfigured += 1;
+  }
+  if (configuredCount > 0 && validConfigured === 0) {
+    throw new Error('configured scanRoots contain no existing directories');
+  }
+  return [...roots.values()].sort();
+}
+
+// Keyed by pathIdentity for the same reason candidateRoots is: one store reached by two names is
+// one store. Values are the canonical spelling, which is what every caller reads back.
+function storesBelow(root) {
+  const out = new Map();
+  const canonicalRoot = canonicalPath(root);
+  if (!canonicalRoot) return out;
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name === 'node_modules' || e.name === '.git') continue;
+      if (e.name === '.swarm') {
+        const db = path.join(dir, '.swarm/memory.db');
+        const canonical = canonicalPath(db);
+        if (canonical) out.set(pathIdentity(canonical) ?? canonical, canonical);
+        continue;
+      }
+      if (e.name.startsWith('.') && e.name !== '.swarm') continue;
+      walk(path.join(dir, e.name), depth + 1);
+    }
+  };
+  walk(canonicalRoot, 0);
+  return out;
+}
+
+export function findStores(root) {
+  const out = new Map();
+  const collect = (found) => { for (const [identity, db] of found) if (!out.has(identity)) out.set(identity, db); };
+  if (root !== undefined) {
+    collect(storesBelow(root));
+    return [...out.values()].sort();
+  }
+
+  for (const candidate of candidateRoots()) collect(storesBelow(candidate));
+  // These two stores intentionally sit outside the project-root convention. They belong only to
+  // the fleet-wide no-argument scan; an explicit root must remain genuinely scoped.
+  for (const extra of [path.join(HOME, '.claude/.swarm/memory.db'), path.join(HOME, 'cognitum-trader/.swarm/memory.db')]) {
+    const canonical = canonicalPath(extra);
+    if (canonical) collect([[pathIdentity(canonical) ?? canonical, canonical]]);
+  }
+  return [...out.values()].sort();
+}
+
+export function displayStoreName(db, home = HOME) {
+  const canonicalDb = canonicalPath(db) || path.resolve(db);
+  const project = path.dirname(path.dirname(canonicalDb));
+  const canonicalHome = canonicalPath(home) || path.resolve(home);
+  const relative = path.relative(canonicalHome, project);
+  if (relative === '') return '~';
+  if (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    return `~/${relative.split(path.sep).join('/')}`;
+  }
+  return project;
+}
+
+export function diagnose(db) {
+  const name = displayStoreName(db);
+
+  const ic = q(db, 'PRAGMA integrity_check;');
+  if (!ic.ok) {
+    // UNREADABLE is its own verdict. It is NOT "empty". Reporting it as zero was the bug.
+    return { name, db, unreadable: ic.err, findings: [`UNREADABLE: ${ic.err}`], learns: false };
+  }
+  const integrity = (ic.value || '').split('\n')[0] || 'unknown';
+
+  const total = n(q(db, 'SELECT count(*) FROM memory_entries;'));
+  const embedded = n(q(db, "SELECT count(*) FROM memory_entries WHERE embedding IS NOT NULL AND length(embedding)>0;"));
+  const nsRes = q(db, 'SELECT namespace, count(*) FROM memory_entries GROUP BY namespace;');
+  const nsRows = (nsRes.value || '').split('\n').filter(Boolean).map((l) => l.split('|'));
+  const noise = nsRows.filter(([ns]) => NOISE_NS.has(ns)).reduce((a, [, c]) => a + (parseInt(c, 10) || 0), 0);
+  const real = total === null ? null : total - noise;
+
+  const patterns = n(q(db, 'SELECT count(*) FROM reasoning_patterns;'));
+  const patternEmb = n(q(db, 'SELECT count(*) FROM pattern_embeddings;'));
+  const episodes = n(q(db, 'SELECT count(*) FROM episodes;'));
+  const epEmb = n(q(db, 'SELECT count(*) FROM episode_embeddings;'));
+  const critiques = n(q(db, 'SELECT count(critique) FROM episodes;'));
+  const skills = n(q(db, 'SELECT count(*) FROM skills;'));
+  const promoted = n(q(db, 'SELECT count(*) FROM reasoning_patterns WHERE promoted=1;')); // absent in older schemas -> null
+
+  // A store with no memory_entries table at all is a DIFFERENT thing from an empty one. Say which.
+  if (total === null) {
+    return { name, db, integrity, schemaless: true,
+             findings: ['no memory_entries table — pre-AgentDB schema, never initialised'], learns: false };
+  }
+
+  const cover = total ? embedded / total : 0;
+  const distilled = real ? patterns / real : 0;
+
+  // Each finding names the ONE thing that is false, in the order the chain breaks. A doctor that
+  // lists twelve symptoms teaches nothing; the first broken link is the only one worth fixing today.
+  const findings = [];
+  if (integrity !== 'ok') findings.push(`CORRUPT (${integrity})`);
+  if (total === 0) findings.push('no memories at all');
+  else if (cover < 0.5) findings.push(`only ${(cover * 100).toFixed(1)}% embedded — nothing can be recalled or distilled`);
+  else if (patterns === 0) findings.push('embedded but never distilled — run: ruflo memory distill run');
+  else if (distilled < 0.05) findings.push(`${patterns} patterns from ${real} real memories — distill barely ran`);
+  if (noise > real && noise > 500) findings.push(`${noise} telemetry rows from npx hooks bury ${real} real memories`);
+  if (episodes > 0 && epEmb === 0) findings.push('reflexion recall dead (0 episode_embeddings — INNER JOIN returns nothing)');
+  if (episodes > 0 && critiques === 0) findings.push('0 critiques — episodes carry no lessons');
+
+  const learns = cover >= 0.5 && patterns > 0 && distilled >= 0.05;
+  return { name, db, integrity, total, embedded, cover, noise, real, patterns, patternEmb,
+           episodes, epEmb, critiques, skills, promoted, distilled, findings, learns };
+}
+
+// Does this project wire `npx <claude-flow|ruvector>` into its tool-use hooks? Those hooks write
+// telemetry rows (hooks:pre-bash, command-history, ...) with no embedding. THE PREDICTION THIS TESTS:
+// if they are the cause of dead memory, then hooked projects should be dead and unhooked ones alive.
+// If a single project breaks that correlation, the theory is wrong and must be discarded.
+export function hasNpxHooks(db) {
+  const projDir = path.dirname(path.dirname(db));
+  for (const f of ['.claude/settings.json', '.claude/settings.local.json']) {
+    const p = path.join(projDir, f);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(p, 'utf8'));
+      const hooks = JSON.stringify(s.hooks || {});
+      if (/npx\s+(-y\s+)?(@?claude-flow|ruvector|aqe)/.test(hooks)) return true;
+    } catch { /* unparseable settings — cannot claim either way */ }
+  }
+  return false;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]).endsWith('memory-doctor.mjs')) {
+  const stores = findStores();
+  const rows = stores.map((db) => ({ ...diagnose(db), npxHooks: hasNpxHooks(db) }));
+  const w = Math.min(34, Math.max(...rows.map((r) => r.name.length), 8));
+  const readable = rows.filter((r) => !r.unreadable && !r.schemaless);
+
+  console.log(`\n  AgentDB fleet — ${rows.length} stores found\n`);
+  console.log(`  ${'PROJECT'.padEnd(w)} ${'MEMORIES'.padStart(9)} ${'EMBED%'.padStart(7)} ${'NOISE'.padStart(7)} ${'PATTERNS'.padStart(8)} ${'npx?'.padStart(5)}  LEARNS?`);
+  console.log(`  ${'-'.repeat(w)} ${'-'.repeat(9)} ${'-'.repeat(7)} ${'-'.repeat(7)} ${'-'.repeat(8)} ${'-'.repeat(5)}  -------`);
+  for (const r of readable.sort((a, b) => b.total - a.total)) {
+    if (r.total === 0) continue;
+    const pct = (r.cover * 100).toFixed(1) + '%';
+    console.log(`  ${r.name.slice(0, w).padEnd(w)} ${String(r.total).padStart(9)} ${pct.padStart(7)} ${String(r.noise).padStart(7)} ${String(r.patterns).padStart(8)} ${(r.npxHooks ? 'YES' : 'no').padStart(5)}  ${r.learns ? 'yes' : 'NO'}`);
+  }
+
+  // THE FALSIFICATION TEST — stated before the answer is known, so it can actually fail.
+  const withMem = readable.filter((r) => r.total >= 50);
+  const hookedDead = withMem.filter((r) => r.npxHooks && !r.learns).length;
+  const hookedAlive = withMem.filter((r) => r.npxHooks && r.learns).length;
+  const cleanAlive = withMem.filter((r) => !r.npxHooks && r.learns).length;
+  const cleanDead = withMem.filter((r) => !r.npxHooks && !r.learns).length;
+  console.log(`\n  HYPOTHESIS: the npx tool-use hooks cause dead memory (unembedded telemetry floods the store).`);
+  console.log(`  ${'npx hooks + DEAD memory  (predicted)'.padEnd(42)} ${hookedDead}`);
+  console.log(`  ${'npx hooks + LIVE memory  (CONTRADICTS)'.padEnd(42)} ${hookedAlive}`);
+  console.log(`  ${'no hooks  + LIVE memory  (predicted)'.padEnd(42)} ${cleanAlive}`);
+  console.log(`  ${'no hooks  + DEAD memory  (CONTRADICTS)'.padEnd(42)} ${cleanDead}`);
+  const contra = hookedAlive + cleanDead;
+  console.log(`  => ${contra === 0 ? 'hypothesis SURVIVES: no contradicting project' : `hypothesis is INCOMPLETE: ${contra} project(s) contradict it — the npx hooks are NOT the whole story`}`);
+
+  const unreadable = rows.filter((r) => r.unreadable);
+  const schemaless = rows.filter((r) => r.schemaless);
+  if (unreadable.length) { console.log(`\n  UNREADABLE (NOT "empty" — we could not open these):`); unreadable.forEach((r) => console.log(`    ${r.name} — ${r.unreadable}`)); }
+  if (schemaless.length) console.log(`\n  no memory_entries table (never initialised): ${schemaless.length}`);
+
+  const dead = readable.filter((r) => !r.learns && r.total > 0);
+  console.log(`\n  ${readable.filter((r) => r.learns).length} of ${readable.filter((r) => r.total > 0).length} populated stores actually learn. ${dead.length} record and forget.\n`);
+  for (const r of dead.slice(0, 10)) console.log(`  ${r.name}\n     - ${r.findings.join('\n     - ')}`);
+
+  // Non-zero when the fleet is not learning: no scheduled job — and no assistant — can ever again
+  // call this "verified" unless the numbers actually agree.
+  process.exit(dead.length || unreadable.length ? 1 : 0);
+}

package/plugin/scripts/nightly-controller.mjs

@@ -0,0 +1,98 @@
+// nightly-controller.mjs — a thin adapter around the installer's one scheduler implementation.
+//
+// It does not write a plist, call launchctl, or invent platform behavior. Both the installer and the
+// console reach the same `bin/install.mjs --enable-nightly/--disable-nightly` door; this adapter only
+// supplies structured status and captures its exit result for the console.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// ROOT is the tree that holds `bin/install.mjs`, and it is resolved by an EXACT layout test rather
+// than by `..` — because `..` means two different things since this file moved into the payload
+// (ADR-065). From `<root>/scripts/` it was the root; from `<root>/plugin/scripts/` it is
+// `<root>/plugin`, and `<root>/plugin/bin/install.mjs` does not exist. Caught live by
+// console-apply-timings.test.mjs, which drove a real /api/apply through the console and got
+// `Error: Cannot find module '<root>/plugin/bin/install.mjs'` back inside a 200 response — a remedy
+// that reported failure honestly, but failed for a packaging reason nobody would have guessed.
+//
+// The test is exact, not a heuristic: this file's directory IS `<candidate>/plugin/scripts` if and
+// only if `<candidate>` is a non-flattened root. A flattened install (the Spine's versions/<gen>/,
+// the plugin cache's <ver>/) has no `plugin/` level, so `../..` is some unrelated parent and the
+// answer falls back to `..` — where `bin/` also does not exist, and applyNightlyChoice() then
+// reports that honestly instead of silently spawning nothing. nightlyStatus() only reads a plist and
+// needs no installer at all, so status stays correct in every layout.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..', '..', 'plugin', 'scripts') === HERE
+  ? path.resolve(HERE, '..', '..')
+  : path.resolve(HERE, '..');
+const INSTALLER = path.join(ROOT, 'bin', 'install.mjs');
+
+/**
+ * THE NIGHTLY JOB'S NAME, stated once for everything that has to recognise it.
+ *
+ * Exported because issue #113 was two files disagreeing about this exact string with nothing to
+ * notice: bin/install.mjs writes a LaunchAgent labelled `com.ruvnet.brain-update`, while
+ * capability-registry.mjs looked for launchd jobs matching `/(nightly|refresh)/` — so the console
+ * reported "not installed" about the very job the installer had loaded, scheduled and run. A label
+ * is an interface between the writer and everyone who looks for it; spelling it out per reader is
+ * how the two drift apart silently.
+ *
+ * bin/install.mjs still holds its own literal (installer-owned code, changed under its own review);
+ * tests/unit/nightly-job-identity.test.mjs asserts the two are the same string, so a drift is a red
+ * test rather than a capability that quietly disappears from the console.
+ */
+export const NIGHTLY_LABEL = 'com.ruvnet.brain-update';
+
+export function nightlyArtifact({ env = process.env, platform = process.platform } = {}) {
+  const home = env.HOME || os.homedir();
+  return {
+    supported: platform === 'darwin',
+    platform,
+    path: path.join(home, 'Library', 'LaunchAgents', `${NIGHTLY_LABEL}.plist`),
+    label: NIGHTLY_LABEL,
+  };
+}
+
+export function nightlyStatus(options = {}) {
+  const artifact = nightlyArtifact(options);
+  if (!artifact.supported) {
+    return { state: 'unsupported', evidence: `No reversible scheduler adapter is implemented for ${artifact.platform}.`, artifact };
+  }
+  const present = fs.existsSync(artifact.path);
+  return {
+    state: present ? 'on' : 'off',
+    evidence: present ? `LaunchAgent plist exists at ${artifact.path}` : `No LaunchAgent plist at ${artifact.path}`,
+    artifact,
+  };
+}
+
+export function applyNightlyChoice(enabled, options = {}) {
+  if (typeof enabled !== 'boolean') return { ok: false, log: 'nightly must be true or false' };
+  const env = options.env || process.env;
+  const before = nightlyStatus({ ...options, env });
+  if (!before.artifact.supported) return { ok: false, state: before, log: before.evidence };
+  const run = spawnSync(process.execPath, [
+    options.installer || INSTALLER,
+    enabled ? '--enable-nightly' : '--disable-nightly',
+  ], {
+    env: { ...env, RUVNET_BRAIN_IMPORT_ONLY: '0' },
+    cwd: options.cwd || ROOT,
+    encoding: 'utf8',
+    shell: false,
+    timeout: options.timeout || 30_000,
+  });
+  const after = nightlyStatus({ ...options, env });
+  const desired = enabled ? 'on' : 'off';
+  const ok = !run.error && run.status === 0 && after.state === desired;
+  return {
+    ok,
+    before,
+    after,
+    log: ok
+      ? `Nightly refresh is ${desired}; verified from ${after.artifact.path}.`
+      : `Nightly refresh did not reach ${desired}: ${run.error?.message || run.stderr?.trim() || run.stdout?.trim() || `exit ${run.status}`}`,
+  };
+}

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/runtime-preferences.mjs

@@ -66,6 +66,18 @@ function validSettings(raw = {}) {
     newProjectDefaults: source.newProjectDefaults === true,
     advocacy: Number.isInteger(source.advocacy) && source.advocacy >= 1 && source.advocacy <= 5
       ? source.advocacy : 3,
+    // ADR-063 / issue #103. Unknown keys are DROPPED by this function, so a setting absent here is
+    // silently unreadable no matter what the Console writes — which is how the first cut of the
+    // managed-memory boundary read `advise` even when the file said `block`.
+    //
+    // NOTE THE DUPLICATION, deliberately not "fixed" here: scripts/user-settings.mjs SETTINGS_SCHEMA
+    // is the authority for these keys and this is a second enumeration of it. Deriving one from the
+    // other is the obvious move and it is the WRONG one — this file ships inside plugin/, that one
+    // does not, so the import would resolve in the checkout and throw ERR_MODULE_NOT_FOUND on a real
+    // install. Same trap as kb/forge-update.mjs reaching for ../scripts. The honest fix is a drift
+    // test that reads both files, not a bridge that breaks installs.
+    managedMemoryBoundary: ['advise', 'read-only', 'block'].includes(source.managedMemoryBoundary)
+      ? source.managedMemoryBoundary : 'advise',
   };
 }
 
@@ -263,6 +275,12 @@ export function seedProjectDefaults(options = {}) {
 
 if (process.argv.includes('--learning-scope')) {
   process.stdout.write(`${loadRuntimePreferences().values.learningScope}\n`);
+} else if (process.argv.includes('--managed-memory-boundary')) {
+  // ADR-063 / issue #103. hijack-ruvnet.sh is POSIX sh and must not parse JSON, so it asks here —
+  // the same idiom learn-capture.sh already uses for --learning-scope. Falls back to the shipped
+  // default rather than erroring: a hook that cannot read a preference must never refuse a command
+  // because of it, so an unreadable settings file degrades to `advise`, which blocks nothing.
+  process.stdout.write(`${loadRuntimePreferences().values.managedMemoryBoundary || 'advise'}\n`);
 } else if (process.argv.includes('--seed-project')) {
   const result = seedProjectDefaults();
   if (!result.ok) process.exitCode = 1;