ruvnet-brain 4.7.19 → 4.7.21

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-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;
   }

package/scripts/corpus-qa.mjs

@@ -50,6 +50,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { FULL_HINTS } from './full-hints.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KB = path.join(ROOT, 'kb');
@@ -245,7 +246,7 @@ export function discoverStores(dir) {
 }
 
 // ---------------- CLI ----------------
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isDirectInvocation(import.meta.url)) {
   const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   const has = (f) => process.argv.includes(f);
   const DIR = path.resolve(arg('--dir', KB));

package/scripts/corpus-reconcile.mjs

@@ -26,6 +26,7 @@ import { captureGistSources } from './gist-receipts.mjs';
 import { projectSourceStore, RUNTIME_LEDGER_KIND } from './rvf-generation.mjs';
 import { compareKnowledgeInputs, fromCoverage as knowledgeFromCoverage, fromSeed as knowledgeFromSeed } from './knowledge-input-digest.mjs';
 import { defaultBaseDelayMs } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export { rebuildCorpusAggregates };
 
@@ -1306,8 +1307,7 @@ export async function main(argv = process.argv.slice(2), {
 // 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-watchdog.mjs

@@ -48,6 +48,7 @@ import { AGGREGATE_ASSET, SIGNING_PUBLIC_KEY_FILE } from './approved-runtime.mjs
 import { COVERAGE_ASSET, COVERAGE_RECEIPT_ASSET, verifyCoverageSidecar } from './corpus-coverage-sidecar.mjs';
 import { parseCorpusGeneration } from './corpus-promotion.mjs';
 import { retryTransientResult } from './transient-gh.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const RED = 'RED';
@@ -496,6 +497,6 @@ async function main(argv = process.argv.slice(2)) {
   return result.verdict === RED ? 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/count-chunks.mjs

@@ -23,6 +23,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyFix } from './claims-verify.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const CHECK = process.argv.includes('--check');
 
@@ -49,6 +50,6 @@ async function main() {
   console.log(`\n[count-chunks] done — ${want} chunks is the live count; ${drifted.length} surface(s) rewritten.`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   await main();
 }

package/scripts/customer-state-matrix.mjs

@@ -34,6 +34,7 @@ import { customerEnv, customerManifestUrl, installCustomer, installedModules } f
 import { addPrivateStore, resolveRuntime } from './customer-seams.mjs';
 export { resolveRuntime };
 import { doctorSmokeArgs } from './installed-brain-health.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const REPO = 'stuinfla/ruvnet-brain';
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -358,6 +359,6 @@ async function main(argv = process.argv.slice(2)) {
   return 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; }, (error) => { console.error(error.stack || error.message); process.exitCode = 1; });
 }

package/scripts/derive-passage-content-map.mjs

@@ -16,6 +16,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { digest } from './coverage-integrity.mjs';
 import { CONTENT_MAP_FILE, CONTENT_MAP_KIND, passageContentDigest } from './retrieval-passage-identity.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const sha256File = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
@@ -68,4 +69,4 @@ function main(argv) {
   console.log(JSON.stringify({ out, resolved: Object.keys(map.entries).length, unresolved: map.unresolved.length }));
 }
 
-if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+if (isDirectInvocation(import.meta.url)) main(process.argv.slice(2));

package/scripts/development-push-check.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export function inspectPush(root, input) {
   const checked = [];
@@ -27,7 +28,7 @@ export function inspectPush(root, input) {
   return { ok: true, checked, scope: 'unpublished-commit-secret-scan' };
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   try {
     const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
     console.log(JSON.stringify(inspectPush(root, fs.readFileSync(0, 'utf8'))));

package/scripts/dispatch-receipt.mjs

@@ -26,6 +26,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { CLAUDE_MODEL_IDS, CLAUDE_TIERS, PRICING, estTokens, estimateCosts, receiptLine, receiptsPath, priceOf } from './route-cheap.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 // Default input share when only a MEASURED TOTAL is known. A subagent's tokens are dominated by input
 // (it re-reads files and tool output on every turn); its final report is small. 0.9 is an assumption,
@@ -109,4 +110,4 @@ function main() {
   console.log(receiptLine(receipt.model, { cost: receipt.est_cost, frontier: receipt.est_frontier_cost, saved: receipt.saved, ref: receipt.inherited }));
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+if (isDirectInvocation(import.meta.url)) main();

package/scripts/doc-currency.mjs

@@ -3,7 +3,8 @@
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { main } from '../plugin/scripts/doc-currency.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 export * from '../plugin/scripts/doc-currency.mjs';
 let direct = false;
-try { direct = Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch {}
+try { direct = isDirectInvocation(import.meta.url); } catch {}
 if (direct) process.exit(main());

package/scripts/dream-issue-gate.mjs

@@ -5,6 +5,7 @@
 // the caller supplies the finding and the current open issues, and receives a disposition before
 // invoking any GitHub write operation.
 
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 const HEX_SHA = /^[0-9a-f]{7,64}$/i;
 const ISSUE_MARKER = 'dream-fingerprint:';
 
@@ -98,7 +99,7 @@ export function buildIssueBody(finding, decision = assessFinding(finding)) {
 // Adapter contract for the Dream Machine runner. Input is JSON on stdin:
 // { "finding": { ... }, "openIssues": [{ "number", "title", "body" }] }
 // Output is the disposition JSON. This command intentionally cannot create or mutate GitHub data.
-if (process.argv[1] === new URL(import.meta.url).pathname) {
+if (isDirectInvocation(import.meta.url)) {
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });

package/scripts/dual-host-deliberation.mjs

@@ -6,6 +6,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { probeSubscriptionHosts, subscriptionOnlyEnv } from './subscription-hosts.mjs';
 import { DUAL_HOST_MODEL_IDS } from './review-model-defaults.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HOSTS = Object.freeze(['claude-code', 'codex']);
 // Top subscription models verified on the native hosts on 2026-09-10.
@@ -322,21 +323,6 @@ export async function main(argv = process.argv.slice(2), {
   }
 }
 
-// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
-// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
-// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
-// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
-// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
-// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
-function isDirectInvocation() {
-  try {
-    if (!process.argv[1]) return false;
-    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
-  } catch {
-    return false;
-  }
-}
-
-if (isDirectInvocation()) {
+if (isDirectInvocation(import.meta.url)) {
   process.exitCode = await main();
 }