ruvnet-brain 4.7.20 → 4.7.22

package/scripts/claims-verify.mjs

@@ -26,6 +26,7 @@ import { storeRoot } from '../kb/store-root.mjs';
 import { validateCoverageDirectory, sha256File } from './coverage-integrity.mjs';
 import { verifyPayload, verifyPayloadMembers, payloadIdFor } from './release-payload.mjs';
 import { extractZip } from '../kb/zip-extract.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -206,6 +207,9 @@ export function readCoverageClaims(readme) {
 export const COVERAGE_REGEN_CMD = 'npm run test:cov';
 
 const DIR_PRUNE = new Set(['node_modules', '.git', 'coverage', 'dist', 'clones']);
+// Root-relative trees that are never coverage sources but can be huge or busy: agent worktrees (whole
+// checkouts), job logs, the QE fleet's state and local caches.
+const ROOT_PRUNE = new Set(['.claude/worktrees', 'logs', '.agentic-qe', '.cache']);
 
 /** Minimal glob → RegExp for the shapes coverage.include/exclude actually use (`**`, `*`, `?`). */
 function globToRe(glob) {
@@ -250,9 +254,9 @@ export async function coverageSourceSet(vitestFile = path.join(ROOT, 'vitest.con
     try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const ent of ents) {
       const abs = path.join(dir, ent.name);
-      if (ent.isDirectory()) { if (!DIR_PRUNE.has(ent.name)) walk(abs); continue; }
-      if (!ent.isFile()) continue;
       const rel = path.relative(root, abs).split(path.sep).join('/');
+      if (ent.isDirectory()) { if (!DIR_PRUNE.has(ent.name) && !ROOT_PRUNE.has(rel)) walk(abs); continue; }
+      if (!ent.isFile()) continue;
       if (incl.some((r) => r.test(rel)) && !exclude.some((r) => r.test(rel))) files.push(abs);
     }
   };
@@ -903,6 +907,6 @@ async function main() {
   if (verdict === 'UNKNOWN' && process.argv.includes('--strict')) process.exitCode = 4;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   await main();
 }

package/scripts/claude-controlled-terminal.mjs

@@ -14,6 +14,7 @@ import { decideNativeTurn, appendGatewayReceipt } from './model-routing-gateway.
 import { subscriptionEnvironment, assertSubscriptionAuth, validateDispatchDecision } from './model-router-dispatch.mjs';
 import { validateClaudeTerminalSettings } from './model-terminal-launchers.mjs';
 import { runManagedPrompt } from './model-managed-prompt.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const REFUSED = 'Controlled Claude turn refused; no fallback.';
 const uuid = value => /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(value || '');
@@ -386,7 +387,7 @@ export async function launchControlledClaudeTerminal({ binary, args = [], input
   } finally { controller.abort(); terminal.close(); for (const name of ['SIGINT', 'SIGTERM', 'SIGHUP']) signalSource.removeListener(name, cancel); }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   const args = process.argv.slice(2);
   if (args[0] !== '--real-binary' || !args[1] || args[2] !== '--') {
     process.stderr.write('Expected --real-binary /absolute/native/claude -- [--resume UUID]\n'); process.exitCode = 1;

package/scripts/claude-terminal-mod.mjs

@@ -6,6 +6,7 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { classify } from '../config/model-router/policy.default.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const MOD_SOURCE = path.join(ROOT, 'config/model-router/claude-terminal-mod');
 export function terminalModDigest(pluginRoot) {
@@ -84,6 +85,6 @@ async function main() {
   else if (mode === '--prepare') process.stdout.write(JSON.stringify(prepareClaudeTerminalMod(request)) + '\n');
   else throw new Error('Expected --prepare, --decision, --ready, or --health');
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(() => {
+if (isDirectInvocation(import.meta.url)) main().catch(() => {
   process.stderr.write('claude-terminal-mod: routing or activation unavailable; no fallback\n'); process.exitCode = 1;
 });

package/scripts/code-release-corpus.mjs

@@ -34,6 +34,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 import { resolveNextCorpusSeed } from './corpus-next-seed.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const CORPUS_TAG = /^corpus-sha256-([0-9a-f]{64})$/;
@@ -266,7 +267,7 @@ export function main(argv = process.argv.slice(2)) {
 
 function isMain() {
   try {
-    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch {
     return false;
   }

package/scripts/codex-boot-surface-proof.mjs

@@ -0,0 +1,208 @@
+// Proof that the Codex boot surface a release changed is the surface a FRESH Codex session will load (issue #391,
+// ADR-0070, ADR-0051). A receipt that names `scripts/hook-shim.mjs`, `mcp/server.mjs` or `skills/` as changed used to stay
+// restartScope:'unproven' forever, because only the two hook-declaration files could be cleared. Each path is proven by
+// the strongest evidence that can be gathered without a Codex relaunch, and any path with no prover stays unproven,
+// NAMED in the result:
+//   hooks/codex-hooks.json, hooks/hooks.json  the fresh-declarations proof (scripts/codex-fresh-host-proof.mjs)
+//   skills/                                    that proof plus a byte-identical skills/ tree
+//   scripts/hook-shim.mjs                      byte-identical AND a real run of the INSTALLED shim with an unknown hook
+//                                              id (it exits 0 doing nothing and lists its roles; every registered Codex
+//                                              role must be listed)
+//   mcp/server.mjs                             byte-identical AND a real stdio initialize + tools/list that must
+//                                              include search_ruvnet
+// The result ALWAYS reports windows that are already open as `unproven` and a host relaunch as `not-observed`. It is
+// read-only: both real processes run against an isolated temporary HOME and brain home (the MCP server leases its
+// generation while running), under a hard deadline, and the temp tree is removed. It never touches a receipt.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { shellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
+
+export const BOOT_REASON_PREFIX = 'boot-level declarations changed: ';
+export const PROVABLE_PATHS = Object.freeze(['hooks/codex-hooks.json', 'hooks/hooks.json', 'skills/',
+  'scripts/hook-shim.mjs', 'mcp/server.mjs']);
+const MAX_CAPTURE = 64 * 1024;
+
+/** The changed paths a machine-generated sessionSafetyReason names, or [] when it names none. */
+export function parseChangedPaths(reason) {
+  if (typeof reason !== 'string' || !reason.startsWith(BOOT_REASON_PREFIX)) return [];
+  return reason.slice(BOOT_REASON_PREFIX.length).split(', ').map((entry) => entry.trim()).filter(Boolean);
+}
+
+/** The hook roles a Codex hooks file registers: the id after the timeout in each `... <timeoutMs> <role> [event]` command. */
+export function registeredCodexRoles(hooksFile) {
+  const parsed = JSON.parse(fs.readFileSync(hooksFile, 'utf8'));
+  const roles = new Set();
+  for (const groups of Object.values(parsed.hooks || {})) {
+    for (const group of groups) {
+      for (const handler of group.hooks || []) {
+        const match = /"\s+\d+\s+([a-z][a-z0-9-]*)(?:\s+\S+)?\s*$/.exec(String(handler.command || ''));
+        if (match) roles.add(match[1]);
+      }
+    }
+  }
+  return [...roles];
+}
+
+// Windows cannot start node (or resolve DLLs, temp, shells) without these; copied only when present, never a secret.
+const WINDOWS_NEEDS = ['SystemRoot', 'windir', 'ComSpec', 'PATHEXT'];
+const IS_WIN = process.platform === 'win32';
+
+/** SIGKILL the probe's whole process group (it is spawned detached, so it leads one); the child alone on Windows. */
+function killTree(child) {
+  try {
+    if (!IS_WIN && Number.isInteger(child?.pid) && child.pid > 1) process.kill(-child.pid, 'SIGKILL');
+    else child?.kill('SIGKILL');
+  } catch { try { child?.kill('SIGKILL'); } catch { /* gone */ } }
+}
+
+export function isolatedEnv(tmp, extra = {}, source = process.env) {
+  const needs = {};
+  for (const name of WINDOWS_NEEDS) if (source[name]) needs[name] = source[name];
+  const env = { ...needs, PATH: source.PATH || source.Path || '', HOME: tmp, USERPROFILE: tmp, TMPDIR: tmp,
+    RUVNET_BRAIN_HOME: path.join(tmp, 'brain'), RUVNET_BRAIN_STATE_DIR: path.join(tmp, 'state'),
+    XDG_CACHE_HOME: path.join(tmp, 'xdg'), XDG_CONFIG_HOME: path.join(tmp, 'xdgc'), CODEX_HOME: path.join(tmp, 'codex'),
+    RUVNET_BRAIN_KB: path.join(tmp, 'kb'), RUVNET_NIGHTLY: '', ...extra };
+  if (IS_WIN) { env.TEMP = tmp; env.TMP = tmp; }   // USERPROFILE is already the isolated tmp; TEMP/TMP must not point at the real profile
+  return env;
+}
+
+function runBounded(args, { cwd, env, timeoutMs }) {
+  return new Promise((resolve) => {
+    let out = ''; let err = ''; let timedOut = false; let settled = false;
+    const child = spawn(process.execPath, args, { cwd, env, detached: !IS_WIN, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const finish = (result) => { if (settled) return; settled = true; clearTimeout(timer); resolve({ stdout: out, stderr: err, timedOut, ...result }); };
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    child.stdout.on('data', (b) => { if (out.length < MAX_CAPTURE) out += b; });
+    child.stderr.on('data', (b) => { if (err.length < MAX_CAPTURE) err += b; });
+    child.once('error', (error) => finish({ code: null, signal: null, spawnError: error.message }));
+    child.once('close', (code, signal) => { killTree(child); finish({ code, signal }); });
+  });
+}
+
+/** Run the INSTALLED shim with an id it does not know. Proven only by exit 0 plus a role list covering every registered role. */
+export async function runShimProbe({ installedRoot, roles, tmp, timeoutMs }) {
+  const shim = path.join(installedRoot, 'scripts', 'hook-shim.mjs');
+  const started = Date.now();
+  const run = await runBounded([shim, 'boot-surface-proof-unknown-hook'], { cwd: tmp, env: isolatedEnv(tmp), timeoutMs });
+  const elapsedMs = Date.now() - started;
+  if (run.timedOut) return { ok: false, elapsedMs, reason: `the installed hook shim did not exit within ${timeoutMs} ms and was killed` };
+  if (run.spawnError) return { ok: false, elapsedMs, reason: `the installed hook shim could not start: ${run.spawnError}` };
+  if (run.code !== 0) return { ok: false, elapsedMs, reason: `the installed hook shim exited ${run.code ?? run.signal} for an unknown hook id (expected 0)` };
+  const listed = /known:\s*([^\n]*)/.exec(run.stderr)?.[1]?.split(',').map((s) => s.trim()).filter(Boolean) || [];
+  const missing = roles.filter((role) => !listed.includes(role));
+  if (!listed.length) return { ok: false, elapsedMs, reason: 'the installed hook shim listed no hook roles' };
+  if (missing.length) return { ok: false, elapsedMs, listed, reason: `the installed hook shim does not list registered Codex role(s): ${missing.join(', ')}` };
+  return { ok: true, elapsedMs, rolesListed: listed.length, rolesRegistered: roles.length };
+}
+
+const STUB_WORKER = "require('node:fs').writeFileSync(process.env.RNB_PROOF_MARKER,String(process.pid));process.exit(0);\n";
+
+/** Real stdio MCP handshake against the INSTALLED server: initialize, tools/list. Never starts the real search worker. */
+export async function runMcpProbe({ installedRoot, tmp, timeoutMs }) {
+  const server = path.join(installedRoot, 'mcp', 'server.mjs');
+  const stub = path.join(tmp, 'stub-worker.cjs'); const marker = path.join(tmp, 'worker-started');
+  fs.writeFileSync(stub, STUB_WORKER);
+  const env = isolatedEnv(tmp, { RUVNET_BRAIN_CHILD_MCP: stub, RNB_PROOF_MARKER: marker });
+  const started = Date.now();
+  return await new Promise((resolve) => {
+    let buffer = ''; let settled = false; let timedOut = false;
+    const replies = new Map(); let stderr = '';
+    const child = spawn(process.execPath, [server], { cwd: tmp, env, detached: !IS_WIN, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    const kill = () => killTree(child);
+    const deadline = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+    const send = (message) => { try { child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`); } catch { /* exit handler reports */ } };
+    const done = (result) => { if (settled) return; settled = true; clearTimeout(deadline); resolve({ elapsedMs: Date.now() - started, ...result }); };
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk;
+      let at;
+      while ((at = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+        let message; try { message = JSON.parse(line); } catch { continue; }
+        if (message.id !== undefined) replies.set(message.id, message);
+        if (message.id === 1) { send({ method: 'notifications/initialized' }); send({ id: 2, method: 'tools/list', params: {} }); }
+        if (message.id === 2) {
+          // initialize launches the warm search worker in the background (plugin/mcp/server.mjs `void ensureChild()`); the
+          // stub worker records that it was launched, so the result reports the fact instead of assuming it.
+          setTimeout(() => { try { child.stdin.end(); } catch { /* gone */ } }, 400);
+        }
+      }
+    });
+    child.stderr.on('data', (b) => { if (stderr.length < MAX_CAPTURE) stderr += b; });
+    child.once('error', (error) => done({ ok: false, reason: `the installed MCP server could not start: ${error.message}` }));
+    child.once('close', (code, signal) => {
+      killTree(child);
+      const leaseLeft = fs.existsSync(path.join(tmp, 'brain', 'leases')) && fs.readdirSync(path.join(tmp, 'brain', 'leases')).length > 0;
+      const initialize = replies.get(1); const list = replies.get(2);
+      const workerStarted = fs.existsSync(marker);
+      const base = { exit: code ?? signal, leaseLeftBehind: leaseLeft, initializeStartsWarmWorker: workerStarted };
+      if (timedOut) return done({ ok: false, ...base, reason: `the installed MCP server did not finish an initialize + tools/list within ${timeoutMs} ms and was killed` });
+      if (!initialize?.result) return done({ ok: false, ...base, reason: 'the installed MCP server did not answer initialize' });
+      const names = Array.isArray(list?.result?.tools) ? list.result.tools.map((tool) => tool?.name) : null;
+      if (!names) return done({ ok: false, ...base, reason: 'the installed MCP server did not answer tools/list' });
+      if (!names.includes('search_ruvnet')) return done({ ok: false, ...base, tools: names, reason: 'the installed MCP server tools/list does not include search_ruvnet' });
+      if (leaseLeft) return done({ ok: false, ...base, tools: names, reason: 'the installed MCP server left its lease file behind after exit' });
+      return done({ ok: true, ...base, tools: names.length });
+    });
+    send({ id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'boot-surface-proof', version: '1' } } });
+  });
+}
+
+/**
+ * @param {object} o
+ * @param {string[]} o.changedPaths        paths the convergence receipt names as changed at boot level
+ * @param {string} o.releasedPluginRoot    the release being converged to (its plugin/ directory)
+ * @param {string} o.installedPluginRoot   the plugin tree Codex loads (its plugin cache for the active version)
+ * @param {object} [o.declarations]        a probeFreshCodexDeclarations() result; required for the declaration paths
+ */
+export async function proveCodexBootSurface({ changedPaths, releasedPluginRoot, installedPluginRoot, declarations = null, timeoutMs = 15_000 } = {}) {
+  const proven = []; const unproven = [];
+  const result = (extra = {}) => ({ ok: !extra.error && changedPaths?.length > 0 && unproven.length === 0,
+    state: !extra.error && changedPaths?.length > 0 && unproven.length === 0 ? 'boot-surface-ready' : 'boot-surface-unproven',
+    scope: 'fresh-codex-boot-surface', changed: changedPaths || [], proven, unproven,
+    reason: extra.error || (unproven.length ? unproven.map((u) => `${u.path}: ${u.reason}`).join('; ') : null),
+    existingWindows: 'unproven', hostRelaunch: 'not-observed', inferenceRequests: 0, ...extra.detail });
+  if (!Array.isArray(changedPaths) || !changedPaths.length) return result({ error: 'no changed boot-level paths are recorded, so there is nothing to prove' });
+  if (!releasedPluginRoot || !installedPluginRoot) return result({ error: 'the released or installed plugin root is unknown' });
+  let diff;
+  try { diff = new Set(shellDiff(installedPluginRoot, releasedPluginRoot)); }
+  catch (error) { return result({ error: `the installed and released plugin trees could not be compared: ${error.message}` }); }
+  const identical = (rel) => !diff.has(rel);
+  const declarationsReady = declarations?.ok === true && declarations.state === 'fresh-declarations-ready';
+  const wants = (rel) => changedPaths.includes(rel);
+  let tmp = null; let shim = null; let mcp = null;
+  try {
+    if (wants('scripts/hook-shim.mjs') || wants('mcp/server.mjs')) {
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rnb-boot-proof-'));
+      for (const dir of ['brain', 'state', 'xdg', 'xdgc', 'codex', 'kb']) fs.mkdirSync(path.join(tmp, dir), { recursive: true });
+    }
+    for (const rel of changedPaths) {
+      if (!PROVABLE_PATHS.includes(rel)) { unproven.push({ path: rel, reason: 'no prover exists for this path; it stays unproven' }); continue; }
+      if (rel === 'hooks/codex-hooks.json' || rel === 'hooks/hooks.json') {
+        if (declarationsReady) proven.push({ path: rel, evidence: 'fresh-declarations-ready' });
+        else unproven.push({ path: rel, reason: `fresh Codex hook declarations are not proven${declarations?.reason ? ` (${declarations.reason})` : ''}` });
+      } else if (rel === 'skills/') {
+        if (!identical(rel)) unproven.push({ path: rel, reason: 'the installed skills/ tree is not byte-identical to the release' });
+        else if (!declarationsReady) unproven.push({ path: rel, reason: `fresh Codex declarations are not proven${declarations?.reason ? ` (${declarations.reason})` : ''}` });
+        else proven.push({ path: rel, evidence: 'byte-identical skills/ tree plus fresh-declarations-ready' });
+      } else if (rel === 'scripts/hook-shim.mjs') {
+        if (!identical(rel)) { unproven.push({ path: rel, reason: 'the installed hook shim is not byte-identical to the release' }); continue; }
+        let roles;
+        try { roles = registeredCodexRoles(path.join(installedPluginRoot, 'hooks', 'codex-hooks.json')); }
+        catch (error) { unproven.push({ path: rel, reason: `the registered Codex roles could not be read: ${error.message}` }); continue; }
+        shim = await runShimProbe({ installedRoot: installedPluginRoot, roles, tmp, timeoutMs });
+        if (shim.ok) proven.push({ path: rel, evidence: `byte-identical; real run exited 0 and listed all ${shim.rolesRegistered} registered Codex roles` });
+        else unproven.push({ path: rel, reason: shim.reason });
+      } else if (rel === 'mcp/server.mjs') {
+        if (!identical(rel)) { unproven.push({ path: rel, reason: 'the installed MCP server is not byte-identical to the release' }); continue; }
+        mcp = await runMcpProbe({ installedRoot: installedPluginRoot, tmp, timeoutMs });
+        if (mcp.ok) proven.push({ path: rel, evidence: `byte-identical; real stdio initialize + tools/list returned ${mcp.tools} tools including search_ruvnet` });
+        else unproven.push({ path: rel, reason: mcp.reason });
+      }
+    }
+  } finally {
+    if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+  return result({ detail: { ...(shim ? { shim } : {}), ...(mcp ? { mcp } : {}) } });
+}

package/scripts/codex-hook-trust-reconcile.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import zlib from 'node:zlib';
 import { codexHookIdentities, codexPluginContentHash } from './codex-hook-trust.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 /**
  * sha256 of every regular file under package/plugin/ in a verified npm tarball, read in memory (ustar with pax `path`
@@ -335,8 +336,73 @@ export async function reconcileVerifiedCodexHookTrust({ releaseIdentity, install
   } finally { await client?.close(); }
 }
 
+/**
+ * Refresh a RUNNING shared Codex app-server (the managed daemon the TUI attaches to) after the Brain changed its
+ * plugin bytes or hook trust from another process (#492). Without this, that long-lived server keeps the plugin
+ * declarations it parsed earlier — codex-rs/core-plugins/src/manager.rs LoadedPluginsCache::get() only drops an
+ * entry when the active plugin ROOT changes, not when files change in place — and its loaded sessions keep their
+ * old hook runtimes. Measured 2026-10-25, codex-cli 0.164.0, isolated CODEX_HOME: after an in-place change the
+ * daemon's hooks/list still showed the old SessionEnd declaration while a fresh server showed the new one.
+ *
+ * The refresh is Codex's own: config/batchWrite with no edits and reloadUserConfig. With no edits nothing is
+ * persisted (config_manager_service.rs apply_edits writes only when config_edits is non-empty); batch_write then
+ * clears the plugin and skill caches (config_processor.rs handle_config_mutation) and reloads every loaded thread
+ * (reload_user_config). The expectedVersion check makes a concurrent config writer fail it safely. It never grants
+ * an approval, starts or stops a server, or touches a thread. No server listening = nothing stale to refresh.
+ * Transport: WebSocket over $CODEX_HOME/app-server-control/app-server-control.sock, a symlink to the physical
+ * socket (codex-rs/app-server-transport/src/transport/{mod.rs,unix_socket.rs}).
+ */
+export async function refreshSharedCodexAppServer({ codexHome, timeoutMs = 8000, connect } = {}) {
+  if (typeof codexHome !== 'string' || !path.isAbsolute(codexHome)) return { state: 'blocked', changed: false, reason: 'Absolute Codex home required' };
+  const rendezvous = path.join(codexHome, 'app-server-control', 'app-server-control.sock');
+  let socketPath;
+  try { socketPath = fs.realpathSync(rendezvous); if (!fs.statSync(socketPath).isSocket()) throw new Error('not a socket'); }
+  catch { return { state: 'no-shared-server', changed: false }; }
+  // ONE total deadline, started BEFORE connecting: a socket that accepts but never completes the WebSocket handshake
+  // must not hang the installer (cross-vendor review F). On timeout the connecting socket is terminated.
+  let ws; let timer; let timedOut = false;
+  const deadline = new Promise((_, reject) => { timer = setTimeout(() => { timedOut = true; reject(new Error('Shared Codex app-server refresh timed out')); }, timeoutMs); });
+  deadline.catch(() => {});
+  try {
+    const run = (async () => {
+      ws = connect ? await connect(socketPath) : await (async () => {
+        const { default: WebSocket } = await import('ws');
+        const socket = new WebSocket(`ws+unix://${socketPath}:/`);
+        ws = socket; // reachable by the timeout's teardown while the handshake is still pending
+        await new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); });
+        return socket;
+      })();
+      if (timedOut) { try { if (ws.terminate) ws.terminate(); else ws.close(); } catch { /* already gone */ } return; }
+      const pending = new Map(); let nextId = 1;
+      ws.on('message', (data) => {
+        let row; try { row = JSON.parse(String(data)); } catch { return; }
+        const item = pending.get(row.id); if (!item) return;
+        pending.delete(row.id);
+        // Native error text can quote private config values; report only which call was refused.
+        if (row.error) item.reject(new Error(`Shared Codex app-server rejected ${item.method}`)); else item.resolve(row.result);
+      });
+      const rpc = (method, params) => new Promise((resolve, reject) => {
+        const id = nextId++; pending.set(id, { resolve, reject, method }); ws.send(JSON.stringify({ id, method, params }));
+      });
+      await rpc('initialize', { clientInfo: { name: 'rnb_host_refresh', version: '1' }, capabilities: { experimentalApi: true } });
+      ws.send(JSON.stringify({ method: 'initialized' }));
+      const read = await rpc('config/read', { includeLayers: true });
+      const users = (read?.layers || []).filter((r) => r.name?.type === 'user');
+      if (users.length !== 1 || typeof users[0].version !== 'string' || typeof users[0].name.file !== 'string') {
+        throw new Error('Shared Codex app-server user config version unavailable');
+      }
+      await rpc('config/batchWrite', { filePath: users[0].name.file, expectedVersion: users[0].version, reloadUserConfig: true, edits: [] });
+    })();
+    run.catch(() => {}); // a late failure after the deadline is already reported
+    await Promise.race([run, deadline]);
+    return { state: 'refreshed', changed: false, approvalsGranted: 0 };
+  } catch (error) {
+    return { state: 'failed', changed: false, reason: error.message };
+  } finally { clearTimeout(timer); try { if (timedOut && ws?.terminate) ws.terminate(); else ws?.close(); } catch { /* already closed */ } }
+}
+
 // Explicit CLI only; importing the helper never starts a process or reads stdin.
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isDirectInvocation(import.meta.url)
   && process.argv[2] === '--reconcile-installed') {
   const started = Date.now(); let emitted = false; let reconcileStarted = false;
   const emit = (receipt) => { if (!emitted) { emitted = true; process.stdout.write(JSON.stringify(receipt) + '\n'); } };

package/scripts/codex-hook-trust.mjs

@@ -78,17 +78,56 @@ export function codexHookIdentities(hooksFile, keySource = 'ruvnet-brain@ruvnet-
  * OLD file's hash at the same key ('modified') or that did not exist before ('untrusted'). A hook the user
  * had already trusted at the old hash stops running until reviewed; that is the whole point of the list.
  */
-export function codexTrustChanges(prevHooksFile, nextHooksFile, keySource) {
+export function codexTrustChanges(prevHooksFile, nextHooksFile, keySource, { contentChanged = false } = {}) {
   const prev = codexHookIdentities(prevHooksFile, keySource);
   const next = codexHookIdentities(nextHooksFile, keySource);
   const changes = [];
   for (const [key, hash] of next) {
     if (!prev.has(key)) changes.push({ key, status: 'untrusted' });
     else if (prev.get(key) !== hash) changes.push({ key, status: 'modified' });
+    // Codex 0.164+: an unchanged declaration is still "modified" once the plugin's bytes change, because the approval
+    // also pins trusted_content_hash (plugin_trust.rs matches_hash; legacy approvals pin a baseline the same way).
+    else if (contentChanged) changes.push({ key, status: 'modified', reason: 'plugin-content' });
   }
   return changes;
 }
 
+/**
+ * Does this Codex approve plugin hooks by content as well as declaration? True from codex-cli 0.164.0, where
+ * discovery.rs reports currentHash "<declaration>/<content>" and plugin_trust.rs checks trusted_content_hash.
+ * Unknown or unparseable versions answer null so a caller can fail toward asking for review.
+ */
+export function codexUsesContentTrust(versionText) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(String(versionText || ''));
+  if (!m) return null;
+  const [major, minor] = [Number(m[1]), Number(m[2])];
+  return major > 0 || minor >= 164;
+}
+
+// Codex writes this under the installed plugin itself (codex-rs/core-plugins/src/command_migration.rs); a candidate
+// release never carries it, so it says nothing about whether the release's bytes changed.
+const CODEX_GENERATED_PREFIX = '.codex-plugin/migrated-command-skills/';
+
+/**
+ * Would Codex see different plugin contents after replacing `installedRoot` with `candidateRoot`? Compares exactly
+ * the files codexPluginContentHash() fingerprints (Codex's own generated migrations aside). Anything unreadable
+ * counts as changed: the answer is used to warn, so it fails toward asking the user to review.
+ */
+export function codexPluginContentChanged(installedRoot, candidateRoot, options = {}) {
+  if (!installedRoot || !candidateRoot) return true;
+  const files = (root) => {
+    const out = new Map();
+    codexPluginContentHash(root, { ...options, onFile: (rel, bytes) => {
+      if (!rel.startsWith(CODEX_GENERATED_PREFIX)) out.set(rel, crypto.createHash('sha256').update(bytes).digest('hex'));
+    } });
+    return out;
+  };
+  try {
+    const a = files(installedRoot); const b = files(candidateRoot);
+    return a.size !== b.size || [...b].some(([rel, h]) => a.get(rel) !== h);
+  } catch { return true; }
+}
+
 /** The exact instruction for a user whose Brain hooks Codex is holding back. */
 export const CODEX_TRUST_ACTION = 'Start Codex (interactive, in any project). At the "Hooks need review" prompt choose'
   + ' "Trust all and continue" — or type /hooks and trust each RuvNet Brain hook. Until then Codex skips them'

package/scripts/codex-hook-wrapper-history.mjs

@@ -21,6 +21,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const HISTORY_FILE = path.join('data', 'codex-hook-wrapper-history.json');
@@ -122,6 +123,6 @@ export function main(argv = process.argv.slice(2)) {
   return 2;
 }
 
-if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = main();
 }

package/scripts/codex-host-execution-proof.mjs

@@ -10,6 +10,7 @@ import { probeFreshCodexDeclarations, classifyFreshCodexDeclarations } from './c
 import { runtimeSnapshot } from './model-routing-launchers.mjs';
 import { maintenanceStatus } from '../plugin/scripts/development-maintenance.mjs';
 import { proofFile, proofDigest, verifyReleasedHostRuntime, assertHostRuntimeUnchanged } from './codex-host-proof-runtime.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const OWNER = 'ruvnet-brain@ruvnet-brain';
 // The diagnostic verifies the canonical ordinary-work route, never selects a separate model.
@@ -241,6 +242,6 @@ export async function executionProofMain(args, { run = produceOwnedCodexExecutio
     return result.ok ? 0 : 1;
   } catch (error) { output(`${JSON.stringify(failure(error.message))}\n${usage}`); return 2; }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = await executionProofMain(process.argv.slice(2));
 }

package/scripts/completion-claim-replay.mjs

@@ -20,6 +20,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { auditCompletionClaims, claudeTurnEvents, extractCommitments } from '../plugin/scripts/completion-claim-evidence.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const argv = process.argv.slice(2);
 const opt = (flag, fallback) => { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback; };
@@ -110,5 +111,5 @@ function main() {
   console.log(JSON.stringify(summary, null, 2));
 }
 
-const isMain = (() => { try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) main();

package/scripts/console-engine.mjs

@@ -102,9 +102,14 @@ export function buildHealthRecommendations({ memory = null, learning = null } =
 
   // 3. A learner that has not trained in days. Installed-but-dormant is a DEFECT, not a neutral
   //    state — the entire point of shipping a learning system is that it runs.
+  //    #377: "quiet" means observations have WAITED more than two days for a distillation, measured
+  //    from `ruflo memory distill status`. An unknown distillation state, or a learner that is caught
+  //    up (nothing recorded since its last distillation), never shows this card.
   const STALE_TRAIN_SECONDS = 60 * 60 * 24 * 2; // two days
-  const age = learning?.enabled === false ? 0 : Number(learning?.lastTrainSeconds);
-  if (learning?.statusKnown && ((Number.isFinite(age) && age > STALE_TRAIN_SECONDS) || (learning.observations > 0 && learning.lastTrainSeconds === null))) {
+  const age = Number(learning?.lastTrainSeconds);
+  const waited = learning?.oldestPendingAt ? (Date.now() - Date.parse(learning.oldestPendingAt)) / 1000 : NaN;
+  if (learning?.enabled !== false && learning?.statusKnown && learning.distillKnown === true
+    && learning.pendingObservations > 0 && Number.isFinite(waited) && waited > STALE_TRAIN_SECONDS) {
     recs.push(makeRecommendation({
       id: 'learning:train',
       scope: learning?.scope === 'user' ? 'user' : 'project',
@@ -115,7 +120,7 @@ export function buildHealthRecommendations({ memory = null, learning = null } =
       plainImpact:
         'Runs one local training cycle so recent work becomes patterns it can reuse next time. '
         + 'Uses the same AgentDB, retains a checked local snapshot, and verifies pattern counts separately from recorded observations.',
-      evidence: [{ observed: `last distillation ${learning.lastTrainSeconds === null ? "not recorded" : (age / 86400).toFixed(1) + " days ago"} (${learning?.observations ?? learning?.trajectories ?? 0} observations recorded)${learning?.learningDb ? ` in ${learning.learningDb}` : ''}` }],
+      evidence: [{ observed: `last distillation ${Number.isFinite(age) ? (age / 86400).toFixed(1) + " days ago" : "not recorded"}; ${learning.pendingObservations} of ${learning?.observations ?? learning?.trajectories ?? 0} observations waiting, oldest ${(waited / 86400).toFixed(1)} days${learning?.learningDb ? ` in ${learning.learningDb}` : ''}` }],
       cost: { time: 'under a minute', risk: 'local structural patterns; snapshot retained; automatic exact restore unavailable' },
       change: { human: 'run one training cycle so captured work becomes reusable patterns' },
       undo: { human: 'retain the WAL-safe snapshot for supervised offline recovery; automatic exact restore is unavailable' },

package/scripts/corpus-canary.mjs

@@ -48,6 +48,7 @@ import { CANARY_VERDICT_KIND, CORPUS_TAG_PATTERN, REQUIRED_CANARY_CHECKS } from
 import { inventoryFootprint } from '../plugin/scripts/brain-footprint.mjs';
 import { eligibleRepositoryStanding } from '../plugin/scripts/coverage-integrity.mjs';
 import { TRANSIENT_HTTP, retryTransientAsync } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const PUBLIC_API = 'https://api.github.com';
 export const FRESHNESS_LIMIT_MS = 48 * 3_600_000;
@@ -579,6 +580,6 @@ async function main(argv = process.argv.slice(2)) {
   return record.verdict === 'PASS' ? 0 : 1;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; });
 }

package/scripts/corpus-candidate.mjs

@@ -34,6 +34,7 @@ import { canonicalJson, digest, fileIdentity, sha256File, validateGistAggregateR
 import { auditCorpusStores, isPassingState } from './rvf-index-audit.mjs';
 import { readDiagnosticAccuracyReport } from './oracle/retrieval-accuracy.mjs';
 import { loadFixture, readRecallReport } from './oracle/repo-recall.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REQUIRED_SUFFIXES = [
@@ -571,8 +572,7 @@ async function main() {
 // with no archive and no receipt on disk. Same defect, same fix as plugin/scripts/hook-input.mjs:518.
 function isMain() {
   try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch {
     return false;
   }

package/scripts/corpus-coverage-sidecar.mjs

@@ -26,6 +26,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { eligibleRepositoryStanding, validateCoverageLedger } from '../plugin/scripts/coverage-integrity.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const COVERAGE_ASSET = 'CORPUS-COVERAGE.json';
 export const COVERAGE_RECEIPT_ASSET = 'coverage-receipt.json';
@@ -195,7 +196,7 @@ export function main(argv = process.argv.slice(2), { stdout = process.stdout, st
 
 function isMain() {
   try {
-    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch {
     return false;
   }

package/scripts/corpus-dispatch-decision.mjs

@@ -34,6 +34,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const MIN_PIPELINE_VERSION = '4.3.38'; // sync-version-ignore: a fixed pipeline floor, not the current version
 /** The dispatcher's second schedule entry; corpus-nightly-dispatch.yml's `on.schedule` must carry exactly this line. */
@@ -188,6 +189,6 @@ export async function main(argv = process.argv.slice(2), { stdout = process.stdo
   return decision.verdict === 'fail' ? 1 : 0;
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; });
 }

package/scripts/corpus-dispatch-receipt.mjs

@@ -1,6 +1,7 @@
 // Correlation is not authorization: protected-release still enforces its own release authority.
 import fs from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export function selectCorpusDispatch(runs, { sha, dispatchId, notBefore }) {
   if (!/^[a-f0-9]{40}$/.test(sha || '') || !/^corpus-\d+-\d+$/.test(dispatchId || '')
@@ -12,7 +13,7 @@ export function selectCorpusDispatch(runs, { sha, dispatchId, notBefore }) {
   return matches[0] || null;
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isDirectInvocation(import.meta.url)) {
   const response = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
   const run = selectCorpusDispatch(response.workflow_runs || [], {
     sha: process.env.CANDIDATE_SHA, dispatchId: process.env.CORPUS_DISPATCH_ID,

package/scripts/corpus-next-seed.mjs

@@ -62,6 +62,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, bindCoverageToReceipt, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 import { retryTransientResult } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HEX64 = /^[0-9a-f]{64}$/;
@@ -423,7 +424,7 @@ export async function main(argv = process.argv.slice(2), { run = defaultRun, std
 // temp directories, and the CLI then exits 0 having done nothing.
 function isMain() {
   try {
-    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    return isDirectInvocation(import.meta.url);
   } catch {
     return false;
   }