ruvnet-brain 4.0.36 → 4.2.2-dev

package/plugin/scripts/degradation-watch.mjs

@@ -0,0 +1,271 @@
+/**
+ * degradation-watch.mjs — a printed warning is not a control. This turns one into a REFUSAL.
+ *
+ * THE FAILURE, 2026-08-13. `ruflo memory store` printed, on every write, for three days:
+ *
+ *     [WARN] Data stored, but persistence is not guaranteed: sql.js fallback driver in use —
+ *            this write may not be durably persisted to disk.
+ *
+ * Nothing persisted after 2026-08-10 17:38. Every lesson, checkpoint and session-end handoff went
+ * into a WASM buffer and evaporated, while the CLI printed `[OK] Data stored successfully`. Root
+ * cause, proven: `better_sqlite3.node` was built against NODE_MODULE_VERSION 141 and the running
+ * node needs 137, so the native bridge threw ERR_DLOPEN_FAILED and the driver fell back.
+ *
+ * I READ THAT WARNING AND CONTINUED. That is the defect, and it is not an information problem —
+ * the answer was ALSO in capability-cards.md, which I had printed to screen twenty minutes earlier:
+ * "a native SQLite ABI mismatch is degraded, not healthy: verify and rebuild the active
+ * better-sqlite3 bridge rather than treating a sql.js fallback as equivalent." Knowing was never
+ * missing. STOPPING was.
+ *
+ * So the cure cannot be printing it again, louder. This project already disproved that approach:
+ * the flywheel hook printed `NOT auto-surfaced: default=38` every session for EIGHT DAYS while six
+ * curated lessons never fired. A diagnostic nobody reads is the same as no diagnostic, and I am the
+ * "nobody" in both sentences.
+ *
+ * WHAT GROUNDING CHANGED HERE (search_ruvnet, receipt ede43691e2d5, against
+ * v3/@claude-flow/cli/src/commands/memory.ts). My first draft detected the DRIVER — "is it sql.js?"
+ * The real source says `// Use direct sql.js storage with automatic embedding generation`: sql.js is
+ * a legitimate path in ruflo, not a fault signal. A driver-identity check would have cried wolf on
+ * healthy installs, and a channel that cries wolf gets skimmed, which is the disease this file
+ * exists to cure. So the PROVER is the authority and it tests the only thing that actually matters:
+ * did the row survive to disk. Signatures are hints that trigger a probe, never the verdict.
+ *
+ * THREE PROPERTIES, all required or this is theatre:
+ *   1. DETECTION MUST NOT DEPEND ON ME NOTICING — the prover exercises the real path, because the
+ *      success line lied: `[OK]` printed over rowcount 0.
+ *   2. THE VERDICT MUST REFUSE, NOT INFORM — an operation whose truth depends on durable storage
+ *      cannot proceed while storage is not durable. "We learned X" is FALSE if X did not persist.
+ *   3. IT MUST FAIL ON THE BROKEN SHAPE — proven by mutation in the test, because "a guard that
+ *      cannot fail" is the other bug I shipped today.
+ *
+ * WHY NOT "ALWAYS CONSULT MEMORY FIRST": measured the same day — when I graded the architecture from
+ * file counts, the facts I needed sat in FOUR reachable places and I read none. A fifth advisory
+ * surface cannot fix a failure caused by skipping four. Retrieval cures ignorance; only
+ * interception cures confidence.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// Required by the isMain guard below. Its try/catch would otherwise swallow the ReferenceError and
+// return false, so the policy entrypoint would silently never run — a guard that cannot fire, which
+// is the exact defect class this file exists to close. Caught by counting occurrences, not by
+// reading the code and believing it.
+import { fileURLToPath } from 'node:url';
+
+/**
+ * THE PROBE TARGET IS A SCRATCH DB, NOT THE PROJECT'S.
+ *
+ * This was `process.cwd()/.swarm/memory.db`. The hook runs MACHINE-WIDE, so in any repo that is not
+ * ruvnet-brain it ran `ruflo memory store --path <that repo>/.swarm/memory.db` — CREATING a .swarm
+ * directory and writing a probe row into somebody else's project. An independent audit named it
+ * "unrelated-project mutation", and it is the plainest possible violation of this project's own rule
+ * (ADR-058 D5: never touch what we do not own). Shipped by me, today, in the hook whose entire
+ * purpose is to stop silent damage.
+ *
+ * The fix is not tighter scoping — it is noticing the question was mis-framed. "Does `ruflo memory
+ * store` durably persist?" is a property of the SQLite DRIVER and its ABI against the running node.
+ * That is machine-wide. It has nothing to do with which repo you happen to be standing in, so a
+ * scratch database answers it exactly as well, mutates nothing, and additionally covers the case an
+ * audit flagged separately: with a real project path, an ABSENT store had to be skipped, which made
+ * the store-CREATING first write the one write the guard could never falsify. A scratch path is
+ * always absent and always created — the first-write case is now the ONLY case.
+ */
+const defaultDb = () => path.join(os.tmpdir(), `ruvnet-durability-probe-${process.pid}.db`);
+
+function defaultRun(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf8', timeout: 30_000, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * THE ONLY ACCEPTABLE PROOF OF A WRITE: store, then RETRIEVE that exact key through the managed
+ * interface and read the value back. Explicitly NOT evidence, each having been believed once: the
+ * `[OK]` success line, a semantic-search hit, the .db mtime, the daemon being up, or which driver is
+ * loaded. And explicitly NOT permitted, per issue #140: opening the managed store with `sqlite3`.
+ */
+export function proveMemoryDurable(dbPath = defaultDb(), { run = defaultRun } = {}) {
+  // AN ABSENT STORE IS NOT AN EXEMPTION. This returned `{ok:true, skipped:true}` when the file did
+  // not exist, which — as an independent audit put it — means "the first `ruflo memory store`, the
+  // operation that CREATES the store, is precisely the write the guard cannot falsify." That is a
+  // hole shaped exactly like the moment durability matters most: a fresh machine, first write, and
+  // the sql.js fallback silently swallowing it. `ruflo memory store` creates the file, so probing an
+  // absent path is a valid question with a real answer; only a path we cannot even attempt is a skip.
+  const key = `durability-probe-${process.pid}-${Date.now()}`;
+  try {
+    // THE PROOF IS THE RETRIEVED VALUE, NOT A SQL ROWCOUNT (issue #140, @sparkling).
+    //
+    // This read the row back with `sqlite3`, which opens a Ruflo-MANAGED store directly — the exact
+    // boundary violation ADR-063 and `hijack-ruvnet` exist to stop, committed by the hook that
+    // guards durability. The justification was real at the time: a write could report success and
+    // persist nothing. But rUv closed that upstream in v3.32.34 ("No manual SQL is required"; the
+    // bridge now FAILS CLOSED and reports the native error instead of a misleading fallback), and
+    // the 2026-08-13 incident confirms retrieve was always sufficient — it answered `Key not found`
+    // on precisely the writes that had evaporated. Verified on ruflo 3.38.12 before this change:
+    // the round-trip returns the stored VALUE, and a damaged store answers `[ERROR] no such table`
+    // rather than a false success.
+    const probeValue = `probe-${key}`;
+    run('ruflo', ['memory', 'store', '--path', dbPath, '-n', 'default', '-k', key, '--value', probeValue]);
+    const back = run('ruflo', ['memory', 'retrieve', '--path', dbPath, '-n', 'default', '-k', key]);
+    if (!String(back).includes(probeValue)) {
+      return { ok: false, why: 'stored a key and retrieving it did not return the value — the store reports a success it cannot honour' };
+    }
+    return { ok: true, why: 'store → retrieve round-trip returned the exact value through the managed interface' };
+  } catch (e) {
+    // "CANNOT PROBE" IS NOT "PROBED AND FAILED", and collapsing them shipped the worst
+    // stranger-facing bug in this repo. Measured with PATH=/usr/bin:/bin — i.e. most machines that
+    // install this plugin but not ruflo — EVERY `git push`, `npm publish` and `gh release create`
+    // was refused, with instructions to `npm rebuild better-sqlite3` in a package the user never
+    // installed. Same for a missing `sqlite3`, which is normal on Linux and Windows.
+    //
+    // The rule was already written, one file away, in identifier-preflight.mjs's header: "FAIL OPEN.
+    // An identifier this cannot resolve is ALLOWED, silently... a fabricated diagnosis is worse than
+    // no check, because it burns the credibility the channel runs on." That header even cites THIS
+    // file as the sibling whose bug taught the rule. The rule was recorded and not applied to the
+    // file it was learned from — the same shape as freshness machinery pointed at coverage but not
+    // the eval, and resolveBash existing but unused at a new call site.
+    //
+    // A missing binary means this machine cannot answer the question. It does not mean the answer
+    // is "broken".
+    const msg = String(e?.message ?? e);
+    if (/ENOENT|not found|spawnSync .* ENOENT/i.test(msg)) {
+      return { ok: true, why: `cannot probe on this machine (${msg.split('\n')[0]}) — declining to guess`, skipped: true };
+    }
+    return { ok: false, why: `probe could not complete: ${msg.split('\n')[0]}` };
+  } finally {
+    // The scratch db is ours alone; remove it and its WAL siblings rather than leaving litter in tmp.
+    for (const suffix of ['', '-wal', '-shm']) {
+      try { fs.unlinkSync(dbPath + suffix); } catch { /* never existed, or already gone */ }
+    }
+  }
+}
+
+/**
+ * A degradation is only worth a channel if something PROVES it. `detect` spots a smell in output a
+ * tool already printed and is a HINT ONLY — it decides when to probe, never what is true.
+ */
+export const SIGNATURES = [
+  {
+    id: 'memory-not-durable',
+    detect: /persistence is not guaranteed|NODE_MODULE_VERSION|ERR_DLOPEN_FAILED|not durably persisted/i,
+    what: 'the memory store is not durably persisting writes',
+    costs: 'every lesson, checkpoint and handoff is silently lost — the learning loop is severed',
+    blocks: ['claim-done', 'ship', 'record-lesson'],
+    fix: 'npm rebuild better-sqlite3 in $(npm root -g)/ruflo, then re-run the round-trip probe',
+    prove: proveMemoryDurable,
+  },
+];
+
+/** Spot a known degradation in text a tool printed. A hint that a probe is warranted — not a verdict. */
+export function detectIn(text, signatures = SIGNATURES) {
+  if (!text) return [];
+  return signatures.filter((s) => s.detect.test(text));
+}
+
+/**
+ * Run every prover and return only the degradations that are REAL RIGHT NOW. A signature its prover
+ * clears is not reported, because a warning channel that cries wolf gets skimmed — which is exactly
+ * how three days of memory were lost.
+ */
+export function activeDegradations(signatures = SIGNATURES, opts = {}) {
+  const out = [];
+  for (const s of signatures) {
+    const verdict = s.prove ? s.prove(opts.dbPath, opts) : { ok: false, why: 'no prover — unprovable claims are treated as failures' };
+    if (!verdict.ok) out.push({ ...s, verdict });
+  }
+  return out;
+}
+
+/**
+ * THE REFUSAL — the property that makes a warning stop being skimmable, because it is no longer
+ * text, it is a closed door. Only operations whose truth DEPENDS on durable storage are blocked;
+ * blocking everything would make this the next thing routed around.
+ */
+export function refusalFor(event, degradations) {
+  const hit = degradations.find((d) => d.blocks.includes(event));
+  if (!hit) return null;
+  return {
+    allow: false,
+    policy: 'degradation-watch',
+    reason:
+      `BLOCKED — ${hit.what}.\n`
+      + `  proof: ${hit.verdict.why}\n`
+      + `  cost:  ${hit.costs}\n`
+      + `  fix:   ${hit.fix}\n`
+      + 'This refuses rather than warns on purpose: the warning WAS printed, on every write, for '
+      + 'three days, and read. Repair the store, then repeat the action.',
+  };
+}
+
+/**
+ * WHICH COMMANDS DEPEND ON DURABLE MEMORY. The probe shells out to ruflo + sqlite3, so running it on
+ * every Bash call would add seconds to every command and become the next thing someone disables.
+ * It fires only where a false success actually costs something: recording a lesson into a store that
+ * drops it, or shipping while claiming the project learned something it did not.
+ */
+export const DEPENDENT_COMMANDS = [
+  // `cat lesson-bridge.mjs` used to match `record-lesson`, so READING the file needed to fix a
+  // degradation was refused while degraded. The verb has to be in the pattern, not just the noun.
+  { event: 'record-lesson', match: /\bruflo\s+memory\s+store\b|lesson-bridge\.mjs\s+--apply/ },
+  // `git -C <path> push` and `git --git-dir=… push` are the forms an agent with absolute paths
+  // actually writes — this environment's own instructions mandate them — and the first version
+  // matched neither. Two independent audits caught that the same day, and both also caught the
+  // inverse: `grep -n "npm publish" docs/…` matched, so reading ABOUT shipping counted as shipping.
+  { event: 'ship', match: /\bgit\b[^|;&]*\bpush\b|\b(?:npm|yarn|pnpm)\s+publish\b|\bgh\s+release\s+create\b|release\.mjs/ },
+];
+
+/**
+ * QUOTED TEXT IS AN ARGUMENT, NOT A COMMAND. The same correction identifier-preflight.mjs needed
+ * hours earlier: the truth-maker is what will EXECUTE, and a prompt, a grep pattern or a commit
+ * message is not that. Without it, `git commit -m "ready to git push"` reads as shipping.
+ */
+const executablePart = (cmd) => String(cmd || '').replace(/"[^"]*"/g, ' ').replace(/'[^']*'/g, ' ');
+
+export function dependentEvent(command, table = DEPENDENT_COMMANDS) {
+  const cmd = executablePart(command);
+  return table.find((c) => c.match.test(cmd))?.event ?? null;
+}
+
+/**
+ * THE CACHE IS GONE, AND ITS REMOVAL IS THE FIX.
+ *
+ * It was keyed `/tmp/ruvnet-degradation-$USER.json` while the probe targets a PER-PROJECT path. Two
+ * independent adversarial audits, blind to each other, each found a different bug in it on the same
+ * day — which is the strongest signal available that the cache, not its key, was the defect:
+ *
+ *   · a DEGRADED project cached ok:false, so `git push` in a HEALTHY project was refused for five
+ *     minutes citing another repo's evidence;
+ *   · a HEALTHY project cached ok:true, so a BROKEN project shipped inside the TTL without ever
+ *     being probed — the direction that actually costs data.
+ *
+ * The probe runs only on `git push`, `npm publish` and `ruflo memory store`: rare, deliberate acts
+ * where one or two seconds is invisible and a wrong answer is expensive. Caching bought latency
+ * nobody was asking for and sold correctness to pay for it. A cache whose key is not the thing that
+ * determines the answer is a restated fact, which is the defect this whole file exists to close.
+ */
+export function cachedDegradations(opts = {}) {
+  return activeDegradations(SIGNATURES, opts);
+}
+
+/**
+ * POLICY ENTRYPOINT — spawned by decision-gate.mjs exactly like the other refusers: payload on
+ * stdin, exit 0 to allow, exit 2 to refuse with the reason on stderr. Deliberately NOT a new hook
+ * mechanism; the invariant this repo already paid for is that ONE process refuses a given tool call.
+ */
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  let payload = '';
+  try { payload = fs.readFileSync(0, 'utf8'); } catch { /* no stdin is not a refusal */ }
+  let input = {};
+  try { input = JSON.parse(payload)?.tool_input ?? {}; } catch { /* malformed payload degrades to allow */ }
+  const event = dependentEvent(input.command);
+  // The overwhelmingly common case: this command does not depend on durable memory. Cost ~0ms.
+  if (!event) process.exit(0);
+  const refusal = refusalFor(event, cachedDegradations());
+  if (!refusal) process.exit(0);
+  process.stderr.write(`⛔ ${refusal.reason}\n`);
+  process.exit(2);
+}

package/plugin/scripts/ground-ruvnet.sh

@@ -177,14 +177,42 @@ fi
 # not prove that the store command wrote the canonical database.
 
 # ── Self-learning flywheel (ruflo ≥3.24, ADR-176) — OFFER it, never switch it on for them ────────
-# Opt-in is a single env var; `harnessLoopOptedIn()` in @claude-flow/cli reads process.env directly,
-# so a project enables it via .claude/settings.json `env`. Unset is a true no-op. We detect BOTH so
-# an already-enabled project is never nagged.
+#
+# ISSUE #138 — CONFIGURED IS NOT OPERATIONAL, AND THIS CONFLATED THEM.
+#
+# The previous detector treated ANY occurrence of the string RUFLO_HARNESS_LOOP in
+# .claude/settings.json as proof the flywheel was on, and then went silent. That is not ruflo's
+# contract. Verified against rUv's source at f35c545, not recalled:
+#
+#   harness-worker.ts:41   /^(1|true|yes|on)$/i.test(process.env.RUFLO_HARNESS_LOOP ?? '')
+#   harness-worker.ts:54   if (!optedIn) return { ran: false, reason: 'opt-in required (…)' }
+#
+# It reads the DAEMON PROCESS ENVIRONMENT. A Claude settings file does not put anything into the
+# environment of a daemon launched by Codex, launchd, systemd, a monitor, or another shell — so the
+# grep proved a FILE MENTIONS A NAME, never that the running daemon inherited it. The Brain then
+# stayed quiet while ruflo recorded "opt-in required" every cycle: a false ENABLED state, which is
+# strictly worse than a false disabled one because nobody goes looking.
+#
+# Same shape as the console learner card (#136): a surface reporting a proxy as if it were the
+# answer. The rule is `lesson-audit-the-answer-not-the-wiring` — a mention is not a measurement.
+#
+# So there are now THREE states, and only the process environment can prove the third:
+#   off        nothing set anywhere            → offer it
+#   declared   a settings file names it, but   → say so, and say what is still missing
+#              THIS process did not inherit it
+#   on         this process HAS it truthy      → stay silent, it is genuinely opted in
 FLYWHEEL=off
 case "${RUFLO_HARNESS_LOOP:-}" in 1|true|yes|on|TRUE|Yes|On) FLYWHEEL=on ;; esac
 if [ "$FLYWHEEL" = "off" ] && grep -qs 'RUFLO_HARNESS_LOOP' .claude/settings.json .claude/settings.local.json 2>/dev/null; then
-  FLYWHEEL=on
+  FLYWHEEL=declared
 fi
+# THE SECOND GATE, and it is not optional (ruflo #2840 / PR #2848). A downstream project must ALSO
+# carry a hash-pinned project-local anchor or the runtime fails closed with
+# "project-local flywheel anchor required" — harness-project-anchor.ts:186. Its canonical path is
+# DEFAULT_PROJECT_ANCHOR_MANIFEST = .claude/eval/flywheel-anchor.manifest.json (same file, :32).
+# Guidance that omits it cannot produce a working setup, which is why "TURN IT ON" below now names it.
+ANCHOR=missing
+[ -f .claude/eval/flywheel-anchor.manifest.json ] && ANCHOR=present
 
 # The cadence belongs to the hook, not to an instruction asking the model to remember whether it
 # already spoke (issue #53). A directory create is the portable atomic primitive here: for one
@@ -208,18 +236,30 @@ claim_flywheel_day() {
   )
 }
 
-if [ "$RUFLO_STATE" = "yes" ] && [ "$FLYWHEEL" = "off" ] && claim_flywheel_day; then
+if [ "$RUFLO_STATE" = "yes" ] && [ "$FLYWHEEL" != "on" ] && claim_flywheel_day; then
   cat <<'EOF'
-[RuvNet Brain — the self-learning flywheel is available here and switched OFF]
-This project runs Ruflo, and ruflo ≥3.24 ships a self-optimizing flywheel that is OFF by default. Offer it plainly and warmly — then drop it. NEVER enable it without an explicit yes. The hook enforces the delivery cadence; do not repeat this advisory yourself.
+[RuvNet Brain — the self-learning flywheel is available here and is NOT running]
+This project runs Ruflo, and ruflo ≥3.24 ships a self-optimizing flywheel that is OFF by default.
+IF a settings file already names RUFLO_HARNESS_LOOP, say so plainly and do not call it enabled: a
+settings entry is not the daemon's environment, and ruflo reports "opt-in required" until the
+process that runs the loop actually carries it. Configured is not operational. Offer it plainly and warmly — then drop it. NEVER enable it without an explicit yes. The hook enforces the delivery cadence; do not repeat this advisory yourself.
 
 Explain it in the user's words, not the plumbing's:
 - WHAT IT IS: ruflo can improve one of its own operating policies over time — specifically how it finds the right stored memory for a query (the BM25/cosine blend, diversity, etc.). Each candidate is scored against a frozen, human-labelled relevance set; a change is promoted ONLY if it measurably beats the current champion on held-out data. Every promotion leaves a signed receipt you can replay yourself, and a drift canary auto-rolls-back on regression. Think "git for decision-policies": each generation has a parent, a diff, evidence, a signature, and an immutable root you can walk back to.
 - WHY IT'S DIFFERENT: most "self-improving agent" claims are unfalsifiable. This one only turns the wheel when an improvement is independently proven, and it hands you the receipt.
 - WHAT IT COSTS: $0. No LLM calls and no network on the decision path.
-- HONEST CAVEAT (say this, don't hide it): it stays idle until the project has accumulated at least 12 stored neural patterns to harvest a corpus from. Before that it reports "store too small" and does nothing. On a brand-new project that means it earns its keep later, not today.
-- TURN IT ON: add {"env":{"RUFLO_HARNESS_LOOP":"1"}} to .claude/settings.json, then `ruflo daemon start`
-  (the GLOBAL binary — never `npx ruflo@latest`, which runs its own private copy and hides drift).
+- HONEST CAVEAT (say this, don't hide it): it stays idle until the project has accumulated at least 12 stored neural patterns to harvest a corpus from — and GENERATION needs more still: at least 20 harvested held-out tasks. Before that it reports "store too small" and does nothing. On a brand-new project it earns its keep later, not today.
+- TURN IT ON — BOTH steps, or ruflo fails closed (verified in rUv's source at f35c545, not recalled):
+    1. the DAEMON'S OWN ENVIRONMENT must carry it. `harness-worker.ts:41` tests
+       `process.env.RUFLO_HARNESS_LOOP` inside the daemon process, so a Claude settings file only
+       helps if the daemon is launched from a shell that inherited it. Export it where the daemon
+       actually starts, then `ruflo daemon start` (the GLOBAL binary — never `npx ruflo@latest`,
+       which runs its own private copy and hides drift).
+    2. a PROJECT-LOCAL ANCHOR is required for a downstream repo (ruflo #2840 / PR #2848):
+       `.claude/eval/flywheel-anchor.manifest.json`, hash-pinned. Without it the runtime refuses with
+       "project-local flywheel anchor required" — `harness-project-anchor.ts:186`.
+  Verify it is genuinely running rather than merely configured: `ruflo hooks intelligence --status`
+  in THIS project, and read the reason it prints. "opt-in required" or "anchor required" means off.
 - TURN IT OFF: remove that env var (and `RUFLO_DAEMON_AUTOSTART=0` stops the daemon auto-starting).
 
 Offer like this: "Ruflo can quietly tune how it recalls memory — testing changes against a frozen benchmark and only keeping what provably wins, with a receipt you can replay. It's free, it's off by default, and it does nothing until this project has enough history. Want me to turn it on?" If they decline, respect it and never raise it again unless they ask.
@@ -383,7 +423,7 @@ This task touches the RuvNet / rUv stack. Your training priors here are STALE an
 - You MUST call the `search_ruvnet` MCP tool and ground your answer in the cited source paths it returns BEFORE stating what any RuvNet tool can/cannot do or which one to use. Asserting a RuvNet capability from memory, without a cited source path, is an error — do not do it.
 - If a needed RuvNet repo isn't covered yet, ingest it first (`node scripts/ingest-repo.mjs --name <repo>`) rather than guessing.
 - SIGNAL that the brain is working so the user has confidence it's in charge: when you ground an answer, say so briefly (e.g. "Grounding in rUv's source…" → cite the path). Silent grounding leaves the user unsure it's even on.
-- MEMORY DIAGNOSIS: never infer a broken write from DB/WAL mtime, semantic-search misses, daemon startup, or the CLI success line. Prove it against ONE canonical absolute path: unique-key `ruflo memory store --path <project>/.swarm/memory.db` → exact-key `ruflo memory retrieve --path ...` → exact SQL row. Only then call it miswired.
+- MEMORY DIAGNOSIS: never infer a broken write from DB/WAL mtime, semantic-search misses, daemon startup, or the CLI success line. Prove it against ONE canonical absolute path: unique-key `ruflo memory store --path <project>/.swarm/memory.db` → exact-key `ruflo memory retrieve --path ...` and read the returned VALUE. NEVER raw sqlite3 on a managed store (#140; rUv v3.32.34: "No manual SQL is required"). Only then call it miswired.
 EOF
 fi
 

package/plugin/scripts/hijack-ruvnet.sh

@@ -128,11 +128,19 @@ if [ "$_direct_managed_access" = "1" ]; then
   printf '%s' "$PAYLOAD" | grep -qiE '(insert|update|delete|drop|alter|create|replace|vacuum|pragma[[:space:]]+[a-z_]+[[:space:]]*=|\.import|\.restore)' && _is_write=1
 
   if [ "$_boundary" = "block" ] || { [ "$_boundary" = "read-only" ] && [ "$_is_write" = "1" ]; }; then
+    # NAME THE STORE THEY ACTUALLY REACHED FOR (#140). The reporter was at a USER-level store,
+    # `~/.claude-flow/user-memory.db`; a refusal that hardcodes <project>/.swarm/memory.db points
+    # them at a DIFFERENT file, so the "sanctioned path" reads as not understanding the situation
+    # — and an agent that cannot see its own store in the substitute goes back to guessing schema,
+    # which is the exact failure #103 measured nine times.
+    _target_store=$(printf '%s' "$PAYLOAD" | grep -oiE '[^ "]*(\.swarm/[a-zA-Z-]*memory\.db|user-memory\.db|agentdb[a-zA-Z-]*\.db|memory\.db)' | head -n 1)
+    [ -z "$_target_store" ] && _target_store="<project>/.swarm/memory.db"
     printf '%s\n' "[RuvNet Brain] REFUSED: direct access to a Ruflo-managed memory store." >&2
     printf '%s\n' "Your setting managedMemoryBoundary=$_boundary refuses this. Ruflo owns these stores; two writers on one file is how they corrupt." >&2
-    printf '%s\n' "Use the sanctioned path instead — it needs no schema knowledge:" >&2
-    printf '%s\n' "  ruflo memory search  -q \"<query>\" --path <project>/.swarm/memory.db" >&2
-    printf '%s\n' "  ruflo memory store   -k \"<key>\" --value \"<text>\" --path <project>/.swarm/memory.db" >&2
+    printf '%s\n' "Use the sanctioned path instead — it needs no schema knowledge, and --path reaches ANY store, user-level ones included:" >&2
+    printf '%s\n' "  ruflo memory search   -q \"<query>\" --path $_target_store" >&2
+    printf '%s\n' "  ruflo memory retrieve -k \"<key>\"   --path $_target_store   # exact key; the returned VALUE is the proof" >&2
+    printf '%s\n' "  ruflo memory store    -k \"<key>\" --value \"<text>\" --path $_target_store" >&2
     printf '%s\n' "To allow this, set managedMemoryBoundary back to 'advise' (or 'read-only' for reads) in the Console." >&2
     exit 2
   fi

package/plugin/scripts/hook-registry.mjs

@@ -18,17 +18,28 @@
  * plus the derived fields the lint needs (`handler`, `shimId`, `codeRoot`, `hasFailsafe`,
  * `declaredMode`, `tools`, `anchored`, `asyncRewake`, `contractSource`).
  *
- * THE SIX REGISTRIES (ADR-055 appendix A), and one deliberate split:
+ * THE SEVEN REGISTRIES (ADR-055 appendix A plus the Codex host, added 2026-08-20 — Dream Cycle
+ * cross-host-conformance finding: this file enumerated six registries and Codex's was not one of
+ * them, so none of M1/M3/M5/M6 had ever run over `codex-hooks.json`), and one deliberate split:
  *
  *   layer                | file                                                    | inMesh
  *   ---------------------|---------------------------------------------------------|-------
  *   plugin               | <repo>/plugin/hooks/hooks.json                          | yes
+ *   codex                | <repo>/plugin/hooks/codex-hooks.json                    | yes
  *   user                 | ~/.claude/settings.json                                 | yes
  *   project              | <repo>/.claude/settings.json                            | yes
  *   third-party:<name>   | <plugin install>/hooks/hooks.json (enabled plugins only)| yes
  *   plugin-installed     | ~/.claude/plugins/cache/ruvnet-brain/<v>/hooks/hooks.json | NO (mirror)
  *   marketplace-clone    | ~/.claude/plugins/marketplaces/ruvnet-brain/…/hooks.json | NO (mirror)
  *
+ * CODEX RECORDS NEVER ROUTE THROUGH `hook-shim.mjs` — Codex's own wrapper chain
+ * (`codex-hook-wrapper.mjs` → `codex-hook-adapter.mjs`) resolves the active spine generation and
+ * dispatches by a trailing CLI token instead (`codexDispatchIdIn()`, below). That token is drawn
+ * from the SAME id space as `hook-shim.mjs`'s dispatch TABLE — verified 2026-08-20: every id
+ * `codex-hooks.json` uses (`decision-gate`, `route-dispatch`, `learn-capture`, …) already exists as
+ * a table key — so a codex registration's `mode`/`offBehavior` resolve from that one table too,
+ * exactly like a plugin registration. No new contract file, no invented declaration.
+ *
  * The last two are the SAME registrations as `plugin`, delivered as different code copies — the
  * repo copy is the preimage, the cache copy is what Claude Code booted, the marketplace clone is
  * what the user layer's own commands execute from. Counting all three in the mesh would invent 30
@@ -105,6 +116,10 @@ export const TOOL_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
 export const TOOLS = Object.freeze([
   'Task', 'TaskStop', 'Agent', 'Bash', 'BashOutput', 'Read', 'Write', 'Edit', 'MultiEdit',
   'NotebookEdit', 'NotebookRead', 'Glob', 'Grep', 'WebFetch', 'WebSearch', 'TodoWrite', 'Skill',
+  // Codex's own tool names (ADR-051) — `exec_command` and `apply_patch` are what `codex-hooks.json`
+  // matchers actually target; without them here M5 could not see whether a Codex matcher anchors
+  // the tool it claims to guard.
+  'exec_command', 'apply_patch',
 ]);
 
 /** `*` and `.*` and `` are Claude Code's "everything" spellings; `*` is not a legal regex. */
@@ -149,6 +164,19 @@ export function shimIdIn(command) {
   return m ? m[1] : null;
 }
 
+/**
+ * The Codex wrapper's dispatch id. `codex-hooks.json` never names `hook-shim.mjs` — its inline
+ * bootstrap (`node -e "<script>" <budgetMs> <hookId>[ <extra>]`) spawns `codex-hook.mjs` and hands
+ * it `<hookId>` as `process.argv[2]`, exactly as `codex-hook-wrapper.mjs` itself reads it
+ * (`const hookId = process.argv[2] || '';`). The closing quote of the `-e` argument followed by a
+ * bare number is what marks where the CLI args begin; verified against all 16 live entries
+ * 2026-08-20, zero false matches.
+ */
+export function codexDispatchIdIn(command) {
+  const m = (command ?? '').match(/"\s+\d+\s+([a-zA-Z][\w-]*)/);
+  return m ? m[1] : null;
+}
+
 /**
  * hook-shim.mjs's dispatch TABLE, parsed rather than re-implemented — it is the authority for
  * `mode` and `offBehavior` on every shim-routed registration (ADR-054 §3: the OFF contract lives in
@@ -313,8 +341,13 @@ export function discoverSources({ repo = REPO, home = os.homedir(), includeMachi
   // so the mesh census silently described a machine with no shipped hooks at all.
   const pluginHooks = ['plugin/hooks/hooks.json', 'hooks/hooks.json']
     .map((rel) => path.join(repo, rel));
+  const codexHooks = ['plugin/hooks/codex-hooks.json', 'hooks/codex-hooks.json']
+    .map((rel) => path.join(repo, rel));
   const sources = [
     { layer: 'plugin', file: pluginHooks.find((f) => fs.existsSync(f)) ?? pluginHooks[0], role: 'shipped', inMesh: true, reachesStrangers: true, machineLocal: false },
+    // Repo-owned and shipped exactly like `plugin` (package.json ships the whole `plugin/` tree) —
+    // just a different host manifest, so it belongs in the same CI-gated block, not the machine one.
+    { layer: 'codex', file: codexHooks.find((f) => fs.existsSync(f)) ?? codexHooks[0], role: 'shipped', inMesh: true, reachesStrangers: true, machineLocal: false },
     { layer: 'project', file: path.join(repo, '.claude/settings.json'), role: 'active', inMesh: true, reachesStrangers: false, machineLocal: false },
   ];
   if (includeMachine) {
@@ -345,7 +378,12 @@ export function buildRegistry({ repo = REPO, home = os.homedir(), includeMachine
     try { regs = readRegistrations(src.file); } catch (e) { errors.push({ file: src.file, layer: src.layer, error: String(e.message ?? e) }); continue; }
     for (const r of regs) {
       const shimId = shimIdIn(r.command);
-      const shim = shimId ? table[shimId] : null;
+      // Codex commands never name hook-shim.mjs, so shimId is always null there — fall back to the
+      // Codex wrapper's own dispatch token, which is drawn from the same table (see the header note
+      // above codex-hooks.json's row in this file's doc comment).
+      const codexHookId = !shimId && src.layer === 'codex' ? codexDispatchIdIn(r.command) : null;
+      const dispatchId = shimId ?? codexHookId;
+      const shim = dispatchId ? table[dispatchId] : null;
       const base = {
         layer: src.layer,
         file: src.file,
@@ -363,7 +401,8 @@ export function buildRegistry({ repo = REPO, home = os.homedir(), includeMachine
         inMesh: src.inMesh,
         machineLocal: src.machineLocal,
         shimId,
-        handler: shim?.file ?? basenamesIn(r.command).filter((b) => b !== 'hook-shim.mjs').pop() ?? null,
+        codexHookId,
+        handler: shim?.file ?? basenamesIn(r.command).filter((b) => b !== 'hook-shim.mjs' && b !== 'codex-hook.mjs').pop() ?? null,
         hasFailsafe: hasFailsafe(r.command),
         anchored: isAnchored(r.matcher),
         tools: matchedTools(r.matcher, r.event),
@@ -409,6 +448,12 @@ export function codeRootOf(rec, repo = REPO, home = os.homedir()) {
     // plugin root — that indirection is the whole point of ADR-023.
     return rec.shimId ? 'spine' : 'plugin-root';
   }
+  if (rec.layer === 'codex') {
+    // codex-hook-wrapper.mjs's activeRoot() resolves the SAME active spine generation
+    // (`$RUVNET_BRAIN_HOME/versions/<gen>`) that hook-shim.mjs resolves for Claude Code — the two
+    // wrappers are two doors onto one axis, so a dispatch-table hit is 'spine' here too.
+    return rec.codexHookId ? 'spine' : 'unknown';
+  }
   // (`<user>` below is a DECLARED placeholder from codex-wiring.test.mjs's allowlist, not a real
   // account. That scan covers everything under plugin/, which this file joined in ADR-065; the
   // example previously wrote an ellipsis where the account name goes, and an ellipsis is

package/plugin/scripts/hook-shim.mjs

@@ -97,6 +97,13 @@ const TABLE = {
   // The consent guard (ADR-054 §3): it protects the OFF state itself, so it is the one hook that
   // matters MORE while the brain is off. 'run', permanently.
   'protect-state':    { file: 'protect-brain-state.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
+  // THE REFUSAL CHOKEPOINT (ADR-067). ONE PreToolUse decision, composed from every policy that could
+  // refuse, with declared precedence and ONE reason. It replaces four independent hooks that could
+  // each exit 2 on the same Write with no precedence and no shared context — the concrete form of
+  // "constraints that collapse on each other". Same shape as 'unprompted-speech' one layer up: that
+  // one is the sole writer of unprompted BYTES, this one is the sole author of a REFUSAL. The four
+  // policies it consults are unchanged and still individually tested; the gate only composes them.
+  'decision-gate':    { file: 'decision-gate.mjs',   interpreter: 'node', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   'learn-capture':    { file: 'learn-capture.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'learn-flush':      { file: 'learn-flush.mjs',     interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 65536 },
@@ -218,6 +225,50 @@ function readHookInput(limit) {
   });
 }
 
+/**
+ * THE LOUD FALLBACK, ONCE — not once per hook fire (2026-08-14).
+ *
+ * Finding 25 is right that a broken spine must never masquerade as health, and the message below is
+ * KEPT verbatim for that reason. What was wrong was the CADENCE. Both fallback lines were written on
+ * EVERY invocation, and this shim is registered ~19 times across the two manifests, on
+ * UserPromptSubmit / PreToolUse / PostToolUse / Stop. Measured on a seeded-but-broken spine: five
+ * consecutive fires of ONE hook id produced five identical stderr lines; a single prompt that runs a
+ * few tools fires far more than five. stderr is precisely what a host renders as "hook error", so a
+ * broken spine did not report itself once — it reported itself as the owner's literal complaint,
+ * "a ton of hook errors".
+ *
+ * Loudness is a fair design choice. Loudness PER INVOCATION is not information; it is noise that
+ * gets the whole surface muted, which is how a real warning stops being read.
+ *
+ * KEYED BY GENERATION + KIND, in a marker file — the same shape as skipNoBash's notice, and for the
+ * same reason. The key changes when the spine changes, so a NEW breakage always announces itself
+ * even if an older one was already reported.
+ *
+ * WHY A TTL RATHER THAN A TRUE SESSION ID, stated plainly rather than implied: no session identifier
+ * reaches this dispatcher. Claude Code does not set CLAUDE_SESSION_ID (learn-flush.mjs documents the
+ * same finding), and the only place `session_id` exists is the stdin payload — which the majority of
+ * these table entries deliberately never read. So the window is an approximation of a session, not a
+ * claim to be one: it bounds a persistent breakage to roughly one line per working session instead
+ * of one per tool call, and re-announces it in tomorrow's session rather than going silent forever.
+ * Never let it block or fail: a notice we could not record is still worth saying.
+ */
+const NOTICE_FILE = path.join(BRAIN_HOME, '.spine-fallback-notice');
+const NOTICE_TTL_MS = Number(process.env.RUVNET_SPINE_NOTICE_TTL_MS ?? 4 * 3600_000);
+function warnOnce(key, message) {
+  try {
+    const prev = JSON.parse(fs.readFileSync(NOTICE_FILE, 'utf8'));
+    const at = Date.parse(prev?.at || '');
+    // Same breakage, still inside the window → already said. Anything else (different key, no
+    // marker, unparseable marker, expired window) falls through and speaks.
+    if (prev?.key === key && Number.isFinite(at) && (Date.now() - at) <= NOTICE_TTL_MS) return;
+  } catch { /* no marker yet, or unreadable → say it */ }
+  try {
+    fs.mkdirSync(BRAIN_HOME, { recursive: true });
+    fs.writeFileSync(NOTICE_FILE, JSON.stringify({ key, at: new Date().toISOString() }) + '\n');
+  } catch { /* best effort — an unrecordable claim must not cost us the warning */ }
+  process.stderr.write(message);
+}
+
 /** Resolve the active code root. Returns { root, source } or null (→ fallback). */
 function resolveCodeRoot() {
   // Dev mode wins when explicitly declared and the target still looks like the checkout it names.
@@ -293,14 +344,18 @@ function dispatchHook() {
     if (fs.existsSync(spineFile)) {
       return runHook(spineFile);
     }
-    // Spine resolved but the body file is missing — fall back LOUDLY (finding 25).
-    process.stderr.write(`[hook-shim] spine (${spine.source}) missing ${entry.file} — falling back to frozen plugin\n`);
+    // Spine resolved but the body file is missing — fall back LOUDLY (finding 25), once per
+    // generation. The key omits entry.file on purpose: one broken generation is ONE piece of news,
+    // and keying per hook would put ~19 identical diagnoses of the same fault on the user's screen.
+    warnOnce(`missing-body:${spine.source}`,
+      `[hook-shim] spine (${spine.source}) missing ${entry.file} — falling back to frozen plugin\n`);
     return runHook(fallbackFile);
   }
   // No spine at all. First-install is the normal quiet case; a previously-seeded-but-broken spine
   // still lands here — the seed marker distinguishes them so breakage is loud, first-run silent.
   if (fs.existsSync(path.join(BRAIN_HOME, '.spine-seeded'))) {
-    process.stderr.write(`[hook-shim] spine unreadable — running frozen plugin fallback (run: node scripts/update-apply.mjs --doctor)\n`);
+    warnOnce('no-spine',
+      `[hook-shim] spine unreadable — running frozen plugin fallback (run: node scripts/update-apply.mjs --doctor)\n`);
   }
   return runHook(fallbackFile);
 }