ruvnet-brain 4.7.20 → 4.7.21

package/scripts/onboarding-console.mjs

@@ -430,8 +430,31 @@ function wiringSurvey() {
 }
 
 // ── Memory health (read-only probes for the project the console was launched from) ────────────────
+// Dream Cycle 2026-09-18 (memory-durability, round-trip-proof): this used to also pass on ANY
+// `.claude/hooks` directory existing, so a machine whose hooks folder holds only an unrelated
+// script (a different plugin, a stale leftover) scored `sessionSurfacing: ok` and printed "the
+// global SessionStart hook surfaces project state at launch" — a claim about a hook that was never
+// installed. Only the specific recall hook's presence can support that claim.
+//
+// Dream Cycle 2026-09-19 (memory-durability, managed-boundary): the fix above still checked only
+// the LEGACY standalone `agentdb-ensure.sh` global hook. It ignored the mechanism this very repo
+// ships and documents as the automatic one — `plugin/hooks/hooks.json`'s own SessionStart entry,
+// which every session restores via `project-progression-session-start.mjs` (wired through
+// `session-start-core.mjs`) whenever the `ruvnet-brain` plugin itself is enabled. A machine that
+// installed this plugin the real, current way (Claude Code's marketplace flow) and never separately
+// placed the legacy global shell hook scored `sessionSurfacing: warn` — a false negative, flagged
+// as an open scope question by PR #296's independent critic, not chased there to keep that change
+// to one conceptual fix. `pluginEnabled()` mirrors the exact `k.startsWith('ruvnet-brain@')` check
+// `capability-registry.mjs`'s `wiredForRoute()` already uses for the same "is our plugin the one
+// Claude Code will actually load" question, rather than re-deriving a second way to ask it.
+function pluginEnabled() {
+  const settings = readJSON(path.join(CONSOLE_ROOT, '.claude', 'settings.json'));
+  return Object.entries(settings?.enabledPlugins || {}).some(([k, v]) => k.startsWith('ruvnet-brain@') && v === true);
+}
 function sessionHookExists() {
-  return fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks/agentdb-ensure.sh')) || fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks'));
+  if (fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks/agentdb-ensure.sh'))) return 'agentdb-ensure';
+  if (pluginEnabled()) return 'ruvnet-brain-plugin';
+  return null;
 }
 // WHICH FILE IS THE PROJECT'S MEMORY STORE IS NOT A CONSTANT (issue #127).
 //
@@ -496,7 +519,12 @@ function probeMemory(projectDir, { now = Date.now() } = {}) {
   // Compaction survival is a ruflo write at PreCompact (project-state-auto-* + exact readback); a refusal
   // reaches the hook-failures summary. It is not re-probed at render.
   probes.compactionSurvival = { status: 'notTested', detail: 'PreCompact stores a project-state-auto-* checkpoint through ruflo and reads it back; failures appear in the SessionStart hook-failures summary' };
-  probes.sessionSurfacing = sessionHookExists() ? { status: 'ok', detail: 'the global SessionStart hook surfaces project state at launch' } : { status: 'warn', detail: 'no SessionStart recall hook found' };
+  const sessionHookVia = sessionHookExists();
+  probes.sessionSurfacing = sessionHookVia === 'agentdb-ensure'
+    ? { status: 'ok', detail: 'the global SessionStart hook surfaces project state at launch', via: sessionHookVia }
+    : sessionHookVia === 'ruvnet-brain-plugin'
+      ? { status: 'ok', detail: 'the ruvnet-brain plugin\'s own SessionStart hook surfaces project state at launch', via: sessionHookVia }
+      : { status: 'warn', detail: 'no SessionStart recall hook found', via: null };
   // recall quality: honestly NOT probed at render (a true probe needs an embedding query; left for an explicit deep test)
   probes.recallQuality = { status: 'notTested', detail: 'not checked this session — a real recall probe needs an embedding round-trip, which render deliberately avoids' };
 
@@ -2613,12 +2641,8 @@ function apply(ids) {
     } : {});
     if (res.ok && learningBefore) {
       const after = observeLearning();
-      // `ruflo memory distill run` owns the patterns; progress here is a known, readable learner afterwards.
-      const progressed = learningBefore.statusKnown && after.statusKnown;
-      if (!progressed) {
-        res.ok = false;
-        res.log += `\nNo measured learning progress: queue ${after.queueDir}; learner ${after.learnerCwd}. Reload to inspect the remaining evidence.`;
-      }
+      res.ok = learningProgressed(learningBefore, after);
+      if (!res.ok) res.log += `\nNo measured learning progress: ${learningProgressDetail(learningBefore, after)}. Reload to inspect the remaining evidence.`;
     }
     phaseMs.childRemedyMs += elapsedMs(remedyStartedAt);
     results.push({ id, ...res, undoToken });
@@ -2628,6 +2652,21 @@ function apply(ids) {
   return { results, timings: { ...phaseMs, totalMs: elapsedMs(startedAt) } };
 }
 
+/**
+ * #377: Apply on "Your learner has gone quiet" counts as progress only when `ruflo memory distill
+ * status` shows the learner's last distillation moved FORWARD. A readable store alone is not progress.
+ */
+export function learningProgressed(before, after) {
+  const was = Date.parse(before?.lastDistillAt || '');
+  const now = Date.parse(after?.lastDistillAt || '');
+  return !!(before?.statusKnown && after?.statusKnown && after.distillKnown === true
+    && Number.isFinite(now) && (!Number.isFinite(was) || now > was));
+}
+export function learningProgressDetail(before, after) {
+  return `learner ${after?.learningDb || before?.learningDb || 'unresolved'}; last distillation `
+    + `${before?.lastDistillAt || 'not recorded'} → ${after?.distillKnown === true ? (after.lastDistillAt || 'not recorded') : 'unknown'}`;
+}
+
 function autoEligibleIds(recommendations = []) {
   return recommendations
     .filter((rec) => rec?.scope === 'project')

package/scripts/oracle/abstain-threshold-sweep.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { wilson } from '../eval-brain.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const rate = (k, n) => { const w = wilson(k, n); return { k, n, p: +w.p.toFixed(4), lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) }; };
 const within5 = (r) => (r.fileRank != null && r.fileRank <= 5) || (r.altFileRank != null && r.altFileRank <= 5);
@@ -59,4 +60,4 @@ async function main() {
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/abstain-trace.mjs

@@ -28,6 +28,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const args = process.argv.slice(2);
 const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
@@ -136,4 +137,4 @@ async function main() {
   process.exit(0);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/doc2query-generate.mjs

@@ -23,6 +23,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { claudeArgs, spawnHost, isQuotaRefusal } from './producer-hosts.mjs';
 import { subscriptionOnlyEnv } from '../subscription-hosts.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export const EXCERPT_CHARS = 1500;
 export const D2Q_SCHEMA = Object.freeze({
@@ -159,4 +160,4 @@ async function main() {
   console.log(JSON.stringify({ files: docs.length, written, stopped: stop }));
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/doc2query-reach.mjs

@@ -22,6 +22,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { wilson } from '../eval-brain.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 /** Collapse ranked entry hits (each pointing at a file) to the first `files` distinct files. */
 export function filesFromEntries(hits, pathOfId, files) {
@@ -107,4 +108,4 @@ async function main() {
   process.exit(0);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/judge-train.mjs

@@ -21,6 +21,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { wilson } from '../eval-brain.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const { JUDGE_FEATURES, judgeFeatures, judgeLogit } = await import(pathToFileURL(path.join(ROOT, 'kb/judge-rank.mjs')).href);
@@ -155,4 +156,4 @@ async function main() {
   console.log(JSON.stringify({ threshold: tau, trainedOn: model.trainedOn, heldout: report.heldout }, null, 1));
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/need-set-split.mjs

@@ -13,6 +13,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export function splitNeedSet(questions, { salt = 'v1', trainFraction = 0.5 } = {}) {
   const byRepo = new Map();
@@ -45,4 +46,4 @@ async function main() {
   console.log(JSON.stringify({ train: split.train.length, heldout: split.heldout.length, contentHash: set.contentHash }));
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/produce-questions.mjs

@@ -34,6 +34,7 @@ import {
   DEFAULT_ROLES, LABEL_SCHEMA, PRODUCER_MODELS, VERDICT_SCHEMA, generatorPrompt, hostAdapters, isQuotaRefusal,
   judgePrompt, spawnHost,
 } from './producer-hosts.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export {
   CLAUDE_SYSTEM_PROMPT, CLAUDE_TIMEOUT_MS, CODEX_TIMEOUT_MS, DEFAULT_ROLES, JUDGE_SYSTEM_PROMPT, LABEL_SCHEMA,
@@ -275,19 +276,4 @@ export async function main(argv = process.argv.slice(2)) {
   return labels.suspended ? 75 : 0;
 }
 
-// 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()) process.exitCode = await main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = await main();

package/scripts/oracle/repo-recall.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { extractZip } from '../../kb/zip-extract.mjs';
 import { validateCoverageLedger } from '../coverage-integrity.mjs';
 import { retiredFixtureStores } from '../fixture-denominator.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
@@ -556,8 +557,7 @@ export async function main(argv = process.argv.slice(2), { searchAll = null } =
 // archive on disk (measured 2026-09-14).
 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/oracle/retrieval-accuracy.mjs

@@ -54,6 +54,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { extractZip } from '../../kb/zip-extract.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(HERE, '..', '..');
@@ -871,8 +872,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/oracle/sona-query-adapter-eval.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { wilson } from '../eval-brain.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 /** Rank (1-based) of the first hit whose path is `gold`, or null within the list. */
 export function rankOf(paths, gold) {
@@ -136,4 +137,4 @@ async function main() {
   process.exit(0);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (isDirectInvocation(import.meta.url)) await main();

package/scripts/oracle/source-tree.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export const SOURCE_TREE_VERSION = 'oracle-source-tree/1';
 export const LFS_POINTER_PREFIX = 'version https://git-lfs.github.com/spec/v1';
@@ -148,18 +149,4 @@ export function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-// 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. 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()) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/scripts/oracle/source-units.mjs

@@ -25,6 +25,7 @@ import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { parse as babelParse } from '@babel/parser';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export const RULES_VERSION = 'oracle-source-units/1';
 export const MAX_SELECTED = 100;
@@ -373,19 +374,4 @@ export function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-// 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()) process.exitCode = main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = main();

package/scripts/oracle/spike-run.mjs

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { buildInventory, resolveCommit } from './source-units.mjs';
 import { produceQuestions, DEFAULT_BATCH } from './produce-questions.mjs';
 import { loadBgeEmbedder, validateLabels } from './validate-labels.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 function arg(argv, flag) { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; }
 const writeJson = (file, value) => fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
@@ -80,19 +81,4 @@ export async function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-// 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()) process.exitCode = await main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = await main();

package/scripts/oracle/validate-labels.mjs

@@ -23,6 +23,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gitBlobSha, sha256Hex, unitText } from './source-units.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 export const THRESHOLDS = Object.freeze({
   minSpanChars: 40, minSpanTokens: 6, maxSpanFractionOfUnit: 0.9,
@@ -232,19 +233,4 @@ export async function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-// 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()) process.exitCode = await main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = await main();

package/scripts/org-repo-count.mjs

@@ -28,6 +28,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 /** The last LIVE reading, so an offline build reuses a real measurement instead of a literal. */
@@ -103,7 +104,7 @@ export function orgRepoCount({ owner = OWNER, file = RECORD_PATH, now = new Date
  * working tree clean for `release-qe`'s stabilization seal.
  */
 const isMain = (() => {
-  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 })();
 

package/scripts/package-cards.mjs

@@ -40,6 +40,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 export const SCHEMA = 'ruvnet-brain.package-cards/1';
@@ -321,7 +322,7 @@ export function snapshotAgeDays(doc, now = Date.now()) {
 }
 
 const isMain = (() => {
-  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  try { return isDirectInvocation(import.meta.url); }
   catch { return false; }
 })();
 

package/scripts/prepublication-evidence.mjs

@@ -10,6 +10,7 @@ import { readCandidateRetrieval } from './staged-host-verifier.mjs';
 import { validateRetrievalCanaryReceipt } from './retrieval-canary.mjs';
 import { payloadIdFor } from './release-payload.mjs';
 import { HOST_WARMUP_TIMEOUT_MS, RELEASE_SEARCH_DEADLINE_MS } from './host-install-matrix.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
 
@@ -191,7 +192,7 @@ export function buildPrepublicationEvidence({
   return { leaves, envelope: aggregateEvidence({ sha, payloadId: payload.payloadId, leaves }) };
 }
 
-const isCli = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isCli = isDirectInvocation(import.meta.url);
 if (isCli) {
   const arg = (name) => {
     const index = process.argv.indexOf(name);

package/scripts/private-overlay.mjs

@@ -31,6 +31,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { sha256File, projectSourceStore } from './rvf-generation.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const REQUIRED_SIDECARS = ['.big.rvf', '.big.rvf.embed.json', '.big.rvf.idmap.json', '.meta.json', '.passages.jsonl'];
 export const OPTIONAL_SIDECARS = ['.symbols.json', '-primer.md'];
@@ -267,4 +268,4 @@ function main() {
   console.log(JSON.stringify(receipt, null, 2));
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) main();
+if (isDirectInvocation(import.meta.url)) main();

package/scripts/product-integrity-contract.mjs

@@ -8,6 +8,7 @@ import {
   digest,
   validateSourceScopeReceipt,
 } from './source-scope-receipt.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const PRODUCT_INTEGRITY_SCHEMA_VERSION = 1;
 export const PRODUCT_INTEGRITY_TEST_CLASSES = Object.freeze(['essential', 'supporting', 'obsolete']);
@@ -180,4 +181,4 @@ export function runProductIntegrityCli(argv = process.argv.slice(2), io = { stdo
     semanticReviewVerified: false, behaviorVerified: false, traceSha256: trace.traceSha256 })}\n`); return 0; }
   throw new Error('invalid product integrity argument combination');
 }
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) { try { process.exitCode = runProductIntegrityCli(); } catch (error) { console.error(`[product-integrity-contract] ${error.message}`); process.exitCode = 1; } }
+if (isDirectInvocation(import.meta.url)) { try { process.exitCode = runProductIntegrityCli(); } catch (error) { console.error(`[product-integrity-contract] ${error.message}`); process.exitCode = 1; } }

package/scripts/protected-release-invocation.mjs

@@ -7,6 +7,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { evaluateCandidateReceipt } from './release-proof.mjs';
 import { getVersion } from './version.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const PROTECTED_WORKFLOW = 'protected-release';
 export const PROTECTED_VERSION = getVersion();
@@ -92,7 +93,7 @@ export function validateProtectedPublishInvocation({ root = process.cwd(), env =
   };
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   const result = validateProtectedPublishInvocation();
   if (result.verdict !== 'PASS') {
     console.error('[protected-release] publication refused:');

package/scripts/public-verification-abandon.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { extractZip } from '../kb/zip-extract.mjs';
 import { abandonPublicVerificationTransaction } from './release-transaction.mjs';
 import { liveReleaseProvider } from './release-transaction-provider.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 function regularJson(file, max = 131072) {
   const stat = fs.lstatSync(file);
@@ -90,7 +91,7 @@ export async function abandonPublicVerification({ identityFile, outputFile, env
   return receipt;
 }
 
-const direct = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const direct = isDirectInvocation(import.meta.url);
 if (direct) {
   const arg = (name) => { const index = process.argv.indexOf(name); return index < 0 ? null : process.argv[index + 1]; };
   try {

package/scripts/public-verification-aggregate.mjs

@@ -8,6 +8,7 @@ import { retrievalOracleExpectationFromPlan, validateRetrievalOracleReview } fro
 import { validateRetrievalCanaryPlan, validateRetrievalCanaryReceipt } from './retrieval-canary.mjs';
 import { validateNightlyProofReceipt, validateNativeSchedulerSmoke } from './nightly-two-run-proof.mjs';
 import { CLAUDE_FABLE_5_ID, GPT_5_6_SOL_ID, LEGACY_REVIEW_MODEL_IDS } from './review-model-defaults.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const PUBLIC_VERIFICATION_OS = Object.freeze(['linux', 'macos', 'windows']);
 export const PUBLIC_VERIFICATION_MODES = Object.freeze(['claude', 'codex', 'dual']);
@@ -359,7 +360,7 @@ async function main() {
     leaves: aggregate.metrics.leaves })}\n`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   main().catch((error) => {
     process.stderr.write(`${error.message}\n`);
     process.exitCode = 1;

package/scripts/public-verification-finalizer.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { finalizeReleaseTransaction } from './release-transaction.mjs';
 import { liveReleaseProvider } from './release-transaction-provider.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const argument = (args, name) => {
   const index = args.indexOf(name);
@@ -61,5 +62,5 @@ export async function main(args = process.argv.slice(2)) {
   }
 }
 
-const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const invokedDirectly = isDirectInvocation(import.meta.url);
 if (invokedDirectly) process.exitCode = await main();

package/scripts/public-verification-inputs.mjs

@@ -17,6 +17,7 @@ import {
   validateRetrievalQueryEvidence,
   verifyQueryOracleSource,
 } from './retrieval-canary.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HEX40 = /^[a-f0-9]{40}$/;
 const HEX64 = /^[a-f0-9]{64}$/;
@@ -602,6 +603,6 @@ export async function main(argv = process.argv.slice(2)) {
   return result;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   main().catch((error) => { console.error(error.message); process.exitCode = 1; });
 }

package/scripts/public-verification-lane.mjs

@@ -20,6 +20,7 @@ import {
   validatePlanAgainstCoverage,
   validateRetrievalCanaryReceipt,
 } from './retrieval-canary.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HEX40 = /^[a-f0-9]{40}$/;
 const HEX64 = /^[a-f0-9]{64}$/;
@@ -353,4 +354,4 @@ export async function main(args = process.argv.slice(2)) {
   }
 }
 
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) process.exitCode = await main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = await main();

package/scripts/publication-receipt.mjs

@@ -29,6 +29,7 @@ import {
   validateNightlyProofReceipt,
 } from './nightly-two-run-proof.mjs';
 import { parseRetrievalResult } from '../kb/retrieval-result.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const PACKAGE = 'ruvnet-brain';
@@ -825,4 +826,4 @@ export async function main(args = process.argv.slice(2)) {
   }
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = await main();
+if (isDirectInvocation(import.meta.url)) process.exitCode = await main();

package/scripts/published-surface-probe.mjs

@@ -54,6 +54,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { describeLatestPointer, isCodeReleaseTag, latestCodeReleaseTag } from './release-channel-kind.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const EXIT = Object.freeze({ PASS: 0, FAIL: 1, UNKNOWN: 4 });
 
@@ -275,5 +276,5 @@ export async function main() {
   return EXIT[verdict];
 }
 
-const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const invokedDirectly = isDirectInvocation(import.meta.url);
 if (invokedDirectly) process.exit(await main());

package/scripts/qe/card-lane-gate.mjs

@@ -28,6 +28,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { answerFromCards } from '../../kb/card-lane.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '../..');
@@ -158,20 +159,5 @@ async function main() {
   process.exit(1);
 }
 
-// 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;
-  }
-}
-
-const invokedDirectly = isDirectInvocation();
+const invokedDirectly = isDirectInvocation(import.meta.url);
 if (invokedDirectly) main();