ruvnet-brain 4.3.21 → 4.3.26

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

@@ -3,346 +3,43 @@
 // latency budget before the shell body reached its first instruction—motivated moving every host
 // onto this dependency-free core. It runs from both the frozen plugin and a Stable Spine generation;
 // session-start.sh remains only a compatibility launcher for callers that still invoke that path.
+//
+// 2026-09-11 REWRITE (latency + scoping + banner-truth pass, two-reviewer-corrected):
+//   - Stage bodies moved into small sibling modules (session-start-{fsutil,health,signals,
+//     issue-alert,repo-identity,update-plane,hook-description,trace,budget}.mjs) so this file stays
+//     under 500 lines. `announceVersion` and `commandExists` were dead code (defined, never called,
+//     never tested anywhere) and were deleted rather than relocated.
+//   - Every stage now runs under session-start-trace.mjs's stage()/stageAsync(), budgeted by
+//     session-start-budget.mjs's STAGE_BUDGETS_MS (the derived-sum contract enforced by
+//     tests/unit/session-start-budget.test.mjs). A stage that would blow the shared deadline is
+//     SKIPPED with an always-written stderr note instead of risking the whole hook getting killed by
+//     its own hooks.json watchdog with zero output (the exact failure this pass started from).
+//   - The maintainer-only open-issue detail moved OUT of this hook entirely; SessionStart may print
+//     at most a one-line pointer (session-start-issue-alert.mjs), gated by BOTH the per-user
+//     entitlement file AND the current project's git remote being the entitled repo (fixed constant,
+//     session-start-repo-identity.mjs) — closing a real leak where the alert surfaced in unrelated
+//     projects.
+//   - LOCAL installation-integrity conditions (split plugin/bundle generation, retrieval down) are
+//     NOT maintainer-only: they are delivered to every user, worded for the user, through the same
+//     always-shown alarm mechanism as the existing HEALTH ALARM.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { restoreProgressionForSession } from './project-progression-session-start.mjs';
+import {
+  read, json, exists, mkdir, write, runNode,
+} from './session-start-fsutil.mjs';
+import { maintainerIssueEntitlement, surfaceIssuePointer } from './session-start-issue-alert.mjs';
+import { surfaceSignals } from './session-start-signals.mjs';
+import { brainState, health, mcpReadiness } from './session-start-health.mjs';
+import { stableSpine, heartbeat } from './session-start-update-plane.mjs';
+import { describeLifecycleHooks, readHookContracts } from './session-start-hook-description.mjs';
+import { createStageTracer } from './session-start-trace.mjs';
 
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const read = (file, fallback = '') => {
-  try { return fs.readFileSync(file, 'utf8'); } catch { return fallback; }
-};
-const json = (file, fallback = null) => {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
-};
-const exists = (file) => {
-  try { return fs.existsSync(file); } catch { return false; }
-};
-const mkdir = (dir) => {
-  try { fs.mkdirSync(dir, { recursive: true }); return true; } catch { return false; }
-};
-const write = (file, value) => {
-  try { mkdir(path.dirname(file)); fs.writeFileSync(file, String(value)); return true; } catch { return false; }
-};
-const mtimeMs = (file) => {
-  try { return fs.statSync(file).mtimeMs; } catch { return 0; }
-};
-const firstVersion = (text) => String(text).split(/\r?\n/).find((line) =>
-  /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(line.trim()))?.trim() || '';
-const commandExists = (name, env, platform) => {
-  const extensions = platform === 'win32'
-    ? String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
-    : [''];
-  for (const dir of String(env.PATH || '').split(path.delimiter).filter(Boolean)) {
-    for (const extension of extensions) {
-      if (exists(path.join(dir, `${name}${extension}`))) return true;
-      if (platform === 'win32' && exists(path.join(dir, `${name}${extension.toLowerCase()}`))) return true;
-    }
-  }
-  return false;
-};
-
-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; }
-};
-
-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;
-
-export const maintainerIssueEntitlement = (env, home, repo, platform = process.platform) => {
-  const file = env.RUVNET_BRAIN_MAINTAINER_ISSUES_FILE
-    || path.join(home, '.config', 'ruvnet-brain', 'maintainer-issues.json');
-  // Windows ACL ownership is not available through this dependency-free hot path. Fail closed
-  // instead of weakening an owner-only promise into "any local user who can write the file".
-  if (platform === 'win32') return false;
-  let stat;
-  try { stat = fs.lstatSync(file); } catch { return false; }
-  if (!stat.isFile() || stat.isSymbolicLink()) return false;
-  // This is maintainer-only operational data. Refuse group/world-readable opt-ins on POSIX so a
-  // shared machine cannot turn a private maintainer signal into a terminal banner for other users.
-  if ((stat.mode & 0o077) !== 0) return false;
-  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) return false;
-  const entitlement = json(file);
-  return entitlement?.enabled === true
-    && Array.isArray(entitlement.repos)
-    && entitlement.repos.includes(repo);
-};
-
-const surfaceIssues = (stateDir, emit, now, env, home, platform) => {
-  const status = json(path.join(stateDir, 'open-issues.json'));
-  const observedAt = Date.parse(status?.at || '');
-  if (!Number.isFinite(observedAt) || observedAt > now + 5 * 60_000 || now - observedAt > 6 * 3600_000) return;
-  if (!maintainerIssueEntitlement(env, home, status.repo, platform)) return;
-  const open = Array.isArray(status.issues) ? status.issues : [];
-  if (!open.length) return;
-  const breaches = open.filter((issue) => issue.breach).sort((a, b) => b.ageHours - a.ageHours);
-  const selected = breaches.length ? breaches : [...open].sort((a, b) => b.ageHours - a.ageHours);
-  const top = selected.slice(0, 4).map((issue) =>
-    breaches.length
-      ? `#${issue.number} (${issue.ageHours}h) ${String(issue.title || '').slice(0, 64)}`
-      : `#${issue.number} (${issue.ageHours}h)`).join(' · ');
-  const more = selected.length > 4 ? ` · +${selected.length - 4} more` : '';
-  if (breaches.length) {
-    emit('[RuvNet Brain — OPEN ISSUES need attention (surface this to the maintainer, once, near the top)]');
-    emit(`${breaches.length} open issue(s) past SLA on ${status.repo}: ${top}${more}; open issues are visible to the maintainer`);
-    emit('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).');
-    return;
-  }
-  emit("[RuvNet Brain — open issues on the maintainer's repo (mention once, calmly, near the top)]");
-  emit(`${open.length} open issue(s) on ${status.repo}, none past SLA: ${top}${more}; open issues are visible to the maintainer`);
-  emit('Within SLA, but the maintainer should know they exist. One line is enough; offer to look.');
-};
-
-const surfaceSignals = ({ env, cwd, stateDir, hookDir, emit, now }) => {
-  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) {
-    runNode(poller, [], { cwd, env, stdio: 'ignore', timeout: 3500 });
-  }
-  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));
-};
-
-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 };
-};
-
-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 };
-};
-
-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 };
-};
-
-const announceVersion = ({ running, off, stateDir, consoleInvoke, emit }) => {
-  if (off || !running) return;
-  const announced = path.join(stateDir, '.last-announced-version');
-  const milestoneFile = path.join(stateDir, '.last-major-milestone');
-  const [base] = running.split('-');
-  const parts = base.split('.').map(Number);
-  let milestone = '';
-  if (parts.every(Number.isFinite)) {
-    const [major = 0, minor = 0, patch = 0] = parts;
-    if (major >= 4) milestone = '4.x';
-    else if (major * 1_000_000 + minor * 1000 + patch >= 3_009_071) milestone = '4.0-line';
-  }
-  let milestoneShown = false;
-  if (milestone && read(milestoneFile).trim() !== milestone) {
-    milestoneShown = true;
-    emit(`[RuvNet Brain — MAJOR-LINE welcome (${milestone}), show ONCE near the top of your first response]`);
-    emit("They upgraded INTO the big release and will NOT have seen the web explainer. Warmly, a few sentences, adapt — don't recite:");
-    emit(milestone === '4.x'
-      ? `  1. They're on RuvNet-Brain ${running}, a major version — the release where the brain got honest, legible, fast and self-measuring.`
-      : `  1. The 4.0-LINE enhancements have landed (they're on v${running}). 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'.`);
-    emit(`  2. Two or three things they can DO now: the Console on ${consoleInvoke} (their whole stack, one live page); every number measured from their machine, never projected; it learns across their projects.`);
-    emit(`  3. OFFER to open the Console now — on yes, invoke ${consoleInvoke}. Point at the native what's-new workflow for the full highlights.`);
-    emit("Never claim 'proven better' or 'fully proactive' — the self-measurement is new and still filling. Once only.");
-    write(milestoneFile, `${milestone}\n`);
-  }
-  if (read(announced).trim() === running) return;
-  const whatsNew = running.startsWith('3.2.') || running.startsWith('3.1.')
-    ? `opens with the Console — ${consoleInvoke} 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.`
-    : running.startsWith('3.0.') ? '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.'
-      : running.startsWith('2.4.') ? '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.'
-        : running.startsWith('2.3.') ? '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\.[012]/.test(running) ? '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.)'
-            : '';
-  if (whatsNew && !milestoneShown) {
-    emit(`[RuvNet Brain — new in v${running}]`);
-    emit(`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} ${whatsNew}`);
-  }
-  write(announced, `${running}\n`);
-};
-
-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;
-};
-
-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 };
-};
-
-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 remote = firstVersion(read(versionLog));
-  dispatchDetached(hookDir, 10, versionLog, process.execPath,
-    [path.join(hookDir, 'host-update.mjs'), '--check'], env);
-  if (!running || !remote || remote === 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${remote} 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${remote} 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${remote} (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('');
-};
+// Re-exported for callers/tests that import the entitlement check directly from this file's own
+// long-standing public surface (tests/unit/session-start-core-parity.test.mjs).
+export { maintainerIssueEntitlement };
 
 const meter = ({ env, cwd, stateDir, output }) => {
   if (env.RUVNET_BRAIN_METER === '0') return;
@@ -380,6 +77,7 @@ export async function runSessionStart({
     const s = String(line);
     return s.startsWith('🚨')
       || s.startsWith('[RuvNet Brain — HEALTH ALARM')
+      || s.startsWith('[RuvNet Brain — INSTALL ALARM')
       || s.startsWith('[RuvNet Brain — NIGHTLY FAILED')
       || s.startsWith('[RuvNet Brain — OPEN ISSUES')
       || /\bopen issue\(s\)/i.test(s)
@@ -403,8 +101,33 @@ export async function runSessionStart({
       || s.startsWith('[RuvNet Brain — PROJECT CONTINUITY RESTORED]')
       || s.startsWith('[RuvNet Brain — MAINTAINER ONLY:');
   };
+  // An alarm's HEADER line always matches isSafeStatus on its own dedicated prefix (above); its
+  // explanatory BODY lines do not, and without this they were silently dropped — a real gap this
+  // pass closes, because correction #4 requires local-integrity alarms to actually reach the user,
+  // not just their header. A header opens a continuation budget sized to EXACTLY that alarm's own
+  // body-line count (never a shared generic number): a generic budget was tried first and found,
+  // by direct reproduction, to LEAK — unused credits from a short alarm silently let an unrelated
+  // LATER unsafe line (a one-time setup prompt) through on whichever run happened to have fewer
+  // lines emitted in between, corrupting a completely unrelated byte-count test. Exact-sizing means
+  // a block can only ever cover its own known body, never bleed into whatever comes after it.
+  const ALARM_BODY_LINES = [
+    { prefix: '🚨', lines: 3 }, // HEALTH ALARM's own 3 body lines (the only bare 🚨 alarm today)
+    { prefix: '[RuvNet Brain — HEALTH ALARM', lines: 3 },
+    { prefix: '[RuvNet Brain — INSTALL ALARM', lines: 1 },
+    { prefix: '[RuvNet Brain — NIGHTLY FAILED', lines: 5 },
+  ];
+  const alarmBodyLines = (s) => {
+    if (s.startsWith('[RuvNet Brain v') && s.includes('RETRIEVAL DOWN')) return 1;
+    return ALARM_BODY_LINES.find((a) => s.startsWith(a.prefix))?.lines || 0;
+  };
+  let alarmContinuationBudget = 0;
   const emit = (line = '') => {
-    if (env.RUVNET_VERBOSE_HOOKS === '1' || isSafeStatus(line)) lines.push(String(line));
+    const s = String(line);
+    const safe = env.RUVNET_VERBOSE_HOOKS === '1' || isSafeStatus(s) || alarmContinuationBudget > 0;
+    if (safe) lines.push(s);
+    const bodyLines = alarmBodyLines(s);
+    if (bodyLines > 0) alarmContinuationBudget = bodyLines;
+    else if (alarmContinuationBudget > 0) alarmContinuationBudget -= 1;
   };
   const home = env.HOME || env.USERPROFILE || os.homedir();
   const stateDir = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain');
@@ -427,6 +150,7 @@ export async function runSessionStart({
     }
   };
 
+  const restoreStart = Date.now();
   try {
     const continuity = await restoreContinuity({ env, cwd });
     if (continuity?.context) emit(continuity.context);
@@ -434,150 +158,190 @@ export async function runSessionStart({
     emit('[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]');
     emit('The SessionStart restore boundary failed unexpectedly. Do not claim project state was restored; verify the canonical store before relying on remembered state.');
   }
+  // Opt-in, matching the pre-existing `trace()` convention below: several other tests assert
+  // SessionStart's stderr is EMPTY in the clean case (hook-battery.test.mjs, hook-hardening.test.mjs
+  // — a real contract, not incidental), so this must never write unconditionally. `restore` shares
+  // this hook's wall-clock budget with everything below even though its code belongs to the
+  // continuity lane — see session-start-budget.mjs — and is reported here under EITHER trace flag.
+  if (env.RUVNET_SESSION_TRACE === '1' || env.RUVNET_BRAIN_SESSION_START_TRACE === '1') {
+    stderr.write(`SESSION_TRACE stage=restore elapsed_ms=${Date.now() - restoreStart}\n`);
+  }
+
+  const tracer = createStageTracer({
+    enabled: env.RUVNET_BRAIN_SESSION_START_TRACE === '1',
+    write: (chunk) => stderr.write(chunk),
+  });
+  let bannerEmitted = false;
 
   try {
     trace('body-start');
-    const settingsFile = env.RUVNET_SETTINGS_FILE
-      || path.join(home, '.config', 'ruvnet-brain', 'settings.json');
-    if (/"newProjectDefaults"\s*:\s*true(?:\s*[,}]|$)/.test(read(settingsFile))) {
-      runNode(path.join(hookDir, 'runtime-preferences.mjs'), ['--seed-project'], {
-        cwd, env, stdio: 'ignore', timeout: 2000,
-      });
-    }
+    tracer.stage('misc', () => {
+      const settingsFile = env.RUVNET_SETTINGS_FILE
+        || path.join(home, '.config', 'ruvnet-brain', 'settings.json');
+      if (/"newProjectDefaults"\s*:\s*true(?:\s*[,}]|$)/.test(read(settingsFile))) {
+        runNode(path.join(hookDir, 'runtime-preferences.mjs'), ['--seed-project'], {
+          cwd, env, stdio: 'ignore', timeout: 2000,
+        });
+      }
 
-    const nightly = path.join(env.CLAUDE_PROJECT_DIR || cwd, '.ruvnet-brain', 'nightly-failure.json');
-    if (exists(nightly)) {
-      emit('[RuvNet Brain — NIGHTLY FAILED, self-heal retry also failed, this is now yours to fix]');
-      emit('Before anything else this session: the ruvnet-brain nightly publish failed twice last run (immediate');
-      emit(`attempt + a 3-minute retry) and could not self-heal. Read ${nightly} for the exact tag/error,`);
-      emit('then logs/nightly.log in that repo for full context. Diagnose and fix it now — do not wait to be');
-      emit('asked, this is a standing directive. Once genuinely fixed and verified (a real release tag advances),');
-      emit('delete the marker file.');
-    }
+      const nightly = path.join(env.CLAUDE_PROJECT_DIR || cwd, '.ruvnet-brain', 'nightly-failure.json');
+      if (exists(nightly)) {
+        emit('[RuvNet Brain — NIGHTLY FAILED, self-heal retry also failed, this is now yours to fix]');
+        emit('Before anything else this session: the ruvnet-brain nightly publish failed twice last run (immediate');
+        emit(`attempt + a 3-minute retry) and could not self-heal. Read ${nightly} for the exact tag/error,`);
+        emit('then logs/nightly.log in that repo for full context. Diagnose and fix it now — do not wait to be');
+        emit('asked, this is a standing directive. Once genuinely fixed and verified (a real release tag advances),');
+        emit('delete the marker file.');
+      }
+    });
 
-    const state = health(home, brain.off);
-    if (state.problem) {
-      emit('🚨 [RuvNet Brain — HEALTH ALARM: THE BRAIN IS DOWN — SURFACE THIS FIRST] 🚨');
-      emit(`Health check failed: ${state.problem}`);
-      emit('Open your VERY FIRST line with a loud plain alert naming that reason and that fix, and offer to run');
-      emit('it. Never answer rUv-stack questions from memory while it is down. Verify after: npx ruvnet-brain --doctor');
-    }
+    const state = tracer.stage('misc', () => {
+      const result = health(home, brain.off);
+      if (result.problem) {
+        emit('🚨 [RuvNet Brain — HEALTH ALARM: THE BRAIN IS DOWN — SURFACE THIS FIRST] 🚨');
+        emit(`Health check failed: ${result.problem}`);
+        emit('Open your VERY FIRST line with a loud plain alert naming that reason and that fix, and offer to run');
+        emit('it. Never answer rUv-stack questions from memory while it is down. Verify after: npx ruvnet-brain --doctor');
+      }
+      return result;
+    }) || { problem: '', absentByChoice: false };
 
-    const consoleOffered = path.join(stateDir, '.console-offered');
-    const firstSession = !brain.off && !exists(consoleOffered);
-    if (firstSession) emit('[RuvNet Brain — first session initialized]');
-    if (!brain.off && !exists(consoleOffered)) {
-      write(consoleOffered, '');
-      emit('[RuvNet Brain — FIRST LOAD: offer the Console once]');
-      emit(`Offer ONCE: "Want to see your whole RuvNet stack on one page?" — installed parts, learned project knowledge and reversible fixes, read-only until clicked; later it's ${consoleInvoke}. On yes invoke ${consoleInvoke}; on no, don't re-offer.`);
-    }
+    tracer.stage('misc', () => {
+      const consoleOffered = path.join(stateDir, '.console-offered');
+      const firstSession = !brain.off && !exists(consoleOffered);
+      if (firstSession) emit('[RuvNet Brain — first session initialized]');
+      if (!brain.off && !exists(consoleOffered)) {
+        write(consoleOffered, '');
+        emit('[RuvNet Brain — FIRST LOAD: offer the Console once]');
+        emit(`Offer ONCE: "Want to see your whole RuvNet stack on one page?" — installed parts, learned project knowledge and reversible fixes, read-only until clicked; later it's ${consoleInvoke}. On yes invoke ${consoleInvoke}; on no, don't re-offer.`);
+      }
+    });
 
-    surfaceIssues(stateDir, emit, now, env, home, platform);
-    surfaceSignals({ env, cwd, stateDir, hookDir, emit, now });
+    tracer.stage('issue-pointer', () => {
+      surfaceIssuePointer({ stateDir, emit, now, env, home, platform, cwd });
+    });
+    tracer.stage('signal-surface', () => {
+      surfaceSignals({ env, cwd, stateDir, hookDir, emit, now });
+    });
 
-    const routerProfile = path.join(home, '.claude', 'model-router', 'profile.json');
-    const routerNudge = path.join(stateDir, '.router-profile-nudged');
-    if (!brain.off && !exists(routerProfile) && !exists(routerNudge)) {
-      write(routerNudge, '');
-      emit('[RuvNet Brain — MetaHarness routing is available but not set up for THIS user yet]');
-      emit('Offer ONCE: route each task to the cheapest capable model, using THEIR subscriptions ($0) before billed models. Set it up?');
-      emit('On yes ask only (1) Claude sub, Pro or Max? (2) Codex CLI on a ChatGPT plan? then:');
-      const routerSetup = path.join(home, '.claude', 'model-router', 'bin', 'model-router-setup.mjs');
-      emit(exists(routerSetup)
-        ? `  in ${path.dirname(routerSetup)}: 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.`
-        : "  the router isn't installed here — run: npx github:stuinfla/ruvnet-brain (it sets it up, asks these questions and shows the path)");
-      emit('On no or silence: drop it, never re-offer.');
-    }
+    tracer.stage('router-nudge', () => {
+      const routerProfile = path.join(home, '.claude', 'model-router', 'profile.json');
+      const routerNudge = path.join(stateDir, '.router-profile-nudged');
+      if (!brain.off && !exists(routerProfile) && !exists(routerNudge)) {
+        write(routerNudge, '');
+        emit('[RuvNet Brain — MetaHarness routing is available but not set up for THIS user yet]');
+        emit('Offer ONCE: route each task to the cheapest capable model, using THEIR subscriptions ($0) before billed models. Set it up?');
+        emit('On yes ask only (1) Claude sub, Pro or Max? (2) Codex CLI on a ChatGPT plan? then:');
+        const routerSetup = path.join(home, '.claude', 'model-router', 'bin', 'model-router-setup.mjs');
+        emit(exists(routerSetup)
+          ? `  in ${path.dirname(routerSetup)}: 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.`
+          : "  the router isn't installed here — run: npx github:stuinfla/ruvnet-brain (it sets it up, asks these questions and shows the path)");
+        emit('On no or silence: drop it, never re-offer.');
+      }
+    });
 
-    // Version announcements belong to the explicit update/what's-new flows, not SessionStart.
-    // Keeping this hook context-only prevents host sessions from receiving response scripts.
-    const autoPref = path.join(stateDir, '.auto-update-pref');
-    if (!exists(autoPref)) {
-      emit('[RuvNet Brain — one-time setup question]');
-      emit('Ask ONCE: should the brain auto-update in the background? (recommended; reversible). Then run ONE via Bash:');
-      emit(`  mkdir -p '${stateDir}' && echo yes > '${autoPref}'   (or echo no)`);
-      emit('No answer: ask next session, never twice.');
+    tracer.stage('misc', () => {
+      const autoPref = path.join(stateDir, '.auto-update-pref');
+      if (!exists(autoPref)) {
+        emit('[RuvNet Brain — one-time setup question]');
+        emit('Ask ONCE: should the brain auto-update in the background? (recommended; reversible). Then run ONE via Bash:');
+        emit(`  mkdir -p '${stateDir}' && echo yes > '${autoPref}'   (or echo no)`);
+        emit('No answer: ask next session, never twice.');
+      }
+    });
+    const spine = tracer.stage('stable-spine', () => stableSpine({
+      env, hookDir, stateDir, home, pluginVersion: running, emit, now,
+    })) || { seedDispatched: false, stamp: path.join(stateDir, '.last-update-check') };
+    if (runHeartbeat) {
+      tracer.stage('heartbeat', () => heartbeat({
+        env, hookDir, stateDir, home, running, ...spine, emit, now,
+      }));
     }
-    const spine = stableSpine({ env, hookDir, stateDir, home, pluginVersion: running, emit, now });
-    if (runHeartbeat) heartbeat({ env, hookDir, stateDir, home, running, ...spine, emit, now });
 
-    const star = path.join(stateDir, '.star-ask-shown');
-    if (!brain.off && exists(path.join(stateDir, '.grounded-once')) && !exists(star) && write(star, '')) {
-      emit('[RuvNet Brain — one-time note. This will NEVER be shown again on this machine.]');
-      emit('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:');
-      emit('  "Finding this useful? Star github.com/stuinfla/ruvnet-brain or leave feedback — it keeps the nightly updates coming."');
-    }
+    tracer.stage('misc', () => {
+      const star = path.join(stateDir, '.star-ask-shown');
+      if (!brain.off && exists(path.join(stateDir, '.grounded-once')) && !exists(star) && write(star, '')) {
+        emit('[RuvNet Brain — one-time note. This will NEVER be shown again on this machine.]');
+        emit('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:');
+        emit('  "Finding this useful? Star github.com/stuinfla/ruvnet-brain or leave feedback — it keeps the nightly updates coming."');
+      }
+    });
 
-    const bannerVersion = effectiveVersion || 'unknown';
-    if (pluginRoot.startsWith(path.join(home, '.claude', 'plugins') + path.sep)) {
-      if (running) write(path.join(stateDir, '.running-version'), `${running}\n`);
-    } else if (running) {
-      write(path.join(stateDir, '.dev-version'), `${running}\n`);
-    }
-    const source = json(path.join(home, '.cache', 'ruvnet-brain', 'kb', 'SOURCE.json'), {});
-    const kbVersion = typeof source?.releaseTag === 'string' ? source.releaseTag : '';
-    const readiness = mcpReadiness(env, home);
+    tracer.stage('ascii-drift', () => {
+      const asciiDrift = path.join(env.CLAUDE_PROJECT_DIR || cwd, 'scripts', 'ascii-drift.mjs');
+      if (!brain.off && exists(asciiDrift)) {
+        const result = runNode(asciiDrift, ['--quiet'], { cwd, env, stdio: 'pipe', timeout: 1000 });
+        const text = String(result?.stdout || '').replace(/\r\n/g, '\n').replace(/\n$/, '');
+        if (text) for (const line of text.split('\n')) emit(line);
+      }
+    });
 
-    const grounding = json(path.join(stateDir, 'install-state.json'));
-    const asciiDrift = path.join(env.CLAUDE_PROJECT_DIR || cwd, 'scripts', 'ascii-drift.mjs');
-    if (!brain.off && exists(asciiDrift)) {
-      const result = runNode(asciiDrift, ['--quiet'], {
-        cwd, env, stdio: 'pipe', timeout: 1000,
-      });
-      const text = String(result?.stdout || '').replace(/\r\n/g, '\n').replace(/\n$/, '');
-      if (text) for (const line of text.split('\n')) emit(line);
-    }
-    if (grounding?.grounding && grounding.grounding !== 'proven') {
-      const when = grounding.at ? new Date(grounding.at).toISOString().slice(0, 16).replace('T', ' ') : 'an earlier run';
-      emit('[RuvNet Brain — grounding not yet PROVEN on this machine (mention once, calmly, near the top)]');
-      emit(`The last check (${when} (${grounding.reason || 'no reason recorded'})) 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.`);
-    }
+    tracer.stage('banner', () => {
+      const bannerVersion = effectiveVersion || 'unknown';
+      if (pluginRoot.startsWith(path.join(home, '.claude', 'plugins') + path.sep)) {
+        if (running) write(path.join(stateDir, '.running-version'), `${running}\n`);
+      } else if (running) {
+        write(path.join(stateDir, '.dev-version'), `${running}\n`);
+      }
+      const source = json(path.join(home, '.cache', 'ruvnet-brain', 'kb', 'SOURCE.json'), {});
+      const kbVersion = typeof source?.releaseTag === 'string' ? source.releaseTag : '';
+      const readiness = mcpReadiness(env, home);
+
+      const grounding = json(path.join(stateDir, 'install-state.json'));
+      if (grounding?.grounding && grounding.grounding !== 'proven') {
+        const when = grounding.at ? new Date(grounding.at).toISOString().slice(0, 16).replace('T', ' ') : 'an earlier run';
+        emit('[RuvNet Brain — grounding not yet PROVEN on this machine (mention once, calmly, near the top)]');
+        emit(`The last check (${when} (${grounding.reason || 'no reason recorded'})) 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.`);
+      }
+
+      if (brain.off) {
+        const absent = state.absentByChoice ? '; no knowledge bundle on this machine — disabled by choice, not broken' : '';
+        emit(`[RuvNet Brain — brain OFF by your setting${brain.since ? ` (since ${brain.since})` : ''}${absent}. Do not mention it unless the user asks.]`);
+        return;
+      }
 
-    if (brain.off) {
-      const absent = state.absentByChoice ? '; no knowledge bundle on this machine — disabled by choice, not broken' : '';
-      emit(`[RuvNet Brain — brain OFF by your setting${brain.since ? ` (since ${brain.since})` : ''}${absent}. Do not mention it unless the user asks.]`);
-    } else {
       if (state.problem) {
         emit(`[RuvNet Brain v${bannerVersion} — active this session, RETRIEVAL DOWN]`);
         emit(`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${bannerVersion}) — but its search is down right now."`);
+        bannerEmitted = true;
+        return;
+      }
+
+      // ONE VERSION, CUSTOMER-FACING (issue #77, restated from the customer's side). The plugin
+      // version and the knowledge bundle's tag are two internal artefacts of ONE product; only the
+      // plugin version is shown. A version SPLIT is a LOCAL INSTALLATION INTEGRITY problem that
+      // affects every user's search quality, not maintainer trivia — per the 2026-09-11 reviewer
+      // correction it is delivered to everyone, worded for the user, through the same always-shown
+      // alarm mechanism as HEALTH ALARM above (never gated by maintainerIssueEntitlement).
+      emit(`[RuvNet Brain v${bannerVersion} — active this session${updated ? ` · updated ${updated}` : ''}]`);
+      bannerEmitted = true;
+      const bundleTag = String(kbVersion).replace(/^v/, '');
+      if (bundleTag && bannerVersion !== 'unknown' && bundleTag !== bannerVersion) {
+        emit('🚨 [RuvNet Brain — INSTALL ALARM: plugin and knowledge bundle are out of sync] 🚨');
+        emit(`Your plugin is v${bannerVersion} but the knowledge bundle on this machine is v${bundleTag} — they are meant to ship together, so search results may not match this plugin's behavior yet. Fix: npx ruvnet-brain@latest --update (or reinstall: npx github:stuinfla/ruvnet-brain --force).`);
+      }
+
+      const hookContracts = readHookContracts(path.join(pluginRoot, 'hooks', 'hook-contracts.json'));
+      const lifecycleLine = describeLifecycleHooks(hookContracts);
+      if (readiness.state === 'ready') {
+        emit(`USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is ready and live. ${lifecycleLine}`);
+      } else if (readiness.state === 'degraded') {
+        const receipt = readiness.receipt || {};
+        emit(`USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is registered but degraded (${receipt.phase || 'startup'}: ${receipt.error || 'readiness failed'}). ${lifecycleLine}`);
       } else {
-        // ONE VERSION, CUSTOMER-FACING (issue #77, restated from the customer's side).
-        //
-        // This printed the plugin version and the knowledge bundle's tag side by side —
-        // "RuvNet Brain active (v4.0.8, brain v4.0.7)". Those are two internal artefacts of ONE
-        // product. Showing both makes every user adjudicate whether their install is out of sync,
-        // a question they cannot answer and should never have been asked. Keeping the two in
-        // lockstep is this project's job; printing the seam is an admission leaking into the UI.
-        //
-        // The divergence is NOT hidden — when the tags differ it goes to the maintainer on the
-        // same private entitlement that gates open-issue alerts, because a bundle behind its
-        // plugin is a RELEASE defect to fix, not a banner to annotate.
-        emit(`[RuvNet Brain v${bannerVersion} — active this session${updated ? ` · updated ${updated}` : ''}]`);
-        const bundleTag = String(kbVersion).replace(/^v/, '');
-        if (bundleTag && bannerVersion !== 'unknown' && bundleTag !== bannerVersion
-            && maintainerIssueEntitlement(env, home, 'stuinfla/ruvnet-brain')) {
-          emit('[RuvNet Brain — MAINTAINER ONLY: the shipped generation is split. Do NOT surface this to the user.]');
-          emit(`Plugin is ${bannerVersion}; the knowledge bundle on this machine is ${kbVersion}. Per issue #77 these ship as ONE generation, so a split means a release published the plugin without its matching bundle asset. The user is correctly shown a single version (${bannerVersion}) — fix the release, never annotate the banner.`);
-        }
-        if (readiness.state === 'ready') {
-          emit('USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is ready and live; the grounding hooks are active.');
-        } else if (readiness.state === 'degraded') {
-          const receipt = readiness.receipt || {};
-          emit(`USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is registered but degraded (${receipt.phase || 'startup'}: ${receipt.error || 'readiness failed'}); the grounding hooks remain active.`);
-        } else {
-          emit('USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is registered; live readiness is not yet proven. The grounding hooks are active.');
-        }
+        emit(`USER-LEVEL: one brain ON DISK (~/.cache/ruvnet-brain/kb) shared by every project and window here — nothing to reinstall per project (each window still runs its own worker process, which now exits when idle). search_ruvnet is registered; live readiness is not yet proven. ${lifecycleLine}`);
       }
-    }
+    });
   } catch (error) {
     if (env.RUVNET_SESSION_TRACE === '1') stderr.write(`SESSION_TRACE native-fail-open ${error?.message || error}\n`);
   }
 
-  if (env.RUVNET_VERBOSE_HOOKS !== '1' && !brain.off) {
+  // ONE banner line, always — the fallback that keeps SessionStart fail-open even if the rich body
+  // above threw before reaching its own banner stage. No longer duplicated (was printed twice, plus
+  // a bare "[RuvNet Brain active]" a third time — three lines from one fact) once the rich path
+  // already emitted its own banner.
+  if (env.RUVNET_VERBOSE_HOOKS !== '1' && !brain.off && !bannerEmitted) {
     lines.push(`[RuvNet Brain v${running || 'unknown'} — active this session]`);
-    // Keep the legacy plain status token for host integrations that key off it; it carries no
-    // instruction and does not introduce a second version or bundle identity.
-    lines.push('[RuvNet Brain active]');
   }
   const output = lines.length ? `${lines.join('\n')}\n` : '';
   meter({ env, cwd, stateDir, output });
@@ -586,8 +350,21 @@ export async function runSessionStart({
   return { ok: true, outputBytes: Buffer.byteLength(output, 'utf8'), platform };
 }
 
-const direct = process.argv[1]
-  && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
+// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
+// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
+// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
+// from "ran, found nothing". Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
+function isDirectInvocation() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+const direct = isDirectInvocation();
 if (direct) {
   runSessionStart().catch((error) => {
     if (process.env.RUVNET_SESSION_TRACE === '1') {