ruvnet-brain 4.0.1 → 4.0.2

package/scripts/memory-doctor.mjs

@@ -0,0 +1,271 @@
+#!/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';
+
+const HOME = os.homedir();
+
+// 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 findStores(root = path.join(HOME, 'Code')) {
+  const 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');
+        if (fs.existsSync(db)) out.push(db);
+        continue;
+      }
+      if (e.name.startsWith('.') && e.name !== '.swarm') continue;
+      walk(path.join(dir, e.name), depth + 1);
+    }
+  };
+  walk(root, 0);
+  // Stores outside ~/Code exist too (~/.claude, ~/cognitum-trader). A one-level glob missed 32 of
+  // these — including Helix — and that miss is exactly how "33/33 verified" got reported.
+  for (const extra of [path.join(HOME, '.claude/.swarm/memory.db'), path.join(HOME, 'cognitum-trader/.swarm/memory.db')]) {
+    if (fs.existsSync(extra) && !out.includes(extra)) out.push(extra);
+  }
+  return out.sort();
+}
+
+export function diagnose(db) {
+  const name = db.replace(HOME + '/Code/', '').replace(HOME + '/', '~/').replace('/.swarm/memory.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/scripts/model-catalog.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// scripts/model-catalog.mjs — the accessor over data/model-catalog.json (the ADR-0016 verified data).
+// The router-optimizer + console read the user's per-HOUSE frontier from here, so the escalation target
+// and savings baseline are personalized to the person's own stack — Claude shop → Fable 5, ChatGPT/Codex
+// shop → GPT-5.6 Sol, Gemini shop → Gemini 3.1 Pro, Grok shop → Grok 4.5 — never defaulted to one house.
+// Every model returned here is gated by verify-model-catalog.mjs (a wrong/stale one fails the build).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+export function loadCatalog(p) {
+  const file = p || process.env.RUVNET_MODEL_CATALOG || path.join(ROOT, 'data/model-catalog.json');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/** Follow aliasOf (e.g. codex → openai). Returns {name, provider}. */
+function resolve(catalog, name) {
+  let p = catalog.providers?.[name];
+  if (p?.aliasOf) { name = p.aliasOf; p = catalog.providers?.[name]; }
+  return { name, provider: p };
+}
+
+const blend = (e) => (e && Number.isFinite(e.in) && Number.isFinite(e.out) ? +(((e.in + e.out) / 2)).toFixed(2) : null);
+
+/**
+ * Which house is this user? Precedence: explicit config.provider → $RUVNET_PROVIDER → an API key present
+ * in env → the catalog default (Anthropic, because this IS a Claude Code plugin — a detected fact, which
+ * the caller surfaces with source:'default' so it never reads as an arbitrary house preference).
+ * Returns { provider, source: 'config'|'env'|'default' }.
+ */
+export function detectProvider(catalog, { provider, env = process.env } = {}) {
+  const P = catalog.providers || {};
+  const pick = provider || env.RUVNET_PROVIDER;
+  if (pick && pick !== 'auto' && P[pick]) return { provider: pick, source: 'config' };
+  // Running inside Claude Code, the dev house is genuinely Anthropic (a fact) — a stray OpenAI key in the
+  // env does NOT make you an "OpenAI shop", so don't silently relabel; the person sets that explicitly.
+  // Outside Claude Code (CI, standalone), fall to key detection.
+  const inClaudeCode = env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT;
+  if (!inClaudeCode) {
+    for (const name of ['openai', 'google', 'xai', 'anthropic']) {
+      const keys = (P[name]?.detect_env || []).filter((k) => !['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'].includes(k));
+      if (keys.some((k) => env[k])) return { provider: name, source: 'env' };
+    }
+  }
+  return { provider: catalog.default_provider || 'anthropic', source: 'default' };
+}
+
+/** The frontier (flagship) for a house: {model, in, out, costPerMTok, rank, released, provider, label}. */
+export function frontierFor(catalog, name) {
+  const { name: r, provider: p } = resolve(catalog, name);
+  if (!p?.frontier) return null;
+  return { ...p.frontier, costPerMTok: blend(p.frontier), provider: r, label: p.label };
+}
+
+/** The full house ladder (cheap/mid/frontier — any may be null). */
+export function ladderFor(catalog, name) {
+  const { name: r, provider: p } = resolve(catalog, name);
+  const t = (e) => (e ? { ...e, costPerMTok: blend(e) } : null);
+  return { provider: r, label: p?.label || r, cheap: t(p?.cheap), mid: t(p?.mid), frontier: t(p?.frontier) };
+}
+
+export function providerLabel(catalog, name) { return resolve(catalog, name).provider?.label || name; }
+
+/** The set of houses a user can pick, for the console selector: [{ id, label }]. */
+export function providerChoices(catalog) {
+  return Object.entries(catalog.providers || {}).map(([id, p]) => ({ id, label: p.label || id }));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const c = loadCatalog();
+  const det = detectProvider(c, {});
+  console.log(`detected house: ${det.provider} (${det.source})`);
+  console.log('frontier:', JSON.stringify(frontierFor(c, det.provider)));
+  console.log('choices:', providerChoices(c).map((x) => x.id).join(', '));
+}

package/scripts/nightly-controller.mjs

@@ -0,0 +1,66 @@
+// 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';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const INSTALLER = path.join(ROOT, 'bin', 'install.mjs');
+const 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', `${LABEL}.plist`),
+    label: 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/scripts/nightly-gists.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+# nightly-gists.sh — keep the brain's view of rUv's thinking current, cheaply.
+#
+# Run by the launchd agent com.ruvnet.brain-gists (21:47 local). Does NOT publish, deploy, push, or
+# touch anything outward-facing. Reads GitHub, writes to kb/ and docs/.
+#
+# COST DISCIPLINE (the whole point):
+#   1. index refresh   — ~5 API calls, no per-gist fetch, no model.          Always.
+#   2. content ingest  — incremental; only re-fetches gists whose updated_at moved.
+#   3. re-embed        — the expensive step (~18 min, 8 shards). SKIPPED ENTIRELY when step 2
+#                        reports "nothing to do". A quiet night costs seconds, not minutes.
+#
+# PATH is set explicitly: launchd does not inherit a login shell's environment, which is why the
+# sibling agent com.ruvnet.brain-nightly has been dying on `spawnSync gh ENOENT` — gh lives in
+# /opt/homebrew/bin and launchd never saw it.
+
+set -eu
+
+cd "$(dirname "$0")/.."
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+export KB_MODEL_CACHE="${KB_MODEL_CACHE:-/Users/stuartkerr/Code/PowerPlatePulse/scripts/models-cache}"
+
+mkdir -p logs
+LOG="logs/gists-nightly.log"
+ts() { date '+%Y-%m-%dT%H:%M:%S%z'; }
+log() { printf '[%s] %s\n' "$(ts)" "$1" >>"$LOG"; }
+
+log "start"
+
+command -v gh >/dev/null 2>&1 || { log "FATAL: gh not on PATH"; exit 1; }
+gh auth status >/dev/null 2>&1 || { log "FATAL: gh not authenticated"; exit 1; }
+
+# 1 — the tracked index. Cheap enough to do unconditionally.
+node scripts/ingest-gists.mjs --index-only >>"$LOG" 2>&1
+log "index refreshed"
+
+# 2 — incremental content ingest.
+if ! OUT=$(node scripts/ingest-gists.mjs 2>&1); then
+  printf '%s\n' "$OUT" >>"$LOG"
+  log "FATAL: ingest failed"
+  exit 1
+fi
+printf '%s\n' "$OUT" >>"$LOG"
+
+if printf '%s' "$OUT" | grep -q 'nothing to do'; then
+  log "no new gists — skipping embed (cost: 0)"
+  exit 0
+fi
+
+# 3 — re-embed, only because the corpus actually changed. 8 shards, then one assemble.
+# DERIVED, not asserted (F6, 2026-07-18): a bare `wait` with no operands ALWAYS returns 0 under
+# POSIX, so a failed shard was structurally invisible — the script would proceed to ingest and log
+# "done — rebuilt" over a half-embedded corpus. Now every shard PID is waited on individually and a
+# single failure aborts BEFORE ingest, loudly. "done" is only printed over a fully-embedded corpus.
+log "corpus changed — re-embedding"
+i=0
+pids=""
+while [ "$i" -lt 8 ]; do
+  node kb/forge-big.mjs embed --dir kb --name ruv-gists --shard "$i" --of 8 >>"$LOG" 2>&1 &
+  pids="$pids $!"
+  i=$((i + 1))
+done
+FAILED_SHARDS=0
+for p in $pids; do
+  wait "$p" || FAILED_SHARDS=$((FAILED_SHARDS + 1))
+done
+if [ "$FAILED_SHARDS" -gt 0 ]; then
+  log "EMBED FAILED — $FAILED_SHARDS of 8 shards exited nonzero; refusing to ingest a half-embedded corpus"
+  exit 1
+fi
+node kb/forge-big.mjs ingest --dir kb --name ruv-gists >>"$LOG" 2>&1 || { log "INGEST FAILED — store NOT rebuilt"; exit 1; }
+log "done — ruv-gists store rebuilt"