ruvnet-brain 3.9.133-dev → 4.0.1

package/plugin/scripts/session-start.sh

@@ -0,0 +1,868 @@
+#!/bin/sh
+# RuvNet Brain — SessionStart hook. THE CONFIDENCE SIGNAL.
+# The #1 UX failure of a background plugin is the user not knowing it's even on. This fires once when
+# a Claude Code session starts (in ANY project / VS Code window) and instructs the model to surface a
+# brief, friendly confirmation so the user KNOWS the brain is active and how to use it — answering the
+# exact questions a newcomer has ("is it on? do I reinstall per project? how do I use it?").
+# stdout is injected into the session context at startup; ALWAYS exit 0 so it can never block a session.
+set +e
+
+# Claude Code supports plugin slash commands. Codex exposes plugin workflows as skills instead, so
+# every instruction emitted by this shared body must name the host's real invocation surface.
+if [ "${RUVNET_HOOK_HOST:-claude}" = "codex" ]; then
+  CONSOLE_INVOKE='$ruvnet-brain:rvbc'
+else
+  CONSOLE_INVOKE='/rvbc'
+fi
+
+# Opt-in stage trace for the release gate. EPOCHREALTIME and printf are Bash builtins, so this adds
+# no subprocess and stays completely silent in real sessions unless the isolated QE harness enables it.
+trace_stage() {
+  [ "${RUVNET_SESSION_TRACE:-0}" = "1" ] && printf 'SESSION_TRACE %s %s\n' "${EPOCHREALTIME:-unknown}" "$1" >&2
+}
+trace_stage "body-start"
+
+# ── WHERE THIS HOOK'S OWN FILES LIVE. Resolved once: every background job below launches through
+# scripts/detach.mjs, a sibling in whichever payload root is executing this body (the spine version
+# dir or the frozen plugin — both mirror plugin/, see update-apply.mjs's stagePayload).
+HOOK_DIR="${0%/*}"
+if [ "$HOOK_DIR" = "$0" ]; then
+  # A native Node process passes this script to Git Bash as C:\...\session-start.sh. In that
+  # invocation $0 has backslashes, so the slash-only expansion above leaves the whole filename
+  # unchanged and every sibling helper silently disappears. Strip the final Windows component
+  # without spawning dirname/cygpath on the latency-critical startup path.
+  case "$0" in
+    *\\*) HOOK_DIR="${0%\\*}" ;;
+    *) HOOK_DIR="." ;;
+  esac
+fi
+DETACH="$HOOK_DIR/detach.mjs"
+
+# ── TOKEN METER (ADR-0011 token_cost_efficiency) — same meter as ground-ruvnet.sh. Everything this
+# hook prints synchronously is captured, replayed verbatim at the end, and its REAL byte count is
+# appended as {source:"hook", class:"session-start"} to .ruvnet-brain/token-ledger.jsonl in the
+# project cwd. RUVNET_BRAIN_METER=0 disables. fd 3 = the real stdout, kept for the finalize below.
+#
+# NOTHING BACKGROUNDED WRITES TO fd 3 ANY MORE (2026-07-27). The KB-freshness notice used to, on the
+# reasoning that an async writer would otherwise land in the meter's tmpfile after the replay and be
+# lost. That was true, and the cure was worse: a detached job writing into the hook's stdout pipe
+# AFTER the hook has exited is writing to a pipe Claude Code has already consumed — the bytes were
+# either dropped or arrived attributed to nothing, and they were never counted by the meter either.
+# The notice is now printed synchronously from the check's own log file (see the KB block below), so
+# it is deterministic, metered, and can no longer race the process that emits it.
+exec 3>&1
+METER_TMP=""
+if [ "${RUVNET_BRAIN_METER:-1}" != "0" ]; then
+  METER_TMP=$(mktemp 2>/dev/null) || METER_TMP=""
+  [ -n "$METER_TMP" ] && exec 1>"$METER_TMP"
+fi
+
+# ── BRAIN OFF — THE INTERNAL SPLIT (ADR-054 §3). ────────────────────────────────────────────────
+#
+# The two duel reviewers disagreed here in a way that turned out to be the design. Fable: OFF must
+# NOT suppress the updater or the alarms — an off machine still has to be able to receive the fix
+# for an off-state bug, or the bug is permanent. GPT-5.6: background work while the product claims
+# to be "off" is undisclosed background work, which is its own lie. Both halves are right, so this
+# hook does not have ONE answer; it splits down the middle:
+#
+#   KEEPS RUNNING while off — the auto-update heartbeat, the nightly-failure escalation, the GONG
+#     health alarm, the open-issue SLA banner, the token meter, the .running-version bookkeeping.
+#     None of those are the brain speaking about itself; they are the machine staying maintainable.
+#     (The console DISCLOSES this in the off state and offers to pause updates too — GPT's half.)
+#
+#   GOES SILENT while off — every byte of advertising: the confidence banner, THE PLAYBOOK, the
+#     console first-load offer, the router nudge, the what's-new line, the major-line welcome, the
+#     token-intelligence line, the star ask.
+#
+#   EXACTLY ONE LINE REMAINS — "brain OFF by your setting (since <date>)". That single line resolves
+#     the silence-vs-legibility contradiction both reviewers flagged from opposite directions: total
+#     silence makes an off brain indistinguishable from a broken one, and this repo has already had
+#     a dark brain nobody noticed for days.
+#
+# THE ONCE-EVER OFFERS ARE NOT CONSUMED while suppressed. Their stamps (.console-offered,
+# .router-profile-nudged, .star-ask-shown, .last-announced-version, .last-major-milestone) are
+# written at the moment they PRINT. Suppressing the print while still writing the stamp would burn
+# a once-per-machine offer into a session that never showed it — the user turns the brain back on
+# and has silently, permanently lost the first-load console offer. So each suppressed block is
+# skipped whole, stamp included.
+#
+# The sentinel is read directly, not only from the shim's forwarded snapshot, because this hook is
+# also invoked outside the shim (by a bare install and by the test suite). RUVNET_BRAIN_OFF, when
+# present, is the shim's ONE resolved answer for this invocation (ADR-054 §4) and wins ties.
+#
+# The `! -r` clause mirrors the node readers: `[ -f ]`, like fs.existsSync, answers "no sentinel" on
+# an unreadable directory, which would report ON for a user who switched OFF. Only genuine absence
+# counts as on — see the same note in ground-before-write.sh and scripts/brain-state.mjs.
+BRAIN_STATE_DIR="${RUVNET_BRAIN_STATE_DIR:-$HOME/.config/ruvnet-brain}"
+OFF_FILE="$BRAIN_STATE_DIR/brain-off"
+BRAIN_OFF=0
+if [ "${RUVNET_BRAIN_OFF:-0}" = "1" ] || [ -f "$OFF_FILE" ] \
+   || { [ -d "$BRAIN_STATE_DIR" ] && [ ! -r "$BRAIN_STATE_DIR" ]; }; then
+  BRAIN_OFF=1
+fi
+OFF_SINCE=""
+if [ "$BRAIN_OFF" = "1" ]; then
+  # The date, from the file's own JSON when it has one, else its mtime. Never invented: if neither
+  # is readable the line simply omits the date rather than printing a plausible-looking one.
+  OFF_SINCE=$(sed -n 's/.*"since"[[:space:]]*:[[:space:]]*"\([0-9-]\{10\}\).*/\1/p' "$OFF_FILE" 2>/dev/null | head -1)
+  [ -n "$OFF_SINCE" ] || OFF_SINCE=$(date -r "$OFF_FILE" +%Y-%m-%d 2>/dev/null)
+fi
+
+# ── nightly failure escalation (Stuart, 2026-07-12): "you need to jump in and fix it" — checked in
+# EVERY session, any project, via an absolute path (this hook fires everywhere, the marker lives in
+# one place). scripts/nightly-wrapper.sh writes this ONLY after a real failure survives its own
+# self-heal retry; a clean run or legitimate no-op removes it. Presence here = unprompted, first
+# thing surfaced, no waiting for the phone alert to be seen.
+# Resolved against the CURRENT project, not a hardcoded absolute path. This was the maintainer's own
+# machine path (/Users/<maintainer>/Code/ruvnet-brain/...) shipped verbatim to every user: inert
+# elsewhere, but it disclosed the maintainer's directory layout in a hook everyone runs, and it only
+# ever worked on one machine. Relative resolution does the same job for whoever is running it.
+NIGHTLY_MARKER="${CLAUDE_PROJECT_DIR:-$PWD}/.ruvnet-brain/nightly-failure.json"
+# canonical project-state-current auto-recall moved to the GLOBAL hook
+# (~/.claude/hooks/agentdb-ensure.sh, 2026-07-12) so every project with AgentDB gets it, not just
+# this one — kept here it would double-print in this repo since both hooks fire in the same session.
+
+if [ -f "$NIGHTLY_MARKER" ]; then
+  cat <<EOF
+[RuvNet Brain — NIGHTLY FAILED, self-heal retry also failed, this is now yours to fix]
+Before anything else this session: the ruvnet-brain nightly publish failed twice last run (immediate
+attempt + a 3-minute retry) and could not self-heal. Read $NIGHTLY_MARKER for the exact tag/error,
+then logs/nightly.log in that repo for full context. Diagnose and fix it now — do not wait to be
+asked, this is a standing directive. Once genuinely fixed and verified (a real release tag advances),
+delete the marker file.
+EOF
+fi
+
+# ── GONG LAYER 2: brain-health alarm, checked EVERY session (Stuart, 2026-07-12: "big gonging
+# things flashing all over the place — that can NEVER happen silently"). On 2026-07-12 the brain's
+# node_modules vanished and every search failed for days, invisibly. These are pure-filesystem
+# checks (<5ms, no node, no network) so they run unconditionally — no rate limiting on an alarm.
+# health.json is written by kb/brain-alarm.mjs the moment a real search fails; the structural
+# checks below catch the broken state even before any search has run.
+GONG_KB="$HOME/.cache/ruvnet-brain/kb"
+GONG_HEALTH="$HOME/.cache/ruvnet-brain/health.json"
+BRAIN_PROBLEM=""
+GONG_HAS_RVF=0
+for GONG_RVF in "$GONG_KB"/*.rvf; do
+  if [ -f "$GONG_RVF" ]; then GONG_HAS_RVF=1; break; fi
+done
+# ADR-054 §3 (Health): an ABSENT knowledge bundle on a machine where the user switched the brain OFF
+# is "disabled by choice", never "THE BRAIN IS DOWN". Screaming a red alarm at someone for the exact
+# state they asked for is the product lying about its own condition — and it would train them to
+# ignore the alarm that matters. Note the narrowness: ONLY the absent-bundle class is reframed. A
+# bundle that IS present but broken (missing reader deps, a failed real search) still rings, because
+# that is a genuine breakage waiting for them the moment they switch back on.
+GONG_ABSENT_BY_CHOICE=0
+if [ "$BRAIN_OFF" = "1" ] && { [ ! -d "$GONG_KB" ] || [ "$GONG_HAS_RVF" != "1" ]; }; then
+  GONG_ABSENT_BY_CHOICE=1
+fi
+if [ "$GONG_ABSENT_BY_CHOICE" = "1" ]; then
+  BRAIN_PROBLEM=""
+elif [ ! -d "$GONG_KB" ]; then
+  BRAIN_PROBLEM="the brain cache directory is MISSING ($GONG_KB) — reinstall: npx github:stuinfla/ruvnet-brain"
+elif [ "$GONG_HAS_RVF" != "1" ]; then
+  BRAIN_PROBLEM="NO vector stores (.rvf) found in $GONG_KB — the brain is empty; reinstall: npx github:stuinfla/ruvnet-brain --force"
+elif [ ! -f "$GONG_KB/node_modules/@xenova/transformers/package.json" ]; then
+  BRAIN_PROBLEM="reader dependencies are MISSING (node_modules gone) — every search WILL fail. Fix: cd $GONG_KB && npm i"
+elif grep -q '"status": *"down"' "$GONG_HEALTH" 2>/dev/null; then
+  BRAIN_PROBLEM="the last real search FAILED across all repos ($(grep -o '"error": *"[^"]*"' "$GONG_HEALTH" 2>/dev/null | head -1 | cut -c1-180)). Fix: cd $GONG_KB && npm i, then run one search to clear the alarm"
+fi
+if [ -n "$BRAIN_PROBLEM" ]; then
+  cat <<EOF
+🚨 [RuvNet Brain — HEALTH ALARM: THE BRAIN IS DOWN — SURFACE THIS FIRST] 🚨
+Health check failed: $BRAIN_PROBLEM
+Open your VERY FIRST line with a loud plain alert naming that reason and that fix, and offer to run
+it. Never answer rUv-stack questions from memory while it is down. Verify after: npx ruvnet-brain --doctor
+EOF
+fi
+
+# ── The Console: FIRST-LOAD OFFER (Stuart's exact UX, 2026-07-16): the console is the marquee —
+# make sure people see it the first time they load the solution. One yes/no, once ever per machine;
+# on yes the model launches it FOR them (/rvbc). Offered before the router nudge — seeing your whole
+# stack comes before tuning one part of it.
+# OFF: skipped WHOLE — print and stamp together (see the split note at the top). A once-ever offer
+# consumed by a session that never showed it is an offer the user can never receive.
+CONSOLE_OFFERED="$HOME/.cache/ruvnet-brain/.console-offered"
+if [ "$BRAIN_OFF" != "1" ] && [ ! -f "$CONSOLE_OFFERED" ]; then
+  mkdir -p "$HOME/.cache/ruvnet-brain" 2>/dev/null
+  touch "$CONSOLE_OFFERED" 2>/dev/null
+  echo "[RuvNet Brain — FIRST LOAD: offer the Console once]"
+  echo "Offer ONCE in one line, then respect it: \"Want to see your whole RuvNet stack on one page?\" — what's installed, what your AI has learned, one-click fixes, read-only until they click; later it's $CONSOLE_INVOKE. On yes invoke $CONSOLE_INVOKE; on no, one gracious line and never again."
+fi
+
+# ── Open-issue surfacer (2026-07-17): issues stacked to 29h unseen because the only alert channel
+# was ntfy (a phone push, easy to miss). The session banner is the one channel the maintainer cannot
+# miss. issue-watch.mjs writes ~/.cache/ruvnet-brain/open-issues.json each hourly run; this reads it
+# and surfaces breaching issues at session start. Best-effort and fail-silent — a jq/read failure
+# emits nothing. Only lights up for whoever RUNS the watcher (the maintainer); downloaders have no
+# such job, so the file never exists for them and this stays quiet.
+ISSUE_STATUS="$HOME/.cache/ruvnet-brain/open-issues.json"
+if [ -f "$ISSUE_STATUS" ] && command -v node >/dev/null 2>&1; then
+  # 2026-07-24: this used to surface ONLY breaching issues — and "breach" is computed from the same
+  # owner-comment predicate the auto-fixer's bot comments satisfy, so on the night four real issues
+  # were open the banner stayed silent. The banner now ALWAYS shows the open count; breaches keep
+  # the urgent wording. Every channel judging by one predicate is how all of them fail together.
+  ISSUE_LINE=$(node -e '
+    try {
+      const fs=require("fs");
+      const s=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+      // stale guard: ignore a snapshot older than 6h (the watcher runs hourly; 6h means it stopped)
+      if (!s.at || (Date.now()-new Date(s.at).getTime()) > 6*3600*1000) process.exit(0);
+      const open=(s.issues||[]);
+      if (!open.length) process.exit(0);
+      const breaches=open.filter(i=>i.breach);
+      if (breaches.length) {
+        breaches.sort((a,b)=>b.ageHours-a.ageHours);
+        const top=breaches.slice(0,4).map(i=>`#${i.number} (${i.ageHours}h) ${String(i.title).slice(0,64)}`).join(" · ");
+        console.log(`BREACH\t${breaches.length} open issue(s) past SLA on ${s.repo}: ${top}${breaches.length>4?" · +"+(breaches.length-4)+" more":""}`);
+      } else {
+        open.sort((a,b)=>b.ageHours-a.ageHours);
+        const top=open.slice(0,4).map(i=>`#${i.number} (${i.ageHours}h)`).join(" · ");
+        console.log(`OPEN\t${open.length} open issue(s) on ${s.repo}, none past SLA: ${top}${open.length>4?" · +"+(open.length-4)+" more":""}`);
+      }
+    } catch { /* fail-silent */ }
+  ' "$ISSUE_STATUS" 2>/dev/null)
+  case "$ISSUE_LINE" in
+    BREACH*)
+      echo "[RuvNet Brain — OPEN ISSUES need attention (surface this to the maintainer, once, near the top)]"
+      echo "${ISSUE_LINE#BREACH	}"
+      echo "These are real user-filed bugs sitting past the response SLA. Mention them plainly so they do not stack unseen; offer to fix them (gh issue list --state open for detail)."
+      ;;
+    OPEN*)
+      echo "[RuvNet Brain — open issues on the maintainer's repo (mention once, calmly, near the top)]"
+      echo "${ISSUE_LINE#OPEN	}"
+      echo "Within SLA, but the maintainer should know they exist. One line is enough; offer to look."
+      ;;
+  esac
+fi
+
+# ── External-signal watch plane, W1+W2 surfacing (ADR-058 §D3; DDD-0013 Context 2) ────────────────
+#
+# THE FAILURE THIS CLOSES: on 2026-07-27 GitHub CI was failing and the OWNER had to tell the model.
+# A product that pitches "proactive" and must be told about a red pipeline by its user has failed.
+# plugin/scripts/signal-watch.mjs (PostToolUse, matcher ^Bash$) opens a pending debt the moment a
+# `git push` succeeds, appended to pending.jsonl (that file's SINGLE writer). This block is the other
+# half: it polls the debt (scripts/signal-watch.mjs — this repo's own maintainer-only dev tool, same
+# class as issue-watch.mjs, so it simply does not exist on a downloader's machine and this whole
+# block stays silent there, matching the open-issue surfacer's own gating just above) when the cache
+# is stale, then surfaces a TRANSITION with zero user input — the 2026-07-27 incident replayed with
+# the human removed.
+#
+# THE ANTI-NAG LAW (ADR-058 §D3, its own hard rule with its own red mutant test): speak on
+# TRANSITIONS ONLY. Green emits ZERO bytes unless it closes a PREVIOUSLY-SURFACED red, which earns
+# exactly one closing line. surfaced.json is this session-start block's own small ledger of what has
+# already been told to the user, so a still-red debt is never re-nagged every session and a debt that
+# was never red never speaks at all on going green.
+#
+# NOT BRAIN_OFF-gated, matching the open-issue SLA banner immediately above (both are named in the
+# top-of-file split note as "KEEPS RUNNING while off" — an off machine must still be able to learn its
+# own CI just broke; this is not the brain advertising itself).
+SIGNAL_DIR="${RUVNET_SIGNAL_DIR:-$HOME/.cache/ruvnet-brain/external-signals}"
+SIGNAL_PENDING="$SIGNAL_DIR/pending.jsonl"
+SIGNAL_STATUS="$SIGNAL_DIR/ci-status.json"
+SIGNAL_SURFACED="$SIGNAL_DIR/surfaced.json"
+if [ -f "$SIGNAL_PENDING" ] && command -v node >/dev/null 2>&1; then
+  SIGNAL_POLLER="${CLAUDE_PROJECT_DIR:-$PWD}/scripts/signal-watch.mjs"
+  if [ -f "$SIGNAL_POLLER" ]; then
+    NOW_SIG=$(date +%s 2>/dev/null || echo 0)
+    LAST_POLL_SIG=0
+    [ -f "$SIGNAL_STATUS" ] && LAST_POLL_SIG=$(date -r "$SIGNAL_STATUS" +%s 2>/dev/null || echo 0)
+    # >10 min stale (or never polled) — bounded by the poller's own 3s gh timeout, so this can never
+    # meaningfully eat the hook's 5s budget even on a cold cache.
+    if [ $((NOW_SIG - LAST_POLL_SIG)) -gt 600 ]; then
+      node "$SIGNAL_POLLER" >/dev/null 2>/dev/null || true
+    fi
+  fi
+
+  if [ -f "$SIGNAL_STATUS" ]; then
+    # surfaced.json shape: { debts: { [debtKey]: "red"|"green"|"unverifiable" }, redRepo: { [repo]: debtKey } }.
+    # `debts` dedupes a re-surfaced alert for the SAME (repo,sha) debt; `redRepo` is what lets a LATER
+    # debt (a different, newer sha — CandidateVerdict is append-only per repo: a verdict for SHA X is
+    # never edited, only superseded by SHA Y, DDD-0013 Context 1 inv. 3) close out an EARLIER one's red.
+    node -e '
+      try {
+        const fs = require("fs");
+        const path = require("path");
+        const [statusPath, surfacedPath] = [process.argv[1], process.argv[2]];
+        const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        let surfaced = { debts: {}, redRepo: {} };
+        try {
+          const onDisk = JSON.parse(fs.readFileSync(surfacedPath, "utf8"));
+          surfaced.debts = onDisk.debts || {};
+          surfaced.redRepo = onDisk.redRepo || {};
+        } catch { /* first run */ }
+        let changed = false;
+        const out = [];
+        // Chronological order — a repo can carry more than one debt, and a CLOSE must reference the
+        // outstanding red it is actually closing, not an arbitrary object-key iteration order.
+        const entries = Object.entries(status).sort((a, b) => new Date(a[1].checkedAt || 0) - new Date(b[1].checkedAt || 0));
+        for (const [key, debt] of entries) {
+          const shortSha = String(debt.ref || "").slice(0, 7);
+          if (debt.state === "resolved" && debt.conclusion !== "success") {
+            if (surfaced.debts[key] !== "red") {
+              out.push(`[RuvNet Brain — EXTERNAL SIGNAL: CI is RED for ${debt.repo}@${shortSha} — surface this to the user now, near the top, with ZERO prompting]`);
+              out.push(`Workflow ${debt.workflowName || "ci"} concluded ${debt.conclusion} on ${debt.repo}@${shortSha}. Say it plainly and offer to look (gh run list --repo ${debt.repo} --commit ${debt.ref}).`);
+              surfaced.debts[key] = "red";
+              surfaced.redRepo[debt.repo] = key;
+              changed = true;
+            }
+          } else if (debt.state === "resolved" && debt.conclusion === "success") {
+            if (surfaced.redRepo[debt.repo]) {
+              out.push(`[RuvNet Brain — external signal: CI is GREEN again for ${debt.repo}@${shortSha} — one line, then move on]`);
+              delete surfaced.redRepo[debt.repo];
+              changed = true;
+            }
+            if (surfaced.debts[key] !== "green") { surfaced.debts[key] = "green"; changed = true; }
+          } else if (debt.state === "unverifiable") {
+            if (surfaced.debts[key] !== "unverifiable") {
+              out.push(`[RuvNet Brain — external signal: CI status could not be checked for ${debt.repo}@${shortSha}: ${debt.reason || "unknown reason"}]`);
+              surfaced.debts[key] = "unverifiable";
+              changed = true;
+            }
+          }
+          // state "pending" (no run yet / transient API hiccup): stays silent — never a decision,
+          // never invented as green (DDD-0013 §Context 2 invariant 1, "UNKNOWN STAYS OPEN").
+        }
+        if (out.length) console.log(out.join("\n"));
+        if (changed) { fs.mkdirSync(path.dirname(surfacedPath), { recursive: true }); fs.writeFileSync(surfacedPath, JSON.stringify(surfaced, null, 2)); }
+      } catch { /* fail-silent — surfacing must never block session start */ }
+    ' "$SIGNAL_STATUS" "$SIGNAL_SURFACED" 2>/dev/null
+  fi
+fi
+
+# ── MetaHarness router: the ONE-LINER OFFER (Stuart's exact UX, 2026-07-12): offer yes/no → on
+# yes, ask two questions → then SHOW the user their recommended path (zero-cost options + what the
+# router uses when work must go out to a paid API). Offered at most once ever per machine; without
+# a profile the engine takes the catalog as-is, which may assume subscriptions this user lacks.
+ROUTER_DIR="$HOME/.claude/model-router"
+ROUTER_NUDGE="$HOME/.cache/ruvnet-brain/.router-profile-nudged"
+if [ "$BRAIN_OFF" != "1" ] && [ ! -f "$ROUTER_DIR/profile.json" ] && [ ! -f "$ROUTER_NUDGE" ]; then
+  touch "$ROUTER_NUDGE" 2>/dev/null
+  echo "[RuvNet Brain — MetaHarness routing is available but not set up for THIS user yet]"
+  echo "Offer ONCE in one line, then respect it: cost-optimal routing sends each task to the cheapest model that can do it, THEIR subscriptions first (\$0) before anything billed. Set it up?"
+  echo "On yes ask only (1) Claude sub, Pro or Max? (2) Codex CLI on a ChatGPT plan? then:"
+  if [ -f "$ROUTER_DIR/bin/model-router-setup.mjs" ]; then
+    echo "  in $ROUTER_DIR/bin: node model-router-setup.mjs --detect-only; set profile.json's subscription fields from their answers (basis 'user-attested <date>'); node model-router-status.mjs and RELAY its 'Recommended path' block — SEEING their zero-cost options IS the deliverable of yes."
+  else
+    echo "  the router isn't installed here — run: npx github:stuinfla/ruvnet-brain (it sets it up, asks these questions and shows the path)"
+  fi
+  echo "On no or silence: drop it, never re-offer."
+fi
+
+# ── heartbeat: rate-limited (~once/20h) check against the live GitHub plugin.json ──
+# Detects a version gap, then APPLIES it automatically in the background — no manual command for the
+# user to remember. `claude plugin marketplace update` + `claude plugin update` only refresh an
+# on-disk cache; they don't touch this session's already-loaded state, so running them from a
+# background subprocess here is safe (proven empirically: this exact pair ran cleanly from inside a
+# live session earlier the same day, no disruption). A restart is still required to LOAD the new
+# version — that's a hard Claude Code platform constraint, not something a plugin can bypass — but
+# restarts happen naturally and often, so once this runs there is nothing left to remember. Never
+# blocks: the update itself is backgrounded (&), and this whole block is best-effort — any failure is
+# silently ignored, curl is capped at 3s, so session start is never meaningfully delayed.
+STATE_DIR="$HOME/.cache/ruvnet-brain"
+STAMP="$STATE_DIR/.last-update-check"
+PREF_FILE="$STATE_DIR/.auto-update-pref"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+# Parse the tiny plugin manifest once with shell builtins. The former grep|sed pipelines read the
+# same file three times per session; on Git-for-Windows each pipeline launches two processes.
+PLUGIN_VERSION=""
+PLUGIN_UPDATED=""
+PLUGIN_JSON="${CLAUDE_PLUGIN_ROOT:-}/.claude-plugin/plugin.json"
+if [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "$PLUGIN_JSON" ]; then
+  PLUGIN_TEXT=$(<"$PLUGIN_JSON")
+  case "$PLUGIN_TEXT" in
+    *'"version"'*)
+      PLUGIN_VALUE="${PLUGIN_TEXT#*\"version\"}"; PLUGIN_VALUE="${PLUGIN_VALUE#*:}"
+      PLUGIN_VALUE="${PLUGIN_VALUE#*\"}"; PLUGIN_VERSION="${PLUGIN_VALUE%%\"*}" ;;
+  esac
+  case "$PLUGIN_TEXT" in
+    *'"updated"'*)
+      PLUGIN_VALUE="${PLUGIN_TEXT#*\"updated\"}"; PLUGIN_VALUE="${PLUGIN_VALUE#*:}"
+      PLUGIN_VALUE="${PLUGIN_VALUE#*\"}"; PLUGIN_UPDATED="${PLUGIN_VALUE%%\"*}" ;;
+  esac
+fi
+
+# ── what's-new: the FIRST session after a version change surfaces ONE positive line about what the
+# new version ADDS — users should learn what improved, not just that something updated. Fires once per
+# new version (tracked in .last-announced-version), EVERY session (not rate-limited like the heartbeat
+# below, so it lands the moment a user restarts onto a new version), non-blocking. To announce a
+# release, add a line to the case. Keep it upbeat and benefit-first — this is the good-news channel.
+RUNNING_V="$PLUGIN_VERSION"
+ANNOUNCED_FILE="$STATE_DIR/.last-announced-version"
+LAST_ANNOUNCED=""
+[ -f "$ANNOUNCED_FILE" ] && IFS= read -r LAST_ANNOUNCED < "$ANNOUNCED_FILE"
+# ── MAJOR-LINE milestone: the "what's new in the big release" first-run experience (owner, 2026-07-25:
+# "people will wake up and it's 4.0 — they won't see the web explainer; the brain has to introduce
+# itself and bring up the console"). This fires ONCE per major line, not per patch: the first session a
+# user lands on the 4.0-line console-rebuild (3.9.71+), and again the day the number actually crosses to
+# 4.x. It is deliberately HONEST about the version — per Accepted ADR-042 the number stays 3.9.x-dev
+# until the 4.0 line is field-verified, so on 3.9.x it says "the 4.0-line enhancements have landed", NEVER
+# "you're on 4.0". Non-blocking; the model decides tone; the full story is /whats-new (docs/RELEASE-NOTES-4.0.md).
+#
+# MOVED ABOVE THE WHAT'S-NEW LINE 2026-07-27, and made to SUPERSEDE it. Both are the same channel —
+# "here is what this version gives you" — and both fire on the same version change, so a user landing
+# on the 4.0 line got TWO good-news blocks in one first response, ~1.7KB of them, saying overlapping
+# things and both ending in an offer to open the Console. One per session, the bigger one wins, and
+# the what's-new stamp IS burned when the milestone speaks: the user genuinely was told about the new
+# version, so re-announcing it next session would be a repeat, not a rescue.
+MILESTONE_SHOWN=0
+if [ "$BRAIN_OFF" != "1" ] && [ -n "$RUNNING_V" ]; then
+  V_NODEV="${RUNNING_V%%-*}"; V_MAJOR="${V_NODEV%%.*}"; V_REST="${V_NODEV#*.}"; V_MINOR="${V_REST%%.*}"; V_PATCH="${V_REST#*.}"
+  case "$V_PATCH" in *.*) V_PATCH="${V_PATCH%%.*}" ;; esac
+  V_MAJOR="${V_MAJOR:-0}"; V_MINOR="${V_MINOR:-0}"; V_PATCH="${V_PATCH:-0}"
+  MILESTONE=""
+  # Single numeric compare (maj*1e6 + min*1e3 + patch) so 3.10+ still counts as the 4.0-line, and a
+  # non-numeric component skips silently rather than crashing this critical hook. 3009071 = 3.9.71.
+  case "$V_MAJOR:$V_MINOR:$V_PATCH" in
+    *[!0-9:]*) : ;;
+    *) V_INT=$(( V_MAJOR * 1000000 + V_MINOR * 1000 + V_PATCH ))
+       if [ "$V_MAJOR" -ge 4 ]; then MILESTONE="4.x"
+       elif [ "$V_INT" -ge 3009071 ]; then MILESTONE="4.0-line"; fi ;;
+  esac
+  MILESTONE_FILE="$STATE_DIR/.last-major-milestone"
+  LAST_MILESTONE=""
+  [ -f "$MILESTONE_FILE" ] && IFS= read -r LAST_MILESTONE < "$MILESTONE_FILE"
+  if [ -n "$MILESTONE" ] && [ "$MILESTONE" != "$LAST_MILESTONE" ]; then
+    MILESTONE_SHOWN=1
+    echo "[RuvNet Brain — MAJOR-LINE welcome ($MILESTONE), show ONCE near the top of your first response]"
+    echo "They upgraded INTO the big release and will NOT have seen the web explainer. Warmly, a few sentences, adapt — don't recite:"
+    if [ "$MILESTONE" = "4.x" ]; then
+      echo "  1. They're on RuvNet-Brain $RUNNING_V, a major version — the release where the brain got honest, legible, fast and self-measuring."
+    else
+      echo "  1. The 4.0-LINE enhancements have landed (they're on v$RUNNING_V). Honestly: the number stays 3.9.x until the work is field-verified (ADR-042), so 'the 4.0-line upgrades are here', NOT 'you're on 4.0'."
+    fi
+    echo "  2. Two or three things they can DO now: the Console on $CONSOLE_INVOKE (their whole stack, one live page); every number measured from their machine, never projected; it learns across their projects."
+    echo "  3. OFFER to open the Console now — on yes, invoke $CONSOLE_INVOKE. Point at the native what's-new workflow for the full highlights."
+    echo "Never claim 'proven better' or 'fully proactive' — the self-measurement is new and still filling. Once only."
+    echo "$MILESTONE" > "$MILESTONE_FILE" 2>/dev/null
+  fi
+fi
+
+# OFF: skipped whole, stamp included — the "what's new" line is the good-news channel, which is
+# advertising, and burning the once-per-version stamp would silently cost the user the announcement.
+if [ "$BRAIN_OFF" != "1" ] && [ -n "$RUNNING_V" ] && [ "$RUNNING_V" != "$LAST_ANNOUNCED" ]; then
+  WHATS_NEW=""
+  case "$RUNNING_V" in
+    3.2.*|3.1.*) WHATS_NEW="opens with the Console — $CONSOLE_INVOKE shows your whole RuvNet stack on one live page: what's installed, what your AI has actually learned from YOUR projects, and one-click reversible fixes. Every number is measured from your machine, never projected." ;;
+    3.0.*) WHATS_NEW="ships a visual configurator — /ruvnet-brain:configure mirrors your machine's RuvNet setup in plain English and turns things on safely with one click. Read-only until you say so; nothing leaves your machine." ;;
+    2.4.*) WHATS_NEW="routes every task to the cheapest model that can do the job, aware of YOUR subscriptions specifically — it detects what it can prove, asks what it can't, and learns from every override." ;;
+    2.3.*) WHATS_NEW="can no longer break silently: a failed search now rings three independent alarms (phone push, red banner at session start, nightly canary), each tested by deliberately breaking the brain. Failed searches say WHY, instead of pretending nothing matched." ;;
+    2.2.0*|2.2.1*|2.2.2*) WHATS_NEW="ships a safety watchdog that alerts you the instant a background tool starts running up API costs or a scheduled job starts failing silently. (Agentic QE testing still bills your Anthropic key — cost-optimized, and opt-in.)" ;;
+  esac
+  # Suppressed WHOLE when the milestone already spoke — see the note above it.
+  if [ -n "$WHATS_NEW" ] && [ "$MILESTONE_SHOWN" != "1" ]; then
+    echo "[RuvNet Brain — new in v$RUNNING_V]"
+    echo "Near the top of your first response, share ONE upbeat line, in your words, on what this update gives them (say it once): RuvNet Brain v$RUNNING_V $WHATS_NEW"
+  fi
+  echo "$RUNNING_V" > "$ANNOUNCED_FILE" 2>/dev/null
+fi
+
+# ADR-054: this one is KEPT while the brain is off, deliberately. It is not advertising — it is the
+# consent gate on whether FIXES can arrive without the user running a command, and §3's rule is that
+# an off machine must still be able to receive the fix for an off-state bug. Suppressing it would
+# mean a user who switches off before ever answering can never get automatic updates at all. The
+# console states the same fact from the other side ("off — still auto-updating; click to pause
+# updates too"), so the two surfaces agree.
+#
+# One-time consent question (asked at most once ever, per machine) — security-conscious default:
+# self-update is powerful (it can change the model's own instructions), so it's opt-in via an explicit
+# yes, not silently on. Once answered, never asked again; the answer is a plain yes/no file, not a flag
+# the user has to remember to pass.
+if [ ! -f "$PREF_FILE" ]; then
+  echo "[RuvNet Brain — one-time setup question]"
+  echo "Ask ONCE near the top of your first response: should the brain auto-update itself in the background, so they never run an update command? (recommended; reversible). Then run ONE via Bash and never ask again:"
+  echo "  mkdir -p '$STATE_DIR' && echo yes > '$PREF_FILE'   (or echo no)"
+  echo "No answer: ask again next session, never twice in one."
+fi
+
+# ── STABLE SPINE (ADR-023): seed on first run; honest restart notice only when the SHELL changed ──
+SPINE_HOME="$HOME/.cache/ruvnet-brain"
+trace_stage "spine-block-start"
+if command -v node >/dev/null 2>&1 && [ -f "$HOOK_DIR/update-apply.mjs" ]; then
+  if [ ! -f "$SPINE_HOME/active.json" ]; then
+    # SPAWN 1 of 3 — Zero-step migration: seed the spine from THIS running plugin install,
+    # engine-locked. It copies the payload into the immutable version store: local file I/O, normally
+    # under a second, but it must be allowed to finish after a fast hook exits or the spine is never
+    # seeded. TTL 120s — generous for a tree copy, far short of forever.
+    # It used to be a bare `( … ) &`, which in a non-interactive sh stays in the HOOK'S process group;
+    # selfcheck.mjs saw it alive at exit and reported `orphan`, and on a stranger's machine it really
+    # was a node process outliving the session. detach.mjs moves it to its own group on purpose, with
+    # a deadline and a receipt (see that file's header for the full reasoning).
+    #
+    # GATED on there actually being something to seed FROM (added with the detach, same day). The
+    # seed's own precondition is `$CLAUDE_PLUGIN_ROOT/scripts` OR a CC-staged version in the plugin
+    # cache (update-apply.mjs's `--seed` branch); with neither, it booted a whole node process to
+    # print "✗ nothing to seed from" and exit 1 — EVERY session, forever, on every machine in that
+    # state, including every CI image. The shell check mirrors that precondition and can only
+    # over-approximate (the cache dir existing but holding no valid version still spawns), never
+    # under-approximate, so no machine that could be seeded stops being seeded.
+    #
+    # AND DEDUPED TO ONE ATTEMPT PER 5 MINUTES — the seed STAMPEDE, found while fixing the orphan.
+    # The only condition here was "active.json is absent", and active.json does not appear until the
+    # seed FINISHES (~600ms measured: a whole payload tree copy). Every session start inside that
+    # window therefore launched ANOTHER seed. Opening six windows at once, or any burst, meant six
+    # concurrent copies of the same payload serializing on update-apply's lock and writing for
+    # seconds. Reproduced here as a test that could not delete its own temp HOME — the writers never
+    # stopped. Same reasoning, same shape, as the heartbeat's own "a burst of window-opens = one
+    # check" dedupe below. The stamp is written BEFORE the launch, so a crashing seed retries in
+    # five minutes rather than on every single session forever.
+    SEED_STAMP="$SPINE_HOME/.seed-attempted"
+    SEED_LAST=$(cat "$SEED_STAMP" 2>/dev/null || echo 0)
+    SEED_NOW=$(date +%s 2>/dev/null || echo 0)
+    case "$SEED_LAST" in *[!0-9]*|'') SEED_LAST=0 ;; esac
+    if { [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -d "$CLAUDE_PLUGIN_ROOT/scripts" ]; } \
+       || [ -d "$HOME/.claude/plugins/cache/ruvnet-brain" ]; then
+      if [ "$SEED_NOW" -gt 0 ] && [ $((SEED_NOW - SEED_LAST)) -gt 300 ]; then
+        mkdir -p "$SPINE_HOME" 2>/dev/null
+        echo "$SEED_NOW" > "$SEED_STAMP" 2>/dev/null
+        [ -f "$DETACH" ] && node "$DETACH" 120 "$SPINE_HOME/.seed.log" \
+          node "$HOOK_DIR/update-apply.mjs" --seed
+        trace_stage "seed-dispatch-returned"
+      fi
+    fi
+  else
+    # The ONE honest nag (replaces the old every-session "restart to load"): fires ONLY when the
+    # active generation changed boot-frozen declarations vs what this CC process booted with.
+    SPINE_V=""
+    SHELL_CHANGED=0
+    while IFS= read -r SPINE_LINE; do
+      case "$SPINE_LINE" in
+        *'"version"'*)
+          SPINE_VALUE="${SPINE_LINE#*:}"; SPINE_VALUE="${SPINE_VALUE#*\"}"
+          SPINE_V="${SPINE_VALUE%%\"*}" ;;
+        *'"shellChanged"'*true*) SHELL_CHANGED=1 ;;
+      esac
+    done < "$SPINE_HOME/active.json"
+    BOOT_V="$PLUGIN_VERSION"
+    if [ "$SHELL_CHANGED" = "1" ] && [ -n "$BOOT_V" ] && [ -n "$SPINE_V" ] && [ "$BOOT_V" != "$SPINE_V" ]; then
+      echo "[RuvNet Brain — v$SPINE_V changed boot-level declarations (the rare case); this session booted v$BOOT_V's]"
+      HOST_NAME="${RUVNET_HOOK_HOST:-claude}"
+      HOST_READY=$(node -e '
+        try {
+          const fs=require("fs"); const [file, version, host]=process.argv.slice(1);
+          const s=JSON.parse(fs.readFileSync(file,"utf8"));
+          if (s.desiredVersion===version && s.hosts?.[host]?.state==="ready" && s.hosts[host].version===version) process.stdout.write("yes");
+        } catch {}
+      ' "$SPINE_HOME/host-convergence.json" "$SPINE_V" "$HOST_NAME" 2>/dev/null)
+      if [ "$HOST_READY" != "yes" ]; then
+        echo "Tell the user ONE line: \"🧠 RuvNet Brain v$SPINE_V runtime is live, but this host's exact boot snapshot is not yet verified — do not restart for this update yet; automatic host repair will retry.\""
+      elif [ "$HOST_NAME" = "codex" ]; then
+        echo "Tell the user ONE line: \"🧠 RuvNet Brain v$SPINE_V is already installed and verified for Codex; restart Codex to load its boot-level declarations, then run /hooks and trust only ruvnet-brain@ruvnet-brain if Codex shows the changed definitions as pending. Runtime behavior already updated live.\""
+      else
+        echo "Tell the user ONE line: \"🧠 RuvNet Brain v$SPINE_V is already installed and verified for Claude Code; one restart picks up its boot-level declarations (\`claude --continue\` keeps this conversation). Runtime behavior already updated live.\""
+      fi
+    fi
+  fi
+fi
+trace_stage "spine-block-finished"
+
+# Check EVERY session start, deduped to once per 15 min (a burst of window-opens = one check).
+# Network I/O NEVER runs in the hook's foreground. A 3s-capped curl was previously called
+# "negligible", but on windows-latest the surrounding shell/process startup pushed one real
+# SessionStart past its 5s declaration and the stranger battery killed it. The check now runs
+# through detach.mjs and writes one version line; a later stale-window session consumes that receipt
+# before launching the next check. This adds at most one 15-minute interval of detection latency
+# while keeping SessionStart independent of GitHub/network health.
+NOW=$(date +%s 2>/dev/null || echo 0)
+LAST=0
+[ -f "$STAMP" ] && IFS= read -r LAST < "$STAMP"
+[ -n "$LAST" ] || LAST=0
+if [ "$NOW" -gt 0 ] && [ $((NOW - LAST)) -gt 900 ]; then
+  trace_stage "heartbeat-block-start"
+  echo "$NOW" > "$STAMP" 2>/dev/null
+
+  # ── KB (brain bundle) freshness — a SEPARATE store at ~/.cache/ruvnet-brain/kb.
+  # SECURITY (SEC-0010 #6): forge-update.mjs --apply overwrites the KB dir INCLUDING its .mjs tool
+  # files, so an unverified Release would be silent RCE on opted-in users.
+  #
+  # STATUS CORRECTED 2026-07-22: the bundle IS signed. Ed25519 signing shipped and every release
+  # from v2.0.0 on carries a valid detached .sig; forge-update.mjs verifies BEFORE extracting and
+  # fail-closes on both an invalid signature and an unfetchable one. The comment and the user-facing
+  # message here both still said "isn't signed yet" — the product was reporting its own security as
+  # weaker than it is, which is its own kind of false statement.
+  # We still DETECT + NOTIFY rather than auto-apply: that is now a deliberate policy choice about
+  # unattended code replacement, not a gap waiting on crypto. Flipping it to auto-apply is a real
+  # decision to make on purpose, not a default to drift into.
+  #
+  # SPAWN 2 of 3, RESHAPED 2026-07-27. It was `( check; if BEHIND then echo notice ) >&3 &` — a
+  # detached job printing a user-facing notice onto the hook's real stdout, minutes after the hook
+  # exited. Two defects in one line: it stayed in the hook's process group (the `orphan` violation)
+  # and its bytes went to a pipe nobody was reading any more. Now the job ONLY performs the network
+  # check and writes its log; the notice is printed synchronously, from the log a previous session's
+  # check left behind. Same information, one session later at worst, and it is metered and ordered.
+  # TTL 60s: forge-update.mjs --check is one signed-manifest fetch with its own timeouts.
+  KB_DIR="$HOME/.cache/ruvnet-brain/kb"
+  if [ "$(cat "$PREF_FILE" 2>/dev/null)" = "yes" ] && [ -f "$KB_DIR/forge-update.mjs" ] && command -v node >/dev/null 2>&1; then
+    if grep -q "BEHIND" "$STATE_DIR/.last-kb-check.log" 2>/dev/null; then
+      echo "[RuvNet Brain — a newer knowledge bundle is available. It is signed (Ed25519) and the updater verifies that signature before extracting anything. We do NOT auto-apply it: applying replaces executable tool files, which is your call. To update: cd ~/.cache/ruvnet-brain/kb && node forge-update.mjs --apply]"
+    fi
+    [ -f "$DETACH" ] && node "$DETACH" 60 "$STATE_DIR/.last-kb-check.log" \
+      /bin/sh -c "cd '$KB_DIR' && node forge-update.mjs --check"
+  fi
+  LOCAL_V="$RUNNING_V"
+  VERSION_LOG="$STATE_DIR/.last-version-check.log"
+  REMOTE_V=$(grep -m1 -E '^[0-9]+(\.[0-9]+){2}(-[A-Za-z0-9.-]+)?$' "$VERSION_LOG" 2>/dev/null | head -1)
+  [ -f "$DETACH" ] && node "$DETACH" 10 "$VERSION_LOG" \
+    node "$HOOK_DIR/host-update.mjs" --check
+  trace_stage "version-dispatch-returned"
+  if [ -n "$LOCAL_V" ] && [ -n "$REMOTE_V" ] && [ "$LOCAL_V" != "$REMOTE_V" ]; then
+    AUTO_PREF=""
+    [ -f "$PREF_FILE" ] && IFS= read -r AUTO_PREF < "$PREF_FILE"
+    if [ "$AUTO_PREF" = "yes" ] && [ -f "$HOOK_DIR/host-update.mjs" ]; then
+      # STABLE SPINE (ADR-023/051): one Brain-owned coordinator invokes the current published
+      # installer, which acquires the signed release, syncs every detected host to that exact
+      # version, verifies it, then advances the ONE spine. It requires neither host's CLI merely
+      # because the other host triggered SessionStart.
+      #
+      # SPAWN 3 of 3, and the one that most needed the deliberate reparenting rather than a kill-on-
+      # exit: two `claude plugin` network operations plus the update engine, minutes of work behind a
+      # hook that exits in ~200ms. Killing it with the session would mean the auto-updater never
+      # completes on any machine. TTL 600s — long enough for a slow network, bounded so a wedged
+      # marketplace call cannot sit on the user's machine forever. detach.mjs redirects the whole
+      # sequence's output to the log, so the per-command redirects are gone.
+      [ -f "$DETACH" ] && node "$DETACH" 600 "$STATE_DIR/.last-auto-update.log" \
+        node "$HOOK_DIR/host-update.mjs"
+      echo "[RuvNet Brain — v$REMOTE_V is downloading and will AUTO-APPLY via the Stable Spine (ADR-023); this session picks up the new behavior live]"
+      echo "Tell the user ONE short line, near the top of your first response:"
+      echo "  \"🧠 RuvNet Brain v$REMOTE_V is installing in the background for every detected host. Runtime behavior goes live automatically; if boot-level declarations changed, I'll ask for a restart only after that host's exact new snapshot is verified.\""
+      echo "Don't repeat this notice later in the same session."
+      echo ""
+    else
+      echo "[RuvNet Brain — update available, auto-update not enabled]"
+      echo "Tell the user this PLAINLY, near the top of your first response:"
+      echo "  \"🧠 RuvNet Brain found v$REMOTE_V (you're on v$LOCAL_V). Run: npx ruvnet-brain@latest --update\""
+      echo "  (Or say the word and I'll turn on auto-update so this never comes up again.)\""
+      echo "Don't repeat this notice later in the same session."
+      echo ""
+    fi
+  fi
+fi
+trace_stage "heartbeat-block-finished"
+
+# ── one-time star/feedback ask — printed ONCE EVER per machine, and only after the brain has
+# actually grounded something (.grounded-once is stamped by the bundle's forge-mcp-all.mjs on the
+# first successful search_ruvnet — so this never fires on a machine where the brain hasn't earned it).
+# The .star-ask-shown stamp is written the moment it prints, BEFORE the echo, so even a killed
+# session can't cause a repeat. Both stamps are local files; nothing here touches the network.
+# OFF: skipped whole, stamp included — asking for a star while the user has the thing switched off
+# is the worst possible moment for it, and burning the once-EVER stamp would lose the ask forever.
+if [ "$BRAIN_OFF" != "1" ] && [ -f "$STATE_DIR/.grounded-once" ] && [ ! -f "$STATE_DIR/.star-ask-shown" ]; then
+  if touch "$STATE_DIR/.star-ask-shown" 2>/dev/null; then
+    echo "[RuvNet Brain — one-time note. This will NEVER be shown again on this machine.]"
+    echo "At a natural CLOSING moment (after the work, never as an interruption), relay this line once and move on — never repeated, never embellished, in this or any future session:"
+    echo "  \"Finding this useful? Star github.com/stuinfla/ruvnet-brain or leave feedback — it keeps the nightly updates coming.\""
+  fi
+fi
+
+# ── read the ACTUAL installed versions (plugin AND brain bundle), live, never hardcoded ──
+BANNER_V="unknown"; BANNER_D=""; BANNER_KB=""
+if [ -n "$PLUGIN_VERSION" ]; then
+  BANNER_V="$PLUGIN_VERSION"
+  BANNER_D="$PLUGIN_UPDATED"
+fi
+[ -z "$BANNER_V" ] && BANNER_V="unknown"
+# Record what THIS session actually loaded. The statusline (and anything else) must report the
+# RUNNING version from this file — never the on-disk marketplace copy, which the background
+# auto-updater refreshes ahead of the restart. Showing a staged version as if it were running
+# is a trust-destroying lie ("user thinks they have the 6.2 fix; they're on 6.1").
+#
+# ONLY A REAL INSTALL MAY WRITE THE GLOBAL RUNNING VERSION (fixed 2026-07-22).
+#
+# $CLAUDE_PLUGIN_ROOT points at whatever plugin THIS session loaded. In a development checkout of
+# this repo that is the working tree — so a dev session wrote its uncommitted version into a file
+# that EVERY OTHER PROJECT's statusline reads. Measured: .running-version held 3.9.0-dev while the
+# installed marketplace copy was 3.8.1-dev, so the owner's other projects displayed a version they
+# were not running. He caught it, not us.
+#
+# That is the same global-state pollution as issue #36 (per-CWD ledgers scattered into users'
+# repos), and the same lie shape the comment above this line already warns about — a staged version
+# shown as running. The comment was right and the code disagreed with it.
+#
+# So: write the global marker only when the loaded plugin IS the installed one. A dev checkout
+# still gets its banner; it just may not speak for the machine.
+case "$CLAUDE_PLUGIN_ROOT" in
+  "$HOME/.claude/plugins/"*)
+    [ "$BANNER_V" != "unknown" ] && echo "$BANNER_V" > "$STATE_DIR/.running-version" 2>/dev/null
+    ;;
+  *)
+    # Development checkout: record it separately so it is visible but never mistaken for the
+    # machine-wide running version.
+    [ "$BANNER_V" != "unknown" ] && echo "$BANNER_V" > "$STATE_DIR/.dev-version" 2>/dev/null
+    ;;
+esac
+# The brain bundle stamps its own provenance (SOURCE.json releaseTag) at build time.
+[ -f "$HOME/.cache/ruvnet-brain/kb/SOURCE.json" ] && \
+  BANNER_KB=$(grep -m1 '"releaseTag"' "$HOME/.cache/ruvnet-brain/kb/SOURCE.json" 2>/dev/null | sed -E 's/.*"releaseTag": *"([^"]+)".*/\1/')
+
+# ── THE OFF STATE LINE (ADR-054 §3) — and then nothing else. ────────────────────────────────────
+# ── ASCII→SVG drift (ADR-055 §8) ─────────────────────────────────────────────────────────────────
+# The owner: ASCII art should become SVG "as a standard course of business… at the appropriate time."
+# The appropriate time is HERE and nowhere else. The ascii-to-svg skill has advertised since
+# 2026-01-08 that it is "fully automatic via global PostToolUse hook … set-and-forget"; that hook
+# never existed, and it never could — converting a diagram needs a MODEL, and a PostToolUse hook has
+# ~5s, no session and no tokens. ADR-055 v1 then moved conversion to pre-push and reproduced the same
+# impossibility one chokepoint over (a git hook is also just a shell). Session start is the one place
+# in the whole system where a model is actually in the room to act on what it is told.
+#
+# So the split is: this measures, the SKILL converts. Deterministic here (hash + the skill's own
+# confidence scoring), generative there. It never converts, never writes and never blocks — worst
+# case is one line nobody acts on. It prints NOTHING when there is nothing to do, which is what keeps
+# it believable; measured at ~80ms, and silent in a repo with no manifest, so it costs other projects
+# nothing. Advertising-class, so it dies with the brain like everything else below.
+# `${CLAUDE_PROJECT_DIR:-$PWD}` is the house form (line 82) — a bare $CLAUDE_PROJECT_DIR resolves to
+# "/scripts/..." when unset. The -f guard is also the SCOPE: the detector derives its root from its
+# own location, so it must only ever run in a project that actually ships it. Other projects get a
+# failed test and zero output, which is exactly right.
+ASCII_DRIFT="${CLAUDE_PROJECT_DIR:-$PWD}/scripts/ascii-drift.mjs"
+if [ "$BRAIN_OFF" != "1" ] && [ -f "$ASCII_DRIFT" ]; then
+  node "$ASCII_DRIFT" --quiet 2>/dev/null || true
+fi
+
+# ── Grounding-unproven surfacer (ADR-058 §D8, closes the "-15 nothing exercises a hook fire /
+# verdict evaporates" findings). bin/install.mjs writes ~/.cache/ruvnet-brain/install-state.json
+# with grounding:"unproven" when its own one-shot smoke query at install time could not verify a
+# real, resolvable citation — DELIBERATELY non-fatal there (a first-run model download or an
+# air-gapped machine is not a broken install; see the comment right above that write in
+# bin/install.mjs). What this banner fixes is the verdict EVAPORATING the moment that process
+# exited: it surfaces here, at every session start, until kb/forge-mcp-all.mjs clears it the
+# instant a real search_ruvnet returns a real cited answer.
+#
+# Same shape as the open-issue surfacer just above (a node -e reader, a tab-delimited marker line,
+# a case statement) and, unlike the console/router/star-ask "advertising" blocks, it is NOT gated on
+# BRAIN_OFF — this is a health fact about the install itself, in the same "keeps running while off"
+# category as the GONG health alarm and the open-issue banner (see this file's header note on the
+# OFF split). Best-effort and fail-silent: a missing file, a missing `node`, or a malformed JSON all
+# emit nothing rather than break the session.
+GROUNDING_STATE="$HOME/.cache/ruvnet-brain/install-state.json"
+if [ -f "$GROUNDING_STATE" ] && command -v node >/dev/null 2>&1; then
+  GROUNDING_LINE=$(node -e '
+    try {
+      const fs=require("fs");
+      const s=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));
+      if (s.grounding && s.grounding !== "proven") {
+        const when = s.at ? new Date(s.at).toISOString().slice(0,16).replace("T"," ") : "an earlier run";
+        console.log(`UNPROVEN\t${when} (${s.reason || "no reason recorded"})`);
+      }
+    } catch { /* fail-silent — a malformed file must never break the session */ }
+  ' "$GROUNDING_STATE" 2>/dev/null)
+  case "$GROUNDING_LINE" in
+    UNPROVEN*)
+      echo "[RuvNet Brain — grounding not yet PROVEN on this machine (mention once, calmly, near the top)]"
+      echo "The last check (${GROUNDING_LINE#UNPROVEN	}) could not verify a real, resolvable citation — often just a first-run model download or an offline machine, not necessarily a broken install. Say so once, plainly: the next real search_ruvnet confirms or clears it automatically, and \`npx ruvnet-brain --doctor\` shows the current verdict any time."
+      ;;
+  esac
+fi
+
+#
+# Everything from here down is the confidence banner, the capability announcement and THE PLAYBOOK:
+# ~2,000 tokens of the brain talking about itself. All of it is advertising, all of it dies when the
+# brain is off, and exactly ONE line replaces it.
+#
+# ONE line, and no instruction attached. Total silence would make an off brain indistinguishable
+# from a broken one — this repo has already shipped a dark brain that nobody noticed for days, which
+# is the whole reason the GONG exists. But an off brain that explains itself at length is just
+# advertising wearing a state label. So: the fact, the date, and a note not to raise it unprompted.
+# The date comes from the switch file itself and is omitted rather than invented if unreadable.
+#
+# It deliberately does NOT say how to switch the brain back on. That mechanism belongs to the user
+# and to the console; handing it to the model in a context block is the same consent problem
+# protect-brain-state.sh exists to wall off.
+if [ "$BRAIN_OFF" = "1" ]; then
+  # An absent knowledge bundle is folded INTO this same line rather than added as a second one — the
+  # GONG's alarm was suppressed for it above (ADR-054 §3 Health), and replacing one alarm with two
+  # quiet lines would just be a quieter version of the same over-speaking.
+  OFF_KB_NOTE=""
+  [ "$GONG_ABSENT_BY_CHOICE" = "1" ] && OFF_KB_NOTE="; no knowledge bundle on this machine — disabled by choice, not broken"
+  echo "[RuvNet Brain — brain OFF by your setting${OFF_SINCE:+ (since $OFF_SINCE)}$OFF_KB_NOTE. Do not mention it unless the user asks.]"
+  # The meter still finalizes below — an off session's byte count is a real measurement.
+  if [ -n "$METER_TMP" ]; then
+    exec 1>&3 3>&-
+    METER_LEDGER_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/ruvnet-brain"
+    node "$HOOK_DIR/finalize-token-meter.mjs" "$METER_TMP" "$METER_LEDGER_DIR" "$PWD" 2>/dev/null
+  fi
+  exit 0
+fi
+
+# THE CONFIDENCE SIGNAL — the hook's original reason to exist (see the header). Condensed 2026-07-27
+# from two blocks totalling 1,603 bytes: the old form wrote the user-facing sentence out verbatim and
+# then told the model to "adapt naturally", which is paying twice for one line. The FACTS the line
+# must carry are unchanged and are all still here; the model writes the sentence.
+# No backticks below — this heredoc interpolates, and a backtick would be command substitution.
+#
+# THE BROKEN-BRAIN BRANCH (added 2026-07-27). The full banner below asserts "search_ruvnet and the
+# grounding hooks are live now". When the GONG above has just reported that retrieval is DOWN, that
+# sentence is FALSE, and the two blocks were printing one after the other — an alarm saying the brain
+# is broken, immediately followed by a confidence banner saying it works. The product may never lie
+# about its own condition, so the down case gets its own short, true banner instead. It costs ~400
+# fewer bytes in exactly the case that was previously the most expensive, which is a consequence and
+# not the reason.
+if [ -n "$BRAIN_PROBLEM" ]; then
+  cat <<EOF
+[RuvNet Brain v$BANNER_V — active this session, RETRIEVAL DOWN]
+The plugin and its hooks are running, but the brain itself is broken (see the alarm above). Do not claim grounding works. If you mention it at all: "🧠 RuvNet Brain active (v$BANNER_V) — but its search is down right now."
+EOF
+else
+  cat <<EOF
+[RuvNet Brain v$BANNER_V — active this session${BANNER_D:+ · updated $BANNER_D}${BANNER_KB:+ · knowledge bundle $BANNER_KB}]
+USER-LEVEL: one brain (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project. search_ruvnet and the grounding hooks are live now.
+Open your FIRST response with ONE short, warm confirmation in your own words (2-3 lines, then move on; never repeat it this session). It must say "🧠 RuvNet Brain active (v$BANNER_V${BANNER_KB:+, brain $BANNER_KB})" — that version, in parentheses, always — and convey: it grounds rUv's stack (RVF, Ruflo, AgentDB, SPARC, agentic-flow…) in his real source rather than guessing; npx github:stuinfla/ruvnet-brain --doctor checks it; $CONSOLE_INVOKE opens a visual settings page.
+EOF
+fi
+
+# ── MetaHarness token-intelligence + QE + brain-score announcement (2.0 features) — fires ONLY when
+# the ruflo MCP is detectable (global CLI, user-level registration in ~/.claude.json, or project
+# markers); degrades SILENTLY when absent so a user without the stack is never promised a tool that
+# isn't wired. HONESTY LINE: the READ layer (metaharness_score / oia_audit, QE on demand, the
+# /brain-score scorecard) is free and on by default; metaharness_evolve (WRITE) and per-task
+# cheap-model routing (agentic-flow --router-mode cost-optimized) need OPENROUTER_API_KEY — the
+# announcement says so plainly instead of pretending a key is already set.
+if command -v ruflo >/dev/null 2>&1 || grep -qs '"ruflo"' "$HOME/.claude.json" || [ -d ".claude-flow" ] || [ -d ".swarm" ]; then
+  cat <<'EOF'
+[RuvNet Brain — token intelligence + QE, mention once]
+Right after the confidence line, ONE line, never repeated this session: token-smart routing, a QE test fleet and a 0-100 repo scorecard are available — say "do this cheaper", "QE this", "score my harness", "score this repo", /brain-build or /brain-prompt. Scoring is free; the self-improvement loop and cheap-model routing need an OPENROUTER_API_KEY.
+EOF
+fi
+
+# ── THE PLAYBOOK (ADR-0011 Phase 2) — injected ONCE per session instead of ~2,000 tokens on every
+# build prompt. The UserPromptSubmit hook (ground-ruvnet.sh Gate 3) emits a ≤12-line reminder that
+# points back here on each build turn.
+#
+# CONDENSED 2026-07-27, and the full text MOVED, not deleted → skills/ruvnet-brain/PLAYBOOK.md.
+# The measurement that forced it: this one block was 6,282 bytes of a 9,127-byte hook output, against
+# the 4,096-byte cap scripts/selfcheck.mjs enforces *because* — its words — "it lands in the user's
+# context window". Nine kilobytes on every session start, in every project on the machine, is a real
+# recurring cost, and the stranger-matrix reported it red on all five images.
+#
+# WHAT WAS AND WAS NOT CUT, stated plainly because tests/unit/hook-hardening.test.mjs §4 argued the
+# opposite case and deserves an answer: every OPERATIVE instruction survives here verbatim in intent
+# — the hard rule, the DO-FIRST three, all six A-beats, all seven B-bullets, C and D. What left is
+# elaboration, worked phrasing, and the "never do X" restatements. Static instructional prose does
+# not have to be re-injected verbatim each session to be obeyed; the pointer below makes the full
+# text one Read away for the turn that actually needs it, which the per-turn Gate-3 reminder is
+# already the precedent for. This is the ADR-level call tests/unit/hook-hardening.test.mjs §4 said
+# was owed — a human should sanity-check that judgement, which is why it is written down here.
+PLAYBOOK_DOC="$HOOK_DIR/../skills/ruvnet-brain/PLAYBOOK.md"
+cat <<EOF
+[RuvNet Brain — standing build playbook for this session (referenced by later turns as THE PLAYBOOK)]
+Full text: $PLAYBOOK_DOC — read it before your first build response this session. Condensed:
+EOF
+cat <<'EOF'
+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.
+⛔ 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.
+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.
+EOF
+
+# ── TOKEN METER finalize — replay the captured output, then log its TRUE size (see header block).
+# Fail-silent at every step: metering can never block a session start (still exit 0 regardless).
+if [ -n "$METER_TMP" ]; then
+  trace_stage "meter-finalize-start"
+  exec 1>&3 3>&-
+  # ONE fixed, user-level ledger — see the full note in ground-ruvnet.sh (issue #36, mamd69).
+  # Writing relative to CWD scattered hidden .ruvnet-brain/ directories into users' project trees.
+  METER_LEDGER_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/ruvnet-brain"
+  node "$HOOK_DIR/finalize-token-meter.mjs" "$METER_TMP" "$METER_LEDGER_DIR" "$PWD" 2>/dev/null
+  trace_stage "meter-finalize-finished"
+fi
+trace_stage "body-finished"
+exit 0