ruvnet-brain 4.0.6 → 4.0.8

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

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SNAPSHOT_SCHEMA = 'ruvnet-brain.session-snapshot';
+export const SNAPSHOT_VERSION = 1;
+export const SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+const EVENTS = new Set(['PreCompact', 'PostCompact', 'SessionEnd']);
+
+export function createSessionSnapshot({ event, capturedAt = new Date().toISOString() }) {
+  if (!EVENTS.has(event)) throw new Error(`unsupported snapshot event: ${event}`);
+  if (!Number.isFinite(Date.parse(capturedAt))) throw new Error('capturedAt must be an ISO-8601 timestamp');
+  return {
+    schema: SNAPSHOT_SCHEMA,
+    version: SNAPSHOT_VERSION,
+    capturedAt,
+    boundary: { event },
+    privacy: { rawTranscriptStored: false, credentialValuesStored: false },
+  };
+}
+
+export function validateSessionSnapshot(value) {
+  return Boolean(value)
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && value.schema === SNAPSHOT_SCHEMA
+    && value.version === SNAPSHOT_VERSION
+    && EVENTS.has(value.boundary?.event)
+    && Number.isFinite(Date.parse(value.capturedAt))
+    && value.privacy?.rawTranscriptStored === false
+    && value.privacy?.credentialValuesStored === false;
+}
+
+function freshness(capturedAt, now) {
+  const age = now - Date.parse(capturedAt);
+  return age >= 0 && age <= SNAPSHOT_MAX_AGE_MS;
+}
+
+function canonical(projectDir, now) {
+  const file = path.join(projectDir, '.swarm', 'agentdb-sessions.jsonl');
+  if (!fs.existsSync(file)) return { values: [], malformed: false };
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024) {
+      return { values: [], malformed: true };
+    }
+    const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean).slice(-128);
+    const values = [];
+    let malformed = false;
+    for (const line of lines) {
+      try {
+        const value = JSON.parse(line);
+        if (validateSessionSnapshot(value)) values.push({ kind: 'canonical', fresh: freshness(value.capturedAt, now), capturedAt: value.capturedAt });
+        else malformed = true;
+      } catch { malformed = true; }
+    }
+    return { values, malformed };
+  } catch { return { values: [], malformed: true }; }
+}
+
+function legacy(projectDir, now) {
+  const values = [];
+  let malformed = false;
+  for (const root of ['.claude', '.claude-flow']) {
+    const directory = path.join(projectDir, root, 'sessions');
+    if (!fs.existsSync(directory)) continue;
+    let names;
+    try {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return { values: [], malformed: true };
+      names = fs.readdirSync(directory).filter((name) => /^session-.*\.json$/.test(name)).slice(-64);
+    } catch { malformed = true; continue; }
+    for (const name of names) {
+      try {
+        const file = path.join(directory, name);
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) { malformed = true; continue; }
+        const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const capturedAt = value.endedAt || value.startedAt;
+        if (typeof value.id !== 'string' || !value.id || !value.context || !value.metrics || !Number.isFinite(Date.parse(capturedAt))) {
+          malformed = true;
+          continue;
+        }
+        values.push({ kind: 'legacy', fresh: freshness(capturedAt, now), capturedAt });
+      } catch { malformed = true; }
+    }
+  }
+  return { values, malformed };
+}
+
+export function inspectSessionSnapshots(projectDir, { now = Date.now() } = {}) {
+  const results = [canonical(projectDir, now), legacy(projectDir, now)];
+  const values = results.flatMap((result) => result.values);
+  const priority = { canonical: 0, legacy: 1 };
+  const fresh = values.filter((value) => value.fresh).sort((a, b) => priority[a.kind] - priority[b.kind] || Date.parse(b.capturedAt) - Date.parse(a.capturedAt))[0];
+  if (fresh) return fresh;
+  if (values.length) return values.sort((a, b) => priority[a.kind] - priority[b.kind] || Date.parse(b.capturedAt) - Date.parse(a.capturedAt))[0];
+  if (results.some((result) => result.malformed)) return { kind: 'malformed', fresh: false };
+  return { kind: 'absent', fresh: false };
+}

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

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createSessionSnapshot } from './session-snapshot-contract.mjs';
+
+function regularOrAbsent(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch (error) {
+    return error?.code === 'ENOENT';
+  }
+}
+
+export function writeSessionSnapshot(projectDir, event) {
+  const swarm = path.join(projectDir, '.swarm');
+  const target = path.join(swarm, 'agentdb-sessions.jsonl');
+  try {
+    if (fs.existsSync(swarm)) {
+      const stat = fs.lstatSync(swarm);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    } else {
+      fs.mkdirSync(swarm, { recursive: false, mode: 0o700 });
+    }
+    if (!regularOrAbsent(target)) return false;
+    fs.appendFileSync(target, `${JSON.stringify(createSessionSnapshot({ event }))}\n`, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
+  writeSessionSnapshot(process.env.CLAUDE_PROJECT_DIR || process.cwd(), process.argv[2] || 'SessionEnd');
+}

package/plugin/scripts/session-start-core.mjs

@@ -62,9 +62,30 @@ const dispatchDetached = (hookDir, ttl, log, command, args = [], env = process.e
     String(ttl), log, command, ...args,
   ], { env, stdio: 'ignore', timeout: 2000 })?.status === 0;
 
-const surfaceIssues = (stateDir, emit, now) => {
+export const maintainerIssueEntitlement = (env, home, repo, platform = process.platform) => {
+  const file = env.RUVNET_BRAIN_MAINTAINER_ISSUES_FILE
+    || path.join(home, '.config', 'ruvnet-brain', 'maintainer-issues.json');
+  // Windows ACL ownership is not available through this dependency-free hot path. Fail closed
+  // instead of weakening an owner-only promise into "any local user who can write the file".
+  if (platform === 'win32') return false;
+  let stat;
+  try { stat = fs.lstatSync(file); } catch { return false; }
+  if (!stat.isFile() || stat.isSymbolicLink()) return false;
+  // This is maintainer-only operational data. Refuse group/world-readable opt-ins on POSIX so a
+  // shared machine cannot turn a private maintainer signal into a terminal banner for other users.
+  if ((stat.mode & 0o077) !== 0) return false;
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) return false;
+  const entitlement = json(file);
+  return entitlement?.enabled === true
+    && Array.isArray(entitlement.repos)
+    && entitlement.repos.includes(repo);
+};
+
+const surfaceIssues = (stateDir, emit, now, env, home, platform) => {
   const status = json(path.join(stateDir, 'open-issues.json'));
-  if (!status?.at || now - new Date(status.at).getTime() > 6 * 3600_000) return;
+  const observedAt = Date.parse(status?.at || '');
+  if (!Number.isFinite(observedAt) || observedAt > now + 5 * 60_000 || now - observedAt > 6 * 3600_000) return;
+  if (!maintainerIssueEntitlement(env, home, status.repo, platform)) return;
   const open = Array.isArray(status.issues) ? status.issues : [];
   if (!open.length) return;
   const breaches = open.filter((issue) => issue.breach).sort((a, b) => b.ageHours - a.ageHours);
@@ -383,7 +404,7 @@ export async function runSessionStart({
       emit(`Offer ONCE: "Want to see your whole RuvNet stack on one page?" — installed parts, learned project knowledge and reversible fixes, read-only until clicked; later it's ${consoleInvoke}. On yes invoke ${consoleInvoke}; on no, don't re-offer.`);
     }
 
-    surfaceIssues(stateDir, emit, now);
+    surfaceIssues(stateDir, emit, now, env, home, platform);
     surfaceSignals({ env, cwd, stateDir, hookDir, emit, now });
 
     const routerProfile = path.join(home, '.claude', 'model-router', 'profile.json');
@@ -476,10 +497,7 @@ export async function runSessionStart({
 
       const playbook = `${hookDir}${path.sep}..${path.sep}skills${path.sep}ruvnet-brain${path.sep}PLAYBOOK.md`;
       emit('[RuvNet Brain — standing build playbook for this session (referenced by later turns as THE PLAYBOOK)]');
-      emit(`Full text: ${playbook} — read it before your first build response this session. Condensed:`);
-      emit('Every build/change request: take the wheel. FIRST, silently — read the files this touches in THEIR repo; search_ruvnet what the feature technically DOES; check project memory.');
-      emit('⛔ NO SILENT SUBSTITUTION (#1 trust-killer): never hand-roll, or aim a generic Task subagent at, work a RuvNet tool owns — QE=agentic-qe, swarms=ruflo, routing=agentic-flow, vectors=RuVector, memory=AgentDB, red/blue=@metaharness/redblue. Use the real one; if absent offer the exact install; if unusable say so out loud, every time. Never give your own code its name.');
-      emit('Beats A-D are in that file, in full. In short: A RESPOND in one voice (hear them; THE ATTACK as one lettered plan over their real files; why it holds; what you checked; "Build it now?") · B ON A YES EXECUTE END-TO-END (SPARC with a QA gate per phase, DDD, ADRs, PARALLEL Ruflo swarm work, AgentDB persistence, frontend-design + real image generation, a PROVEN result scored to >=98, ONE ask for a missing API key) · C TAKE OVER what you do well · D keep them oriented. RUN THE PROCESS.');
+      emit(`Read ${playbook} before the first build response. It requires source inspection, search_ruvnet grounding, project-memory recall, and the real owning rUv tool—never a silent hand-roll or generic substitute.`);
     }
   } catch (error) {
     if (env.RUVNET_SESSION_TRACE === '1') stderr.write(`SESSION_TRACE native-fail-open ${error?.message || error}\n`);

package/plugin/scripts/swarm-slot-recycler.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// swarm-slot-recycler.mjs — Claude Code TeammateIdle recycling boundary.
+//
+// Claude owns the shared task files and their claim locks. This hook never edits them. It reads the
+// team ledger at the synchronous TeammateIdle boundary and refuses idling only when it can prove an
+// unassigned pending task is ready. Claude then performs the normal locked TaskUpdate claim. Missing,
+// malformed, dependency-blocked, or ambiguous state fails open: a scheduler must not invent work.
+//
+// Host boundary: Claude Code exposes TeammateIdle; Codex 0.146.0 exposes SubagentStop but no
+// TeammateIdle/TaskCompleted event or equivalent shared-task ledger. Do not register this body in the
+// Codex manifest and do not claim Codex recycling is hook-enforced.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readStdinBounded } from './hook-input.mjs';
+
+const MAX_INPUT_BYTES = 64 * 1024;
+const MAX_TASK_BYTES = 256 * 1024;
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function allowIdle() { process.exit(0); }
+
+let raw = Buffer.alloc(0);
+try {
+  raw = await readStdinBounded({ maxBytes: MAX_INPUT_BYTES, idleMs: 50, emptyMs: 250 });
+} catch { allowIdle(); }
+
+let event;
+try {
+  event = JSON.parse(raw.toString('utf8'));
+} catch { allowIdle(); }
+
+if (!event || typeof event !== 'object' || Array.isArray(event)) allowIdle();
+if (event.hook_event_name !== 'TeammateIdle') allowIdle();
+
+const teamName = String(event.team_name || '');
+const teammateName = String(event.teammate_name || '');
+if (!SAFE_NAME.test(teamName) || !SAFE_NAME.test(teammateName)) allowIdle();
+
+const tasksRoot = process.env.RUVNET_CLAUDE_TASKS_DIR
+  || path.join(os.homedir(), '.claude', 'tasks');
+const teamDir = path.resolve(tasksRoot, teamName);
+const root = path.resolve(tasksRoot);
+if (path.dirname(teamDir) !== root) allowIdle();
+
+let files;
+try {
+  files = fs.readdirSync(teamDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /^\d+\.json$/.test(entry.name))
+    .map((entry) => entry.name);
+} catch { allowIdle(); }
+
+const tasks = new Map();
+for (const file of files) {
+  try {
+    const taskPath = path.join(teamDir, file);
+    const stat = fs.statSync(taskPath);
+    if (!stat.isFile() || stat.size > MAX_TASK_BYTES) continue;
+    const task = JSON.parse(fs.readFileSync(taskPath, 'utf8'));
+    if (!task || typeof task !== 'object' || Array.isArray(task)) continue;
+    const id = String(task.id || path.basename(file, '.json'));
+    if (!/^\d+$/.test(id)) continue;
+    tasks.set(id, task);
+  } catch { /* one bad task cannot make another look ready */ }
+}
+
+const completed = new Set(
+  [...tasks].filter(([, task]) => task.status === 'completed').map(([id]) => id),
+);
+
+const ready = [...tasks]
+  .filter(([, task]) => task.status === 'pending')
+  .filter(([, task]) => !String(task.owner || '').trim())
+  .filter(([, task]) => {
+    if (!Array.isArray(task.blockedBy)) return false;
+    return task.blockedBy.every((id) => completed.has(String(id)));
+  })
+  .sort(([left], [right]) => Number(left) - Number(right));
+
+if (!ready.length) allowIdle();
+
+const [id, task] = ready[0];
+const subject = String(task.subject || 'untitled task').replace(/[\r\n]+/g, ' ').slice(0, 160);
+process.stderr.write(
+  `Ready work remains. Claim task ${id} (${subject}) now with TaskUpdate owner=${teammateName} `
+  + 'and status=in_progress, then execute it. Do not go idle while an unassigned, unblocked pending task exists.\n',
+);
+process.exit(2);

package/plugin/skills/release-proof/SKILL.md

@@ -30,10 +30,10 @@ green.
 ## Candidate seal
 
 Generate the receipt from commands in the protected candidate workflow. Do not hand-author it.
-For generation 4.0.4, dispatch `.github/workflows/protected-release.yml` only with the full candidate
-SHA, sealed artifact SHA-256, exact version `4.0.4`, and the successful exact-SHA CI run ID whose
-named `release-qe` job produced `release-evidence-<sha>`. The workflow checks every binding before
-creating its sealed handoff and again after the production reviewer approves. Missing artifacts,
+Dispatch `.github/workflows/protected-release.yml` only with the full candidate SHA, the exact
+current version, and the successful exact-SHA CI run ID whose named `release-qe` job produced
+`release-evidence-<sha>`. The workflow derives the artifact digest from those sealed bytes and checks
+every binding before creating its handoff and again at the Production boundary. Missing artifacts,
 pending/red jobs, malformed inputs, version splits, and byte mismatches stop before the publisher.
 Validate it from the repository with:
 

package/plugin/skills/release-proof/scripts/release-proof.mjs

@@ -145,8 +145,11 @@ export function evaluatePublicationReceipt(candidate, publication) {
   const failures = [...candidateResult.failures];
   const sha = candidateResult.sha;
   const digest = candidateResult.artifactSha256;
-  if (publication?.schemaVersion !== 1 || publication?.phase !== 'publication') failures.push(fail('INVALID_PUBLICATION_RECEIPT', 'schemaVersion=1 and phase=publication are required'));
+  if (publication?.schemaVersion !== 2 || publication?.phase !== 'publication') failures.push(fail('INVALID_PUBLICATION_RECEIPT', 'schemaVersion=2 and phase=publication are required'));
   if (publication?.sha !== sha || publication?.artifactSha256 !== digest) failures.push(fail('PUBLICATION_SEAL_MISMATCH', 'publication does not reference candidate seal'));
+  if (!cleanHex(publication?.payloadId, 64) || !cleanHex(publication?.bundleArtifactSha256, 64)) {
+    failures.push(fail('PUBLIC_PAYLOAD_BINDING_MISSING', 'signed payload and public bundle digests are required'));
+  }
   const version = versionField(candidate?.version);
   const tag = version ? `v${version}` : null;
   const identityMismatches = versionIdentityFailures(version, candidate?.tag, [
@@ -155,8 +158,9 @@ export function evaluatePublicationReceipt(candidate, publication) {
     ['GitHub release tag', publication?.githubRelease?.tag, tag],
     ['bundle brainVersion', publication?.bundle?.brainVersion],
     ['bundle releaseTag', publication?.bundle?.releaseTag, tag],
-    ['installed Claude host', publication?.installed?.claude?.version],
-    ['installed Codex host', publication?.installed?.codex?.version],
+    ['Claude-only host', publication?.installed?.claudeOnly?.version],
+    ['Codex-only host', publication?.installed?.codexOnly?.version],
+    ['dual host', publication?.installed?.dual?.version],
   ]);
   if (identityMismatches.length > 0) {
     failures.push(fail('PUBLIC_VERSION_IDENTITY_MISMATCH', `public surfaces must identify candidate ${version ?? 'UNKNOWN'}: ${identityMismatches.join(', ')}`));
@@ -165,9 +169,12 @@ export function evaluatePublicationReceipt(candidate, publication) {
     const item = publication?.[surface];
     if (item?.sha !== sha || item?.artifactSha256 !== digest) failures.push(fail('PUBLIC_ARTIFACT_MISMATCH', `${surface} differs from candidate seal`));
   }
-  for (const hostName of ['claude', 'codex']) {
+  for (const hostName of ['claudeOnly', 'codexOnly', 'dual']) {
     const host = publication?.installed?.[hostName];
-    if (host?.status !== 'PASS' || host?.artifactSha256 !== digest) failures.push(fail('PUBLIC_HOST_NOT_PASS', `${hostName} is not running sealed public artifact`));
+    if (host?.status !== 'PASS' || host?.doctorExit !== 0 || host?.artifactSha256 !== digest
+      || host?.functionalSearch !== true || !(host?.searchMs <= Number(publication?.brain?.deadlineMs) * 0.8)) {
+      failures.push(fail('PUBLIC_HOST_NOT_PASS', `${hostName} is not running a doctor-clean functional sealed public artifact`));
+    }
   }
   const brain = publication?.brain || {};
   if (brain.status !== 'PASS' || brain.selfStore !== true || !(brain.broadMs <= Number(brain.deadlineMs) * 0.8)) failures.push(fail('PUBLIC_BRAIN_NOT_PASS', 'public installed Brain acceptance failed'));

package/plugin/skills/ruvnet-brain/PLAYBOOK.md

@@ -1,6 +1,6 @@
 # THE PLAYBOOK — the standing build playbook, in full
 
-Updated: 2026-07-30 | Version 1.0.1
+Updated: 2026-08-02 | Version 1.1.0
 Created: 2026-07-27
 
 **Read this before your first build response in a session.** `plugin/scripts/session-start.sh`
@@ -87,10 +87,25 @@ rule-compliance, cite a source the tools didn't return, or claim a check that di
   Completion, with a QA gate between phases.
 - For a non-trivial domain, model it first (DDD: bounded contexts, aggregates, domain events) and
   capture key decisions as ADRs — design before code.
-- Spin up PARALLEL work where it helps (a Ruflo swarm / multiple agents) instead of serial drudgery.
+- **Parallel-by-default state machine for multi-part work.** Before the first spawn, decompose the
+  whole request, create the complete shared task list/ledger, record dependencies and give every
+  writing task its own worktree. Ruflo coordinates roles and state; the native host executes. Fill
+  available executor slots with independent ready work immediately, without asking, up to the
+  host's configured capacity; never oversubscribe and never put more than one writer in a worktree.
+  A completion moves that task to completed, unblocks its dependents, and the freed slot claims the
+  first unassigned, unblocked pending task immediately. Only allow a slot to idle when no such task
+  exists. Keep dependent integration with the designated integration owner.
+  - **Claude Code:** its shared task ledger and `TeammateIdle` hook make recycling enforceable: the
+    shipped recycler refuses idle while a ready unassigned task exists, then Claude's locked
+    `TaskUpdate` claim performs the transition.
+  - **Codex:** Codex 0.146.0 exposes no `TeammateIdle` or `TaskCompleted` hook and no equivalent
+    shared-task hook ledger. Initial fan-out and completion-notification recycling are guidance,
+    not hook enforcement: the lead must immediately dispatch the next ready ledger item when a
+    collaboration slot completes. State this degraded boundary if it affects the run; never call it
+    enforced.
   If Ruflo / RuVector MCP tools aren't available in this environment, DON'T block or stall — degrade
-  gracefully to Claude Code's native subagents (Task) and local .rvf, and briefly note the tool that
-  would make it better + how to add it. Never demand a tool the user doesn't have.
+  gracefully to the native host's agents and local .rvf, and briefly note the tool that would make
+  it better + how to add it. Never demand a tool the user doesn't have.
 - Persist decisions + state to AgentDB memory so nothing is lost across sessions or compaction.
 - If it has a UI, treat design as a BUILD STEP, not a coat of paint: apply the frontend-design
   discipline and GENERATE the visuals (AI image generation for UI mockups / diagrams / the explainer

package/scripts/candidate-host-evidence.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { stagedHostVerifier } from './staged-host-verifier.mjs';
+import { payloadIdFor } from './release-payload.mjs';
+
+const arg = (name) => {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+};
+const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+const manifestPath = path.resolve(arg('--manifest'));
+const packagePath = path.resolve(arg('--package'));
+const bundlePath = path.resolve(arg('--bundle'));
+const out = path.resolve(arg('--out'));
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const payloadId = payloadIdFor(manifest);
+const identity = { version: manifest.version, candidateSha: manifest.candidateSha, payloadId };
+const result = await stagedHostVerifier({ assets: { packagePath, bundlePath }, identity })
+  .verify({ source: 'candidate', assets: { packagePath, bundlePath } });
+if (result.verdict !== 'PASS') throw new Error(`candidate host matrix failed: ${result.error || 'unknown'}`);
+
+const modeNames = { claude: 'claude-only', codex: 'codex-only', dual: 'dual-host' };
+const leaves = Object.entries(modeNames).map(([mode, name]) => {
+  const fixture = result.fixtures?.[mode];
+  if (fixture?.status !== 'PASS' || fixture?.doctorExit !== 0) throw new Error(`${name} did not produce a clean doctor receipt`);
+  return {
+    name,
+    sha: manifest.candidateSha,
+    payloadId,
+    status: fixture.status === 'PASS' ? 'completed' : 'failed',
+    conclusion: 'success',
+    verdict: 'PASS',
+    source: 'candidate-host-evidence',
+    mode,
+    doctorExit: fixture.doctorExit,
+    artifactSha256: sha256(packagePath),
+  };
+});
+fs.writeFileSync(out, `${JSON.stringify({
+  schemaVersion: 1,
+  sha: manifest.candidateSha,
+  payloadId,
+  artifactSha256: sha256(packagePath),
+  leaves,
+}, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+console.log(JSON.stringify({ verdict: 'PASS', payloadId, leaves: leaves.map(({ name }) => name) }));

package/scripts/capability-registry.mjs

@@ -515,9 +515,9 @@ export const CAPABILITIES = [
       // router was in fact never being consulted at all. A quiet week and a severed wire look identical
       // from the receipt file, so read the wire directly.
       //
-      // Two things must both be true for anything to route: a PreToolUse gate on subagent dispatch
-      // (plugin/scripts/route-dispatch.sh, which is what turns "declare a model" from advice into a
-      // wall), and the opt-in profile it refuses to act without (route-dispatch.sh:46 exits 0 when
+      // Two things must both be true for the host-limited dispatch audit to record anything: a
+      // PreToolUse hook on subagent dispatch and the opt-in profile it refuses to act without
+      // (route-dispatch.sh exits 0 when
       // profile.json is absent). Either missing ⇒ the router cannot fire, regardless of how healthy
       // the receipt ledger looks.
       const profile = fs.existsSync(path.join(HOME, '.claude/model-router/profile.json'));

package/scripts/ci/learning-replay-codex-adapter.mjs

@@ -23,8 +23,20 @@ const probe = process.env.RUVNET_REPLAY_LESSON_PROBE || '';
 if (event === 'PreToolUse') {
   const recorder = process.env.RUVNET_REPLAY_RECORDER || '';
   if (!recorder) process.exit(2);
+  // Codex emits exec_command with tool_input.cmd; the shared Claude/Ruflo boundary consumes
+  // Bash with tool_input.command. Normalize the real host envelope before the recorder parses it.
+  const recorderInput = Buffer.from(JSON.stringify({
+    ...input,
+    tool_name: /^(?:functions[._]{1,2})?exec_command$/.test(String(input.tool_name || ''))
+      ? 'Bash'
+      : input.tool_name,
+    tool_input: {
+      ...(input.tool_input || {}),
+      command: input.tool_input?.command ?? input.tool_input?.cmd ?? input.command ?? '',
+    },
+  }));
   const result = spawnSync(process.execPath, [recorder, attemptsFile, sequenceFile], {
-    input: raw,
+    input: recorderInput,
     encoding: 'utf8',
     env: process.env,
   });

package/scripts/learning-replay-contract.mjs

@@ -59,6 +59,16 @@ export function trapSpec(id = TRAP.MEMORY_SEARCH) {
   };
 }
 
+// Codex commonly prints the global binary as $HOME/.npm-global/bin/ruflo. That is a real shell
+// executable path, not prose, but the shared command parser intentionally does not expand shell
+// variables. Canonicalize only an executable-position prefix; never rewrite quoted mentions.
+export function normalizeRufloExecutable(command) {
+  return String(command || '').replace(
+    /(^|(?:&&|\|\||[;|()\n])\s*)\$(?:HOME|\{HOME\})\/\.npm-global\/bin\/(ruflo|claude-flow)(?=\s|$)/g,
+    '$1$2',
+  );
+}
+
 export const LOAD_BEARING = Object.freeze([
   'scripts/learning-replay.mjs',
   'scripts/learning-replay-contract.mjs',
@@ -80,7 +90,7 @@ export const LOAD_BEARING = Object.freeze([
 ]);
 
 export function classifyCommand(cmd) {
-  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  const invocations = findInvocations(normalizeRufloExecutable(cmd), ['ruflo', 'claude-flow']);
   if (!invocations.length) return 'none';
   let sawPositional = false;
   for (const inv of invocations) {
@@ -102,7 +112,7 @@ export function classifyCommand(cmd) {
 }
 
 export function subcommandCorrect(cmd) {
-  for (const inv of findInvocations(String(cmd || ''), ['ruflo', 'claude-flow'])) {
+  for (const inv of findInvocations(normalizeRufloExecutable(cmd), ['ruflo', 'claude-flow'])) {
     const words = inv.args.filter((a) => a !== '' && !a.startsWith('-'));
     const memory = words.indexOf('memory');
     if (memory !== -1 && words[memory + 1] === 'search') return true;
@@ -124,7 +134,7 @@ export function optionValue(args, short, long) {
 }
 
 export function classifyPostTaskCommand(cmd) {
-  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  const invocations = findInvocations(normalizeRufloExecutable(cmd), ['ruflo', 'claude-flow']);
   if (!invocations.length) return 'none';
   let sawPostTask = false;
   for (const inv of invocations) {
@@ -142,7 +152,7 @@ export function classifyPostTaskCommand(cmd) {
 }
 
 export function postTaskSubcommandCorrect(cmd) {
-  return findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']).some((inv) => {
+  return findInvocations(normalizeRufloExecutable(cmd), ['ruflo', 'claude-flow']).some((inv) => {
     const words = inv.args.filter((a) => a !== '' && !a.startsWith('-'));
     const hooks = words.indexOf('hooks');
     return hooks !== -1 && words[hooks + 1] === 'post-task';

package/scripts/learning-replay-execution.mjs

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { commandNodes, findInvocations } from '../plugin/scripts/hook-input.mjs';
-import { optionValue, TRAP } from './learning-replay-contract.mjs';
+import { normalizeRufloExecutable, optionValue, TRAP } from './learning-replay-contract.mjs';
 
 export const PROJECT_B_MEMORY_KEY = 'note-caching-strategy';
 export const PROJECT_B_MEMORY_VALUE =
@@ -90,9 +90,10 @@ export function executeProducedCommand(cmd, {
     output: '',
     ...extra,
   });
-  const invocations = findInvocations(String(cmd || ''), ['ruflo', 'claude-flow']);
+  const normalized = normalizeRufloExecutable(cmd);
+  const invocations = findInvocations(normalized, ['ruflo', 'claude-flow']);
   if (!invocations.length) return reject('no Ruflo invocation to execute');
-  const firstExecutable = path.basename(commandNodes(String(cmd || ''))[0]?.exe || '').split('@')[0];
+  const firstExecutable = path.basename(commandNodes(normalized)[0]?.exe || '').split('@')[0];
   if (invocations.length !== 1 || firstExecutable !== 'ruflo') {
     return reject('corrective command was not the first and only Ruflo invocation');
   }

package/scripts/learning-replay-fixture.mjs

@@ -48,6 +48,16 @@ function initMemoryDb(ruflo, db, cwd) {
   return sh(ruflo, ['memory', 'init', '--path', db, '--backend', 'hybrid'], { cwd });
 }
 
+function retrieveExact(ruflo, db, cwd, key, expected) {
+  const result = sh(ruflo, [
+    'memory', 'retrieve', '-k', key, '-n', 'default', '--value-only', '--path', db,
+  ], { cwd });
+  return {
+    exit: result.status,
+    matched: result.status === 0 && String(result.stdout || '').includes(expected),
+  };
+}
+
 export function buildFixtures(baseDir) {
   fs.mkdirSync(baseDir, { recursive: true });
   const dirs = {
@@ -90,6 +100,7 @@ export function recordInProjectA(dirs, {
       'memory', 'search', '-q', spec.recordQuery,
       '-n', 'default', '--path', db, '-t', 'keyword',
     ], { cwd: project });
+    const exact = retrieveExact(ruflo, db, project, key, spec.lesson);
     return {
       project: path.basename(project),
       db,
@@ -97,7 +108,8 @@ export function recordInProjectA(dirs, {
       initExit: init.status,
       storeExit: store.status,
       readBackExit: readBack.status,
-      recorded: fs.existsSync(db),
+      exactReadExit: exact.exit,
+      recorded: exact.matched,
     };
   });
   const lesson = makeLesson({
@@ -138,12 +150,14 @@ export function seedProjectBMemory(dirs, { ruflo = RUFLO_BIN } = {}) {
     'memory', 'store', '-k', PROJECT_B_MEMORY_KEY,
     '--value', PROJECT_B_MEMORY_VALUE, '-n', 'default', '--path', db,
   ], { cwd: dirs.projectB });
+  const exact = retrieveExact(ruflo, db, dirs.projectB, PROJECT_B_MEMORY_KEY, PROJECT_B_MEMORY_VALUE);
   return {
     db,
     key: PROJECT_B_MEMORY_KEY,
     initExit: init.status,
     storeExit: store.status,
-    ok: init.status === 0 && store.status === 0 && fs.existsSync(db),
+    exactReadExit: exact.exit,
+    ok: init.status === 0 && store.status === 0 && exact.matched,
   };
 }
 
@@ -156,6 +170,13 @@ export function nightlyRefresh(dirs, { ruflo = RUFLO_BIN } = {}) {
     path.join(ROOT, 'scripts', 'ci', 'learning-replay-codex-adapter.mjs'),
     path.join(versionDir, 'scripts', 'codex-hook-adapter.mjs'),
   );
+  // Codex registrations call this stable, generation-independent wrapper. A fixture that only
+  // creates active.json silently falls back to the user's real Brain home and never records the
+  // trap's PreToolUse command, making an expensive replay unmeasurable.
+  fs.copyFileSync(
+    path.join(ROOT, 'plugin', 'scripts', 'codex-hook-wrapper.mjs'),
+    path.join(dirs.brainHome, 'codex-hook.mjs'),
+  );
   fs.writeFileSync(path.join(dirs.brainHome, 'active.json'), JSON.stringify({
     codeRoot: versionDir,
     generation,

package/scripts/lesson-lifecycle.mjs

@@ -43,7 +43,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { ORIGIN, STATUS, ENFORCEMENT, loadLessons } from './lesson-store.mjs';
+import { ORIGIN, SOURCE_CLASS, STATUS, ENFORCEMENT, loadLessons } from './lesson-store.mjs';
 
 // ── The bars, in one place, as numbers a human can argue with ────────────────────────────────────
 export const RETIREMENT = Object.freeze({
@@ -385,6 +385,7 @@ export function explainGeneralization(lesson, otherProjects = [], { minProjects
     // `{...lesson, ...proposal}`, so the result cannot block even if the source lesson was ratified
     // and blocking — the trust boundary is enforced by the data, not by the caller remembering.
     origin: ORIGIN.MODEL_INFERRED,
+    sourceClass: SOURCE_CLASS.MODEL_INFERRED,
     status: STATUS.CANDIDATE,
     enforcement: ENFORCEMENT.CHECKLIST,
     intendedEnforcement: null,

package/scripts/lesson-ratify.mjs

@@ -26,7 +26,7 @@
  * correctly, stops using it.
  */
 import os from 'node:os';
-import { loadLessons, saveLessons, ratify, demote, weightOf, pending, ENFORCEMENT, STATUS, ORIGIN, TRIGGERS } from './lesson-store.mjs';
+import { loadLessons, saveLessons, ratify, demote, weightOf, pending, ENFORCEMENT, STATUS, ORIGIN, SOURCE_CLASS, TRIGGERS } from './lesson-store.mjs';
 
 const argv = process.argv.slice(2);
 const arg = (f) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : null; };
@@ -34,7 +34,7 @@ const has = (f) => argv.includes(f);
 
 const lessons = loadLessons();
 if (!lessons.length) {
-  console.log('\n  No lessons stored yet. Seed them with:  node scripts/lesson-seed.mjs --apply\n');
+  console.log('\n  No personal lessons stored yet. They appear after an explicit user correction is captured.\n');
   process.exit(0);
 }
 
@@ -86,7 +86,10 @@ if (has('--ratify')) {
   // Bulk convenience, deliberately scoped: it can only touch lessons the USER stated. Model-inferred
   // lessons are never swept up by a bulk action — that would be exactly the hole the boundary closes.
   let next = lessons;
-  const targets = lessons.filter((l) => l.origin === ORIGIN.USER_STATED && l.status === STATUS.CANDIDATE && !l.demoted);
+  const targets = lessons.filter((l) => l.origin === ORIGIN.USER_STATED
+    && l.sourceClass === SOURCE_CLASS.CURRENT_USER
+    && l.status === STATUS.CANDIDATE
+    && !l.demoted);
   for (const l of targets) next = ratify(l.id, next);
   saveLessons(next);
   const nowBlocking = next.filter((l) => l.enforcement === ENFORCEMENT.BLOCK).length;