ruvnet-brain 4.0.6 → 4.0.7

package/plugin/scripts/hook-shim.mjs

@@ -13,8 +13,8 @@
 //     hook-shim-bash.mjs (bash-interpreter resolution, issue #38) — colocated in this same
 //     boot-frozen scripts/ dir, never resolved from the spine. No imports from the hook BODY.
 //   • Typed dispatch table (red-team findings 15/16/30): each hook declares its file, interpreter,
-//     and mode. `blocking` hooks propagate their exact exit code (route-dispatch's deliberate
-//     exit-2 wall survives by CONTRACT); `advisory` hooks can never block a turn — any failure,
+//     and mode. `blocking` hooks propagate their exact exit code; `advisory` hooks can never block
+//     a turn — any failure,
 //     including a missing file, exits 0.
 //   • Containment (finding 13): a codeRoot is honored ONLY if it resolves under
 //     ~/.cache/ruvnet-brain/versions/ — or is the explicit dev-mode checkout declared in
@@ -71,9 +71,9 @@ catch (e) { BRAIN_OFF = !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
 //
 //   'silence' — this hook exists to advertise, ground, or learn. Off means it does not run at all
 //               and writes ZERO bytes. Nothing downstream can tell it apart from not being installed.
-//   'run'     — this is a SAFETY WALL that guards money or honesty, not retrieval. route-dispatch
-//               stops a subagent fan-out inheriting an expensive model; design-wall stops an
-//               ungraded surface shipping; protect-state guards the user's own consent record.
+//   'run'     — this protection/audit remains relevant without retrieval. route-dispatch records
+//               inherited-model fan-out; design-wall stops an ungraded surface shipping;
+//               protect-state guards the user's own consent record.
 //               None becomes acceptable because retrieval is off.
 //   'partial' — the hook splits INTERNALLY. session-start-core still runs the auto-updater heartbeat, the
 //               GONG health alarm and the SLA banner (an off machine must still receive fixes,
@@ -84,7 +84,9 @@ const TABLE = {
   'session-start':    { file: 'session-start-core.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'partial' },
   'ground-ruvnet':    { file: 'ground-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence', stdinBytes: 32768 },
   'hijack-ruvnet':    { file: 'hijack-ruvnet.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
-  'route-dispatch':   { file: 'route-dispatch.sh',   interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
+  // Claude Code 2.1.220 consumes Agent/Task PreToolUse results after tool_dispatch_end (#84).
+  // A refusal here would be late and therefore false enforcement; retain only bounded audit.
+  'route-dispatch':   { file: 'route-dispatch.sh',   interpreter: 'bash', mode: 'advisory', offBehavior: 'run', stdinBytes: 65536 },
   'ground-before-write': { file: 'ground-before-write.sh', interpreter: 'bash', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   'grounding-stamp': { file: 'grounding-stamp.sh', interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'verify-interface': { file: 'verify-interface.sh', interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
@@ -94,6 +96,7 @@ const TABLE = {
   'protect-state':    { file: 'protect-brain-state.sh', interpreter: 'bash', 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 },
   'md-stamp':         { file: 'md-stamp.mjs',        interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   // THE EXTERNAL-SIGNAL WATCH PLANE, W1 OBSERVED (ADR-058 §D3; DDD-0013 Context 2). PostToolUse,
   // matcher ^Bash$ (anchored — an unanchored matcher is F3/F4). Classifies gh/vercel/netlify/npm
@@ -105,6 +108,10 @@ const TABLE = {
   // session-start-core.mjs, and that surfacing already lives under SessionStart's 'partial' contract.
   'signal-watch':     { file: 'signal-watch.mjs',    interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   'routing-outcome':  { file: 'routing-outcome-capture.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run' },
+  // Claude Code's synchronous TeammateIdle boundary can prevent a worker slot from going unused
+  // while its host-owned shared ledger has ready work. The body is read-only and fail-open; exit 2
+  // is reserved for one proved, unassigned, dependency-ready task. Codex has no equivalent event.
+  'swarm-slot-recycler': { file: 'swarm-slot-recycler.mjs', interpreter: 'node', mode: 'blocking', offBehavior: 'run', stdinBytes: 65536 },
   // The unprompted-speech chokepoint (ADR-040 / DDD-0004). ONE runtime is the sole writer of
   // user-facing bytes for every unprompted hook: it spawns the real producers (anticipate, lesson)
   // in candidate mode, applies the per-channel policy, and writes the final envelope itself. `channel`

package/plugin/scripts/lesson-provenance.mjs

@@ -0,0 +1,21 @@
+export const SOURCE_CLASS = Object.freeze({
+  CURRENT_USER: 'current-user',
+  IMPORTED_OWNER: 'imported-owner',
+  MODEL_INFERRED: 'model-inferred',
+  DEMONSTRATION: 'demonstration',
+});
+
+export const BUNDLED_OWNER_SEED_IDS = new Set([
+  'L01-verify-with-a-capable-channel',
+  'L02-check-before-you-assert',
+  'L03-research-before-recommending',
+  'L04-never-relay-a-number',
+  'L05-version-is-the-update-signal',
+  'L06-use-the-real-tool',
+  'L07-blast-radius-not-social-comfort',
+  'L08-status-is-a-table',
+  'L09-gradeable-is-not-valuable',
+  'L10-under-enumeration-is-a-tell',
+  'L11-retrieval-without-volition-is-broken',
+  'L12-efficiency-seeking-is-the-tell',
+]);

package/plugin/scripts/lesson-store.mjs

@@ -23,6 +23,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { BUNDLED_OWNER_SEED_IDS, SOURCE_CLASS } from './lesson-provenance.mjs';
+
+export { BUNDLED_OWNER_SEED_IDS, SOURCE_CLASS } from './lesson-provenance.mjs';
 
 /** Resolve fixture/plugin configuration without mutating the child process account HOME. */
 export function resolveConfigRoot(env = process.env, home = os.homedir()) {
@@ -99,6 +102,8 @@ export const ORIGIN = Object.freeze({
 });
 const ORIGIN_VALUES = new Set(Object.values(ORIGIN));
 
+const SOURCE_CLASS_VALUES = new Set(Object.values(SOURCE_CLASS));
+
 /**
  * STATUS — the ratification ladder. A lesson does not become policy by existing.
  * candidate → ratified (a human agreed) → active (in force at its trigger).
@@ -128,6 +133,11 @@ export function makeLesson(spec) {
     severity = 'normal',              // 'normal' | 'high' — see weightOf()
     intendedEnforcement = null,       // what it should become once a human ratifies it
     ratifiedBy = null,
+    sourceClass = origin === ORIGIN.USER_STATED
+      ? SOURCE_CLASS.CURRENT_USER
+      : origin === ORIGIN.MODEL_INFERRED
+        ? SOURCE_CLASS.MODEL_INFERRED
+        : SOURCE_CLASS.IMPORTED_OWNER,
   } = spec;
   const err = (m) => { throw new Error(`Lesson "${id ?? '?'}" invalid: ${m}`); };
 
@@ -151,6 +161,10 @@ export function makeLesson(spec) {
   }
 
   if (!ORIGIN_VALUES.has(origin)) err(`origin must be one of: ${[...ORIGIN_VALUES].join(', ')}`);
+  if (!SOURCE_CLASS_VALUES.has(sourceClass)) err(`sourceClass must be one of: ${[...SOURCE_CLASS_VALUES].join(', ')}`);
+  if (sourceClass === SOURCE_CLASS.CURRENT_USER && origin !== ORIGIN.USER_STATED) {
+    err('sourceClass:current-user requires origin:user-stated');
+  }
   if (!STATUS_VALUES.has(status)) err(`status must be one of: ${[...STATUS_VALUES].join(', ')}`);
 
   // THE TRUST BOUNDARY. A lesson the model wrote about itself, or one imported from a repo, cannot
@@ -166,7 +180,7 @@ export function makeLesson(spec) {
 
   return Object.freeze({
     id, statement, trigger, enforcement, evidence,
-    surface, origin, status, severity,
+    surface, origin, sourceClass, status, severity,
     intendedEnforcement: intendedEnforcement ?? null,
     ratifiedBy: ratifiedBy ?? null,
     projects: [...projects],
@@ -255,7 +269,12 @@ export function loadLessons(file = STORE_PATH) {
     // to edit and delete these); a malformed entry must be dropped loudly rather than acted upon.
     const out = [];
     const dropped = [];
-    for (const l of raw.lessons || []) {
+    const rows = Array.isArray(raw.lessons) ? raw.lessons : [];
+    const ids = new Set(rows.map((lesson) => lesson?.id));
+    const legacyOwnerSeed = rows.length === BUNDLED_OWNER_SEED_IDS.size
+      && ids.size === BUNDLED_OWNER_SEED_IDS.size
+      && [...BUNDLED_OWNER_SEED_IDS].every((id) => ids.has(id));
+    for (const stored of rows) {
       // SKIP THE BAD ROW, BUT NEVER SILENTLY. An adversarial review proved that a schema change
       // (ADR-035 proposes new enforcement values the current enum rejects) would take this store
       // from 16 lessons to 0 with NO error and exit 0 — output indistinguishable from "no lessons
@@ -264,6 +283,14 @@ export function loadLessons(file = STORE_PATH) {
       //
       // A store that empties itself quietly is the worst possible failure here, because the whole
       // product promise is "you should never have to tell me twice."
+      const l = legacyOwnerSeed ? {
+        ...stored,
+        origin: ORIGIN.IMPORTED,
+        sourceClass: SOURCE_CLASS.IMPORTED_OWNER,
+        status: STATUS.CANDIDATE,
+        demoted: true,
+        ratifiedBy: null,
+      } : stored;
       try { out.push(makeLesson(l)); } catch (e) {
         dropped.push({ id: l && l.id, why: String(e && e.message || e) });
       }
@@ -435,6 +462,7 @@ export function restore(id, lessons) {
 export function ratify(id, lessons, { by = 'user' } = {}) {
   return lessons.map((l) => {
     if (l.id !== id) return l;
+    if (l.sourceClass === SOURCE_CLASS.IMPORTED_OWNER || l.sourceClass === SOURCE_CLASS.DEMONSTRATION) return l;
     const target = l.intendedEnforcement || l.enforcement;
     const canBlock = l.origin === ORIGIN.USER_STATED;
     return makeLesson({
@@ -448,5 +476,7 @@ export function ratify(id, lessons, { by = 'user' } = {}) {
 
 /** Lessons awaiting a human decision — what the management surface must show first. */
 export function pending(lessons) {
-  return lessons.filter((l) => l.status === STATUS.CANDIDATE && !l.demoted);
+  return lessons.filter((l) => l.status === STATUS.CANDIDATE && !l.demoted
+    && l.sourceClass !== SOURCE_CLASS.IMPORTED_OWNER
+    && l.sourceClass !== SOURCE_CLASS.DEMONSTRATION);
 }

package/plugin/scripts/route-dispatch.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# route-dispatch.sh — PreToolUse gate on subagent dispatch. Ends model-inheritance-by-omission.
+# route-dispatch.sh — bounded PreToolUse audit of subagent model selection.
 #
 # ─────────────────────────────────────────────────────────────────────────────────────────────────
 # THE LEAK (2026-07-13). Stuart: "What happens when I'm right here in Opus 4.8 and it has 10 things
@@ -8,8 +8,12 @@
 #     A SUBAGENT INHERITS THE MAIN-LOOP MODEL UNLESS `model` IS EXPLICITLY PASSED.
 #
 # Ten agents on a Fable session = ten agents at $10/$50 per Mtok, ~10x Haiku for identical mechanical
-# work. The router existed; the rule to use it existed; the router's ENTIRE LIFETIME OUTPUT was 3 test
-# pings and $0.018 saved — because the rule was ADVISORY. So this is a wall, not advice.
+# work. This hook records declared and inherited dispatches so the leak remains measurable.
+#
+# HOST LIMITATION (#84): Claude Code 2.1.220 registers Agent/Task PreToolUse hooks asynchronously,
+# completes the subagent dispatch, and only then consumes the hook result. An exit-2 refusal is
+# therefore too late to block and must not be represented as enforcement. The hook is intentionally
+# silent and advisory until the host provides a synchronous pre-dispatch decision boundary.
 #
 # ─────────────────────────────────────────────────────────────────────────────────────────────────
 # THREE DEFECTS IN MY OWN FIRST VERSION, caught by asking the questions Stuart would have asked
@@ -21,14 +25,10 @@
 #      (a model-router profile.json exists = they answered the two subscription questions). Everyone
 #      else gets NOTHING — not even a warning. Consent is the default.
 #   2. IT REQUIRED python3. The other three plugin hooks are pure bash. A hard dependency inside a
-#      BLOCKING hook is how you brick someone's session. Now pure bash — no interpreters.
-#   3. IT COULD FAIL CLOSED. A blocking hook that errors must never take the session with it. Every
-#      unparseable/ambiguous case now FAILS OPEN (exit 0). A gate that breaks your tools is worse
-#      than the leak it prevents.
+#      hook is how you brick someone's session. Now pure bash — no interpreters.
+#   3. IT COULD FAIL CLOSED. Every unparseable/ambiguous case fails open (exit 0).
 #
-# CONTRACT (verified against this machine's live hook config):
-#   exit 0          → allow
-#   exit 2 + stderr → BLOCK, and stderr comes back to the model as the reason (so it retries correctly)
+# CONTRACT: always exit 0 and emit no user-facing bytes. Audit receipts are best-effort only.
 # ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 set -uo pipefail
@@ -93,9 +93,10 @@ TOOL_USE_ID=$(field tool_use_id)
 SESSION_ID=$(field session_id)
 DESC="${DESC// /_}"; DESC="${DESC:0:40}"   # builtin substitution — no `tr`, no `cut`
 
-if [ -n "$MODEL" ]; then
-  # Declared. Log it so routing is AUDITABLE, not merely claimed — a growing ledger is evidence;
-  # a promise is not. (This log is how the $0.018-lifetime failure became visible in the first place.)
+log_dispatch() {
+  local selected_model="$1"
+  local enforcement="$2"
+  # Log so routing is AUDITABLE, not merely claimed — a growing ledger is evidence; a promise is not.
   # `date` is the ONE external command left, and only on the ALLOW path — so its absence must be
   # silent, not a stderr spew from a hook that just said "yes". (bash's printf %()T would avoid it
   # entirely, but macOS still ships bash 3.2, which does not support it.)
@@ -105,44 +106,17 @@ if [ -n "$MODEL" ]; then
   {
     TS=$(date -u +%FT%TZ) || TS="unknown"   # the one external command, and only on the allow path
     mkdir -p "$HOME/.claude/metaharness"
-    printf '{"ts":"%s","event":"dispatch","model":"%s","agent":"%s","task":"%s","toolUseId":"%s","sessionId":"%s"}\n' \
-      "$TS" "$MODEL" "${SUBTYPE:-unknown}" "${DESC:-unlabeled}" "${TOOL_USE_ID:-}" "${SESSION_ID:-}" \
+    printf '{"ts":"%s","event":"dispatch","model":"%s","enforcement":"%s","agent":"%s","task":"%s","toolUseId":"%s","sessionId":"%s"}\n' \
+      "$TS" "$selected_model" "$enforcement" "${SUBTYPE:-unknown}" "${DESC:-unlabeled}" "${TOOL_USE_ID:-}" "${SESSION_ID:-}" \
       >> "$HOME/.claude/metaharness/dispatch-log.jsonl"
   } 2>/dev/null || true
+}
+
+if [ -n "$MODEL" ]; then
+  log_dispatch "$MODEL" "declared"
   exit 0
 fi
 
-# ── BLOCKED: no model declared → it would silently inherit the session model. ──
-# `read` + `printf` are BUILTINS. The original used `cat >&2 <<EOF`, which made the BLOCK path itself
-# depend on an external binary — the third dependency hole found in my own hook in ten minutes.
-read -r -d '' BLOCK_MSG <<'EOF' || true
-⛔ SUBAGENT DISPATCH BLOCKED — you did not declare a `model`.
-
-An agent with no `model` INHERITS this session's model. On an Opus session that is an Opus agent;
-on a Fable session it is $10/$50 per Mtok — up to 10x what the same work costs on Haiku.
-Inheritance-by-omission is the biggest cost leak in this harness, and an advisory rule did not fix
-it (the router's entire first life saved $0.018). Hence a wall.
-
-Re-issue the SAME Agent call with an explicit `model`, chosen by what the task actually IS:
-
-  model: "haiku"   mechanical — greps, file sweeps, log triage, mechanical edits, fixture rewrites
-  model: "sonnet"  analytical — trace a bug across files, summarize a subsystem, draft tests
-  model: "opus"    judgment   — architecture, root cause, security, anything user-facing
-                   (if it truly needs the main model's judgment, ask whether it should be a
-                    subagent at all, or work you should do inline)
-
-Not sure? Ask rUv's real router — it predicts each model's quality on THIS task and returns the
-cheapest one that clears the bar, with your subscriptions priced at $0:
-
-  node ~/.claude/model-router/bin/model-router-engine.mjs --harness claude-code --prompt "<task>" --json
-
-Then log the receipt when it returns, so the saving is visible instead of asserted:
-
-  node scripts/dispatch-receipt.mjs --model <m> --inherited <this session's model> \
-       --task "<what it did>" --total-tokens <the agent's reported total>
-
-Deliberate exception (rare — and say WHY out loud): RUVNET_ALLOW_INHERITED_MODEL=1
-EOF
-bash "$(dirname "${BASH_SOURCE[0]}")/gate-receipt.sh" route-dispatch "subagent" "would inherit the session model instead of routing to a cheaper one" 2>/dev/null || true
-printf '%s\n' "$BLOCK_MSG" >&2
-exit 2
+# Missing model: record the inheritance leak, but do not emit a late refusal the host cannot enforce.
+log_dispatch "inherited" "advisory-host-timing"
+exit 0

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/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/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'));