ruvnet-brain 4.7.20 → 4.7.22

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();

package/scripts/qe/session-start-gate.mjs

@@ -52,6 +52,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fireHook, resolveInstalledSurface, readInstalledRegistrations } from '../selfcheck.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REPO_ROOT = path.resolve(HERE, '../..');
@@ -225,20 +226,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();

package/scripts/qe/ux-suite.mjs

@@ -33,6 +33,7 @@ import { runCommandProbe } from '../../tests/ux/command-probe.mjs';
 import { runCardLaneGate } from './card-lane-gate.mjs';
 import { runSessionStartGate } from './session-start-gate.mjs';
 import { automaticHookRetirementStatus } from '../../bin/install.mjs';
+import { isDirectInvocation } from '../../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const RENDER_PROBE = path.resolve(HERE, '../../tests/ux/render-probe.mjs');
@@ -394,7 +395,7 @@ export async function runUxSuite() {
   throw error;
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   runUxSuite().catch((e) => {
     if (!e.receipt) console.error('  ux-suite crashed:', e.message);
     process.exit(e.receipt ? 1 : 2);

package/scripts/qualified-candidate-check.mjs

@@ -10,6 +10,7 @@ import { evaluateCandidateReceipt } from './release-proof.mjs';
 import { aggregateEvidence } from './release-evidence-aggregate.mjs';
 import { payloadIdFor } from './release-payload.mjs';
 import { canonicalJson } from './release-transaction.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const REPO = 'stuinfla/ruvnet-brain';
 const WORKFLOW = '.github/workflows/release-candidate-preflight.yml';
@@ -109,7 +110,7 @@ export async function checkQualifiedCandidate({ sha, requiredCheck, timeoutMs =
     await pause(Math.min(pollMs, remaining));
   }
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   try {
     if (process.env.GITHUB_REPOSITORY !== REPO) throw new Error('unexpected qualification repository');
     const args = process.argv.slice(2), options = {};

package/scripts/rebuild-gists-from-receipts.mjs

@@ -25,6 +25,7 @@ import {
   sealGistReceipt,
   sealGistReceiptSet,
 } from './gist-receipts.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export { buildGistAggregate, paragraphChunks, provenanceBanner, rawUrlFor };
 
@@ -263,7 +264,7 @@ export async function main(argv = process.argv.slice(2), {
   return 0;
 }
 
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; }).catch((error) => {
     console.error(error.message);
     process.exitCode = 1;

package/scripts/recall-latency-probe.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Measures the real hook paths against a real store (#429): prompt-time recall() and SessionStart restore().
+ *   node scripts/recall-latency-probe.mjs --project <repo> [--runs N]
+ * Prints per-run milliseconds, outcome and `uptime` (machine load). Exit 1 unless EVERY prompt recall is
+ * ok-with-results / ok-empty within 1900 ms and EVERY restore is 'restored' within 3500 ms. The thresholds are
+ * the product's budgets, not tuned to the machine.
+ */
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { recall } from '../plugin/scripts/agentdb-recall.mjs';
+import { restore } from '../plugin/scripts/ruflo-memory-hooks.mjs';
+
+export const RECALL_LIMIT_MS = 1900;
+export const RESTORE_LIMIT_MS = 3500;
+const PROMPT = 'Where are we on the recall latency work? Catch me up on the last decision.';
+
+const argValue = (name) => { const at = process.argv.indexOf(name); return at >= 0 ? process.argv[at + 1] : undefined; };
+const uptime = () => { try { return execFileSync('uptime', { encoding: 'utf8' }).trim(); } catch { return 'uptime unavailable'; } };
+
+async function main() {
+  const project = argValue('--project');
+  const runs = Number(argValue('--runs') ?? 5);
+  if (!project || !Number.isInteger(runs) || runs < 1) {
+    console.error('usage: recall-latency-probe.mjs --project <repo> [--runs N]');
+    process.exit(2);
+  }
+  const dir = path.resolve(project);
+  let failures = 0;
+  for (let run = 1; run <= runs; run += 1) {
+    const t0 = Date.now();
+    const r = await recall({ prompt: PROMPT, projectDir: dir });
+    const recallMs = Date.now() - t0;
+    const recallOk = ['ok-with-results', 'ok-empty'].includes(r.outcome) && recallMs <= RECALL_LIMIT_MS;
+    const t1 = Date.now();
+    const s = await restore({ cwd: dir });
+    const restoreMs = Date.now() - t1;
+    const restoreOk = s.status === 'restored' && restoreMs <= RESTORE_LIMIT_MS;
+    if (!recallOk) failures += 1;
+    if (!restoreOk) failures += 1;
+    console.log(`run ${run}: recall ${recallMs} ms ${r.outcome}${r.status?.['memory.db'] && r.outcome !== 'ok-with-results' ? ` [${r.status['memory.db']}]` : ''}${r.reason ? ` (${r.reason})` : ''} ${recallOk ? 'PASS' : 'FAIL'}`
+      + ` | restore ${restoreMs} ms ${s.status} ${restoreOk ? 'PASS' : 'FAIL'} | ${uptime()}`);
+  }
+  console.log(failures ? `FAIL: ${failures} of ${runs * 2} measurements outside budget (recall <= ${RECALL_LIMIT_MS} ms, restore <= ${RESTORE_LIMIT_MS} ms)`
+    : `PASS: all ${runs * 2} measurements within budget`);
+  process.exit(failures ? 1 : 0);
+}
+await main();

package/scripts/recommendation-eval.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { indexCards, rank, SNAPSHOT_FILE } from '../plugin/scripts/package-recommender.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
@@ -76,7 +77,7 @@ export function evaluate(items, index) {
   };
 }
 
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) {
   const sets = [];
   let cards = SNAPSHOT_FILE;

package/scripts/recommendation-floor.mjs

@@ -14,6 +14,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { judgeScore } from './recommendation-judge-score.mjs';
 import { wilson } from './recommendation-eval.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const POS = new Set(['design', 'diagnosis']);
@@ -31,7 +32,7 @@ export function applyFloor(key, picks, floor) {
   return Object.fromEntries(key.map((k) => [k.qid, k.lane === 'semantic' && !(k.topSimilarity >= floor) ? null : picks[k.qid] ?? null]));
 }
 
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) {
   const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   const dir = arg('--dir', null);

package/scripts/recommendation-judge-score.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { wilson } from './recommendation-eval.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const POS = new Set(['design', 'diagnosis']);
@@ -57,7 +58,7 @@ export function judgeScore(key, picks, cards, { familyAware = false } = {}) {
   };
 }
 
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) {
   const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   const dir = arg('--dir', null);

package/scripts/recommendation-real-host-score.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { wilson } from './recommendation-eval.mjs';
 import { applyFloor } from './recommendation-floor.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const POS = new Set(['design', 'diagnosis']);
@@ -55,7 +56,7 @@ export function scoreRealHost(real, key, simPicks, cards) {
   };
 }
 
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) {
   const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
   const real = JSON.parse(fs.readFileSync(arg('--real'), 'utf8'));

package/scripts/recommendation-real-host.mjs

@@ -21,6 +21,7 @@ import os from 'node:os';
 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)));
 const arg = (n, d) => { const i = process.argv.indexOf(n); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
@@ -53,7 +54,7 @@ export function mentioned(answer, offered) {
   return null;
 }
 
-const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain = isDirectInvocation(import.meta.url);
 if (isMain) {
   const outDir = arg('--out', null);
   if (!outDir || !arg('--key', null)) { console.error('--key and --out are required'); process.exit(2); }

package/scripts/refresh-capability-only-store.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { buildCorpus } from '../kb/forge-corpus.mjs';
 import { loadRvf } from '../kb/resolve-deps.mjs';
 import { CAPABILITY_RETIRED_SUFFIXES, isCapabilityOnly } from '../kb/capability-only.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const NAME = 'cognitum-ruos';
@@ -138,6 +139,6 @@ async function main(argv) {
   console.log(JSON.stringify({ store: NAME, ...result }));
 }
 
-if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+if (isDirectInvocation(import.meta.url)) {
   try { await main(process.argv.slice(2)); } catch (error) { console.error(`[capability-store] ${error.message}`); process.exitCode = 1; }
 }

package/scripts/refresh-model-catalog.mjs

@@ -15,6 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -123,6 +124,6 @@ async function main() {
   }
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isDirectInvocation(import.meta.url)) {
   main().catch((e) => { console.error('refresh-model-catalog FAILED:', e.message); process.exit(1); });
 }

package/scripts/rehearse-corpus-pipeline.mjs

@@ -68,6 +68,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 export const REAL_ROOT = path.resolve(HERE, '..');
@@ -1591,7 +1592,7 @@ export async function main(argv = process.argv.slice(2)) {
   return receipt.verdict === 'PASS' ? 0 : 1;
 }
 
-if (((() => { try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })())) {
+if (isDirectInvocation(import.meta.url)) {
   main().then((code) => { process.exitCode = code; }).catch((error) => {
     console.error(error?.message || error);
     process.exitCode = 1;

package/scripts/release-authority.mjs

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const CANONICAL_PUBLISHERS = new Set([
@@ -203,7 +204,7 @@ export function main(root = ROOT) {
 // spellings of one file, so the guard silently reads false and the CLI exits 0 having done nothing —
 // the same defect 6eead7bc fixed in release-projection.mjs, which is a gate this repo relies on.
 if (((() => {
-  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+  try { return isDirectInvocation(import.meta.url); } catch { return false; }
 })())) {
   process.exitCode = main();
 }

package/scripts/release-evidence-aggregate.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { canonicalJson } from './release-transaction.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 export const REQUIRED_RELEASE_LEAVES = Object.freeze([
   'source-quality',
@@ -38,7 +39,7 @@ export function aggregateEvidence({ sha, payloadId, leaves }) {
   return { ...envelope, evidenceDigest: crypto.createHash('sha256').update(canonicalJson(envelope)).digest('hex') };
 }
 
-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/release-payload.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { canonicalJson } from './release-transaction.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
 
 const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
 const digestFile = (file) => sha256(fs.readFileSync(file));
@@ -51,7 +52,7 @@ const arg = (name) => {
   const index = process.argv.indexOf(name);
   return index >= 0 ? process.argv[index + 1] : null;
 };
-const command = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+const command = isDirectInvocation(import.meta.url)
   ? process.argv[2]
   : null;