ruvnet-brain 4.3.21 → 4.3.26

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// session-start-fsutil.mjs — the small set of fail-silent fs/process helpers every SessionStart
+// stage module needs. Extracted 2026-09-11 so session-start-core.mjs's own file could shrink below
+// 500 lines by moving stage bodies into their own modules without each one re-implementing the same
+// six helpers. Every function here is deliberately fail-open: SessionStart is advisory and must
+// never throw a session over a missing file or a slow subprocess.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const read = (file, fallback = '') => {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return fallback; }
+};
+
+export const json = (file, fallback = null) => {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+};
+
+export const exists = (file) => {
+  try { return fs.existsSync(file); } catch { return false; }
+};
+
+export const mkdir = (dir) => {
+  try { fs.mkdirSync(dir, { recursive: true }); return true; } catch { return false; }
+};
+
+export const write = (file, value) => {
+  try { mkdir(path.dirname(file)); fs.writeFileSync(file, String(value)); return true; } catch { return false; }
+};
+
+export const mtimeMs = (file) => {
+  try { return fs.statSync(file).mtimeMs; } catch { return 0; }
+};
+
+export const firstVersion = (text) => String(text).split(/\r?\n/).find((line) =>
+  /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(line.trim()))?.trim() || '';
+
+/** spawnSync a node script, fail-silent: a missing file, a spawn error, or a timeout all resolve to
+ * null — never thrown. SessionStart is advisory; no stage may fail a session over a subprocess. */
+export const runNode = (file, args = [], options = {}) => {
+  if (!exists(file)) return null;
+  try {
+    return spawnSync(process.execPath, [file, ...args], {
+      cwd: options.cwd,
+      env: options.env,
+      encoding: 'utf8',
+      stdio: options.stdio || 'ignore',
+      timeout: options.timeout,
+      windowsHide: true,
+    });
+  } catch { return null; }
+};
+
+/** Launch a maintenance job OUT of this process's own wait — via the shared detach.mjs launcher,
+ * which forks a truly detached child and returns in ~40ms (see plugin/scripts/detach.mjs's own
+ * header). `timeout: 2000` bounds ONLY the launch step (spawning the detached grandchild), never the
+ * job itself, whose lifetime is `ttl` seconds inside detach.mjs's own supervisor. */
+export const dispatchDetached = (hookDir, ttl, log, command, args = [], env = process.env) =>
+  runNode(path.join(hookDir, 'detach.mjs'), [
+    String(ttl), log, command, ...args,
+  ], { env, stdio: 'ignore', timeout: 2000 })?.status === 0;

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// session-start-health.mjs — the three LOCAL installation-health reads SessionStart's banner depends
+// on: is the brain turned off, is the knowledge cache actually usable, and is the MCP worker alive.
+// Extracted 2026-09-11 out of session-start-core.mjs to keep that file under 500 lines; behavior is
+// unchanged from the original inline functions.
+//
+// These are the checks behind the 🚨 HEALTH ALARM and the RETRIEVAL-DOWN banner — LOCAL installation
+// integrity, not maintainer-only content. Per the 2026-09-11 reviewer correction, everything read
+// here is delivered to every user via SessionStart's existing always-shown alarm/banner lines,
+// worded for the user — never gated behind the maintainer entitlement file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { json, exists, mtimeMs } from './session-start-fsutil.mjs';
+
+export const brainState = (env, home) => {
+  const stateDir = env.RUVNET_BRAIN_STATE_DIR || path.join(home, '.config', 'ruvnet-brain');
+  const file = path.join(stateDir, 'brain-off');
+  let off = env.RUVNET_BRAIN_OFF === '1';
+  if (!off) {
+    try { fs.statSync(file); off = true; }
+    catch (error) { off = !(error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')); }
+  }
+  let since = '';
+  if (off) {
+    const record = json(file);
+    if (typeof record?.since === 'string') since = record.since.slice(0, 10);
+    if (!since && mtimeMs(file)) since = new Date(mtimeMs(file)).toISOString().slice(0, 10);
+  }
+  return { off, since, stateDir, file };
+};
+
+export const health = (home, off) => {
+  const kb = path.join(home, '.cache', 'ruvnet-brain', 'kb');
+  let rvf = false;
+  try { rvf = fs.readdirSync(kb).some((name) => name.endsWith('.rvf') && exists(path.join(kb, name))); }
+  catch { /* absent */ }
+  const absentByChoice = off && (!exists(kb) || !rvf);
+  if (absentByChoice) return { problem: '', absentByChoice };
+  if (!exists(kb)) return { problem: `the brain cache directory is MISSING (${kb}) — reinstall: npx github:stuinfla/ruvnet-brain`, absentByChoice };
+  if (!rvf) return { problem: `NO vector stores (.rvf) found in ${kb} — the brain is empty; reinstall: npx github:stuinfla/ruvnet-brain --force`, absentByChoice };
+  if (!exists(path.join(kb, 'node_modules', '@xenova', 'transformers', 'package.json'))) {
+    return { problem: `reader dependencies are MISSING (node_modules gone) — every search WILL fail. Fix: cd ${kb} && npm i`, absentByChoice };
+  }
+  const last = json(path.join(home, '.cache', 'ruvnet-brain', 'health.json'));
+  if (last?.status === 'down') {
+    const detail = `"error": ${JSON.stringify(String(last.error || 'unknown error'))}`.slice(0, 180);
+    return { problem: `the last real search FAILED across all repos (${detail}). Fix: cd ${kb} && npm i, then run one search to clear the alarm`, absentByChoice };
+  }
+  return { problem: '', absentByChoice };
+};
+
+export const mcpReadiness = (env, home) => {
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
+  const receipt = json(path.join(brainHome, 'mcp-readiness.json'));
+  if (receipt?.state === 'ready' && Number.isInteger(receipt.pid) && Number.isInteger(receipt.workerPid)) {
+    try {
+      process.kill(receipt.pid, 0);
+      process.kill(receipt.workerPid, 0);
+      return { state: 'ready', receipt };
+    } catch { /* a stale receipt is registration evidence, not live evidence */ }
+  }
+  if (receipt?.state === 'degraded') return { state: 'degraded', receipt };
+  return { state: 'registered', receipt };
+};

package/plugin/scripts/session-start-hook-description.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// session-start-hook-description.mjs — BANNER TRUTH. The banner used to say "the grounding hooks
+// are active" unconditionally, in every state, on every version — false since 4.3.17 retired the
+// grounding plane (plugin/hooks/hook-contracts.json's own `_note`: "Exactly two continuity handlers
+// are permitted"). This module reads THAT file at runtime and describes whatever is actually
+// registered, so the sentence can never drift from the real contract again — including forward, when
+// the continuity lane bumps hook-contracts.json to a new `_version` with a different event set
+// (e.g. capture hooks at Stop/PreCompact/SessionEnd, an advocacy route on UserPromptSubmit): this
+// file does not hardcode which ids or events exist, only how to render whatever it finds.
+import fs from 'node:fs';
+
+// Friendly labels for ids this file KNOWS about today. Anything else still renders correctly via the
+// fallback below — this dictionary only makes today's two contracts read naturally; it is never the
+// thing that decides what counts as "active".
+const KNOWN_ACTIONS = {
+  'session-start': 'restore',
+  'continuation-gate': 'continuation',
+};
+
+function friendlyAction(contract) {
+  const known = KNOWN_ACTIONS[contract?.id];
+  if (known) return known;
+  const id = String(contract?.id || '').trim();
+  return id ? id.replace(/-/g, ' ') : 'hook';
+}
+
+/** One factual sentence naming every {event, action} pair hook-contracts.json currently declares,
+ * grouped by event. Never asserts a capability (like "grounding") the data does not name. */
+export function describeLifecycleHooks(contractsDoc) {
+  const contracts = Array.isArray(contractsDoc?.contracts) ? contractsDoc.contracts : [];
+  if (!contracts.length) return 'No lifecycle hooks are currently registered.';
+  const byEvent = new Map();
+  for (const contract of contracts) {
+    if (!contract?.event) continue;
+    const list = byEvent.get(contract.event) || [];
+    list.push(friendlyAction(contract));
+    byEvent.set(contract.event, list);
+  }
+  const parts = [...byEvent.entries()].map(([event, actions]) => `${event} ${actions.join('/')}`);
+  return parts.length ? `Lifecycle hooks: ${parts.join(', ')}.` : 'No lifecycle hooks are currently registered.';
+}
+
+export function readHookContracts(hookContractsPath) {
+  try { return JSON.parse(fs.readFileSync(hookContractsPath, 'utf8')); } catch { return null; }
+}

package/plugin/scripts/session-start-issue-alert.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// session-start-issue-alert.mjs — the maintainer-only open-issue pointer.
+//
+// REWRITTEN 2026-09-11 after two findings:
+//   1. SCOPING BUG: the per-user entitlement file was never checked against the CURRENT project's
+//      identity, so an entitled maintainer saw the alert in every unrelated project on the machine.
+//      Fixed by session-start-repo-identity.mjs's isMaintainerRepo() — BOTH the local entitlement
+//      file AND the current checkout's git remote must agree before anything is shown.
+//   2. SCOPE CREEP: SessionStart printed a per-issue breakdown (numbers, titles, ages) sourced from a
+//      GitHub lookup. Per reviewer correction, that detail belongs to issue-watch.mjs's own output
+//      surface (its console report and open-issues.json), not to a hook that fires on every prompt
+//      boundary. SessionStart now prints AT MOST one line — a pointer, not a report — read from the
+//      cache within a 100ms budget and never touching the network itself.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMaintainerRepo } from './session-start-repo-identity.mjs';
+
+const json = (file, fallback = null) => {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+};
+
+export const ISSUE_POINTER_BUDGET_MS = 100;
+// A corrupt/huge open-issues.json is not evidence of anything actionable; refuse to even attempt
+// parsing past this size rather than let a pathological file consume the stage's budget.
+const MAX_STATUS_BYTES = 256 * 1024;
+
+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);
+};
+
+/**
+ * At most ONE line, naming a count and where to look — never a per-issue breakdown. Requires BOTH
+ * the local per-user entitlement file AND the current project's git remote to name the entitled
+ * repo; either alone is not enough (see module header).
+ */
+export function surfaceIssuePointer({ stateDir, emit, now, env, home, platform, cwd, budgetMs = ISSUE_POINTER_BUDGET_MS }) {
+  const start = Date.now();
+  try {
+    const statusPath = path.join(stateDir, 'open-issues.json');
+    let size = 0;
+    try { size = fs.statSync(statusPath).size; } catch { return; }
+    if (size > MAX_STATUS_BYTES) return;
+
+    const status = json(statusPath);
+    const observedAt = Date.parse(status?.at || '');
+    if (!Number.isFinite(observedAt) || observedAt > now + 5 * 60_000 || now - observedAt > 6 * 3600_000) return;
+    // The 100ms budget covers exactly what correction #2 named — "a one-line pointer read from the
+    // cache" — checked HERE, before the (separately, generously bounded — see
+    // session-start-repo-identity.mjs's own spawnSync timeout) git-based repo-scoping check below.
+    // A local JSON read is always microseconds; a real overrun here means something pathological.
+    if (Date.now() - start > budgetMs) return;
+    if (!maintainerIssueEntitlement(env, home, status.repo, platform)) return;
+    if (!isMaintainerRepo(cwd)) return; // the CURRENT project must itself be the entitled repo
+
+    const open = Array.isArray(status.issues) ? status.issues : [];
+    if (!open.length) return;
+    const breaches = open.filter((issue) => issue.breach).length;
+    const ageHours = (now - observedAt) / 3_600_000;
+    const breachNote = breaches ? `, ${breaches} past SLA` : '';
+    emit(`[RuvNet Brain — OPEN ISSUES: ${open.length} on ${status.repo}${breachNote}, checked ${ageHours.toFixed(1)}h ago — full detail: node scripts/issue-watch.mjs]`);
+  } catch { /* advisory only — a broken cache read must never affect the session */ }
+}

package/plugin/scripts/session-start-repo-identity.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// session-start-repo-identity.mjs — resolves whether the CURRENT project's git remote IS the one
+// maintainer-scoped repo, read-only and bounded. See session-start-issue-alert.mjs for the bug this
+// closes.
+//
+// THE BUG (found 2026-09-11): the maintainer entitlement file
+// (~/.config/ruvnet-brain/maintainer-issues.json) is PER-USER, not per-project. A maintainer entitled
+// for stuinfla/ruvnet-brain therefore saw the SAME "16 issues past SLA" banner in every UNRELATED
+// project on the machine — Codex repeated it in 4 of 8 answers on sandbox repos with zero relation to
+// ruvnet-brain. The entitlement check never looked at what project the session was actually IN. This
+// module is that missing half.
+//
+// FIXED CONSTANT, ON PURPOSE (reviewer correction 2026-09-11): entitlement must be an exact
+// remote-URL match against ONE fixed repo, never a value read back out of a cache file or the
+// entitlement file's own `repos` array — so a corrupted or malicious open-issues.json / entitlement
+// file can widen who is ASKED, but never which repo is ELIGIBLE to be asked about.
+import { spawnSync } from 'node:child_process';
+
+export const MAINTAINER_REPO_SLUG = 'stuinfla/ruvnet-brain';
+
+// Matches both `git@github.com:owner/repo.git` (ssh) and `https://github.com/owner/repo(.git)`.
+const SLUG_RE = /github\.com[:/]+([^/]+)\/([^/.]+?)(?:\.git)?$/;
+
+/** "owner/repo" from a git remote URL in either form; null for anything else (including no URL). */
+export function parseRepoSlugFromRemote(remoteUrl) {
+  const m = SLUG_RE.exec(String(remoteUrl || '').trim());
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Read-only, LOCAL-only (`git config --get`, never a network call), bounded so a hung or missing
+ * git binary can never eat the SessionStart budget. Returns null for: not a git checkout, no
+ * `origin` remote, a non-GitHub remote, or git missing/erroring.
+ *
+ * 1000ms, not a few hundred (2026-09-11, found live under real machine load with several parallel
+ * agents contending for CPU): `git config --get` is normally single-digit ms, but a tighter budget
+ * measurably flaked under contention — the git subprocess got killed before it could answer, which
+ * fails CLOSED (hides the pointer) rather than open, but is still avoidable jitter for a purely
+ * local read. Matches this codebase's own convention for "should be near-instant, allow headroom
+ * for a loaded runner" (ascii-drift.mjs's spawnSync timeout is the same order of magnitude). */
+export function resolveProjectRepoSlug(cwd, { timeoutMs = 1000, gitBin = process.env.GIT_BIN || 'git' } = {}) {
+  try {
+    const r = spawnSync(gitBin, ['config', '--get', 'remote.origin.url'], {
+      cwd, encoding: 'utf8', timeout: timeoutMs,
+    });
+    if (r.status !== 0) return null;
+    return parseRepoSlugFromRemote(r.stdout);
+  } catch { return null; }
+}
+
+/** The ONE predicate maintainer-only content may gate on: is THIS project checkout the entitled
+ * repo, by exact remote-URL match against the fixed constant above. */
+export function isMaintainerRepo(cwd, options) {
+  return resolveProjectRepoSlug(cwd, options) === MAINTAINER_REPO_SLUG;
+}

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

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// session-start-signals.mjs — surfaces external CI-signal transitions (red/green/unverifiable)
+// recorded by scripts/signal-watch.mjs's polled half. Extracted 2026-09-11 out of
+// session-start-core.mjs to keep that file under 500 lines, AND fixed at the same time:
+//
+// THE MEASURED SLOW PART (2026-09-11 latency profiling): this repo's own checkout has
+// scripts/signal-watch.mjs (a dev-only tool — a downloader's machine has none), so
+// `exists(poller)` was true and the OLD code ran it with a blocking `spawnSync` whenever
+// pending.jsonl was non-empty and ci-status.json was stale — a real `gh run list` network call,
+// internally bounded at 3000ms by that file's own GH_TIMEOUT_MS, dominating every cold/warm firing
+// measured in this repo. That 3000ms budget was sized for the OLD "SessionStart owns the whole 5s
+// hooks.json timeout" assumption; the derived-sum contract (session-start-budget.mjs) no longer
+// allows any one stage that much room.
+//
+// THE FIX: dispatch the poll the same way session-start-core.mjs already dispatches every other
+// maintenance job (stableSpine's seed, heartbeat's update-check) — DETACHED, via detach.mjs, which
+// returns in ~40ms having handed the real work to a background process with its own TTL. The signal
+// surfaced THIS session-start is therefore always the PREVIOUS poll's result (same "eventually
+// consistent, never blocking" contract issue-watch.mjs's hourly cache already uses for open issues);
+// a push's CI-red transition surfaces on the NEXT session-start rather than the current one, which is
+// still well inside the "surface this soon, not never" intent and no longer risks a multi-second hang.
+import path from 'node:path';
+import { json, exists, mtimeMs, write, dispatchDetached } from './session-start-fsutil.mjs';
+
+export function surfaceSignals({ env, cwd, stateDir, hookDir, emit, now, pollTtlSec = 30 }) {
+  const signalDir = env.RUVNET_SIGNAL_DIR || path.join(stateDir, 'external-signals');
+  const pending = path.join(signalDir, 'pending.jsonl');
+  const statusFile = path.join(signalDir, 'ci-status.json');
+  const surfacedFile = path.join(signalDir, 'surfaced.json');
+  if (!exists(pending)) return;
+
+  const poller = path.join(env.CLAUDE_PROJECT_DIR || cwd, 'scripts', 'signal-watch.mjs');
+  if (exists(poller) && now - mtimeMs(statusFile) > 600_000) {
+    dispatchDetached(hookDir, pollTtlSec, path.join(stateDir, '.last-signal-poll.log'), process.execPath, [poller], env);
+  }
+  const status = json(statusFile);
+  if (!status || typeof status !== 'object') return;
+  const onDisk = json(surfacedFile, {});
+  const surfaced = {
+    debts: onDisk?.debts && typeof onDisk.debts === 'object' ? onDisk.debts : {},
+    redRepo: onDisk?.redRepo && typeof onDisk.redRepo === 'object' ? onDisk.redRepo : {},
+  };
+  let changed = false;
+  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') continue;
+      emit(`[RuvNet Brain — EXTERNAL SIGNAL: CI is RED for ${debt.repo}@${shortSha} — surface this to the user now, near the top, with ZERO prompting]`);
+      emit(`Workflow ${debt.workflowName || 'ci'} concluded ${debt.conclusion} on ${debt.repo}@${shortSha}; inspect with gh run list --repo ${debt.repo} --commit ${debt.ref}.`);
+      surfaced.debts[key] = 'red';
+      surfaced.redRepo[debt.repo] = key;
+      changed = true;
+      continue;
+    }
+    if (debt?.state === 'resolved' && debt.conclusion === 'success') {
+      if (surfaced.redRepo[debt.repo]) {
+        emit(`[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; }
+      continue;
+    }
+    if (debt?.state === 'unverifiable' && surfaced.debts[key] !== 'unverifiable') {
+      emit(`[RuvNet Brain — external signal: CI status could not be checked for ${debt.repo}@${shortSha}: ${debt.reason || 'unknown reason'}]`);
+      surfaced.debts[key] = 'unverifiable';
+      changed = true;
+    }
+  }
+  if (changed) write(surfacedFile, JSON.stringify(surfaced, null, 2));
+}

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// session-start-trace.mjs — runtime enforcement of the STAGE_BUDGETS_MS contract
+// (session-start-budget.mjs), plus the fine-grained diagnostic trace requested after the 2026-09-11
+// incident where one SessionStart firing was silently killed by its own watchdog with zero output:
+// nothing recorded WHICH stage was still running when the 5s hooks.json timeout hit.
+//
+// TWO JOBS, one small module (ADR-055 F16 — a gate and its evidence must not be two code paths):
+//   1. stage(name, fn) — always runs fn and always records its elapsed ms. When
+//      RUVNET_BRAIN_SESSION_START_TRACE=1 it also streams `SESSION_TRACE stage=<name>
+//      elapsed_ms=<n>` to stderr — the exact substring scripts/selfcheck.mjs's assertContract()
+//      already greps out of a slow hook's stderr (see its 'slow' violation), so a stage trace is
+//      useful diagnostic detail on a stranger's machine even without the env flag set, the moment a
+//      firing is already slow enough to be flagged.
+//   2. A wall-clock DEADLINE derived from the very same STAGE_BUDGETS_MS: once the running total of
+//      "budget that should already have been spent" would exceed the deadline, a stage is SKIPPED
+//      with a one-line stderr note instead of being allowed to run past the hook's own timeout and
+//      get killed with no explanation. Skipping is always safe here — every stage this file wraps is
+//      advisory (SessionStart's whole contract is 'advisory'; nothing wrapped may block a session).
+import { STAGE_BUDGETS_MS, sumBudgetsMs } from './session-start-budget.mjs';
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.enabled] - stream each stage's timing to stderr as it completes.
+ * @param {(chunk: string) => void} [opts.write] - stderr sink (defaults to a no-op).
+ * @param {Record<string, number>} [opts.budgets] - stage name -> budget ms (defaults to the shared
+ *   contract in session-start-budget.mjs; a test seam only).
+ * @param {number} [opts.deadlineMs] - total wall-clock budget for every WRAPPED stage combined,
+ *   excluding `restore` (which runs before this tracer starts, outside session-start-core.mjs's
+ *   try block). Defaults to the contract sum minus `restore`'s own budget.
+ */
+export function createStageTracer({
+  enabled = false,
+  write = () => {},
+  budgets = STAGE_BUDGETS_MS,
+  deadlineMs = sumBudgetsMs(budgets) - (budgets.restore || 0),
+} = {}) {
+  const stages = [];
+  const bodyStart = Date.now();
+
+  const record = (name, ms, extra = '') => {
+    stages.push({ name, ms, skipped: Boolean(extra) });
+    // A skip is an anomaly, not a diagnostic opt-in: it is the direct fix for "the watchdog killed
+    // the hook with zero output", so it is written UNCONDITIONALLY, trace flag or not. Normal
+    // per-stage timings stay opt-in behind RUVNET_BRAIN_SESSION_START_TRACE so a healthy hook's
+    // stderr stays quiet by default.
+    if (extra) write(`SESSION_TRACE stage=${name} elapsed_ms=${ms}${extra}\n`);
+    else if (enabled) write(`SESSION_TRACE stage=${name} elapsed_ms=${ms}\n`);
+  };
+
+  /** Would running `name` now blow the shared wall-clock deadline? Checked against that stage's OWN
+   * declared budget (not the actual runtime, which is not known until after it runs) — the same
+   * "assume the worst case" posture the hooks.json timeout itself takes. */
+  const wouldExceedDeadline = (name) => {
+    const budget = budgets[name] ?? 0;
+    return (Date.now() - bodyStart) + budget > deadlineMs;
+  };
+
+  const stage = (name, fn) => {
+    if (wouldExceedDeadline(name)) {
+      record(name, 0, ' skipped=budget-exceeded');
+      return undefined;
+    }
+    const t0 = Date.now();
+    const result = fn();
+    record(name, Date.now() - t0);
+    return result;
+  };
+
+  const stageAsync = async (name, fn) => {
+    if (wouldExceedDeadline(name)) {
+      record(name, 0, ' skipped=budget-exceeded');
+      return undefined;
+    }
+    const t0 = Date.now();
+    const result = await fn();
+    record(name, Date.now() - t0);
+    return result;
+  };
+
+  return {
+    stage,
+    stageAsync,
+    table: () => stages.slice(),
+    totalMs: () => Date.now() - bodyStart,
+  };
+}

package/plugin/scripts/session-start-update-plane.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// session-start-update-plane.mjs — the Stable Spine seed dispatch and the update-check heartbeat.
+// Extracted 2026-09-11 out of session-start-core.mjs (unchanged behavior) to keep that file under
+// 500 lines. `announceVersion` was intentionally NOT migrated here: it was dead code (defined, never
+// called, never tested) and was deleted rather than relocated — moving unused code to a new module
+// would still be scope creep, just in a different file.
+import path from 'node:path';
+import { read, write, exists, json, firstVersion, dispatchDetached } from './session-start-fsutil.mjs';
+
+export const compareVersions = (a, b) => {
+  const left = String(a).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  const right = String(b).split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const x = left[i] ?? 0;
+    const y = right[i] ?? 0;
+    if (x === y) continue;
+    if (typeof x === 'number' && typeof y === 'number') return x - y;
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return 0;
+};
+
+export const stableSpine = ({ env, hookDir, stateDir, home, pluginVersion, emit, now }) => {
+  const activeFile = path.join(stateDir, 'active.json');
+  const stamp = path.join(stateDir, '.last-update-check');
+  let seedDispatched = false;
+  if (!exists(activeFile)) {
+    const seedStamp = path.join(stateDir, '.seed-attempted');
+    const last = Number(read(seedStamp).trim()) || 0;
+    const canSeed = exists(path.join(env.CLAUDE_PLUGIN_ROOT || '', 'scripts'))
+      || exists(path.join(home, '.claude', 'plugins', 'cache', 'ruvnet-brain'));
+    if (canSeed && now / 1000 - last > 300) {
+      write(seedStamp, `${Math.floor(now / 1000)}\n`);
+      seedDispatched = dispatchDetached(hookDir, 120, path.join(stateDir, '.seed.log'),
+        'node', [
+          path.join(hookDir, 'first-session-worker.mjs'),
+          path.join(hookDir, 'update-apply.mjs'),
+          path.join(hookDir, 'host-update.mjs'),
+          path.join(stateDir, '.last-version-check.log'),
+        ], env);
+      if (seedDispatched) write(stamp, `${Math.floor(now / 1000)}\n`);
+    }
+  } else {
+    const active = json(activeFile);
+    const shellBoundary = active?.shellChangedAtVersion;
+    const shellChangedBeforeHost = shellBoundary && pluginVersion
+      ? compareVersions(pluginVersion, shellBoundary) < 0
+      : false;
+    if ((active?.shellChanged || shellChangedBeforeHost) && pluginVersion && active.version && active.version !== pluginVersion) {
+      emit(`[RuvNet Brain — v${active.version} changed boot-level declarations (the rare case); this session booted v${pluginVersion}'s]`);
+      const host = env.RUVNET_HOOK_HOST || 'claude';
+      const convergence = json(path.join(stateDir, 'host-convergence.json'));
+      const ready = convergence?.desiredVersion === active.version
+        && convergence?.hosts?.[host]?.state === 'ready'
+        && convergence.hosts[host].version === active.version;
+      if (!ready) {
+        emit(`Tell the user ONE line: "🧠 RuvNet Brain v${active.version} 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."`);
+      } else if (host === 'codex') {
+        emit(`Tell the user ONE line: "🧠 RuvNet Brain v${active.version} 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 {
+        emit(`Tell the user ONE line: "🧠 RuvNet Brain v${active.version} 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."`);
+      }
+    }
+  }
+  return { seedDispatched, stamp };
+};
+
+export const heartbeat = ({ env, hookDir, stateDir, home, running, seedDispatched, stamp, emit, now }) => {
+  const last = Number(read(stamp).trim()) || 0;
+  const epoch = Math.floor(now / 1000);
+  if (seedDispatched || epoch <= 0 || epoch - last <= 900) return;
+  write(stamp, `${epoch}\n`);
+  const pref = read(path.join(stateDir, '.auto-update-pref')).trim();
+  const kbDir = path.join(home, '.cache', 'ruvnet-brain', 'kb');
+  if (pref === 'yes' && exists(path.join(kbDir, 'forge-update.mjs'))) {
+    const kbLog = path.join(stateDir, '.last-kb-check.log');
+    if (/\bBEHIND\b/.test(read(kbLog))) {
+      emit('[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]');
+    }
+    dispatchDetached(hookDir, 60, kbLog, process.execPath,
+      [path.join(kbDir, 'forge-update.mjs'), '--check'], env);
+  }
+  const versionLog = path.join(stateDir, '.last-version-check.log');
+  const remoteVersion = firstVersion(read(versionLog));
+  dispatchDetached(hookDir, 10, versionLog, process.execPath,
+    [path.join(hookDir, 'host-update.mjs'), '--check'], env);
+  if (!running || !remoteVersion || remoteVersion === running) return;
+  if (pref === 'yes' && exists(path.join(hookDir, 'host-update.mjs'))) {
+    dispatchDetached(hookDir, 600, path.join(stateDir, '.last-auto-update.log'),
+      process.execPath, [path.join(hookDir, 'host-update.mjs')], env);
+    emit(`[RuvNet Brain — v${remoteVersion} is downloading and will AUTO-APPLY via the Stable Spine (ADR-023); this session picks up the new behavior live]`);
+    emit('Tell the user ONE short line, near the top of your first response:');
+    emit(`  "🧠 RuvNet Brain v${remoteVersion} 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."`);
+    emit("Don't repeat this notice later in the same session.");
+    emit('');
+    return;
+  }
+  emit('[RuvNet Brain — update available, auto-update not enabled]');
+  emit('Tell the user this PLAINLY, near the top of your first response:');
+  emit(`  "🧠 RuvNet Brain found v${remoteVersion} (you're on v${running}). Run: npx ruvnet-brain@latest --update"`);
+  emit("  (Or say the word and I'll turn on auto-update so this never comes up again.)\"");
+  emit("Don't repeat this notice later in the same session.");
+  emit('');
+};

package/plugin/scripts/unprompted-runtime.mjs

@@ -48,6 +48,17 @@
 //               stdout — an opted-in refusal is never swallowed.
 //   alarm     → always delivered. Not gated by anything. Silence here = a broken install looking healthy.
 //
+// WHO ACTUALLY READS THE ADVISORY PATH — a precision this file's own wording keeps blurring, and the
+// blur causes a real authoring mistake. "User-facing bytes" is right about OWNERSHIP (these are the
+// only bytes that leave the hook) and wrong about AUDIENCE on the advisory path: `additionalContext`
+// is injected into the MODEL's context window, not printed to the user's terminal. So an advisory
+// `copy` that reads as finished user-facing prose produces a sentence the user never sees and a model
+// that may or may not paraphrase it. An advisory candidate should be written as ONE INSTRUCTION TO
+// THE MODEL, with any user-facing sentence quoted inside it (see advocacy-route.mjs for the shape).
+// The BLOCK path is different and unchanged: exit 2's stderr becomes the refusal the user is shown.
+// Consequence for measurement: a test at this boundary proves CANDIDATE DELIVERED. Whether the user
+// ever saw a sentence is the model's behaviour and is only observable in a real-host run.
+//
 // DELIVERY (the runtime writes the final envelope to the REAL streams, itself):
 //   advisory → exit 0, stdout = {"hookSpecificOutput":{"hookEventName":…, "additionalContext":…}}.
 //   block    → exit 2, reason on stderr, stdout byte-empty.
@@ -140,8 +151,18 @@ const BASH = resolveBash();
 const ANTICIPATE = { argv: [BASH, path.join(SCRIPTS_DIR, 'anticipate.sh')], feedStdin: true, channels: ['advocacy', 'promotion'] };
 const lesson = (subEvent) => ({ argv: [BASH, path.join(SCRIPTS_DIR, 'lesson-hooks.sh'), subEvent], feedStdin: true, channels: ['lesson'] });
 
+// THE RECOMMENDATION PRODUCER (advocacy-route.mjs). It answers a DIFFERENT question from anticipate:
+// anticipate asks "what is installed here and switched OFF?", the route asks "what does rUv already
+// ship that would materially help THIS ordinary request?" — the second is unreachable through the
+// first, because anticipate's SILENCE RULE 1 makes an 'absent' capability silent by design and
+// goal-match.mjs's GLOBAL_VETO rejects `customers`/`production`/`deploy` prompts outright.
+// It is bound to the advocacy channel ONLY: it can never emit a lesson block or an alarm.
+// process.execPath, not 'node' — the same reason resolveBash() exists: a PATH lookup that fails on
+// one host is a producer that is dead there and indistinguishable from "nothing to say".
+const ADVOCACY_ROUTE = { argv: [process.execPath, path.join(SCRIPTS_DIR, 'advocacy-route.mjs')], feedStdin: true, channels: ['advocacy'] };
+
 const BUILTIN_REGISTRY = {
-  'UserPromptSubmit': [ANTICIPATE, lesson('UserPromptSubmit')],
+  'UserPromptSubmit': [ANTICIPATE, ADVOCACY_ROUTE, lesson('UserPromptSubmit')],
   'PreToolUse-write': [lesson('PreToolUse-write')],
   'PreToolUse-bash':  [lesson('PreToolUse-bash')],
   'PreToolUse-push':  [lesson('PreToolUse-push')],
@@ -219,9 +240,18 @@ for (const p of producers) {
   if (remaining <= 0) break;                 // global budget spent → run no more producers
   let out = '';
   try {
+    // Build env for the spawned producer. advocacy-route.mjs needs RUVNET_ADVOCACY_ROUTE_BUDGET_MS
+    // to self-limit under concurrent load; pass it through if set by the test or caller.
+    const producerEnv = {
+      ...process.env,
+      RUVNET_EMIT_CANDIDATES: '1',
+    };
+    if (process.env.RUVNET_ADVOCACY_ROUTE_BUDGET_MS) {
+      producerEnv.RUVNET_ADVOCACY_ROUTE_BUDGET_MS = process.env.RUVNET_ADVOCACY_ROUTE_BUDGET_MS;
+    }
     const r = spawnSync(p.argv[0], p.argv.slice(1), {
       input: p.feedStdin ? payload : Buffer.alloc(0),
-      env: { ...process.env, RUVNET_EMIT_CANDIDATES: '1' },
+      env: producerEnv,
       timeout: remaining,
       maxBuffer: MAX_BUFFER,
     });