ruvnet-brain 4.0.2 → 4.0.4

package/scripts/memory-doctor.mjs

@@ -43,6 +43,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const HOME = os.homedir();
+const DEFAULT_SCAN_ROOTS = ['Code', 'code', 'src', 'source', 'projects', 'dev', 'work'];
 
 // Telemetry namespaces: high-volume, unembedded, zero-signal. Written by the npx hook calls.
 // Counted separately so "you have 11,000 memories" is never mistaken for "you have 11,000 lessons".
@@ -131,8 +132,35 @@ const q = (db, sql) => {
 // n() returns null for "unknown" and a number only when we genuinely counted. Callers must handle null.
 const n = (r) => (r.ok ? (r.value === null || r.value === '' ? null : parseInt(r.value, 10)) : null);
 
-export function findStores(root = path.join(HOME, 'Code')) {
-  const out = [];
+function realExisting(value) {
+  try { return fs.realpathSync(value); } catch { return null; }
+}
+
+export function candidateRoots({
+  home = HOME,
+  configPath = path.join(home, '.claude', 'ruvnet-brain', 'config.json'),
+} = {}) {
+  let configured = [];
+  try {
+    const value = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (Array.isArray(value.scanRoots)) configured = value.scanRoots.filter((item) => typeof item === 'string' && item.trim());
+  } catch { /* absent or malformed config does not erase the common roots */ }
+
+  const roots = new Set();
+  for (const value of [...DEFAULT_SCAN_ROOTS, ...configured]) {
+    const absolute = path.isAbsolute(value) ? value : path.join(home, value);
+    const canonical = realExisting(absolute);
+    try {
+      if (canonical && fs.statSync(canonical).isDirectory()) roots.add(canonical);
+    } catch { /* missing/non-directory roots are not candidates on this machine */ }
+  }
+  return [...roots].sort();
+}
+
+function storesBelow(root) {
+  const out = new Set();
+  const canonicalRoot = realExisting(root);
+  if (!canonicalRoot) return out;
   const walk = (dir, depth) => {
     if (depth > 4) return;
     let entries;
@@ -142,24 +170,51 @@ export function findStores(root = path.join(HOME, 'Code')) {
       if (e.name === 'node_modules' || e.name === '.git') continue;
       if (e.name === '.swarm') {
         const db = path.join(dir, '.swarm/memory.db');
-        if (fs.existsSync(db)) out.push(db);
+        const canonical = realExisting(db);
+        if (canonical) out.add(canonical);
         continue;
       }
       if (e.name.startsWith('.') && e.name !== '.swarm') continue;
       walk(path.join(dir, e.name), depth + 1);
     }
   };
-  walk(root, 0);
-  // Stores outside ~/Code exist too (~/.claude, ~/cognitum-trader). A one-level glob missed 32 of
-  // these — including Helix — and that miss is exactly how "33/33 verified" got reported.
+  walk(canonicalRoot, 0);
+  return out;
+}
+
+export function findStores(root) {
+  const out = new Set();
+  if (root !== undefined) {
+    for (const db of storesBelow(root)) out.add(db);
+    return [...out].sort();
+  }
+
+  for (const candidate of candidateRoots()) {
+    for (const db of storesBelow(candidate)) out.add(db);
+  }
+  // These two stores intentionally sit outside the project-root convention. They belong only to
+  // the fleet-wide no-argument scan; an explicit root must remain genuinely scoped.
   for (const extra of [path.join(HOME, '.claude/.swarm/memory.db'), path.join(HOME, 'cognitum-trader/.swarm/memory.db')]) {
-    if (fs.existsSync(extra) && !out.includes(extra)) out.push(extra);
+    const canonical = realExisting(extra);
+    if (canonical) out.add(canonical);
+  }
+  return [...out].sort();
+}
+
+export function displayStoreName(db, home = HOME) {
+  const canonicalDb = realExisting(db) || path.resolve(db);
+  const project = path.dirname(path.dirname(canonicalDb));
+  const canonicalHome = realExisting(home) || path.resolve(home);
+  const relative = path.relative(canonicalHome, project);
+  if (relative === '') return '~';
+  if (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    return `~/${relative.split(path.sep).join('/')}`;
   }
-  return out.sort();
+  return project;
 }
 
 export function diagnose(db) {
-  const name = db.replace(HOME + '/Code/', '').replace(HOME + '/', '~/').replace('/.swarm/memory.db', '');
+  const name = displayStoreName(db);
 
   const ic = q(db, 'PRAGMA integrity_check;');
   if (!ic.ok) {

package/scripts/nightly-wrapper.sh

@@ -41,8 +41,8 @@ echo $$ > "$LOCK"
 trap 'rm -f "$LOCK"' EXIT
 
 # NIGHTLY_SMOKE=1 — prove this whole chain (launchd -> heartbeat wrapper -> here -> node -> the repo
-# scan -> the log) WITHOUT a multi-hour rebuild or a real Release publish. self-update.mjs is dry-run
-# by default, so dropping --apply --publish exercises every link except the build itself.
+# scan -> the log) WITHOUT a multi-hour rebuild. self-update.mjs is dry-run by default, so dropping
+# --apply exercises every link except the build itself. Publication is never part of this job.
 # WHY IT EXISTS (2026-07-13): the 03:15 fire on 07-12 died before it could even write its own log
 # ("/bin/bash: logs/nightly.log: No such file or directory" — relative path, no working directory) and
 # NOBODY KNEW, because the only way to test this chain was to wait until 03:15 and hope. A scheduled job
@@ -51,40 +51,32 @@ trap 'rm -f "$LOCK"' EXIT
 SMOKE="${NIGHTLY_SMOKE:-0}"
 
 run_once() {
-  local before after rc tail
-  before=$(gh release view --json tagName -q .tagName 2>/dev/null || echo "unknown")
-  { echo "===== nightly-wrapper attempt $1 — $(date -u +%FT%TZ) — before: $before ====="
+  local rc
+  { echo "===== nightly-wrapper rebuild attempt $1 — $(date -u +%FT%TZ) ====="
     if [ "$SMOKE" = "1" ]; then
-      echo "[SMOKE] dry-run: exercising the full chain, NOT building or publishing"
+      echo "[SMOKE] dry-run: exercising the full chain, NOT building"
       /usr/local/bin/node scripts/self-update.mjs --fresh-window 60
     else
-      /usr/local/bin/node scripts/self-update.mjs --apply --publish --fresh-window 60
+      /usr/local/bin/node scripts/self-update.mjs --apply --fresh-window 60
     fi
   } >> "$LOG" 2>&1
   rc=$?
-  if [ "$SMOKE" = "1" ]; then
-    # A smoke run must never claim a real outcome, touch the failure marker, or alter the tag story.
-    if [ "$rc" -eq 0 ]; then echo "===== attempt $1: SMOKE OK — chain intact (no build, no publish) =====" >> "$LOG"; return 0; fi
-    echo "===== attempt $1: SMOKE FAILED exit $rc — the chain is BROKEN, fix before 03:15 =====" >> "$LOG"
+  if [ "$rc" -ne 0 ]; then
+    echo "===== attempt $1: FAILED exit $rc — rebuild/candidate preparation did not complete =====" >> "$LOG"
     return 1
   fi
-  after=$(gh release view --json tagName -q .tagName 2>/dev/null || echo "unknown")
-  if [ "$after" != "$before" ] && [ -n "$after" ] && [ "$after" != "unknown" ]; then
-    echo "===== attempt $1: VERIFIED SUCCESS $before -> $after =====" >> "$LOG"
-    rm -f "$MARKER"
-    return 0
-  elif [ "$rc" -eq 0 ]; then
-    echo "===== attempt $1: CLEAN NO-OP, tag unchanged at $after =====" >> "$LOG"
-    rm -f "$MARKER"
+  if [ "$SMOKE" = "1" ]; then
+    # A smoke run must never claim a real outcome, touch the failure marker, or alter the tag story.
+    echo "===== attempt $1: SMOKE OK — chain intact (no build, no publish) =====" >> "$LOG"
     return 0
-  else
-    echo "===== attempt $1: FAILED exit $rc, tag stuck at $after =====" >> "$LOG"
-    return 1
   fi
+  echo "===== attempt $1: REBUILD COMPLETE — candidate bytes prepared; no release channel was promoted =====" >> "$LOG"
+  rm -f "$MARKER"
+  return 0
 }
 
 # Memory distillation (ADR-174) had gone stale 3 days — same silent-death pattern as everything
-# else tonight. Independent of publish success/failure: mine raw memory_entries into structured
+# else tonight. Independent of rebuild success/failure: mine raw memory_entries into structured
 # episodes/reasoning_patterns on every nightly run. Best-effort, never blocks the real job.
 RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory distill run --path .swarm/memory.db >> "$LOG" 2>&1 || true
 # Durability: was a one-off manual snapshot before tonight. Now recurring — WAL-safe, rotates
@@ -94,7 +86,7 @@ RUFLO_DAEMON_AUTOSTART=0 ~/.npm-global/bin/ruflo memory backup --db .swarm/memor
 # AgentDB drift canary (2026-07-23, P7 wiring sweep) — scripts/memdb-health.sh existed unwired since
 # 2026-07-09/10, the exact nights idx_bridge_key/idx_bridge_ns corruption recurred 3x on this very DB
 # while in WAL mode. Best-effort, same shape as its brain-health/key-health siblings below: never
-# blocks the real publish, just makes a WAL-mode/integrity regression loud instead of silent.
+# blocks the real rebuild, just makes a WAL-mode/integrity regression loud instead of silent.
 echo "===== memdb-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
 sh scripts/memdb-health.sh .swarm/memory.db >> "$LOG" 2>&1 \
   && echo "===== memdb-health canary: OK =====" >> "$LOG" \
@@ -109,7 +101,7 @@ sh scripts/memdb-health.sh .swarm/memory.db >> "$LOG" 2>&1 \
 # is the currency gate on the artifact this writes; if this step stops running, that workflow goes red
 # on staleness rather than everything staying quietly green.
 #
-# Best-effort, same shape as the canaries below: it never blocks the publish. Its exit code is not
+# Best-effort, same shape as the canaries below: it never blocks the rebuild. Its exit code is not
 # thrown away though — it is written to the log by name, because 0/1/3/4 are four different facts
 # (PASS / the lesson stopped transferring / the trap was invalidated / it could not be measured) and
 # collapsing them into "failed" is how the seven prior silent-death bugs in this file happened.
@@ -126,7 +118,7 @@ esac
 # ── GONG LAYER 3: brain-health canary (Stuart, 2026-07-12 — the brain must NEVER be dark silently).
 # One real query against the LIVE cache brain every night. forge-ask-all.mjs exits non-zero on a
 # total retrieval failure (all repos erroring) and rings kb/brain-alarm.mjs itself; this adds the
-# guaranteed-nightly cadence plus its own urgent push, independent of the publish job's outcome.
+# guaranteed-nightly cadence plus its own urgent push, independent of the rebuild job's outcome.
 BRAIN_KB="$HOME/.cache/ruvnet-brain/kb"
 if [ -f "$BRAIN_KB/forge-ask-all.mjs" ]; then
   echo "===== brain-health canary — $(date -u +%FT%TZ) =====" >> "$LOG"
@@ -170,11 +162,11 @@ python3 -c "
 import json, datetime
 json.dump({
   'at': datetime.datetime.utcnow().isoformat() + 'Z',
-  'tag_stuck_at': '$AFTER',
+  'last_release_tag_observed': '$AFTER',
   'tail': '''$TAIL''',
   'note': 'Nightly failed twice (immediate + 3min retry). Needs a live session to diagnose — see logs/nightly.log.'
 }, open('$MARKER', 'w'), indent=2)
 "
-sh scripts/notify.sh "🔴 Nightly FAILED twice — needs you" "tag stuck at $AFTER after retry. Last: $TAIL" urgent "rotating_light"
+sh scripts/notify.sh "🔴 Nightly FAILED twice — needs you" "candidate rebuild failed; last release remains $AFTER. Last: $TAIL" urgent "rotating_light"
 echo "===== ESCALATED: marker written at $MARKER =====" >> "$LOG"
 exit 1

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';
@@ -79,6 +79,199 @@ const INSTALLED_KB = process.env.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(HOME, '.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 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 +316,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) => {
@@ -273,19 +448,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);
@@ -2477,6 +2640,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 +2652,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 +2761,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`);
@@ -2629,6 +2813,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 +2890,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 +2919,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 };

package/scripts/protected-release-invocation.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Local publication is deliberately impossible. The one publisher may mutate public channels only
+// when the reviewer-protected GitHub workflow carries a fully valid candidate seal into it.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { evaluateCandidateReceipt } from './release-proof.mjs';
+import { getVersion } from './version.mjs';
+
+export const PROTECTED_WORKFLOW = 'protected-release';
+export const PROTECTED_VERSION = getVersion();
+
+const hex = (value, length) => new RegExp(`^[0-9a-f]{${length}}$`).test(String(value || ''));
+const digestOf = (receipt) => String(receipt?.artifact?.sha256 || '').replace(/^sha256:/, '');
+
+export function validateProtectedPublishInvocation({ root = process.cwd(), env = process.env } = {}) {
+  const failures = [];
+  let releaseMode = 'unknown';
+  if (env.GITHUB_ACTIONS !== 'true' || env.GITHUB_WORKFLOW !== PROTECTED_WORKFLOW) {
+    failures.push('publication is allowed only inside the protected-release GitHub workflow');
+  }
+
+  const expectedSha = String(env.RUVNET_EXPECTED_SHA || '');
+  const expectedDigest = String(env.RUVNET_EXPECTED_ARTIFACT_SHA256 || '').replace(/^sha256:/, '');
+  const expectedVersion = String(env.RUVNET_EXPECTED_VERSION || '');
+  if (!hex(expectedSha, 40)) failures.push('expected candidate SHA is missing or malformed');
+  if (!hex(expectedDigest, 64)) failures.push('expected artifact digest is missing or malformed');
+  if (expectedVersion !== PROTECTED_VERSION) failures.push(`release generation must be ${PROTECTED_VERSION}`);
+
+  const receiptRelative = String(env.RUVNET_CANDIDATE_RECEIPT || '');
+  const evidenceRoot = path.resolve(root, 'release-evidence');
+  const receiptPath = path.resolve(root, receiptRelative || '.missing-candidate-receipt');
+  if (!receiptRelative || !(receiptPath === evidenceRoot || receiptPath.startsWith(`${evidenceRoot}${path.sep}`))) {
+    failures.push('candidate receipt must be inside release-evidence');
+  }
+
+  let receipt = null;
+  try {
+    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  } catch (error) {
+    failures.push(`candidate receipt unavailable: ${error.message}`);
+  }
+
+  if (receipt) {
+    const seal = evaluateCandidateReceipt(receipt);
+    if (seal.verdict !== 'PASS') failures.push(`candidate seal failed: ${seal.failures.map(({ code }) => code).join(',')}`);
+    const receiptDigest = digestOf(receipt);
+    if (receipt.sha !== expectedSha) failures.push('candidate receipt SHA mismatch');
+    if (receiptDigest !== expectedDigest) failures.push('candidate artifact digest mismatch');
+    if (receipt.version !== expectedVersion) failures.push('candidate version mismatch');
+    const expectedMode = receipt.phase === 'stabilization-candidate' ? 'stabilization' : 'strict';
+    releaseMode = expectedMode;
+    if (env.RUVNET_RELEASE_MODE !== expectedMode) failures.push(`release mode must be ${expectedMode} for this receipt`);
+
+    const artifactPath = path.resolve(root, String(receipt.artifact?.path || '.missing-artifact'));
+    if (!(artifactPath === evidenceRoot || artifactPath.startsWith(`${evidenceRoot}${path.sep}`))) {
+      failures.push('candidate artifact must be inside release-evidence');
+    } else {
+      try {
+        const actual = crypto.createHash('sha256').update(fs.readFileSync(artifactPath)).digest('hex');
+        if (actual !== expectedDigest) failures.push('candidate artifact bytes do not match the seal');
+      } catch (error) {
+        failures.push(`candidate artifact unavailable: ${error.message}`);
+      }
+    }
+  }
+
+  return {
+    verdict: failures.length === 0 ? 'PASS' : 'FAIL',
+    sha: expectedSha,
+    artifactSha256: expectedDigest,
+    version: expectedVersion,
+    mode: releaseMode,
+    failures,
+  };
+}