ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/brain-novice-50.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const NOVICE_QUESTIONS = [
+  ['orientation', 'I just installed this. What is RuvNet Brain actually for?', 'ruvnet-brain', /source|ground|actual|rUv/i],
+  ['orientation', 'I am lost. What should I try first?', 'ruvnet-brain', /install|doctor|console|search/i],
+  ['orientation', 'Is this a chatbot, a database, or something else?', 'ruvnet-brain', /knowledge|ground|MCP|RVF/i],
+  ['orientation', 'Why would I use this instead of asking Claude from memory?', 'ruvnet-brain', /source|stale|ground|cite/i],
+  ['orientation', 'Does this work in Codex too, or only Claude Code?', 'ruvnet-brain', /Codex|Claude/i],
+  ['tiny-command', 'How do I open the settings screen?', 'ruvnet-brain', /rvbc|console/i],
+  ['tiny-command', 'What command checks whether my install is healthy?', 'ruvnet-brain', /doctor/i],
+  ['tiny-command', 'How do I see what changed in version 4?', 'ruvnet-brain', /what.?s.new|upgrade|4\.0/i],
+  ['tiny-command', 'Do I install this separately in every project?', 'ruvnet-brain', /user.level|shared|every project|cache/i],
+  ['tiny-command', 'Can I turn the Brain off temporarily?', 'ruvnet-brain', /off|disable|sentinel/i],
+  ['mistake', 'I guess RVF is just a JSON file full of embeddings, right?', 'ruvector', /binary|HNSW|RVF/i],
+  ['mistake', 'Should I put these vectors in Pinecone instead?', 'ruvector', /RVF|HNSW|local|zero.server/i],
+  ['mistake', 'AgentDB and RVF are the same thing, correct?', 'agentdb', /structured|memory|vector|RVF/i],
+  ['mistake', 'Ruflo is only a prompt library, isn’t it?', 'ruflo', /orchestrat|agent|swarm|memory/i],
+  ['mistake', 'If search finds nothing, that proves the feature does not exist, yes?', 'ruvnet-brain', /thin|absence|narrow|artifact/i],
+  ['small-specific', 'Where does RuvNet Brain store its own knowledge?', 'ruvnet-brain', /RVF|kb|cache/i],
+  ['small-specific', 'What is HNSW doing inside RVF?', 'ruvector', /index|nearest|vector|search/i],
+  ['small-specific', 'What is a witness chain in an RVF file?', 'ruvector', /witness|integrity|chain|provenance/i],
+  ['small-specific', 'What does AgentDB remember that RVF does not?', 'agentdb', /structured|operational|agent|memory/i],
+  ['small-specific', 'What is RuLake supposed to speed up?', 'rulake', /cache|read|vector|RVF/i],
+  ['how-to', 'How do I ask RuvNet Brain a source question?', 'ruvnet-brain', /search_ruvnet|query|source/i],
+  ['how-to', 'How do I make several coding agents work together?', 'ruflo', /swarm|agent|orchestrat|hierarchical/i],
+  ['how-to', 'How do I keep project decisions across sessions?', 'ruflo', /memory store|memory search|AgentDB|session/i],
+  ['how-to', 'How do I test a repo with specialized QE agents?', 'agentic-qe', /test|fleet|agent|quality/i],
+  ['how-to', 'How do I find code that has weak test coverage?', 'agentic-qe', /coverage|gap|risk/i],
+  ['big-picture', 'Explain how RVF, AgentDB, Ruflo, and RuvNet Brain fit together.', 'ruvnet-brain', /RVF|AgentDB|Ruflo|ground/i],
+  ['big-picture', 'What happens from my question to a cited answer?', 'ruvnet-brain', /retriev|rerank|evidence|cite/i],
+  ['big-picture', 'How does the system avoid hallucinating about shipped features?', 'ruvnet-brain', /implementation|source|manifest|proposed/i],
+  ['big-picture', 'What is the difference between orchestration and memory here?', 'ruflo', /orchestrat|memory|agent/i],
+  ['big-picture', 'Why use local models and files instead of a hosted vector server?', 'ruvector', /local|offline|RVF|server/i],
+  ['recovery', 'My search has been spinning for minutes. What should I check?', 'ruvnet-brain', /doctor|model|cache|health|timeout/i],
+  ['recovery', 'The Brain says evidence is thin. What do I do next?', 'ruvnet-brain', /narrow|repo|artifact|query/i],
+  ['recovery', 'My project memory is not updating. Which store should I inspect?', 'ruflo', /memory\.db|ruflo memory|swarm/i],
+  ['recovery', 'Ruflo memory says success but nothing was written. How do I prove it?', 'ruflo', /retrieve|search|sqlite|mtime|row/i],
+  ['recovery', 'The native SQLite bridge has the wrong Node ABI. Is fallback good enough?', 'ruflo', /ABI|better-sqlite3|fallback|native/i],
+  ['architecture', 'What is the correct storage split for a new knowledge app?', 'ruvnet-brain', /RVF|AgentDB|structured|vector/i],
+  ['architecture', 'When should I use SPARC?', 'sparc', /specification|architecture|refinement|completion/i],
+  ['architecture', 'How should a release prove the exact artifact it publishes?', 'ruvnet-brain', /SHA|digest|artifact|publish/i],
+  ['architecture', 'How should RuvNet Brain behave when a source worker times out?', 'ruvnet-brain', /kill|health|error|restart|timeout/i],
+  ['architecture', 'How does query routing keep searches from touching every repo?', 'ruvnet-brain', /route|card|scope|repo/i],
+  ['truth', 'Is the cross-encoder cascade currently shipped on by default?', 'ruvnet-brain', /off|default|ADR-060|accepted/i],
+  ['truth', 'Can you prove the release-proof protocol is implemented, not merely proposed?', 'ruvnet-brain', /implementation|source|manifest|proven/i],
+  ['truth', 'Does a green test run prove the npm package works after install?', 'ruvnet-brain', /packed|install|artifact|public/i],
+  ['truth', 'If Agentic QE executes zero tests, may the gate still pass?', 'ruvnet-brain', /zero|vacuous|fail|gate/i],
+  ['truth', 'Is every capability described in an ADR already available?', 'ruvnet-brain', /proposed|accepted|implemented|status/i],
+  ['comparison', 'RuvNet Brain versus Ruflo: which one answers source questions?', 'ruvnet-brain', /source|orchestrat|Ruflo|Brain/i],
+  ['comparison', 'RVF versus AgentDB: where do vectors and structured records go?', 'agentdb', /RVF|vector|AgentDB|structured/i],
+  ['comparison', 'RuLake versus RVF: is the cache the source of truth?', 'rulake', /cache|RVF|source|truth/i],
+  ['advanced', 'Which code path reranks candidates after RVF retrieval?', 'ruvnet-brain', /forge-rerank|cross.encoder|rerank/i],
+  ['advanced', 'What exact evidence would make you call RuvNet Brain ready to ship?', 'ruvnet-brain', /exact|artifact|test|public|receipt/i],
+].map(([category, query, repo, required], index) => ({
+  id: index + 1, category, query, repo, required,
+}));
+
+function percentile(values, fraction) {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.max(0, Math.ceil(sorted.length * fraction) - 1)];
+}
+
+function grade(spec, text, elapsedMs, transportOk) {
+  const repo = spec.repo.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const expectedRepoCited = new RegExp(
+    `(?:repo\\s*=\\s*["']?${repo}\\b|path\\s*:\\s*${repo}/|capability-cards\\.md#${repo}\\b)`,
+    'i',
+  ).test(text);
+  const cited = /(?:#\d+\s+repo=[a-z0-9._-]+|path\s*:\s*[a-z0-9._-]+\/|capability-cards\.md#[a-z0-9._-]+)/i
+    .test(text);
+  const useful = spec.required.test(text);
+  const unsupportedAbsence = /\b(?:does not exist|must be built|you need to build it)\b/i.test(text);
+  const evidenceQualified = /EVIDENCE:\s*THIN|NOT PROVEN|PROPOSED|curated-capability-card|THIS QUERY found nothing/i.test(text);
+  const honest = !unsupportedAbsence || evidenceQualified;
+  const latencyPoints = elapsedMs <= 4000 ? 10 : elapsedMs <= 8000 ? 5 : 0;
+  const score = (transportOk ? 20 : 0) + (text.length > 200 ? 20 : 0)
+    + (cited ? 20 : 0) + (useful ? 20 : 0) + (honest ? 10 : 0) + latencyPoints;
+  const effective = transportOk && cited && useful && honest && elapsedMs <= 4000;
+  return { score, cited, expectedRepoCited, useful, honest, effective, latencyPoints };
+}
+
+async function main() {
+  const concurrency = Math.max(1, Number(process.argv[2] || 10));
+  const brainHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-brain-novice-'));
+  const child = spawn(process.execPath, [path.join(ROOT, 'plugin/mcp/server.mjs')], {
+    cwd: ROOT,
+    env: {
+      ...process.env,
+      RUVNET_BRAIN_HOME: brainHome,
+      RUVNET_BRAIN_KB: path.join(ROOT, 'kb'),
+      RUVNET_BRAIN_CHILD_MCP: path.join(ROOT, 'kb/forge-mcp-all.mjs'),
+      KB_MODEL_CACHE: path.join(ROOT, 'kb/models-cache'),
+      RUVNET_BRAIN_CALL_TIMEOUT_MS: '30000',
+      RUVNET_BRAIN_METER: '0',
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const rl = readline.createInterface({ input: child.stdout });
+  const waiting = new Map();
+  let id = 0;
+  let stderr = '';
+  child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+  rl.on('line', (line) => {
+    let msg; try { msg = JSON.parse(line); } catch { return; }
+    const done = waiting.get(msg.id);
+    if (done) { waiting.delete(msg.id); done(msg); }
+  });
+  const request = (method, params, timeoutMs = 120_000) => {
+    const requestId = ++id;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        waiting.delete(requestId);
+        resolve({ error: { message: `${method} client timeout` } });
+      }, timeoutMs);
+      waiting.set(requestId, (msg) => { clearTimeout(timer); resolve(msg); });
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: requestId, method, params })}\n`);
+    });
+  };
+
+  const readyAt = performance.now();
+  await request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'novice-50', version: '1' } });
+  const tools = await request('tools/list', {});
+  if (!tools.result?.tools?.some((tool) => tool.name === 'search_ruvnet')) throw new Error('search_ruvnet not ready');
+  const readinessMs = Math.round(performance.now() - readyAt);
+
+  const results = new Array(NOVICE_QUESTIONS.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (let index = next++; index < NOVICE_QUESTIONS.length; index = next++) {
+      const spec = NOVICE_QUESTIONS[index];
+      const started = performance.now();
+      const msg = await request('tools/call', {
+        name: 'search_ruvnet',
+        arguments: { query: spec.query, k: 5 },
+      }, 35_000);
+      const elapsedMs = Math.round(performance.now() - started);
+      const text = msg.result?.content?.[0]?.text || '';
+      const transportOk = !msg.error && msg.result?.isError !== true;
+      results[index] = {
+        ...spec,
+        elapsedMs,
+        transportOk,
+        error: msg.error?.message || (msg.result?.isError ? text.slice(0, 240) : null),
+        answer: text,
+        ...grade(spec, text, elapsedMs, transportOk),
+      };
+      process.stdout.write(`${String(spec.id).padStart(2, '0')} ${String(results[index].score).padStart(3)} ${String(elapsedMs).padStart(6)}ms ${spec.category.padEnd(14)} ${spec.query}\n`);
+    }
+  }));
+
+  child.stdin.end();
+  await Promise.race([new Promise((resolve) => child.once('exit', resolve)), new Promise((resolve) => setTimeout(resolve, 5000))]);
+  if (child.exitCode === null) child.kill('SIGKILL');
+  rl.close();
+  fs.rmSync(brainHome, { recursive: true, force: true });
+
+  const times = results.map((result) => result.elapsedMs);
+  const report = {
+    generatedAt: new Date().toISOString(),
+    concurrency,
+    readinessMs,
+    passed: results.filter((result) => result.effective).length,
+    under4s: results.filter((result) => result.elapsedMs <= 4000).length,
+    averageScore: Math.round(results.reduce((sum, result) => sum + result.score, 0) / results.length),
+    averageMs: Math.round(times.reduce((sum, value) => sum + value, 0) / times.length),
+    medianMs: percentile(times, 0.5),
+    p95Ms: percentile(times, 0.95),
+    longestMs: Math.max(...times),
+    stderr: stderr.trim(),
+    results,
+  };
+  const output = path.join(ROOT, 'data/novice-50-report.json');
+  fs.writeFileSync(output, JSON.stringify(report, null, 2) + '\n');
+  console.log(`SUMMARY ${report.passed}/50 effective · ${report.under4s}/50 under 4s · score ${report.averageScore}/100 · avg ${report.averageMs}ms · p95 ${report.p95Ms}ms · max ${report.longestMs}ms`);
+  console.log(`REPORT ${output}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => { console.error(error.stack || error.message); process.exitCode = 1; });
+}

package/scripts/brain-stamp.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// brain-stamp.mjs — stamp the bundle with build date + per-repo commit SHA.
+// Writes data/manifest.json and injects the stamp into the primer header + each KB SOURCE.json.
+// Run after a (re)build. Self-update calls this so every download says exactly what it covers.
+//
+// Usage: node scripts/brain-stamp.mjs [--brain-version v0.1.0-dev]
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { canonicalRvfStores, hasCanonicalRvfStore } from './rvf-generation.mjs';
+import { getVersionTag, stripTag } from './version.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const BRAIN_VERSION = arg('--brain-version', getVersionTag()); // inherits the single source of truth
+const NOW = new Date().toISOString();
+const KB_DIR = path.join(ROOT, 'kb');
+
+// Known local clones (extend as repos are added). Self-update resolves remote SHAs for the rest.
+const CLONES = JSON.parse(process.env.RUVNET_KNOWN_CLONES || '{}');
+const builtName = (n) => hasCanonicalRvfStore(KB_DIR, n);
+const shaOf = (dir) => { try { return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir }).toString().trim(); } catch { return null; } };
+// no shell: slug is placed in a URL arg, never interpreted by a shell
+const remoteSha = (slug) => { try { return execFileSync('git', ['ls-remote', `https://github.com/ruvnet/${slug}`, 'HEAD']).toString().split(/\s/)[0] || null; } catch { return null; } };
+
+const tiers = JSON.parse(fs.readFileSync(path.join(ROOT, 'data/registry.tiers.json'), 'utf8'));
+const repos = [];
+for (const t of ['T0', 'T1', 'T2', 'T3']) {
+  for (const r of tiers.tiers[t].repos) {
+    // Default clone location is ROOT/clones/<name> (where self-update.mjs puts them) — the env
+    // override is the exception, not the only source. Stamping 'unknown' when a real clone sits
+    // on disk made unknown-SHA repos permanently invisible to the freshness loop (ruflo bug).
+    const cloneDir = CLONES[r.name] || path.join(ROOT, 'clones', r.name);
+    const localSha = fs.existsSync(path.join(cloneDir, '.git')) ? shaOf(cloneDir) : null;
+    repos.push({
+      name: r.name, tier: t, stars: r.stars,
+      builtFromSha: builtName(r.name) ? (localSha || 'unknown') : null,
+      latestRemoteSha: null,           // filled by --check-remote (network) in self-update
+      status: builtName(r.name) ? 'built' : 'pending',
+    });
+  }
+}
+
+// DURABILITY FIX (nail-the-nightly): the nightly is now --fresh-window / live-scan driven, but this
+// stamper was tiers-file driven. A repo discovered by --fresh-window that isn't in the static
+// registry.tiers.json would build every night yet never receive a builtFromSha, so the freshness loop
+// would REBUILD it forever. Stamp EVERY built store on disk (tiers-listed or not) so "unchanged =>
+// skipped" holds for fresh-window repos too. Clone dir resolved case-insensitively (store names are
+// lowercased; clone dirs keep the repo's own casing, e.g. kb/photonlayer.rvf <- clones/PhotonLayer).
+const clonesDir = path.join(ROOT, 'clones');
+const cloneEntries = fs.existsSync(clonesDir) ? fs.readdirSync(clonesDir) : [];
+const findClone = (name) => {
+  if (CLONES[name] && fs.existsSync(path.join(CLONES[name], '.git'))) return CLONES[name];
+  const exact = path.join(clonesDir, name);
+  if (fs.existsSync(path.join(exact, '.git'))) return exact;
+  const ci = cloneEntries.find((d) => d.toLowerCase() === name.toLowerCase());
+  return ci && fs.existsSync(path.join(clonesDir, ci, '.git')) ? path.join(clonesDir, ci) : null;
+};
+const seen = new Set(repos.map((r) => r.name.toLowerCase()));
+for (const store of canonicalRvfStores(KB_DIR)) {
+  if (seen.has(store.toLowerCase())) continue;
+  seen.add(store.toLowerCase());
+  const cloneDir = findClone(store);
+  repos.push({
+    name: store, tier: 'fresh', stars: undefined,
+    builtFromSha: cloneDir ? (shaOf(cloneDir) || 'unknown') : 'unknown',
+    latestRemoteSha: null,
+    status: 'built',
+  });
+}
+const built = repos.filter((r) => r.status === 'built');
+const manifest = {
+  brainVersion: stripTag(BRAIN_VERSION), // FIELD = bare literal; the "v" tag is display-only (see version.mjs)
+  generated: NOW,
+  generatedHuman: new Date(NOW).toUTCString(),
+  coverage: { built: built.length, catalogued: repos.length, orgTotalApprox: 248, pending: repos.length - built.length },
+  builtRepos: built,
+  pendingRepos: repos.filter((r) => r.status === 'pending').map((r) => ({ name: r.name, tier: r.tier })),
+};
+fs.mkdirSync(path.join(ROOT, 'data'), { recursive: true });
+fs.writeFileSync(path.join(ROOT, 'data/manifest.json'), JSON.stringify(manifest, null, 2));
+
+// Stamp the primer header line.
+const primerPath = path.join(ROOT, 'primer/ruvnet-primer.md');
+if (fs.existsSync(primerPath)) {
+  let p = fs.readFileSync(primerPath, 'utf8');
+  const stamp = `\`Brain version: ${BRAIN_VERSION} · Built: ${new Date(NOW).toISOString().slice(0, 10)} · Covers: ${built.length}/${repos.length} repos built @ pinned SHAs (see data/manifest.json)\``;
+  p = p.replace(/`Brain version:[^`]*`/, stamp);
+  fs.writeFileSync(primerPath, p);
+}
+console.log(`Stamped ${BRAIN_VERSION} @ ${NOW}`);
+console.log(`Coverage: ${built.length} built / ${repos.length} total`);
+for (const b of built) console.log(`  ${b.tier} ${b.name} @ ${b.builtFromSha?.slice(0, 12)}`);

package/scripts/brain-state.mjs

@@ -0,0 +1,212 @@
+// brain-state.mjs — is the brain ON or OFF? One question, one file, no third state. (ADR-054 §2)
+//
+// THE ONE IDEA: THE SENTINEL *IS* THE SWITCH.
+//
+// `~/.config/ruvnet-brain/brain-off` present = off. Absent = on. There is deliberately no "enabled"
+// value anywhere that a reader has to parse, interpret, version-negotiate, or repair — because every
+// one of those verbs is a place where the user's stated choice can be silently lost, and the
+// 2026-07-26 adversarial duel found all of them in the JSON-settings design this replaced:
+//
+//   • SKEW. An older release's validate() DROPS unknown keys ("Dropped, not preserved" —
+//     user-settings.mjs). A user turns the brain off on v4, opens a project still running v3, v3
+//     saves any unrelated setting, and `brainEnabled` is gone. The next session the brain is back on
+//     and nothing anywhere reports it. Gate test 1 reproduces exactly that sequence.
+//   • CORRUPTION AND FAIL POLARITY. A truncated write, an EACCES, or a file written by a future
+//     version all make loadSettings() fall back to DEFAULTS — and the default is ON. Every failure
+//     mode in a settings file therefore fails toward "enabled", which is the wrong direction for a
+//     consent record. `[ -f ]` has no failure mode that resolves to "the user must have meant on".
+//   • READERS. Three bash gates and a bundled MCP child have to answer this question. `[ -f x ]`
+//     works in bash 3.2 with no jq, no node and no parsing; `fs.existsSync` works in any node
+//     vintage. A JSON schema does not.
+//
+// settings.json keeps a MIRROR key (`brainEnabled`) so the console has a UI record and so the choice
+// shows up where a user goes looking for their choices. The mirror is a record, never the switch:
+// when the two disagree the sentinel wins and `disagreement()` hands the console the fact to show,
+// rather than letting one surface quietly pick a winner.
+//
+// DELIBERATELY DEPENDENCY-FREE. node builtins only. This module is imported by the console and by
+// the installer's siblings; the boot-frozen hook shim and the bundled KB child re-derive the same
+// path inline instead of importing it, because neither can reach outside its own frozen tree. Those
+// three copies are held together by tests, not by hope (tests/unit/brain-off.test.mjs asserts the
+// real path from bash, from the shim and from the bundle).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * WHERE IT LIVES. Same directory, and the same argument, as user-settings.mjs's STORE_PATH: grepping
+ * bin/install.mjs for `.config/ruvnet-brain` shows the installer has no code path that writes there
+ * during `--update`, so a preference stored here survives every release. `--uninstall` is the ONE
+ * exception and it is deliberate (ADR-054 §5): a removed product must not leave an invisible OFF
+ * behind for its own reinstall to inherit.
+ *
+ * Resolved per call, not once at module load, so a test (or a second machine profile) can point it
+ * somewhere else with RUVNET_BRAIN_STATE_DIR and have every function in this file agree immediately.
+ */
+export function stateDir() {
+  return process.env.RUVNET_BRAIN_STATE_DIR || path.join(os.homedir(), '.config', 'ruvnet-brain');
+}
+
+/** The switch. Its EXISTENCE is the entire protocol; its contents are metadata for humans. */
+export function sentinelPath() {
+  return path.join(stateDir(), 'brain-off');
+}
+
+/**
+ * IS THE BRAIN OFF? The only question this module exists to answer.
+ *
+ * Note what it does NOT do: read the file, parse it, validate it, or consult settings.json. A
+ * `touch`ed, empty, corrupt or hand-written sentinel all mean the same thing, because a user who put
+ * a file there meant it. Anything cleverer would reintroduce a parse step, and a parse step is a
+ * failure mode, and a failure mode on a consent record resolves to "we ignored what you asked for".
+ */
+export function isBrainOff(file = sentinelPath()) {
+  try { fs.statSync(file); return true; }
+  catch (e) { return !isAbsent(e); }
+}
+
+/**
+ * ONLY "the file is genuinely not there" counts as ON. Everything else counts as OFF.
+ *
+ * This distinction was NOT in the first draft and gate test 5 caught it, which is the whole reason
+ * that test exists. `fs.existsSync` does not throw on EACCES — it returns FALSE. So a state
+ * directory the process cannot read reported "no sentinel" and the brain came back on, silently,
+ * for a user who had switched it off: the exact fail-open polarity ADR-054 §2 chose the sentinel to
+ * dissolve, reproduced inside the sentinel's own reader.
+ *
+ * The tradeoff is stated rather than hidden. An unreadable state dir now reads as OFF even for a
+ * user who never switched it off — and that is the direction to be wrong in. Wrong-toward-off is
+ * VISIBLE (session-start prints its one state line every session, the console shows the switch,
+ * both name the file) and recoverable in one `chmod`. Wrong-toward-on is INVISIBLE and overrides a
+ * choice the user already made, which is a consent violation rather than a bug.
+ */
+function isAbsent(e) {
+  return !!e && (e.code === 'ENOENT' || e.code === 'ENOTDIR');
+}
+
+/**
+ * READ THE STATE, including the parts we might not know.
+ *
+ * `since` falls back to the file's own mtime when the contents are unparseable, so the session-start
+ * line can still name a date instead of printing "since undefined". `reason` does NOT get a fallback:
+ * we either know why or we say null. Inventing a plausible reason on a consent record is precisely
+ * the fabrication this repo has a standing order against.
+ */
+export function readOffState(file = sentinelPath()) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch (e) {
+    // Same polarity as isBrainOff(): only genuine absence is ON. An unreadable state dir reports OFF
+    // with everything it does not know set to null, rather than inventing an "on" it cannot see.
+    if (isAbsent(e)) return { off: false, since: null, reason: null, host: null, path: file };
+    return { off: true, since: null, reason: null, host: null, path: file, unreadable: e.code || 'unknown' };
+  }
+
+  let parsed = null;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { /* touched / truncated / hand-written — existence still decides */ }
+
+  const valid = parsed && typeof parsed === 'object' && !Array.isArray(parsed);
+  return {
+    off: true,
+    since: (valid && typeof parsed.since === 'string' && !Number.isNaN(Date.parse(parsed.since)))
+      ? parsed.since
+      : new Date(stat.mtimeMs).toISOString(),
+    reason: valid && typeof parsed.reason === 'string' && parsed.reason ? parsed.reason : null,
+    host: valid && typeof parsed.host === 'string' ? parsed.host : null,
+    path: file,
+  };
+}
+
+/**
+ * TURN IT OFF — atomically, so no reader can ever observe a half-written sentinel.
+ *
+ * temp-file + rename, the same primitive and the same reason as user-settings.mjs's writeAtomic():
+ * two console tabs, two Claude Code windows and a CLI can all be writing this at once, and a reader
+ * that catches a zero-byte file mid-write must still read "off" rather than crash or, far worse,
+ * read "on". The temp name carries the pid so concurrent writers cannot collide on it.
+ *
+ * The write is best-effort about its CONTENT and strict about its EXISTENCE: if the JSON body cannot
+ * be written we still report the failure honestly rather than claiming the brain is off when it is
+ * not. A switch that lies about having been flipped is worse than a switch that refuses.
+ */
+export function setBrainOff(reason = null, { file = sentinelPath() } = {}) {
+  const dir = path.dirname(file);
+  try { fs.mkdirSync(dir, { recursive: true }); }
+  catch (e) { return { ok: false, path: file, log: `could not create ${dir}: ${e.message}` }; }
+
+  const body = `${JSON.stringify({
+    off: true,
+    since: new Date().toISOString(),
+    reason: reason ? String(reason) : null,
+    host: os.hostname(),
+    // Legible to a human who finds this file and has no idea what it is. Support reads it in one go.
+    note: 'RuvNet Brain is switched OFF. This file IS the switch — deleting it turns the brain back on.',
+  }, null, 2)}\n`;
+
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmp, body, { flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* leave the temp rather than throw over it */ }
+    return { ok: false, path: file, log: `could not write the switch: ${e.message}` };
+  }
+  return { ok: true, path: file, off: true, log: 'the brain is off' };
+}
+
+/**
+ * TURN IT ON — remove the sentinel. Idempotent by construction: "already on" is a success, not an
+ * error, because the caller asked for a STATE and got it. The installer's uninstall path relies on
+ * exactly this shape.
+ */
+export function setBrainOn({ file = sentinelPath() } = {}) {
+  try {
+    if (!fs.existsSync(file)) return { ok: true, path: file, off: false, log: 'the brain was already on' };
+    fs.rmSync(file);
+    return { ok: true, path: file, off: false, log: 'the brain is on' };
+  } catch (e) {
+    return { ok: false, path: file, log: `could not remove the switch (${file}): ${e.message}` };
+  }
+}
+
+/**
+ * DO THE SWITCH AND ITS MIRROR AGREE? Returns null when they do, and the FACT when they do not.
+ *
+ * The console renders this rather than resolving it silently. The two can legitimately drift — an
+ * older release drops the mirror key (gate test 1), a user hand-edits one of the two files, a
+ * `--update` from a different line lands in between — and in every one of those cases the honest
+ * surface says "these disagree, here is which one is in force" instead of showing a toggle whose
+ * position is a guess.
+ */
+export function disagreement(mirrorEnabled, { file = sentinelPath() } = {}) {
+  const off = isBrainOff(file);
+  const mirrorSaysOff = mirrorEnabled === false;
+  if (off === mirrorSaysOff) return null;
+  return {
+    sentinelWins: true,
+    inForce: off ? 'off' : 'on',
+    sentinel: off ? 'off' : 'on',
+    mirror: mirrorSaysOff ? 'off' : 'on',
+    note: off
+      ? 'The switch file says OFF and your saved settings say ON. The switch is what every part of the brain actually reads, so the brain is OFF.'
+      : 'Your saved settings say OFF but the switch file is gone, so the brain is ON. Set it again here if you meant it to stay off.',
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────
+// Read-only. Turning the brain on or off is the console's job (it takes a backup of the mirror and
+// records the change); this prints what is true right now so support can diagnose in one command.
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWith('brain-state.mjs');
+if (invokedDirectly) {
+  const state = readOffState();
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(state, null, 2));
+  } else if (state.off) {
+    console.log(`\n  RuvNet Brain: OFF since ${state.since.slice(0, 10)}${state.reason ? ` — ${state.reason}` : ''}`);
+    console.log(`  Switch file : ${state.path.replace(os.homedir(), '~')}\n`);
+  } else {
+    console.log(`\n  RuvNet Brain: ON (no switch file at ${state.path.replace(os.homedir(), '~')})\n`);
+  }
+}