ruvnet-brain 4.0.2 → 4.0.5

package/scripts/onboarding-console.mjs

@@ -27,7 +27,7 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync, execFileSync, spawn } from 'node:child_process';
 
 import { auditModel, installedVersion } from './stack-sync.mjs';
-import { findStores, diagnose } from './memory-doctor.mjs';
+import { candidateRoots, findStores, diagnose } from './memory-doctor.mjs';
 import { buildStackRecommendations, buildWiringRecommendations, summarizeWiring, scoreMemoryHealth, buildHealthRecommendations, buildCapabilityRecommendations } from './console-engine.mjs';
 import { planFor } from './remedy-registry.mjs';
 import { auditAll as capabilityAuditAll } from './capability-registry.mjs';
@@ -69,16 +69,230 @@ import { applyNightlyChoice, nightlyStatus } from './nightly-controller.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO = path.dirname(__dirname);
 const CONSOLE_DIR = path.join(REPO, 'console');
-const HOME = os.homedir();
-const NPM_PREFIX = path.join(HOME, '.npm-global');
-const CONFIG_DIR = path.join(HOME, '.claude/ruvnet-brain');
+const SYSTEM_HOME = os.homedir();
+
+/**
+ * The console's explicit root boundary. It scopes only console-owned configuration, state, cache,
+ * and discovery; global binaries, account credentials, and external tool state retain SYSTEM_HOME.
+ */
+export function consoleRootFromEnvironment(env = process.env, systemHome = SYSTEM_HOME) {
+  const configured = env.RUVNET_CONSOLE_ROOT;
+  if (!configured) return systemHome;
+  if (typeof configured !== 'string' || !path.isAbsolute(configured)) {
+    throw new Error('RUVNET_CONSOLE_ROOT must be an absolute path');
+  }
+  return path.resolve(configured);
+}
+
+// A test or an embedded caller can isolate the console's owned files and discovery roots without
+// redefining the operating-system home directory. Normal launches retain the OS home exactly.
+const CONSOLE_ROOT = consoleRootFromEnvironment();
+const NPM_PREFIX = path.join(SYSTEM_HOME, '.npm-global');
+const CONFIG_DIR = path.join(CONSOLE_ROOT, '.claude/ruvnet-brain');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
-const UNDO_JOURNAL = path.join(HOME, '.cache/ruvnet-brain/console-undo.jsonl');
+const UNDO_JOURNAL = path.join(CONSOLE_ROOT, '.cache/ruvnet-brain/console-undo.jsonl');
 const INSTALLED_KB = process.env.RUVNET_BRAIN_KB
-  || path.join(HOME, '.cache', 'ruvnet-brain', 'kb');
+  || path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'kb');
 const COMPLETE_BRAIN_SOURCE = process.env.RUVNET_BRAIN_COMPLETE_SOURCE
   || path.join(REPO, 'dist', 'ruvnet-brain');
 const TOKEN = crypto.randomBytes(24).toString('hex');
+const RUNTIME_RECEIPT_DIR = path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'console-instances');
+const RUNTIME_PRODUCT = 'ruvnet-brain-console';
+const RUNTIME_SCHEMA = 1;
+const RUNTIME_API_CONTRACT = 1;
+const RUNTIME_SCRIPT = fs.realpathSync(fileURLToPath(import.meta.url));
+const RUNTIME_SOURCE_SHA256 = crypto.createHash('sha256').update(fs.readFileSync(RUNTIME_SCRIPT)).digest('hex');
+
+function consoleCandidateRoots() {
+  return candidateRoots({ home: CONSOLE_ROOT, configPath: CONFIG_PATH });
+}
+
+function canonicalScope(cwd = process.cwd()) {
+  try { return fs.realpathSync(cwd); } catch { return path.resolve(cwd); }
+}
+
+function runtimeReceiptPath(cwd = process.cwd()) {
+  const scope = canonicalScope(cwd);
+  const scopeId = crypto.createHash('sha256').update(scope).digest('hex').slice(0, 24);
+  return path.join(RUNTIME_RECEIPT_DIR, `${scopeId}.json`);
+}
+
+function runtimeIdentity({ port, cwd = process.cwd(), pid = process.pid, startedAt = new Date().toISOString() }) {
+  return {
+    product: RUNTIME_PRODUCT,
+    schema: RUNTIME_SCHEMA,
+    apiContract: RUNTIME_API_CONTRACT,
+    pid,
+    port,
+    startedAt,
+    scope: canonicalScope(cwd),
+    scriptRealpath: RUNTIME_SCRIPT,
+    runtimeVersion: brainVersionOnDisk(),
+    sourceSha256: RUNTIME_SOURCE_SHA256,
+  };
+}
+
+function validRuntimeReceipt(receipt, file) {
+  if (!receipt || typeof receipt !== 'object') return false;
+  if (process.platform !== 'win32') {
+    try { if ((fs.statSync(file).mode & 0o777) !== 0o600) return false; } catch { return false; }
+  }
+  return receipt.product === RUNTIME_PRODUCT
+    && receipt.schema === RUNTIME_SCHEMA
+    && receipt.apiContract === RUNTIME_API_CONTRACT
+    && Number.isInteger(receipt.pid) && receipt.pid > 0
+    && Number.isInteger(receipt.port) && receipt.port > 0 && receipt.port <= 65535
+    && typeof receipt.startedAt === 'string'
+    && typeof receipt.scope === 'string'
+    && typeof receipt.scriptRealpath === 'string'
+    && typeof receipt.runtimeVersion === 'string'
+    && /^[a-f0-9]{64}$/.test(receipt.sourceSha256 || '')
+    && /^[a-f0-9]{48}$/.test(receipt.controlToken || '');
+}
+
+function publicRuntimeIdentity(receipt) {
+  const { controlToken: _secret, ...identity } = receipt;
+  return identity;
+}
+
+function writeRuntimeReceipt(receipt, file = runtimeReceiptPath(receipt.scope)) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') fs.chmodSync(path.dirname(file), 0o700);
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600, flag: 'wx' });
+    if (process.platform !== 'win32') fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+  } finally {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch { /* best effort */ }
+  }
+  return file;
+}
+
+function removeOwnedRuntimeReceipt(file, controlToken) {
+  const current = readJSON(file);
+  if (!current || current.controlToken !== controlToken) return false;
+  try { fs.unlinkSync(file); return true; } catch { return false; }
+}
+
+function sameRuntimeIdentity(left, right) {
+  return ['product', 'schema', 'apiContract', 'pid', 'port', 'startedAt', 'scope',
+    'scriptRealpath', 'runtimeVersion', 'sourceSha256'].every((key) => left?.[key] === right?.[key]);
+}
+
+function probeRuntime(port, timeout = 800) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/runtime', timeout }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => {
+        body += chunk;
+        if (body.length > 16_384) req.destroy();
+      });
+      res.on('end', () => {
+        if (res.statusCode !== 200) return resolve(null);
+        try { resolve(JSON.parse(body)); } catch { resolve(null); }
+      });
+      res.on('error', () => resolve(null));
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+function probeHttpEndpoint(port, endpoint = '/api/runtime', timeout = 800) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: endpoint, timeout }, (res) => {
+      res.resume();
+      res.on('end', () => resolve({ reachable: true, status: res.statusCode }));
+    });
+    req.on('error', () => resolve({ reachable: false, status: null }));
+    req.on('timeout', () => { req.destroy(); resolve({ reachable: false, status: null }); });
+  });
+}
+
+function requestRuntimeShutdown(port, controlToken, timeout = 1_500) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ controlToken });
+    const req = http.request({
+      host: '127.0.0.1', port, path: '/api/runtime/shutdown', method: 'POST', timeout,
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+    }, (res) => {
+      res.resume();
+      res.on('end', () => resolve(res.statusCode === 202));
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end(body);
+  });
+}
+
+async function waitForRuntimeToStop(port, timeout = 3_000) {
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    if (!await probeRuntime(port, 150)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return false;
+}
+
+async function inspectConsoleRuntime({ cwd = process.cwd(), preferredPort = Number(process.env.CONSOLE_PORT) || 7411 } = {}) {
+  const receiptFile = runtimeReceiptPath(cwd);
+  if (!fs.existsSync(receiptFile)) {
+    const endpoint = await probeHttpEndpoint(preferredPort);
+    return endpoint.reachable
+      ? { state: 'foreign-port', scope: canonicalScope(cwd), port: preferredPort }
+      : { state: 'not-running', scope: canonicalScope(cwd) };
+  }
+  const receipt = readJSON(receiptFile);
+  if (!validRuntimeReceipt(receipt, receiptFile)) return { state: 'receipt-invalid', scope: canonicalScope(cwd) };
+  const live = await probeRuntime(receipt.port);
+  if (!live) {
+    const endpoint = await probeHttpEndpoint(receipt.port);
+    return endpoint.reachable
+      ? { state: 'legacy-unowned', scope: canonicalScope(cwd), port: receipt.port }
+      : { state: 'stale-receipt', scope: canonicalScope(cwd), port: receipt.port };
+  }
+  if (!sameRuntimeIdentity(live, publicRuntimeIdentity(receipt))) {
+    return { state: 'legacy-unowned', scope: canonicalScope(cwd), port: receipt.port };
+  }
+  const candidate = runtimeIdentity({ port: receipt.port, cwd, pid: receipt.pid, startedAt: receipt.startedAt });
+  const current = sameRuntimeIdentity(live, candidate);
+  return {
+    state: current ? 'current' : 'stale-running',
+    scope: canonicalScope(cwd),
+    port: receipt.port,
+    live,
+    candidate: publicRuntimeIdentity(candidate),
+  };
+}
+
+async function launchConsole({ port = Number(process.env.CONSOLE_PORT) || 7411, open = false, cwd = process.cwd() } = {}) {
+  const status = await inspectConsoleRuntime({ cwd, preferredPort: port });
+  if (status.state === 'current') {
+    const url = `http://127.0.0.1:${status.port}/`;
+    console.log(`\n  🧠  RuvNet Brain — Onboarding Console (already running)\n      ${url}\n`);
+    if (open) openBrowser(url);
+    return { reused: true, port: status.port };
+  }
+
+  if (status.state === 'stale-running') {
+    const receiptFile = runtimeReceiptPath(cwd);
+    const receipt = readJSON(receiptFile);
+    const stopped = validRuntimeReceipt(receipt, receiptFile)
+      && await requestRuntimeShutdown(receipt.port, receipt.controlToken)
+      && await waitForRuntimeToStop(receipt.port);
+    if (stopped) {
+      console.log(`  replacing owned stale Console on port ${receipt.port}…`);
+      return { reused: false, server: startServer({ port: receipt.port, open, cwd }) };
+    }
+    console.error('  owned stale Console did not release its port — starting the current Console separately');
+  }
+
+  if (status.state === 'stale-receipt' || status.state === 'receipt-invalid') {
+    try { fs.unlinkSync(runtimeReceiptPath(cwd)); } catch { /* already gone or unreadable */ }
+  }
+  return { reused: false, server: startServer({ port, open, cwd }) };
+}
 
 const NPX_RUV = /npx\s+(?:-y\s+|--yes\s+)?(?:@claude-flow\/[\w-]+|claude-flow|ruflo|ruvector|ruv-swarm|flow-nexus|metaharness|@metaharness\/[\w-]+|agentic-qe|aqe)(?:@[\w.-]+)?/;
 
@@ -123,27 +337,9 @@ function robustReadJSON(db, sql) {
 const VENDOR = ['/clones/', '/node_modules/', '/vendor/', '/upstream/', '.claude-backup', '_snapshots',
   '/ruvnet-repos/', '/ruvnet_repos/'];
 
-// ── Candidate scan roots (issue #19) ────────────────────────────────────────────────────────────
-// A single hardcoded `~/Code` silently reports "0" on any machine that keeps projects somewhere
-// else (a reporter's `~/source`, `~/dev`, `~/work`, …) — a confident zero that just means "didn't
-// look in the right place". Scan every root that actually exists on THIS machine, plus a user
-// override in config.json (`scanRoots`, absolute paths or relative to $HOME) when present.
-const DEFAULT_SCAN_ROOTS = ['Code', 'code', 'src', 'source', 'projects', 'dev', 'work'];
-function candidateRoots() {
-  const cfg = readJSON(CONFIG_PATH) || {};
-  const configured = Array.isArray(cfg.scanRoots) && cfg.scanRoots.length > 0
-    ? cfg.scanRoots.map((r) => (path.isAbsolute(r) ? r : path.join(HOME, r)))
-    : DEFAULT_SCAN_ROOTS.map((d) => path.join(HOME, d));
-  const seen = new Set();
-  const roots = [];
-  for (const r of configured) {
-    const resolved = path.resolve(r);
-    if (seen.has(resolved)) continue;
-    seen.add(resolved);
-    try { if (fs.statSync(resolved).isDirectory()) roots.push(resolved); } catch { /* doesn't exist on this machine — skip silently */ }
-  }
-  return roots;
-}
+// memory-doctor.mjs owns candidate-root policy for the standalone CLI, Console, and other callers.
+// Keeping one exported implementation prevents a new project-root convention from fixing one
+// surface while another continues to print a confident but incomplete machine-wide count (#81).
 function findProjects(root) {
   const out = new Set();
   const walk = (dir, depth) => {
@@ -181,7 +377,7 @@ function wiringSurvey() {
   // must never count the same project twice.
   const seenProjects = new Set();
   const projects = [];
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     for (const proj of findProjects(root)) {
       const resolved = path.resolve(proj);
       if (seenProjects.has(resolved)) continue;
@@ -219,7 +415,7 @@ function wiringSurvey() {
 
 // ── Memory health (read-only probes for the project the console was launched from) ────────────────
 function sessionHookExists() {
-  return fs.existsSync(path.join(HOME, '.claude/hooks/agentdb-ensure.sh')) || fs.existsSync(path.join(HOME, '.claude/hooks'));
+  return fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks/agentdb-ensure.sh')) || fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks'));
 }
 function probeMemory(projectDir) {
   const db = path.join(projectDir, '.swarm/memory.db');
@@ -273,19 +469,7 @@ function probeMemory(projectDir) {
 // machine has 100+. That is far too slow to sit on the page's first paint, so it is its own endpoint
 // (/api/memory) and hydrates late, exactly like the stack audit does.
 function scanFleet() {
-  // memory-doctor.mjs's findStores() defaults to ~/Code and cannot be edited here (issue #19) — so
-  // pass it every candidate root explicitly and de-dupe (it also always appends a couple of known
-  // extra paths regardless of root, which the Set below folds together instead of duplicating).
-  const seen = new Set();
-  const stores = [];
-  for (const root of candidateRoots()) {
-    for (const db of findStores(root)) {
-      const resolved = path.resolve(db);
-      if (seen.has(resolved)) continue;
-      seen.add(resolved);
-      stores.push(db);
-    }
-  }
+  const stores = findStores();
   const fleet = [];
   for (const db of stores) {
     const d = diagnose(db);
@@ -299,7 +483,7 @@ function scanFleet() {
 function gatherMemory(cwd, { fleet = true } = {}) {
   // health = for the project the console was launched from (fall back to this repo)
   const project = fs.existsSync(path.join(cwd, '.swarm/memory.db')) ? cwd : REPO;
-  const projName = project.replace(HOME + '/Code/', '').replace(HOME + '/', '~/');
+  const projName = project.replace(CONSOLE_ROOT + '/Code/', '').replace(CONSOLE_ROOT + '/', '~/');
   const health = scoreMemoryHealth({ project: projName, probes: probeMemory(project) });
   return { fleet: fleet ? scanFleet() : null, health };
 }
@@ -308,10 +492,10 @@ function gatherMemory(cwd, { fleet = true } = {}) {
 function gatherSavings() {
   // Primary source is the real routing-receipts ledger written by scripts/route-cheap.mjs.
   const files = [
-    path.join(HOME, '.claude/metaharness/routing-receipts.jsonl'),
-    path.join(HOME, '.cache/ruvnet-brain/metaharness-receipts.jsonl'),
+    path.join(SYSTEM_HOME, '.claude/metaharness/routing-receipts.jsonl'),
+    path.join(SYSTEM_HOME, '.cache/ruvnet-brain/metaharness-receipts.jsonl'),
     // Canonical user-level ledger (issue #36 — the hooks no longer scatter per-CWD copies).
-    path.join(HOME, '.cache/ruvnet-brain/token-ledger.jsonl'),
+    path.join(SYSTEM_HOME, '.cache/ruvnet-brain/token-ledger.jsonl'),
     // Legacy location, still read so an existing user's history is not orphaned by the move.
     path.join(REPO, 'plugin/scripts/.ruvnet-brain/token-ledger.jsonl'),
   ];
@@ -415,7 +599,7 @@ function gatherConfig() {
     });
   }
   return {
-    path: CONFIG_PATH.replace(HOME, '~'),
+    path: CONFIG_PATH.replace(CONSOLE_ROOT, '~'),
     exists: fs.existsSync(CONFIG_PATH),
     values: {
       openrouterKey: credential.configured,                // boolean only — never the secret itself
@@ -464,7 +648,7 @@ function gatherAdvocacy() {
   const chosen = raw && typeof raw === 'object' && raw.settings && typeof raw.settings === 'object'
     ? raw.settings : {};
   return {
-    path: state.path.replace(HOME, '~'),
+    path: state.path.replace(CONSOLE_ROOT, '~'),
     exists: state.exists,
     values: Object.fromEntries(LIVE_USER_FIELDS.map((field) => [
       field.key,
@@ -512,7 +696,7 @@ function saveAdvocacy(values) {
   publishSettingsToCache();
   return {
     ok: true,
-    backup: result.backup ? result.backup.replace(HOME, '~') : null,
+    backup: result.backup ? result.backup.replace(CONSOLE_ROOT, '~') : null,
     values: Object.fromEntries(LIVE_USER_SETTING_KEYS.map((key) => [key, result.values[key]])),
     log: result.log,
   };
@@ -552,7 +736,7 @@ function gatherBrainProfile() {
   const source = measureBrainProfile(COMPLETE_BRAIN_SOURCE);
   const updaterAvailable = fs.existsSync(path.join(INSTALLED_KB, 'forge-update.mjs'));
   return {
-    path: INSTALLED_KB.replace(HOME, '~'),
+    path: INSTALLED_KB.replace(CONSOLE_ROOT, '~'),
     values: { brainProfile: actual },
     stored: settings.values.brainProfile,
     disagreement: settings.values.brainProfile !== actual,
@@ -573,7 +757,7 @@ function gatherBrainProfile() {
         bytes: installed.byStore.ruvector ?? source.byStore.ruvector ?? null,
       },
     },
-    restoreSource: COMPLETE_BRAIN_SOURCE.replace(HOME, '~'),
+    restoreSource: COMPLETE_BRAIN_SOURCE.replace(CONSOLE_ROOT, '~'),
   };
 }
 
@@ -584,7 +768,7 @@ function gatherBrainPower() {
     off: state.off,
     since: state.since,
     reason: state.reason,
-    switchPath: state.path.replace(HOME, '~'),
+    switchPath: state.path.replace(CONSOLE_ROOT, '~'),
     // The RESOLVED answer — what the machine actually does — not the mirror's opinion of it.
     values: { brainEnabled: !state.off },
     defaults: { brainEnabled: BRAIN_FIELD.default },
@@ -666,7 +850,7 @@ function saveBrainProfile(values) {
     removed: changed.removed || [],
     bytesFreed: changed.bytesFreed || 0,
     mirrored: mirrored.ok,
-    backup: mirrored.backup ? mirrored.backup.replace(HOME, '~') : null,
+    backup: mirrored.backup ? mirrored.backup.replace(CONSOLE_ROOT, '~') : null,
     log: mirrored.ok
       ? (profile === PROFILE_RUVECTOR
         ? `RuVector Only is active — ${changed.removed.length} unselected artifact(s) removed`
@@ -754,7 +938,7 @@ function saveBrainPower(values) {
     ok: true,
     off: state.off,
     since: state.since,
-    backup: mirrored.backup ? mirrored.backup.replace(HOME, '~') : null,
+    backup: mirrored.backup ? mirrored.backup.replace(CONSOLE_ROOT, '~') : null,
     values: { brainEnabled: !state.off },
     // Honest about the half-failure rather than reporting a clean success: the switch is what counts
     // and it moved, but say so plainly if the visible record did not follow it.
@@ -924,7 +1108,7 @@ function setLesson(body) {
 // setImmediate either (deferring synchronous work still blocks the loop when it runs). A machine with
 // no fleet scan yet is reported `warming`, never as a fabricated zero.
 let ACTIVITY_MACHINE_CACHE = null;
-const CONSOLE_CACHE_PATH = path.join(HOME, '.cache/ruvnet-brain/console-cache.json');
+const CONSOLE_CACHE_PATH = path.join(CONSOLE_ROOT, '.cache/ruvnet-brain/console-cache.json');
 
 // ── Warm-cache serving (2026-07-17, the demo-hang fix) ─────────────────────────────────────────────
 // Every read-model here does multi-second synchronous work: gatherState ~13s, gatherStack ~22s,
@@ -1374,7 +1558,7 @@ function refreshFleetCache() {
   const seen = new Set();
   // Scan every candidate root (issue #19) — this is what made machine-wide totals read 0 on a
   // machine whose projects live under ~/source instead of ~/Code.
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     for (const s of findMemoryStores(root)) {
       const resolved = path.resolve(s.project);
       if (seen.has(resolved)) continue; // a project visible under two roots (e.g. a symlink) counts once
@@ -1653,11 +1837,11 @@ function brainVersionOnDisk() {
   try { return getVersion(); } catch { return null; }
 }
 function readInstallChannel() {
-  const reg = readJSON(path.join(HOME, '.claude/plugins/installed_plugins.json'));
+  const reg = readJSON(path.join(SYSTEM_HOME, '.claude/plugins/installed_plugins.json'));
   const entries = reg && reg.plugins && reg.plugins['ruvnet-brain@ruvnet-brain'];
   const e = Array.isArray(entries) ? entries[0] : null;
   if (!e || !e.installPath || !fs.existsSync(e.installPath)) return { installed: false };
-  const km = readJSON(path.join(HOME, '.claude/plugins/known_marketplaces.json'));
+  const km = readJSON(path.join(SYSTEM_HOME, '.claude/plugins/known_marketplaces.json'));
   const src = km && km['ruvnet-brain'] && km['ruvnet-brain'].source;
   const pinned = !!(src && (src.ref || src.tag || src.commit)); // no pin recorded → tracking latest
   return {
@@ -1665,7 +1849,7 @@ function readInstallChannel() {
     version: path.basename(e.installPath) || e.version || null, // the plugin cache version dir IS the truth
     channel: pinned ? 'pinned' : 'latest',
     lastUpdated: e.lastUpdated || null,
-    cacheDir: String(e.installPath).replace(HOME, '~'),
+    cacheDir: String(e.installPath).replace(SYSTEM_HOME, '~'),
     repo: (src && src.repo) || null,
   };
 }
@@ -1806,7 +1990,7 @@ function gatherState(cwd, { fleet = true } = {}) {
   // agentic-flow, and the Savings card claiming "Smart routing: ON" while the Capabilities card said
   // "not installed" — in the same render — was the contradiction that made the whole page untrustworthy.
   // The card now carries the same measurement the capability row uses, so the two cannot disagree.
-  savings.routingInstalled = fs.existsSync(path.join(HOME, '.npm-global/bin/agentic-flow'));
+  savings.routingInstalled = fs.existsSync(path.join(SYSTEM_HOME, '.npm-global/bin/agentic-flow'));
   try { savings.routerEngine = gatherRouterEngine(); } catch { savings.routerEngine = null; }
   try {
     const cat = loadCatalog();
@@ -1852,7 +2036,7 @@ function gatherState(cwd, { fleet = true } = {}) {
     token: TOKEN,
     generatedAt: new Date().toISOString(),
     preStateHash,
-    host: { user: os.userInfo().username, platform: process.platform, node: process.version, npmPrefix: NPM_PREFIX.replace(HOME, '~'), brainVersion: brainVersionOnDisk() },
+    host: { user: os.userInfo().username, platform: process.platform, node: process.version, npmPrefix: NPM_PREFIX.replace(SYSTEM_HOME, '~'), brainVersion: brainVersionOnDisk() },
     sections: { wiring, memory, savings, config, userSettings, brainPower, gates, recommendations },
   };
   // Cache the last good state so repeat page-loads paint instantly, same as the stack audit does.
@@ -1873,7 +2057,7 @@ function gatherStack() {
   // ISSUE #22 — carry `source` ('npm-global' | 'plugin') + marketplace through so the console can show
   // (and count) tools installed via the Claude Code plugin marketplace, not just `npm install -g` ones.
   const rows = a.rows.map((r) => ({ name: r.name, installed: r.installed, target: r.target, tag: r.tag, state: r.state, source: r.source ?? 'npm-global', marketplace: r.marketplace ?? null }));
-  const shadows = a.shadows.map((s) => ({ name: s.name, version: s.version, global: s.global, dir: String(s.dir).replace(HOME, '~'), stale: !!(s.global && s.version !== s.global) }));
+  const shadows = a.shadows.map((s) => ({ name: s.name, version: s.version, global: s.global, dir: String(s.dir).replace(SYSTEM_HOME, '~'), stale: !!(s.global && s.version !== s.global) }));
   const by = (st) => rows.filter((r) => r.state === st).length;
   const summary = { total: rows.length, behind: by('BEHIND'), broken: by('BROKEN'), ahead: by('AHEAD'), current: by('CURRENT'), unresolved: by('UNRESOLVED'), shadows: shadows.length, stale: a.stale.length };
   const recommendations = buildStackRecommendations({ rows: a.rows, stale: a.stale });
@@ -1901,29 +2085,32 @@ function runNode(scriptRelPath, args) {
   const r = spawnSync(process.execPath, [path.join(REPO, scriptRelPath), ...args], { encoding: 'utf8', timeout: 16 * 60 * 1000, cwd: REPO });
   return { ok: r.status === 0, code: r.status, log: `${r.stdout || ''}${r.stderr || ''}`.trim().slice(-4000) };
 }
+function elapsedMs(startedAt) {
+  return Math.round((performance.now() - startedAt) * 1000) / 1000;
+}
 
 // A wiring recommendation's `project` id is relative to whichever candidate root it was found under
 // (issue #19) — reconstruct the absolute path by checking each root, so reconcile/undo can act on a
 // project under ~/source just as well as one under ~/Code.
 function resolveProjectDir(project) {
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     const p = path.join(root, project);
     if (fs.existsSync(p)) return p;
   }
-  return path.join(HOME, 'Code', project); // last-resort fallback: the previous fixed behavior
+  return path.join(CONSOLE_ROOT, 'Code', project); // last-resort fallback: the previous fixed behavior
 }
 // Re-derive the currently-valid recommendation set, so apply can only ever act on something STILL true.
 /**
  * Observe the learner's REAL state, for the health recommendations.
  *
- * Deliberately reads the GLOBAL learner (`cwd: HOME`), because that is the store the capture flush
+ * Deliberately reads the global learner, because that is the store the capture flush
  * actually writes to. Reading the project-local `.claude-flow/neural` instead is exactly the mistake
  * that made the console display a dead learner (5 trajectories, last trained 6 days earlier) while
  * the live one held 412 — rUv documents this fragmentation as issue #2245, "four contradictory
  * sources". Until it is unified upstream we read the store that learning writes, never the corpse.
  */
 function observeLearning() {
-  const queueDir = path.join(os.homedir(), '.cache', 'ruvnet-brain', 'learn');
+  const queueDir = path.join(SYSTEM_HOME, '.cache', 'ruvnet-brain', 'learn');
   let queueDepth = 0;
   try {
     for (const f of fs.readdirSync(queueDir)) {
@@ -1934,10 +2121,10 @@ function observeLearning() {
 
   let lastTrainSeconds = null; let trajectories = 0;
   try {
-    const r = spawnSync(path.join(os.homedir(), '.npm-global/bin/ruflo'),
+    const r = spawnSync(path.join(SYSTEM_HOME, '.npm-global/bin/ruflo'),
       ['hooks', 'intelligence', '--status'],
       {
-        cwd: os.homedir(),
+        cwd: SYSTEM_HOME,
         env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
         encoding: 'utf8',
         timeout: 20_000,
@@ -2004,11 +2191,15 @@ function currentValidIds(onlyId = null) {
   return { ids, auditRows };
 }
 function apply(ids) {
+  const startedAt = performance.now();
+  const phaseMs = { revalidationMs: 0, undoJournalMs: 0, childRemedyMs: 0 };
   const results = [];
   for (const id of ids) {
     // Re-read immediately before EACH fix. A batch can change the validity of the next item; one
     // pre-flight snapshot for the whole list would let item 2 run against the world item 1 changed.
+    const revalidationStartedAt = performance.now();
     const { ids: validNow } = currentValidIds(id);
+    phaseMs.revalidationMs += elapsedMs(revalidationStartedAt);
     if (!validNow.has(id)) { results.push({ id, ok: false, skipped: true, error: 'worldMoved', log: 'Skipped — this is already resolved, or your machine changed since the page loaded. Nothing was done. Reload to see the current state.' }); continue; }
 
     // ONE dispatch, through the registry (scripts/remedy-registry.mjs). This used to be a chain of
@@ -2050,16 +2241,22 @@ function apply(ids) {
     // flag exists so it cannot recur here.
     if (plan.exec.usesServerProject) args = [...args, '--project', process.cwd()];
     if (plan.exec.needsReceipt) {
-      const receipt = path.join(HOME, '.cache', 'ruvnet-brain', 'undo', `${plan.key}-${stamp()}.json`);
+      const receipt = path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'undo', `${plan.key}-${stamp()}.json`);
       undoSpec.receipt = receipt;
       args = [...args, '--receipt', receipt];
     }
 
+    const journalStartedAt = performance.now();
     const undoToken = journalUndo(undoSpec);
+    phaseMs.undoJournalMs += elapsedMs(journalStartedAt);
+    const remedyStartedAt = performance.now();
     const res = runNode(plan.exec.script, args);
+    phaseMs.childRemedyMs += elapsedMs(remedyStartedAt);
     results.push({ id, ...res, undoToken });
   }
-  return { results };
+  // This receipt contains only aggregate durations, never the applied ids, paths, command output,
+  // or undo tokens. It makes an end-user-visible delay diagnosable without exposing their machine.
+  return { results, timings: { ...phaseMs, totalMs: elapsedMs(startedAt) } };
 }
 
 function autoEligibleIds(recommendations = []) {
@@ -2131,7 +2328,7 @@ function validateConfigPatch(values) {
  */
 function saveConfig(values) {
   try { fs.mkdirSync(CONFIG_DIR, { recursive: true }); }
-  catch (e) { return { ok: false, log: `could not create ${CONFIG_DIR.replace(HOME, '~')}: ${e.message}` }; }
+  catch (e) { return { ok: false, log: `could not create ${CONFIG_DIR.replace(CONSOLE_ROOT, '~')}: ${e.message}` }; }
 
   const { clean, rejected } = validateConfigPatch(values);
   // Nothing valid to write is not a save. Saying "Saved." here would be the dead-button failure with
@@ -2193,7 +2390,7 @@ function saveConfig(values) {
     // A successfully encrypted credential retires the legacy plaintext field on this same commit.
     if (credentialChange?.ok) delete next.openrouterKey;
     try { writeAtomic(CONFIG_PATH, JSON.stringify(next, null, 2) + '\n'); }
-    catch (e) { return { ok: false, backup, log: `write failed: ${e.message}${backup ? `; your previous settings are at ${backup.replace(HOME, '~')}` : ''}` }; }
+    catch (e) { return { ok: false, backup, log: `write failed: ${e.message}${backup ? `; your previous settings are at ${backup.replace(CONSOLE_ROOT, '~')}` : ''}` }; }
     try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort on non-posix */ }
 
     // The undo token is journalled only AFTER the write succeeded. Recording an undo for a save that
@@ -2207,7 +2404,7 @@ function saveConfig(values) {
       secretPath: credentialChange?.path ?? null,
       secretExisted: credentialChange?.existed ?? null,
     });
-    return { ok: true, backup: backup ? backup.replace(HOME, '~') : null, undoToken, rejected };
+    return { ok: true, backup: backup ? backup.replace(CONSOLE_ROOT, '~') : null, undoToken, rejected };
   });
 
   if (held.timedOut) {
@@ -2301,7 +2498,7 @@ function undo(undoToken) {
       try {
         const bytes = fs.readFileSync(entry.backup);
         held = withLock(CONFIG_PATH, () => writeAtomic(CONFIG_PATH, bytes));
-      } catch (e) { return { ok: false, log: `restore failed: ${e.message} — your backup at ${entry.backup.replace(HOME, '~')} is intact` }; }
+      } catch (e) { return { ok: false, log: `restore failed: ${e.message} — your backup at ${entry.backup.replace(CONSOLE_ROOT, '~')} is intact` }; }
       if (held.timedOut) return { ok: false, log: `another process is writing your settings and did not finish within ${LOCK_WAIT_MS}ms — NOTHING was restored and your backup is intact; try again` };
       try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort on non-posix */ }
       const effectFailures = restoreConfigEffects(entry);
@@ -2361,10 +2558,10 @@ function undo(undoToken) {
     const base = `${path.basename(entry.db)}.rescue-`;
     let baks = [];
     try { baks = fs.readdirSync(dir).filter((n) => n.startsWith(base)).sort(); } catch { /* dir gone */ }
-    if (!baks.length) return { ok: false, log: `no pre-repair backup found next to ${entry.db.replace(HOME, '~')} — nothing was restored` };
+    if (!baks.length) return { ok: false, log: `no pre-repair backup found next to ${entry.db.replace(CONSOLE_ROOT, '~')} — nothing was restored` };
     const from = path.join(dir, baks[baks.length - 1]);
     try { fs.copyFileSync(from, entry.db); }
-    catch (e) { return { ok: false, log: `could not restore ${from.replace(HOME, '~')}: ${e.message}` }; }
+    catch (e) { return { ok: false, log: `could not restore ${from.replace(CONSOLE_ROOT, '~')}: ${e.message}` }; }
     markUndoConsumed(undoToken);
     return { ok: true, log: `restored your memory store from the snapshot taken before the repair (${baks[baks.length - 1]})` };
   }
@@ -2477,6 +2674,9 @@ function openBrowser(url) {
   }
 }
 function startServer({ port = Number(process.env.CONSOLE_PORT) || 7411, open = false, cwd = process.cwd() } = {}) {
+  const controlToken = crypto.randomBytes(24).toString('hex');
+  let activeRuntime = null;
+  let receiptFile = null;
   const server = http.createServer(async (req, res) => {
     // DNS-rebinding guard: this server binds 127.0.0.1 only. Reject any request whose Host header
     // isn't loopback, so a malicious web page can't rebind a hostname to 127.0.0.1 and read local state.
@@ -2486,6 +2686,19 @@ function startServer({ port = Number(process.env.CONSOLE_PORT) || 7411, open = f
     }
     try {
       const url = req.url.split('?')[0];
+      // This identity endpoint is deliberately cache-independent and never exposes the shutdown
+      // token. The private receipt is ownership proof; this endpoint only proves which generation
+      // is listening before reuse or replacement.
+      if (req.method === 'GET' && url === '/api/runtime') {
+        return sendJSON(res, activeRuntime ? 200 : 503, activeRuntime || { error: 'runtime not ready' });
+      }
+      if (req.method === 'POST' && url === '/api/runtime/shutdown') {
+        const body = await readBody(req);
+        if (body.controlToken !== controlToken) return sendJSON(res, 403, { error: 'bad or missing control token' });
+        sendJSON(res, 202, { ok: true, stopping: true });
+        setImmediate(() => server.close());
+        return;
+      }
       // Heavy read-models: ALWAYS cache-first (fast=1 or not — both land here now). The handler
       // never blocks the event loop; kickRefresh() recomputes in a detached child. See writeCache/
       // serveCached above and the --refresh-cache CLI mode. TOKEN is injected at serve time so it
@@ -2582,9 +2795,14 @@ function startServer({ port = Number(process.env.CONSOLE_PORT) || 7411, open = f
     if (e.code === 'EADDRINUSE' && port !== 0) { console.error(`  port ${port} busy — trying a free one…`); startServer({ port: 0, open, cwd }); }
     else { console.error(`  server error: ${e.message}`); process.exit(1); }
   });
+  server.on('close', () => {
+    if (receiptFile) removeOwnedRuntimeReceipt(receiptFile, controlToken);
+  });
   server.listen(port, '127.0.0.1', () => {
     const actual = server.address().port;
     const url = `http://127.0.0.1:${actual}/`;
+    activeRuntime = runtimeIdentity({ port: actual, cwd });
+    receiptFile = writeRuntimeReceipt({ ...activeRuntime, controlToken });
     console.log(`\n  🧠  RuvNet Brain — Onboarding Console`);
     console.log(`      ${url}`);
     console.log(`      read-only until you click · token-gated · ^C to stop\n`);
@@ -2617,7 +2835,7 @@ function startServer({ port = Number(process.env.CONSOLE_PORT) || 7411, open = f
     // precise moment a first-time user is deciding whether this thing works. The child does that
     // scan now (see --refresh-cache), and gatherActivity reports `warming` until it lands.
     if (open) openBrowser(url);
-    // Browser acceptance pre-warms a disposable HOME and disables only this redundant second scan.
+    // Browser acceptance pre-warms a disposable fixture root and disables only this redundant second scan.
     // The production default is unchanged: every ordinary console start refreshes in the background.
     if (process.env.RUVNET_CONSOLE_DISABLE_BACKGROUND_REFRESH !== '1') kickRefresh({ force: true });
   });
@@ -2629,6 +2847,7 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('onboarding-consol
   const args = process.argv.slice(2);
   if (args.includes('--print-state')) { console.log(JSON.stringify(gatherState(process.cwd()), null, 2)); }
   else if (args.includes('--print-stack')) { console.log(JSON.stringify(gatherStack(), null, 2)); }
+  else if (args.includes('--runtime-status')) { console.log(JSON.stringify(await inspectConsoleRuntime())); }
   else if (args.includes('--refresh-cache')) {
     // Runs as a DETACHED CHILD of the server (kickRefresh) — or standalone to pre-warm. Computes the
     // heavy read-models HERE, in a separate process, so the server's event loop is never blocked, and
@@ -2705,26 +2924,13 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith('onboarding-consol
     process.exit(0);
   }
   else if (args.includes('--serve') || args.length === 0) {
-    // Hitting the command again should land on the console you already have, not spawn a second
-    // server on a random port and a second tab. If one is already up, just point the browser at it.
-    const port = Number(process.env.CONSOLE_PORT) || 7411;
-    const open = args.includes('--open');
-    const url = `http://127.0.0.1:${port}/`;
-    const alive = await new Promise((resolve) => {
-      const req = http.get({ host: '127.0.0.1', port, path: '/', timeout: 800 }, (res) => {
-        let b = ''; res.on('data', (c) => { b += c; if (b.length > 4096) res.destroy(); });
-        res.on('end', () => resolve(res.statusCode === 200 && /RuvNet Brain/.test(b)));
-        res.on('error', () => resolve(false));
-      });
-      req.on('error', () => resolve(false));
-      req.on('timeout', () => { req.destroy(); resolve(false); });
+    await launchConsole({
+      port: Number(process.env.CONSOLE_PORT) || 7411,
+      open: args.includes('--open'),
+      cwd: process.cwd(),
     });
-    if (alive) {
-      console.log(`\n  🧠  RuvNet Brain — Onboarding Console (already running)\n      ${url}\n`);
-      if (open) openBrowser(url);
-    } else { startServer({ port, open, cwd: process.cwd() }); }
   }
-  else { console.log(`\n  onboarding-console — the RuvNet Brain configure page\n\n    --serve [--open]   start the local server (and open your browser)\n    --print-state      print the read-only state JSON and exit (for tests)\n    --print-stack      print the stack audit JSON and exit\n`); }
+  else { console.log(`\n  onboarding-console — the RuvNet Brain configure page\n\n    --serve [--open]   start or safely replace the scoped local server\n    --runtime-status   print candidate, receipt, and live runtime status\n    --print-state      print the read-only state JSON and exit (for tests)\n    --print-stack      print the stack audit JSON and exit\n`); }
 }
 
 export {
@@ -2747,3 +2953,4 @@ export {
 // Exported for the cross-project cache-isolation test (console-cache-scope.test.mjs). serveCached's
 // scopeKey is the guard that stops one project's cached state being served for another.
 export { serveCached, writeCache, kickRefresh };
+export { inspectConsoleRuntime, launchConsole, runtimeReceiptPath, startServer };